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

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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"}

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

@@ -44,6 +44,7 @@
  * standard legible error, and a tree that cannot be keyed says so on stderr
  * rather than silently declining.
  */
+import type * as ProjectionSqlite from '@vibe-agent-toolkit/projection-sqlite';
 import type { PopulationCache } from '@vibe-agent-toolkit/resources';
 /**
  * The env var that selects a projection store for this process.
@@ -90,6 +91,34 @@ import type { PopulationCache } from '@vibe-agent-toolkit/resources';
 export declare const PROJECTION_STORE_ENV = "VAT_PROJECTION_STORE";
 /** {@link PROJECTION_STORE_ENV}'s value that selects the SQLite backend. */
 export declare const PROJECTION_STORE_SQLITE = "sqlite";
+/**
+ * Where the projection store's database lives, overriding the default.
+ *
+ * The default is `tmpdir/.vat-cache/<version>/projection-<shapeDigest>` — one
+ * database per VAT release, shared by every root on the machine. This names a
+ * different one **explicitly**, which is what an adopter with a per-job cache
+ * directory, a shared build agent running two jobs at once, or a test arm that
+ * must not touch the developer's live cache actually needs.
+ *
+ * 🪤 **What it replaces is redirecting `TMPDIR`, which works and is the wrong
+ * instrument.** `defaultStoreDirectory()` resolves through
+ * `vatCacheNamespaceRoot()` → `normalizedTmpdir()`, so pointing the OS temp
+ * directory elsewhere does move the store — along with every other temp
+ * consumer in the process, on a variable whose name is not the same on both
+ * platforms (`TMPDIR` on POSIX; `TEMP`, then `TMP`, on Windows, so setting one
+ * is silently inert on the other). It relocates the store as a side effect of
+ * relocating something larger. This variable says the one thing meant.
+ *
+ * ⚠️ It does **not** consult `XDG_CACHE_HOME` or `HOME`. A caller that set
+ * those believed it had its own database and was writing into the shared one;
+ * the fix is to name the directory here, not to add more implicit roots.
+ *
+ * An environment variable rather than a config field, for the same reason
+ * {@link PROJECTION_STORE_ENV} is one: it says where an INSTRUMENT keeps its
+ * scratch space, not what the project means, and it has to be reachable from a
+ * harness that spawns the binary.
+ */
+export declare const PROJECTION_STORE_DIR_ENV = "VAT_PROJECTION_STORE_DIR";
 /**
  * The env var that turns VAT's disk caches off for a run.
  *
@@ -133,7 +162,19 @@ export declare const CACHE_DISABLED = "0";
  * @returns `true` when a store is selected
  */
 export declare function projectionStoreSelected(): boolean;
-/** An open store, the key half it is used with, and the way to let it go. */
+/**
+ * An open store, the key half it is used with, and the way to let it go.
+ *
+ * ⚠️ **Deliberately NOT typed for SQL, and do not re-widen it.** This handle
+ * reaches the database at {@link PROJECTION_STORE_DIR_ENV}'s directory, which
+ * defaults to one file per VAT release shared by every root on the machine —
+ * holding other repositories' link text, heading text and frontmatter. A field
+ * typed `SqlQueryableStore` used to live here "for a caller that needs to ASK
+ * the store something", and that caller was removed precisely because arbitrary
+ * SQL over this store answers from trees the asker never named. `populate()`
+ * needs the engine-free {@link PopulationCache} and nothing more; a query lane
+ * builds its own store (see `projection-query.ts`).
+ */
 export interface OpenedPopulationCache {
     /** Hand this to `populate()`. */
     readonly cache: PopulationCache;
@@ -163,6 +204,57 @@ export interface OpenedPopulationCache {
 export declare function openPopulationCache(options: {
     root: string;
 }): Promise<OpenedPopulationCache | undefined>;
+/**
+ * Open a store that lives only in this process's memory.
+ *
+ * 🔑 **This is what keeps the query surface an ANSWER rather than a privilege.**
+ * A caller with no store selected — CI's first run, or a developer who never set
+ * the selector — still gets the same SQL over the same schema; the on-disk store
+ * only makes the second run cheap. Without it, "what does this tree contain"
+ * would be answerable only where a cache happened to exist, and two callers
+ * would hold differently-shaped views of one tree.
+ *
+ * It is a cache that cannot hit: nothing survives the close, so a caller must
+ * write the projection into it before asking anything.
+ *
+ * @returns An open, empty store; close it when done
+ */
+export declare function openEphemeralQueryStore(): Promise<ProjectionSqlite.SqlQueryableStore>;
+/**
+ * The legible failure for "your Node is too old", or `undefined` when this is
+ * some other failure — including "the package is absent".
+ *
+ * Exported, and returning the error rather than throwing it, so the DIAGNOSIS
+ * is unit-testable without a mocked dynamic import. A test cannot make a mocked
+ * `import()` reject with a plain `{ code }` — the test runner wraps whatever a
+ * module factory throws in its own error, so the code never survives to be
+ * read — and the branch's whole value is the message it produces.
+ *
+ * 🪤 The two are **different error codes**, and only one of them reaches
+ * {@link isModuleMissing}. `@vibe-agent-toolkit/projection-sqlite` imports
+ * `node:sqlite`, which arrived in Node 22.13.0; on 22.0–22.12 the import fails
+ * with `ERR_UNKNOWN_BUILTIN_MODULE`, not `ERR_MODULE_NOT_FOUND`. Without this
+ * branch the user gets a bare `No such built-in module: node:sqlite` — which
+ * names neither the version floor nor the fix.
+ *
+ * ⚠️ It is reachable on EVERY `vat resources query`/`check` run, and not a
+ * corner: VAT's own floor is `>=22.0.0`, so a supported Node hits it. That was
+ * already true before the store-selected path stopped querying a shared
+ * database — the query lane has always fallen back to
+ * {@link openEphemeralQueryStore} when no store is selected, which is the
+ * default, so `node:sqlite` was required on every default run. Nothing here
+ * became newly reachable; the branch is load-bearing because the FLOOR is,
+ * whichever way the lane resolves its store.
+ *
+ * The repair stays distinct from the missing-package one on purpose:
+ * "install this package" is the wrong instruction for "upgrade Node", and
+ * sending someone round that loop cannot terminate.
+ *
+ * @param error - Whatever the dynamic import threw
+ * @returns The error to raise when Node itself lacks the builtin; `undefined`
+ *   when this failure is something else and the caller should keep diagnosing
+ */
+export declare function nodeSqliteFloorFailure(error: unknown): Error | undefined;
 /**
  * Run one command's work with a projection store open for its whole duration,
  * and closed however it ends.
@@ -175,7 +267,17 @@ export declare function openPopulationCache(options: {
  *
  * It is also the `withGitSnapshotCache` bracket for the work inside it, so the
  * key and the extent filed under it come from ONE git snapshot — see the note
- * on the call below.
+ * in the body.
+ *
+ * `undefined` on a run with no store selected, which is the shape every
+ * population lane wants: no store means re-derive, not fail.
+ *
+ * ⚠️ A caller that wants to run SQL must NOT query this store. It is one
+ * database per VAT release, shared by every root on the machine, so arbitrary
+ * SQL over it answers from other repositories — see `projection-query.ts`.
+ * That is also why this is the ONLY scope over the opened store: there is no
+ * separate "opened handle" bracket for a caller wanting more than the cache,
+ * because there is nothing legitimate for such a caller to want.
  *
  * @param options - Where the corpus is
  * @param options.root - The absolute corpus root

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

@@ -1 +1 @@
-{"version":3,"file":"projection-store.d.ts","sourceRoot":"","sources":["../../src/utils/projection-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,gHAAgH;AAChH,eAAO,MAAM,cAAc,MAAM,CAAC;AAelC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAsB7C;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACzB,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GACvD,OAAO,CAAC,CAAC,CAAC,CA0BZ"}
+{"version":3,"file":"projection-store.d.ts","sourceRoot":"","sources":["../../src/utils/projection-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,KAAK,gBAAgB,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,+BAA+B,CAAC;AAKtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,gHAAgH;AAChH,eAAO,MAAM,cAAc,MAAM,CAAC;AAkBlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAsB7C;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAE3F;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAaxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACzB,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GACvD,OAAO,CAAC,CAAC,CAAC,CA0BZ"}

package/dist/utils/projection-store.js

@@ -91,6 +91,34 @@ import { isModuleMissing, reportMissingBackend } from './optional-backend.js';
 export const PROJECTION_STORE_ENV = 'VAT_PROJECTION_STORE';
 /** {@link PROJECTION_STORE_ENV}'s value that selects the SQLite backend. */
 export const PROJECTION_STORE_SQLITE = 'sqlite';
+/**
+ * Where the projection store's database lives, overriding the default.
+ *
+ * The default is `tmpdir/.vat-cache/<version>/projection-<shapeDigest>` — one
+ * database per VAT release, shared by every root on the machine. This names a
+ * different one **explicitly**, which is what an adopter with a per-job cache
+ * directory, a shared build agent running two jobs at once, or a test arm that
+ * must not touch the developer's live cache actually needs.
+ *
+ * 🪤 **What it replaces is redirecting `TMPDIR`, which works and is the wrong
+ * instrument.** `defaultStoreDirectory()` resolves through
+ * `vatCacheNamespaceRoot()` → `normalizedTmpdir()`, so pointing the OS temp
+ * directory elsewhere does move the store — along with every other temp
+ * consumer in the process, on a variable whose name is not the same on both
+ * platforms (`TMPDIR` on POSIX; `TEMP`, then `TMP`, on Windows, so setting one
+ * is silently inert on the other). It relocates the store as a side effect of
+ * relocating something larger. This variable says the one thing meant.
+ *
+ * ⚠️ It does **not** consult `XDG_CACHE_HOME` or `HOME`. A caller that set
+ * those believed it had its own database and was writing into the shared one;
+ * the fix is to name the directory here, not to add more implicit roots.
+ *
+ * An environment variable rather than a config field, for the same reason
+ * {@link PROJECTION_STORE_ENV} is one: it says where an INSTRUMENT keeps its
+ * scratch space, not what the project means, and it has to be reachable from a
+ * harness that spawns the binary.
+ */
+export const PROJECTION_STORE_DIR_ENV = 'VAT_PROJECTION_STORE_DIR';
 /**
  * The env var that turns VAT's disk caches off for a run.
  *
@@ -111,6 +139,8 @@ export const CACHE_DISABLED = '0';
  * it: RAG carries a platform-native binary, while this one carries a Node
  * version floor.
  */
+/** What Node throws for `import('node:sqlite')` before 22.13.0. */
+const UNKNOWN_BUILTIN_MODULE = 'ERR_UNKNOWN_BUILTIN_MODULE';
 const PROJECTION_STORE_BACKEND = {
     feature: 'The projection store',
     packageName: '@vibe-agent-toolkit/projection-sqlite',
@@ -193,19 +223,101 @@ export async function openPopulationCache(options) {
  * for "upgrade Node", and diagnosing a version floor as a missing dependency
  * sends a user round a loop that cannot terminate.
  *
- * @returns The opened store
+ * @returns The opened store, typed as the engine-free contract — the SQLite
+ *   backend really does return a `SqlQueryableStore`, and this narrows it away
+ *   on purpose so the population path cannot grow a query
  */
 async function loadStore() {
+    const directory = process.env[PROJECTION_STORE_DIR_ENV];
+    // Spread rather than passed, because the backend defaults the field when it is
+    // ABSENT and an explicit `undefined` is a different argument under
+    // `exactOptionalPropertyTypes`. Empty string is treated as unset: an unset
+    // variable and one exported as `''` are the same intent, and `''` would
+    // otherwise resolve to the process cwd.
+    return (await loadBackend()).openSqliteProjectionStore(directory === undefined || directory === '' ? {} : { directory });
+}
+/**
+ * Open a store that lives only in this process's memory.
+ *
+ * 🔑 **This is what keeps the query surface an ANSWER rather than a privilege.**
+ * A caller with no store selected — CI's first run, or a developer who never set
+ * the selector — still gets the same SQL over the same schema; the on-disk store
+ * only makes the second run cheap. Without it, "what does this tree contain"
+ * would be answerable only where a cache happened to exist, and two callers
+ * would hold differently-shaped views of one tree.
+ *
+ * It is a cache that cannot hit: nothing survives the close, so a caller must
+ * write the projection into it before asking anything.
+ *
+ * @returns An open, empty store; close it when done
+ */
+export async function openEphemeralQueryStore() {
+    return (await loadBackend()).openEphemeralProjectionStore();
+}
+/**
+ * Load the selected backend module, or report it as uninstalled and exit.
+ *
+ * @returns The backend's module namespace
+ */
+async function loadBackend() {
     try {
-        const backend = await import('@vibe-agent-toolkit/projection-sqlite');
-        return backend.openSqliteProjectionStore();
+        return await import('@vibe-agent-toolkit/projection-sqlite');
     }
     catch (error) {
+        const floor = nodeSqliteFloorFailure(error);
+        if (floor !== undefined)
+            throw floor;
         if (!isModuleMissing(error))
             throw error;
         reportMissingBackend(PROJECTION_STORE_BACKEND);
     }
 }
+/**
+ * The legible failure for "your Node is too old", or `undefined` when this is
+ * some other failure — including "the package is absent".
+ *
+ * Exported, and returning the error rather than throwing it, so the DIAGNOSIS
+ * is unit-testable without a mocked dynamic import. A test cannot make a mocked
+ * `import()` reject with a plain `{ code }` — the test runner wraps whatever a
+ * module factory throws in its own error, so the code never survives to be
+ * read — and the branch's whole value is the message it produces.
+ *
+ * 🪤 The two are **different error codes**, and only one of them reaches
+ * {@link isModuleMissing}. `@vibe-agent-toolkit/projection-sqlite` imports
+ * `node:sqlite`, which arrived in Node 22.13.0; on 22.0–22.12 the import fails
+ * with `ERR_UNKNOWN_BUILTIN_MODULE`, not `ERR_MODULE_NOT_FOUND`. Without this
+ * branch the user gets a bare `No such built-in module: node:sqlite` — which
+ * names neither the version floor nor the fix.
+ *
+ * ⚠️ It is reachable on EVERY `vat resources query`/`check` run, and not a
+ * corner: VAT's own floor is `>=22.0.0`, so a supported Node hits it. That was
+ * already true before the store-selected path stopped querying a shared
+ * database — the query lane has always fallen back to
+ * {@link openEphemeralQueryStore} when no store is selected, which is the
+ * default, so `node:sqlite` was required on every default run. Nothing here
+ * became newly reachable; the branch is load-bearing because the FLOOR is,
+ * whichever way the lane resolves its store.
+ *
+ * The repair stays distinct from the missing-package one on purpose:
+ * "install this package" is the wrong instruction for "upgrade Node", and
+ * sending someone round that loop cannot terminate.
+ *
+ * @param error - Whatever the dynamic import threw
+ * @returns The error to raise when Node itself lacks the builtin; `undefined`
+ *   when this failure is something else and the caller should keep diagnosing
+ */
+export function nodeSqliteFloorFailure(error) {
+    const isFloor = typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === UNKNOWN_BUILTIN_MODULE;
+    if (!isFloor)
+        return undefined;
+    return new Error('The projection store needs `node:sqlite`, which this Node does not have.'
+        + ` VAT runs on Node >= 22.0.0, but \`node:sqlite\` arrived in 22.13.0 — you are on ${process.version}.`
+        + ' Upgrade Node to 22.13.0 or newer. Installing a package will not help:'
+        + ' the module is built into Node, not published to npm.');
+}
 /**
  * Run one command's work with a projection store open for its whole duration,
  * and closed however it ends.
@@ -218,7 +330,17 @@ async function loadStore() {
  *
  * It is also the `withGitSnapshotCache` bracket for the work inside it, so the
  * key and the extent filed under it come from ONE git snapshot — see the note
- * on the call below.
+ * in the body.
+ *
+ * `undefined` on a run with no store selected, which is the shape every
+ * population lane wants: no store means re-derive, not fail.
+ *
+ * ⚠️ A caller that wants to run SQL must NOT query this store. It is one
+ * database per VAT release, shared by every root on the machine, so arbitrary
+ * SQL over it answers from other repositories — see `projection-query.ts`.
+ * That is also why this is the ONLY scope over the opened store: there is no
+ * separate "opened handle" bracket for a caller wanting more than the cache,
+ * because there is nothing legitimate for such a caller to want.
  *
  * @param options - Where the corpus is
  * @param options.root - The absolute corpus root

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

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

package/dist/utils/vat-bin-path.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where the built vat CLI entry is, for the commands that re-invoke it as a
+ * child process.
+ *
+ * ## 🪤 `dist/bin.js`, deliberately NOT `dist/bin/vat.js`
+ *
+ * `packages/lab/src/harness/instrument.ts` documents `dist/bin/vat.js` as a
+ * re-resolving WRAPPER: it looks the CLI up again at run time, so spawning it
+ * can execute a different build than the one the caller is running from. A
+ * supervisor that thinks it is bounding its own code, and a corpus runner that
+ * thinks it is auditing with its own validators, both need the entry point that
+ * cannot be redirected.
+ *
+ * ## Why the two branches
+ *
+ * `node` cannot execute `.ts`, so a caller running from SOURCE under vitest
+ * still has to reach the COMPILED entry — which is why the source-tree branch
+ * walks across to `packages/cli/dist/bin.js` rather than to a sibling. A build
+ * is therefore a precondition for every test that spawns the CLI, and a system
+ * test that skipped it would prove things about a stale `dist`.
+ *
+ * 🪤 Shared rather than copied. This resolution lived inline in
+ * `commands/corpus/runner.ts` and a second caller wanted it; a second copy is a
+ * duplication-gate failure under this repo's zero-tolerance policy, and — worse
+ * — two copies drift, so one caller would keep spawning the wrapper long after
+ * the other stopped. The `__dirname`-relative hops below are correct for THIS
+ * module's location and nothing else, which is precisely why it is not a snippet
+ * to paste.
+ */
+/**
+ * Resolve the path to the built vat CLI entry.
+ *
+ * @returns An absolute path to `dist/bin.js`
+ */
+export declare function resolveVatBinPath(): string;
+//# sourceMappingURL=vat-bin-path.d.ts.map

package/dist/utils/vat-bin-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-bin-path.d.ts","sourceRoot":"","sources":["../../src/utils/vat-bin-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAUH;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C"}