ADR-0020: Envelope Carries Boundary Metadata and Policy Labels

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

• 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 layer
• from_zone: declared origin zone, validated against authenticated peer identity
• to_zone: intended destination zone
• produced_at_unix_ms: producer event time
• correlation_id: workflow or conversation linkage
• causation_id: immediate causal predecessor linkage
• object_media_type: optional representation hint
• object_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