@vantageos/backend-doctor 0.1.12 → 0.1.14

package/dist/cli.js

@@ -5,16 +5,17 @@
 // 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 { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { 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 { 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 { NOT_MECHANICALLY_CHECKABLE, notCheckableResults, } from "./not-checkable.js";
 import { REGISTRY } from "./registry.js";
 import { writeReport } from "./report.js";
-import { tally, tallyLine, verdict } from "./tally.js";
+import { handlerSurfaceLine, handlerSurfaceStats, 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) {
@@ -42,6 +43,110 @@ function toolVersion() {
     const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
     return pkg.version;
 }
+/** Recursively collect files under `dir` whose basename matches `pred`, as paths
+ * relative to `base`. Silently skips node_modules/.git and unreadable dirs. */
+function collectFiles(dir, base, pred, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name === "node_modules" || name === ".git")
+            continue;
+        const full = join(dir, name);
+        let isDir;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            collectFiles(full, base, pred, out);
+        else {
+            const rel = relative(base, full);
+            if (pred(rel))
+                out.push(rel);
+        }
+    }
+    return out;
+}
+/** Read the convex tree + the schema + probe an app routes dir, then render the
+ * CRUD coverage section. The target is the convex dir; the app routes dir is a
+ * sibling probe (`../src/app`, `../app`, `../src/routes`). */
+function scanCrudCoverageForCli(target) {
+    const convexRels = collectFiles(target, target, (rel) => rel.endsWith(".ts") && !rel.endsWith(".test.ts"));
+    const files = [];
+    let schemaText;
+    for (const rel of convexRels) {
+        let text;
+        try {
+            text = readFileSync(join(target, rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        files.push({ rel, text });
+        if (/(^|\/)schema\.ts$/.test(rel))
+            schemaText = text;
+    }
+    return scanCrudCoverage(schemaText, files, probeRoutes(target));
+}
+/** Probe the app-route surface as a sibling of the convex `target` dir. Reports
+ * BOTH whether a candidate app/src routes dir EXISTS and the route paths found in
+ * it, so the scan can tell "no routes dir" (n/a) from "dir exists, no router
+ * convention recognised" (could-not-judge) — Eta REVISE blocker 3. Recognises
+ * Next/SvelteKit convention files AND a react-router `<Route path>` /
+ * `createBrowserRouter` router in App.tsx/main.tsx/a routes file. */
+function probeRoutes(target) {
+    const ROUTE_FILE = /(^|\/)(page\.tsx|route\.tsx?|\+page\.svelte)$/;
+    const appRoot = resolve(target, "..");
+    let candidateDir;
+    const routePaths = [];
+    // (a) Next/SvelteKit convention dirs (a sibling of the convex target).
+    for (const candidate of ["src/app", "app", "src/routes"]) {
+        const routeRoot = join(appRoot, candidate);
+        let isDir = false;
+        try {
+            isDir = statSync(routeRoot).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir)
+            continue;
+        if (candidateDir === undefined)
+            candidateDir = candidate;
+        routePaths.push(...collectFiles(routeRoot, routeRoot, (rel) => ROUTE_FILE.test(rel)));
+    }
+    // (b) react-router (Vite SPA): parse the router source for its route paths.
+    for (const rel of [
+        "src/App.tsx",
+        "src/main.tsx",
+        "src/routes.tsx",
+        "src/router.tsx",
+        "App.tsx",
+        "main.tsx",
+    ]) {
+        const full = join(appRoot, rel);
+        let text;
+        try {
+            text = readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // the src dir hosting the router is a candidate app dir, even if its own
+        // route-path extraction turns up empty (→ could-not-judge, never n/a).
+        if (candidateDir === undefined)
+            candidateDir = dirname(rel) || rel;
+        routePaths.push(...extractReactRouterPaths(text));
+    }
+    return { candidateDir, routePaths };
+}
 function main() {
     const target = resolve(process.argv[2] ?? process.cwd());
     // Instrument self-check, BEFORE any judging: a backend-doctor run reads its
@@ -62,6 +167,14 @@ function main() {
         ...notCheckableResults(),
     ];
     console.log(renderTable("backend-doctor (VantagePeers oracle @ day158)", 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);
+    console.log(crudCoverageSection(crud));
+    const crudDefect = crud.status === "unreadable" || !crud.unionEqualsSchema;
     console.log("");
     const cov = coverage();
     console.log(coverageSummary(cov));
@@ -82,6 +195,10 @@ function main() {
     const v = verdict(t, results);
     console.log("");
     console.log(tallyLine(t));
+    // The handler-surface slice (R-50/R-51) reported APART from the doc/oracle/
+    // 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(v.summary);
     if (v.criticalViolations > 0) {
         console.log(`  critical violations: ${v.violations.critical.join(", ")}`);
@@ -105,6 +222,13 @@ function main() {
         console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
         process.exit(1);
     }
+    // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
+    // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
+    // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
+    if (crudDefect) {
+        console.log("\nNOTE: CRUD coverage self-check FAILED — the rows do not cover every schema table (or the schema is unreadable). See the CRUD COVERAGE section above.");
+        process.exit(1);
+    }
     process.exit(v.exitCode);
 }
 main();

package/dist/crud-coverage.d.ts

@@ -0,0 +1,81 @@
+/** A convex source file, reconstructed as text — the unit the scanner reads. */
+export interface SourceFile {
+    rel: string;
+    text: string;
+}
+/** Each cell is exactly one of these. `n/a: <reason>` (a MEASURED absence — there
+ *  is genuinely no candidate routes dir) and `could-not-judge: <reason>` (a
+ *  candidate dir EXISTS but no router convention was recognised, so presence was
+ *  NOT measured) are DISTINCT — `n/a` must never stand for an unmeasured cell. */
+export type Cell = "present" | "ABSENT" | `n/a: ${string}` | `could-not-judge: ${string}`;
+/**
+ * The app-route probe the CLI gathers from the filesystem and hands to the scan.
+ * It carries the two facts the cell disposition turns on: whether a candidate
+ * app/src routes dir EXISTS at all, and the normalized route paths recognised in
+ * it (Next/SvelteKit convention file rels AND react-router `<Route path>` /
+ * `createBrowserRouter` paths). The distinction closes Eta REVISE blocker 3:
+ * `n/a` asserts absence, but the pre-fix probe only knew its OWN matcher found
+ * nothing — a full react-router dir rendered n/a, a false assertion of absence.
+ */
+export interface RouteProbe {
+    /** a candidate app/src routes dir that EXISTS on disk, named — undefined iff
+     *  there is genuinely no candidate routes dir at all (the only `n/a` case). */
+    candidateDir?: string;
+    /** normalized route path strings — Next/SvelteKit file rels OR react-router
+     *  paths. Non-empty means a router WAS recognised and cells are judged. */
+    routePaths: string[];
+}
+/** 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 declare function extractReactRouterPaths(text: string): string[];
+export interface TableRow {
+    table: string;
+    create: Cell;
+    get: Cell;
+    update: Cell;
+    remove: Cell;
+    list: Cell;
+    detail: Cell;
+    edit: Cell;
+}
+export interface AbsentCell {
+    table: string;
+    column: string;
+}
+export interface CrudCoverage {
+    status: "ok" | "unreadable";
+    /** set when status === "unreadable" — names what could not be read. */
+    reason?: string;
+    rows: TableRow[];
+    rowCount: number;
+    schemaTableCount: number;
+    unionEqualsSchema: boolean;
+    absentCells: AbsentCell[];
+}
+export declare function deriveTableNames(schemaText: string): string[];
+/** One public query/mutation, with the three attribution inputs: the file it
+ * lives in, its export name, its `args:` validator text (for `v.id("<table>")`)
+ * and its handler body text (for the `ctx.db.*` op it performs). */
+export interface Handler {
+    /** module basename, lower-cased, no `.ts` (e.g. `tasks`). */
+    fileBase: string;
+    /** the export name (e.g. `get`, `update`, `remove`). */
+    exportName: string;
+    /** the `args:` object literal source text (may be ""). */
+    argsText: string;
+    /** the `handler:` function source text (may be ""). */
+    body: string;
+}
+/** Every PUBLIC query/mutation exported from one module, with its attribution
+ * inputs. Non-exported / internal* builders are excluded. */
+export declare function publicHandlers(name: string, text: string): Handler[];
+export declare function scanCrudCoverage(schemaText: string | undefined, files: SourceFile[], routeFiles: string[] | RouteProbe): CrudCoverage;
+export declare function coverageUnionOk(schemaTables: string[], rows: {
+    table: string;
+}[]): {
+    ok: boolean;
+    missing: string[];
+};
+export declare function crudCoverageSection(cov: CrudCoverage): string;
+export declare function crudCoverageLine(cov: CrudCoverage): string;

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/source/_scan.js

@@ -40,11 +40,16 @@ export function decide(ruleId, id, check, scan, emptyReason) {
         .map((x) => `${x.rel}:${x.n} (${x.note})`)
         .join("; ");
     if (nV > 0) {
+        // A non-conforming verdict must NAME its could-not-judge sites, not drop them
+        // to a bare integer in the breakdown — the one disposition that owes a human
+        // verdict is otherwise the only one printed without an address (Eta REVISE
+        // blocker 1: R-51 CRM could-not-judge=1 was counted but never located). The
+        // data is already in scan.cnj; list it under its own label whenever non-empty.
         return {
             id,
             anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
             state: "non-conforming",
-            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`,
+            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}${nJ ? ` could-not-judge sites (human verdict owed): ${fmt(scan.cnj)}.` : ""}`,
         };
     }
     if (nJ > 0) {

package/dist/detectors/source/isolation.js

@@ -342,7 +342,7 @@ export function scanR50(files) {
                 ungated.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public query with no org-throw, no fail-closed resolver, and no isolation-contract marker — no org-isolation handling is visible in convex/, and whether a subscribing client can reach it before an org exists is not statically decidable; a reviewer must confirm this read isolates by org (never a silent clean bill)`,
+                    note: `${fn}: public query with no org-throw, no fail-closed resolver, and no isolation-contract marker — an UNMARKED public read. No org-isolation handling and no client contract is visible in convex/; an instrument that abstains here protects nothing (a fully-unmarked read is exactly the surface a subscribing client can hit before an org exists). NON-CONFORMING until the author resolves org via a fail-closed non-throwing path (\`withOrgScope\`), returns a typed empty/unauthorized shape, or records an isolation-contract marker`,
                 });
                 continue;
             }
@@ -410,15 +410,15 @@ export function scanR50(files) {
     // so the verdict is CNJ-with-sites, not a misleading empty abstain. Gated on "scan
     // otherwise empty" so a tree that already produced subjects (VP: 20 conform) is
     // byte-for-byte unchanged.
-    // A bare ungated public read (no throw / resolver / marker) is NEVER a silent
-    // clean bill — whether the scan is otherwise empty (a fully-ungated backend) OR
-    // mixed (bare reads alongside gated subjects). Surface EVERY such read as
-    // could-not-judge naming its site: never conformed, never dropped. (Eta mixed-tree
-    // follow-up: the prior "scan otherwise empty" guard silently dropped bare ungated
-    // reads whenever any gated subject also existed — a bare read hidden behind a
-    // conforming sibling. Removed: the disposition is per-def, not per-tree.)
+    // An UNMARKED bare public read (no throw / resolver / marker) is NON-CONFORMING,
+    // never an abstention — whether the scan is otherwise empty (a fully-unmarked
+    // backend) OR mixed (bare reads alongside gated subjects). Laurent doctrine: "an
+    // instrument that cannot go red protects nothing; CNJ is for UNREADABLE input
+    // only." A bare read is fully READABLE — its two absences (no isolation, no
+    // contract) are the defect, not a could-not-read. Push to violate; the author's
+    // exit is a resolver, a typed-empty return, or a recorded isolation-contract marker.
     for (const u of ungated)
-        scan.cnj.push(u);
+        scan.violate.push(u);
     return scan;
 }
 export const R50 = srcDetector("R-50", "R-50 org isolation on a reactively-subscribed read returns a typed empty/unauthorized result, never an uncaught throw", "a public query that resolves org via a fail-closed non-throwing path or documents its client contract — it never throws on the missing-org path a subscribing client cannot catch", scanR50, "R-50: no public query matched in the scanned tree — no reactive read to certify. NOT a clean bill.");

package/dist/detectors/source/write-isolation.js

@@ -252,7 +252,7 @@ export function scanR51(files) {
                 ungated.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public mutation with no org-throw, no typed-unauthorized return, and no write-contract marker — no org-isolation handling is visible in convex/, and whether a client can reach it before an org exists is not statically decidable; a reviewer must confirm this write isolates by org (never a silent clean bill)`,
+                    note: `${fn}: public mutation with no org-throw, no typed-unauthorized return, and no write-contract marker — an UNMARKED public write. No org-isolation handling and no client contract is visible in convex/; an instrument that abstains here protects nothing (a fully-unmarked write is exactly the surface a pre-org client shell can issue). NON-CONFORMING until the author isolates org via a fail-closed path, returns a typed unauthorized result, or records a write-contract marker`,
                 });
                 continue; // not a gated subject
             }
@@ -321,16 +321,16 @@ export function scanR51(files) {
     // abstain. Gated on "scan otherwise empty" so a tree that already produced
     // subjects (VP: 7 marker CNJ) is byte-for-byte unchanged — the bare-write
     // disposition in a mixed tree is out of this fix's scope.
-    // A bare ungated public write (no throw / typed-unauth / marker) is NEVER a silent
-    // clean bill — whether the scan is otherwise empty (a fully-ungated public-write
-    // surface) OR mixed (bare writes alongside gated/marker subjects). Surface EVERY
-    // such write as could-not-judge naming its site: never conformed, never dropped.
-    // (Eta mixed-tree follow-up: the prior "scan otherwise empty" guard silently
-    // dropped bare ungated writes whenever any gated/marker subject also existed — a
-    // bare write hidden behind a sibling that happened to produce a verdict. Removed:
-    // the disposition is per-def, not per-tree.)
+    // An UNMARKED bare public write (no throw / typed-unauth / marker) is
+    // NON-CONFORMING, never an abstention — whether the scan is otherwise empty (a
+    // fully-unmarked public-write surface) OR mixed (bare writes alongside
+    // gated/marker subjects). Laurent doctrine: "an instrument that cannot go red
+    // protects nothing; CNJ is for UNREADABLE input only." A bare write is fully
+    // READABLE — its two absences (no isolation, no contract) are the defect, not a
+    // could-not-read. Push to violate; the author's exit is a fail-closed path, a
+    // typed unauthorized return, or a recorded write-contract marker.
     for (const u of ungated)
-        scan.cnj.push(u);
+        scan.violate.push(u);
     return scan;
 }
 export const R51 = srcDetector("R-51", "R-51 a public mutation returns a typed unauthorized result on the no-org path, never an uncaught throw a pre-org client shell cannot render", "a public write either returns a typed unauthorized result / documents its client contract, or a human confirms a pre-org client cannot reach it — it never throws NO_ORG on a path an ordinary render can hit", scanR51, "R-51: no public mutation matched in the scanned tree — no write to certify. NOT a clean bill.");

package/dist/detectors/source/writesafety.js

@@ -179,22 +179,23 @@ const LOOP_NAMED = /\bfor\s*\(|\bfor\s+(?:const|let|var|await)\b|\.forEach\s*\(|
 const INDEPENDENCE_STATED = /no\s+invariant\s+spans|invariant\s+spans\s+no|writes?\s+are\s+independent|independently\s+atomic|no\s+cross-write\s+invariant/i;
 // Shape-(1) sub-condition (Eta REVISE #26, 2026-08-31): "a pre-I/O gate mutation
 // precedes a single atomic write" describes itself CHECKABLY — it is EXACTLY TWO
-// ctx.runMutation calls, the FIRST a gate (require*/assert*/ensure*/bind*). A shape-1
+// ctx.runMutation calls, the FIRST a gate (require*/assert*/bind*). A shape-1
 // marker on anything else (three calls, an unbounded loop, a first call that is not a
 // gate) is INCOMPLETE and stays non-conforming, exactly as an incomplete shape-2 does
 // — otherwise eleven words in a comment remove a real violation from the #1250 prod
 // gate (abstentions do not block; mechanical_violations is the sole driver), and the
 // mechanical count that gate rests on is no longer honest.
-const GATE_CALLEE = /\b(require|assert|ensure|bind)\w*/i;
-// Shape (3) narrows the gate stems: `ensure*` is the standard prefix for an UPSERT
-// WRITE helper (ensureUser/ensureWorkspace/ensureRow), so on the reingest shape — whose
-// FIRST runMutation is the gate — accepting `ensure*` lets a first WRITE renamed the
-// usual way (e.g. _insertImportedMemory -> ensureImportedMemory) masquerade as the gate
-// and buy the exemption, removing a real violation from the #1250 prod gate (Eta REVISE
-// #27, probe B). `bind` STAYS (bindOrAssertStorageOwnership is kb.ts's real gate, the
-// case this shape exists for); `require`/`assert` are unambiguous. Shapes 1/2 keep the
-// broader GATE_CALLEE.
-const GATE_CALLEE_REINGEST = /\b(require|assert|bind)\w*/i;
+// The gate stem excludes `ensure*` — the standard prefix for an UPSERT WRITE helper
+// (ensureUser/ensureWorkspace/ensureRow). Both shapes whose FIRST runMutation is the gate
+// (shape 1 pre-io-gate, shape 3 gate-then-idempotent-reingest) checked the callee NAME, so
+// accepting `ensure*` let a first WRITE renamed the usual way (_insertImportedMemory ->
+// ensureImportedMemory) masquerade as the gate and buy the exemption — removing a real
+// violation from the #1250 prod gate. Fixed at the CLASS (Eta REVISE #27 probe B closed
+// shape 3; this closes the same hole in shape 1, task k179fmje8vb7y0tbjdmxbzg78h8dhj3q):
+// the defect was a gate sub-condition decided by a name stem that idiomatically names
+// writes, so the fix is one narrowed stem set for every gate check. `bind` STAYS
+// (bindOrAssertStorageOwnership is kb.ts's real gate); `require`/`assert` are unambiguous.
+const GATE_CALLEE = /\b(require|assert|bind)\w*/i;
 export function scanR29(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -218,7 +219,7 @@ export function scanR29(files) {
                 const shapeGate = count === 2 && GATE_CALLEE.test(firstMutCallee);
                 // Shape (3) sub-conditions: a leading gate runMutation, a supersede/dedup on
                 // a stable namespace, a re-insert loop, AND an explicit convergence statement.
-                const shapeReingest = GATE_CALLEE_REINGEST.test(firstMutCallee) &&
+                const shapeReingest = GATE_CALLEE.test(firstMutCallee) &&
                     REINGEST_SUPERSEDE.test(region) &&
                     STABLE_KEY.test(region) &&
                     LOOP_NAMED.test(region) &&
@@ -240,7 +241,7 @@ export function scanR29(files) {
                             ? "the region names its loop and states the per-item writes are independently atomic (no invariant spans two)"
                             : shape === SHAPE_GATE_REINGEST
                                 ? "a leading gate runMutation, a supersede/dedup keyed on a stable namespace, and a recovering re-insert loop, with the convergence stated explicitly — a re-ingest of the same stable key converges on one current set"
-                                : "exactly two runMutations, the first a gate (require*/assert*/ensure*/bind*) preceding a single atomic write, which R-29's <=1 bar has no room for"}. R-29 refuses (a reviewer verifies the claim per site) — never a silent green (Eta ruling 2026-08-31)`,
+                                : "exactly two runMutations, the first a gate (require*/assert*/bind*) preceding a single atomic write, which R-29's <=1 bar has no room for"}. R-29 refuses (a reviewer verifies the claim per site) — never a silent green (Eta ruling 2026-08-31)`,
                     });
                 }
                 else if (shape === SHAPE_GATE_REINGEST) {
@@ -248,7 +249,7 @@ export function scanR29(files) {
                     // NOT buy could-not-judge (Eta: a shape names a checkable sub-condition, or
                     // the carve-out becomes a vocabulary).
                     const missing = [
-                        !GATE_CALLEE_REINGEST.test(firstMutCallee) && "a leading gate runMutation (require*/assert*/bind* — ensure* is an upsert-write stem, excluded here)",
+                        !GATE_CALLEE.test(firstMutCallee) && "a leading gate runMutation (require*/assert*/bind* — ensure* is an upsert-write stem, excluded here)",
                         !REINGEST_SUPERSEDE.test(region) && "a supersede/dedup call",
                         !STABLE_KEY.test(region) && "a stable namespace key (namespace/docId/contentHash)",
                         !LOOP_NAMED.test(region) && "a re-insert loop (for/for-of/.forEach/.map)",
@@ -266,7 +267,7 @@ export function scanR29(files) {
                     scan.violate.push({
                         rel: f.rel,
                         n: firstMut || openLine,
-                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls with an atomicity-exception "${SHAPE_PRE_IO_GATE}" marker that is INCOMPLETE — this shape is EXACTLY TWO runMutations whose FIRST is a gate (require*/assert*/ensure*/bind*); here ${count !== 2
+                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls with an atomicity-exception "${SHAPE_PRE_IO_GATE}" marker that is INCOMPLETE — this shape is EXACTLY TWO runMutations whose FIRST is a gate (require*/assert*/bind*); here ${count !== 2
                             ? `there are ${count}, not two`
                             : "the first runMutation is not a gate call"}. A gate-then-single-write is checkable; a marker cannot remove a >2-call or loop site from the gate`,
                     });

package/dist/tally.d.ts

@@ -53,5 +53,40 @@ export interface Verdict {
  * on an exit that means abstention.
  */
 export declare function verdict(t: Tally, results: DetectorResult[], severity?: Map<string, Severity>): Verdict;
+/**
+ * The HANDLER-SURFACE rules — the source/*-isolation detectors that judge the
+ * public query/mutation surface (R-50 read-isolation, R-51 write-isolation).
+ * Reported APART from the document/oracle/process rules (R-32, R-37, R-40,
+ * R-48, …) so the handler-surface could-not-judge count is visible on its own
+ * and can be driven to 0 without conflating it with honest human-gate CNJ.
+ * Laurent doctrine: an instrument that cannot go red protects nothing — the
+ * handler-surface CNJ must reach 0 except genuine parse-fail / marker-borne /
+ * ambiguous-domination sites.
+ */
+export declare const HANDLER_SURFACE_RULES: readonly string[];
+export interface HandlerSurfaceStats {
+    byState: Record<State, number>;
+    /** rule-level state per handler-surface ruleId (worst across its results). */
+    ruleState: Map<string, State>;
+    /** the handler-surface could-not-judge RULE count — R-50/R-51 as rules abstain
+     *  or they don't. This is 0 whenever both rules reach a verdict, EVEN when the
+     *  underlying sites include abstaining ones — so it must never be printed alone. */
+    couldNotJudge: number;
+    /** the handler-surface could-not-judge SITE count — the sum of every rule's
+     *  scan.cnj length, parsed from each result's `could-not-judge=N` breakdown. A
+     *  non-conforming rule can still carry abstaining SITES (Eta REVISE blocker 2:
+     *  the CRM run had rules-abstaining=0 while 8 sites abstained). Both are printed. */
+    sitesAbstaining: number;
+}
+/**
+ * The handler-surface slice of the tally, computed over HANDLER_SURFACE_RULES
+ * only. Reduces each rule to its worst result state (same reduction as `tally`)
+ * so a rule with any non-conforming result reads non-conforming, and surfaces a
+ * distinct handler-surface could-not-judge count the CLI prints separately.
+ */
+export declare function handlerSurfaceStats(results: DetectorResult[], handlerRules?: readonly string[]): HandlerSurfaceStats;
+/** The one-line handler-surface tally string the CLI prints, apart from the
+ *  document/oracle/process rules. */
+export declare function handlerSurfaceLine(s: HandlerSurfaceStats): string;
 /** The one-line machine tally string the CLI prints. */
 export declare function tallyLine(t: Tally): string;

package/dist/tally.js

@@ -19,7 +19,12 @@ const STATE_RANK = {
     absent: 1,
     present: 0,
 };
-const ALL_STATES = ["present", "non-conforming", "could-not-judge", "absent"];
+const ALL_STATES = [
+    "present",
+    "non-conforming",
+    "could-not-judge",
+    "absent",
+];
 /** Extract the ruleId (`R-N`) a result belongs to, from its leading id token. */
 export function ruleIdOf(result) {
     const m = /^(R-\d+)\b/.exec(result.id);
@@ -143,6 +148,75 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
         summary,
     };
 }
+/**
+ * The HANDLER-SURFACE rules — the source/*-isolation detectors that judge the
+ * public query/mutation surface (R-50 read-isolation, R-51 write-isolation).
+ * Reported APART from the document/oracle/process rules (R-32, R-37, R-40,
+ * R-48, …) so the handler-surface could-not-judge count is visible on its own
+ * and can be driven to 0 without conflating it with honest human-gate CNJ.
+ * Laurent doctrine: an instrument that cannot go red protects nothing — the
+ * handler-surface CNJ must reach 0 except genuine parse-fail / marker-borne /
+ * ambiguous-domination sites.
+ */
+export const HANDLER_SURFACE_RULES = ["R-50", "R-51"];
+// The per-rule breakdown token every source detect() emits: `could-not-judge=N`.
+// The site figure is the sum of N across the handler-surface rules' results — the
+// same N that names the sites under decide()'s CNJ label, never a re-derivation.
+const CNJ_SITES_IN_VERDICT = /could-not-judge=(\d+)/;
+/**
+ * The handler-surface slice of the tally, computed over HANDLER_SURFACE_RULES
+ * only. Reduces each rule to its worst result state (same reduction as `tally`)
+ * so a rule with any non-conforming result reads non-conforming, and surfaces a
+ * distinct handler-surface could-not-judge count the CLI prints separately.
+ */
+export function handlerSurfaceStats(results, handlerRules = HANDLER_SURFACE_RULES) {
+    const set = new Set(handlerRules);
+    const ruleState = new Map();
+    // Sites abstaining is summed over the RAW results (before the rule reduction),
+    // so a non-conforming rule's abstaining sites are still counted — one entry per
+    // rule's single reduced result here, but robust to multi-result rules.
+    const cnjSitesByRule = new Map();
+    for (const r of results) {
+        const id = ruleIdOf(r);
+        if (!set.has(id))
+            continue;
+        const prev = ruleState.get(id);
+        if (prev === undefined || STATE_RANK[r.state] > STATE_RANK[prev]) {
+            ruleState.set(id, r.state);
+        }
+        const m = CNJ_SITES_IN_VERDICT.exec(r.verdict);
+        if (m)
+            cnjSitesByRule.set(id, (cnjSitesByRule.get(id) ?? 0) + Number(m[1]));
+    }
+    const byState = {
+        present: 0,
+        "non-conforming": 0,
+        "could-not-judge": 0,
+        absent: 0,
+    };
+    for (const s of ruleState.values())
+        byState[s] += 1;
+    let sitesAbstaining = 0;
+    for (const n of cnjSitesByRule.values())
+        sitesAbstaining += n;
+    return {
+        byState,
+        ruleState,
+        couldNotJudge: byState["could-not-judge"],
+        sitesAbstaining,
+    };
+}
+/** The one-line handler-surface tally string the CLI prints, apart from the
+ *  document/oracle/process rules. */
+export function handlerSurfaceLine(s) {
+    const ids = [...s.ruleState.entries()]
+        .map(([id, st]) => `${id}=${st}`)
+        .join(", ");
+    return (`HANDLER-SURFACE TALLY (${HANDLER_SURFACE_RULES.join("+")}, reported apart from doc/oracle/process rules): ` +
+        `present=${s.byState.present} non-conforming=${s.byState["non-conforming"]} ` +
+        `could-not-judge=${s.byState["could-not-judge"]} absent=${s.byState.absent}` +
+        `${ids ? ` [${ids}]` : ""} | rules abstaining=${s.couldNotJudge} | sites abstaining=${s.sitesAbstaining}`);
+}
 /** The one-line machine tally string the CLI prints. */
 export function tallyLine(t) {
     return (`TALLY (by rule, ${t.ruleTotal} rules from ${t.resultTotal} results): ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "A conformance instrument that measures the VantagePeers backend against the pinned backend standard. The THIRD doctor built ON the @vantageos/mcp-doctor engine — never a third engine. It consumes runDoctor/renderTable and adds only detectors.",
   "type": "module",
   "main": "./dist/cli.js",