Plant Situation Model (PSM)

Purpose#

A DecisionCaseOne run unit: intake + snapshot + obligations + candidates + terminal needs more than the EvidenceLayer contract for detector output (direction; as built: Finding finding.json 1.2.0) (FindingAs-built L3 detector output admitted to L4 (finding.json 1.2.0)) local window. Portfolio conflicts, shifting bottlenecks, shared-utility peaks, and open-card footprints live at plant scale. The PSMPlant Situation Model is the derived, versioned, per-plant model that holds that context. It is a cache with provenance in the L4 operational store — not a system of record. L2 remains plant truth for raw series and published topology (D1; KR graph modules are read-only views).

Layers#

flowchart TB
    %% house-style: psm-layers
    subgraph l2in["② Context (L2 + site pack)"]
        direction LR
        sp["Site-pack topology via L2"]
        l2s["State / alarms / material"]
        l2h["Series and baselines"]
    end
    subgraph psm["PSM snapshot (L4 cache)"]
        direction LR
        struct["Structure"]
        state["State"]
        hist["History views"]
        ctx["Plan context"]
        cons["Constraints index"]
        dec["Decision state"]
    end
    subgraph out["Run outputs"]
        direction LR
        dig["Plant digest<br/>(code-built)"]
        led["Evidence ledger<br/>for run"]
    end
    sp --> struct
    l2s --> state
    l2h --> hist
    l3["L3 baselines / methods"] --> hist
    plan["Orders, dues, roster, rates"] --> ctx
    cr["Constraint rows"] --> cons
    cards["Open / held / shadow cards"] --> dec
    struct --> snap["PSM snapshot"]
    state --> snap
    hist --> snap
    ctx --> snap
    cons --> snap
    dec --> snap
    snap --> dig
    snap --> 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 snap govc

Propagation rules#

Typed, versioned, directed, with lag:

• Upstream starve
• Downstream block
• Buffer and lag along flow edges
• Shared-resource demand aggregation

A plain k-hop neighbourhood cannot tell starving from blocking. Propagation code walks structure; models do not.

Plant digest#

Built in code, not by an LLM. Fixed schema per area:

• state summary
• ranked deviations from baseline (L3 method where certified)
• what changed since the last digest
• open footprints
• constraints about to expire
• unknowns

Plus a coverage manifest: assets and resources included, excluded, or unknown. Size budget and digest version are pinned in the lockfile.

Bitemporal snapshots#

Each element carries effective time and recorded time. A run snapshot is as-known-at: late L2 corrections do not change what replay says L4 knew. Working ledgers freeze the snapshot into the DecisionTraceAlways-on record: observed, context, action, policy, approval, outcome (and seam decisions) (05-context-engineering.md).

Scaling#

• Hierarchical partitions: plant → area → resource group → asset
• Incremental updates by watermark
• Deterministic scanners run before any LLM call
• Admission rule: an element exists only if a family, pattern, or constraint kind reads it (ADR-019 / research 17)

Graph and zoom#

Models never traverse the graph and never invent edges into live structure (suggestions go through the owner path in 02-plant-structure.md).

Pluggable elements#

Each PSM element has its own builder registered behind a port. An element can be added, replaced, or retired without rebuilding the rest. New builders are registry + lockfile + replay (21-registries-and-stage-graph.md).

Why derived and temporal#

Per-Finding assembly cannot see portfolio conflicts, recurring patterns, or shifting bottlenecks. An L2-owned product graph turns every topology change into a store migration and reopens “graph becomes the product.” The PSM is the middle path: derived, versioned, admitted by use, replayable.

v1 slice vs later#