@shrkcrft/boundaries 0.1.0-alpha.27 → 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/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/package.json

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