Context
BSFG requires a transport-neutral semantic unit that can cross zone boundaries, survive replay, remain auditable, and avoid coupling the boundary substrate to any single domain ontology. The unit must support deterministic idempotency, large-attachment indirection, and later interpretation by domain-specific consumers.
The design must also preserve the distinction between:
- transport and policy metadata such as identity, origin, timestamps, and labels
- domain meaning carried as a statement about the world
Options Considered
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| Typed domain messages | Model each business concept as a dedicated transport message type. | strong compile-time typing clear per-domain contracts |
boundary layer becomes domain-coupled schema churn propagates into transport weak fit for generic replay substrate |
| Envelope plus message-kind hierarchy | Use envelope metadata plus top-level kinds such as event, delta, snapshot, ack, control. | more structured than raw payloads supports multiple semantic styles |
kind taxonomy becomes unstable delta vs snapshot is representational rather than fundamental pharma terminology overload around “event” |
| Envelope plus fact (Selected) | Represent the semantic core as a fact triple carried inside a transport envelope. | minimal and durable clean separation of transport vs meaning naturally replayable domain-agnostic substrate |
strong typing moves to producer/consumer edges predicate vocabulary must be governed explicitly |
Decision
BSFG will treat the semantic transport unit as:
message = envelope + fact
The envelope carries transport and policy metadata. The fact carries domain meaning.
fact = (subject, predicate, object_json)
The canonical fact fields are:
subject: stable identifier using grammarkind:idorkind:scope/idpredicate: stable lower_snake_case relation nameobject_json: canonical JSON bytes
The envelope carries fields such as:
message_idfrom_zoneto_zoneproduced_atcorrelation_idcausation_idlabelsobject_schema(optional reference)
Large artifacts are not embedded by default; they are stored out-of-band and referenced from facts via attachment metadata.
Consequences
Benefits:
- transport remains stable while domains evolve independently
- facts are small, replayable, and easy to hash for idempotency
- boundary layer stays neutral with respect to business ontology
- compliance metadata remains clearly separated from domain assertions
Tradeoffs:
- schema validation is externalized to producers and consumers
- predicate and subject conventions must be curated deliberately
- downstream projections must impose stronger typing where needed