@shrkcrft/boundaries 0.1.0-alpha.26 → 0.1.0-alpha.28

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

@@ -1,20 +1,20 @@
-import type { IWiringRule, IWiringSource } from '@shrkcrft/core';
+import { type IWiringRule, type IWiringSource } from '@shrkcrft/core';
+import { type IExtractFileEntry, type IExtractedSite } from '../extract/extract-tokens.js';
 export declare const WIRING_SCHEMA: "sharkcraft.wiring/v1";
 /** A file made available to the engine. */
-export interface IWiringFileEntry {
-    /** Project-relative POSIX path. */
-    readonly path: string;
-    readonly content: string;
-}
+export type IWiringFileEntry = IExtractFileEntry;
 /** A captured token + where it was captured. */
-export interface IWiringTokenSite {
-    readonly token: string;
-    readonly file: string;
-    readonly line: number;
-}
+export type IWiringTokenSite = IExtractedSite;
+/**
+ * Per-rule outcome. `skipped` is deliberately DISTINCT from `passed`: a rule
+ * whose source side extracted nothing checked nothing, and reporting that as a
+ * pass is the single failure mode that lets a stale selector ship a real
+ * violation. See {@link IWiringSkip}.
+ */
+export type WiringRuleStatus = 'passed' | 'failed' | 'skipped' | 'error';
 export interface IWiringViolation {
     readonly ruleId: string;
-    /** The token that is missing from the other side. */
+    /** The token that is missing from (or wrongly shared with) the other side. */
     readonly token: string;
     /** Declaring (or registering) file (project-relative) + 1-based line. */
     readonly file: string;
@@ -23,20 +23,53 @@ export interface IWiringViolation {
     /**
      * Which side the token is missing from. `declared-missing` (the subset case):
      * declared but not registered. `registered-missing` (parity only): registered
-     * but never declared.
+     * but never declared. `overlap` (disjoint only): present on both sides.
      */
-    readonly direction?: 'declared-missing' | 'registered-missing';
+    readonly direction?: 'declared-missing' | 'registered-missing' | 'overlap';
+    /** For a `chain` rule: which hop pair failed (0-based). */
+    readonly hop?: number;
+    /** Rendered `message` template, when the rule sets one. */
+    readonly message?: string;
     readonly hint?: string;
 }
+/** A rule that could not be evaluated because its source side matched nothing. */
+export interface IWiringSkip {
+    readonly ruleId: string;
+    /** Human-readable cause (`0 files matched` / `0 ids extracted`). */
+    readonly reason: string;
+    /** True when the rule set `failOnEmpty` — the skip counts as a failure. */
+    readonly failed: boolean;
+    readonly severity: 'error' | 'warning';
+}
+/** One `hop_i ⊆ hop_i+1` step of a multi-hop chain rule. */
+export interface IWiringHopResult {
+    readonly index: number;
+    readonly fromCount: number;
+    readonly toCount: number;
+    readonly missing: number;
+}
 export interface IWiringRuleResult {
     readonly ruleId: string;
     readonly description?: string;
     readonly severity: 'error' | 'warning';
+    readonly status: WiringRuleStatus;
     readonly declaredCount: number;
     readonly registeredCount: number;
+    /** Files actually scanned per side (after glob resolution) — the stale-glob signal. */
+    readonly declaredFiles: number;
+    readonly registeredFiles: number;
     readonly violations: readonly IWiringViolation[];
     /** Set when the rule is misconfigured (bad regex / no capture group / bad source). */
     readonly error?: string;
+    /**
+     * True when the SINK extracted 0 ids while the source extracted some. Every
+     * declared token then "fails", which is a real failure — but almost always
+     * because the sink glob went stale, so the diff is annotated rather than
+     * silently reported as N unrelated violations.
+     */
+    readonly emptySink?: boolean;
+    /** Per-hop breakdown for a `chain` rule. */
+    readonly hops?: readonly IWiringHopResult[];
 }
 export interface IWiringReport {
     readonly schema: typeof WIRING_SCHEMA;
@@ -44,34 +77,54 @@ export interface IWiringReport {
     readonly violations: readonly IWiringViolation[];
     /** Rule-level misconfiguration messages (never throws — degrades gracefully). */
     readonly diagnostics: readonly string[];
+    /** Rules that checked nothing, reported loudly instead of as a green pass. */
+    readonly skipped: readonly IWiringSkip[];
     /**
-     * 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.
+     * Count of rules that actually ran a comparison. A rule whose source side
+     * matched 0 files or extracted 0 ids is NOT evaluated (see {@link 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[];
+/** Normalize the `registered` field (single source or union array) to an array. */
+export declare function registeredSources(reg: IWiringRule['registered']): readonly IWiringSource[];
+/**
+ * The rule's SOURCE side — the set whose membership is being asserted. For a
+ * chain rule that is hop 0. Used for glob collection, the loud-skip test, and
+ * `selfTest` expectations.
+ */
+export declare function wiringSourceSide(rule: IWiringRule): IWiringSource | undefined;
+/** Every source a rule references, in declaration order. */
+export declare function wiringSourcesOf(rule: IWiringRule): readonly IWiringSource[];
+/** Every glob a rule references (both sides / every hop). */
+export declare function wiringGlobsOf(rule: IWiringRule): string[];
 /**
- * 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).
+ * Public: extract every token site from ONE wiring source over the given files.
+ * Shared by the wiring evaluator, the registry-inventory engine, and the
+ * extractor-backed baseline compute, so all three honour identical 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;
 };
+/** Structural validation of a whole rule (both forms), independent of the tree. */
+export declare function validateWiringRule(rule: IWiringRule): string | undefined;
 /**
- * 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.
+ * Pure wiring evaluation.
+ *
+ * For each rule the SOURCE token set is compared against the SINK sets per
+ * `mode` (`subset` / `parity` / `disjoint`) and `registeredMode` (`union` /
+ * `intersection`). A `chain` rule runs the same comparison across each adjacent
+ * hop pair. With `groupBy`, membership is checked within the same dir/package.
+ *
+ * Three outcomes are kept distinct, because collapsing them is what makes a
+ * homegrown gate untrustworthy: a rule that PASSED, a rule that FAILED, and a
+ * rule that checked NOTHING (`skipped`, promoted to a failure by `failOnEmpty`).
+ *
  * 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).
  */

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,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"}
+{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"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"}

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

@@ -1,5 +1,5 @@
 import type { IWiringRule } from '@shrkcrft/core';
-import { type IWiringTokenSite } from './evaluate-wiring.js';
+import { type IWiringHopResult, 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 {
@@ -22,7 +22,8 @@ export interface IWiringExplain {
     readonly schema: typeof WIRING_EXPLAIN_SCHEMA;
     readonly ruleId: string;
     readonly description?: string;
-    readonly mode: 'subset' | 'parity';
+    readonly mode: 'subset' | 'parity' | 'disjoint';
+    readonly registeredMode: 'union' | 'intersection';
     readonly groupBy?: 'dir' | 'package';
     readonly severity: 'error' | 'warning';
     readonly declared: IWiringSideExplain;
@@ -31,6 +32,14 @@ export interface IWiringExplain {
     readonly declaredNotRegistered: readonly IWiringTokenSite[];
     /** Registered tokens absent from the declared set (parity-only `registered-missing`). */
     readonly registeredNotDeclared: readonly IWiringTokenSite[];
+    /** Tokens present on BOTH sides (disjoint-only `overlap`). */
+    readonly overlap: readonly IWiringTokenSite[];
+    /** Per-hop breakdown when the rule is a multi-hop `chain`. */
+    readonly hops?: readonly IWiringHopResult[];
+    /** `passed` / `failed` / `skipped` / `error` — skipped is never a pass. */
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    /** Why the rule checked nothing, when it was skipped. */
+    readonly skipReason?: string;
     readonly verdict: 'pass' | 'errors' | 'warnings';
     /** Rule-level misconfiguration messages (engine degrades gracefully). */
     readonly diagnostics: readonly string[];
@@ -43,11 +52,10 @@ export interface IExplainWiringOptions {
  * 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.
+ * <candidate>`, `gates explain <id>`, and `check wiring --explain <ruleId>`: the
+ * author can SEE the 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). 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

@@ -1 +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"}
+{"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,EAOL,KAAK,gBAAgB,EACrB,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,GAAG,UAAU,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,cAAc,CAAC;IAClD,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,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,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;AAQD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAyEhB"}

package/dist/wiring/explain-wiring.js

@@ -1,10 +1,7 @@
 import { matchesAny } from "../scan/glob.js";
 import { readMatchingFiles } from "../util/walk-files.js";
-import { collectSourceSites, evaluateWiring, } from "./evaluate-wiring.js";
+import { collectSourceSites, evaluateWiring, registeredSources, wiringGlobsOf, wiringSourceSide, } 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));
 }
@@ -12,31 +9,32 @@ function sortSites(sites) {
  * 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.
+ * <candidate>`, `gates explain <id>`, and `check wiring --explain <ruleId>`: the
+ * author can SEE the 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). 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 sourceSide = wiringSourceSide(rule);
+    // For a chain, the reported "registered" side is the LAST hop (the far end).
+    const sinkSources = rule.chain && rule.chain.length >= 2
+        ? [rule.chain[rule.chain.length - 1]]
+        : registeredSources(rule.registered);
+    const allGlobs = [...new Set(wiringGlobsOf(rule))];
     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 filesFor = (source) => entries.filter((f) => matchesAny(f.path, source.files ?? []));
+    const declaredFiles = sourceSide ? filesFor(sourceSide) : [];
+    const declaredRes = sourceSide
+        ? collectSourceSites(sourceSide, declaredFiles)
+        : { sites: [], error: 'rule sets no source side' };
     const registeredFiles = new Set();
     const registeredSites = [];
     let registeredError;
-    for (const source of regSources) {
+    for (const source of sinkSources) {
         const files = filesFor(source);
         for (const f of files)
             registeredFiles.add(f.path);
@@ -48,17 +46,16 @@ export function explainWiring(projectRoot, rule, options = {}) {
     // 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')
+    const byDirection = (d) => sortSites((ruleResult?.violations ?? [])
+        .filter((v) => v.direction === d)
         .map((v) => ({ token: v.token, file: v.file, line: v.line })));
+    const skip = report.skipped[0];
     return {
         schema: WIRING_EXPLAIN_SCHEMA,
         ruleId: rule.id,
         ...(rule.description ? { description: rule.description } : {}),
-        mode: rule.mode === 'parity' ? 'parity' : 'subset',
+        mode: rule.mode ?? 'subset',
+        registeredMode: rule.registeredMode ?? 'union',
         ...(rule.groupBy ? { groupBy: rule.groupBy } : {}),
         severity: rule.severity ?? 'error',
         declared: {
@@ -73,8 +70,12 @@ export function explainWiring(projectRoot, rule, options = {}) {
             filesScanned: registeredFiles.size,
             ...(registeredError ? { error: registeredError } : {}),
         },
-        declaredNotRegistered,
-        registeredNotDeclared,
+        declaredNotRegistered: byDirection('declared-missing'),
+        registeredNotDeclared: byDirection('registered-missing'),
+        overlap: byDirection('overlap'),
+        ...(ruleResult?.hops ? { hops: ruleResult.hops } : {}),
+        status: ruleResult?.status ?? 'error',
+        ...(skip ? { skipReason: skip.reason } : {}),
         verdict: report.verdict,
         diagnostics: report.diagnostics,
     };

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

@@ -1,4 +1,5 @@
 import type { IRegistrationIdiom } from '@shrkcrft/core';
+import { type IWiringFileEntry } from './evaluate-wiring.js';
 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 {
@@ -54,6 +55,14 @@ export declare function buildRegistrationGraph(projectRoot: string, idioms: read
  * 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;
+/**
+ * The set of tokens the given file entries PROVIDE under any idiom. Used to diff
+ * a base-ref snapshot against the worktree: a REMOVED provider leaves NO site in
+ * the changed file (so post-change site-scoping can't see it), but the base
+ * content still shows the token was provided there — so a provider deletion
+ * (the most common way DI wiring silently breaks) stays change-attributable.
+ */
+export declare function providedTokensFromEntries(idioms: readonly IRegistrationIdiom[], entries: readonly IWiringFileEntry[]): Set<string>;
 /** A token's full registration chain, with role presence flags. */
 export interface IRegistrationChain extends IRegistrationNode {
     readonly isDeclared: boolean;
@@ -71,13 +80,26 @@ export interface IUnprovidedToken {
     readonly declared: readonly IRegistrationSite[];
     readonly consumed: readonly IRegistrationSite[];
 }
+/**
+ * Does the changed-file set touch ANY role-site of ANY token in the graph? Lets
+ * a changed-only gate tell "evaluated the registration scope, found it clean"
+ * (a real pass) apart from "the change touched no wiring at all" (nothing to
+ * verify → the caller should skip, never paint green). An empty `changedFiles`
+ * is vacuously false.
+ */
+export declare function registrationTouchesChanged(graph: IRegistrationGraph, changedFiles: readonly string[]): boolean;
 /**
  * `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.
+ *
+ * When `changedFiles` is supplied the result is CHANGESET-SCOPED: a token is
+ * kept only if one of its declared/consumed sites is in the changed set — i.e.
+ * "did THIS change leave a token unprovided", the change-attributed question a
+ * `wiring unprovided --changed-only` gate needs.
  */
-export declare function registrationUnprovided(graph: IRegistrationGraph): readonly IUnprovidedToken[];
+export declare function registrationUnprovided(graph: IRegistrationGraph, changedFiles?: readonly string[]): readonly IUnprovidedToken[];
 /** A token provided/registered that nothing consumes — a dead registration. */
 export interface IOrphanRegistration {
     readonly token: string;
@@ -87,6 +109,9 @@ export interface IOrphanRegistration {
  * `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).
+ *
+ * `changedFiles`, when supplied, scopes the result to orphans whose provided
+ * site is in the changed set (the registration THIS change added/touched).
  */
-export declare function registrationOrphans(graph: IRegistrationGraph): readonly IOrphanRegistration[];
+export declare function registrationOrphans(graph: IRegistrationGraph, changedFiles?: readonly string[]): readonly IOrphanRegistration[];
 //# sourceMappingURL=registration-graph.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"registration-graph.d.ts","sourceRoot":"","sources":["../../src/wiring/registration-graph.ts"],"names":[],"mappings":"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"}

package/dist/wiring/registration-graph.js

@@ -86,6 +86,22 @@ export function registrationGraphSignature(projectRoot, idioms, options = {}) {
     }
     return createHash('sha1').update(parts.join('\n')).digest('hex').slice(0, 16);
 }
+/**
+ * The set of tokens the given file entries PROVIDE under any idiom. Used to diff
+ * a base-ref snapshot against the worktree: a REMOVED provider leaves NO site in
+ * the changed file (so post-change site-scoping can't see it), but the base
+ * content still shows the token was provided there — so a provider deletion
+ * (the most common way DI wiring silently breaks) stays change-attributable.
+ */
+export function providedTokensFromEntries(idioms, entries) {
+    const tokens = new Set();
+    for (const idiom of idioms) {
+        const files = entries.filter((f) => matchesAny(f.path, idiom.provided.files));
+        for (const s of collectSourceSites(idiom.provided, files).sites)
+            tokens.add(s.token);
+    }
+    return tokens;
+}
 /**
  * `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.
@@ -101,24 +117,57 @@ export function registrationChain(graph, token) {
         isConsumed: node.consumed.length > 0,
     };
 }
+/** Project-relative path normalizer so site files and git changed-files compare. */
+function normalizeRel(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** True when ANY of `sites` falls in the changed-file scope. */
+function anySiteInScope(sites, scope) {
+    return sites.some((s) => scope.has(normalizeRel(s.file)));
+}
+/**
+ * Does the changed-file set touch ANY role-site of ANY token in the graph? Lets
+ * a changed-only gate tell "evaluated the registration scope, found it clean"
+ * (a real pass) apart from "the change touched no wiring at all" (nothing to
+ * verify → the caller should skip, never paint green). An empty `changedFiles`
+ * is vacuously false.
+ */
+export function registrationTouchesChanged(graph, changedFiles) {
+    if (changedFiles.length === 0)
+        return false;
+    const scope = new Set(changedFiles.map(normalizeRel));
+    return graph.tokens.some((t) => anySiteInScope([...t.declared, ...t.provided, ...t.consumed], scope));
+}
 /**
  * `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.
+ *
+ * When `changedFiles` is supplied the result is CHANGESET-SCOPED: a token is
+ * kept only if one of its declared/consumed sites is in the changed set — i.e.
+ * "did THIS change leave a token unprovided", the change-attributed question a
+ * `wiring unprovided --changed-only` gate needs.
  */
-export function registrationUnprovided(graph) {
+export function registrationUnprovided(graph, changedFiles) {
+    const scope = changedFiles ? new Set(changedFiles.map(normalizeRel)) : undefined;
     return graph.tokens
         .filter((t) => t.provided.length === 0 && (t.declared.length > 0 || t.consumed.length > 0))
+        .filter((t) => !scope || anySiteInScope([...t.declared, ...t.consumed], scope))
         .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).
+ *
+ * `changedFiles`, when supplied, scopes the result to orphans whose provided
+ * site is in the changed set (the registration THIS change added/touched).
  */
-export function registrationOrphans(graph) {
+export function registrationOrphans(graph, changedFiles) {
+    const scope = changedFiles ? new Set(changedFiles.map(normalizeRel)) : undefined;
     return graph.tokens
         .filter((t) => t.provided.length > 0 && t.consumed.length === 0)
+        .filter((t) => !scope || anySiteInScope(t.provided, scope))
         .map((t) => ({ token: t.token, provided: t.provided }));
 }

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

@@ -37,4 +37,13 @@ export declare function scanRegistry(projectRoot: string, decl: IRegistryDeclara
 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;
+/**
+ * Ids declared in more than one place.
+ *
+ * A latent bug the compiler cannot see: two roots both claiming the same
+ * registry id compile fine, and whichever registration wins at runtime is an
+ * accident of load order. Reported with EVERY site so the duplicate can be
+ * resolved, not just detected.
+ */
+export declare function registryDuplicates(inventory: IRegistryInventory): readonly IRegistryEntry[];
 //# sourceMappingURL=registry-query.d.ts.map

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,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"}
+{"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;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,cAAc,EAAE,CAE3F"}

package/dist/wiring/registry-query.js

@@ -63,3 +63,14 @@ export function registryExists(inventory, id) {
 export function registryWhere(inventory, id) {
     return inventory.entries.find((e) => e.id === id);
 }
+/**
+ * Ids declared in more than one place.
+ *
+ * A latent bug the compiler cannot see: two roots both claiming the same
+ * registry id compile fine, and whichever registration wins at runtime is an
+ * accident of load order. Reported with EVERY site so the duplicate can be
+ * resolved, not just detected.
+ */
+export function registryDuplicates(inventory) {
+    return inventory.entries.filter((e) => e.sites.length > 1);
+}

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,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"}
+{"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,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,CA+Bf"}

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

@@ -1,13 +1,9 @@
 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). */
+import { evaluateWiring, wiringGlobsOf, } from "./evaluate-wiring.js";
+/** All file globs a rule references: every side / every hop. */
 function ruleGlobs(rule) {
-    const reg = rule.registered;
-    const sources = Array.isArray(reg)
-        ? reg
-        : [reg];
-    return [...rule.declared.files, ...sources.flatMap((s) => [...s.files])];
+    return wiringGlobsOf(rule);
 }
 /**
  * Filesystem-backed wiring run: walks the project once, reads only the files a
@@ -33,6 +29,7 @@ export function runWiring(projectRoot, rules, options = {}) {
             rules: [],
             violations: [],
             diagnostics: [],
+            skipped: [],
             evaluated: 0,
             verdict: 'pass',
         };

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

@@ -7,12 +7,18 @@ export declare const TRACE_DEFAULT_GLOBS: readonly string[];
  *  - `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':`).
+ *  - `render`   — rendered / emitted at the boundary (JSX child `>{ 'lit' }`, template
+ *                 interpolation `${ 'lit' }`, a `render('lit')` / `res.send('lit')` call).
  *  - `reference`— an occurrence we can't confidently classify (still reported, with context).
+ *
+ * `render` only ever refines what would otherwise be a `reference`; it never
+ * steals a site from `declare` / `register` / `consume`.
  */
 export declare enum TraceRole {
     Declare = "declare",
     Register = "register",
     Consume = "consume",
+    Render = "render",
     Reference = "reference"
 }
 /** One occurrence of the traced literal (or a const aliased to it). */

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;;;;;;;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"}
+{"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"}