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

package/dist/utils/package-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"package-json.js","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,KAAK,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,uBAAuB,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,wDAAwD,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"package-json.js","sourceRoot":"","sources":["../../src/utils/package-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAClH,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,KAAK,CAAC;QACjD,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,GAAG,OAAO,uBAAuB,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,GAAG,OAAO,wDAAwD,CAAC,CAAC;IACxH,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC"}

package/dist/utils/population-wiring.d.ts

@@ -1,64 +1,57 @@
 /**
- * The three arguments every CLI lane hands a projection population builder the
- * same way: the blob-stage observer, the ignore oracle, and the run's store.
+ * The one entry by which a CLI lane populates a tree from its rows: it hands the
+ * builder the ignore oracle, the run's store and the declared collections the
+ * same way every time, and reports what the population refused. The report is
+ * inside the only exported entry, so a lane cannot build a population it forgets
+ * to report.
  *
  * ## Why this is CLI code and not `resources` code
  *
- * Nothing here decides anything about a projection. The observer's whole body is
- * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to a
- * {@link Logger}, which is a CLI type no other package has; the two spreads exist
- * only because `exactOptionalPropertyTypes` makes "absent" and "present and
- * undefined" different arguments. That is command plumbing, in the same family as
- * `projection-store.ts` next door, so it stays inside the package the CLI-stays-
- * dumb rule allows it in.
+ * Nothing here decides anything about a projection. The report's whole body is
+ * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to
+ * a {@link Logger}, which is a CLI type no other package has; the
+ * spreads exist only because `exactOptionalPropertyTypes` makes "absent" and
+ * "present and undefined" different arguments. That is command plumbing, in the
+ * same family as `projection-store.ts` next door.
  *
- * ## The observer is the reason this is shared rather than retyped
+ * ## Why the report reads the projection, not the run
  *
- * `buildInventoryPopulation` and `buildClaudeContextPopulation` both REQUIRE
- * `onBlobPopulation` — a caller with nothing to do with the counts must name
- * `DISCARD_BLOB_POPULATION` rather than leave it off — because a tree whose every
- * document was declined as binary otherwise populates as empty and reports
- * success. Two hand-written copies of the reporting half is two places for that
- * report to quietly become a no-op.
+ * A store hit derives nothing. A report built from what this process derived
+ * vanished on the warm run, so `vat resources check` was silent about a binary
+ * `vat resources validate` had just stored a refusal for.
  */
-import { type BlobPopulationReport, type CollectionConfig, type PopulationCache } from '@vibe-agent-toolkit/resources';
+import { type BlobRefusalRows, type CollectionConfig, type PopulationCache } from '@vibe-agent-toolkit/resources';
 import type { GitTracker } from '@vibe-agent-toolkit/utils/git';
 import type { Logger } from './logger.js';
 /**
- * The population arguments {@link populationWiring} supplies.
+ * The population arguments {@link populateAndReport} supplies.
  *
  * Spread into a builder's options object, so the three optional inputs are
  * optional in the `exactOptionalPropertyTypes` sense — omitted entirely when
  * they are absent, never present-and-undefined.
  */
 export interface PopulationWiring {
-    onBlobPopulation: (report: BlobPopulationReport) => void;
     gitTracker?: GitTracker | undefined;
     cache?: PopulationCache | undefined;
     collections?: Readonly<Record<string, CollectionConfig>> | undefined;
 }
 /**
- * Wire one population's blob-stage observer, ignore oracle and store.
+ * Populate one tree through `build`, then report its refused content to
+ * **stderr** (callers write a parseable document to stdout), named by
+ * `population` because one command can build two — the resources lane and the
+ * claude-context lens.
  *
- * `describeBlobRefusals` returns undefined on a run that refused nothing, so a
- * clean population stays exactly as quiet as it was — which is the only thing
- * that keeps the line worth reading when it does appear.
- *
- * ⚠️ The refusals go to `logger.warn`, i.e. **stderr**. Both callers write a
- * parseable document to stdout, and a diagnostic in the middle of it breaks every
- * consumer.
- *
- * @param logger - Where blob-stage refusals are reported
- * @param gitTracker - The ignore oracle, or undefined when there is none. Not
- *   cosmetic: `resource_realizations.gitignored` is filled only when a tracker
- *   was supplied, so its absence decides whether a consumer can TELL which
- *   members were ignored
- * @param cache - The run's projection store, or undefined to re-derive
- * @param root - The project root, from which the run's declared `mimeType`
- *   routing is READ rather than passed. See {@link collectionsOption}
- * @returns The options to spread into the population builder's argument
+ * @param options - The run: `root`, `cache`, `logger`, and the `population` name
+ * @param build - Builds the population from the wiring this entry supplies
+ * @param refusalRowsOf - The rows the report reads, from a derive or a hit alike
+ * @returns Whatever `build` returned
  */
-export declare function populationWiring(logger: Logger, gitTracker: GitTracker | undefined, cache: PopulationCache | undefined, root: string): PopulationWiring;
+export declare function populateAndReport<R>(options: {
+    root: string;
+    cache: PopulationCache | undefined;
+    logger: Logger;
+    population: string;
+}, build: (wiring: PopulationWiring) => Promise<R>, refusalRowsOf: (result: R) => BlobRefusalRows): Promise<R>;
 /**
  * The project's collection declarations at `root`, or undefined for a project
  * that declares none.

package/dist/utils/population-wiring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"population-wiring.d.ts","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACzD,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,KAAK,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,gBAAgB,CAUlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CAAE,CAG9D"}
+{"version":3,"file":"population-wiring.d.ts","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAKhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,KAAK,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EACjG,KAAK,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,aAAa,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,eAAe,GAC5C,OAAO,CAAC,CAAC,CAAC,CAOZ;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CAAE,CAG9D"}

package/dist/utils/population-wiring.js

@@ -1,40 +1,51 @@
 /**
- * The three arguments every CLI lane hands a projection population builder the
- * same way: the blob-stage observer, the ignore oracle, and the run's store.
+ * The one entry by which a CLI lane populates a tree from its rows: it hands the
+ * builder the ignore oracle, the run's store and the declared collections the
+ * same way every time, and reports what the population refused. The report is
+ * inside the only exported entry, so a lane cannot build a population it forgets
+ * to report.
  *
  * ## Why this is CLI code and not `resources` code
  *
- * Nothing here decides anything about a projection. The observer's whole body is
- * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to a
- * {@link Logger}, which is a CLI type no other package has; the two spreads exist
- * only because `exactOptionalPropertyTypes` makes "absent" and "present and
- * undefined" different arguments. That is command plumbing, in the same family as
- * `projection-store.ts` next door, so it stays inside the package the CLI-stays-
- * dumb rule allows it in.
+ * Nothing here decides anything about a projection. The report's whole body is
+ * `describeBlobRefusals` — owned by `@vibe-agent-toolkit/resources` — routed to
+ * a {@link Logger}, which is a CLI type no other package has; the
+ * spreads exist only because `exactOptionalPropertyTypes` makes "absent" and
+ * "present and undefined" different arguments. That is command plumbing, in the
+ * same family as `projection-store.ts` next door.
  *
- * ## The observer is the reason this is shared rather than retyped
+ * ## Why the report reads the projection, not the run
  *
- * `buildInventoryPopulation` and `buildClaudeContextPopulation` both REQUIRE
- * `onBlobPopulation` — a caller with nothing to do with the counts must name
- * `DISCARD_BLOB_POPULATION` rather than leave it off — because a tree whose every
- * document was declined as binary otherwise populates as empty and reports
- * success. Two hand-written copies of the reporting half is two places for that
- * report to quietly become a no-op.
+ * A store hit derives nothing. A report built from what this process derived
+ * vanished on the warm run, so `vat resources check` was silent about a binary
+ * `vat resources validate` had just stored a refusal for.
  */
 import { describeBlobRefusals, } from '@vibe-agent-toolkit/resources';
+import { gitTrackerForProjectRoot } from '../commands/audit/distributed-tree.js';
 import { loadConfigCached } from './config-loader.js';
 /**
- * Wire one population's blob-stage observer, ignore oracle and store.
+ * Populate one tree through `build`, then report its refused content to
+ * **stderr** (callers write a parseable document to stdout), named by
+ * `population` because one command can build two — the resources lane and the
+ * claude-context lens.
  *
- * `describeBlobRefusals` returns undefined on a run that refused nothing, so a
- * clean population stays exactly as quiet as it was — which is the only thing
- * that keeps the line worth reading when it does appear.
- *
- * ⚠️ The refusals go to `logger.warn`, i.e. **stderr**. Both callers write a
- * parseable document to stdout, and a diagnostic in the middle of it breaks every
- * consumer.
+ * @param options - The run: `root`, `cache`, `logger`, and the `population` name
+ * @param build - Builds the population from the wiring this entry supplies
+ * @param refusalRowsOf - The rows the report reads, from a derive or a hit alike
+ * @returns Whatever `build` returned
+ */
+export async function populateAndReport(options, build, refusalRowsOf) {
+    const { root, cache, logger, population } = options;
+    const gitTracker = await gitTrackerForProjectRoot(root);
+    const result = await build(populationWiring(gitTracker, cache, root));
+    const refusals = describeBlobRefusals(refusalRowsOf(result));
+    if (refusals !== undefined)
+        logger.warn(`${population} population: ${refusals}`);
+    return result;
+}
+/**
+ * Wire one population's ignore oracle, store and declared collections.
  *
- * @param logger - Where blob-stage refusals are reported
  * @param gitTracker - The ignore oracle, or undefined when there is none. Not
  *   cosmetic: `resource_realizations.gitignored` is filled only when a tracker
  *   was supplied, so its absence decides whether a consumer can TELL which
@@ -44,13 +55,8 @@ import { loadConfigCached } from './config-loader.js';
  *   routing is READ rather than passed. See {@link collectionsOption}
  * @returns The options to spread into the population builder's argument
  */
-export function populationWiring(logger, gitTracker, cache, root) {
+function populationWiring(gitTracker, cache, root) {
     return {
-        onBlobPopulation: (report) => {
-            const refusals = describeBlobRefusals(report);
-            if (refusals !== undefined)
-                logger.warn(refusals);
-        },
         ...(gitTracker !== undefined && { gitTracker }),
         ...(cache !== undefined && { cache }),
         ...collectionsOption(root),
@@ -92,7 +98,7 @@ export function populationWiring(logger, gitTracker, cache, root) {
  *   `resources.collections` in it
  */
 export function collectionsOption(root) {
-    const collections = loadConfigCached(root)?.resources?.collections;
+    const collections = loadConfigCached(root, 'source')?.resources?.collections;
     return collections === undefined ? {} : { collections };
 }
 //# sourceMappingURL=population-wiring.js.map

package/dist/utils/population-wiring.js.map

@@ -1 +1 @@
-{"version":3,"file":"population-wiring.js","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,oBAAoB,GAIrB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAiBtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAAkC,EAClC,KAAkC,EAClC,IAAY;IAEZ,OAAO;QACL,gBAAgB,EAAE,CAAC,MAAM,EAAE,EAAE;YAC3B,MAAM,QAAQ,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,QAAQ,KAAK,SAAS;gBAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,CAAC;QACD,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;QACrC,GAAG,iBAAiB,CAAC,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY;IAEZ,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC;IACnE,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"population-wiring.js","sourceRoot":"","sources":["../../src/utils/population-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,oBAAoB,GAIrB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAEjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgBtD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiG,EACjG,KAA+C,EAC/C,aAA6C;IAE7C,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACpD,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,IAAI,QAAQ,KAAK,SAAS;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IACjF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CACvB,UAAkC,EAClC,KAAkC,EAClC,IAAY;IAEZ,OAAO;QACL,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;QACrC,GAAG,iBAAiB,CAAC,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY;IAEZ,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC;IAC7E,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;AAC1D,CAAC"}

package/dist/utils/project-root-policy.d.ts

@@ -12,6 +12,8 @@
  * `.action(...)` callbacks). Inner library functions should take the resolved
  * root as a parameter — never call `findProjectRoot` themselves.
  */
+import { type Stats } from 'node:fs';
+import { type SideOfPath, type SourceOrigin } from '@vibe-agent-toolkit/utils';
 import type { Logger } from './logger.js';
 /**
  * `required` policy — refuse to run if no projectRoot can be discovered.
@@ -47,7 +49,78 @@ export declare function projectRootOrNull(startDir: string): string | null;
  *
  * @param pathArg - The argument as typed, relative to cwd or absolute
  * @returns The resolved absolute path
- * @throws When it does not exist or is not a directory
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is not a directory
+ * @throws {FsFaultError} a `source` fault named by an argument when the `stat` throws:
+ *   absent is the table's `USAGE_INVALID`, a refusal (an `EACCES` parent) `INPUT_UNREADABLE`
  */
 export declare function assertDirectoryArgument(pathArg: string): string;
+/**
+ * What an absent input means at its call site: who named it — the refusal table decides
+ * the code from that — and the sentence naming the remedy.
+ */
+interface AbsentInput {
+    readonly origin: SourceOrigin;
+    readonly message: string;
+}
+/**
+ * The refusal for an input the CONFIG, an earlier step or the command line names whose
+ * `stat` or read threw: classified as a `source` fault of the input's origin. An absence
+ * keeps the caller's sentence — a `files[].source` nothing built, a `publish.changelog`
+ * naming no file — under the refusal the table owes that origin, carrying the classified
+ * fault as its cause; anything else is the classified fault itself.
+ */
+export declare function classifyInputFault(resolved: string, error: unknown, absent: AbsentInput): unknown;
+/** A config key naming a file that is not there: the config's mistake. */
+export declare function configNamedFileAbsent(key: string, named: string): AbsentInput;
+/**
+ * Refuse unless `resolved` can be stat'ed.
+ *
+ * @param within - The tree `resolved` is read in, whose links are read before the kernel follows
+ *   them (a project root); `resolved` itself when it IS the operator's own argument
+ * @param sideOf - The side of each path the `stat` touches — `resolved`, and each component walked beneath
+ *   `within`: a refusal is charged to the side of the path the OS refused
+ * @returns What the `stat` found
+ * @throws {CommandRefusalError} `absent` when nothing is there (the refusal its origin owes)
+ * @throws {FsFaultError} when the OS refuses the `stat`, or the chain names a network or device path
+ */
+export declare function requireInputPath(resolved: string, within: string, absent: AbsentInput, sideOf: SideOfPath): Stats;
+/**
+ * Read a UTF-8 input file, refusing like {@link requireInputPath}.
+ *
+ * @throws {CommandRefusalError} `absent` when nothing is there (the refusal its origin owes)
+ * @throws {FsFaultError} when it cannot be read
+ */
+export declare function readInputFile(resolved: string, absent: AbsentInput): string;
+/**
+ * Why a DIRECTORY argument cannot be read, or `undefined` when it can be.
+ *
+ * A probe, not a listing: the verb's own walk owns enumeration; this only asks
+ * whether it can start. A directory the OS will not let the process list or
+ * enter is an input that exists and cannot be read — `INPUT_UNREADABLE`, never
+ * "not found" and never a finding about a tree nothing was read from.
+ *
+ * @param dir - The resolved argument, known to be a directory
+ * @returns The classified `source` fault (origin `argument`), or `undefined`
+ */
+export declare function unlistableDirectoryRefusal(dir: string): unknown;
+/**
+ * {@link assertDirectoryArgument}, plus the one more way a directory argument
+ * can leave nothing to examine: the OS will not let the process read it.
+ *
+ * @param pathArg - The argument as typed, relative to cwd or absolute
+ * @returns The resolved absolute path
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is not a directory
+ * @throws {FsFaultError} when it does not exist (`USAGE_INVALID`) or cannot be listed
+ */
+export declare function assertReadableDirectoryArgument(pathArg: string): string;
+/**
+ * Why `resolved` cannot be read as a directory — absent (a classified argument fault,
+ * `USAGE_INVALID`) or not a directory (`USAGE_INVALID`), or refused by the OS (a
+ * classified fault, `INPUT_UNREADABLE`) — or `undefined`. The one judgement behind
+ * {@link assertReadableDirectoryArgument} and the skills scope guard.
+ *
+ * @param resolved - The resolved argument
+ */
+export declare function readableDirectoryRefusal(resolved: string): unknown;
+export {};
 //# sourceMappingURL=project-root-policy.d.ts.map

package/dist/utils/project-root-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-root-policy.d.ts","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS/D"}
+{"version":3,"file":"project-root-policy.d.ts","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAuC,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG1E,OAAO,EAAwI,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGrN,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAUhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAgBD;;;GAGG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAEjG;AAcD,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAE7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,KAAK,CAMjH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAM3E;AAmBD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAElE"}

package/dist/utils/project-root-policy.js

@@ -12,8 +12,10 @@
  * `.action(...)` callbacks). Inner library functions should take the resolved
  * root as a parameter — never call `findProjectRoot` themselves.
  */
-import { existsSync, statSync } from 'node:fs';
-import { findProjectRoot, safePath } from '@vibe-agent-toolkit/utils';
+import { accessSync, constants, readFileSync } from 'node:fs';
+import { fsFaultRefusal } from '@vibe-agent-toolkit/schema';
+import { classifyFsFault, findProjectRoot, isFsFaultError, refusedPathOf, requireFollowedStatSync, safePath } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError } from './command-refusal.js';
 /**
  * `required` policy — refuse to run if no projectRoot can be discovered.
  *
@@ -22,7 +24,7 @@ import { findProjectRoot, safePath } from '@vibe-agent-toolkit/utils';
 export function requireProjectRoot(startDir, commandName) {
     const root = findProjectRoot(startDir);
     if (root === null) {
-        throw new Error(`${commandName} requires a vibe-agent-toolkit.config.yaml or .git/ ancestor. ` +
+        throw new CommandRefusalError('USAGE_INVALID', `${commandName} requires a vibe-agent-toolkit.config.yaml or .git/ ancestor. ` +
             `Run from inside a VAT project or initialize one.`);
     }
     return root;
@@ -64,16 +66,152 @@ export function projectRootOrNull(startDir) {
  *
  * @param pathArg - The argument as typed, relative to cwd or absolute
  * @returns The resolved absolute path
- * @throws When it does not exist or is not a directory
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is not a directory
+ * @throws {FsFaultError} a `source` fault named by an argument when the `stat` throws:
+ *   absent is the table's `USAGE_INVALID`, a refusal (an `EACCES` parent) `INPUT_UNREADABLE`
  */
 export function assertDirectoryArgument(pathArg) {
     const resolved = safePath.resolve(pathArg);
-    if (!existsSync(resolved)) {
-        throw new Error(`Path does not exist: ${resolved}`);
+    const refusal = directoryRefusal(resolved);
+    if (refusal !== undefined)
+        throw refusal;
+    return resolved;
+}
+/**
+ * How a `stat`, `lstat` or read of a path the command line named is classified: a
+ * `source` fault of origin `argument`. Only an ABSENCE is the invocation's mistake (the
+ * table's `USAGE_INVALID`); any other error — an `EACCES` parent the process may not
+ * traverse, an `ELOOP` — means whether the path exists is unknown: the INPUT's refusal,
+ * never "does not exist" and never a scan that starts anyway. Never classify with
+ * `existsSync`: it answers `false` for both.
+ *
+ * @param path - The resolved path that was examined
+ */
+function argumentPath(path) {
+    return { side: 'source', origin: 'argument', action: 'read the path', path };
+}
+/**
+ * The refusal for an input the CONFIG, an earlier step or the command line names whose
+ * `stat` or read threw: classified as a `source` fault of the input's origin. An absence
+ * keeps the caller's sentence — a `files[].source` nothing built, a `publish.changelog`
+ * naming no file — under the refusal the table owes that origin, carrying the classified
+ * fault as its cause; anything else is the classified fault itself.
+ */
+export function classifyInputFault(resolved, error, absent) {
+    return classifyInputFaultOn('source', resolved, error, absent);
+}
+/**
+ * {@link classifyInputFault}, the refusal charged to `side`: the side of the path the OS refused, which for a
+ * walked input may be a directory above it on another side (`<project>/dist`, the tree a build writes), or the
+ * input itself when it is the run's own output (`dist/skills` under `vat build`). An absence keeps the caller's
+ * sentence, under the refusal the table owes THAT side: nothing is there to read, whoever's directory said so.
+ */
+function classifyInputFaultOn(side, resolved, error, absent) {
+    const fault = classifyFsFault(error, { side, origin: absent.origin, action: 'read the input', path: resolved });
+    if (!isFsFaultError(fault) || fault.faultClass !== 'absent')
+        return fault;
+    return new CommandRefusalError(fsFaultRefusal(side, 'absent', absent.origin).refusal, absent.message, { cause: fault });
+}
+/** A config key naming a file that is not there: the config's mistake. */
+export function configNamedFileAbsent(key, named) {
+    return { origin: 'config', message: `${key} names ${named}, which does not exist.` };
+}
+/**
+ * Refuse unless `resolved` can be stat'ed.
+ *
+ * @param within - The tree `resolved` is read in, whose links are read before the kernel follows
+ *   them (a project root); `resolved` itself when it IS the operator's own argument
+ * @param sideOf - The side of each path the `stat` touches — `resolved`, and each component walked beneath
+ *   `within`: a refusal is charged to the side of the path the OS refused
+ * @returns What the `stat` found
+ * @throws {CommandRefusalError} `absent` when nothing is there (the refusal its origin owes)
+ * @throws {FsFaultError} when the OS refuses the `stat`, or the chain names a network or device path
+ */
+export function requireInputPath(resolved, within, absent, sideOf) {
+    try {
+        return requireFollowedStatSync(resolved, within);
     }
-    if (!statSync(resolved).isDirectory()) {
-        throw new Error(`Path is not a directory: ${resolved}`);
+    catch (error) {
+        throw classifyInputFaultOn(sideOf(refusedPathOf(error, resolved)), resolved, error, absent);
     }
+}
+/**
+ * Read a UTF-8 input file, refusing like {@link requireInputPath}.
+ *
+ * @throws {CommandRefusalError} `absent` when nothing is there (the refusal its origin owes)
+ * @throws {FsFaultError} when it cannot be read
+ */
+export function readInputFile(resolved, absent) {
+    try {
+        return readFileSync(resolved, 'utf-8');
+    }
+    catch (error) {
+        throw classifyInputFault(resolved, error, absent);
+    }
+}
+/**
+ * Why `resolved` is not a usable directory, or `undefined` when it is one.
+ * A `stat` that throws is classified as the argument's fault ({@link classifyInputFault}):
+ * absent says so in the invocation's words.
+ */
+function directoryRefusal(resolved) {
+    let stats;
+    try {
+        // The operator's own argument: its own `within`.
+        stats = requireFollowedStatSync(resolved, resolved);
+    }
+    catch (error) {
+        return classifyInputFault(resolved, error, { origin: 'argument', message: `Path does not exist: ${resolved}` });
+    }
+    if (!stats.isDirectory())
+        return new CommandRefusalError('USAGE_INVALID', `Path is not a directory: ${resolved}`);
+    return undefined;
+}
+/**
+ * Why a DIRECTORY argument cannot be read, or `undefined` when it can be.
+ *
+ * A probe, not a listing: the verb's own walk owns enumeration; this only asks
+ * whether it can start. A directory the OS will not let the process list or
+ * enter is an input that exists and cannot be read — `INPUT_UNREADABLE`, never
+ * "not found" and never a finding about a tree nothing was read from.
+ *
+ * @param dir - The resolved argument, known to be a directory
+ * @returns The classified `source` fault (origin `argument`), or `undefined`
+ */
+export function unlistableDirectoryRefusal(dir) {
+    try {
+        accessSync(dir, constants.R_OK | constants.X_OK);
+        return undefined;
+    }
+    catch (error) {
+        return classifyFsFault(error, argumentPath(dir));
+    }
+}
+/**
+ * {@link assertDirectoryArgument}, plus the one more way a directory argument
+ * can leave nothing to examine: the OS will not let the process read it.
+ *
+ * @param pathArg - The argument as typed, relative to cwd or absolute
+ * @returns The resolved absolute path
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is not a directory
+ * @throws {FsFaultError} when it does not exist (`USAGE_INVALID`) or cannot be listed
+ */
+export function assertReadableDirectoryArgument(pathArg) {
+    const resolved = safePath.resolve(pathArg);
+    const refusal = readableDirectoryRefusal(resolved);
+    if (refusal !== undefined)
+        throw refusal;
     return resolved;
 }
+/**
+ * Why `resolved` cannot be read as a directory — absent (a classified argument fault,
+ * `USAGE_INVALID`) or not a directory (`USAGE_INVALID`), or refused by the OS (a
+ * classified fault, `INPUT_UNREADABLE`) — or `undefined`. The one judgement behind
+ * {@link assertReadableDirectoryArgument} and the skills scope guard.
+ *
+ * @param resolved - The resolved argument
+ */
+export function readableDirectoryRefusal(resolved) {
+    return directoryRefusal(resolved) ?? unlistableDirectoryRefusal(resolved);
+}
 //# sourceMappingURL=project-root-policy.js.map

package/dist/utils/project-root-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-root-policy.js","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAItE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,WAAmB;IACtE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,gEAAgE;YAC5E,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAc;IACnE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,CACT,oEAAoE,GAAG,iBAAiB,CACzF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"project-root-policy.js","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"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"}

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

@@ -12,7 +12,8 @@
  * `docs/architecture/zones.md` §2, "A lens is evaluated only when a statement
  * names one of its relations".
  */
-import { type DerivedTableName, type PopulationCache, type Projection } from '@vibe-agent-toolkit/resources';
+import { type DerivedTableName, type PopulationCache, type PopulationOutcome, type Projection } from '@vibe-agent-toolkit/resources';
+import type { LensPopulation } from './lens-population.js';
 import type { Logger } from './logger.js';
 /**
  * The rows one lens evaluation produced, keyed by `DERIVED_TABLES`' own keys.
@@ -24,16 +25,32 @@ import type { Logger } from './logger.js';
 export type LensRows = {
     readonly [Name in DerivedTableName]?: readonly Record<string, unknown>[];
 };
+/**
+ * What one lens evaluation produced: its rows, and where its OWN population came
+ * from — `null` for a lens that populated nothing (it read the run's projection).
+ * Required, so a lens that populates cannot leave its provenance unstated.
+ */
+export interface LensEvaluation {
+    readonly rows: LensRows;
+    readonly population: PopulationOutcome['population'] | null;
+}
+/**
+ * A run's {@link LensPopulation} from each evaluated lens's own population.
+ *
+ * @param populations - Each evaluated lens's `population`, in evaluation order
+ * @returns The run's lens provenance
+ */
+export declare function lensPopulationOf(populations: readonly LensEvaluation['population'][]): LensPopulation;
 /** Everything a lens may read while evaluating. */
 export interface LensEvaluationInput {
     /** The resources-lane projection the run already populated. */
     readonly projection: Projection;
     /** Absolute corpus root, for a lens that must populate a lane of its own. */
     readonly root: string;
-    /** Where a lens's own blob-stage refusals go — stderr. */
-    readonly logger: Logger;
     /** The run's projection store, so a lens's own population can hit it. */
     readonly cache: PopulationCache | undefined;
+    /** Where a lens that populates reports its own population's refused content. */
+    readonly logger: Logger;
 }
 /** One lens: the relations it owns, and how to produce their rows. */
 export interface ProjectionLens {
@@ -52,9 +69,10 @@ export interface ProjectionLens {
      *
      * @param input - The projection, the root, and the run's oracles
      * @returns Every relation this lens owns — all of them, every time, because
-     *   omitting one leaves its previous contents in place
+     *   omitting one leaves its previous contents in place — and where its own
+     *   population came from
      */
-    readonly evaluate: (input: LensEvaluationInput) => Promise<LensRows> | LensRows;
+    readonly evaluate: (input: LensEvaluationInput) => Promise<LensEvaluation> | LensEvaluation;
 }
 /** The authored-link lens: `lens_contexts`, `edges`, `edge_resolutions`. */
 export declare const AUTHORED_LINK_LENS: ProjectionLens;
@@ -91,8 +109,8 @@ export declare function lensesNamedBy(statements: readonly string[] | undefined)
  *
  * @param lens - The lens
  * @param input - What it may read
- * @returns Its rows
+ * @returns Its rows and its own population's provenance
  * @throws Error When the rows omit a declared relation or carry an undeclared one
  */
-export declare function evaluateLens(lens: ProjectionLens, input: LensEvaluationInput): Promise<LensRows>;
+export declare function evaluateLens(lens: ProjectionLens, input: LensEvaluationInput): Promise<LensEvaluation>;
 //# sourceMappingURL=projection-lenses.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"projection-lenses.d.ts","sourceRoot":"","sources":["../../src/utils/projection-lenses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAI7H,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,IAAI,IAAI,gBAAgB,CAAC,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;CACzE,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;CAC7C;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;CACjF;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,cAIhC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAE,cAIjC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAGtD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,cAAc,EAAE,CAMlG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAYnB"}
+{"version":3,"file":"projection-lenses.d.ts","sourceRoot":"","sources":["../../src/utils/projection-lenses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EAChB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,IAAI,IAAI,gBAAgB,CAAC,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;CACzE,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,SAAS,cAAc,CAAC,YAAY,CAAC,EAAE,GAAG,cAAc,CAIrG;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;CAC7F;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,cAKhC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAE,cAIjC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAGtD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,cAAc,EAAE,CAMlG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,cAAc,CAAC,CAazB"}