Chronicle: one append-only trace for every build attempt at every rung

[MaxGhenis]

Ratified 8/5. The trace of all builds — sparse/dense history, failed runs, smoke/dev rungs, shipping candidates — gets one system of record.

Design:

• builds_ledger.jsonl in THIS git repo (reviewable, versioned, CI-guarded) — not HF main, which keeps Per-target banking for the ACS transfer: preemptions mid-phase cost one target, not the phase (#578) #608's tag-only doctrine untouched. One schema-versioned row per build attempt at any rung, hash-chained (each row carries the previous row's digest — tamper-evident append-only; CI validates chain + schema).
• Row: build_id · ts · pipeline · rung (fraction token) · seed · code pin · input-pins digest · identity digest · phases reached · per-gate verdicts + receipts pointer · wall/cost · artifact location (local/volume/HF tag/discarded) · disposition (iterating → boring-counter → billed → published → certified) · prediction_id (links the pre-stated P(pass) — calibration becomes computable from build history).
• Writers: local rung runs append directly (tool-side); cloud runs emit a ledger_row.json artifact beside their manifest, harvested into the repo with the artifacts. The ledger write is part of the pipeline, not agent bookkeeping.
• Naming stays the release-id grammar; ladder ids carry fraction + seed + realized count so rung is legible from the id.
• Render: a builds page (populace.dev) reads the ledger; markdown render ships with the CLI meanwhile.
• Backfill: the 23 existing HF releases (manifests harvested) + the unpublished run 5–7 era as first-class failed/superseded rows.

Part of the #624 doctrine; consumes #616's identity machinery.

🤖 Generated with Claude Code

[MaxGhenis]

Storage decision (Max, 8/5): Supabase as the live system of record, git as the tamper-evident archive. Rationale: cloud writers POST rows directly at terminal states (kills the harvest-and-commit step — the clunkiest part of the pure-git design). Doctrine preserved: insert-only RLS role for writers (no update/delete), trigger-maintained hash chain, local spool + idempotent POST so builds never block on the SaaS, per-merge export appending to builds_ledger.jsonl in-repo as the reviewable archive, and populace.dev reads a curated public-safe view (raw rows carry costs/diagnostics that stay internal by default). Predictions table FK-joins builds so gate calibration is one query.

[MaxGhenis]

Named (Max, in the 8/5 microcosm meeting): Chronicle — avoiding the collision with the raw-data Ledger doctrine component. Naming sweep: Postgres schema chronicle containing builds + predictions tables and the builds_public view; module populace.build.chronicle; CLI tools/chronicle.py; in-repo archive chronicle.jsonl; the populace.dev page is just "Chronicle." The in-flight implementation lane built under the working name — the rename lands wholesale at its review round.

[MaxGhenis]

Naming final + one scope ruling

The tool is named Logbook. Max adjudicated the collision today: the data platform's Ledger repo becomes PolicyEngine/chronicle (a chronicle of official facts), and this build-trace tool takes Logbook — recycling "ledger" was considered and rejected because it would swap the referent of a word that has meant the data platform in a year of docs and threads. Both open PRs are renamed (#632 = the full tool, #631 = the adoption-side writer); schema logbook, roles logbook_writer/logbook_exporter/logbook_break_glass_admin, CLI tools/logbook.py, spool logbook-spool/, archive logbook.jsonl. Row bytes and digests are name-free and unchanged.

O2 ruling (dense-P3 a3 salvage candidate): excluded from the seed backfill, with this comment as the receipt. The backfill's declared scope is tagged HF releases plus run-5/6/7 attempts; a3 is neither, and the facts a row requires (timestamp window, cost, pins) are not assembled to row standard. The logbook is append-only precisely so this isn't a rewrite problem: if a3's facts get assembled, it appends as a normal row then. What I will not do is seed a row with guessed cost or timestamps.

[MaxGhenis]

Logbook live store is up — 26-row backfill loaded and verified

#632 merged (8d7ac677); the Supabase side is now applied and populated.

Applied: both migrations pushed to the populace project (it was paused; restored first), logbook schema exposed to PostgREST, and a dedicated HS256 signing key imported so the writer JWT carries role: logbook_writer rather than reusing a service key.

Live verification (psql + REST, on the real project):

• Schema: builds, predictions; FORCE row-level security true on both; roles logbook_writer / logbook_exporter / logbook_break_glass_admin present.
• The F1 fix is live and correctly bounded: the writer's only column privilege is SELECT(build_id) with policy builds_writer_conflict_select; a writer read of cost_usd returns 42501 permission denied.
• Backfill: 26 rows attempted, 26 posted, 0 retained. In the database: 1 genesis, 25 parent-child links, tail f3cffe9403ae… — byte-identical to the tail in the round-1 review receipt and the git archive.
• Dispositions: 22 published, 1 certified, 2 failed, 1 superseded.
• Redaction: the anon builds_public view exposes no cost_usd and no gate_verdicts; anon on the raw builds table returns 401.

The single-genesis guard earned its keep on day one. The first stacked smoke build (round 1, failed) wrote its row without a predecessor — my launcher omitted --logbook-prev-row-digest. Posting it was refused with 23514, the row was retained in the spool, and the store stayed at 26. Fail-closed behaved exactly as designed against a real operator error, not a synthetic one. The launcher now resolves the archive tail and passes it explicitly; that unchained round-1 row stays a local receipt and does not join the chain (its digest is bound to prev=null, so re-parenting would be forgery, not repair).

Credentials are in the operator keychain as POPULACE_LEDGER_URL / POPULACE_LEDGER_KEY / POPULACE_LEDGER_API_KEY; absent them the client is spool-only by design.