rvlib-shipkit 1.5.0 → 1.6.0

package/src/ledger/ledger.ts

@@ -9,15 +9,17 @@
 //
 //  1. DEFAULT DENY. A check 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.
+//     what makes the burn-down a to-do rather than a hazard. A task that
+//     declares nothing is keyed on the work tree instead (gate-checks.ts).
 //  2. POST RUN RE HASH. Results are BUFFERED while the gate runs and written
 //     only after the inputs are hashed a second time. A check 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).
+//  3. THE GATE CODE IS IN THE KEY. Editing the shipkit code that runs a check
+//     or stores its answer moves that key in every repo, and an edit no answer
+//     depends on moves none (ledger/toolchain-identity.ts).
 //  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".
@@ -41,7 +43,7 @@
 import { join } from 'path'
 import type { RvtConfig } from '../ts/config.ts'
 import type { Line } from '../core/wire.ts'
-import { KeyLayer, type CheckDecl, type CheckKey } from './git-key.ts'
+import { classify, KeyLayer, type CheckDecl, type CheckKey } from './git-key.ts'
 import { shipkitRoot } from './db.ts'
 import { Answers, answersDb, FRESH_ENV, type AnswerRef, type AnswerWrite } from './store.ts'
 import type { Problem } from '../problems/problem-line.ts'
@@ -81,8 +83,20 @@ export type CheckOutcome = {
     measuredMs: number
 }
 
-/** what a READS answer is stored as: the verdict and what it read */
-type Stored = CheckOutcome & { reads?: ReadSet }
+/** what an answer is stored as: the verdict, what it read (READS), and the
+ *  key components it was stored under, so a later miss can say what moved */
+type Stored = CheckOutcome & { reads?: ReadSet; components?: string[] }
+
+/** why a check did not come from the cache this run, one per check that ran
+ *  or cannot be cached. The verdict prints them grouped, so a re-run is never
+ *  unexplained */
+export type RanWhy = {
+    /** `moved`: its key or a read changed. `first`: nothing stored for it.
+     *  `not kept`: it ran and its answer cannot be stored. `never`: no key can
+     *  describe it. `off`: this run reads no cache */
+    group: 'moved' | 'first' | 'not kept' | 'never' | 'off'
+    why: string
+}
 
 export type LedgerOpts = {
     /** the cli entry driving this run (toolchain identity needs it) */
@@ -128,6 +142,8 @@ export class Ledger {
     private misses = 0
     private unkeyed = 0
     private joined = 0
+    private readonly ranWhy = new Map<string, RanWhy>()
+    private fresh = false
 
     private constructor(
         readonly layer: KeyLayer,
@@ -144,7 +160,9 @@ export class Ledger {
         const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg, scope: o.scope })
         const fresh = o.fresh === true || process.env[FRESH_ENV] != null
         const reading = (o.read ?? ledgerReadEnabled()) && !fresh
-        return new Ledger(layer, new Answers(answersDb(root)), join(shipkitRoot(root), 'inflight'), reading, o.now ?? Date.now)
+        const l = new Ledger(layer, new Answers(answersDb(root)), join(shipkitRoot(root), 'inflight'), reading, o.now ?? Date.now)
+        l.fresh = fresh
+        return l
     }
 
     /** the key for a check, computed once per run and remembered: `keyFor`
@@ -168,13 +186,24 @@ export class Ledger {
 
     /** the stored answer for this check, or null when it must run. Counts what
      *  it was asked, so the run can report hit/miss/uncacheable honestly. */
+    /** drop the stored answer for a check's CURRENT key: the cache audit found
+     *  that a fresh run disagrees with it, and a fresh failure is never stored
+     *  in its place, so the stale green would keep being served */
+    forget(id: string): void {
+        const k = this.key(id)
+        if (k.key != null) this.answers.drop(NS, k.id, k.key)
+    }
+
     replay(id: string): (CheckOutcome & { at: number }) | null {
         const k = this.key(id)
-        if (k.key == null) { this.unkeyed++; return null }
-        if (!this.reading) { this.misses++; return null }
+        if (k.key == null) { this.unkeyed++; this.ranWhy.set(id, { group: 'never', why: this.neverWhy(k) }); return null }
+        if (!this.reading) { this.misses++; this.ranWhy.set(id, { group: 'off', why: this.fresh ? '--fresh' : 'cache reads off' }); return null }
         const e = this.read(k)
-        if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
-        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, () => this.view()) != null)) { this.misses++; return null }
+        if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; this.ranWhy.set(id, this.movedWhy(k)); return null }
+        if (k.population === 'reads') {
+            const drift = e.payload.reads == null ? 'its read set was not stored' : this.driftOf(e.payload.reads, () => this.view())
+            if (drift != null) { this.misses++; this.ranWhy.set(id, { group: 'moved', why: drift }); return null }
+        }
         this.hits++
         this.replayed.push({ ns: NS, name: k.id, key: k.key })
         return { ...e.payload, at: e.at }
@@ -212,23 +241,70 @@ export class Ledger {
 
     /** a check that missed the store and then adopted another run's in
      *  flight answer: counted apart, so the header never claims it measured */
-    noteAttached(): void {
+    noteAttached(id: string): void {
         if (this.misses > 0) this.misses--
         this.joined++
+        this.ranWhy.delete(id)
+    }
+
+    /** the lines that say why every check that did not replay ran, one per
+     *  reason, so a re-run is never unexplained. A run that reads no cache
+     *  says so in its header instead. `quiet`: a check its author decided is
+     *  never cached, which nobody acts on (--verbose prints it) */
+    explain(): { line: Line; quiet: boolean }[] {
+        const order: RanWhy['group'][] = ['moved', 'first', 'not kept', 'never']
+        const groups = new Map<string, { w: RanWhy; ids: string[] }>()
+        for (const [id, w] of this.ranWhy) {
+            if (w.group === 'off') continue
+            const k = `${order.indexOf(w.group)}\0${w.why}`
+            const g = groups.get(k) ?? { w, ids: [] }
+            g.ids.push(id)
+            groups.set(k, g)
+        }
+        return [...groups.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, { w, ids }]) => {
+            const who = listShort(ids, 5)
+            const text = w.group === 'never' ? `never cached: ${w.why} (${who})`
+                : w.group === 'not kept' ? `ran, not kept: ${w.why} (${who})`
+                : `ran: ${w.why} (${who})`
+            return { line: { kind: 'ok' as const, text }, quiet: w.group === 'never' && w.why.startsWith('never: ') }
+        })
     }
 
     /** buffer what a check just measured. Nothing reaches the store until
      *  commit() has re-hashed the inputs (rule 2). A READS check with no read
      *  set (it reached the world) is never stored (rule 7). */
-    record(id: string, outcome: CheckOutcome, reads?: ReadSet | null): void {
+    record(id: string, outcome: CheckOutcome, reads?: ReadSet | null, notKept?: string | null): void {
         const k = this.key(id)
         if (k.key == null) return
         if (k.population === 'reads') {
-            if (reads == null) return
-            this.buffered.set(id, { ...outcome, reads })
+            if (reads == null) { this.ranWhy.set(id, { group: 'not kept', why: notKept ?? 'it read outside what the cache can see' }); return }
+            this.buffered.set(id, { ...outcome, reads, components: k.components })
             return
         }
-        this.buffered.set(id, outcome)
+        this.buffered.set(id, { ...outcome, components: k.components })
+    }
+
+    /** why a check has no key: its own words when it decided `never`, the
+     *  key layer's otherwise */
+    private neverWhy(k: CheckKey): string {
+        const d = this.layer.decls.find((x) => x.id === k.id)
+        return d != null && classify(d).decided === true ? `never: ${d.never}` : k.reason ?? 'undeclared'
+    }
+
+    /** what moved since this check's last stored answer, by diffing the key
+     *  components it was stored under against this run's */
+    private movedWhy(k: CheckKey): RanWhy {
+        const prev = this.answers.latest<Stored>(NS, k.id)
+        if (prev == null) return { group: 'first', why: 'nothing stored for it yet' }
+        const before = prev.payload.components
+        if (before == null) return { group: 'moved', why: 'its key changed' }
+        const moved = movedParts(before, k.components)
+        return moved.length === 0 ? { group: 'first', why: 'nothing stored for this key yet' } : { group: 'moved', why: `${listShort(moved, 3)} changed` }
+    }
+
+    /** every check that did not come from the cache, and why */
+    get why(): ReadonlyMap<string, RanWhy> {
+        return this.ranWhy
     }
 
     /** re-hash, then write what still describes the tree on disk. */
@@ -295,6 +371,45 @@ export class Ledger {
     }
 }
 
+/** the key components that differ between two keys of one check, in words */
+export function movedParts(before: string[], after: string[]): string[] {
+    const split = (c: string): [string, string] => {
+        // several excluded paths share the name: each one is its own component
+        if (c.startsWith('excluded=')) return [c, '']
+        const i = c.indexOf('=')
+        return i < 0 ? [c, ''] : [c.slice(0, i), c.slice(i + 1)]
+    }
+    const a = new Map(before.map(split))
+    const b = new Map(after.map(split))
+    const names = [...new Set([...a.keys(), ...b.keys()])].filter((n) => a.get(n) !== b.get(n))
+    return [...new Set(names.map(componentWords))]
+}
+
+/** one key component's name as a reader says it */
+function componentWords(name: string): string {
+    if (name === 'v') return "shipkit's key format"
+    if (name === 'bun') return 'the bun version'
+    if (name === 'frozen') return 'frozen mode'
+    if (name === 'toolchain') return "shipkit's gate code"
+    if (name === 'install') return 'node_modules'
+    if (name === 'argv') return 'its command'
+    if (name === 'lib') return 'its shipkit code'
+    if (name === 'libused') return 'the shipkit modules this repo imports'
+    if (name === 'extra') return 'its settings'
+    if (name === 'node') return 'the node version'
+    if (name.startsWith('names:')) return `the names under ${name.slice(6)}`
+    if (name.startsWith('env:')) return `$${name.slice(4)}`
+    if (name === 'in:.') return 'the work tree'
+    if (name.startsWith('in:') || name.startsWith('code:')) return name.slice(name.indexOf(':') + 1)
+    if (name.startsWith('excluded')) return 'ignored files under its inputs'
+    return name
+}
+
+/** `a, b, c`, and `a, b, +3 more` past `max` */
+function listShort(items: string[], max: number): string {
+    return items.length <= max ? items.join(', ') : `${items.slice(0, max - 1).join(', ')}, +${items.length - max + 1} more`
+}
+
 /** where askers of one question meet while one of them measures it: a file
  *  name per (ns, id, key), hashed so any id is a safe name */
 export function inflightSlot(dir: string, ns: string, id: string, key: string): string {

package/src/ledger/store.ts

@@ -164,6 +164,20 @@ export class Answers {
         })
     }
 
+    /** the newest answer of one check under ANY key: what a miss diffs its
+     *  own key against, to say what moved */
+    latest<T>(ns: string, name: string): Stored<T> | null {
+        const row = this.with(READ_BUSY_MS, (h) => h.query('select v, key, at, keeps, payload from answers where ns = ? and name = ? order by at desc limit 1').get(ns, name) as (Row & { key: string }) | null)
+        if (row == null) return null
+        try {
+            const payload = JSON.parse(row.payload) as T
+            if (Number(row.v) !== STORE_VERSION || typeof row.at !== 'number' || payload == null) return null
+            return { v: Number(row.v), key: row.key, at: row.at, keeps: row.keeps ?? undefined, payload }
+        } catch {
+            return null
+        }
+    }
+
     drop(ns: string, name: string, key: string): void {
         this.with(BUSY_MS, (h) => h.query('delete from answers where ns = ? and name = ? and key = ?').run(ns, name, key))
     }

package/src/ledger/toolchain-identity.ts

@@ -1,4 +1,4 @@
-// WHAT PROGRAM IS ABOUT TO RUN, as one hash.
+// WHAT PROGRAM IS ABOUT TO RUN, as hashes.
 //
 // A cache key built from the repo's git tree answers "what source is being
 // gated". It cannot answer "what is doing the gating", and those two already
@@ -16,8 +16,12 @@
 //      package.json files of exactly the same byte length, so only the parsed
 //      `version` separates them.
 //
-// So the key has three parts: the runtime, the gate binary, and what is
-// actually installed.
+// So there are three parts: the RUNNER (the runtime, the gate code that runs
+// and stores every answer, the data files a check reads), the INSTALL (what is
+// actually in node_modules), and the toolkit SOURCE, which each check is keyed
+// on through its own module closure (LibSource), never as a whole. A whole
+// tree hash made a css edit in the hub, or a new test file, move every key in
+// every repo on the machine, and a repo that links the toolkit paid it twice.
 //
 // THE ONE DELIBERATE MISS: a human hand-editing a file inside `node_modules`
 // is accepted, not caught. Catching it means content-hashing the whole tree,
@@ -27,11 +31,21 @@
 // debugging on purpose can delete the ledger.
 import { createHash } from 'crypto'
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'fs'
-import { isAbsolute, join, relative, resolve } from 'path'
+import { dirname, isAbsolute, join, posix, relative, resolve } from 'path'
+import { ALWAYS_SKIP, type RvtConfig } from '../ts/config.ts'
+import { extractSpecs, resolveSpec } from '../ts/source-graph.ts'
+import { blobOid } from '../core/read-set.ts'
 
 export type Toolchain = {
-    /** the identity, 16 hex chars, stable for identical programs */
+    /** the RUNNER, 16 hex chars: the runtime, the gate code that runs and
+     *  stores every answer, and the data files a check reads. Every key
+     *  carries it */
     id: string
+    /** what is installed, 16 hex chars. Only a key whose answer runs the
+     *  repo's own tools carries it: a content or a world check */
+    install: string
+    /** the toolkit's source, for a check's own module closure */
+    lib: LibSource
 }
 
 /** the gate binary driving THIS process, which is what the key hashes when a
@@ -88,9 +102,173 @@ function hashTree(h: ReturnType<typeof createHash>, dir: string, tag: string): v
     h.update(`${tag}=${files.length}\n`)
 }
 
-/** the gate binary's own source, content-hashed. This is what makes editing
- *  shipkit invalidate every key in every repo, in-repo copy or dependency. */
-const hashCliTree = (h: ReturnType<typeof createHash>, cli: string): void => hashTree(h, resolve(cli, '..'), 'clifiles')
+/** a path with its links resolved, as given when it cannot be (a file not
+ *  there yet): /var and /private/var must name one file */
+const real = (p: string): string => { try { return realpathSync(p) } catch { return p } }
+
+/** the modules that run a check and store its answer, relative to the
+ *  toolkit's src. A gate binary without them (a test fixture) is keyed on its
+ *  own entry's closure */
+export const RUNNER_ENTRIES = ['core/run-ci.ts', 'core/run-check.ts']
+
+/** file kinds under src that no check and no runner reads: the page the hub
+ *  serves and the mac app's source. Every other non code file there is data a
+ *  check can read (the scaffold templates), so it is in the runner id */
+const NOT_READ_BY_CHECKS = /\.(css|html|swift)$/
+
+/**
+ * the toolkit's source, keyed one module closure at a time. A check is keyed
+ * on the files its own module can reach, the runner on the files the runner
+ * can reach, and a file neither reaches (the hub page, a test) moves nothing.
+ * Each file is hashed once per process.
+ */
+export class LibSource {
+    /** the package root, resolved: the dir holding the source dir */
+    readonly pkgRoot: string
+    /** the source dir, resolved: the gate binary's own dir */
+    readonly srcDir: string
+    private readonly cfg: RvtConfig
+    private readonly oids = new Map<string, string>()
+    private readonly closures = new Map<string, string[]>()
+    /** file → the files it imports directly, so a file shared by many
+     *  closures is read and parsed once */
+    private readonly direct = new Map<string, string[]>()
+    private readonly probed = new Map<string, boolean>()
+    /** the package name a repo imports the toolkit by, null for a toolkit
+     *  with no package.json (a test fixture) */
+    readonly name: string | null
+
+    constructor(cliEntry: string) {
+        this.srcDir = dirname(realpathSync(cliEntry))
+        this.pkgRoot = dirname(this.srcDir)
+        let name: string | null = null
+        try { name = (JSON.parse(readFileSync(join(this.pkgRoot, 'package.json'), 'utf8')) as { name?: string }).name ?? null } catch { name = null }
+        this.name = name
+        // the toolkit imports itself by its package name, and a closure that
+        // could not follow those would stop at the first such import
+        this.cfg = { root: this.pkgRoot, roots: [relative(this.pkgRoot, this.srcDir)], skip: [...ALWAYS_SKIP], packages: name == null ? [] : [{ name, dir: '.' }] }
+    }
+
+    /** the toolkit file a package specifier names (`rvlib-shipkit/src/x.ts`),
+     *  or null when it names none */
+    fileOf(spec: string): string | null {
+        if (this.name == null || !spec.startsWith(`${this.name}/`)) return null
+        const abs = join(this.pkgRoot, spec.slice(this.name.length + 1))
+        return this.owns(abs) && existsSync(abs) ? abs : null
+    }
+
+    /** is this absolute path a source file of the toolkit? */
+    owns(abs: string): boolean {
+        const r = relative(this.srcDir, real(abs))
+        return r !== '' && !r.startsWith('..') && !isAbsolute(r) && /\.tsx?$/.test(abs)
+    }
+
+    /** package-relative files one entry can reach, dynamic imports included.
+     *  The same walk as `importClosure`, with each file's imports kept */
+    closureOf(abs: string): string[] {
+        const rel = relative(this.pkgRoot, real(abs)).replace(/\\/g, '/')
+        let c = this.closures.get(rel)
+        if (c == null) {
+            const seen = new Set<string>([rel])
+            const queue = [rel]
+            while (queue.length > 0) for (const t of this.importsOf(queue.shift()!)) if (!seen.has(t)) { seen.add(t); queue.push(t) }
+            c = [...seen].sort()
+            this.closures.set(rel, c)
+        }
+        return c
+    }
+
+    private importsOf(file: string): string[] {
+        let d = this.direct.get(file)
+        if (d == null) {
+            const has = (p: string): boolean => {
+                let r = this.probed.get(p)
+                if (r == null) { r = /\.tsx?$/.test(p) && existsSync(join(this.pkgRoot, p)); this.probed.set(p, r) }
+                return r
+            }
+            let text = ''
+            // the entry itself must exist: a missing one throws below, when it is hashed
+            try { text = readFileSync(join(this.pkgRoot, file), 'utf8') } catch { text = '' }
+            const resolveHere = (spec: string): string | null => resolveSpec(this.cfg, file, spec, has)
+            const targets = [...extractSpecs(text, { dynamic: true }).map(resolveHere), ...pathLiterals(text, file, resolveHere)]
+            d = [...new Set(targets.filter((t): t is string => t != null).map((t) => posix.normalize(t)))]
+            this.direct.set(file, d)
+        }
+        return d
+    }
+
+    /** blob id of one package-relative file. A file that cannot be read
+     *  THROWS: a closure only partly read must never be keyed */
+    private oid(rel: string): string {
+        let o = this.oids.get(rel)
+        if (o == null) { o = blobOid(readFileSync(join(this.pkgRoot, rel))); this.oids.set(rel, o) }
+        return o
+    }
+
+    /** the identity of what these entries can reach, 16 hex chars */
+    closureKey(absEntries: string[]): string {
+        const files = [...new Set(absEntries.flatMap((e) => this.closureOf(e)))].sort()
+        const h = createHash('sha256')
+        for (const f of files) h.update(`${f}=${this.oid(f)}\n`)
+        h.update(`n=${files.length}\n`)
+        return h.digest('hex').slice(0, 16)
+    }
+
+    /** the data files under src a check can read, as lines */
+    dataLines(): string[] {
+        const out: string[] = []
+        const walk = (dir: string, rel: string): void => {
+            for (const name of readdirSync(dir).sort()) {
+                if (name === 'node_modules' || name.startsWith('.')) continue
+                const abs = join(dir, name)
+                const r = `${rel}/${name}`
+                if (statSync(abs).isDirectory()) walk(abs, r)
+                else if (!/\.tsx?$/.test(name) && !NOT_READ_BY_CHECKS.test(name)) out.push(`data:${r}=${this.oid(r)}`)
+            }
+        }
+        walk(this.srcDir, relative(this.pkgRoot, this.srcDir))
+        // the version a check compares a repo's pin against
+        if (existsSync(join(this.pkgRoot, 'package.json'))) out.push(`data:package.json=${this.oid('package.json')}`)
+        return out
+    }
+}
+
+/** toolkit modules a file RUNS by path rather than imports: a preload handed
+ *  to bun, a cli spawned through `c.exec`. `join(import.meta.dir, 'x.ts')`,
+ *  `new URL('x.ts', import.meta.url)` and `import.meta.resolve('pkg/x.ts')`,
+ *  resolved like an import. The gate's own `cli.ts` is left out: a module
+ *  that names it spawns the whole program, and what of it produces an answer
+ *  is the runner every key already carries */
+function pathLiterals(text: string, file: string, resolveSpecifier: (spec: string) => string | null): (string | null)[] {
+    const out: (string | null)[] = []
+    const str = /'([^'\n]+)'|"([^"\n]+)"/g
+    const strings = (s: string): string[] => [...s.matchAll(str)].map((x) => x[1] ?? x[2]!)
+    const rel = (parts: string[]): string | null => {
+        const target = posix.normalize(posix.join(posix.dirname(file), ...parts))
+        if (target.endsWith('/cli.ts') || target === 'cli.ts') return null
+        return resolveSpecifier(`./${posix.relative(posix.dirname(file), target)}`)
+    }
+    for (const m of text.matchAll(/join\(\s*import\.meta\.dir\s*,((?:\s*(?:'[^'\n]*'|"[^"\n]*")\s*,?)+)\)/g)) {
+        const parts = strings(m[1]!)
+        if (parts.length > 0 && /\.tsx?$/.test(parts.at(-1)!)) out.push(rel(parts))
+    }
+    for (const m of text.matchAll(/new URL\(\s*('[^'\n]+'|"[^"\n]+")\s*,\s*import\.meta\.url\s*\)/g)) {
+        const p = strings(m[1]!)[0]!
+        if (/\.tsx?$/.test(p)) out.push(rel([p]))
+    }
+    for (const m of text.matchAll(/import\.meta\.resolve\(\s*('[^'\n]+'|"[^"\n]+")\s*\)/g)) {
+        const p = strings(m[1]!)[0]!
+        if (!p.endsWith('/cli.ts')) out.push(resolveSpecifier(p))
+    }
+    return out
+}
+
+/** the runner: the modules that run a check and store its answer, plus the
+ *  data files a check reads */
+function runnerLines(lib: LibSource, cliEntry: string): string[] {
+    const entries = RUNNER_ENTRIES.map((e) => join(lib.srcDir, e)).filter((e) => existsSync(e))
+    return [`runner=${lib.closureKey(entries.length > 0 ? entries : [realpathSync(cliEntry)])}`, ...lib.dataLines()]
+}
 
 /**
  * what ONE install holds, as a hash: every top-level package's name, version
@@ -129,18 +307,14 @@ export function installIdentity(nodeModules: string): string {
  * moves an mtime without changing content produces no miss.
  */
 export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain {
-    const h = createHash('sha256')
     // BOTH sides resolved, or the comparison is wrong on macOS: /var is a
     // symlink to /private/var, so an in-repo cli under a resolved path reads
     // as outside an unresolved root. That mistake is silent and expensive: it
-    // content-hashes the gate binary on every single run, and folds absolute
-    // paths into the id, which is what would stop two worktrees agreeing.
+    // folds absolute paths into the id, which is what would stop two
+    // worktrees agreeing.
     const root = ((): string => { try { return realpathSync(repoRoot) } catch { return resolve(repoRoot) } })()
 
-    // the runtime. Free, and a bun upgrade genuinely changes behaviour
-    h.update(`bun=${Bun.version}\n`)
-
-    // the gate binary, ALWAYS content-hashed, and its path never folded in.
+    // the gate code, ALWAYS content-hashed, and its path never folded in.
     //
     // The earlier shape wrote `cli=in-repo` for a binary inside the repo and
     // leaned on the git tree key to cover it. Both halves were wrong, and both
@@ -149,19 +323,27 @@ export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain
     // covered none of it. And between a checkout that HOSTS the binary and a
     // worktree that runs the same one through the global shim, one wrote
     // `in-repo` and the other wrote an absolute path, so two checkouts running
-    // one identical program could never agree on a key. Content-hashing costs
-    // 3.5 to 9.2ms on a 163-file tree, and it is the only form that is the
-    // same value wherever the caller stands.
-    hashCliTree(h, realpathSync(cliEntry))
+    // one identical program could never agree on a key. Package-relative
+    // content is the only form that is the same value wherever the caller
+    // stands.
+    const lib = new LibSource(cliEntry)
+    const r = createHash('sha256')
+    // the runtime. Free, and a bun upgrade genuinely changes behaviour
+    r.update(`bun=${Bun.version}\n`)
+    for (const l of runnerLines(lib, cliEntry)) r.update(`${l}\n`)
+    return { id: r.digest('hex').slice(0, 16), install: installOf(root, lib), lib }
+}
 
-    // what is installed. The lockfile states the intent; the tree states the fact
+/** what is installed. The lockfile states the intent; the tree states the fact */
+function installOf(root: string, lib: LibSource): string {
+    const h = createHash('sha256')
     const lock = join(root, 'bun.lock')
     h.update(`lock=${existsSync(lock) ? createHash('sha256').update(readFileSync(lock)).digest('hex') : 'none'}\n`)
     const nm = join(root, 'node_modules')
     if (!existsSync(nm)) {
         // a worktree nobody installed is a REAL difference, not a missing input
         h.update('nm=absent\n')
-        return { id: h.digest('hex').slice(0, 16) }
+        return h.digest('hex').slice(0, 16)
     }
     const names = installedNames(nm)
     for (const n of names) {
@@ -180,16 +362,19 @@ export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain
         // its files do, and so does what it has installed itself, since its
         // own imports resolve there. Outside the try on purpose: a linked tree
         // that cannot be read throws, and the key layer then keys nothing.
-        // ~20ms for the whole rvlib-shipkit tree
-        if (outside != null) {
+        //
+        // The toolkit running this gate is the one exception: each check is
+        // keyed on its own closure of it, and hashing it whole here put a css
+        // edit of the hub into every content key of every repo that links it
+        if (outside != null && outside !== lib.pkgRoot) {
             hashTree(h, outside, `linked:${n}`)
             h.update(`${installIdentity(join(outside, 'node_modules'))}\n`)
         }
         let version = 'MISSING'
         try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
-        h.update(`${n}@${version}${link}\n`)
+        h.update(`${n}@${version}${link === '' || outside === lib.pkgRoot ? '' : link}\n`)
     }
     // the count catches a removal that leaves every survivor identical
     h.update(`n=${names.length}\n`)
-    return { id: h.digest('hex').slice(0, 16) }
+    return h.digest('hex').slice(0, 16)
 }

package/src/problems/extract.ts

@@ -10,6 +10,7 @@ import { existsSync } from 'fs'
 import { isAbsolute, relative, resolve } from 'path'
 import type { Line } from '../core/wire.ts'
 import type { Problem, Severity } from './problem-line.ts'
+import { BUN_RECAP } from '../suite/judge-suites.ts'
 
 export type ExtractCtx = {
     /** the repo root every file is made relative to */
@@ -124,6 +125,8 @@ export function fromBunTest(text: string, ctx: ExtractCtx): Problem[] {
     for (const raw of stripAnsi(text).split('\n')) {
         const s = BUN_SUITE.exec(raw)
         if (s != null) { suite = repoFile(ctx, s[1]!, false); error = null; at = null; continue }
+        // every line after it repeats a failure already read above
+        if (BUN_RECAP.test(raw)) break
         const e = BUN_ERROR.exec(raw)
         if (e != null) { error = e[1]!.trim(); at = null; continue }
         const f = BUN_FRAME.exec(raw)

package/src/repo-config.ts

@@ -143,6 +143,15 @@ export type RepoConfig = {
     /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
      *  block — for ecosystem-specific names the published lib may not carry */
     gitignore?: string[]
+    /** gitignored paths a task READS, by task id (`'*'` for every task),
+     *  repo-relative: a path joins that task's key by content (generated
+     *  types, a local fixture), and `dir/**` by the names under the dir (an
+     *  output folder a suite lists). A task keyed on the whole work tree sees
+     *  no gitignored file, and a declared list names none either, so both
+     *  carry these. The traced audit (SK031) finds the missing ones and the
+     *  fix pass writes them into their own managed block; an entry written
+     *  outside it stops that repair */
+    ignoredInputs?: Record<string, string[]>
     /** untrack the paths shipkit generates on every run (STATUS.md and
      *  friends) the first time it sees them tracked, in one commit. Default
      *  ON: a generated file left in the index dirties every tree forever and
@@ -286,7 +295,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'ignoredInputs', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -298,6 +307,14 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
     if (c.serve != null && 'processes' in c.serve)
         throw new Error(`defineRepo: serve.processes was removed; declare each process in a <name>.shipkit.ts file as \`export default globalProcess({...})\``)
+    if (c.ignoredInputs != null && (typeof c.ignoredInputs !== 'object' || Array.isArray(c.ignoredInputs)))
+        throw new Error(`defineRepo: ignoredInputs is { <task id or '*'>: [paths] }`)
+    for (const [task, paths] of Object.entries(c.ignoredInputs ?? {})) {
+        if (task === '' || !Array.isArray(paths)) throw new Error(`defineRepo: ignoredInputs '${task}' must name a task (or '*') and list paths`)
+        for (const p of paths)
+            if (typeof p !== 'string' || p === '' || p.startsWith('/') || p.split('/').includes('..'))
+                throw new Error(`defineRepo: ignoredInputs '${String(p)}' must be a repo-relative path inside the repo`)
+    }
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))