Data contracts between layers

Ten contracts carry the stack (D2). They are drafted in SE beside contracts 0.16.0 as 0.x, marked experimental; the first plant that uses one in production bumps it to 1.0.0 (section 5.11). Every message travels inside the Envelope header (section 5.10). Where an existing schema covers part of a contract, the section says so.

flowchart TB
    %% house-style: contract-flow
    subgraph inputs["State and evidence"]
        direction LR
        LOT["Lot and genealogy"]
        PS["PlantState"]
        EVI["Evidence"]
    end
    LOT --> EVI
    PS --> EVI
    EVI --> RX["Prescription"]
    RX --> WR["WriteRequest"]
    POL{{"AutonomyPolicy"}} --> WR
    RX --> CS["ClosureState (cards)"]
    WR --> ACT["Action"]
    CS --> ACT
    ACT --> VR["ValueRecord"]
    EVI --> VR
    VR -. "same-condition wins" .-> POL

    classDef govc fill:#fff4d6,stroke:#c99a2e,color:#000
    classDef agentc fill:#e8f0ff,stroke:#5b7bd5,color:#000
    classDef loopc fill:#eef7ee,stroke:#4f9a4f,color:#000
    class POL govc

5.1 PlantState#

The estimated state of an asset at a time, with uncertainty. Produced by layer 3 (twin runtime or estimators), consumed by layer 4 and the writer.

Exists today: nothing. twin_state table is DOCS.

5.2 Evidence#

A typed claim with its support. Replaces the energy-only FindingAs-built L3 detector output admitted to L4 (finding.json 1.2.0) as the unit of analytical output.

Exists today: finding.json (1.2.0, energy-centric) and finding-2.0.0.json (direction only).

Tier mapping (accepted under D13, 7 Oct 2026). The package uses two vocabularies. The contract tiers (measured, confirmed, modeled, unknown) are the provenance of a claim. The evidence labels (Measured, Estimated, Assumed, Unknown, plus calibrated or uncalibrated) are the status of each quantity inside it. A claim takes the weakest label among its load-bearing quantities, and only a passed check raises it to confirmed.

confirmed is not "verified". Only a counterfactual method that passed its checks (D5) may be called verified (section 1.1). A confirmation by a named plant person is recorded and shown as that person's confirmation, never as savings.

5.3 Prescription#

What to do, why, by whom, and how it will be checked.

Exists today: prescription.json with the first two rows.

5.4 Action#

What actually happened. One record per executed action, whether a person did it or the writer did.

Exists today: closure/action-intent.json (leftover, missing the write fields; retired in favour of WriteRequestPlant Box write path request (direction; closure/action-intent.json retired), section 5.8). L5 card transitions record people's actions on cards.

5.5 ValueRecord#

The ledger row. One per action or per bundle, per KPI.

Exists today: ledger.mv_ledger (L2, energy-only, keyed by prescription), closure/ledger-entry.json (energy-only, different enum), L5 verification packs.

5.6 AutonomyPolicy#

The grant of authority.

Exists today: the card-transition gate in L5. No contract.

5.7 Lot and genealogy#

Which units, parts and lots passed through which assets, and how sure the link is. Stored as relational and event tables in L2 (D1).

Exists today: L2 context records (migration 014) and topology, stops and changeovers (016). No lot or link tables.

5.8 WriteRequest#

A request to change one set point, following the NE 178 Verification of Request pattern at pattern level (D17). The writer accepts nothing else.

Exists today: nothing. closure/action-intent.json is retired.

5.9 ClosureState#

The card lifecycle the L5 machine already runs, published so L6 and analytics stop guessing. Values are the code values in stamped_l5_domain/cards/states.py.

closed_verified is a code name: it means the L5 verification pack saw the change in telemetry, which is ops_confirmed in ledger terms, not counterfactual verification. The contract keeps the code value and documents this; a rename waits for 1.0.0. The 8-state description in older docs is retired.

5.10 Envelope#

The header every contract travels in.

5.11 Versioning and compatibility#

• Semantic versions per contract. While 0.x, a minor bump may break; consumers pin the minor version.
• From 1.0.0: additive fields are minor; removing or renaming a field, or changing an enum value, is major and needs a migration note and one release where both versions are accepted.
• Unknown fields are ignored by consumers; missing required fields are rejected at the seam, never defaulted.
• SE CI validates every schema and its examples (the existing contract-check workflow).