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

package/dist/utils/projection-query.js

@@ -48,9 +48,9 @@
 import { performance } from 'node:perf_hooks';
 import { allDerivedSpecs, buildResourceProjection, PROJECTION_TABLES, splitProjectionByScope, } from '@vibe-agent-toolkit/resources';
 import { gitTrackerForProjectRoot } from '../commands/audit/distributed-tree.js';
-import { evaluateAuthoredLenses } from './edge-lens-evaluation.js';
 import { populationWiring } from './population-wiring.js';
-import { openEphemeralQueryStore, withPopulationCache } from './projection-store.js';
+import { evaluateLens, lensesNamedBy } from './projection-lenses.js';
+import { openCompileProbe, openEphemeralQueryStore, withPopulationCache } from './projection-store.js';
 /**
  * The tree hash an in-memory store's one population is filed under.
  *
@@ -61,8 +61,10 @@ import { openEphemeralQueryStore, withPopulationCache } from './projection-store
  * would invite the reader to believe the ephemeral store is shareable.
  */
 const EPHEMERAL_TREE_HASH = 'ephemeral';
+/** What SQLite says when a statement names a table the schema does not have. */
+const TABLE_NOT_FOUND = 'no such table:';
 /** What SQLite says when a statement names something the schema does not have. */
-const NAME_NOT_FOUND = ['no such table:', 'no such column:'];
+const NAME_NOT_FOUND = [TABLE_NOT_FOUND, 'no such column:'];
 /**
  * Compile every statement a run intends to ask, against the schema and NO rows,
  * before anything is populated.
@@ -107,7 +109,11 @@ const NAME_NOT_FOUND = ['no such table:', 'no such column:'];
 export async function assertQueriesCompile(statements) {
     if (statements.length === 0)
         return;
-    const probe = await openEphemeralQueryStore();
+    // 🔑 A compile PROBE, not the query store: this runs before any lens is
+    // evaluated, and the query store has no table for an unevaluated relation.
+    // The probe carries every derived relation and cannot answer a query, so its
+    // empty tables can never be read as a result.
+    const probe = await openCompileProbe();
     try {
         for (const { sql, parameters } of statements) {
             try {
@@ -133,9 +139,13 @@ export async function assertQueriesCompile(statements) {
  * @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
+ * @param options.statements - Every statement this run may ask, for LENS
+ *   SELECTION only — never compiled, never bound, and deliberately separate from
+ *   `preflight`. ⛔ Omitting it evaluates EVERY lens, which is the correct answer
+ *   and the expensive one
+ * @param work - Given the asker, where its rows came from, how much of the tree
+ *   they cover, and the ROWS THEMSELVES. The store is open for exactly this call
+ *   and closed however it ends
  * @returns Whatever `work` returned
  */
 export async function withQueriedProjection(options, work) {
@@ -205,15 +215,25 @@ export async function withQueriedProjection(options, work) {
             // prevent. Overlapping spans also made `populationSecs + lensSecs`
             // over-count wall time for anyone who added them.
             const populationMs = performance.now() - populationStart;
-            // The lens's output, alongside the tree's facts. Unconditional rather
-            // than behind a flag: the relations are the answer to questions the
-            // projection was built to support, and a surface that exists only when
-            // someone remembered a flag is one nobody writes a check against. What it
-            // costs is published as `lensSecs` rather than folded into the population
-            // — a caller who finds it too expensive can see the number they are
-            // paying, which a hidden cost never permits.
+            // 🔑 The lenses this run's statements NAME, and no others — zones.md §2
+            // carries why. The relations are still not behind a flag: a surface that
+            // exists only when somebody remembered a flag is one nobody writes a check
+            // against. What decides is the statement, which cannot be forgotten.
+            //
+            // ⛔ The narrowing is safe ONLY because an unevaluated relation does not
+            // EXIST in `store`: the backend creates a derived table on the write that
+            // fills it, so a statement naming one no lens filled fails `no such table`
+            // in SQLite itself — whatever spelling slipped past the selector's scan —
+            // and {@link describeQueryFailure} says why. Create the relations up front
+            // and this becomes a silent wrong answer: an empty table selecting zero rows.
+            const lenses = lensesNamedBy(options.statements);
             const lensStart = performance.now();
-            await store.writeDerived(evaluateAuthoredLenses(projection));
+            for (const lens of lenses) {
+                // Sequential, not `Promise.all`: a lens may populate, and two
+                // populations racing for one projection store is the concurrency this
+                // lane has no reason to invite.
+                await store.writeDerived(await evaluateLens(lens, { projection, root, logger, cache }));
+            }
             const lensMs = performance.now() - lensStart;
             // The shared setup is done. Everything after this line is the caller's.
             const ask = (sql, ...parameters) => {
@@ -224,12 +244,17 @@ export async function withQueriedProjection(options, work) {
                     throw new Error(describeQueryFailure(sql, error instanceof Error ? error.message : String(error)));
                 }
             };
-            return await work(ask, { population: contributorRecords === 0 ? 'store' : 'derived', populationMs, lensMs }, 
+            return await work(ask, {
+                population: contributorRecords === 0 ? 'store' : 'derived',
+                populationMs,
+                lensMs,
+                lensesEvaluated: lenses.map((lens) => lens.name),
+            }, 
             // 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 });
+            { membersEnumerated: projection.resourceRealizations.length }, projection);
         }
         finally {
             // Closed however the work ends. An in-memory database is reclaimed with the
@@ -239,6 +264,25 @@ export async function withQueriedProjection(options, work) {
         }
     });
 }
+/**
+ * The derived relation a `no such table` failure names, if it names one.
+ *
+ * SQLite echoes the reference as written — `edges`, `EDGES`, `main.edges` — so
+ * the schema prefix is dropped and the comparison case-folds, as SQLite's own
+ * name resolution does. Names come from the relation registry, never a list
+ * kept here.
+ *
+ * @param message - What the engine said
+ * @returns The relation's registry spelling, or undefined
+ */
+function unevaluatedRelationIn(message) {
+    const at = message.indexOf(TABLE_NOT_FOUND);
+    if (at === -1)
+        return undefined;
+    const reference = message.slice(at + TABLE_NOT_FOUND.length).trim().split(/\s/u)[0] ?? '';
+    const bare = reference.slice(reference.lastIndexOf('.') + 1).toLowerCase();
+    return allDerivedSpecs().find((spec) => spec.name.toLowerCase() === bare)?.name;
+}
 /**
  * Turn a rejected statement into a message that names the surface it missed.
  *
@@ -276,6 +320,23 @@ export async function withQueriedProjection(options, work) {
 export function describeQueryFailure(sql, message) {
     if (!NAME_NOT_FOUND.some((prefix) => message.includes(prefix)))
         return message;
+    // 🚨 A MISSING DERIVED RELATION IS NOT A TYPO — it is the refusal that makes
+    // lazy lens evaluation an optimisation. The run's database creates a derived
+    // relation only when a lens fills it, so one no lens was evaluated for is
+    // absent, and SQLite refuses it rather than answering `0` from an empty table
+    // (indistinguishable from a tree with no links, and for `vat resources check`
+    // a rule that could no longer fail). The refusal is the engine's, so it holds
+    // for any spelling the lens selector's scan missed; this only says why. For
+    // `check` it surfaces as a `RESOURCE_CHECK_BROKEN` finding naming the rule.
+    // The compile preflight never reaches here with one: its probe has them all.
+    const unevaluated = unevaluatedRelationIn(message);
+    if (unevaluated !== undefined) {
+        return `${message}\n\n`
+            + `This statement reads ${unevaluated}, a derived relation that was not evaluated for this run:`
+            + ' no statement the run DECLARED names it, so no lens producing it ran and there is no answer'
+            + ' to give. Declare this statement (`vat resources query` passes the one it was given;'
+            + ' `vat resources check` passes every statement in `resources.checks`).';
+    }
     // 🪤 The derived relations belong in this listing even though they are not
     // projection tables. A user who mistypes `edge_resolution` gets "no such
     // table" and a list of everything they could have meant — and a list that

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

@@ -1 +1 @@
-{"version":3,"file":"projection-query.js","sourceRoot":"","sources":["../../src/utils/projection-query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"projection-query.js","sourceRoot":"","sources":["../../src/utils/projection-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAGjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvG;;;;;;;;GAQG;AACH,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAExC,gFAAgF;AAChF,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC,kFAAkF;AAClF,MAAM,cAAc,GAAsB,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;AAwL/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,UAAyC;IAClF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,wEAAwE;IACxE,2EAA2E;IAC3E,6EAA6E;IAC7E,8CAA8C;IAC9C,MAAM,KAAK,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,KAAK,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,UAAU,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,KAAK,CAAC,cAAc,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,oBAAoB,CAAC,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAClF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAKC,EACD,IAYmB;IAEnB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEjC,0EAA0E;IAC1E,8EAA8E;IAC9E,+EAA+E;IAC/E,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM;IACN,MAAM,oBAAoB,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAEpD,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,+EAA+E;IAC/E,+EAA+E;IAC/E,qEAAqE;IACrE,2CAA2C;IAC3C,EAAE;IACF,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,4BAA4B;IAC5B,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAE1C,+EAA+E;IAC/E,+CAA+C;IAC/C,OAAO,mBAAmB,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QACnD,2EAA2E;QAC3E,4EAA4E;QAC5E,4EAA4E;QAC5E,uEAAuE;QACvE,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,IAAI,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,MAAM,uBAAuB,CAAC;YAC/C,IAAI;YACJ,GAAG,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC;YACpD,mBAAmB,EAAE,GAAG,EAAE;gBACxB,kBAAkB,IAAI,CAAC,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;QAEH,6EAA6E;QAC7E,MAAM,KAAK,GAAG,MAAM,uBAAuB,EAAE,CAAC;QAC9C,IAAI,CAAC;YACH,2EAA2E;YAC3E,yDAAyD;YACzD,2EAA2E;YAC3E,uEAAuE;YACvE,0EAA0E;YAC1E,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,kFAAkF;sBAChF,kFAAkF;sBAClF,gEAAgE,CACnE,CAAC;YACJ,CAAC;YACD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;YAC7D,MAAM,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAClC,MAAM,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,EAAE,MAAM,CAAC,CAAC;YAC3E,uEAAuE;YACvE,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,mEAAmE;YACnE,uEAAuE;YACvE,kEAAkE;YAClE,mEAAmE;YACnE,kDAAkD;YAClD,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;YAEzD,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,qEAAqE;YACrE,EAAE;YACF,wEAAwE;YACxE,0EAA0E;YAC1E,2EAA2E;YAC3E,0EAA0E;YAC1E,2EAA2E;YAC3E,8EAA8E;YAC9E,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YACjD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YACpC,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;gBAC1B,8DAA8D;gBAC9D,sEAAsE;gBACtE,gCAAgC;gBAChC,MAAM,KAAK,CAAC,YAAY,CAAC,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YAC1F,CAAC;YACD,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC7C,wEAAwE;YAExE,MAAM,GAAG,GAAkB,CAAC,GAAG,EAAE,GAAG,UAAU,EAAE,EAAE;gBAChD,IAAI,CAAC;oBACH,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,CAAC;gBACzC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CACb,oBAAoB,CAAC,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAClF,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC;YAEF,OAAO,MAAM,IAAI,CACf,GAAG,EACH;gBACE,UAAU,EAAE,kBAAkB,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBAC1D,YAAY;gBACZ,MAAM;gBACN,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;aACjD;YACD,yEAAyE;YACzE,yEAAyE;YACzE,qEAAqE;YACrE,iEAAiE;YACjE,EAAE,iBAAiB,EAAE,UAAU,CAAC,oBAAoB,CAAC,MAAM,EAAE,EAC7D,UAAU,CACX,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,4EAA4E;YAC5E,sEAAsE;YACtE,uDAAuD;YACvD,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5C,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1F,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3E,OAAO,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,EAAE,IAAI,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,OAAe;IAC/D,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IAE/E,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,8EAA8E;IAC9E,8EAA8E;IAC9E,8EAA8E;IAC9E,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,MAAM,WAAW,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACnD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,GAAG,OAAO,MAAM;cACnB,wBAAwB,WAAW,2DAA2D;cAC9F,6FAA6F;cAC7F,sFAAsF;cACtF,uEAAuE,CAAC;IAC9E,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,0EAA0E;IAC1E,4EAA4E;IAC5E,8CAA8C;IAC9C,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,GAAG,eAAe,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAClF,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC;QAC9B,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC9E,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC;QAC9B,CAAC,CAAC,qDAAqD;QACvD,CAAC,CAAC,iDAAiD,CAAC;IAEtD,OAAO,GAAG,OAAO,OAAO,OAAO,KAAK,OAAO,EAAE,CAAC;AAChD,CAAC"}

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

@@ -47,7 +47,15 @@
 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.
+ * The env var that selects — or now, DESELECTS — a projection store for this
+ * process.
+ *
+ * 🔑 **The store is on by default, so this is the escape hatch rather than the
+ * selector.** Same shape and same reason as `VAT_RESOURCES_CRAWL`: any value the
+ * off-parser does not read as false leaves the store selected, including the
+ * historical `sqlite`, so every script and lab arm that names it explicitly
+ * keeps working and keeps MEANING the same thing. See
+ * {@link PROJECTION_STORE_OFF} for the one way out.
  *
  * An environment switch rather than a config field, for the same reason
  * `VAT_INVENTORY_CRAWL` and `VAT_RESOURCES_CRAWL` are: it selects which
@@ -57,40 +65,28 @@ import type { PopulationCache } from '@vibe-agent-toolkit/resources';
  * edits the thing it measures.
  *
  * 🔑 It is read from the environment, and **every phase now runs in the process
- * that read it** — phases used to be child processes inheriting it across a
- * `spawnSync`, which reached the same place by a longer route. `vat validate`'s
- * phases see the same selection their orchestrator did, and can no longer fail
- * to.
- *
- * 🔑 **That sharing has a within-verb instance.** `vat build`'s two
- * phases — `skills build` and `claude plugin build` — both reach the lane
- * through `withResourcePopulationSource` (see `resource-loader.ts`), and both
- * root their population at the same directory, so phase 2 reads the extent
- * phase 1 wrote. Measured on `packages/vat-development-agents` with
- * `VAT_CRAWL_TIMING`: with a cold store phase 1 files `builtin:filesystem`
- * 39.2 ms and `projection-store:write` 10.1 ms, phase 2 files neither and its
- * `resource-registry:enumerate` reads 3.6 ms against phase 1's 66.6 ms.
- *
- * It did NOT need the closure to emit reasons, which is what an earlier reading
- * of this expected: the packaging lanes consume `resource_realizations` and let
- * `walkLinkGraph` keep running on top of the registry, so the base extent alone
- * answers them — the same shape `buildResourcePopulation` already had.
- *
- * The cross-INVOCATION win is unchanged and independent: `vat validate` and
- * `vat verify` spawn a byte-identical `resources validate` child, so the second
- * hits the store.
- *
- * ⚠️ One packaging enumeration is still on the walk: `vat claude plugin build`'s
- * per-skill post-build validation, which reaches `crawlAndResolveRegistry` in
- * `packaging-validator.ts` without a source — its `withResourcePopulationSource`
- * bracket closes around `createProjectRegistry` and does not span the
- * marketplace loop. `vat skills build` no longer does: it holds one bracket over
- * the whole run, and the registry memo is keyed on the population source, so
- * both of its registries source from the projection.
+ * that read it**, so `vat validate`'s phases cannot fail to see the selection
+ * their orchestrator did. Which lanes share a store within one verb and across
+ * invocations, with the measurements, and the ⚠️ one packaging enumeration still
+ * on the walk: `docs/architecture/resource-scanning-and-caching.md` §3.7.
  */
 export declare const PROJECTION_STORE_ENV = "VAT_PROJECTION_STORE";
-/** {@link PROJECTION_STORE_ENV}'s value that selects the SQLite backend. */
+/**
+ * {@link PROJECTION_STORE_ENV}'s value that names the SQLite backend. Redundant
+ * with the default now, and kept — see
+ * `docs/architecture/resource-scanning-and-caching.md` §3.7.
+ */
 export declare const PROJECTION_STORE_SQLITE = "sqlite";
+/**
+ * The value that turns the store OFF while leaving VAT's other caches on.
+ *
+ * Read through the same {@link parseEnvBoolean} as every other VAT switch, so
+ * `0`, `false`, `no` and `n` work too. The empty string joins them: unlike
+ * {@link PROJECTION_STORE_DIR_ENV}, where empty falls back to a default
+ * directory that means something, there is nothing else for a cleared selector
+ * to mean.
+ */
+export declare const PROJECTION_STORE_OFF = "off";
 /**
  * Where the projection store's database lives, overriding the default.
  *
@@ -132,11 +128,9 @@ export declare const CACHE_ENV = "VAT_CACHE";
 /**
  * Whether this process should read and write a projection store.
  *
- * **Off unless asked for**, which is the opposite of `vat inventory`'s crawl
- * selector and matches `vat resources scan`'s. A cache changes no answer, so
- * the reason to hold it back is not correctness but evidence: the win is a
- * claim about cost, and a default flipped before the cost is measured on real
- * corpora is a claim nobody checked.
+ * **On unless turned off.** It used to be the opposite; the measurement that
+ * paid for the flip, and the blob-tier bound that had to land first, are in
+ * `docs/architecture/resource-scanning-and-caching.md` §3.7.
  *
  * Read from the environment at each call rather than memoized at module load:
  * `vitest.setup.js` deletes every `VAT_*` variable before any test module
@@ -145,7 +139,7 @@ export declare const CACHE_ENV = "VAT_CACHE";
  *
  * ## The two switches are AND-ed, and the second one is a veto
  *
- * {@link PROJECTION_STORE_ENV} says *which* backend; {@link CACHE_ENV} says
+ * {@link PROJECTION_STORE_ENV} turns off THIS cache; {@link CACHE_ENV} says
  * whether this run caches at all. A store selected while `VAT_CACHE=0` was
  * measured writing a 9.8 MB, 18,079-row store on this repository and hitting it
  * on the next run — a user who asked for no cache silently got one, and
@@ -161,7 +155,9 @@ export declare const CACHE_ENV = "VAT_CACHE";
  *
  * Only an explicit `false` vetoes. `parseEnvBoolean` returns `undefined` for a
  * value it cannot read, and an unreadable value is not something the operator
- * said — the veto has to be a statement, not a shrug.
+ * said — the veto has to be a statement, not a shrug. That reading is why both
+ * variables can be read through ONE parser even though they now sit on
+ * opposite default sides: each asks only whether the operator SAID no.
  *
  * @returns `true` when a store is selected
  */
@@ -196,9 +192,9 @@ export interface OpenedPopulationCache {
  *
  * Returns `undefined` when no store is selected, and when the tree cannot be
  * keyed — the two "carry on without a cache" answers. It does **not** return
- * `undefined` for an uninstalled backend: a user who set the selector asked for
- * a store, and answering that request by silently not having one is how an
- * opted-in cache becomes an unmeasured one.
+ * `undefined` for an uninstalled backend: the store is on unless a user turned it
+ * off, and answering that by silently not having one is how a default-on cache
+ * becomes an unmeasured one.
  *
  * @param options - Where the corpus is
  * @param options.root - The absolute corpus root. Used to find the repository;
@@ -224,6 +220,16 @@ export declare function openPopulationCache(options: {
  * @returns An open, empty store; close it when done
  */
 export declare function openEphemeralQueryStore(): Promise<ProjectionSqlite.SqlQueryableStore>;
+/**
+ * Open a compile-only probe over the full queryable schema, derived relations
+ * included — for checking statements BEFORE any population or lens has run.
+ *
+ * ⚠️ Not {@link openEphemeralQueryStore}: that store has no table for a derived
+ * relation until a lens fills it, which is how an unevaluated one is refused.
+ *
+ * @returns An open probe; close it when done
+ */
+export declare function openCompileProbe(): Promise<ProjectionSqlite.ProjectionCompileProbe>;
 /**
  * The legible failure for "your Node is too old", or `undefined` when this is
  * some other failure — including "the package is absent".
@@ -305,6 +311,19 @@ export declare function nodeSqliteFloorFailure(error: unknown): Error | undefine
  * separate "opened handle" bracket for a caller wanting more than the cache,
  * because there is nothing legitimate for such a caller to want.
  *
+ * ## 🔑 It NESTS, and the outermost scope wins
+ *
+ * A scope opened inside another over the same repository **joins** it: same
+ * cache by identity, no second database, no second `git write-tree`, and the
+ * inner scope does not close what it did not open. That lets an orchestrator
+ * hold one bracket over a whole run (`vat validate` does) while each lane
+ * underneath keeps its own and stays correct run alone. Reuse is gated on the
+ * TREE HASH, never on "a scope is open" — see {@link joinableCache}.
+ *
+ * ⚠️ The whole nest shares ONE snapshot, so work that must see its own edits as
+ * they land must not run inside a single scope. That is why a hoist is a
+ * decision rather than a refactor.
+ *
  * @param options - Where the corpus is
  * @param options.root - The absolute corpus root
  * @param work - Given the cache, or `undefined` when there is none to give

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,KAAK,gBAAgB,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,+BAA+B,CAAC;AAOtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AAmBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAmBxE;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"}
+{"version":3,"file":"projection-store.d.ts","sourceRoot":"","sources":["../../src/utils/projection-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,OAAO,KAAK,KAAK,gBAAgB,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,+BAA+B,CAAC;AAOtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAmBrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CASjD;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,CA6B7C;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAE3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,CAEzF;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAmBxE;AAgFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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,CA4BZ"}