Context
BSFG separates transport meaning from domain meaning. Domain meaning lives in the fact:
fact = (subject, predicate, object_json)
The remaining metadata must answer different questions:
- where did this message originate and where is it intended to go?
- what idempotency key and causal linkage does it carry?
- what optional policy or operational hints should infrastructure use?
- what schema or media hints help downstream interpretation?
These concerns should not be embedded into the subject or predicate, and they should not be mixed into the semantic fact object.
Options Considered
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| No explicit envelope | Put origin, causal, and policy metadata into fact fields or transport-specific headers ad hoc. | minimal apparent structure fewer top-level fields |
mixes semantics with transport harder to reason about consistency weak portability across runtimes |
| Rigid closed envelope enum model | Constrain zone identity and metadata into fixed enums and tightly typed fixed slots only. | strong compile-time rigidity easy to validate narrowly |
poor fit for evolving zone topologies policy metadata becomes hard to extend forces redeploys for metadata growth |
| Everything in generic headers only | Rely entirely on transport headers for all metadata instead of a first-class envelope model. | transport-native implementation fewer application fields |
boundary semantics become protocol-dependent harder to persist and replay uniformly less explicit contract |
| Explicit envelope with stable core fields and extensible labels (Selected) | Use a first-class envelope for core boundary metadata, plus extensible labels for policy treatment. | clean separation of transport vs fact semantics stable idempotency and causality model zone topology remains configurable rather than hard-coded policy metadata can evolve without changing fact shape |
label vocabulary must be governed implementations must avoid treating labels as semantic fact content |
Decision
BSFG uses a first-class envelope to carry transport and policy metadata.
message = envelope + fact
The envelope contains the stable core fields:
message_id
from_zone
to_zone
produced_at_unix_ms
correlation_id
causation_id
object_media_type
object_schema
labels
Semantics of the core fields:
message_id: idempotency key at the boundary layerfrom_zone: declared origin zone, validated against authenticated peer identityto_zone: intended destination zoneproduced_at_unix_ms: producer event timecorrelation_id: workflow or conversation linkagecausation_id: immediate causal predecessor linkageobject_media_type: optional representation hintobject_schema: optional schema URI or version hint
labels are defined as policy metadata, not semantic fact content. They are optional, extensible, and infrastructure-oriented.
Examples:
classification = GMP
retention = 7y
site = PlantA
source_system = PASX
priority = high
Labels may influence routing, retention, filtering, or operational treatment, but they do not change the meaning of the fact itself.
Consequences
Benefits:
- transport metadata remains explicit and replayable
- fact semantics stay clean and domain-focused
- zone identity and causal linkage are first-class contract elements
- policy tags can evolve without mutating the fact model
Tradeoffs:
- label keys and allowed meanings need governance
- producers must avoid using labels as a substitute for proper fact fields
- consumers must distinguish transport metadata from semantic truth