ADR-0016: Subject Identity Uses Kind With Optional Scope

Context

Every BSFG fact is anchored by a subject. Subject identity must be stable across replay, compact enough to live comfortably in message metadata, and flexible enough to represent both single-site and multi-site deployments.

The subject grammar must also avoid collapsing distinct concerns into one token. In particular:

• subject identity should describe what the fact is about
• zone routing should remain in envelope fields such as from_zone and to_zone
• policy treatment should remain in labels
• business meaning beyond identity should remain in predicate and object_json

Options Considered

• simple uniqueness model
• easy to generate mechanically

|

• poor readability
• weak partitioning ergonomics
• kind must be carried somewhere else anyway

| | Hierarchical path with mandatory full scope | Encode full site, area, line, and object path inside the subject string. |

• high descriptive power
• can reflect physical structure

|

• brittle when topology changes
• subjects become long and policy-laden
• identity is coupled to mutable organization

| | Kind plus opaque ID only | Always use kind:id with no scope capability. |

• simple and compact
• readable

|

• insufficient for multi-site collisions
• forces external disambiguation everywhere

| | Kind with optional scope (Selected) | Use kind:id by default, with optional kind:scope/id where multi-site or namespace disambiguation is required. |

• compact default
• multi-site safe when needed
• keeps scope separate from zone routing
• supports stable partitioning by kind

|

• requires naming discipline
• scope vocabulary must remain governed but loosely interpreted

|

Decision

BSFG subject identity uses the following grammar:

kind:id
kind:scope/id

Rules:

• kind is a stable, lower-case domain noun such as batch, asset, lot, recipe, or document
• id is an opaque producer-owned identifier
• scope is optional and used only when disambiguation across sites or namespaces is required
• BSFG treats scope as a namespace component, not as transport routing metadata

Examples:

batch:B1042
asset:FILLER-07
batch:PlantA/B1042
asset:PlantB/FILLER-07
lot:PlantA/RM-8821
document:QMS/SOP-123.v4

Subjects must not absorb unrelated concerns such as priority, retention, network lane, or approval state. Those belong elsewhere in the model.

Consequences

Benefits:

• subjects stay compact and readable
• single-site deployments are not forced into unnecessary ceremony
• multi-site deployments can disambiguate safely when needed
• partitioning by kind remains straightforward

Tradeoffs:

• scope usage must be governed consistently across producers
• the same business entity must not appear under conflicting subject conventions
• downstream consumers must not infer too much semantics from scope text alone