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

package/dist/gates/incomplete-registry-inventory.js

@@ -0,0 +1,63 @@
+import { describeUnread, readScopeCoverage, readScopeHasUnread, registryDuplicates, registryExists, } from '@shrkcrft/boundaries';
+import { ExitCode } from "../exit-codes.js";
+import { asJson } from "../output/format-output.js";
+import { settleVerdict } from "./settle-verdict.js";
+import { verdictLine } from "./verdict-line.js";
+/**
+ * Answer a `registry <name> list | exists | where | duplicates` query over an
+ * INCOMPLETE inventory: one whose source globs matched a file the reader did
+ * not read (over the read cap). Returns `undefined` when the answer is
+ * verified anyway, so the caller answers normally.
+ *
+ * Only a POSITIVE finding survives an incomplete read. An id found among the
+ * files read is declared, and a duplicate found there is a duplicate. Absence
+ * ("no", "not declared", "no duplicates") and the listing itself may be wrong,
+ * because the unread file can hold the id. So those are NOT VERIFIED (2),
+ * whatever guard flag was passed, and are settled through the one coverage
+ * guard (`readScopeCoverage` → `settleVerdict`) so the exit and the printed
+ * verdict agree. `exists X --fail-if-taken` over an unread file is never the
+ * "free" 0 a duplicate guard would march on.
+ */
+export function answerIncompleteInventory(inventory, decl, action, id, json) {
+    if (!readScopeHasUnread(inventory.readScope))
+        return undefined;
+    if ((action === 'exists' || action === 'where') && id !== undefined && registryExists(inventory, id)) {
+        return undefined;
+    }
+    if (action === 'duplicates' && registryDuplicates(inventory).length > 0)
+        return undefined;
+    const coverage = {
+        ...readScopeCoverage({ unit: 'ids', expected: inventory.entries.length, examined: inventory.entries.length }, inventory.readScope),
+        subject: `registry "${inventory.name}"`,
+    };
+    const settled = settleVerdict(ExitCode.VerifiedPass, [coverage]);
+    const what = describeUnread(inventory.readScope.unread);
+    if (json) {
+        process.stdout.write(asJson({
+            name: inventory.name,
+            ...(action ? { action } : {}),
+            ...(id !== undefined ? { id } : {}),
+            ids: inventory.entries.map((e) => e.id),
+            verified: false,
+            unread: inventory.readScope.unread,
+            exitCode: settled.exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+        }) + '\n');
+        return settled.exit;
+    }
+    process.stdout.write(`Registry "${inventory.name}"${decl.description ? ` — ${decl.description}` : ''}: its source globs matched ${what},\n` +
+        '  so the inventory is incomplete and this answer is NOT verified.\n');
+    if (action === 'list' || action === undefined) {
+        process.stdout.write(`  ${inventory.entries.length} id(s) among the files read:\n`);
+        for (const e of inventory.entries)
+            process.stdout.write(`  • ${e.id}\n`);
+    }
+    else if (id !== undefined) {
+        process.stdout.write(`  "${id}" is not among the ids read; the unread file may declare it.\n`);
+    }
+    const line = verdictLine(settled, '');
+    if (line)
+        process.stdout.write(`${line}\n`);
+    return settled.exit;
+}

package/dist/gates/measure-registration-roles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * THE role measurement of a registration idiom — re-exported. Round 13 (P4):
+ * the implementation moved to `@shrkcrft/boundaries`
+ * (`packages/boundaries/src/wiring/measure-registration-roles.ts`) so the
+ * registration-graph queries read the SAME authority `gates check` / `gates
+ * coverage` read — MCP `get_wiring_graph` cannot import the CLI. Edit it
+ * there; this path stays so every gates import is unchanged.
+ */
+export { measureRegistrationRoles } from '@shrkcrft/boundaries';
+//# sourceMappingURL=measure-registration-roles.d.ts.map

package/dist/gates/measure-registration-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-registration-roles.d.ts","sourceRoot":"","sources":["../../src/gates/measure-registration-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/gates/measure-registration-roles.js

@@ -0,0 +1,9 @@
+/**
+ * THE role measurement of a registration idiom — re-exported. Round 13 (P4):
+ * the implementation moved to `@shrkcrft/boundaries`
+ * (`packages/boundaries/src/wiring/measure-registration-roles.ts`) so the
+ * registration-graph queries read the SAME authority `gates check` / `gates
+ * coverage` read — MCP `get_wiring_graph` cannot import the CLI. Edit it
+ * there; this path stays so every gates import is unchanged.
+ */
+export { measureRegistrationRoles } from '@shrkcrft/boundaries';

package/dist/gates/plane-verdict.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A plane payload's top-level `verdict`, derived from the SETTLED exit — so a
+ * `--json` payload can never say `pass` (or `warnings`) next to `exitCode: 2`.
+ *
+ *   0 → `warnings` when the engine reported non-blocking findings, else `pass`
+ *   1 → `errors`
+ *   2 → `not-verified`
+ *   3 → `usage-error`
+ *
+ * Spread the engine's report first and set `verdict: planeVerdictForExit(exit,
+ * report.verdict)` after it, so the settled word overrides the engine's.
+ */
+export declare function planeVerdictForExit(exit: number, engineVerdict?: string): 'pass' | 'warnings' | 'errors' | 'not-verified' | 'usage-error';
+//# sourceMappingURL=plane-verdict.d.ts.map

package/dist/gates/plane-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane-verdict.d.ts","sourceRoot":"","sources":["../../src/gates/plane-verdict.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,CAKjE"}

package/dist/gates/plane-verdict.js

@@ -0,0 +1,22 @@
+import { ExitCode } from "../exit-codes.js";
+/**
+ * A plane payload's top-level `verdict`, derived from the SETTLED exit — so a
+ * `--json` payload can never say `pass` (or `warnings`) next to `exitCode: 2`.
+ *
+ *   0 → `warnings` when the engine reported non-blocking findings, else `pass`
+ *   1 → `errors`
+ *   2 → `not-verified`
+ *   3 → `usage-error`
+ *
+ * Spread the engine's report first and set `verdict: planeVerdictForExit(exit,
+ * report.verdict)` after it, so the settled word overrides the engine's.
+ */
+export function planeVerdictForExit(exit, engineVerdict) {
+    if (exit === ExitCode.VerifiedPass)
+        return engineVerdict === 'warnings' ? 'warnings' : 'pass';
+    if (exit === ExitCode.Failure)
+        return 'errors';
+    if (exit === ExitCode.NotVerified)
+        return 'not-verified';
+    return 'usage-error';
+}

package/dist/gates/qualify-clean-for-units.d.ts

@@ -0,0 +1,12 @@
+import type { IUnitStateNotes } from './i-unit-state-notes.js';
+/**
+ * A verb's clean sentence, qualified by THE shared unit-state renderer's
+ * findings (round 13, K2): with a dead unit or a LOCAL went-live marker listed
+ * above, EVERY ✓ is withheld and the sentence says why — `No policy
+ * violations on the scanned surfaces, but 1 expectEmpty unit(s) went live —
+ * remove the markers (listed above).` The exit is unchanged (advisory);
+ * `verdictLine` still prints the sentence only at exit 0, followed by any
+ * acceptance. An empty `clean` stays empty.
+ */
+export declare function qualifyCleanForUnits(clean: string, notes: IUnitStateNotes): string;
+//# sourceMappingURL=qualify-clean-for-units.d.ts.map

package/dist/gates/qualify-clean-for-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualify-clean-for-units.d.ts","sourceRoot":"","sources":["../../src/gates/qualify-clean-for-units.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAOlF"}

package/dist/gates/qualify-clean-for-units.js

@@ -0,0 +1,18 @@
+/**
+ * A verb's clean sentence, qualified by THE shared unit-state renderer's
+ * findings (round 13, K2): with a dead unit or a LOCAL went-live marker listed
+ * above, EVERY ✓ is withheld and the sentence says why — `No policy
+ * violations on the scanned surfaces, but 1 expectEmpty unit(s) went live —
+ * remove the markers (listed above).` The exit is unchanged (advisory);
+ * `verdictLine` still prints the sentence only at exit 0, followed by any
+ * acceptance. An empty `clean` stays empty.
+ */
+export function qualifyCleanForUnits(clean, notes) {
+    if (clean.length === 0 || notes.stale.length === 0)
+        return clean;
+    const lead = clean
+        .replace(/\s*✓/gu, '')
+        .replace(/ {2,}/gu, ' ')
+        .replace(/[.\s]+$/u, '');
+    return `${lead}, but ${notes.stale.join(', and ')} (listed above).`;
+}

package/dist/gates/registration-graph-verdict.d.ts

@@ -0,0 +1,34 @@
+import { type IGateEnvelope } from './gate-envelope.js';
+import type { IRegistrationQuerySettleInput } from './i-registration-query-settle-input.js';
+/**
+ * Settle a registration-graph absence query (`wiring unprovided` / `wiring
+ * orphans`) against what the graph read AND what every idiom's roles examined.
+ *
+ * The coverage comes from ONE place, @shrkcrft/boundaries
+ * `registrationUnprovidedVerdict` / `registrationOrphansVerdict`: the idiom
+ * files the reader could not read (over the read cap), named; every absence
+ * such a file could refute, demoted from a finding to `unproven`; and — round
+ * 13 (P4) — every idiom's ROLE record from THE role authority
+ * (`measureRegistrationRoles`), so a declared role that matched no file is a
+ * shortfall here exactly as on `gates check`. finish's unprovided sub-gate and
+ * MCP `get_wiring_graph` read the same records, so the verb and its siblings
+ * cannot disagree.
+ *
+ * The settle runs through the shared gate envelope (one row per record, the
+ * query's own row carrying its findings): a proposed 0 over a shortfall is NOT
+ * VERIFIED (2), a 1 keeps its exit and gains the `(also not verified: …)`
+ * line, an expectEmpty acceptance is printed at 0, and a fully-examined graph
+ * settles exactly as proposed, with the clean line. `--json` ALWAYS carries
+ * `gate`, `coverage`, `exitCode`, `verdict`, `shortfalls` and `accepted` — it
+ * carried them only when a file was unread, so a dead declared role printed
+ * `{"total":0,"unprovided":[]}` at exit 0 with nothing to say it proved nothing.
+ */
+export declare function settleRegistrationGraph<T extends {
+    readonly token: string;
+}>(input: IRegistrationQuerySettleInput<T>): {
+    readonly exit: number;
+    readonly line: string;
+    readonly json: Readonly<Record<string, unknown>>;
+    readonly gate: IGateEnvelope;
+};
+//# sourceMappingURL=registration-graph-verdict.d.ts.map

package/dist/gates/registration-graph-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-graph-verdict.d.ts","sourceRoot":"","sources":["../../src/gates/registration-graph-verdict.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,aAAa,EAAwB,MAAM,oBAAoB,CAAC;AACjG,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AAG5F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC1E,KAAK,EAAE,6BAA6B,CAAC,CAAC,CAAC,GACtC;IACD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B,CA6CA"}

package/dist/gates/registration-graph-verdict.js

@@ -0,0 +1,70 @@
+import { ExitCode } from "../exit-codes.js";
+import { buildGateEnvelope } from "./gate-envelope.js";
+import { verdictLine } from "./verdict-line.js";
+/**
+ * Settle a registration-graph absence query (`wiring unprovided` / `wiring
+ * orphans`) against what the graph read AND what every idiom's roles examined.
+ *
+ * The coverage comes from ONE place, @shrkcrft/boundaries
+ * `registrationUnprovidedVerdict` / `registrationOrphansVerdict`: the idiom
+ * files the reader could not read (over the read cap), named; every absence
+ * such a file could refute, demoted from a finding to `unproven`; and — round
+ * 13 (P4) — every idiom's ROLE record from THE role authority
+ * (`measureRegistrationRoles`), so a declared role that matched no file is a
+ * shortfall here exactly as on `gates check`. finish's unprovided sub-gate and
+ * MCP `get_wiring_graph` read the same records, so the verb and its siblings
+ * cannot disagree.
+ *
+ * The settle runs through the shared gate envelope (one row per record, the
+ * query's own row carrying its findings): a proposed 0 over a shortfall is NOT
+ * VERIFIED (2), a 1 keeps its exit and gains the `(also not verified: …)`
+ * line, an expectEmpty acceptance is printed at 0, and a fully-examined graph
+ * settles exactly as proposed, with the clean line. `--json` ALWAYS carries
+ * `gate`, `coverage`, `exitCode`, `verdict`, `shortfalls` and `accepted` — it
+ * carried them only when a file was unread, so a dead declared role printed
+ * `{"total":0,"unprovided":[]}` at exit 0 with nothing to say it proved nothing.
+ */
+export function settleRegistrationGraph(input) {
+    const { verdict } = input;
+    const own = verdict.coverage.find((c) => c.subject === input.subject);
+    const all = { unit: 'registration idioms', expected: input.idioms, examined: input.idioms };
+    const fails = input.proposed === ExitCode.Failure;
+    const rows = [
+        ...verdict.coverage
+            .filter((c) => c !== own)
+            .map((c) => ({
+            id: `${c.subject ?? 'registration graph'}${c.acceptedBy !== undefined ? ' (expectEmpty)' : ''}`,
+            type: 'registration',
+            status: 'passed',
+            severity: 'warning',
+            counts: {},
+            violations: [],
+            coverage: c,
+        })),
+        {
+            id: input.subject,
+            type: 'registration',
+            status: fails ? 'failed' : 'passed',
+            severity: fails ? 'error' : 'warning',
+            counts: { findings: verdict.findings.length, unproven: verdict.unproven.length },
+            violations: fails ? verdict.findings.map((t) => ({ id: t.token })) : [],
+            coverage: own ?? all,
+        },
+    ];
+    const gate = buildGateEnvelope(input.verb, input.proposed, rows, all);
+    return {
+        exit: gate.exit,
+        line: verdictLine(gate, input.clean),
+        json: {
+            coverage: verdict.coverage,
+            ...(verdict.unread.length > 0 ? { unread: verdict.unread } : {}),
+            ...(verdict.unproven.length > 0 ? { unproven: verdict.unproven } : {}),
+            exitCode: gate.exit,
+            verdict: gate.verdict,
+            shortfalls: gate.shortfalls,
+            accepted: gate.accepted,
+            gate,
+        },
+        gate,
+    };
+}

package/dist/gates/registration-roles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * THE registration-role measurement's shape — re-exported. Round 13 (P4): it
+ * moved to `@shrkcrft/boundaries`
+ * (`packages/boundaries/src/wiring/i-registration-roles.ts`) with
+ * `measureRegistrationRoles`, and gained the `unitAcceptance?` carrier (settle
+ * record B). Edit it there.
+ */
+export type { IRegistrationRoles } from '@shrkcrft/boundaries';
+//# sourceMappingURL=registration-roles.d.ts.map

package/dist/gates/registration-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-roles.d.ts","sourceRoot":"","sources":["../../src/gates/registration-roles.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/gates/registration-roles.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/registry-liveness.d.ts

@@ -0,0 +1,11 @@
+import type { IRegistryDeclaration, ISettledUnitLiveness } from '@shrkcrft/core';
+/**
+ * A registry's `source` / `consumer` glob units settled with their
+ * `expectEmpty` markers (round 13) — THE per-source request `gates coverage`
+ * builds too (`sourceLivenessRequest` over `registryLabeledSources`). The
+ * registry verbs (`registry <name> list|exists|where|duplicates`) and `gates
+ * check` both decide an empty inventory from it, so they cannot disagree about
+ * a registry over a planned directory.
+ */
+export declare function registryLiveness(cwd: string, decl: IRegistryDeclaration, excludeDirs: readonly string[]): ISettledUnitLiveness;
+//# sourceMappingURL=registry-liveness.d.ts.map

package/dist/gates/registry-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-liveness.d.ts","sourceRoot":"","sources":["../../src/gates/registry-liveness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAIjF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,EAC1B,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,oBAAoB,CAEtB"}

package/dist/gates/registry-liveness.js

@@ -0,0 +1,13 @@
+import { settleGlobLists, sourceLivenessRequest } from '@shrkcrft/boundaries';
+import { registryLabeledSources } from "./gate-rule-globs.js";
+/**
+ * A registry's `source` / `consumer` glob units settled with their
+ * `expectEmpty` markers (round 13) — THE per-source request `gates coverage`
+ * builds too (`sourceLivenessRequest` over `registryLabeledSources`). The
+ * registry verbs (`registry <name> list|exists|where|duplicates`) and `gates
+ * check` both decide an empty inventory from it, so they cannot disagree about
+ * a registry over a planned directory.
+ */
+export function registryLiveness(cwd, decl, excludeDirs) {
+    return settleGlobLists(sourceLivenessRequest(cwd, registryLabeledSources(decl), excludeDirs, decl.name));
+}

package/dist/gates/rule-coverage.d.ts

@@ -1,6 +1,11 @@
-import type { IWiringSource } from '@shrkcrft/core';
+import type { IWiringSource, ISelectorUnitFailOptions, IUnitLiveness, IUnitStateLists, IVerdictCoverage } from '@shrkcrft/core';
+import { RuleEmptiness } from '@shrkcrft/core';
+import type { ICoverageDeadGlob } from './i-coverage-dead-glob.js';
+import type { ICoverageNegation } from './i-coverage-negation.js';
 import { type ISharkcraftInspection } from '@shrkcrft/inspector';
 import type { IGateRuleView } from './gate-rule-view.js';
+import { type IGateEnvelope, type IGateRuleResult } from './gate-envelope.js';
+import type { ISelfTestCheck } from './self-test-check.js';
 export declare const GATE_COVERAGE_SCHEMA: "sharkcraft.gate-coverage/v1";
 /**
  * Whether a rule is connected to anything at all.
@@ -9,7 +14,9 @@ export declare const GATE_COVERAGE_SCHEMA: "sharkcraft.gate-coverage/v1";
  * matches nothing passes every gate forever, so the ONLY way to notice is to
  * report the match count itself and flag zero. `failed-expectation` is the
  * stronger form — the author wrote down what the rule should match, and it
- * doesn't.
+ * doesn't. A rule whose empty result is the INTENDED one (round 13: a fence's
+ * asserted empty set, or every primary input glob marked `expectEmpty`) is
+ * `ok` — its acceptance is printed.
  */
 export type GateCoverageStatus = 'ok' | 'empty' | 'error' | 'failed-expectation';
 export interface IGateCoverage {
@@ -19,10 +26,17 @@ export interface IGateCoverage {
     readonly status: GateCoverageStatus;
     /** Files the rule's primary selector matched. */
     readonly filesMatched: number;
-    /** Ids/units the rule extracted (findings scanned, for the policy plane). */
+    /** Ids/units the rule extracted (content units scanned, for the policy plane). */
     readonly unitsMatched: number;
     /** What "units" means for this plane, for honest reporting. */
     readonly unitLabel: string;
+    /** What one extracted "id" is on this plane — what `expectIds` is checked against. */
+    readonly idLabel: string;
+    /**
+     * The selector coverage (and the selfTest) consulted, e.g.
+     * `registry "mcp-tools" — source packages/…/*.tool.ts (regex-capture)`.
+     */
+    readonly consulted: string;
     /** A few of the extracted ids, so the author can eyeball correctness. */
     readonly sampleIds: readonly string[];
     /**
@@ -31,22 +45,115 @@ export interface IGateCoverage {
      * fact almost no consumer of it needs — `gates try --full` does.
      */
     readonly allIds?: readonly string[];
+    /**
+     * The extracted ids a `selfTest` may safely PIN, when that is narrower than
+     * the whole set. Present only on the policy plane. It holds the distinct hits
+     * an `exemptFiles` / `exemptLines` exemption let through (a fixture proving
+     * the forbidden pattern still bites). A live finding is debt the author will
+     * pay down, so `gates scaffold-selftest` never pins one: the gate would go
+     * red on the day the violation is fixed.
+     */
+    readonly pinIds?: readonly string[];
+    /**
+     * `false` when coverage cannot inspect this rule without a side effect: a
+     * `command` baseline with no `watchFiles`, or a doc-reference rule whose
+     * registries were not loaded. Such a rule's `coverage` records nothing
+     * examined. A caller that ran the rule's own check (`shrk quality`) settles
+     * it on that check's coverage instead. Absent when the rule was inspected.
+     */
+    readonly inspectable?: boolean;
     /** True when a zero match is a hard failure for this rule. */
     readonly failOnEmpty: boolean;
     readonly error?: string;
     /**
      * A diagnosis for a zero-match that is correct but probably not intended —
      * e.g. an `import-edges` rule targeting `to.files` against barrel imports.
+     * Never set on a rule whose empty result is the intended one (a verified
+     * fence, an intended-empty rule): it would invite the author to "fix" it.
      */
     readonly hint?: string;
-    /** Unmet `selfTest` expectations, each a human-readable sentence. */
+    /** Unmet `selfTest` expectations, each a sentence naming the selector consulted. */
     readonly expectationFailures: readonly string[];
+    /**
+     * EVERY declared `selfTest` expectation with its result — held, failed, or
+     * not-evaluable — from the one evaluator (`gates/self-test.ts`). Present only
+     * when the rule declares a selfTest.
+     */
+    readonly selfTestChecks?: readonly ISelfTestCheck[];
+    /**
+     * Globs inside this rule that do nothing — a dead unit a connected rule
+     * hides, because its sibling globs keep it matching: an inclusion glob that
+     * selects nothing, or a negation that excludes nothing. Prefixed with the
+     * side (`declared: src/moved/*.ts`) when the rule reads more than one source.
+     * UNMARKED dead units only (round 13): a glob marked `expectEmpty` is
+     * intended-empty (accepted) or went-live, never here. Advisory unless
+     * `gates coverage --fail-on-dead-units`.
+     */
+    readonly deadGlobs: readonly string[];
+    /**
+     * The units behind {@link deadGlobs}, in the same order, each with the
+     * reason it is dead (`matched 0 files`, `matches only files the list's
+     * negations exclude (N)`, `excludes nothing — …`). Always set by
+     * {@link buildGateCoverage}; read it through {@link coverageDeadUnits}.
+     */
+    readonly deadGlobUnits?: readonly ICoverageDeadGlob[];
+    /**
+     * The LIVE negations inside this rule (`!` entries that exclude at least one
+     * file from their own list), each with what it excludes — the narrowing a
+     * `!` performs, made visible. Always set by {@link buildGateCoverage}.
+     */
+    readonly negations?: readonly ICoverageNegation[];
+    /**
+     * Present only when the rule's PRIMARY selector list was emptied by its own
+     * negations: its inclusion globs matched files and these negations (each
+     * with what it excluded) removed every one. A zero match here is the
+     * author's `!` at work, not a stale selector — the text line, the `gate`
+     * envelope's `skipReason` and `shrk quality` say so. Exits are unchanged.
+     */
+    readonly excludedByNegations?: readonly ICoverageNegation[];
+    /** How many distinct globs the dead-glob check examined (0 = not checked on this plane). */
+    readonly globsChecked: number;
     /**
      * Named extractor this rule's primary selector came from. Present only for a
      * `$use` consumer — the answer to "is this rule looking at the shared set, or
      * a copy of it that has since drifted?".
      */
     readonly viaExtractor?: string;
+    /**
+     * How much of the rule's scope this coverage run could see: every unit it
+     * matched; for a subset wiring rule, the registered tokens its declared
+     * selector produced (from the engine `check wiring` runs, so the two agree);
+     * for a fence, the asserted empty set (accepted by `expectEmpty: true`); for
+     * an intended-empty rule, the acceptance of its marked inputs; for a rule
+     * that could not be inspected, nothing. The `gate` envelope turns a gap here
+     * into a `partial` rule.
+     */
+    readonly coverage: IVerdictCoverage;
+    /**
+     * The rule's `expectEmpty` acceptance — settle record B
+     * (`settleUnitLiveness(...).acceptance`, `@shrkcrft/core`) over every glob
+     * list the rule reads — carried beside the primary {@link coverage} so
+     * `settleGateCoverage` hands it to the envelope rule's `unitAcceptance`;
+     * without a carrier an acceptance would be dropped silently. Absent when no
+     * unit of the rule is intended-empty.
+     */
+    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 (dead, intended-empty, went-live, unproven),
+     * as the settle judged them — what `--fail-on-dead-units` decides through
+     * (`selectorUnitFails`) and what the ⚠ `expectEmpty is stale` rows print.
+     */
+    readonly unitLiveness?: readonly IUnitLiveness[];
+    /**
+     * Set when the rule matched nothing: THE rule-emptiness settle's state
+     * (`settleRuleEmptiness`) — `intended-empty` and `asserted-empty-output`
+     * read `ok` (accepted), `stale` / `emptied-by-negations` read `empty`.
+     */
+    readonly emptiness?: RuleEmptiness;
+    /** The skip reason of an `empty` rule, when it is more than "matched 0 units" (a fence over a dead input). */
+    readonly emptyReason?: string;
 }
 /**
  * One named extractor, reported ONCE with the rules that share it.
@@ -72,11 +179,14 @@ export interface IGateCoverageReport {
     readonly empty: number;
     readonly errored: number;
     readonly expectationFailures: number;
+    /** Dead globs across every rule (the sum of each rule's `deadGlobs`). */
+    readonly deadGlobCount: number;
     /** Named extractors referenced by at least one rule, each reported once. */
     readonly extractors: readonly ISharedExtractorCoverage[];
     /**
      * `pass` — every rule matched something and met its expectations.
      * `stale` — at least one rule matched nothing (or broke an expectation).
+     * Dead globs inside connected rules are advisory and do not change it.
      */
     readonly verdict: 'pass' | 'stale';
 }
@@ -88,4 +198,77 @@ export interface IGateCoverageReport {
  * the report never claims a fact it did not check.
  */
 export declare function buildGateCoverage(cwd: string, rules: readonly IGateRuleView[], excludeDirs?: readonly string[], extractors?: Readonly<Record<string, IWiringSource>>, includeAllIds?: boolean, inspection?: ISharkcraftInspection): IGateCoverageReport;
+/**
+ * The coverage report with every pack rule the merge seam REJECTED folded in as
+ * a misconfigured (`error`) row (round 12 review, R12-X1) — from THE rows
+ * `seamRejectedRules` builds for `gates check`, so the coverage verb and the
+ * check cannot disagree about a rule that never ran. It counts in `total` and
+ * `errored`, so `settleGateCoverage` fails it (exit 1) and names it unexamined.
+ */
+export declare function withRejectedRules(report: IGateCoverageReport, rejected: readonly (IGateRuleResult & {
+    readonly type: IGateRuleView['plane'];
+})[]): IGateCoverageReport;
+/**
+ * Whether a rule's dead globs are a finding of their OWN: the rule is connected
+ * (it matched something, or it is an inspected fence / clean rule reported
+ * `ok`), so sibling globs can hide the dead ones.
+ *
+ * A rule already reported as matching nothing has no live sibling to hide
+ * behind. Its "matched nothing" verdict (skip, or failOnEmpty failure) already
+ * says it, so its dead globs are not counted, drawn or failed a second time.
+ * `--fail-on-dead-units` must never turn a soft-empty rule's `2` into a `1`.
+ * The report count, the ⚠ lines, the settle and the quality notes all read
+ * this one predicate.
+ */
+export declare function reportsDeadGlobs(r: IGateCoverage): boolean;
+/**
+ * THE dead units of a coverage row, each with its reason — what the ⚠ line,
+ * the `--fail-on-dead-units` violation and the `shrk quality` note all print,
+ * so the three cannot word one unit differently. A row built without
+ * `deadGlobUnits` (a hand-built report) falls back to its `deadGlobs` labels,
+ * read as inclusion globs that matched nothing.
+ */
+export declare function coverageDeadUnits(r: IGateCoverage): readonly ICoverageDeadGlob[];
+/**
+ * THE went-live units of a coverage row (round 13): each glob marked
+ * `expectEmpty` whose target now exists — the fence went live. What the ⚠
+ * `expectEmpty is stale` rows, the `--fail-on-dead-units` violation and the
+ * `shrk quality` note print.
+ */
+export declare function coverageWentLiveUnits(r: IGateCoverage): readonly IUnitLiveness[];
+/**
+ * The selector units that FAIL a coverage row under the given flags — decided
+ * by THE predicate every `--fail-on-dead-units` consumer calls
+ * (`selectorUnitFails`, core): an unmarked dead glob of a connected rule
+ * ({@link reportsDeadGlobs}), and a LOCAL went-live marker. A pack marker that
+ * went live is INFO, never a failure; an intended-empty unit never fails.
+ */
+export declare function coverageUnitFailures(r: IGateCoverage, flags: ISelectorUnitFailOptions): readonly {
+    readonly selector: string;
+    readonly message: string;
+}[];
+/** `declared: src/moved/*.ts (matched 0 files), !src/nowhere/** (excludes nothing — …)`. */
+export declare function formatDeadUnits(units: readonly ICoverageDeadGlob[]): string;
+/** `declared: !src/**\/*.spec.ts (1 file), !docs/drafts/** (3 files)`. */
+export declare function formatNegations(negations: readonly ICoverageNegation[]): string;
+/** Options for {@link settleGateCoverage}. */
+interface ISettleGateCoverageOptions {
+    /** `--fail-on-dead-units`: a dead glob inside a connected rule, or a local went-live marker, fails the run. */
+    readonly failOnDeadUnits?: boolean;
+}
+/**
+ * Settle a coverage report into the shared `gate` envelope — THE derivation of
+ * what `gates coverage` concludes.
+ *
+ * `gates coverage` and `shrk quality`'s coverage item both call this, so the
+ * pre-push bundle cannot pass a rule set the verb itself reports broken (a
+ * failed selfTest, a stale failOnEmpty selector, a partial rule). A rule that
+ * matched nothing is not-verified (2) by default; `failOnEmpty` on the rule
+ * makes it a failure (1); `failOnDeadUnits` makes a dead glob inside a
+ * connected rule — or a local marker whose target went live — a failure too
+ * (`selectorUnitFails`). Each rule's `expectEmpty` acceptance rides on its
+ * envelope rule (`unitAcceptance`) into the one settle.
+ */
+export declare function settleGateCoverage(report: IGateCoverageReport, options?: ISettleGateCoverageOptions): IGateEnvelope;
+export {};
 //# sourceMappingURL=rule-coverage.d.ts.map

package/dist/gates/rule-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/rule-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAQV,aAAa,EAEd,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAG,6BAAsC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,oBAAoB,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAyKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,WAAW,GAAE,SAAS,MAAM,EAAO,EACnC,UAAU,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAM,EACxD,aAAa,UAAQ,EACrB,UAAU,CAAC,EAAE,qBAAqB,GACjC,mBAAmB,CAOrB"}
+{"version":3,"file":"rule-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/rule-coverage.ts"],"names":[],"mappings":"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"}