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

package/dist/utils/repeatable-option.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The collector every REPEATABLE option in this CLI uses, and the reason none
+ * of them is variadic.
+ *
+ * Commander offers two spellings for "this flag takes several values":
+ *
+ * - **Variadic** — `--param <values...>`, which consumes every following token
+ *   up to the next option-shaped one.
+ * - **Repeatable** — `--param <value>` passed more than once, accumulated by a
+ *   custom collector. This one.
+ *
+ * The variadic spelling is unusable on a command that also has a positional
+ * argument, and every command here has one. It ate the positional:
+ * `vat resources query 'SELECT ? AS x, ? AS y' --param a docs/` bound `docs/`
+ * as the SECOND SQL VALUE, left the `[path]` positional unread, and reported
+ * `status: success` at exit 0 with `y: 'docs/'` in its rows — a token the
+ * operator typed as a location, silently reinterpreted as data. On
+ * `vat skill test run <skill>` the same shape consumed the subject and the run
+ * died claiming the subject was missing.
+ *
+ * ⚠️ What the swallowed token would have DONE is a separate question, and on
+ * `query` the answer is "located the project": `[path]` there is a root
+ * locator, not a scope — see `queryCommand` — so an earlier reading of this
+ * incident as "answered about the whole tree instead of `docs/`" claimed a
+ * scoping the verb never had. The defect this module fixes is the swallow.
+ *
+ * So: no variadic options. `test/commands/no-variadic-cli-options.test.ts`
+ * enforces that against the source, because the defect is a declaration shape
+ * rather than a bug in any one command.
+ *
+ * @param value - The value Commander parsed for this occurrence of the flag
+ * @param previous - What earlier occurrences accumulated, or `undefined` for the first
+ * @returns A NEW array — never a mutation of `previous`, which on a defaulted
+ *   option is shared by every parse of the same `Option` instance
+ */
+export declare function collectRepeated(value: string, previous?: readonly string[]): string[];
+//# sourceMappingURL=repeatable-option.d.ts.map

package/dist/utils/repeatable-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatable-option.d.ts","sourceRoot":"","sources":["../../src/utils/repeatable-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAErF"}

package/dist/utils/repeatable-option.js

@@ -0,0 +1,39 @@
+/**
+ * The collector every REPEATABLE option in this CLI uses, and the reason none
+ * of them is variadic.
+ *
+ * Commander offers two spellings for "this flag takes several values":
+ *
+ * - **Variadic** — `--param <values...>`, which consumes every following token
+ *   up to the next option-shaped one.
+ * - **Repeatable** — `--param <value>` passed more than once, accumulated by a
+ *   custom collector. This one.
+ *
+ * The variadic spelling is unusable on a command that also has a positional
+ * argument, and every command here has one. It ate the positional:
+ * `vat resources query 'SELECT ? AS x, ? AS y' --param a docs/` bound `docs/`
+ * as the SECOND SQL VALUE, left the `[path]` positional unread, and reported
+ * `status: success` at exit 0 with `y: 'docs/'` in its rows — a token the
+ * operator typed as a location, silently reinterpreted as data. On
+ * `vat skill test run <skill>` the same shape consumed the subject and the run
+ * died claiming the subject was missing.
+ *
+ * ⚠️ What the swallowed token would have DONE is a separate question, and on
+ * `query` the answer is "located the project": `[path]` there is a root
+ * locator, not a scope — see `queryCommand` — so an earlier reading of this
+ * incident as "answered about the whole tree instead of `docs/`" claimed a
+ * scoping the verb never had. The defect this module fixes is the swallow.
+ *
+ * So: no variadic options. `test/commands/no-variadic-cli-options.test.ts`
+ * enforces that against the source, because the defect is a declaration shape
+ * rather than a bug in any one command.
+ *
+ * @param value - The value Commander parsed for this occurrence of the flag
+ * @param previous - What earlier occurrences accumulated, or `undefined` for the first
+ * @returns A NEW array — never a mutation of `previous`, which on a defaulted
+ *   option is shared by every parse of the same `Option` instance
+ */
+export function collectRepeated(value, previous) {
+    return [...(previous ?? []), value];
+}
+//# sourceMappingURL=repeatable-option.js.map

package/dist/utils/repeatable-option.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatable-option.js","sourceRoot":"","sources":["../../src/utils/repeatable-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,QAA4B;IACzE,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC"}

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 { GitTracker } from '@vibe-agent-toolkit/utils';
+import { ResourceRegistry, type CrawlSourceKind, type ProjectConfig, type ResourcePopulationSource } from '@vibe-agent-toolkit/resources';
+import { GitTracker } from '@vibe-agent-toolkit/utils/git';
 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,106 @@ 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` drops one at a single seam to match it (git's
+ * mode `120000` for the paths the tree snapshot described, an `lstat` for the
+ * collapsed `ls-files --others` entries that carry no mode) — so BOTH projection
+ * extents omit a symlink, committed or not, 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).
+ * The omission is no longer SILENT — each declined link is an `info` row under
+ * one of the three declined-link codes (`EXTENT_SYMLINK_NOT_REALIZED`,
+ * `EXTENT_SYMLINK_TARGET_OUTSIDE_ROOT`, `EXTENT_SYMLINK_TARGET_UNRESOLVED` — the
+ * last is a dangling in-root target) — but no such row is a `LINK_BROKEN_FILE`
+ * finding.
+ * {@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;AAEH,OAAO,EAKL,gBAAgB,EAEhB,KAAK,eAAe,EAEpB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAE9B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAmB,MAAM,+BAA+B,CAAC;AAG5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C;;;;;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;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1F;AA8DD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AAsED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAwH7B"}

package/dist/utils/resource-loader.js

@@ -1,10 +1,37 @@
 /**
  * Utilities for loading and crawling resources
  */
-import { existsSync, statSync } from 'node:fs';
-import { DEFAULT_RESOURCE_INCLUDE, ResourceRegistry, } from '@vibe-agent-toolkit/resources';
-import { GitTracker, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
+import { buildLinkAuthEngineConfig, buildResourcePopulation, DEFAULT_RESOURCE_INCLUDE, gitExtentSelected, ResourceRegistry, } from '@vibe-agent-toolkit/resources';
+import { relativeEscapesRoot, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
+import { GitTracker, gitTreeSnapshot } from '@vibe-agent-toolkit/utils/git';
 import { loadConfig } from './config-loader.js';
+import { collectionsOption } from './population-wiring.js';
+import { assertDirectoryArgument } from './project-root-policy.js';
+import { withPopulationCache } from './projection-store.js';
+/**
+ * Refuse a `resources.linkAuth` provider that cannot compile HERE, where the
+ * config is loaded, so every verb that loads it answers the same way.
+ *
+ * `buildLinkAuthEngineConfig` is the one place the per-provider compile check
+ * (`assertProviderCompiles`) lives, and the registry calls it only when it
+ * constructs the external-link validator — i.e. under `--check-external-urls`.
+ * Every other verb on this loader (`vat validate`, `vat resources validate`
+ * without the flag, `vat resources scan`, `vat rag index`) accepted an
+ * uncompilable `when` and exited 0, while the validation-code registry
+ * promised the refusal "at config load … and every other command that loads
+ * `resources.linkAuth`". The registry was right about what the contract should
+ * be; this makes the code keep it. The built config is discarded — the
+ * registry builds its own when the lane runs — because the value wanted is
+ * the throw, and calling the same function is how the two stay one check.
+ *
+ * @throws {LinkAuthConfigError} naming `providers[<n>]`, the host and the field;
+ *   every caller's catch turns a thrown error into exit 2.
+ */
+function assertLinkAuthProvidersCompile(config) {
+    const linkAuth = config.resources?.linkAuth;
+    if (linkAuth !== undefined)
+        buildLinkAuthEngineConfig(linkAuth);
+}
 /**
  * Scope resource include patterns to a subdirectory of the crawl base.
  *
@@ -41,38 +68,211 @@ function crawlOptionsForPath(pathArg, projectRoot, config, logger) {
     // safePath.relative already normalizes, but toForwardSlash makes the
     // separator assumption in the `../` test below explicit on Windows too.
     const normalizedRelDir = toForwardSlash(safePath.relative(projectRoot, resolved));
-    if (normalizedRelDir === '..' || normalizedRelDir.startsWith('../')) {
+    if (relativeEscapesRoot(normalizedRelDir)) {
         // Outside the project root, so the config's root-relative globs describe a
         // different tree and genuinely cannot apply. Say so rather than dropping
         // them silently — silent dropping is the bug this function exists to fix.
         logger.warn(`${resolved} is outside projectRoot ${projectRoot}; ` +
             `resources include/exclude patterns from the config do not apply to it`);
-        return { baseDir: resolved };
+        return { baseDir: resolved, unreadable: RESOURCES_UNREADABLE };
     }
-    assertCrawlableDirectory(resolved);
+    // The crawler used to perform this check itself, because it received the path
+    // argument as its `baseDir`. Now that `baseDir` is the project root, a bad path
+    // argument would otherwise degrade into a glob that matches nothing — a green
+    // run reporting `filesScanned: 0`.
+    assertDirectoryArgument(resolved);
     return {
         baseDir: projectRoot,
+        unreadable: RESOURCES_UNREADABLE,
         include: scopeIncludeToSubtree(DEFAULT_RESOURCE_INCLUDE, normalizedRelDir),
         ...(config?.resources?.exclude ? { exclude: config.resources.exclude } : {}),
     };
 }
 /**
- * Fail loudly on a path argument that cannot be crawled.
+ * The resources verbs' ruling for a directory the crawl cannot list: refuse
+ * the run by name, exit 2 — `vat resources validate`/`scan`/`check` and every
+ * verb that reaches this loader act on the registry as the whole population,
+ * and the projection lane behind `populationSource` refuses the same directory
+ * with the same sentence, so the two lanes cannot reach different exits.
+ * See `RegistryUnreadablePolicy` on the registry.
+ */
+const RESOURCES_UNREADABLE = 'refuse';
+/**
+ * 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.
  *
- * The crawler used to perform this check itself, because it received the path
- * argument as its `baseDir`. Now that `baseDir` is the project root, a bad path
- * argument would otherwise degrade into a glob that matches nothing — a green
- * run reporting `filesScanned: 0`.
+ * 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.
  */
-function assertCrawlableDirectory(resolved) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI path argument, resolved above
-    if (!existsSync(resolved)) {
-        throw new Error(`Path does not exist: ${resolved}`);
+export const RESOURCES_CRAWL_ENV = 'VAT_RESOURCES_CRAWL';
+/** {@link RESOURCES_CRAWL_ENV}'s value that selects the projection lane. */
+export 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 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` drops one at a single seam to match it (git's
+ * mode `120000` for the paths the tree snapshot described, an `lstat` for the
+ * collapsed `ls-files --others` entries that carry no mode) — so BOTH projection
+ * extents omit a symlink, committed or not, 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).
+ * The omission is no longer SILENT — each declined link is an `info` row under
+ * one of the three declined-link codes (`EXTENT_SYMLINK_NOT_REALIZED`,
+ * `EXTENT_SYMLINK_TARGET_OUTSIDE_ROOT`, `EXTENT_SYMLINK_TARGET_UNRESOLVED` — the
+ * last is a dangling in-root target) — but no such row is a `LINK_BROKEN_FILE`
+ * finding.
+ * {@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 function resourcesProjectionCrawlSelected() {
+    return process.env[RESOURCES_CRAWL_ENV] !== RESOURCES_CRAWL_WALK;
+}
+/**
+ * The projection-backed enumeration for this run, or `undefined` to keep the
+ * incumbent `crawlDirectory` walk.
+ *
+ * Gated on the selector alone — and NOT additionally on a discoverable project
+ * root, which is where this differs from `vat inventory`'s
+ * `populationProviderFor`. That gate exists there because inventory membership
+ * is resolved per skill against a root the extractor derives itself, so a
+ * population rooted anywhere else answers a different question.
+ *
+ * The root the caller resolved is carried ON the source rather than merely used
+ * to build it, which is what lets `ResourceRegistry.populationFrom` decline a
+ * crawl of some OTHER tree instead of answering it with this tree's ignore
+ * oracle. This function used to argue that no second root existed to disagree
+ * with; it does — `crawlOptionsForPath` re-bases `baseDir` onto a path argument
+ * that lies outside the project root, and the packaging validator's
+ * `findProjectRoot(...) ?? dirname(skillPath)` can land on a build output
+ * directory. Both are now declined rather than served.
+ *
+ * The tracker is threaded through because its absence is not cosmetic: with no
+ * tracker every realization row reads `gitignored: false`, and the population
+ * would admit the ignored half of a git tree rather than decline it. See
+ * `buildResourcePopulation`.
+ *
+ * @param root - The root this source may answer for, and no other
+ * @param gitTracker - The run's ignore oracle
+ * @param observeExtentSource - Called with the enumerator that actually ran,
+ *   once per enumerated root. The value cannot be recovered afterwards by
+ *   re-reading the environment — see {@link ResourceLoadResult.extentSource}.
+ *   🪤 On a cache hit NO enumerator runs and this still reports the one this
+ *   process selected, because the source is chosen before the store is asked
+ * @param cache - The run's projection store, or `undefined` to enumerate every
+ *   time. A SEPARATE selector from {@link RESOURCES_CRAWL_ENV}: which lane
+ *   enumerates and whether its answer is cached are independent choices, and a
+ *   cache folded into the lane switch could never be measured against it
+ * @returns A population source, or `undefined` to use the walk
+ */
+function populationSourceFor(root, gitTracker, observeExtentSource, cache) {
+    if (!resourcesProjectionCrawlSelected()) {
+        return undefined;
     }
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI path argument, existence checked above
-    if (!statSync(resolved).isDirectory()) {
-        throw new Error(`Path is not a directory: ${resolved}`);
+    return {
+        root: safePath.resolve(root),
+        enumerate: async (enumeratedRoot) => {
+            const population = await buildResourcePopulation({
+                root: enumeratedRoot,
+                gitTracker,
+                ...(cache !== undefined && { cache }),
+                // `enumeratedRoot` and this source's own `root` are the SAME directory,
+                // always: `populationFrom` compares them and declines outright when they
+                // differ, so `enumerate` is never called for another tree. Reading the
+                // declarations off the root being enumerated is therefore not a guard
+                // against a second root — it is how the declaration and the enumeration
+                // are kept demonstrably on one tree at the point of use, with no second
+                // variable to fall out of step with the one that was checked.
+                ...collectionsOption(enumeratedRoot),
+            });
+            observeExtentSource(population.extentSource);
+            return { paths: population.paths, conditions: population.conditions };
+        },
+    };
+}
+/**
+ * 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 async function withResourcePopulationSource(options, work) {
+    // Checked before anything is built or opened: an unselected lane must cost
+    // nothing, or every command pays a tracker and a store to decline them.
+    if (!resourcesProjectionCrawlSelected()) {
+        return work(undefined);
     }
+    const gitTracker = options.gitTracker ?? new GitTracker(options.root);
+    return withPopulationCache({ root: options.root }, async (cache) => {
+        // Initialized inside the bracket for the reason `loadResourcesWithConfig`
+        // gives at its own call: the store has already taken the snapshot that
+        // answers this tracker's question, so asking git again is a spawn spent
+        // rebuilding a set the process is holding.
+        if (options.gitTracker === undefined) {
+            await gitTracker.initialize();
+        }
+        return work(populationSourceFor(options.root, gitTracker, options.observeExtentSource ?? (() => undefined), cache));
+    });
 }
 /**
  * Load resources from a path with config support
@@ -107,21 +307,29 @@ export async function loadResourcesWithConfig(pathArg, projectRoot, logger) {
     const config = loadConfig(projectRoot);
     if (config) {
         logger.debug(`Loaded config from ${projectRoot}`);
+        assertLinkAuthProvidersCompile(config);
     }
-    // Create and initialize GitTracker anchored at the resolved projectRoot.
+    // Built here, but deliberately NOT initialized here — see the call inside the
+    // population-cache bracket below. The registry only reads the tracker during
+    // `crawl`, which happens inside that bracket, so nothing observes it empty.
     const gitTracker = new GitTracker(projectRoot);
-    await gitTracker.initialize();
-    const stats = gitTracker.getStats();
-    logger.debug(`GitTracker initialized with ${stats.cacheSize} tracked files`);
     // Create registry and crawl
-    // Build options conditionally to satisfy exactOptionalPropertyTypes
+    // Build options conditionally to satisfy exactOptionalPropertyTypes.
+    //
+    // 🚨 The config is handed over WHENEVER one was loaded — never gated on one of
+    // its keys. This used to read `if (config?.resources?.collections)`, written
+    // when collections were the only thing the registry read from it. The registry
+    // has since grown a second consumer, `resources.linkAuth`, and the gate made
+    // it silently inert for every adopter who declared `linkAuth` without
+    // `collections`: no rewrite, no token, no `LINK_AUTH_*` code — the anonymous
+    // lane ran and the run reported success. Every read inside the registry is
+    // already `this.config?.resources?.<key>`-guarded, so an undeclared key costs
+    // nothing; a key-gate here can only ever hide the next consumer the same way.
     const registryOptions = {
         baseDir: projectRoot,
         gitTracker,
+        ...(config === undefined ? {} : { config }),
     };
-    if (config?.resources?.collections) {
-        registryOptions.config = config;
-    }
     const registry = new ResourceRegistry(registryOptions);
     let crawlOptions;
     if (pathArg) {
@@ -136,19 +344,74 @@ export async function loadResourcesWithConfig(pathArg, projectRoot, logger) {
         logger.debug(`No path argument, using: ${projectRoot}`);
         crawlOptions = {
             baseDir: projectRoot,
+            unreadable: RESOURCES_UNREADABLE,
             // Apply include patterns from config (if specified)
             ...(config?.resources?.include ? { include: config.resources.include } : {}),
             // Apply exclude patterns from config (if specified)
             ...(config?.resources?.exclude ? { exclude: config.resources.exclude } : {}),
         };
     }
-    await registry.crawl(crawlOptions);
+    // Which lane enumerates. Applied to the options both branches above produced,
+    // so the path-argument case and the whole-root case cannot end up on different
+    // crawlers — the bug shape this file already carries one fix for.
+    let extentSource = null;
+    // The store brackets the crawl and is closed however the crawl ends. Nothing
+    // outside this bracket can reach it: the population source is called from
+    // inside `registry.crawl` and nowhere else.
+    const lane = await withPopulationCache({ root: projectRoot }, async (cache) => {
+        // The git enumerator takes a `gitTreeSnapshot` during the crawl below no matter
+        // what. Taking it HERE instead is the same snapshot moved a few lines earlier —
+        // the open bracket memoizes it, so the enumerator's own call becomes a lookup —
+        // and it puts the answer in hand before the tracker asks its question.
+        //
+        // ⚠️ Gated, because ungated this is a LOSS: a snapshot is `git add --all` plus
+        // two more spawns, and on the filesystem enumerator or the incumbent walk
+        // nothing would ever consume it. Guarded by `gitExtentSelected` rather than a
+        // second copy of the condition, so the two cannot drift.
+        //
+        // ⚠️⚠️ BOTH HALVES, and the second one is not redundant. `gitExtentSelected`
+        // answers "which ENUMERATOR would the projection lane use", which stopped
+        // implying "the projection lane is running" the moment git became the extent
+        // default: under `VAT_RESOURCES_CRAWL=walk` it still answers true inside any
+        // repository, so the walk paid for a snapshot nothing consumed — measured at
+        // 7 git spawns on the escape hatch against 2 before the flip. The lane check
+        // is the half that went missing when the default moved.
+        if (resourcesProjectionCrawlSelected() && gitExtentSelected(projectRoot)) {
+            gitTreeSnapshot({ cwd: projectRoot });
+        }
+        // Now inside the bracket, and after the snapshot above. The set a snapshot
+        // describes — `tracked ∪ (untracked ∧ ¬ignored)` — is exactly the set this
+        // would otherwise spawn `git ls-files --cached --others --exclude-standard` to
+        // rebuild, so on the git lane it reads the answer instead of re-asking. Where
+        // no snapshot was taken the peek misses and it spawns exactly as before.
+        await gitTracker.initialize();
+        logger.debug(`GitTracker initialized with ${gitTracker.getStats().cacheSize} tracked files`);
+        const populationSource = populationSourceFor(projectRoot, gitTracker, (kind) => {
+            extentSource = kind;
+        }, cache);
+        const selected = populationSource ? 'projection' : 'walk';
+        if (populationSource) {
+            logger.debug(`Enumerating via the projection lane (${RESOURCES_CRAWL_ENV}=${RESOURCES_CRAWL_PROJECTION})`);
+            crawlOptions = { ...crawlOptions, populationSource };
+        }
+        else {
+            // Said for the same reason the projection branch says it, and the symmetry
+            // is the point: a marker that only one lane emits makes the other lane
+            // identifiable by ABSENCE, which is indistinguishable from a build too old
+            // to have either lane.
+            logger.debug(`Enumerating via the incumbent walk (${RESOURCES_CRAWL_ENV} unset)`);
+        }
+        await registry.crawl(crawlOptions);
+        return selected;
+    });
     return {
         scanPath: pathArg ?? projectRoot,
         projectRoot,
         config,
         registry,
         gitTracker,
+        lane,
+        extentSource,
     };
 }
 //# sourceMappingURL=resource-loader.js.map