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

package/dist/commands/resources/query-schema.d.ts

@@ -0,0 +1,188 @@
+/**
+ * The document `vat resources query` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **`examined` is the population, not the rows.** A statement selecting
+ * zero rows over a populated tree is a real answer (`ok`); a statement over a
+ * population of zero resources is not one, and the writer refuses it.
+ */
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat resources query`, and the remedy when it is zero. */
+export declare const RESOURCES_QUERY_EXAMINED: ExaminedDeclaration;
+declare const ResourcesQueryDataSchema: z.ZodObject<{
+    /** The project the statement was asked about. */
+    root: z.ZodString;
+    /** The statement's result columns, in order — present even when it selected no row. */
+    columns: z.ZodArray<z.ZodString, "many">;
+    /** The selected rows, exactly as SQLite holds the values. */
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    /** Whether the projection was derived this run or read from the store — the cache tell. */
+    population: z.ZodEnum<["store" | "derived", ...("store" | "derived")[]]>;
+    /** What that population cost. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the statement ran. */
+    lensSecs: z.ZodNumber;
+    /** Which lenses that covers — the derived relations this statement named. */
+    lensesEvaluated: z.ZodArray<z.ZodString, "many">;
+    /** Where those lenses' own populations came from: `none` when no evaluated lens populated anything. */
+    lensPopulation: z.ZodEnum<["none", "store" | "derived", ...("store" | "derived")[]]>;
+    /** The prose frame `limits` is read under; present exactly when a bounded lens ran. */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /** What the derived rows do NOT settle; present exactly when a bounded lens ran. */
+    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">>;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "store" | "derived";
+    rows: Record<string, unknown>[];
+    populationSecs: number;
+    lensSecs: number;
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
+    columns: string[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "store" | "derived";
+    rows: Record<string, unknown>[];
+    populationSecs: number;
+    lensSecs: number;
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
+    columns: string[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>;
+export type ResourcesQueryData = z.infer<typeof ResourcesQueryDataSchema>;
+/** The document this command publishes. */
+export declare const RESOURCES_QUERY_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The project the statement was asked about. */
+    root: z.ZodString;
+    /** The statement's result columns, in order — present even when it selected no row. */
+    columns: z.ZodArray<z.ZodString, "many">;
+    /** The selected rows, exactly as SQLite holds the values. */
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    /** Whether the projection was derived this run or read from the store — the cache tell. */
+    population: z.ZodEnum<["store" | "derived", ...("store" | "derived")[]]>;
+    /** What that population cost. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the statement ran. */
+    lensSecs: z.ZodNumber;
+    /** Which lenses that covers — the derived relations this statement named. */
+    lensesEvaluated: z.ZodArray<z.ZodString, "many">;
+    /** Where those lenses' own populations came from: `none` when no evaluated lens populated anything. */
+    lensPopulation: z.ZodEnum<["none", "store" | "derived", ...("store" | "derived")[]]>;
+    /** The prose frame `limits` is read under; present exactly when a bounded lens ran. */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /** What the derived rows do NOT settle; present exactly when a bounded lens ran. */
+    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">>;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "store" | "derived";
+    rows: Record<string, unknown>[];
+    populationSecs: number;
+    lensSecs: number;
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
+    columns: string[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "store" | "derived";
+    rows: Record<string, unknown>[];
+    populationSecs: number;
+    lensSecs: number;
+    lensesEvaluated: string[];
+    lensPopulation: "store" | "none" | "derived";
+    columns: string[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>, z.ZodObject<Omit<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info", "ignore"]>;
+    message: z.ZodString;
+    location: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    field: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "severity"> & {
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    column: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}>>;
+export type ResourcesQueryReport = Report<ResourcesQueryData>;
+export {};
+//# sourceMappingURL=query-schema.d.ts.map

package/dist/commands/resources/query-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/query-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAIxE,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,EAAE,mBAItC,CAAC;AAEF,QAAA,MAAM,wBAAwB;IAC5B,iDAAiD;;IAEjD,uFAAuF;;IAEvF,6DAA6D;;IAE7D,2FAA2F;;IAE3F,iCAAiC;;IAEjC,sEAAsE;;IAEtE,6EAA6E;;IAE7E,uGAAuG;;IAEvG,uFAAuF;;IAEvF,oFAAoF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE3E,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,2CAA2C;AAC3C,eAAO,MAAM,6BAA6B;IAzBxC,iDAAiD;;IAEjD,uFAAuF;;IAEvF,6DAA6D;;IAE7D,2FAA2F;;IAE3F,iCAAiC;;IAEjC,sEAAsE;;IAEtE,6EAA6E;;IAE7E,uGAAuG;;IAEvG,uFAAuF;;IAEvF,oFAAoF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAOY,CAAC;AAEnG,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/commands/resources/query-schema.js

@@ -0,0 +1,48 @@
+/**
+ * The document `vat resources query` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **`examined` is the population, not the rows.** A statement selecting
+ * zero rows over a populated tree is a real answer (`ok`); a statement over a
+ * population of zero resources is not one, and the writer refuses it.
+ */
+import { POPULATION_ORIGINS } from '@vibe-agent-toolkit/resources';
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import { LENS_POPULATIONS } from '../../utils/lens-population.js';
+import { StatedLimitSchema } from './check-schema.js';
+/** What `examined` counts for `vat resources query`, and the remedy when it is zero. */
+export const RESOURCES_QUERY_EXAMINED = {
+    unit: 'resources in the population',
+    whenZero: 'The projection holds no tracked resource, so no statement over it answers anything: run from inside'
+        + ' the project, and check that its files are tracked or not excluded.',
+};
+const ResourcesQueryDataSchema = z.object({
+    /** The project the statement was asked about. */
+    root: z.string(),
+    /** The statement's result columns, in order — present even when it selected no row. */
+    columns: z.array(z.string()),
+    /** The selected rows, exactly as SQLite holds the values. */
+    rows: z.array(z.record(z.string(), z.unknown())),
+    /** Whether the projection was derived this run or read from the store — the cache tell. */
+    population: z.enum(POPULATION_ORIGINS),
+    /** What that population cost. */
+    populationSecs: z.number().nonnegative(),
+    /** What evaluating the lenses cost, paid before the statement ran. */
+    lensSecs: z.number().nonnegative(),
+    /** Which lenses that covers — the derived relations this statement named. */
+    lensesEvaluated: z.array(z.string()),
+    /** Where those lenses' own populations came from: `none` when no evaluated lens populated anything. */
+    lensPopulation: z.enum(LENS_POPULATIONS),
+    /** The prose frame `limits` is read under; present exactly when a bounded lens ran. */
+    boundsStatement: z.string().optional(),
+    /** What the derived rows do NOT settle; present exactly when a bounded lens ran. */
+    limits: z.array(StatedLimitSchema).optional(),
+}).strict();
+/** The document this command publishes. */
+export const RESOURCES_QUERY_REPORT_SCHEMA = reportSchema(ResourcesQueryDataSchema, FindingSchema);
+//# sourceMappingURL=query-schema.js.map

package/dist/commands/resources/query-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-schema.js","sourceRoot":"","sources":["../../../src/commands/resources/query-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,wFAAwF;AACxF,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IAC3D,IAAI,EAAE,6BAA6B;IACnC,QAAQ,EAAE,qGAAqG;UAC3G,qEAAqE;CAC1E,CAAC;AAEF,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,iDAAiD;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,uFAAuF;IACvF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAChD,2FAA2F;IAC3F,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC;IACtC,iCAAiC;IACjC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACxC,sEAAsE;IACtE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IAClC,6EAA6E;IAC7E,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACpC,uGAAuG;IACvG,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;IACxC,uFAAuF;IACvF,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,oFAAoF;IACpF,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,6BAA6B,GAAG,YAAY,CAAC,wBAAwB,EAAE,aAAa,CAAC,CAAC"}

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

@@ -4,7 +4,7 @@
  * ## Why a query verb at all, when `scan` already reports counts
  *
  * `vat resources scan` answers the questions its payload was written for, and
- * nothing else. The projection holds thirteen tables — realizations, references,
+ * nothing else. The projection holds a table per fact kind — realizations, references,
  * sections, conditions, provenance, rule patterns — and every question nobody
  * anticipated currently has no answer short of writing a new command. This verb
  * is the general case: one statement, the rows it selects, no new field.
@@ -24,9 +24,9 @@
  * from the **store**. It has to be reported, because it cannot be inferred: a
  * correct hit and a correct re-derivation produce byte-identical rows, so "did
  * the cache work" is otherwise unfalsifiable — this repository's most repeated
- * failure. The signal is real rather than declarative: a store hit
- * short-circuits `populate()` before the builder exists, so no contributor runs
- * and no timing record is filed. An empty record list IS the hit.
+ * failure. The signal is real rather than declarative: it is the outcome
+ * `populate()` returns, which says whether the store served the run.
+ * `lensPopulation` is the same tell for a lens that populates a lane of its own.
  *
  * `populationSecs` sits beside it and says what that origin was worth — the wall
  * time of the setup both this verb and `vat resources check` pay before either
@@ -45,6 +45,7 @@
  * authority on why.
  */
 import { type ProjectionProvenance } from '../../utils/projection-query.js';
+import type { ResourcesQueryReport } from './query-schema.js';
 interface QueryOptions {
     debug?: boolean;
     /** Bound in order, for every `?` in the statement. */
@@ -54,7 +55,11 @@ interface QueryOptions {
 }
 /** What one query run produced, and what produced it. */
 interface QueryOutcome extends ProjectionProvenance {
+    /** The statement's result columns, in order — known even when it selected no row. */
+    columns: readonly string[];
     rows: readonly Record<string, unknown>[];
+    /** Resources the population enumerated: what the statement was asked OVER. */
+    membersEnumerated: number;
 }
 export interface ProjectionQueryPayloadInput extends QueryOutcome {
     /** The stated root the query was asked about. */
@@ -62,21 +67,21 @@ export interface ProjectionQueryPayloadInput extends QueryOutcome {
     durationMs: number;
 }
 /**
- * Build the query payload.
+ * Build the query report.
  *
  * Pure: no file system, no clock, no `process.exit` — the same contract
- * `buildScanOutputData` follows, and for the same reason: it keeps the
- * document's shape, field names included, under unit test rather than only
- * under a CLI spawn.
+ * `buildScanReport` follows, and for the same reason: it keeps the document's
+ * shape, field names included, under unit test rather than only under a CLI
+ * spawn.
  *
- * `rowCount` is stated beside `rows` rather than left for the consumer to
- * count, because the two answer different questions once a caller pipes the
- * document somewhere: a truncated read still carries the true total.
+ * 🔑 `examined` is the POPULATION the statement ran over, never the rows it
+ * selected. Zero rows over a populated tree is an answer (`ok`); a statement
+ * over a population of nothing answers nothing, and the writer refuses it.
  *
  * @param input - The rows and the provenance of the run that produced them
- * @returns The document to serialize
+ * @returns The report to publish
  */
-export declare function buildProjectionQueryOutputData(input: ProjectionQueryPayloadInput): Record<string, unknown>;
+export declare function buildProjectionQueryReport(input: ProjectionQueryPayloadInput): ResourcesQueryReport;
 /**
  * Run one read-only SQL statement against this tree's resource projection.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AASH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,iCAAiC,CAAC;AAGzC,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,UAAU,YAAa,SAAQ,oBAAoB;IACjD,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,2BAA4B,SAAQ,YAAY;IAC/D,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2B1G;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Bf"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AASH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,UAAU,YAAa,SAAQ,oBAAoB;IACjD,qFAAqF;IACrF,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACzC,8EAA8E;IAC9E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA4B,SAAQ,YAAY;IAC/D,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,2BAA2B,GAAG,oBAAoB,CAiCnG;AA2CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/commands/resources/query.js

@@ -4,7 +4,7 @@
  * ## Why a query verb at all, when `scan` already reports counts
  *
  * `vat resources scan` answers the questions its payload was written for, and
- * nothing else. The projection holds thirteen tables — realizations, references,
+ * nothing else. The projection holds a table per fact kind — realizations, references,
  * sections, conditions, provenance, rule patterns — and every question nobody
  * anticipated currently has no answer short of writing a new command. This verb
  * is the general case: one statement, the rows it selects, no new field.
@@ -24,9 +24,9 @@
  * from the **store**. It has to be reported, because it cannot be inferred: a
  * correct hit and a correct re-derivation produce byte-identical rows, so "did
  * the cache work" is otherwise unfalsifiable — this repository's most repeated
- * failure. The signal is real rather than declarative: a store hit
- * short-circuits `populate()` before the builder exists, so no contributor runs
- * and no timing record is filed. An empty record list IS the hit.
+ * failure. The signal is real rather than declarative: it is the outcome
+ * `populate()` returns, which says whether the store served the run.
+ * `lensPopulation` is the same tell for a lens that populates a lane of its own.
  *
  * `populationSecs` sits beside it and says what that origin was worth — the wall
  * time of the setup both this verb and `vat resources check` pay before either
@@ -44,56 +44,62 @@
  * spec and arbitrary SQL has none. `SqlQueryableStore.query`'s docstring is the
  * authority on why.
  */
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { handleCommandError } from '../../utils/command-error.js';
+import { buildReport } from '@vibe-agent-toolkit/schema';
+import { refusalCodeOf } from '../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, NOTHING_FINISHED } from '../../utils/document-writer.js';
 import { formatDurationSecs } from '../../utils/duration.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeStructuredOutput } from '../../utils/output.js';
 import { assertDirectoryArgument, projectRootOrLoudCwd } from '../../utils/project-root-policy.js';
 import { withQueriedProjection, } from '../../utils/projection-query.js';
 import { relationBoundsFor } from '../../utils/relation-limits.js';
 /**
- * Build the query payload.
+ * Build the query report.
  *
  * Pure: no file system, no clock, no `process.exit` — the same contract
- * `buildScanOutputData` follows, and for the same reason: it keeps the
- * document's shape, field names included, under unit test rather than only
- * under a CLI spawn.
+ * `buildScanReport` follows, and for the same reason: it keeps the document's
+ * shape, field names included, under unit test rather than only under a CLI
+ * spawn.
  *
- * `rowCount` is stated beside `rows` rather than left for the consumer to
- * count, because the two answer different questions once a caller pipes the
- * document somewhere: a truncated read still carries the true total.
+ * 🔑 `examined` is the POPULATION the statement ran over, never the rows it
+ * selected. Zero rows over a populated tree is an answer (`ok`); a statement
+ * over a population of nothing answers nothing, and the writer refuses it.
  *
  * @param input - The rows and the provenance of the run that produced them
- * @returns The document to serialize
+ * @returns The report to publish
  */
-export function buildProjectionQueryOutputData(input) {
-    return {
-        status: 'success',
-        // Stated once, and the only absolute path in the document.
-        root: input.root,
-        // The cache tell — see the header.
-        population: input.population,
-        // Immediately after the origin, because the two are one statement: served
-        // or derived, and what that was worth. Separated they read as two unrelated
-        // numbers in a list.
-        populationSecs: formatDurationSecs(input.populationMs),
-        // Beside the population it is NOT part of. A store hit does not make a lens
-        // evaluation cheaper, so folding it into `populationSecs` would read as the
-        // store having got worse. See `ProjectionProvenance.lensMs`.
-        lensSecs: formatDurationSecs(input.lensMs),
-        // 🔑 What that number covers. A lens is evaluated only when THIS statement
-        // names one of its relations, so an empty list beside `lensSecs: 0` is the
-        // statement saying it asked for none — not a lens that silently stopped
-        // running. See `ProjectionProvenance.lensesEvaluated`.
-        lensesEvaluated: input.lensesEvaluated,
-        // The bounds of the rows below, stated ONCE and only when a bounded lens
-        // ran — `relation-limits.ts` carries why the SQL route owes them at all.
-        ...relationBoundsFor(input.lensesEvaluated),
-        rowCount: input.rows.length,
-        durationSecs: formatDurationSecs(input.durationMs),
-        rows: input.rows,
-    };
+export function buildProjectionQueryReport(input) {
+    return buildReport({
+        examined: input.membersEnumerated,
+        findings: [],
+        // `vat resources query` offers no `--strict`, and reports no finding of its own.
+        gate: { strict: false },
+        durationMs: input.durationMs,
+        data: {
+            // Stated once, and the only absolute path in the document.
+            root: input.root,
+            columns: [...input.columns],
+            rows: [...input.rows],
+            // The cache tell — see the header.
+            population: input.population,
+            // Immediately after the origin, because the two are one statement: served
+            // or derived, and what that was worth.
+            populationSecs: formatDurationSecs(input.populationMs),
+            // Beside the population it is NOT part of. A store hit does not make a lens
+            // evaluation cheaper, so folding it into `populationSecs` would read as the
+            // store having got worse. See `ProjectionProvenance.lensMs`.
+            lensSecs: formatDurationSecs(input.lensMs),
+            // 🔑 What that number covers. A lens is evaluated only when THIS statement
+            // names one of its relations, so an empty list beside `lensSecs: 0` is the
+            // statement saying it asked for none — not a lens that silently stopped
+            // running. See `ProjectionProvenance.lensesEvaluated`.
+            lensesEvaluated: [...input.lensesEvaluated],
+            // The cache tell for those lenses' own populations — see the header.
+            lensPopulation: input.lensPopulation,
+            // The bounds of the rows, stated ONCE and only when a bounded lens ran —
+            // `relation-limits.ts` carries why the SQL route owes them at all.
+            ...relationBoundsFor(input.lensesEvaluated),
+        },
+    });
 }
 /**
  * Populate the tree and run the caller's one statement against it.
@@ -111,7 +117,7 @@ export function buildProjectionQueryOutputData(input) {
  * @param options.logger - Where blob-stage refusals are reported
  * @returns The rows and the provenance of the population behind them
  */
-async function runProjectionQuery(options) {
+function runProjectionQuery(options) {
     const { root, sql, parameters, logger } = options;
     // The statement is compiled against the empty schema first, so a typo'd
     // column — or a `?` with no `--param` behind it — costs milliseconds instead
@@ -121,7 +127,12 @@ async function runProjectionQuery(options) {
     // preflight COMPILES this statement early, while `statements` decides which
     // derived relations get evaluated at all. One statement, two questions asked
     // of it.
-    { root, logger, preflight: [{ sql, parameters }], statements: [sql] }, (ask, provenance) => ({ rows: ask(sql, ...parameters), ...provenance }));
+    { root, logger, preflight: [{ sql, parameters }], statements: [sql] }, (ask, provenance, extent, _projection, columnsOf) => ({
+        columns: columnsOf(sql, ...parameters),
+        rows: ask(sql, ...parameters),
+        membersEnumerated: extent.membersEnumerated,
+        ...provenance,
+    }));
 }
 /**
  * Run one read-only SQL statement against this tree's resource projection.
@@ -150,6 +161,8 @@ async function runProjectionQuery(options) {
 export async function queryCommand(sql, pathArg, options) {
     const logger = createLogger({ debug: options.debug ?? false });
     const startTime = Date.now();
+    // The two formats this verb offers (Commander refuses any other).
+    const format = options.format === 'json' ? 'json' : 'yaml';
     try {
         if (pathArg !== undefined)
             assertDirectoryArgument(pathArg);
@@ -162,16 +175,15 @@ export async function queryCommand(sql, pathArg, options) {
             parameters: options.param ?? [],
             logger,
         });
-        const payload = buildProjectionQueryOutputData({
+        endWithReport('resources query', buildProjectionQueryReport({
             ...outcome,
             root: projectRoot,
             durationMs: Date.now() - startTime,
-        });
-        writeStructuredOutput(payload, options.format);
-        process.exit(ExitCode.OK);
+        }), format);
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'Query', options.format);
+        // A refused statement is USAGE_INVALID by its code; see `describedFailure`.
+        endWithRefusal('resources query', refusalCodeOf(error), error, format, { strict: false }, NOTHING_FINISHED);
     }
 }
 //# sourceMappingURL=query.js.map

package/dist/commands/resources/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/commands/resources/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/commands/resources/query.ts"],"names":[],"mappings":"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"}