@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/crud-coverage.js

@@ -0,0 +1,375 @@
+// CRUD COVERAGE — an inventory/coverage report DIMENSION (not a numbered rule in
+// the pinned 50-rule standard). It answers, per SCHEMA TABLE derived at run time:
+// does a public convex create/get/update/remove exist, and (if an app routes dir
+// exists) a list/detail/edit route? Every cell is exactly one of
+// `present` | `ABSENT` | `n/a: <written reason>`.
+//
+// DERIVE-NEVER-TYPE: the rows are EVERY `defineTable` table parsed from the
+// target's schema.ts at run time (never a hand-typed subset). If the schema
+// cannot be parsed / yields no table, the report is `unreadable` (fail-closed) —
+// it must NEVER present a subset as a complete inventory.
+//
+// LOAD-BEARING: the union of the report's rows MUST equal the set of schema
+// tables. A schema table ABSENT from the rows is a DOCTOR DEFECT → the run is RED
+// (fail-closed), never a silent pass. `coverageUnionOk` is that assertion.
+//
+// Parsing reuses the R-46 approach (the TypeScript compiler API) — see
+// src/detectors/standard/r46-returns-validator.ts — so the table set is the same
+// truth R-46 derives, never a second, drifting parser.
+import * as ts from "typescript";
+import { deriveSchemaFields } from "./detectors/standard/r46-returns-validator.js";
+/** Extract react-router route paths from a router source (App.tsx / main.tsx /
+ *  a routes file): both the `<Route path="…">` element form and the
+ *  `createBrowserRouter([{ path: "…" }])` object form. Deduped. */
+export function extractReactRouterPaths(text) {
+    const paths = [];
+    const routeEl = /<Route\b[^>]*\bpath\s*=\s*["'`]([^"'`]*)["'`]/g;
+    const routeObj = /\bpath\s*:\s*["'`]([^"'`]*)["'`]/g;
+    for (const m of text.matchAll(routeEl))
+        paths.push(m[1]);
+    for (const m of text.matchAll(routeObj))
+        paths.push(m[1]);
+    return [...new Set(paths)];
+}
+// ---------------------------------------------------------------------------
+// Schema → table names. Reuse the R-46 derivation so there is ONE parser of
+// truth. Throwing / zero tables is surfaced by the caller as `unreadable`.
+// ---------------------------------------------------------------------------
+export function deriveTableNames(schemaText) {
+    return [...deriveSchemaFields(schemaText).keys()];
+}
+// ---------------------------------------------------------------------------
+// Public-handler bodies. We only judge PUBLIC query/mutation surface — the
+// internal* variants are not a user-facing CRUD path. Each public handler's
+// body text is extracted so the db-op scan never trips on a `v.id("table")` in
+// the args/returns validators (those live outside the handler body).
+// ---------------------------------------------------------------------------
+// A PUBLIC function-builder identifier: the bare `query`/`mutation`, or a repo
+// custom builder that ends in `Query`/`Mutation` (Convex convention — e.g.
+// `authedQuery`, `writeMutation`, `publicQuery`). `internal*` builders are NOT a
+// user-facing surface and are excluded, so an internalMutation write does not
+// count as a public CRUD path.
+function isPublicBuilder(name) {
+    if (/^internal/i.test(name))
+        return false;
+    return /(^query$|^mutation$|Query$|Mutation$)/.test(name);
+}
+function parse(name, text) {
+    return ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+/** Every PUBLIC query/mutation exported from one module, with its attribution
+ * inputs. Non-exported / internal* builders are excluded. */
+export function publicHandlers(name, text) {
+    let sf;
+    try {
+        sf = parse(name, text);
+    }
+    catch {
+        return [];
+    }
+    const fileBase = (name.split("/").pop() ?? name)
+        .replace(/\.ts$/, "")
+        .toLowerCase();
+    const handlers = [];
+    function fromConfig(config, exportName) {
+        let argsText = "";
+        let body = "";
+        for (const prop of config.properties) {
+            if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+                continue;
+            if (prop.name.text === "args")
+                argsText = prop.initializer.getText(sf);
+            if (prop.name.text === "handler")
+                body = prop.initializer.getText(sf);
+        }
+        handlers.push({ fileBase, exportName, argsText, body });
+    }
+    function visit(node) {
+        if (ts.isVariableStatement(node) &&
+            node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+            for (const decl of node.declarationList.declarations) {
+                if (!ts.isIdentifier(decl.name) || !decl.initializer)
+                    continue;
+                const init = decl.initializer;
+                if (ts.isCallExpression(init) &&
+                    ts.isIdentifier(init.expression) &&
+                    isPublicBuilder(init.expression.text)) {
+                    const arg = init.arguments[0];
+                    if (arg && ts.isObjectLiteralExpression(arg))
+                        fromConfig(arg, decl.name.text);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sf);
+    return handlers;
+}
+const CREATE_NAMES = new Set(["create", "add", "insert", "new"]);
+const GET_NAMES = new Set(["get", "getbyid", "detail", "show", "byid", "find"]);
+const UPDATE_NAMES = new Set(["update", "patch", "edit", "modify", "set"]);
+const REMOVE_NAMES = new Set(["remove", "delete", "del", "destroy", "archive"]);
+/** the schema table a file basename attributes to, singular/plural tolerant. */
+function schemaTableForBase(base, tables) {
+    for (const t of tables) {
+        const tl = t.toLowerCase();
+        if (base === tl)
+            return t;
+        if (base === singular(t).toLowerCase())
+            return t;
+        if (singular(base) === singular(t).toLowerCase())
+            return t;
+    }
+    return undefined;
+}
+const ID_ARG = /v\.id\(\s*["']([a-zA-Z_][\w]*)["']/g;
+const LITERAL_REF = /["']([a-zA-Z_][\w]*)["']/g;
+function attribute(handlers, tables) {
+    const tableSet = new Set(tables);
+    const present = new Map();
+    const touched = new Set();
+    const mark = (t, col) => {
+        if (!tableSet.has(t))
+            return;
+        let s = present.get(t);
+        if (!s) {
+            s = new Set();
+            present.set(t, s);
+        }
+        s.add(col);
+        touched.add(t);
+    };
+    const markLiterals = (body, op, col) => {
+        const re = new RegExp(`\\.db\\.${op}\\(\\s*["']([a-zA-Z_][\\w]*)["']`, "g");
+        for (const m of body.matchAll(re))
+            mark(m[1], col);
+    };
+    for (const h of handlers) {
+        // (3) explicit table-literal ops
+        markLiterals(h.body, "insert", "create");
+        markLiterals(h.body, "get", "get");
+        markLiterals(h.body, "patch", "update");
+        markLiterals(h.body, "replace", "update");
+        markLiterals(h.body, "delete", "remove");
+        // (1) args `v.id("<t>")` + body op with no table literal
+        const argT = new Set();
+        for (const m of h.argsText.matchAll(ID_ARG))
+            if (tableSet.has(m[1]))
+                argT.add(m[1]);
+        const bodyGet = /\.db\.get\s*\(/.test(h.body);
+        const bodyUpd = /\.db\.(patch|replace)\s*\(/.test(h.body);
+        const bodyDel = /\.db\.delete\s*\(/.test(h.body);
+        for (const t of argT) {
+            touched.add(t);
+            if (bodyGet)
+                mark(t, "get");
+            if (bodyUpd)
+                mark(t, "update");
+            if (bodyDel)
+                mark(t, "remove");
+        }
+        // (2) file basename + export name
+        const ft = schemaTableForBase(h.fileBase, tables);
+        if (ft) {
+            touched.add(ft);
+            const n = h.exportName.toLowerCase();
+            if (CREATE_NAMES.has(n))
+                mark(ft, "create");
+            if (GET_NAMES.has(n))
+                mark(ft, "get");
+            if (UPDATE_NAMES.has(n))
+                mark(ft, "update");
+            if (REMOVE_NAMES.has(n))
+                mark(ft, "remove");
+        }
+        // touched (for the n/a distinction): any schema-table name quoted anywhere.
+        for (const m of `${h.body}\n${h.argsText}`.matchAll(LITERAL_REF))
+            if (tableSet.has(m[1]))
+                touched.add(m[1]);
+    }
+    return { present, touched };
+}
+// ---------------------------------------------------------------------------
+// App-route detection. A route dir "exists in this tree" iff at least one route
+// file was probed. When none exists, list/detail/edit are n/a with the written
+// reason. When one exists, a table's route presence is judged by a path segment
+// matching the table name (or its singular), with `[..]`/detail and `edit`.
+// ---------------------------------------------------------------------------
+const NO_ROUTES = "n/a: no app routes dir in this tree";
+/** a dynamic route segment — Next `[id]` OR react-router `:id`. */
+const DYNAMIC_SEG = /\[[^\]]+\]|:[A-Za-z0-9_]+/;
+const EDIT_SEG = /\/edit(\/|$|\.)/;
+function singular(table) {
+    if (table.endsWith("ies"))
+        return `${table.slice(0, -3)}y`;
+    if (table.endsWith("s"))
+        return table.slice(0, -1);
+    return table;
+}
+function segMatches(path, table) {
+    const segs = path.toLowerCase().split("/");
+    const names = new Set([table.toLowerCase(), singular(table).toLowerCase()]);
+    return segs.some((s) => names.has(s));
+}
+/** Normalize the third scan argument: a bare `string[]` (legacy / Next-file list)
+ *  becomes a probe where a non-empty list means a router WAS recognised, and an
+ *  empty list means no candidate dir at all (`n/a`). A `RouteProbe` passes through. */
+function normalizeProbe(input) {
+    if (Array.isArray(input)) {
+        return {
+            routePaths: input,
+            candidateDir: input.length > 0 ? "app routes" : undefined,
+        };
+    }
+    return input;
+}
+function routeCells(table, probe) {
+    // A router WAS recognised (Next/SvelteKit files or react-router paths) — judge
+    // each table's presence against it. An unmatched table is a real ABSENT gap.
+    if (probe.routePaths.length > 0) {
+        const forTable = probe.routePaths.filter((p) => segMatches(p, table));
+        const hasList = forTable.some((p) => !DYNAMIC_SEG.test(p) && !EDIT_SEG.test(p));
+        const hasDetail = forTable.some((p) => DYNAMIC_SEG.test(p) && !EDIT_SEG.test(p));
+        const hasEdit = forTable.some((p) => EDIT_SEG.test(p));
+        return {
+            list: hasList ? "present" : "ABSENT",
+            detail: hasDetail ? "present" : "ABSENT",
+            edit: hasEdit ? "present" : "ABSENT",
+        };
+    }
+    // A candidate app/src dir EXISTS but no known router convention was recognised
+    // in it — presence was NOT measured. `could-not-judge` NAMING the dir, never
+    // `n/a` (which would falsely assert absence of a dir that is right there).
+    if (probe.candidateDir !== undefined) {
+        const cnj = `could-not-judge: routes dir "${probe.candidateDir}" exists but no known router convention (Next page.tsx / SvelteKit +page.svelte / react-router <Route path>/createBrowserRouter) was recognised — route presence was NOT measured, so this is could-not-judge, not an asserted absence`;
+        return { list: cnj, detail: cnj, edit: cnj };
+    }
+    // Genuinely no candidate routes dir at all — the only honest `n/a`.
+    return { list: NO_ROUTES, detail: NO_ROUTES, edit: NO_ROUTES };
+}
+// ---------------------------------------------------------------------------
+// The scan — one row per schema table, fail-closed on an unreadable schema.
+// ---------------------------------------------------------------------------
+export function scanCrudCoverage(schemaText, files, routeFiles) {
+    const probe = normalizeProbe(routeFiles);
+    if (schemaText === undefined) {
+        return unreadable("no schema.ts with a defineTable found in the target tree — the table set cannot be DERIVED (fail-closed, NOT an empty inventory)");
+    }
+    let tables;
+    try {
+        tables = deriveTableNames(schemaText);
+    }
+    catch (e) {
+        return unreadable(`schema.ts could not be parsed (${e.message}) — the table set cannot be DERIVED (fail-closed)`);
+    }
+    if (tables.length === 0) {
+        return unreadable("schema.ts parsed but yielded no defineTable tables — the inventory cannot be complete (fail-closed)");
+    }
+    // Collect every public handler across the convex tree once, then attribute
+    // its ops to tables via the three signals (v.id arg, filename, literal).
+    const handlers = [];
+    for (const f of files) {
+        if (/\.test\.ts$/.test(f.rel) || f.rel.includes("_generated/"))
+            continue;
+        if (/(^|\/)schema\.ts$/.test(f.rel))
+            continue;
+        handlers.push(...publicHandlers(f.rel, f.text));
+    }
+    const { present, touched } = attribute(handlers, tables);
+    const rows = [];
+    const absentCells = [];
+    for (const table of tables.slice().sort()) {
+        const cols = present.get(table) ?? new Set();
+        const rc = routeCells(table, probe);
+        // A table touched by NO public handler at all (no file, no literal, no v.id
+        // arg) is legitimately without a user-facing convex surface in this tree — an
+        // n/a with a written reason, not four bare ABSENT cells that read as gaps.
+        const naReason = `n/a: no public handler references table "${table}"`;
+        const isTouched = cols.size > 0 || touched.has(table);
+        const cell = (col) => isTouched ? (cols.has(col) ? "present" : "ABSENT") : naReason;
+        const row = {
+            table,
+            create: cell("create"),
+            get: cell("get"),
+            update: cell("update"),
+            remove: cell("remove"),
+            list: rc.list,
+            detail: rc.detail,
+            edit: rc.edit,
+        };
+        rows.push(row);
+        for (const col of [
+            "create",
+            "get",
+            "update",
+            "remove",
+            "list",
+            "detail",
+            "edit",
+        ]) {
+            if (row[col] === "ABSENT")
+                absentCells.push({ table, column: col });
+        }
+    }
+    const union = coverageUnionOk(tables, rows);
+    return {
+        status: "ok",
+        rows,
+        rowCount: rows.length,
+        schemaTableCount: tables.length,
+        unionEqualsSchema: union.ok,
+        absentCells,
+    };
+}
+function unreadable(reason) {
+    return {
+        status: "unreadable",
+        reason,
+        rows: [],
+        rowCount: 0,
+        schemaTableCount: 0,
+        unionEqualsSchema: false,
+        absentCells: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// The load-bearing coverage assertion: the rows' table union MUST equal the
+// schema table set. A schema table missing from the rows is a DOCTOR DEFECT.
+// ---------------------------------------------------------------------------
+export function coverageUnionOk(schemaTables, rows) {
+    const have = new Set(rows.map((r) => r.table));
+    const missing = schemaTables.filter((t) => !have.has(t)).sort();
+    return { ok: missing.length === 0, missing };
+}
+// ---------------------------------------------------------------------------
+// Rendering — the CLI section + the one-line summary.
+// ---------------------------------------------------------------------------
+function short(cell) {
+    if (cell === "present")
+        return "present";
+    if (cell === "ABSENT")
+        return "ABSENT ";
+    return cell; // n/a: ...
+}
+export function crudCoverageSection(cov) {
+    const header = "=== CRUD COVERAGE (per schema table, derived at run time) ===";
+    if (cov.status === "unreadable") {
+        return `${header}\n  UNREADABLE (fail-closed): ${cov.reason}\n${crudCoverageLine(cov)}`;
+    }
+    const lines = cov.rows.map((r) => {
+        return (`  ${r.table.padEnd(28)} ` +
+            `create=${short(r.create)} get=${short(r.get)} ` +
+            `update=${short(r.update)} remove=${short(r.remove)} ` +
+            `| list=${short(r.list)} detail=${short(r.detail)} edit=${short(r.edit)}`);
+    });
+    return `${header}\n${lines.join("\n")}\n${crudCoverageLine(cov)}`;
+}
+export function crudCoverageLine(cov) {
+    if (cov.status === "unreadable") {
+        return `coverage UNREADABLE (fail-closed) — ${cov.reason}`;
+    }
+    const defect = cov.unionEqualsSchema
+        ? ""
+        : " | DOCTOR DEFECT: rows do NOT cover the schema (RED, fail-closed)";
+    return `coverage rows=${cov.rowCount} schema tables=${cov.schemaTableCount} | ABSENT cells=${cov.absentCells.length}${defect}`;
+}

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 = {