rvlib-shipkit 0.38.0 → 1.0.0

package/src/ledger/live-timeline.ts

@@ -0,0 +1,97 @@
+// THE LIVE TIMELINE: what the strip under the hub header draws. The same
+// shape the runs page reads (ledger/run-timeline.ts), cut to a rolling
+// window that ends now, with the runs still going in it, plus one collapsed
+// lane per OTHER repo that has something in flight.
+//
+// Pure, on a clock the caller passes, so every rule is pinned on a fake one.
+// A run still in the live table is drawn from there, its running checks
+// ending at now. A run already flushed is drawn from the run record. The
+// drawing and the lanes are the page's (hub-app/timeline-geometry.ts), so a
+// run looks the same in both places.
+import { liveRowsOf, type LiveRow, type LiveWait } from './live-runs.ts'
+import type { InvocationRow, RunRow } from './run-log.ts'
+import { invocationsOf, type TimelineBar, type TimelineInvocation } from './run-timeline.ts'
+
+/** how far back the server looks: the unfolded strip's widest window */
+export const LIVE_HISTORY_MS = 600_000
+
+/** another repo with something in flight, collapsed to one lane */
+export type RepoLane = { repo: string; label: string; by: string; start: number; running: number; checks: string[] }
+
+/** a run in flight here, for the header's one line */
+export type RunSummary = { runId: string; label: string; by: string; done: number; total: number; reds: number }
+
+export type LiveView = {
+    /** the server clock the view was shaped at */
+    now: number
+    historyMs: number
+    /** the runner's cap, and how many of its slots this repo has busy */
+    cap: number
+    busy: number
+    /** every invocation touching the window, newest first, the ones in flight
+     *  marked running */
+    invocations: TimelineInvocation[]
+    repos: RepoLane[]
+    runs: RunSummary[]
+    /** of the newest run in flight: checks ready for a slot, and checks
+     *  waiting on another one */
+    queued: number
+    blocked: LiveWait[]
+}
+
+/** a live row as the page's invocation: its finished checks where they
+ *  were, its running ones ending now */
+export function invocationOfLive(r: LiveRow, now: number): TimelineInvocation {
+    const bars: TimelineBar[] = [
+        ...r.finished.map((f) => ({ id: f.id, start: f.start, end: f.end, ms: f.end - f.start, status: f.status, replayed: f.replayed })),
+        ...r.running.map((c) => ({ id: c.id, start: c.started, end: now, ms: now - c.started, status: 'pass' as const, replayed: false, running: true })),
+    ].sort((a, b) => a.start - b.start || a.id.localeCompare(b.id))
+    const ended = r.ended ?? now
+    return {
+        runId: r.runId, kind: r.kind, by: r.by, label: r.label, started: r.started, ended, wallMs: ended - r.started, bars,
+        reds: r.reds, replays: bars.filter((b) => b.replayed).length, running: r.ended == null,
+    }
+}
+
+/** another repo, collapsed: one lane while it has anything running, from
+ *  its earliest running check to now. null when nothing runs there */
+export function repoLane(repo: string, rows: LiveRow[], now: number, alive?: (pid: number) => boolean): RepoLane | null {
+    const going = liveRowsOf(rows, now, alive).filter((r) => r.ended == null && r.running.length > 0)
+    if (going.length === 0) return null
+    const running = going.flatMap((r) => r.running)
+    return { repo, label: going[0]!.label, by: going[0]!.by, start: Math.min(...running.map((c) => c.started)), running: running.length, checks: running.map((c) => c.id) }
+}
+
+export function shapeLive(o: {
+    now: number
+    cap: number
+    live: LiveRow[]
+    /** the run record's rows that finished inside the window */
+    runs: RunRow[]
+    invocations: InvocationRow[]
+    others?: { repo: string; rows: LiveRow[] }[]
+    alive?: (pid: number) => boolean
+    historyMs?: number
+}): LiveView {
+    const historyMs = o.historyMs ?? LIVE_HISTORY_MS
+    const from = o.now - historyMs
+    const rows = liveRowsOf(o.live, o.now, o.alive)
+    const inLive = new Set(rows.map((r) => r.runId))
+    const flushed = invocationsOf(o.runs.filter((r) => !inLive.has(r.runId)), o.invocations)
+    const invocations = [...rows.map((r) => invocationOfLive(r, o.now)), ...flushed]
+        .filter((i) => i.ended >= from)
+        .sort((a, b) => b.started - a.started)
+    const inFlight = rows.filter((r) => r.ended == null)
+    const newest = inFlight[0]
+    return {
+        now: o.now,
+        historyMs,
+        cap: o.cap,
+        busy: inFlight.reduce((a, r) => a + r.running.length, 0),
+        invocations,
+        repos: (o.others ?? []).map((x) => repoLane(x.repo, x.rows, o.now, o.alive)).filter((x) => x != null).sort((a, b) => a.repo.localeCompare(b.repo)),
+        runs: inFlight.map((r) => ({ runId: r.runId, label: r.label, by: r.by, done: r.done, total: r.total, reds: r.reds })),
+        queued: newest?.waiting.filter((w) => w.deps.length === 0).length ?? 0,
+        blocked: newest?.waiting.filter((w) => w.deps.length > 0) ?? [],
+    }
+}

package/src/ledger/repo-view.ts

@@ -0,0 +1,73 @@
+// THE FILE LIST a check context lists from, and the one a cached answer's
+// listings are re-checked against. It is what git sees: tracked files plus
+// untracked ones no ignore rule hides, read off the same scratch index scan the
+// content keys use (ledger/git-scan.ts), so a gitignored build dir or a
+// worktree parked inside the repo never enters a listing.
+//
+// Built once per run and shared: `c.list` in every check and the ledger's
+// replay check read the same snapshot, so a check never lists one tree and is
+// validated against another inside one run.
+import { relative } from 'path'
+import { gitBin } from '../core/git-bin.ts'
+import { GitScanError, scanPaths, WHOLE_TREE, type ScanResult } from './git-scan.ts'
+
+export class RepoView {
+    private constructor(
+        /** every file, repo-relative, sorted */
+        readonly files: readonly string[],
+        /** why this list did not come from git, null when it did. A listing
+         *  from a disk walk is fine to answer a check with, and never good
+         *  enough to validate a cached answer against */
+        readonly fallback: string | null,
+        /** the scan it was read off, handed to the next open as its prior */
+        readonly scan: ScanResult | null = null,
+    ) {}
+
+    /** `prior`: an earlier view of the same root in this run. Its scan
+     *  answers git's ignore question again, and the tree is still staged and
+     *  hashed fresh, so the list is today's */
+    static open(root: string, prior?: RepoView | null): RepoView {
+        try {
+            const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined)
+            const tree = scan.oidByPath.get(WHOLE_TREE)
+            if (tree == null) throw new GitScanError('git could not name the work tree')
+            return new RepoView(filesOf(root, tree), null, scan)
+        } catch (e) {
+            return new RepoView(walk(root), e instanceof Error ? e.message : String(e))
+        }
+    }
+
+    /** the files matching `glob`, sorted */
+    list(glob: string): string[] {
+        const g = new Bun.Glob(glob)
+        return this.files.filter((f) => g.match(f))
+    }
+}
+
+/** a tree id names its content, so its file list is a pure function of the
+ *  id and one listing serves every view of that tree */
+const listed = new Map<string, string[]>()
+const LISTED_MAX = 64
+
+function filesOf(root: string, tree: string): string[] {
+    const hit = listed.get(tree)
+    if (hit != null) return hit
+    const p = Bun.spawnSync([gitBin(), 'ls-tree', '-r', '-z', '--name-only', tree], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    if (p.exitCode !== 0) throw new GitScanError(`git ls-tree exited ${p.exitCode}: ${p.stderr.toString().trim()}`)
+    const files = p.stdout.toString().split('\0').filter((f) => f !== '').sort()
+    if (listed.size >= LISTED_MAX) listed.delete(listed.keys().next().value!)
+    listed.set(tree, files)
+    return files
+}
+
+/** no git: every file under the root, installs and dot dirs left out */
+function walk(root: string): string[] {
+    try {
+        return [...new Bun.Glob('**/*').scanSync({ cwd: root, onlyFiles: true, dot: false })]
+            .map((f) => relative('.', f).replace(/\\/g, '/'))
+            .filter((f) => !f.split('/').includes('node_modules'))
+            .sort()
+    } catch {
+        return []
+    }
+}

package/src/ledger/run-log.ts

@@ -0,0 +1,448 @@
+// THE RUN RECORD — what every check cost, on every run, red runs included.
+//
+// The ledger stores a GREEN only (ledger/ledger.ts rule 6), so an average
+// built from it is an average of the runs that passed, and the slowest run of
+// a check is precisely the one it cannot see. This is the record beside it: one
+// row per check per run, written after the gate has finished with that check,
+// plus the last wire lines each check printed so a check's own page can say WHY
+// it is red without re-running it.
+//
+// It lives in ONE sqlite db (ledger/db.ts owns the file and the schema), and
+// the three properties it has to keep are unchanged by that:
+//  1. ONE WRITE PER RUN, in one immediate transaction, so several gates in one
+//     checkout interleave runs and never rows.
+//  2. NEVER READ BY THE GATE. Nothing here can change what a check does or what
+//     it replays: a record that cannot be written costs a run one warn line,
+//     never a verdict, which is what keeps a reporting surface from becoming a
+//     correctness surface.
+//  3. SWEPT BY AGE, like the store beside it, because a run knows nothing
+//     about the checks it did not run. The sweep is a DELETE now rather than a
+//     rewrite of the whole file, so a row written while it runs is kept.
+import { Database } from 'bun:sqlite'
+import { existsSync } from 'fs'
+import type { Line } from '../core/wire.ts'
+import { dbPath, INSERT_RUN, openDb, UPSERT_INVOCATION, UPSERT_LAST, UPSERT_LIVE } from './db.ts'
+import { LIVE_BEAT_MS, liveRowDead, type LiveRow, type LiveState } from './live-runs.ts'
+import { KEEP_MS } from './store.ts'
+
+export type RunStatus = 'pass' | 'warn' | 'fail' | 'skip'
+
+/** one check, one run. `ms` is what it MEASURED: a replay measured nothing and
+ *  says 0, so the two can never be averaged together by accident. */
+export type RunRow = {
+    runId: string
+    id: string
+    /** epoch ms, when the check finished */
+    at: number
+    ms: number
+    status: RunStatus
+    replayed: boolean
+    /** the run asked for the full test tier (its invocation says `--full`).
+     *  Absent on a row written without an invocation */
+    full?: boolean
+}
+
+/** where the record lives. Both questions it answers, the timings and the last
+ *  lines, are tables of that one file, so there is one name for it. */
+export const runsPath = dbPath
+
+/** what wrote a run: the command (`ci` answers the gate's question, `check`
+ *  the health pass's), who started it (a terminal, the hub's buttons, the
+ *  hub's daily timer), and whether it was narrowed to named checks. A
+ *  narrowed health pass is not a health pass: the scheduler reads the last
+ *  WHOLE one. */
+export type InvocationKind = 'ci' | 'check'
+export type InvokedBy = 'cli' | 'hub' | 'schedule'
+export type Invocation = { kind: InvocationKind; label: string; by: InvokedBy; narrowed: boolean }
+
+/** one invocation as the record holds it. `started` is when its record was
+ *  opened, `ended` when it was written, so `ended - started` is its wall
+ *  time as the runner saw it. */
+export type InvocationRow = Invocation & { runId: string; started: number; ended: number }
+
+export type LastLine = { at: number; status: RunStatus; ms: number; lines: Line[] }
+
+/** a check's page is a card, not a log dump, and one runaway check must not
+ *  make this table unbounded */
+const MAX_LINES = 40
+const MAX_TEXT = 400
+
+/** how long a live write waits on another writer before it is dropped. The
+ *  runner calls it from its loop, and a strip is never worth stalling a gate:
+ *  the next turn of the loop writes the state again */
+const LIVE_BUSY_MS = 50
+
+/** a run's own id: every row of one gate carries it, so "the gate took 21s and
+ *  here is the breakdown" is reconstructable, which it never was from the
+ *  store (nothing there links a check to its siblings). */
+export const newRunId = (now: number): string => `${now.toString(36)}-${process.pid.toString(36)}`
+
+/** a repeating timer, and the call that stops it */
+export type Every = (fn: () => void, ms: number) => () => void
+
+/** unref'd: a beat must never be the thing that keeps a process alive */
+const everyReal: Every = (fn, ms) => {
+    const t = setInterval(fn, ms)
+    t.unref?.()
+    return () => clearInterval(t)
+}
+
+export class RunLog {
+    private rows: RunRow[] = []
+    private last: Record<string, LastLine> = {}
+    /** the live state last written, so an unchanged turn writes nothing */
+    private liveSent = ''
+    /** the handle live writes go through, closed by the flush */
+    private liveDb: Database | null = null
+    /** stops the beat. null while no beat runs */
+    private stopBeat: (() => void) | null = null
+
+    readonly started: number
+
+    private constructor(
+        readonly path: string,
+        readonly runId: string,
+        private readonly now: () => number,
+        private readonly busyMs?: number,
+        readonly invocation: Invocation | null = null,
+        private readonly every: Every = everyReal,
+    ) {
+        this.started = now()
+    }
+
+    /** `path` is resolved once: it shells out to git, and a gate asks for the
+     *  record after every check. A location that cannot be resolved at all (no
+     *  such dir, no git) yields a record that collects rows and writes
+     *  nothing, because a dashboard's history is never worth a thrown gate. */
+    static open(root: string, o?: { runId?: string; now?: () => number; busyMs?: number; invocation?: Invocation; every?: Every }): RunLog {
+        const now = o?.now ?? Date.now
+        let path = ''
+        try { path = runsPath(root) } catch { path = '' }
+        return new RunLog(path, o?.runId ?? newRunId(now()), now, o?.busyMs, o?.invocation ?? null, o?.every)
+    }
+
+    add(u: { id: string; status: RunStatus; ms: number; replayed?: boolean; at?: number; lines?: Line[] }): void {
+        const at = u.at ?? this.now()
+        // a replay measured nothing, and writing what the ORIGINAL cost would
+        // count one measurement once per run that replayed it
+        const ms = u.replayed === true ? 0 : Math.round(u.ms)
+        if (u.lines != null)
+            this.last[u.id] = { at, status: u.status, ms, lines: u.lines.slice(0, MAX_LINES).map((l) => ({ ...l, text: l.text.slice(0, MAX_TEXT) })) }
+        this.rows.push({ runId: this.runId, id: u.id, at, ms, status: u.status, replayed: u.replayed === true })
+    }
+
+    get pending(): number {
+        return this.rows.length
+    }
+
+    /** what the runner is doing right now, for every surface that shows a run
+     *  in flight: one row per run, rewritten in place. Only a run that knows
+     *  what it is (an invocation) has a row, and a write that cannot land is
+     *  dropped, because the next turn of the runner's loop writes it again.
+     *  The row goes in the flush, in the transaction that writes the run's
+     *  rows, so a finished check is never missing from both. While the run
+     *  is in flight a beat stamps the row, so a reader can tell a long check
+     *  from a writer that is gone (live-runs.ts LIVE_STALE_MS) */
+    live(state: LiveState): void {
+        const inv = this.invocation
+        if (this.path === '' || inv == null) return
+        if (state.ended != null) this.quiet()
+        else if (this.stopBeat == null) this.stopBeat = this.every(() => this.beat(), LIVE_BEAT_MS)
+        const json = JSON.stringify(state)
+        if (json === this.liveSent) return
+        // one handle for the whole run: opening the file is most of what a
+        // write costs, and the runner writes on every turn of its loop
+        if (this.liveDb == null) this.liveDb = openDb(this.path, { busyMs: LIVE_BUSY_MS })?.db ?? null
+        if (this.liveDb == null) return
+        try {
+            this.liveDb.query(UPSERT_LIVE).run(this.runId, inv.kind, inv.label, inv.by, process.pid, this.started, this.now(), json)
+            this.liveSent = json
+        } catch { /* the next turn writes it again */ }
+    }
+
+    /** the row's stamp, moved on its own: nothing changed, the run is alive */
+    private beat(): void {
+        if (this.liveDb == null || this.liveSent === '') return
+        try {
+            this.liveDb.query('update live set updated = ? where run_id = ?').run(this.now(), this.runId)
+        } catch { /* the next beat stamps it again */ }
+    }
+
+    private quiet(): void {
+        this.stopBeat?.()
+        this.stopBeat = null
+    }
+
+    /** one write for the whole run, in one transaction: the rows, the last
+     *  lines MERGED per check (a narrowed run knows about one check and must not
+     *  erase the other sixty-nine), and the age sweep. Returns what the caller
+     *  prints: a one time migration note, and one warn when the record could
+     *  not be written, because a history that vanishes silently reads as a
+     *  repo nobody ever gated. */
+    flush(): Line[] {
+        const rows = this.rows
+        const last = Object.entries(this.last)
+        this.rows = []
+        this.last = {}
+        const hadLive = this.liveSent !== ''
+        this.quiet()
+        this.liveSent = ''
+        try { this.liveDb?.close() } catch { /* already gone */ }
+        this.liveDb = null
+        if (this.path === '' || (rows.length === 0 && last.length === 0 && !hadLive)) return []
+        const opened = openDb(this.path, { busyMs: this.busyMs })
+        if (opened == null) return unwritable(this.path)
+        try {
+            const insert = opened.db.query(INSERT_RUN)
+            const upsert = opened.db.query(UPSERT_LAST)
+            const invoked = opened.db.query(UPSERT_INVOCATION)
+            const now = this.now()
+            const cutoff = now - KEEP_MS
+            const inv = this.invocation
+            opened.db.transaction(() => {
+                for (const r of rows) insert.run(r.runId, r.id, r.at, r.ms, r.status, r.replayed ? 1 : 0)
+                for (const [check, l] of last) upsert.run(check, l.at, l.status, l.ms, JSON.stringify(l.lines))
+                if (inv != null) invoked.run(this.runId, inv.kind, inv.label, inv.by, inv.narrowed ? 1 : 0, this.started, now)
+                if (hadLive) opened.db.query('delete from live where run_id = ?').run(this.runId)
+                sweepAll(opened.db, now, cutoff)
+            }).immediate()
+            return []
+        } catch {
+            return unwritable(this.path)
+        } finally {
+            try { opened.db.close() } catch { /* already gone */ }
+        }
+    }
+}
+
+const unwritable = (path: string): Line[] => [
+    { kind: 'warn', text: `run record not written, so this run is missing from the timings (${path})` },
+    { kind: 'fix-warn', text: `nothing to do for the verdict above. A record that stays unwritable is one file: rm ${path}` },
+]
+
+/** the age sweep, over every table that grows per run. A live row nobody
+ *  writes anymore is a run lost mid way, and it goes here too */
+const sweepAll = (db: Database, now: number, cutoff: number): void => {
+    sweepDeadLive(db, now)
+    db.query('delete from runs where at < ?').run(cutoff)
+    db.query('delete from invocations where ended < ?').run(cutoff)
+    db.query('delete from suites where at < ?').run(cutoff)
+    db.query('delete from suite_runs where at < ?').run(cutoff)
+}
+
+/** every invocation on record that ended at or after `since`, oldest
+ *  first. An unreadable db is none. */
+export function readInvocations(path: string, since = 0): InvocationRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        const rows = opened.db.query('select run_id as runId, kind, label, by, narrowed, started, ended from invocations where ended >= ? order by started asc').all(since) as {
+            runId: string; kind: string; label: string; by: string; narrowed: number; started: number; ended: number
+        }[]
+        return rows.map((r): InvocationRow => ({
+            runId: String(r.runId), kind: r.kind === 'ci' ? 'ci' : 'check', label: String(r.label),
+            by: r.by === 'hub' || r.by === 'schedule' ? r.by : 'cli', narrowed: Number(r.narrowed) === 1,
+            started: Number(r.started), ended: Number(r.ended),
+        }))
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+type RawLive = { runId: string; kind: string; label: string; by: string; pid: number; started: number; updated: number; state: string }
+
+const LIVE_SELECT = 'select run_id as runId, kind, label, by, pid, started, updated, state from live'
+
+const liveRowOf = (r: RawLive): LiveRow | null => {
+    let st: Partial<LiveState>
+    try { st = JSON.parse(r.state) as Partial<LiveState> } catch { return null }
+    return {
+        cap: Number(st.cap ?? 0), total: Number(st.total ?? 0), done: Number(st.done ?? 0), reds: Number(st.reds ?? 0),
+        running: st.running ?? [], waiting: st.waiting ?? [], finished: st.finished ?? [], ended: st.ended ?? null,
+        runId: String(r.runId), kind: r.kind === 'ci' ? 'ci' : 'check', label: String(r.label),
+        // a starter this build does not name yet stays what it said, so a
+        // newer runner's word reaches the page rather than a wrong one
+        by: String(r.by) as InvokedBy, pid: Number(r.pid), started: Number(r.started), updated: Number(r.updated),
+    }
+}
+
+/** every live row on record, as written. `liveRowsOf` says which are still
+ *  worth reading. An unreadable db is none: a strip with nothing on it
+ *  beats a crash */
+export function readLive(path: string): LiveRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        return (opened.db.query(LIVE_SELECT).all() as RawLive[]).map(liveRowOf).filter((r) => r != null)
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+/** the live rows of ANOTHER repo's record, strictly read only: no schema
+ *  migration, no journal switch, nothing written. A record from before the
+ *  live table, or one that cannot be opened, is none */
+export function readLiveReadonly(path: string): LiveRow[] {
+    if (!existsSync(path)) return []
+    let db: Database | null = null
+    try {
+        db = new Database(path, { readonly: true })
+        db.exec('pragma busy_timeout = 50')
+        if (db.query("select 1 from sqlite_master where type = 'table' and name = 'live'").get() == null) return []
+        return (db.query(LIVE_SELECT).all() as RawLive[]).map(liveRowOf).filter((r) => r != null)
+    } catch {
+        return []
+    } finally {
+        try { db?.close() } catch { /* already gone */ }
+    }
+}
+
+/** every check's last outcome in a record, read only, for a hub that shows
+ *  ANOTHER repo's gate: `[]` when the record or the table is missing */
+export function readLastStatusReadonly(path: string): { id: string; status: string }[] {
+    if (!existsSync(path)) return []
+    let db: Database | null = null
+    try {
+        db = new Database(path, { readonly: true })
+        db.exec('pragma busy_timeout = 50')
+        if (db.query("select 1 from sqlite_master where type = 'table' and name = 'check_last'").get() == null) return []
+        return db.query('select id, status from check_last').all() as { id: string; status: string }[]
+    } catch {
+        return []
+    } finally {
+        try { db?.close() } catch { /* already gone */ }
+    }
+}
+
+/** the rows that finished at or after `since`, oldest first: the recent
+ *  window a live chart draws, without reading a fortnight of history */
+export function readRunsSince(path: string, since: number): RunRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        const rows = opened.db.query(`${RUN_ROWS} where r.at >= ? order by r.at asc, r.rowid asc`).all(since) as RawRow[]
+        return rows.map(runRow)
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+/** when the last WHOLE health pass started, whoever ran it. null = none on
+ *  record, which is what makes a fresh hub run one at once. */
+export function lastHealthPassAt(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 where kind = 'check' and narrowed = 0").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 */ }
+    }
+}
+
+/** every row the record holds, oldest first. A db that cannot be read is no
+ *  rows at all: it feeds a dashboard, and an empty history beats a crash. */
+export function readRuns(path: string): RunRow[] {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return []
+    try {
+        const rows = opened.db.query(`${RUN_ROWS} order by r.at asc, r.rowid asc`).all() as RawRow[]
+        return rows.map(runRow)
+    } catch {
+        return []
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+type RawRow = { runId: string; id: string; at: number; ms: number; status: string; replayed: number; label: string | null }
+
+/** every run row with the label of the invocation that wrote it, which is
+ *  where the tier is said (`shipkit ci --full`) */
+const RUN_ROWS = 'select r.run_id as runId, r.id as id, r.at as at, r.ms as ms, r.status as status, r.replayed as replayed, i.label as label from runs r left join invocations i on i.run_id = r.run_id'
+
+const runRow = (r: RawRow): RunRow => ({
+    runId: String(r.runId ?? ''), id: String(r.id), at: Number(r.at), ms: Number(r.ms), status: r.status as RunStatus, replayed: Number(r.replayed) === 1,
+    ...(r.label == null ? {} : { full: /(^|\s)--full(\s|$)/.test(String(r.label)) }),
+})
+
+/** what each check last printed. A row this reader cannot parse is no lines at
+ *  all: it feeds a card, and a card with nothing on it beats a crash. */
+export function readLastLines(path: string): Record<string, LastLine> {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return {}
+    const out: Record<string, LastLine> = {}
+    try {
+        for (const r of opened.db.query('select id, at, status, ms, lines from check_last').all() as { id: string; at: number; status: string; ms: number; lines: string }[]) {
+            try {
+                const lines = JSON.parse(r.lines) as Line[]
+                if (Array.isArray(lines)) out[r.id] = { at: Number(r.at), status: r.status as RunStatus, ms: Number(r.ms), lines }
+            } catch { /* one unreadable card, never the whole surface */ }
+        }
+    } catch {
+        return {}
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+    return out
+}
+
+/** what the record looks like from the outside, for a reader caching on it.
+ *  The FILE cannot answer this: in WAL mode a commit lands in the sidecar and
+ *  the db's own mtime does not move. */
+export function runsStamp(path: string): string {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return 'none'
+    try {
+        const r = opened.db.query('select count(*) as n, max(at) as last from runs').get() as { n: number; last: number | null }
+        return `${Number(r.n)}/${r.last ?? 0}`
+    } catch {
+        return 'none'
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+/** age based housekeeping, the same window the store keeps. A DELETE, so a row
+ *  written while it runs is kept: the file rewrite this replaced lost them. */
+export function sweepRuns(path: string, now: number, keepMs = KEEP_MS): void {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return
+    try {
+        sweepAll(opened.db, now, now - keepMs)
+    } catch {
+        // housekeeping never fails a run
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
+const sweepDeadLive = (db: Database, now: number, ownPid?: number): void => {
+    for (const r of db.query('select run_id as runId, pid, updated from live').all() as { runId: string; pid: number; updated: number }[])
+        if (Number(r.pid) === ownPid || liveRowDead({ pid: Number(r.pid), updated: Number(r.updated) }, now))
+            db.query('delete from live where run_id = ?').run(r.runId)
+}
+
+/** drops every live row nobody writes. `ownPid`: also every row that pid
+ *  holds, for a process that starts before it runs anything, so a row with
+ *  its pid is one an earlier image of it left (`bun --watch` restarts in
+ *  place, pid kept) */
+export function sweepLive(path: string, now: number, o?: { ownPid?: number }): void {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return
+    try {
+        sweepDeadLive(opened.db, now, o?.ownPid)
+    } catch {
+        // housekeeping never fails a run
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}