rvlib-shipkit 1.1.0 → 1.2.0

package/src/plan/cadence.ts

@@ -0,0 +1,237 @@
+// WHEN A CHECK RUNS, as a check declares it: `every` (a span, a range, or a
+// pure function of its last result), `cron`, and `whenInactive`. Pure: no
+// clock, no disk, so the planner (planner.ts) and every test read the same
+// answer from the same facts.
+//
+// the one constraint a reader breaks first: a lambda must stay pure. It is
+// called on every plan look, and one that throws is an error row, never a
+// silence: the check falls back to running on change only.
+import { parseDuration } from '../core/wire.ts'
+
+export type LastStatus = 'pass' | 'warn' | 'fail' | 'skip'
+
+/** a check's last result on record: its status, when it finished, and how
+ *  many runs in a row ended on that same status */
+export type LastResult = { status: LastStatus; at: number; streak: number }
+
+/** what a lambda sees beside the last result */
+export type CadenceState = { active: boolean }
+
+/** a span (`'24h'`), a range (`['10h', '12h']`), a cron expression
+ *  (`'0 9 * * 1'`), or null for on change only */
+export type EveryValue = string | readonly [string, string] | null
+
+export type Every = EveryValue | ((last: LastResult | null, s: CadenceState) => EveryValue)
+
+export type WhenInactive = 'run' | 'wait'
+
+export type WhenInactiveDecl = WhenInactive | ((last: LastResult | null, s: CadenceState) => WhenInactive)
+
+/** what a check declared about its timing, as the planner reads it */
+export type PlanDecl = { every?: Every; cron?: string; whenInactive?: WhenInactiveDecl }
+
+/** one resolved cadence */
+export type Cadence =
+    | { kind: 'change' }
+    | { kind: 'every'; ms: number }
+    | { kind: 'range'; min: number; max: number; point: number }
+    | { kind: 'cron'; expr: string; cron: Cron }
+
+/** the cadence a check runs on, and the words saying what chose it */
+export type Resolved = { cadence: Cadence; rule: string; error: string | null }
+
+const isCron = (s: string): boolean => s.trim().split(/\s+/).length === 5
+
+/** a stable fraction in [0, 1) for one repo and check: the same pair always
+ *  lands on the same point of its range, and pairs spread over it */
+export function stablePoint(seed: string): number {
+    let h = 0x811c9dc5
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i)
+        h = Math.imul(h, 0x01000193) >>> 0
+    }
+    return h / 0x1_0000_0000
+}
+
+/** one value to a cadence, or the reason it is not one */
+export function cadenceOf(v: EveryValue, seed: string): Cadence | string {
+    if (v == null) return { kind: 'change' }
+    if (Array.isArray(v)) {
+        if (v.length !== 2) return `a range is two spans, as in ['10h', '12h']`
+        try {
+            const min = parseDuration(v[0]!)
+            const max = parseDuration(v[1]!)
+            if (!(max > min) || min <= 0) return `range ${JSON.stringify(v)}: the second span must be longer than the first, and both above zero`
+            return { kind: 'range', min, max, point: Math.round(min + stablePoint(seed) * (max - min)) }
+        } catch (e) {
+            return (e as Error).message
+        }
+    }
+    if (typeof v !== 'string') return `every takes a span, a range, a cron expression or null, got ${typeof v}`
+    if (isCron(v)) {
+        const c = parseCron(v)
+        return typeof c === 'string' ? c : { kind: 'cron', expr: v.trim(), cron: c }
+    }
+    try {
+        const ms = parseDuration(v)
+        if (ms <= 0) return `every '${v}' must be above zero`
+        return { kind: 'every', ms }
+    } catch (e) {
+        return (e as Error).message
+    }
+}
+
+/** the problem with a static declaration, or null. A lambda is judged when it
+ *  runs, so it passes here */
+export function planDeclProblem(d: PlanDecl): string | null {
+    if (d.every != null && d.cron != null) return 'every and cron contradict each other: declare one'
+    if (d.every != null && typeof d.every !== 'function') {
+        const c = cadenceOf(d.every, '')
+        if (typeof c === 'string') return `every: ${c}`
+    }
+    if (d.cron != null) {
+        if (typeof d.cron !== 'string' || !isCron(d.cron)) return `cron takes five fields, as in '0 9 * * 1'`
+        const c = parseCron(d.cron)
+        if (typeof c === 'string') return `cron: ${c}`
+    }
+    if (d.whenInactive != null && typeof d.whenInactive !== 'function' && d.whenInactive !== 'run' && d.whenInactive !== 'wait')
+        return `whenInactive takes 'run', 'wait' or a function returning one`
+    return null
+}
+
+const words = (v: EveryValue): string => (v == null ? 'on change' : Array.isArray(v) ? `every ${v[0]}..${v[1]}` : isCron(v as string) ? `cron ${v}` : `every ${v}`)
+
+const stateWords = (last: LastResult | null, s: CadenceState): string =>
+    `${last == null ? 'never ran' : `last ${last.status} x${last.streak}`}, ${s.active ? 'active' : 'inactive'}`
+
+/** the cadence one check runs on now. `fallback` is what applies when the
+ *  check declared nothing: its ttl, or the daily default */
+export function resolveCadence(d: PlanDecl, fallback: { value: EveryValue; why: string }, last: LastResult | null, s: CadenceState, seed: string): Resolved {
+    let value: EveryValue
+    let rule: string
+    if (d.cron != null) {
+        value = d.cron
+        rule = `cron ${d.cron}`
+    } else if (typeof d.every === 'function') {
+        try {
+            value = d.every(last, s)
+        } catch (e) {
+            return { cadence: { kind: 'change' }, rule: `every lambda threw (${stateWords(last, s)}), on change only`, error: `every lambda threw: ${(e as Error).message}` }
+        }
+        rule = `every lambda returned ${JSON.stringify(value)} (${stateWords(last, s)})`
+    } else if (d.every !== undefined) {
+        value = d.every
+        rule = words(value)
+    } else {
+        value = fallback.value
+        rule = `${words(value)} (${fallback.why})`
+    }
+    const c = cadenceOf(value, seed)
+    if (typeof c === 'string') return { cadence: { kind: 'change' }, rule: `${rule}, on change only`, error: c }
+    return { cadence: c, rule, error: null }
+}
+
+/** what the check does while its repo is inactive, and the error when a
+ *  lambda threw (then it waits) */
+export function resolveWhenInactive(d: PlanDecl, last: LastResult | null, s: CadenceState): { value: WhenInactive; rule: string; error: string | null } {
+    const w = d.whenInactive
+    if (w == null) return { value: 'wait', rule: 'whenInactive wait (default)', error: null }
+    if (typeof w !== 'function') return { value: w, rule: `whenInactive ${w}`, error: null }
+    try {
+        const v = w(last, s)
+        if (v !== 'run' && v !== 'wait') return { value: 'wait', rule: `whenInactive lambda returned ${JSON.stringify(v)}, read as wait`, error: `whenInactive lambda returned ${JSON.stringify(v)}: it takes 'run' or 'wait'` }
+        return { value: v, rule: `whenInactive lambda returned '${v}' (${stateWords(last, s)})`, error: null }
+    } catch (e) {
+        return { value: 'wait', rule: 'whenInactive lambda threw, read as wait', error: `whenInactive lambda threw: ${(e as Error).message}` }
+    }
+}
+
+/** when a cadence is next due after a run at `last`, null for on change
+ *  only. A check that never ran is due now, except a cron one, which waits
+ *  for its next slot */
+export function nextDue(c: Cadence, last: number | null, now: number): number | null {
+    if (c.kind === 'change') return null
+    if (c.kind === 'every') return last == null ? now : last + c.ms
+    if (c.kind === 'range') return last == null ? now : last + c.point
+    return cronNext(c.cron, last ?? now)
+}
+
+// ── a five field cron: minute hour day-of-month month day-of-week ─────────
+
+export type Cron = { min: Set<number>; hour: Set<number>; dom: Set<number>; mon: Set<number>; dow: Set<number>; domAny: boolean; dowAny: boolean }
+
+const FIELDS: [string, number, number][] = [['minute', 0, 59], ['hour', 0, 23], ['day of month', 1, 31], ['month', 1, 12], ['day of week', 0, 7]]
+
+function field(raw: string, name: string, lo: number, hi: number): Set<number> | string {
+    const out = new Set<number>()
+    for (const part of raw.split(',')) {
+        const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part)
+        if (m == null) return `${name} '${part}' is not a number, a range, * or a step`
+        const step = m[2] == null ? 1 : Number(m[2])
+        if (step < 1) return `${name} step must be at least 1`
+        let a = lo
+        let b = hi
+        if (m[1] !== '*') {
+            const [x, y] = m[1]!.split('-').map(Number)
+            a = x!
+            b = y ?? (m[2] == null ? x! : hi)
+        }
+        if (a < lo || b > hi || a > b) return `${name} '${part}' is outside ${lo}..${hi}`
+        for (let v = a; v <= b; v += step) out.add(v)
+    }
+    return out
+}
+
+export function parseCron(expr: string): Cron | string {
+    const parts = expr.trim().split(/\s+/)
+    if (parts.length !== 5) return `cron takes five fields (minute hour day month weekday), got ${parts.length}`
+    const sets: Set<number>[] = []
+    for (let i = 0; i < 5; i++) {
+        const [name, lo, hi] = FIELDS[i]!
+        const s = field(parts[i]!, name, lo, hi)
+        if (typeof s === 'string') return s
+        sets.push(s)
+    }
+    const dow = sets[4]!
+    if (dow.has(7)) dow.add(0)
+    return { min: sets[0]!, hour: sets[1]!, dom: sets[2]!, mon: sets[3]!, dow, domAny: parts[2] === '*', dowAny: parts[4] === '*' }
+}
+
+/** the first minute strictly after `after` that the cron matches, in local
+ *  time. Walks months, days and hours before minutes, so a yearly slot costs
+ *  a few hundred steps */
+export function cronNext(c: Cron, after: number): number {
+    const d = new Date(after)
+    d.setSeconds(0, 0)
+    d.setMinutes(d.getMinutes() + 1)
+    const dayOk = (x: Date): boolean => {
+        const dom = c.dom.has(x.getDate())
+        const dow = c.dow.has(x.getDay())
+        // the classic rule: both restricted means either one matches
+        if (c.domAny) return dow
+        if (c.dowAny) return dom
+        return dom || dow
+    }
+    for (let guard = 0; guard < 100_000; guard++) {
+        if (!c.mon.has(d.getMonth() + 1)) {
+            d.setMonth(d.getMonth() + 1, 1)
+            d.setHours(0, 0, 0, 0)
+            continue
+        }
+        if (!dayOk(d)) {
+            d.setDate(d.getDate() + 1)
+            d.setHours(0, 0, 0, 0)
+            continue
+        }
+        if (!c.hour.has(d.getHours())) {
+            d.setHours(d.getHours() + 1, 0, 0, 0)
+            continue
+        }
+        if (!c.min.has(d.getMinutes())) {
+            d.setMinutes(d.getMinutes() + 1, 0, 0)
+            continue
+        }
+        return d.getTime()
+    }
+    throw new Error('cron has no matching minute within the search window')
+}

package/src/plan/planner.ts

@@ -0,0 +1,303 @@
+// 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.
+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
+    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>
+}
+
+export type PlanState = 'running' | 'due' | 'late' | 'next' | 'idle'
+
+export type PlanRow = {
+    repo: string
+    check: string
+    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 save burst must be quiet before the plan asks what it moved */
+export const QUIET_MS = 250
+
+/** 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
+    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
+    /** 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 started: what was overdue then is spread, never fired at once */
+    private readonly bootAt: number
+
+    constructor(private o: { now?: () => number; timers?: PlanTimers; quietMs?: number; onError?: (repo: string, e: Error) => void } = {}) {
+        this.now = o.now ?? Date.now
+        this.bootAt = this.now()
+        this.timers = o.timers ?? realTimers
+        this.quietMs = o.quietMs ?? QUIET_MS
+    }
+
+    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, detecting: null, again: false, error: null }
+        this.repos.set(src.repo, r)
+        await this.reload(src.repo)
+    }
+
+    /** 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)
+    }
+
+    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` */
+    touched(repo: string): void {
+        const r = this.repos.get(repo)
+        if (r == null) return
+        if (r.timer != null) this.timers.clear(r.timer)
+        r.timer = this.timers.set(() => {
+            r.timer = 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, 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) return { ...base, state: 'due', reason: 'changed', dueAt: m.changedAt }
+        const lastAt = Math.max(last?.at ?? -Infinity, m.attemptAt ?? -Infinity)
+        const raw = 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! }))
+    }
+
+    /** 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 {
+        if (this.running != null) return null
+        const due = this.rows().filter((x) => x.state === 'due')
+        if (due.length === 0) return 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! }
+    }
+
+    /** 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,100 @@
+// 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 { readLastResults } from '../ledger/run-log.ts'
+import { gateBinary } from '../ledger/toolchain-identity.ts'
+import { populationOf } from '../problems/problem-line.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
+    if (row.optIn) return false
+    return !(row.build && row.when.at === 'health')
+}
+
+/** one inventory row as a plan check. A world check keeps its ttl as its
+ *  cadence; a build step waits for a save; any other check with no cadence
+ *  runs about once a day, at its own stable point of a 20h to 28h range, so
+ *  checks never fire together */
+/** a check that declares no cadence runs about once a day, never in step */
+const DEFAULT_EVERY: [string, string] = ['20h', '28h']
+
+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 != null ? { value: ttl, why: 'its ttl' } : row.build ? { value: null, why: 'a build step' } : { value: DEFAULT_EVERY, why: 'the default range' }
+    return {
+        id: row.decl.id,
+        plan: row.plan ?? {},
+        onChange: pop !== 'world' && (keyed || row.gate),
+        fallback,
+    }
+}
+
+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>()
+    return {
+        repo: d.repo,
+        checks: async () => {
+            rows = (await gateInventory(d.root, d.config(), { tier: 'quick' })).filter(plannable)
+            return rows.map(planCheckOf)
+        },
+        last: () => (d.record === '' ? {} : readLastResults(d.record)),
+        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
+                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
+        },
+        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