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

package/dist/baseline/compute-baseline.d.ts

@@ -1,10 +1,18 @@
 import type { IWiringSource } from '@shrkcrft/core';
+import type { IUnreadFile } from '../util/unread-file.js';
 /** The value an extractor-backed baseline computes, ready to diff or commit. */
 export interface IExtractorCompute {
     /** Canonical serialization: a pretty-printed JSON array of sorted, unique ids. */
     readonly text: string;
     readonly ids: readonly string[];
+    /** Matched files the compute READ. */
     readonly filesScanned: number;
+    /**
+     * Matched files the reader did NOT read (over the read cap, or unreadable).
+     * The recompute is incomplete without them: an id only they hold is missing
+     * from `ids`, so the baseline's coverage names them and never reads clean.
+     */
+    readonly unread: readonly IUnreadFile[];
     /** Set when the source is misconfigured (never throws). */
     readonly error?: string;
 }

package/dist/baseline/compute-baseline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/compute-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAenB"}
+{"version":3,"file":"compute-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/compute-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,iBAAiB,CAiBnB"}

package/dist/baseline/compute-baseline.js

@@ -1,5 +1,4 @@
-import { matchesAny } from "../scan/glob.js";
-import { readMatchingFiles } from "../util/walk-files.js";
+import { readSelectedFiles } from "../util/read-selected-files.js";
 import { loadTsconfigPaths } from "../scan/tsconfig-aliases.js";
 import { extractTokens } from "../extract/extract-tokens.js";
 /**
@@ -14,18 +13,20 @@ import { extractTokens } from "../extract/extract-tokens.js";
  * from a pack, unlike a `command` one.
  */
 export function computeBaselineFromExtractor(projectRoot, source, excludeDirs = []) {
-    const cache = readMatchingFiles(projectRoot, source.files ?? [], new Set(excludeDirs));
-    const files = [...cache.entries()]
-        .filter(([path]) => matchesAny(path, source.files ?? []))
-        .map(([path, content]) => ({ path, content }));
+    // The files the source's list SELECTS — a `!` entry excludes, so an id only
+    // an excluded file holds is not in the recomputed ledger.
+    const selected = readSelectedFiles(projectRoot, source.files ?? [], new Set(excludeDirs));
+    const files = [...selected.files.entries()].map(([path, content]) => ({ path, content }));
+    const unread = selected.unread;
     const res = extractTokens(source, files, { tsconfigPaths: loadTsconfigPaths(projectRoot) });
     if (res.error) {
-        return { text: '[]', ids: [], filesScanned: files.length, error: res.error };
+        return { text: '[]', ids: [], filesScanned: files.length, unread, error: res.error };
     }
     const ids = [...new Set(res.sites.map((s) => s.token))].sort();
     return {
         text: JSON.stringify(ids, null, 2) + '\n',
         ids,
         filesScanned: files.length,
+        unread,
     };
 }

package/dist/baseline/diff-baseline.d.ts

@@ -65,4 +65,32 @@ export declare function diffBaseline(rule: IBaselineRule, committed: string, cur
 export declare function baselineFails(rule: IBaselineRule, diff: IBaselineDiff): boolean;
 /** Entry count for a side, matching the comparison mode. */
 export declare function baselineCount(rule: IBaselineRule, text: string): number;
+/** The verdict of a `mode: 'ceiling'` baseline: one measured number vs its limit. */
+export interface ICeilingVerdict {
+    readonly value: number;
+    readonly ceiling: number;
+    readonly direction: 'at-most' | 'at-least';
+    readonly failed: boolean;
+    /** Headroom left (`at-most`) or shortfall (`at-least`); negative when failing. */
+    readonly slack: number;
+}
+/**
+ * Measured value for a ceiling rule's computed text.
+ *
+ * A `command` compute whose stdout IS a number (`wc -l`, a bundle size, a
+ * warning count) reports that number; anything else is measured by entry count,
+ * the same way a ledger counts. Guessing wrong in either direction would make
+ * the ratchet silently measure something other than what the author wrote, so
+ * the rule is one line and stated here rather than inferred per call site.
+ */
+export declare function ceilingValue(rule: IBaselineRule, text: string): number;
+/**
+ * Compare a measured value against the rule's declared ceiling.
+ *
+ * `at-most` is the default because the shape people hand-roll is almost always
+ * a debt ratchet — "no more than N of X, and never more". A floor (`at-least`)
+ * is the same engine with the comparison flipped, so a coverage ratchet does
+ * not need a second gate.
+ */
+export declare function evaluateCeiling(rule: IBaselineRule, value: number): ICeilingVerdict;
 //# sourceMappingURL=diff-baseline.d.ts.map

package/dist/baseline/diff-baseline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/diff-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,eAAO,MAAM,eAAe,EAAG,wBAAiC,CAAC;AAEjE,uCAAuC;AACvC,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEjF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GAAG,WAAW,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,eAAe,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;CAClD;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,aAAa,CA4Bf;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAU/E;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvE"}
+{"version":3,"file":"diff-baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/diff-baseline.ts"],"names":[],"mappings":"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"}

package/dist/baseline/diff-baseline.js

@@ -108,3 +108,32 @@ export function baselineCount(rule, text) {
     const pair = canonicalizePair(text, text, form);
     return textEntries(pair.expected.text).length;
 }
+/**
+ * Measured value for a ceiling rule's computed text.
+ *
+ * A `command` compute whose stdout IS a number (`wc -l`, a bundle size, a
+ * warning count) reports that number; anything else is measured by entry count,
+ * the same way a ledger counts. Guessing wrong in either direction would make
+ * the ratchet silently measure something other than what the author wrote, so
+ * the rule is one line and stated here rather than inferred per call site.
+ */
+export function ceilingValue(rule, text) {
+    const trimmed = text.trim();
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    return baselineCount(rule, text);
+}
+/**
+ * Compare a measured value against the rule's declared ceiling.
+ *
+ * `at-most` is the default because the shape people hand-roll is almost always
+ * a debt ratchet — "no more than N of X, and never more". A floor (`at-least`)
+ * is the same engine with the comparison flipped, so a coverage ratchet does
+ * not need a second gate.
+ */
+export function evaluateCeiling(rule, value) {
+    const ceiling = rule.ceiling ?? 0;
+    const direction = rule.direction === 'at-least' ? 'at-least' : 'at-most';
+    const slack = direction === 'at-most' ? ceiling - value : value - ceiling;
+    return { value, ceiling, direction, failed: slack < 0, slack };
+}

package/dist/evaluate/boundary-unit-finding.d.ts

@@ -0,0 +1,10 @@
+import { type IUnitLiveness } from '@shrkcrft/core';
+import type { IBoundaryUnitFinding } from './i-boundary-unit-finding.js';
+/**
+ * A settled boundary unit as its report row. Its `reason` is THE per-unit line
+ * (`formatUnitLiveness`, `@shrkcrft/core` — `DEAD_SELECTOR_CAUSES` appended to an
+ * unmarked unit that matches nothing) without the selector the row names, so no
+ * surface words a state itself.
+ */
+export declare function boundaryUnitFinding(ruleId: string, unit: IUnitLiveness): IBoundaryUnitFinding;
+//# sourceMappingURL=boundary-unit-finding.d.ts.map

package/dist/evaluate/boundary-unit-finding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-unit-finding.d.ts","sourceRoot":"","sources":["../../src/evaluate/boundary-unit-finding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,oBAAoB,CAY7F"}

package/dist/evaluate/boundary-unit-finding.js

@@ -0,0 +1,21 @@
+import { formatUnitLiveness } from '@shrkcrft/core';
+import { boundaryUnitKind } from "./boundary-unit-kind.js";
+/**
+ * A settled boundary unit as its report row. Its `reason` is THE per-unit line
+ * (`formatUnitLiveness`, `@shrkcrft/core` — `DEAD_SELECTOR_CAUSES` appended to an
+ * unmarked unit that matches nothing) without the selector the row names, so no
+ * surface words a state itself.
+ */
+export function boundaryUnitFinding(ruleId, unit) {
+    const line = formatUnitLiveness(unit);
+    const lead = `${unit.label} — `;
+    return {
+        ruleId,
+        unit: boundaryUnitKind(unit.list, unit.unit),
+        selector: unit.unit,
+        state: unit.state,
+        reason: line.startsWith(lead) ? line.slice(lead.length) : unit.message,
+        ...(unit.mark?.reason !== undefined ? { markReason: unit.mark.reason } : {}),
+        ...(unit.mark?.packageName !== undefined ? { packageName: unit.mark.packageName } : {}),
+    };
+}

package/dist/evaluate/boundary-unit-kind.d.ts

@@ -0,0 +1,7 @@
+import type { IBoundaryDeadUnit } from './evaluate-boundaries.js';
+/**
+ * The boundary JSON's `unit` word for a settled unit's list — unchanged since
+ * round 11: a `from` negation reports as `exemptFiles`, the exemption it is.
+ */
+export declare function boundaryUnitKind(list: string, unit: string): IBoundaryDeadUnit['unit'];
+//# sourceMappingURL=boundary-unit-kind.d.ts.map

package/dist/evaluate/boundary-unit-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-unit-kind.d.ts","sourceRoot":"","sources":["../../src/evaluate/boundary-unit-kind.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAKtF"}

package/dist/evaluate/boundary-unit-kind.js

@@ -0,0 +1,14 @@
+import { BoundaryMarkableList } from "../model/boundary-markable-list.js";
+/**
+ * The boundary JSON's `unit` word for a settled unit's list — unchanged since
+ * round 11: a `from` negation reports as `exemptFiles`, the exemption it is.
+ */
+export function boundaryUnitKind(list, unit) {
+    if (list === BoundaryMarkableList.From)
+        return unit.startsWith('!') ? 'exemptFiles' : 'from';
+    if (list === BoundaryMarkableList.ForbiddenImports)
+        return 'forbidden';
+    if (list === BoundaryMarkableList.AllowedImports)
+        return 'allowed';
+    return 'exemptFiles';
+}

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

@@ -1,4 +1,5 @@
-import type { IBoundaryRule, BoundarySeverity } from '../model/boundary-rule.js';
+import { UnitDeadCause, type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage, type UnitLivenessState } from '@shrkcrft/core';
+import type { BoundaryMatchKind, BoundarySeverity, IBoundaryRule, IBoundaryRuleException, IBoundaryScopeExemption } from '../model/boundary-rule.js';
 import type { IImportScanResult } from '../scan/scan-imports.js';
 import { type ITsconfigPathsMap } from '../scan/tsconfig-aliases.js';
 export interface IBoundaryViolation {
@@ -12,6 +13,11 @@ export interface IBoundaryViolation {
     matchedFrom: string;
     /** Pattern from `forbiddenImports` that matched the specifier, if any. */
     matchedForbidden?: string;
+    /**
+     * `subpath` when only the package semantics reached the specifier (a deeper
+     * import of a package the pattern names — round 11, 1.5), `exact` otherwise.
+     */
+    matchKind?: BoundaryMatchKind;
     /** When triggered by allowedImports = [..] (none matched). */
     notAllowed?: boolean;
     /** When the match came from an alias-resolved candidate path. */
@@ -28,21 +34,242 @@ export interface IEvaluateOptions {
      * matched against rule patterns alongside the original specifier.
      */
     tsconfigPaths?: ITsconfigPathsMap;
+    /**
+     * Package names the workspace knows (dependencies, workspace package names,
+     * node builtins). A forbidden pattern naming one is RESOLVABLE even when
+     * nothing imports it today — a deliberate "never adopt X" guard is not a
+     * dead unit. The orchestrator supplies this; the evaluator stays pure.
+     */
+    knownPackages?: readonly string[];
+}
+/** A rule's outcome: `skipped` = its scope matched no governed file (it enforced nothing). */
+export type BoundaryRuleStatus = 'passed' | 'failed' | 'skipped';
+/**
+ * One selector unit that matches nothing (round 11, 1.3) — a scope glob gone
+ * dead after a rename, a forbidden pattern that can never match (a typo, a
+ * retired package, or a target that does not exist yet), an exemption that
+ * exempts nothing. The rule around it can keep reporting "evaluated" while the
+ * unit silently stopped enforcing; this is the per-unit signal. The same shape
+ * as the other planes' dead units.
+ *
+ * Round 13: an UNMARKED unit only — the settled `.dead` of `settleBoundaryRule`.
+ * A unit marked `{ pattern, expectEmpty: true }` whose target does not exist is
+ * intended-empty (accepted and printed), one whose target exists went live; it
+ * is never here.
+ */
+export interface IBoundaryDeadUnit {
+    readonly ruleId: string;
+    readonly unit: 'from' | 'forbidden' | 'allowed' | 'exemptFiles';
+    readonly selector: string;
+    /**
+     * THE per-unit sentence (`formatUnitLiveness`, `@shrkcrft/core`) without the
+     * selector: what was observed, then — for a unit that simply matches nothing —
+     * `DEAD_SELECTOR_CAUSES` (typo, retired target, or a target that does not
+     * exist yet).
+     */
+    readonly reason: string;
+    /**
+     * Set when the unit is dead by its SHAPE alone (round 12): `defect` — an
+     * `importPatternDefect` (a `!`, an empty pattern, a trailing `/` under
+     * package semantics); `shadowed` — an `allowedImports` entry a forbidden
+     * sibling covers, so it can never admit an import. Proved without reading a
+     * file, so no unread file can refute it, and never markable. Unset for
+     * "matches nothing".
+     */
+    readonly cause?: UnitDeadCause;
+}
+/**
+ * A violation the rule MARKED rather than reported — an exempt file, or an
+ * adjudicated exception. Counted and listed, never silently dropped: a
+ * silently-dropped exemption is indistinguishable from a stale glob.
+ */
+export interface IBoundarySuppressedViolation {
+    readonly violation: IBoundaryViolation;
+    readonly reason: 'exempt-file' | 'exception';
+    /** The exemption glob, for `exempt-file`. */
+    readonly glob?: string;
+    /** The exception that allowed the edge, for `exception`. */
+    readonly exception?: IBoundaryRuleException;
+}
+/**
+ * An exception that suppressed NO real edge in this run. It fails the run: an
+ * exception list that cannot rot loudly rots into permanent silent width.
+ */
+export interface IBoundaryStaleException {
+    readonly ruleId: string;
+    /** Position in the rule's `exceptions[]`. */
+    readonly index: number;
+    readonly exception: IBoundaryRuleException;
+    readonly severity: 'error';
+    readonly message: string;
+}
+/** Files one glob matched. */
+export interface IBoundaryGlobCount {
+    readonly glob: string;
+    /** Governed (non-exempt) files the glob matched. */
+    readonly files: number;
+    /** The settled state of the glob as a selector unit (round 13): live, dead, intended-empty, went-live, unproven. */
+    readonly state?: UnitLivenessState;
+}
+/** What one forbidden pattern hit, in scope and anywhere. */
+export interface IBoundaryPatternCount {
+    readonly pattern: string;
+    /** Violations it produced in this rule's governed files. */
+    readonly hitsInScope: number;
+    /** Distinct specifiers (literal or alias-resolved) it matches anywhere in the scan. */
+    readonly hitsAnywhere: number;
+    /** Can it ever match? (a hit anywhere, a known package, an alias, a file) */
+    readonly resolvable: boolean;
+    /** For `forbiddenMatch: 'exact'`: specifiers only the package semantics would have reached. */
+    readonly subpathHitsAnywhere?: number;
+    /**
+     * A sibling forbidden pattern of the same rule that already covers every
+     * import this one matches (`@scope/pkg/**` next to `@scope/pkg` under package
+     * semantics) — redundant, safe to delete. INFO: never a dead unit, never a
+     * verdict change (round 12, R12-5.6; from `boundaryPatternOverlaps`).
+     */
+    readonly subsumedBy?: string;
+    /** The settled state of the pattern as a selector unit (round 13). */
+    readonly state?: UnitLivenessState;
+}
+/** Per-rule coverage: what each unit of the rule actually matched. */
+export interface IBoundaryRuleCoverage {
+    readonly ruleId: string;
+    readonly severity: BoundarySeverity;
+    readonly status: BoundaryRuleStatus;
+    /** Why the rule checked nothing, when `skipped`. */
+    readonly skipReason?: string;
+    /** A skip that FAILS the run (`failOnEmpty`, on by default for `error` rules). */
+    readonly failedOnEmpty?: boolean;
+    /**
+     * The rule settled IntendedEmpty (round 13, core `settleRuleEmptiness`):
+     * every `from` inclusion is marked `expectEmpty` and it matched no file — it
+     * examined 0 files, so it is ACCEPTED (its coverage is the acceptance), never
+     * counted as evaluated (`rulesEvaluated`, `boundaryRulesEvaluated`).
+     */
+    readonly acceptedAsIntendedEmpty?: true;
+    /** Governed files: inside `from`, not exempt. */
+    readonly filesInScope: number;
+    /** Inside `from` but exempt — scanned, violations suppressed. */
+    readonly exemptFilesInScope: number;
+    /** Import edges read from governed files. */
+    readonly edgesInScope: number;
+    /** Unsuppressed violations. */
+    readonly violations: number;
+    readonly suppressed: number;
+    readonly fromGlobs: readonly IBoundaryGlobCount[];
+    readonly forbidden: readonly IBoundaryPatternCount[];
+    /**
+     * `shadowedBy`: a forbidden pattern of the same rule covering every import
+     * this allowance matches — forbidden is checked first, so it can never admit
+     * one (its dead unit carries `cause: 'shadowed'`; round 12, R12-5.3).
+     */
+    readonly allowed: readonly {
+        readonly pattern: string;
+        readonly hitsAnywhere: number;
+        readonly shadowedBy?: string;
+        readonly state?: UnitLivenessState;
+    }[];
+    readonly exemptions: readonly (IBoundaryScopeExemption & {
+        readonly files: number;
+        readonly state?: UnitLivenessState;
+    })[];
+    readonly exceptions: readonly (IBoundaryRuleException & {
+        readonly matched: number;
+    })[];
+    readonly deadUnits: readonly IBoundaryDeadUnit[];
+    /**
+     * Every judged selector unit, settled (round 13): the observation, its state
+     * and its one sentence. The orchestrator's unread re-settle reads it, and
+     * `--fail-on-dead-units` judges each unit through core's `selectorUnitFails`.
+     */
+    readonly unitLiveness?: readonly IUnitLiveness[];
+    /**
+     * The verdict coverage the gate envelope settles on: scope globs that reached
+     * a governed file, of the scope globs the rule JUDGES (a marked intended-empty
+     * glob is accepted by {@link unitAcceptance}, not judged) — for a rule whose
+     * every `from` inclusion is intended-empty and that matched no file, the
+     * acceptance itself. Engine-owned, like the wiring and policy planes' — a
+     * surface reads it, never recomputes it.
+     */
+    readonly coverage: IVerdictCoverage;
+    /**
+     * Settle record B (round 13): the rule's intended-empty units,
+     * `acceptedBy: 'expectEmpty'`. Folded beside {@link coverage} into the ONE
+     * verdict settle (`ruleVerdictRecords`), so it prints `accepted by
+     * expectEmpty: …` at exit 0 and can never cover a dead unit.
+     */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live unit lines (`unitStateLists`), when it has any. */
+    readonly units?: IUnitStateLists;
 }
 export interface IEvaluateResult {
+    /** Rules selected for evaluation (after `onlyRuleId`). */
+    rulesConfigured: number;
+    /**
+     * Rules that examined at least one governed file — never a skipped rule, and
+     * never one accepted as intended-empty (it examined 0 files; round 13 —
+     * counted in {@link rulesAcceptedEmpty} instead).
+     */
     rulesEvaluated: number;
+    /**
+     * Rules accepted as intended-empty (round 13): every `from` inclusion marked
+     * `expectEmpty`, no file matched — `acceptedAsIntendedEmpty` on its coverage.
+     * Printed apart from the evaluated count (`N evaluated, M accepted as
+     * intended-empty`).
+     */
+    rulesAcceptedEmpty: number;
     edgesEvaluated: number;
+    /** Source files the scopes were counted against. */
+    filesScanned: number;
+    /**
+     * Where that file list came from: the scan's own `files` (every scanned
+     * file), or — for a hand-built scan without one — the files that appear in
+     * `edges`, which cannot see import-free files.
+     */
+    fileUniverse: 'scan' | 'edges';
     violations: IBoundaryViolation[];
-    /** Quick counts grouped by severity. */
+    /** Quick counts grouped by severity (unsuppressed violations only). */
     counts: {
         error: number;
         warning: number;
         info: number;
     };
+    suppressed: IBoundarySuppressedViolation[];
+    suppressedCounts: {
+        exemptFile: number;
+        exception: number;
+    };
+    staleExceptions: IBoundaryStaleException[];
+    coverage: IBoundaryRuleCoverage[];
+    skipped: {
+        ruleId: string;
+        reason: string;
+        severity: BoundarySeverity;
+        failed: boolean;
+    }[];
+    deadUnits: IBoundaryDeadUnit[];
+    /**
+     * Rules the engine entry could not normalise (round 13) — a hand-built rule
+     * with a malformed `expectEmpty` marker, which every loader refuses first.
+     * Never evaluated and never a crash: each is a skipped rule that fails the run.
+     */
+    invalidRules?: {
+        ruleId: string;
+        problems: readonly string[];
+    }[];
 }
 /**
  * Evaluate every rule against every scanned edge. Returns the list of
- * violations + counts. Pure function — no I/O.
+ * violations + counts, and — round 11 — what every rule and every selector
+ * unit actually matched, so a rule that enforced nothing can never read as
+ * evaluated. Pure function — no I/O.
+ *
+ * Round 13: each rule is normalised IDEMPOTENTLY at entry
+ * (`normalizeBoundaryRule` — a loaded rule comes back unchanged), so a
+ * hand-built rule with a `{ pattern, expectEmpty: true }` entry is honoured,
+ * never a `pattern.includes is not a function` crash; and every rule's units
+ * and emptiness settle through the ONE boundary settle (`settleBoundaryRule`).
  */
 export declare function evaluateBoundaries(scan: IImportScanResult, rules: readonly IBoundaryRule[], options?: IEvaluateOptions): IEvaluateResult;
 //# sourceMappingURL=evaluate-boundaries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"evaluate-boundaries.d.ts","sourceRoot":"","sources":["../../src/evaluate/evaluate-boundaries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEjF,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,wCAAwC;IACxC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA6DjB"}
+{"version":3,"file":"evaluate-boundaries.d.ts","sourceRoot":"","sources":["../../src/evaluate/evaluate-boundaries.ts"],"names":[],"mappings":"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"}