@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/structural.js

@@ -1,51 +1,81 @@
 // The two STRUCTURAL detectors — R-14 and R-38. They judge the inventory SCHEMA
-// against the §2 contract, not a single row. Run against THIS oracle they MUST
-// return `non-conforming`, because §2 splits authority into two distinct fields
-// (reader R-5, writer R-10) and the oracle carries a SINGLE merged `rbac_qui`
-// column. Agreeing with the oracle here would be certifying the defect the
-// instrument exists to find — so these are NOT tuned to pass.
-import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, WRITER_AUTHORITY_COLUMN, authorityIsMerged } from "../contract.js";
-import { ORACLE_COLUMNS, readOracle } from "../oracle.js";
-const CSV_ANCHOR = "oracle:vp-by-tool-day158.csv col#9 rbac_qui";
+// against the §2 contract, not a single row.
+//
+// §2 splits authority into two contract fields (reader R-5, writer R-10). The
+// oracle carries ONE authority column, `rbac_qui`; writer authority has a column
+// of its own only through the writer-tier side-car (`writer_tier`, joined on
+// `outil` — see resolveAuthoritySplit in src/contract.ts). So:
+//   side-car absent, or missing a write tool -> non-conforming (merged/omitted)
+//   side-car unreadable                      -> could-not-judge
+//   side-car complete over every write tool  -> the split is declared
+// An oracle alone is never green here: agreeing with a merged column would be
+// certifying the defect the instrument exists to find.
+import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, resolveAuthoritySplit, SPLIT_WRITER_AUTHORITY_COLUMN, } from "../contract.js";
+import { isInventoryRow, ORACLE_COLUMNS, oracleLabel, readOracle, readWriterTier, refuseWithoutOracle, requireOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
+import { WRITE_VERBS } from "./shared.js";
+const csvAnchor = () => `${oracleLabel()} col#9 rbac_qui`;
+function splitFor(rows, sideCar) {
+    const writeTools = rows
+        .filter(isInventoryRow)
+        .filter((r) => WRITE_VERBS.has(r.by.crud))
+        .map((r) => r.by.outil);
+    return resolveAuthoritySplit(writeTools, sideCar());
+}
+function unjudgeable(id, reason) {
+    const verdict = `${id.split(" ")[0]}: could not judge — ${reason}.`;
+    return { id, anchor: csvAnchor(), state: "could-not-judge", verdict, reason: verdict };
+}
 /**
  * R-14 — inventory-schema parity, contract → inventory, one direction.
  * A merged reader/writer authority column is "non-conforming by construction"
- * (§12). The oracle's column 9 `rbac_qui` is that single merged column.
+ * (§12). Writer authority is a separate column only when the side-car declares it.
  */
-export function makeR14(columns = ORACLE_COLUMNS) {
+export function makeR14(columns = ORACLE_COLUMNS, rowsProvider = readOracle, sideCar = readWriterTier) {
+    const id = "R-14 inventory-schema parity";
     return {
-        id: "R-14 inventory-schema parity",
-        run: () => {
-            const authorityColumns = columns.filter((c) => c === "rbac_qui");
-            if (authorityIsMerged() || authorityColumns.length < 2) {
-                return {
-                    id: "R-14 inventory-schema parity",
-                    anchor: CSV_ANCHOR,
+        id,
+        // The verdict is about the oracle's schema, so with no oracle bound there is
+        // no subject: refuse (could-not-judge), never a verdict on the tool's own constant.
+        run: () => refuseWithoutOracle(id, () => {
+            requireOracle();
+            const missing = CONTRACT_FIELDS.flatMap((f) => f.columns.filter((c) => !columns.includes(c)).map((c) => `${f.field}→${c}`));
+            const split = splitFor(rowsProvider(), sideCar);
+            if (split.kind === "unjudgeable")
+                return unjudgeable(id, split.reason);
+            if (split.kind === "merged" || missing.length > 0) {
+                return withCount({
+                    id,
+                    anchor: csvAnchor(),
                     state: "non-conforming",
-                    verdict: "R-14: the inventory holds a SINGLE merged authority column `rbac_qui` (col#9), " +
-                        "but §2 splits authority into two distinct contract fields — reader authority (R-5) " +
-                        "and writer authority (R-10). A merged authority column is non-conforming by construction: " +
-                        "the reader/writer divergence R-10 and R-7 exist to record cannot be written in it.",
-                };
+                    verdict: "R-14: §2 splits authority into two distinct contract fields — reader authority (R-5) " +
+                        `and writer authority (R-10) — but the inventory's only authority column is \`${READER_AUTHORITY_COLUMN}\` (col#9)` +
+                        (split.kind === "merged" ? `: ${split.reason}. ` : ". ") +
+                        "A merged authority column is non-conforming by construction: the reader/writer divergence " +
+                        "R-10 and R-7 exist to record cannot be written in it." +
+                        (missing.length ? ` Also missing: ${missing.join(", ")}.` : ""),
+                }, itemCount(1));
             }
             return {
-                id: "R-14 inventory-schema parity",
-                anchor: "oracle:vp-by-tool-day158.csv",
+                id,
+                anchor: `${oracleLabel()} + ${split.sideCar}`,
                 state: "present",
-                verdict: "R-14: every §2 contract field present; reader and writer authority are two separate columns.",
+                verdict: `R-14: every §2 contract field present; reader authority is \`${READER_AUTHORITY_COLUMN}\`, writer authority is ` +
+                    `\`${SPLIT_WRITER_AUTHORITY_COLUMN}\` in ${split.sideCar}, recorded for all ${split.writeTools} write tools.`,
             };
-        },
+        }),
     };
 }
 /**
- * R-38 — the completeness gate over the thirteen §2 fields. The oracle cannot
- * satisfy the contract because reader and writer authority are not two separate
- * fields (both map to `rbac_qui`).
+ * R-38 — the completeness gate over the thirteen §2 fields. Writer authority is
+ * complete only when the side-car records a tier for every write tool.
  */
-export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
+export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle, sideCar = readWriterTier) {
+    const id = "R-38 thirteen-field completeness";
     return {
-        id: "R-38 thirteen-field completeness",
-        run: () => {
+        id,
+        run: () => refuseWithoutOracle(id, () => {
+            requireOracle();
             const colSet = new Set(columns);
             const missing = [];
             for (const f of CONTRACT_FIELDS) {
@@ -54,30 +84,36 @@ export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
                         missing.push(`${f.field}→${col}`);
                 }
             }
-            const authorityMerged = READER_AUTHORITY_COLUMN === WRITER_AUTHORITY_COLUMN && colSet.has(READER_AUTHORITY_COLUMN);
-            if (authorityMerged || missing.length > 0) {
-                const rows = rowsProvider();
+            const rows = rowsProvider();
+            const split = splitFor(rows, sideCar);
+            if (split.kind === "unjudgeable")
+                return unjudgeable(id, split.reason);
+            if (split.kind === "merged" || missing.length > 0) {
+                const uncovered = split.kind === "merged" ? new Set(split.uncovered) : new Set();
                 const sample = rows
-                    .filter((r) => !r.malformed && r.by.rbac_qui && r.by.table !== "TOTAL")
+                    .filter((r) => isInventoryRow(r) && r.by.rbac_qui && (uncovered.size === 0 || uncovered.has(r.by.outil)))
                     .slice(0, 3)
                     .map((r) => `row#${r.n} "${r.by.outil || r.by.table}" rbac_qui="${r.by.rbac_qui}"`)
                     .join("; ");
-                return {
-                    id: "R-38 thirteen-field completeness",
-                    anchor: CSV_ANCHOR,
+                return withCount({
+                    id,
+                    anchor: csvAnchor(),
                     state: "non-conforming",
-                    verdict: `R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and ` +
-                        `writer authority (R-10) are not two separate fields; both map to the single column ` +
-                        `\`rbac_qui\` (col#9).${missing.length ? ` Also missing: ${missing.join(", ")}.` : ""} ` +
-                        `Evidence: ${sample}.`,
-                };
+                    verdict: "R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and " +
+                        `writer authority (R-10) are not two separate fields for every tool; writer authority falls back to ` +
+                        `\`${READER_AUTHORITY_COLUMN}\` (col#9)` +
+                        (split.kind === "merged" ? `: ${split.reason}.` : ".") +
+                        (missing.length ? ` Also missing: ${missing.join(", ")}.` : "") +
+                        ` Evidence: ${sample}.`,
+                }, itemCount(1));
             }
             return {
-                id: "R-38 thirteen-field completeness",
-                anchor: "oracle:vp-by-tool-day158.csv",
+                id,
+                anchor: `${oracleLabel()} + ${split.sideCar}`,
                 state: "present",
-                verdict: "R-38: all thirteen §2 contract fields present per table, each within its vocabulary.",
+                verdict: "R-38: all thirteen §2 contract fields present per table; writer authority is " +
+                    `\`${SPLIT_WRITER_AUTHORITY_COLUMN}\` in ${split.sideCar} for all ${split.writeTools} write tools.`,
             };
-        },
+        }),
     };
 }

package/dist/not-checkable.d.ts

@@ -1,3 +1,4 @@
+import type { DetectorResult } from "./engine-types.js";
 /**
  * The deferral bucket. R-1..R-47 each carry an executable control (registry.ts),
  * so none is deferred to "a human decides". R-48 (authority-totality, the #130
@@ -9,7 +10,6 @@
  * moves to registry.ts and this entry is removed. The export is consumed by
  * coverage.ts / coverage-cli.ts / cli.ts.
  */
-import type { DetectorResult } from "./engine-types.js";
 export declare const NOT_MECHANICALLY_CHECKABLE: Record<string, string>;
 /**
  * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so

package/dist/not-checkable.js

@@ -15,6 +15,17 @@
 // input is vendored. They were built, not relabelled. The bucket was not renamed to a
 // gentler word — it was emptied.
 import { STANDARD_FILE } from "./detectors/standard/_doc.js";
+/**
+ * The deferral bucket. R-1..R-47 each carry an executable control (registry.ts),
+ * so none is deferred to "a human decides". R-48 (authority-totality, the #130
+ * class) was added to the standard at the 51ec7af1 re-pin AFTER its detector; its
+ * text is now pinned so coverage enumerates 48, but no detector exists yet — so it
+ * is reported here as NOT_MECHANICALLY_CHECKABLE with a written reason rather than
+ * silently omitted, which would let coverage pretend 47 is the whole document. The
+ * detector is task k17chpr4kzp399j3s7r7edpm4s8cscbz (after D5); when it lands, R-48
+ * moves to registry.ts and this entry is removed. The export is consumed by
+ * coverage.ts / coverage-cli.ts / cli.ts.
+ */
 export const NOT_MECHANICALLY_CHECKABLE = {
     "R-48": "R-48 authority-totality detector pending — task k17chpr4kzp399j3s7r7edpm4s8cscbz; text pinned at 4bcd605 so coverage cannot pretend 47 is complete. No mechanical control yet; R-48 is enumerated and visible, never silently dropped.",
 };

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

@@ -1,11 +1,18 @@
 import type { Detector } from "./engine-types.js";
 /** The standard both pins the whole wave against. */
-export declare const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4bcd605656ceff52d4f1593a9176cd6b988471be (elpiarthera/ElPi-Corp)";
+export declare const STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ 2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3 (elpiarthera/ElPi-Corp, merge of PR #228 on origin/main, after #226 at 9f7d789)";
 export interface RegistryEntry {
     detector: Detector;
     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[];