@vantageos/backend-doctor 0.1.14 → 0.2.0

package/dist/cli.js

@@ -5,17 +5,22 @@
 // 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, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderTable, runDoctor } from "@vantageos/mcp-doctor";
+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 } from "./coverage.js";
 import { crudCoverageSection, extractReactRouterPaths, scanCrudCoverage, } from "./crud-coverage.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 { handlerSurfaceLine, handlerSurfaceStats, tally, tallyLine, verdict, } from "./tally.js";
+import { describeScope, loadScopedTree, onScopedTree, resolveTarget, } from "./target.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) {
@@ -148,7 +153,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 +210,43 @@ 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;
     console.log("");
     const cov = coverage();
     console.log(coverageSummary(cov));
@@ -199,6 +271,7 @@ 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(v.summary);
     if (v.criticalViolations > 0) {
         console.log(`  critical violations: ${v.violations.critical.join(", ")}`);
@@ -210,13 +283,16 @@ function main() {
     // 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),
+    ]);
     console.log(`\nreport written: ${path}`);
     if (!cov.ok) {
         console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
@@ -229,6 +305,13 @@ function main() {
         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);
     }
+    // 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. Reported BEFORE the numbered-rule exit so the reason is legible.
+    if (crDefect) {
+        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.`);
+        process.exit(1);
+    }
     process.exit(v.exitCode);
 }
 main();

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/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,13 +18,14 @@
 //
 // 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 { ORACLE_COLUMNS, parseCsv, activeOracle, oracleLabel, readOracle, refuseWithoutOracle, requireVrOracle, } from "../oracle.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
@@ -44,13 +45,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 +166,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 +197,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,
                 };
@@ -210,10 +219,10 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
             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"}`,
+                anchor: `${r40Anchor()} field=${sites[0]?.field ?? "schema"}`,
                 state: "non-conforming",
                 verdict: reason,
             };
-        },
+        }),
     };
 }

package/dist/detectors/oracle-axis2.js

@@ -1,4 +1,4 @@
-import { isInventoryRow, readOracle, } from "../oracle.js";
+import { isInventoryRow, oracleLabel, readOracle, refuseWithoutOracle, } 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
@@ -152,13 +152,12 @@ export function findDivergences(rows) {
     return sites;
 }
 const R37_ID = "R-37 filled-neighbour divergence";
-const R37_ANCHOR = "oracle:vp-by-tool-day158.csv";
 /** Wrap the filled-neighbour compare into a Detector. `rowsProvider` is
  * injectable for tests; production reads the memoized real oracle. */
 export function makeR37(rowsProvider = readOracle) {
     return {
         id: R37_ID,
-        run: () => {
+        run: () => refuseWithoutOracle(R37_ID, () => {
             const all = findDivergences(rowsProvider());
             // MECHANICAL disposition: an unjustified divergence is the defect; a
             // divergence carrying a written per-tool justification token is accepted.
@@ -173,7 +172,7 @@ export function makeR37(rowsProvider = readOracle) {
                 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,
+                    anchor: oracleLabel(),
                     state: "present",
                     verdict: reason,
                 };
@@ -185,10 +184,10 @@ export function makeR37(rowsProvider = readOracle) {
             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}`,
+                anchor: `${oracleLabel()} table=${sites[0].table}`,
                 state: "non-conforming",
                 verdict: reason,
             };
-        },
+        }),
     };
 }

package/dist/detectors/predicates.d.ts

@@ -1,3 +1,4 @@
+import { type WriterTierTable } from "../oracle.js";
 import { type RulePredicate } from "./shared.js";
 /** Collapse a raw `surface` to one of the three canonical exposures, or null. */
 export declare function collapseSurface(raw: string): string | null;
@@ -11,6 +12,8 @@ export declare const r4: RulePredicate;
 export declare function collapseTier(raw: string): string | null;
 export declare const r5: RulePredicate;
 export declare const r9: RulePredicate;
+export declare const WRITER_TIERS: ReadonlySet<string>;
+export declare function makeR10(sideCar: () => WriterTierTable): RulePredicate;
 export declare const r10: RulePredicate;
 export declare const r12: RulePredicate;
 export declare const r13: RulePredicate;

package/dist/detectors/predicates.js

@@ -1,3 +1,9 @@
+// The eleven per-row first-wave predicates. Each transcribes its §15 "The
+// check" row and its §2 field mapping from the pinned standard, then applies
+// that predicate to the oracle rows. Structural R-14 and R-38 live in
+// structural.ts (they judge the inventory SCHEMA, not a row).
+import { basename } from "node:path";
+import { WRITER_TIER_NAME, readWriterTier } from "../oracle.js";
 import { LIST_VERBS, WRITE_VERBS, isMcpPublic } from "./shared.js";
 // ---- R-1 exposure declared ------------------------------------------------
 // §2 line 32: exposure -> `surface` = `public` (MCP surface) / `internal` /
@@ -200,22 +206,81 @@ export const r9 = {
     },
 };
 // ---- R-10 writer authority, a distinct resolved tier ----------------------
-// §2 writer authority [shared] -> `rbac_qui`. §15: writer tier present, DISTINCT,
-// one of five. The oracle has a SINGLE `rbac_qui` column, so no write can carry
-// a writer tier distinct from its reader tier — the headline merge (R-14).
-export const r10 = {
-    ruleId: "R-10",
-    id: "R-10 writer authority, distinct tier",
-    check: "writer tier present, distinct from reader, one of five",
-    classify: (r) => {
-        if (!WRITE_VERBS.has(r.by.crud))
-            return { kind: "na" };
-        return {
-            kind: "violate",
-            note: "writer authority is not recorded as a field distinct from reader authority — both merged into the single `rbac_qui` column",
-        };
-    },
-};
+// §2 line 36: writer authority is "a **distinct** tier from the same set, resolved
+// from a verified identity"; §15 line 413: "writer tier present, distinct, one of
+// five"; line 63: "Reader and writer are two fields". DISTINCT is a property of
+// the FIELD, not of the value: the standard requires the writer tier to be
+// RECORDED apart from the reader tier so a `read=public write=admin` divergence
+// can be written — it nowhere forbids a tool whose writer tier happens to equal
+// its reader tier (an org member reading and writing its own org's rows). So an
+// equal VALUE conforms; a MERGED field (no separate record, or one cell naming
+// several tiers) violates.
+//
+// Material: the writer-tier side-car (src/oracle.ts WRITER_TIER_NAME), joined on
+// `outil`. Branches, per write row:
+//   side-car absent / unreadable           -> cnj, naming the file(s) looked at
+//   no side-car row for the tool           -> violate (tier absent)
+//   two rows with different tiers          -> violate (merged)
+//   tier empty / `?`                       -> violate (unknown)
+//   tier naming several tiers (a/b, a+b)   -> violate (merged)
+//   tier outside the five                  -> violate
+//   writer_gate empty or `mcp-scope:<t>`   -> cnj: the tier was not derived from
+//        a gate on a write door, so "resolved from a verified identity" is not
+//        evidenced by the side-car (never a silent pass)
+//   otherwise                              -> conform
+export const WRITER_TIERS = new Set([
+    "public",
+    "org-member",
+    "org-admin",
+    "fleet-internal",
+    "master",
+]);
+const UNKNOWN_TIER = new Set(["", "?", "unknown", "n/a", "tbd"]);
+const MERGED_TIER = /[/+,|&]|\s(and|or|et|ou)\s/i;
+export function makeR10(sideCar) {
+    return {
+        ruleId: "R-10",
+        id: "R-10 writer authority, distinct tier",
+        check: "writer tier recorded in its own field (side-car joined on `outil`), one of five, gated on a write door; equal-to-reader values conform (the field must be distinct, §2 line 36)",
+        classify: (r) => {
+            if (!WRITE_VERBS.has(r.by.crud))
+                return { kind: "na" };
+            const t = sideCar();
+            if (t.status === "absent")
+                return {
+                    kind: "cnj",
+                    note: `writer-tier side-car ${WRITER_TIER_NAME} ABSENT (${t.origin}; searched: ${t.searched.join(", ") || "<none>"}) — this oracle has write rows, so writer authority cannot be judged`,
+                };
+            if (t.status === "unreadable")
+                return { kind: "cnj", note: `writer-tier side-car ${t.path} unreadable — ${t.reason}` };
+            const file = basename(t.path);
+            const entries = t.byTool.get(r.by.outil) ?? [];
+            if (entries.length === 0)
+                return { kind: "violate", note: `no writer tier recorded for "${r.by.outil}" in ${file} — writer authority absent` };
+            const tiers = [...new Set(entries.map((e) => e.writer_tier))];
+            if (tiers.length > 1)
+                return {
+                    kind: "violate",
+                    note: `${file} records ${tiers.length} writer tiers for "${r.by.outil}" (${tiers.join(", ")}) — merged, not one tier`,
+                };
+            const tier = tiers[0];
+            if (UNKNOWN_TIER.has(tier.toLowerCase()))
+                return { kind: "violate", note: `writer_tier="${tier || "<empty>"}" for "${r.by.outil}" — unknown, not a tier` };
+            if (MERGED_TIER.test(tier))
+                return { kind: "violate", note: `writer_tier="${tier}" names several tiers — merged, not one tier` };
+            if (!WRITER_TIERS.has(tier))
+                return { kind: "violate", note: `writer_tier="${tier}" is none of the five tiers {${[...WRITER_TIERS].join(", ")}}` };
+            const gate = entries[0].writer_gate;
+            if (gate === "" || gate.startsWith("mcp-scope:"))
+                return {
+                    kind: "cnj",
+                    note: `writer_tier="${tier}" for "${r.by.outil}" rests on ${gate === "" ? "no writer_gate" : `the MCP-scope fallback "${gate}"`} — no write-door gate evidences resolution from a verified identity`,
+                };
+            return { kind: "conform" };
+        },
+    };
+}
+export const r10 = makeR10(readWriterTier);
 // ---- R-12 vector search declares namespace + topK -------------------------
 // §2 vector boundary -> `search_mecanisme`. §15: real namespace + numeric topK.
 export const r12 = {

package/dist/detectors/shared.js

@@ -1,4 +1,4 @@
-import { isInventoryRow, readOracle } from "../oracle.js";
+import { isInventoryRow, oracleLabel, readOracle, refuseWithoutOracle, } from "../oracle.js";
 /** Run a predicate over a row set, tallying per-kind. */
 export function tally(spec, rows) {
     const t = { conform: 0, violate: 0, cnj: 0, na: 0, violations: [], unjudged: [] };
@@ -52,7 +52,7 @@ export function evaluate(spec, rows) {
             .join("; ")}. This is NOT a clean bill. ${breakdown}`;
         return {
             id: spec.id,
-            anchor: anchorFor(t.unjudged, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.unjudged, oracleLabel()),
             state: "could-not-judge",
             verdict: reason,
             reason,
@@ -65,14 +65,14 @@ export function evaluate(spec, rows) {
             .join("; ");
         return {
             id: spec.id,
-            anchor: anchorFor(t.violations, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.violations, oracleLabel()),
             state: "non-conforming",
             verdict: `${spec.ruleId}: ${t.violate} of ${applicable} applicable oracle rows VIOLATE (${spec.check}). ${breakdown} Examples: ${examples}.`,
         };
     }
     return {
         id: spec.id,
-        anchor: "oracle:vp-by-tool-day158.csv",
+        anchor: oracleLabel(),
         state: "present",
         verdict: `${spec.ruleId}: ${t.conform} applicable oracle rows conform (${spec.check}); 0 violations. ${breakdown}`,
     };
@@ -85,7 +85,7 @@ export function evaluate(spec, rows) {
 export function makeOracleDetector(spec, rowsProvider = readOracle) {
     return {
         id: spec.id,
-        run: () => evaluate(spec, rowsProvider()),
+        run: () => refuseWithoutOracle(spec.id, () => evaluate(spec, rowsProvider())),
     };
 }
 // ---- small shared classifiers over oracle vocabulary --------------------

package/dist/detectors/source/backfill.js

@@ -73,7 +73,15 @@ export function derivedStructures(files) {
             if (FIELD_LINE.test(l.raw))
                 fields += 1;
             const id = ID_REF.exec(l.raw);
-            if (id && !fkTarget)
+            // A SYSTEM table (`_storage`, `_scheduled_functions` — Convex reserves the
+            // leading underscore) is not a source a migration can backfill FROM: its
+            // rows are platform objects, not domain rows, and there is no
+            // `ctx.db.query("_storage")` that enumerates what the write path would
+            // have bound. A table whose only foreign key points at a system table
+            // (a TOFU ownership binding of uploaded blobs, kbUploads) is therefore
+            // not a derived structure in R-44's sense. The first NON-system FK is
+            // the source; a table with none is skipped.
+            if (id && !fkTarget && !id[1].startsWith("_"))
                 fkTarget = id[1];
             if (HAS_INDEX.test(l.raw))
                 hasIndex = true;

package/dist/detectors/source/guard-helper-flow.d.ts

@@ -0,0 +1,112 @@
+import * as ts from "typescript";
+export type GuardHelperKind = "binds-arg" | "master-only";
+export type HelperVerdict = {
+    verdict: "honoured";
+} | {
+    verdict: "refused";
+    why: string;
+} | {
+    verdict: "could-not-judge";
+    why: string;
+};
+/** A callee name, as seen from the function being judged, resolved to its
+ * definition in the tree (and to a resolver for names seen from THAT file). */
+export type CallResolver = (name: string) => {
+    fn: ts.FunctionLikeDeclaration;
+    key: string;
+    resolve: CallResolver;
+} | undefined;
+/** Judge one helper function on its control flow. */
+export declare function judgeHelperFunction(fn: ts.FunctionLikeDeclaration, kind: GuardHelperKind): HelperVerdict;
+export interface FoundHelper {
+    name: string;
+    line: number;
+    exported: boolean;
+    judgement: HelperVerdict;
+}
+/** Every definition, in `source`, of a helper named in `kinds`. */
+export declare function findHelperDefinitions(fileName: string, source: string, kinds: Readonly<Record<string, GuardHelperKind>>): FoundHelper[];
+/** The arguments of each `await <helper>(…)` that is a DIRECT statement of the
+ * handler `name` (`export const name = mutation({ handler: … })`) and starts
+ * before `beforeLine`. A helper call nested in a branch, a try, or a closure of
+ * the handler is not a statement every path runs, so it is not returned.
+ * `null` = the handler's body could not be located in the file. */
+export declare function topLevelHelperCalls(fileName: string, source: string, handlerName: string, 
+/** `null` = any identifier callee (judged by the caller on its body). */
+helpers: ReadonlySet<string> | null, beforeLine: number): {
+    name: string;
+    args: string;
+    argNodes: readonly ts.Expression[];
+    line: number;
+}[] | null;
+export interface TopLevelFunction {
+    name: string;
+    line: number;
+    exported: boolean;
+    fn: ts.FunctionLikeDeclaration;
+}
+/** Every top-level function declaration and `const f = (…) => {…}` /
+ * `function (…) {…}` of a file. */
+export declare function topLevelFunctions(fileName: string, source: string): TopLevelFunction[];
+/** Judge a function as an IDENTITY RESOLVER (shape 1 above). */
+export declare function judgeResolverFunction(fn: ts.FunctionLikeDeclaration): HelperVerdict;
+export type ValidatorSummary = {
+    ok: false;
+    why: string;
+} | {
+    ok: true;
+    /** every normal exit binds the target parameter (or is the master's) */
+    exitsBound: boolean;
+    /** every normal exit is the fleet master's */
+    exitsMaster: boolean;
+    /** no normal exit at all: it refuses every caller */
+    never: boolean;
+};
+export declare function summarizeValidator(fn: ts.FunctionLikeDeclaration, o: {
+    /** the parameter whose binding is asked; undefined = master-only asked */
+    boundIdx: number | undefined;
+    /** the parameter receiving the caller's verified scope, if any */
+    identityIdx: number | undefined;
+    /** the call's arguments (object literals become constants) */
+    callArgs: readonly ts.Expression[];
+    resolve: CallResolver;
+    key: string;
+    depth: number;
+}): ValidatorSummary;
+/** Judge a function as a REFUSING PREDICATE (shape 2 above): parameter
+ * `identityIdx` receives the caller's verified scope, `boundIdx` the value the
+ * caller then writes. */
+export declare function judgePredicateFunction(fn: ts.FunctionLikeDeclaration, identityIdx: number, boundIdx: number): HelperVerdict;
+/** What a mutation handler's own body declares and refuses before `beforeLine`. */
+export interface HandlerGuards {
+    /** Top-level `const` locals: whether bound straight to an identity read, or
+     * to `await <callee>(…)` (the callee is then judged by the caller). */
+    consts: Map<string, {
+        identityRead: boolean;
+        awaitedCallee?: string;
+    }>;
+    /** `if (!P(a, b, …)) { …throw }` statements: the predicate and its args. */
+    refusals: {
+        predicate: string;
+        args: {
+            text: string;
+            ident?: string;
+            memberBase?: string;
+        }[];
+        line: number;
+    }[];
+}
+/** Read the direct statements of handler `name` before `beforeLine`. `null`
+ * when the handler's body cannot be located. */
+export declare function readHandlerGuards(fileName: string, source: string, handlerName: string, beforeLine: number): HandlerGuards | null;
+/** A CONDITIONAL boundary value at a write site (`orgId: c ? a : b`): which arm
+ * reads the caller's `args`, and whether the condition is a positive
+ * `<local>.isMaster` test (the fleet carve-out, which may write what the
+ * master names). Read with the TypeScript parser on the write-site text. */
+export interface ConditionalBoundary {
+    field: string;
+    masterBase?: string;
+    trueReadsArgs: boolean;
+    falseReadsArgs: boolean;
+}
+export declare function conditionalBoundaries(text: string, fields: ReadonlySet<string>): ConditionalBoundary[];