Home Documentation

infrastructure_model_invariants_v0.1

5 min read

Infrastructure Model — Draft Invariants (v0.1)

1. Identity and Naming

1.1 Every object has an id

Every object instance has an id within its class namespace or a global namespace.

1.2 id and name are distinct

  • id is stable, machine-oriented, and used for references.
  • name is human-oriented and may change.

1.3 id is not inferred from name

Two objects may have identical names but different ids.

1.4 Derived names are defaults

If name is explicitly specified, it overrides any derived naming rule.

1.5 Derived names may depend on

  • containing PortList
  • PortType
  • containing Device
  • port ordinal within the list

1.6 Missing name does not imply missing identity

Objects without a name still have a valid id.

2. Device / PortList / Port Structure

2.1 A Device has zero or more PortLists

2.2 A PortList belongs to exactly one Device

2.3 A Device.portLists collection contains no duplicate members

2.4 A PortList has exactly one PortType

2.5 A PortList contains one or more Ports (tentative)

2.6 A Port belongs to exactly one PortList

2.7 A Port belongs indirectly to exactly one Device

2.8 All ports in a PortList share the same PortType

2.9 A PortList is ordered

Its ports array preserves order.

2.10 A Port index within a PortList is semantically meaningful

2.11 Derived ordinal

ordinal = index + baseOrdinal

2.12 Array index and displayed number are distinct

  • array index typically 0-based
  • displayed ordinal typically 1-based

2.13 A PortList may define a naming template

2.14 A PortType may define a default naming template

2.15 PortList IDs are unique within a Device (tentative)

2.16 Port IDs are unique within a Device (tentative)

3. Port Semantics

3.1 A Port is an attachment point on a Device

3.2 A Port may have zero or one associated Connector

3.3 Connector—Port association is symmetric

If a connector references a port, that port references the connector.

3.4 A Port cannot be associated with more than one connector at once

3.5 A Port may be unoccupied

3.6 PortType constrains compatible ConnectorTypes

3.7 A Port may specify constraints beyond its PortType (tentative)

Examples: - maximum speed - PoE capability - voltage - administrative state

4. Cable / Connector Structure

4.1 A Cable has exactly one CableType

4.2 A Cable has one or more Connectors

4.3 A Connector belongs to exactly one Cable

4.4 A Cable’s connectors are distinguishable (ordered or labeled)

4.5 A Connector has exactly one ConnectorType

4.6 A Connector may be associated with zero or one Port

4.7 Connector—Port association must be symmetric

4.8 A Connector cannot be associated with more than one Port

4.9 A Cable may exist in inventory unconnected

4.10 A Cable may be partially deployed

4.11 A CableType constrains allowable connector configurations

4.12 A CableType may constrain connector count (tentative)

5. Connector / Port Compatibility

5.1 A Connector may plug into a Port only if types are compatible

5.2 Compatibility is explicitly declared

Never inferred from string matching.

5.3 Compatibility may be many-to-many

5.4 Physical compatibility and functional compatibility differ

Example: A connector may fit mechanically but violate electrical/protocol constraints.

5.5 Physical plug validity does not guarantee functional correctness (tentative)

6. Derived Connectivity

6.1 Device-to-device connectivity is derived

Primary facts are: - cable has connectors - connector plugs into port - port belongs to device

6.2 Two ports are physically linked if connectors of the same cable attach to them

6.3 Two devices are directly connected if ports on those devices are linked by a cable

6.4 A cable with fewer than two connected connectors does not create a full path

6.5 Multi-ended cables allowed only if permitted by CableType (tentative)

7. Areas and Containment

7.1 An Area may have zero or more parent areas

7.2 Simpler model: normally an area has at most one parent (tentative)

7.3 A Device may be in one or more areas (tentative)

7.4 Simpler model: normally a device has exactly one containing area (tentative)

7.5 Area names are unique within their containing area

7.6 Device names are unique within their containing area

7.7 Name uniqueness is scoped to the containing area

7.8 Device isIn Area

7.9 Area isPartOf Area

7.10 Transitive inference allowed

If:

A isIn B
B isPartOf C

then:

A isIn C

8. Typing and Inheritance

8.1 CableType, ConnectorType, PortType are first-class objects

8.2 Types may define defaults and constraints

Examples: - naming templates - connector count - compatibility - medium - direction

8.3 Subtypes may refine but not violate parent invariants

8.4 Instance values override type defaults

9. Consistency Rules

9.1 Every referenced object must exist

9.2 Containment relations must be acyclic

9.3 isPartOf relations must be acyclic

9.4 Device → PortList → Port ownership must be exclusive

9.5 Connector—Port association must be consistent

9.6 Derived values must be deterministic

9.7 Explicit values override derived values but must still validate

10. Port Naming and Derivation

10.1 Port.id may be derived

From: - containing Device - containing PortList - port index

10.2 Port.name may be derived

From: - PortList naming template - else PortType template - else fallback ordinal

10.3 Port.name and Port.id are independent

10.4 Displayed port number may be offset

Example:

sfpPorts[0] → port 25

10.5 Explicit name does not affect port ordering

Open Questions

A. Can a PortList be empty?

B. Can a Port participate in multiple connectors over time but only one at once?

C. Can a Device be in multiple areas?

D. Can an Area have multiple parents?

E. Can a Cable have more than two connectors?

F. Should Port.id be stored or always derived?

G. Must Port.name be unique within a Device?

Graph View