rvlib-shipkit 0.38.0 → 1.0.0

package/src/wiki/serve-graph.ts

@@ -1,18 +1,48 @@
 // Local graph server: `load()` runs on EVERY request, so a reload always shows
 // the wiki as it is on disk right now — no stale exports, no build step.
+import { relative } from 'path'
+import { gitRoot } from '../core/git-root.ts'
+import { sameOrigin } from '../serve/same-origin.ts'
 import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
+import { acceptPositions, positionsFile, readPositions, seedPositions } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
 import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
-export type ServeMdGraphConfig = { port: number; load: () => MdGraph; title?: string }
+/** the one path from a graph to its page and back: the hub and the standalone
+ *  server both mount it. `file` null = no memory, the page never saves */
+export function graphRoutes(o: { load: () => MdGraph; title?: string; file: string | null; saveUrl: string }) {
+    return {
+        page(): string {
+            const g = o.load()
+            if (o.file == null) return graphHtml(g, { title: o.title })
+            return graphHtml(g, { title: o.title, seed: seedPositions(g, readPositions(o.file)), saveUrl: o.saveUrl })
+        },
+        save(req: Request): Promise<Response> | Response {
+            return o.file == null ? new Response('not found', { status: 404 }) : acceptPositions(req, o.file, o.load)
+        },
+    }
+}
+
+export type ServeMdGraphConfig = { port: number; load: () => MdGraph; title?: string; root?: string }
+
+/** outside a git checkout the standalone graph keeps no memory: it has no
+ *  untracked place to write to */
+export function standalonePositionsFile(root: string): string | null {
+    const top = gitRoot(root)?.top
+    if (top == null) return null
+    return positionsFile(root, `wiki-serve.${relative(top, root) || 'root'}`)
+}
 
-// routes: `/` the interactive graph · `/graph.json` the raw graph data
+// routes: `/` the interactive graph · `/graph.json` the raw graph data · `/positions` the one save per display
 export function serveMdGraph(cfg: ServeMdGraphConfig) {
+    const routes = graphRoutes({ load: cfg.load, title: cfg.title, file: cfg.root == null ? null : standalonePositionsFile(cfg.root), saveUrl: '/positions' })
     return Bun.serve({
         port: cfg.port,
         fetch(req) {
             const path = new URL(req.url).pathname
-            if (path === '/') return new Response(graphHtml(cfg.load(), { title: cfg.title }), { headers: { 'content-type': 'text/html; charset=utf-8' } })
+            if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the graph page', { status: 403 })
+            if (path === '/') return new Response(routes.page(), { headers: { 'content-type': 'text/html; charset=utf-8' } })
             if (path === '/graph.json') return Response.json(cfg.load())
+            if (path === '/positions') return routes.save(req)
             return new Response('not found', { status: 404 })
         },
     })

package/src/cli/cmd_Rules.ts

@@ -1,51 +0,0 @@
-// shipkit rules, render the rule registry: shipkit's built-in SK rules
-// plus whatever the repo registered through `repo.config.ts rules: []`.
-// Agents read ids HERE (or --json), never guess or mint one: the registry
-// is the single source, and a repo whose own invariants are absent from it
-// is a repo whose agents cannot know what binds them.
-import { Command, Option } from 'clipanion'
-import { RULES } from '../rules/rule-registry.ts'
-import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
-
-export type RuleRow = { id: string; title: string; owner: string; blocking: boolean; fixable: boolean; source: 'shipkit' | 'repo'; exempt?: string }
-
-/** the catalog: built-in rules, then the repo's own */
-export function ruleRows(config: RepoConfig | null): RuleRow[] {
-    const row = (source: RuleRow['source']) => (r: { id: string; title: string; owner: string; blocking: boolean; fix?: unknown }): RuleRow =>
-        ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source, ...(config?.ruleExempt?.[r.id] == null ? {} : { exempt: config.ruleExempt[r.id] }) })
-    return [...RULES.map(row('shipkit')), ...(config?.rules ?? []).map(row('repo'))]
-}
-
-export class RulesCommand extends Command {
-    static override paths = [['rules']]
-
-    static override usage = Command.Usage({
-        category: 'Health',
-        description: 'every rule that runs here: whether it BLOCKS or only warns, what it lints, the owning doc, and whether --fix can repair it. Built-in SK rules plus the repo\'s own.',
-        examples: [
-            ['list rules', 'shipkit rules'],
-            ['machine-readable', 'shipkit rules --json'],
-        ],
-    })
-
-    json = Option.Boolean('--json', false, { description: 'machine-readable [{id, title, owner, blocking, fixable, source}]' })
-
-    async execute(): Promise<number> {
-        // a repo without repo.config.ts still gets the built-in catalog: this
-        // command must answer "what rules exist" from anywhere
-        const config = await loadRepoConfig(process.cwd()).catch(() => null)
-        const repoRules = config?.rules ?? []
-        const rows = ruleRows(config)
-        if (this.json) {
-            this.context.stdout.write(`${JSON.stringify(rows)}\n`)
-            return 0
-        }
-        // a catalog, not a health run — no wire prefixes (`ok:` would assert
-        // a passing check into anything that parses wire output)
-        for (const r of rows)
-            this.context.stdout.write(`${r.blocking ? 'BLOCKS ' : 'warns  '}${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}${r.exempt == null ? '' : ` · EXEMPT here: ${r.exempt}`}\n`)
-        if (repoRules.length > 0)
-            this.context.stdout.write(`\n${RULES.length} built-in · ${repoRules.length} repo-local (repo.config.ts rules)\n`)
-        return 0
-    }
-}

package/src/cli/cmd_Units.ts

@@ -1,82 +0,0 @@
-// shipkit units — THE inventory: every task, rule and discovered check on one
-// table, with what it declared about itself. `shipkit rules` covers a third of
-// it, `shipkit keys` answers a different question (what is a unit keyed on,
-// right now), and neither says whether a unit blocks you or only reports the
-// world. That answer had no surface, so it was reconstructed by reading source
-// files, which is how a repo ends up with checks nobody can account for.
-import { writeFileSync } from 'fs'
-import { resolve } from 'path'
-import { Command, Option } from 'clipanion'
-import { loadRepoConfig } from '../repo-config.ts'
-import { envTier, gateInventory, tieredTasks } from '../ledger/gate-units.ts'
-import { renderUnitTable } from '../ledger/unit-table.ts'
-import { classify } from '../ledger/git-key.ts'
-
-export class UnitsCommand extends Command {
-    static override paths = [['units']]
-
-    static override usage = Command.Usage({
-        category: 'Health',
-        description: 'every gate unit on one table: task, rule or check, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
-        examples: [
-            ['the whole inventory', 'shipkit units'],
-            ['the big markdown table, written to a file', 'shipkit units --out STATUS.full.md'],
-            ['only the ones the gate never runs', 'shipkit units --proactive'],
-            ['machine-readable', 'shipkit units --json'],
-        ],
-    })
-
-    json = Option.Boolean('--json', false, { description: 'machine-readable UnitRow[] with the resolved cache population' })
-    md = Option.Boolean('--md', false, { description: 'the full markdown table on stdout, the same bytes --out writes' })
-    out = Option.String('--out', { required: false, description: 'write the markdown table to this file instead of stdout' })
-    blocking = Option.Boolean('--blocking', false, { description: 'only units whose failure can stop you' })
-    proactive = Option.Boolean('--proactive', false, { description: 'only units the gate never runs (`shipkit check` reports them)' })
-    full = Option.Boolean('--full', false, { description: 'resolve tasks the way a FULL-tier run resolves them' })
-
-    async execute(): Promise<number> {
-        const root = process.cwd()
-        const c = await loadRepoConfig(root)
-        const tier = this.full ? 'full' : envTier()
-        let rows = gateInventory(root, c, tieredTasks(c, root, tier))
-        if (this.blocking) rows = rows.filter((r) => r.blocking !== false)
-        if (this.proactive) rows = rows.filter((r) => !r.gate)
-
-        if (this.json) {
-            this.context.stdout.write(`${JSON.stringify(rows.map((r) => ({ ...r, population: classify(r.decl).population })))}\n`)
-            return 0
-        }
-
-        if (this.md || this.out != null) {
-            const md = renderUnitTable({ name: c.name, rows })
-            if (this.out != null) {
-                const target = resolve(root, this.out)
-                writeFileSync(target, `${md.trimEnd()}\n`)
-                this.context.stdout.write(`ok: ${rows.length} unit(s) written to ${this.out}\n`)
-                return 0
-            }
-            this.context.stdout.write(`${md}\n`)
-            return 0
-        }
-
-        // a catalog, not a health run — no wire prefixes, or anything parsing
-        // wire output reads this as a passing check
-        this.context.stdout.write(`${'kind'.padEnd(5)} ${'unit'.padEnd(28)} ${'runs in'.padEnd(9)} ${'failure'.padEnd(10)} ${'cache'.padEnd(11)} ttl\n`)
-        for (const r of rows) {
-            const cls = classify(r.decl)
-            const cache = cls.error != null ? 'BROKEN' : cls.population === 'none' ? (cls.decided === true ? 'never' : 'UNDECLARED') : cls.population
-            const blocking = r.blocking == null ? 'UNDECLARED' : r.blocking ? 'blocks' : 'warns'
-            const runsIn = r.optIn ? 'opt-in' : r.gate ? 'gate' : 'proactive'
-            this.context.stdout.write(
-                `${r.decl.kind.padEnd(5)} ${r.decl.id.padEnd(28)} ${runsIn.padEnd(9)} ${blocking.padEnd(10)} ${cache.padEnd(11)} ${r.decl.ttl ?? ''}\n`,
-            )
-        }
-        const undeclared = rows.filter((r) => { const cl = classify(r.decl); return cl.population === 'none' && cl.decided !== true }).length
-        const proactive = rows.filter((r) => !r.gate && !r.optIn).length
-        this.context.stdout.write(
-            `\n${rows.length} units — ${rows.length - proactive} in the gate, ${proactive} proactive · ${undeclared} still uncacheable with nobody having looked\n`,
-        )
-        if (undeclared > 0) this.context.stdout.write(`      why each one: shipkit keys --burn-down\n`)
-        this.context.stdout.write(`      the full table, refreshed by every gate run: STATUS.full.md\n`)
-        return 0
-    }
-}

package/src/collections/graphs.ts

@@ -1,32 +0,0 @@
-// graphs collection — the MOUNTED md graphs as CHECKED section entries. The
-// mounts arrive as data from the hub's own route resolution (serve/run-serve),
-// never re-derived here: a card linking at an unmounted route renders the 404
-// body inside its iframe. Each instance carries its lint state (orphans +
-// dangling refs = yellow with counts; clean = quiet). A graph whose lint
-// belongs to another repo is link-only, never double-judged here.
-import { lintMd } from '../wiki/lint-md.ts'
-import type { GraphMount } from '../wiki/graph-mount.ts'
-import type { Collection, Instance } from './collection-types.ts'
-
-export function graphsCollection(mounts: GraphMount[]): Collection {
-    return {
-        id: 'graphs',
-        title: 'graphs',
-        media: 'data',
-        list: async () =>
-            mounts.map((m): Instance => {
-                const id = `graph:${m.id}`
-                const href = `/graph/${m.id}`
-                const label = m.note != null ? `${m.label} (${m.note})` : m.label
-                if (m.lint == null) return { id, text: label, href }
-                const r = lintMd({ root: m.lint.root, index: m.lint.index })
-                const issues = r.orphans.length + r.dangling.length
-                return {
-                    id,
-                    text: issues === 0 ? label : `${label} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
-                    severity: issues === 0 ? undefined : 'yellow',
-                    href,
-                }
-            }),
-    }
-}

package/src/contracts/contracts-once.ts

@@ -1,43 +0,0 @@
-// ONE contract evaluation per gate run.
-//
-// Two surfaces report fulfillness inside a single `shipkit ci`: the `contracts`
-// TASK, which exists because deploy tasks declare `deps: ['contracts']` and so
-// need a real ordering edge in the DAG, and rule SK002, which exists because a
-// `shipkit check` with no task phase must still report it. Both are load
-// bearing and neither can be deleted: dropping the task would silently ungate
-// every deploy that depends on it, since checks run AFTER every task.
-//
-// So they stay two REPORTS of one evaluation. The task runs first and its
-// result is what SK002 reads. THE TASK IS AUTHORITATIVE (contracts.md says so
-// too); SK002 evaluating on its own is the fallback for a run with no task
-// phase, not a second opinion.
-//
-// The scope is EXPLICIT and never ambient. A memo that outlived its run would
-// let the hub, which rebuilds its collection list on every request, answer
-// from a snapshot of whatever the last gate saw. Only a caller that owns a run
-// opens one.
-import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts-engine.ts'
-import type { ContractManifest } from './contract-types.ts'
-
-let open = false
-let cached: { key: string; result: Promise<ContractsResult> } | null = null
-
-/** run `fn` as ONE gate run: contract evaluation inside it happens once. */
-export async function withContractsScope<T>(fn: () => Promise<T>): Promise<T> {
-    const outer = open
-    open = true
-    try { return await fn() } finally { if (!outer) { open = false; cached = null } }
-}
-
-/** the evaluation, memoised only while a run scope is open. Outside one it is
- *  a plain call, so `shipkit contracts` and the hub always measure reality. */
-export function evaluateContractsOnce(manifests: ContractManifest[], cfg: ContractsConfig): Promise<ContractsResult> {
-    if (!open) return evaluateContracts(manifests, cfg)
-    // the config decides the verdict, so it belongs in the identity: a run that
-    // somehow evaluated two different configs must not serve one for the other
-    const key = JSON.stringify(cfg)
-    if (cached != null && cached.key === key) return cached.result
-    const result = evaluateContracts(manifests, cfg)
-    cached = { key, result }
-    return result
-}

package/src/core/check-suite.ts

@@ -1,302 +0,0 @@
-// CheckSuite — declare tools / secrets / checks, then `await suite.run()`;
-// renders the v0 wire contract (wire.ts) with exit code.
-//
-// The TTL cache is the API-spam guard: a passing check with `remainValidFor`
-// replays without touching the network. Only clean passes are cached;
-// WARN/FAIL evict. Busts: version bump, secret rotation (key hashes the
-// secret value), `<freshEnv>=1`.
-//
-// STORAGE is not this module's concern any more: ledger/store.ts owns the
-// one store, its shape, and its housekeeping (one immutable file per key,
-// tmp + rename, age-based sweep). This is the WORLD half of the three
-// populations — an answer nothing on disk describes, remembered for a TTL and
-// busted by rotation. The CONTENT half is keyed instead of timed and lives in
-// ledger/ledger.ts. Same store, different key.
-//
-// Secret VALUES never enter this module's state beyond the injected
-// getSecret call + a truncated hash for cache-busting.
-import { existsSync } from 'fs'
-import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
-import { dropStored, entryPath, FRESH_ENV, readStored, sweepStore, writeStored } from '../ledger/store.ts'
-import { fmtStamp, formatLine, parseDuration, type Line } from './wire.ts'
-
-type Logic = (t: CheckCtx) => unknown
-type Prep = { skip?: string; cacheExtra?: string }
-type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic; blocking: boolean }
-
-/** the longest a MEASURED NEGATIVE is remembered, whatever TTL the unit
- *  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. A clean
- *  answer is not capped: "fine" is what a long TTL is for. */
-const NEGATIVE_TTL_CAP_MS = 60 * 60 * 1000
-
-export type GetSecret = (name: string, field: 'get' | 'account') => string | null
-
-export type SecretSpec = {
-    remainValidFor?: string | number
-    version?: number
-    /** appended to the unstored skip message — a POINTER to where to mint (URL, file, or doc section), never inline mint steps */
-    skipHint: string
-}
-
-export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean; /** wall time of the LOGIC, ms — 0 on a replay, since a replay measured nothing */ ms: number }
-
-export type CheckSuiteOpts = {
-    name: string
-    /** the ONE store root (ledger/store.ts storeRoot). Injected rather than
-     *  resolved here so a test can point a suite at a scratch dir. */
-    storeDir: string
-    now?: () => number
-    /** secret backend — consumers inject their own store; default = nothing stored, every secret check skips */
-    getSecret?: GetSecret
-    /** TEST SEAM: the env var that busts this suite's replays. Production is
-     *  always the one house-wide flag (ledger/store.ts FRESH_ENV); a test
-     *  overrides it so busting one suite cannot poison a neighbour's run. */
-    freshEnv?: string
-    /** per-check completion tap (the TUI streams results in) — cached replays
-     *  report cached:true, prep-skips (unstored secret) report status 'skip' */
-    onResult?: (name: string, r: CheckOutcome) => void
-}
-
-export class CheckSuite {
-    readonly name: string
-    private runners: Runner[] = []
-    private toolPaths = new Map<string, string>()
-    private storeDir: string
-    private now: () => number
-    private getSecret: GetSecret
-    private freshEnv: string
-    private onResult?: (name: string, r: CheckOutcome) => void
-
-    constructor(opts: CheckSuiteOpts) {
-        this.name = opts.name
-        this.storeDir = opts.storeDir
-        this.now = opts.now ?? Date.now
-        this.getSecret = opts.getSecret ?? (() => null)
-        this.freshEnv = opts.freshEnv ?? FRESH_ENV
-        this.onResult = opts.onResult
-    }
-
-    /** `blocking` decides what a NEGATIVE result may be cached as: see the
-     *  measured-negative rule in execute(). Default true, the safe side: a
-     *  check that never declared itself is treated as being about this repo,
-     *  so its failures are never replayed. */
-    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic; blocking?: boolean }): void {
-        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic, blocking: spec.blocking ?? true })
-    }
-
-    defineRequiredTool(name: string, opts: { candidates?: string[]; probe?: { args: string[]; expect?: RegExp }; fix: string }): void {
-        this.addCheck({
-            name,
-            logic: async (t) => {
-                // explicit candidate paths beat ambient PATH — a stale global (e.g. tsc 4.x) must not shadow the pinned one
-                const bin = opts.candidates?.find((c) => existsSync(c)) ?? Bun.which(name)
-                if (bin == null) return t.fail(`${name} not installed`, opts.fix)
-                this.toolPaths.set(name, bin)
-                if (opts.probe == null) return t.ok(`${name} present`)
-                const p = await t.exec([bin, ...opts.probe.args])
-                const first = p.out.trim().split('\n')[0] ?? ''
-                if (p.code !== 0 || (opts.probe.expect != null && !opts.probe.expect.test(p.out.trim())))
-                    return t.fail(`${name} present but broken (${first.slice(0, 120)})`, opts.fix)
-                // version-ish summary, not the whole banner (some CLIs append build date + ref)
-                t.ok(`${name} ${(first.split(',')[0] ?? first).slice(0, 80)}`)
-            },
-        })
-    }
-
-    defineRequiredSecret(spec: SecretSpec & { name: string; account?: false; validate: (value: string, t: CheckCtx) => unknown }): void
-    defineRequiredSecret(spec: SecretSpec & { name: string; account: true; validate: (cred: { value: string; account: string }, t: CheckCtx) => unknown }): void
-    defineRequiredSecret(spec: SecretSpec & { name: string[]; validate: (values: string[], t: CheckCtx) => unknown }): void
-    defineRequiredSecret(spec: SecretSpec & { name: string | string[]; account?: boolean; validate: (v: never, t: CheckCtx) => unknown }): void {
-        const names = [spec.name].flat()
-        const primary = names[0]
-        if (primary == null) throw new Error('defineRequiredSecret: name must be non-empty')
-        // probes may run without typechecking — enforce the required pointer at define time too
-        if (typeof spec.skipHint !== 'string' || spec.skipHint.length === 0)
-            throw new Error(`defineRequiredSecret(${primary}): skipHint is required — a pointer to where to mint (URL, file, or doc section)`)
-        const validate = spec.validate as (v: unknown, t: CheckCtx) => unknown
-        let payload: unknown
-        this.runners.push({
-            // conservative on purpose: a secret probe keeps today's behaviour,
-            // where no negative is remembered. Its cache key already hashes the
-            // secret VALUE, so a rotation busts it, which would make caching a
-            // measured 403 sound. That is a severity call for whoever owns the
-            // secrets surface, not a side effect of this change.
-            blocking: true,
-            // bare secret name — this shows up in human-facing WARN/FAIL lines
-            name: names.length === 1 ? primary : primary.split('/').slice(0, 2).join('/') + '/*',
-            ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0,
-            version: spec.version ?? 1,
-            prep: () => {
-                const values = names.map((n) => this.getSecret(n, 'get'))
-                const account = spec.account === true ? this.getSecret(primary, 'account') : undefined
-                const missing = names.filter((_, i) => values[i] == null)
-                if (spec.account === true && account == null) missing.push(`${primary} (account field)`)
-                if (missing.length > 0)
-                    return { skip: `${missing.join(', ')} unstored — ${spec.skipHint}` }
-                payload = spec.account === true ? { value: values[0], account } : Array.isArray(spec.name) ? values : values[0]
-                // secret rotation busts the cache: key = hash of the value(s)
-                const material = [...(values as string[]), account ?? ''].join('\0')
-                return { cacheExtra: new Bun.CryptoHasher('sha256').update(material).digest('hex').slice(0, 16) }
-            },
-            logic: (t) => validate(payload, t),
-        })
-    }
-
-    /** the key a world answer is remembered under: the check's own version
-     *  plus whatever the prep declared (a secret's value hash, a rule's
-     *  cacheKey). A version bump and a rotation both move it, so neither can
-     *  replay across the change. */
-    private cacheKey(r: Runner, extra: string): string {
-        return `v${r.version}\0${extra}`
-    }
-
-    // test seam — run() prints + exits; execute() returns the structured result
-    /** ONE check: cache replay, run, classify, and what it wants remembered.
-     *  Pure with respect to its neighbours, which is what lets execute() run
-     *  them together. */
-    private async runOne(r: Runner): Promise<{ lines: Line[]; skip: string | null; ran: boolean; failed: boolean }> {
-        const prep = r.prep?.() ?? {}
-        if (prep.skip != null) {
-            this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false, ms: 0 })
-            return { lines: [], skip: prep.skip, ran: false, failed: false }
-        }
-        const key = this.cacheKey(r, prep.cacheExtra ?? '')
-        const path = entryPath(this.storeDir, this.name, r.name, key)
-        const entry = readStored<Line[]>(path, key)
-        // an entry may keep for LESS than the declared TTL: a measured negative
-        // writes its own shorter window (below), so the run after a fix sees
-        // the fix rather than the memory of the breakage
-        const keeps = entry?.keeps ?? r.ttlMs
-        const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
-            && entry != null && this.now() - entry.at < keeps && this.now() >= entry.at
-        if (fresh) {
-            // the stamp was baked in when the check RAN (below): a replay
-            // prints the stored lines VERBATIM, so the live run and every
-            // later replay render the same string, and the line changes
-            // only when a re-validation happens. Annotating replays but
-            // not live runs still diffed on every fresh-vs-cached
-            // alternation, so neither side annotates
-            // a replayed WORLD negative keeps its severity: it is still the
-            // answer, and demoting it to a pass would hide a real finding
-            const replayedWarn = entry.payload.some((l) => l.kind === 'warn' || l.kind === 'fail')
-            this.onResult?.(r.name, { lines: entry.payload, status: replayedWarn ? 'warn' : 'pass', cached: true, ms: 0 })
-            return { lines: entry.payload, skip: null, ran: true, failed: false }
-        }
-        const t = new CheckCtx(this.toolPaths)
-        const started = performance.now()
-        try {
-            await r.logic(t)
-        } catch (e) {
-            // both of these mean the probe never reached its subject, so the
-            // run has no answer to remember
-            if (e instanceof RateLimited) t.unreachable(`${r.name} not validated this run (${e.message}) — retry later`)
-            else if (e instanceof ToolUnresolved) { t.unmeasured = true; t.note(`${r.name} skipped (${e.message})`) }
-            else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
-        }
-        // 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", "five repos are
-        //                      uncatalogued") 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, and that asymmetry is
-        //                      deliberate: a clean pass says the world is fine,
-        //                      which a long TTL is exactly right for, while a
-        //                      negative names something a HUMAN is expected to
-        //                      go fix, and the fix is invisible from here. A
-        //                      100d TTL over a revoked token would show the
-        //                      same red for 100 days after it was re-minted,
-        //                      because the token value is not in this key. So a
-        //                      negative keeps for NEGATIVE_TTL_CAP at most.
-        //   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.
-        //                      `skip` lines and the unmeasured flag mark these.
-        //
-        // A measured negative caches ONLY for a check about the WORLD. A
-        // blocking check reports THIS REPO, where the whole point is that a
-        // human fixes it and the next run goes green: replaying its red for a
-        // TTL would be the cache lying about work already done.
-        const unmeasured = t.unmeasured || t.lines.some((l) => l.kind === 'skip')
-        const clean = !t.failed && !t.warned
-        const cacheable = r.ttlMs > 0 && !unmeasured && (clean || !r.blocking)
-        // a clean answer keeps for the whole declared TTL. a negative keeps
-        // only long enough to stop the re-ask storm, so the run after a human
-        // fixes the world sees the fix instead of the memory of the breakage
-        const keepsFor = clean ? r.ttlMs : Math.min(r.ttlMs, NEGATIVE_TTL_CAP_MS)
-        const lines = cacheable
-            ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (${clean ? 'cached' : 'measured'} at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + keepsFor)})` } : l))
-            : t.lines
-        this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false, ms: performance.now() - started })
-        // this check writes its OWN file, and only its own: nothing here reads
-        // or rewrites a neighbour's entry, so a racing runner can lose nothing
-        if (r.ttlMs > 0) {
-            if (cacheable) writeStored(path, key, lines, this.now(), keepsFor)
-            // 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.
-            else if (entry != null) dropStored(path)
-        }
-        return { lines, skip: null, ran: true, failed: t.failed }
-    }
-
-    async execute(): Promise<{ lines: Line[]; exitCode: number }> {
-        sweepStore(this.storeDir, this.name, this.now())
-
-        // CONCURRENT, bounded. Checks are independent by contract: each answers
-        // one question about the world or the repo and shares nothing with its
-        // neighbours, and most of the wall time is a network round trip or a
-        // cold `bun` start. In series, twenty checks cost the SUM; together
-        // they cost the slowest one. Measured on this repo: 18.4s to 6.0s.
-        // Order is preserved by collecting per runner and concatenating in
-        // declaration order, so the wire output is byte-identical to the
-        // sequential run and the frozen contract still holds.
-        const cap = Math.max(2, Math.min(8, navigator.hardwareConcurrency || 4))
-        const results = new Array<Awaited<ReturnType<CheckSuite['runOne']>>>(this.runners.length)
-        let next = 0
-        const worker = async (): Promise<void> => {
-            for (;;) {
-                const i = next++
-                if (i >= this.runners.length) return
-                results[i] = await this.runOne(this.runners[i]!)
-            }
-        }
-        await Promise.all(Array.from({ length: Math.min(cap, this.runners.length) }, () => worker()))
-
-        const out: Line[] = []
-        const skipped: string[] = []
-        let ran = 0
-        let anyFail = false
-        for (let i = 0; i < this.runners.length; i++) {
-            const r = results[i]!
-            out.push(...r.lines)
-            if (r.skip != null) skipped.push(r.skip)
-            if (r.ran) ran++
-            if (r.failed) anyFail = true
-        }
-
-        // contract: `skip:` lines ONLY when no check ran at all (whole probe is
-        // moot without the creds); otherwise a neutral note so passing probes
-        // are not relabeled 'check skip'
-        if (ran === 0) out.push(...skipped.map((s): Line => ({ kind: 'skip', text: `${s} (creds gate reports it)` })))
-        else out.push(...skipped.map((s): Line => ({ kind: 'note', text: `${s} — validation skipped (creds gate reports it)` })))
-
-        return { lines: out, exitCode: anyFail ? 1 : 0 }
-    }
-
-    async run(): Promise<never> {
-        const { lines, exitCode } = await this.execute()
-        const color = process.stdout.isTTY && process.env.NO_COLOR == null
-        for (const l of lines) console.log(formatLine(l, color))
-        process.exit(exitCode)
-    }
-}