@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/commands/resources/check.js

@@ -0,0 +1,1365 @@
+/**
+ * `vat resources check` — run the project's own assertions over its resource
+ * projection, as a gate.
+ *
+ * The invariants this file implements are written down once, in
+ * `docs/architecture/cli.md` under "`vat resources check [path]`". Read that
+ * before changing anything here; the headlines, so a reader knows when to:
+ *
+ * - 🔑 **Four ways to check nothing are all refusals**, at error severity under
+ *   the non-overridable `RESOURCE_CHECK_BROKEN`: a statement that will not run
+ *   (the `catch` in `runUnits`), a corpus that enumerated empty
+ *   ({@link emptyCorpusFinding}), a `--check` name nothing declares
+ *   (`requireKnownCheck`), and not one check executed at all
+ *   ({@link noCheckRanFinding}, derived in {@link buildCheckOutputData} so an
+ *   emptied `BUILTIN_CHECKS` cannot publish a clean document).
+ * - ⚠️ That last one does NOT make the step always able to fail: the only
+ *   built-in ships at `info`. Do not invent a second refusal for it — that
+ *   would refuse the no-config run the default set exists to serve.
+ * - 🔑 **No built-in check may be SQL.** {@link checkCommand} reads
+ *   `config?.resources?.checks` and nothing else for statements; built-ins are
+ *   TypeScript predicates over the row model, and a built-in's `sqlTwin` is
+ *   documentation an adopter copies, never executed here.
+ * - 🔑 **The default set belongs to the pipeline, not the config file.**
+ *   `BUILTIN_CHECKS` reaches {@link runProjectChecks} as a REQUIRED `builtins`
+ *   argument via {@link runOutcome}; nothing on that path reads `config`.
+ * - 🚨 **Adopter SQL runs unsandboxed on purpose, and contributed SQL is not
+ *   adopter SQL** — a contributed statement ships as a reviewed example.
+ * - ⛔ A TypeScript/SQL twin is documentation and a differential oracle, never
+ *   a runtime optimizer to schedule between.
+ */
+import { performance } from 'node:perf_hooks';
+import { bindBuiltinChecks, BUILTIN_CHECK_NAMES, issuesFromCheckRows, LIMIT_DIRECTIONS, } from '@vibe-agent-toolkit/resources';
+import { buildReport, CUSTOM_CHECK_CODE_PREFIX, ExitCode, isCustomCheckCode, reportSchema, toFindings, } from '@vibe-agent-toolkit/schema';
+import { safePath } from '@vibe-agent-toolkit/utils';
+import { z } from 'zod';
+import { handleReportCommandError } from '../../utils/command-error.js';
+import { loadConfigCached } from '../../utils/config-loader.js';
+import { formatDurationSecs } from '../../utils/duration.js';
+import { resolveIssueSeverity } from '../../utils/issue-severity.js';
+import { createLogger } from '../../utils/logger.js';
+import { writeStdoutSync, writeStructuredOutput } from '../../utils/output.js';
+import { assertDirectoryArgument, projectRootOrLoudCwd, projectRootOrNull } from '../../utils/project-root-policy.js';
+import { withQueriedProjection, } from '../../utils/projection-query.js';
+import { relationBoundsFor } from '../../utils/relation-limits.js';
+import { nothingCheckedFinding, runIntegrityFinding } from '../../utils/run-integrity.js';
+import { createProgressWriter, parseProgressLog, unitInFlight, } from './check-progress.js';
+import { parseBudgetSeconds, requireSupervisableFlags, runsInThisProcess, superviseCheck, withProgressLog, } from './check-supervisor.js';
+/** What one rule cost, as the document publishes it. */
+const PublishedCheckCostSchema = z.object({
+    name: z.string(),
+    /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
+    durationSecs: z.number().nonnegative(),
+    /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
+    rows: z.number().int().nonnegative().optional(),
+    broken: z.literal(true).optional(),
+    /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
+    builtin: z.literal(true).optional(),
+}).strict();
+/**
+ * The published copy of {@link relationBoundsFor}'s answer.
+ *
+ * The registry lists are `readonly` and this document is handed to a serializer,
+ * so the arrays are copied rather than referenced — the same rule
+ * `lensesEvaluated` follows one field above: a published document owns no
+ * reference into the run's own state.
+ *
+ * @param lensesEvaluated - The lenses this run evaluated
+ * @returns The bounds keys to spread, or nothing
+ */
+function structuredBounds(lensesEvaluated) {
+    const bounds = relationBoundsFor(lensesEvaluated);
+    if (bounds.boundsStatement === undefined || bounds.limits === undefined)
+        return {};
+    return { boundsStatement: bounds.boundsStatement, limits: bounds.limits.map((limit) => ({ ...limit })) };
+}
+/**
+ * A signed bound on what the derived rows settle, as `@vibe-agent-toolkit/resources`
+ * states it.
+ *
+ * ⛔ The direction vocabulary is IMPORTED, never respelled: `LIMIT_DIRECTIONS`
+ * is the one list, tied to `StatedLimit['direction']` by `satisfies`, so a
+ * fifth direction cannot leave this schema quietly rejecting it.
+ */
+const StatedLimitSchema = z.object({
+    id: z.string(),
+    direction: z.enum(LIMIT_DIRECTIONS),
+    statement: z.string(),
+}).strict();
+/**
+ * What the check run reports beyond its findings.
+ *
+ * The envelope's `examined` is `membersEnumerated` — what the rules ran
+ * AGAINST. `checksRun` is the other denominator, the number of RULES, and both
+ * are needed: zero findings is the pass condition and either number at zero
+ * makes that pass vacuous.
+ */
+export const CheckDataSchema = z.object({
+    root: z.string(),
+    /** Whether the projection was derived this run or read from the store. */
+    population: z.enum(['derived', 'store']),
+    /** What the population cost — charged to no check, see `CheckCost`. */
+    populationSecs: z.number().nonnegative(),
+    /** What evaluating the lenses cost, paid before the first statement ran. */
+    lensSecs: z.number().nonnegative(),
+    /**
+     * Which lenses that covers — the derived relations this run's checks could
+     * actually read. 🔑 An empty list says "no check asked for a derived relation"
+     * rather than "a lens stopped running"; without it `lensSecs: 0` is the same
+     * document either way, and a gate whose rules silently read empty relations is
+     * a gate that cannot fail.
+     */
+    lensesEvaluated: z.array(z.string()),
+    /**
+     * The prose frame {@link CheckDataSchema.limits} is read under. Present
+     * exactly when a lens with stated bounds was evaluated.
+     */
+    boundsStatement: z.string().optional(),
+    /**
+     * What the derived rows this run could read do NOT settle — signed and
+     * directional, the same list `vat claude context` publishes beside its own
+     * answer. Absent when no bounded lens ran: an empty list would claim nothing
+     * bounds the answer, which is stronger than "the answer holds no such row".
+     */
+    limits: z.array(StatedLimitSchema).optional(),
+    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
+    checksRun: z.number().int().nonnegative(),
+    /** What each rule cost, directly under the denominator it is the breakdown of. */
+    checks: z.array(PublishedCheckCostSchema),
+}).strict();
+/** The document this command publishes. */
+export const CHECK_REPORT_SCHEMA = reportSchema(CheckDataSchema);
+/**
+ * The refusal for a run in which NO check executed.
+ *
+ * 🚨 **The defect this closes shipped, and it is the shape by which a gate gets
+ * silently deleted.** A project with a valid `vibe-agent-toolkit.config.yaml`
+ * and no `checks:` block produced `status: success`, `checksRun: 0`, exit 0 — a
+ * passing gate document. Delete the `checks:` block and the CI step keeps going
+ * green forever; the only thing that said otherwise was a stderr warning nothing
+ * parses. **A gate that checked nothing is indistinguishable from a gate that
+ * was removed, and the whole argument for having these gates is that you never
+ * let those two look alike.**
+ *
+ * It is the third instance of the shape in this release — `vat claude budget`
+ * answered `success` on a path that matched no working location, and the repo's
+ * audit quality gate had a green path over zero parsed findings — so it is
+ * closed the way those were rather than a third way: a non-overridable
+ * `RUN_INTEGRITY_CODE` at `error`, derived in the report builder.
+ *
+ * 🔑 **Derived in {@link buildCheckOutputData}, not asserted by the handler.**
+ * That placement is the guarantee. The builder is where `checksRun` is computed
+ * and every lane's document goes through it — the completed run, the recovered
+ * document of an interrupted one, the child a supervisor forwards — so "the
+ * denominator is zero and the status is clean" is unrepresentable by
+ * construction, and a fourth lane added later inherits the refusal instead of
+ * having to remember it. It also lands after `resolveIssueSeverity`, which is
+ * belt and braces: the code is already unreachable from a `severity` key.
+ *
+ * The mechanism — ask the DENOMINATOR never the config, one report per
+ * situation, stand down behind an existing run-integrity finding — is the shared
+ * {@link nothingCheckedFinding}; this wrapper owns only the message. The
+ * stand-down matters here for an interrupted run, which recovers zero costs when
+ * the kill landed before the first statement finished and already carries
+ * {@link interruptedRunFinding}, the more specific of the two claims. A `--check`
+ * filter that matched nothing is refused earlier by {@link requireKnownCheck},
+ * and must stay refused even if that guard is ever widened.
+ *
+ * 🔑 **An absent `checks:` block does not empty the denominator** — the built-in
+ * set is in the pipeline, so reaching zero here means not even a default ran and
+ * the remedy is not "declare some checks". The guard stays because it is the
+ * mechanism-level guarantee that `checksRun: 0` can never be published clean,
+ * whatever empties it.
+ *
+ * @param costs - One record per check that EXECUTED; its length is `checksRun`
+ * @param issues - What the run already found, so an existing run-integrity
+ *   report is not duplicated
+ * @returns The finding, or nothing when at least one check ran
+ */
+function noCheckRanFinding(costs, issues) {
+    return nothingCheckedFinding(costs.length, issues, () => 'No check ran at all, so this document is not a verdict: a gate that checked nothing'
+        + ' produces the same report as a gate that was removed, and this run cannot tell'
+        + ' you which happened.'
+        + ' This is not an absent `resources.checks` block — VAT\'s own built-in checks run'
+        + ' whether or not a project declares any, so reaching zero means not even those'
+        + ' executed. Re-run with --debug and report it; if the run was filtered, check that'
+        + ' --check named a rule this build still ships.');
+}
+/**
+ * Build the check report.
+ *
+ * Pure: no file system, no clock, no `process.exit` — the same contract every
+ * other payload builder here follows, so the document's shape stays under unit
+ * test rather than only under a CLI spawn.
+ *
+ * `checksRun` is published beside the counts and is not decoration: zero
+ * findings from four checks and zero findings from **no** checks are the same
+ * document without it, and they mean opposite things. A project whose config key
+ * is misspelled would otherwise read as passing. It is DERIVED from the `checks`
+ * list rather than carried alongside it, so the denominator and the entries that
+ * account for it cannot disagree.
+ *
+ * 🚨 `populationSecs` and the per-check `durationSecs` do not overlap and do not
+ * sum to `durationMs`. The population is paid once and shared by every check;
+ * see {@link CheckCost} for why it is charged to none of them.
+ *
+ * 🔑 A denominator of zero is refused HERE rather than published — see
+ * {@link noCheckRanFinding}. This is the one function every lane's document
+ * passes through, so deriving the refusal in it is what makes "checked nothing,
+ * status clean" unrepresentable rather than merely unwritten.
+ *
+ * 🪤 The findings are NOT run through `relativizePathEntries`. Every other
+ * payload builder re-bases here because its producer keeps absolute paths
+ * internally; these arrive project-relative instead, and re-basing an
+ * already-relative path would resolve it against the wrong base and silently
+ * corrupt it. The guarantee is `locationOf` in `sql-checks.ts` — the one place
+ * a projection column becomes a finding's `location`, and which refuses an
+ * absolute or backslashed value there. Nothing on this path parses findings
+ * through the schema at runtime, and do not "fix" that by parsing at this
+ * boundary: it would convert a slip in `locationOf` from "this finding loses
+ * its anchor" into "the whole run throws", which is strictly worse for a gate.
+ *
+ * @param input - The findings and the provenance of the run behind them
+ * @returns The document to serialize
+ */
+export function buildCheckOutputData(input) {
+    const issues = [...noCheckRanFinding(input.costs, input.issues), ...input.issues];
+    return buildReport({
+        // The OTHER denominator, and the one whose absence shipped a green gate over
+        // an empty repository. `checksRun` counts rules; this counts what they ran
+        // against.
+        examined: input.membersEnumerated,
+        findings: toFindings(issues),
+        durationMs: input.durationMs,
+        data: {
+            root: input.root,
+            population: input.population,
+            // Beside the origin, because a `population: store` a reader cannot price is
+            // a label taken on faith. Charged to no check — see {@link CheckCost}.
+            populationSecs: formatDurationSecs(input.populationMs),
+            // Published here too, and not only by `query`, because this verb pays it
+            // identically — the lens is evaluated before the first statement runs. A
+            // document that priced the population but not the lens would attribute the
+            // lens's cost to whichever rule the reader happened to be looking at, which
+            // is the same defect `populationSecs` exists to prevent.
+            lensSecs: formatDurationSecs(input.lensMs),
+            // What that number covers — see `CheckDataSchema.lensesEvaluated`. Copied
+            // into a plain array so the published document owns no reference into the
+            // run's own state.
+            lensesEvaluated: [...input.lensesEvaluated],
+            // The bounds of the rows those lenses produced, stated ONCE and only when
+            // a bounded lens ran. This is the verb an adopter makes GATE, so it is the
+            // one that most owes them — `utils/relation-limits.ts` carries why.
+            // Copied out of the readonly registry lists: the published document owns
+            // no reference into module state a later render could mutate.
+            ...structuredBounds(input.lensesEvaluated),
+            // The denominator of rules. Derived from `checks`, never carried beside it.
+            checksRun: input.costs.length,
+            // What each rule cost, directly under the denominator it is a breakdown
+            // of. A SQL surface is an unbounded cost — a project can declare a
+            // statement that scans every row of every table — and a single total
+            // attributes nothing: ten seconds is one expensive rule, a slow
+            // population, or forty cheap rules, and only this list tells them apart.
+            //
+            // 🪤 `rows` and `broken` are spread conditionally rather than defaulted.
+            // `rows: 0` on a statement that never returned would read as a clean pass,
+            // which is the exact confusion `RESOURCE_CHECK_BROKEN` exists to prevent —
+            // so a check that threw publishes no row count at all.
+            checks: input.costs.map((cost) => ({
+                name: cost.name,
+                // Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather
+                // than rounding to a zero that reads as "not measured".
+                durationSecs: formatDurationSecs(cost.durationMs),
+                ...(cost.rows === undefined ? {} : { rows: cost.rows }),
+                ...(cost.broken === undefined ? {} : { broken: cost.broken }),
+                // Absent, never `false`, on a declared rule — so the key's presence is
+                // the whole claim and a reader never has to tell `false` from unset.
+                ...(cost.builtin === undefined ? {} : { builtin: cost.builtin }),
+            })),
+        },
+    });
+}
+/**
+ * Run a thunk between two readings of the clock, and report both.
+ *
+ * ## 🚨 Why this is a helper and not a stopwatch inline in the loop
+ *
+ * The loop used to read the clock into a `startedAt`, call `ask`, and subtract
+ * two lines later — and the claim below that "the span is `ask(check.sql)` and
+ * nothing else" had NO guard behind it. A reviewer moved the subtraction below
+ * the row-to-finding mapping, widening the measured span to cover work that is
+ * not the statement, and **the entire unit suite stayed green (36/36)**. That is
+ * measured, not assumed.
+ *
+ * No cleverer fake clock closes it. The injected clock advances per READING, so
+ * every mutation that keeps two readings per check yields the same number; a
+ * clock that advanced only inside `ask` could not tell the two positions apart
+ * either, because the real mapping never touches the clock — and making the
+ * mapping slow in real time would buy a flake, not a guard.
+ *
+ * So the span is a THUNK. What is timed is what is passed in, and widening it
+ * stops being a one-line move of a subtraction and becomes a visible rewrite of
+ * the call site.
+ *
+ * 🪤 The throw is CAUGHT rather than propagated, so the failing path has a
+ * duration too. Keep it that way: a `try` in the caller around a helper that
+ * only times the happy path re-opens the two-read stopwatch this closes.
+ *
+ * @param now - The clock, in milliseconds
+ * @param run - The work whose duration is wanted, and nothing else
+ * @returns What `run` produced or threw, and how long that took
+ */
+function timed(now, run) {
+    const startedAt = now();
+    try {
+        return { ok: true, value: run(), durationMs: now() - startedAt };
+    }
+    catch (error) {
+        return { ok: false, error, durationMs: now() - startedAt };
+    }
+}
+/**
+ * The finding for a statement that would not run.
+ *
+ * 🔑 A finding, not a skip, at `error`, and under its OWN code.
+ *
+ * The check's declared severity describes how bad a VIOLATION is; it says
+ * nothing about how bad it is that the check cannot run, and a `warning` check
+ * whose SQL broke would otherwise fail nothing while asserting nothing. That
+ * much was always true of the DECLARATION.
+ *
+ * 🪤 It was never true of an adopter OVERRIDE, and this finding used to carry
+ * `customCheckCode(name)` — the same code as a violation of that very check. So
+ * `severity: { 'CUSTOM:foo': 'ignore' }`, the documented way to stand down a
+ * check you inherited, also silenced "foo could not run", and `'warning'`
+ * demoted it below the exit threshold. A renamed projection column then produced
+ * exit 0 from a gate. `RESOURCE_CHECK_BROKEN` is a non-overridable code
+ * precisely so that config line cannot reach here.
+ *
+ * 🪤 Only `ask` reaches this. Turning the selected rows INTO findings is not a
+ * statement failure, and reporting it as one told the operator a working rule
+ * was broken — see the append in {@link runUnits}.
+ *
+ * @param name - The check's key in `resources.checks`
+ * @param error - Whatever the statement threw
+ * @returns The run-integrity finding
+ */
+function brokenCheckFinding(name, error) {
+    return runIntegrityFinding(`The check "${name}" could not run, so it is asserting nothing: `
+        + (error instanceof Error ? error.message : String(error)));
+}
+/**
+ * One declared statement, as a unit.
+ *
+ * @param name - The check's key in `resources.checks`
+ * @param check - Its declaration
+ * @param ask - Runs one statement against the populated projection
+ * @returns The runnable unit
+ */
+function sqlCheckUnit(name, check, ask) {
+    return {
+        name,
+        select: () => {
+            const rows = ask(check.sql);
+            return { rows: rows.length, report: () => issuesFromCheckRows(name, check, rows) };
+        },
+    };
+}
+/**
+ * One built-in predicate, as a unit.
+ *
+ * 🪤 Its `rows` is the finding count, and that is the same quantity a statement
+ * reports: one finding per violating row. There is no conversion step to leave
+ * outside the clock, so the whole predicate is timed.
+ *
+ * @param builtin - The built-in, already bound to this run's projection
+ * @returns The runnable unit
+ */
+function builtinCheckUnit(builtin) {
+    return {
+        name: builtin.name,
+        builtin: true,
+        select: () => {
+            const issues = builtin.run();
+            return { rows: issues.length, report: () => issues };
+        },
+    };
+}
+/**
+ * Every check this run will attempt, in the order it will attempt them.
+ *
+ * 🔑 **Built-ins FIRST, and never interleaved with the declared ones**, so the
+ * document's `checks[]` opens with the same rules in the same order for every
+ * project and a reader comparing two runs compares like with like.
+ *
+ * 🪤 A project MAY declare a check whose key equals a built-in's name. Both run,
+ * both are priced, `builtin` on the cost record tells them apart, and
+ * `--check <name>` selects both. Not refused: a new config error is a breaking
+ * change and nothing about the collision is unsafe.
+ *
+ * @param builtins - The default set, bound to this run's projection
+ * @param checks - The project's `resources.checks`
+ * @param ask - Runs one statement against the populated projection
+ * @returns The units, built-ins first
+ */
+function checkUnits(builtins, checks, ask) {
+    return [
+        ...builtins.map((builtin) => builtinCheckUnit(builtin)),
+        ...Object.entries(checks).map(([name, check]) => sqlCheckUnit(name, check, ask)),
+    ];
+}
+/**
+ * Run every unit, collect its findings, and price it.
+ *
+ * 🚨 **The timed span is `unit.select()` and nothing else** — structurally,
+ * because it is the thunk handed to {@link timed}. 🚨 **And the loop announces a
+ * check BEFORE it can be stopped**, because a runaway statement can only be
+ * ended by an external `SIGKILL` that publishes nothing of the killed process's
+ * memory. Both, with the clock-granularity and one-record-per-check rules they
+ * rest on: `docs/architecture/cli.md`, "The population is charged to NOBODY" and
+ * "Why the loop announces a check before it can be stopped".
+ *
+ * @param units - Every check this run will attempt, built-ins first
+ * @param only - A single check name to run, or undefined for all of them
+ * @param now - The clock, in milliseconds; injected so a test can assert an
+ *   exact duration rather than a range that passes on a timer that never started
+ * @param onProgress - Told what is about to run and what it cost, or undefined
+ *   when nothing is watching (the in-process lane, and `--budget 0`)
+ * @returns The findings, and one cost record per check that ran
+ */
+function runUnits(units, only, now, onProgress) {
+    const issues = [];
+    const costs = [];
+    /** File the cost with the observer as well as with the caller — one place. */
+    const price = (cost) => {
+        costs.push(cost);
+        onProgress?.({ kind: 'check', ...cost });
+    };
+    for (const unit of units) {
+        const { name } = unit;
+        if (only !== undefined && name !== only)
+            continue;
+        // Spread onto every cost record this unit files, so the two arms below
+        // cannot disagree about which set the rule came from.
+        const origin = unit.builtin === undefined ? {} : { builtin: unit.builtin };
+        // 🪤 BEFORE `timed`, and not one line later. `ask` is where a runaway
+        // statement never returns from, so an announcement below it is filed by
+        // every check except the one whose name the operator needs.
+        onProgress?.({ kind: 'start', name });
+        const outcome = timed(now, unit.select);
+        if (!outcome.ok) {
+            // Priced up to the throw, and with NO row count: a check that did not
+            // complete selected nothing, and `rows: 0` would say it selected nothing
+            // and passed. A built-in reaches this arm too — a defect in VAT's own
+            // predicate must fail the gate rather than vanish.
+            price({ name, durationMs: outcome.durationMs, broken: true, ...origin });
+            issues.push(brokenCheckFinding(name, outcome.error));
+            continue;
+        }
+        price({ name, durationMs: outcome.durationMs, rows: outcome.value.rows, ...origin });
+        // 🪤 Appended one at a time, NEVER `issues.push(...findings)`. A spread
+        // becomes an ARGUMENT LIST, which throws `RangeError: Maximum call stack
+        // size exceeded` past roughly 125,000 elements on the main thread — and a
+        // check's result set is unbounded by construction. VAT's own
+        // `blob_references` table already holds 29,645 rows, so `SELECT * FROM
+        // blob_references` over a repository a few times this size reached it, and
+        // the throw landed in the arm above: a rule that ran perfectly was reported
+        // as one that "could not run, so it is asserting nothing". A loop does not
+        // put the argument limit in play at all.
+        for (const issue of outcome.value.report())
+            issues.push(issue);
+    }
+    return { issues, costs };
+}
+/**
+ * Refuse a `--check` name that names neither a built-in nor a declared check.
+ *
+ * 🔑 **An unknown name is otherwise a silent green.** With nothing comparing the
+ * flag against the known names, `--check nope` filters every check away, runs
+ * none, and exits 0 with `checksRun: 0` and `issues: []` on empty stderr — and
+ * the "no checks are declared" warning does not fire, because it asks whether
+ * the `checks` MAP is empty, never whether the FILTER matched anything. Not a
+ * hypothetical typo: rename or delete a check and the CI step keeps passing
+ * forever while asserting nothing.
+ *
+ * Thrown rather than reported as a finding, because it is an OPERATOR error and
+ * not a content violation — the two have different exit codes in this command's
+ * contract (2 versus 1) and different audiences. Thrown before the projection is
+ * populated, so a mistyped flag costs no crawl.
+ *
+ * 🔑 **A built-in is nameable here exactly like a declared one.** A guard that
+ * only knew the config would refuse the very rules that run when there is no
+ * config at all. The refusal names both sets.
+ *
+ * @param builtinNames - The default set's names — {@link BUILTIN_CHECK_NAMES} in
+ *   production, and passed in rather than imported here so a test can prove the
+ *   guard rather than restate the constant
+ * @param checks - The project's `resources.checks`
+ * @param only - The `--check` value, or undefined
+ * @throws When `only` names no check this run would attempt
+ */
+export function requireKnownCheck(builtinNames, checks, only) {
+    // 🪤 `Object.hasOwn`, not `only in checks`. `in` walks the prototype chain, so
+    // `--check toString` would have looked declared, matched nothing, and restored
+    // the exact silent green this guard closes.
+    if (only === undefined || builtinNames.includes(only) || Object.hasOwn(checks, only))
+        return;
+    const declared = Object.keys(checks);
+    throw new Error(`No check named "${only}" exists. `
+        + `Built in: ${builtinNames.join(', ')}. `
+        + (declared.length === 0
+            ? 'This project declares none of its own — add them under `resources.checks` in'
+                + ' vibe-agent-toolkit.config.yaml.'
+            : `Declared under \`resources.checks\`: ${declared.join(', ')}.`));
+}
+/**
+ * Name every `CUSTOM:` severity override that overrides nothing.
+ *
+ * 🔑 **The same silent-green shape as an unknown `--check` name, one surface
+ * over.** {@link requireKnownCheck} refuses `--check nope` because a filter
+ * that matched nothing ran nothing and exited 0. A `validation.severity` entry
+ * keyed `CUSTOM:<name>` for a check that is not declared is the mirror image: it
+ * parses (the schema validates the KEY's shape and cannot see
+ * `resources.checks`), applies to no finding, and says nothing. An adopter
+ * renames a check and leaves the override behind, or mistypes it while standing
+ * down an inherited one — and in the second direction the check they meant to
+ * silence keeps failing their build with no clue why.
+ *
+ * ⚠️ **A warning, not a refusal, and the asymmetry with `--check` is
+ * deliberate.** `--check` is a flag typed for THIS run, so a mistake is an
+ * operator error and exiting 2 costs nothing. A `severity` entry lives in a
+ * committed config that may legitimately be shared across repositories or
+ * outlive a check through a rename in flight; refusing it would be a new
+ * breaking config error, which is exactly the change this release already
+ * decided not to make twice (see `ResourcesConfigSchema`). Stderr, so the
+ * document on stdout stays parseable — the same channel and the same reasoning
+ * as the "no checks are declared" warning in {@link checkCommand}.
+ *
+ * 📌 The registry half of the key space needs no equivalent: a misspelled
+ * REGISTRY code is already refused by `SeverityOverrideCodeSchema`, whose
+ * `SEVERITY_KEY_PATTERN` alternates every registry code name with the `CUSTOM:`
+ * namespace — so a key has to BE one of the shipped codes to match that half.
+ * Only the open `CUSTOM:` half can name something that does not exist, because
+ * only it matches on shape rather than on identity.
+ *
+ * @param checks - The project's `resources.checks`
+ * @param validation - The project's `resources.validation`, or undefined
+ * @param logger - Where the warning goes (stderr)
+ */
+export function warnUndeclaredOverrides(checks, validation, logger) {
+    const stale = Object.keys(validation?.severity ?? {})
+        .filter((code) => isCustomCheckCode(code))
+        // 🪤 `Object.hasOwn`, not `in` — same reason {@link requireKnownCheck}
+        // uses it: `in` walks the prototype chain, so an override keyed
+        // `CUSTOM:toString` would look declared and stay silent.
+        .filter((code) => !Object.hasOwn(checks, code.slice(CUSTOM_CHECK_CODE_PREFIX.length)));
+    if (stale.length === 0)
+        return;
+    const declared = Object.keys(checks);
+    logger.warn(`resources.validation.severity names ${stale.length} check(s) this project does not declare,`
+        + ` so ${stale.length === 1 ? 'it overrides' : 'they override'} nothing: ${stale.join(', ')}.`
+        + (declared.length === 0
+            ? ' No checks are declared at all.'
+            : ` Declared under \`resources.checks\`: ${declared.join(', ')}.`)
+        + ' Correct the spelling, or delete the entry — a severity override for a check that no longer'
+        + ' exists is not silencing anything, and a MISTYPED one leaves the check you meant to stand'
+        + ' down still failing the build.');
+}
+/**
+ * The finding for a run whose checks executed over an empty corpus.
+ *
+ * 🔑 **The defect this closes shipped.** A scratch repository with
+ * `.gitignore = *` and two declared checks reported `checksRun: 2`,
+ * `status: success`, exit 0 and empty stderr over a corpus of ZERO files. The
+ * rules reported nothing because there was nothing to report on, and the
+ * document could not say so: `checksRun` is the denominator of rules, not of
+ * rows, so a gate over eight thousand files and a gate over none serialized
+ * identically. A broad ignore pattern, a shallow or sparse CI checkout, a root
+ * that resolved to the wrong directory, or an extent source that enumerated
+ * nothing all produce it — and because population DECLINES ignored members
+ * rather than flagging them, the tables carry no trace of the difference.
+ *
+ * The precedent is `population-wiring.ts`, which makes `onBlobPopulation`
+ * mandatory because "a tree whose every document was declined as binary
+ * otherwise populates as empty and reports success". That guard covers blob
+ * refusals only; this one covers the extent.
+ *
+ * 🪤 **Only when checks actually RAN.** A run with no rules at all is refused
+ * too — it is the same class one level further out — but by
+ * {@link noCheckRanFinding}, whose message is about the missing RULES rather
+ * than about the missing rows. Firing both would hand the operator two reports
+ * about one situation, and this is the less specific of the two: "the 0 checks
+ * that ran asserted nothing over 0 members" sends them to inspect a
+ * `.gitignore` when what they are missing is a `checks:` block.
+ *
+ * 🪤 **`RUN_INTEGRITY_CODE`, not a code of its own** — see that constant
+ * for why all four refusals in this verb share one.
+ *
+ * @param checksRun - How many checks EXECUTED. Under `--check` that is fewer
+ *   than the project declares, which is why the message says "ran" and not
+ *   "declared": the number is the size of the filtered run
+ * @param membersEnumerated - How many members the population enumerated
+ * @returns The finding, or nothing when the run had a corpus (or no checks)
+ */
+function emptyCorpusFinding(checksRun, membersEnumerated) {
+    if (checksRun === 0 || membersEnumerated > 0)
+        return [];
+    return [runIntegrityFinding(`The projection enumerated 0 members, so the ${checksRun} check(s) that ran`
+            + ' asserted nothing: there were no rows for any statement to select and'
+            + ' zero findings means only that the corpus was empty.'
+            + ' Look at `.gitignore` (one broad pattern declines every file), at whether'
+            + ' the checkout is complete rather than shallow or sparse, and at whether'
+            + ' `root` in this report is the directory you meant.'
+            + ' `vat resources scan` over the same path lists what an enumeration finds.')];
+}
+/**
+ * Where the run was when it stopped, as a phrase.
+ *
+ * @param inFlight - What the log's last state says
+ * @returns A clause naming the unit
+ */
+function inFlightPhrase(inFlight) {
+    if (inFlight.kind === 'check')
+        return `while the check "${inFlight.name}" was running`;
+    if (inFlight.kind === 'reporting') {
+        return 'after the last check had finished, while its document was being assembled';
+    }
+    // 🪤 The HEDGE is load-bearing and was once deleted on the strength of
+    // `checks-complete`. It does not cover this window. `price()` files the last
+    // check's cost BEFORE `issuesFromCheckRows` turns its rows into issues, and
+    // `checks-complete` is written after that conversion — so a kill in between
+    // leaves a log of nothing but completed checks, which reads as `idle`. The
+    // unhedged sentence then told an operator whose run had finished every rule
+    // that it died before the first statement. The window is narrow (the
+    // conversion runs ~0.74x the statement it follows, so a budget that survived
+    // the statement survives the conversion) but a narrow window is not a closed
+    // one, and the sentence costs nothing to keep honest.
+    return 'while no check was running — either between the population and the first'
+        + ' statement, or after the last one had filed its cost';
+}
+/**
+ * What ended the child, as a phrase.
+ *
+ * @param death - The ending the supervisor resolved
+ * @returns A clause naming the mechanism
+ */
+function deathPhrase(death) {
+    if (death.kind === 'signal')
+        return `the child process was terminated by ${death.signal}`;
+    if (death.kind === 'spawn-failed') {
+        return `the child process could not be started at all (${death.binary}: ${death.detail})`;
+    }
+    if (death.kind === 'kill-failed') {
+        return 'the budget was blown and the SIGKILL that should have ended the run was REFUSED'
+            + ` (${death.detail})`;
+    }
+    if (death.kind === 'no-output') {
+        return `the child process exited ${death.code} and published no report at all`;
+    }
+    return 'the child process ended with neither an exit code nor a signal';
+}
+/**
+ * What to do about a child that never started.
+ *
+ * 🚨 **"Check your PATH" is the wrong thing to tell a saturated runner.**
+ * `spawn` fails with `EAGAIN` when the machine has no free process slot and
+ * `ENOMEM` when it has no free memory — which is precisely the memory-pressured
+ * environment this whole feature exists for, and precisely where an operator
+ * least deserves to be sent hunting an installation problem that is not there.
+ *
+ * @param detail - What `spawn` reported
+ * @returns The remedy sentence
+ */
+function spawnFailedRemedy(detail) {
+    if (/\b(?:EAGAIN|ENOMEM)\b/.test(detail)) {
+        return ' The child could not be started because the RUNNER had nothing left to start it'
+            + ' with — EAGAIN is "no free process slot" and ENOMEM is "no free memory" — so this is'
+            + ' about how loaded the machine is, not about the installation and not about the SQL.'
+            + ' Give the job a less contended runner, or reduce what else is running beside it.';
+    }
+    return ' Nothing ran at all, so this is an installation or PATH problem rather than'
+        + ' anything about the SQL.';
+}
+/**
+ * What to do about a kill the kernel refused.
+ *
+ * ⛔ This must never be composed from the spawn-failure sentence, however
+ * similar the plumbing is. The two are opposites: one child never existed, and
+ * this one is, as far as this process can tell, STILL RUNNING.
+ *
+ * @param death - The refused kill, and the pid it left behind
+ * @returns The remedy sentence
+ */
+function killFailedRemedy(detail, pid) {
+    const handle = pid === undefined
+        ? ' The child\'s pid is not known to this process.'
+        : ` The child was process ${pid}.`;
+    return ' The run started, ran past its budget, and then REFUSED TO DIE: the watchdog sent'
+        + ` SIGKILL and the kernel would not deliver it (${detail}), which normally means EPERM.`
+        + handle
+        + ' It may still be running and still holding whatever the statement was holding, so'
+        + ' check for it and end it by hand before starting another run. Nothing about the SQL'
+        + ' or the installation is implicated by the refusal itself — but the bound could not be'
+        + ' enforced, so treat this run as unsupervised.'
+        // 🚨 Its OWN budget-role sentence, because the generic one below is false
+        // here: this is the single abnormal death the watchdog causes. Saying "the
+        // watchdog never fired" would repeat, in the report, the exact confusion
+        // that produced the defect.
+        + ' The watchdog DID fire — the budget is what decided this run should stop — but the'
+        + ' kill was refused, so raising the budget only moves when the refusal happens. It does'
+        + ' not make the run stoppable.';
+}
+/**
+ * What to do about a particular signal.
+ *
+ * 🚨 **The defect this closes: the fallback contradicted the sentence beside
+ * it.** Only `SIGABRT` and `SIGKILL` were partitioned on and everything else
+ * fell through to a sentence written for `no-status` — so a real `kill -TERM`
+ * produced "terminated by SIGTERM … The cause is outside anything this command
+ * can observe; the child left no exit code to report". It names the signal, and
+ * then says it can see nothing and was told nothing. SIGSEGV, SIGBUS, SIGHUP and
+ * SIGXCPU read the same way.
+ *
+ * ⚠️ **SIGTERM is not exotic; it is how CI kills things** — `timeout(1)`, a
+ * cancelled job, a container stopping. The old claim that "SIGABRT and SIGKILL
+ * are the two that actually happen" was wrong about the commonest one.
+ *
+ * @param signal - The signal `close` reported
+ * @returns The remedy sentence
+ */
+function signalRemedy(signal) {
+    if (signal === 'SIGABRT') {
+        return ' SIGABRT here is Node aborting on its own heap limit: the run exhausted memory'
+            + ' MATERIALISING a result set, which is what an unbounded statement does as soon as it'
+            + ' selects rows rather than an aggregate. The remedy is a narrower statement or a'
+            + ' `LIMIT`, not a bigger machine.';
+    }
+    if (signal === 'SIGKILL') {
+        return ' Nothing inside this run sends SIGKILL except the budget watchdog, and the watchdog'
+            + ' did not fire — so something OUTSIDE killed the child: a kernel OOM killer on a'
+            + ' memory-capped runner (it picks the largest process, which is this child and never the'
+            + ' idle parent), a container memory limit, or an operator. Give the job more memory, or'
+            + ' narrow the statement so it needs less.';
+    }
+    if (signal === 'SIGTERM' || signal === 'SIGINT' || signal === 'SIGHUP') {
+        return ` Nothing inside this run sends ${signal}: something OUTSIDE asked the child to stop.`
+            + ' On CI that is almost always a step or job timeout (`timeout(1)`, a workflow'
+            + ' `timeout-minutes`), a cancelled pipeline, or a container being shut down. Look at the'
+            + ' job\'s own time limit and at whether the run was cancelled — not at the SQL, which was'
+            + ' still working when it was interrupted.';
+    }
+    if (signal === 'SIGSEGV' || signal === 'SIGBUS') {
+        return ` ${signal} is a CRASH inside native code, not anything an adopter's SQL can express:`
+            + ' the process was killed by the kernel for touching memory it should not have. That'
+            + ' points at a native module (`node:sqlite` is one) or at the platform, and it is worth'
+            + ' reporting with the Node version, the platform and the statement that was running.';
+    }
+    return ` ${signal} was not sent by anything inside this run, and this command has no specific`
+        + ' remedy for it: look at what else on this machine signals its child processes — a'
+        + ' supervisor, a resource limit, or an operator.';
+}
+/**
+ * The exit code Node uses for its own fatal abort, on EVERY platform.
+ *
+ * 🚨 **This is measured, and it is NOT the local platform's signal number.** On
+ * macOS and Linux 134 is the shell encoding `128 + SIGABRT`, where `SIGABRT` is
+ * 6. On Windows `os.constants.signals.SIGABRT` is **22** — MSVC numbers it
+ * differently — so deriving the code from that table gives 150 and matches
+ * nothing Node ever emits. A `windows-latest` run of the heap-abort case
+ * reported exactly **134**, the same as Unix: the number comes from Node's own
+ * abort path, not from the platform's signal table.
+ *
+ * 🪤 An earlier version of this file DID derive it from `os.constants.signals`,
+ * and its unit test derived the same way — so the test agreed with the code, the
+ * round-trip passed on every machine, and the pair was wrong together on the one
+ * platform the branch exists for. The value is therefore pinned as a measured
+ * fact, and a test asserts the number itself rather than re-deriving it.
+ *
+ * ⛔ Not a version constant: it decides nothing about whether stored data is
+ * still valid. It is an external protocol value, like an API header.
+ */
+export const NODE_FATAL_ABORT_EXIT_CODE = 134;
+/**
+ * What to do about a child that exited with a code and said nothing.
+ *
+ * 🚨 **This is the SAME event as a signal death, seen on a platform without
+ * signals.** Windows has none, so Node reports its own fatal abort — the heap
+ * limit among them — as an exit code with `signal === null`, where macOS and
+ * Linux report `SIGABRT` with no code at all. An operator hitting the heap limit
+ * on Windows CI deserves the identical remedy as one hitting it on Linux, so the
+ * abort is recognised by its code and {@link signalRemedy} answers both.
+ *
+ * ⚠️ Every OTHER code gets a deliberately non-committal sentence. This command
+ * cannot tell an external termination it has no name for from a bug of its own,
+ * and claiming either would send half its readers to the wrong place — the exact
+ * defect {@link signalRemedy}'s fall-through was written to fix.
+ *
+ * @param code - The exit code the child reported
+ * @returns The remedy sentence
+ */
+function noOutputRemedy(code) {
+    if (code === NODE_FATAL_ABORT_EXIT_CODE) {
+        return ` Exit ${code} is Node's own fatal abort. A platform with no signal to report — Windows`
+            + ' — surfaces as an exit code what macOS and Linux report as SIGABRT itself, and it is the'
+            + ' same event.' + signalRemedy('SIGABRT');
+    }
+    return ` Exit ${code} is not Node's abort code, and the child published none of the document`
+        + ' every path through this command ends by writing — so this is either a termination from'
+        + ' outside that left an exit code instead of a signal, or a defect in vat. The child\'s stderr'
+        + ' was inherited, so whatever it managed to say is above this report; if there is nothing'
+        + ' there either, report this exit code with the platform and the statement that was running.';
+}
+/**
+ * What to DO about it — and the reason the death is carried this far as a union
+ * rather than as a string.
+ *
+ * 🔑 Every kind wants a DIFFERENT file looked at: SIGABRT is the statement,
+ * SIGKILL is the runner's memory, SIGTERM is the job's own timeout, a failed
+ * spawn is either the installation or the runner's load, and a refused kill is a
+ * process still running. A message that conflated any two of them would send
+ * half its readers to the wrong place.
+ *
+ * ⛔ **The last line is for `no-status` and nothing else.** It is the only
+ * ending about which this command genuinely knows nothing, and it used to be
+ * the fall-through for every unpartitioned signal — which produced messages
+ * that named a signal and then denied having any information about it.
+ *
+ * @param death - The ending the supervisor resolved
+ * @returns The remedy sentence
+ */
+function deathRemedy(death) {
+    if (death.kind === 'kill-failed')
+        return killFailedRemedy(death.detail, death.pid);
+    if (death.kind === 'spawn-failed')
+        return spawnFailedRemedy(death.detail) + WATCHDOG_UNINVOLVED;
+    if (death.kind === 'signal')
+        return signalRemedy(death.signal) + WATCHDOG_UNINVOLVED;
+    if (death.kind === 'no-output')
+        return noOutputRemedy(death.code) + WATCHDOG_UNINVOLVED;
+    return ' The cause is outside anything this command can observe; the child left no exit code'
+        + ' to report.' + WATCHDOG_UNINVOLVED;
+}
+/**
+ * The sentence that keeps an abnormal death from being blamed on the bound.
+ *
+ * ⛔ Appended by every arm of {@link deathRemedy} EXCEPT the refused kill, which
+ * writes its own — because there the watchdog is exactly what fired, and this
+ * sentence would repeat in the report the confusion that produced the defect:
+ * an `error` event read as a spawn failure, so `killed` was never consulted.
+ */
+const WATCHDOG_UNINVOLVED = ' The budget was not what ended this run — the watchdog never fired — so raising it'
+    + ' would not help.';
+/**
+ * The sentence that says what this document does NOT contain.
+ *
+ * 🚨 Load-bearing, and shared by both endings. The progress log records COSTS,
+ * not findings: a check that completed contributes its `rows` (how many rows its
+ * statement selected) but not the violations those rows would have become,
+ * because the child never got to turn them into issues. A reader who took the
+ * issue list as the complete account would conclude the finished rules found
+ * nothing.
+ */
+const INCOMPLETE_NOTICE = ' ⚠️ The checks listed under `checks` DID complete and `rows` is what each'
+    + ' statement selected, but their individual violations are NOT in `issues`: the'
+    + ' progress log records costs, not findings. Read that list as incomplete.';
+/**
+ * The finding for a run that was interrupted, however it was interrupted.
+ *
+ * 🪤 **`RUN_INTEGRITY_CODE`, for the reason that constant gives.** An
+ * interrupted run must never be silenceable by the config of the very project
+ * whose SQL hung.
+ *
+ * 🔑 **This is the MORE SPECIFIC of two claims that can be true at once.** A run
+ * killed before its first statement completed recovers zero costs, which
+ * {@link noCheckRanFinding} also refuses — so that one stands down when this
+ * one is present. The dedupe there is order-independent (`issues.some(code ===
+ * RUN_INTEGRITY_CODE)`), so this finding only has to be IN the issue list of an
+ * interrupted document, not first in it.
+ *
+ * @param inFlight - What the run was doing when the log stopped growing
+ * @param ending - Which way the run ended, and what the operator can do
+ * @returns The run-integrity finding
+ */
+function interruptedRunFinding(inFlight, ending) {
+    const where = inFlightPhrase(inFlight);
+    const message = ending.kind === 'budget'
+        ? budgetKillMessage(inFlight, ending.budgetSecs, where)
+        : `This run DIED before it finished: ${deathPhrase(ending.death)} ${where}, so the checks`
+            + ' after it never executed and this document is not a verdict.'
+            + deathRemedy(ending.death);
+    return runIntegrityFinding(message + INCOMPLETE_NOTICE);
+}
+/**
+ * What a WATCHDOG kill means, which depends entirely on what was in flight.
+ *
+ * 🚨 **The defect this closes: the `reporting` state got the statement-hang
+ * body.** Creating that state adapted only the *where* clause, so a run whose
+ * ten checks had ALL completed and whose 1,000,000-issue document blew the
+ * budget was told "the checks after it never executed" and "a statement that
+ * will not finish cannot be stopped from inside the process — the query is
+ * synchronous and holds the event loop". Measured on that run: `checksRun: 10`,
+ * all ten costs present, no statement running, nothing holding the loop for any
+ * SQL reason. The operator was sent to hunt a hanging rule that does not exist,
+ * and the message never mentioned the thing that actually killed the run.
+ *
+ * ⚠️ It is easy to reach on a real gate, not a curiosity: serialising 2,000,000
+ * issues takes ~17 s after `checks-complete` is filed, which is one budget
+ * window on its own.
+ *
+ * @param inFlight - What the log's last state says
+ * @param budgetSecs - The bound that was blown
+ * @param where - The clause naming the unit, from {@link inFlightPhrase}
+ * @returns The message body
+ */
+function budgetKillMessage(inFlight, budgetSecs, where) {
+    if (inFlight.kind === 'reporting') {
+        return `This run made no progress for ${budgetSecs}s and was killed ${where}.`
+            + ' Every declared check had already finished and filed its cost, so no statement was'
+            + ' running and there was nothing left to execute: the cause is the SIZE of the document'
+            + ' being assembled, not a rule that would not return. Serialising a large result is'
+            + ' linear in how much there is — 2,000,000 issues take about 17 seconds — so look at'
+            + ' the rules under `checks` that produced the most rows and narrow them (a `LIMIT`, or'
+            + ' one row per violation rather than one per member), or raise the bound with'
+            + ' `--budget <seconds>` so the document has time to be written.';
+    }
+    return `This run made no progress for ${budgetSecs}s and was killed ${where}, so the`
+        + ' checks after it never executed and this document is not a verdict.'
+        + ' A statement that will not finish cannot be stopped from inside the process —'
+        + ' the query is synchronous and holds the event loop — so the bound is enforced by'
+        + ' killing the run. Raise it with `--budget <seconds>` if the work is legitimately'
+        + ' slow, or `--budget 0` to remove it (the run can then hang forever).';
+}
+/**
+ * The refusal when there is no population line to build a document from.
+ *
+ * Separate wording per ending for the same reason the finding is: telling an
+ * operator whose child was OOM-killed to raise `--budget` sends them to change
+ * the one thing that had nothing to do with it.
+ *
+ * @param ending - Which way the run ended
+ * @returns The operator-error message
+ */
+function noPopulationMessage(ending) {
+    const tail = ' There is no projection to report on and no honest document to publish.';
+    if (ending.kind === 'abnormal') {
+        return `This run DIED before its population completed: ${deathPhrase(ending.death)}.`
+            + tail + deathRemedy(ending.death);
+    }
+    return `The run made no progress for ${ending.budgetSecs}s and was killed before its`
+        + ' population completed.' + tail
+        + ' Population is legitimately slow on a large tree, and it reports progress only when it'
+        + ' FINISHES, so the budget is a total bound for that one unit — raise it with'
+        + ' `--budget <seconds>` before assuming the crawl is stuck.'
+        + ' For scale, two MEASURED trees, neither of them yours: VAT\'s own repository is ~1.2s'
+        + ' warm and 33-35s with a cold parse cache; a 10,000-file adopter tree is ~5s warm and'
+        + ' 16.5s cold. Your tree is a third number.';
+}
+/**
+ * Rebuild the document from what an INTERRUPTED run left on disk.
+ *
+ * Both interruptions come here — the watchdog's kill and an abnormal death —
+ * because everything below this line is identical for them: the same recovered
+ * costs, the same non-overridable finding, the same refusal when there is no
+ * population. Only the sentences differ, and {@link CheckRunEnding} carries that.
+ *
+ * 🔑 It feeds {@link buildCheckOutputData}, the SAME builder a completed run
+ * uses. A second payload builder for this lane would be a second shape to
+ * keep in step with every future field — and the failure mode is silent, because
+ * nobody reads an interrupted run's document until the day they need it.
+ *
+ * 🚨 **A run interrupted during POPULATION gets no document at all.** There is no
+ * projection, so `population`, `populationSecs` and `membersEnumerated` have no
+ * honest value — and inventing `membersEnumerated: 0` would be worse than a
+ * blank, because that value already MEANS "this gate ran over an empty corpus",
+ * which is a different and wrong claim. The throw becomes an operator error
+ * (exit 2) through the same `handleReportCommandError` path everything else here uses.
+ *
+ * @param options - The wreckage
+ * @param options.entries - What `parseProgressLog` recovered
+ * @param options.root - The corpus root the parent resolved
+ * @param options.ending - Which way the run was interrupted
+ * @param options.durationMs - Wall time from spawn to ending
+ * @returns The input to {@link buildCheckOutputData}
+ * @throws When the child never reported a completed population
+ */
+export function buildInterruptedCheckInput(options) {
+    const { entries, root, ending, durationMs } = options;
+    const population = entries.find((entry) => entry.kind === 'population');
+    if (population === undefined)
+        throw new Error(noPopulationMessage(ending));
+    return {
+        root,
+        durationMs,
+        population: population.population,
+        populationMs: population.populationMs,
+        lensMs: population.lensMs,
+        lensesEvaluated: population.lensesEvaluated,
+        membersEnumerated: population.membersEnumerated,
+        issues: [interruptedRunFinding(unitInFlight(entries), ending)],
+        // 🪤 Rebuilt field by field rather than passed through. The log's check
+        // entry carries a `kind` discriminator that `CheckCost` does not, and the
+        // conditional spreads keep `rows`/`broken` ABSENT rather than `undefined` —
+        // which is what makes `rows: 0` on a statement that never returned
+        // impossible, exactly as it is on the completed path.
+        costs: entries.filter((entry) => entry.kind === 'check').map((entry) => ({
+            name: entry.name,
+            durationMs: entry.durationMs,
+            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+            ...(entry.broken === undefined ? {} : { broken: entry.broken }),
+            ...(entry.builtin === undefined ? {} : { builtin: entry.builtin }),
+        })),
+    };
+}
+/**
+ * Run this project's checks — VAT's default set plus whatever the project
+ * declared — and resolve their severities: the whole of this verb's logic, with
+ * the database taken out.
+ *
+ * 🔑 **`builtins` is a required argument beside `checks`, never a default inside
+ * this function.** That is what makes "the default set belongs to the pipeline,
+ * not to the config file" a property of the signature — nobody can get the
+ * defaults by omitting an argument or lose them by supplying no config.
+ *
+ * Exported and pure so the loop is provable without a spawn. It was not: every
+ * spawned case declared ONE check (the `--check` case declares two and filters
+ * to one, which the loop cannot distinguish), so `checksRun` was never observed
+ * above 1 and a `break` at the end of the loop would have left the suite green.
+ *
+ * Pure in the same sense the payload builder is, with ONE seam: it reads a
+ * clock. That is why the clock is a parameter — the measurement is the point of
+ * the `costs` it returns, and a duration nothing can pin is a number nobody can
+ * trust.
+ *
+ * @param options - The run
+ * @param options.builtins - The default set, already bound to this run's
+ *   projection. Required, and `[]` is a deliberate statement rather than an
+ *   omission
+ * @param options.checks - The declared checks
+ * @param options.only - A single check name, or undefined for all
+ * @param options.ask - Runs one statement against the populated projection
+ * @param options.validation - The project's severity overrides, or undefined
+ * @param options.membersEnumerated - How many members the population enumerated.
+ *   Told rather than asked, because no answer can reveal it: an `ask` over an
+ *   empty projection and an `ask` over a clean one both return no rows
+ * @param options.now - The measurement clock in milliseconds, defaulting to
+ *   `performance.now()`. Injected only so a unit test can pin an exact per-check
+ *   duration; nothing in production passes it
+ * @param options.onProgress - Where each check's `start` and cost are announced
+ *   so an outside supervisor can see them, or undefined when the run is not
+ *   supervised. Optional rather than required because `--budget 0` and every
+ *   unit case run with nobody watching
+ * @returns The resolved findings, and one cost record per check that ran
+ */
+export function runProjectChecks(options) {
+    const now = options.now ?? (() => performance.now());
+    const { issues, costs } = runUnits(checkUnits(options.builtins, options.checks, options.ask), options.only, now, options.onProgress);
+    // 🚨 HERE, and this line moved to get here. `checks-complete` buys the phase
+    // after the last statement a fresh watchdog window, and three places
+    // documented that phase as "resolving severities and serialising". It was
+    // emitted a level up, by `runOutcome`, AFTER this function returned — so
+    // `resolveIssueSeverity` below ran inside the LAST CHECK's window and the
+    // documented claim was false for the half of the phase that is quadratic in
+    // the issue count. Emitting it before that call is what makes the claim true,
+    // which is the useful direction: the alternative was to weaken three docs.
+    //
+    // ⚠️ It does NOT cover the last check's row-to-issue conversion, which
+    // `runUnits` does after filing that check's cost — see {@link inFlightPhrase}
+    // for why the `idle` sentence still has to hedge for that window.
+    options.onProgress?.({ kind: 'checks-complete' });
+    // The run-integrity report leads. An aggregate check selects a row whatever
+    // the corpus is, so its findings can outnumber this one — and every one of
+    // them is noise until the operator knows the gate ran over nothing.
+    const reported = [...emptyCorpusFinding(costs.length, options.membersEnumerated), ...issues];
+    return {
+        // The adopter's own `resources.validation.severity` still applies, so a
+        // check inherited from a shared config can be downgraded or ignored without
+        // editing it. Applied AFTER the run, never before: a check that is going to
+        // be ignored must still be EXECUTED, or "ignored" would quietly become
+        // "never checked" and those are different claims.
+        //
+        // It reaches a check's VIOLATIONS only. `RESOURCE_CHECK_BROKEN` is not an
+        // overridable code, so the news that a check stopped checking survives every
+        // override an adopter can write about the check itself.
+        //
+        // 🔑 A BUILT-IN's findings pass through the identical call, under their
+        // ordinary registry code: `severity: { CLAUDE_RULE_GLOB_INERT: ignore }`
+        // silences the default exactly as it silences any other code VAT emits, with
+        // no `CUSTOM:` spelling and no second override surface. That the two lanes
+        // share this one line is the reason there is nothing to keep in step.
+        issues: resolveIssueSeverity(reported, options.validation),
+        costs,
+    };
+}
+/**
+ * Serialize the document in the format the operator asked for.
+ *
+ * Extracted because BOTH endings publish one — a completed run and a killed one
+ * — and two copies of a two-branch format switch is how one of them ends up
+ * ignoring `--format json`.
+ *
+ * @param payload - The document
+ * @param format - `json`, or anything else for YAML
+ */
+function emitCheckDocument(payload, format) {
+    writeStructuredOutput(payload, format);
+}
+/**
+ * The child's argv — this very command, plus the hidden flag that stops it
+ * spawning a child of its own.
+ *
+ * 🚨 `--cost-log` is ALWAYS appended, and that is the recursion guard. Its
+ * presence is the sole discriminator between "supervise a child" and "do the
+ * work"; a path that built these arguments without it would fork bomb.
+ *
+ * @param pathArg - The corpus root the operator named, or undefined
+ * @param options - What the operator passed
+ * @param logPath - The progress log both sides watch
+ * @returns The child's arguments after the CLI entry point
+ */
+function childArgs(pathArg, options, logPath) {
+    return [
+        'resources',
+        'check',
+        ...(pathArg === undefined ? [] : [pathArg]),
+        ...(options.check === undefined ? [] : ['--check', options.check]),
+        ...(options.format === undefined ? [] : ['--format', options.format]),
+        ...(options.debug === true ? ['--debug'] : []),
+        '--cost-log',
+        logPath,
+    ];
+}
+/**
+ * Run the checks in a child bounded by `budgetSecs`, and report either what it
+ * said or what killing it revealed.
+ *
+ * 🪤 The endings are RETURNED rather than exited on from inside
+ * `withProgressLog`. `process.exit` skips a `finally`, so exiting in there would
+ * leak the temp directory on every single run — and it is the successful runs,
+ * which are all of them but one, that would accumulate.
+ *
+ * @param options - The run
+ * @param options.pathArg - The corpus root the operator named, or undefined
+ * @param options.options - What the operator passed
+ * @param options.budgetSecs - The bound, in seconds
+ * @returns What to publish, and with what exit code
+ * @throws When the child was killed before its population completed
+ */
+async function superviseCheckRun(options) {
+    const startDir = options.pathArg ?? process.cwd();
+    // 🪤 The SILENT resolution, deliberately. `projectRootOrLoudCwd` warns on
+    // stderr when there is no project ancestor, and the CHILD runs that policy for
+    // real — a parent that ran it too would print the same warning twice for one
+    // run. The parent needs a root only to label a KILLED run's document.
+    const root = projectRootOrNull(startDir) ?? safePath.resolve(startDir);
+    return withProgressLog(async (logPath) => {
+        const run = await superviseCheck({
+            args: childArgs(options.pathArg, options.options, logPath),
+            logPath,
+            budgetMs: options.budgetSecs * 1000,
+        });
+        if (run.outcome === 'completed')
+            return { forward: run.stdout, code: run.code };
+        return {
+            payload: buildCheckOutputData(buildInterruptedCheckInput({
+                entries: parseProgressLog(run.log),
+                root,
+                // 🚨 The abnormal ending reaches the SAME fail-closed document the
+                // watchdog's kill does. It used to reach `{ outcome: 'completed', code:
+                // 0 }` instead, because the close handler never read `close`'s signal
+                // argument — so a child that aborted on its heap limit printed nothing
+                // and exited 0, on precisely the runaway shape the bound exists for.
+                ending: run.outcome === 'killed'
+                    ? { kind: 'budget', budgetSecs: options.budgetSecs }
+                    : { kind: 'abnormal', death: run.death },
+                durationMs: run.elapsedMs,
+            })),
+        };
+    });
+}
+/**
+ * Run the project's declared checks against its projection.
+ *
+ * ## 🚨 Why this verb spawns a child and `vat resources query` does not
+ *
+ * Both verbs run SQL an adopter wrote, over the same projection, through the
+ * same `withQueriedProjection` — which does NOT diverge here, and must not. The
+ * fork is this function and nothing below it.
+ *
+ * `query`'s author is at the keyboard, and Ctrl-C already works for them. It
+ * works for one reason worth stating, because it is fragile: NO signal handler
+ * is installed anywhere on this path. A process blocked in synchronous
+ * `node:sqlite` dies instantly on SIGINT while that remains true, and SURVIVES
+ * SIGINT and SIGTERM the moment a handler exists — the handler is a JS callback
+ * and the event loop that would schedule it is the blocked resource. Adding one
+ * would take Ctrl-C away from `query` without adding anything to `check`.
+ *
+ * `check` runs unattended in CI, where nobody is there to press it. So it gets a
+ * bound enforced from outside itself, and a hang becomes a bounded failure
+ * instead of a job that burns its runner minutes and reports nothing.
+ *
+ * ## `[path]` locates the project; a `WHERE` clause is the only scope a check has
+ *
+ * Same contract as `vat resources query`, for the same reason (see
+ * `queryCommand`): the projection is the whole tracked tree, so the argument is
+ * where root discovery starts and nothing more. A locator that names no
+ * directory is refused HERE, before the fork below — the parent would otherwise
+ * resolve it silently to the cwd's project and spawn a child to run every check
+ * over a tree the operator did not name, at exit 0.
+ *
+ * @param pathArg - Where to look for the project, or omitted for the current directory
+ * @param options - Parsed command-line options
+ */
+export async function checkCommand(pathArg, options) {
+    const logger = createLogger({ debug: options.debug ?? false });
+    const startTime = Date.now();
+    try {
+        if (pathArg !== undefined)
+            assertDirectoryArgument(pathArg);
+        const budgetSecs = parseBudgetSeconds(options.budget);
+        // Before anything is spawned: a budget the fork below would silently ignore
+        // is an operator error, not a bound.
+        requireSupervisableFlags({
+            costLog: options.costLog,
+            budgetRaw: options.budget,
+            budgetSecs,
+        });
+        // The presence of `--cost-log` says "you ARE the child". `--budget 0` says
+        // the operator declined the bound; both run the work here, and the second
+        // can therefore hang forever, which its help text says.
+        if (!runsInThisProcess({ costLog: options.costLog, budgetSecs })) {
+            const ending = await superviseCheckRun({ pathArg, options, budgetSecs });
+            if ('forward' in ending) {
+                // Verbatim. The child already built the document the operator's
+                // `--format` asked for, and re-serializing it here would be a second
+                // place for that shape to live.
+                //
+                // ⚠️ `durationSecs` in it is therefore the CHILD's wall time and does
+                // not include this process's own startup and spawn (~0.15 s measured).
+                // Deliberate: the field is a breakdown that `populationSecs` and the
+                // per-rule costs have to reconcile against, and folding in a supervisor
+                // overhead none of them can account for would leave a remainder a
+                // reader would attribute to whichever rule they were looking at — the
+                // exact defect `CheckCost` documents.
+                writeStdoutSync(ending.forward);
+                process.exit(ending.code);
+            }
+            emitCheckDocument(ending.payload, options.format);
+            // ⛔ Never OK. A run that did not finish — killed by the watchdog OR dead of
+            // its own memory — must not look like a pass. FINDINGS, because the
+            // document it just published says `status: findings` with the killed
+            // check named as one: the checks that completed are kept, and the exit
+            // code follows the document, as everywhere else.
+            process.exit(ExitCode.FINDINGS);
+        }
+        const projectRoot = projectRootOrLoudCwd(pathArg ?? process.cwd(), logger);
+        const config = loadConfigCached(projectRoot);
+        const checks = config?.resources?.checks;
+        if (checks === undefined || Object.keys(checks).length === 0) {
+            // 🪤 Stderr only, and it decides NOTHING — the document is what the exit
+            // code is computed from and what CI parses. ⚠️ It does not stand beside a
+            // refusal: the built-in set runs here, so this run DID assert something.
+            // What the operator needs to know is that the project is relying entirely
+            // on VAT's defaults, which is what a deleted `checks:` block looks like.
+            logger.warn(`No checks of this project's own are declared, so this run asserted only VAT's`
+                + ` built-in set (${BUILTIN_CHECK_NAMES.join(', ')}).`
+                + ' Add your own under `resources.checks` in vibe-agent-toolkit.config.yaml;'
+                + ' each is a description plus one SQL statement selecting the rows that VIOLATE it.'
+                + ' `vat resources check --help` prints the SQL each built-in is equivalent to,'
+                + ' as a starting point.');
+        }
+        // Before the crawl: a mistyped flag is an operator error and pays nothing.
+        requireKnownCheck(BUILTIN_CHECK_NAMES, checks ?? {}, options.check);
+        // Also before the crawl, and for the same reason: an override that overrides
+        // nothing is knowable from the config alone, and the operator should read it
+        // beside the other config news rather than after a full population.
+        warnUndeclaredOverrides(checks ?? {}, config?.resources?.validation, logger);
+        const outcome = await runOutcome({
+            root: projectRoot,
+            checks: checks ?? {},
+            only: options.check,
+            logger,
+            validation: config?.resources?.validation,
+            onProgress: options.costLog === undefined
+                ? undefined
+                : createProgressWriter(options.costLog),
+        });
+        const payload = buildCheckOutputData({
+            ...outcome,
+            root: projectRoot,
+            durationMs: Date.now() - startTime,
+        });
+        emitCheckDocument(payload, options.format);
+        process.exit(payload.summary.errors > 0 ? ExitCode.FINDINGS : ExitCode.OK);
+    }
+    catch (error) {
+        handleReportCommandError(error, logger, startTime, 'Check', options.format);
+    }
+}
+/**
+ * Populate once, run the checks, resolve their severities.
+ *
+ * @param options - The run
+ * @param options.root - Absolute corpus root
+ * @param options.checks - The declared checks
+ * @param options.only - A single check key, or undefined for all
+ * @param options.logger - Where blob-stage refusals are reported
+ * @param options.validation - The project's severity overrides, or undefined
+ * @param options.onProgress - Where each unit is announced for a supervisor
+ *   outside this process, or undefined when nothing is watching
+ * @returns The findings and the provenance of the population behind them
+ */
+async function runOutcome(options) {
+    const { root, checks, only, logger, validation, onProgress } = options;
+    // 🪤 **No `preflight` here, deliberately.** `withQueriedProjection` can compile
+    // statements against the empty schema before populating — `vat resources query`
+    // passes its one statement and gets a typo back in milliseconds instead of
+    // after a full population. This verb must NOT, because a check that cannot run
+    // is not an operator error here: it is a `RESOURCE_CHECK_BROKEN` finding naming
+    // the check, at `error`, in a document that also reports how big the corpus was
+    // and what the population cost. Failing early would trade that document for a
+    // bare throw, and the finding exists precisely so a renamed column cannot end a
+    // gate quietly. The population is the price of an honest report, and it is
+    // charged once for every check rather than per broken one.
+    // 🔑 `statements` IS passed, and it is a different question from `preflight`:
+    // it only decides which derived relations are evaluated. Every declared
+    // statement goes in, including one `--check` narrows away — the lens is per
+    // RUN, and narrowing it would make `--check foo` and a full run disagree about
+    // which relations exist.
+    const statements = Object.values(checks).map((check) => check.sql);
+    return withQueriedProjection({ root, logger, statements }, (ask, provenance, extent, projection) => {
+        // 🔑 Emitted HERE, inside the callback, because this is the one place where
+        // the provenance and the extent are both exactly in hand — and emitted the
+        // INSTANT population completes, because its arrival is what tells a
+        // supervisor that a kill has a projection to report on. It also resets the
+        // watchdog, so the population is bounded by the budget without being charged
+        // the first check's share of it.
+        onProgress?.({
+            kind: 'population',
+            population: provenance.population,
+            populationMs: provenance.populationMs,
+            lensMs: provenance.lensMs,
+            lensesEvaluated: [...provenance.lensesEvaluated],
+            membersEnumerated: extent.membersEnumerated,
+        });
+        // 🪤 `checks-complete` is NOT emitted here. It used to be, and that put
+        // `resolveIssueSeverity` — which runs inside `runProjectChecks` — on the
+        // wrong side of the line, still charged to the last check's budget window
+        // while three separate docs said otherwise. It is emitted by
+        // `runProjectChecks` itself now, the instant the last statement is done.
+        //
+        // 🔑 The DEFAULT SET enters HERE, from a module constant bound to the
+        // projection — never from `config`, which this line does not read. That is
+        // the placement the "defaults belong to the pipeline" invariant is about.
+        const ran = runProjectChecks({
+            builtins: bindBuiltinChecks(projection),
+            checks,
+            only,
+            ask,
+            validation,
+            ...extent,
+            onProgress,
+        });
+        return { ...ran, ...provenance, ...extent };
+    });
+}
+//# sourceMappingURL=check.js.map