@shrkcrft/boundaries 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/index.d.ts

@@ -7,6 +7,10 @@ export * from './evaluate/evaluate-boundaries.js';
 export * from './scan/tsconfig-aliases.js';
 export * from './wiring/evaluate-wiring.js';
 export * from './wiring/scan-wiring-files.js';
+export * from './wiring/explain-wiring.js';
+export * from './wiring/registry-query.js';
+export * from './wiring/registration-graph.js';
+export * from './wiring/trace-literal.js';
 export * from './policy/extract-templates.js';
 export * from './policy/evaluate-policy.js';
 export * from './policy/run-policy.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -7,6 +7,10 @@ export * from "./evaluate/evaluate-boundaries.js";
 export * from "./scan/tsconfig-aliases.js";
 export * from "./wiring/evaluate-wiring.js";
 export * from "./wiring/scan-wiring-files.js";
+export * from "./wiring/explain-wiring.js";
+export * from "./wiring/registry-query.js";
+export * from "./wiring/registration-graph.js";
+export * from "./wiring/trace-literal.js";
 export * from "./policy/extract-templates.js";
 export * from "./policy/evaluate-policy.js";
 export * from "./policy/run-policy.js";

package/dist/policy/evaluate-policy.d.ts

@@ -36,6 +36,14 @@ export interface IPolicyReport {
     readonly rules: readonly IPolicyRuleResult[];
     readonly findings: readonly IPolicyFinding[];
     readonly diagnostics: readonly string[];
+    /**
+     * Count of rules that actually scanned ≥1 unit. A rule whose globs matched 0
+     * files (e.g. a `style` rule in a project with no stylesheets) is NOT
+     * evaluated — a silent no-op the gate surfaces as `skipped` rather than a
+     * green pass. Misconfigured rules count as evaluated so their error is not
+     * swallowed by the gate's `evaluated === 0` skip path.
+     */
+    readonly evaluated: number;
     readonly verdict: 'pass' | 'errors' | 'warnings';
 }
 /** Resolves the content units to scan for a given rule (injected for purity/testability). */

package/dist/policy/evaluate-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,kBAAkB,EAAG,2BAAoC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,SAAS,WAAW,EAAE,CAAC;AAgB/E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAoExG"}
+{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,kBAAkB,EAAG,2BAAoC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,SAAS,WAAW,EAAE,CAAC;AAgB/E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CA2ExG"}

package/dist/policy/evaluate-policy.js

@@ -23,6 +23,7 @@ export function evaluatePolicy(rules, resolve) {
     const ruleResults = [];
     const findings = [];
     const diagnostics = [];
+    let evaluated = 0;
     let misconfigError = false;
     let misconfigWarn = false;
     for (const rule of rules) {
@@ -36,11 +37,17 @@ export function evaluatePolicy(rules, resolve) {
             else
                 misconfigWarn = true;
             ruleResults.push({ ruleId: rule.id, surface: rule.surface, severity, findingCount: 0, error: msg });
+            // A misconfigured rule attempted to run — count it as evaluated so its
+            // error isn't swallowed by the gate's `evaluated === 0` skip path.
+            evaluated += 1;
             continue;
         }
+        const units = resolve(rule);
+        if (units.length > 0)
+            evaluated += 1;
         let count = 0;
         let zeroWidth = false;
-        for (const unit of resolve(rule)) {
+        for (const unit of units) {
             re.lastIndex = 0;
             let m;
             while ((m = re.exec(unit.content)) !== null) {
@@ -87,6 +94,7 @@ export function evaluatePolicy(rules, resolve) {
         rules: ruleResults,
         findings,
         diagnostics,
+        evaluated,
         verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
     };
 }

package/dist/policy/run-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAY5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAsCf"}
+{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAY5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CA6Cf"}

package/dist/policy/run-policy.js

@@ -35,14 +35,22 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
         selected = selected.filter((r) => changed.some((c) => matchesAny(c, globsFor(r))));
     }
     if (selected.length === 0) {
-        return { schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], verdict: 'pass' };
+        return { schema: 'sharkcraft.policy-lint/v1', rules: [], findings: [], diagnostics: [], evaluated: 0, verdict: 'pass' };
     }
+    // Under --changed-only, restrict the SCANNED files to the changed set too (not
+    // just rule selection). Per-file regex findings have no cross-file dependency,
+    // so a pre-existing violation in a file the diff never touched is out of scope
+    // — this mirrors how `check boundaries`/wiring restrict to the changeset and
+    // stops the gate failing RED on untouched legacy debt.
+    const changedSet = options.changedOnly ? new Set(options.changedFiles ?? []) : undefined;
     const allGlobs = [...new Set(selected.flatMap((r) => [...globsFor(r)]))];
     const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
     return evaluatePolicy(selected, (rule) => {
         const globs = globsFor(rule);
         const units = [];
         for (const [path, content] of cache) {
+            if (changedSet && !changedSet.has(path))
+                continue;
             if (!matchesAny(path, globs))
                 continue;
             const ext = nodePath.extname(path).toLowerCase();

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

@@ -1 +1 @@
-{"version":3,"file":"scan-imports.d.ts","sourceRoot":"","sources":["../../src/scan/scan-imports.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAoFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAyB3E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB7E"}
+{"version":3,"file":"scan-imports.d.ts","sourceRoot":"","sources":["../../src/scan/scan-imports.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAyB3E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB7E"}

package/dist/scan/scan-imports.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as nodePath from 'node:path';
 const SUPPORTED_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
 const DEFAULT_IGNORE = new Set([
@@ -46,18 +46,16 @@ function* walk(root, current, extraIgnore) {
         const name = String(entry.name);
         if (isIgnored(name, extraIgnore))
             continue;
+        // Do NOT descend into (or yield through) symlinks. Following a symlinked
+        // directory can inject phantom files into the graph — a self-referential
+        // loop (`src/loop -> src` => `src/loop/loop/loop/...`) only self-terminates
+        // by accident at PATH_MAX, and a link to a large external tree gets fully
+        // scanned. Mirror detect-workspace.ts's isTraversableDir pruning.
+        if (entry.isSymbolicLink())
+            continue;
         const full = nodePath.join(current, name);
-        try {
-            const isDir = entry.isDirectory() || entry.isSymbolicLink();
-            if (isDir) {
-                const stat = statSync(full);
-                if (stat.isDirectory()) {
-                    yield* walk(root, full, extraIgnore);
-                }
-                continue;
-            }
-        }
-        catch {
+        if (entry.isDirectory()) {
+            yield* walk(root, full, extraIgnore);
             continue;
         }
         if (entry.isFile()) {

package/dist/wiring/evaluate-wiring.d.ts

@@ -6,7 +6,7 @@ export interface IWiringFileEntry {
     readonly path: string;
     readonly content: string;
 }
-/** A captured token + where it was captured (for declared tokens). */
+/** A captured token + where it was captured. */
 export interface IWiringTokenSite {
     readonly token: string;
     readonly file: string;
@@ -14,12 +14,18 @@ export interface IWiringTokenSite {
 }
 export interface IWiringViolation {
     readonly ruleId: string;
-    /** The declared token that is not present in the registered set. */
+    /** The token that is missing from the other side. */
     readonly token: string;
-    /** Declaring file (project-relative) + 1-based line. */
+    /** Declaring (or registering) file (project-relative) + 1-based line. */
     readonly file: string;
     readonly line: number;
     readonly severity: 'error' | 'warning';
+    /**
+     * Which side the token is missing from. `declared-missing` (the subset case):
+     * declared but not registered. `registered-missing` (parity only): registered
+     * but never declared.
+     */
+    readonly direction?: 'declared-missing' | 'registered-missing';
     readonly hint?: string;
 }
 export interface IWiringRuleResult {
@@ -29,7 +35,7 @@ export interface IWiringRuleResult {
     readonly declaredCount: number;
     readonly registeredCount: number;
     readonly violations: readonly IWiringViolation[];
-    /** Set when the rule is misconfigured (bad regex / no capture group). */
+    /** Set when the rule is misconfigured (bad regex / no capture group / bad source). */
     readonly error?: string;
 }
 export interface IWiringReport {
@@ -38,15 +44,36 @@ export interface IWiringReport {
     readonly violations: readonly IWiringViolation[];
     /** Rule-level misconfiguration messages (never throws — degrades gracefully). */
     readonly diagnostics: readonly string[];
+    /**
+     * Count of rules that actually ran a comparison. A rule whose declared+
+     * registered globs matched 0 files is NOT evaluated (a silent no-op the gate
+     * surfaces as `skipped`). Misconfigured rules count as evaluated so their
+     * error is not swallowed.
+     */
+    readonly evaluated: number;
     readonly verdict: 'pass' | 'errors' | 'warnings';
 }
 /** Resolves a rule-side's globs to the concrete files (path + content) to scan. */
 export type WiringFileResolver = (source: IWiringSource) => readonly IWiringFileEntry[];
 /**
- * Pure wiring evaluation. For each rule: every DECLARED token that is not in the
- * REGISTERED set is a violation, reported at its first declaring site. The
- * `resolve` callback supplies the files for a given rule-side (injected so the
- * engine stays pure / testable — see `runWiring` for the fs-backed wiring).
+ * Public: extract every token site from ONE wiring source (regex capture group
+ * 1 or `arrayProperty` elements) over the given files. Shared by the wiring
+ * evaluator and the registry-inventory engine so both honour the exact same
+ * extraction semantics. A misconfigured source returns an `error` and no sites
+ * (never throws).
+ */
+export declare function collectSourceSites(source: IWiringSource, files: readonly IWiringFileEntry[]): {
+    sites: readonly IWiringTokenSite[];
+    error?: string;
+};
+/**
+ * Pure wiring evaluation. For each rule: the DECLARED token set is checked
+ * against the UNION of the REGISTERED sources. Every declared token absent from
+ * the registered set is a `declared-missing` violation; in `parity` mode every
+ * registered token absent from the declared set is also a `registered-missing`
+ * violation. With `groupBy`, membership is checked within the same dir/package.
+ * The `resolve` callback supplies the files for a given rule-side (injected so
+ * the engine stays pure / testable — see `runWiring` for the fs-backed wiring).
  */
 export declare function evaluateWiring(rules: readonly IWiringRule[], resolve: WiringFileResolver): IWiringReport;
 //# sourceMappingURL=evaluate-wiring.d.ts.map

package/dist/wiring/evaluate-wiring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS,gBAAgB,EAAE,CAAC;AAiDxF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAkFf"}
+{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGjE,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,GAAG,oBAAoB,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAED,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS,gBAAgB,EAAE,CAAC;AAsCxF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,gBAAgB,EAAE,GACjC;IAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAOxD;AAuJD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAsHf"}

package/dist/wiring/explain-wiring.d.ts

@@ -0,0 +1,53 @@
+import type { IWiringRule } from '@shrkcrft/core';
+import { type IWiringTokenSite } from './evaluate-wiring.js';
+export declare const WIRING_EXPLAIN_SCHEMA: "sharkcraft.wiring-explain/v1";
+/** One side (declared or registered) of a wiring rule, as extracted from the tree. */
+export interface IWiringSideExplain {
+    /** Every capture site (token + file:line), stable-sorted by (file, line). */
+    readonly sites: readonly IWiringTokenSite[];
+    /** Distinct membership-key count (mirrors the gate's `declared/registered N`). */
+    readonly distinctCount: number;
+    /** Files scanned for this side (after glob resolution). */
+    readonly filesScanned: number;
+    /** Misconfiguration (bad regex / no capture group / bad source), if any. */
+    readonly error?: string;
+}
+/**
+ * The full intermediate output of evaluating ONE wiring rule against the live
+ * tree: the declared set and the registered set each source extracted (with
+ * file:line), plus the set-difference and verdict — the thing {@link
+ * evaluateWiring} computes internally but only emits as counts + violations.
+ */
+export interface IWiringExplain {
+    readonly schema: typeof WIRING_EXPLAIN_SCHEMA;
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly mode: 'subset' | 'parity';
+    readonly groupBy?: 'dir' | 'package';
+    readonly severity: 'error' | 'warning';
+    readonly declared: IWiringSideExplain;
+    readonly registered: IWiringSideExplain;
+    /** Declared tokens absent from the registered set (the `declared-missing` diff). */
+    readonly declaredNotRegistered: readonly IWiringTokenSite[];
+    /** Registered tokens absent from the declared set (parity-only `registered-missing`). */
+    readonly registeredNotDeclared: readonly IWiringTokenSite[];
+    readonly verdict: 'pass' | 'errors' | 'warnings';
+    /** Rule-level misconfiguration messages (engine degrades gracefully). */
+    readonly diagnostics: readonly string[];
+}
+export interface IExplainWiringOptions {
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Dry-run a single wiring rule against the live tree and return what each side
+ * extracted (declared set, registered set, the set-difference, the verdict) —
+ * WITHOUT writing config. Powers `wiring explain <ruleId>`, `wiring test
+ * <candidate>`, and `check wiring --explain <ruleId>`: the author can SEE the
+ * alias-resolved cross-file set-difference the gate computes before committing
+ * a rule. The diff/verdict reuse {@link evaluateWiring} so they match the gate
+ * exactly (incl. `groupBy` membership); the full per-site lists are extracted
+ * with the shared {@link collectSourceSites}. Never throws.
+ */
+export declare function explainWiring(projectRoot: string, rule: IWiringRule, options?: IExplainWiringOptions): IWiringExplain;
+//# sourceMappingURL=explain-wiring.d.ts.map

package/dist/wiring/explain-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/explain-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,qBAAqB,EAAG,8BAAuC,CAAC;AAE7E,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,oFAAoF;IACpF,QAAQ,CAAC,qBAAqB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5D,yFAAyF;IACzF,QAAQ,CAAC,qBAAqB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IACjD,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAYD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAmEhB"}

package/dist/wiring/explain-wiring.js

@@ -0,0 +1,81 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { collectSourceSites, evaluateWiring, } from "./evaluate-wiring.js";
+export const WIRING_EXPLAIN_SCHEMA = 'sharkcraft.wiring-explain/v1';
+function registeredSources(reg) {
+    return Array.isArray(reg) ? reg : [reg];
+}
+function sortSites(sites) {
+    return [...sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.token.localeCompare(b.token));
+}
+/**
+ * Dry-run a single wiring rule against the live tree and return what each side
+ * extracted (declared set, registered set, the set-difference, the verdict) —
+ * WITHOUT writing config. Powers `wiring explain <ruleId>`, `wiring test
+ * <candidate>`, and `check wiring --explain <ruleId>`: the author can SEE the
+ * alias-resolved cross-file set-difference the gate computes before committing
+ * a rule. The diff/verdict reuse {@link evaluateWiring} so they match the gate
+ * exactly (incl. `groupBy` membership); the full per-site lists are extracted
+ * with the shared {@link collectSourceSites}. Never throws.
+ */
+export function explainWiring(projectRoot, rule, options = {}) {
+    const regSources = registeredSources(rule.registered);
+    const allGlobs = [
+        ...new Set([...rule.declared.files, ...regSources.flatMap((s) => [...s.files])]),
+    ];
+    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
+    const entries = [...cache.entries()].map(([path, content]) => ({
+        path,
+        content,
+    }));
+    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files));
+    // Declared side — full sites.
+    const declaredFiles = filesFor(rule.declared);
+    const declaredRes = collectSourceSites(rule.declared, declaredFiles);
+    // Registered side — union of every source, full sites.
+    const registeredFiles = new Set();
+    const registeredSites = [];
+    let registeredError;
+    for (const source of regSources) {
+        const files = filesFor(source);
+        for (const f of files)
+            registeredFiles.add(f.path);
+        const res = collectSourceSites(source, files);
+        if (res.error && !registeredError)
+            registeredError = res.error;
+        registeredSites.push(...res.sites);
+    }
+    // Canonical diff + counts + verdict from the gate engine (same groupBy logic).
+    const report = evaluateWiring([rule], filesFor);
+    const ruleResult = report.rules[0];
+    const declaredNotRegistered = sortSites((ruleResult?.violations ?? [])
+        .filter((v) => v.direction === 'declared-missing')
+        .map((v) => ({ token: v.token, file: v.file, line: v.line })));
+    const registeredNotDeclared = sortSites((ruleResult?.violations ?? [])
+        .filter((v) => v.direction === 'registered-missing')
+        .map((v) => ({ token: v.token, file: v.file, line: v.line })));
+    return {
+        schema: WIRING_EXPLAIN_SCHEMA,
+        ruleId: rule.id,
+        ...(rule.description ? { description: rule.description } : {}),
+        mode: rule.mode === 'parity' ? 'parity' : 'subset',
+        ...(rule.groupBy ? { groupBy: rule.groupBy } : {}),
+        severity: rule.severity ?? 'error',
+        declared: {
+            sites: sortSites(declaredRes.sites),
+            distinctCount: ruleResult?.declaredCount ?? 0,
+            filesScanned: declaredFiles.length,
+            ...(declaredRes.error ? { error: declaredRes.error } : {}),
+        },
+        registered: {
+            sites: sortSites(registeredSites),
+            distinctCount: ruleResult?.registeredCount ?? 0,
+            filesScanned: registeredFiles.size,
+            ...(registeredError ? { error: registeredError } : {}),
+        },
+        declaredNotRegistered,
+        registeredNotDeclared,
+        verdict: report.verdict,
+        diagnostics: report.diagnostics,
+    };
+}

package/dist/wiring/registration-graph.d.ts

@@ -0,0 +1,92 @@
+import type { IRegistrationIdiom } from '@shrkcrft/core';
+export declare const REGISTRATION_GRAPH_SCHEMA: "sharkcraft.registration-graph/v1";
+/** A token role-site: which idiom + file:line it was found at. */
+export interface IRegistrationSite {
+    readonly idiom: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** One token in the registration graph and the three roles it plays. */
+export interface IRegistrationNode {
+    readonly token: string;
+    /** Sites where the token is DECLARED (token/provider definition). */
+    readonly declared: readonly IRegistrationSite[];
+    /** Sites where the token is PROVIDED / REGISTERED into a composition. */
+    readonly provided: readonly IRegistrationSite[];
+    /** Sites where the token is CONSUMED / INJECTED. */
+    readonly consumed: readonly IRegistrationSite[];
+}
+/**
+ * The registration / DI graph: a peer to the import graph extracted from the
+ * declared idiom shapes, keyed by token. Distinct edge kinds (declared /
+ * provided / consumed) so the runtime-wiring questions imports can't answer
+ * become deterministic queries.
+ */
+export interface IRegistrationGraph {
+    readonly schema: typeof REGISTRATION_GRAPH_SCHEMA;
+    /** Idiom names that contributed to this graph. */
+    readonly idioms: readonly string[];
+    /** Every distinct token, sorted, with its role-sites. */
+    readonly tokens: readonly IRegistrationNode[];
+    /** Misconfiguration messages (bad regex / no capture group / bad source). */
+    readonly diagnostics: readonly string[];
+}
+export interface IBuildRegistrationGraphOptions {
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Build the registration/DI graph from the declared idioms. For each idiom the
+ * three roles (declared / provided / consumed) are extracted with the shared
+ * alias-aware {@link collectSourceSites}, then bucketed by token across every
+ * idiom. Pure-engine output; the only IO is a single read-only tree walk over
+ * the union of all idiom globs. Never throws — a misconfigured source becomes a
+ * diagnostic.
+ */
+export declare function buildRegistrationGraph(projectRoot: string, idioms: readonly IRegistrationIdiom[], options?: IBuildRegistrationGraphOptions): IRegistrationGraph;
+/**
+ * A cheap content-signature of the exact files {@link buildRegistrationGraph}
+ * would read for these idioms: the sorted `relpath:mtimeMs:size` of every matched
+ * file, hashed. Because it reflects the graph's ACTUAL data source (a live tree
+ * walk) rather than the unrelated code-graph index, it is the correct key for any
+ * 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.
+ */
+export declare function registrationGraphSignature(projectRoot: string, idioms: readonly IRegistrationIdiom[], options?: IBuildRegistrationGraphOptions): string;
+/** A token's full registration chain, with role presence flags. */
+export interface IRegistrationChain extends IRegistrationNode {
+    readonly isDeclared: boolean;
+    readonly isProvided: boolean;
+    readonly isConsumed: boolean;
+}
+/**
+ * `wiring chain <token>` — the declared → provided → consumed hops of one token
+ * with file:line at each, or `undefined` if the token is unknown to the graph.
+ */
+export declare function registrationChain(graph: IRegistrationGraph, token: string): IRegistrationChain | undefined;
+/** A token declared or injected but never provided — silently absent at runtime. */
+export interface IUnprovidedToken {
+    readonly token: string;
+    readonly declared: readonly IRegistrationSite[];
+    readonly consumed: readonly IRegistrationSite[];
+}
+/**
+ * `wiring unprovided` — tokens that are DECLARED or CONSUMED but have ZERO
+ * provided sites. This is the silent-at-runtime class: typecheck/AOT-green, but
+ * the provider is never registered (or the injected token has no provider
+ * anywhere), so it resolves to undefined at runtime. The thing imports can't see.
+ */
+export declare function registrationUnprovided(graph: IRegistrationGraph): readonly IUnprovidedToken[];
+/** A token provided/registered that nothing consumes — a dead registration. */
+export interface IOrphanRegistration {
+    readonly token: string;
+    readonly provided: readonly IRegistrationSite[];
+}
+/**
+ * `wiring orphans` — tokens that ARE provided/registered but have ZERO consumed
+ * sites: a provider/registration nothing injects (a build-clean no-op, or a
+ * sign the consumer was renamed/removed).
+ */
+export declare function registrationOrphans(graph: IRegistrationGraph): readonly IOrphanRegistration[];
+//# sourceMappingURL=registration-graph.d.ts.map

package/dist/wiring/registration-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-graph.d.ts","sourceRoot":"","sources":["../../src/wiring/registration-graph.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,gBAAgB,CAAC;AAKxE,eAAO,MAAM,yBAAyB,EAAG,kCAA2C,CAAC;AAErF,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,yBAAyB,CAAC;IAClD,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,8BAA8B;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAiBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,OAAO,GAAE,8BAAmC,GAC3C,kBAAkB,CAqDpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,OAAO,GAAE,8BAAmC,GAC3C,MAAM,CAiBR;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,MAAM,GACZ,kBAAkB,GAAG,SAAS,CAShC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,gBAAgB,EAAE,CAI7F;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,mBAAmB,EAAE,CAI7F"}

package/dist/wiring/registration-graph.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles, walkMatching } from "../util/walk-files.js";
+import { collectSourceSites } from "./evaluate-wiring.js";
+export const REGISTRATION_GRAPH_SCHEMA = 'sharkcraft.registration-graph/v1';
+function sortSites(sites) {
+    return [...sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.idiom.localeCompare(b.idiom));
+}
+/** Union (deduped) of every glob any role of any idiom references. */
+function registrationGlobs(idioms) {
+    return [
+        ...new Set(idioms.flatMap((i) => [...i.declared.files, ...i.provided.files, ...i.consumed.files])),
+    ];
+}
+/**
+ * Build the registration/DI graph from the declared idioms. For each idiom the
+ * three roles (declared / provided / consumed) are extracted with the shared
+ * alias-aware {@link collectSourceSites}, then bucketed by token across every
+ * idiom. Pure-engine output; the only IO is a single read-only tree walk over
+ * the union of all idiom globs. Never throws — a misconfigured source becomes a
+ * diagnostic.
+ */
+export function buildRegistrationGraph(projectRoot, idioms, options = {}) {
+    const cache = readMatchingFiles(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? []));
+    const entries = [...cache.entries()].map(([path, content]) => ({
+        path,
+        content,
+    }));
+    const filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files));
+    const declared = new Map();
+    const provided = new Map();
+    const consumed = new Map();
+    const diagnostics = [];
+    const harvest = (idiom, role, source, into) => {
+        const res = collectSourceSites(source, filesFor(source));
+        if (res.error)
+            diagnostics.push(`idiom "${idiom}" ${role}: ${res.error}`);
+        for (const s of res.sites) {
+            const list = into.get(s.token) ?? [];
+            list.push({ idiom, file: s.file, line: s.line });
+            into.set(s.token, list);
+        }
+    };
+    for (const idiom of idioms) {
+        harvest(idiom.name, 'declared', idiom.declared, declared);
+        harvest(idiom.name, 'provided', idiom.provided, provided);
+        harvest(idiom.name, 'consumed', idiom.consumed, consumed);
+    }
+    const tokenSet = new Set([...declared.keys(), ...provided.keys(), ...consumed.keys()]);
+    const tokens = [...tokenSet].sort().map((token) => ({
+        token,
+        declared: sortSites(declared.get(token) ?? []),
+        provided: sortSites(provided.get(token) ?? []),
+        consumed: sortSites(consumed.get(token) ?? []),
+    }));
+    return {
+        schema: REGISTRATION_GRAPH_SCHEMA,
+        idioms: idioms.map((i) => i.name),
+        tokens,
+        diagnostics,
+    };
+}
+/**
+ * A cheap content-signature of the exact files {@link buildRegistrationGraph}
+ * would read for these idioms: the sorted `relpath:mtimeMs:size` of every matched
+ * file, hashed. Because it reflects the graph's ACTUAL data source (a live tree
+ * walk) rather than the unrelated code-graph index, it is the correct key for any
+ * 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.
+ */
+export function registrationGraphSignature(projectRoot, idioms, options = {}) {
+    const files = walkMatching(projectRoot, registrationGlobs(idioms), new Set(options.excludeDirs ?? [])).sort();
+    const parts = [];
+    for (const rel of files) {
+        try {
+            const st = statSync(nodePath.join(projectRoot, rel));
+            parts.push(`${rel}:${st.mtimeMs}:${st.size}`);
+        }
+        catch {
+            // Unreadable / racing delete — omit; a real content change still shifts
+            // the hash via the surviving entries (and via this file's disappearance).
+        }
+    }
+    return createHash('sha1').update(parts.join('\n')).digest('hex').slice(0, 16);
+}
+/**
+ * `wiring chain <token>` — the declared → provided → consumed hops of one token
+ * with file:line at each, or `undefined` if the token is unknown to the graph.
+ */
+export function registrationChain(graph, token) {
+    const node = graph.tokens.find((t) => t.token === token);
+    if (!node)
+        return undefined;
+    return {
+        ...node,
+        isDeclared: node.declared.length > 0,
+        isProvided: node.provided.length > 0,
+        isConsumed: node.consumed.length > 0,
+    };
+}
+/**
+ * `wiring unprovided` — tokens that are DECLARED or CONSUMED but have ZERO
+ * provided sites. This is the silent-at-runtime class: typecheck/AOT-green, but
+ * the provider is never registered (or the injected token has no provider
+ * anywhere), so it resolves to undefined at runtime. The thing imports can't see.
+ */
+export function registrationUnprovided(graph) {
+    return graph.tokens
+        .filter((t) => t.provided.length === 0 && (t.declared.length > 0 || t.consumed.length > 0))
+        .map((t) => ({ token: t.token, declared: t.declared, consumed: t.consumed }));
+}
+/**
+ * `wiring orphans` — tokens that ARE provided/registered but have ZERO consumed
+ * sites: a provider/registration nothing injects (a build-clean no-op, or a
+ * sign the consumer was renamed/removed).
+ */
+export function registrationOrphans(graph) {
+    return graph.tokens
+        .filter((t) => t.provided.length > 0 && t.consumed.length === 0)
+        .map((t) => ({ token: t.token, provided: t.provided }));
+}

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

@@ -0,0 +1,40 @@
+import type { IRegistryDeclaration } from '@shrkcrft/core';
+export declare const REGISTRY_SCHEMA: "sharkcraft.registry-inventory/v1";
+/** Where an id was found (project-relative path + 1-based line). */
+export interface IRegistrySite {
+    readonly file: string;
+    readonly line: number;
+}
+/** One id in a registry: its declaration sites + (optional) consumer/binding sites. */
+export interface IRegistryEntry {
+    readonly id: string;
+    /** Declaration sites (from `source`), sorted by file then line. */
+    readonly sites: readonly IRegistrySite[];
+    /** Consumer/binding sites (from `consumer`), when the declaration sets one. */
+    readonly consumerSites?: readonly IRegistrySite[];
+}
+/** A scanned registry inventory: every distinct id and where it lives. */
+export interface IRegistryInventory {
+    readonly schema: typeof REGISTRY_SCHEMA;
+    readonly name: string;
+    readonly description?: string;
+    /** Distinct ids, sorted, each with its sites. */
+    readonly entries: readonly IRegistryEntry[];
+    /** Misconfiguration messages (bad regex / no capture group / bad source). */
+    readonly diagnostics: readonly string[];
+}
+export interface IScanRegistryOptions {
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+}
+/**
+ * Scan a declared registry, returning every distinct id and its declaration
+ * (and optional consumer) sites. Pure-engine output; the only IO is a single
+ * read-only tree walk over the union of the source/consumer globs.
+ */
+export declare function scanRegistry(projectRoot: string, decl: IRegistryDeclaration, options?: IScanRegistryOptions): IRegistryInventory;
+/** True if `id` is declared in the registry (alias-blind exact membership). */
+export declare function registryExists(inventory: IRegistryInventory, id: string): boolean;
+/** The entry for `id`, or undefined if not declared. */
+export declare function registryWhere(inventory: IRegistryInventory, id: string): IRegistryEntry | undefined;
+//# sourceMappingURL=registry-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry-query.d.ts","sourceRoot":"","sources":["../../src/wiring/registry-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK3D,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,CA+CpB;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"}

package/dist/wiring/registry-query.js

@@ -0,0 +1,65 @@
+import { matchesAny } from "../scan/glob.js";
+import { readMatchingFiles } from "../util/walk-files.js";
+import { collectSourceSites } from "./evaluate-wiring.js";
+export const REGISTRY_SCHEMA = 'sharkcraft.registry-inventory/v1';
+function sortSites(sites) {
+    return [...sites].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+/**
+ * Scan a declared registry, returning every distinct id and its declaration
+ * (and optional consumer) sites. Pure-engine output; the only IO is a single
+ * read-only tree walk over the union of the source/consumer globs.
+ */
+export function scanRegistry(projectRoot, decl, options = {}) {
+    const globs = [
+        ...new Set([...decl.source.files, ...(decl.consumer ? decl.consumer.files : [])]),
+    ];
+    const cache = readMatchingFiles(projectRoot, globs, new Set(options.excludeDirs ?? []));
+    const entries = [...cache.entries()].map(([path, content]) => ({ path, content }));
+    const diagnostics = [];
+    const sourceFiles = entries.filter((f) => matchesAny(f.path, decl.source.files));
+    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, decl.consumer.files));
+        const consumed = collectSourceSites(decl.consumer, consumerFiles);
+        if (consumed.error)
+            diagnostics.push(`registry "${decl.name}" consumer: ${consumed.error}`);
+        for (const s of consumed.sites) {
+            const list = consumerByToken.get(s.token) ?? [];
+            list.push({ file: s.file, line: s.line });
+            consumerByToken.set(s.token, list);
+        }
+    }
+    const declaredByToken = new Map();
+    for (const s of declared.sites) {
+        const list = declaredByToken.get(s.token) ?? [];
+        list.push({ file: s.file, line: s.line });
+        declaredByToken.set(s.token, list);
+    }
+    const entriesOut = [...declaredByToken.keys()].sort().map((id) => {
+        const consumerSites = consumerByToken.get(id);
+        return {
+            id,
+            sites: sortSites(declaredByToken.get(id) ?? []),
+            ...(consumerSites && consumerSites.length > 0 ? { consumerSites: sortSites(consumerSites) } : {}),
+        };
+    });
+    return {
+        schema: REGISTRY_SCHEMA,
+        name: decl.name,
+        ...(decl.description ? { description: decl.description } : {}),
+        entries: entriesOut,
+        diagnostics,
+    };
+}
+/** True if `id` is declared in the registry (alias-blind exact membership). */
+export function registryExists(inventory, id) {
+    return inventory.entries.some((e) => e.id === id);
+}
+/** The entry for `id`, or undefined if not declared. */
+export function registryWhere(inventory, id) {
+    return inventory.entries.find((e) => e.id === id);
+}

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,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,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,CAyBf"}
+{"version":3,"file":"scan-wiring-files.d.ts","sourceRoot":"","sources":["../../src/wiring/scan-wiring-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAW9B,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,CA8Bf"}

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

@@ -1,6 +1,14 @@
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
 import { evaluateWiring, } from "./evaluate-wiring.js";
+/** All file globs a rule references: its declared side + every registered source (union). */
+function ruleGlobs(rule) {
+    const reg = rule.registered;
+    const sources = Array.isArray(reg)
+        ? reg
+        : [reg];
+    return [...rule.declared.files, ...sources.flatMap((s) => [...s.files])];
+}
 /**
  * Filesystem-backed wiring run: walks the project once, reads only the files a
  * rule references (skipping oversized files), and evaluates every (selected)
@@ -15,17 +23,22 @@ export function runWiring(projectRoot, rules, options = {}) {
     if (options.changedOnly) {
         const changed = options.changedFiles ?? [];
         selected = selected.filter((r) => {
-            const globs = [...r.declared.files, ...r.registered.files];
+            const globs = ruleGlobs(r);
             return changed.some((c) => matchesAny(c, globs));
         });
     }
     if (selected.length === 0) {
-        return { schema: 'sharkcraft.wiring/v1', rules: [], violations: [], diagnostics: [], verdict: 'pass' };
+        return {
+            schema: 'sharkcraft.wiring/v1',
+            rules: [],
+            violations: [],
+            diagnostics: [],
+            evaluated: 0,
+            verdict: 'pass',
+        };
     }
     // Union of all globs across selected rules → one tree walk, cached reads.
-    const allGlobs = [
-        ...new Set(selected.flatMap((r) => [...r.declared.files, ...r.registered.files])),
-    ];
+    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 }));
     return evaluateWiring(selected, (source) => entries.filter((f) => matchesAny(f.path, source.files)));

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

@@ -0,0 +1,60 @@
+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[];
+/**
+ * How a literal occurrence relates to the cross-fence contract — the direction
+ * grep can't give you:
+ *  - `declare`  — a canonical definition (`const X = 'lit'`, `kind: 'lit'`, an enum value).
+ *  - `register` — added to a collection / mapping (`register('lit')`, an array element, `{ 'lit': … }`).
+ *  - `consume`  — compared / switched / handled (`=== 'lit'`, `case 'lit':`).
+ *  - `reference`— an occurrence we can't confidently classify (still reported, with context).
+ */
+export declare enum TraceRole {
+    Declare = "declare",
+    Register = "register",
+    Consume = "consume",
+    Reference = "reference"
+}
+/** One occurrence of the traced literal (or a const aliased to it). */
+export interface ITraceSite {
+    readonly file: string;
+    readonly line: number;
+    readonly role: TraceRole;
+    /** The trimmed source line, for context. */
+    readonly text: string;
+    /** Set when this site reached the literal through a `const NAME = 'literal'` alias. */
+    readonly viaAlias?: string;
+}
+export interface ITraceReport {
+    readonly schema: typeof TRACE_SCHEMA;
+    readonly literal: string;
+    readonly total: number;
+    /** Distinct files the literal (or an alias) was found in. */
+    readonly files: number;
+    /** Sites grouped by role, each group sorted by (file, line). */
+    readonly byRole: Readonly<Record<TraceRole, readonly ITraceSite[]>>;
+    /** Const names found bound to the literal (`const NAME = 'literal'`), if any. */
+    readonly aliases: readonly string[];
+}
+export interface ITraceOptions {
+    /** Override the default source globs. */
+    readonly globs?: readonly string[];
+    /** Project-relative directories to prune from the walk. */
+    readonly excludeDirs?: readonly string[];
+    /**
+     * Resolve `const NAME = 'literal'` bindings and also classify uses of NAME
+     * (flagged `viaAlias`). On by default — it is the cross-fence value over grep.
+     */
+    readonly resolveAliases?: boolean;
+}
+/**
+ * Trace every declare → register → consume site of an EXACT string literal
+ * across the tree, classifying each occurrence with a direction. Generalizes
+ * `registry where` to any cross-fence string contract (a kind slug, permission
+ * id, route key, data key) WITHOUT a pre-declared registry — point it at any
+ * literal and get the chain grep can't: direction + role + layer-spanning
+ * grouping, plus (by default) the const-alias bindings of the literal and their
+ * use-sites. Pure-engine; the only IO is one read-only tree walk. Never throws.
+ */
+export declare function traceLiteral(projectRoot: string, literal: string, options?: ITraceOptions): ITraceReport;
+//# sourceMappingURL=trace-literal.d.ts.map

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

@@ -0,0 +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;;;;;;;GAOG;AACH,oBAAY,SAAS;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,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;AAmED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAqFd"}

package/dist/wiring/trace-literal.js

@@ -0,0 +1,187 @@
+import { readMatchingFiles } from "../util/walk-files.js";
+export const TRACE_SCHEMA = 'sharkcraft.trace/v1';
+/** Default source globs scanned when `trace` is given no `--glob`. */
+export const TRACE_DEFAULT_GLOBS = [
+    '**/*.ts',
+    '**/*.tsx',
+    '**/*.mts',
+    '**/*.cts',
+    '**/*.js',
+    '**/*.jsx',
+    '**/*.mjs',
+    '**/*.cjs',
+];
+/**
+ * How a literal occurrence relates to the cross-fence contract — the direction
+ * grep can't give you:
+ *  - `declare`  — a canonical definition (`const X = 'lit'`, `kind: 'lit'`, an enum value).
+ *  - `register` — added to a collection / mapping (`register('lit')`, an array element, `{ 'lit': … }`).
+ *  - `consume`  — compared / switched / handled (`=== 'lit'`, `case 'lit':`).
+ *  - `reference`— an occurrence we can't confidently classify (still reported, with context).
+ */
+export var TraceRole;
+(function (TraceRole) {
+    TraceRole["Declare"] = "declare";
+    TraceRole["Register"] = "register";
+    TraceRole["Consume"] = "consume";
+    TraceRole["Reference"] = "reference";
+})(TraceRole || (TraceRole = {}));
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function lineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i += 1) {
+        if (content[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line for a character offset, given precomputed line-start offsets. */
+function lineAt(starts, offset) {
+    // Binary search for the greatest start <= offset.
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+function lineText(content, starts, line) {
+    const start = starts[line - 1] ?? 0;
+    const nl = content.indexOf('\n', start);
+    return content.slice(start, nl === -1 ? content.length : nl);
+}
+/**
+ * Heuristic declare-vs-register-vs-consume classifier from the text immediately
+ * around the occurrence. High-precision rules first; anything unmatched stays
+ * `reference` (reported, never silently dropped). Deterministic.
+ */
+function classifyRole(before, after) {
+    const b = before.replace(/\s+$/, '');
+    const a = after.replace(/^\s+/, '');
+    // switch/case handler.
+    if (/\bcase$/.test(b) && a.startsWith(':'))
+        return TraceRole.Consume;
+    // equality / inequality comparison on either side.
+    if (/(===|!==|==|!=)$/.test(b) || /^(===|!==|==|!=)/.test(a))
+        return TraceRole.Consume;
+    // object / map key mapping: `{ 'lit': … }` or `, 'lit': …`.
+    if (a.startsWith(':') && /[{,]$/.test(b))
+        return TraceRole.Register;
+    // registration-ish call: register('lit'), provide('lit'), on('lit'), .set('lit', …).
+    if (/\b(register|provide|add|use|on|handle|bind|emit|dispatch|listen|subscribe|define)\w*\($/i.test(b)) {
+        return TraceRole.Register;
+    }
+    if (/\.\s*set\($/.test(b))
+        return TraceRole.Register;
+    // array element: the literal directly follows `[` or `,`.
+    if (/[[,]$/.test(b))
+        return TraceRole.Register;
+    // canonical binding: const/let/var X = 'lit'.
+    if (/\b(?:const|let|var)\s+[\w$]+\s*=$/.test(b))
+        return TraceRole.Declare;
+    // definition-ish object property: `kind: 'lit'`, `id = 'lit'`, etc.
+    if (/\b(kind|type|id|name|slug|key|tag|code|token|permission|route|event|action|channel|topic|status|provide|providerToken)\s*[:=]$/i.test(b)) {
+        return TraceRole.Declare;
+    }
+    return TraceRole.Reference;
+}
+/** A const name is alias-resolvable only if Pascal/SCREAMING-cased (low collision risk). */
+const ALIAS_NAME = /^[A-Z][\w$]*$/;
+/**
+ * Trace every declare → register → consume site of an EXACT string literal
+ * across the tree, classifying each occurrence with a direction. Generalizes
+ * `registry where` to any cross-fence string contract (a kind slug, permission
+ * id, route key, data key) WITHOUT a pre-declared registry — point it at any
+ * literal and get the chain grep can't: direction + role + layer-spanning
+ * grouping, plus (by default) the const-alias bindings of the literal and their
+ * use-sites. Pure-engine; the only IO is one read-only tree walk. Never throws.
+ */
+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);
+    const sites = [];
+    const aliasNames = new Set();
+    // Exact quoted-literal match: the closing quote immediately follows, so the
+    // quoted CONTENT equals the literal (not a substring of a longer string).
+    const litRe = new RegExp(`(['"\`])${escapeRegex(literal)}\\1`, 'g');
+    for (const [file, content] of cache) {
+        const starts = lineStarts(content);
+        litRe.lastIndex = 0;
+        let m;
+        while ((m = litRe.exec(content)) !== null) {
+            if (m.index === litRe.lastIndex)
+                litRe.lastIndex += 1;
+            const line = lineAt(starts, m.index);
+            const text = lineText(content, starts, line);
+            const col = m.index - (starts[line - 1] ?? 0);
+            const before = text.slice(0, col);
+            const after = text.slice(col + m[0].length);
+            const role = classifyRole(before, after);
+            sites.push({ file, line, role, text: text.trim() });
+            // Capture a const alias bound to this literal for the second pass.
+            const bind = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=$/.exec(before.replace(/\s+$/, ''));
+            if (bind && ALIAS_NAME.test(bind[1]))
+                aliasNames.add(bind[1]);
+        }
+    }
+    // Second pass: classify uses of any const aliased to the literal.
+    const resolveAliases = options.resolveAliases !== false;
+    if (resolveAliases && aliasNames.size > 0) {
+        for (const name of aliasNames) {
+            // The lookbehind excludes `.` as well as word chars/`$`: a genuine use of
+            // the top-level const alias is never dot-prefixed, whereas `Enum.NAME` /
+            // `obj.NAME` is a member/enum accessor that merely shares the alias's name
+            // and must NOT be counted as a use of the traced literal (over-match).
+            const useRe = new RegExp(`(?<![\\w$.])${escapeRegex(name)}(?![\\w$])`, 'g');
+            for (const [file, content] of cache) {
+                const starts = lineStarts(content);
+                useRe.lastIndex = 0;
+                let m;
+                while ((m = useRe.exec(content)) !== null) {
+                    const line = lineAt(starts, m.index);
+                    const text = lineText(content, starts, line);
+                    const col = m.index - (starts[line - 1] ?? 0);
+                    const before = text.slice(0, col);
+                    const after = text.slice(col + name.length);
+                    // Skip ONLY the binding occurrence itself (`const NAME = …`) — it's
+                    // already counted as a literal Declare site. Keying on the exact
+                    // `const NAME` position (not the whole line) means a genuine alias use
+                    // that merely SHARES a line with some literal is still reported.
+                    if (/\b(?:const|let|var)\s+$/.test(before))
+                        continue;
+                    const role = classifyRole(before, after);
+                    sites.push({ file, line, role, text: text.trim(), viaAlias: name });
+                }
+            }
+        }
+    }
+    const sortSites = (xs) => [...xs].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    const byRole = {
+        [TraceRole.Declare]: [],
+        [TraceRole.Register]: [],
+        [TraceRole.Consume]: [],
+        [TraceRole.Reference]: [],
+    };
+    for (const s of sites)
+        byRole[s.role].push(s);
+    return {
+        schema: TRACE_SCHEMA,
+        literal,
+        total: sites.length,
+        files: new Set(sites.map((s) => s.file)).size,
+        byRole: {
+            [TraceRole.Declare]: sortSites(byRole[TraceRole.Declare]),
+            [TraceRole.Register]: sortSites(byRole[TraceRole.Register]),
+            [TraceRole.Consume]: sortSites(byRole[TraceRole.Consume]),
+            [TraceRole.Reference]: sortSites(byRole[TraceRole.Reference]),
+        },
+        aliases: [...aliasNames].sort(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/boundaries",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "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.22"
+    "@shrkcrft/core": "^0.1.0-alpha.24"
   },
   "publishConfig": {
     "access": "public"