Architecture Decision Record

BSFG ADR-0016

Status: Accepted · Date: 2026-03-06

Status: Accepted

Date: 2026-03-06

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

Option Description Benefits Drawbacks
Opaque UUID only Use a globally unique identifier with no kind prefix or readable structure. 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
← Previous ADR Next ADR →