// falsification_state state machine — the lifecycle of a providence
// record after it lands in cache.
//
// Cache lookups filter on state='live'. Drift (re-ingest yielding a
// different document_root than the one bound into the record) flips
// the record to 'stale'. Explicit human/operator override flips to
// 'failed' (audit-preserving) or removes the row entirely via burn
// (which is refused if the record has children unless FORCE=1).
//
// Render: dot -Tsvg falsification-states.dot -o falsification-states.svg

digraph falsification_states {
    rankdir=LR
    node [shape=ellipse, style="filled", fontname="Helvetica", fontsize=10]
    edge [fontname="Helvetica", fontsize=9]
    bgcolor="white"

    start [label="cache write\n(verifier sets audit_mode)", shape=note, fillcolor="#fff7e6"]

    live [label="LIVE\ncache lookups\nreturn this row", fillcolor="#28a745", fontcolor="white"]
    stale [label="STALE\nsource drifted\n(document_root changed\non re-ingest)", fillcolor="#ffc107"]
    failed [label="FAILED\nhuman / operator\nfalsified", fillcolor="#dc3545", fontcolor="white"]
    quarantined [label="QUARANTINED\nverifier downgrade\npending review", fillcolor="#6c757d", fontcolor="white"]

    gone [label="(burn — row deleted)\nrefused if record has children\nunless FORCE=1", shape=octagon, fillcolor="#888888", fontcolor="white"]

    audit [label="every transition\nwrites one audit_event\nchain remains intact", shape=note, fillcolor="#fff0e0"]

    start -> live [label="initial state\nif verifier produced\nany audit_mode"]

    live -> stale [label="re-ingest produces\ndifferent document_root\n(drift detection)"]
    live -> failed [label="make falsify KEY=…\nREASON='…'\n(audit-preserving)"]
    live -> quarantined [label="verifier rule change\n+ promotion gate\n(rare)"]

    stale -> live [label="re-ingest matches\nbound root again\n(corpus returned to\nprior state)", style=dotted]
    quarantined -> live [label="review passed", style=dotted]
    quarantined -> failed [label="review rejected", style=dotted]

    failed -> gone [label="make burn KEY=…\nREASON='…'\n(kindergarten only)", color="#aa0000"]
    stale -> gone [label="make burn KEY=…", color="#aa0000", style=dashed]

    // Audit-chain annotation
    live -> audit [style=dashed, color="#888888"]
    stale -> audit [style=dashed, color="#888888"]
    failed -> audit [style=dashed, color="#888888"]
    quarantined -> audit [style=dashed, color="#888888"]

    {rank=same; live; stale}
    {rank=same; failed; quarantined}
}
