LEDGER — the intent ledger, v0.1

1. What the ledger is

07A persistent, content-addressed store of memoized queries about the project: get_or_compute(query) -> entry.

08Cache hit ≈ $0; miss runs the producer (algorithm below the floor, LLM above it) and materializes the result.

09Execution model borrowed from Salsa / the rustc query system (MIT/Apache-2.0 — ideas and, where useful, code); persistence and cross-process reach are ours, because our queries span tools, sessions, and machines, which in-memory incremental frameworks do not.

10What it is not:

• 11not ground truth (authored truth lives in code tags and spec units — PROP-014);
• not committed to git (regenerable derived data);
• not a vector database (embeddings are a possible later producer, not the store's identity).

2. Two storage classes — the load-bearing taxonomy

13The conform engine's fact store (ENGINE §3) is the facts class instantiated.

14Everything an LLM produces is interpretations class, no exceptions.

3. Epochs — contextual invalidation

epoch = H( dependency lockfiles (Cargo.lock, vibe.lock)
         , toolchain version
         , discipline-package versions in effect
         , metamodel schema version )

16Epoch changes when the context of meaning changes, even though no subject file did.

17Interpretations keyed under an old epoch are not served — hard invalidation, no serve-while-stale for A1-critical surfaces.

18The recompute decision then happens above the floor: the producer may read the old entry as a draft input ("here is what was previously believed; re-verify against the new epoch"), which converts most invalidations into cheap re-affirmations rather than from-scratch work — A2 preserved in weakened, honest form: never pay full price twice. Specified, not built: no producer reads a prior-epoch entry. The one producer that ships, explain.item/prose-template-1, renders from scratch on every miss (ledger.rs:151) and never opens the old slot; there is no draft-input path in any engine crate, stack CLI or host driver. The clause costs nothing today because a deterministic template pays no full price to begin with — it becomes load-bearing when the first LLM producer lands.

4. Provenance — every entry confesses its origin

19Each entry carries {producer, model_id?, prompt_rev?, inputs (hashes + spec URIs ~r), epoch, cost, created_at, confidence}. Partly built (the B-022 slice, 2026-08-04): the entry wrapper ships and stores {schema, kind, producer, epoch, inputs_hash, created_at} — the fields a deterministic producer can populate (ledger.rs, LedgerEntry). The rest of the row — model_id?, prompt_rev?, cost, confidence, and spec-URI ~r inputs — has no writer: every shipped producer is a deterministic template, and those fields first get a value when the external-LLM client lands (→ BACKLOG.md B-020). Interim per the owner's B-022 ruling, 2026-08-04.

20Every rendered explanation displays its provenance line ("computed at PROP-003#conditional-deps~r2, epoch 7f3a, model …").

21Staleness thereby becomes detectable by the reader even across policy bugs — the last line of defense.

5. Storage and lifecycle

• 22Layout: .ledger/objects/<sha256[0..2]>/<sha256> + a small index; sharded like git objects. Local per checkout; CI carries a shared warm copy (standard action-cache pattern, cf. Bazel/sccache — Apache-2.0 prior art, ideas only needed). Partly built: the sharding and the local-per-checkout half ship and run — ledger.rs:119-122 builds exactly that path and a live store stands at .ledger/objects/<2>/<64> alongside .ledger/telemetry.json. The index does not exist: the store is directory-only, and nothing enumerates it. The CI warm copy has no carrier — this repository's owner decision is no-CI, so the clause is not unimplemented so much as unapplicable here, and the terraform close-out already records that the CI bullets need parameterising to "where CI exists".
• GC: LRU with a pin set (entries referenced by the current release slice are pinned). Size budget configurable; eviction never affects correctness, only cost. Specified, not built: no GC exists — no LRU order, no pin set, no size budget; the store only grows, and nothing deletes a slot (ledger.rs writes objects and never removes them). Dormant by design until two keys turn: eviction pressure needs a producer whose recompute costs something (→ BACKLOG.md B-020 — the shipped deterministic template recomputes for ≈ free, so today there is nothing worth evicting), and the pin set's source is the release slice (§7, itself waiting whole on the owner's B-015 notice). Interim per the owner's B-022 ruling, 2026-08-04.
• Concurrency: entries are immutable values under content keys; last-write-wins on identical keys is benign.
• Telemetry (feeds the Charter's headline metric): hit rate, cost per query kind, LLM-$ per merged change, and the contextual-rot rate — fraction of epoch-invalidated entries whose re-verification changed the answer. Threshold from the design review: if rot among hash-valid entries exceeds ~10–15% per epoch window, the epoch formula is too coarse and gains inputs (e.g., per-subsystem epochs). Partly built: two of the four measures stand — hit rate (live hits/misses counters, .ledger/telemetry.json) and the contextual-rot plumbing (rot_checks/rot_changed counters; no data until a producer re-verifies an epoch-invalidated entry — none does yet). The two cost measures have no carrier: Telemetry has no cost field and no priced work exists to meter until the external-LLM client lands (→ BACKLOG.md B-020); the per-kind split gained its axis with the B-022 QueryKind enum (2026-08-04) and turns on with the second kind. Interim per the owner's B-022 ruling, 2026-08-04.

6. Query kinds shipped in v0.1

1. 23facts.extract(file) — frontends (algorithmic).
2. explain.item(symbol) — structured subgraph (algorithmic) + optional prose render (LLM, interpretations class).
3. classify.legacy_unit(text) — importer support (LLM). Specified, not built: this query kind has never been run. legacy_unit / classify.legacy return no hit in any engine crate, stack CLI, host crate or host artefact — the only occurrences repository-wide are this line, its vendored copies, and a campaign document citing it as unbuilt. No importer path exists to support.
4. propose.links(crate, doc) — Phase-2 mining (LLM; output lands in the proposals file, never directly in code — affirmation is a human diff, PROP-014 §2.7).

24Everything else waits for demand: a query kind is added when two distinct consumers ask for it.

7. The release slice

25At tag time, a frozen subset — facts for the tagged tree + affirmed interpretations (item summaries, command explanations) — is exported, signed, and shipped with the package (the AI-native OSS artifact: agents debugging vibe at v0.3.2 query the v0.3.2 slice). Specified, not built: no export, no signing and no shipping path exists in any engine crate, stack CLI or host driver. A strict subset of the parked security programme — and because this section's own rule forbids unsigned remote exposure, there is no honest unsigned interim: the mechanism waits whole for the owner's B-015 notice (BACKLOG.md B-015 — «НЕ строить до его специального уведомления»). Interim per the owner's B-022 ruling, 2026-08-04.

26Unsigned slices are not exposed remotely, full stop (PROP-014 §2.8.4).

27Signing scheme is Charter-level Open Question; until it lands, the slice exists for local use only.

8. Failure modes, named

• 28Confident staleness → epochs + hard no-serve + provenance display (§3–4).
• Cache poisoning (a producer writes wrong values at scale) → producer id + prompt_rev in keys make wholesale invalidation of a bad producer one predicate; release slices are re-derivable from source. Partly built: the second half holds unconditionally — the store is derived data, git-ignored and regenerable, so deleting it costs nothing but time. The mitigation as stated does not: prompt_rev is in no key (§2), and because the key is an opaque sha256 over producer+epoch+subject rather than a structured tuple, a bad producer's entries cannot be selected at all — there is no predicate, no index to run one over, and no command that sweeps by producer. Today's answer is to delete .ledger/ wholesale.
• Key under-specification (two different questions colliding on one key) → query kinds are a closed enum with reviewed key schemas; adding a kind is a PR, not a string.
• Ledger worship (treating renders as truth) → renders cite spec URIs; the --json raw subgraph is always available; A4 keeps the human the accountability point.

29Any query kind, key field, or policy here not exercised by Playbook Phase 5 is either removed from this document or annotated in place as specified, not built — never carried as unmarked aspiration.