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

package/dist/extract/parse-imports.d.ts

@@ -1,17 +1,19 @@
 /**
- * The ONE import-statement parser.
+ * Which text an import statement may be read from.
  *
- * Two features need to read import statements out of source text: the
- * `--fix` planner (does this sink bind the token, and how?) and the
- * `import-edges` extractor (which file imports what, from where?). A second
- * parser would drift from the first, and the two would then disagree about
- * what a file imports — which is precisely the class of silent disagreement
- * this engine exists to eliminate. So both consume this.
- *
- * It is a lexer, not a compiler: it answers what the text says, which is the
- * largest thing that stays honest across `.ts`, `.tsx`, `.mts` and plain JS
- * with one code path.
+ *   - `code` (the default): the statement's keyword must start in executable
+ *     code and its specifier must be a real string literal; comments are
+ *     blanked before matching, so an apostrophe inside a comment within a
+ *     multi-line clause can no longer cut a real import short.
+ *   - `all`: the raw file text — every byte, comments included. The explicit
+ *     escape hatch (`check boundaries --include-comments`, `scan: 'all'`).
  */
+export type ImportParseZone = 'code' | 'all';
+/** Options for {@link parseImportStatements}. */
+export interface IParseImportsOptions {
+    /** Default `code`. */
+    readonly zone?: ImportParseZone;
+}
 /** How a name entered scope through an import. */
 export type ImportBindingKind = 'named' | 'default' | 'namespace';
 /** One name bound by an import statement. */
@@ -53,6 +55,26 @@ export interface IParsedImport {
  * dependency graph legitimately counts it as an edge. Returning it and letting
  * each caller decide keeps that judgement at the call site instead of baking
  * one feature's answer into the shared parser.
+ *
+ * In the default `code` zone a statement is kept only when its keyword starts
+ * in a code zone AND its specifier quote opens a real string literal — the
+ * same {@link zoneKeepsAt} authority the policy plane and the extraction DSL
+ * use. Offsets, lines and `raw` always refer to the ORIGINAL text (blanking
+ * preserves length), so callers that splice `content` stay correct.
+ */
+export declare function parseImportStatements(content: string, options?: IParseImportsOptions): IParsedImport[];
+/**
+ * {@link parseImportStatements}, plus how many characters the zone BLANKED
+ * before matching: the comment characters under `code`, `0` under `all`.
+ *
+ * The `import-edges` extractor zones itself (a pre-blanked buffer would erase
+ * every specifier), so this is the figure it reports as its `blankedChars` —
+ * the number `wiring explain` / `gates explain` print as
+ * `scan: code (N chars blanked)`. Without it the note claimed a zone removed
+ * nothing while it had dropped a commented-out edge.
  */
-export declare function parseImportStatements(content: string): IParsedImport[];
+export declare function parseImportStatementsWithMeta(content: string, options?: IParseImportsOptions): {
+    readonly statements: IParsedImport[];
+    readonly blankedChars: number;
+};
 //# sourceMappingURL=parse-imports.d.ts.map

package/dist/extract/parse-imports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-imports.d.ts","sourceRoot":"","sources":["../../src/extract/parse-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAElE,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhG,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAgDtE"}
+{"version":3,"file":"parse-imports.d.ts","sourceRoot":"","sources":["../../src/extract/parse-imports.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7C,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;CACjC;AAED,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAElE,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhG,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAsID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,aAAa,EAAE,CAEjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC;IAAE,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA4EzE"}

package/dist/extract/parse-imports.js

@@ -11,19 +11,43 @@
  * It is a lexer, not a compiler: it answers what the text says, which is the
  * largest thing that stays honest across `.ts`, `.tsx`, `.mts` and plain JS
  * with one code path.
+ *
+ * Round 11 (6.1a) made it the ONLY import extractor: `scanImports` (every
+ * boundary check, drift, impact, review packet…) and the `import-edges` DSL
+ * extractor both read through here, so "what does this file import" has one
+ * answer. By default it reads CODE only — a commented-out import, an import in
+ * a doc-comment code fence, or `"import x from 'y'"` inside a string is not a
+ * dependency. Measured against the TypeScript oracle over this repo (1716
+ * files): 79 phantom edges and 1 real miss before, 0 / 0 after.
  */
+import { blankZoneKinds, lexCodeZones, zoneContaining, zoneKeepsAt, } from "./code-zones.js";
 /**
  * Matches one import/re-export statement up to its specifier.
  *
  * The clause may span lines (a multi-line `{ … }` block is normal) but never
- * contains a `;` or a quote, which is what keeps the lazy match from running
- * past the end of its own statement into the next one.
+ * contains a `;`, a quote or a BACKTICK, which is what keeps the lazy match
+ * from running past the end of its own statement into the next one. No real
+ * import clause holds a backtick; prose does — a doc comment's
+ * `` `shrk import <format> --populate` `` used to open a clause that ran on to
+ * the next real `from '…'`, so the raw reading (`--include-comments`,
+ * `scan: 'all'`) filed that import on the comment's line. The old scanImports
+ * regex excluded the backtick too; raw-mode lines match it again.
  *
  * `export … from '…'` is matched too: a re-export is an edge in the dependency
  * graph exactly like an import, and a barrel that is invisible here would make
  * every consumer behind it invisible as well.
+ *
+ * Linear by construction (round 11, 6.1(b)): the old form
+ * `\s+([^;'"]*?)\s*from` put three whitespace-consuming quantifiers side by
+ * side, which is fine on raw source and O(run²) once comments are blanked into
+ * long runs of spaces (6 / 24 / 94 / 371 ms as a JSDoc block doubled). Here a
+ * single `\s` separates the keyword from ONE lazy class, and `\bfrom` needs no
+ * whitespace quantifier in front of it, so each keyword costs one forward scan
+ * to its statement's end. Verified byte-identical to the old form on the raw
+ * text of every file in this repo. Do not reintroduce adjacent `\s*`/`\s+`
+ * around a lazy class — `r75-import-scan-zones.test.ts` times it.
  */
-const IMPORT_STATEMENT = /\b(import|export)\s+([^;'"]*?)\s*from\s*['"]([^'"]+)['"]\s*;?/g;
+const IMPORT_STATEMENT = /\b(import|export)\s([^;'"`]*?)\bfrom\s*['"]([^'"]+)['"]\s*;?/g;
 /**
  * The specifier-only forms, which bind no name: a side-effect import, a dynamic
  * `import()`, and `require()`. Each is a real dependency edge — the boundary
@@ -90,14 +114,42 @@ function parseClause(clause) {
     }
     return bindings;
 }
-/** 1-based line number of `index` within `content`. */
-function lineAt(content, index) {
-    let line = 1;
-    for (let i = 0; i < index && i < content.length; i += 1) {
-        if (content[i] === '\n')
-            line += 1;
+/** Offsets of every `\n` in `content`, for O(log n) line lookups. */
+function newlineOffsets(content) {
+    const out = [];
+    for (let i = content.indexOf('\n'); i !== -1; i = content.indexOf('\n', i + 1))
+        out.push(i);
+    return out;
+}
+/**
+ * 1-based line of `index`: one plus the number of newlines BEFORE it. The
+ * index is the keyword's own offset — the old `scanImports` regex consumed the
+ * preceding `\n` with `(?:^|\s)`, so every import after line 1 was reported
+ * one line early (round 11, 6.1a#line-numbers).
+ */
+function lineAt(newlines, index) {
+    let lo = 0;
+    let hi = newlines.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (newlines[mid] < index)
+            lo = mid + 1;
+        else
+            hi = mid;
     }
-    return line;
+    return lo + 1;
+}
+/** Zones blanked before matching in `code` mode: comments only — the specifier is a string. */
+const COMMENT_ZONES = new Set(['comment']);
+/**
+ * Offset (within the match) of the specifier's OPENING quote. Every pattern
+ * ends `<quote><specifier><quote>` followed only by whitespace, `;` or `)`,
+ * and no clause may contain a quote, so the last quote in the match closes the
+ * specifier.
+ */
+function specifierQuoteOffset(match, specifier) {
+    const closing = Math.max(match.lastIndexOf("'"), match.lastIndexOf('"'));
+    return closing - specifier.length - 1;
 }
 /**
  * Every import / re-export statement in `content`, with the names it binds.
@@ -107,22 +159,66 @@ function lineAt(content, index) {
  * dependency graph legitimately counts it as an edge. Returning it and letting
  * each caller decide keeps that judgement at the call site instead of baking
  * one feature's answer into the shared parser.
+ *
+ * In the default `code` zone a statement is kept only when its keyword starts
+ * in a code zone AND its specifier quote opens a real string literal — the
+ * same {@link zoneKeepsAt} authority the policy plane and the extraction DSL
+ * use. Offsets, lines and `raw` always refer to the ORIGINAL text (blanking
+ * preserves length), so callers that splice `content` stay correct.
+ */
+export function parseImportStatements(content, options = {}) {
+    return parseImportStatementsWithMeta(content, options).statements;
+}
+/**
+ * {@link parseImportStatements}, plus how many characters the zone BLANKED
+ * before matching: the comment characters under `code`, `0` under `all`.
+ *
+ * The `import-edges` extractor zones itself (a pre-blanked buffer would erase
+ * every specifier), so this is the figure it reports as its `blankedChars` —
+ * the number `wiring explain` / `gates explain` print as
+ * `scan: code (N chars blanked)`. Without it the note claimed a zone removed
+ * nothing while it had dropped a commented-out edge.
  */
-export function parseImportStatements(content) {
+export function parseImportStatementsWithMeta(content, options = {}) {
+    const zone = options.zone ?? 'code';
+    const zones = zone === 'code' ? lexCodeZones(content) : undefined;
+    const blanked = zones ? blankZoneKinds(content, zones, COMMENT_ZONES) : undefined;
+    const text = blanked ? blanked.content : content;
+    // Built on first use: a file whose statements are all zoned out (or that has
+    // none) never needs a line table.
+    let newlines;
+    const lineOfIndex = (index) => lineAt((newlines ??= newlineOffsets(content)), index);
+    const keep = (index, match, specifier) => {
+        if (!zones)
+            return true;
+        const quote = index + specifierQuoteOffset(match, specifier);
+        // The specifier's quote must OPEN a plain string literal. "Inside a string"
+        // is not enough: `export const t = \`import z from 'w'\`` starts with a
+        // code `export`, and its `'w'` sits inside the template literal.
+        const specZone = zoneContaining(zones, quote);
+        return (zoneKeepsAt('code', zones, index) &&
+            zoneKeepsAt('strings', zones, quote) &&
+            specZone !== undefined &&
+            specZone.start === quote &&
+            specZone.template !== true);
+    };
     const out = [];
     const claimed = [];
     let m;
     IMPORT_STATEMENT.lastIndex = 0;
-    while ((m = IMPORT_STATEMENT.exec(content)) !== null) {
+    while ((m = IMPORT_STATEMENT.exec(text)) !== null) {
+        const specifier = m[3];
+        if (!keep(m.index, m[0], specifier))
+            continue;
         const clause = m[2];
         const typeOnly = /^type\b/.test(clause.trim());
         claimed.push({ start: m.index, end: m.index + m[0].length });
         out.push({
-            specifier: m[3],
+            specifier,
             bindings: typeOnly ? [] : parseClause(clause),
-            line: lineAt(content, m.index),
+            line: lineOfIndex(m.index),
             index: m.index,
-            raw: m[0],
+            raw: content.slice(m.index, m.index + m[0].length),
             typeOnly,
             kind: m[1] === 'export' ? 'reexport' : 'import',
         });
@@ -137,19 +233,22 @@ export function parseImportStatements(content) {
         [REQUIRE_CALL, 'require'],
     ]) {
         re.lastIndex = 0;
-        while ((m = re.exec(content)) !== null) {
+        while ((m = re.exec(text)) !== null) {
             if (overlapsClaimed(m.index))
                 continue;
+            const specifier = m[1];
+            if (!keep(m.index, m[0], specifier))
+                continue;
             out.push({
-                specifier: m[1],
+                specifier,
                 bindings: [],
-                line: lineAt(content, m.index),
+                line: lineOfIndex(m.index),
                 index: m.index,
-                raw: m[0],
+                raw: content.slice(m.index, m.index + m[0].length),
                 typeOnly: false,
                 kind,
             });
         }
     }
-    return out.sort((a, b) => a.index - b.index);
+    return { statements: out.sort((a, b) => a.index - b.index), blankedChars: blanked?.blankedChars ?? 0 };
 }

package/dist/extract/scan-literals.d.ts

@@ -11,7 +11,18 @@
  * comment syntax differs from the C/JS family (e.g. `#` comments) is scanned as
  * plain code.
  */
-/** Index of the closing quote of the string starting at `start` (handles escapes). */
+/**
+ * Index of the closing quote of the string starting at `start` (handles escapes).
+ *
+ * A `'…'` or `"…"` literal ends at an unescaped NEWLINE (JS semantics — only a
+ * template literal spans lines): the returned index is then the last character
+ * before the newline. Without this a quote the lexer could not recognise as
+ * code — the `'` inside a regex literal such as `/[&<>"']/g`, an apostrophe in
+ * prose — swallowed the rest of the FILE as one phantom string, hiding every
+ * real construct after it (round 11, 6.1a: a real `import()` 60 lines later
+ * vanished). Bounding the mis-lex to one line is strictly more accurate for
+ * every caller: zone lexing, the policy plane and array extraction alike.
+ */
 export declare function skipString(content: string, start: number): number;
 /**
  * If a comment starts at `start`, the index of its LAST character; otherwise

package/dist/extract/scan-literals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-literals.d.ts","sourceRoot":"","sources":["../../src/extract/scan-literals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlE;AAED,iDAAiD;AACjD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA0CD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAgC7E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB7D"}
+{"version":3,"file":"scan-literals.d.ts","sourceRoot":"","sources":["../../src/extract/scan-literals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlE;AAED,iDAAiD;AACjD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA0CD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAgC7E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB7D"}

package/dist/extract/scan-literals.js

@@ -11,9 +11,21 @@
  * comment syntax differs from the C/JS family (e.g. `#` comments) is scanned as
  * plain code.
  */
-/** Index of the closing quote of the string starting at `start` (handles escapes). */
+/**
+ * Index of the closing quote of the string starting at `start` (handles escapes).
+ *
+ * A `'…'` or `"…"` literal ends at an unescaped NEWLINE (JS semantics — only a
+ * template literal spans lines): the returned index is then the last character
+ * before the newline. Without this a quote the lexer could not recognise as
+ * code — the `'` inside a regex literal such as `/[&<>"']/g`, an apostrophe in
+ * prose — swallowed the rest of the FILE as one phantom string, hiding every
+ * real construct after it (round 11, 6.1a: a real `import()` 60 lines later
+ * vanished). Bounding the mis-lex to one line is strictly more accurate for
+ * every caller: zone lexing, the policy plane and array extraction alike.
+ */
 export function skipString(content, start) {
     const quote = content[start];
+    const singleLine = quote === "'" || quote === '"';
     for (let i = start + 1; i < content.length; i += 1) {
         if (content[i] === '\\') {
             i += 1;
@@ -21,6 +33,8 @@ export function skipString(content, start) {
         }
         if (content[i] === quote)
             return i;
+        if (singleLine && content[i] === '\n')
+            return i - 1;
     }
     return content.length - 1;
 }

package/dist/extract/source-liveness-request.d.ts

@@ -0,0 +1,24 @@
+import type { IGlobListUnits } from '../util/i-glob-list-units.js';
+import type { IGlobLivenessRequest } from '../util/i-glob-liveness-request.js';
+import type { ILabeledSource } from './i-labeled-source.js';
+/**
+ * THE glob lists of a rule's extraction sources as the gate-plane liveness
+ * settle reads them (round 13) — every source's `files` and, NEW this round,
+ * an `import-edges` source's `to.files` (judged for liveness, so a typo'd fence
+ * target is no longer a silent pass, and markable, so a fence to a planned
+ * subtree is sayable).
+ *
+ * Each list is qualified by its side (`declared.files`, `compute.source.to.files`
+ * — `qualifyListPath`), and each source's markers the same way
+ * (`qualifyUnitMarks`), so one settle spans a rule's every source without two
+ * sides' `files` colliding. In a multi-source rule a unit prints `<side>: <glob>`
+ * (today's dead-glob selector); `to.files` units print `[<side> ]to.files: <glob>`.
+ *
+ * `gates coverage` (`buildGateCoverage`), the wiring engine (`runWiring`) and
+ * the registration role measurement all build their request here, so the one
+ * rule's units read identically on every surface. `unitsOf` lets a caller
+ * judge a `files` list off a walk it already did; `to.files` matches resolved
+ * import targets, so it is judged off the one reader's own walk of its globs.
+ */
+export declare function sourceLivenessRequest(projectRoot: string, sources: readonly ILabeledSource[], excludeDirs?: readonly string[], subject?: string, unitsOf?: (globs: readonly string[]) => IGlobListUnits): IGlobLivenessRequest;
+//# sourceMappingURL=source-liveness-request.d.ts.map

package/dist/extract/source-liveness-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-liveness-request.d.ts","sourceRoot":"","sources":["../../src/extract/source-liveness-request.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,WAAW,GAAE,SAAS,MAAM,EAAO,EACnC,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,cAAc,GACrD,oBAAoB,CAuBtB"}

package/dist/extract/source-liveness-request.js

@@ -0,0 +1,45 @@
+import { qualifyListPath, qualifyUnitMarks } from '@shrkcrft/core';
+import { readGlobListUnits } from "../util/dead-glob-units.js";
+/**
+ * THE glob lists of a rule's extraction sources as the gate-plane liveness
+ * settle reads them (round 13) — every source's `files` and, NEW this round,
+ * an `import-edges` source's `to.files` (judged for liveness, so a typo'd fence
+ * target is no longer a silent pass, and markable, so a fence to a planned
+ * subtree is sayable).
+ *
+ * Each list is qualified by its side (`declared.files`, `compute.source.to.files`
+ * — `qualifyListPath`), and each source's markers the same way
+ * (`qualifyUnitMarks`), so one settle spans a rule's every source without two
+ * sides' `files` colliding. In a multi-source rule a unit prints `<side>: <glob>`
+ * (today's dead-glob selector); `to.files` units print `[<side> ]to.files: <glob>`.
+ *
+ * `gates coverage` (`buildGateCoverage`), the wiring engine (`runWiring`) and
+ * the registration role measurement all build their request here, so the one
+ * rule's units read identically on every surface. `unitsOf` lets a caller
+ * judge a `files` list off a walk it already did; `to.files` matches resolved
+ * import targets, so it is judged off the one reader's own walk of its globs.
+ */
+export function sourceLivenessRequest(projectRoot, sources, excludeDirs = [], subject, unitsOf) {
+    const multi = sources.length > 1;
+    const exclude = new Set(excludeDirs);
+    const judge = unitsOf ?? ((globs) => readGlobListUnits(projectRoot, globs, exclude));
+    const lists = [];
+    const marks = [];
+    for (const { label, source } of sources) {
+        const files = source.files ?? [];
+        if (files.length > 0) {
+            lists.push({ list: qualifyListPath(label, 'files'), ...(multi ? { label } : {}), globs: files, units: judge(files) });
+        }
+        const to = source.to?.files ?? [];
+        if (to.length > 0) {
+            lists.push({
+                list: qualifyListPath(label, 'to.files'),
+                label: multi ? `${label} to.files` : 'to.files',
+                globs: to,
+                units: readGlobListUnits(projectRoot, to, exclude),
+            });
+        }
+        marks.push(...qualifyUnitMarks(source.expectEmptyUnits ?? [], label));
+    }
+    return { ...(subject !== undefined ? { subject } : {}), lists, marks };
+}

package/dist/generated/check-provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-provenance.d.ts","sourceRoot":"","sources":["../../src/generated/check-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB;AAC/B,qEAAqE;AACnE,gBAAgB;AAClB,mFAAmF;GACjF,YAAY;AACd,qEAAqE;GACnE,kBAAkB;AACpB,0EAA0E;GACxE,cAAc;AAChB,4DAA4D;GAC1D,uBAAuB,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAO7E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,cAAc,GAAE,uBAA4B,GAC3C;IAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAgF7D"}
+{"version":3,"file":"check-provenance.d.ts","sourceRoot":"","sources":["../../src/generated/check-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAI7D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB;AAC/B,qEAAqE;AACnE,gBAAgB;AAClB,mFAAmF;GACjF,YAAY;AACd,qEAAqE;GACnE,kBAAkB;AACpB,0EAA0E;GACxE,cAAc;AAChB,4DAA4D;GAC1D,uBAAuB,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ7E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,cAAc,GAAE,uBAA4B,GAC3C;IAAE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAgF7D"}

package/dist/generated/check-provenance.js

@@ -1,3 +1,4 @@
+import { globListWalkGlobs } from "../scan/glob.js";
 import { safeCompile } from "../util/safe-regex.js";
 /** The head of a file, as the header contract sees it. */
 function headOf(content, withinLines) {
@@ -11,7 +12,8 @@ function headOf(content, withinLines) {
  */
 export function deriveOutsideGlobs(generatedGlob) {
     const exts = new Set();
-    for (const g of generatedGlob) {
+    // Inclusion globs only: a `!gen/**/*.hand.ts` names no extension to search.
+    for (const g of globListWalkGlobs(generatedGlob)) {
         const m = /\.([A-Za-z0-9]+)$/.exec(g);
         if (m)
             exts.add(m[1]);

package/dist/generated/read-regen-tree.d.ts

@@ -0,0 +1,16 @@
+import type { IMatchedFiles } from '../util/matched-files.js';
+/**
+ * Read a REGENERATED temp tree (what a `generatedArtifacts[].regen` wrote into
+ * `{TMP}`): every file under `root`, keyed by POSIX path relative to it.
+ *
+ * Same contract as the one reader (`readMatchingFiles`): a file it did not read
+ * (over {@link MAX_REGEN_FILE_BYTES}, or unreadable) is returned in `unread`
+ * with its reason, never dropped. It used to be dropped, so a regen that wrote
+ * a NEW 2.1MB file read "byte-identical to a fresh regen ✓" while the same
+ * file at 100 bytes failed as "regen produces it but it is not committed".
+ * The caller decides what an unread output means: one keyed onto a committed
+ * file cannot be byte-compared (a coverage gap), one keyed onto nothing
+ * committed is drift its path alone proves.
+ */
+export declare function readRegenTree(root: string): IMatchedFiles;
+//# sourceMappingURL=read-regen-tree.d.ts.map

package/dist/generated/read-regen-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-regen-tree.d.ts","sourceRoot":"","sources":["../../src/generated/read-regen-tree.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAK9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAuCzD"}

package/dist/generated/read-regen-tree.js

@@ -0,0 +1,61 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { UnreadFileReason } from "../util/unread-file-reason.js";
+import { MAX_REGEN_FILE_BYTES } from "../util/walk-files.js";
+/**
+ * Read a REGENERATED temp tree (what a `generatedArtifacts[].regen` wrote into
+ * `{TMP}`): every file under `root`, keyed by POSIX path relative to it.
+ *
+ * Same contract as the one reader (`readMatchingFiles`): a file it did not read
+ * (over {@link MAX_REGEN_FILE_BYTES}, or unreadable) is returned in `unread`
+ * with its reason, never dropped. It used to be dropped, so a regen that wrote
+ * a NEW 2.1MB file read "byte-identical to a fresh regen ✓" while the same
+ * file at 100 bytes failed as "regen produces it but it is not committed".
+ * The caller decides what an unread output means: one keyed onto a committed
+ * file cannot be byte-compared (a coverage gap), one keyed onto nothing
+ * committed is drift its path alone proves.
+ */
+export function readRegenTree(root) {
+    const files = new Map();
+    const unread = [];
+    const visit = (abs) => {
+        let entries;
+        try {
+            entries = readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const child = nodePath.join(abs, e.name);
+            if (e.isDirectory()) {
+                visit(child);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            const rel = nodePath.relative(root, child).split(nodePath.sep).join('/');
+            let size;
+            try {
+                size = statSync(child).size;
+            }
+            catch {
+                unread.push({ path: rel, reason: UnreadFileReason.Unreadable });
+                continue;
+            }
+            if (size > MAX_REGEN_FILE_BYTES) {
+                unread.push({ path: rel, reason: UnreadFileReason.OverRegenCap, bytes: size });
+                continue;
+            }
+            try {
+                files.set(rel, readFileSync(child, 'utf8'));
+            }
+            catch {
+                unread.push({ path: rel, reason: UnreadFileReason.Unreadable, bytes: size });
+            }
+        }
+    };
+    visit(root);
+    unread.sort((a, b) => a.path.localeCompare(b.path));
+    return { files, unread: Object.freeze(unread) };
+}

package/dist/generated/scan-generated.d.ts

@@ -1,4 +1,5 @@
 import type { IGeneratedArtifactRule } from '@shrkcrft/core';
+import type { IReadScope } from '../util/read-scope.js';
 /** One writer's slice of a mixed generated tree. */
 export interface IGeneratedSourceSlice {
     /** Label for output — the writer's `id`, or `source[<index>]`. */
@@ -43,6 +44,13 @@ export interface IGeneratedScan {
     readonly outside: ReadonlyMap<string, string>;
     /** Globs actually used for the outside scan (derived or configured). */
     readonly outsideGlobs: readonly string[];
+    /**
+     * The rule's read scope: every file read (committed generated files, plus
+     * the outside candidates when `forbidOutside` is on), and every matched file
+     * the reader did NOT read (over the read cap, or unreadable). An unread
+     * committed file was never header-checked or byte-compared.
+     */
+    readonly readScope: IReadScope;
 }
 /**
  * Read + CLASSIFY the committed side of a generated-artifact rule.

package/dist/generated/scan-generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-generated.d.ts","sourceRoot":"","sources":["../../src/generated/scan-generated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAM7D,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,sBAAsB,EAC5B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,cAAc,CAiGhB"}
+{"version":3,"file":"scan-generated.d.ts","sourceRoot":"","sources":["../../src/generated/scan-generated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAI7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,sBAAsB,EAC5B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,cAAc,CAkHhB"}

package/dist/generated/scan-generated.js

@@ -1,6 +1,7 @@
-import { matchesAny } from "../scan/glob.js";
+import { globListSelects } from "../scan/glob.js";
 import { safeCompile } from "../util/safe-regex.js";
-import { readMatchingFiles } from "../util/walk-files.js";
+import { readSelectedFiles } from "../util/read-selected-files.js";
+import { mergeReadScopes, unreadEntryMatches, unreadEntryWhollyMatches } from "../util/read-scope-coverage.js";
 import { deriveOutsideGlobs } from "./check-provenance.js";
 /**
  * Read + CLASSIFY the committed side of a generated-artifact rule.
@@ -19,7 +20,10 @@ import { deriveOutsideGlobs } from "./check-provenance.js";
  */
 export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
     const exclude = new Set(excludeDirs);
-    const generated = readMatchingFiles(projectRoot, rule.generatedGlob, exclude);
+    // The files `generatedGlob` SELECTS: a `!` entry (`!gen/**/*.hand.ts`)
+    // excludes, so a hand file carved out of the tree is never header-checked.
+    const generatedRead = readSelectedFiles(projectRoot, rule.generatedGlob, exclude);
+    const generated = generatedRead.files;
     const blessPatterns = rule.handMaintained ?? [];
     // The in-file marker is read from the same head window the header contract
     // uses, so "the top of the file" means one thing for both classifications.
@@ -37,7 +41,7 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
     const markedHandMaintained = [];
     const checkable = new Map();
     for (const [path, content] of generated) {
-        if (blessPatterns.length > 0 && matchesAny(path, blessPatterns)) {
+        if (blessPatterns.length > 0 && globListSelects(path, blessPatterns)) {
             handMaintained.push(path);
             continue;
         }
@@ -52,13 +56,17 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
     markedHandMaintained.sort();
     // A bless is pinned to a NAMED file (the schema forbids a wildcard basename),
     // so one that matches nothing points at a file that has been renamed away.
+    // A file over the read cap was still MATCHED, so a bless naming it is live.
+    // So is one that could match beneath a directory the walk could not list.
+    const matchedPaths = [...generated.keys()];
     const staleHandMaintained = blessPatterns
-        .filter((pattern) => ![...generated.keys()].some((p) => matchesAny(p, [pattern])))
+        .filter((pattern) => !matchedPaths.some((p) => globListSelects(p, [pattern])) &&
+        !generatedRead.unread.some((u) => unreadEntryMatches(u, [pattern])))
         .sort();
     const slices = (rule.sources ?? []).map((src, i) => {
         const files = new Map();
         for (const [path, content] of checkable) {
-            if (matchesAny(path, src.glob))
+            if (globListSelects(path, src.glob))
                 files.set(path, content);
         }
         return {
@@ -73,7 +81,7 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
     // everything its glob matched, so nothing there can be unclassified.
     const unclassified = slices.length === 0
         ? []
-        : [...checkable.keys()].filter((p) => !slices.some((s) => matchesAny(p, s.glob))).sort();
+        : [...checkable.keys()].filter((p) => !slices.some((s) => globListSelects(p, s.glob))).sort();
     const wantOutside = rule.provenanceHeader?.forbidOutside === true;
     if (!wantOutside) {
         return {
@@ -86,18 +94,24 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
             slices,
             outside: new Map(),
             outsideGlobs: [],
+            readScope: { read: generated.size, unread: generatedRead.unread },
         };
     }
     const outsideGlobs = rule.provenanceHeader?.outsideGlob && rule.provenanceHeader.outsideGlob.length > 0
         ? [...rule.provenanceHeader.outsideGlob]
         : deriveOutsideGlobs(rule.generatedGlob);
-    const all = readMatchingFiles(projectRoot, outsideGlobs, exclude);
+    const all = readSelectedFiles(projectRoot, outsideGlobs, exclude);
     const outside = new Map();
-    for (const [path, content] of all) {
-        if (matchesAny(path, rule.generatedGlob))
+    for (const [path, content] of all.files) {
+        // A file `generatedGlob` excludes is OUTSIDE the generated tree: carrying
+        // the "do not edit" header there is exactly a mislabel.
+        if (globListSelects(path, rule.generatedGlob))
             continue;
         outside.set(path, content);
     }
+    // An unlistable directory is "outside" unless the generated glob covers ALL
+    // of it (it may hold both); `mergeReadScopes` counts a shared path once.
+    const outsideUnread = all.unread.filter((u) => !unreadEntryWhollyMatches(u, rule.generatedGlob));
     return {
         generated,
         checkable,
@@ -108,5 +122,6 @@ export function scanGeneratedFiles(projectRoot, rule, excludeDirs = []) {
         slices,
         outside,
         outsideGlobs,
+        readScope: mergeReadScopes(generated.size + outside.size, [generatedRead.unread, outsideUnread]),
     };
 }