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

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

@@ -1,5 +1,7 @@
-import { type IWiringRule, type IWiringSource } from '@shrkcrft/core';
-import { type IExtractFileEntry, type IExtractedSite } from '../extract/extract-tokens.js';
+import { type ISettledUnitLiveness, type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage, type IWiringRule, type IWiringSource } from '@shrkcrft/core';
+import { type IExtractContext, type IExtractFileEntry, type IExtractedSite } from '../extract/extract-tokens.js';
+import type { IUnreadFile } from '../util/unread-file.js';
+import type { IGlobNegation } from '../util/i-glob-negation.js';
 export declare const WIRING_SCHEMA: "sharkcraft.wiring/v1";
 /** A file made available to the engine. */
 export type IWiringFileEntry = IExtractFileEntry;
@@ -68,8 +70,52 @@ export interface IWiringRuleResult {
      * silently reported as N unrelated violations.
      */
     readonly emptySink?: boolean;
+    /**
+     * A diagnosis for a side that extracted nothing for a knowable reason — e.g.
+     * an `import-edges` sink targeting `to.files` against barrel imports. Carried
+     * so the empty-sink message can explain itself instead of sending the reader
+     * to check a glob that is fine.
+     */
+    readonly sinkHint?: string;
     /** Per-hop breakdown for a `chain` rule. */
     readonly hops?: readonly IWiringHopResult[];
+    /**
+     * Registered sites whose membership key the declared side never produced —
+     * ONE derivation, two renderings. `parity` reports each as a
+     * `registered-missing` violation; `subset` (the default) reports them here,
+     * because a `declared ⊆ registered` rule never examined them: the declared
+     * selector may be narrower than reality, and the rule would pass by
+     * construction. Set for a classic (non-chain) subset/parity rule that ran,
+     * sorted by membership key. `explainWiring` reads this rather than
+     * recomputing it.
+     */
+    readonly registeredOnly?: readonly IWiringTokenSite[];
+    /**
+     * What the rule examined against what it was asked to (see
+     * `IVerdictCoverage`). A subset rule whose registered side holds tokens the
+     * declared selector never produced reports them as unexamined `registered
+     * tokens`, so the gate envelope marks it `partial` and the verdict is not
+     * verified — unless the rule's `registeredExtras` accepts them explicitly.
+     * The engine fills it in; it never decides a verdict from it.
+     */
+    readonly coverage: IVerdictCoverage;
+    /**
+     * Glob-matched files on any side of the rule that the one reader did not
+     * read (over the read cap, or unreadable). Set only when non-empty.
+     * `coverage` names them too: such a rule is never a pass.
+     */
+    readonly unread?: readonly IUnreadFile[];
+    /**
+     * The acceptance of the rule's `expectEmpty` units — settle record B of
+     * every source's glob lists (round 13). Folded into the envelope's ONE
+     * settle beside {@link coverage}; when the rule is intended-empty it IS
+     * {@link coverage}.
+     */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live glob units as printed lines (`unitStateLists`). */
+    readonly units?: IUnitStateLists;
+    /** The rule's non-live glob units, for `--fail-on-dead-units` (`selectorUnitFails`). */
+    readonly unitLiveness?: readonly IUnitLiveness[];
 }
 export interface IWiringReport {
     readonly schema: typeof WIRING_SCHEMA;
@@ -80,11 +126,22 @@ export interface IWiringReport {
     /** 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 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.
+     * Count of rules that settled a verdict: ran a comparison, or were
+     * misconfigured (counted so their error is not swallowed), or were ACCEPTED
+     * as intended-empty (round 13 — every source inclusion glob marked
+     * `expectEmpty`, 0 files matched; counted so the verdict path's
+     * `evaluated === 0` NOT-VERIFIED guard never reads an accepted plan as
+     * "nothing ran"). A rule whose source side matched 0 files or extracted 0 ids
+     * WITHOUT that acceptance is NOT evaluated (see {@link skipped}). The printed
+     * "N evaluated" excludes the accepted ones: N = `evaluated − acceptedEmpty`.
      */
     readonly evaluated: number;
+    /**
+     * Rules accepted as intended-empty (round 13, K6): they examined 0 files, so
+     * a renderer prints them apart — `N evaluated, M accepted as
+     * intended-empty` — never inside the evaluated count.
+     */
+    readonly acceptedEmpty: number;
     readonly verdict: 'pass' | 'errors' | 'warnings';
 }
 /** Resolves a rule-side's globs to the concrete files (path + content) to scan. */
@@ -107,9 +164,10 @@ export declare function wiringGlobsOf(rule: IWiringRule): string[];
  * 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[]): {
+export declare function collectSourceSites(source: IWiringSource, files: readonly IWiringFileEntry[], context?: IExtractContext): {
     sites: readonly IWiringTokenSite[];
     error?: string;
+    blankedChars?: number;
 };
 /** Structural validation of a whole rule (both forms), independent of the tree. */
 export declare function validateWiringRule(rule: IWiringRule): string | undefined;
@@ -127,6 +185,29 @@ export declare function validateWiringRule(rule: IWiringRule): string | undefine
  *
  * 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).
+ *
+ * `unreadFor` supplies the files a side's globs matched that the one reader
+ * did NOT read. A rule with any in its scope has its coverage replaced by the
+ * file record (`readScopeCoverage`), so it is never a pass. When the unread
+ * file is on the source side and is why the rule compared nothing, the rule is
+ * PARTIAL rather than a (failOnEmpty) skip: it matched a file it could not read.
+ *
+ * `emptiedBy` names the negations that excluded EVERY file a source's
+ * inclusion globs matched (`undefined` when the list was not emptied that
+ * way). A source side emptied by its own `!` entries is skipped with THE
+ * negation-aware reason (`matched nothing after its own negations: …`), never
+ * "0 files matched the source globs" — a file matched, then was excluded.
+ */
+export declare function evaluateWiring(rules: readonly IWiringRule[], resolve: WiringFileResolver, context?: IExtractContext, unreadFor?: (source: IWiringSource) => readonly IUnreadFile[], emptiedBy?: (source: IWiringSource) => readonly IGlobNegation[] | undefined, 
+/**
+ * Every source's glob units settled with their `expectEmpty` markers
+ * (round 13) — `runWiring` supplies it (`sourceLivenessRequest` over the
+ * engine's side labels, `settleGlobLists`). A rule whose source side matched
+ * nothing is decided from it by THE rule-emptiness settle
+ * (`settleRuleEmptiness`): every inclusion glob of the source side
+ * intended-empty and no file matched → accepted, never a skip. Its
+ * acceptance and non-live units ride on the rule result. Absent: no unit is
+ * marked, so an empty rule is a loud skip exactly as before.
  */
-export declare function evaluateWiring(rules: readonly IWiringRule[], resolve: WiringFileResolver): IWiringReport;
+ruleLivenessOf?: (rule: IWiringRule) => ISettledUnitLiveness): 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":"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"}
+{"version":3,"file":"evaluate-wiring.d.ts","sourceRoot":"","sources":["../../src/wiring/evaluate-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAEjD,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,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,GAAG,SAAS,CAAC;IAC3E,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CACxC;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;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,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uFAAuF;IACvF,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;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAClD;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,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,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;AAExF,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,SAAS,aAAa,EAAE,CAG1F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAG7E;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,aAAa,EAAE,CAM3E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAEzD;AAmBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,OAAO,GAAE,eAAoB,GAC5B;IAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAO/E;AAwHD,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CA+BxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,eAAoB,EAC7B,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS,WAAW,EAAE,EAC7D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS,aAAa,EAAE,GAAG,SAAS;AAC3E;;;;;;;;;GASG;AACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,oBAAoB,GAC3D,aAAa,CA0Wf"}

package/dist/wiring/evaluate-wiring.js

@@ -1,5 +1,8 @@
-import { failsWhenEmpty, validateWiringSource, } from '@shrkcrft/core';
+import { failsWhenEmpty, normalizeWiringRule, RuleEmptiness, settleRuleEmptiness, unitStateLists, UnitLivenessState, validateWiringSource, } from '@shrkcrft/core';
+import { settleGlobLists } from "../util/settle-glob-lists.js";
 import { extractTokens, } from "../extract/extract-tokens.js";
+import { describeUnread, mergeReadScopes, readScopeCoverage, readScopeHasUnread, } from "../util/read-scope-coverage.js";
+import { emptiedByNegationsReason } from "../util/negation-cause.js";
 export const WIRING_SCHEMA = 'sharkcraft.wiring/v1';
 /** Normalize the `registered` field (single source or union array) to an array. */
 export function registeredSources(reg) {
@@ -54,9 +57,14 @@ function hopPairs(rule) {
  * extractor-backed baseline compute, so all three honour identical semantics. A
  * misconfigured source returns an `error` and no sites (never throws).
  */
-export function collectSourceSites(source, files) {
-    const res = extractTokens(source, files);
-    return res.error ? { sites: [], error: res.error } : { sites: res.sites };
+export function collectSourceSites(source, files, context = {}) {
+    const res = extractTokens(source, files, context);
+    if (res.error)
+        return { sites: [], error: res.error };
+    return {
+        sites: res.sites,
+        ...(res.blankedChars !== undefined ? { blankedChars: res.blankedChars } : {}),
+    };
 }
 /** Group key for a token site under `groupBy` (dir = dirname; package = first two segments). */
 function groupKeyOf(path, groupBy) {
@@ -88,6 +96,67 @@ function renderMessage(template, rule, site) {
         .replace(/\{line\}/g, String(site.line))
         .replace(/\{rule\}/g, rule.id);
 }
+/**
+ * Registered sites whose membership key the declared side never produced,
+ * sorted by key. The ONE derivation behind both parity's `registered-missing`
+ * violations and a subset rule's coverage shortfall — two renderings of one set
+ * difference, so they cannot disagree.
+ */
+function registeredNotDeclared(fromKeys, unionKeys) {
+    return [...unionKeys.keys()]
+        .sort()
+        .filter((k) => !fromKeys.has(k))
+        .map((k) => unionKeys.get(k));
+}
+/** At most this many unexamined labels ride on one coverage record. */
+const COVERAGE_LABEL_CAP = 20;
+/**
+ * What one wiring rule examined, for the verdict's coverage guard.
+ *
+ * Only a classic SUBSET rule can pass over a scope it never examined: its
+ * relation is `declared ⊆ registered`, so a registered member the declared
+ * selector never produced is never looked at, and the rule weakens silently
+ * every time the tree grows past the selector. For it the unit is `registered
+ * tokens`; `registeredExtras` (literal ids, or `'allow'`) accepts known extras
+ * explicitly. Every other shape examines each declared token it extracted, so
+ * its unit is `declared tokens`. A skipped or misconfigured rule examined
+ * nothing.
+ */
+function wiringCoverage(rule, outcome) {
+    if (outcome.kind === 'error') {
+        return { unit: 'declared tokens', expected: 0, examined: 0, reason: 'the rule is misconfigured' };
+    }
+    if (outcome.kind === 'skipped') {
+        return { unit: 'declared tokens', expected: 0, examined: 0, reason: outcome.reason };
+    }
+    const only = outcome.registeredOnly;
+    const subset = rule.mode === undefined || rule.mode === 'subset';
+    if (only === undefined || !subset || outcome.registeredCount === 0) {
+        return { unit: 'declared tokens', expected: outcome.declaredCount, examined: outcome.declaredCount };
+    }
+    const extras = rule.registeredExtras;
+    const listed = new Set(extras === 'allow' ? [] : (extras ?? []));
+    const accepted = new Set(only.filter((s) => extras === 'allow' || listed.has(s.token)));
+    const unaccepted = only.filter((s) => !accepted.has(s));
+    const named = unaccepted.length > 0 ? unaccepted : [...accepted];
+    return {
+        unit: 'registered tokens',
+        expected: outcome.registeredCount,
+        examined: outcome.registeredCount - only.length,
+        ...(named.length > 0
+            ? {
+                unexamined: named.slice(0, COVERAGE_LABEL_CAP).map((s) => s.token),
+                unexaminedTotal: named.length,
+                reason: unaccepted.length > 0 && accepted.size > 0
+                    ? `registered with no declared site this selector produces (${accepted.size} more accepted by registeredExtras)`
+                    : 'registered with no declared site this selector produces',
+            }
+            : {}),
+        ...(unaccepted.length === 0 && accepted.size > 0
+            ? { acceptedBy: extras === 'allow' ? "registeredExtras: 'allow'" : 'registeredExtras' }
+            : {}),
+    };
+}
 /** Structural validation of a whole rule (both forms), independent of the tree. */
 export function validateWiringRule(rule) {
     const hasChain = Array.isArray(rule.chain) && rule.chain.length > 0;
@@ -95,6 +164,10 @@ export function validateWiringRule(rule) {
     if (hasChain && hasClassic) {
         return '`chain` is mutually exclusive with `declared`/`registered`';
     }
+    if (rule.registeredExtras !== undefined &&
+        (hasChain || (rule.mode !== undefined && rule.mode !== 'subset'))) {
+        return '`registeredExtras` applies only to a classic subset rule (parity reports registered-only tokens as violations; disjoint / chain rules never examine them)';
+    }
     if (hasChain) {
         if (rule.chain.length < 2)
             return '`chain` needs at least 2 hops';
@@ -132,17 +205,69 @@ export function validateWiringRule(rule) {
  *
  * 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).
+ *
+ * `unreadFor` supplies the files a side's globs matched that the one reader
+ * did NOT read. A rule with any in its scope has its coverage replaced by the
+ * file record (`readScopeCoverage`), so it is never a pass. When the unread
+ * file is on the source side and is why the rule compared nothing, the rule is
+ * PARTIAL rather than a (failOnEmpty) skip: it matched a file it could not read.
+ *
+ * `emptiedBy` names the negations that excluded EVERY file a source's
+ * inclusion globs matched (`undefined` when the list was not emptied that
+ * way). A source side emptied by its own `!` entries is skipped with THE
+ * negation-aware reason (`matched nothing after its own negations: …`), never
+ * "0 files matched the source globs" — a file matched, then was excluded.
  */
-export function evaluateWiring(rules, resolve) {
+export function evaluateWiring(rules, resolve, context = {}, unreadFor, emptiedBy, 
+/**
+ * Every source's glob units settled with their `expectEmpty` markers
+ * (round 13) — `runWiring` supplies it (`sourceLivenessRequest` over the
+ * engine's side labels, `settleGlobLists`). A rule whose source side matched
+ * nothing is decided from it by THE rule-emptiness settle
+ * (`settleRuleEmptiness`): every inclusion glob of the source side
+ * intended-empty and no file matched → accepted, never a skip. Its
+ * acceptance and non-live units ride on the rule result. Absent: no unit is
+ * marked, so an empty rule is a loud skip exactly as before.
+ */
+ruleLivenessOf) {
     const ruleResults = [];
     const all = [];
     const diagnostics = [];
     const skipped = [];
     let evaluated = 0;
+    let acceptedEmpty = 0;
     let misconfigError = false;
     let misconfigWarn = false;
-    for (const rule of rules) {
-        const severity = rule.severity ?? 'error';
+    for (const authored of rules) {
+        const severity = authored.severity ?? 'error';
+        // The engine entry normalises idempotently (round 13): a loaded rule comes
+        // back equal; a hand-built `{ pattern, expectEmpty }` entry is a glob plus
+        // a marker; a malformed entry is a misconfigured rule — never a crash.
+        const normalized = normalizeWiringRule(authored);
+        if (!normalized.ok) {
+            const msg = `rule "${authored.id}": ${normalized.error.message}`;
+            diagnostics.push(msg);
+            if (severity === 'error')
+                misconfigError = true;
+            else
+                misconfigWarn = true;
+            ruleResults.push({
+                ruleId: authored.id,
+                ...(authored.description ? { description: authored.description } : {}),
+                severity,
+                status: 'error',
+                declaredCount: 0,
+                registeredCount: 0,
+                declaredFiles: 0,
+                registeredFiles: 0,
+                violations: [],
+                error: msg,
+                coverage: wiringCoverage(authored, { kind: 'error' }),
+            });
+            evaluated += 1;
+            continue;
+        }
+        const rule = normalized.value;
         const groupBy = rule.groupBy;
         // Validate defensively — a misconfigured rule becomes a diagnostic, never a
         // thrown exception that would crash the gate.
@@ -165,12 +290,26 @@ export function evaluateWiring(rules, resolve) {
                 registeredFiles: 0,
                 violations: [],
                 error: msg,
+                coverage: wiringCoverage(rule, { kind: 'error' }),
             });
             // A misconfigured rule attempted to run — count it so its error isn't
             // swallowed by the gate's `evaluated === 0` skip path.
             evaluated += 1;
             continue;
         }
+        // The rule's glob units and their `expectEmpty` markers (round 13): the
+        // acceptance, the printed unit lines and the non-live units ride on every
+        // result below, so `check wiring` accepts a planned glob the way `gates
+        // coverage` does.
+        const liveness = ruleLivenessOf?.(rule);
+        const nonLive = liveness?.units.filter((u) => u.state !== UnitLivenessState.Live) ?? [];
+        const unitFields = {
+            ...(liveness?.acceptance !== undefined ? { unitAcceptance: liveness.acceptance } : {}),
+            ...(liveness !== undefined && liveness.dead.length + liveness.intendedEmpty.length + liveness.wentLive.length > 0
+                ? { units: unitStateLists(liveness) }
+                : {}),
+            ...(nonLive.length > 0 ? { unitLiveness: nonLive } : {}),
+        };
         const pairs = hopPairs(rule);
         const violations = [];
         const hops = [];
@@ -179,17 +318,32 @@ export function evaluateWiring(rules, resolve) {
         let sinkFiles = 0;
         let sinkCount = 0;
         let emptySink = false;
+        let sinkHint;
+        // Registered sites no declared site produced — classic (one-hop) rules only.
+        let registeredOnly;
+        // Every file any side READ (for the read scope), and the last hop's sinks'
+        // unread files (to explain an empty sink that was simply never read).
+        const readPaths = new Set();
+        let sinkUnread = [];
         for (const [hopIndex, pair] of pairs.entries()) {
             const fromFiles = resolve(pair.from);
-            const fromSites = extractTokens(pair.from, fromFiles).sites;
+            for (const f of fromFiles)
+                readPaths.add(f.path);
+            const fromSites = extractTokens(pair.from, fromFiles, context).sites;
             const fromKeys = firstSites(fromSites, groupBy);
             // Each sink kept separate so `intersection` can require membership in ALL.
             const sinkKeySets = [];
             let hopSinkFiles = 0;
+            sinkUnread = unreadFor ? pair.to.flatMap((s) => unreadFor(s)) : [];
             for (const sink of pair.to) {
                 const files = resolve(sink);
+                for (const f of files)
+                    readPaths.add(f.path);
                 hopSinkFiles += files.length;
-                sinkKeySets.push(firstSites(extractTokens(sink, files).sites, groupBy));
+                const sinkRes = extractTokens(sink, files, context);
+                if (sinkRes.hint && sinkHint === undefined)
+                    sinkHint = sinkRes.hint;
+                sinkKeySets.push(firstSites(sinkRes.sites, groupBy));
             }
             const unionKeys = new Map();
             for (const set of sinkKeySets) {
@@ -248,12 +402,16 @@ export function evaluateWiring(rules, resolve) {
                         ...(declaredHint ? { hint: declaredHint } : {}),
                     });
                 }
+                // ONE set difference, two renderings: parity FAILS on each registered
+                // token no declared site produced; subset records them as unexamined
+                // (its coverage shortfall). Only a classic one-hop rule carries the
+                // set — a chain hop keeps the declared-token view.
+                const regOnly = registeredNotDeclared(fromKeys, unionKeys);
+                if (pairs.length === 1)
+                    registeredOnly = regOnly;
                 if (rule.mode === 'parity') {
                     const registeredHint = rule.hintRegisteredMissing ?? rule.hint;
-                    for (const k of [...unionKeys.keys()].sort()) {
-                        if (fromKeys.has(k))
-                            continue;
-                        const site = unionKeys.get(k);
+                    for (const site of regOnly) {
                         violations.push({
                             ruleId: rule.id,
                             token: site.token,
@@ -269,16 +427,104 @@ export function evaluateWiring(rules, resolve) {
             }
             hops.push({ index: hopIndex, fromCount: fromKeys.size, toCount: unionKeys.size, missing });
         }
+        // What the rule's walk covered: every file any side read, and every file
+        // any side's globs matched that the reader did not read.
+        const scope = unreadFor
+            ? mergeReadScopes(readPaths.size, wiringSourcesOf(rule).map((s) => unreadFor(s)))
+            : undefined;
+        const unreadField = scope !== undefined && scope.unread.length > 0 ? { unread: scope.unread } : {};
+        // An empty sink whose files were never READ is not a stale glob — say so,
+        // or the reader is sent to fix a selector that is fine.
+        if (emptySink && sinkUnread.length > 0) {
+            sinkHint = `the registered side ${describeUnread(sinkUnread)} was never read, so a token registered there cannot be seen`;
+        }
         // Loud skip: the SOURCE side checked nothing. Deliberately NOT triggered by
         // an empty sink — that is a real failure, flagged via `emptySink` instead.
+        // A source its OWN negations emptied is worded as such (round 12 review,
+        // R12-DOC-2), exactly as `gates coverage` and `policy-lint` word it.
+        const firstSource = pairs[0]?.from;
+        const emptiedByOwn = sourceFiles === 0 && firstSource ? emptiedBy?.(firstSource) : undefined;
         const skipReason = sourceFiles === 0
-            ? '0 files matched the source globs'
+            ? emptiedByOwn !== undefined && emptiedByOwn.length > 0
+                ? emptiedByNegationsReason(emptiedByOwn)
+                : '0 files matched the source globs'
             : sourceCount === 0
                 ? '0 ids extracted from the source side'
                 : undefined;
+        const sourceSide = pairs[0]?.from;
+        const sourceUnread = sourceSide && unreadFor ? unreadFor(sourceSide) : [];
+        if (skipReason !== undefined && readScopeHasUnread({ read: sourceFiles, unread: sourceUnread })) {
+            // The source side's zero comes from a file the reader could not read,
+            // not from a stale selector: PARTIAL (its coverage names the file),
+            // never failOnEmpty's failure and never a pass. Nothing was compared,
+            // so no violation derived from the incomplete side is reported.
+            ruleResults.push({
+                ruleId: rule.id,
+                ...(rule.description ? { description: rule.description } : {}),
+                severity,
+                status: 'passed',
+                declaredCount: sourceCount,
+                registeredCount: sinkCount,
+                declaredFiles: sourceFiles,
+                registeredFiles: sinkFiles,
+                violations: [],
+                ...(pairs.length > 1 ? { hops } : {}),
+                ...unreadField,
+                ...unitFields,
+                coverage: readScopeCoverage(wiringCoverage(rule, { kind: 'skipped', reason: skipReason }), scope),
+            });
+            evaluated += 1;
+            continue;
+        }
         if (skipReason !== undefined) {
-            const failed = failsWhenEmpty(rule);
-            skipped.push({ ruleId: rule.id, reason: skipReason, failed, severity });
+            // THE rule-emptiness settle (round 13, `settleRuleEmptiness`): every
+            // inclusion glob of the SOURCE side marked `expectEmpty` and no file
+            // matched → the empty result is the intended one, accepted and printed.
+            // Anything else is the loud skip it always was (failOnEmpty's 1, else 2):
+            // `0 ids extracted` from live files is never assertable.
+            const primaryLabel = (rule.chain?.length ?? 0) > 0 ? 'chain[0]' : 'declared';
+            const emptied = emptiedByOwn !== undefined && emptiedByOwn.length > 0;
+            const emptiness = settleRuleEmptiness({
+                subject: rule.id,
+                unitLabel: 'declared tokens',
+                filesMatched: sourceFiles,
+                unitsMatched: sourceCount,
+                unread: false,
+                emptiedByNegations: emptied,
+                ...(emptied ? { emptiedReason: skipReason } : {}),
+                liveness: liveness ?? settleGlobLists({ subject: rule.id, lists: [], marks: [] }),
+                primaryLists: [`${primaryLabel}.files`],
+                failOnEmpty: failsWhenEmpty(rule),
+                noFilesReason: '0 files matched the source globs',
+                noUnitsReason: '0 ids extracted from the source side',
+            });
+            if (emptiness.state === RuleEmptiness.IntendedEmpty && emptiness.coverage !== undefined) {
+                ruleResults.push({
+                    ruleId: rule.id,
+                    ...(rule.description ? { description: rule.description } : {}),
+                    severity,
+                    status: 'passed',
+                    declaredCount: sourceCount,
+                    registeredCount: sinkCount,
+                    declaredFiles: sourceFiles,
+                    registeredFiles: sinkFiles,
+                    violations: [],
+                    ...(pairs.length > 1 ? { hops } : {}),
+                    ...unreadField,
+                    ...unitFields,
+                    // The acceptance IS the rule's coverage (the same record, folded once).
+                    coverage: emptiness.coverage,
+                });
+                // Counted in `evaluated` (the verdict path's "nothing ran" guard must
+                // never read an accepted plan as a skip) AND in `acceptedEmpty`, which
+                // a renderer subtracts: `N evaluated, M accepted as intended-empty`.
+                evaluated += 1;
+                acceptedEmpty += 1;
+                continue;
+            }
+            const reason = emptiness.skipReason ?? skipReason;
+            const failed = emptiness.fails;
+            skipped.push({ ruleId: rule.id, reason, failed, severity });
             if (failed) {
                 if (severity === 'error')
                     misconfigError = true;
@@ -296,6 +542,9 @@ export function evaluateWiring(rules, resolve) {
                 registeredFiles: sinkFiles,
                 violations: [],
                 ...(pairs.length > 1 ? { hops } : {}),
+                ...unreadField,
+                ...unitFields,
+                coverage: readScopeCoverage(wiringCoverage(rule, { kind: 'skipped', reason }), scope),
             });
             continue;
         }
@@ -310,7 +559,17 @@ export function evaluateWiring(rules, resolve) {
             registeredFiles: sinkFiles,
             violations,
             ...(emptySink ? { emptySink: true } : {}),
+            ...(emptySink && sinkHint !== undefined ? { sinkHint } : {}),
             ...(pairs.length > 1 ? { hops } : {}),
+            ...(registeredOnly !== undefined ? { registeredOnly } : {}),
+            ...unreadField,
+            ...unitFields,
+            coverage: readScopeCoverage(wiringCoverage(rule, {
+                kind: 'ran',
+                declaredCount: sourceCount,
+                registeredCount: sinkCount,
+                ...(registeredOnly !== undefined ? { registeredOnly } : {}),
+            }), scope),
         });
         all.push(...violations);
         evaluated += 1;
@@ -326,6 +585,7 @@ export function evaluateWiring(rules, resolve) {
         diagnostics,
         skipped,
         evaluated,
+        acceptedEmpty,
         verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
     };
 }

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

@@ -1,4 +1,4 @@
-import type { IWiringRule } from '@shrkcrft/core';
+import { type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage, type IWiringRule, type ScanZone } from '@shrkcrft/core';
 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. */
@@ -11,6 +11,24 @@ export interface IWiringSideExplain {
     readonly filesScanned: number;
     /** Misconfiguration (bad regex / no capture group / bad source), if any. */
     readonly error?: string;
+    /**
+     * Named extractor this side resolved from, when it used one. Surfaced so an
+     * author reading an explain can tell a SHARED selector from a local copy of
+     * it — the two look identical in the extracted ids, and only one of them is
+     * guaranteed to stay in step with the other planes.
+     */
+    readonly viaExtractor?: string;
+    /** The lexical zone this side extracted from, when it is not the default `all`. */
+    readonly scan?: ScanZone;
+    /**
+     * Characters a non-`all` `scan` blanked before extraction.
+     *
+     * A zone is the one setting that legitimately makes a rule match LESS while
+     * still reading green, so the amount removed is shown rather than assumed: a
+     * suspicious drop separates "the pattern was reading prose" from "the glob
+     * went stale".
+     */
+    readonly blankedChars?: number;
 }
 /**
  * The full intermediate output of evaluating ONE wiring rule against the live
@@ -36,11 +54,44 @@ export interface IWiringExplain {
     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';
+    /**
+     * `passed` / `partial` / `failed` / `skipped` / `error` — skipped is never a
+     * pass, and neither is `partial`: a rule the engine reported `passed` whose
+     * {@link coverage} has a shortfall. Derived by core's `settleRuleStatus`, the
+     * same function the gate envelope uses, so `gates explain` and `gates check`
+     * report the same status for the same rule.
+     */
+    readonly status: 'passed' | 'partial' | 'failed' | 'skipped' | 'error';
     /** Why the rule checked nothing, when it was skipped. */
     readonly skipReason?: string;
-    readonly verdict: 'pass' | 'errors' | 'warnings';
+    /**
+     * The engine's verdict, settled against {@link coverage}: a `pass` or
+     * `warnings` verdict over a coverage shortfall is `not-verified` — exactly the
+     * `0 → 2` the gate envelope applies. `errors` is never changed.
+     */
+    readonly verdict: 'pass' | 'errors' | 'warnings' | 'not-verified';
+    /** What the rule examined against what it was asked to (the engine's own coverage). */
+    readonly coverage: IVerdictCoverage;
+    /** The coverage gap that vetoes a clean verdict, when there is one (`coverageShortfall`). */
+    readonly shortfall?: string;
+    /** A gap the rule's own config waived (`registeredExtras`), printed — never silent. */
+    readonly acceptance?: string;
+    /**
+     * The rule's `expectEmpty` acceptance (round 13) — the engine's settle record
+     * B, read off the rule result exactly as `check wiring` carries it — so a
+     * verdict settled over this explain (`settleWiringExplain`, `gates try`)
+     * folds it through `ruleVerdictRecords` and prints it. When the rule is
+     * intended-empty it IS {@link coverage}.
+     */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live glob units as printed lines. */
+    readonly units?: IUnitStateLists;
+    /**
+     * The rule's non-live glob units as the engine settled them (round 13
+     * review, additive) — what the explain renderers' went-live / dead block
+     * reads, so explain says what `check wiring` and `gates coverage` say.
+     */
+    readonly unitLiveness?: readonly IUnitLiveness[];
     /** Rule-level misconfiguration messages (engine degrades gracefully). */
     readonly diagnostics: readonly string[];
 }
@@ -48,14 +99,5 @@ 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>`, `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;
+export declare function explainWiring(projectRoot: string, authored: IWiringRule, options?: IExplainWiringOptions): IWiringExplain;
 //# sourceMappingURL=explain-wiring.d.ts.map