@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.3

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

@@ -0,0 +1,186 @@
+/**
+ * Selecting, opening and keying the **projection store** — the cross-process
+ * cache that makes a second population of an unchanged tree cheap.
+ *
+ * ## Why the CLI owns this and `resources` does not
+ *
+ * `@vibe-agent-toolkit/resources` states the {@link ProjectionStore} contract
+ * and never picks a backend, for the same reason it states the parse contract
+ * and never picks a parser: it is the toolkit's most widely installed package,
+ * and a storage engine is a *choice*. The choice is made here, at the edge that
+ * already owns every other optional backend — see `optional-backend.ts`, whose
+ * header names a projection store as one of the shapes it exists for.
+ *
+ * So `populate()` takes a {@link PopulationCache} it is handed, and this module
+ * is the only place in the toolkit that knows `@vibe-agent-toolkit/projection-
+ * sqlite` exists.
+ *
+ * ## The key, and why it is a whole-repository tree hash
+ *
+ * A stored extent is filed under `(rootId, treeHash)`. `populate()` derives the
+ * root id itself so a caller cannot file one root's contents under another's;
+ * this module supplies the other half.
+ *
+ * {@link gitTreeSnapshot} answers it with `git write-tree` against a throwaway
+ * index, which covers staged edits, unstaged edits and untracked files, and
+ * carries **no timestamp** — byte-identical content always produces the same
+ * hash. 🪤 Never `git stash create`: a stash is a *commit*, so two calls over
+ * identical content agree only within the same wall-clock second, and every
+ * read would miss.
+ *
+ * ⚠️ That hash covers the whole **repository**, not the subtree the root names.
+ * An edit anywhere in the repository therefore cools the cache for every root
+ * inside it. This is conservative in the safe direction and cheap to be
+ * conservative about — `git write-tree` against a throwaway index is the same
+ * call `vibe-validate` makes on every commit.
+ *
+ * ## An opted-in cache that quietly does nothing is worse than no cache
+ *
+ * Every failure here is loud, and that is deliberate rather than harsh. A
+ * selector nobody honours produces a measurement arm that believes it is
+ * testing a cache and is testing an ordinary cold run — the "subject that
+ * exercises nothing looks like a clean result" failure that has already cost
+ * this project one whole A/B. So an uninstalled backend exits with the seam's
+ * standard legible error, and a tree that cannot be keyed says so on stderr
+ * rather than silently declining.
+ */
+import type { PopulationCache } from '@vibe-agent-toolkit/resources';
+/**
+ * The env var that selects a projection store for this process.
+ *
+ * An environment switch rather than a config field, for the same reason
+ * `VAT_INVENTORY_CRAWL` and `VAT_RESOURCES_CRAWL` are: it selects which
+ * INSTRUMENT runs, not what the project means, and it has to be reachable from
+ * the lab, which spawns the binary and controls its environment. A config field
+ * would put the A and B arms inside the subject's own tree, where a measurement
+ * edits the thing it measures.
+ *
+ * 🔑 It is read from the environment and therefore **inherited by every phase
+ * child**. `runPhase` passes no `env` to `spawnSync`, so `vat validate`'s
+ * children see the same selection their parent did.
+ *
+ * 🔑 **That inheritance now 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.
+ */
+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";
+/**
+ * The env var that turns VAT's disk caches off for a run.
+ *
+ * Not this module's invention — `ParseCache` has read it since the parse cache
+ * shipped, and `vat`'s root `--no-cache` exports it from a `preAction` hook so
+ * the decision reaches every spawned phase. Named here rather than spelled
+ * inline so the projection store is visibly the same tenant as the caches the
+ * flag was written for.
+ */
+export declare const CACHE_ENV = "VAT_CACHE";
+/** {@link CACHE_ENV}'s one off value. Exactly `'0'`, never truthiness — see {@link projectionStoreSelected}. */
+export declare const CACHE_DISABLED = "0";
+/**
+ * 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.
+ *
+ * Read from the environment at each call rather than memoized at module load:
+ * `vitest.setup.js` deletes every `VAT_*` variable before any test module
+ * loads, so a module-level binding would make the switch unobservable to every
+ * test that sets it.
+ *
+ * ## The two switches are AND-ed, and the second one is a veto
+ *
+ * {@link PROJECTION_STORE_ENV} says *which* backend; {@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
+ * `vat cache`'s own help text described three caches while a fourth was being
+ * written beside them.
+ *
+ * 🪤 Compared against `'0'` exactly, never for truthiness, matching
+ * `ParseCache`'s `env['VAT_CACHE'] !== '0'`. `VAT_CACHE=1` is the value an
+ * operator writes to turn caching ON, and a truthiness test would read it as a
+ * reason to decline.
+ *
+ * @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. */
+export interface OpenedPopulationCache {
+    /** Hand this to `populate()`. */
+    readonly cache: PopulationCache;
+    /**
+     * Close the underlying connection.
+     *
+     * Must be called. A `DatabaseSync` left open holds its file handle and, in
+     * WAL mode, its read transaction — see `projection-sqlite`'s note on why an
+     * unfinalized read statement pins a connection to a stale snapshot.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Open the projection store this process selected, keyed to one tree.
+ *
+ * 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.
+ *
+ * @param options - Where the corpus is
+ * @param options.root - The absolute corpus root. Used to find the repository;
+ *   the resulting hash covers that whole repository, not this subtree
+ * @returns The cache and its closer, or `undefined` to populate uncached
+ */
+export declare function openPopulationCache(options: {
+    root: string;
+}): Promise<OpenedPopulationCache | undefined>;
+/**
+ * Run one command's work with a projection store open for its whole duration,
+ * and closed however it ends.
+ *
+ * A scope rather than a bare open/close pair, because the store must outlive the
+ * call that builds a population source and not merely the call that uses it: the
+ * inventory extractor MEMOIZES its population provider and may reach it well
+ * after the frame that supplied it has returned. A store closed at the end of
+ * that frame would be closed under its own consumer.
+ *
+ * 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.
+ *
+ * @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
+ * @returns Whatever `work` returned
+ */
+export declare function withPopulationCache<T>(options: {
+    root: string;
+}, work: (cache: PopulationCache | undefined) => Promise<T>): Promise<T>;
+//# sourceMappingURL=projection-store.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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"}

package/dist/utils/projection-store.js

@@ -0,0 +1,255 @@
+/**
+ * Selecting, opening and keying the **projection store** — the cross-process
+ * cache that makes a second population of an unchanged tree cheap.
+ *
+ * ## Why the CLI owns this and `resources` does not
+ *
+ * `@vibe-agent-toolkit/resources` states the {@link ProjectionStore} contract
+ * and never picks a backend, for the same reason it states the parse contract
+ * and never picks a parser: it is the toolkit's most widely installed package,
+ * and a storage engine is a *choice*. The choice is made here, at the edge that
+ * already owns every other optional backend — see `optional-backend.ts`, whose
+ * header names a projection store as one of the shapes it exists for.
+ *
+ * So `populate()` takes a {@link PopulationCache} it is handed, and this module
+ * is the only place in the toolkit that knows `@vibe-agent-toolkit/projection-
+ * sqlite` exists.
+ *
+ * ## The key, and why it is a whole-repository tree hash
+ *
+ * A stored extent is filed under `(rootId, treeHash)`. `populate()` derives the
+ * root id itself so a caller cannot file one root's contents under another's;
+ * this module supplies the other half.
+ *
+ * {@link gitTreeSnapshot} answers it with `git write-tree` against a throwaway
+ * index, which covers staged edits, unstaged edits and untracked files, and
+ * carries **no timestamp** — byte-identical content always produces the same
+ * hash. 🪤 Never `git stash create`: a stash is a *commit*, so two calls over
+ * identical content agree only within the same wall-clock second, and every
+ * read would miss.
+ *
+ * ⚠️ That hash covers the whole **repository**, not the subtree the root names.
+ * An edit anywhere in the repository therefore cools the cache for every root
+ * inside it. This is conservative in the safe direction and cheap to be
+ * conservative about — `git write-tree` against a throwaway index is the same
+ * call `vibe-validate` makes on every commit.
+ *
+ * ## An opted-in cache that quietly does nothing is worse than no cache
+ *
+ * Every failure here is loud, and that is deliberate rather than harsh. A
+ * selector nobody honours produces a measurement arm that believes it is
+ * testing a cache and is testing an ordinary cold run — the "subject that
+ * exercises nothing looks like a clean result" failure that has already cost
+ * this project one whole A/B. So an uninstalled backend exits with the seam's
+ * standard legible error, and a tree that cannot be keyed says so on stderr
+ * rather than silently declining.
+ */
+import { gitTreeSnapshot, withGitSnapshotCache } from '@vibe-agent-toolkit/utils';
+import { isModuleMissing, reportMissingBackend } from './optional-backend.js';
+/**
+ * The env var that selects a projection store for this process.
+ *
+ * An environment switch rather than a config field, for the same reason
+ * `VAT_INVENTORY_CRAWL` and `VAT_RESOURCES_CRAWL` are: it selects which
+ * INSTRUMENT runs, not what the project means, and it has to be reachable from
+ * the lab, which spawns the binary and controls its environment. A config field
+ * would put the A and B arms inside the subject's own tree, where a measurement
+ * edits the thing it measures.
+ *
+ * 🔑 It is read from the environment and therefore **inherited by every phase
+ * child**. `runPhase` passes no `env` to `spawnSync`, so `vat validate`'s
+ * children see the same selection their parent did.
+ *
+ * 🔑 **That inheritance now 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.
+ */
+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';
+/**
+ * The env var that turns VAT's disk caches off for a run.
+ *
+ * Not this module's invention — `ParseCache` has read it since the parse cache
+ * shipped, and `vat`'s root `--no-cache` exports it from a `preAction` hook so
+ * the decision reaches every spawned phase. Named here rather than spelled
+ * inline so the projection store is visibly the same tenant as the caches the
+ * flag was written for.
+ */
+export const CACHE_ENV = 'VAT_CACHE';
+/** {@link CACHE_ENV}'s one off value. Exactly `'0'`, never truthiness — see {@link projectionStoreSelected}. */
+export const CACHE_DISABLED = '0';
+/**
+ * The backend as a user is told to install it.
+ *
+ * Named separately from the RAG backend's entry because the *reason* it ships
+ * apart is different, and the install message is the only place a user learns
+ * it: RAG carries a platform-native binary, while this one carries a Node
+ * version floor.
+ */
+const PROJECTION_STORE_BACKEND = {
+    feature: 'The projection store',
+    packageName: '@vibe-agent-toolkit/projection-sqlite',
+};
+/**
+ * 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.
+ *
+ * Read from the environment at each call rather than memoized at module load:
+ * `vitest.setup.js` deletes every `VAT_*` variable before any test module
+ * loads, so a module-level binding would make the switch unobservable to every
+ * test that sets it.
+ *
+ * ## The two switches are AND-ed, and the second one is a veto
+ *
+ * {@link PROJECTION_STORE_ENV} says *which* backend; {@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
+ * `vat cache`'s own help text described three caches while a fourth was being
+ * written beside them.
+ *
+ * 🪤 Compared against `'0'` exactly, never for truthiness, matching
+ * `ParseCache`'s `env['VAT_CACHE'] !== '0'`. `VAT_CACHE=1` is the value an
+ * operator writes to turn caching ON, and a truthiness test would read it as a
+ * reason to decline.
+ *
+ * @returns `true` when a store is selected
+ */
+export function projectionStoreSelected() {
+    if (process.env[CACHE_ENV] === CACHE_DISABLED)
+        return false;
+    return process.env[PROJECTION_STORE_ENV] === PROJECTION_STORE_SQLITE;
+}
+/**
+ * Open the projection store this process selected, keyed to one tree.
+ *
+ * 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.
+ *
+ * @param options - Where the corpus is
+ * @param options.root - The absolute corpus root. Used to find the repository;
+ *   the resulting hash covers that whole repository, not this subtree
+ * @returns The cache and its closer, or `undefined` to populate uncached
+ */
+export async function openPopulationCache(options) {
+    if (!projectionStoreSelected())
+        return undefined;
+    // Before the import, so a corpus outside a repository costs nothing and says
+    // why. `gitTreeSnapshot` returns null for every "git could not answer" case —
+    // no `git` on PATH, not a repository, a bare or unreadable one — and an empty
+    // snapshot of an initialized repository stays distinguishable from it.
+    const snapshot = gitTreeSnapshot({ cwd: options.root });
+    if (snapshot === null) {
+        process.stderr.write(`${PROJECTION_STORE_ENV} is set, but ${options.root} is not inside a readable git`
+            + ' repository, so there is no deterministic key to store a projection under.'
+            + ' Populating without a cache.\n');
+        return undefined;
+    }
+    const store = await loadStore();
+    return {
+        cache: { store, treeHash: snapshot.hash },
+        close: () => store.close(),
+    };
+}
+/**
+ * Load the selected backend, or report it as uninstalled and exit.
+ *
+ * 🪤 Only `ERR_MODULE_NOT_FOUND` means "not installed". A Node older than
+ * 22.13.0 has no `node:sqlite` at all and fails with a *different* code, which
+ * must propagate as itself: "install this package" would be the wrong repair
+ * 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
+ */
+async function loadStore() {
+    try {
+        const backend = await import('@vibe-agent-toolkit/projection-sqlite');
+        return backend.openSqliteProjectionStore();
+    }
+    catch (error) {
+        if (!isModuleMissing(error))
+            throw error;
+        reportMissingBackend(PROJECTION_STORE_BACKEND);
+    }
+}
+/**
+ * Run one command's work with a projection store open for its whole duration,
+ * and closed however it ends.
+ *
+ * A scope rather than a bare open/close pair, because the store must outlive the
+ * call that builds a population source and not merely the call that uses it: the
+ * inventory extractor MEMOIZES its population provider and may reach it well
+ * after the frame that supplied it has returned. A store closed at the end of
+ * that frame would be closed under its own consumer.
+ *
+ * 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.
+ *
+ * @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
+ * @returns Whatever `work` returned
+ */
+export async function withPopulationCache(options, work) {
+    // ONE git snapshot for the whole scope, and this is the level that gets it:
+    // `openPopulationCache` below takes one to derive the store key, and the crawl
+    // that runs inside `work` takes another to enumerate the extent — same
+    // repository, sequentially, ~195 ms and ~159 ms measured on a large monorepo.
+    //
+    // The correctness half matters more than the saving. Taken separately, a
+    // working-tree edit landing between them makes the two snapshots DIFFERENT
+    // answers, and the extent from the second is then filed under the key from the
+    // first: a cache entry whose key does not describe its contents, written
+    // silently. The bracket closes that race rather than merely deduplicating.
+    //
+    // Opened here rather than around either consumer because it must enclose BOTH
+    // — a bracket opened deeper than one of them dedupes nothing while looking
+    // exactly like a bracket that works. Every CLI entry into the projection lane
+    // (`inventory`, `resource-loader`'s two) reaches the store through this scope,
+    // so this one placement covers all of them.
+    return withGitSnapshotCache(async () => {
+        const opened = await openPopulationCache(options);
+        if (opened === undefined)
+            return work(undefined);
+        try {
+            return await work(opened.cache);
+        }
+        finally {
+            await opened.close();
+        }
+    });
+}
+//# sourceMappingURL=projection-store.js.map

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

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

package/dist/utils/resource-loader.d.ts

@@ -1,15 +1,47 @@
 /**
  * Utilities for loading and crawling resources
  */
-import { ResourceRegistry, type ProjectConfig } from '@vibe-agent-toolkit/resources';
+import { ResourceRegistry, type CrawlSourceKind, type ProjectConfig, type ResourcePopulationSource } from '@vibe-agent-toolkit/resources';
 import { GitTracker } from '@vibe-agent-toolkit/utils';
 import type { Logger } from './logger.js';
+/**
+ * Which enumerator produced a load's population.
+ *
+ * `walk` is the incumbent `crawlDirectory` route; `projection` is the
+ * projection lane behind {@link RESOURCES_CRAWL_ENV}.
+ */
+export type ResourceCrawlLane = 'walk' | 'projection';
 export interface ResourceLoadResult {
     scanPath: string;
     projectRoot: string;
     config: ProjectConfig | undefined;
     registry: ResourceRegistry;
     gitTracker: GitTracker | undefined;
+    /**
+     * Which lane enumerated, as a fact about the run rather than about the
+     * environment that requested it.
+     *
+     * Reported so that a population can be held against another one: two scans of
+     * the same tree that disagree are only interpretable if each says which
+     * enumerator produced it. Reading the env var back instead would prove what
+     * was ASKED for, never what happened — a distinction that has already voided
+     * one whole A/B on this codebase, where both arms silently ran the incumbent.
+     */
+    lane: ResourceCrawlLane;
+    /**
+     * Which enumerator the projection lane used, or `null` when the walk ran and
+     * there was no extent to source.
+     *
+     * Reported for the same reason {@link ResourceCrawlLane} is, one level down.
+     * `lane` distinguishes the walk from the projection; it does NOT distinguish
+     * the projection's two enumerators, and `VAT_EXTENT_SOURCE` is exactly the
+     * axis a flip decision turns on. Without this, both arms of that A/B report
+     * `projection` and two identical populations mean either "the enumerators
+     * agree" or "the switch was ignored" — indistinguishable, and the second is
+     * reachable, because `crawlSourceFor` falls back to the walk without saying
+     * so when the root is not in a repository.
+     */
+    extentSource: CrawlSourceKind | null;
 }
 /**
  * Scope resource include patterns to a subdirectory of the crawl base.
@@ -23,6 +55,100 @@ export interface ResourceLoadResult {
  * `docs/**\/*.md` still matches `docs/a.md`.
  */
 export declare function scopeIncludeToSubtree(include: readonly string[], relDir: string): string[];
+/**
+ * The env var that selects the crawler behind every resources-crawling verb —
+ * `vat resources scan`/`validate`, `vat rag index`, the pipeline oracles, and
+ * (via {@link withResourcePopulationSource}) the packaging verbs
+ * `vat skills build`/`validate` and `vat claude plugin build`, which is what
+ * puts `vat build` on the lane at all.
+ *
+ * An environment switch rather than a config field, for the same reason
+ * `VAT_INVENTORY_CRAWL` is one: it selects which INSTRUMENT runs, not what
+ * the project means, and it has to be reachable from the lab, which spawns the
+ * binary and controls its environment. A config field would put the A and B arms
+ * inside the subject's own tree, where a measurement edits the thing it measures.
+ */
+export declare const RESOURCES_CRAWL_ENV = "VAT_RESOURCES_CRAWL";
+/** {@link RESOURCES_CRAWL_ENV}'s value that selects the projection lane. */
+export declare const RESOURCES_CRAWL_PROJECTION = "projection";
+/**
+ * {@link RESOURCES_CRAWL_ENV}'s value that opts BACK to the incumbent walk.
+ *
+ * The projection lane is the default now, so this is the escape hatch rather
+ * than the selector. Any other value — including the historical `projection` —
+ * leaves the projection lane selected, so existing scripts and lab arms that
+ * name it explicitly keep working and keep MEANING the same thing.
+ */
+export declare const RESOURCES_CRAWL_WALK = "walk";
+/**
+ * Whether this process should source the resources population from a projection.
+ *
+ * **Defaults to the projection lane.** Both lanes now enumerate
+ * `tracked ∪ (untracked ∧ ¬ignored)` — `ResourceRegistry.crawl` passes
+ * `includeUntracked: true` per `docs/architecture/resource-scanning-and-caching.md`
+ * §2.1 — so the population question they answer is the same one.
+ *
+ * ⚠️⚠️ **ONE DISAGREEMENT SURVIVES, AND IT DROPS FINDINGS: SYMLINKS.** The
+ * `filesystem` extent crawls with `followSymlinks: false` and records no link's
+ * own path, and `GitCrawlSource` skips mode `120000` deliberately to match it —
+ * so BOTH projection extents omit a committed symlink that the incumbent walk
+ * includes. For an out-of-tree target those bytes have no other path into the
+ * population, which means **a broken symlink the walk reports as
+ * `LINK_BROKEN_FILE` is not reported on this lane.** That is a real loss, it is
+ * known, and it is the cost this default was accepted at; closing it is its own
+ * change (teaching an extent to admit `120000` entries as their own paths).
+ * {@link RESOURCES_CRAWL_WALK} is the one-value escape hatch meanwhile.
+ *
+ * Read from the environment at each call rather than memoized at module load:
+ * `vitest.setup.js` deletes every `VAT_*` variable before any test module loads,
+ * so a module-level binding would make the switch unobservable to every test
+ * that sets it.
+ *
+ * @returns `true` when the projection lane is selected
+ */
+export declare function resourcesProjectionCrawlSelected(): boolean;
+/**
+ * Run one command's work with the projection-backed population source it
+ * selected, and the store that answers it open for the whole call.
+ *
+ * The lane-selection seam for every command that builds its OWN registry rather
+ * than going through {@link loadResourcesWithConfig} — `vat skills build` and
+ * `vat claude plugin build` (via `createProjectRegistry`) and
+ * `vat skills validate` (via its shared-context registry). Those three are what
+ * put `vat build` on the projection lane at all: before this, that verb reached
+ * a projection store on NO phase.
+ *
+ * Same selector, same store, same ignore oracle as the resource loader —
+ * deliberately, and not merely for tidiness. A second way to decide the lane is
+ * a second thing to keep in step, and a packaging lane that answered the
+ * selector differently from the validation lane would make a whole-run A/B
+ * uninterpretable: half the phases on one population, half on the other, and
+ * nothing in the output saying so.
+ *
+ * ⚠️ The tracker is **not optional dressing**. With no `GitTracker` every
+ * realization row reads `gitignored: false`, so the population would admit the
+ * ignored half of a git tree — generated markdown, caches, vendored corpora —
+ * and the packaging run would start bundling and validating files the project
+ * told git to forget. One is built here when the caller has none, rooted at the
+ * same root the population is enumerated from.
+ *
+ * @param options - Where the corpus is, and what to reuse
+ * @param options.root - The absolute corpus root, which is also the basis every
+ *   enumerated path is returned against
+ * @param options.gitTracker - An already-initialized tracker to reuse. Omit to
+ *   have one built, which costs a `git ls-files` spawn — and only when the lane
+ *   is actually selected
+ * @param options.observeExtentSource - Called with the enumerator that ran, once
+ *   per enumerated root. 🪤 NOT a cache-hit marker: on a hit no enumerator runs
+ *   and this still reports the one this process selected
+ * @param work - Given the source, or `undefined` when the walk stays selected
+ * @returns Whatever `work` returned
+ */
+export declare function withResourcePopulationSource<T>(options: {
+    root: string;
+    gitTracker?: GitTracker | undefined;
+    observeExtentSource?: ((kind: CrawlSourceKind) => void) | undefined;
+}, work: (populationSource: ResourcePopulationSource | undefined) => Promise<T>): Promise<T>;
 /**
  * Load resources from a path with config support
  *

package/dist/utils/resource-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-loader.d.ts","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAEL,gBAAgB,EAEhB,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAA4B,MAAM,2BAA2B,CAAC;AAGjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1F;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAuD7B"}
+{"version":3,"file":"resource-loader.d.ts","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAIL,gBAAgB,EAEhB,KAAK,eAAe,EAEpB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAE9B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAA6C,MAAM,2BAA2B,CAAC;AAGlG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC;;;;;;;;;OASG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1F;AA+CD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,mBAAmB,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACrE,EACD,IAAI,EAAE,CAAC,gBAAgB,EAAE,wBAAwB,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3E,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CA8G7B"}