How the system audits itself

Everything you've studied builds the graph from derived signals — RPC probes, heuristics, decoders. Any of them can be wrong: a stale balance, a missed admin, an edge that no longer reflects the chain. So the system does what a careful engineer would — it re-reads the chain and checks its own work. That's the chain-reference harness, the home of the "freshness verifier" L26 kept pointing at, and the closed loop that makes discovery's honest gaps actionable.

1 · The Verifier: a set comparison against truth

The interface (verifier.go) is strikingly small. Each verifier supplies the chain truth-set, the stored set, and a per-instance recheck:

type Verifier interface {
    Class() string                                          // e.g. "HOLDS", "LENDING_COLLATERAL"
    EnumerateOnChain(ctx, block) ([]Ref, error)             // C — the canonical truth set
    EnumerateGraph(ctx) ([]Ref, error)                      // G — what we currently store
    VerifyInstance(ctx, ref, block) (pass bool, []Diff)     // recheck one ref's VALUES
}

From C and G the runner derives three kinds of finding — and that taxonomy is the whole mental model:

2 · ~30 verifiers, three jobs

The verify_*.go files (one per class) sort into three jobs — and you've met all three before:

3 · The actuator loop — what makes it more than a test

A unit test fails loudly and stops. A production graph drifts constantly and partially — you can't page a human on every transient blip. So findings flow through a streak-based actuator:

• Streaks separate signal from noise. Each finding is a durable OpenSearch doc with a streak counter: re-detected next run → streak++; resolved (no longer found) → streak = 0. Only findings with streak >= threshold are FetchPromotable — so a one-cycle mid-block balance or an RPC blip never escalates, but a persistent discrepancy does.
• Persistent findings become tickets. The LinearPromoter opens a Linear issue and stamps linear_issue_id back on the finding (so it's filed once, not every run). Drift the system can't self-correct becomes tracked engineering work — automatically.
• Some findings self-heal. Healers (runner_healer.go, healers/) auto-fix what they can — re-enrich a node, reclassify it, prune a stale edge — instead of ticketing. The harness fixes the cheap stuff and escalates the rest.

4 · Where the output surfaces

Each run writes a ClassReport (coverage %, gap/excess/drift counts) persisted as a :QualityReport node — read by the admin-panel /quality page (L17). So an operator sees, per class, "HOLDS coverage 99.2%, 14 drifts, 3 gaps" at a glance, with the durable findings behind it in OpenSearch and the escalated ones linked to Linear. The harness turns "is our graph any good?" from a vibe into a dashboard.

What you can now do

• Distinguish parity (matches Python batch) from chainref (matches the blockchain) as two correctness axes.
• Read the Verifier interface and derive gap / excess / drift from the C-vs-G set comparison + per-instance recheck.
• Explain the two-bound drift tolerance and why both bounds are required.
• Sort the ~30 verifiers into coverage / correctness / freshness, and link coverage findings to discovery gaps.
• Walk the streak-based actuator (finding → OpenSearch streak → Linear ticket or healer) and justify sampling under the RPC budget.