v2 surface migration plan: retire frozen ledger-named machine surfaces

[MaxGhenis]

The 2026-08-07 rename (PR #142) deliberately froze every machine surface at its v1 ledger-named form. This issue scopes the deliberate v2 migration:

• Schema ids: ledger.bundle*.v1, ledger.build_artifact.v1, ledger.consumer_fact.v1, ledger.relational.v1, policyengine_ledger.{consumer_artifact,target_profile,resolved_target,approved_agents}.v1
• Fact-identity hash domains (ledger.*.v2) — renaming changes every fact hash; needs an explicit identity-migration story (dual-hash window or v3 domains) coordinated with the witnessed journal
• R2 buckets ledger-raw/ledger-derived and storage.r2 manifest keys; ledger.db artifact filename
• Supabase schema "ledger", mirror tables/columns (ledger_builds, ledger_source_status)
• Governance role ids (ledger-*) and concept authorities (ledger-us)
• POLICYENGINE_LEDGER_* / LEDGER_* env names (dual-read fallback)
• CLI ledger alias retirement after consumers migrate (María's publish flow, microcosm build scripts)
• codex/thesis-ledger-facts branch + thesis witness machinery (Thesis session owns the canonical-URL PR)
• thesisinstitute.org /ledger app dir + journal data paths (deferred with the witness machinery)

[MaxGhenis]

Migration spec: three mechanisms, strict order

Each frozen surface is load-bearing in one of three different ways, so this is three migrations, not one rename. Historical bytes migrate nowhere under any of them — witnessed history keeping ledger-era names is a feature, the same way the immutable releases/README.md is: the record shows what things were called when they were recorded.

1. Fact identity — migrate by epoch, never in place

The hash domains (ledger.aggregate_fact.v2, ledger.semantic_fact.v2, assertion ids av2:) sit inside every fact key, golden, witnessed row, and registered-target binding. Renaming in place invalidates all of them simultaneously; the correct move is the av1→av2 precedent:

• Introduce chronicle.*.v3 domains for newly emitted facts at a declared cutover release.
• Dual-domain acceptance in every validator, landed in lockstep before the cutover: chronicle build/load, microcosm require_pins row validation, the brier append gate (which recomputes keys byte-identically with the chronicle side — both move together or neither), and the vidimus append_gate/release_chain spec pins. The vidimus change requires a pins update plus a fresh byte-equivalence re-proof at chronicle's then-current pin, per the standing rule in the shims.
• ledger.*.v2 hashes stay valid as history forever. No golden regenerates; no witnessed row rewrites. Consumers distinguish era by domain prefix, which is the point.
• Schema ids (ledger.bundle*.v1, ledger.consumer_fact.v1, …) ride the same mechanism: v2 schema ids are chronicle-named, v1 stays parseable, emit flips at cutover.

2. The journal — migrate by witnessed continuation

The codex/thesis-ledger-facts branch, journal data paths, and pin bindings can move only the way the journal itself moves: append-forward, witnessed.

• Rename the branch (GitHub preserves history and redirects); cut a genesis-style release manifest attesting continuation at the new name — and, once Anchor witnessed release manifests in Bitcoin via OpenTimestamps #182/Schedule daily OpenTimestamps anchoring of the witnessed journal #183 land, anchor that continuation release via OTS as well as the TSA pair.
• Repoint the brier pin and the site in lockstep. The pin validator accepts the historical branch string for historical v3 registration snapshots — their contract hashes contain thesis-ledger-facts and remain true statements about the past — and requires the new name from the continuation release forward.
• Thesis session owns the canonical-URL and witness-pin halves (already noted in the issue body); coordinate the cutover release with them so both land in one witnessed step.

3. Operational stores — migrate by dual-run

R2 buckets, ledger.db, the Supabase "ledger" schema and mirror tables, env names, role ids, concept authorities: new chronicle-named homes for new writes, backfill, repoint consumers, retire the old — with one hard exception: archived witness records pin raw R2 URLs by hash. ledger-raw/ledger-derived go read-only-preserved forever; nothing archived is rewritten or moved. Env names get a dual-read window (CHRONICLE_* preferred, LEDGER_* honored with a deprecation warning) so María's publish flow and the microcosm build scripts migrate on their own schedule; the CLI ledger alias retires last, after both are confirmed off it.

Sequencing and gates

Epoch (1) first — it unblocks nothing else but touches the most validators, so it wants the longest bake. Journal continuation (2) second, as a single witnessed step. Infra (3) third, piecewise and boring. Each phase behind the existing gates: dual-domain validators land with adversarial tests before any emit flips; the continuation release is judged by the append gate like any other; vidimus equivalence re-proof precedes the consumption bump.

Out of scope, deliberately: microcosm-dynamics (its own repin ceremony, microcosm-dynamics#373, dynamics lane owns it — "ledger" there is generic vocabulary inside registered keys); all committed goldens, fixtures, and recorded traces; anything under releases/ (byte-immutable post-genesis).

Open context worth tracking alongside: residuals R2/R5/R9 from the July hardening reviews (feed-dir publication, typed periods on US-fiscal paths, allowedHosts provenance), and Thesis's USAspending contract-controls-outcome fix, which must land before any registration references those templates.

[MaxGhenis]

Execution started 2026-09-02, per the three-mechanism spec above. Three PRs are in preparation and will link back here:

• Mechanism 1, step 1 (this repo): dual-domain acceptance — chronicle-era hash domains (chronicle.*.v3) and chronicle-named schema ids accepted by every reader/validator, emit unchanged. The emit flip is a later PR gated on the consumer validators.
• Mechanism 3, slice 1 (this repo): CHRONICLE_* env names with LEDGER_* fallback and deprecation warning, chronicle.db for new suite outputs (ledger.db still read), R2 bucket names configurable with defaults unchanged, plus a documented bucket-cutover checklist. Supabase schema/table names and the ledger CLI alias stay for later slices.
• Consumer side (PolicyEngine/microcosm): accept both consumer-artifact schema ids and both key epochs; CHRONICLE_* env names.

Gates that are not code:

• Creating chronicle-raw / chronicle-derived on the pinned Cloudflare account needs an R2-scoped login (the current wrangler token has user:read only).
• Mechanism 2 (journal continuation) waits on Anchor witnessed release manifests in Bitcoin via OpenTimestamps #182 and Schedule daily OpenTimestamps anchoring of the witnessed journal #183 merging and the first Bitcoin attestation, as specified.
• Thesis-side pins (scripts/pin_ledger.py, verify_custody.py, witness_upstream_ledger.py, three workflows) hard-compare the branch string; they move with the continuation release, owned by the Thesis lane.

[MaxGhenis]

Mechanism 3 progress (2026-09-02): chronicle-raw and chronicle-derived now exist on the pinned account. Backfill of ledger-raw → chronicle-raw is complete: all 156 manifest-declared raw objects are present in the new bucket at their recorded keys, each verified against the sha256 in the key, with a hash-verified readback. Twelve of them had never been uploaded to ledger-raw at all despite manifests recording a URI there; they were recovered from publishers (8, byte-exact) or tracked repo copies (4) and written to both buckets at the recorded keys, so nothing archived was rewritten and the recorded URIs are now true. Details and the three follow-ups (R2-verify in inventory, IRS re-publication of the 2022 IRA tables, OBR blocking unattended fetch) are in #225.

ledger-derived cannot be enumerated with the current tooling (no object-list command in wrangler; remote dev needs a workers.dev subdomain on the account), so its dual-run starts with new writes only; backfill follows once listing is possible. Bucket defaults stay on ledger-* until the slice-1 PR lands and the consumers repoint.