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

package/dist/wiring/registration-graph.js

@@ -2,8 +2,9 @@ import { createHash } from 'node:crypto';
 import { statSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { resolveSourceGlobs } from '@shrkcrft/core';
-import { matchesAny } from "../scan/glob.js";
+import { globListSelects } from "../scan/glob.js";
 import { readMatchingFiles, walkMatching } from "../util/walk-files.js";
+import { readScopeOfLists } from "../util/read-scope-coverage.js";
 import { collectSourceSites } from "./evaluate-wiring.js";
 export const REGISTRATION_GRAPH_SCHEMA = 'sharkcraft.registration-graph/v1';
 function sortSites(sites) {
@@ -28,12 +29,14 @@ function registrationGlobs(idioms) {
  * diagnostic.
  */
 export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
-    const cache = readMatchingFiles(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? []));
-    const entries = [...cache.entries()].map(([path, content]) => ({
+    const matched = readMatchingFiles(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? []));
+    const entries = [...matched.files.entries()].map(([path, content]) => ({
         path,
         content,
     }));
-    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(source)));
+    // The walk is the POSITIVE union of every role of every idiom; each role
+    // selects its own files, so one role's `!x` never hides another role's file.
+    const filesFor = (source) => entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(source)));
     const declared = new Map();
     const provided = new Map();
     const consumed = new Map();
@@ -60,11 +63,15 @@ export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
         provided: sortSites(provided.get(token) ?? []),
         consumed: sortSites(consumed.get(token) ?? []),
     }));
+    // Read scope PER ROLE LIST (one file counted once): an unread file every
+    // role that could reach it EXCLUDES is out of scope, not a gap.
+    const scope = readScopeOfLists(matched, idioms.flatMap((i) => [i.declared, i.provided, i.consumed].map((s) => resolveSourceGlobs(s))));
     return {
         schema: REGISTRATION_GRAPH_SCHEMA,
         idioms: idioms.map((i) => i.name),
         tokens,
         diagnostics,
+        ...(scope.unread.length > 0 ? { readScope: scope } : {}),
     };
 }
 /**
@@ -75,6 +82,10 @@ export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
  * persisted registration-graph cache — a source edit shifts the signature even
  * when no reindex has run, so a stale wiring verdict is impossible. Walk-and-stat
  * only (no file reads), so it stays far cheaper than a full build. Never throws.
+ *
+ * It signs the POSITIVE union walk, not each role's selected set: a file a
+ * role's `!` excludes still shifts the signature. That over-inclusion can only
+ * cause a spurious cache miss — the safe direction — never a stale verdict.
  */
 export function registrationGraphSignature(projectRoot, idioms, options = {}) {
     const files = walkMatching(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? [])).sort();
@@ -101,7 +112,7 @@ export function registrationGraphSignature(projectRoot, idioms, options = {}) {
 export function providedTokensFromEntries(idioms, entries) {
     const tokens = new Set();
     for (const idiom of idioms) {
-        const files = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(idiom.provided)));
+        const files = entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(idiom.provided)));
         for (const s of collectSourceSites(idiom.provided, files).sites)
             tokens.add(s.token);
     }

package/dist/wiring/registration-query-verdict.d.ts

@@ -0,0 +1,23 @@
+import { type IRegistrationIdiom, type IVerdictCoverage } from '@shrkcrft/core';
+import type { IIdiomRoleCoverage } from './i-idiom-role-coverage.js';
+import type { IRegistrationQueryVerdict } from './i-registration-query-verdict.js';
+import { type IOrphanRegistration, type IRegistrationGraph, type IUnprovidedToken } from './registration-graph.js';
+/**
+ * THE registration graph's read-scope record: the idiom files the reader could
+ * not read, named (`examined 3 of 4 files, 1 over the 1MB read cap: …`), or
+ * `undefined` when it read every file its idioms matched. `wiring unprovided |
+ * orphans`, finish's unprovided sub-gate and MCP `get_wiring_graph` all read
+ * it here, so the verb and its siblings cannot disagree about what was read.
+ */
+export declare function registrationGraphCoverage(graph: IRegistrationGraph): IVerdictCoverage | undefined;
+/**
+ * `wiring unprovided` settled against what the graph read AND what every
+ * idiom's roles examined (`roles`: `measureIdiomRoleCoverage`, THE role
+ * authority — required, so no surface can forget the fold). `extra` adds
+ * candidates found another way (finish's base-ref provider regressions); they
+ * are merged by token and sorted, as finish always did.
+ */
+export declare function registrationUnprovidedVerdict(graph: IRegistrationGraph, idioms: readonly IRegistrationIdiom[], roles: readonly IIdiomRoleCoverage[], changedFiles?: readonly string[], extra?: readonly IUnprovidedToken[]): IRegistrationQueryVerdict<IUnprovidedToken>;
+/** `wiring orphans` settled against what the graph read and what every idiom's roles examined. */
+export declare function registrationOrphansVerdict(graph: IRegistrationGraph, idioms: readonly IRegistrationIdiom[], roles: readonly IIdiomRoleCoverage[], changedFiles?: readonly string[]): IRegistrationQueryVerdict<IOrphanRegistration>;
+//# sourceMappingURL=registration-query-verdict.d.ts.map

package/dist/wiring/registration-query-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-query-verdict.d.ts","sourceRoot":"","sources":["../../src/wiring/registration-query-verdict.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAKjC;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,SAAS,CASjG;AAwFD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,EAChC,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAClC,yBAAyB,CAAC,gBAAgB,CAAC,CAQ7C;AAED,kGAAkG;AAClG,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,yBAAyB,CAAC,mBAAmB,CAAC,CAUhD"}

package/dist/wiring/registration-query-verdict.js

@@ -0,0 +1,118 @@
+import { coverageShortfall, resolveSourceGlobs, ruleVerdictRecords, } from '@shrkcrft/core';
+import { describeUnread, readScopeCoverage, unreadMatching } from "../util/read-scope-coverage.js";
+import { registrationOrphans, registrationUnprovided, } from "./registration-graph.js";
+/** At most this many demoted tokens ride on one coverage record. */
+const TOKEN_LABEL_CAP = 20;
+/**
+ * THE registration graph's read-scope record: the idiom files the reader could
+ * not read, named (`examined 3 of 4 files, 1 over the 1MB read cap: …`), or
+ * `undefined` when it read every file its idioms matched. `wiring unprovided |
+ * orphans`, finish's unprovided sub-gate and MCP `get_wiring_graph` all read
+ * it here, so the verb and its siblings cannot disagree about what was read.
+ */
+export function registrationGraphCoverage(graph) {
+    if (!graph.readScope || graph.readScope.unread.length === 0)
+        return undefined;
+    return {
+        ...readScopeCoverage({ unit: 'registration idioms', expected: graph.idioms.length, examined: graph.idioms.length }, graph.readScope),
+        subject: 'registration graph',
+    };
+}
+/**
+ * Every idiom's role records, as an absence query settles them (round 13, P4):
+ * the role authority's coverage (`examined 2 of 3 roles … declared (0 files)`)
+ * plus its expectEmpty acceptance, folded by core's `ruleVerdictRecords` and
+ * subject-prefixed with the idiom. A role record that is only the idiom's read
+ * gap is dropped while the graph's own read-scope record is carried — that
+ * record already names every unread idiom file (a union over idioms); its
+ * acceptance is kept, so a record B is never dropped silently.
+ */
+function roleRecords(graph, roles) {
+    const graphNamesUnread = registrationGraphCoverage(graph) !== undefined;
+    return roles.flatMap((r) => {
+        const records = graphNamesUnread && r.readGap
+            ? r.unitAcceptance
+                ? [r.unitAcceptance]
+                : []
+            : ruleVerdictRecords(r.coverage, r.unitAcceptance);
+        return records.map((c) => ({ ...c, subject: c.subject ?? r.idiom }));
+    });
+}
+/**
+ * THE rule for an absence claim over an incomplete read. The graph merges
+ * tokens across idioms, so a site of the missing role in ANY idiom satisfies a
+ * token. When an unread file matches any idiom's `missingRole` globs, every
+ * candidate could be refuted there: all are demoted to `unproven`, named in a
+ * second coverage record. Otherwise the candidates are findings.
+ *
+ * Round 13 (P4): every idiom's ROLE coverage is carried too, always — the
+ * graph's read scope said nothing about a role whose globs matched no file, so
+ * "every declared token has a provider" printed a ✓ over a declared role that
+ * examined nothing. A dead role never demotes a candidate (a finding stays a
+ * finding, as on `gates check`); it keeps a clean answer from being a pass.
+ */
+function absenceVerdict(graph, idioms, roles, missingRole, candidates, unit, subject) {
+    const unread = graph.readScope?.unread ?? [];
+    // Per idiom's role LIST, never a flattened union: a negation subtracts from
+    // its own list only, so one idiom's `!x` cannot hide a refuting file from
+    // another idiom that reads it. Deduped by path, sorted.
+    const refutingByPath = new Map();
+    for (const i of unread.length > 0 ? idioms : []) {
+        for (const u of unreadMatching(unread, resolveSourceGlobs(i[missingRole]))) {
+            if (!refutingByPath.has(u.path))
+                refutingByPath.set(u.path, u);
+        }
+    }
+    const refuting = [...refutingByPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+    const unproven = refuting.length > 0 ? candidates : [];
+    const fileRecord = registrationGraphCoverage(graph);
+    const coverage = [
+        ...(fileRecord ? [fileRecord] : []),
+        ...roleRecords(graph, roles),
+        ...(unproven.length > 0
+            ? [
+                {
+                    unit,
+                    expected: unproven.length,
+                    examined: 0,
+                    unexamined: unproven.slice(0, TOKEN_LABEL_CAP).map((t) => t.token),
+                    unexaminedTotal: unproven.length,
+                    reason: `may be ${missingRole} in a file the reader did not read — ${describeUnread(refuting)}`,
+                    subject,
+                },
+            ]
+            : []),
+    ];
+    return {
+        findings: refuting.length > 0 ? [] : candidates,
+        unproven,
+        coverage,
+        shortfalls: coverage.flatMap((c) => {
+            const s = coverageShortfall(c);
+            return s === undefined ? [] : [s];
+        }),
+        unread,
+    };
+}
+/**
+ * `wiring unprovided` settled against what the graph read AND what every
+ * idiom's roles examined (`roles`: `measureIdiomRoleCoverage`, THE role
+ * authority — required, so no surface can forget the fold). `extra` adds
+ * candidates found another way (finish's base-ref provider regressions); they
+ * are merged by token and sorted, as finish always did.
+ */
+export function registrationUnprovidedVerdict(graph, idioms, roles, changedFiles, extra) {
+    let candidates = registrationUnprovided(graph, changedFiles);
+    if (extra !== undefined) {
+        const byToken = new Map();
+        for (const u of [...candidates, ...extra])
+            if (!byToken.has(u.token))
+                byToken.set(u.token, u);
+        candidates = [...byToken.values()].sort((a, b) => a.token.localeCompare(b.token));
+    }
+    return absenceVerdict(graph, idioms, roles, 'provided', candidates, 'unprovided tokens', 'unprovided');
+}
+/** `wiring orphans` settled against what the graph read and what every idiom's roles examined. */
+export function registrationOrphansVerdict(graph, idioms, roles, changedFiles) {
+    return absenceVerdict(graph, idioms, roles, 'consumed', registrationOrphans(graph, changedFiles), 'orphan registrations', 'orphans');
+}

package/dist/wiring/registry-query.d.ts

@@ -1,4 +1,5 @@
 import { type IRegistryDeclaration } from '@shrkcrft/core';
+import type { IReadScope } from '../util/read-scope.js';
 export declare const REGISTRY_SCHEMA: "sharkcraft.registry-inventory/v1";
 /** Where an id was found (project-relative path + 1-based line). */
 export interface IRegistrySite {
@@ -22,6 +23,13 @@ export interface IRegistryInventory {
     readonly entries: readonly IRegistryEntry[];
     /** Misconfiguration messages (bad regex / no capture group / bad source). */
     readonly diagnostics: readonly string[];
+    /**
+     * The SOURCE side's read scope: declaration files read, and matched ones the
+     * reader did not read (over the read cap, or unreadable). With any unread
+     * the inventory is incomplete: an absent id, "no duplicates" or an empty
+     * inventory proves nothing.
+     */
+    readonly readScope: IReadScope;
 }
 export interface IScanRegistryOptions {
     /** Project-relative directories to prune from the walk. */

package/dist/wiring/registry-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-query.d.ts","sourceRoot":"","sources":["../../src/wiring/registry-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK/E,eAAO,MAAM,eAAe,EAAG,kCAA2C,CAAC;AAE3E,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,CAkDpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,cAAc,EAAE,CAE3F"}
+{"version":3,"file":"registry-query.d.ts","sourceRoot":"","sources":["../../src/wiring/registry-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,eAAO,MAAM,eAAe,EAAG,kCAA2C,CAAC;AAE3E,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,CAwDpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,cAAc,EAAE,CAE3F"}

package/dist/wiring/registry-query.js

@@ -1,6 +1,7 @@
 import { resolveSourceGlobs } from '@shrkcrft/core';
-import { matchesAny } from "../scan/glob.js";
+import { globListSelects } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
+import { unreadMatching } from "../util/read-scope-coverage.js";
 import { collectSourceSites } from "./evaluate-wiring.js";
 export const REGISTRY_SCHEMA = 'sharkcraft.registry-inventory/v1';
 function sortSites(sites) {
@@ -18,16 +19,18 @@ export function scanRegistry(projectRoot, decl, options = {}) {
             ...(decl.consumer ? resolveSourceGlobs(decl.consumer) : []),
         ]),
     ];
-    const cache = readMatchingFiles(projectRoot, globs, new Set(options.excludeDirs ?? []));
-    const entries = [...cache.entries()].map(([path, content]) => ({ path, content }));
+    const matched = readMatchingFiles(projectRoot, globs, new Set(options.excludeDirs ?? []));
+    const entries = [...matched.files.entries()].map(([path, content]) => ({ path, content }));
     const diagnostics = [];
-    const sourceFiles = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(decl.source)));
+    // The walk above is the POSITIVE union of both sides; each side selects its
+    // own files, so the source's `!` never hides a consumer file (or vice versa).
+    const sourceFiles = entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(decl.source)));
     const declared = collectSourceSites(decl.source, sourceFiles);
     if (declared.error)
         diagnostics.push(`registry "${decl.name}" source: ${declared.error}`);
     const consumerByToken = new Map();
     if (decl.consumer) {
-        const consumerFiles = entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(decl.consumer)));
+        const consumerFiles = entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(decl.consumer)));
         const consumed = collectSourceSites(decl.consumer, consumerFiles);
         if (consumed.error)
             diagnostics.push(`registry "${decl.name}" consumer: ${consumed.error}`);
@@ -57,6 +60,10 @@ export function scanRegistry(projectRoot, decl, options = {}) {
         ...(decl.description ? { description: decl.description } : {}),
         entries: entriesOut,
         diagnostics,
+        readScope: {
+            read: sourceFiles.length,
+            unread: unreadMatching(matched.unread, resolveSourceGlobs(decl.source)),
+        },
     };
 }
 /** True if `id` is declared in the registry (alias-blind exact membership). */

package/dist/wiring/scan-wiring-files.d.ts

@@ -12,8 +12,10 @@ export interface IRunWiringOptions {
 }
 /**
  * Filesystem-backed wiring run: walks the project once, reads only the files a
- * rule references (skipping oversized files), and evaluates every (selected)
- * rule. Pure-engine output; the only IO is the read-only tree walk + reads.
+ * rule references, and evaluates every (selected) rule. A matched file the
+ * reader could not read (over the read cap) is handed to the engine as
+ * unread, so the rule's coverage names it instead of passing over it.
+ * Pure-engine output; the only IO is the read-only tree walk + reads.
  */
 export declare function runWiring(projectRoot: string, rules: readonly IWiringRule[], options?: IRunWiringOptions): IWiringReport;
 //# sourceMappingURL=scan-wiring-files.d.ts.map

package/dist/wiring/scan-wiring-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-wiring-files.d.ts","sourceRoot":"","sources":["../../src/wiring/scan-wiring-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAItE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAqCf"}
+{"version":3,"file":"scan-wiring-files.d.ts","sourceRoot":"","sources":["../../src/wiring/scan-wiring-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2C,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAQ3F,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAQ9B,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAsEf"}

package/dist/wiring/scan-wiring-files.js

@@ -1,29 +1,49 @@
-import { resolveSourceGlobs } from '@shrkcrft/core';
-import { matchesAny } from "../scan/glob.js";
+import { normalizeWiringRule, resolveSourceGlobs } from '@shrkcrft/core';
+import { globListSelects } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
+import { unreadMatching } from "../util/read-scope-coverage.js";
+import { globListUnits } from "../util/dead-glob-units.js";
+import { settleGlobLists } from "../util/settle-glob-lists.js";
+import { sourceLivenessRequest } from "../extract/source-liveness-request.js";
 import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
-import { evaluateWiring, wiringGlobsOf, } from "./evaluate-wiring.js";
+import { evaluateWiring, wiringGlobsOf, wiringSourcesOf, } from "./evaluate-wiring.js";
+import { wiringLabeledSources } from "./wiring-labeled-sources.js";
 /** All file globs a rule references: every side / every hop. */
 function ruleGlobs(rule) {
     return wiringGlobsOf(rule);
 }
 /**
  * Filesystem-backed wiring run: walks the project once, reads only the files a
- * rule references (skipping oversized files), and evaluates every (selected)
- * rule. Pure-engine output; the only IO is the read-only tree walk + reads.
+ * rule references, and evaluates every (selected) rule. A matched file the
+ * reader could not read (over the read cap) is handed to the engine as
+ * unread, so the rule's coverage names it instead of passing over it.
+ * Pure-engine output; the only IO is the read-only tree walk + reads.
  */
 export function runWiring(projectRoot, rules, options = {}) {
-    let selected = rules;
+    // The engine entry normalises idempotently (round 13): a loaded rule comes
+    // back equal, a hand-built `{ pattern, expectEmpty }` entry becomes a glob
+    // plus a marker. A MALFORMED entry stays on the authored rule, which
+    // `evaluateWiring` reports as misconfigured — no glob reader here sees it.
+    const malformed = new Set();
+    let selected = rules.map((r) => {
+        const n = normalizeWiringRule(r);
+        if (n.ok)
+            return n.value;
+        malformed.add(r);
+        return r;
+    });
     if (options.only && options.only.length > 0) {
         const ids = new Set(options.only);
         selected = selected.filter((r) => ids.has(r.id));
     }
     if (options.changedOnly) {
         const changed = options.changedFiles ?? [];
-        selected = selected.filter((r) => {
-            const globs = ruleGlobs(r);
-            return changed.some((c) => matchesAny(c, globs));
-        });
+        // Per SOURCE, never through the flattened union: a negation subtracts from
+        // its own list only, so one side's `!x` cannot hide a changed file another
+        // side reads, and a change touching only excluded files selects nothing.
+        // A malformed rule has no footprint to prove it out of scope: it stays in.
+        selected = selected.filter((r) => malformed.has(r) ||
+            wiringSourcesOf(r).some((s) => changed.some((c) => globListSelects(c, resolveSourceGlobs(s)))));
     }
     if (selected.length === 0) {
         return {
@@ -33,14 +53,31 @@ export function runWiring(projectRoot, rules, options = {}) {
             diagnostics: [],
             skipped: [],
             evaluated: 0,
+            acceptedEmpty: 0,
             verdict: 'pass',
         };
     }
-    // Union of all globs across selected rules → one tree walk, cached reads.
-    const allGlobs = [...new Set(selected.flatMap(ruleGlobs))];
-    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
-    const entries = [...cache.entries()].map(([path, content]) => ({ path, content }));
+    // Union of all globs across selected rules → one POSITIVE tree walk, cached
+    // reads; each source then selects its own files from it (`globListSelects`).
+    const allGlobs = [...new Set(selected.filter((r) => !malformed.has(r)).flatMap(ruleGlobs))];
+    const excludeDirs = options.excludeDirs ?? [];
+    const matched = readMatchingFiles(projectRoot, allGlobs, new Set(excludeDirs));
+    const entries = [...matched.files.entries()].map(([path, content]) => ({ path, content }));
+    const walked = entries.map((f) => f.path);
+    // THE one dead-unit decision (`globListUnits`, the one `gates coverage` and
+    // `policy-lint` read) over this run's positive walk.
+    const unitsOf = (globs) => globListUnits(walked, matched.unread, globs);
     // The tsconfig paths let an `import-edges` source resolve alias specifiers the
     // way the compiler does — the same map `check boundaries` resolves with.
-    return evaluateWiring(selected, (source) => entries.filter((f) => matchesAny(f.path, resolveSourceGlobs(source))), { tsconfigPaths: loadTsconfigPaths(projectRoot) });
+    return evaluateWiring(selected, (source) => entries.filter((f) => globListSelects(f.path, resolveSourceGlobs(source))), { tsconfigPaths: loadTsconfigPaths(projectRoot) }, (source) => unreadMatching(matched.unread, resolveSourceGlobs(source)), 
+    // Which negations emptied a source's list, so its skip reason says so (R12-DOC-2).
+    (source) => {
+        const units = unitsOf(resolveSourceGlobs(source));
+        return units.allExcluded ? units.negations : undefined;
+    }, 
+    // Every source's glob units settled with their `expectEmpty` markers
+    // (round 13) — THE per-source request `gates coverage` builds too
+    // (`sourceLivenessRequest` over the engine's own side labels), so `check
+    // wiring` and `gates coverage` accept, and word, one planned glob alike.
+    (rule) => settleGlobLists(sourceLivenessRequest(projectRoot, wiringLabeledSources(rule), excludeDirs, rule.id, unitsOf)));
 }

package/dist/wiring/sink-imports.d.ts

@@ -31,6 +31,17 @@ export interface ISinkBinding {
     /** Module specifier, for an import binding. */
     readonly specifier?: string;
 }
+/**
+ * Top-level value/type declarations — the names a file binds itself.
+ *
+ * Every whitespace run is single-line (`[ \t]`). The old form opened with
+ * `(?:^|\n)\s*`: from every newline of a long blank block, `\s*` ran across all
+ * the lines below it and backtracked through each — O(lines × run) per block
+ * (`findBlankRunHazards` flags that shape). Modifiers and the declared name sit
+ * on the declaration's own line in real TS, so the matches are the same
+ * (`r75-blank-run-linearity.test.ts` holds old ≡ new over every source file).
+ */
+export declare const LOCAL_DECL: RegExp;
 /**
  * Every value name bound in the file: imports plus its own top-level
  * declarations.

package/dist/wiring/sink-imports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink-imports.d.ts","sourceRoot":"","sources":["../../src/wiring/sink-imports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,OAAO,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAsBnE;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,eAAe,GAAG,SAAS,CA6B7B;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,SAAS,CAe9B"}
+{"version":3,"file":"sink-imports.d.ts","sourceRoot":"","sources":["../../src/wiring/sink-imports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,OAAO,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,QAC0I,CAAC;AAElK;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAsBnE;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,eAAe,GAAG,SAAS,CA6B7B;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,SAAS,CAe9B"}

package/dist/wiring/sink-imports.js

@@ -1,7 +1,16 @@
 import { lineOf } from "../extract/scan-literals.js";
 import { parseImportStatements } from "../extract/parse-imports.js";
-/** Top-level value/type declarations — the names a file binds itself. */
-const LOCAL_DECL = /(?:^|\n)\s*(?:export\s+)?(?:declare\s+)?(?:default\s+)?(?:const|let|var|function\s*\*?|class|enum|interface|type)\s+([A-Za-z_$][\w$]*)/g;
+/**
+ * Top-level value/type declarations — the names a file binds itself.
+ *
+ * Every whitespace run is single-line (`[ \t]`). The old form opened with
+ * `(?:^|\n)\s*`: from every newline of a long blank block, `\s*` ran across all
+ * the lines below it and backtracked through each — O(lines × run) per block
+ * (`findBlankRunHazards` flags that shape). Modifiers and the declared name sit
+ * on the declaration's own line in real TS, so the matches are the same
+ * (`r75-blank-run-linearity.test.ts` holds old ≡ new over every source file).
+ */
+export const LOCAL_DECL = /(?:^|\n)[ \t]*(?:export[ \t]+)?(?:declare[ \t]+)?(?:default[ \t]+)?(?:const|let|var|function(?:[ \t]*\*)?|class|enum|interface|type)[ \t]+([A-Za-z_$][\w$]*)/g;
 /**
  * Every value name bound in the file: imports plus its own top-level
  * declarations.

package/dist/wiring/trace-literal.d.ts

@@ -1,3 +1,4 @@
+import type { IUnreadFile } from '../util/unread-file.js';
 export declare const TRACE_SCHEMA: "sharkcraft.trace/v1";
 /** Default source globs scanned when `trace` is given no `--glob`. */
 export declare const TRACE_DEFAULT_GLOBS: readonly string[];
@@ -41,6 +42,11 @@ export interface ITraceReport {
     readonly byRole: Readonly<Record<TraceRole, readonly ITraceSite[]>>;
     /** Const names found bound to the literal (`const NAME = 'literal'`), if any. */
     readonly aliases: readonly string[];
+    /**
+     * Matched files the reader did not read (over the read cap, or unreadable),
+     * so a site inside one is missing from `byRole`. Set only when non-empty.
+     */
+    readonly unread?: readonly IUnreadFile[];
 }
 export interface ITraceOptions {
     /** Override the default source globs. */

package/dist/wiring/trace-literal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-literal.d.ts","sourceRoot":"","sources":["../../src/wiring/trace-literal.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA6ED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAuFd"}
+{"version":3,"file":"trace-literal.d.ts","sourceRoot":"","sources":["../../src/wiring/trace-literal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAShD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA6ED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CA0Fd"}

package/dist/wiring/trace-literal.js

@@ -1,4 +1,4 @@
-import { readMatchingFiles } from "../util/walk-files.js";
+import { readSelectedFiles } from "../util/read-selected-files.js";
 export const TRACE_SCHEMA = 'sharkcraft.trace/v1';
 /** Default source globs scanned when `trace` is given no `--glob`. */
 export const TRACE_DEFAULT_GLOBS = [
@@ -125,7 +125,9 @@ const ALIAS_NAME = /^[A-Z][\w$]*$/;
 export function traceLiteral(projectRoot, literal, options = {}) {
     const globs = options.globs && options.globs.length > 0 ? options.globs : TRACE_DEFAULT_GLOBS;
     const exclude = new Set(options.excludeDirs ?? []);
-    const cache = readMatchingFiles(projectRoot, globs, exclude);
+    // One glob list (the caller's `--glob`s, or the defaults): a `!` excludes.
+    const matched = readSelectedFiles(projectRoot, globs, exclude);
+    const cache = matched.files;
     const sites = [];
     const aliasNames = new Set();
     // Exact quoted-literal match: the closing quote immediately follows, so the
@@ -205,5 +207,6 @@ export function traceLiteral(projectRoot, literal, options = {}) {
             [TraceRole.Reference]: sortSites(byRole[TraceRole.Reference]),
         },
         aliases: [...aliasNames].sort(),
+        ...(matched.unread.length > 0 ? { unread: matched.unread } : {}),
     };
 }

package/dist/wiring/wiring-labeled-sources.d.ts

@@ -0,0 +1,12 @@
+import type { IWiringRule } from '@shrkcrft/core';
+import type { ILabeledSource } from '../extract/i-labeled-source.js';
+/**
+ * THE enumeration of a wiring rule's sources, each named by its side —
+ * `declared`, `registered` (or `registered[i]` when a rule unions several
+ * sinks), `chain[i]`. `gates coverage` / `gates explain` (the CLI's
+ * `gateRuleLabeledSources`) and the wiring engine's liveness settle
+ * (`runWiring`) both read it, so a marker or a dead glob is named by one side
+ * label on every surface.
+ */
+export declare function wiringLabeledSources(rule: IWiringRule): readonly ILabeledSource[];
+//# sourceMappingURL=wiring-labeled-sources.d.ts.map

package/dist/wiring/wiring-labeled-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring-labeled-sources.d.ts","sourceRoot":"","sources":["../../src/wiring/wiring-labeled-sources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,cAAc,EAAE,CAWjF"}

package/dist/wiring/wiring-labeled-sources.js

@@ -0,0 +1,20 @@
+/**
+ * THE enumeration of a wiring rule's sources, each named by its side —
+ * `declared`, `registered` (or `registered[i]` when a rule unions several
+ * sinks), `chain[i]`. `gates coverage` / `gates explain` (the CLI's
+ * `gateRuleLabeledSources`) and the wiring engine's liveness settle
+ * (`runWiring`) both read it, so a marker or a dead glob is named by one side
+ * label on every surface.
+ */
+export function wiringLabeledSources(rule) {
+    const registered = Array.isArray(rule.registered)
+        ? rule.registered
+        : rule.registered
+            ? [rule.registered]
+            : [];
+    return [
+        ...(rule.declared ? [{ label: 'declared', source: rule.declared }] : []),
+        ...registered.map((source, i) => ({ label: registered.length > 1 ? `registered[${i}]` : 'registered', source })),
+        ...(rule.chain ?? []).map((source, i) => ({ label: `chain[${i}]`, source })),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/boundaries",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "SharkCraft boundary rules: detect when a repository violates its own architecture (forbidden imports across folder/package/layer boundaries).",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,7 +43,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.30"
+    "@shrkcrft/core": "^0.1.0-alpha.31"
   },
   "publishConfig": {
     "access": "public"