ADR-0008: Semantic Unit Is Envelope Plus Fact

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

• 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 grammar kind:id or kind:scope/id
• predicate: stable lower_snake_case relation name
• object_json: canonical JSON bytes

The envelope carries fields such as:

• message_id
• from_zone
• to_zone
• produced_at
• correlation_id
• causation_id
• labels
• object_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