Hardware catalog and components

Separate reusable hardware definitions from actual assets, expected components, and observed hardware evidence. Renga should answer what equipment is expected, what was discovered, how observations map to physical slots, and where hardware is missing, unexpected, or ambiguous without manufacturing observed facts from a catalog template.

This RFD owns manufacturers, hardware types, modules, bays, expected component structure, actual component projections, and inventory-only parts. Physical placement belongs to RFD 5; network and cable topology belong to RFD 7.

Renga adopts the type-versus-instance separation from NetBox’s device models, module models, and component models. A device type describes reusable make/model structure; a device is an actual asset; a module occupies a compatible bay; and inventory items represent serialized hardware that is not necessarily a topology endpoint.

Renga deliberately does not copy NetBox’s automatic implication that components instantiated from templates are current hardware. Catalog structure creates expectations. Only observations or confirmed operator actions establish actual components.

The initial catalog contains:

Manufacturers, hardware types, and module types receive resource envelopes. Templates are versioned subordinate rows owned by their type. Manufacturer plus model is unique in its relevant type category. Manufacturer aliases and source-reported names are identifier claims rather than duplicate manufacturers.

Frequently queried and invariant-bearing specifications use typed columns. Variable vendor data remains JSONB. A catalog revision changes expected structure prospectively; it does not rewrite historical evidence or silently replace confirmed exceptions on existing assets.

Physical device resources gain an optional hardware_type_id. Assignment may be operator-selected or reconciled from manufacturer, model, product ID, and other source claims. Ambiguous catalog matches remain findings and do not select the first candidate.

Actual topology-bearing components use typed projections with stable identity, position or bay name, status, asset identifiers, and metadata. Components remain subordinate to their owning device or module unless they need independent lifecycle, ownership, or reconciliation; a line card or replaceable module may receive a resource envelope while a CPU core does not.

A module bay belongs to one device or module and accepts compatible module types. Desired bay assignment and reconciled current installation remain separate; one of each may exist per bay. Current installation and removal are transactional and retain history through events and evidence. Disabled or incompatible bays cannot accept desired assignments or current installations.

InventoryItem represents serialized or tracked physical parts that are useful for asset inventory but are not graph endpoints, such as DIMMs, CPUs, disks, fans, and miscellaneous FRUs. Inventory items may nest for assembly structure but reject cycles. When a part becomes topology-bearing or independently managed, it is promoted through an explicit typed relationship rather than overloading inventory-item metadata.

Module and inventory-item hierarchy mutations serialize on an owning-resource or organization-and-hierarchy lock before ancestry validation and the parent write. This closes concurrent inverse-parent races that snapshot-only cycle checks cannot prevent.

Assigning a hardware or module type materializes versioned expected components, not observations. Each expectation references its originating type revision and template. Confirmed local exceptions can add, suppress, or alter expectations without mutating the shared catalog.

Current agent components remain shape-open observation data. Product slices promote useful kinds into typed component evidence with source, observation, observed time, stable source-local identity, slot or path, serial and part numbers, attributes, and raw metadata. Unknown component kinds remain preserved in the immutable observation and do not block ingestion.

Reconciliation matches observed components using stable serial or provider IDs, then slot/path plus part number, then weaker normalized attributes. It records missing expected, unexpected observed, ambiguous match, conflicting identity, incompatible module, and specification-drift findings. Source omission makes that source’s component evidence stale only when the source policy and accepted observation declare the component section a complete snapshot. Omission from a partial, paginated, failed, or capability-limited collection has no absence meaning and never deletes the canonical component or expected structure. The initial completeness gate requires Source.metadata.component_snapshot_policy = "complete", payload.section_completeness.components = true, and an explicit component list; neither declaration is authoritative by itself.

Existing canonical interfaces remain the network projection used by IPAM and topology. Interface templates and observed NIC/port components may match and enrich an interface but must not create a second competing interface model. Template identity, component evidence, and canonical interface identity remain linked and explainable. The initial implementation treats entries in the existing interfaces payload section and their InterfaceEvidence rows as NIC/port evidence; it does not add an interface kind to the shape-open components section.

The same rule applies to future power and console components: catalog templates describe expected endpoints, observations provide evidence, and one canonical typed endpoint participates in topology.

The first UI provides manufacturer and type catalogs, type detail with expected components, device hardware matching, module/bay inventory, inventory items, and component reconciliation findings. Users can distinguish catalog expectation, confirmed actual hardware, and current source evidence.

Routes belong inside the existing live_session :require_authenticated_user block and [:browser, :require_authenticated_user] pipeline because hardware catalogs and assets are organization inventory and every view requires login. Reads follow organization membership. Catalog, matching, and exception mutations allow active members, admins, and owners; viewers remain read-only.

Initial routes are:

The first implementation excludes procurement, purchase orders, depreciation, warranty workflows, stock warehouses, firmware distribution, automatic driver selection, and complete vendor-specific component taxonomies.

Progress against this proposal is tracked in the RFD 6 implementation checklist.