rvlib-shipkit 1.1.1 → 1.3.0

package/src/plan/planner.ts

@@ -0,0 +1,428 @@
+// THE PLAN: one list for the machine of every (repo, check) pair, with when it
+// is due next and why. The only thing that starts a run nobody asked for. A
+// save makes the checks whose answer it moved `changed`; a check's `every` or
+// `cron` makes it `scheduled`; a `wait` check of an inactive repo turns `late`
+// and runs once the repo is active again; a click or a terminal is `asked`.
+//
+// the one constraint a reader breaks first: the planner owns no clock. The host
+// calls tick() on its own beat (the daemon's tick, or one interval in a hub of
+// its own), and only the save debounce holds a timer, injected. It decides
+// WHEN, never what is true: every verdict comes from the repo's own runner.
+//
+// what keeps it off the cpu: a save burst is asked about once the repo is
+// quiet (QUIET_MS, or MAX_WAIT_MS into a burst that never stops), a check a
+// save moved waits COST_FACTOR times its last measured run, and nothing it
+// starts on its own starts while the load per core is above LOAD_MAX.
+import { availableParallelism, loadavg } from 'os'
+import { CATCH_UP_BEAT_MS, resumeCatchUp, type CatchUpStore } from './catch-up.ts'
+import { nextDue, resolveCadence, resolveWhenInactive, stablePoint, type EveryValue, type LastResult, type PlanDecl } from './cadence.ts'
+
+export type PlanReason = 'changed' | 'scheduled' | 'late' | 'asked'
+
+/** one check as the plan sees it */
+export type PlanCheck = {
+    id: string
+    /** the name an operator reads, when the host knows one */
+    title?: string
+    plan: PlanDecl
+    /** a save can make it due: its answer is keyed on the tree, or it is a
+     *  gate check nothing can key */
+    onChange: boolean
+    /** what applies when it declared no `every` or `cron` */
+    fallback: { value: EveryValue; why: string }
+}
+
+/** one repo, as the host hands it to the plan */
+export type PlanSource = {
+    repo: string
+    /** its plannable checks, read again after a config reload */
+    checks: () => Promise<PlanCheck[]>
+    /** every check's last result on record */
+    last: () => Record<string, LastResult>
+    /** the checks a save moved: their answer would not replay */
+    changed: () => Promise<string[]>
+    /** run these checks now, in the background; resolves to the exit code */
+    run: (ids: string[], why: PlanReason) => Promise<number>
+    /** at join: did the owner edit something after the repo's last run. A
+     *  yes counts as a save, so a burst a restart in place cut off settles
+     *  and is asked about like any other */
+    pending?: () => Promise<boolean>
+}
+
+export type PlanState = 'running' | 'due' | 'late' | 'next' | 'idle'
+
+export type PlanRow = {
+    repo: string
+    check: string
+    /** the name an operator reads, when the host knows one */
+    title: string | null
+    state: PlanState
+    /** why it is due or planned, null for a check that waits for a save */
+    reason: PlanReason | null
+    /** when it is due, null when only a save makes it due */
+    dueAt: number | null
+    /** the rule that planned it: for a lambda, the value it returned and the
+     *  state that chose it */
+    rule: string
+    /** what it does while the repo is inactive, and why */
+    inactive: string
+    /** a lambda that threw, or a value that is not a cadence */
+    error: string | null
+    last: LastResult | null
+    active: boolean
+}
+
+export type PlanTimers = { set: (fn: () => void, ms: number) => unknown; clear: (h: unknown) => void }
+
+const realTimers: PlanTimers = { set: (fn, ms) => setTimeout(fn, ms), clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>) }
+
+/** how long a repo must be quiet (no tracked write) before the plan asks
+ *  what a save burst moved: an agent's edit, test, edit loop stays inside it,
+ *  so the loop costs one question and one run */
+export const QUIET_MS = 60_000
+
+/** a repo written to without a pause is still asked this often */
+export const MAX_WAIT_MS = 10 * 60_000
+
+/** a check a save moved runs at most once per this many times its last
+ *  measured run: a 30s suite at most every 10 minutes, a 200ms lint at once */
+export const COST_FACTOR = 20
+
+/** above this 1 minute load average per core, the plan starts nothing on its
+ *  own: every core already has a process waiting for it */
+export const LOAD_MAX = 1
+
+/** the machine's 1 minute load average per core */
+export const machineLoad = (): number => loadavg()[0]! / Math.max(1, availableParallelism())
+
+/** a decided fact whose probe could not answer retries after this, doubled
+ *  per skip in a row, up to ONCE_RETRY_MAX_MS. From its run on record, so a
+ *  restart changes nothing */
+export const ONCE_RETRY_MS = 3_600_000
+export const ONCE_RETRY_MAX_MS = 24 * 3_600_000
+
+export const onceRetry = (streak: number): number => Math.min(ONCE_RETRY_MAX_MS, ONCE_RETRY_MS * 2 ** Math.max(0, Math.min(10, streak - 1)))
+
+/** how often the last results are read again when nothing ran here */
+export const LAST_EVERY_MS = 15_000
+
+type Mark = { changedAt?: number; askedAt?: number; attemptAt?: number }
+
+type Repo = {
+    src: PlanSource
+    checks: PlanCheck[]
+    last: Record<string, LastResult>
+    lastRead: number
+    marks: Map<string, Mark>
+    timer: unknown
+    /** when the save burst the timer waits on began */
+    burstAt: number | null
+    /** when that timer fires */
+    settleAt: number | null
+    detecting: Promise<void> | null
+    again: boolean
+    error: string | null
+}
+
+const ORDER: Record<PlanReason, number> = { asked: 0, changed: 1, scheduled: 2, late: 3 }
+
+/** work already overdue when the plan starts spreads over this window */
+export const CATCH_UP_MS = 2 * 3_600_000
+
+export class Planner {
+    private repos = new Map<string, Repo>()
+    private running: { repo: string; ids: Set<string>; since: number } | null = null
+    private readonly now: () => number
+    private readonly timers: PlanTimers
+    private readonly quietMs: number
+    private readonly maxWaitMs: number
+    private readonly load: () => number
+    private readonly cores: number
+    private holdReason: string | null = null
+    private readonly catchUp: CatchUpStore | null
+    private beatAt: number
+    /** is this repo active: an agent works in it, VS Code has it open, or it is flagged */
+    active: (repo: string) => boolean = () => true
+
+    /** when this plan's catch up window started: what was overdue then is
+     *  spread, never fired at once. With a store, a restart in place keeps
+     *  the window it had (catch-up.ts) */
+    private readonly bootAt: number
+
+    constructor(private o: { now?: () => number; timers?: PlanTimers; quietMs?: number; maxWaitMs?: number; load?: () => number; cores?: number; catchUp?: CatchUpStore; onError?: (repo: string, e: Error) => void } = {}) {
+        this.now = o.now ?? Date.now
+        this.catchUp = o.catchUp ?? null
+        this.bootAt = this.catchUp != null ? resumeCatchUp(this.now(), this.catchUp) : this.now()
+        this.beatAt = this.now()
+        this.cores = o.cores ?? availableParallelism()
+        this.timers = o.timers ?? realTimers
+        this.quietMs = o.quietMs ?? QUIET_MS
+        this.maxWaitMs = o.maxWaitMs ?? MAX_WAIT_MS
+        this.load = o.load ?? machineLoad
+    }
+
+    private fail(repo: string, e: unknown): void {
+        this.o.onError?.(repo, e instanceof Error ? e : new Error(String(e)))
+    }
+
+    /** a repo joins the plan (or its source is replaced, after a reload) */
+    async add(src: PlanSource): Promise<void> {
+        const old = this.repos.get(src.repo)
+        if (old?.timer != null) this.timers.clear(old.timer)
+        const r: Repo = { src, checks: [], last: {}, lastRead: -Infinity, marks: old?.marks ?? new Map(), timer: null, burstAt: null, settleAt: null, detecting: null, again: false, error: null }
+        this.repos.set(src.repo, r)
+        await this.reload(src.repo)
+        try {
+            if (this.repos.get(src.repo) === r && (await src.pending?.()) === true) this.touched(src.repo)
+        } catch (e) {
+            this.fail(src.repo, e)
+        }
+    }
+
+    /** read its checks again, after a config edit */
+    async reload(repo: string): Promise<void> {
+        const r = this.repos.get(repo)
+        if (r == null) return
+        try {
+            r.checks = await r.src.checks()
+            r.error = null
+        } catch (e) {
+            r.error = `its checks did not load: ${(e as Error).message}`
+            this.fail(repo, e)
+        }
+        this.readLast(r, true)
+    }
+
+    remove(repo: string): void {
+        const r = this.repos.get(repo)
+        if (r?.timer != null) this.timers.clear(r.timer)
+        this.repos.delete(repo)
+    }
+
+    has(repo: string): boolean {
+        return this.repos.has(repo)
+    }
+
+    /** the check ids a repo declares today; null while the plan does not
+     *  hold them (not loaded, still loading, or its checks failed to load) */
+    declared(repo: string): ReadonlySet<string> | null {
+        const r = this.repos.get(repo)
+        if (r == null || r.error != null || r.checks.length === 0) return null
+        return new Set(r.checks.map((c) => c.id))
+    }
+
+    /** each declared check's title by id, null while `declared` is */
+    titles(repo: string): ReadonlyMap<string, string> | null {
+        if (this.declared(repo) == null) return null
+        return new Map(this.repos.get(repo)!.checks.map((c) => [c.id, c.title ?? c.id]))
+    }
+
+    private readLast(r: Repo, force = false): void {
+        const now = this.now()
+        if (!force && now - r.lastRead < LAST_EVERY_MS) return
+        r.lastRead = now
+        try {
+            r.last = r.src.last()
+        } catch (e) {
+            this.fail(r.src.repo, e)
+        }
+    }
+
+    private mark(r: Repo, id: string): Mark {
+        let m = r.marks.get(id)
+        if (m == null) {
+            m = {}
+            r.marks.set(id, m)
+        }
+        return m
+    }
+
+    /** a file moved in this repo: once the burst is quiet, the checks whose
+     *  answer it moved turn `changed`. A burst past the wait cap keeps the
+     *  timer it has, so a repo never quiet is still asked */
+    touched(repo: string): void {
+        const r = this.repos.get(repo)
+        if (r == null) return
+        const now = this.now()
+        r.burstAt ??= now
+        if (r.timer != null) {
+            if (now - r.burstAt >= this.maxWaitMs) return
+            this.timers.clear(r.timer)
+        }
+        r.settleAt = now + this.quietMs
+        r.timer = this.timers.set(() => {
+            r.timer = null
+            r.burstAt = null
+            r.settleAt = null
+            void this.detect(repo)
+        }, this.quietMs)
+    }
+
+    /** ask the repo which checks a save moved, now. One question at a time
+     *  per repo, and one more after it when a save landed meanwhile */
+    async detect(repo: string): Promise<string[]> {
+        const r = this.repos.get(repo)
+        if (r == null) return []
+        if (r.detecting != null) {
+            r.again = true
+            await r.detecting
+            return []
+        }
+        let found: string[] = []
+        r.detecting = (async () => {
+            do {
+                r.again = false
+                try {
+                    // a save can add a check file or edit a cadence
+                    await this.reload(repo)
+                    const ids = await r.src.changed()
+                    const at = this.now()
+                    const known = new Set(r.checks.filter((c) => c.onChange).map((c) => c.id))
+                    for (const id of ids) {
+                        if (!known.has(id)) continue
+                        const m = this.mark(r, id)
+                        m.changedAt ??= at
+                        found.push(id)
+                    }
+                } catch (e) {
+                    this.fail(repo, e)
+                }
+            } while (r.again)
+        })().finally(() => { r.detecting = null })
+        await r.detecting
+        return found
+    }
+
+    /** a click or a terminal: this check runs next */
+    ask(repo: string, check: string): boolean {
+        const r = this.repos.get(repo)
+        if (r == null || !r.checks.some((c) => c.id === check)) return false
+        this.mark(r, check).askedAt = this.now()
+        return true
+    }
+
+    private row(r: Repo, c: PlanCheck, now: number, active: boolean): PlanRow {
+        const m = r.marks.get(c.id) ?? {}
+        const last = r.last[c.id] ?? null
+        const s = { active }
+        const cad = resolveCadence(c.plan, c.fallback, last, s, `${r.src.repo}\0${c.id}`)
+        const wi = resolveWhenInactive(c.plan, last, s)
+        const error = cad.error ?? wi.error
+        const base = { repo: r.src.repo, check: c.id, title: c.title ?? null, rule: cad.rule, inactive: wi.rule, error, last, active }
+        if (this.running?.repo === r.src.repo && this.running.ids.has(c.id)) return { ...base, state: 'running', reason: null, dueAt: this.running.since }
+        if (m.askedAt != null) return { ...base, state: 'due', reason: 'asked', dueAt: m.askedAt }
+        if (m.changedAt != null) {
+            // a check pays for its own runs: one save cannot run it again
+            // before COST_FACTOR times its last measured run has passed
+            const spaced = last?.cost != null ? last.cost.at + COST_FACTOR * last.cost.ms : -Infinity
+            const at = Math.max(m.changedAt, spaced)
+            return { ...base, state: at > now ? 'next' : 'due', reason: 'changed', dueAt: at }
+        }
+        const lastAt = Math.max(last?.at ?? -Infinity, m.attemptAt ?? -Infinity)
+        // a decided fact that could not answer: its retry comes from its run
+        // on record, never from a boot
+        const raw = cad.cadence.kind === 'once' && last?.unknown === true ? Math.max(last.at + onceRetry(last.streak), m.attemptAt != null ? m.attemptAt + onceRetry(last.streak) : -Infinity) : nextDue(cad.cadence, Number.isFinite(lastAt) ? lastAt : null, now)
+        // overdue before the plan started (a machine asleep, a day off): each
+        // pair lands at its own stable point of the catch up window
+        const due = raw != null && raw < this.bootAt ? this.bootAt + Math.round(stablePoint(`catch up\0${r.src.repo}\0${c.id}`) * CATCH_UP_MS) : raw
+        if (due == null) return { ...base, state: 'idle', reason: null, dueAt: null }
+        if (due > now) return { ...base, state: 'next', reason: 'scheduled', dueAt: due }
+        if (!active && wi.value === 'wait') return { ...base, state: 'late', reason: 'late', dueAt: due }
+        return { ...base, state: 'due', reason: 'scheduled', dueAt: due }
+    }
+
+    /** the whole plan, now: every repo and check pair */
+    rows(repo?: string): PlanRow[] {
+        const now = this.now()
+        const out: PlanRow[] = []
+        for (const r of this.repos.values()) {
+            if (repo != null && r.src.repo !== repo) continue
+            this.readLast(r)
+            const active = this.active(r.src.repo)
+            for (const c of r.checks) out.push(this.row(r, c, now, active))
+        }
+        return out
+    }
+
+    /** what the host shows beside the rows: a repo whose checks did not load */
+    errors(): { repo: string; error: string }[] {
+        return [...this.repos.values()].filter((r) => r.error != null).map((r) => ({ repo: r.src.repo, error: r.error! }))
+    }
+
+    /** what holds work back right now, one line each: the repos whose save
+     *  burst is settling, and the load that held the last look */
+    held(): string[] {
+        const now = this.now()
+        const out: string[] = []
+        for (const r of this.repos.values())
+            if (r.settleAt != null) out.push(`settling: ${r.src.repo}, ${Math.max(0, Math.ceil((r.settleAt - now) / 1_000))}s`)
+        if (this.holdReason != null) out.push(this.holdReason)
+        return out
+    }
+
+    /** a batch is in flight */
+    busy(): boolean {
+        return this.running != null
+    }
+
+    /** one look: when nothing runs, the repo holding the most urgent due row
+     *  runs every row of its that is due, as one background run. Resolves when
+     *  that batch is started, never when it ends */
+    tick(): { repo: string; ids: string[]; reason: PlanReason } | null {
+        this.beat()
+        if (this.running != null) return null
+        let due = this.rows().filter((x) => x.state === 'due')
+        if (due.length === 0) {
+            this.holdReason = null
+            return null
+        }
+        // a loaded machine runs only what someone asked for
+        const load = this.load()
+        if (load > LOAD_MAX) {
+            due = due.filter((x) => x.reason === 'asked')
+            if (due.length === 0) {
+                this.holdReason = `held: load ${(load * this.cores).toFixed(1)} on ${this.cores} cores`
+                return null
+            }
+        }
+        this.holdReason = null
+        due.sort((a, b) => ORDER[a.reason!] - ORDER[b.reason!] || (a.dueAt ?? 0) - (b.dueAt ?? 0))
+        const first = due[0]!
+        const r = this.repos.get(first.repo)!
+        const rows = due.filter((x) => x.repo === first.repo)
+        const ids = rows.map((x) => x.check)
+        const at = this.now()
+        for (const x of rows) {
+            const m = this.mark(r, x.check)
+            // a save during the run marks it again, after this stamp
+            if (m.changedAt != null && m.changedAt <= at) delete m.changedAt
+            if (m.askedAt != null && m.askedAt <= at) delete m.askedAt
+            m.attemptAt = at
+        }
+        this.running = { repo: first.repo, ids: new Set(ids), since: at }
+        void r.src.run(ids, first.reason!)
+            .catch((e) => this.fail(first.repo, e))
+            .finally(() => {
+                this.running = null
+                if (this.repos.get(first.repo) === r) this.readLast(r, true)
+            })
+        return { repo: first.repo, ids, reason: first.reason! }
+    }
+
+    /** the catch up window's last beat, at most once a minute */
+    private beat(): void {
+        const now = this.now()
+        if (this.catchUp == null || now - this.beatAt < CATCH_UP_BEAT_MS) return
+        this.beatAt = now
+        this.catchUp.set({ start: this.bootAt, seen: now })
+    }
+
+    /** resolves once no batch is in flight */
+    async idle(): Promise<void> {
+        while (this.running != null) await new Promise((res) => setTimeout(res, 5))
+    }
+
+    stop(): void {
+        for (const r of this.repos.values()) if (r.timer != null) this.timers.clear(r.timer)
+    }
+}

package/src/plan/repo-source.ts

@@ -0,0 +1,212 @@
+// one repo as the plan sees it (planner.ts PlanSource): which checks it can
+// plan and on what, their last results from the run record, which ones a
+// save moved, and how a batch runs through the hub's own runner.
+//
+// the one constraint a reader breaks first: `changed` asks the ledger, never
+// the file event. A check is changed when its answer would not replay: a key
+// that moved, a read set that drifted, no stored green, or no key at all for
+// a gate check. A red keyed on content counts only once its key moves, so a
+// save elsewhere never re-runs it.
+import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
+import { Ledger } from '../ledger/ledger.ts'
+import { answersDb } from '../ledger/store.ts'
+import { hasWorld, worldKeyOf, type WorldCache } from '../ledger/world-cache.ts'
+import { FOREVER, FOREVER_MS } from '../core/wire.ts'
+import { ONCE, type LastResult } from './cadence.ts'
+import { openDb } from '../ledger/db.ts'
+import { readLastResults } from '../ledger/run-log.ts'
+import { gateBinary } from '../ledger/toolchain-identity.ts'
+import { populationOf } from '../problems/problem-line.ts'
+import { movedSince } from '../serve/tracked-watch.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { PlanCheck, PlanReason, PlanSource } from './planner.ts'
+
+/** the rows the plan covers: what a gate or a health pass runs. A release
+ *  check, an off one and an opt in build step wait for whoever names them */
+export function plannable(row: CheckRow): boolean {
+    if (row.when.at !== 'always' && row.when.at !== 'health') return false
+    // nothing to do in this repo on a clock (check.ts planOff)
+    if (row.planOff != null) return false
+    if (row.optIn) return false
+    return !(row.build && row.when.at === 'health')
+}
+
+/** a REPO check nothing can key and that declares no cadence runs about
+ *  once a day, never in step, until it declares what it depends on. No
+ *  built-in may land here (tests/plan-default-range.test.ts) */
+const DEFAULT_EVERY: [string, string] = ['20h', '28h']
+
+/** why the plan cannot tell when this check's answer moves, or null when it
+ *  can: a key, a ttl, a build step or a declared cadence says it */
+export function planGap(row: CheckRow): string | null {
+    const pop = populationOf(row.decl)
+    if (pop === 'content' || pop === 'reads' || pop === 'world' || row.build) return null
+    if (row.plan?.every !== undefined || row.plan?.cron != null) return null
+    const why = row.decl.never != null && row.decl.never !== '' ? `never cached (${row.decl.never})` : (row.decl.uncacheable ?? 'declares neither inputs nor ttl')
+    return `${why}, and no every: nothing says when its answer moves`
+}
+
+/** one inventory row as a plan check. A world check keeps its ttl as its
+ *  cadence; a build step and a check keyed on its files wait for a save (its
+ *  answer replays until a file moves, so a clock re-asks nothing); a repo
+ *  check with no cadence runs at its own stable point of the default range,
+ *  and a built-in with none waits for a save and shows on the burn-down */
+export function planCheckOf(row: CheckRow): PlanCheck {
+    const pop = populationOf(row.decl)
+    const keyed = pop === 'content' || pop === 'reads'
+    const ttl = row.decl.ttl != null && row.decl.ttl !== '' ? row.decl.ttl : null
+    const fallback =
+        ttl === FOREVER ? { value: ONCE, why: 'a decided fact: ttl forever' }
+        : ttl != null ? { value: ttl, why: 'its ttl' }
+        : row.build ? { value: null, why: 'a build step' }
+        : keyed ? { value: null, why: 'keyed on its files' }
+        : row.from === 'repo' ? { value: DEFAULT_EVERY, why: 'the default range' }
+        : { value: null, why: 'a built-in declaring nothing, see shipkit keys --burn-down' }
+    // a gate check nothing can key waits for a save only when no cadence
+    // says when to run it: a range or an every it declares is the rule
+    const clocked = fallback.value != null || row.plan?.every !== undefined || row.plan?.cron != null
+    return {
+        id: row.decl.id,
+        title: row.title,
+        plan: row.plan ?? {},
+        // a decided fact is keyed on its declaration, so a save can move it
+        onChange: isForever(row) || (pop !== 'world' && (keyed || (row.gate && !clocked))),
+        fallback,
+    }
+}
+
+const isForever = (row: CheckRow): boolean => row.decl.ttl === FOREVER
+
+/** the key a decided fact's answer is stored under: its declared value */
+const factKey = (r: CheckRow): string => worldKeyOf({ ttlMs: FOREVER_MS, toolchain: '', code: '', rotation: r.decl.extra ?? '', frozen: r.decl.writes === true ? false : null })
+
+/** a decided fact with no answer stored for its current key: its declaration
+ *  moved, it never ran, or the db was lost. The plan runs these once */
+export function unknownFacts(rows: CheckRow[], cache: WorldCache): Set<string> {
+    const out = new Set<string>()
+    for (const r of rows) if (isForever(r) && !hasWorld(cache, r.decl.id, factKey(r), FOREVER_MS)) out.add(r.decl.id)
+    return out
+}
+
+/** each check's last MEASURED run from the record: when it finished and how
+ *  long it took. A replayed run is left out, it cost nothing */
+export function readLastCosts(path: string): Record<string, { at: number; ms: number }> {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return {}
+    const out: Record<string, { at: number; ms: number }> = {}
+    try {
+        const rows = opened.db.query(`select id, max(at) as at, ms from runs where replayed = 0 group by id`).all() as { id: string; at: number; ms: number }[]
+        for (const r of rows) out[r.id] = { at: Number(r.at), ms: Number(r.ms) }
+    } catch {
+        return {}
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+    return out
+}
+
+/** when the latest run on record started, whoever ran it, or null */
+export function lastStarted(path: string): number | null {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return null
+    try {
+        const r = opened.db.query('select max(started) as at from invocations').get() as { at: number | null } | null
+        return r?.at == null ? null : Number(r.at)
+    } catch {
+        return null
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+export type RepoSourceDeps = {
+    repo: string
+    root: string
+    /** the config as it stands on disk */
+    config: () => RepoConfig
+    /** the run record path, '' when there is none */
+    record: string
+    /** the hub's own runner: `gate` for checks the gate runs, else a health run */
+    run: (ids: string[], o: { gate: boolean }, why: PlanReason) => Promise<number>
+}
+
+export function repoSource(d: RepoSourceDeps): PlanSource {
+    let rows: CheckRow[] = []
+    /** the content key each check had at the last question, so a red one
+     *  counts as changed only when its key moves */
+    const seen = new Map<string, string>()
+    /** the decided facts with no answer for their key, asked again at every
+     *  load and save: their last result counts as none, so they are due */
+    let unknown = new Set<string>()
+    /** the decided facts whose declaration moved since the last load */
+    const moved = new Set<string>()
+    const facts = new Map<string, string>()
+    const cache = (): WorldCache => ({ db: answersDb(d.root), ns: d.config().name, now: Date.now })
+    return {
+        repo: d.repo,
+        checks: async () => {
+            rows = (await gateInventory(d.root, d.config(), { tier: 'quick' })).filter(plannable)
+            unknown = rows.some(isForever) ? unknownFacts(rows, cache()) : new Set()
+            for (const r of rows.filter(isForever)) {
+                const k = factKey(r)
+                const before = facts.get(r.decl.id)
+                if (before != null && before !== k) moved.add(r.decl.id)
+                facts.set(r.decl.id, k)
+            }
+            return rows.map(planCheckOf)
+        },
+        last: () => {
+            const all: Record<string, LastResult> = d.record === '' ? {} : readLastResults(d.record)
+            // a fact with no answer runs; one whose probe could not answer
+            // retries on a backoff from its skip, never at each boot
+            for (const id of unknown) {
+                if (all[id]?.status === 'skip') all[id] = { ...all[id]!, unknown: true }
+                else delete all[id]
+            }
+            const costs = d.record === '' ? {} : readLastCosts(d.record)
+            for (const [id, cost] of Object.entries(costs)) if (all[id] != null) all[id] = { ...all[id]!, cost }
+            return all
+        },
+        changed: async () => {
+            const decls = rows.map((r) => r.decl)
+            if (decls.length === 0) return []
+            const ledger = Ledger.open(d.root, decls, { cliEntry: gateBinary(), read: true })
+            const out: string[] = []
+            for (const r of rows) {
+                const c = planCheckOf(r)
+                if (!c.onChange) continue
+                if (isForever(r)) {
+                    // only an edited declaration: a probe that could not answer
+                    // (gh down) must not run again at every save
+                    if (moved.has(c.id) && unknown.has(c.id)) out.push(c.id)
+                    moved.delete(c.id)
+                    continue
+                }
+                const k = ledger.layer.keyFor(c.id)
+                if (k.key == null) {
+                    out.push(c.id)
+                    continue
+                }
+                const before = seen.get(c.id)
+                seen.set(c.id, k.key)
+                if (ledger.replay(c.id) != null) continue
+                if (k.population === 'content' && before === k.key) continue
+                out.push(c.id)
+            }
+            return out
+        },
+        pending: async () => {
+            const since = d.record === '' ? null : lastStarted(d.record)
+            return since != null && (await movedSince(d.root, since))
+        },
+        run: async (ids, why) => {
+            const byId = new Map(rows.map((r) => [r.decl.id, r]))
+            const gate = ids.filter((id) => byId.get(id)?.gate === true)
+            const health = ids.filter((id) => byId.get(id)?.gate !== true)
+            let code = 0
+            if (gate.length > 0) code = Math.max(code, await d.run(gate, { gate: true }, why))
+            if (health.length > 0) code = Math.max(code, await d.run(health, { gate: false }, why))
+            return code
+        },
+    }
+}

package/src/problems/problem-line.ts

@@ -24,7 +24,7 @@ export type Problem = {
 }
 
 export const FRAME_BEGIN = 'shipkit problems: begin'
-const FRAME_END_HEAD = 'shipkit problems: end'
+export const FRAME_END_HEAD = 'shipkit problems: end'
 
 export function frameEnd(problems: Problem[]): string {
     const errors = problems.filter((p) => p.severity === 'error').length

package/src/release/run-release.ts

@@ -27,8 +27,11 @@ export type ReleaseConfig = {
     tag?: string
     /** the ROOT unit's versioned changelog (default 'CHANGELOG.md') */
     changelog?: string
-    /** publish the ROOT unit to npm. Default: its package.json is not private.
-     *  A private package NEVER publishes, whatever this says. */
+    /** publish the ROOT unit to npm, declared and never inferred: a root whose
+     *  package.json is not private refuses to release until this says true or
+     *  false. A private package NEVER publishes, whatever this says. True makes
+     *  the root package.json a public contract. What each check does with it:
+     *  wiki/build/shipkit/built-in-checks.md */
     npm?: boolean
     /** argv printing an npm auth token on stdout, as in a secret-manager read.
      *  Absent = rely on ambient npm auth. Never put a token in config.
@@ -122,6 +125,10 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         // real repositories) are exactly the ones a publish must not be wrong
         // about. Publishing behind a partial suite is a green nobody measured.
         tests: 'full',
+        // a release log is read once and kept as evidence: the tier it asked
+        // for, the cache reads it refused and the units it left to their own
+        // release are all part of what it proves
+        verbose: true,
         // a check that cannot block cannot change the outcome, so a release
         // never probes the world: publishing a lib does not depend on whether
         // a DNS provider answers, and asking spends an API call per publish.