@vibe-agent-toolkit/cli 0.2.0-rc.7 → 0.2.0-rc.9

package/dist/commands/resources/check.d.ts

@@ -1,168 +1,36 @@
 /**
- * `vat resources check` — run the project's own SQL assertions over its
- * resource projection.
- *
- * ## Why this verb exists when `vat resources query` already runs SQL
- *
- * A query answers a question once. A question worth asking twice is a rule, and
- * a rule that lives in someone's shell history is not enforced — it decays into
- * a comment. This verb runs the statements a project wrote into
- * `resources.checks`, turns each violating row into an ordinary validation
- * finding, and exits non-zero when any of them is an error. That is the whole
- * difference, and it is the difference between a tool and a gate.
- *
- * ## 🔑 A broken check is an ERROR, never a skip
- *
- * VAT ships no schema version, so a renamed column simply breaks a check's SQL.
- * The tempting handling — log it and carry on — is the one thing this must never
- * do: a check that stopped running looks exactly like a check that passed, and
- * the project keeps reporting green over an assertion nobody is making any more.
- * So a statement that will not run is reported as a finding at **error**
- * severity, with the columns the projection actually has, and it fails the run.
- *
- * That report carries its OWN code (`RESOURCE_CHECK_BROKEN`), which no
- * `validation.severity` entry can reach. A check's severity override is about how
- * bad a VIOLATION is; while the two shared the code `CUSTOM:<name>`, the
- * documented way to stand down an inherited check also silenced the news that it
- * had stopped checking. See the `catch` in `runChecks`.
- *
- * ## 🔑 An empty CORPUS is a refusal too, not a pass
- *
- * The same class one level further out, and the one that shipped. `checksRun` is
- * the denominator of RULES; nothing counted the ROWS, so a repository whose
- * enumeration came back empty — a broad `.gitignore`, a shallow or sparse CI
- * checkout, a root that resolved somewhere else — ran every declared check over
- * nothing and reported `status: success` on exit 0 with empty stderr. Population
- * declines ignored members rather than flagging them, so the tables held no
- * trace of it either.
- *
- * So the population's size is published (`membersEnumerated`), and a run whose
- * checks executed over zero members is an ERROR under the same non-overridable
- * code as a broken statement — see {@link emptyCorpusFinding}. A gate that
- * asserts nothing over nothing has not passed.
- *
- * ## 🔑 An unknown `--check` name is a refusal, not an empty pass
- *
- * The same failure class one flag over: a filter that matched nothing ran nothing
- * and exited 0. `requireDeclaredCheck` refuses it before the crawl, naming the
- * declared set. A gate that cannot fail is worse than no gate.
- *
- * ## 🔑 NO checks at all is the same refusal, and the one that shipped longest
- *
- * A project with a valid config and no `checks:` block reported `status:
- * success`, `checksRun: 0`, exit 0 — so DELETING the `checks:` block silently
- * deleted the gate and nothing anywhere said so. A gate that checked nothing is
- * indistinguishable from a gate that was removed, and the entire argument for
- * having these gates is that you never let those two look alike. It is now a
- * `RESOURCE_CHECK_BROKEN` error like the other three — see
- * {@link noCheckRanFinding}, and `RUN_INTEGRITY_CODE` for why one code
- * covers all four. Declaring no checks is a legitimate CHOICE; running a gate
- * that can only pass is not, so the remedy is to take the command out of the
- * pipeline.
- *
- * ## 🔑 SQL is the surface a user OPTED IN to, so no BUILT-IN check may be SQL
- *
- * Every check this verb runs is adopter-declared: {@link checkCommand} reads
- * `config?.resources?.checks` and nothing else, and warns loudly when a project
- * declares none. There are no built-ins, and the one way to end that quietly is
- * to author the first one as SQL. A default-on rule written as a statement makes
- * the engine, the projection and the population mandatory for everyone who
- * inherits it, without anybody deciding that. So: **built-ins are TypeScript
- * predicates over the projection's row model.** SQL stays the two places a user
- * asked for it — this verb's declared checks, and `vat resources query`.
- *
- * ⚠️ The engine today is `node:sqlite`, built into Node, so the thing at stake is
- * not an install — it is the POPULATION. On an ~11,700-member adopter tree
- * building the projection is **>99.9%** of a check run (16.5 s cold, ~1.3 s from
- * the store) against **0.0008–0.004 s** for the statements themselves; see
- * `vat-knowledge-resources.md`, which carries that measurement. That is exactly
- * the cost "What this does NOT do" below refuses to put on every adopter's
- * pre-commit path, and a default-on SQL check would put it there without the
- * decision. The INSTALL cost is deferred rather than gone: the open question
- * about a columnar engine is a 108 MB platform binding on a published toolkit,
- * and this invariant is what keeps that question still answerable either way.
- *
- * ## 🔑 The DEFAULT check set belongs to the pipeline, not to the config file
- *
- * A directory with no `vibe-agent-toolkit.config.yaml` must run exactly the same
- * default-on checks as one with a config; config only ADDS to that set or
- * OVERRIDES a severity in it. This is load-bearing rather than a convenience:
- * *"'default-on error' is meaningless as a category if being default-on requires
- * a config file to say so."*
- *
- * It is therefore a constraint on WHERE the defaults live in code, not only on
- * what they are. They cannot be defaulted into the parsed config object, because
- * an absent config is `undefined` and every default would vanish with it — for
- * the project that never wrote one, which is the population the category exists
- * for. The rest of VAT already behaves this way and is the shape to match:
- * `vat audit` completes its entire scan first and reads config only to apply
- * severity overrides, warning and CONTINUING when the file cannot be read; and
- * `loadResourcesWithConfig` hands `vat resources validate` a registry whose
- * built-in validators run whether `loadConfig` returned a config or nothing.
- * This verb has no defaults yet, so the invariant is a rule for the first one —
- * and the day it is written is the easiest day to break it.
- *
- * ## Keeping a TypeScript check and its SQL twin: two good reasons, one trap
- *
- * The proposal was "write the predicate twice, in TypeScript and in SQL, and run
- * whichever is faster". Two thirds of it are worth having.
- *
- * ✅ **As documentation.** An SQL twin is executable documentation of the row
- * model, and strictly better than prose about it: prose can describe a column
- * that no longer exists and never say so, while a statement stops compiling —
- * which this verb reports as `RESOURCE_CHECK_BROKEN` rather than as a skip.
- *
- * ✅ **As a differential oracle.** Run both over the frozen corpus and assert
- * IDENTICAL findings. That is the only thing which makes a dual implementation
- * better than a single one rather than worse: two implementations with no
- * mandatory differential test are simply two places for one rule to be wrong.
- * Apply it selectively, to genuinely relational checks — done by default, every
- * new rule costs three artifacts instead of one.
- *
- * ⛔ **As a runtime optimizer — rejected, on two INDEPENDENT grounds.** It would
- * essentially never choose SQL: `buildResourceProjection` hands the rows back in
- * memory before the ephemeral database exists at all, so the TypeScript arm is a
- * for-loop over data already in hand, and the SQL arm's whole measured share of a
- * run is the 0.0008–0.004 s above. A scheduler would be choosing between two
- * arms of the 0.1%. And it reintroduces the dependency through the back door: an
- * optimizer that MAY choose SQL means SQL MAY be needed at check time, which for
- * anyone shipping the thing is the same as needed. **Optionality is not a
- * property you can keep while also letting a scheduler reach for the optional
- * thing.**
- *
- * ## 🔑 Adopter SQL runs UNSANDBOXED on purpose — and contributed SQL is not adopter SQL
- *
- * What a statement may BE is gated hard, and documented where it is enforced:
- * `assertIsQuery` and `detachForeignSchemas` in
- * `packages/projection-sqlite/src/store.ts` refuse `ATTACH` and `PRAGMA`, with
- * the measured cross-repository leak that motivated both, and CHANGELOG.md's
- * `--budget` entry carries why nothing inside this process can interrupt a
- * runaway statement. Read those; do not restate them here.
- *
- * What is written down nowhere else is that everything PAST those gates is
- * unsandboxed deliberately. A `.sql` file the adopter points their own config at
- * is adopter code, at the same trust boundary as their eslint config: they wrote
- * it or they chose to inherit it, and VAT is not the thing standing between a
- * project and its own repository.
- *
- * 🚨 That reasoning covers exactly ONE trust domain, and the rule scoping it is
- * the other half: **contributed SQL is a reviewed EXAMPLE, never an
- * auto-executed check.** A contribution channel is third-party text, and a
- * statement arriving through one has none of the "they chose it" the paragraph
- * above rests on. Ship it as documentation an adopter copies into their own
- * `resources.checks` deliberately. One paragraph must not be stretched to cover
- * both domains.
- *
- * ## What this does NOT do
- *
- * It does not fold into `vat resources validate`. That command is on every
- * adopter's pre-commit path, and adding a store-backed population to it is a
- * cost and a risk that deserves its own decision with its own evidence. Wiring
- * this into CI is one line in a workflow; making it unavoidable is not this
- * change's call to make.
+ * `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 { type ResourceCheck } from '@vibe-agent-toolkit/resources';
-import { type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { type BoundBuiltinCheck, type ResourceCheck } from '@vibe-agent-toolkit/resources';
+import { type Report, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
 import { type SeverityOverrides } from '../../utils/issue-severity.js';
 import { type Logger } from '../../utils/logger.js';
 import { type AskProjection, type PopulationExtent, type ProjectionProvenance } from '../../utils/projection-query.js';
@@ -198,33 +66,27 @@ interface CheckOptions {
 /**
  * What one declared check cost, and what it found.
  *
- * ## 🚨 The population is charged to NOBODY, and that is deliberate
- *
- * {@link durationMs} is the STATEMENT alone. The git tracker, the projection
- * build and the load into the ephemeral database happen ONCE and serve every
- * check in the run, so folding that shared setup into each rule would make N
- * cheap rules look expensive and make the per-rule numbers sum to N times a cost
- * paid once. It is published separately instead — `populationSecs` beside
- * `population` in the document — so a reader can reconcile the parts against
- * `durationSecs` rather than inferring the remainder and attributing it to
- * whichever rule they happen to be reading.
- *
- * 🪤 This repo has already shipped the opposite mistake once, in another
- * instrument: `parse ab` reported a pooled arm BACKWARDS because its estimate
- * was thread-summed, and the report surfaced no caveat that would have told the
- * reader. A shared cost silently attributed to one participant is the same
- * defect wearing different clothes. If you ever want the population inside these
- * numbers, divide it out explicitly and say so in the field name.
+ * 🚨 **The population is charged to NOBODY, and that is deliberate.**
+ * {@link durationMs} is the STATEMENT alone; the shared setup is published as
+ * `populationSecs`. Why, and the pooled-arm defect this avoids:
+ * `docs/architecture/cli.md`, "The population is charged to NOBODY".
  */
 export interface CheckCost {
-    /** The check's key in `resources.checks`. */
+    /** The check's key in `resources.checks`, or a built-in's name. */
     readonly name: string;
-    /** Wall time of this check's statement, and of nothing it shares with others. */
+    /** Wall time of this check's selection, and of nothing it shares with others. */
     readonly durationMs: number;
-    /** Rows the statement returned — the violations it selected. Absent when the statement did not run. */
+    /** Rows the selection returned — the violations it found. Absent when it did not run. */
     readonly rows?: number;
-    /** Set when the statement threw. A statement that did not complete has no row count. */
+    /** Set when the check threw. One that did not complete has no row count. */
     readonly broken?: true;
+    /**
+     * Set when VAT supplied this check rather than the project. 🔑 Without it a
+     * reader whose config declares nothing finds a rule they never wrote in
+     * `checks[]` with no way to tell a default from a stale declaration — or, when
+     * a project declares a check of the same name, to tell the two entries apart.
+     */
+    readonly builtin?: true;
 }
 /** What one run of the checks produced. */
 interface CheckOutcome extends ProjectionProvenance, PopulationExtent {
@@ -245,6 +107,229 @@ export interface CheckPayloadInput extends CheckOutcome {
     root: string;
     durationMs: number;
 }
+/**
+ * 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 declare const CheckDataSchema: z.ZodObject<{
+    root: z.ZodString;
+    /** Whether the projection was derived this run or read from the store. */
+    population: z.ZodEnum<["derived", "store"]>;
+    /** What the population cost — charged to no check, see `CheckCost`. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the first statement ran. */
+    lensSecs: z.ZodNumber;
+    /**
+     * 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.ZodArray<z.ZodString, "many">;
+    /**
+     * The prose frame {@link CheckDataSchema.limits} is read under. Present
+     * exactly when a lens with stated bounds was evaluated.
+     */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        direction: z.ZodEnum<["over-report", "under-report", "scope", "assumption"]>;
+        statement: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }>, "many">>;
+    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
+    checksRun: z.ZodNumber;
+    /** What each rule cost, directly under the denominator it is the breakdown of. */
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
+        durationSecs: z.ZodNumber;
+        /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
+        rows: z.ZodOptional<z.ZodNumber>;
+        broken: z.ZodOptional<z.ZodLiteral<true>>;
+        /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
+        builtin: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>;
+export type CheckData = z.infer<typeof CheckDataSchema>;
+/** The document this command publishes. */
+export declare const CHECK_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    root: z.ZodString;
+    /** Whether the projection was derived this run or read from the store. */
+    population: z.ZodEnum<["derived", "store"]>;
+    /** What the population cost — charged to no check, see `CheckCost`. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the first statement ran. */
+    lensSecs: z.ZodNumber;
+    /**
+     * 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.ZodArray<z.ZodString, "many">;
+    /**
+     * The prose frame {@link CheckDataSchema.limits} is read under. Present
+     * exactly when a lens with stated bounds was evaluated.
+     */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        direction: z.ZodEnum<["over-report", "under-report", "scope", "assumption"]>;
+        statement: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }>, "many">>;
+    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
+    checksRun: z.ZodNumber;
+    /** What each rule cost, directly under the denominator it is the breakdown of. */
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
+        durationSecs: z.ZodNumber;
+        /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
+        rows: z.ZodOptional<z.ZodNumber>;
+        broken: z.ZodOptional<z.ZodLiteral<true>>;
+        /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
+        builtin: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>>;
+export type CheckReport = Report<CheckData>;
 /**
  * Build the check report.
  *
@@ -260,7 +345,7 @@ export interface CheckPayloadInput extends CheckOutcome {
  * account for it cannot disagree.
  *
  * 🚨 `populationSecs` and the per-check `durationSecs` do not overlap and do not
- * sum to `durationSecs`. The population is paid once and shared by every check;
+ * 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
@@ -268,39 +353,54 @@ export interface CheckPayloadInput extends CheckOutcome {
  * 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 declare function buildCheckOutputData(input: CheckPayloadInput): Record<string, unknown>;
+export declare function buildCheckOutputData(input: CheckPayloadInput): CheckReport;
 /**
- * Refuse a `--check` name the project does not declare.
+ * Refuse a `--check` name that names neither a built-in nor a declared check.
  *
- * 🔑 **An unknown name used to be a silent green.** The filter was a bare
- * `if (only !== undefined && name !== only) continue;` and nothing compared the
- * flag against the declared keys, so `--check nope` filtered every check away,
- * ran none, and exited 0 with `checksRun: 0` and `issues: []` on empty stderr.
- * The loud "no checks are declared" warning never fired, because it asks whether
- * the `checks` MAP is empty, never whether the FILTER matched anything.
- *
- * That is not a hypothetical typo: `vat resources check --check orphan-skills`
- * is the example in this command's own help text. Rename or delete that check
- * and the CI step keeps passing forever while asserting nothing.
+ * 🔑 **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 declared check
+ * @throws When `only` names no check this run would attempt
  */
-export declare function requireDeclaredCheck(checks: Readonly<Record<string, ResourceCheck>>, only: string | undefined): void;
+export declare function requireKnownCheck(builtinNames: readonly string[], checks: Readonly<Record<string, ResourceCheck>>, only: string | undefined): void;
 /**
  * Name every `CUSTOM:` severity override that overrides nothing.
  *
  * 🔑 **The same silent-green shape as an unknown `--check` name, one surface
- * over.** {@link requireDeclaredCheck} refuses `--check nope` because a filter
+ * 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
@@ -386,7 +486,7 @@ export declare const NODE_FATAL_ABORT_EXIT_CODE = 134;
  * 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 `handleCommandError` path everything else here uses.
+ * (exit 2) through the same `handleReportCommandError` path everything else here uses.
  *
  * @param options - The wreckage
  * @param options.entries - What `parseProgressLog` recovered
@@ -403,8 +503,14 @@ export declare function buildInterruptedCheckInput(options: {
     durationMs: number;
 }): CheckPayloadInput;
 /**
- * Run the declared checks and resolve their severities — the whole of this
- * verb's logic, with the database taken out.
+ * 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
@@ -417,8 +523,11 @@ export declare function buildInterruptedCheckInput(options: {
  * 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 key, or undefined for all
+ * @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.
@@ -433,7 +542,8 @@ export declare function buildInterruptedCheckInput(options: {
  *   unit case run with nobody watching
  * @returns The resolved findings, and one cost record per check that ran
  */
-export declare function runDeclaredChecks(options: {
+export declare function runProjectChecks(options: {
+    builtins: readonly BoundBuiltinCheck[];
     checks: Readonly<Record<string, ResourceCheck>>;
     only: string | undefined;
     ask: AskProjection;

package/dist/commands/resources/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkKG;AAIH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE1D,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uGAAuG;IACvG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB;AAED,2CAA2C;AAC3C,UAAU,YAAa,SAAQ,oBAAoB,EAAE,gBAAgB;IACnE,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IACnC;;;;;;;;;OASG;IACH,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoEtF;AA8KD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,EAC/C,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,EAC/C,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,IAAI,CAoBN;AAuDD;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAuJjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAuL9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,iBAAiB,CAyBpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAChD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,GAAG,EAAE,aAAa,CAAC;IACnB,UAAU,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAOnB,UAAU,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACvC,GAAG;IAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAmCpD;AA6GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAsFf"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check.ts"],"names":[],"mappings":"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"}