russell@unturf.com
06e6c7a918
Address Grok's two minor-improvement flags on the docs.
New docs/diagrams/{three-layer-stack,cache-key-8dim,falsification-states}.{dot,svg,png}
embedded into docs/_source/concepts.rst — visual scaffolding for the
3-layer stack, 8-dim cache_key composition, and falsification state
machine (previously prose+tables only).
docs/_source/cookbook.rst gains a "Use arborist as a Python library"
section: open_store + ingest_documents, custom Source subclass,
audit-chain walk + verify, Merkle proof round-trip, programmatic
arborist.qa.query() with OpenAICompatibleClient + StubClient swap.
Every Python recipe smoke-tested against a scratch DB before publish.
make docs-api: 0 new warnings. make test: 2557 passed.
50 lines
2.5 KiB
Text
50 lines
2.5 KiB
Text
// 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}
|
|
}
|