@vantageos/backend-doctor 0.1.0 → 0.1.2

package/README.md

@@ -81,7 +81,7 @@ A `could-not-judge` rule is an **abstention** — a human verdict is owed, never
 
 Every input is pinned and, where it is a vendored document, proven byte-identical to its upstream git blob (an un-hashable vendored doc is an authority granted to oneself).
 
-**The single authority for which standard fixture is active is the loader constant** `STANDARD_FILE` in [`src/detectors/standard/_doc.ts`](./src/detectors/standard/_doc.ts) — currently `backend-standard-51ec7af1.md` (48 rules, canonical source: ElPi-Corp `analysis/vantagepeers/backend-standard/backend-standard.md`). Everything else is provenance, NOT the active pin: `PINS.txt` and any other `fixtures/backend-standard-<sha>.md` still in the tree (e.g. the superseded `backend-standard-a9d7877b.md`, 47 rules — it lacks R-48) are kept only to show what was scored before. If any of them disagrees with `STANDARD_FILE`, `STANDARD_FILE` wins. Read the active pin from `STANDARD_FILE`, never from `PINS.txt` or a number typed elsewhere — following a stale `PINS.txt` would silently score the superseded 47-rule document and never surface R-48. See [`PINS.txt`](./PINS.txt) for the engine, backend snapshot, and MCP-family doc + VR inventory pins.
+**The single authority for which standard fixture is active is the loader constant** `STANDARD_FILE` in [`src/detectors/standard/_doc.ts`](./src/detectors/standard/_doc.ts) — currently `backend-standard-4265226e.md` (49 rules — adds R-50, org isolation on a subscribed read is a typed empty result, never an uncaught throw; canonical source: ElPi-Corp `analysis/vantagepeers/backend-standard/backend-standard.md`). Everything else is provenance, NOT the active pin: `PINS.txt` and any other `fixtures/backend-standard-<sha>.md` still in the tree (e.g. the superseded `backend-standard-a9d7877b.md`, 47 rules — it lacks R-48) are kept only to show what was scored before. If any of them disagrees with `STANDARD_FILE`, `STANDARD_FILE` wins. Read the active pin from `STANDARD_FILE`, never from `PINS.txt` or a number typed elsewhere — following a stale `PINS.txt` would silently score the superseded 47-rule document and never surface R-48. See [`PINS.txt`](./PINS.txt) for the engine, backend snapshot, and MCP-family doc + VR inventory pins.
 
 ## Discipline (how a detector is proven)
 

package/dist/cli.js

@@ -8,17 +8,20 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runDoctor, renderTable } from "@vantageos/mcp-doctor";
-import { REGISTRY } from "./registry.js";
+import { renderTable, runDoctor } from "@vantageos/mcp-doctor";
 import { coverage, coverageSummary } from "./coverage.js";
+import { checkStandardReadable } from "./detectors/standard/_doc.js";
 import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults } from "./not-checkable.js";
-import { tally, tallyLine, verdict } from "./tally.js";
+import { REGISTRY } from "./registry.js";
 import { writeReport } from "./report.js";
+import { tally, tallyLine, verdict } from "./tally.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) {
     try {
-        return execFileSync("git", ["-C", target, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+        return execFileSync("git", ["-C", target, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+        }).trim();
     }
     catch {
         return "not a git repo";
@@ -41,6 +44,15 @@ function toolVersion() {
 }
 function main() {
     const target = resolve(process.argv[2] ?? process.cwd());
+    // 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
+    // not read, never exit 1 (which reads as "a violation was found"). Eta #12 REVISE.
+    const readable = checkStandardReadable();
+    if (!readable.ok) {
+        console.error(readable.refusal);
+        process.exit(2);
+    }
     // Every derived rule carries EXACTLY ONE result: the executable detectors plus
     // one could-not-judge abstention per NOT_MECHANICALLY_CHECKABLE rule (R-48's
     // pending detector) — so the tally's rule total equals the 48 derived rules and
@@ -54,7 +66,7 @@ function main() {
     const cov = coverage();
     console.log(coverageSummary(cov));
     console.log("");
-    console.log(`NOT MECHANICALLY CHECKABLE (${cov.notCheckable.length}) — a human decides, or it governs a document; NOT a clean bill:`);
+    console.log(`NOT MECHANICALLY CHECKABLE (${cov.notCheckable.length}) — NAMED, OWNED gaps (detector owned by another task), NOT 'a human decides'; NOT a clean bill:`);
     for (const id of cov.notCheckable) {
         console.log(`  ${id} — ${NOT_MECHANICALLY_CHECKABLE[id]}`);
     }
@@ -62,6 +74,10 @@ function main() {
     // DERIVED here (no human counts rows) and the verdict maps to a TRUTHFUL exit
     // code — >=1 critical or a hard violation exits 1, a human-verdict-owed
     // abstention exits 2, approve exits 0. See src/tally.ts + src/severity.ts.
+    // The tally is over ALL 48 derived rules: the executable detectors' results
+    // PLUS the one could-not-judge abstention per NOT_MECHANICALLY_CHECKABLE rule
+    // (R-48) appended above — so `results` already carries exactly one result per
+    // rule and `tally` reconciles against deriveRuleIds() (48), nothing dropped.
     const t = tally(results);
     const v = verdict(t, results);
     console.log("");

package/dist/coverage.d.ts

@@ -1,9 +1,10 @@
 /** The standard is VENDORED at the pin as a fixture — DATA at 51ec7af1, a
  * comparison target on the same footing as the oracle CSV. deriveRuleIds no
  * longer shells out to any local repo, so it is CI-portable. Re-pinned from the
- * stale 47-rule freeze (a9d7877b) to the canonical 48-rule standard (adds R-48,
- * authority-totality) so coverage cannot pretend 47 is the whole document. */
-export declare const STANDARD_SHA = "51ec7af1bc84239aefd751d16389c65af6082c9f";
+ * 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 = "4265226eb6698c7dfbae3ced77df564e877908ad";
 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

@@ -15,10 +15,11 @@ const here = dirname(fileURLToPath(import.meta.url));
 /** The standard is VENDORED at the pin as a fixture — DATA at 51ec7af1, a
  * comparison target on the same footing as the oracle CSV. deriveRuleIds no
  * longer shells out to any local repo, so it is CI-portable. Re-pinned from the
- * stale 47-rule freeze (a9d7877b) to the canonical 48-rule standard (adds R-48,
- * authority-totality) so coverage cannot pretend 47 is the whole document. */
-export const STANDARD_SHA = "51ec7af1bc84239aefd751d16389c65af6082c9f";
-export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-51ec7af1.md");
+ * 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 = "4265226eb6698c7dfbae3ced77df564e877908ad";
+export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-4265226e.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.js

@@ -6,16 +6,17 @@
 // Axis-2 (divergence WITHIN one backend) is R-37; Axis-1 (BETWEEN two backends)
 // is R-40 — it fires the moment a second backend's inventory exists.
 //
-// This is a JUDGEMENT rule with a mechanical half. Like R-7/R-8/R-37 the
-// instrument performs the mechanical half IN FULL — it names every concrete
-// between-backend divergence site (which shared field, which value on VP vs
-// which on VR) — and returns `could-not-judge`: whether each divergence carries
-// a SOUND written justification is the human half. It never claims `present`
-// (a clean bill) nor `absent` (does-not-apply) while real divergences exist.
+// The instrument performs the mechanical compare IN FULL — it names every
+// concrete between-backend divergence site (which shared field, which value on
+// VP vs which on VR) — and DECIDES: a divergence with no written justification
+// token is `non-conforming` (the two backends owe either agreement or a recorded
+// justification); a run where every divergence carries a written justification
+// token, or where the two agree on every shared field, is `present`. The
+// disposition is the token's PRESENCE, never a human's opinion of its soundness.
+// could-not-judge is reserved for an unreadable oracle (a malformed VR/VP CSV),
+// never for "a person should weigh the divergence".
 //
-// Both inputs are IN HAND (VP oracle + VR oracle, both vendored + hash-checked),
-// so this is NOT the input-absent could-not-judge — it is the human-verdict-owed
-// state, the acceptance property of a comparative judgement rule.
+// 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 { fileURLToPath } from "node:url";
@@ -28,7 +29,7 @@ export const VR_ORACLE_PATH = join(here, "..", "..", "fixtures", "vr-by-tool-day
  * §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-51ec7af1.md");
+export const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-4265226e.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) {
@@ -176,22 +177,20 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
             if (schema.vrOnlyColumns.length)
                 schemaBits.push(`VR-only column(s): ${schema.vrOnlyColumns.join(", ")}`);
             const schemaFinding = schemaBits.length
-                ? `Between-schema divergence (R-14-class): ${schemaBits.join("; ")} — a shared field absent on one backend; a human must judge whether the schema difference is justified.`
+                ? `Between-schema divergence (R-14-class): ${schemaBits.join("; ")} — a shared field absent on one backend, with no written justification recorded; non-conforming until the schema difference carries a written justification.`
                 : "No between-schema column divergence.";
             const totalValueDivergences = sites.reduce((n, s) => n + s.vpOnly.length + s.vrOnly.length, 0);
             const breakdown = `[shared-field-sites=${sites.length} value-divergences=${totalValueDivergences} schema-col-divergences=${schema.vpOnlyColumns.length + schema.vrOnlyColumns.length}]`;
             if (sites.length === 0 && schemaBits.length === 0) {
-                // The two backends agree on every shared field's vocabulary — still not a
-                // clean bill: R-40's disposition (is each divergence justified?) is human,
-                // and here there is simply nothing owed. The instrument abstains rather
-                // than claim the rule held.
-                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. Confirming the contract is human. ${breakdown}`;
+                // The two backends agree on every shared field's vocabulary and share
+                // every column — a decisive PASS. The disposition is mechanical (nothing
+                // diverges, so no justification is owed); the instrument does not abstain.
+                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,
-                    state: "could-not-judge",
+                    state: "present",
                     verdict: reason,
-                    reason,
                 };
             }
             const examples = sites
@@ -208,13 +207,12 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
                 return `${s.field}: VP-only {${vp || "—"}} vs VR-only {${vr || "—"}}`;
             })
                 .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; a human must judge whether each between-backend divergence carries a SOUND written justification. This is NOT a clean bill. ${schemaFinding} ${breakdown} Field sites: ${examples}.`;
+            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 {
                 id: R40_ID,
                 anchor: `${R40_ANCHOR} field=${sites[0]?.field ?? "schema"}`,
-                state: "could-not-judge",
+                state: "non-conforming",
                 verdict: reason,
-                reason,
             };
         },
     };

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

@@ -1,6 +1,7 @@
 import type { Detector } from "../engine-types.js";
 import { type OracleRow } from "../oracle.js";
 import type { RulePredicate } from "./shared.js";
+export declare function hasJustificationToken(r: OracleRow): boolean;
 export declare const r7: RulePredicate;
 export declare const r8: RulePredicate;
 export interface DivergenceSite {
@@ -10,6 +11,11 @@ export interface DivergenceSite {
     valA: string;
     toolB: string;
     valB: string;
+    /** MECHANICAL disposition: the divergence carries a written per-tool
+     * justification token on at least one of the two diverging rows. A justified
+     * divergence is `present`; an unjustified one is `non-conforming`. This is the
+     * pole that replaced "a human judges whether the justification is sound". */
+    justified: boolean;
 }
 /**
  * Group the inventory rows by table and, per shared field, name ONE diverging

package/dist/detectors/oracle-axis2.js

@@ -1,4 +1,29 @@
 import { isInventoryRow, readOracle, } from "../oracle.js";
+// A written justification token turns a flagged divergence from a DEFECT the
+// author owes into a recorded, accepted divergence. It is the mechanical pole
+// that replaced "a human decides whether the divergence is sound": the control
+// reads whether the token is PRESENT in the inventory (the `rbac_adjustment_needed`
+// remediation cell), never whether a person judges it sound. `CORRIGER`/`REVOIR`
+// are remediation-owed markers (R-28) — a fix still owed, NOT a justification —
+// so they do not satisfy this predicate; only an explicit JUSTIFIÉ/JUSTIFIED/
+// STATELESS/ACCEPTED token does.
+export function hasJustificationToken(r) {
+    const cell = (r.by.rbac_adjustment_needed ?? "").trim();
+    // Anchored on the DOCUMENTED shape: the standard writes the token with a
+    // trailing colon (`JUSTIFIÉ:` / `JUSTIFIED:` / `STATELESS:`), at a word
+    // boundary. Two failures a bare substring match let through, both closed here:
+    //   • a LEADING-letter negation — "UNJUSTIFIED" contains "JUSTIFIED", so the
+    //     leading `(?<![A-Za-zÀ-ÿ-])` (not preceded by a letter OR a hyphen — a
+    //     hyphen-joined negation like French `non-justifié:` clears a letter-only
+    //     lookbehind, Eta #12 round-2) rejects it; and R-37's own output prints
+    //     "N UNJUSTIFIED divergence(s)".
+    //   • a token with NO colon — "not justified", "justified by design" — cleared
+    //     the guard though the standard requires the colon; the trailing `\s*:`
+    //     now rejects it. Only the recorded token form (`TOKEN:`) is a justification.
+    // No trailing \b before the colon: an accented final letter (É in JUSTIFIÉ) is
+    // not an ASCII word char, so \b would not match after it — the colon is the anchor.
+    return /(?<![A-Za-zÀ-ÿ-])(JUSTIFI(É|E|ED)|STATELESS|ACCEPT(É|E|ED)|WONTFIX)\s*:/i.test(cell);
+}
 // ---- R-7 read/write coherence divergence (INCOHERENT* table-aggregate flag) -
 // §18: "`INCOHERENT*` flag (mechanical); divergence justified (human)". The
 // oracle's `rbac_coherence_table` carries the audit's table-aggregate coherence
@@ -9,14 +34,23 @@ import { isInventoryRow, readOracle, } from "../oracle.js";
 export const r7 = {
     ruleId: "R-7",
     id: "R-7 read/write coherence divergence",
-    check: "row carries an `INCOHERENT*` coherence flag (mechanical); whether the read/write divergence is justified is human",
+    check: "row carries an `INCOHERENT*` coherence flag with NO written justification token in its remediation cell → non-conforming; a `COHERENT*` verdict, or an `INCOHERENT*` carrying a `JUSTIFIÉ:`/`JUSTIFIED:` token, → present (the machine decides on the token's PRESENCE, never on a person's opinion of its soundness)",
     classify: (r) => {
         const v = r.by.rbac_coherence_table;
-        if (/^INCOHERENT/i.test(v))
+        if (/^INCOHERENT/i.test(v)) {
+            // The disposition is MECHANICAL: an incoherence publishes only with a
+            // written justification token recorded in the inventory (the same
+            // remediation cell R-28 governs). No token → non-conforming; the row owes
+            // a fix or a written justification, and asserting neither is the defect.
+            // could-not-judge is NOT emitted here — it is reserved for a row the
+            // parser could not read (handled upstream by the malformed branch).
+            if (hasJustificationToken(r))
+                return { kind: "conform" };
             return {
-                kind: "cnj",
-                note: `rbac_coherence_table="${v}" — a read/write incoherence; a human must record whether this divergence is justified or the tool corrected`,
+                kind: "violate",
+                note: `rbac_coherence_table="${v}" — a read/write incoherence with no written justification token (JUSTIFIÉ:/JUSTIFIED:) in rbac_adjustment_needed; it owes a fix or a recorded justification`,
             };
+        }
         if (/^COHERENT/i.test(v))
             return { kind: "conform" };
         return { kind: "na" }; // no coherence verdict recorded on this row (e.g. n/a)
@@ -30,7 +64,7 @@ export const r7 = {
 export const r8 = {
     ruleId: "R-8",
     id: "R-8 zero scope check on a data op",
-    check: "empty/`AUCUN` scope enforcement on a row carrying a data op (mechanical); whether the stateless justification is sound is human",
+    check: "empty/`AUCUN` scope enforcement on a row carrying a data op, with NO written stateless/read-nothing justification token → non-conforming; a genuine scope check, or a no-scope row carrying a `JUSTIFIÉ:`/`STATELESS:` token, → present (the machine decides on the token's PRESENCE, never on a person's opinion of soundness)",
     classify: (r) => {
         const scope = r.by.scope_enforcement.trim();
         const crud = r.by.crud.trim();
@@ -38,11 +72,18 @@ export const r8 = {
         if (!hasDataOp)
             return { kind: "na" }; // no data op — R-8 does not apply
         const noScope = scope === "" || /AUCUN/i.test(scope);
-        if (noScope)
+        if (noScope) {
+            // MECHANICAL disposition: a zero-scope data op publishes only with an
+            // explicit written stateless/read-nothing justification token in its
+            // remediation cell. No token → non-conforming. could-not-judge is reserved
+            // for an unreadable row, never for "a person should weigh soundness".
+            if (hasJustificationToken(r) || /STATELESS/i.test(scope))
+                return { kind: "conform" };
             return {
-                kind: "cnj",
-                note: `scope_enforcement="${scope || "<empty>"}" on a data op crud="${crud}" — no scope check; a human must judge whether the stateless justification is sound`,
+                kind: "violate",
+                note: `scope_enforcement="${scope || "<empty>"}" on a data op crud="${crud}" — no scope check and no written stateless justification token (JUSTIFIÉ:/STATELESS:)`,
             };
+        }
         return { kind: "conform" }; // a genuine scope check is recorded
     },
 };
@@ -104,6 +145,7 @@ export function findDivergences(rows) {
                     valA: first.by[col],
                     toolB: neighbour.by.outil,
                     valB: neighbour.by[col],
+                    justified: hasJustificationToken(first) || hasJustificationToken(neighbour),
                 });
         }
     }
@@ -117,32 +159,35 @@ export function makeR37(rowsProvider = readOracle) {
     return {
         id: R37_ID,
         run: () => {
-            const sites = findDivergences(rowsProvider());
+            const all = findDivergences(rowsProvider());
+            // MECHANICAL disposition: an unjustified divergence is the defect; a
+            // divergence carrying a written per-tool justification token is accepted.
+            // The instrument decides present/non-conforming — it never abstains on
+            // "a human should weigh soundness". could-not-judge would appear only if
+            // the oracle itself were unreadable (there is no such branch to reach here
+            // because a malformed row cannot form a filled pair).
+            const sites = all.filter((s) => !s.justified);
             const tables = new Set(sites.map((s) => s.table));
-            const breakdown = `[filled-neighbour-divergences=${sites.length} across tables=${tables.size}]`;
+            const breakdown = `[filled-neighbour-divergences=${all.length} unjustified=${sites.length} justified=${all.length - sites.length} across tables=${tables.size}]`;
             if (sites.length === 0) {
-                // No divergence anywhere — still not a clean bill: R-37's disposition is
-                // human, so the instrument abstains rather than claim the rule held.
-                const reason = `R-37: no filled-neighbour divergence found across the oracle's per-table groups; the mechanical compare is exhausted, but confirming the per-tool contract is human. ${breakdown}`;
+                const reason = `R-37: no UNJUSTIFIED filled-neighbour divergence across the oracle's per-table groups (${all.length} divergence(s), all carrying a written per-tool justification token, or none present). The mechanical compare is exhaustive and the disposition is decided by the token's presence, not a human verdict. ${breakdown}`;
                 return {
                     id: R37_ID,
                     anchor: R37_ANCHOR,
-                    state: "could-not-judge",
+                    state: "present",
                     verdict: reason,
-                    reason,
                 };
             }
             const examples = sites
                 .slice(0, 5)
                 .map((s) => `${s.table}.${s.field}: ${s.toolA} "${s.valA.slice(0, 32)}" vs ${s.toolB} "${s.valB.slice(0, 32)}"`)
                 .join("; ");
-            const reason = `R-37: ${sites.length} filled-neighbour divergence(s) across ${tables.size} tables — the mechanical compare names WHICH TWO TOOLS diverge on a shared contract field; a human must judge whether each per-tool justification is sound. This is NOT a clean bill. ${breakdown} Examples: ${examples}.`;
+            const reason = `R-37: ${sites.length} UNJUSTIFIED filled-neighbour divergence(s) across ${tables.size} tables — the mechanical compare names WHICH TWO TOOLS diverge on a shared contract field, and none carries a written per-tool justification token (JUSTIFIÉ:/JUSTIFIED: in rbac_adjustment_needed); each owes a fix or a recorded justification. This IS a violation, not an abstention. ${breakdown} Examples: ${examples}.`;
             return {
                 id: R37_ID,
                 anchor: `oracle:vp-by-tool-day158.csv table=${sites[0].table}`,
-                state: "could-not-judge",
+                state: "non-conforming",
                 verdict: reason,
-                reason,
             };
         },
     };

package/dist/detectors/source/isolation.d.ts

@@ -0,0 +1,6 @@
+import type { Detector } from "../../engine-types.js";
+import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare function scanR50(files: SrcFile[]): Scan;
+export declare const R50: Detector;
+/** In the form the orchestrator spreads into REGISTRY. */
+export declare const SOURCE_ISOLATION_DETECTORS: SourceDetectorEntry[];