@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/oracle.d.ts

@@ -1,5 +1,91 @@
-/** Absolute path to the pinned oracle fixture. */
-export declare const ORACLE_PATH: string;
+import type { DetectorResult } from "./engine-types.js";
+/** The vendored day158 snapshot. It is a FIXTURE for this tool's own tests and
+ * for an operator who names it explicitly with `--oracle`. It is NEVER a default:
+ * nothing in the run path reads it unless a caller passes this path in. */
+export declare const FIXTURE_ORACLE_PATH: string;
+export declare const ORACLE_DIR = ".backend-doctor";
+export declare const ORACLE_NAME = "vp-by-tool.csv";
+export declare const VR_ORACLE_NAME = "vr-by-tool.csv";
+export interface OracleFile {
+    status: "found";
+    path: string;
+    /** where the path came from: "flag" or "convention:<dir>". */
+    origin: string;
+}
+export interface OracleMissing {
+    status: "absent";
+    /** every path that was looked at, in order. */
+    searched: string[];
+    origin: string;
+}
+export type OracleLocation = OracleFile | OracleMissing;
+export interface OracleSelection {
+    target: string;
+    vp: OracleLocation;
+    vr: OracleLocation;
+    /** the writer-tier side-car R-10 reads (see WRITER_TIER_NAME). Optional so a
+     * caller that binds only the two oracles keeps working: when undefined, the
+     * side-car is derived beside the bound vp oracle at read time. */
+    writerTier?: OracleLocation;
+}
+/** The convention dirs for `target`, in search order, never above the repo root. */
+export declare function oracleDirs(target: string): string[];
+/** Derive the oracle for `target`. Pure over the filesystem; never reads this tool's own directory. */
+export declare function resolveOracle(target: string, opts?: {
+    oracle?: string;
+    vrOracle?: string;
+    writerTier?: string;
+}): OracleSelection;
+export declare const WRITER_TIER_NAME = "vp-writer-tier.csv";
+export declare const WRITER_TIER_COLUMNS: readonly ["outil", "writer_tier", "writer_gate"];
+export interface WriterTierEntry {
+    /** 1-based data-row index in the side-car. */
+    n: number;
+    outil: string;
+    writer_tier: string;
+    writer_gate: string;
+}
+export type WriterTierTable = {
+    status: "found";
+    path: string;
+    byTool: Map<string, WriterTierEntry[]>;
+} | {
+    status: "absent";
+    searched: string[];
+    origin: string;
+} | {
+    status: "unreadable";
+    path: string;
+    reason: string;
+};
+/** Parse one side-car. A missing required column or a row whose cell count
+ * differs from the header makes the WHOLE file unreadable — never a partial pass. */
+export declare function readWriterTierFile(path: string): WriterTierTable;
+/** The side-car bound for THIS run. Throws OracleAbsentError when no vp oracle is
+ * bound (R-10 then refuses like every oracle-backed rule); otherwise returns the
+ * table, or an `absent` record naming every path that was looked at. */
+export declare function readWriterTier(): WriterTierTable;
+/** One human line naming which oracle files a run used and where each came from. */
+export declare function describeOracle(sel: OracleSelection): string;
+/** Raised when an oracle-backed rule is asked to judge and no oracle describes the tree. */
+export declare class OracleAbsentError extends Error {
+    readonly which: "vp" | "vr";
+    readonly searched: string[];
+    constructor(which: "vp" | "vr", searched: string[], detail?: string);
+}
+/** Bind the oracle for this run. The CLI calls it once with the target's resolution. */
+export declare function activateOracle(sel: OracleSelection | null): void;
+/** The oracle currently bound, or null. */
+export declare function activeOracle(): OracleSelection | null;
+/** Path of the bound VP oracle, or throws OracleAbsentError. */
+export declare function requireOracle(): OracleFile;
+/** Path of the bound VR oracle, or throws OracleAbsentError. */
+export declare function requireVrOracle(): OracleFile;
+/** `oracle:<file>` naming the bound oracle in a result anchor, or `oracle:ABSENT`. */
+export declare function oracleLabel(): string;
+/** Run an oracle-backed detector body. An absent oracle is could-not-judge —
+ * never present, never non-conforming. Anything else propagates untouched. */
+export declare function refuseWithoutOracle(id: string, body: () => DetectorResult): DetectorResult;
 /** The eighteen audit columns, in file order. §2 of the standard maps contract
  * fields onto these column names. */
 export declare const ORACLE_COLUMNS: readonly ["table", "outil", "T2_verdict", "T2_composant_cible", "crud", "operation_detail", "search_mecanisme", "surface", "rbac_qui", "scope_enforcement", "namespace_ou_org", "tokens_estime_contexte", "doublon_alias", "rbac_coherence_table", "rbac_adjustment_needed", "table_purpose", "table_conserver_supprimer", "statut_suppression"];
@@ -23,7 +109,10 @@ export interface OracleRow {
 export declare function parseCsv(text: string): string[][];
 /** Build typed rows from raw parsed cells (header already removed). */
 export declare function toRows(dataRows: string[][]): OracleRow[];
-/** Memoized read of the real pinned oracle fixture. */
+/** Memoized read of one oracle CSV, keyed by path. */
+export declare function readOracleFile(path: string): OracleRow[];
+/** The rows of the oracle bound for THIS run (derived from the target).
+ * Throws OracleAbsentError when none is bound or none was found. */
 export declare function readOracle(): OracleRow[];
 /**
  * A real inventory row is one tool/table entry. The audit's trailing `TOTAL`

package/dist/oracle.js

@@ -5,12 +5,222 @@
 // The tree the engine's loadTree builds is .ts-only and does NOT contain this
 // CSV, so every first-wave detector ignores `tree` and consults this memoized
 // reader instead.
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { resolveTarget } from "./target.js";
 const here = dirname(fileURLToPath(import.meta.url));
-/** Absolute path to the pinned oracle fixture. */
-export const ORACLE_PATH = join(here, "..", "fixtures", "vp-by-tool-day158.csv");
+/** The vendored day158 snapshot. It is a FIXTURE for this tool's own tests and
+ * for an operator who names it explicitly with `--oracle`. It is NEVER a default:
+ * nothing in the run path reads it unless a caller passes this path in. */
+export const FIXTURE_ORACLE_PATH = join(here, "..", "fixtures", "vp-by-tool-day158.csv");
+// ---------------------------------------------------------------------------
+// ORACLE RESOLUTION — the oracle describes the TREE UNDER JUDGEMENT, so it is
+// found from the target the CLI was given, never from this tool's install dir.
+//
+// Rule (first hit wins, every candidate is listed in the refusal when none hits):
+//   1. an explicit path (`--oracle <file>` / `--vr-oracle <file>`). An explicit
+//      path that does not exist is a REFUSAL, never a silent fall-through.
+//   2. `<convexDir>/.backend-doctor/<name>`, then `<repoRoot>/.backend-doctor/<name>`,
+//      then `<target>/.backend-doctor/<name>` when the argument is neither — where
+//      repoRoot/convexDir come from resolveTarget (src/target.ts), so `convex` and
+//      `.` search the SAME list. Nothing ABOVE the repository root is ever read: a
+//      `.backend-doctor/` in a parent directory describes some other tree.
+// where <name> is `vp-by-tool.csv` (the target backend's own inventory) and
+// `vr-by-tool.csv` (the second backend R-40 compares against).
+// No oracle found => the oracle-backed rules return could-not-judge.
+// ---------------------------------------------------------------------------
+export const ORACLE_DIR = ".backend-doctor";
+export const ORACLE_NAME = "vp-by-tool.csv";
+export const VR_ORACLE_NAME = "vr-by-tool.csv";
+/** The convention dirs for `target`, in search order, never above the repo root. */
+export function oracleDirs(target) {
+    const scope = resolveTarget(target);
+    const dirs = [
+        ...(scope.convexDir ? [join(scope.convexDir, ORACLE_DIR)] : []),
+        join(scope.repoRoot, ORACLE_DIR),
+        join(scope.input, ORACLE_DIR),
+    ];
+    return [...new Set(dirs)];
+}
+function locate(target, name, explicit) {
+    if (explicit !== undefined) {
+        const p = resolve(explicit);
+        return existsSync(p)
+            ? { status: "found", path: p, origin: "flag" }
+            : { status: "absent", searched: [p], origin: "flag (explicit path does not exist)" };
+    }
+    const dirs = oracleDirs(target);
+    const searched = dirs.map((d) => join(d, name));
+    for (let i = 0; i < searched.length; i++) {
+        if (existsSync(searched[i])) {
+            return { status: "found", path: searched[i], origin: `convention:${dirs[i]}` };
+        }
+    }
+    return { status: "absent", searched, origin: "convention" };
+}
+/** Derive the oracle for `target`. Pure over the filesystem; never reads this tool's own directory. */
+export function resolveOracle(target, opts = {}) {
+    const t = resolve(target);
+    const vp = locate(t, ORACLE_NAME, opts.oracle);
+    return {
+        target: t,
+        vp,
+        vr: locate(t, VR_ORACLE_NAME, opts.vrOracle),
+        writerTier: locateWriterTier(vp, opts.writerTier),
+    };
+}
+// ---------------------------------------------------------------------------
+// WRITER-TIER SIDE-CAR — R-10's material.
+//
+// §2 splits authority into reader (R-5) and writer (R-10). The oracle's eighteen
+// columns carry ONE authority column (`rbac_qui`, the reader), and a 19th column
+// would make every row of every 18-column oracle malformed under toRows (measured
+// on vantage-peers: 108/108). So the writer tier travels in a SIDE-CAR beside the
+// oracle, joined by tool name (`outil`). Header-addressed, so a producer may add
+// columns; the three below are required.
+//
+// Resolution: an explicit `--writer-tier <file>` (missing => absent, never a
+// fall-through), else `<dirname(vp oracle)>/vp-writer-tier.csv`. A side-car that
+// is absent or unreadable makes every WRITE row could-not-judge, naming the file.
+// ---------------------------------------------------------------------------
+export const WRITER_TIER_NAME = "vp-writer-tier.csv";
+export const WRITER_TIER_COLUMNS = ["outil", "writer_tier", "writer_gate"];
+function locateWriterTier(vp, explicit) {
+    if (explicit !== undefined) {
+        const p = resolve(explicit);
+        return existsSync(p)
+            ? { status: "found", path: p, origin: "flag" }
+            : { status: "absent", searched: [p], origin: "flag (explicit path does not exist)" };
+    }
+    if (vp.status === "absent")
+        return { status: "absent", searched: [], origin: "no vp oracle to sit beside" };
+    const p = join(dirname(vp.path), WRITER_TIER_NAME);
+    return existsSync(p)
+        ? { status: "found", path: p, origin: `beside-oracle:${dirname(vp.path)}` }
+        : { status: "absent", searched: [p], origin: "beside-oracle" };
+}
+const writerCache = new Map();
+/** Parse one side-car. A missing required column or a row whose cell count
+ * differs from the header makes the WHOLE file unreadable — never a partial pass. */
+export function readWriterTierFile(path) {
+    const hit = writerCache.get(path);
+    if (hit)
+        return hit;
+    const raw = parseCsv(readFileSync(path, "utf8")).filter((r) => !(r.length === 1 && r[0] === ""));
+    const [header = [], ...data] = raw;
+    const cols = header.map((h) => h.trim());
+    const missing = WRITER_TIER_COLUMNS.filter((c) => !cols.includes(c));
+    let table;
+    if (missing.length > 0) {
+        table = { status: "unreadable", path, reason: `header lacks required column(s) ${missing.join(", ")}` };
+    }
+    else {
+        const bad = data.findIndex((cells) => cells.length !== cols.length);
+        if (bad !== -1) {
+            table = {
+                status: "unreadable",
+                path,
+                reason: `row ${bad + 1} has ${data[bad].length} cells, header has ${cols.length}`,
+            };
+        }
+        else {
+            const at = (c) => cols.indexOf(c);
+            const byTool = new Map();
+            data.forEach((cells, i) => {
+                const e = {
+                    n: i + 1,
+                    outil: cells[at("outil")].trim(),
+                    writer_tier: cells[at("writer_tier")].trim(),
+                    writer_gate: cells[at("writer_gate")].trim(),
+                };
+                byTool.set(e.outil, [...(byTool.get(e.outil) ?? []), e]);
+            });
+            table = { status: "found", path, byTool };
+        }
+    }
+    writerCache.set(path, table);
+    return table;
+}
+/** The side-car bound for THIS run. Throws OracleAbsentError when no vp oracle is
+ * bound (R-10 then refuses like every oracle-backed rule); otherwise returns the
+ * table, or an `absent` record naming every path that was looked at. */
+export function readWriterTier() {
+    const vp = requireOracle();
+    const loc = active?.writerTier ?? locateWriterTier(vp, undefined);
+    if (loc.status === "absent")
+        return { status: "absent", searched: loc.searched, origin: loc.origin };
+    return readWriterTierFile(loc.path);
+}
+/** One human line naming which oracle files a run used and where each came from. */
+export function describeOracle(sel) {
+    const one = (label, l) => l.status === "found"
+        ? `${label}=${l.path} (from ${l.origin})`
+        : `${label}=ABSENT (${l.origin}; searched: ${l.searched.join(", ")})`;
+    const wt = sel.writerTier ? `; ${one("writer-tier", sel.writerTier)}` : "";
+    return `oracle for target ${sel.target}: ${one("vp", sel.vp)}; ${one("vr", sel.vr)}${wt}`;
+}
+/** Raised when an oracle-backed rule is asked to judge and no oracle describes the tree. */
+export class OracleAbsentError extends Error {
+    which;
+    searched;
+    constructor(which, searched, detail) {
+        super(`no ${which === "vp" ? "target-backend" : "second-backend (VR)"} oracle describes this tree — ${detail ?? `searched: ${searched.join(", ")}`}`);
+        this.which = which;
+        this.searched = searched;
+        this.name = "OracleAbsentError";
+    }
+}
+let active = null;
+/** Bind the oracle for this run. The CLI calls it once with the target's resolution. */
+export function activateOracle(sel) {
+    active = sel;
+}
+/** The oracle currently bound, or null. */
+export function activeOracle() {
+    return active;
+}
+function requireLocation(which) {
+    if (!active) {
+        throw new OracleAbsentError(which, [], "no target was bound (activateOracle never called), so no oracle was derived");
+    }
+    const l = active[which];
+    if (l.status === "absent")
+        throw new OracleAbsentError(which, l.searched);
+    return l;
+}
+/** Path of the bound VP oracle, or throws OracleAbsentError. */
+export function requireOracle() {
+    return requireLocation("vp");
+}
+/** Path of the bound VR oracle, or throws OracleAbsentError. */
+export function requireVrOracle() {
+    return requireLocation("vr");
+}
+/** `oracle:<file>` naming the bound oracle in a result anchor, or `oracle:ABSENT`. */
+export function oracleLabel() {
+    const l = active?.vp;
+    return l && l.status === "found" ? `oracle:${basename(l.path)}` : "oracle:ABSENT";
+}
+/** Run an oracle-backed detector body. An absent oracle is could-not-judge —
+ * never present, never non-conforming. Anything else propagates untouched. */
+export function refuseWithoutOracle(id, body) {
+    try {
+        return body();
+    }
+    catch (e) {
+        if (!(e instanceof OracleAbsentError))
+            throw e;
+        const reason = `${id}: REFUSED TO JUDGE — ${e.message}. An absent oracle is neither a clean bill nor a violation; supply one with --oracle/--vr-oracle or place it under ${ORACLE_DIR}/.`;
+        return {
+            id,
+            anchor: `oracle:ABSENT (${e.which})`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+}
 /** The eighteen audit columns, in file order. §2 of the standard maps contract
  * fields onto these column names. */
 export const ORACLE_COLUMNS = [
@@ -106,16 +316,23 @@ export function toRows(dataRows) {
         return { n, cells, by };
     });
 }
-let cache = null;
-/** Memoized read of the real pinned oracle fixture. */
-export function readOracle() {
-    if (cache)
-        return cache;
-    const text = readFileSync(ORACLE_PATH, "utf8");
+const cache = new Map();
+/** Memoized read of one oracle CSV, keyed by path. */
+export function readOracleFile(path) {
+    const hit = cache.get(path);
+    if (hit)
+        return hit;
+    const text = readFileSync(path, "utf8");
     const raw = parseCsv(text).filter((r) => !(r.length === 1 && r[0] === ""));
     const [, ...data] = raw; // drop header
-    cache = toRows(data);
-    return cache;
+    const rows = toRows(data);
+    cache.set(path, rows);
+    return rows;
+}
+/** The rows of the oracle bound for THIS run (derived from the target).
+ * Throws OracleAbsentError when none is bound or none was found. */
+export function readOracle() {
+    return readOracleFile(requireOracle().path);
 }
 /**
  * A real inventory row is one tool/table entry. The audit's trailing `TOTAL`

package/dist/registry.d.ts

@@ -6,6 +6,13 @@ export interface RegistryEntry {
     ruleId: string;
     standardPin: string;
 }
+/**
+ * Merge two detectors that judge halves of the SAME rule into one result: the
+ * worst state wins (non-conforming > could-not-judge > absent > present, the
+ * tally's own ranking), the anchor is the deciding half's, the title is the LATER
+ * (refined) half's, and both halves' verdicts are kept — nothing is dropped.
+ */
+export declare function mergeHalves(ruleId: string, a: Detector, b: Detector): Detector;
 export declare const REGISTRY: RegistryEntry[];
 /** The rule ids this wave mechanically CHECKS — derived from the registry. */
 export declare function checkedRuleIds(): string[];

package/dist/registry.js

@@ -20,8 +20,38 @@ import { R41, SIBLING_PIN } from "./detectors/standard/r41-frontier.js";
 import { R46_STANDARD_PIN, STANDARD_SOURCE_DETECTORS, } from "./detectors/standard/r46-returns-validator.js";
 import { STANDARD_DOC_DETECTORS } from "./detectors/standard/standard-doc.js";
 import { makeR14, makeR38 } from "./detectors/structural.js";
+import { STATE_RANK } from "./state-rank.js";
 /** The standard both pins the whole wave against. */
 export const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4bcd605656ceff52d4f1593a9176cd6b988471be (elpiarthera/ElPi-Corp)";
+/**
+ * Merge two detectors that judge halves of the SAME rule into one result: the
+ * worst state wins (non-conforming > could-not-judge > absent > present, the
+ * tally's own ranking), the anchor is the deciding half's, the title is the LATER
+ * (refined) half's, and both halves' verdicts are kept — nothing is dropped.
+ */
+export function mergeHalves(ruleId, a, b) {
+    return {
+        id: b.id,
+        run: (tree) => {
+            const ra = a.run(tree);
+            const rb = b.run(tree);
+            const decider = STATE_RANK[ra.state] > STATE_RANK[rb.state] ? ra : rb;
+            const verdict = `${ruleId} (two halves, worst wins): [${ra.id}] ${ra.state} — ${ra.verdict} || [${rb.id}] ${rb.state} — ${rb.verdict}`;
+            const reasons = [ra, rb]
+                .filter((r) => r.state === "could-not-judge")
+                .map((r) => r.reason ?? r.verdict);
+            return {
+                id: b.id,
+                anchor: decider.anchor,
+                state: decider.state,
+                verdict,
+                ...(decider.state === "could-not-judge"
+                    ? { reason: reasons.join(" || ") }
+                    : {}),
+            };
+        },
+    };
+}
 export const REGISTRY = [
     ...PER_ROW_PREDICATES.map((spec) => ({
         detector: makeOracleDetector(spec),
@@ -51,7 +81,7 @@ export const REGISTRY = [
     {
         detector: makeR40(),
         ruleId: "R-40",
-        standardPin: `${STANDARD_PIN} + oracle:vr-by-tool-day159.csv @ a74a042b`,
+        standardPin: `${STANDARD_PIN} + second-backend oracle derived from the target (vr-by-tool.csv / --vr-oracle)`,
     },
     // The twenty source-tree detectors (built all at once — the wave plan cancelled).
     // Each reads the REAL convex/ source; R-6/R-16 also carry a live half. Their
@@ -121,11 +151,23 @@ export const REGISTRY = [
         // VENDORED standard itself, performs its mechanical/static half in full, and
         // returns could-not-judge naming the sites a human/gate verdict is owed on.
         ...STANDARD_DOC_DETECTORS,
-    ].map((e) => ({
-        detector: e.detector,
-        ruleId: e.ruleId,
-        standardPin: STANDARD_PIN,
-    })),
+    ].reduce((acc, e) => {
+        // ONE result per rule. Two modules carry an R-31 half (writesafety: the
+        // bulk-WRITE self-schedule; readbudget: the refined read+write budget), and
+        // both used to print as two R-31 rows under two different titles. They are
+        // merged into one row titled by the refined standard text (4bcd605 :266).
+        const prev = acc.find((x) => x.ruleId === e.ruleId);
+        if (prev) {
+            prev.detector = mergeHalves(e.ruleId, prev.detector, e.detector);
+            return acc;
+        }
+        acc.push({
+            detector: e.detector,
+            ruleId: e.ruleId,
+            standardPin: STANDARD_PIN,
+        });
+        return acc;
+    }, []),
     // R-41 — the ONE fully-mechanical rule of the nine: it reads the backend
     // standard's §9 frontier AND the four vendored MCP-family siblings, resolving
     // every cited S-/C-/E-/A- id against its sibling's defined-id set. present when

package/dist/report.d.ts

@@ -17,6 +17,8 @@ export interface ReportContext {
      * bit a reviewer). Empty string means a clean tree.
      */
     treeStatus: string;
+    /** which oracle files the run used and where each came from (describeOracle). Optional so older callers still compile. */
+    oracle?: string;
 }
 /** Derive the committed report path from the target basename + the run date. */
 export declare function reportPath(target: string, dateISO: string, dir: string): string;
@@ -32,4 +34,12 @@ export declare function buildReport(ctx: ReportContext, results: DetectorResult[
  * <dir> if needed. Returns the absolute path written. The caller (CLI) supplies the
  * ReportContext (clock + git) and the computed tally/verdict.
  */
-export declare function writeReport(ctx: ReportContext, results: DetectorResult[], t: Tally, v: Verdict, dir: string, severity?: Map<string, Severity>): string;
+export declare function writeReport(ctx: ReportContext, results: DetectorResult[], t: Tally, v: Verdict, dir: string, severity?: Map<string, Severity>, 
+/**
+ * Doctor-owned sections appended VERBATIM after the rule tables, each in its
+ * own fence. CR-1 renders through here: its contract is that every member of
+ * every class is NAMED, and the truncation that hid thirteen of fourteen
+ * violations is the defect that contract exists not to repeat — so this
+ * carries the section's own text rather than re-deriving or summarising it.
+ */
+extraSections?: string[]): string;

package/dist/report.js

@@ -94,6 +94,7 @@ export function buildReport(ctx, results, t, v, severity = deriveSeverityMap())
 - **target commit**: \`${ctx.targetCommit}\`
 - **standard commit** (pinned): \`${STANDARD_SHA}\`
 - **tool version**: \`${ctx.toolVersion}\`
+- **oracle**: ${ctx.oracle ?? "(not recorded)"}
 - **run date**: ${ctx.dateISO}
 - **machine tally**: \`${tallyLine(t)}\`
 - **verdict**: ${v.summary}
@@ -130,9 +131,21 @@ ${present.length === 0 ? "_none._" : present.join(", ")}
  * <dir> if needed. Returns the absolute path written. The caller (CLI) supplies the
  * ReportContext (clock + git) and the computed tally/verdict.
  */
-export function writeReport(ctx, results, t, v, dir, severity = deriveSeverityMap()) {
+export function writeReport(ctx, results, t, v, dir, severity = deriveSeverityMap(), 
+/**
+ * Doctor-owned sections appended VERBATIM after the rule tables, each in its
+ * own fence. CR-1 renders through here: its contract is that every member of
+ * every class is NAMED, and the truncation that hid thirteen of fourteen
+ * violations is the defect that contract exists not to repeat — so this
+ * carries the section's own text rather than re-deriving or summarising it.
+ */
+extraSections = []) {
     mkdirSync(dir, { recursive: true });
     const path = reportPath(ctx.target, ctx.dateISO, dir);
-    writeFileSync(path, buildReport(ctx, results, t, v, severity), "utf8");
+    const body = [
+        buildReport(ctx, results, t, v, severity),
+        ...extraSections.map((sec) => `\n\n\`\`\`\n${sec}\n\`\`\`\n`),
+    ].join("");
+    writeFileSync(path, body, "utf8");
     return path;
 }

package/dist/state-rank.d.ts

@@ -0,0 +1,5 @@
+import type { State } from "./engine-types.js";
+/** The four states, worst highest — every reduction (tally, a merged rule) picks
+ * the worst. A module of its own so registry.ts can use it without a cycle
+ * through tally -> coverage -> registry. */
+export declare const STATE_RANK: Record<State, number>;

package/dist/state-rank.js

@@ -0,0 +1,9 @@
+/** The four states, worst highest — every reduction (tally, a merged rule) picks
+ * the worst. A module of its own so registry.ts can use it without a cycle
+ * through tally -> coverage -> registry. */
+export const STATE_RANK = {
+    "non-conforming": 3,
+    "could-not-judge": 2,
+    absent: 1,
+    present: 0,
+};

package/dist/tally.d.ts

@@ -53,5 +53,40 @@ export interface Verdict {
  * on an exit that means abstention.
  */
 export declare function verdict(t: Tally, results: DetectorResult[], severity?: Map<string, Severity>): Verdict;
+/**
+ * The HANDLER-SURFACE rules — the source/*-isolation detectors that judge the
+ * public query/mutation surface (R-50 read-isolation, R-51 write-isolation).
+ * Reported APART from the document/oracle/process rules (R-32, R-37, R-40,
+ * R-48, …) so the handler-surface could-not-judge count is visible on its own
+ * and can be driven to 0 without conflating it with honest human-gate CNJ.
+ * Laurent doctrine: an instrument that cannot go red protects nothing — the
+ * handler-surface CNJ must reach 0 except genuine parse-fail / marker-borne /
+ * ambiguous-domination sites.
+ */
+export declare const HANDLER_SURFACE_RULES: readonly string[];
+export interface HandlerSurfaceStats {
+    byState: Record<State, number>;
+    /** rule-level state per handler-surface ruleId (worst across its results). */
+    ruleState: Map<string, State>;
+    /** the handler-surface could-not-judge RULE count — R-50/R-51 as rules abstain
+     *  or they don't. This is 0 whenever both rules reach a verdict, EVEN when the
+     *  underlying sites include abstaining ones — so it must never be printed alone. */
+    couldNotJudge: number;
+    /** the handler-surface could-not-judge SITE count — the sum of every rule's
+     *  scan.cnj length, parsed from each result's `could-not-judge=N` breakdown. A
+     *  non-conforming rule can still carry abstaining SITES (Eta REVISE blocker 2:
+     *  the CRM run had rules-abstaining=0 while 8 sites abstained). Both are printed. */
+    sitesAbstaining: number;
+}
+/**
+ * The handler-surface slice of the tally, computed over HANDLER_SURFACE_RULES
+ * only. Reduces each rule to its worst result state (same reduction as `tally`)
+ * so a rule with any non-conforming result reads non-conforming, and surfaces a
+ * distinct handler-surface could-not-judge count the CLI prints separately.
+ */
+export declare function handlerSurfaceStats(results: DetectorResult[], handlerRules?: readonly string[]): HandlerSurfaceStats;
+/** The one-line handler-surface tally string the CLI prints, apart from the
+ *  document/oracle/process rules. */
+export declare function handlerSurfaceLine(s: HandlerSurfaceStats): string;
 /** The one-line machine tally string the CLI prints. */
 export declare function tallyLine(t: Tally): string;