The layer model

flowchart TB
    %% house-style: layer-model
    gov["<b>Governance plane</b> (applies to every layer; no arrows drawn)<br/>• Data quality, evidence labels, calibration gates<br/>• Model registry, evals, sustainment (re-ID, model health)<br/>• Autonomy policy<br/>• Message/alarm budgets and disposition<br/>• Audit trail, intervention log, episode_id<br/>• Predictive safety filter (drawn in the flow below)"]
    subgraph L_plant["① Layer 1 · Plant systems (customer-owned)"]
        ps["PLC, DCS, SIS, historians, meters, MES, ERP, paper"]
    end
    subgraph L_ctx["② Layer 2 · Context"]
        direction LR
        conn["Connectors and fast read, one ingest path"] --> ctx["Context store in L2: assets, topology, states, lots, genealogy links with confidence, documents"] --> sem["Semantic metric layer"]
    end
    subgraph L_ana["③ Layer 3 · Analytics (seven-job chain, jobs 1–5)"]
        direction LR
        det["SPC → MSPC → residuals"]
        est["Estimation (KF family, twins)"]
        pred["Prediction: soft sensors, forecasts"]
        cause["Causal quality and attribution"]
        router["Method-selection router with abstain"]
        det & est & pred & cause --> router
    end
    subgraph L_dec["④ Layer 4 · Decision (jobs 6–7)"]
        direction LR
        rank["Prescriptions ranked by value and confidence"]
        opt["Optimisation: set-point, scheduling, tariff"]
        ctrl["Control: rule → advice → BO/EVOP<br/>Later: MPC; shielded RL not in the next 12 months"]
    end
    saf{{"Predictive safety filter (governance plane): every proposal passes here"}}
    subgraph L_act["⑤ Layer 5 · Action"]
        direction LR
        msg["Messages and cards"]
        exp["Experiments: step tests, EVOP, switchback"]
        wr["Policy-granted write-back"]
    end
    subgraph L_ver["⑥ Layer 6 · Value"]
        direction LR
        fb["Operator feedback and overrides"] --> led["Value ledger: counterfactual M&V per KPI"]
    end
    wb(["↩ Back to Layer 1: approved writes only, inside the plant's limits"])
    ln(["↩ Learning and sustainment: the ledger updates layers 3 and 4 and the model registry, with review"])

    agents["Agents: read-only tools over layers 2 to 4, propose only"]

    ps --> conn
    L_ctx -->|"context, states, metrics"| L_ana
    router -->|"chosen method, or abstain"| L_dec
    L_dec -->|"proposals"| saf
    saf -->|"approved only"| L_act
    L_act -->|"outcomes"| L_ver
    wr --> wb
    led --> ln
    agents -. "reads layers 2 to 4" .-> L_ctx
    agents -. "proposes to the router" .-> router

    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 gov,saf govc
    class agents agentc
    class wb,ln loopc

flowchart TB
    %% house-style: two-loops
    subgraph fast["Fast loop at the plant (Plant Box), seconds"]
        direction LR
        r["Fast read 1 s"] --> s["State estimate (twin_state)"]
        s --> d["Decision under standing policy"]
        d --> f
        f{{"Predictive safety filter"}} --> w["Writer: VoR-style verify, limits, watchdog, read-back"]
        w --> r
        f --> m["Operator message (budgeted)"]
    end
    subgraph slow["Slow loop in the cloud, minutes to weeks"]
        direction LR
        a["Analytics, MSPC, causal, forecasts"] --> p["Prescriptions, schedules, policies"]
        p --> v["Value ledger and verification"]
        v --> u["Model and parameter updates (reviewed)"]
        u --> a
    end
    fast -- "outbound sync: readings, twin_state, write_log, outcomes" --> slow
    slow -- "pulled by the plant: approved parameters, policy grants, model versions" --> fast

    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 f govc

flowchart TB
    %% house-style: layer-1-plant
    subgraph own["① Customer-owned systems: they stay in charge"]
        direction LR
        plc["PLC and DCS<br/>basic control loops"]
        meters["Energy meters,<br/>check-weighers"]
        hist["Historians, SCADA"]
        mes["MES, ERP, lab results,<br/>paper logs"]
    end
    sis{{"SIS and interlocks: outside every Stamped envelope, never read as a target, never written"}}
    subgraph read["How Stamped reads (read-only)"]
        direction LR
        ea["edge-agent: Modbus, OPC UA, MQTT,<br/>historian SQL, files"]
        up["Connectors and uploads<br/>for orders, lots, documents"]
    end
    ctx["② Layer 2 · Context"]
    wb(["↩ The only way back: an OPC UA write to an operator-settable set point,<br/>through the Plant Box writer, inside a signed operating envelope"])
    plc & meters & hist --> ea
    mes --> up
    ea & up -->|"readings, events, records"| ctx
    wb -.-> plc

    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 sis govc
    class wb loopc

flowchart TB
    %% house-style: layer-2-context
    subgraph site["At the plant"]
        direction LR
        ea["edge-agent<br/>buffer, drift watcher"]
        pb["Plant Box fast read, 1 s<br/>fast-loop tags only"]
    end
    subgraph ing["One ingest path"]
        direction LR
        in["CLOUD ingest: Envelope, sequence<br/>numbers, dedupe, replay (section 7.3)"]
        dq{{"Quality codes and evidence labels (C03, D13)"}}
    end
    subgraph store["② L2 store of record: Postgres + TimescaleDB (D1, D20)"]
        direction LR
        ts["Readings<br/>compressed hypertables"]
        assets["Assets, topology,<br/>operating states"]
        lots["Lots, events, genealogy links<br/>with method and confidence"]
        docs["Context records<br/>and documents"]
    end
    sem["Semantic metric layer: versioned metrics and baselines (C08, C10)"]
    views["Read-only graph views for L3 and KR"]
    ana["③ Layer 3 · Analytics"]
    ea & pb --> in --> dq --> ts & assets & lots & docs
    store --> sem -->|"metrics with versions"| ana
    assets & lots --> views --> ana

    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 dq govc

flowchart TB
    %% house-style: layer-3-analytics
    ctx["② From Layer 2: readings, states, lots, metrics"]
    subgraph chain["③ Seven-job chain, jobs 1–5"]
        direction LR
        j1["1 SPC"] --> j2["2 MSPC and profiles"] --> j3["3 Residuals and<br/>innovations"] --> j4["4 State estimation<br/>Kalman family, twin (C14)"] --> j5["5 Prediction<br/>soft sensors, forecasts"]
    end
    cause["Causal quality and attribution (C18)"]
    cal{{"Calibration gate (C44): coverage and NIS per model class (D14)"}}
    router["Method-selection router (C45): climbs only as far as the evidence allows"]
    abst(["↩ Abstain: say which data or test is missing"])
    dec["④ Layer 4 · Decision"]
    ctx --> j1
    ctx --> cause
    j5 & cause --> cal --> router
    router -->|"chosen method"| dec
    router --> abst

    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 cal govc
    class abst loopc

flowchart TB
    %% house-style: layer-4-decision
    ana["③ From Layer 3: chosen method and calibrated outputs"]
    subgraph jobs["④ Jobs 6–7"]
        direction LR
        rank["Rank prescriptions by value,<br/>confidence and evidence tier"]
        sp["Set-point optimisation<br/>BO or EVOP inside the envelope"]
        sched["Scheduling repair (CP-SAT)<br/>proposes a near-term sequence"]
        ctrl["Control ladder: rule, advice, BO/EVOP<br/>Later: MPC"]
    end
    person["A named person accepts any sequence before write-back"]
    saf{{"Predictive safety filter: every proposal passes here"}}
    act["⑤ Layer 5 · Action"]
    ana --> rank
    rank --> sp & sched & ctrl
    sched --> person
    rank & sp & ctrl & person --> saf
    saf -->|"approved only"| act

    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 saf govc
    class person agentc

flowchart TB
    %% house-style: layer-5-action
    dec["④ From Layer 4: proposals"]
    saf{{"Predictive safety filter (L5 autonomy, D15): operating envelope, operating state, FMEA refs"}}
    subgraph act["⑤ Layer 5 · Action"]
        direction LR
        cards["L5 card machine (ClosureState)<br/>budgets and suppression (D16)"]
        exp["Experiments: step test, EVOP,<br/>switchback, under their own policy"]
        wrq["WriteRequest (section 5.8)<br/>Verification of Request flow"]
    end
    send["One sender: WhatsApp"]
    disp["Plant Box local display (D7)"]
    wri["Plant Box writer: limits, watchdog, read-back"]
    op["Operator or owner: acts, overrides, stops"]
    wb(["↩ To Layer 1: OPC UA set point inside the operating envelope"])
    val["⑥ Layer 6 · Value"]
    dec --> saf --> cards & exp & wrq
    cards --> send & disp --> op
    wrq --> wri --> wb
    op -->|"Action records"| val
    wri -->|"Action records"| val

    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 saf govc
    class op agentc
    class wb loopc

flowchart TB
    %% house-style: layer-6-value
    act["⑤ From Layer 5: actions, outcomes, overrides"]
    subgraph val["⑥ Layer 6 · Value"]
        direction LR
        norm["Normalise: output,<br/>mix, shift, ambient"]
        meth["Method per action class (D5):<br/>switchback, else adjusted baseline;<br/>power analysis first"]
        vr["ValueRecord per KPI:<br/>energy, scrap, throughput, quality"]
    end
    tier{{"Tier from evidence labels: measured, confirmed, modeled, unknown"}}
    sign["Customer sign-off (status signed_off)"]
    ln(["↩ Sustainment: re-identify models, update the registry, widen or narrow AutonomyPolicy, with review"])
    act --> norm --> meth --> vr
    vr --> tier --> sign
    vr --> ln

    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 tier govc
    class sign agentc
    class ln loopc

flowchart TB
    %% house-style: governance-plane
    subgraph gdata["Governance plane, part 1: data and models"]
        direction LR
        labels{{"Evidence labels, data quality (C03, D13)"}}
        calib{{"Calibration gates per model class (C44, D14)"}}
        reg{{"One model registry, human-gated promotion (D9)"}}
        sus{{"Sustainment: coverage drift, PSI, re-ID (C47)"}}
    end
    subgraph gauth["Governance plane, part 2: authority and record"]
        direction LR
        saf{{"Predictive safety filter (D15)"}}
        pol{{"AutonomyPolicy, operating envelope (section 5.6)"}}
        msg{{"Message budgets, disposition (D16)"}}
        audit{{"Audit: hash-chained write_log, episode_id"}}
    end
    gdata ~~~ gauth
    subgraph layers["The layers"]
        direction LR
        L2["② Context"]
        L3["③ Analytics"]
        L4["④ Decision"]
        L5["⑤ Action"]
        L6["⑥ Value"]
        L2 ~~~ L3 ~~~ L4 ~~~ L5 ~~~ L6
    end
    labels -.-> L2
    calib -.-> L3
    reg -.-> L3
    saf -.-> L4
    pol -.-> L5
    msg -.-> L5
    audit -.-> L5
    sus -.-> L6

    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 labels,calib,reg,pol,saf,msg,audit,sus govc

flowchart TB
    %% house-style: fast-loop
    subgraph pbox["Plant Box, seconds (shadow first)"]
        direction LR
        r["Fast read 1 s"] --> q["Data-quality gate,<br/>evidence labels"] --> s["State estimate<br/>(twin_state, D3)"] --> d["Decision under<br/>standing policy"] --> f{{"Safety filter (edge copy)"}} --> w["Writer: VoR checks,<br/>limits, read-back"]
    end
    wd{{"Watchdog: heartbeat, clock skew, operator touch"}}
    disp["Local display and card"]
    op["Operator: confirms at AL2, can stop at any time"]
    ret(["↩ Set point back to the PLC; the next reading closes the loop"])
    up(["↩ Outbound sync to the cloud: readings, twin_state, write_log (section 7.3)"])
    f --> disp --> op
    op -->|"confirm or stop"| w
    wd -.->|"stop"| w
    w --> ret
    s --> up

    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 f,wd govc
    class op agentc
    class ret,up loopc

flowchart TB
    %% house-style: slow-loop
    subgraph cloud["Cloud, minutes to weeks"]
        direction LR
        in["Sync in: one ingest path,<br/>sequence numbers, replay"] --> a["Analytics: MSPC, causal,<br/>forecasts (Layer 3)"] --> p["Prescriptions, schedules,<br/>policy drafts (Layer 4)"] --> c["Cards and experiments<br/>(Layer 5)"] --> v["Value ledger<br/>(Layer 6)"]
    end
    rev{{"Review gate: no auto-promotion (D9)"}}
    u["Model and parameter updates in the registry"]
    person["Plant approver signs the AutonomyPolicy at the plant"]
    bundle(["↩ Signed bundle pulled by the Plant Box: grants, parameters, model versions"])
    v --> rev --> u
    u -->|"next cycle"| a
    u --> bundle
    p --> person --> bundle

    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 rev govc
    class person agentc
    class bundle loopc