rvlib-shipkit 0.38.0 → 1.0.0

package/src/ledger/run-timeline.ts

@@ -0,0 +1,173 @@
+// THE RUN TIMELINE, shaped from the run record: every invocation on record
+// (`shipkit ci`, `shipkit check`, the hub's buttons and its daily pass), each
+// check a lane with its bar at its real start and end, and three lists beside
+// it: the slowest checks, the longest invocations, the test files to fix.
+//
+// Pure: the record is read by the caller, so every rule here is pinned on a
+// seeded record without a disk. Nothing is estimated. A check's start is its
+// finish minus what it measured, which is exactly what the runner timed
+// (core/check-runner.ts finish), and a replay measured nothing, so its bar is a
+// tick at the moment it was answered.
+import type { InvocationRow, InvokedBy, RunRow, RunStatus } from './run-log.ts'
+import type { SuiteRow } from './suite-log.ts'
+
+/** how many invocations the timeline draws, newest first */
+export const TIMELINE_INVOCATIONS = 12
+/** how many rows each list keeps */
+export const TIMELINE_LIST = 12
+/** past this share of its ceiling a check is flagged near it: the same share
+ *  the hub's duration tone turns red at (hub-app/dur.ts) */
+export const NEAR_CEILING_SHARE = 0.5
+
+/** one check run. `running` = still going: its end is the moment the view
+ *  was shaped, and a drawing carries it to now */
+export type TimelineBar = { id: string; start: number; end: number; ms: number; status: RunStatus; replayed: boolean; running?: boolean }
+
+export type TimelineInvocation = {
+    runId: string
+    /** `unknown` for rows written before invocations were recorded */
+    kind: 'ci' | 'check' | 'unknown'
+    /** who started it. A starter this build does not name stays the word the
+     *  record holds */
+    by: InvokedBy | 'unknown' | (string & {})
+    label: string
+    started: number
+    ended: number
+    wallMs: number
+    /** one lane per check, in the order they started */
+    bars: TimelineBar[]
+    reds: number
+    replays: number
+    /** still going: `ended` is the moment the view was shaped */
+    running?: boolean
+}
+
+/** an invocation in a list: its numbers without its lanes */
+export type InvocationSummary = Omit<TimelineInvocation, 'bars'> & { checks: number }
+
+export type SlowCheck = { id: string; meanMs: number; worstMs: number; samples: number; ceilingMs: number | null; flag: 'over' | 'near' | null }
+
+export type SuiteToFix = {
+    check: string; unit: string; file: string; at: number; ms: number; budgetMs: number; tier: 'quick' | 'full'; red: boolean; slow: boolean
+    /** the first failure bun printed for it, when the record kept one */
+    failLine?: string
+}
+
+export type Timeline = {
+    invocations: TimelineInvocation[]
+    slowest: SlowCheck[]
+    longest: InvocationSummary[]
+    testFiles: SuiteToFix[]
+    /** whether a suite record exists at all: an empty list means "nothing to
+     *  fix" only when something was recorded */
+    suitesRecorded: boolean
+    /** the runner's cap, when the caller knows it: what the concurrency band
+     *  draws its line at */
+    cap?: number
+}
+
+export type TimelineInput = {
+    runs: RunRow[]
+    invocations: InvocationRow[]
+    suites: SuiteRow[]
+    /** each check's kill time, ms */
+    ceilings: Record<string, number>
+    /** the checks the repo declares today. Given, `slowest` lists only these:
+     *  a deleted check's rows stay in the run history, and no edit can make it
+     *  faster */
+    inventory?: readonly string[]
+    /** suites declared slow: the quick tier leaves them out, so the budget is
+     *  not theirs to break */
+    declaredSlow?: string[]
+    cap?: number
+    keep?: number
+    listSize?: number
+}
+
+const barOf = (r: RunRow): TimelineBar => ({ id: r.id, start: r.at - r.ms, end: r.at, ms: r.ms, status: r.status, replayed: r.replayed })
+
+/** every invocation on record, newest first, each with its lanes */
+export function invocationsOf(runs: RunRow[], invocations: InvocationRow[]): TimelineInvocation[] {
+    const byRun = new Map<string, RunRow[]>()
+    for (const r of runs) {
+        const list = byRun.get(r.runId) ?? []
+        list.push(r)
+        byRun.set(r.runId, list)
+    }
+    const meta = new Map(invocations.map((i) => [i.runId, i]))
+    const out: TimelineInvocation[] = []
+    for (const [runId, rows] of byRun) {
+        const bars = rows.map(barOf).sort((a, b) => a.start - b.start || a.id.localeCompare(b.id))
+        const inv = meta.get(runId)
+        const first = Math.min(...bars.map((b) => b.start))
+        const last = Math.max(...bars.map((b) => b.end))
+        const started = inv != null ? Math.min(inv.started, first) : first
+        const ended = inv != null ? Math.max(inv.ended, last) : last
+        out.push({
+            runId,
+            kind: inv?.kind ?? 'unknown',
+            by: inv?.by ?? 'unknown',
+            label: inv?.label ?? 'a run recorded before invocations were',
+            started,
+            ended,
+            wallMs: ended - started,
+            bars,
+            reds: bars.filter((b) => b.status === 'fail').length,
+            replays: bars.filter((b) => b.replayed).length,
+        })
+    }
+    return out.sort((a, b) => b.started - a.started)
+}
+
+/** the checks that cost the most when they really run: mean and worst of the
+ *  MEASURED runs, flagged when the worst reached its ceiling or half of it */
+export function slowestChecks(runs: RunRow[], ceilings: Record<string, number>, size = TIMELINE_LIST, inventory?: readonly string[]): SlowCheck[] {
+    const live = inventory == null ? null : new Set(inventory)
+    const ms = new Map<string, number[]>()
+    for (const r of runs) {
+        if (r.replayed || r.status === 'skip') continue
+        if (live != null && !live.has(r.id)) continue
+        const list = ms.get(r.id) ?? []
+        list.push(r.ms)
+        ms.set(r.id, list)
+    }
+    const out: SlowCheck[] = []
+    for (const [id, list] of ms) {
+        const worstMs = Math.max(...list)
+        const ceilingMs = ceilings[id] ?? null
+        const flag = ceilingMs == null ? null : worstMs >= ceilingMs ? 'over' : worstMs > ceilingMs * NEAR_CEILING_SHARE ? 'near' : null
+        out.push({ id, meanMs: Math.round(list.reduce((a, b) => a + b, 0) / list.length), worstMs, samples: list.length, ceilingMs, flag })
+    }
+    return out.sort((a, b) => b.meanMs - a.meanMs || a.id.localeCompare(b.id)).slice(0, size)
+}
+
+/** each suite's LAST recorded run, kept when it was red or broke the quick
+ *  tier budget. Red first, then the slowest */
+export function testFilesToFix(suites: SuiteRow[], declaredSlow: string[] = []): SuiteToFix[] {
+    const slowDecl = new Set(declaredSlow.map((f) => f.replace(/^\.\//, '')))
+    const last = new Map<string, SuiteRow>()
+    for (const s of suites) {
+        const prev = last.get(s.file)
+        if (prev == null || s.at >= prev.at) last.set(s.file, s)
+    }
+    const out: SuiteToFix[] = []
+    for (const s of last.values()) {
+        const red = s.status === 'fail'
+        const slow = s.tier === 'quick' && s.ms > s.budgetMs && !slowDecl.has(s.file)
+        if (red || slow) out.push({ check: s.check, unit: s.unit, file: s.file, at: s.at, ms: s.ms, budgetMs: s.budgetMs, tier: s.tier, red, slow, ...(red && s.failLine != null && s.failLine !== '' ? { failLine: s.failLine } : {}) })
+    }
+    return out.sort((a, b) => Number(b.red) - Number(a.red) || b.ms - a.ms || a.file.localeCompare(b.file))
+}
+
+export function shapeTimeline(o: TimelineInput): Timeline {
+    const all = invocationsOf(o.runs, o.invocations)
+    const size = o.listSize ?? TIMELINE_LIST
+    return {
+        invocations: all.slice(0, o.keep ?? TIMELINE_INVOCATIONS),
+        slowest: slowestChecks(o.runs, o.ceilings, size, o.inventory),
+        longest: [...all].sort((a, b) => b.wallMs - a.wallMs || b.started - a.started).slice(0, size).map(({ bars, ...rest }) => ({ ...rest, checks: bars.length })),
+        testFiles: testFilesToFix(o.suites, o.declaredSlow),
+        suitesRecorded: o.suites.length > 0,
+        ...(o.cap == null ? {} : { cap: o.cap }),
+    }
+}

package/src/ledger/store.ts

@@ -1,5 +1,6 @@
-// ONE STORE. Everything this toolkit remembers between runs lives here, in
-// one shape, under one root, busted by one flag.
+// ONE STORE for every ANSWER this toolkit remembers between runs, in one
+// shape, under one root, busted by one flag. What a run COST lives beside it
+// in `ledger/db.ts`, which nothing about a verdict ever reads.
 //
 // 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
@@ -24,9 +25,16 @@
 // 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.
+//
+// The store dir holds keyed entries and NOTHING else: every file under it is
+// one whole json document, so a reader can walk it and parse all of it. The
+// reporting record beside it (the run db) lives one level up, in
+// `shipkitRoot`, because it is not keyed and is not a json document.
 import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
 import { dirname, join } from 'path'
+import { gitRoot } from '../core/git-root.ts'
 import { atomicWrite } from '../core/locked-write.ts'
+import { LAYOUT } from '../core/layout.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
@@ -44,7 +52,7 @@ export type Stored<T> = {
     key: string
     /** when it was written, ms since epoch */
     at: number
-    /** how long THIS entry stays valid, when that is shorter than the unit's
+    /** how long THIS entry stays valid, when that is shorter than the check's
      *  declared TTL. A measured negative writes one, so a red about the world
      *  clears soon after a human fixes the world, while a clean answer keeps
      *  for the full declared window. Absent means the declared TTL. */
@@ -56,19 +64,22 @@ export type Stored<T> = {
  *  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.
+/** the one dir everything this repo remembers hangs off.
  *
  *  `--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/`,
+ *  A tree that is not a git repo at all still gets one, under `.shipkit/cache/`,
  *  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')
+export function shipkitRoot(root: string): string {
+    const dir = gitRoot(root)?.commonDir
+    return dir == null ? join(root, LAYOUT.cache) : join(dir, 'shipkit')
 }
 
+/** where this repo's remembered ANSWERS live: keyed entries only, one whole
+ *  json document per file, nothing else at any depth. */
+export const storeRoot = (root: string): string => join(shipkitRoot(root), '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
@@ -81,7 +92,7 @@ export function entryPath(store: string, ns: string, name: string, key: string):
 }
 
 /** 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
+ *  side: the check 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 {
@@ -106,8 +117,8 @@ 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
+/** age-based housekeeping. Sweeping by "the checks I know about" is what made
+ *  the old prune wrong: a run narrowed with --only knows about one check 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))

package/src/ledger/suite-log.ts

@@ -0,0 +1,161 @@
+// THE SUITE RECORD — what every test suite cost and whether it passed, per run
+// of the suite runner (src/suite/suite-cli.ts). The runner already timed every
+// suite for its budget and threw the numbers away with its temp dir, so "which
+// tests are slow, which are red" had no answer after the run.
+//
+// Same file and same rules as the run record (ledger/run-log.ts): never read by
+// the gate, one transaction per write, swept by age with the other tables, and
+// a db that cannot be written costs the history one warn line, never a verdict.
+import { treePrefix } from '../core/nesting.ts'
+import { INSERT_SUITE, INSERT_SUITE_RUN, openDb } from './db.ts'
+import { runsPath, type RunStatus } from './run-log.ts'
+
+export type SuiteRow = {
+    /** epoch ms, when the run that timed it ended */
+    at: number
+    /** the suite path, repo relative */
+    file: string
+    ms: number
+    status: Extract<RunStatus, 'pass' | 'fail'>
+    tier: 'quick' | 'full'
+    /** the per suite budget the quick tier held it to */
+    budgetMs: number
+    /** the check whose suite runner timed it (`test`, `test:rvlib-shipkit`), '' when
+     *  the runner ran outside a check or before the record named it */
+    check: string
+    /** the unit whose tests these are (`root`, `rvlib-shipkit`), '' when
+     *  the runner was not told, or before the record named it */
+    unit: string
+    /** CPU the file burned on its own, ms: known only where a process ran it
+     *  alone (an over budget file run again by itself, a phase of one file).
+     *  null or absent everywhere else, because a shared worker's CPU is not
+     *  any one file's */
+    cpuMs?: number | null
+    /** the runner phase that timed it: `parallel` (the quick tier's workers),
+     *  `sequential` (the first phase, one file at a time), `serial` (the
+     *  declared serial files, after it). '' or absent before the record named it */
+    phase?: SuitePhase | ''
+    /** its wall time in that phase, as bun timed it among the others. `ms` is
+     *  the time the budget judged, which an alone rerun replaces with the
+     *  file's own CPU or wall; this is what the file cost the shared run */
+    phaseMs?: number | null
+    /** the first failure bun printed for it, '' or absent when it passed or
+     *  before the record kept it */
+    failLine?: string
+}
+
+export type SuitePhase = 'parallel' | 'sequential' | 'serial'
+
+/** one run of the suite runner as a whole: where its wall time went. The
+ *  check's own run (the run record) is this plus the process that hosts it */
+export type SuiteRunRow = {
+    /** the same `at` as the suite rows it timed */
+    at: number
+    check: string
+    unit: string
+    tier: 'quick' | 'full'
+    /** the runner, first line to the record write */
+    wallMs: number
+    /** before the first phase: probing bun, reading the bunfig and the pool */
+    setupMs: number
+    /** the parallel workers, 0 = one file at a time */
+    workers: number
+    files: number
+    parallelMs: number
+    parallelCpuMs: number | null
+    /** null = no serial phase */
+    serialMs: number | null
+    serialCpuMs: number | null
+    serialFiles: number
+    /** the over budget files, run again one by one before they can fail */
+    aloneMs: number
+    aloneFiles: number
+    /** the machine's one minute load and its cores when the runner judged */
+    load1: number | null
+    cores: number | null
+}
+
+/** how a check runner tells the process it spawns which check it is: the
+ *  suite runner files every suite it times under it */
+export const CHECK_ID_ENV = 'SHIPKIT_CHECK_ID'
+
+/** one write for the whole suite run, each file named from the top of the
+ *  work tree. Returns the warn line a caller prints when the record could not
+ *  be written, null when it was */
+export function recordSuites(root: string, rows: SuiteRow[], run?: SuiteRunRow): string | null {
+    if (rows.length === 0) return null
+    // a unit's runner names its suites from the unit's own dir, while
+    // the record and the hub read paths from the top of the work tree
+    const prefix = treePrefix(root)
+    let path = ''
+    try { path = runsPath(root) } catch { return 'WARN suite timings not recorded: the run record has no home here' }
+    const opened = openDb(path)
+    if (opened == null) return `WARN suite timings not recorded, the run record did not open (${path})`
+    try {
+        const insert = opened.db.query(INSERT_SUITE)
+        opened.db.transaction(() => {
+            for (const r of rows)
+                insert.run(r.at, `${prefix}${r.file}`, Math.round(r.ms), r.status, r.tier, Math.round(r.budgetMs), r.check, r.unit, r.cpuMs == null ? null : Math.round(r.cpuMs), r.phase ?? '', r.phaseMs == null ? null : Math.round(r.phaseMs), r.failLine ?? '')
+            if (run != null)
+                opened.db.query(INSERT_SUITE_RUN).run(run.at, run.check, run.unit, run.tier, Math.round(run.wallMs), Math.round(run.setupMs), run.workers, run.files, Math.round(run.parallelMs),
+                    roundOrNull(run.parallelCpuMs), roundOrNull(run.serialMs), roundOrNull(run.serialCpuMs), run.serialFiles, Math.round(run.aloneMs), run.aloneFiles, run.load1, run.cores)
+        }).immediate()
+        return null
+    } catch {
+        return `WARN suite timings not recorded, the run record refused the write (${path})`
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+const roundOrNull = (n: number | null): number | null => (n == null ? null : Math.round(n))
+const numOrNull = (n: unknown): number | null => (n == null ? null : Number(n))
+const PHASES: readonly string[] = ['parallel', 'sequential', 'serial'] satisfies SuitePhase[]
+
+/** every suite row on record, oldest first. An unreadable db is none */
+export function readSuites(path: string): SuiteRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        const rows = opened.db.query('select at, file, ms, status, tier, budget_ms as budgetMs, check_id as checkId, unit, cpu_ms as cpuMs, phase, phase_ms as phaseMs, fail_line as failLine from suites order by at asc, rowid asc').all() as {
+            at: number; file: string; ms: number; status: string; tier: string; budgetMs: number; checkId: string; unit: string; cpuMs: number | null; phase: string; phaseMs: number | null; failLine: string
+        }[]
+        return rows.map((r): SuiteRow => ({
+            at: Number(r.at), file: String(r.file), ms: Number(r.ms), status: r.status === 'fail' ? 'fail' : 'pass',
+            tier: r.tier === 'full' ? 'full' : 'quick', budgetMs: Number(r.budgetMs), check: String(r.checkId ?? ''), unit: String(r.unit ?? ''),
+            // each one only where the record holds it, so a row written before
+            // the record kept them reads exactly as it was written
+            ...(r.cpuMs == null ? {} : { cpuMs: Number(r.cpuMs) }),
+            ...(PHASES.includes(r.phase) ? { phase: r.phase as SuitePhase } : {}),
+            ...(r.phaseMs == null ? {} : { phaseMs: Number(r.phaseMs) }),
+            ...(r.failLine == null || r.failLine === '' ? {} : { failLine: String(r.failLine) }),
+        }))
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+/** every run of the suite runner on record, oldest first. An unreadable db,
+ *  or one written before the table existed, is none */
+export function readSuiteRuns(path: string): SuiteRunRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        const rows = opened.db.query(
+            'select at, check_id as checkId, unit, tier, wall_ms as wallMs, setup_ms as setupMs, workers, files, parallel_ms as parallelMs, parallel_cpu_ms as parallelCpuMs,' +
+            ' serial_ms as serialMs, serial_cpu_ms as serialCpuMs, serial_files as serialFiles, alone_ms as aloneMs, alone_files as aloneFiles, load1, cores from suite_runs order by at asc, rowid asc',
+        ).all() as Record<string, unknown>[]
+        return rows.map((r): SuiteRunRow => ({
+            at: Number(r.at), check: String(r.checkId ?? ''), unit: String(r.unit ?? ''), tier: r.tier === 'full' ? 'full' : 'quick',
+            wallMs: Number(r.wallMs), setupMs: Number(r.setupMs), workers: Number(r.workers), files: Number(r.files),
+            parallelMs: Number(r.parallelMs), parallelCpuMs: numOrNull(r.parallelCpuMs), serialMs: numOrNull(r.serialMs), serialCpuMs: numOrNull(r.serialCpuMs),
+            serialFiles: Number(r.serialFiles ?? 0), aloneMs: Number(r.aloneMs ?? 0), aloneFiles: Number(r.aloneFiles ?? 0), load1: numOrNull(r.load1), cores: numOrNull(r.cores),
+        }))
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}

package/src/ledger/toolchain-identity.ts

@@ -38,6 +38,12 @@ export type Toolchain = {
     uncacheable: string[]
 }
 
+/** the gate binary driving THIS process, which is what the key hashes when a
+ *  caller names none. One owner rather than the same URL written at each
+ *  entry point, and one place for a caller that must NOT be keyed on the
+ *  source tree it is running from to hand in something stable instead. */
+export const gateBinary = (): string => new URL('../cli.ts', import.meta.url).pathname
+
 /** does this path live inside the repo being gated? */
 const inRepo = (repoRoot: string, p: string): boolean => {
     const r = relative(repoRoot, p)
@@ -82,7 +88,7 @@ function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
  * Exported because a repo's own install is not the only one a gate can run
  * against. Sub-packages carry their own `node_modules`, gitignored like every
  * other, so no git key can see them and the root toolchain does not describe
- * them either. A unit whose declared inputs COVER such a directory folds this
+ * them either. A check whose declared inputs COVER such a directory folds this
  * in beside the path, or the toolchain component stops at the repo root while
  * the task it is meant to describe does not.
  *

package/src/ledger/world-cache.ts

@@ -0,0 +1,111 @@
+// THE WORLD POPULATION's replay policy, in one place: how long an answer
+// about the world keeps, which answers may be kept at all, and what a kept
+// answer is stamped with.
+//
+// The gate runner remembers a check's `ttl` answer through here. Storage is
+// not this module's concern:
+// ledger/store.ts owns the file, and the CONTENT half of the three
+// populations is keyed instead of timed (ledger/ledger.ts).
+//
+// AN ANSWER CACHES. THE ABSENCE OF ONE DOES NOT. That distinction, not
+// pass-versus-fail, is what decides cacheability here, and a future reader is
+// warned off "fixing" the asymmetry:
+//
+//   measured negative  a probe that RAN and came back bad ("the box is off",
+//                      "the token answered 403") is a real answer about the
+//                      world. Replaying it is CORRECT for a WHILE: the world
+//                      does not fix itself between two gate runs, and
+//                      re-asking every 30 seconds spends a third-party API
+//                      call to be told the same thing. It is NOT correct for
+//                      the full TTL, because a negative names something a
+//                      HUMAN is expected to go fix and the fix is invisible
+//                      from here. So a negative keeps for the cap below at
+//                      most, while a clean pass keeps for the whole declared
+//                      window, which is what a long TTL is for.
+//   unmeasured         a probe that could not run at all (registry
+//                      unreachable, no cred, rate limited, tool missing)
+//                      produced no answer. Caching it asserts a dead network
+//                      as fact long after it recovered, so it stores nothing
+//                      and EVICTS whatever was stored.
+//
+// A measured negative may be kept only for a check about the WORLD. One about
+// THIS REPO is fixed by a human and the next run goes green, so replaying its
+// red would be the cache lying about work already done.
+import { fmtStamp, type Line } from '../core/wire.ts'
+import { dropStored, entryPath, FRESH_ENV, readStored, writeStored } from './store.ts'
+import { CACHED, RAN } from '../core/outcome-words.ts'
+
+/** the longest a MEASURED NEGATIVE is remembered, whatever TTL was declared.
+ *  Long enough to stop a re-ask storm inside one working session, short
+ *  enough that the world being fixed is noticed the same day. */
+export const NEGATIVE_TTL_CAP_MS = 60 * 60 * 1000
+
+export type WorldCache = {
+    /** the ONE store root (ledger/store.ts storeRoot) */
+    storeDir: string
+    /** which namespace inside it (the repo name for the gate), so a sweep or
+     *  a manual `rm` can be scoped */
+    ns: string
+    now: () => number
+    /** TEST SEAM: the env var that busts replays. Production is always the one
+     *  house-wide flag, and a test overrides it so busting one suite cannot
+     *  poison a neighbour's run. */
+    freshEnv?: string
+}
+
+const pathFor = (c: WorldCache, name: string, key: string): string => entryPath(c.storeDir, c.ns, name, key)
+
+/** the stored answer for this exact question, or null when it must be
+ *  measured. An entry may keep for LESS than the declared TTL: a measured
+ *  negative wrote its own shorter window, so the run after a fix sees the fix
+ *  rather than the memory of the breakage. */
+export function replayWorld(c: WorldCache, name: string, key: string, ttlMs: number): Line[] | null {
+    if (ttlMs <= 0) return null
+    if (process.env[c.freshEnv ?? FRESH_ENV] != null) return null
+    const entry = readStored<Line[]>(pathFor(c, name, key), key)
+    if (entry == null) return null
+    const keeps = entry.keeps ?? ttlMs
+    const now = c.now()
+    if (now - entry.at >= keeps || now < entry.at) return null
+    // the stamp was baked in when the answer was MEASURED (below): a replay
+    // prints the stored lines VERBATIM, so the live run and every later replay
+    // render the same string. Annotating replays but not live runs diffed on
+    // every fresh-vs-cached alternation, so neither side annotates.
+    return entry.payload
+}
+
+export type Measured = {
+    lines: Line[]
+    /** it passed with nothing to say: no FAIL, no WARN */
+    clean: boolean
+    /** the probe never reached its subject, so there is no answer to keep */
+    unmeasured: boolean
+    /** a negative may be kept: this check reports the WORLD rather than this
+     *  repo (`blocking: false`) */
+    keepNegative: boolean
+}
+
+/** what a measured answer leaves behind, and the lines to report for it. This
+ *  check writes its OWN file and only its own, so a racing runner can lose
+ *  nothing. */
+export function rememberWorld(c: WorldCache, name: string, key: string, ttlMs: number, m: Measured): Line[] {
+    if (ttlMs <= 0) return m.lines
+    const cacheable = !m.unmeasured && (m.clean || m.keepNegative)
+    const keepsFor = m.clean ? ttlMs : Math.min(ttlMs, NEGATIVE_TTL_CAP_MS)
+    const path = pathFor(c, name, key)
+    if (!cacheable) {
+        // an unmeasured run evicts whatever was stored: a later run must
+        // re-probe rather than replay an answer recorded before the outage. A
+        // racing runner may have written a good answer into that same file a
+        // moment ago and lose it here, which costs one re-probe and can never
+        // produce a stale green, so it is the safe direction.
+        dropStored(path)
+        return m.lines
+    }
+    const now = c.now()
+    const lines = m.lines.map((l, i): Line =>
+        i === 0 ? { ...l, text: `${l.text} (${m.clean ? `${CACHED} at ${fmtStamp(now)} until` : `${RAN} at ${fmtStamp(now)}, kept until`} ${fmtStamp(now + keepsFor)})` } : l,
+    )
+    writeStored(path, key, lines, now, keepsFor)
+    return lines
+}

package/src/mv/mv-md.ts

@@ -14,6 +14,10 @@ export type MvOpts = { write?: boolean; commit?: boolean }
 
 const sh = (cmd: string, cwd: string): string => execSync(cmd, { cwd }).toString()
 
+/** a page's own probe, named after the page: a check file, or a legacy
+ *  check script, which shares the suffix. */
+const SIBLING_SUFFIXES = ['.check.ts'] as const
+
 const posix = (p: string): string => p.replace(/\\/g, '/')
 /** a link points at a file. A directory that happens to share a prose word's
  *  spelling is not a reference, and existsSync alone accepts it */
@@ -114,8 +118,10 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
         ...(oldId != null ? [[`${oldId}.md`, `${newId}.md`] as [string, string]] : []),
         // probe file is named after its page; DIR-qualified so another
         // page's same-named check.ts in a different dir never gets rewritten
-        [`${oldBase}/${oldName}.check.ts`, `${newBase}/${newName}.check.ts`],
-        ...(oldId != null ? [[`${oldId}/${oldName}.check.ts`, `${newId}/${newName}.check.ts`] as [string, string]] : []),
+        ...SIBLING_SUFFIXES.flatMap((sfx): [string, string][] => [
+            [`${oldBase}/${oldName}${sfx}`, `${newBase}/${newName}${sfx}`],
+            ...(oldId != null ? [[`${oldId}/${oldName}${sfx}`, `${newId}/${newName}${sfx}`] as [string, string]] : []),
+        ]),
         [`${oldBase}/`, `${newBase}/`],
         ...(oldId != null ? [[`${oldId}/`, `${newId}/`] as [string, string]] : []),
         [oldBase, newBase],
@@ -134,8 +140,10 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     if (existsSync(join(root, oldBase))) {
         moves.set(oldBase, newBase)
         for (const f of tracked) if (f.startsWith(`${oldBase}/`)) moves.set(f, `${newBase}${f.slice(oldBase.length)}`)
-        const probe = `${oldBase}/${oldName}.check.ts`
-        if (existsSync(join(root, probe))) moves.set(probe, `${newBase}/${newName}.check.ts`)
+        for (const sfx of SIBLING_SUFFIXES) {
+            const probe = `${oldBase}/${oldName}${sfx}`
+            if (existsSync(join(root, probe))) moves.set(probe, `${newBase}/${newName}${sfx}`)
+        }
     }
 
     let touched = 0
@@ -164,8 +172,10 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
         // the probe is named after its page, so it only moves when the NAME
         // changed. A move that keeps the name and changes the directory takes
         // the probe along inside the dir, and `git mv X X` is a fatal
-        const oldCheck = join(newBase, `${oldName}.check.ts`)
-        if (oldName !== newName && existsSync(join(root, oldCheck))) sh(`git mv ${JSON.stringify(oldCheck)} ${JSON.stringify(join(newBase, `${newName}.check.ts`))}`, root)
+        for (const sfx of SIBLING_SUFFIXES) {
+            const oldProbe = join(newBase, `${oldName}${sfx}`)
+            if (oldName !== newName && existsSync(join(root, oldProbe))) sh(`git mv ${JSON.stringify(oldProbe)} ${JSON.stringify(join(newBase, `${newName}${sfx}`))}`, root)
+        }
     }
 
     // repo-specific re-stamps (e.g. wiki depth frontmatter) — loud on failure