rvlib-shipkit 1.0.0 → 1.1.0

package/src/ledger/git-scan.ts

@@ -35,6 +35,7 @@ import { isAbsolute, join, normalize, resolve } from 'path'
 import { probeGitRoot } from '../core/git-root.ts'
 import { treePrefix } from '../core/nesting.ts'
 import { gitBin } from '../core/git-bin.ts'
+import { blobOid } from '../core/read-set.ts'
 
 /** what a scan measured. Every OID is a git object id of the CURRENT disk
  *  content, tracked or not. */
@@ -59,6 +60,14 @@ export type ScanResult = {
 
 export class GitScanError extends Error {}
 
+export type ScanOpts = {
+    /** the caller reads the whole tree's id and nothing else, so git is never
+     *  asked what it ignores: that answer only feeds force-adds and the
+     *  excluded list, and `git add -- .` leaves ignored files out by itself.
+     *  `excluded` and `ignored` come back empty */
+    treeOnly?: boolean
+}
+
 /** the scratch index FORMAT. Bump it whenever what the scan stages changes.
  *  The index is persistent, and anything staged into it stays there until
  *  something stages over it: a run that force-added a path a later version no
@@ -208,10 +217,15 @@ const underNodeModules = (p: string): boolean => p.split('/').includes('node_mod
  * stale describes files nobody has, and a key built on it is a false green
  * waiting for its first hit.
  */
-export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult): ScanResult {
+export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult, o: ScanOpts = {}): ScanResult {
     const started = performance.now()
+    if (o.treeOnly === true && (rawPaths.length !== 1 || normalizeInput(rawPaths[0]!) !== WHOLE_TREE))
+        throw new GitScanError(`treeOnly scans the whole tree and nothing else, asked for: ${rawPaths.join(', ')}`)
     const { scratch: indexFile, ignored: ignoredIndex, real: realIndex } = indexPaths(root)
     const wanted = [...new Set(rawPaths.map(normalizeInput))].sort()
+    // nothing asked for: the repo is still validated above, and no tree is
+    // written that nobody reads (a run of read checks declares no path)
+    if (wanted.length === 0) return { treeOid: '', oidByPath: new Map(), missing: [], excluded: new Map(), ignored: [], ignoredTreeOid: null, ms: performance.now() - started }
     const missing = wanted.filter((p) => !existsSync(join(root, p)))
     const present = wanted.filter((p) => existsSync(join(root, p)))
     const toAdd = dropCovered(present)
@@ -227,7 +241,9 @@ export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult):
     // A path that became ignored in between makes its plain add fail, which
     // throws, and a throw stores nothing: the one failure mode stays loud.
     const sameMissing = prior != null && prior.missing.join('\n') === [...new Set(missing)].sort().join('\n')
-    const ignored = prior != null && sameMissing
+    const ignored = o.treeOnly === true
+        ? []
+        : prior != null && sameMissing
         ? prior.ignored
         : toAdd.length === 0
         ? []
@@ -363,14 +379,16 @@ function excludedBy(wanted: string[], ignored: string[], forced: Set<string>): M
 }
 
 /**
- * blob ids for a list of FILES, one process, no index, no lock.
+ * blob ids for a list of FILES, hashed in process: no git, no index, no lock.
  *
  * The scratch index is the right tool for a declared input, which is usually a
  * directory and usually unchanged (git's stat cache answers without reading).
  * It is the wrong tool for the module-graph closure: those are individual
- * files, they belong to no declared path, and staging each one would cost a
- * `git add` spawn per file. `hash-object --stdin-paths` reads them all in one
- * call and returns exactly what a blob of that content would be.
+ * files, they belong to no declared path, and a check's code is a handful of
+ * small sources that cost less to read than one spawn. The id is the blob id
+ * of the bytes on disk, the same one the read recorder uses (`blobOid`). Git
+ * would apply clean filters (eol, lfs) first, so this id is only ever STRICTER:
+ * a filter-only change is a miss, never a false hit.
  *
  * A file that is not on disk is skipped and reported, never guessed at.
  */
@@ -379,16 +397,10 @@ export function hashFiles(root: string, files: string[]): { oids: Map<string, st
     const wanted = [...new Set(files.map(normalizeInput))].sort()
     const missing = wanted.filter((f) => !existsSync(join(root, f)))
     const present = wanted.filter((f) => existsSync(join(root, f)))
-    if (present.length === 0) return { oids, missing }
-    const p = Bun.spawnSync([gitBin(), 'hash-object', '--stdin-paths'], {
-        cwd: root,
-        stdin: Buffer.from(`${present.join('\n')}\n`),
-        stdout: 'pipe',
-        stderr: 'pipe',
-    })
-    if (p.exitCode !== 0) throw new GitScanError(`git hash-object exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n').slice(0, 3).join(' / ')}`)
-    const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
-    if (lines.length !== present.length) throw new GitScanError(`git hash-object answered ${lines.length} of ${present.length} files`)
-    present.forEach((f, i) => oids.set(f, lines[i]!.trim()))
+    for (const f of present) {
+        try { oids.set(f, blobOid(readFileSync(join(root, f)))) } catch (e) {
+            throw new GitScanError(`cannot read ${f} to hash it: ${e instanceof Error ? e.message : String(e)}`)
+        }
+    }
     return { oids, missing }
 }

package/src/ledger/ledger.ts

@@ -92,6 +92,8 @@ export type LedgerOpts = {
     fresh?: boolean
     /** module-graph config, loaded from the repo when omitted */
     cfg?: RvtConfig
+    /** the checks this run executes (KeyLayerOpts.scope) */
+    scope?: ReadonlySet<string>
     now?: () => number
 }
 
@@ -133,7 +135,7 @@ export class Ledger {
     ) {}
 
     static open(root: string, decls: CheckDecl[], o: LedgerOpts): Ledger {
-        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg })
+        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg, scope: o.scope })
         const fresh = o.fresh === true || process.env[FRESH_ENV] != null
         const reading = (o.read ?? ledgerReadEnabled()) && !fresh
         return new Ledger(layer, storeRoot(root), reading, o.now ?? Date.now)
@@ -166,7 +168,7 @@ export class Ledger {
         if (!this.reading) { this.misses++; return null }
         const e = readStored<Stored>(this.path(k), k.key)
         if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
-        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, this.view()) != null)) { this.misses++; return null }
+        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, () => this.view()) != null)) { this.misses++; return null }
         this.hits++
         return e.payload
     }
@@ -178,8 +180,14 @@ export class Ledger {
         return readStored<Stored>(this.path(k), k.key)?.payload.reads ?? null
     }
 
-    private driftOf(reads: ReadSet, view: RepoView): string | null {
-        return readSetDrift(this.layer.root, reads, (g) => (view.fallback != null ? null : view.list(g)))
+    /** the view is asked for only when a glob needs it: a read set with no
+     *  listing is validated on file content alone, and a whole tree git scan
+     *  per replay would buy nothing */
+    private driftOf(reads: ReadSet, view: () => RepoView): string | null {
+        return readSetDrift(this.layer.root, reads, (g) => {
+            const v = view()
+            return v.fallback != null ? null : v.list(g)
+        })
     }
 
     /** where askers of this check's exact question meet while one of them is
@@ -230,11 +238,11 @@ export class Ledger {
         // a fresh list, never this run's: the question is whether the tree
         // still is what the body read
         let fresh: RepoView | null = null
+        const freshView = (): RepoView => (fresh ??= RepoView.open(this.layer.root, this.viewMemo))
         for (const [id, outcome] of this.buffered) {
             if (touched.has(id)) { discarded.push(id); continue }
             if (outcome.reads != null) {
-                fresh ??= RepoView.open(this.layer.root, this.viewMemo)
-                const moved = this.driftOf(outcome.reads, fresh)
+                const moved = this.driftOf(outcome.reads, freshView)
                 if (moved != null) { discarded.push(id); drifted.push(moved); continue }
             }
             const k = this.key(id)

package/src/ledger/repo-view.ts

@@ -23,12 +23,12 @@ export class RepoView {
         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 */
+    /** `prior`: an earlier view of the same root in this run. The tree is
+     *  still staged and hashed fresh, so the list is today's, and an unchanged
+     *  tree reuses the prior's answer */
     static open(root: string, prior?: RepoView | null): RepoView {
         try {
-            const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined)
+            const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined, { treeOnly: true })
             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)
@@ -45,14 +45,16 @@ export class RepoView {
 }
 
 /** 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 */
+ *  id and one listing serves every view of that tree. `--full-tree` keeps it
+ *  so: without it git filters the listing by the cwd's path under the work
+ *  tree, and a nested folder's own subtree lists nothing */
 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' })
+    const p = Bun.spawnSync([gitBin(), 'ls-tree', '--full-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!)

package/src/ledger/run-log.ts

@@ -21,7 +21,7 @@
 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 { BUSY_MS, 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'
 
@@ -187,10 +187,16 @@ export class RunLog {
         const hadLive = this.liveSent !== ''
         this.quiet()
         this.liveSent = ''
-        try { this.liveDb?.close() } catch { /* already gone */ }
+        // the live row's handle writes the run too: an open and a close are
+        // most of what a write costs. It waits like a fresh one would
+        const live = this.liveDb
         this.liveDb = null
-        if (this.path === '' || (rows.length === 0 && last.length === 0 && !hadLive)) return []
-        const opened = openDb(this.path, { busyMs: this.busyMs })
+        if (this.path === '' || (rows.length === 0 && last.length === 0 && !hadLive)) { try { live?.close() } catch { /* already gone */ } return [] }
+        let opened: { db: Database } | null = null
+        if (live != null) {
+            try { live.exec(`pragma busy_timeout = ${Math.max(0, Math.round(this.busyMs ?? BUSY_MS))}`); opened = { db: live } } catch { try { live.close() } catch { /* already gone */ } }
+        }
+        opened ??= openDb(this.path, { busyMs: this.busyMs })
         if (opened == null) return unwritable(this.path)
         try {
             const insert = opened.db.query(INSERT_RUN)

package/src/ledger/run-timeline.ts

@@ -45,7 +45,9 @@ export type TimelineInvocation = {
 /** an invocation in a list: its numbers without its lanes */
 export type InvocationSummary = Omit<TimelineInvocation, 'bars'> & { checks: number }
 
-export type SlowCheck = { id: string; meanMs: number; worstMs: number; samples: number; ceilingMs: number | null; flag: 'over' | 'near' | null }
+/** `over` its ceiling, `near` it (past half), or over its `budget` on the
+ *  mean of its quick tier runs */
+export type SlowCheck = { id: string; meanMs: number; worstMs: number; samples: number; ceilingMs: number | null; budgetMs: number | null; flag: 'over' | 'near' | 'budget' | null }
 
 export type SuiteToFix = {
     check: string; unit: string; file: string; at: number; ms: number; budgetMs: number; tier: 'quick' | 'full'; red: boolean; slow: boolean
@@ -72,6 +74,8 @@ export type TimelineInput = {
     suites: SuiteRow[]
     /** each check's kill time, ms */
     ceilings: Record<string, number>
+    /** each check's resolved budget (core/budget.ts), for the slowest list */
+    budgets?: Record<string, number>
     /** the checks the repo declares today. Given, `slowest` lists only these:
      *  a deleted check's rows stay in the run history, and no edit can make it
      *  faster */
@@ -120,23 +124,31 @@ export function invocationsOf(runs: RunRow[], invocations: InvocationRow[]): Tim
 }
 
 /** the checks that cost the most when they really run: mean and worst of the
- *  MEASURED runs, flagged when the worst reached its ceiling or half of it */
-export function slowestChecks(runs: RunRow[], ceilings: Record<string, number>, size = TIMELINE_LIST, inventory?: readonly string[]): SlowCheck[] {
+ *  MEASURED runs, flagged when the worst reached its ceiling or half of it,
+ *  else when the mean of its QUICK tier runs is over its budget (the full
+ *  tier runs every slow suite on purpose, and is never judged) */
+export function slowestChecks(runs: RunRow[], ceilings: Record<string, number>, size = TIMELINE_LIST, inventory?: readonly string[], budgets: Record<string, number> = {}): SlowCheck[] {
     const live = inventory == null ? null : new Set(inventory)
     const ms = new Map<string, number[]>()
+    const quick = new Map<string, number[]>()
+    const add = (m: Map<string, number[]>, id: string, v: number): void => { m.set(id, [...(m.get(id) ?? []), v]) }
     for (const r of runs) {
         if (r.replayed || r.status === 'skip') continue
         if (live != null && !live.has(r.id)) continue
-        const list = ms.get(r.id) ?? []
-        list.push(r.ms)
-        ms.set(r.id, list)
+        add(ms, r.id, r.ms)
+        if (r.full !== true) add(quick, r.id, r.ms)
     }
+    const mean = (list: number[]): number => Math.round(list.reduce((a, b) => a + b, 0) / list.length)
     const out: SlowCheck[] = []
     for (const [id, list] of ms) {
         const worstMs = Math.max(...list)
         const ceilingMs = ceilings[id] ?? null
-        const flag = ceilingMs == null ? null : worstMs >= ceilingMs ? 'over' : worstMs > ceilingMs * NEAR_CEILING_SHARE ? 'near' : null
-        out.push({ id, meanMs: Math.round(list.reduce((a, b) => a + b, 0) / list.length), worstMs, samples: list.length, ceilingMs, flag })
+        const budgetMs = budgets[id] ?? null
+        const q = quick.get(id) ?? []
+        const flag = ceilingMs != null && worstMs >= ceilingMs ? 'over'
+            : ceilingMs != null && worstMs > ceilingMs * NEAR_CEILING_SHARE ? 'near'
+                : budgetMs != null && q.length > 0 && mean(q) > budgetMs ? 'budget' : null
+        out.push({ id, meanMs: mean(list), worstMs, samples: list.length, ceilingMs, budgetMs, flag })
     }
     return out.sort((a, b) => b.meanMs - a.meanMs || a.id.localeCompare(b.id)).slice(0, size)
 }
@@ -164,7 +176,7 @@ export function shapeTimeline(o: TimelineInput): Timeline {
     const size = o.listSize ?? TIMELINE_LIST
     return {
         invocations: all.slice(0, o.keep ?? TIMELINE_INVOCATIONS),
-        slowest: slowestChecks(o.runs, o.ceilings, size, o.inventory),
+        slowest: slowestChecks(o.runs, o.ceilings, size, o.inventory, o.budgets),
         longest: [...all].sort((a, b) => b.wallMs - a.wallMs || b.started - a.started).slice(0, size).map(({ bars, ...rest }) => ({ ...rest, checks: bars.length })),
         testFiles: testFilesToFix(o.suites, o.declaredSlow),
         suitesRecorded: o.suites.length > 0,

package/src/problems/problem-board.ts

@@ -2,10 +2,21 @@
 // asked about three checks replaces those three and leaves the rest standing:
 // vscode clears the whole pane at every frame, so a narrowed run that printed
 // only its own findings would erase every other check's.
-import { frameLines, type Problem } from './problem-line.ts'
+import type { HubProblem } from '../serve/hub-problems.ts'
+import { frameLines, hubProblemLine, type Problem } from './problem-line.ts'
 
 export class ProblemBoard {
     private readonly byCheck = new Map<string, Problem[]>()
+    private hub: Problem[] = []
+
+    /** what is wrong with the hub itself (serve/hub-problems.ts), which no
+     *  check owns. Returns whether the board moved */
+    setHub(problems: HubProblem[]): boolean {
+        const next = problems.map(hubProblemLine)
+        const moved = JSON.stringify(next) !== JSON.stringify(this.hub)
+        this.hub = next
+        return moved
+    }
 
     /** a check reached a verdict. What it carries has already passed the pane
      *  rule (problem-line.ts feedsProblemsPane), so an empty list clears it */
@@ -17,7 +28,7 @@ export class ProblemBoard {
     /** every finding standing, sorted by file then line, so a frame reads the
      *  same whatever order the checks finished in */
     all(): Problem[] {
-        return [...this.byCheck.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col || a.check.localeCompare(b.check))
+        return [...this.hub, ...this.byCheck.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col || a.check.localeCompare(b.check))
     }
 
     /** one check's verdict, as the runner reports it. A skip is no verdict

package/src/problems/problem-line.ts

@@ -39,6 +39,15 @@ export const ENDS_PATTERN = `^${FRAME_END_HEAD}\\b`
  *  (`imports:check`) both split right */
 export const PROBLEM_PATTERN = '^(.+?):(\\d+):(\\d+): (error|warning) (\\S+?): (.*)$'
 
+/** where a problem of the hub itself is anchored: it has no file, and the
+ *  matcher needs one, so it sits on line 1 of the file that declares the
+ *  hub. Check id `hub` */
+export const HUB_ANCHOR = 'repo.config.ts'
+
+export function hubProblemLine(p: { text: string; severity: 'red' | 'yellow' }): Problem {
+    return { file: HUB_ANCHOR, line: 1, col: 1, severity: p.severity === 'red' ? 'error' : 'warning', check: 'hub', message: p.text }
+}
+
 export function formatProblem(p: Problem): string {
     const message = p.message.replace(/\s*\n\s*/g, ' ').trim()
     return `${p.file}:${p.line}:${p.col}: ${p.severity} ${p.check}: ${message}`

package/src/repo-config.ts

@@ -8,11 +8,10 @@
 // a slot that can't fill emits a visible reason, disabling via
 // `defaults: { x: false }` prints a skipped-by-config line — never silence.
 // The `contracts` task is always present when any contract applies.
-import { existsSync, readFileSync } from 'fs'
+import { existsSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
-import { fileURLToPath } from 'url'
 import { ROUTED_SCRIPTS } from './core/canonical-scripts.ts'
-import { FLOOR_IDS, resolveFloor, type FloorResolution } from './core/floor.ts'
+import { FLOOR_IDS } from './core/floor.ts'
 export { resolveFloor, type FloorResolution, type FloorSource } from './core/floor.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
 import type { ProseConfig } from './prose/run-prose.ts'
@@ -21,6 +20,7 @@ import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { RULE_ID_RE, validateRules } from './rules/rule.ts'
 import { builtinCheckIds } from './core/discover-checks.ts'
 import { parseWhen } from './core/when.ts'
+import { budgetValueProblem } from './core/budget.ts'
 import type { Rule } from './check.ts'
 import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
@@ -105,6 +105,14 @@ export type RepoConfig = {
          *  Its last recorded run, from a gate or a health pass, is the secret's
          *  verdict. Absent: no check probes it, and the row says so */
         probedBy?: string
+        /** how much breaks without it, which decides its colour when it is
+         *  missing or its probe fails. `core`: the toolkit's own features stop
+         *  (a push, creating a repo, a release), so it is red, and a missing
+         *  one reaches `shipkit needs` as red. `used`: a feature this repo uses today, so
+         *  it is orange, a needs line that never pings. `minor`: proactive,
+         *  for something nothing uses yet, so it is dim and stays out of
+         *  `shipkit needs`. Default `used` */
+        level?: 'core' | 'used' | 'minor'
     }[]
     /** store-command template for a missing secret tile, `{name}` substituted, as in your secret manager's set command */
     credsCommand?: string
@@ -145,6 +153,12 @@ export type RepoConfig = {
      *  reason, and on an id no check carries. The hub writes this
      *  map through the managed block in this file (core/when-block.ts). */
     when?: Record<string, string>
+    /** WHAT A HEALTHY RUN OF EACH CHECK TAKES, in ms, keyed by check id. A
+     *  check that passes over its budget prints a WARN and reads yellow, and
+     *  never blocks. It wins over the check's own `budgetMs` and the default
+     *  for its kind (core/budget.ts). An id no check carries fails the run,
+     *  the same as a `when` entry. */
+    budgets?: Record<string, number>
     /** DEPRECATED, read into `when` as `off:<reason>`: rule id → the reason
      *  this repo breaks that invariant on purpose. An exempted rule does not
      *  lint and prints a skip line carrying the reason. `defineRepo` throws on
@@ -242,7 +256,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -320,6 +334,12 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
             throw new Error(`defineRepo: when.${id} names no rule, the ids are in \`shipkit checks\``)
     }
+    // a budget turns a slow pass yellow, so a value it cannot compare with dies here
+    for (const [id, v] of Object.entries(c.budgets ?? {})) {
+        if (id.trim() === '') throw new Error(`defineRepo: budgets has an entry with no check id`)
+        const bad = budgetValueProblem(v)
+        if (bad != null) throw new Error(`defineRepo: budgets.${id} ${bad}`)
+    }
     // an exemption silences a gate, so it names a rule that exists and says why
     for (const [id, reason] of Object.entries(c.ruleExempt ?? {})) {
         if (!builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))

package/src/serve/hub-app/check-view.tsx

@@ -47,10 +47,10 @@ const VERDICT_WORD: Record<'pass' | 'warn' | 'fail' | 'skip', string> = {
 // ── the pieces ───────────────────────────────────────────────────────────
 
 /** one duration, in the one unit, in the one tone */
-const Dur = ({ ms, ceiling }: { ms: number | null | undefined; ceiling?: number }) =>
+const Dur = ({ ms, ceiling, budget }: { ms: number | null | undefined; ceiling?: number; budget?: number }) =>
     ms == null
         ? <span className="dim">not timed yet</span>
-        : <span className={`dnum ${durationTone(ms, ceiling) ?? ''}`}>{fmtMs(ms)}</span>
+        : <span className={`dnum ${durationTone(ms, ceiling, budget) ?? ''}`}>{fmtMs(ms)}</span>
 
 const MdHelp = ({ text }: { text: string }) => <Help text={<span className="md" dangerouslySetInnerHTML={{ __html: renderMd(text) }} />} />
 
@@ -177,14 +177,14 @@ const RunWhen = observer(({ app, u }: { app: HubSt; u: CheckFacts }) => {
 
 /** the last N outcomes as a bar row: an average hides the shape, and the
  *  reds it cannot even see */
-const Bars = ({ runs, ceiling }: { runs: RecentRun[]; ceiling: number }) => {
+const Bars = ({ runs, ceiling, budget }: { runs: RecentRun[]; ceiling: number; budget: number }) => {
     if (runs.length === 0) return <div className="dim">no run on record yet</div>
     const top = Math.max(...runs.map((r) => r.ms), 1)
     return (
         <div className="bars">
             {runs.map((r, n) => (
                 <i key={`${r.at}-${n}`}
-                    className={`bar ${r.replayed ? 'rep' : r.status === 'fail' ? 'red' : r.status === 'warn' ? 'warn' : r.status === 'skip' ? 'rep' : durationTone(r.ms, ceiling) ?? 'plain'}`}
+                    className={`bar ${r.replayed ? 'rep' : r.status === 'fail' ? 'red' : r.status === 'warn' ? 'warn' : r.status === 'skip' ? 'rep' : durationTone(r.ms, ceiling, budget) ?? 'plain'}`}
                     style={{ height: `${r.replayed ? 8 : Math.max(10, Math.round((r.ms / top) * 100))}%` }}
                     title={`${stampWords(r.at)}: ${r.replayed ? CACHED : `${VERDICT_WORD[r.status]} in ${fmtMs(r.ms)}`}`} />
             ))}
@@ -200,22 +200,23 @@ export const LastRunValue = observer(({ app, u }: { app: HubSt; u: CheckFacts })
         <>
             <span className={`tl ${l.tone}`}>{l.word}</span>
             {u.lastAt == null ? null : <> <TimeAgo clock={app.clock} at={u.lastAt} /></>}
-            {u.lastMs == null || u.replayed ? null : <> in <Dur ms={u.lastMs} ceiling={u.timeoutMs} /></>}
+            {u.lastMs == null || u.replayed ? null : <> in <Dur ms={u.lastMs} ceiling={u.timeoutMs} budget={u.budgetMs} /></>}
             {l.verdict == null ? null : <span className={`tl ${l.tone}`}>, {l.verdict}</span>}
         </>
     )
 })
 
 export const Timings = ({ u }: { u: CheckFacts }) => (
-    <Row k="timings" wide help="what this check costs: its last run, the mean of the runs that really ran, the worst one on record, and the limit it is killed at">
+    <Row k="timings" wide help="what this check costs: its last run, the mean of the runs that really ran, the worst one on record, what a healthy run takes, and the limit it is killed at">
         <span className="ctimes">
-            <span><span className="ck">last</span> <Dur ms={u.lastMs} ceiling={u.timeoutMs} /></span>
-            <span><span className="ck">average</span> {u.samples === 0 ? <span className="dim">not timed yet</span> : <><Dur ms={u.avgMs} ceiling={u.timeoutMs} /> <span className="dim">over {u.samples}</span></>}</span>
-            <span><span className="ck">slowest</span> <Dur ms={u.slowestMs} ceiling={u.timeoutMs} />{u.failures > 0 ? <span className="dim">, {u.failures} red</span> : null}</span>
-            {/* a limit, never a measurement: it wears no tone of its own */}
+            <span><span className="ck">last</span> <Dur ms={u.lastMs} ceiling={u.timeoutMs} budget={u.budgetMs} /></span>
+            <span><span className="ck">average</span> {u.samples === 0 ? <span className="dim">not timed yet</span> : <><Dur ms={u.avgMs} ceiling={u.timeoutMs} budget={u.budgetMs} /> <span className="dim">over {u.samples}</span></>}</span>
+            <span><span className="ck">slowest</span> <Dur ms={u.slowestMs} ceiling={u.timeoutMs} budget={u.budgetMs} />{u.failures > 0 ? <span className="dim">, {u.failures} red</span> : null}</span>
+            {/* a budget and a limit, never measurements: they wear no tone of their own */}
+            <span><span className="ck">budget</span> <span className="dnum dim">{fmtMs(u.budgetMs)}</span> <Help term="budget" /></span>
             <span><span className="ck">limit</span> <span className="dnum dim">{fmtMs(u.timeoutMs)}</span> <Help term="ceiling" /></span>
         </span>
-        <Bars runs={u.recent ?? []} ceiling={u.timeoutMs} />
+        <Bars runs={u.recent ?? []} ceiling={u.timeoutMs} budget={u.budgetMs} />
     </Row>
 )
 

package/src/serve/hub-app/cols-svc.ts

@@ -5,7 +5,7 @@
 // the card.
 import { makeAutoObservable, runInAction } from 'mobx'
 import type { HubSt } from './hub-st.ts'
-import type { Col, ColMeta, Resource, Schedule } from './hub-types.ts'
+import type { Col, ColMeta, HubProblem, Resource, Schedule } from './hub-types.ts'
 
 export class ColsSvc {
     /** exactly what the server last sent; `resources` is this plus the live
@@ -14,6 +14,10 @@ export class ColsSvc {
     colMeta: ColMeta[] = []
     /** the hub's daily health pass timer, as the last poll saw it */
     schedule: Schedule | null = null
+    /** what the server says is wrong with the hub itself */
+    hubProblems: HubProblem[] = []
+    /** the last poll failed: the page cannot reach its own server */
+    fetchErr: string | null = null
     actErr = ''
     remarkDraft = ''
     proofDraft = ''
@@ -37,20 +41,18 @@ export class ColsSvc {
         try {
             const r = await fetch('/api/resources.json')
             if (!r.ok) throw new Error(await r.text())
-            const j = (await r.json()) as { collections: ColMeta[]; resources: Resource[]; schedule?: Schedule | null }
+            const j = (await r.json()) as { collections: ColMeta[]; resources: Resource[]; schedule?: Schedule | null; hub?: HubProblem[] }
             runInAction(() => {
                 this.colMeta = j.collections
                 this.fetched = j.resources
                 this.schedule = j.schedule ?? null
+                this.hubProblems = j.hub ?? []
+                this.fetchErr = null
             })
         } catch (e) {
-            // a dead server must SAY so on the tree, never render an empty
-            // repo that reads like a healthy one
-            const text = `resources fetch broke: ${(e as Error).message}`
-            runInAction(() => {
-                this.colMeta = [{ id: 'hub', title: 'hub', media: 'health' }]
-                this.fetched = [{ id: 'hub:resources-broken', collection: 'hub', type: 'health', path: 'health/hub-fetch', virtual: true, title: text, text, state: 'red', severity: 'red' }]
-            })
+            // a dead server must SAY so, in the header, never leave a tree
+            // that reads like a healthy repo. The last rows stay, dated by it
+            runInAction(() => { this.fetchErr = `the page cannot reach this hub: ${(e as Error).message}` })
         }
     }
 
@@ -62,6 +64,11 @@ export class ColsSvc {
     }
 
     /** the collections, as a grouping of the one array */
+    /** the header's red: the server's own problems, then an unreachable server */
+    get hubStatus(): HubProblem[] {
+        return [...this.hubProblems, ...(this.fetchErr == null ? [] : [{ id: 'fetch', text: this.fetchErr, severity: 'red' as const }])]
+    }
+
     get cols(): Col[] {
         return this.colMeta.map((m) => ({ ...m, instances: this.resources.filter((r) => r.collection === m.id) }))
     }

package/src/serve/hub-app/dur.ts

@@ -31,9 +31,18 @@ const group = (n: number): string => {
 
 export const fmtMs = (ms: number | null | undefined): string => (ms == null ? '' : `${group(Math.round(ms))}ms`)
 
-export function durationTone(ms: number | null | undefined, ceilingMs?: number | null): DurTone | null {
+/** the tone of one duration. A check's own BUDGET, when the caller knows it,
+ *  replaces the table above it: over the budget is red, past half of it
+ *  orange, and a suite well inside a generous budget never reads red because
+ *  a rule would be slow at that length (core/budget.ts) */
+export function durationTone(ms: number | null | undefined, ceilingMs?: number | null, budgetMs?: number | null): DurTone | null {
     if (ms == null) return null
     if (ceilingMs != null && ceilingMs > 0 && ms > ceilingMs * CEILING_SHARE) return 'bad'
+    if (budgetMs != null && budgetMs > 0) {
+        if (ms > budgetMs) return 'bad'
+        if (ms > budgetMs / 2) return 'slow'
+        return ms < FAST_MS ? 'fast' : 'plain'
+    }
     if (ms < FAST_MS) return 'fast'
     if (ms < PLAIN_MS) return 'plain'
     if (ms < SLOW_MS) return 'slow'

package/src/serve/hub-app/header-bar.tsx

@@ -46,6 +46,16 @@ const RunState = observer(({ app }: { app: HubSt }) => {
     )
 })
 
+/** what is wrong with the hub itself, one chip per problem. Nothing when all
+ *  is well: the header states trouble, never health */
+const HubStatus = observer(({ app }: { app: HubSt }) => (
+    <>
+        {app.cols.hubStatus.map((p) => (
+            <span key={p.id} className={`hstatus ${p.severity === 'red' ? 'red' : 'warn'}`} title={p.text}>{p.text}</span>
+        ))}
+    </>
+))
+
 export const HeaderBar = observer(({ app }: { app: HubSt }) => {
     const u = app.checks
     return (
@@ -57,6 +67,7 @@ export const HeaderBar = observer(({ app }: { app: HubSt }) => {
                 ))}
             </nav>
             <span className="sp" />
+            <HubStatus app={app} />
             <RunState app={app} />
             <button className="primary" disabled={u.busy} onClick={() => void u.run()}>run the health pass</button>
             <button disabled={u.busy} onClick={() => void u.run(undefined, { gate: true, label: 'the gate' })}>run the gate</button>

package/src/serve/hub-app/help.tsx

@@ -14,6 +14,7 @@ export const TERMS: Record<string, string> = {
     advisory: 'it can fail without stopping anything: the gate reports it and goes on',
     blocking: 'its failure stops the gate, and stops you',
     ceiling: 'the time it is killed at: a check creeping toward its ceiling is visible before it trips',
+    budget: 'what a healthy run takes: a run that passes over it warns and reads yellow, and never blocks. Set it with budgetMs in the check file, or budgets in repo.config.ts',
     cached: 'it did not run: the answer came from the cache, because nothing it depends on moved since it last ran',
     ran: 'it ran and was timed, so the number is what it costs today',
     slowest: 'the worst run on record, reds included',

package/src/serve/hub-app/hub-st.ts

@@ -134,10 +134,9 @@ export class HubSt {
         // the runs page is a page, not a resource, so no collection lists it
         out.push({ id: 'page:runs', label: 'runs', section: 'page', run: () => this.cols.select('runs', RUNS_ID) })
         for (const col of this.cols.sidebarCols) {
-            const health = col.id === 'health'
-            out.push({ id: `col:${col.id}`, label: col.title, section: 'section', run: () => (health ? this.showStatus() : this.showCol(col.id)) })
+            out.push({ id: `col:${col.id}`, label: col.title, section: 'section', run: () => this.showCol(col.id) })
             for (const i of col.instances)
-                out.push({ id: `item:${i.id}`, label: i.text, section: col.title, run: () => (health ? this.showStatus() : this.cols.select(col.id, i.id)) })
+                out.push({ id: `item:${i.id}`, label: i.text, section: col.title, run: () => this.cols.select(col.id, i.id) })
         }
         return out
     }
@@ -203,7 +202,7 @@ export class HubSt {
         this.cols.select(r.collection, r.id)
     }
 
-    /** collection view — one card per instance (health has StatusCard instead) */
+    /** collection view — one card per instance */
     showCol(id: string): void {
         this.setSel({ t: 'col', id })
     }

package/src/serve/hub-app/hub-types.ts

@@ -105,6 +105,7 @@ export type CheckFacts = {
     ttl?: string
     never?: string
     timeoutMs: number
+    budgetMs: number
     status: CheckStatus | null
     replayed: boolean
     lastMs: number | null
@@ -121,6 +122,10 @@ export type CheckFacts = {
     recent?: RecentRun[]
 }
 
+/** what is wrong with the hub itself, as the resources feed sends it
+ *  (serve/hub-problems.ts): the header shows it, never the tree */
+export type HubProblem = { id: string; text: string; severity: 'red' | 'yellow' }
+
 /** the hub's daily health pass timer, as the resources feed sends it
  *  (serve/health-schedule.ts). null = this hub runs no timer */
 export type Schedule = { everyMs: number; lastPassAt: number | null; nextAt: number; running: boolean }