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

package/dist/utils/rag-database.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one check every `vat rag` verb makes before acting on a database: that it
+ * IS a RAG database — and, for `stats`, `query` and `clear`, that it is there.
+ * Apart from the command modules, which do not read the filesystem themselves.
+ */
+import { type FsSide } from '@vibe-agent-toolkit/utils';
+/**
+ * Refuse a path that is not a RAG database, before anything opens or removes it.
+ *
+ * `stats`, `query` and `clear` act on a database `vat rag index` made. Opening
+ * a path creates it, so a mistyped `--db` used to leave a new directory behind
+ * and publish `ok`; and `clear` removes recursively, so a `--db` naming any
+ * other directory — the project, `$HOME` — used to be deleted with
+ * `cleared: true`. A database is a directory holding only VAT's LanceDB tables
+ * (or nothing, after an index of nothing); anything else is refused.
+ *
+ * @param dbPath - The resolved database path
+ * @param explicit - Whether `--db` named it; otherwise it is the project default
+ * @param side - The verb's side of the database: `source` for `stats` and `query`,
+ *   which read it; `destination` for `clear`, which removes it
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a `--db` that names nothing
+ *   or a file, and for a `--db` directory holding anything but a RAG database
+ *   (operating-system litter such as `.DS_Store` aside); `INPUT_UNREADABLE` for
+ *   a project `.rag-db` that is a file or holds anything else
+ * @throws {FsFaultError} for a path the OS will not list, classified on `side`
+ * @throws {VatError} `RAG_INDEX_EMPTY` (`INPUT_UNREADABLE`) when the project
+ *   default is absent: nothing has been indexed, the same refusal a query over
+ *   an empty index gets
+ */
+export declare function requireExistingDatabase(dbPath: string, explicit: boolean, side: FsSide): void;
+/**
+ * The refusal a database `vat rag clear` will not remove is — a link (removing it would leave
+ * the database it names in place), or a directory holding anything a database does not, as
+ * `removeRagDatabase`'s plan judged it (`TREE_DEST_NOT_OWNED`): the invocation's to fix for a
+ * `--db`, the project's state for its own `.rag-db`, as {@link refuseForeignEntries} decides.
+ *
+ * A link's refusal ends with the command that clears the database it leads to.
+ *
+ * @param error - What the removal threw
+ * @param dbPath - The database path the removal was given
+ * @param explicit - Whether `--db` named the database; otherwise it is the project default
+ * @returns The refusal for a not-owned database; any other error as it is
+ */
+export declare function notRemovableRefusal(error: unknown, dbPath: string, explicit: boolean): unknown;
+/**
+ * Make sure `vat rag index` can write its database at `dbPath`, before LanceDB
+ * is handed the path: one that cannot hold a database is the caller's input, and
+ * one the OS will not let the run write is the run not finishing — neither is a
+ * defect in VAT, which is what LanceDB's own failure for either read as.
+ *
+ * @param dbPath - The resolved database path
+ * @param explicit - Whether `--db` named it; otherwise it is the project default
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a `--db` that is (or lies
+ *   under) a file or a directory holding anything a RAG database does not,
+ *   `INPUT_UNREADABLE` for a project `.rag-db` that is either
+ * @throws {FsFaultError} a `destination` fault for a path the OS will not examine
+ *   or list, and for a database directory the run cannot create or write
+ *   (`RUN_INCOMPLETE`): the database is what `vat rag index` writes
+ */
+export declare function requireWritableDatabase(dbPath: string, explicit: boolean): void;
+//# sourceMappingURL=rag-database.d.ts.map

package/dist/utils/rag-database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-database.d.ts","sourceRoot":"","sources":["../../src/utils/rag-database.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAwC,KAAK,MAAM,EAAyK,MAAM,2BAA2B,CAAC;AA8ErQ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7F;AA8BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAK9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAiB/E"}

package/dist/utils/rag-database.js

@@ -0,0 +1,178 @@
+/**
+ * The one check every `vat rag` verb makes before acting on a database: that it
+ * IS a RAG database — and, for `stats`, `query` and `clear`, that it is there.
+ * Apart from the command modules, which do not read the filesystem themselves.
+ */
+import { accessSync, constants, readdirSync } from 'node:fs';
+import { foreignDatabaseEntries, linkedDatabasePath } from '@vibe-agent-toolkit/rag-lancedb';
+import { classifyFsFault, isFileInTheWayError, isPathAbsentError, isVatError, mkdirSyncReal, RAG_INDEX_EMPTY_CODE, requireFollowedStatSync, TREE_DEST_NOT_OWNED_CODE, VatError, withFsFaultSync } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError } from './command-refusal.js';
+/** How many foreign entries a refusal names before it summarises the rest. */
+const NAMED_ENTRIES = 5;
+/**
+ * How a database path's filesystem fault is classified: on the verb's side (`source` for
+ * the verbs that read it, `destination` for `index` and `clear`, which write and remove
+ * it), named by `--db` (`argument`) or the project's own default (`content`).
+ */
+function databaseFault(dbPath, side, explicit, action) {
+    return { side, origin: explicit ? 'argument' : 'content', action, path: dbPath };
+}
+function probe(fault, read) {
+    try {
+        return { found: read() };
+    }
+    catch (error) {
+        if (isFileInTheWayError(error))
+            return { missing: 'file-in-the-way' };
+        if (isPathAbsentError(error))
+            return { missing: 'absent' };
+        throw classifyFsFault(error, fault);
+    }
+}
+/**
+ * `stat` the database path. It is the operator's own (`--db`, or the project's default location
+ * the operator runs the verb on): its own `within`.
+ */
+function statDatabasePath(dbPath) {
+    return requireFollowedStatSync(dbPath, dbPath);
+}
+/** Whether a probe met a file in the way. */
+const fileInTheWay = (probed) => 'missing' in probed && probed.missing === 'file-in-the-way';
+/**
+ * Why a path that would not list is not a directory: it is a file itself, or
+ * something above it is (`readdir` says ENOTDIR for both).
+ *
+ * @param dbPath - The path `readdir` refused with ENOTDIR
+ * @param fault - How a `stat` the OS refuses is classified
+ * @returns The sentence naming which
+ */
+function notADirectory(dbPath, fault) {
+    return fileInTheWay(probe(fault, () => statDatabasePath(dbPath))) ? `a path above ${dbPath} is not a directory` : `${dbPath} is not a directory`;
+}
+/**
+ * List the database directory, refusing a path that is not one.
+ *
+ * @param dbPath - The resolved database path
+ * @param explicit - Whether `--db` named it
+ * @param side - The verb's side of the database
+ * @returns Its typed entries
+ */
+function listDatabase(dbPath, explicit, side) {
+    const fault = databaseFault(dbPath, side, explicit, 'list the RAG database');
+    const listed = probe(fault, () => readdirSync(dbPath, { withFileTypes: true }));
+    if ('found' in listed)
+        return listed.found;
+    if (fileInTheWay(listed)) {
+        // A --db naming a file is the invocation's mistake; the project's own `.rag-db` being one is its state.
+        throw new CommandRefusalError(explicit ? 'USAGE_INVALID' : 'INPUT_UNREADABLE', `Not a RAG database: ${notADirectory(dbPath, fault)}.`);
+    }
+    // A --db naming nothing is the invocation's mistake; the project's own default missing means nothing was indexed.
+    throw explicit
+        ? new CommandRefusalError('USAGE_INVALID', `Path does not exist: ${dbPath}`)
+        : new VatError(RAG_INDEX_EMPTY_CODE, `No data indexed yet: there is no RAG database at ${dbPath}. Run vat rag index first.`);
+}
+/**
+ * Refuse a path that is not a RAG database, before anything opens or removes it.
+ *
+ * `stats`, `query` and `clear` act on a database `vat rag index` made. Opening
+ * a path creates it, so a mistyped `--db` used to leave a new directory behind
+ * and publish `ok`; and `clear` removes recursively, so a `--db` naming any
+ * other directory — the project, `$HOME` — used to be deleted with
+ * `cleared: true`. A database is a directory holding only VAT's LanceDB tables
+ * (or nothing, after an index of nothing); anything else is refused.
+ *
+ * @param dbPath - The resolved database path
+ * @param explicit - Whether `--db` named it; otherwise it is the project default
+ * @param side - The verb's side of the database: `source` for `stats` and `query`,
+ *   which read it; `destination` for `clear`, which removes it
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a `--db` that names nothing
+ *   or a file, and for a `--db` directory holding anything but a RAG database
+ *   (operating-system litter such as `.DS_Store` aside); `INPUT_UNREADABLE` for
+ *   a project `.rag-db` that is a file or holds anything else
+ * @throws {FsFaultError} for a path the OS will not list, classified on `side`
+ * @throws {VatError} `RAG_INDEX_EMPTY` (`INPUT_UNREADABLE`) when the project
+ *   default is absent: nothing has been indexed, the same refusal a query over
+ *   an empty index gets
+ */
+export function requireExistingDatabase(dbPath, explicit, side) {
+    refuseForeignEntries(dbPath, listDatabase(dbPath, explicit, side), explicit, 'Nothing was read or removed', 'the directory vat rag index wrote');
+}
+/**
+ * Refuse a database directory listing anything a database `vat rag index` made
+ * would not hold.
+ *
+ * @param dbPath - The resolved database path
+ * @param entries - Its typed listing
+ * @param explicit - Whether `--db` named it; otherwise it is the project default
+ * @param untouched - What the refusal left alone, the sentence that opens its fix
+ * @param wanted - What a `--db` should name instead
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a `--db`, `INPUT_UNREADABLE`
+ *   for the project's own `.rag-db`
+ */
+function refuseForeignEntries(dbPath, entries, explicit, untouched, wanted) {
+    const foreign = foreignDatabaseEntries(dbPath, entries);
+    if (foreign.length === 0)
+        return;
+    const named = foreign.slice(0, NAMED_ENTRIES).join(', ');
+    const more = foreign.length > NAMED_ENTRIES ? ` and ${foreign.length - NAMED_ENTRIES} more` : '';
+    // A --db naming the wrong directory is the invocation's mistake; the project's own
+    // `.rag-db` holding something else is the project's state — no --db was given to fix.
+    throw new CommandRefusalError(explicit ? 'USAGE_INVALID' : 'INPUT_UNREADABLE', `Not a RAG database: ${dbPath} holds ${named}${more}, which no database vat rag index made would hold. ` +
+        (explicit
+            ? `${untouched}; point --db at ${wanted}.`
+            : `${untouched}; move those entries out of the project's .rag-db, or name another database with --db.`));
+}
+/**
+ * The refusal a database `vat rag clear` will not remove is — a link (removing it would leave
+ * the database it names in place), or a directory holding anything a database does not, as
+ * `removeRagDatabase`'s plan judged it (`TREE_DEST_NOT_OWNED`): the invocation's to fix for a
+ * `--db`, the project's state for its own `.rag-db`, as {@link refuseForeignEntries} decides.
+ *
+ * A link's refusal ends with the command that clears the database it leads to.
+ *
+ * @param error - What the removal threw
+ * @param dbPath - The database path the removal was given
+ * @param explicit - Whether `--db` named the database; otherwise it is the project default
+ * @returns The refusal for a not-owned database; any other error as it is
+ */
+export function notRemovableRefusal(error, dbPath, explicit) {
+    if (!isVatError(error, TREE_DEST_NOT_OWNED_CODE))
+        return error;
+    const real = linkedDatabasePath(dbPath);
+    const remedy = real === undefined ? '' : ` Run vat rag clear --db ${real} to clear the database itself.`;
+    return new CommandRefusalError(explicit ? 'USAGE_INVALID' : 'INPUT_UNREADABLE', `Not removed: ${error.message}.${remedy}`, { cause: error });
+}
+/**
+ * Make sure `vat rag index` can write its database at `dbPath`, before LanceDB
+ * is handed the path: one that cannot hold a database is the caller's input, and
+ * one the OS will not let the run write is the run not finishing — neither is a
+ * defect in VAT, which is what LanceDB's own failure for either read as.
+ *
+ * @param dbPath - The resolved database path
+ * @param explicit - Whether `--db` named it; otherwise it is the project default
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a `--db` that is (or lies
+ *   under) a file or a directory holding anything a RAG database does not,
+ *   `INPUT_UNREADABLE` for a project `.rag-db` that is either
+ * @throws {FsFaultError} a `destination` fault for a path the OS will not examine
+ *   or list, and for a database directory the run cannot create or write
+ *   (`RUN_INCOMPLETE`): the database is what `vat rag index` writes
+ */
+export function requireWritableDatabase(dbPath, explicit) {
+    const inputRefusal = explicit ? 'USAGE_INVALID' : 'INPUT_UNREADABLE';
+    const fault = databaseFault(dbPath, 'destination', explicit, 'examine the RAG database directory');
+    const stats = probe(fault, () => statDatabasePath(dbPath));
+    if (fileInTheWay(stats)) {
+        throw new CommandRefusalError(inputRefusal, `Cannot index into ${dbPath}: a path above it is not a directory.`);
+    }
+    if (!('found' in stats)) {
+        withFsFaultSync({ ...fault, action: 'create the RAG database directory' }, () => mkdirSyncReal(dbPath, { recursive: true }));
+        return;
+    }
+    if (!stats.found.isDirectory()) {
+        throw new CommandRefusalError(inputRefusal, `Cannot index into ${dbPath}: it is not a directory, so it cannot hold a RAG database.`);
+    }
+    // LanceDB writes its tables into whatever directory it is handed: `--db .` filled the project root.
+    refuseForeignEntries(dbPath, listDatabase(dbPath, explicit, 'destination'), explicit, 'Nothing was indexed', 'a RAG database, an empty directory or a path that does not exist yet');
+    withFsFaultSync({ ...fault, action: 'write into the RAG database directory' }, () => accessSync(dbPath, constants.W_OK));
+}
+//# sourceMappingURL=rag-database.js.map

package/dist/utils/rag-database.js.map

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

package/dist/utils/relation-limits.d.ts

@@ -30,9 +30,9 @@ import { type StatedLimit } from '@vibe-agent-toolkit/resources';
 /** What a report carries when a lens with stated bounds was evaluated. */
 interface RelationBounds {
     /** The prose frame the limits are read under, stated once. */
-    readonly boundsStatement?: string;
+    boundsStatement?: string;
     /** The signed, directional list — what the rows do NOT settle. */
-    readonly limits?: readonly StatedLimit[];
+    limits?: StatedLimit[];
 }
 /**
  * The bounds to publish beside an answer, given the lenses the run evaluated.
@@ -42,6 +42,11 @@ interface RelationBounds {
  * `limits: []` would read as "nothing bounds this answer", which is a stronger
  * claim than "this answer contains no row anything bounds".
  *
+ * The limits are COPIED out of the readonly registry list: the answer is
+ * spread into a published document, and a published document owns no
+ * reference into module state a later render could mutate. `vat resources
+ * check` and `vat resources query` both publish it, through this one function.
+ *
  * @param lensesEvaluated - The run's `lensesEvaluated`, as the provenance names them
  * @returns The bounds keys, or an empty object
  */

package/dist/utils/relation-limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relation-limits.d.ts","sourceRoot":"","sources":["../../src/utils/relation-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAIvC,0EAA0E;AAC1E,UAAU,cAAc;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAMpF"}
+{"version":3,"file":"relation-limits.d.ts","sourceRoot":"","sources":["../../src/utils/relation-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAIvC,0EAA0E;AAC1E,UAAU,cAAc;IACtB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAMpF"}

package/dist/utils/relation-limits.js

@@ -36,6 +36,11 @@ import { CLAUDE_CONTEXT_LENS } from './projection-lenses.js';
  * `limits: []` would read as "nothing bounds this answer", which is a stronger
  * claim than "this answer contains no row anything bounds".
  *
+ * The limits are COPIED out of the readonly registry list: the answer is
+ * spread into a published document, and a published document owns no
+ * reference into module state a later render could mutate. `vat resources
+ * check` and `vat resources query` both publish it, through this one function.
+ *
  * @param lensesEvaluated - The run's `lensesEvaluated`, as the provenance names them
  * @returns The bounds keys, or an empty object
  */
@@ -44,7 +49,7 @@ export function relationBoundsFor(lensesEvaluated) {
         return {};
     return {
         boundsStatement: CLAUDE_CONTEXT_BOUNDS_STATEMENT,
-        limits: CLAUDE_CONTEXT_RELATION_LIMITS,
+        limits: CLAUDE_CONTEXT_RELATION_LIMITS.map((limit) => ({ ...limit })),
     };
 }
 //# sourceMappingURL=relation-limits.js.map

package/dist/utils/relation-limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"relation-limits.js","sourceRoot":"","sources":["../../src/utils/relation-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAU7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,eAAkC;IAClE,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACnE,OAAO;QACL,eAAe,EAAE,+BAA+B;QAChD,MAAM,EAAE,8BAA8B;KACvC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"relation-limits.js","sourceRoot":"","sources":["../../src/utils/relation-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAU7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,eAAkC;IAClE,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACnE,OAAO;QACL,eAAe,EAAE,+BAA+B;QAChD,MAAM,EAAE,8BAA8B,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;KACtE,CAAC;AACJ,CAAC"}

package/dist/utils/relativize-paths.d.ts

@@ -42,4 +42,27 @@ export declare function relativizePath(absolutePath: string, root: string): stri
  *   coordinate systems — so a producer that adds a carrier must name it here.
  */
 export declare function relativizePathEntries<T extends PathEntry>(entries: readonly T[], root: string, nestedKeys?: readonly string[]): T[];
+/**
+ * A relativized location, or `undefined` when it has no relative spelling.
+ *
+ * On Windows a target on another drive than its root has no path relative to
+ * it: `path.relative` hands back the absolute one, which a published finding's
+ * `location` refuses — so a run that let it through died on its own document.
+ * The lanes that can meet a cross-drive path ask here and degrade (omit the
+ * location) or refuse ({@link relativeLocationOrRefuse}).
+ *
+ * @param location - What `issueLocation` / `safePath.relative` returned
+ * @returns The location, unchanged, when it is relative
+ */
+export declare function relativeLocationOrUndefined(location: string): string | undefined;
+/**
+ * A relativized location, or the invocation's refusal when it has none.
+ *
+ * @param location - What `issueLocation` / `safePath.relative` returned
+ * @param root - What it is relative to, for the message
+ * @param verb - The command, for the message (`vat agent validate`)
+ * @returns The location, unchanged, when it is relative
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is absolute (another drive)
+ */
+export declare function relativeLocationOrRefuse(location: string, root: string, verb: string): string;
 //# sourceMappingURL=relativize-paths.d.ts.map

package/dist/utils/relativize-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relativize-paths.d.ts","sourceRoot":"","sources":["../../src/utils/relativize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,SAAS,EACvD,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,CAAC,EAAE,CAEL"}
+{"version":3,"file":"relativize-paths.d.ts","sourceRoot":"","sources":["../../src/utils/relativize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,SAAS,EACvD,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,CAAC,EAAE,CAEL;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7F"}

package/dist/utils/relativize-paths.js

@@ -15,7 +15,8 @@
  * which values are absolute would silently corrupt an already-relative one.
  * The caller names the nested carriers it owns instead.
  */
-import { issueLocation } from '@vibe-agent-toolkit/utils';
+import { isAbsoluteAnyPlatform, issueLocation } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError } from './command-refusal.js';
 /**
  * Re-base one absolute path onto `root`, as a forward-slashed relative path.
  *
@@ -64,4 +65,34 @@ function relativizeEntry(entry, root, nestedKeys) {
 export function relativizePathEntries(entries, root, nestedKeys = []) {
     return entries.map((entry) => relativizeEntry(entry, root, nestedKeys));
 }
+/**
+ * A relativized location, or `undefined` when it has no relative spelling.
+ *
+ * On Windows a target on another drive than its root has no path relative to
+ * it: `path.relative` hands back the absolute one, which a published finding's
+ * `location` refuses — so a run that let it through died on its own document.
+ * The lanes that can meet a cross-drive path ask here and degrade (omit the
+ * location) or refuse ({@link relativeLocationOrRefuse}).
+ *
+ * @param location - What `issueLocation` / `safePath.relative` returned
+ * @returns The location, unchanged, when it is relative
+ */
+export function relativeLocationOrUndefined(location) {
+    return isAbsoluteAnyPlatform(location) ? undefined : location;
+}
+/**
+ * A relativized location, or the invocation's refusal when it has none.
+ *
+ * @param location - What `issueLocation` / `safePath.relative` returned
+ * @param root - What it is relative to, for the message
+ * @param verb - The command, for the message (`vat agent validate`)
+ * @returns The location, unchanged, when it is relative
+ * @throws {CommandRefusalError} `USAGE_INVALID` when it is absolute (another drive)
+ */
+export function relativeLocationOrRefuse(location, root, verb) {
+    const relative = relativeLocationOrUndefined(location);
+    if (relative !== undefined)
+        return relative;
+    throw new CommandRefusalError('USAGE_INVALID', `${verb} reports locations relative to ${root}, and ${location} has no path relative to it (it is on another drive). Run from that drive.`);
+}
 //# sourceMappingURL=relativize-paths.js.map

package/dist/utils/relativize-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"relativize-paths.js","sourceRoot":"","sources":["../../src/utils/relativize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAO1D;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,IAAY;IAC/D,MAAM,QAAQ,GAAG,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC1C,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,KAAQ,EACR,IAAY,EACZ,UAA6B;IAE7B,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IACjE,4EAA4E;IAC5E,2EAA2E;IAC3E,oCAAoC;IACpC,MAAM,GAAG,GAAG,GAAyC,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CACtC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAqB,EACrB,IAAY,EACZ,aAAgC,EAAE;IAElC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AAC1E,CAAC"}
+{"version":3,"file":"relativize-paths.js","sourceRoot":"","sources":["../../src/utils/relativize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAO3D;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,IAAY;IAC/D,MAAM,QAAQ,GAAG,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC1C,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,KAAQ,EACR,IAAY,EACZ,UAA6B;IAE7B,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IACjE,4EAA4E;IAC5E,2EAA2E;IAC3E,oCAAoC;IACpC,MAAM,GAAG,GAAG,GAAyC,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CACtC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAqB,EACrB,IAAY,EACZ,aAAgC,EAAE;IAElC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAgB;IAC1D,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB,EAAE,IAAY,EAAE,IAAY;IACnF,MAAM,QAAQ,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,IAAI,mBAAmB,CAC3B,eAAe,EACf,GAAG,IAAI,kCAAkC,IAAI,SAAS,QAAQ,4EAA4E,CAC3I,CAAC;AACJ,CAAC"}

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

@@ -1,7 +1,7 @@
 /**
  * Utilities for loading and crawling resources
  */
-import { ResourceRegistry, type CrawlSourceKind, type ProjectConfig, type ResourcePopulationSource } from '@vibe-agent-toolkit/resources';
+import { ResourceRegistry, type CrawlPopulation, type CrawlSourceKind, type PopulationOutcome, type ProjectConfig, type ResourcePopulationSource } from '@vibe-agent-toolkit/resources';
 import { GitTracker } from '@vibe-agent-toolkit/utils/git';
 import type { Logger } from './logger.js';
 /**
@@ -10,7 +10,37 @@ import type { Logger } from './logger.js';
  * `walk` is the incumbent `crawlDirectory` route; `projection` is the
  * projection lane behind {@link RESOURCES_CRAWL_ENV}.
  */
-export type ResourceCrawlLane = 'walk' | 'projection';
+export type ResourceCrawlLane = CrawlPopulation['lane'];
+/**
+ * The published `population` an observation implies: `null` for the walk —
+ * offered no source, or declined the one it was offered — because nothing was
+ * populated from or into the store.
+ *
+ * @param observation - The load's one observation
+ * @returns `'store'`, `'derived'` or `null`
+ */
+export declare function publishedPopulation(observation: CrawlPopulation): PopulationOutcome['population'] | null;
+/**
+ * Which enumerator the projection lane used, or `null` when the walk ran and
+ * there was no extent to source.
+ *
+ * Reported for the same reason the lane is, one level down. The 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.
+ *
+ * 🪤 NOT a cache-hit marker: on a hit no enumerator runs and it still names the
+ * one this process selected, because the source is chosen before the store is
+ * asked.
+ *
+ * @param population - The load's population
+ * @returns The enumerator, or `null` for the walk
+ */
+export declare function extentSourceOf(population: CrawlPopulation): CrawlSourceKind | null;
 export interface ResourceLoadResult {
     scanPath: string;
     projectRoot: string;
@@ -18,30 +48,20 @@ export interface ResourceLoadResult {
     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.
+     * Where the population came from: the `CrawlPopulation` the crawl itself
+     * returned, carried here unchanged — the one channel, so a load cannot report
+     * a lane its crawl did not take. `{ lane: 'walk' }` both when the projection
+     * lane is not selected and when the crawl declined the 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.
+     * Reported as a fact about the run rather than about the environment that
+     * requested it: 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. See {@link publishedPopulation} and
+     * {@link extentSourceOf} for the two views callers publish.
      */
-    extentSource: CrawlSourceKind | null;
+    population: CrawlPopulation;
 }
 /**
  * Scope resource include patterns to a subdirectory of the crawl base.
@@ -55,6 +75,21 @@ export interface ResourceLoadResult {
  * `docs/**\/*.md` still matches `docs/a.md`.
  */
 export declare function scopeIncludeToSubtree(include: readonly string[], relDir: string): string[];
+/**
+ * Refuse a `--collection` that names no collection the project declares.
+ *
+ * A typo'd filter used to run the verb over zero resources and answer with a
+ * run-integrity finding (or, in `scan`, a zero count under the typo'd name) —
+ * a report about a collection that does not exist. It is the invocation's
+ * mistake, and `resources validate` and `resources scan` refuse it the same way.
+ * A declared collection that matched no file is NOT refused here: that is a run
+ * over nothing, and the writer's run-integrity refusal says so.
+ *
+ * @param config - The loaded project config, when there is one
+ * @param collection - The `--collection` value, when one was passed
+ * @throws {CommandRefusalError} `USAGE_INVALID` naming the declared collections
+ */
+export declare function assertDeclaredCollection(config: ProjectConfig | undefined, collection: string | undefined): void;
 /**
  * The env var that selects the crawler behind every resources-crawling verb —
  * `vat resources scan`/`validate`, `vat rag index`, the pipeline oracles, and
@@ -80,6 +115,17 @@ export declare const RESOURCES_CRAWL_PROJECTION = "projection";
  * name it explicitly keep working and keep MEANING the same thing.
  */
 export declare const RESOURCES_CRAWL_WALK = "walk";
+/**
+ * The debug line naming the lane a crawl was offered, for every verb that
+ * offers one. Each lane says it — a marker only one lane emitted would make the
+ * other identifiable by ABSENCE, which is indistinguishable from a build too
+ * old to have either lane — and there is no source only when the walk was
+ * selected, so the walk's line names {@link RESOURCES_CRAWL_WALK}.
+ *
+ * @param populationSource - The source offered to the crawl, if any
+ * @returns The line to log
+ */
+export declare function crawlLaneDebugLine(populationSource: ResourcePopulationSource | undefined): string;
 /**
  * Whether this process should source the resources population from a projection.
  *
@@ -99,9 +145,10 @@ export declare const RESOURCES_CRAWL_WALK = "walk";
  * 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`
+ * one of the four declined-link codes (`EXTENT_SYMLINK_NOT_REALIZED`,
+ * `EXTENT_SYMLINK_TARGET_OUTSIDE_ROOT`, `EXTENT_SYMLINK_TARGET_UNRESOLVED` for a
+ * dangling in-root target, `EXTENT_SYMLINK_TARGET_UNREADABLE` for one the OS
+ * would not resolve) — but no such row is a `LINK_BROKEN_FILE`
  * finding.
  * {@link RESOURCES_CRAWL_WALK} is the one-value escape hatch meanwhile.
  *
@@ -144,16 +191,12 @@ export declare function resourcesProjectionCrawlSelected(): boolean;
  * @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
@@ -181,7 +224,8 @@ export declare function withResourcePopulationSource<T>(options: {
  * @param pathArg - Path argument from CLI (optional)
  * @param projectRoot - Pre-resolved project root from the CLI boundary
  * @param logger - Logger instance
- * @returns Resource load result with registry and metadata
+ * @returns Resource load result with registry, metadata and the population the
+ *   crawl returned
  */
 export declare function loadResourcesWithConfig(pathArg: string | undefined, projectRoot: string, logger: Logger): Promise<ResourceLoadResult>;
 //# sourceMappingURL=resource-loader.d.ts.map

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;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"}
+{"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,EACpB,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAE9B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAmB,MAAM,+BAA+B,CAAC;AAI5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,eAAe,GAAG,iBAAiB,CAAC,YAAY,CAAC,GAAG,IAAI,CAExG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CAElF;AAED,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;;;;;;;;;;;;;OAaG;IACH,UAAU,EAAE,eAAe,CAAC;CAC7B;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAShH;AAgED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,wBAAwB,GAAG,SAAS,GAAG,MAAM,CAIjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AAmED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACrC,EACD,IAAI,EAAE,CAAC,gBAAgB,EAAE,wBAAwB,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3E,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CA+G7B"}