rvlib-shipkit 0.34.0 → 0.35.1

package/src/core/run-check.ts

@@ -1,11 +1,20 @@
 // periodic health — contracts + every *.check.ts in the repo. Discovery IS
 // the registration (core/discover-checks.ts); each check runs as a
-// subprocess: wire lines parsed back, exit code is truth. A check that runs
-// its own CheckSuite keeps its own TTL cache and is never double-cached
-// here; plain checks get a short orchestrator TTL. `--fresh` busts both
-// layers (SHIPKIT_FRESH=1 + RV_CHECK_FRESH=1 travel to children).
+// subprocess: wire lines parsed back, exit code is truth.
+//
+// NOTHING here decides what may be remembered any more. A rule or a check is
+// replayed when it DECLARED how ("inputs" makes it content-keyed and the
+// ledger owns it, "ttl" makes it a world probe and CheckSuite owns it), and
+// otherwise it is measured every run. The blanket 30-minute orchestrator TTL
+// that used to cover every plain check died with that: it cached by default,
+// on top of whatever the check cached for itself, so one question had two
+// staleness windows and neither was declared by anyone. `--fresh`
+// (SHIPKIT_FRESH=1, which travels to children) busts the one that is left.
 import { join, relative } from 'path'
 import { CheckSuite, type CheckOutcome } from './check-suite.ts'
+import { gateUnits } from '../ledger/gate-units.ts'
+import { Ledger, stampReplayed } from '../ledger/ledger.ts'
+import { storeRoot } from '../ledger/store.ts'
 import { CheckCtx } from './check-ctx.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
@@ -18,9 +27,6 @@ import { writeStatus } from './write-status.ts'
 import { SHARE_ENV } from '../release/releases-share.ts'
 import { rmSync } from 'fs'
 
-// orchestrator cache for checks WITHOUT their own suite — short on purpose:
-// this layer only absorbs back-to-back runs, real TTLs live in the checks
-const DISCOVERED_TTL = '30m'
 const CHECK_TIMEOUT_MS = 120_000
 
 export type CheckOpts = {
@@ -44,12 +50,26 @@ export type CheckOpts = {
      *  spends a third-party API call per publish. Undeclared checks are still
      *  collected, because an unclassified check stays fatal. */
     onlyBlocking?: boolean
+    /** the caller is the GATE (`shipkit ci`), so checks that declared
+     *  `export const gate = false` are skipped. `shipkit check` leaves it unset
+     *  and runs everything: the health surface is where a human todo list
+     *  belongs, and the gate is not. */
+    gateOnly?: boolean
     /** the caller narrowed the run to these ids (`ci --only`). Empty or absent
      *  means everything. A `--only` that narrowed TASKS while every check still
      *  ran made the flag actively harmful: `ci --only cycles`, a 0.03s task,
      *  probed every third-party service the repo knows about. One flag, one
      *  meaning, across all three surfaces. */
     only?: string[]
+    /** the run's ledger, when the caller already opened one (runCi does). A
+     *  standalone `shipkit check` opens its own. */
+    ledger?: Ledger | null
+    /** refresh the motherhome registry row. runCi passes false and does it
+     *  ITSELF, after the ledger has committed: that row is a TRACKED file under
+     *  `wiki/`, so writing it before the post-run re-hash makes the gate look
+     *  like an agent editing the tree and throws away every result the run just
+     *  measured. Two reports per gate run was duplication anyway. */
+    reportHome?: boolean
 }
 
 /** does this rule or check answer to one of the `--only` ids? Matched against
@@ -83,7 +103,61 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     const prevFrozen = process.env.SHIPKIT_FROZEN
     if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
     if (o.frozen === true) process.env.SHIPKIT_FROZEN = '1'
-    const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
+    // the caller's ledger, or this run's own. `shipkit check` is a full run
+    // of every rule and check, so it deserves the same replay the gate gets.
+    let ledger: Ledger | null = o.ledger ?? null
+    if (ledger === null && o.ledger === undefined) {
+        try {
+            ledger = Ledger.open(root, gateUnits(root, c), { cliEntry: new URL('../cli.ts', import.meta.url).pathname, fresh: o.fresh })
+        } catch { ledger = null }
+    }
+    const replayed = new Set<string>()
+    const unitIdByName = new Map<string, string>()
+    /** what a TTL'd answer is remembered under, beside its rotation key. A TTL
+     *  says how long the WORLD keeps; it cannot say that the probe was
+     *  rewritten, or that a different shipkit measured it. Without these two a
+     *  fixed check replayed its old verdict for the rest of its TTL. */
+    const worldKey = (unitId: string, rotation?: string): string => {
+        let code = ''
+        try { code = ledger?.layer.keyFor(unitId).codeKey ?? '' } catch { code = '' }
+        return `tc=${ledger?.layer.toolchainId ?? ''}\0code=${code}\0${rotation ?? ''}`
+    }
+    const suite = new CheckSuite({
+        name: c.name,
+        storeDir: storeRoot(root),
+        onResult: (name, r) => {
+            o.onResult?.(name, r)
+            // a replay measured nothing, and a red is never stored. A check
+            // that cannot block had its FAIL rewritten to a warn before this
+            // fires, so the demotion list is what says it failed: a content
+            // key has no TTL, so storing that red would pin it until an
+            // unrelated edit moved the tree, and "the box is off" is fixed by
+            // turning the box on, which changes no file.
+            if (ledger == null || r.cached || replayed.has(name) || r.status === 'skip' || r.status === 'fail') return
+            if (advisoryFailures.includes(name)) return
+            const id = unitIdByName.get(name)
+            if (id == null) return
+            ledger.record(id, { status: r.status, lines: r.lines, measuredMs: r.ms })
+        },
+    })
+    /** a stored answer, re-emitted as a runner that does no work. Keeping it in
+     *  the suite rather than splicing lines afterwards is what preserves
+     *  declaration order, which the wire contract is frozen on. */
+    const addReplay = (unitId: string, name: string, blocking: boolean): boolean => {
+        const hit = ledger?.replay(unitId)
+        if (hit == null) return false
+        replayed.add(name)
+        unitIdByName.set(name, unitId)
+        suite.addCheck({
+            blocking,
+            name,
+            logic: (t) => {
+                for (const l of stampReplayed(hit.lines, hit.measuredMs)) t.lines.push(l)
+                if (t.lines.some((l) => l.kind === 'warn' || l.kind === 'fix-warn')) t.warned = true
+            },
+        })
+        return true
+    }
     // built-in SK rules (rules/rule-registry.ts) THEN the repo's own
     // (repo.config rules: []), id-tagged, crash-safe, fix-pointer floor
     // (rules/rule.ts runRuleLint owns the semantics). `shipkit ci` runs this
@@ -104,11 +178,13 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     for (const rule of [...RULES, ...(c.rules ?? [])]) {
         if (!matchesOnly(o.only, rule.id, rule.title)) continue
         if (o.onlyBlocking === true && !rule.blocking) continue
+        unitIdByName.set(rule.title, rule.id)
+        if (addReplay(rule.id, rule.title, rule.blocking)) continue
         suite.addCheck({
             blocking: rule.blocking,
             name: rule.title,
             remainValidFor: rule.ttl,
-            cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
+            cacheExtra: () => worldKey(rule.id, rule.cacheKey?.({ root, config: c })),
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
@@ -123,22 +199,33 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
         [SHARE_ENV]: sharePath,
-        ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
+        ...(o.fresh === true ? { SHIPKIT_FRESH: '1' } : {}),
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path)
         // file wins, then the repo default, then nothing: an unclassified
         // check is an error, never a guess
         if (!matchesOnly(o.only, d.name, rel)) continue
+        // `ci` answers "is my change good". A check that answers something else,
+        // and that can sit red for months with nothing wrong, is not part of
+        // that answer at any interval. `shipkit check` still runs it, and
+        // naming it in `--only` still runs it, so opting out is never a way to
+        // make a check unreachable.
+        if (o.gateOnly === true && !d.gate && o.only == null) continue
         const blocking = d.blocking ?? c.checkDefaults?.blocking
         if (blocking == null) undeclared.push(rel)
         if (o.onlyBlocking === true && blocking !== true) continue
+        unitIdByName.set(d.name, d.name)
+        if (addReplay(d.name, d.name, blocking ?? true)) continue
         suite.addCheck({
             // a check about the WORLD may remember a measured negative; one
             // about this repo never does (check-suite.ts, the rule)
             blocking: blocking ?? true,
             name: d.name,
-            remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
+            // a WORLD check says how long its answer keeps; everything else is
+            // measured every run rather than blanket-cached by this layer
+            remainValidFor: d.ttl ?? undefined,
+            cacheExtra: () => worldKey(d.name),
             logic: async (t) => {
                 const r = await spawnWithTimeout(['bun', d.path], { cwd: root, timeoutMs: CHECK_TIMEOUT_MS, env: childEnv })
                 for (const l of parseWireOutput(r.out)) t.lines.push(l)
@@ -159,7 +246,11 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
     // frozen = a release-shaped run: reporting would re-dirty the tree the
     // caller is about to demand clean (field wart 2026-08-05, second head)
-    if (o.frozen !== true) reportToMotherhome(root, c)
+    if (o.frozen !== true && o.reportHome !== false) reportToMotherhome(root, c)
+    // the caller that OPENED the ledger owns committing it: runCi commits once
+    // after its tasks and its checks, so a task and a check in one run share
+    // one post-run re-hash
+    if (o.ledger === undefined && ledger != null) r.lines.push(...ledger.header(ledger.commit()))
     return { lines: r.lines, blocked: r.exitCode !== 0, advisoryFailures, undeclared }
 }
 

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, gateOnly: true })
     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 {