rvlib-shipkit 0.34.0 → 0.35.0

package/src/core/run-ci.ts

@@ -11,15 +11,15 @@ import { reportToMotherhome } from './motherhome.ts'
 import { collectChecks } from './run-check.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
-import { runTasks, type TaskResult } from './task-runner.ts'
+import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 import { rmSync } from 'fs'
 
 import { SHARE_ENV } from '../release/releases-share.ts'
 import { collectReports } from '../release/run-releases.ts'
 import { withContractsScope } from '../contracts/contracts-once.ts'
-import { gateUnits } from '../ledger/gate-units.ts'
-import { validateRegistration } from '../ledger/git-key.ts'
+import { envTier, FULL_TESTS_ENV, gateUnits, type TestTier } from '../ledger/gate-units.ts'
+import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -61,6 +61,14 @@ export type CiOpts = {
      *  loads of repo.config.ts can disagree, and the release path classifies
      *  rule-vs-probe severity from the config it holds. */
     config?: RepoConfig
+    /** re-measure everything: no unit replays from the ledger, and what this
+     *  run measures is stored fresh. Travels to child checks as SHIPKIT_FRESH. */
+    fresh?: boolean
+    /** read the ledger at all. The release path passes false, unconditionally
+     *  and not configurably: every remaining hole in the key is then capped at
+     *  "an agent saw a stale local green", never "a stale green authorised a
+     *  publish" (ledger/ledger.ts rule 4). */
+    ledgerRead?: boolean
     /** which test tier the run asks the repo's suite for. 'quick' is the
      *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every task, which
      *  a suite reads to include the slow, real-world tiers it otherwise skips.
@@ -70,12 +78,8 @@ export type CiOpts = {
     tests?: TestTier
 }
 
-export type TestTier = 'quick' | 'full'
-
-/** the env var a repo's own suite reads to widen itself. Named here because
- *  the gate is what sets it, and a suite that invents its own name is a tier
- *  the release path cannot reach. */
-export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+export type { TestTier } from '../ledger/gate-units.ts'
+export { FULL_TESTS_ENV } from '../ledger/gate-units.ts'
 
 /** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
  *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
@@ -118,7 +122,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const all = allTasks(c, root)
     const { disabled, unfilled } = all
     const skipIds = new Set(o.skipTaskIds ?? [])
-    const tier: TestTier = o.tests ?? (process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick')
+    const tier: TestTier = o.tests ?? envTier()
     const tasks = all.tasks
         .filter((t) => !skipIds.has(t.id))
         // the whole run carries the flag rather than one task id: a repo names
@@ -132,27 +136,37 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
     for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
-    // the cache-declaration state, once per run. NO git work happens here and
-    // nothing is cached yet: this is the REGISTRATION half, which is pure, and
-    // it has to be loud in the gate rather than only in `shipkit keys`,
-    // because a unit declaring two contradictory populations is a bug in what
-    // binds every repo. The burn-down is one line, never a wall.
+    // THE LEDGER, opened once per run and AFTER the fix pass: the fixers
+    // rewrite source, and a scan taken before them would have every unit
+    // discarded by its own gate's repair work.
+    //
+    // Registration is validated on the way in, and it is loud in the gate
+    // rather than only in `shipkit keys`, because a unit declaring two
+    // contradictory populations is a bug in what binds every repo. The
+    // burn-down is one line, never a wall.
     let registrationFailed = false
+    let ledger: Ledger | null = null
     try {
-        const reg = validateRegistration(gateUnits(root, c))
+        ledger = Ledger.open(root, gateUnits(root, c, tasks), {
+            cliEntry: new URL('../cli.ts', import.meta.url).pathname,
+            read: o.ledgerRead,
+            fresh: o.fresh,
+        })
+        const reg = ledger.layer.registration
         for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
         if (registrationFailed) sink('      fix: a unit declares `inputs` (content), or `ttl` (world), or `never: <reason>`, and never two of them')
         // both counts, always. Printing only the burn-down made `never:` the
         // cheap way to shrink the visible number, and that field carries no
         // verification at all: a growing decided population has to be as
-        // visible as a shrinking undeclared one. No causal clause either,
-        // because nothing is cached yet and "so nothing can replay them"
-        // implies the rest are being replayed.
+        // visible as a shrinking undeclared one.
         const decided = reg.units - reg.burnDown.length - reg.declared
         if (reg.burnDown.length > 0 || decided > 0)
-            sink(`skip: cache declarations — ${reg.declared}/${reg.units} declared, ${decided} decided uncacheable, ${reg.burnDown.length} undeclared (shipkit keys --burn-down)`)
+            sink(`skip: cache declarations — ${reg.declared}/${reg.units} declared, ${decided} decided uncacheable, ${reg.burnDown.length} undeclared, so they are measured every run (shipkit keys --burn-down)`)
+        if (ledger.layer.failure != null)
+            sink(`WARN the git scan failed, so NOTHING replays and nothing is stored this run — ${ledger.layer.failure}`)
     } catch (e) {
-        sink(`WARN cache declarations unreadable (${String(e).slice(0, 160)}) — nothing is cached, so the gate is unaffected`)
+        ledger = null
+        sink(`WARN ledger unavailable (${String(e).slice(0, 160)}) — every unit is measured this run, so the gate is correct and slower`)
     }
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
     // look like a full one (the fresh-repo floor gap)
@@ -176,22 +190,77 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // paying a 4s network survey to answer it is the same bug --only was
     // fixed for
     const willRunChecks = o.skipChecks !== true && (o.onlyIds ?? []).length === 0
-    const survey = willRunChecks ? collectReports(root, c).catch(() => null) : null
-    const summary = await runTasks({
-        tasks,
+    // REPLAY, before the DAG sees the list. A replayed task is removed from
+    // the run entirely, which is also what makes its dependents correct: the
+    // runner treats a filtered dep as satisfied, and only a GREEN is ever
+    // stored, so a dependent can never start on the back of a red nobody saw.
+    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [] }).selected.map((t) => t.id))
+    const replayedTasks = new Map<string, UnitOutcome>()
+    const toRun = tasks
+        .filter((t) => {
+            if (ledger == null || !selectable.has(t.id)) return true
+            const hit = ledger.replay(t.id)
+            if (hit == null) return true
+            replayedTasks.set(t.id, hit)
+            for (const l of stampReplayed(hit.lines, hit.measuredMs)) sink(formatLine(l, false))
+            return false
+        })
+        // a dep ON a replayed task is DROPPED, not left dangling. The runner
+        // validates every dep against the list it was handed and dies with
+        // `unknown dep` otherwise, and dropping is the honest edge here: only a
+        // GREEN is ever replayed, so the dependent's precondition is met and
+        // this is the same "a filtered dep counts as satisfied" the runner
+        // already applies to --skip and opt-in tasks.
+        .map((t) => (t.deps?.some((d) => replayedTasks.has(d)) === true ? { ...t, deps: t.deps.filter((d) => !replayedTasks.has(d)) } : t))
+    // the pre-warm exists to hide the survey behind the TASKS. When every task
+    // replayed there is nothing to hide it behind, and starting it anyway is a
+    // 4s network call the run may never need: the five checks that want it
+    // fetch it themselves, and when they replay too, nobody pays for it at all.
+    const survey = willRunChecks && toRun.length > 0 ? collectReports(root, c).catch(() => null) : null
+    // a NAMED task that replayed leaves the list, so its name has to leave the
+    // filters with it: the runner validates `--only`/`--with` against the list
+    // it was handed and answers `unknown task id`. `bun run typecheck` and
+    // `bun run test` route through `--only`, so this is the reflex verb every
+    // agent in every wired repo types, going red on a warm store.
+    const onlyIds = (o.onlyIds ?? []).filter((id) => !replayedTasks.has(id))
+    const withIds = (o.withIds ?? []).filter((id) => !replayedTasks.has(id))
+    // narrowed to nothing is NOT the same as "no filter": an empty --only would
+    // widen the run to every task
+    const nothingToRun = replayedTasks.size > 0 && (toRun.length === 0 || ((o.onlyIds ?? []).length > 0 && onlyIds.length === 0))
+    // every asked-for task replayed: the DAG has nothing to schedule, and
+    // running it anyway would print `all 0 tasks green`, which reads as a gate
+    // that measured nothing rather than one that already knew the answer
+    const summary = nothingToRun
+        ? { ok: true, results: [], interrupted: false }
+        : await runTasks({
+        tasks: toRun,
         logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
         cwd: root,
         bail: o.bail ?? false,
         skipGroups: o.skipGroups ?? [],
-        withIds: o.withIds ?? [],
-        onlyIds: o.onlyIds ?? [],
+        withIds,
+        onlyIds,
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
+    if (nothingToRun) sink(`ok: all ${replayedTasks.size} task(s) asked for replayed, none measured`)
     // what the suite ACTUALLY ran, from its own summary line. A flag that was
     // set proves the intent; the count proves the tests
-    const ranTests = summary.results
-        .map((r) => /Ran (\d+) tests?/.exec(r.lastLine ?? '')?.[1])
+    for (const r of summary.results) {
+        if (ledger == null || r.status !== 'pass') continue
+        const surfaced = r.lines.filter((l) => l.kind === 'warn' || l.kind === 'fix-warn' || l.kind === 'skip')
+        ledger.record(r.id, {
+            status: surfaced.some((l) => l.kind === 'warn' || l.kind === 'fix-warn') ? 'warn' : 'pass',
+            // the headline is REBUILT rather than captured: the runner renders
+            // the wall time into it, and a duration baked into a stored line
+            // would be replayed as if this run had measured it
+            lines: [{ kind: 'ok', text: r.id }, ...surfaced],
+            lastLine: r.lastLine,
+            measuredMs: r.durationMs,
+        })
+    }
+    const ranTests = [...summary.results.map((r) => r.lastLine ?? ''), ...[...replayedTasks.values()].map((o) => o.lastLine ?? '')]
+        .map((l) => /Ran (\d+) tests?/.exec(l)?.[1])
         .find((n) => n != null)
     if (ranTests != null) sink(`ok: test tier ${tier}: ${ranTests} tests ran`)
     // the checks, in the SAME command. there is no second surface: a check
@@ -202,7 +271,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     if (survey != null) await survey
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds })
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false })
     if (priorShare == null) delete process.env[SHARE_ENV]; else process.env[SHARE_ENV] = priorShare
     for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
@@ -219,6 +288,11 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
             sink('      fix: shipkit check')
         } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
     }
+    // the post-run re-hash, then the store. NOTHING was written while the gate
+    // ran: a unit whose inputs moved under it answered about a tree that no
+    // longer exists, and this is where that result is thrown away instead of
+    // stored under a key that describes the file as it was before the edit.
+    if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
     const code = summary.ok && !fixFailed && !registrationFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
     // motherhome row (docsBase wiki on this disk) — never affects the gate,
     // and never fires under frozen: a bump/release gate must not re-dirty

package/src/core/task-runner.ts

@@ -45,6 +45,13 @@ export type TaskDef = {
     never?: string
 }
 
+/** every field a `TaskDef` may carry. Declared as a value so `defineRepo` can
+ *  refuse a typo inside a `defaults` slot: a slot with no `cmd` DECORATES the
+ *  resolved task, so a misspelled field is not a type error at the call site
+ *  and would land as a task that is quietly never cached. Add a field above,
+ *  add it here. */
+export const TASK_DEF_KEYS = ['id', 'cmd', 'logic', 'deps', 'env', 'cwd', 'group', 'optIn', 'timeoutMs', 'inputs', 'ttl', 'never'] as const
+
 export type TaskResult = {
     id: string
     status: 'pass' | 'fail' | 'skipped'

package/src/ledger/gate-units.ts

@@ -8,14 +8,40 @@
 // that drifts the first time somebody adds a check.
 import { relative } from 'path'
 import { allTasks, type RepoConfig } from '../repo-config.ts'
+import type { TaskDef } from '../core/task-runner.ts'
 import { discoverChecks } from '../core/discover-checks.ts'
 import { RULES } from '../rules/rule-registry.ts'
 import type { UnitDecl } from './git-key.ts'
 
-/** every task, rule and discovered check, in the order the gate meets them. */
-export function gateUnits(root: string, c: RepoConfig): UnitDecl[] {
+/** the env var a repo's own suite reads to widen itself. It lives HERE because
+ *  it rewrites every task's env, which is part of the key: a run that asked for
+ *  the quick tier and one that asked for the full tier are different questions,
+ *  and a surface that renders keys without applying it renders a tier nobody
+ *  ran. */
+export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+
+export type TestTier = 'quick' | 'full'
+
+/** the tier this process is asking for, absent an explicit choice */
+export function envTier(): TestTier {
+    return process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick'
+}
+
+/** the repo's tasks as the gate will actually run them at `tier`. */
+export function tieredTasks(c: RepoConfig, root: string, tier: TestTier): TaskDef[] {
+    const tasks = allTasks(c, root).tasks
+    return tier === 'full' ? tasks.map((t) => ({ ...t, env: { ...t.env, [FULL_TESTS_ENV]: '1' } })) : tasks
+}
+
+/** every task, rule and discovered check, in the order the gate meets them.
+ *
+ *  `tasks` overrides what the repo resolves to, and the gate MUST pass what it
+ *  is actually about to run: `--full` rewrites every task's env, and a key
+ *  built from the unmodified list would let a quick run replay into a full one
+ *  under one identity. */
+export function gateUnits(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitDecl[] {
     const out: UnitDecl[] = []
-    for (const t of allTasks(c, root).tasks) {
+    for (const t of tasks ?? allTasks(c, root).tasks) {
         out.push({
             id: t.id,
             kind: 'task',

package/src/ledger/git-key.ts

@@ -28,14 +28,15 @@
 // differ from main by two top-level packages. That is what makes a shared
 // ledger safe rather than a stale green in a checkout nobody looked at.
 import { createHash } from 'crypto'
+import { join } from 'path'
 import { loadConfig, type RvtConfig } from '../ts/config.ts'
 import { importClosure } from '../ts/source-graph.ts'
-import { GitScanError, hashFiles, normalizeInput, scanPaths, type ScanResult } from './git-scan.ts'
-import { toolchainIdentity } from './toolchain-identity.ts'
+import { GitScanError, hashFiles, normalizeInput, scanPaths, WHOLE_TREE, type ScanResult } from './git-scan.ts'
+import { installIdentity, toolchainIdentity } from './toolchain-identity.ts'
 
 /** the key format. Bumped when a component is added or its rendering changes,
  *  so an old ledger can never answer a new question. */
-export const KEY_VERSION = 1
+export const KEY_VERSION = 2
 
 export type Population = 'content' | 'world' | 'none'
 
@@ -176,6 +177,16 @@ export class KeyLayer {
         readonly openMs: number,
     ) {}
 
+    private readonly installIds = new Map<string, string>()
+
+    /** the identity of the program this run is driving: bun version, the gate
+     *  binary's whole source, and every installed package. A WORLD unit needs
+     *  it too, because a TTL'd answer measured by a different shipkit is a
+     *  different answer, and the TTL alone cannot see that. */
+    get toolchainId(): string {
+        return this.toolchain.id
+    }
+
     /** wall time the GIT half alone cost, ms — `openMs` is what a run pays */
     get scanMs(): number {
         return this.scan?.ms ?? 0
@@ -276,6 +287,10 @@ export class KeyLayer {
             `v=${KEY_VERSION}`,
             `unit=${d.kind}:${d.id}`,
             `bun=${Bun.version}`,
+            // report-only mode changes what a self-maintaining rule DOES, and
+            // a TTL cannot see a mode. A frozen answer replayed into a normal
+            // run, or the reverse, is an answer to the other question.
+            `frozen=${process.env['SHIPKIT_FROZEN'] === '1'}`,
             `toolchain=${this.toolchain.id}`,
             `argv=${JSON.stringify(d.argv ?? [])}`,
             ...(d.env ?? []).slice().sort().map((n) => `env:${n}=${process.env[n] ?? '<unset>'}`),
@@ -284,17 +299,53 @@ export class KeyLayer {
             ...(d.extra != null ? [`extra=${d.extra}`] : []),
             // ignored content nobody keyed on is part of the key's MEANING:
             // two runs that excluded different things answered different
-            // questions, and a silently narrowed key is the false green
-            ...hidden.sort().map((p) => `excluded=${p}`),
+            // questions, and a silently narrowed key is the false green.
+            //
+            // An excluded INSTALL carries its contents rather than only its
+            // name. `test:libs` declares `wiki/build`, every sub-package's
+            // `node_modules` sits inside it and is ignored, and the toolchain
+            // component describes the ROOT install only: without this, a lib
+            // whose own dependencies moved replayed a green measured against
+            // the previous ones, and no path in the key could say so.
+            ...hidden.sort().map((p) => (p.split('/').at(-1) === 'node_modules' ? `excluded=${p}#${this.installOf(p)}` : `excluded=${p}`)),
         ]
         const key = createHash('sha256').update(components.join('\n')).digest('hex').slice(0, 32)
         return { ...base, key, components, inputOids }
     }
 
+    /** an excluded install's identity, once per layer: several units can name
+     *  the same one, and hashing a `node_modules` twice in a run is pure cost. */
+    private installOf(rel: string): string {
+        let id = this.installIds.get(rel)
+        if (id == null) { id = installIdentity(join(this.root, rel)); this.installIds.set(rel, id) }
+        return id
+    }
+
     keys(): UnitKey[] {
         return this.decls.map((d) => this.keyFor(d.id))
     }
 
+    /** which units READ one of these paths. Answers the only question a
+     *  post-run re-hash has: whose result now describes a tree that no longer
+     *  exists. A unit declaring the whole work tree reads everything, so any
+     *  drift at all touches it. */
+    unitsTouchedBy(drifted: string[]): Set<string> {
+        const hit = new Set<string>()
+        if (drifted.length === 0) return hit
+        for (const d of this.decls) {
+            // the unit's own source counts exactly like a declared input: an
+            // agent fixing a check WHILE it runs must not store the old
+            // verdict under the new code's key
+            if ((this.closureByUnit.get(d.id) ?? []).some((f) => drifted.includes(f))) { hit.add(d.id); continue }
+            for (const raw of d.inputs ?? []) {
+                let p: string
+                try { p = normalizeInput(raw) } catch { hit.add(d.id); break }
+                if (p === WHOLE_TREE || drifted.some((x) => x === p || x.startsWith(`${p}/`))) { hit.add(d.id); break }
+            }
+        }
+        return hit
+    }
+
     /**
      * POST RUN RE HASH. Re-scan exactly what this layer keyed on and report
      * every path whose object id moved while the units were running.

package/src/ledger/git-scan.ts

@@ -29,7 +29,7 @@
 //     `git add` on one index file, 9 fail with `Unable to create …lock`. Three
 //     agents in one checkout is the normal case here, so lock contention is
 //     retried and only a NON lock failure is fatal.
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
 
 /** what a scan measured. Every OID is a git object id of the CURRENT disk
@@ -135,12 +135,25 @@ export function indexPaths(root: string): { scratch: string; ignored: string; re
             if (/^scan-\d+\.idx(\.tmp)?$/.test(f) && statSync(join(dir, f)).mtimeMs < cutoff) rmSync(join(dir, f), { force: true })
     } catch {}
     // tmp + rename: a half-copied index is a corrupt index, and git's error
-    // for that is not the one the retry loop is meant to absorb
+    // for that is not the one the retry loop is meant to absorb.
+    //
+    // THE COPY KEEPS THE ORIGINAL'S MTIME, and that one line is the whole of a
+    // reproduced false green. Git decides an entry is "racily clean" by
+    // comparing the entry's cached mtime against the INDEX FILE's own mtime,
+    // and re-reads content whenever it cannot tell them apart. macOS git
+    // records mtimes at one-second granularity, so a file rewritten to the
+    // same SIZE inside the second it was staged is invisible to the stat cache
+    // and only that racy rule catches it. A fresh copy has mtime NOW, which
+    // makes every entry look comfortably older than the index and switches the
+    // rule off. Measured: 1 miss in 30 on a file edited between two scans, and
+    // a miss here is a replay of an answer about content nobody has any more.
     try {
         rmSync(scratch, { force: true })
         if (existsSync(real)) {
+            const st = statSync(real)
             const tmp = `${scratch}.tmp`
             copyFileSync(real, tmp)
+            utimesSync(tmp, st.atime, st.mtime)
             renameSync(tmp, scratch)
         }
     } catch {

package/src/ledger/ledger.ts

@@ -0,0 +1,202 @@
+// THE LEDGER — the CONTENT half of the three populations: a unit's answer,
+// stored under the identity of the question it answered, replayed only when
+// that identity is bit-for-bit the same question again.
+//
+// ledger/git-key.ts owns the identity, ledger/store.ts owns the file. This
+// module owns the POLICY, and the policy is where a cache turns into a false
+// green, so every rule below exists because a specific failure was reproduced
+// during the design pass:
+//
+//  1. DEFAULT DENY. A unit that declared nothing is never replayed and never
+//     stored. Forgetting to declare costs speed, never correctness, which is
+//     what makes the burn-down a to-do rather than a hazard.
+//  2. POST RUN RE HASH. Results are BUFFERED while the gate runs and written
+//     only after the inputs are hashed a second time. A unit whose inputs
+//     moved between its run and that second hash answered about a tree that no
+//     longer exists, so its result is discarded rather than stored under a key
+//     that describes the file as it was BEFORE the edit. Three agents in one
+//     checkout is the normal case here, so that window is not theoretical.
+//  3. THE GATE BINARY IS IN THE KEY. Editing shipkit moves every key in every
+//     repo (ledger/toolchain-identity.ts content-hashes the cli tree).
+//  4. RELEASE NEVER READS IT. `bump` and `release` pass read:false, not
+//     configurably. Every remaining hole is then capped at "an agent saw a
+//     stale local green", never "a stale green authorised a publish".
+//  5. NO SILENT REPLAY. Every replayed line is stamped with the word
+//     `replayed` and what the measured run cost, and the run prints hit, miss
+//     and uncacheable counts. A cached green that cannot be told from a
+//     measured green is the bug this whole design exists to not ship.
+//  6. ONLY A GREEN REPLAYS. A red is the one outcome an agent acts on
+//     immediately, and acting on it changes content, which moves the key — so
+//     replaying a red buys almost nothing, while an undeclared flake would
+//     pin its red until something unrelated happened to change. The safe
+//     direction here is re-measuring, and it costs only the run that was
+//     already going red.
+import type { RvtConfig } from '../ts/config.ts'
+import type { Line } from '../core/wire.ts'
+import { KeyLayer, type UnitDecl, type UnitKey } from './git-key.ts'
+import { entryPath, FRESH_ENV, KEEP_MS, readStored, storeRoot, sweepStore, writeStored } from './store.ts'
+
+/** the env var that turns the READ path on or off for a whole session.
+ *  Writing is unconditional either way: an entry nobody reads breaks nothing. */
+export const LEDGER_ENV = 'SHIPKIT_LEDGER'
+
+/** where unit results live inside the one store */
+const NS = 'units'
+
+/** whether the read path is on by default, before any flag.
+ *
+ *  It shipped OFF and ran that way while two other efforts gated in this
+ *  checkout, because a bug here would have handed one of them a green nobody
+ *  measured. It went ON once eleven scenarios pinned the failure modes, a race
+ *  of five real gates on one checkout agreed on one verdict, and the dark run
+ *  had turned up and fixed a false green in the key layer that predates it.
+ *  `SHIPKIT_LEDGER=0` turns it off for a session, and this line is the revert. */
+export const READ_DEFAULT = true
+
+export type UnitOutcome = {
+    /** only a green is ever stored (rule 6 above) */
+    status: 'pass' | 'warn'
+    lines: Line[]
+    /** the task-runner headline, which the gate greps for the test count */
+    lastLine?: string
+    /** what the measured run cost, ms — printed on the replay so a hit says
+     *  what it saved instead of pretending the work was free */
+    measuredMs: number
+}
+
+export type LedgerOpts = {
+    /** the cli entry driving this run (toolchain identity needs it) */
+    cliEntry: string
+    /** read the store at all. false = every unit is measured this run. */
+    read?: boolean
+    /** this run re-measures everything, and re-stores what it measured */
+    fresh?: boolean
+    /** module-graph config, loaded from the repo when omitted */
+    cfg?: RvtConfig
+    now?: () => number
+}
+
+export type CommitReport = {
+    /** unit ids written to the store */
+    stored: string[]
+    /** unit ids whose result was thrown away because an input moved */
+    discarded: string[]
+    /** the paths that moved */
+    drifted: string[]
+    /** the re-hash itself failed; nothing was stored */
+    error: string | null
+    ms: number
+}
+
+/** is the read path on for this process? A run may still turn it off. */
+export function ledgerReadEnabled(): boolean {
+    const v = process.env[LEDGER_ENV]
+    if (v === '1' || v === 'true') return true
+    if (v === '0' || v === 'false') return false
+    return READ_DEFAULT
+}
+
+export class Ledger {
+    private readonly buffered = new Map<string, UnitOutcome>()
+    private readonly keys = new Map<string, UnitKey>()
+    private hits = 0
+    private misses = 0
+    private unkeyed = 0
+
+    private constructor(
+        readonly layer: KeyLayer,
+        private readonly store: string,
+        /** replays are allowed */
+        readonly reading: boolean,
+        private readonly now: () => number,
+    ) {}
+
+    static open(root: string, decls: UnitDecl[], o: LedgerOpts): Ledger {
+        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg })
+        const fresh = o.fresh === true || process.env[FRESH_ENV] != null
+        const reading = (o.read ?? ledgerReadEnabled()) && !fresh
+        return new Ledger(layer, storeRoot(root), reading, o.now ?? Date.now)
+    }
+
+    /** the key for a unit, computed once per run and remembered: `keyFor`
+     *  re-derives the component list every call, and the gate asks twice (once
+     *  to replay, once to record). */
+    private key(id: string): UnitKey {
+        let k = this.keys.get(id)
+        if (k == null) { k = this.layer.keyFor(id); this.keys.set(id, k) }
+        return k
+    }
+
+    private path(k: UnitKey): string {
+        return entryPath(this.store, NS, `${k.kind}:${k.id}`, k.key!)
+    }
+
+    /** the stored answer for this unit, or null when it must run. Counts what
+     *  it was asked, so the run can report hit/miss/uncacheable honestly. */
+    replay(id: string): UnitOutcome | null {
+        const k = this.key(id)
+        if (k.key == null) { this.unkeyed++; return null }
+        if (!this.reading) { this.misses++; return null }
+        const e = readStored<UnitOutcome>(this.path(k), k.key)
+        if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
+        this.hits++
+        return e.payload
+    }
+
+    /** buffer what a unit just measured. Nothing reaches the store until
+     *  commit() has re-hashed the inputs (rule 2). */
+    record(id: string, outcome: UnitOutcome): void {
+        const k = this.key(id)
+        if (k.key == null) return
+        this.buffered.set(id, outcome)
+    }
+
+    /** re-hash, then write what still describes the tree on disk. */
+    commit(): CommitReport {
+        const empty: CommitReport = { stored: [], discarded: [], drifted: [], error: null, ms: 0 }
+        if (this.buffered.size === 0) return empty
+        const started = performance.now()
+        const d = this.layer.rescan()
+        if (d.error != null) return { ...empty, discarded: [...this.buffered.keys()].sort(), error: d.error, ms: performance.now() - started }
+        const touched = this.layer.unitsTouchedBy(d.drifted)
+        const stored: string[] = []
+        const discarded: string[] = []
+        for (const [id, outcome] of this.buffered) {
+            if (touched.has(id)) { discarded.push(id); continue }
+            const k = this.key(id)
+            writeStored(this.path(k), k.key!, outcome, this.now())
+            stored.push(id)
+        }
+        sweepStore(this.store, NS, this.now(), KEEP_MS)
+        return { stored: stored.sort(), discarded: discarded.sort(), drifted: d.drifted, error: null, ms: performance.now() - started }
+    }
+
+    get counts(): { hit: number; miss: number; uncacheable: number } {
+        return { hit: this.hits, miss: this.misses, uncacheable: this.unkeyed }
+    }
+
+    /** the one line a run prints about its own cache. Never silent: a run that
+     *  replayed nothing says so, so a green is always attributable. */
+    header(commit: CommitReport): Line[] {
+        const c = this.counts
+        const asked = c.hit + c.miss + c.uncacheable
+        if (asked === 0) return []
+        const out: Line[] = []
+        // `skip:` and not a bare note: the ci wire prefixes are a frozen
+        // contract every agent and every parser reads, and these lines are
+        // exactly what the run did NOT measure
+        const mode = this.reading ? '' : this.layer.failure != null ? ', reads off because the git scan failed' : ', reads off'
+        out.push({ kind: 'skip', text: `ledger — ${c.hit} replayed, ${c.miss} measured, ${c.uncacheable} uncacheable${mode}` })
+        if (commit.error != null) out.push({ kind: 'warn', text: `ledger stored nothing this run — the post-run re-hash failed: ${commit.error}` })
+        else if (commit.discarded.length > 0)
+            out.push({ kind: 'skip', text: `ledger stored nothing for ${commit.discarded.length} unit(s) — ${commit.drifted.slice(0, 3).join(', ')}${commit.drifted.length > 3 ? ` +${commit.drifted.length - 3} more` : ''} moved while the gate ran` })
+        return out
+    }
+}
+
+/** stamp a replayed unit's lines. The FIRST line carries the word, because
+ *  that is the line an agent reads, and a replay that renders identically to a
+ *  measurement is the one thing this design refuses to ship. */
+export function stampReplayed(lines: Line[], measuredMs: number): Line[] {
+    return lines.map((l, i) => (i === 0 ? { ...l, text: `${l.text} (replayed, ${(measuredMs / 1000).toFixed(1)}s saved)` } : l))
+}