@shrkcrft/boundaries 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/util/read-scope.d.ts

@@ -0,0 +1,14 @@
+import type { IUnreadFile } from './unread-file.js';
+/**
+ * What one rule's walk covered: the glob-matched files in its scope that were
+ * READ, and the ones that were not. `readScopeCoverage` folds this into the
+ * rule's coverage record. It is the only function that decides how an unread
+ * file changes a verdict.
+ */
+export interface IReadScope {
+    /** Glob-matched files in the rule's scope that the reader read. */
+    readonly read: number;
+    /** Glob-matched files in the rule's scope that it did not read. */
+    readonly unread: readonly IUnreadFile[];
+}
+//# sourceMappingURL=read-scope.d.ts.map

package/dist/util/read-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-scope.d.ts","sourceRoot":"","sources":["../../src/util/read-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC"}

package/dist/util/read-scope.js

@@ -0,0 +1 @@
+export {};

package/dist/util/read-selected-files.d.ts

@@ -0,0 +1,16 @@
+import type { IMatchedFiles } from './matched-files.js';
+/**
+ * THE reader for ONE glob list: the one reader's positive walk
+ * (`readMatchingFiles`, memoised), narrowed to the files the list SELECTS
+ * (`globListSelects` — an inclusion glob matches, no negation does) and to the
+ * unread entries in front of it (`unreadMatching`, negation-aware).
+ *
+ * Every single-list plane reader goes through here — an extraction source, an
+ * extractor baseline, a doc-reference rule, a generated tree, a trace — so "which
+ * files does this list read?" has one answer, and an over-cap file the author
+ * excluded never makes the rule PARTIAL. A caller walking the UNION of several
+ * lists must not use this on the union (one list's `!` would leak into
+ * another's scope): walk the union, then select per list.
+ */
+export declare function readSelectedFiles(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): IMatchedFiles;
+//# sourceMappingURL=read-selected-files.d.ts.map

package/dist/util/read-selected-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-selected-files.d.ts","sourceRoot":"","sources":["../../src/util/read-selected-files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,aAAa,CAOf"}

package/dist/util/read-selected-files.js

@@ -0,0 +1,25 @@
+import { globListSelects } from "../scan/glob.js";
+import { unreadMatching } from "./read-scope-coverage.js";
+import { readMatchingFiles } from "./walk-files.js";
+/**
+ * THE reader for ONE glob list: the one reader's positive walk
+ * (`readMatchingFiles`, memoised), narrowed to the files the list SELECTS
+ * (`globListSelects` — an inclusion glob matches, no negation does) and to the
+ * unread entries in front of it (`unreadMatching`, negation-aware).
+ *
+ * Every single-list plane reader goes through here — an extraction source, an
+ * extractor baseline, a doc-reference rule, a generated tree, a trace — so "which
+ * files does this list read?" has one answer, and an over-cap file the author
+ * excluded never makes the rule PARTIAL. A caller walking the UNION of several
+ * lists must not use this on the union (one list's `!` would leak into
+ * another's scope): walk the union, then select per list.
+ */
+export function readSelectedFiles(root, globs, excludeDirs = new Set(), allowDotDirs = new Set()) {
+    const matched = readMatchingFiles(root, globs, excludeDirs, allowDotDirs);
+    const files = new Map();
+    for (const [path, content] of matched.files) {
+        if (globListSelects(path, globs))
+            files.set(path, content);
+    }
+    return { files, unread: Object.freeze(unreadMatching(matched.unread, globs)) };
+}

package/dist/util/settle-glob-lists.d.ts

@@ -0,0 +1,12 @@
+import { type ISettledUnitLiveness } from '@shrkcrft/core';
+import type { IGlobLivenessRequest } from './i-glob-liveness-request.js';
+/**
+ * Settle a gate rule's glob lists through core's one authority,
+ * `settleUnitLiveness`, over THE gate-plane observation predicate
+ * (`globListLivenessInput`) — the call every plane engine makes before it
+ * decides what an empty rule is (`settleRuleEmptiness` takes the result as its
+ * `liveness`). `settled.dead` holds UNMARKED dead units only; a marked glob is
+ * intended-empty or went-live, and `settled.acceptance` is its printed record.
+ */
+export declare function settleGlobLists(request: IGlobLivenessRequest): ISettledUnitLiveness;
+//# sourceMappingURL=settle-glob-lists.d.ts.map

package/dist/util/settle-glob-lists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle-glob-lists.d.ts","sourceRoot":"","sources":["../../src/util/settle-glob-lists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAEnF"}

package/dist/util/settle-glob-lists.js

@@ -0,0 +1,13 @@
+import { settleUnitLiveness } from '@shrkcrft/core';
+import { globListLivenessInput } from "./glob-list-liveness-input.js";
+/**
+ * Settle a gate rule's glob lists through core's one authority,
+ * `settleUnitLiveness`, over THE gate-plane observation predicate
+ * (`globListLivenessInput`) — the call every plane engine makes before it
+ * decides what an empty rule is (`settleRuleEmptiness` takes the result as its
+ * `liveness`). `settled.dead` holds UNMARKED dead units only; a marked glob is
+ * intended-empty or went-live, and `settled.acceptance` is its printed record.
+ */
+export function settleGlobLists(request) {
+    return settleUnitLiveness(globListLivenessInput(request));
+}

package/dist/util/unread-file-reason.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Why the one reader (`readMatchingFiles`) matched a file against a rule's
+ * globs but did not read it. Either way the file is IN the rule's scope and
+ * was never examined, which is a coverage gap. It is never narrowing.
+ */
+export declare enum UnreadFileReason {
+    /** Larger than `MAX_SCAN_FILE_BYTES`, so the reader skipped it. */
+    OverReadCap = "over-read-cap",
+    /**
+     * A regenerated file (`generated check`'s temp tree) larger than
+     * `MAX_REGEN_FILE_BYTES`, so it was never read or byte-compared.
+     */
+    OverRegenCap = "over-regen-cap",
+    /** The stat or the read failed (permissions, or a delete racing the walk). */
+    Unreadable = "unreadable",
+    /**
+     * A DIRECTORY the walk could not list (permissions): no file beneath it was
+     * ever matched, let alone read. The entry's `path` ends in `/` (the root is
+     * `./`), and it is in front of every rule whose globs could match beneath it
+     * — `unreadEntryMatches`, the one test every plane uses. It used to be a
+     * silent `return`, so a violation under a `chmod 000` directory read as a
+     * clean `0` with full coverage.
+     */
+    UnreadableDirectory = "unreadable-directory"
+}
+//# sourceMappingURL=unread-file-reason.d.ts.map

package/dist/util/unread-file-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unread-file-reason.d.ts","sourceRoot":"","sources":["../../src/util/unread-file-reason.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,gBAAgB;IAC1B,mEAAmE;IACnE,WAAW,kBAAkB;IAC7B;;;OAGG;IACH,YAAY,mBAAmB;IAC/B,8EAA8E;IAC9E,UAAU,eAAe;IACzB;;;;;;;OAOG;IACH,mBAAmB,yBAAyB;CAC7C"}

package/dist/util/unread-file-reason.js

@@ -0,0 +1,26 @@
+/**
+ * Why the one reader (`readMatchingFiles`) matched a file against a rule's
+ * globs but did not read it. Either way the file is IN the rule's scope and
+ * was never examined, which is a coverage gap. It is never narrowing.
+ */
+export var UnreadFileReason;
+(function (UnreadFileReason) {
+    /** Larger than `MAX_SCAN_FILE_BYTES`, so the reader skipped it. */
+    UnreadFileReason["OverReadCap"] = "over-read-cap";
+    /**
+     * A regenerated file (`generated check`'s temp tree) larger than
+     * `MAX_REGEN_FILE_BYTES`, so it was never read or byte-compared.
+     */
+    UnreadFileReason["OverRegenCap"] = "over-regen-cap";
+    /** The stat or the read failed (permissions, or a delete racing the walk). */
+    UnreadFileReason["Unreadable"] = "unreadable";
+    /**
+     * A DIRECTORY the walk could not list (permissions): no file beneath it was
+     * ever matched, let alone read. The entry's `path` ends in `/` (the root is
+     * `./`), and it is in front of every rule whose globs could match beneath it
+     * — `unreadEntryMatches`, the one test every plane uses. It used to be a
+     * silent `return`, so a violation under a `chmod 000` directory read as a
+     * clean `0` with full coverage.
+     */
+    UnreadFileReason["UnreadableDirectory"] = "unreadable-directory";
+})(UnreadFileReason || (UnreadFileReason = {}));

package/dist/util/unread-file.d.ts

@@ -0,0 +1,10 @@
+import type { UnreadFileReason } from './unread-file-reason.js';
+/** A file a rule's globs matched that the one reader did not read. */
+export interface IUnreadFile {
+    /** Project-relative POSIX path. */
+    readonly path: string;
+    readonly reason: UnreadFileReason;
+    /** Size on disk, when the stat succeeded. */
+    readonly bytes?: number;
+}
+//# sourceMappingURL=unread-file.d.ts.map

package/dist/util/unread-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unread-file.d.ts","sourceRoot":"","sources":["../../src/util/unread-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/util/unread-file.js

@@ -0,0 +1 @@
+export {};

package/dist/util/walk-files.d.ts

@@ -1,13 +1,96 @@
+import type { IMatchedFiles } from './matched-files.js';
 /** Vendor / build / VCS dirs never scanned. */
 export declare const SKIP_DIRS: ReadonlySet<string>;
-/** Files larger than this are skipped (regex token extraction over multi-MB blobs is pointless). */
+/**
+ * Files larger than this are not READ (regex token extraction over multi-MB
+ * blobs is pointless). They are still MATCHED: `readMatchingFiles` reports
+ * each one as unread, and every coverage record counts it as unexamined.
+ */
 export declare const MAX_SCAN_FILE_BYTES = 1000000;
 /**
- * Walk `root`, returning project-relative POSIX paths that match any glob.
- * `excludeDirs` is a set of project-relative POSIX directory paths to prune
- * entirely (e.g. the SharkCraft asset/config dir).
+ * The cap on one file of a REGENERATED temp tree (`generated check` /
+ * `generated update`): a runaway regen must not be read into memory whole. A
+ * file over it is reported unread (`UnreadFileReason.OverRegenCap`) by
+ * `readRegenTree`, never dropped.
+ */
+export declare const MAX_REGEN_FILE_BYTES = 2000000;
+/**
+ * THE rule for which directories the walk never enters: a vendor/build/VCS
+ * dir (`SKIP_DIRS`, absolute), an `excludeDirs` entry (project-relative), or a
+ * dot-directory the caller's globs did not name (`allowDotDirs`).
+ *
+ * A file under a skipped directory is outside every plane's scope by design,
+ * and is neither read nor reported unread. Anything that asks "would the walk
+ * reach this path?" must ask this predicate; it must not keep its own copy of
+ * the list. (Round 11: run-policy used to re-derive it to guess which unread
+ * changed paths were in scope. It now reads the reader's own unread list.)
+ */
+export declare function walkSkipsDirectory(name: string, relPath: string, excludeDirs: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): boolean;
+/**
+ * Walk `root`, returning project-relative POSIX paths that match any INCLUSION
+ * glob. `excludeDirs` is a set of project-relative POSIX directory paths to
+ * prune entirely (e.g. the SharkCraft asset/config dir).
+ *
+ * A walk is a POSITIVE union primitive: a `!` entry is dropped here, never
+ * applied. Planes walk the union of many rules' lists once, and a negation
+ * applied to that union would delete rule A's `!x` from rule B's scope — a
+ * silent under-selection. Each list's negations subtract per list, after the
+ * walk, through `globListSelects` (or `readSelectedFiles` for one list).
+ *
+ * `unlistedDirs`, when given, collects every directory the walk entered but
+ * could not LIST (a permission error — not a directory that vanished), as a
+ * project-relative path ending in `/` (the root is `./`). Every file beneath
+ * one was never matched; `readMatchingFiles` reports it unread rather than
+ * letting its files drop out of every rule's scope in silence.
+ */
+export declare function walkMatching(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>, unlistedDirs?: string[]): string[];
+/** How many times `readMatchingFiles` walked + read the tree, and how many calls the memo served. */
+export declare function readMatchingFilesStats(): {
+    readonly walks: number;
+    readonly memoHits: number;
+};
+/** Reset {@link readMatchingFilesStats}. */
+export declare function resetReadMatchingFilesStats(): void;
+/**
+ * Run `fn` with the read memo enabled, then clear it.
+ *
+ * ONLY wrap a scan that performs no writes of its own for its duration. A
+ * command the scan SPAWNS (a baseline's `compute.run`, a generated artifact's
+ * `regen`) may rewrite files, so every spawn site calls
+ * {@link clearFileReadCache} right after the child exits: a read after the
+ * spawn is then fresh, and reuse inside the window stays exact rather than
+ * merely probable.
+ */
+export declare function withFileReadCache<T>(fn: () => T): T;
+/** Drop every memoized read. For tests, and for a caller that has just written. */
+export declare function clearFileReadCache(): void;
+/**
+ * The dot-directory segments a glob set explicitly names.
+ *
+ * `.claude/skills/**` asks for `.claude`; `docs/**` asks for nothing. Deriving
+ * the allowlist from the globs themselves means a rule gets exactly the
+ * directories it named and no others — a blanket "scan dot-dirs" switch would
+ * wander into `.venv` and `.yarn` the moment someone wrote a recursive glob.
+ */
+export declare function dotDirsNamedBy(globs: readonly string[]): Set<string>;
+/**
+ * THE reader: walk + read every file matching `globs`.
+ *
+ * Returns the files it read AND the matched files it did not read (over
+ * {@link MAX_SCAN_FILE_BYTES}, or unreadable), each with its reason. It used
+ * to drop those silently. Every plane then counted its expected scope from
+ * what was read, so an over-cap file holding a forbidden token read
+ * "examined 1 of 1 ✓". Now the gap is part of the return value, and every
+ * engine folds it into its rule coverage through `readScopeCoverage`.
+ *
+ * A path deleted between the walk and the stat is no longer in scope and is
+ * not reported.
+ *
+ * POSITIVE-ONLY, like {@link walkMatching}: a `!` entry in `globs` never
+ * subtracts here, because callers hand this the union of many lists. The
+ * result is every file an inclusion glob matched; a caller reading ONE list
+ * selects through `readSelectedFiles`, a caller reading many filters each
+ * list with `globListSelects` / `unreadMatching`.
  */
-export declare function walkMatching(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>): string[];
-/** Walk + read every file matching `globs`, skipping oversized/unreadable files. */
-export declare function readMatchingFiles(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>): Map<string, string>;
+export declare function readMatchingFiles(root: string, globs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): IMatchedFiles;
 //# sourceMappingURL=walk-files.d.ts.map

package/dist/util/walk-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk-files.d.ts","sourceRoot":"","sources":["../../src/util/walk-files.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAUxC,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,MAAM,EAAE,CA2BV;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBrB"}
+{"version":3,"file":"walk-files.d.ts","sourceRoot":"","sources":["../../src/util/walk-files.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,+CAA+C;AAC/C,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAUxC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,OAAO,CAGT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,EAC7C,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,MAAM,EAAE,CAqCV;AA0BD,qGAAqG;AACrG,wBAAgB,sBAAsB,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAE9F;AAED,4CAA4C;AAC5C,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CASnD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAGD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAWpE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,aAAa,CA8Df"}

package/dist/util/walk-files.js

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { matchesAny } from "../scan/glob.js";
+import { globListWalkGlobs, globMayMatchUnder, matchesAny } from "../scan/glob.js";
+import { UnreadFileReason } from "./unread-file-reason.js";
 /** Vendor / build / VCS dirs never scanned. */
 export const SKIP_DIRS = new Set([
     'node_modules',
@@ -13,21 +14,66 @@ export const SKIP_DIRS = new Set([
     '.turbo',
     '.cache',
 ]);
-/** Files larger than this are skipped (regex token extraction over multi-MB blobs is pointless). */
+/**
+ * Files larger than this are not READ (regex token extraction over multi-MB
+ * blobs is pointless). They are still MATCHED: `readMatchingFiles` reports
+ * each one as unread, and every coverage record counts it as unexamined.
+ */
 export const MAX_SCAN_FILE_BYTES = 1_000_000;
 /**
- * Walk `root`, returning project-relative POSIX paths that match any glob.
- * `excludeDirs` is a set of project-relative POSIX directory paths to prune
- * entirely (e.g. the SharkCraft asset/config dir).
+ * The cap on one file of a REGENERATED temp tree (`generated check` /
+ * `generated update`): a runaway regen must not be read into memory whole. A
+ * file over it is reported unread (`UnreadFileReason.OverRegenCap`) by
+ * `readRegenTree`, never dropped.
  */
-export function walkMatching(root, globs, excludeDirs = new Set()) {
+export const MAX_REGEN_FILE_BYTES = 2_000_000;
+/**
+ * THE rule for which directories the walk never enters: a vendor/build/VCS
+ * dir (`SKIP_DIRS`, absolute), an `excludeDirs` entry (project-relative), or a
+ * dot-directory the caller's globs did not name (`allowDotDirs`).
+ *
+ * A file under a skipped directory is outside every plane's scope by design,
+ * and is neither read nor reported unread. Anything that asks "would the walk
+ * reach this path?" must ask this predicate; it must not keep its own copy of
+ * the list. (Round 11: run-policy used to re-derive it to guess which unread
+ * changed paths were in scope. It now reads the reader's own unread list.)
+ */
+export function walkSkipsDirectory(name, relPath, excludeDirs, allowDotDirs = new Set()) {
+    if (SKIP_DIRS.has(name) || excludeDirs.has(relPath))
+        return true;
+    return name.startsWith('.') && !allowDotDirs.has(name);
+}
+/**
+ * Walk `root`, returning project-relative POSIX paths that match any INCLUSION
+ * glob. `excludeDirs` is a set of project-relative POSIX directory paths to
+ * prune entirely (e.g. the SharkCraft asset/config dir).
+ *
+ * A walk is a POSITIVE union primitive: a `!` entry is dropped here, never
+ * applied. Planes walk the union of many rules' lists once, and a negation
+ * applied to that union would delete rule A's `!x` from rule B's scope — a
+ * silent under-selection. Each list's negations subtract per list, after the
+ * walk, through `globListSelects` (or `readSelectedFiles` for one list).
+ *
+ * `unlistedDirs`, when given, collects every directory the walk entered but
+ * could not LIST (a permission error — not a directory that vanished), as a
+ * project-relative path ending in `/` (the root is `./`). Every file beneath
+ * one was never matched; `readMatchingFiles` reports it unread rather than
+ * letting its files drop out of every rule's scope in silence.
+ */
+export function walkMatching(root, globs, excludeDirs = new Set(), allowDotDirs = new Set(), unlistedDirs) {
+    const walkGlobs = globListWalkGlobs(globs);
     const out = [];
     const visit = (abs) => {
         let entries;
         try {
             entries = readdirSync(abs, { withFileTypes: true });
         }
-        catch {
+        catch (e) {
+            const code = e.code;
+            if (unlistedDirs && code !== 'ENOENT' && code !== 'ENOTDIR') {
+                const rel = nodePath.relative(root, abs).split(nodePath.sep).join('/');
+                unlistedDirs.push(rel === '' ? './' : `${rel}/`);
+            }
             return;
         }
         for (const e of entries) {
@@ -39,12 +85,16 @@ export function walkMatching(root, globs, excludeDirs = new Set()) {
                 // so neither policy-lint nor wiring scans tooling/vendored sources.
                 // (Dirent.isDirectory() is false for symlinks, so symlinked dirs are
                 // never descended — no loop risk.)
-                if (e.name.startsWith('.') || SKIP_DIRS.has(e.name) || excludeDirs.has(rel))
+                // Dot-directories are vendored tooling by default (`.venv`, `.yarn`,
+                // `.gradle`). But a rule may legitimately target one — an agent skill
+                // file lives in `.claude/skills` — so a caller can name the dot-dirs
+                // its OWN globs ask for. `SKIP_DIRS` stays absolute either way.
+                if (walkSkipsDirectory(e.name, rel, excludeDirs, allowDotDirs))
                     continue;
                 visit(childAbs);
             }
             else if (e.isFile()) {
-                if (matchesAny(rel, globs))
+                if (matchesAny(rel, walkGlobs))
                     out.push(rel);
             }
         }
@@ -52,29 +102,166 @@ export function walkMatching(root, globs, excludeDirs = new Set()) {
     visit(root);
     return out;
 }
-/** Walk + read every file matching `globs`, skipping oversized/unreadable files. */
-export function readMatchingFiles(root, globs, excludeDirs = new Set()) {
-    const out = new Map();
-    for (const rel of walkMatching(root, globs, excludeDirs)) {
+/**
+ * Memo of `readMatchingFiles`, keyed by (root, glob set, excludes).
+ *
+ * One coverage run resolves the SAME globs many times over: every rule on every
+ * plane walks the tree for its own sources, and a shared `$use` extractor is by
+ * construction read once per consumer. The walk + read is roughly half the cost
+ * of a wide extraction, so memoizing turns N walks into one.
+ *
+ * It is OFF by default and enabled only by {@link withFileReadCache}, around a
+ * scan that provably neither spawns nor writes. That restriction is not
+ * caution for its own sake — a global memo really does hand back a stale
+ * snapshot when the same process writes a file between two scans, and a trust
+ * tool answering "nothing drifted" from a stale read is worse than a slow one.
+ * Making the safe window explicit means the condition cannot be forgotten at a
+ * call site.
+ */
+const READ_MEMO = new Map();
+/** True only inside {@link withFileReadCache}. */
+let memoEnabled = false;
+/** Tree walks `readMatchingFiles` performed, and walks the memo served (tests / perf locks). */
+let walkCount = 0;
+let readMemoHits = 0;
+/** How many times `readMatchingFiles` walked + read the tree, and how many calls the memo served. */
+export function readMatchingFilesStats() {
+    return { walks: walkCount, memoHits: readMemoHits };
+}
+/** Reset {@link readMatchingFilesStats}. */
+export function resetReadMatchingFilesStats() {
+    walkCount = 0;
+    readMemoHits = 0;
+}
+/**
+ * Run `fn` with the read memo enabled, then clear it.
+ *
+ * ONLY wrap a scan that performs no writes of its own for its duration. A
+ * command the scan SPAWNS (a baseline's `compute.run`, a generated artifact's
+ * `regen`) may rewrite files, so every spawn site calls
+ * {@link clearFileReadCache} right after the child exits: a read after the
+ * spawn is then fresh, and reuse inside the window stays exact rather than
+ * merely probable.
+ */
+export function withFileReadCache(fn) {
+    const previous = memoEnabled;
+    memoEnabled = true;
+    try {
+        return fn();
+    }
+    finally {
+        memoEnabled = previous;
+        if (!previous)
+            READ_MEMO.clear();
+    }
+}
+/** Drop every memoized read. For tests, and for a caller that has just written. */
+export function clearFileReadCache() {
+    READ_MEMO.clear();
+}
+/**
+ * The dot-directory segments a glob set explicitly names.
+ *
+ * `.claude/skills/**` asks for `.claude`; `docs/**` asks for nothing. Deriving
+ * the allowlist from the globs themselves means a rule gets exactly the
+ * directories it named and no others — a blanket "scan dot-dirs" switch would
+ * wander into `.venv` and `.yarn` the moment someone wrote a recursive glob.
+ */
+export function dotDirsNamedBy(globs) {
+    const out = new Set();
+    // Only an inclusion glob can put a file in scope, so only it opens a dot-dir.
+    for (const glob of globListWalkGlobs(globs)) {
+        for (const segment of glob.split('/')) {
+            if (segment.startsWith('.') && segment.length > 1 && !segment.includes('*') && !segment.includes('?')) {
+                out.add(segment);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * THE reader: walk + read every file matching `globs`.
+ *
+ * Returns the files it read AND the matched files it did not read (over
+ * {@link MAX_SCAN_FILE_BYTES}, or unreadable), each with its reason. It used
+ * to drop those silently. Every plane then counted its expected scope from
+ * what was read, so an over-cap file holding a forbidden token read
+ * "examined 1 of 1 ✓". Now the gap is part of the return value, and every
+ * engine folds it into its rule coverage through `readScopeCoverage`.
+ *
+ * A path deleted between the walk and the stat is no longer in scope and is
+ * not reported.
+ *
+ * POSITIVE-ONLY, like {@link walkMatching}: a `!` entry in `globs` never
+ * subtracts here, because callers hand this the union of many lists. The
+ * result is every file an inclusion glob matched; a caller reading ONE list
+ * selects through `readSelectedFiles`, a caller reading many filters each
+ * list with `globListSelects` / `unreadMatching`.
+ */
+export function readMatchingFiles(root, globs, excludeDirs = new Set(), allowDotDirs = new Set()) {
+    // `['src/**', '!src/x.ts']` and `['src/**']` are one walk, so one memo entry.
+    const walkGlobs = globListWalkGlobs(globs);
+    const key = memoEnabled
+        ? `${root}\u0000${[...walkGlobs].sort().join('\u0001')}\u0000${[...excludeDirs].sort().join('\u0001')}` +
+            `\u0000${[...allowDotDirs].sort().join('\u0001')}`
+        : undefined;
+    if (key !== undefined) {
+        const hit = READ_MEMO.get(key);
+        // Hand back a COPY of the map: callers routinely mutate the one they get
+        // (the wiring scan filters it, the generated scan partitions it), and a
+        // shared instance would let one rule's bookkeeping corrupt the next
+        // rule's inputs. The unread list is frozen, so it is shared as is.
+        if (hit) {
+            readMemoHits += 1;
+            return { files: new Map(hit.files), unread: hit.unread };
+        }
+    }
+    walkCount += 1;
+    const files = new Map();
+    const unread = [];
+    const unlistedDirs = [];
+    const matchedPaths = walkMatching(root, walkGlobs, excludeDirs, allowDotDirs, unlistedDirs);
+    // A directory the walk could not list hides every file beneath it. It is in
+    // front of any glob that could match there, so it is reported unread (the
+    // rule over that tree settles PARTIAL), never dropped from scope in silence.
+    // Only an inclusion glob can be in front of it: `!**/x` has a `**` segment,
+    // but a negation selects nothing on its own.
+    for (const dir of unlistedDirs) {
+        if (walkGlobs.some((g) => globMayMatchUnder(g, dir))) {
+            unread.push({ path: dir, reason: UnreadFileReason.UnreadableDirectory });
+        }
+    }
+    for (const rel of matchedPaths) {
         const abs = nodePath.join(root, rel);
-        let size = -1;
+        let size;
         try {
             const st = statSync(abs);
             if (!st.isFile())
                 continue;
             size = st.size;
         }
-        catch {
+        catch (e) {
+            // Deleted since the walk saw it: gone, so out of scope. Anything else
+            // (a permission error) leaves a matched file unexamined.
+            if (e.code !== 'ENOENT') {
+                unread.push({ path: rel, reason: UnreadFileReason.Unreadable });
+            }
             continue;
         }
-        if (size > MAX_SCAN_FILE_BYTES)
+        if (size > MAX_SCAN_FILE_BYTES) {
+            unread.push({ path: rel, reason: UnreadFileReason.OverReadCap, bytes: size });
             continue;
+        }
         try {
-            out.set(rel, readFileSync(abs, 'utf8'));
+            files.set(rel, readFileSync(abs, 'utf8'));
         }
         catch {
-            // unreadable — skip
+            unread.push({ path: rel, reason: UnreadFileReason.Unreadable, bytes: size });
         }
     }
-    return out;
+    unread.sort((a, b) => a.path.localeCompare(b.path));
+    const result = { files, unread: Object.freeze(unread) };
+    if (key !== undefined)
+        READ_MEMO.set(key, { files: new Map(files), unread: result.unread });
+    return result;
 }