@vibe-agent-toolkit/cli 0.2.0-rc.4 → 0.2.0-rc.5

package/dist/utils/projection-query.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Populating a tree's resource projection and putting it somewhere ASKABLE —
+ * the shared half of every command that runs SQL over it.
+ *
+ * `vat resources query` runs one statement a person typed; `vat resources check`
+ * runs the statements a project wrote down. They differ in what they do with
+ * rows and in nothing else: same population, same store selection, same
+ * ephemeral fallback, same cache tell. This module is that "and in nothing
+ * else", stated once so the two cannot drift into answering about different
+ * corpora.
+ *
+ * ## 🚨 The SQL ALWAYS runs against a per-run in-memory database. Never the store.
+ *
+ * This is a correctness property, not an optimisation choice, and it was learned
+ * the expensive way. The on-disk projection store is **one database per VAT
+ * release, shared by every root on the machine** (`defaultStoreDirectory()` is
+ * `tmpdir/.vat-cache/<version>/projection-<shapeDigest>`), it retains three tree
+ * hashes per root, and its blob tier is never evicted and carries no tree key at
+ * all. `ProjectionStore.readExtent` narrows by `(rootId, treeHash)`; **arbitrary
+ * SQL does not**, and cannot be made to — a `WHERE` clause the caller wrote is
+ * not a key predicate.
+ *
+ * So running a user's statement against the file-backed store answered from
+ * every projection on the machine. Measured on a two-file scratch repository:
+ * `SELECT COUNT(*) FROM resource_realizations` returned **3** with no store and
+ * **5,779** with one, and `WHERE path LIKE 'packages/%'` returned paths from a
+ * different repository entirely. That is a wrong answer and a cross-project
+ * disclosure of link text, heading text and frontmatter — the same material
+ * `store.ts` cites as the reason it chmods the cache `0o700`.
+ *
+ * ⇒ The store's job is to make the POPULATION cheap, and that is all. Whatever
+ * `populate()` returns — served from the store or derived — is written into a
+ * fresh in-memory database that holds this tree and nothing else, and the SQL
+ * runs there. The saving is untouched (it was always in the population: on this
+ * repository {@link ProjectionProvenance.populationMs} reads 1.16-1.18 s derived
+ * against 0.29-0.31 s served), and "one tree, one answer" stops being a claim
+ * about how callers behave and becomes a property of the shape.
+ *
+ * ## The store never reaches a caller
+ *
+ * Work runs against an `ask` closure rather than a store handle. That is
+ * deliberate: `utils/projection-store.ts` is the one module in the toolkit that
+ * knows `@vibe-agent-toolkit/projection-sqlite` exists, and handing commands a
+ * backend-typed object would spread that knowledge to every future verb. A
+ * closure also puts the legible-failure wrapper on the single path that can
+ * throw, so no command can forget it.
+ */
+import type { Logger } from './logger.js';
+/** Where the POPULATION a statement ran against came from. */
+export type PopulationOrigin = 'derived' | 'store';
+/**
+ * What a run's rows are, and where they came from.
+ *
+ * ⚠️ There is deliberately no `engine` field beside these. An earlier version
+ * published one (`sqlite | ephemeral`) to say which database answered the SQL;
+ * it is gone because the answer is now always the same — see the header — and a
+ * field with one possible value tells a reader nothing while implying the other
+ * value is reachable.
+ */
+export interface ProjectionProvenance {
+    /**
+     * 🔑 The cache tell. Reported rather than inferred, because it CANNOT be
+     * inferred: a correct store hit and a correct re-derivation produce identical
+     * rows. A hit short-circuits `populate()` before the builder exists, so no
+     * contributor timing is filed — an empty record list IS the hit.
+     *
+     * It describes the POPULATION, which is the only thing the store now affects.
+     */
+    readonly population: PopulationOrigin;
+    /**
+     * 🔑 What that origin was WORTH. {@link population} says whether the
+     * projection was served or re-derived; this says what the difference cost, so
+     * the tell stops being a bare label a reader has to take on faith.
+     *
+     * Measured as THIS field, by running `vat resources query 'SELECT COUNT(*) AS
+     * n FROM blobs'` against this repository three times per arm with the parse
+     * cache warm: **1.16-1.18 s derived against 0.29-0.31 s served**. With a cold
+     * parse cache the derived arm is 33-35 s, so the pair above is the store's
+     * saving and not the parse cache's.
+     *
+     * The wall time of the SHARED setup and nothing else: everything
+     * {@link withQueriedProjection} does before it hands control to the caller's
+     * work — opening the population cache (which, when a store is selected, is a
+     * `git write-tree` spawn plus the backend's dynamic import and
+     * `openSqliteProjectionStore()`), the git tracker, `buildResourceProjection`,
+     * opening the ephemeral database, and writing the blob tier and the extent
+     * into it.
+     *
+     * ⚠️ The population cache's CLOSE is outside it, necessarily: that runs in
+     * `withPopulationCache`'s `finally`, after the caller's work returns, and a
+     * span that ends before the work begins cannot contain it. It is a handle
+     * release, not population.
+     *
+     * 🪤 **The span's start is load-bearing, and moving it inward is silent.**
+     * This shipped with the clock started on the first line INSIDE
+     * `withPopulationCache`'s callback — which put the population-cache open, the
+     * only part of the setup a store adds, OUTSIDE the measurement, and only on
+     * the arm where a store exists. Measured on a two-file corpus with identical
+     * total wall time on both arms: no store 0.145 of 0.146 s, cold store 0.0475
+     * of 0.161 s. Same work, `populationSecs` three times apart, and a reader
+     * comparing a no-store run to a warm-store run read a 42x saving where the
+     * honest totals differ by 1.75x. The field was added to stop the cache tell
+     * being a label taken on faith and had become the artifact instead. A
+     * measurement that flatters one arm is this repository's most-repeated
+     * defect; the system suite now pins `populationSecs / durationSecs > 0.6` on a
+     * cold run so the next inward move is red rather than quiet.
+     *
+     * ## Why it belongs on shared provenance rather than on one verb
+     *
+     * Both verbs pay it, identically, because it is the half of the run they hold
+     * in common — a `check` that runs forty statements and a `query` that runs one
+     * do the same population first. And a per-statement cost is UNREADABLE without
+     * it: `vat resources check` publishes what each rule's SQL cost, and a reader
+     * handed forty small numbers and a large total has no way to tell an expensive
+     * rule from a setup everybody shares. Absent this field the only arithmetic
+     * available is "total minus the statements", which silently attributes the
+     * shared setup to whichever rule the reader is looking at.
+     *
+     * ⚠️ Measured with `performance.now()`, not `Date.now()`. A warm population
+     * lands well under a millisecond on a small tree, and a millisecond-granularity
+     * clock reports that as `0` — which reads as "not measured" rather than "very
+     * fast", turning the best case the store has into its least credible number.
+     *
+     * ⚠️ Deliberately ONE number, not a breakdown. Splitting it into crawl, parse
+     * and store-load is a real question and it is the lab's: an instrument that
+     * gets reviewed and re-run, rather than a product document that would then owe
+     * every consumer a stable sub-phase vocabulary.
+     */
+    readonly populationMs: number;
+}
+/**
+ * How much of the tree the population actually covered.
+ *
+ * ## Why this is not a field on {@link ProjectionProvenance}
+ *
+ * Provenance is a fact both verbs PUBLISH verbatim — "these rows were served or
+ * re-derived" is the same sentence in either document. This is a fact a verb
+ * REASONS with, and only one of them has anything to reason about: `vat
+ * resources query` prints the rows a person selected, so its reader can see the
+ * extent for themselves, while `vat resources check` prints a verdict and a
+ * count of rules. Only the second can pass vacuously, and only the second needs
+ * to know.
+ *
+ * ## 🔑 The failure it exists to make visible
+ *
+ * `vat resources check` reported how many CHECKS ran; nothing said how many ROWS
+ * they ran against. So "four checks passed over eight thousand files" and "four
+ * checks passed over ZERO files" were byte-identical documents, and the second
+ * was a green gate asserting nothing. A broad `.gitignore`, a shallow or sparse
+ * checkout, a root that resolved elsewhere, or an extent source that enumerated
+ * nothing all produce it — and `buildResourceProjection` DECLINES ignored
+ * members rather than flagging them, so an emptied enumeration leaves no trace
+ * in the tables either.
+ */
+export interface PopulationExtent {
+    /**
+     * One per `(extentId, path)` row the population enumerated.
+     *
+     * 🪤 Realizations rather than any other count, because every alternative
+     * fails to reach zero on the case that matters: `roots` always holds exactly
+     * one row (the invariant thrown for below), so a total over all twelve tables
+     * is never 0; `blobs` is content-keyed and deduped, so it counts parse REACH
+     * and already has its own guard in `onBlobPopulation`; and `resources` counts
+     * identities, which a corpus can legitimately have none of while enumerating
+     * plenty. One row per enumerated path is non-zero exactly when something was
+     * enumerated.
+     */
+    readonly membersEnumerated: number;
+}
+/** Run one read-only statement against the populated projection. */
+export type AskProjection = (sql: string, ...parameters: readonly string[]) => readonly Record<string, unknown>[];
+/**
+ * Compile every statement a run intends to ask, against the schema and NO rows,
+ * before anything is populated.
+ *
+ * ## 🔑 What this buys, measured
+ *
+ * SQLite resolves table and column names when a statement is *prepared*, not
+ * when it is stepped — so a typo is knowable before a single row exists. It was
+ * not knowable in practice, because the only place a statement met the schema
+ * was after the projection had been built. On a real adopter tree, `SELECT path,
+ * no_such_column …` cost **8.3 s**, every millisecond of it spent building a
+ * projection the statement could never have read. The same typo now costs the
+ * price of an empty in-memory database — one extra `createSchema` into
+ * `:memory:`, which is the whole overhead this adds on the happy path.
+ *
+ * It also moves the KIND refusals — a second statement, an `ATTACH`, a `PRAGMA`
+ * — in front of the population, so a statement rejected for what it is costs no
+ * more than one rejected for what it names.
+ *
+ * ⚠️ **This is a pre-flight, not a second gate.** `ask` still compiles and runs
+ * the real statement against the real projection, and nothing here is trusted in
+ * place of that. A statement that compiles here can still fail there — SQLite
+ * resolves names against a schema, and this is the same schema, but a run-time
+ * error (a bad cast, an overflow) belongs to stepping and is unreachable from a
+ * prepare.
+ *
+ * ⚠️ It deliberately does not STEP anything. Stepping is where a check's
+ * unbounded cost lives, and a preflight that ran `WITH RECURSIVE …` would hang
+ * before the run it exists to make cheap had begun.
+ *
+ * @param statements - Every statement the run will ask, in any order
+ * @throws The same legible failure `ask` throws, for the first statement that
+ *   does not compile
+ */
+export declare function assertQueriesCompile(statements: readonly string[]): Promise<void>;
+/**
+ * Populate the tree, load it into something askable, and hand the caller a way
+ * to ask.
+ *
+ * @param options - The run
+ * @param options.root - Absolute corpus root
+ * @param options.logger - Where blob-stage refusals are reported (stderr, so a
+ *   parseable document on stdout stays parseable)
+ * @param options.preflight - Every statement this run intends to ask, compiled
+ *   against the empty schema BEFORE the population starts. See
+ *   {@link assertQueriesCompile}
+ * @param work - Given the asker, where its rows came from, and how much of the
+ *   tree they cover. The store is open for exactly this call and closed however
+ *   it ends
+ * @returns Whatever `work` returned
+ */
+export declare function withQueriedProjection<T>(options: {
+    root: string;
+    logger: Logger;
+    preflight?: readonly string[];
+}, work: (ask: AskProjection, provenance: ProjectionProvenance, extent: PopulationExtent) => Promise<T> | T): Promise<T>;
+/**
+ * Turn a rejected statement into a message that names the surface it missed.
+ *
+ * ## Why this wrapper exists
+ *
+ * VAT ships no schema version, by standing rule — the *cache* is safe across a
+ * shape change because its digest self-invalidates, but submitted SQL is not: it
+ * simply breaks. Pre-1.0 that is acceptable. A raw SQLite error reaching the
+ * user is not, because `no such column: contentHash` says nothing about what the
+ * column is called now. It matters more for a CHECK than for a query: a query's
+ * author is at the keyboard, while a check's author wrote it months ago and the
+ * person reading the failure is someone else.
+ *
+ * ⚠️ **A legibility wrapper, not a validator.** It does not parse SQL and does
+ * not check a statement before running it — it reacts to a failure by listing
+ * what the query COULD have named. When the statement mentions a known table,
+ * that table's columns are listed, which is the case that actually answers "what
+ * moved"; otherwise the table names are, which at least answers "what is there".
+ *
+ * 🪤 **Only a name that was not found gets the listing.** The engine also refuses
+ * a write and this backend refuses a second statement, and neither is answered by
+ * a column list — appending one says the problem is the schema when the problem
+ * is what the caller asked for. A wrapper that decorates every failure identically
+ * teaches the reader to skip the decoration, which costs the case it was written for.
+ *
+ * Matching is a plain lowercase substring test rather than a regex: the input is
+ * user text, and a pattern built from it is both a lint failure here and a
+ * needless hazard.
+ *
+ * @param sql - The statement that was submitted
+ * @param message - What the engine said
+ * @returns The message to surface, with the queryable surface appended when the
+ *   failure was a name this projection does not have
+ */
+export declare function describeQueryFailure(sql: string, message: string): string;
+//# sourceMappingURL=projection-query.d.ts.map

package/dist/utils/projection-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-query.d.ts","sourceRoot":"","sources":["../../src/utils/projection-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAYH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAkB1C,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,SAAS,MAAM,EAAE,KAC7B,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACxE,IAAI,EAAE,CACJ,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,gBAAgB,KACrB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CA4FZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAezE"}

package/dist/utils/projection-query.js

@@ -0,0 +1,262 @@
+/**
+ * Populating a tree's resource projection and putting it somewhere ASKABLE —
+ * the shared half of every command that runs SQL over it.
+ *
+ * `vat resources query` runs one statement a person typed; `vat resources check`
+ * runs the statements a project wrote down. They differ in what they do with
+ * rows and in nothing else: same population, same store selection, same
+ * ephemeral fallback, same cache tell. This module is that "and in nothing
+ * else", stated once so the two cannot drift into answering about different
+ * corpora.
+ *
+ * ## 🚨 The SQL ALWAYS runs against a per-run in-memory database. Never the store.
+ *
+ * This is a correctness property, not an optimisation choice, and it was learned
+ * the expensive way. The on-disk projection store is **one database per VAT
+ * release, shared by every root on the machine** (`defaultStoreDirectory()` is
+ * `tmpdir/.vat-cache/<version>/projection-<shapeDigest>`), it retains three tree
+ * hashes per root, and its blob tier is never evicted and carries no tree key at
+ * all. `ProjectionStore.readExtent` narrows by `(rootId, treeHash)`; **arbitrary
+ * SQL does not**, and cannot be made to — a `WHERE` clause the caller wrote is
+ * not a key predicate.
+ *
+ * So running a user's statement against the file-backed store answered from
+ * every projection on the machine. Measured on a two-file scratch repository:
+ * `SELECT COUNT(*) FROM resource_realizations` returned **3** with no store and
+ * **5,779** with one, and `WHERE path LIKE 'packages/%'` returned paths from a
+ * different repository entirely. That is a wrong answer and a cross-project
+ * disclosure of link text, heading text and frontmatter — the same material
+ * `store.ts` cites as the reason it chmods the cache `0o700`.
+ *
+ * ⇒ The store's job is to make the POPULATION cheap, and that is all. Whatever
+ * `populate()` returns — served from the store or derived — is written into a
+ * fresh in-memory database that holds this tree and nothing else, and the SQL
+ * runs there. The saving is untouched (it was always in the population: on this
+ * repository {@link ProjectionProvenance.populationMs} reads 1.16-1.18 s derived
+ * against 0.29-0.31 s served), and "one tree, one answer" stops being a claim
+ * about how callers behave and becomes a property of the shape.
+ *
+ * ## The store never reaches a caller
+ *
+ * Work runs against an `ask` closure rather than a store handle. That is
+ * deliberate: `utils/projection-store.ts` is the one module in the toolkit that
+ * knows `@vibe-agent-toolkit/projection-sqlite` exists, and handing commands a
+ * backend-typed object would spread that knowledge to every future verb. A
+ * closure also puts the legible-failure wrapper on the single path that can
+ * throw, so no command can forget it.
+ */
+import { performance } from 'node:perf_hooks';
+import { buildResourceProjection, PROJECTION_TABLES, splitProjectionByScope, } from '@vibe-agent-toolkit/resources';
+import { gitTrackerForProjectRoot } from '../commands/audit/distributed-tree.js';
+import { populationWiring } from './population-wiring.js';
+import { openEphemeralQueryStore, withPopulationCache } from './projection-store.js';
+/**
+ * The tree hash an in-memory store's one population is filed under.
+ *
+ * ⚠️ Deliberately NOT a tree hash. Nothing else ever opens this database, no
+ * read-back compares the key against another run's, and the store is gone at the
+ * end of the call — so the key only has to be internally consistent. A real
+ * `git write-tree` here would cost a spawn to produce a value nobody reads, and
+ * would invite the reader to believe the ephemeral store is shareable.
+ */
+const EPHEMERAL_TREE_HASH = 'ephemeral';
+/** What SQLite says when a statement names something the schema does not have. */
+const NAME_NOT_FOUND = ['no such table:', 'no such column:'];
+/**
+ * Compile every statement a run intends to ask, against the schema and NO rows,
+ * before anything is populated.
+ *
+ * ## 🔑 What this buys, measured
+ *
+ * SQLite resolves table and column names when a statement is *prepared*, not
+ * when it is stepped — so a typo is knowable before a single row exists. It was
+ * not knowable in practice, because the only place a statement met the schema
+ * was after the projection had been built. On a real adopter tree, `SELECT path,
+ * no_such_column …` cost **8.3 s**, every millisecond of it spent building a
+ * projection the statement could never have read. The same typo now costs the
+ * price of an empty in-memory database — one extra `createSchema` into
+ * `:memory:`, which is the whole overhead this adds on the happy path.
+ *
+ * It also moves the KIND refusals — a second statement, an `ATTACH`, a `PRAGMA`
+ * — in front of the population, so a statement rejected for what it is costs no
+ * more than one rejected for what it names.
+ *
+ * ⚠️ **This is a pre-flight, not a second gate.** `ask` still compiles and runs
+ * the real statement against the real projection, and nothing here is trusted in
+ * place of that. A statement that compiles here can still fail there — SQLite
+ * resolves names against a schema, and this is the same schema, but a run-time
+ * error (a bad cast, an overflow) belongs to stepping and is unreachable from a
+ * prepare.
+ *
+ * ⚠️ It deliberately does not STEP anything. Stepping is where a check's
+ * unbounded cost lives, and a preflight that ran `WITH RECURSIVE …` would hang
+ * before the run it exists to make cheap had begun.
+ *
+ * @param statements - Every statement the run will ask, in any order
+ * @throws The same legible failure `ask` throws, for the first statement that
+ *   does not compile
+ */
+export async function assertQueriesCompile(statements) {
+    if (statements.length === 0)
+        return;
+    const probe = await openEphemeralQueryStore();
+    try {
+        for (const sql of statements) {
+            try {
+                probe.assertCompiles(sql);
+            }
+            catch (error) {
+                throw new Error(describeQueryFailure(sql, error instanceof Error ? error.message : String(error)));
+            }
+        }
+    }
+    finally {
+        await probe.close();
+    }
+}
+/**
+ * Populate the tree, load it into something askable, and hand the caller a way
+ * to ask.
+ *
+ * @param options - The run
+ * @param options.root - Absolute corpus root
+ * @param options.logger - Where blob-stage refusals are reported (stderr, so a
+ *   parseable document on stdout stays parseable)
+ * @param options.preflight - Every statement this run intends to ask, compiled
+ *   against the empty schema BEFORE the population starts. See
+ *   {@link assertQueriesCompile}
+ * @param work - Given the asker, where its rows came from, and how much of the
+ *   tree they cover. The store is open for exactly this call and closed however
+ *   it ends
+ * @returns Whatever `work` returned
+ */
+export async function withQueriedProjection(options, work) {
+    const { root, logger } = options;
+    // 🔑 BEFORE the clock and before the population, because being before the
+    // population is the entire point — see {@link assertQueriesCompile}. It is an
+    // option rather than a step each verb remembers for the same reason everything
+    // else here is shared: a verb that forgot it would silently go back to paying
+    // a full population to learn about a typo, and nothing in its output would say
+    // so.
+    await assertQueriesCompile(options.preflight ?? []);
+    // 🚨 OUTSIDE `withPopulationCache`, and it must stay outside. That helper
+    // awaits `openPopulationCache` — a `git write-tree` spawn plus the backend's
+    // dynamic import and `openSqliteProjectionStore()` — BEFORE it invokes the
+    // callback below, and it pays that cost ONLY when a store is selected. A clock
+    // started inside the callback therefore drops the store's own setup out of the
+    // measurement on precisely the arm the number is used to praise. See
+    // `populationMs` for what that shipped as.
+    //
+    // What is NOT in the span, deliberately: `withPopulationCache`'s `finally`,
+    // which closes the opened cache AFTER `work` returns. A span that ends before
+    // `work` begins cannot contain it, and stretching the span past `work` would
+    // fold the caller's statements into a number whose entire purpose is to be
+    // read against them. The close is a handle release on an already-open
+    // database, not population.
+    let contributorRecords = 0;
+    const populationStart = performance.now();
+    // The file-backed store, when one is selected, and ONLY as a population cache.
+    // Its rows are never queried — see the header.
+    return withPopulationCache({ root }, async (cache) => {
+        // The cache tell. `populate()` short-circuits a hit before any contributor
+        // is constructed, so this staying at zero is the ONLY observable difference
+        // between a served population and a re-derived one. Declared with the clock
+        // above rather than here so the two cannot drift apart when one moves.
+        const gitTracker = await gitTrackerForProjectRoot(root);
+        const projection = await buildResourceProjection({
+            root,
+            ...populationWiring(logger, gitTracker, cache, root),
+            onContributorTiming: () => {
+                contributorRecords += 1;
+            },
+        });
+        // ONE tree, in a database nothing else can reach, built fresh for this call.
+        const store = await openEphemeralQueryStore();
+        try {
+            // The key is read OFF the projection rather than re-derived from the root.
+            // The driver mints `roots.id` with `rootIdFor` and every
+            // `resolution_contexts.rootId` is a foreign key into it, so taking it from
+            // the rows means the key provably describes them — a second derivation
+            // could drift from the first and file rows under an id they do not carry.
+            const rootId = projection.roots[0]?.id;
+            if (rootId === undefined) {
+                throw new Error('The population produced no root row, so there is no id to file its extent under.'
+                    + ' This is a driver invariant rather than a user error — `populate()` adds exactly'
+                    + ' one, and a projection without it cannot be stored or queried.');
+            }
+            const { blobs, extent } = splitProjectionByScope(projection);
+            await store.writeBlobFacts(blobs);
+            await store.writeExtent({ rootId, treeHash: EPHEMERAL_TREE_HASH }, extent);
+            // The shared setup is done. Everything after this line is the caller's.
+            const populationMs = performance.now() - populationStart;
+            const ask = (sql, ...parameters) => {
+                try {
+                    return store.query(sql, ...parameters);
+                }
+                catch (error) {
+                    throw new Error(describeQueryFailure(sql, error instanceof Error ? error.message : String(error)));
+                }
+            };
+            return await work(ask, { population: contributorRecords === 0 ? 'store' : 'derived', populationMs }, 
+            // Read off the PROJECTION rather than counted back out of the store with
+            // a `SELECT COUNT(*)`: a count that travelled through the same `ask` the
+            // caller's statements do would be broken by the very schema drift it
+            // exists to survive, and it is the population's size either way.
+            { membersEnumerated: projection.resourceRealizations.length });
+        }
+        finally {
+            // Closed however the work ends. An in-memory database is reclaimed with the
+            // process either way, but a command that runs several of these in one
+            // process would otherwise hold every one of them open.
+            await store.close();
+        }
+    });
+}
+/**
+ * Turn a rejected statement into a message that names the surface it missed.
+ *
+ * ## Why this wrapper exists
+ *
+ * VAT ships no schema version, by standing rule — the *cache* is safe across a
+ * shape change because its digest self-invalidates, but submitted SQL is not: it
+ * simply breaks. Pre-1.0 that is acceptable. A raw SQLite error reaching the
+ * user is not, because `no such column: contentHash` says nothing about what the
+ * column is called now. It matters more for a CHECK than for a query: a query's
+ * author is at the keyboard, while a check's author wrote it months ago and the
+ * person reading the failure is someone else.
+ *
+ * ⚠️ **A legibility wrapper, not a validator.** It does not parse SQL and does
+ * not check a statement before running it — it reacts to a failure by listing
+ * what the query COULD have named. When the statement mentions a known table,
+ * that table's columns are listed, which is the case that actually answers "what
+ * moved"; otherwise the table names are, which at least answers "what is there".
+ *
+ * 🪤 **Only a name that was not found gets the listing.** The engine also refuses
+ * a write and this backend refuses a second statement, and neither is answered by
+ * a column list — appending one says the problem is the schema when the problem
+ * is what the caller asked for. A wrapper that decorates every failure identically
+ * teaches the reader to skip the decoration, which costs the case it was written for.
+ *
+ * Matching is a plain lowercase substring test rather than a regex: the input is
+ * user text, and a pattern built from it is both a lint failure here and a
+ * needless hazard.
+ *
+ * @param sql - The statement that was submitted
+ * @param message - What the engine said
+ * @returns The message to surface, with the queryable surface appended when the
+ *   failure was a name this projection does not have
+ */
+export function describeQueryFailure(sql, message) {
+    if (!NAME_NOT_FOUND.some((prefix) => message.includes(prefix)))
+        return message;
+    const lowered = sql.toLowerCase();
+    const named = Object.values(PROJECTION_TABLES).filter((spec) => lowered.includes(spec.name.toLowerCase()));
+    const surface = named.length > 0
+        ? named.map((spec) => `  ${spec.name}(${spec.columns.join(', ')})`).join('\n')
+        : Object.values(PROJECTION_TABLES).map((spec) => `  ${spec.name}`).join('\n');
+    const heading = named.length > 0
+        ? 'The tables this statement names hold these columns:'
+        : 'The projection holds these tables:';
+    return `${message}\n\n${heading}\n${surface}`;
+}
+//# sourceMappingURL=projection-query.js.map

package/dist/utils/projection-query.js.map

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