rvlib-shipkit 0.33.0 → 0.35.0

package/src/ledger/git-scan.ts

@@ -0,0 +1,327 @@
+// WHAT IS ON DISK RIGHT NOW, as git object ids, using git's own index.
+//
+// A cache key needs the identity of the files a unit reads, INCLUDING files
+// that are untracked or modified. `git hash-object` per file is O(files) and
+// re-reads everything; git's index already carries a stat cache that answers
+// "unchanged" without reading the blob. So: a scratch index of our own, per
+// path adds, one `write-tree`, one `cat-file --batch-check`.
+//
+// FOUR THINGS THIS FILE EXISTS TO GET RIGHT, each reproduced before it was
+// written:
+//
+//  1. PER PATH ADDS, EXIT CODE CHECKED. `git add -A -- a.txt missing/` exits
+//     128, stages NOTHING, and `write-tree` then hands back the tree of the
+//     LAST successful write. Measured on a scratch repo: the batched form
+//     returned HEAD's tree while a.txt was modified on disk, so every key
+//     derived from it described a file nobody had. One add per path turns that
+//     into one loud failure on one path.
+//  2. A MISSING DECLARED PATH IS NOT A GIT ERROR. A repo without `tests/` is
+//     normal, and hard-failing the gate on it would be wrong, so a path that
+//     does not exist never reaches `git add`: it comes back in `missing` and
+//     the caller refuses to cache that unit. That keeps rule 1's hard failure
+//     for what it is actually about, git going wrong on a path that IS there.
+//  3. ONLY AN IGNORED PATH IS FORCE ADDED. `git add -Af` on a broad path force
+//     adds node_modules and costs 17.7s; the ignored paths that genuinely hold
+//     declared inputs here (.rv-social/patreon/, .rv-assets/out/) cost 76ms.
+//     One `ls-files --others -i --directory` names them, and node_modules is
+//     refused force-add at any depth.
+//  4. THE SCRATCH INDEX IS SHARED, SO IT IS CONTENDED. Measured: 10 parallel
+//     `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, 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
+ *  content, tracked or not. */
+export type ScanResult = {
+    /** root tree of the scratch index after the adds */
+    treeOid: string
+    /** repo-relative path → git object id (tree for a dir, blob for a file) */
+    oidByPath: Map<string, string>
+    /** declared paths that are not on disk — the caller must not cache them */
+    missing: string[]
+    /** repo-relative path → ignored content under it that is NOT in the key
+     *  (node_modules only, by policy: toolchain-identity.ts owns installs) */
+    excluded: Map<string, string[]>
+    /** wall time of the whole scan */
+    ms: number
+}
+
+export class GitScanError extends Error {}
+
+/** the scratch index FORMAT. Bump it whenever what the scan stages changes.
+ *  The index is persistent, and anything staged into it stays there until
+ *  something stages over it: a run that force-added a path a later version no
+ *  longer touches would keep serving that path's content forever, frozen at
+ *  the moment of the bad run. A version stamp beside the file turns that into
+ *  one discarded index instead of a permanently wrong key. */
+export const SCAN_INDEX_VERSION = 2
+
+const LOCK_RE = /Unable to create '.*\.lock'|index\.lock/i
+const RETRIES = 12
+
+const git = (root: string, args: string[], indexFile: string): { code: number; out: string } => {
+    const p = Bun.spawnSync(['git', ...args], {
+        cwd: root,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { ...process.env, GIT_INDEX_FILE: indexFile },
+    })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}` }
+}
+
+/** one git call that MUST succeed. Lock contention is retried (three agents in
+ *  one checkout is normal); anything else throws with git's own words. */
+function gitOrThrow(root: string, args: string[], indexFile: string): string {
+    let last = { code: -1, out: '' }
+    for (let attempt = 0; attempt < RETRIES; attempt++) {
+        last = git(root, args, indexFile)
+        if (last.code === 0) return last.out
+        if (!LOCK_RE.test(last.out)) break
+        Bun.sleepSync(10 + attempt * 10)
+    }
+    throw new GitScanError(`git ${args.join(' ')} exited ${last.code}: ${last.out.trim().split('\n').slice(0, 3).join(' / ')}`)
+}
+
+/** the THREE index files a scan uses, and why it is three and not one.
+ *
+ *  SCRATCH is where the plain adds go, and it is COPIED FRESH from the repo's
+ *  real index on every scan. Keeping it across runs was the obvious design and
+ *  it was wrong twice, both measured. Anything staged into an index stays
+ *  staged, so a path force-added by one run rode in every later run's tree,
+ *  which made the whole-tree id a function of this machine's scan history and
+ *  reproducible on no other checkout. And a file that stopped being tracked
+ *  (`git rm --cached`) stayed in the scratch index, so the tree still carried
+ *  it and a rule keyed on tracked-ness saw nothing change. The copy costs
+ *  about 1ms and the real index is already warm, so the whole reset plus
+ *  `git add -- .` plus `write-tree` measures 30 to 40ms, FASTER than the
+ *  persistent index it replaces.
+ *
+ *  IGNORED is a separate index for the force-adds, so a path one unit named
+ *  can never leak into the whole-tree id another unit is keyed on. Without the
+ *  split, one unit's key changed depending on which OTHER units were in the
+ *  run, which is exactly the silently narrowed key the excluded list exists to
+ *  prevent. It stays warm across runs: an entry left in it can only affect the
+ *  path it belongs to, never the root tree.
+ *
+ *  REAL is read, never written, and only to answer "does git ignore this".
+ *  `ls-files --others` means UNTRACKED, so asking an index we force-add into
+ *  reports a force-added path as no longer ignored, and the next run then
+ *  plain-adds it, which exits 1 and takes the scan down. */
+export function indexPaths(root: string): { scratch: string; ignored: string; real: string } {
+    const p = Bun.spawnSync(['git', 'rev-parse', '--absolute-git-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    if (p.exitCode !== 0) throw new GitScanError(`not a git repository: ${root} (${p.stderr.toString().trim()})`)
+    const gitDir = p.stdout.toString().trim()
+    const dir = join(gitDir, 'shipkit')
+    mkdirSync(dir, { recursive: true })
+    const real = join(gitDir, 'index')
+    const ignored = join(dir, 'scan-ignored.idx')
+    const stamp = join(dir, 'scan.idx.version')
+    const seen = ((): string => { try { return readFileSync(stamp, 'utf8').trim() } catch { return '' } })()
+    if (seen !== String(SCAN_INDEX_VERSION)) {
+        try { rmSync(ignored, { force: true }) } catch {}
+        try { writeFileSync(stamp, `${SCAN_INDEX_VERSION}\n`) } catch {}
+    }
+    // per-process scratch: it is rewritten from `real` every scan anyway, so
+    // sharing one file across concurrent runners buys no warmth and only adds
+    // lock contention
+    const scratch = join(dir, `scan-${process.pid}.idx`)
+    // a run that was killed leaves its file behind, and pids are reused, so
+    // sweep anything an hour old rather than trusting the pid to be free
+    try {
+        const cutoff = Date.now() - 3_600_000
+        for (const f of readdirSync(dir))
+            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.
+    //
+    // 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 {
+        // no seed is survivable: the adds are just colder
+    }
+    return { scratch, ignored, real }
+}
+
+/** the whole work tree as one input. A rule that walks the repo (SK001's test
+ *  file probe, SK010's `git ls-files`) genuinely reads all of it, and saying so
+ *  is more honest than naming three of the files it happens to open. Its object
+ *  id is the scan's root tree, so it moves on any edit anywhere. */
+export const WHOLE_TREE = '.'
+
+/** repo-relative posix, no './', no trailing slash. Throws on anything that
+ *  escapes the repo — a key component outside the tree is a key nobody else
+ *  can reproduce. */
+export function normalizeInput(p: string): string {
+    const n = normalize(p).replace(/\\/g, '/').replace(/\/+$/, '').replace(/^\.\//, '')
+    if (n === '.' || n === '') return WHOLE_TREE
+    if (isAbsolute(p) || n === '..' || n.startsWith('../'))
+        throw new GitScanError(`input path '${p}' is outside the repo — declare a path inside it, or '.' for the whole work tree`)
+    return n
+}
+
+/** drop paths already covered by an ancestor in the same set: adding `wiki`
+ *  stages `wiki/build/...` too, and a second add of the child is pure cost. */
+export function dropCovered(paths: string[]): string[] {
+    if (paths.includes(WHOLE_TREE)) return [WHOLE_TREE]
+    const sorted = [...new Set(paths)].sort()
+    const kept: string[] = []
+    for (const p of sorted) if (!kept.some((k) => p === k || p.startsWith(`${k}/`))) kept.push(p)
+    return kept
+}
+
+const underNodeModules = (p: string): boolean => p.split('/').includes('node_modules')
+
+/**
+ * stage `paths` into the scratch index and read back one git object id each.
+ *
+ * Throws `GitScanError` on any git failure that is not lock contention. The
+ * caller's contract on a throw is absolute: produce NO key. A tree that may be
+ * stale describes files nobody has, and a key built on it is a false green
+ * waiting for its first hit.
+ */
+export function scanPaths(root: string, rawPaths: string[]): ScanResult {
+    const started = performance.now()
+    const { scratch: indexFile, ignored: ignoredIndex, real: realIndex } = indexPaths(root)
+    const wanted = [...new Set(rawPaths.map(normalizeInput))].sort()
+    const missing = wanted.filter((p) => !existsSync(join(root, p)))
+    const present = wanted.filter((p) => existsSync(join(root, p)))
+    const toAdd = dropCovered(present)
+    const named = wanted.filter((p) => p !== WHOLE_TREE)
+
+    // ignored content under what we are about to stage. One call, and it also
+    // answers "is this declared path itself ignored": `--directory` collapses
+    // a dir whose ENTIRE content is ignored, so the answer comes back as the
+    // dir with a trailing slash.
+    const ignored = toAdd.length === 0
+        ? []
+        : gitOrThrow(root, ['ls-files', '--others', '-i', '--exclude-standard', '--directory', '--', ...toAdd], realIndex)
+            .split('\n')
+            .map((l) => l.trim().replace(/\/+$/, ''))
+            .filter((l) => l !== '')
+    // ONLY a path a declaration NAMES is force-added. Ignored content that
+    // merely sits under a declared path is reported and left out.
+    //
+    // This is the whole of defense 3, and the wide reading of it is a disaster
+    // measured twice: with `.` declared (which every repo-walking rule
+    // declares), "ignored content under a declared path" is every ignored path
+    // in the repo, so one run force-staged two entire worktrees, the log dir,
+    // the private model dumps and the prompt corpora, for 680ms. Naming the
+    // path is what makes it an input.
+    //
+    // Installs are refused on top of that, at any depth AND as an ancestor:
+    // `--directory` collapses a dir whose entire content is ignored, so
+    // force-adding that one entry stages the node_modules inside it.
+    const declared = new Set(wanted)
+    const denied = ignored.filter(underNodeModules)
+    const forceAdd = ignored.filter((p) => declared.has(p) && !underNodeModules(p) && !denied.some((d) => d.startsWith(`${p}/`)))
+    // a path git itself calls ignored must NOT get the plain add: `git add --
+    // <ignored>` exits 1 and takes the whole scan down with it
+    const ignoredSet = new Set(ignored)
+    for (const p of toAdd) if (!ignoredSet.has(p)) gitOrThrow(root, ['add', '--', p], indexFile)
+    // force-adds land in their OWN index, so a path one unit named can never
+    // ride inside the whole-tree id another unit is keyed on
+    for (const p of forceAdd) gitOrThrow(root, ['add', '-Af', '--', p], ignoredIndex)
+
+    const treeOid = gitOrThrow(root, ['write-tree'], indexFile).trim()
+    const oidByPath = new Map<string, string>()
+    // the work tree's own id IS the tree the adds just produced — there is no
+    // `<tree>:` path to ask git for
+    if (wanted.includes(WHOLE_TREE)) oidByPath.set(WHOLE_TREE, treeOid)
+    const forceSet = new Set(forceAdd)
+    const plain = named.filter((p) => !forceSet.has(p))
+    for (const [tree, paths, index] of [[treeOid, plain, indexFile], [null, forceAdd, ignoredIndex]] as const) {
+        if (paths.length === 0) continue
+        const root_ = tree ?? gitOrThrow(root, ['write-tree'], index).trim()
+        const query = paths.map((p) => `${root_}:${p}`).join('\n')
+        const p = Bun.spawnSync(['git', 'cat-file', '--batch-check'], {
+            cwd: root,
+            stdin: Buffer.from(`${query}\n`),
+            stdout: 'pipe',
+            stderr: 'pipe',
+            env: { ...process.env, GIT_INDEX_FILE: index },
+        })
+        if (p.exitCode !== 0) throw new GitScanError(`git cat-file --batch-check exited ${p.exitCode}: ${p.stderr.toString().trim()}`)
+        const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
+        if (lines.length !== paths.length)
+            throw new GitScanError(`git cat-file --batch-check answered ${lines.length} of ${paths.length} paths`)
+        paths.forEach((path, i) => {
+            const oid = lines[i]!.split(' ')[0] ?? ''
+            // 'missing' / 'ambiguous' come back in place of an id — a path git
+            // cannot name is a path we cannot key on
+            if (/^[0-9a-f]{40}$/.test(oid)) oidByPath.set(path, oid)
+            else if (!missing.includes(path)) missing.push(path)
+        })
+    }
+
+    const excluded = new Map<string, string[]>()
+    for (const d of ignored) {
+        // EVERY owner that covers it, not the first one found, and membership
+        // must not depend on what OTHER units declared. `.` sorts first and
+        // covers everything, so a `find` here handed the whole exclusion list
+        // to the whole-tree unit and left every narrower unit claiming it was
+        // blind to nothing. Filtering force-added paths out globally had the
+        // same shape: one unit naming `ign` deleted `excluded=ign` from a
+        // whole-tree unit that is still blind to it. Measured both ways, one
+        // unit producing two keys for one unchanged tree, and the component
+        // that vanished is the one that exists to stop a silently narrowed key.
+        for (const w of wanted) {
+            if (!(w === WHOLE_TREE || d === w || d.startsWith(`${w}/`))) continue
+            // the one owner that is NOT blind: it named the path itself, so it
+            // got the content through the force-add
+            if (d === w && forceSet.has(d)) continue
+            excluded.set(w, [...(excluded.get(w) ?? []), d])
+        }
+    }
+    return { treeOid, oidByPath, missing: [...new Set(missing)].sort(), excluded, ms: performance.now() - started }
+}
+
+/**
+ * blob ids for a list of FILES, one process, no index, no lock.
+ *
+ * The scratch index is the right tool for a declared input, which is usually a
+ * directory and usually unchanged (git's stat cache answers without reading).
+ * It is the wrong tool for the module-graph closure: those are individual
+ * files, they belong to no declared path, and staging each one would cost a
+ * `git add` spawn per file. `hash-object --stdin-paths` reads them all in one
+ * call and returns exactly what a blob of that content would be.
+ *
+ * A file that is not on disk is skipped and reported, never guessed at.
+ */
+export function hashFiles(root: string, files: string[]): { oids: Map<string, string>; missing: string[] } {
+    const oids = new Map<string, string>()
+    const wanted = [...new Set(files.map(normalizeInput))].sort()
+    const missing = wanted.filter((f) => !existsSync(join(root, f)))
+    const present = wanted.filter((f) => existsSync(join(root, f)))
+    if (present.length === 0) return { oids, missing }
+    const p = Bun.spawnSync(['git', 'hash-object', '--stdin-paths'], {
+        cwd: root,
+        stdin: Buffer.from(`${present.join('\n')}\n`),
+        stdout: 'pipe',
+        stderr: 'pipe',
+    })
+    if (p.exitCode !== 0) throw new GitScanError(`git hash-object exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n').slice(0, 3).join(' / ')}`)
+    const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
+    if (lines.length !== present.length) throw new GitScanError(`git hash-object answered ${lines.length} of ${present.length} files`)
+    present.forEach((f, i) => oids.set(f, lines[i]!.trim()))
+    return { oids, missing }
+}

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))
+}

package/src/ledger/store.ts

@@ -0,0 +1,122 @@
+// ONE STORE. Everything this toolkit remembers between runs lives here, in
+// one shape, under one root, busted by one flag.
+//
+// There used to be two: `tmp/.shipkit-cache` for the check orchestrator and
+// `tmp/.check-cache` for the page checks, each with its own bust env var, each
+// per worktree. Two stores means two staleness windows over one question, and
+// the stamps in this repo's own history went BACKWARDS between checkouts
+// because of it. This module is the single mechanism; what differs between
+// populations is the KEY, never the storage.
+//
+// THE SHAPE, unchanged from the check cache slice 2 landed and proved:
+// one immutable file per key, named by the key, written tmp + rename. No
+// lock, no merge, no read-modify-write, and no prune of another runner's
+// entries. Three agents in one checkout is the normal case, so the only safe
+// aggregate is no aggregate: a run with a different key writes a DIFFERENT
+// file, a run with the same key replaces its own whole answer or none of it,
+// and housekeeping sweeps by AGE, which needs no knowledge of what the
+// current run knows about.
+//
+// WHERE. `<git-common-dir>/shipkit/store/`, which is SHARED by every linked
+// worktree of the repo. That is safe only because no key component is a path:
+// the toolchain identity content-hashes the gate binary and every installed
+// package, so two worktrees carrying different installs produce different
+// keys and simply miss each other (ledger/toolchain-identity.ts owns the
+// measurement). It is also outside the work tree, so nothing here can dirty a
+// diff or reach a commit.
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+
+/** the storage FORMAT. Bumped when the envelope changes, so an old file can
+ *  never be handed to a new reader. The KEY carries everything about the
+ *  question; this is only about the file around it. */
+export const STORE_VERSION = 1
+
+/** the ONE env var that busts every remembered answer, content or TTL. */
+export const FRESH_ENV = 'SHIPKIT_FRESH'
+
+/** one remembered answer. `key` is stored as well as hashed into the file
+ *  name, and re-checked on read: a name collision must miss, never serve a
+ *  neighbour's answer. */
+export type Stored<T> = {
+    v: number
+    key: string
+    /** when it was written, ms since epoch */
+    at: number
+    payload: T
+}
+
+/** how long a superseded entry survives. Far past the longest TTL any check
+ *  declares, so a live entry is never swept out from under a replay. */
+export const KEEP_MS = 30 * 24 * 60 * 60 * 1000
+
+/** where this repo's remembered answers live.
+ *
+ *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
+ *  git dir but shares the common one, and slice 3 measured that sharing is
+ *  SAFE here because every key component is content or a version string.
+ *  A tree that is not a git repo at all still gets a store, under `tmp/`,
+ *  because a scaffold in progress must not crash on it. */
+export function storeRoot(root: string): string {
+    const p = Bun.spawnSync(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const dir = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+    return dir === '' ? join(root, 'tmp/.shipkit-store') : join(dir, 'shipkit/store')
+}
+
+const slug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
+
+/** where ONE answer lives. The key is in the file NAME, so a run whose key
+ *  moved writes a new file instead of rewriting the old one, and two runners
+ *  with different keys never collide. `ns` keeps populations apart so a sweep
+ *  or a manual `rm` can be scoped. */
+export function entryPath(store: string, ns: string, name: string, key: string): string {
+    const h = new Bun.CryptoHasher('sha256').update(`${ns}\0${name}\0${key}`).digest('hex').slice(0, 12)
+    return join(store, slug(ns), `${slug(name)}.${h}.json`)
+}
+
+/** a missing or half-written file reads as "no answer", which is the safe
+ *  side: the unit runs. tmp + rename means half-written cannot happen from a
+ *  shipkit write, so this only ever catches a truncated file from something
+ *  else, and treats it the same way. */
+export function readStored<T>(path: string, key: string): Stored<T> | null {
+    try {
+        const e = JSON.parse(readFileSync(path, 'utf8')) as Partial<Stored<T>>
+        if (e.v !== STORE_VERSION || e.key !== key || typeof e.at !== 'number' || e.payload == null) return null
+        return e as Stored<T>
+    } catch { return null }
+}
+
+export function writeStored<T>(path: string, key: string, payload: T, at: number): void {
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, payload }))
+    } catch {
+        // a store that cannot be written is slow, never wrong: the answer was
+        // already printed, and the next run measures again
+    }
+}
+
+export function dropStored(path: string): void {
+    try { rmSync(path, { force: true }) } catch { /* raced with another runner: it is gone either way */ }
+}
+
+/** age-based housekeeping. Sweeping by "the units I know about" is what made
+ *  the old prune wrong: a run narrowed with --only knows about one unit and
+ *  would delete the other sixty-five. */
+export function sweepStore(store: string, ns: string, now: number, keepMs = KEEP_MS): void {
+    const dir = join(store, slug(ns))
+    const cutoff = now - keepMs
+    try {
+        for (const f of readdirSync(dir)) {
+            // `.<name>.tmp-<pid>` is what atomicWrite lands beside its target,
+            // and a writer killed between the write and the rename leaves one
+            // behind. Sweeping only *.json accreted them without bound.
+            if (!f.endsWith('.json') && !/\.tmp-\d+$/.test(f)) continue
+            const p = join(dir, f)
+            try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+        }
+    } catch {
+        // no dir yet, or unreadable: housekeeping never fails a run
+    }
+}