07 Interfaces, ownership and the control channel

Docs 01 to 06 describe each piece. This doc fixes how the pieces meet: who owns each job, which topic and table each piece uses, how the cloud reaches the Plant BoxPlant-side computer for the fast loop (direction; D4), and what happens when a link fails. Where it settles something the earlier docs left open, it says so; those points are listed for sign-off in the fast-loop handoff.

1. Two paths, one owner per job#

2. Topic registry#

All topics sit under stamped/v1/{org}/{plant}/. Docs 02 and 05 and the data plane page use these names exactly.

Broker ACLs follow the publisher and reader columns; nothing else may publish or subscribe. Fast batches for replay travel on the existing durable upload, not on these topics (section 7).

3. Ownership matrix: tables#

Rows reach L2 through records/{type} and the existing L1 cloud path, as upserts on the key in 05. Each row carries episode_id where one applies and the plant-box lockfile id (section 9).

write_log in L2 is the record of every write and refusal. The L5 evidence store keeps references to its rows, not a second copy.

4. Control channel: cloud to plant box#

The plant allows outbound connections only, so the cloud never connects in.

1. sync-agent polls L2 over HTTPS (GET /v1/plants/{plant_id}/plant-box-config?since=) with a plant-box credential.
2. The response is a plant_box_config bundle: accepted procedures with versions and recipients, per-shift procedure switches, approved parameter rows, part aliases, roster roles and the L5 budget settings. L5 and the L3 tuning job write their parts into L2; L2 assembles the bundle.
3. The bundle is signed with the Stamped release key. sync-agent verifies the signature and version, then publishes it on control/in. The twin and relay load only verified bundles and stamp the bundle version on what they produce.
4. If the link is down, the last verified bundle stays in force.

Safety asymmetry (today's stage). A remote change can always switch a procedure or a write tag off, and the box applies an off at once. Switching writes on takes a person at the plant: the "Stamped auto" switch on the machine plus the in-charge's enable on a plant-local screen. The writer's allow-list, limits and hazard rows are not carried on this channel; they live in the site packVersioned, owner-reviewed plant configuration including topology, change only on site, are signed by the plant's production head and are checksummed by the writer. This matches section 7 of the master document: writes do not come from the cloud.

Message-only procedures (AL1Autonomy levels (direction; fast-loop stages 1–3 = AL1–AL3)) can be switched on for a shift from L6, because they write nothing.

5. Stage 2 confirmation path#

At AL2 a person confirms each write. The confirmation is a token, not a write: it may come from a plant-local screen or as a reply to the relay's message (carried back through cloud L5 and the control bundle when the link is up). The twin then builds the write request on the Plant Box, and the writer runs every check in 02 section 3.3, including the 2-minute token age. A token never carries a value the twin did not propose.

6. Messages: the L5 relay and one budget per person#

• The twin never sends to WhatsApp, SMS or a stack light directly. It publishes on messages/out; stamped-l5-relay (code in closure-verification) owns delivery from the Plant Box.
• Online: the relay applies the L5 budgets from the bundle and reports every send and reply to cloud L5, which stays the budget authority (ADR-036, D16).
• Offline: the relay sends alerts and signals only, under conservative local caps, and holds actions until the link returns. Cloud L5 reconciles the relay's log on return.
• One person budget. L4's attention_budget stays a pre-filter on cards (l4/22). Any card or action that reaches a person counts against that person's L5 action budget. Alerts and signals keep their own rules.

7. One Finding outbox; the fast-data tier#

Findings. The twin holds no outbox. Card-worthy patterns become EvidenceLayer contract for detector output (direction; as built: Finding finding.json 1.2.0) (direction; as built: FindingAs-built L3 detector output admitted to L4 (finding.json 1.2.0) 1.2.0) on the scheduled path: L3 engines read twin records from L2 (a procedure that keeps not being followed, model drift on an asset, repeated risk on one part) and emit through the existing outbox and dual-lane gate. Lab still never promotes.

Fast data. The Plant Box keeps a rolling fast archive and uploads it in compressed batches to telemetry.fast_reading, kept at least 13 months so a full-year replay is possible. Per-minute measurements continue on the existing path, so live upload is unchanged (ADR-034).

8. Episode trace#

The twin mints episode_id when a procedure or alert first fires for a condition. It is carried on twin records, messages, replies, follow_through, missed_savings and write_log, and the L5 thread uses it. A Finding built from twin records lists the episode ids in its evidence references, so a card links back to the floor events behind it.

flowchart TB
    %% house-style: episode-trace
    subgraph floor["Plant Box"]
        direction LR
        edge["L1 edge fast read"] --> twin["L3 twin"]
        twin --> relay["L5 relay"]
        relay --> person["Operator"]
        twin --> writer["L1 writer"]
        writer --> twin
    end
    store(["L2 records, follow_through, write_log"])
    twin --> store
    person -.->|"Done reply"| relay
    twin -.->|"follow-through from machine data"| twin

    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 person agentc
    class store loopc

9. Plant-box lockfile#

One versioned manifest per Plant Box: edge-agent, sync-agent, writer, twin and relay versions; procedure catalog version; parameter set version; site pack version and checksum; bundle version. Signed with the Stamped release key. Its id is stamped on every record and every write. It plays the role the L4 release lockfile plays for the decision runtime (l4/16).

10. Service levels#

11. Degraded modes#

12. Control today#

Stamped recommends and the plant team decides. Safety systems, quality holds and release, maintenance authorisation and lockout, and customer priority, promise dates, routing, master data and the full dispatch sequence stay with the plant. Writes reach only allow-listed process setpoints through stamped-writer, earned stage by stage as ADR-035 sets out (AL1 messages, AL2 confirm, AL3 standing); that is the first path to autonomous execution, under the plant's control and approval.