Contract deltas (cross-layer)

Documentation and schema intents for L4 to run against L1–L6. Implementation follows in the layer repos under separate plans.

Section 5 reconciliation (summary)#

---

1. L1 → L2: topology records#

section 5 map: Envelope (section 5.10) + context inputs to PlantState (section 5.1, direction). Status: as-built (contracts 0.16.0 / L2).

Implemented: one record_type topology_record with a kind discriminator (area, flow_edge, shared_resource, meter_node, asset_draw); schema contracts/schemas/plant/topology-record.json. See L1-L2-DATA-PLANE.md.

New record kinds (site-pack topology section published as typed context records):

Rules:

• Versioned with the site packVersioned, owner-reviewed plant configuration including topology; owner-reviewed before publish.
• L4 PSMPlant Situation Model builder consumes via builder reads (bulk/list). Not agent tools.
• Suggestions from models do not publish here until owner confirmation (02-plant-structure.md).

---

2. L2 → L4: builder reads vs agent tools#

section 5 map: Envelope (section 5.10); builder reads feed PSM / PlantState (section 5.1, direction). Status: as-built (contracts 0.16.0 / L2).

Builder reads in contracts/tools/l2-builder-reads.json (builder_topology, builder_changes, paths under /v1/builder/); agent tools in contracts/tools/l2-query-tools.json 1.1.0. The two files share no path.

Both are read-only. Contract docs must name the two catalogs so an agent cannot call a builder bulk export as a “tool.”

---

3. L3 → L4: Finding floor (unchanged intent, sharpened)#

section 5 map: EvidenceLayer contract for detector output (direction; as built: Finding finding.json 1.2.0) (section 5.2). Status: contract floor; as-built: finding.json 1.2.0.

L4 intake requires (existing research 15 floor, made explicit for implementers):

• detector_id, detector_version
• condition / asset binding
• evidence references
• verification plan (or explicit absence → shadow / withhold per family rules)
• calculator references for any priced effect

Uncertified detector versions → shadow only.

Discovery support from L3 (new consumption, not new L3 product claim):

• condition test API for hypothesis grounding
• verification-plan builder from signals already in L2
• simulator methods with intended-use envelope
• system methods (bottleneck, blocked/starved, utility balance) where certified

Detail: 15-l3-l4-interface.md.

---

4. L4 → L5: card proposal#

section 5 map: PrescriptionWhat to do, why, who, check plan (direction; as built: prescription.json 1.0.0 / card-proposal) (section 5.3). Status: as-built (prescription.json 1.0.0, card-proposal schema); direction fields in section 5.3 (action_class, options, required_autonomy_level, …) extend the wire without retiring the facts below.

Emit / supersede payload remains one card proposal (direction: Prescription). Fields:

L5 does not re-judge kernel criteria. It owns live card lifecycle, notification, and verification execution. On operation=supersede, L5 marks the prior open proposal superseded (not a new closure state) only if that proposal is not yet owner-accepted; otherwise L5 rejects the supersede and L4 must emit a separate card or conflict note.

Hold never appears on this interface — holds stay in the L4 store.

---

5. L5 → L4: learning facts#

section 5 map: not a section 5 wire contract; closes feed case libraryEpisodic store of traces joined with L5 outcomes; authority when it disagrees with Hindsight and ValueRecord / Action context (sections 5.4–5.5). Status: contract (memory ports).

Typed learning facts for Hindsight / case library (eligible vs ineligible close, outcome null rules): see 06-memory.md. Ineligible closes must not inflate proof counts.

---

6. L6 Ask#

section 5 map: none (presentation over L4 tools; read-only per section 8). Status: as-built + contract.

Ask is a view over L4 (and L5 ClosureStateEleven code states on the live card (direction; as built: stamped_l5_domain/cards/states.py) / card state, section 5.9). No second memory judge. Dialogue banks are hard-walled (14-ask.md). No new write contract.

---

7. Soft-gate / opportunity ledger (L4-internal)#

section 5 map: none (L4 store). Cards that graduate use Prescription (section 5.3) with exploration=true. Status: contract.

No cross-layer contract required for the ledger itself. Soft-gate threshold changes stay inside L4 registries. Exploration cards that emit use the L4→L5 fields above with exploration=true.

---

8. Disagreement policy amendment#

section 5 map: none (L4 runtime); consistent with section 8 read-only agents and validator gates. Status: contract.

Research notes 14 / 15 described low confidence falling back to a generative agent. Amended: seams touching action, owner, constraint, verification, or terminal withhold on dual-family disagreement. Routing seams use the registry default. Documented in 11-models-and-seams.md and ADR-023.

---

Implementation order (suggested)#

1. Topology record kinds + site-pack section (L1/L2)
2. Builder-read catalog (L2)
3. L4 store + PSM builder (L4)
4. FindingAs-built L3 detector output admitted to L4 (finding.json 1.2.0) intake + kernel (L4)
5. L5 consume new proposal fields
6. Discovery scanners + patterns
7. Opportunity ledgerStore of every blocked candidate with gate id and later outcome if known + soft-gate calibration

---

v1 slice vs later#