D2 Contracts for the layer seams · Stamped architecture

Status: RECOMMENDED — awaiting Vinayak
Options: Add to SE now as 0.x drafts; or wait for the first live plants to settle fields
Trade-offs: Early contracts force alignment across repos; late contracts fit reality better
Recommendation: Draft the ten contracts in architecture section 5 (PlantState, Evidence, Prescription, Action, ValueRecord, AutonomyPolicy, Lot and genealogy, WriteRequest, ClosureState, Envelope) in SE now as 0.x, marked experimental. The first plant that uses a contract in production bumps it to 1.0.0. Envelope is the common message header (contract name, version, tenant, plant, episode, producer, idempotency key); the safety limits live inside AutonomyPolicy as the operating envelope. ValueRecord carries two separate fields: status (pending, ops_confirmed, signed_off, disputed, superseded) and tier (measured, confirmed, modeled, unknown). Migration: L2 verified becomes signed_off where a customer sign-off exists, otherwise ops_confirmed; contract modeled becomes tier = modeled with status = pending. tier is derived from the D13 evidence labels by the section 5.2 mapping: all load-bearing quantities Measured gives measured; Measured or calibrated Estimated plus a passed check gives confirmed; any unchecked Estimated or any Assumed gives modeled; any Unknown gives unknown. The master document does not define tiers; SE owns this enum. Order of first use: Envelope, Evidence, PlantState, ClosureState and ValueRecord for the slow loop; AutonomyPolicy, WriteRequest and Action for the shadow fast loop; Lot and genealogy only at plants that track lots.
Why: Six repos already disagree on four shapes (section 2.3). Drafts force one shape now; the experimental mark keeps the cost of changing fields low.
Evidence: section 2.3 duplications (ledger status, write path, closure states, finding); SE contracts 0.16.0; closure/action-intent.json (withdrawn ADR-W029).
Reversible: Yes while 0.x; after 1.0.0 only by a versioned migration.
Blocks: Every build-order phase that crosses a repo seam.

Status history

RECOMMENDED since 2026-10-07 · b4db9d4

Where this decision is cited

Page history: last 2 changes

2026-10-07 docs(research): retire stale research to archive/research-2026-10 with a register ab84821
2026-10-07 docs(technical): split decision board into DECISIONS.md b4db9d4