How a finding becomes a decision card

A detection in L3 becomes Evidence, L4 turns Evidence into at most one Prescription draft, and L5 turns that draft into a live card assigned to a person on shift. Each hop runs on a named contract, and any kWh, kilogram or rupee figure on the card must resolve to an Evidence record.

How to read it.

Arrow labels are the contracts. Where the code still uses an older schema, it is named in brackets.
Yellow boxes are gates. The dual lane in L3 keeps lab output from reaching L4, and the safety filter checks every proposal that implies action.
Withholding is a normal result. L4 records why it did not send a card.

Build now: this whole path at AL1. Later: the same path feeding WriteRequests once a plant grants AL2.

View Mermaid source

flowchart TB
    %% house-style: tour-card-path
    subgraph l3["L3 intelligence-core"]
        direction LR
        eng["Engines on L2 telemetry"] --> lane{{"Dual lane: only status=emitted, delivery=l4 leaves"}}
    end
    subgraph l4["L4 DecisionRuntime"]
        direction LR
        case["Decision case and situation model"] --> rx["Prescription draft: options, owner role, autonomy level, M&V plan"]
        case --> wh["Withhold or abstain, with a trace"]
    end
    saf{{"Predictive safety filter, for anything that implies action"}}
    subgraph l5["L5 closure-verification"]
        direction LR
        card["Live card: role resolved to a person"] --> send["One sender, with message budgets"]
        send --> verify["Verification pack checks L2 telemetry"]
    end
    person["Person on shift: accept, edit, reject or defer"]
    led(["ValueRecord in the ledger, then learning"])
    lane -- "Evidence (as built: Finding 1.2.0)" --> case
    rx --> saf -- "Prescription (as built: card proposal)" --> card
    send --> person --> verify
    verify --> led

    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 lane,saf govc
    class person agentc
    class led loopc

In L3: detect and label#

L3 engines run on schedule over L2 telemetry and emit findings. Today the output is Finding 1.2.0, an energy-centric schema that requires a monthly kWh and rupee estimate. The direction is the Evidence contract: a typed claim with its support, a contract tier (measured, confirmed, modeled or unknown) and a value vector that can carry scrap, throughput or quality risk as well as energy. Only findings with status=emitted and delivery=l4 leave L3. Lab results never promote themselves.

The method router decides how far up the seven-job chain the evidence allows. If the inputs are Assumed or Unknown, or a model has not passed its calibration gate, the router abstains, and that is recorded as a result rather than an error.

In L4: decide, or decline to#

DecisionRuntime takes evidence into a plant work queue, builds a decision case against the situation model, and produces at most one owned Prescription draft for the condition. The draft carries what, why, who, when, the expected impact and the M&V plan. It lists options with predicted outcomes, and hold is always one of them. It also states the autonomy level it would need and an expiry time.

L4 may also withhold, supersede an earlier proposal, or abstain. Each of those leaves a decision trace, so "why didn't we get a card?" has an answer. L4 never assigns the final person and never sends a message.

In L5: a person, a channel, a closure#

L5 resolves the owner role to a person on shift and sends the card through one sender. That sender carries budgets and suppression (D16), so a plant does not get flooded. The design target is a card within two minutes of the prescription at p95. The person accepts, edits, rejects or defers, with a reason.

The card then moves through ClosureState, the 11 states the L5 machine already runs. A verification pack checks the change in L2 telemetry. Note the naming trap: closed_verified in code means the change was seen in telemetry, which is ops_confirmed in ledger terms, not a counterfactual verification. The outcome lands as a ValueRecord per KPI, and L6 shows the queue, the card and its history.

Go deeper: proposal and live card · L4 decision runtime · L5 closure