Observable semantics as design documentation

Observable semantics are part of a system's design, not Bridge runtime state. Record them in ordinary, version-controlled design documentation next to the subsystem they describe.

Bridge does not define or validate a special observable-contract artifact. A design document does not prove that instrumentation or trace validation exists, and its presence does not satisfy an evidence obligation. Configure executable trace, runtime, or model-comparison commands in the project profile; Bridge evaluates their evidence receipts.

What to document

For each observable or event, state the details that a reader cannot safely infer from code alone:

• source location and trigger point;
• whether capture represents pre-state, post-state, a mixed view, or a derived value;
• snapshot consistency and concurrency guarantees;
• collection mechanism and whether collection can affect execution;
• captured fields, stable identities, and diagnostic-only values;
• mapping to domain operations, model transitions, or trace events;
• consumers such as runtime assertions, replay, differential comparison, or trace validation;
• ordering, omission, sampling, and loss semantics;
• constraints, known ambiguities, and review conditions.

Prefer precise prose, tables, and diagrams over a schema-shaped checklist. Link to implementation and executable evidence where useful.

Bridge integration

Use profile and policy configuration to connect this documentation to Bridge's change and evidence loop:

• include the document in the subsystem's docs-globs;
• use file-glob-rules and concern-class to provide context matched by policy rules;
• register trace validation, runtime checks, model checks, or differential checks as canonical evidence commands;
• express required evidence levels in the verification policy.

This keeps semantic knowledge reviewable while leaving obligation inference and freshness to Bridge's profile, candidate state, and evidence receipts.

See the DPDK ring example for one possible document shape.