@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/cli.js

@@ -5,17 +5,25 @@
 // DISTINCTLY. The target is a real directory so the engine's loadTree succeeds;
 // the first-wave detectors ignore the tree and consult the oracle.
 import { execFileSync } from "node:child_process";
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderTable, runDoctor } from "@vantageos/mcp-doctor";
-import { coverage, coverageSummary } from "./coverage.js";
+import { parseArgs, USAGE } from "./args.js";
+import { checkDistFreshness } from "./build-stamp.js";
+import { CR1_ID, callerResolutionResult, callerResolutionSection, violations as crViolations, scanCallerResolution, } from "./caller-resolution.js";
+import { coverage, coverageSummary, deriveRuleIds } from "./coverage.js";
 import { crudCoverageSection, extractReactRouterPaths, scanCrudCoverage, } from "./crud-coverage.js";
+import { CR2_ID, localIdentityResult, localIdentitySection, scanLocalIdentity, } from "./detectors/source/local-identity.js";
 import { checkStandardReadable } from "./detectors/standard/_doc.js";
 import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults, } from "./not-checkable.js";
+import { activateOracle, describeOracle, resolveOracle } from "./oracle.js";
 import { REGISTRY } from "./registry.js";
 import { writeReport } from "./report.js";
+import { buildEvidence, classifyRules, countMechanical, mechanicalLine, } from "./rule-class.js";
 import { handlerSurfaceLine, handlerSurfaceStats, tally, tallyLine, verdict, } from "./tally.js";
+import { describeScope, loadScopedTree, onScopedTree, resolveTarget, } from "./target.js";
+import { mechanicalRuleCounts, mechanicalRuleCountsLine, } from "./violation-count.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** `git -C <target> rev-parse HEAD`, or "not a git repo" when it is not one. */
 function targetCommit(target) {
@@ -39,6 +47,41 @@ function treeStatus(target) {
         return "not a git repo";
     }
 }
+/** The instrument's own identity for the evidence file: the backend-doctor
+ * checkout's HEAD when this module runs from its own git checkout (`+dirty` when
+ * src/ or fixtures/ differ from it), else the published package version. Never the
+ * HEAD of a repository that merely CONTAINS an installed copy. */
+function cliCommit() {
+    const root = resolve(here, "..");
+    try {
+        const top = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (resolve(top) !== root)
+            throw new Error("not this checkout");
+        const head = execFileSync("git", ["-C", root, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+        }).trim();
+        const dirty = execFileSync("git", ["-C", root, "status", "--porcelain", "--", "src", "fixtures"], { encoding: "utf8" }).trim();
+        return dirty ? `${head}+dirty` : head;
+    }
+    catch {
+        return `npm @vantageos/backend-doctor@${toolVersion()}`;
+    }
+}
+/** `git -C <dir> <args>` trimmed, or undefined when git refuses. */
+function gitOut(dir, args) {
+    try {
+        return execFileSync("git", ["-C", dir, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
 function toolVersion() {
     const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
     return pkg.version;
@@ -148,7 +191,49 @@ function probeRoutes(target) {
     return { candidateDir, routePaths };
 }
 function main() {
-    const target = resolve(process.argv[2] ?? process.cwd());
+    // Refuse to judge from a dist/ compiled from other source than this checkout's
+    // (src/build-stamp.ts). Runs before anything is read, so no verdict is printed.
+    // Flags first: --version/--help answer without reading a target, and an unknown
+    // flag is a usage error — never a path handed to the filesystem (an `-v` used to
+    // become `<cwd>/-v` and die on an uncaught ENOENT stack).
+    const args = parseArgs(process.argv.slice(2));
+    if (args.kind === "version") {
+        console.log(toolVersion());
+        process.exit(0);
+    }
+    if (args.kind === "help") {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    if (args.kind === "usage-error") {
+        console.error(`backend-doctor: ${args.message}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    const fresh = checkDistFreshness(here);
+    if (!fresh.ok) {
+        console.error(`backend-doctor: REFUSING TO RUN — ${fresh.reason}`);
+        process.exit(2);
+    }
+    const target = resolve(args.positional[0] ?? process.cwd());
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        console.error(`backend-doctor: target ${target} is not a readable directory — could not judge.\n\n${USAGE}`);
+        process.exit(2);
+    }
+    // ONE normalisation (src/target.ts): `convex` and `.` resolve to the same repo
+    // root, convex dir and file set, so every rule sees the same rels either way.
+    const scope = resolveTarget(target);
+    const tree = loadScopedTree(scope);
+    console.log(describeScope(scope, tree));
+    // The oracle is DERIVED from the target (never from this tool's own install
+    // directory) and the run says which file it used and where that came from.
+    // Absent => the oracle-backed rules refuse to judge (could-not-judge).
+    const oracleSel = resolveOracle(target, {
+        oracle: args.flags.oracle,
+        vrOracle: args.flags["vr-oracle"],
+        writerTier: args.flags["writer-tier"],
+    });
+    activateOracle(oracleSel);
+    console.log(describeOracle(oracleSel));
     // Instrument self-check, BEFORE any judging: a backend-doctor run reads its
     // pinned standard fixture as material. If that fixture is absent/unreadable the
     // tool cannot judge — REFUSE with exit 2 (could-not-judge) naming what it could
@@ -163,18 +248,64 @@ function main() {
     // pending detector) — so the tally's rule total equals the 48 derived rules and
     // nothing is silently dropped.
     const results = [
-        ...runDoctor(target, REGISTRY.map((e) => e.detector)),
+        ...runDoctor(scope.repoRoot, onScopedTree(tree, REGISTRY.map((e) => e.detector))),
         ...notCheckableResults(),
     ];
-    console.log(renderTable("backend-doctor (VantagePeers oracle @ day158)", results));
+    console.log(renderTable("backend-doctor (oracle derived from target)", results));
     // CRUD COVERAGE — an inventory/coverage report DIMENSION (not a numbered rule
     // in the pinned 50-rule standard). Rows are EVERY defineTable table derived
     // from the target schema at run time; the union of rows MUST equal the schema
     // table set or the run is RED (fail-closed).
     console.log("");
-    const crud = scanCrudCoverageForCli(target);
+    const crud = scanCrudCoverageForCli(scope.convexDir ?? target);
     console.log(crudCoverageSection(crud));
     const crudDefect = crud.status === "unreadable" || !crud.unionEqualsSchema;
+    // CALLER RESOLUTION (CR-1) — a DOCTOR-OWNED CRITICAL control, reported in its own
+    // section for the same reason CRUD coverage is: the pinned standard numbers
+    // R-1..R-51 and does not define it, so putting it in REGISTRY would make
+    // coverage.ts report a phantom rule and would forge the standard's pin. It is run
+    // through the engine's OWN loader (never a second tree traversal) and its
+    // violations drive the exit code — an unjustified NO-IDENTITY or a FAIL-OPEN
+    // registration is mechanical, so the gate refuses on it.
+    console.log("");
+    let crScan;
+    runDoctor(scope.repoRoot, onScopedTree(tree, [
+        {
+            id: CR1_ID,
+            run: (t) => {
+                crScan = scanCallerResolution(t);
+                return callerResolutionResult(crScan);
+            },
+        },
+    ]));
+    if (crScan === undefined) {
+        console.error("CR-1: the engine did not run the caller-resolution detector — refusing to report a surface that was never scanned.");
+        process.exit(2);
+    }
+    console.log(callerResolutionSection(crScan));
+    const crResult = callerResolutionResult(crScan);
+    const crDefect = crViolations(crScan).length > 0;
+    // LOCAL IDENTITY (CR-2) — DOCTOR-OWNED mechanical control, same footing as
+    // CR-1: no application defines its own identity primitive; identity lives
+    // only in @vantageos/cloud-identity. Ceiling 0 — any violation exits non-zero.
+    console.log("");
+    let liScan;
+    runDoctor(scope.repoRoot, onScopedTree(tree, [
+        {
+            id: CR2_ID,
+            run: (t) => {
+                liScan = scanLocalIdentity(t.files);
+                return localIdentityResult(liScan);
+            },
+        },
+    ]));
+    if (liScan === undefined) {
+        console.error("CR-2: the engine did not run the local-identity detector — refusing to report a surface that was never scanned.");
+        process.exit(2);
+    }
+    console.log(localIdentitySection(liScan));
+    const liResult = localIdentityResult(liScan);
+    const liDefect = liScan.violate.length > 0;
     console.log("");
     const cov = coverage();
     console.log(coverageSummary(cov));
@@ -199,36 +330,137 @@ function main() {
     // process rules, so its could-not-judge count is visible on its own and can be
     // driven to 0 (Laurent: an instrument that cannot go red protects nothing).
     console.log(handlerSurfaceLine(handlerSurfaceStats(results)));
+    console.log(`CALLER-RESOLUTION TALLY (CR-1, doctor-owned, outside the pinned rule set): state=${crResult.state} violations=${crViolations(crScan).length} | ${crResult.verdict.split("\n")[0]}`);
+    console.log(`LOCAL-IDENTITY TALLY (CR-2, doctor-owned, outside the pinned rule set): state=${liResult.state} violations=${liScan.violate.length} exempt=${liScan.exempt.length} could-not-judge=${liScan.cnj.length}`);
     console.log(v.summary);
     if (v.criticalViolations > 0) {
         console.log(`  critical violations: ${v.violations.critical.join(", ")}`);
     }
     if (v.criticalAbstentions > 0) {
-        console.log(`  critical abstentions (human verdict owed): ${v.abstentions.critical.join(", ")}`);
+        console.log(`  critical abstentions (not decided; each rule names why): ${v.abstentions.critical.join(", ")}`);
+    }
+    // The process exit code, decided ONCE so the evidence file records the code the
+    // process actually exits with. Order matches the NOTE lines printed below.
+    let exitCode = v.exitCode;
+    if (!cov.ok || crudDefect || crDefect || liDefect)
+        exitCode = 1;
+    // CR-2 abstaining (an unparsable file) is never a pass.
+    if (exitCode === 0 && liResult.state === "could-not-judge")
+        exitCode = 2;
+    // MECHANICAL VIOLATIONS — the deploy gate's only refusal driver. The class of
+    // each rule is DATA (fixtures/rule-classes-<pin>.json, cross-checked against the
+    // pinned standard in src/rule-class.ts). Instrument self-defects and an
+    // unclassified rule make the count null (could-not-judge), never 0.
+    const convexPath = scope.convexDir ?? target;
+    const repoOfConvex = scope.convexDir
+        ? dirname(scope.convexDir)
+        : scope.repoRoot;
+    const instrumentDefects = [];
+    if (!cov.ok)
+        instrumentDefects.push(coverageSummary(cov));
+    if (crudDefect)
+        instrumentDefects.push("CRUD coverage self-check failed (rows do not cover every schema table, or the schema is unreadable)");
+    // CR1_ID is the detector's full label; its rule id is the leading `CR-N` token.
+    const cr1Rule = /^CR-\d+/.exec(CR1_ID)?.[0] ?? CR1_ID;
+    const cr2Rule = /^CR-\d+/.exec(CR2_ID)?.[0] ?? CR2_ID;
+    const classification = classifyRules([...deriveRuleIds(), cr1Rule, cr2Rule]);
+    const ruleStates = new Map(t.ruleState);
+    ruleStates.set(cr1Rule, crResult.state);
+    ruleStates.set(cr2Rule, liResult.state);
+    const evidencePath = args.flags["json-evidence"];
+    let evidenceSha;
+    if (evidencePath !== undefined) {
+        evidenceSha = gitOut(repoOfConvex, ["rev-parse", "HEAD"]);
+        const dirty = gitOut(convexPath, [
+            "status",
+            "--porcelain",
+            "--untracked-files=all",
+            "--",
+            ".",
+        ]);
+        if (evidenceSha !== undefined && dirty === undefined)
+            instrumentDefects.push(`git status of ${convexPath} failed — whether the judged tree equals HEAD cannot be shown`);
+        else if (dirty)
+            instrumentDefects.push(`the judged convex tree differs from HEAD ${evidenceSha?.slice(0, 12)} (${dirty.split("\n").length} path(s) modified or untracked) — the count would describe bytes the sha does not name`);
+    }
+    const mech = countMechanical(ruleStates, classification, instrumentDefects);
+    if (mech.count === null && exitCode === 0)
+        exitCode = 2;
+    console.log(mechanicalLine(mech));
+    // Per red mechanical rule, the count its report line printed — read from the
+    // result the detector returned (src/violation-count.ts), never from the text.
+    const ruleCounts = mechanicalRuleCounts([...results, crResult, liResult], mech);
+    console.log(mechanicalRuleCountsLine(ruleCounts));
+    if (classification.stale.length > 0) {
+        console.log(`  STALE SIDECAR ENTRIES (name no rule of this run): ${classification.stale.join(", ")}`);
     }
     // The run WRITES its report to a FILE, ALWAYS — not behind a flag. The clock and
     // the git facts are gathered HERE (a real process) and handed to the pure writer.
     const ctx = {
         target,
-        targetCommit: targetCommit(target),
+        targetCommit: targetCommit(scope.repoRoot),
         toolVersion: toolVersion(),
         dateISO: new Date().toISOString().slice(0, 10),
-        treeStatus: treeStatus(target),
+        treeStatus: treeStatus(scope.repoRoot),
+        oracle: describeOracle(oracleSel),
     };
     const reportDir = join(here, "..", "reports");
-    const path = writeReport(ctx, results, t, v, reportDir);
+    const path = writeReport(ctx, results, t, v, reportDir, undefined, [
+        callerResolutionSection(crScan),
+        localIdentitySection(liScan),
+        mechanicalLine(mech),
+        mechanicalRuleCountsLine(ruleCounts),
+    ]);
     console.log(`\nreport written: ${path}`);
+    // The deploy-gate evidence, keyed to the sha of the repository holding the
+    // judged convex dir. No sha, no file: evidence that names no commit certifies
+    // nothing, so the run refuses (exit 2) rather than write one.
+    if (evidencePath !== undefined) {
+        if (evidenceSha === undefined) {
+            console.error(`backend-doctor: --json-evidence REFUSED — \`git -C ${repoOfConvex} rev-parse HEAD\` failed, so the evidence would name no commit. No evidence file written.`);
+            process.exit(2);
+        }
+        const evidence = buildEvidence({
+            sha: evidenceSha,
+            cli_commit: cliCommit(),
+            convex_path: convexPath,
+            exit_code: exitCode,
+            checked: cov.checked.length,
+            total: cov.ruleIds.length,
+            mechanical_violations: mech.count,
+            mechanical_rule_counts: ruleCounts.counts,
+            mechanical_rule_module_counts: ruleCounts.moduleCounts,
+        });
+        let out = resolve(evidencePath);
+        // A trailing slash names a directory even before it exists.
+        if (/[/\\]$/.test(evidencePath))
+            mkdirSync(out, { recursive: true });
+        if (existsSync(out) && statSync(out).isDirectory())
+            out = join(out, `backend-doctor-${evidenceSha}.json`);
+        else
+            mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, `${JSON.stringify(evidence, null, 2)}\n`);
+        console.log(`evidence written: ${out}`);
+    }
     if (!cov.ok) {
         console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
-        process.exit(1);
     }
-    // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
-    // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
-    // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
-    if (crudDefect) {
+    else if (crudDefect) {
+        // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
+        // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
+        // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
         console.log("\nNOTE: CRUD coverage self-check FAILED — the rows do not cover every schema table (or the schema is unreadable). See the CRUD COVERAGE section above.");
-        process.exit(1);
     }
-    process.exit(v.exitCode);
+    else if (crDefect) {
+        // CR-1 is CRITICAL: a FAIL-OPEN or unjustified NO-IDENTITY public registration
+        // is a mechanical violation, so the gate refuses on it even when every numbered
+        // rule is satisfied.
+        console.log(`\nNOTE: CR-1 (caller resolution) FAILED — ${crViolations(crScan).length} public registration(s) serve or write data without resolving their caller. CRITICAL, no bypass. See the CALLER RESOLUTION section above; every member is named there.`);
+    }
+    if (liDefect) {
+        // Reported independently of the NOTE chain above: CR-2 is its own gate.
+        console.log(`\nNOTE: CR-2 (local identity) FAILED — ${liScan.violate.length} site(s) define a local identity primitive instead of calling @vantageos/cloud-identity. Ceiling 0. See the LOCAL IDENTITY section above; every site is named there.`);
+    }
+    process.exit(exitCode);
 }
 main();

package/dist/contract.d.ts

@@ -1,4 +1,4 @@
-import type { OracleColumn } from "./oracle.js";
+import { type OracleColumn, type WriterTierTable } from "./oracle.js";
 export interface ContractField {
     /** the §2 contract field name. */
     field: string;
@@ -9,10 +9,28 @@ export interface ContractField {
 }
 /** The thirteen §2 contract fields (R-38 completeness gate operates on this). */
 export declare const CONTRACT_FIELDS: ContractField[];
-/** The two §2 fields that MUST be two distinct columns — reader and writer
- * authority. The oracle merges both onto `rbac_qui`: the structural defect. */
+/** Reader authority (R-5) lives in the oracle's own `rbac_qui` column. */
 export declare const READER_AUTHORITY_COLUMN: OracleColumn;
-export declare const WRITER_AUTHORITY_COLUMN: OracleColumn;
-/** True when reader and writer authority resolve to the SAME column — the
- * merged-authority non-conformance R-14 names by construction. */
-export declare function authorityIsMerged(): boolean;
+/** Without a side-car, writer authority (R-10) can only fall back to the SAME
+ * column — the merge §12 calls non-conforming by construction. */
+export declare const MERGED_WRITER_AUTHORITY_COLUMN: OracleColumn;
+/** The side-car column that carries writer authority apart from `rbac_qui`. */
+export declare const SPLIT_WRITER_AUTHORITY_COLUMN: "writer_tier";
+export type AuthoritySplit = {
+    kind: "split";
+    sideCar: string;
+    writeTools: number;
+} | {
+    kind: "merged";
+    reason: string;
+    uncovered: string[];
+} | {
+    kind: "unjudgeable";
+    reason: string;
+};
+/**
+ * Resolve where writer authority lives for this oracle.
+ * @param writeTools the `outil` of every inventory row whose verb writes.
+ * @param sideCar the bound writer-tier side-car.
+ */
+export declare function resolveAuthoritySplit(writeTools: readonly string[], sideCar: WriterTierTable): AuthoritySplit;

package/dist/contract.js

@@ -1,8 +1,20 @@
+// The §2 per-table contract, transcribed from the pinned standard
+// (backend-standard.md @ a9d7877b, read by command — never from memory).
+//
+// §2 splits authority into TWO distinct contract fields — reader authority (R-5)
+// and writer authority (R-10). The oracle's eighteen columns carry ONE authority
+// column, `rbac_qui`. An oracle alone is therefore merged, and R-14 calls a merged
+// authority column "non-conforming by construction". An oracle declares the split
+// through its writer-tier side-car (see resolveAuthoritySplit below).
+import { basename } from "node:path";
+import { WRITER_TIER_NAME } from "./oracle.js";
 /** The thirteen §2 contract fields (R-38 completeness gate operates on this). */
 export const CONTRACT_FIELDS = [
     { field: "exposure", columns: ["surface"], rule: "R-1" },
     { field: "operation verb", columns: ["crud"], rule: "R-2" },
     { field: "reader authority", columns: ["rbac_qui"], rule: "R-5" },
+    // §2's table maps writer authority onto `rbac_qui` too; that mapping IS the
+    // merge. The split column is the side-car's `writer_tier` (resolveAuthoritySplit).
     { field: "writer authority", columns: ["rbac_qui"], rule: "R-10" },
     { field: "retrieval mechanism", columns: ["search_mecanisme"], rule: "R-4" },
     { field: "pagination", columns: ["search_mecanisme"], rule: "R-3" },
@@ -18,12 +30,45 @@ export const CONTRACT_FIELDS = [
         rule: "R-13/R-27",
     },
 ];
-/** The two §2 fields that MUST be two distinct columns — reader and writer
- * authority. The oracle merges both onto `rbac_qui`: the structural defect. */
+/** Reader authority (R-5) lives in the oracle's own `rbac_qui` column. */
 export const READER_AUTHORITY_COLUMN = "rbac_qui";
-export const WRITER_AUTHORITY_COLUMN = "rbac_qui";
-/** True when reader and writer authority resolve to the SAME column — the
- * merged-authority non-conformance R-14 names by construction. */
-export function authorityIsMerged() {
-    return READER_AUTHORITY_COLUMN === WRITER_AUTHORITY_COLUMN;
+/** Without a side-car, writer authority (R-10) can only fall back to the SAME
+ * column — the merge §12 calls non-conforming by construction. */
+export const MERGED_WRITER_AUTHORITY_COLUMN = "rbac_qui";
+/** The side-car column that carries writer authority apart from `rbac_qui`. */
+export const SPLIT_WRITER_AUTHORITY_COLUMN = "writer_tier";
+const UNKNOWN_WRITER_TIER = new Set(["", "?", "unknown", "n/a", "tbd"]);
+/**
+ * Resolve where writer authority lives for this oracle.
+ * @param writeTools the `outil` of every inventory row whose verb writes.
+ * @param sideCar the bound writer-tier side-car.
+ */
+export function resolveAuthoritySplit(writeTools, sideCar) {
+    if (sideCar.status === "absent") {
+        return {
+            kind: "merged",
+            reason: `writer-tier side-car ${WRITER_TIER_NAME} ABSENT (${sideCar.origin}; searched: ${sideCar.searched.join(", ") || "<none>"}), so writer authority has no column of its own`,
+            uncovered: [],
+        };
+    }
+    if (sideCar.status === "unreadable") {
+        return {
+            kind: "unjudgeable",
+            reason: `writer-tier side-car ${sideCar.path} unreadable — ${sideCar.reason}; whether \`${SPLIT_WRITER_AUTHORITY_COLUMN}\` declares writer authority cannot be read`,
+        };
+    }
+    const tools = [...new Set(writeTools)];
+    const uncovered = tools.filter((t) => {
+        const entries = sideCar.byTool.get(t) ?? [];
+        return !entries.some((e) => !UNKNOWN_WRITER_TIER.has(e.writer_tier.trim().toLowerCase()));
+    });
+    const file = basename(sideCar.path);
+    if (uncovered.length > 0) {
+        return {
+            kind: "merged",
+            reason: `${file} records no \`${SPLIT_WRITER_AUTHORITY_COLUMN}\` for ${uncovered.length} write tool(s) of ${tools.length} (${uncovered.join(", ")}), so for those tools writer authority is omitted`,
+            uncovered,
+        };
+    }
+    return { kind: "split", sideCar: file, writeTools: tools.length };
 }

package/dist/coverage-cli.js

@@ -2,8 +2,16 @@
 // Prints the coverage proof over the TWO buckets — CHECKED and
 // NOT_MECHANICALLY_CHECKABLE. Exits non-zero only if the union does not equal
 // the derived rule ids (a rule in no bucket, in two, or a stale bucket entry).
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkDistFreshness } from "./build-stamp.js";
 import { coverage, coverageSummary } from "./coverage.js";
 import { NOT_MECHANICALLY_CHECKABLE } from "./not-checkable.js";
+const fresh = checkDistFreshness(dirname(fileURLToPath(import.meta.url)));
+if (!fresh.ok) {
+    console.error(`backend-doctor --coverage: REFUSING TO RUN — ${fresh.reason}`);
+    process.exit(2);
+}
 const r = coverage();
 console.log(coverageSummary(r));
 console.log("");

package/dist/coverage.d.ts

@@ -4,7 +4,7 @@
  * canonical 48-rule standard (51ec7af1) to 2bb402f7, which closes R-7/R-8/R-37/R-40
  * as a written-justification-token control (§23) — the paired standard PR the four
  * decisive detectors below track. Still 48 rules; the pin moves forward with them. */
-export declare const STANDARD_SHA = "4bcd605656ceff52d4f1593a9176cd6b988471be";
+export declare const STANDARD_SHA = "2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3";
 export declare const VENDORED_STANDARD_PATH: string;
 /**
  * Derive the full rule list R-1..R-42 from the VENDORED standard fixture —

package/dist/coverage.js

@@ -18,8 +18,8 @@ const here = dirname(fileURLToPath(import.meta.url));
  * canonical 48-rule standard (51ec7af1) to 2bb402f7, which closes R-7/R-8/R-37/R-40
  * as a written-justification-token control (§23) — the paired standard PR the four
  * decisive detectors below track. Still 48 rules; the pin moves forward with them. */
-export const STANDARD_SHA = "4bcd605656ceff52d4f1593a9176cd6b988471be";
-export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-4bcd605.md");
+export const STANDARD_SHA = "2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3";
+export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-2825122.md");
 /**
  * Derive the full rule list R-1..R-42 from the VENDORED standard fixture —
  * never typed, never a git show against a local repo. Reads the `**R-NN`

package/dist/detectors/oracle-axis1.d.ts

@@ -1,8 +1,9 @@
 import type { Detector } from "../engine-types.js";
 import { type OracleRow } from "../oracle.js";
-/** Absolute path to the pinned SECOND-backend (VantageRegistry) oracle fixture.
+/** The vendored day159 SECOND-backend (VantageRegistry) snapshot — a FIXTURE for
+ * this tool's tests, never a default (see oracle.ts resolveOracle).
  * Vendored at pin a74a042b, blob b53e2626954a887303d11d944b6132a11dbd34f6. */
-export declare const VR_ORACLE_PATH: string;
+export declare const FIXTURE_VR_ORACLE_PATH: string;
 /** The vendored standard (the R-5 law) — the SAME pin coverage.ts parses. The
  * §2 [shared] contract columns are DERIVED from this file, never hardcoded.
  * Defined locally (not imported from coverage.ts) to avoid a registry ↔ coverage
@@ -19,7 +20,8 @@ export interface Inventory {
 /** Load any backend inventory CSV generically from its OWN header — the shared
  * fields are DERIVED from these real headers, never a prose illustration. */
 export declare function loadInventory(path: string): Inventory;
-/** Memoized read of the pinned VR inventory. */
+/** Memoized read of the VR inventory bound for THIS run (derived from the target).
+ * Throws OracleAbsentError when none was found. */
 export declare function readVrInventory(): Inventory;
 /** The VP inventory, adapted from the memoized VP oracle reader — the SAME rows
  * the axis-2 detectors read, exposed with VP's real header. */

package/dist/detectors/oracle-axis1.js

@@ -18,18 +18,20 @@
 //
 // Both inputs are IN HAND (VP oracle + VR oracle, both vendored + hash-checked).
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ORACLE_COLUMNS, parseCsv, readOracle, } from "../oracle.js";
+import { activeOracle, ORACLE_COLUMNS, oracleLabel, parseCsv, readOracle, refuseWithoutOracle, requireVrOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
 const here = dirname(fileURLToPath(import.meta.url));
-/** Absolute path to the pinned SECOND-backend (VantageRegistry) oracle fixture.
+/** The vendored day159 SECOND-backend (VantageRegistry) snapshot — a FIXTURE for
+ * this tool's tests, never a default (see oracle.ts resolveOracle).
  * Vendored at pin a74a042b, blob b53e2626954a887303d11d944b6132a11dbd34f6. */
-export const VR_ORACLE_PATH = join(here, "..", "..", "fixtures", "vr-by-tool-day159.csv");
+export const FIXTURE_VR_ORACLE_PATH = join(here, "..", "..", "fixtures", "vr-by-tool-day159.csv");
 /** The vendored standard (the R-5 law) — the SAME pin coverage.ts parses. The
  * §2 [shared] contract columns are DERIVED from this file, never hardcoded.
  * Defined locally (not imported from coverage.ts) to avoid a registry ↔ coverage
  * import cycle. */
-export const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-4bcd605.md");
+export const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-2825122.md");
 /** Load any backend inventory CSV generically from its OWN header — the shared
  * fields are DERIVED from these real headers, never a prose illustration. */
 export function loadInventory(path) {
@@ -44,13 +46,17 @@ export function loadInventory(path) {
     });
     return { header, rows };
 }
-let vrCache = null;
-/** Memoized read of the pinned VR inventory. */
+const vrCache = new Map();
+/** Memoized read of the VR inventory bound for THIS run (derived from the target).
+ * Throws OracleAbsentError when none was found. */
 export function readVrInventory() {
-    if (vrCache)
-        return vrCache;
-    vrCache = loadInventory(VR_ORACLE_PATH);
-    return vrCache;
+    const path = requireVrOracle().path;
+    const hit = vrCache.get(path);
+    if (hit)
+        return hit;
+    const inv = loadInventory(path);
+    vrCache.set(path, inv);
+    return inv;
 }
 /** The VP inventory, adapted from the memoized VP oracle reader — the SAME rows
  * the axis-2 detectors read, exposed with VP's real header. */
@@ -161,13 +167,17 @@ export function compareBackends(vpProvider = readOracle, vrProvider = readVrInve
     };
 }
 const R40_ID = "R-40 between-backend divergence";
-const R40_ANCHOR = "oracle:vp-by-tool-day158.csv vs oracle:vr-by-tool-day159.csv";
+function r40Anchor() {
+    const vr = activeOracle()?.vr;
+    const vrName = vr && vr.status === "found" ? basename(vr.path) : "ABSENT";
+    return `${oracleLabel()} vs oracle:${vrName}`;
+}
 /** Wrap the Axis-1 compare into a Detector. Providers are injectable for tests;
  * production reads the two memoized real oracles. */
 export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
     return {
         id: R40_ID,
-        run: () => {
+        run: () => refuseWithoutOracle(R40_ID, () => {
             const cmp = compareBackends(vpProvider, vrProvider);
             const { schema, sites } = cmp;
             // the schema (column) divergence is itself a site — surfaced, never dropped.
@@ -188,7 +198,7 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
                 const reason = `R-40: the VP and VR inventories agree on every shared field's closed vocabulary and share every column; the mechanical between-backend compare is exhausted with no divergence. Present — decided by the compare, not a human verdict. ${breakdown}`;
                 return {
                     id: R40_ID,
-                    anchor: R40_ANCHOR,
+                    anchor: r40Anchor(),
                     state: "present",
                     verdict: reason,
                 };
@@ -208,12 +218,12 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
             })
                 .join("; ");
             const reason = `R-40: ${sites.length} shared field(s) diverge BETWEEN VP and VR on their closed vocabulary — the mechanical compare names WHICH FIELD and WHICH value on VP vs VR, and none carries a written between-backend justification; non-conforming until each divergence is reconciled or carries a recorded justification. ${schemaFinding} ${breakdown} Field sites: ${examples}.`;
-            return {
+            return withCount({
                 id: R40_ID,
-                anchor: `${R40_ANCHOR} field=${sites[0]?.field ?? "schema"}`,
+                anchor: `${r40Anchor()} field=${sites[0]?.field ?? "schema"}`,
                 state: "non-conforming",
                 verdict: reason,
-            };
-        },
+            }, itemCount(sites.length));
+        }),
     };
 }

package/dist/detectors/oracle-axis2.d.ts

@@ -1,7 +1,13 @@
 import type { Detector } from "../engine-types.js";
 import { type OracleRow } from "../oracle.js";
 import type { RulePredicate } from "./shared.js";
+export declare const JUSTIFICATION_TOKEN_RE: RegExp;
+/** The oracle-row form: reads the row's remediation cell (`rbac_adjustment_needed`). */
 export declare function hasJustificationToken(r: OracleRow): boolean;
+/** The raw-text form — for a SOURCE-scan site with no oracle row: a nearby code
+ * comment window is that site's "remediation cell". Same regex, same word-
+ * boundary/negation guards; never a second matcher. */
+export declare function hasJustificationTokenInText(text: string): boolean;
 export declare const r7: RulePredicate;
 export declare const r8: RulePredicate;
 export interface DivergenceSite {