@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/_ast.js

@@ -0,0 +1,353 @@
+// Shared TypeScript-AST primitives for the R-52 / R-53 source detectors.
+//
+// Both rules read the SAME delivered material — the schema's tenant columns, every
+// public write handler, and the helper functions a handler calls — and both need
+// the parser rather than a line regex: R-52 traces a selector's provenance across
+// statements, R-53 reads the operands of an admission comparison. One parse per
+// file, one function index per tree; nothing here decides a verdict.
+import * as ts from "typescript";
+export function sourceOf(f) {
+    return f.lines.map((l) => l.raw).join("\n");
+}
+export function parseFile(f) {
+    return {
+        rel: f.rel,
+        sf: ts.createSourceFile(f.rel, sourceOf(f), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+    };
+}
+export function lineOf(n) {
+    const sf = n.getSourceFile();
+    return sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
+}
+/** Strip `await`, parentheses, `!` non-null, `as`/`satisfies` casts. */
+export function unwrap(e) {
+    let x = e;
+    for (;;) {
+        if (ts.isAwaitExpression(x) ||
+            ts.isParenthesizedExpression(x) ||
+            ts.isNonNullExpression(x) ||
+            ts.isAsExpression(x) ||
+            ts.isSatisfiesExpression(x))
+            x = x.expression;
+        else
+            return x;
+    }
+}
+/** A property read: `x.prop`, or `x["prop"]` (a string-literal element access
+ * is the same read, spelled differently). A computed key is not a read of a
+ * known property and gives undefined. */
+export function propRead(e) {
+    if (ts.isPropertyAccessExpression(e))
+        return { obj: e.expression, name: e.name.text };
+    if (ts.isElementAccessExpression(e) &&
+        ts.isStringLiteralLike(e.argumentExpression))
+        return { obj: e.expression, name: e.argumentExpression.text };
+    return undefined;
+}
+/** The initializer of the NEAREST `const <id> = <init>` visible from `id`, or
+ * undefined (a parameter or a `let` in between shadows it, so does a
+ * destructure). Exactly one level: the caller never follows an alias of an
+ * alias. */
+export function constInit(id) {
+    for (let x = id.parent; x; x = x.parent) {
+        if (ts.isFunctionLike(x) &&
+            x.parameters.some((q) => ts.isIdentifier(q.name) && q.name.text === id.text))
+            return undefined;
+        const stmts = ts.isBlock(x) || ts.isSourceFile(x) || ts.isModuleBlock(x)
+            ? x.statements
+            : ts.isCaseClause(x) || ts.isDefaultClause(x)
+                ? x.statements
+                : undefined;
+        if (!stmts)
+            continue;
+        for (const st of stmts) {
+            if (!ts.isVariableStatement(st))
+                continue;
+            for (const d of st.declarationList.declarations)
+                if (ts.isIdentifier(d.name) && d.name.text === id.text)
+                    return st.declarationList.flags & ts.NodeFlags.Const
+                        ? d.initializer
+                        : undefined;
+        }
+    }
+    return undefined;
+}
+/** `e` as a property read, one const alias deep: `x.p`, `x["p"]`, or an
+ * identifier declared `const a = x.p` / `const a = x["p"]` (read as `x.p`). */
+export function propReadResolved(e) {
+    const u = unwrap(e);
+    const direct = propRead(u);
+    if (direct)
+        return direct;
+    if (!ts.isIdentifier(u))
+        return undefined;
+    const init = constInit(u);
+    return init ? propRead(unwrap(init)) : undefined;
+}
+/** Visit every descendant of `n` (pre-order), NOT descending into nested
+ * function bodies when `ownOnly` is set. */
+export function walk(n, visit, ownOnly = false) {
+    const rec = (x) => {
+        visit(x);
+        if (ownOnly &&
+            x !== n &&
+            (ts.isFunctionDeclaration(x) ||
+                ts.isFunctionExpression(x) ||
+                ts.isArrowFunction(x)))
+            return;
+        ts.forEachChild(x, rec);
+    };
+    rec(n);
+}
+/** `a.b.c` as text, or undefined when the expression is not a dotted chain. */
+export function dotted(e) {
+    const x = unwrap(e);
+    if (ts.isIdentifier(x))
+        return x.text;
+    if (ts.isPropertyAccessExpression(x)) {
+        const head = dotted(x.expression);
+        return head === undefined ? undefined : `${head}.${x.name.text}`;
+    }
+    return undefined;
+}
+/** The callee's last name: `ctx.db.patch` -> `patch`, `helper` -> `helper`. */
+export function calleeName(c) {
+    const e = unwrap(c.expression);
+    if (ts.isIdentifier(e))
+        return e.text;
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text;
+    return undefined;
+}
+const BUILDERS = new Set([
+    "mutation",
+    "action",
+    "query",
+    "internalMutation",
+    "internalAction",
+    "internalQuery",
+]);
+export function idTableOf(text) {
+    const m = /^\s*(?:v\.optional\(\s*)?v\.id\(\s*["'`]([A-Za-z0-9_]+)["'`]\s*\)/.exec(text);
+    return m?.[1];
+}
+/** The ONE table a validator's text references through `v.id("T")` — through
+ * `v.optional`, `v.array`, or a nested `v.object` — or undefined when it names
+ * none or several. */
+export function singleIdTable(text) {
+    const ts_ = new Set([...text.matchAll(/v\.id\(\s*["'`]([A-Za-z0-9_]+)["'`]\s*\)/g)].map((m) => m[1]));
+    return ts_.size === 1 ? [...ts_][0] : undefined;
+}
+/** The object literal of an `args:` validator: inline, `v.object({…})`, or a
+ * same-file top-level const naming either. */
+function argsObject(p, e0) {
+    const e = unwrap(e0);
+    if (ts.isObjectLiteralExpression(e))
+        return e;
+    if (ts.isCallExpression(e) &&
+        calleeName(e) === "object" &&
+        e.arguments[0] &&
+        ts.isObjectLiteralExpression(unwrap(e.arguments[0])))
+        return unwrap(e.arguments[0]);
+    if (ts.isIdentifier(e)) {
+        for (const st of p.sf.statements) {
+            if (!ts.isVariableStatement(st))
+                continue;
+            for (const d of st.declarationList.declarations)
+                if (ts.isIdentifier(d.name) && d.name.text === e.text && d.initializer)
+                    return argsObject(p, d.initializer);
+        }
+    }
+    return undefined;
+}
+/** Every `export const NAME = <builder>({ … handler … })` of a file. */
+export function registrations(p) {
+    const out = [];
+    for (const st of p.sf.statements) {
+        if (!ts.isVariableStatement(st))
+            continue;
+        for (const d of st.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name) || !d.initializer)
+                continue;
+            const init = unwrap(d.initializer);
+            if (!ts.isCallExpression(init))
+                continue;
+            const b = calleeName(init);
+            if (b === undefined || !BUILDERS.has(b))
+                continue;
+            const cfg = init.arguments[0];
+            if (!cfg || !ts.isObjectLiteralExpression(cfg))
+                continue;
+            let handler;
+            const argIdTable = new Map();
+            for (const prop of cfg.properties) {
+                const key = prop.name && ts.isIdentifier(prop.name) ? prop.name.text : undefined;
+                if (key === "handler") {
+                    if (ts.isMethodDeclaration(prop))
+                        handler = prop;
+                    else if (ts.isPropertyAssignment(prop)) {
+                        const h = unwrap(prop.initializer);
+                        if (ts.isArrowFunction(h) || ts.isFunctionExpression(h))
+                            handler = h;
+                    }
+                }
+                if (key === "args" && ts.isPropertyAssignment(prop)) {
+                    const obj = argsObject(p, prop.initializer);
+                    for (const a of obj?.properties ?? []) {
+                        if (ts.isPropertyAssignment(a) && ts.isIdentifier(a.name)) {
+                            const t = singleIdTable(a.initializer.getText(p.sf));
+                            if (t)
+                                argIdTable.set(a.name.text, t);
+                        }
+                    }
+                }
+            }
+            if (handler === undefined)
+                continue;
+            out.push({
+                name: d.name.text,
+                builder: b,
+                rel: p.rel,
+                line: lineOf(d),
+                handler,
+                argIdTable,
+            });
+        }
+    }
+    return out;
+}
+/** Every top-level `function f` / `const f = (…) => …` across the parsed files. */
+export function indexFunctions(ps) {
+    const idx = new Map();
+    const add = (d) => {
+        const xs = idx.get(d.name) ?? [];
+        xs.push(d);
+        idx.set(d.name, xs);
+    };
+    for (const p of ps) {
+        for (const st of p.sf.statements) {
+            if (ts.isFunctionDeclaration(st) && st.name && st.body)
+                add({ name: st.name.text, rel: p.rel, line: lineOf(st), fn: st });
+            else if (ts.isVariableStatement(st))
+                for (const d of st.declarationList.declarations) {
+                    const init = d.initializer && unwrap(d.initializer);
+                    if (ts.isIdentifier(d.name) &&
+                        init &&
+                        (ts.isArrowFunction(init) || ts.isFunctionExpression(init)))
+                        add({ name: d.name.text, rel: p.rel, line: lineOf(d), fn: init });
+                }
+        }
+    }
+    return idx;
+}
+/** Names of the plain-identifier functions a body calls. */
+export function calledNames(fn) {
+    const out = new Set();
+    walk(fn, (x) => {
+        if (ts.isCallExpression(x)) {
+            const e = unwrap(x.expression);
+            if (ts.isIdentifier(e))
+                out.add(e.text);
+        }
+    });
+    return out;
+}
+/** A per-function boolean property closed over the call graph: `own(fn)` holds,
+ * or the function calls (by name) another function for which it holds. */
+export function closeOverCalls(idx, own) {
+    const holds = new Set();
+    for (const [n, ds] of idx)
+        if (ds.some(own))
+            holds.add(n);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [n, ds] of idx) {
+            if (holds.has(n))
+                continue;
+            if (ds.some((d) => [...calledNames(d.fn)].some((c) => holds.has(c)))) {
+                holds.add(n);
+                grew = true;
+            }
+        }
+    }
+    return holds;
+}
+// ---- schema ---------------------------------------------------------------
+/** The tenant columns, as standard 2825122 §4 R-52 lists them:
+ * `orgId`/`tenantId`/`workspaceId`/`orgSlug` (vantage-peers stamps its agents
+ * under `orgSlug: client_org_mapping.clerkOrgSlug`). A `namespace` is NOT in this
+ * set: the standard counts it only when it is "checked against the caller's
+ * allowed prefixes", which is a property of the code around the table, not of
+ * the schema. `readSchema` records it apart (`SchemaTable.namespace`) and R-52
+ * decides it per table (cross-tenant-write.ts `namespaceDecisions`). */
+export const TENANT_COLUMNS = new Set([
+    "orgId",
+    "tenantId",
+    "workspaceId",
+    "orgSlug",
+]);
+/** The column that is a tenant column only where it is prefix-checked. */
+export const NAMESPACE_COLUMN = "namespace";
+/** Read every `name: defineTable({...})` of a schema file. */
+export function readSchema(p) {
+    const out = new Map();
+    walk(p.sf, (x) => {
+        if (!ts.isPropertyAssignment(x) || !ts.isIdentifier(x.name))
+            return;
+        // the initializer is `defineTable({...})` possibly chained `.index(...)`.
+        let e = x.initializer;
+        for (;;) {
+            const u = unwrap(e);
+            if (ts.isCallExpression(u) &&
+                ts.isPropertyAccessExpression(u.expression)) {
+                e = u.expression.expression;
+                continue;
+            }
+            e = u;
+            break;
+        }
+        if (!ts.isCallExpression(e) ||
+            calleeName(e) !== "defineTable" ||
+            !e.arguments[0] ||
+            !ts.isObjectLiteralExpression(e.arguments[0]))
+            return;
+        const fields = [];
+        const idRef = new Map();
+        let tenant = "none";
+        let namespace = "none";
+        for (const prop of e.arguments[0].properties) {
+            if (!ts.isPropertyAssignment(prop))
+                continue;
+            const k = ts.isIdentifier(prop.name)
+                ? prop.name.text
+                : ts.isStringLiteral(prop.name)
+                    ? prop.name.text
+                    : undefined;
+            if (k === undefined)
+                continue;
+            fields.push(k);
+            const text = prop.initializer.getText(p.sf);
+            const t = idTableOf(text);
+            if (t)
+                idRef.set(k, t);
+            const opt = /^\s*v\.optional\(/.test(text);
+            if (TENANT_COLUMNS.has(k)) {
+                if (!opt)
+                    tenant = "required";
+                else if (tenant === "none")
+                    tenant = "optional";
+            }
+            if (k === NAMESPACE_COLUMN)
+                namespace = opt ? "optional" : "required";
+        }
+        out.set(x.name.text, {
+            name: x.name.text,
+            tenant,
+            namespace,
+            fields,
+            idRef,
+        });
+    });
+    return out;
+}

package/dist/detectors/source/_scan.js

@@ -1,3 +1,4 @@
+import { siteCount, withCount } from "../../violation-count.js";
 /** The standard both wave-2 files are pinned against (short hash a9d7877b). */
 export const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 export function emptyScan() {
@@ -45,12 +46,12 @@ export function decide(ruleId, id, check, scan, emptyReason) {
         // 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 {
+        return withCount({
             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)}.` : ""}${nJ ? ` could-not-judge sites (human verdict owed): ${fmt(scan.cnj)}.` : ""}`,
-        };
+            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}${nJ ? ` could-not-judge sites (not decided; each names why): ${fmt(scan.cnj)}.` : ""}`,
+        }, siteCount(scan.violate));
     }
     if (nJ > 0) {
         const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}`;

package/dist/detectors/source/backfill.js

@@ -1,3 +1,4 @@
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 import { base, code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
 // A schema definition file — where defineTable declarations live.
 const SCHEMA_FILE = /schema\.ts$/;
@@ -73,7 +74,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;
@@ -96,7 +105,9 @@ export function scanR44(files) {
         let directInsert = false;
         let loopsSource = false;
         let referenced = false;
+        let migText = "";
         for (const f of migFiles) {
+            migText += `${f.lines.map((l) => l.raw).join("\n")}\n`;
             for (const l of f.lines) {
                 if (!code(l))
                     continue;
@@ -118,18 +129,39 @@ export function scanR44(files) {
             });
         }
         else if (directInsert) {
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table} has a migration inserting it, but no query/paginate of the source table ${d.source} is visible — coverage of existing source rows is not statically decidable (name the migration site)`,
-            });
+            // judgement retired (task k179jnhx, §23): flagged (no visible query/
+            // paginate of the source table); decides on the migration file's written
+            // JUSTIFIÉ:/JUSTIFIED: token, never a person's opinion of coverage.
+            if (hasJustificationTokenInText(migText)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a migration inserting it; no query/paginate of ${d.source} is visible, but the migration file carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a migration inserting it, but no query/paginate of the source table ${d.source} is visible, and no written JUSTIFIÉ:/JUSTIFIED: token in the migration file — coverage of existing source rows owes a fix or a recorded justification`,
+                });
+            }
         }
         else if (referenced) {
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table} has a backfill migration NAMED for it, but it writes the structure via a helper (no direct ctx.db.insert("${d.table}") in the migration) — its idempotence/coverage of existing source rows is not statically decidable (human verifies)`,
-            });
+            if (hasJustificationTokenInText(migText)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a backfill migration NAMED for it, writing the structure via a helper; the migration file carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a backfill migration NAMED for it, but it writes the structure via a helper (no direct ctx.db.insert("${d.table}") in the migration), and no written JUSTIFIÉ:/JUSTIFIED: token in the migration file — idempotence/coverage owes a fix or a recorded justification`,
+                });
+            }
         }
         else {
             scan.violate.push({
@@ -146,10 +178,12 @@ export const R44 = srcDetector("R-44", "R-44 a derived structure carries a same-
 // R-45 — a derived structure carries a test whose fixture bypasses the write
 // path and brackets the migration.
 // ===========================================================================
+const R45_TOKEN_WINDOW = 6;
 export function scanR45(files) {
     const scan = emptyScan();
     const derived = derivedStructures(files);
     const testFiles = files.filter(isTest);
+    const byRel = new Map(files.map((f) => [f.rel, f]));
     for (const d of derived) {
         const insertSourceRe = INSERT_OF(d.source);
         const stem = d.table.toLowerCase();
@@ -192,13 +226,32 @@ export function scanR45(files) {
             });
         }
         else {
-            // No test reaches the subject at all — the test-independence property
-            // cannot be judged. A could-not-judge work-item, never a silent green.
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path (and no create-only fixture to mark red) — its fixture-independence is not statically decidable; a human must verify a test brackets the migration before AND after`,
-            });
+            // No test reaches the subject at all — flagged. judgement retired
+            // (task k179jnhx, §23): the schema declaration's comment window is this
+            // site's remediation cell. No JUSTIFIÉ:/JUSTIFIED: token → non-conforming;
+            // token present → present, decided by the token's presence, never a
+            // person's opinion of whether the untested state is sound.
+            const declFile = byRel.get(d.rel);
+            const window = declFile
+                ? declFile.lines
+                    .slice(Math.max(0, d.n - 1 - R45_TOKEN_WINDOW), d.n - 1 + R45_TOKEN_WINDOW)
+                    .map((l) => l.raw)
+                    .join("\n")
+                : "";
+            if (hasJustificationTokenInText(window)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path, but the schema declaration's comment window carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path (and no create-only fixture to mark red), and no written JUSTIFIÉ:/JUSTIFIED: token near its schema declaration — fixture-independence owes a test or a recorded justification`,
+                });
+            }
         }
     }
     return scan;

package/dist/detectors/source/contract.js

@@ -18,6 +18,8 @@
 // zero-applicable-site abstain that resolves to could-not-judge WITH a reason.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { siteCount, withCount } from "../../violation-count.js";
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 /** The standard all four are pinned against (short hash a9d7877b). */
 export const SOURCE_CONTRACT_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 function emptyScan() {
@@ -73,12 +75,12 @@ function decide(ruleId, id, check, scan, emptyReason) {
     const breakdown = `[conform=${nC} non-conforming=${nV} could-not-judge=${nJ}]`;
     const fmt = (s) => s.slice(0, 3).map((x) => `${x.rel}:${x.n} (${x.note})`).join("; ");
     if (nV > 0) {
-        return {
+        return withCount({
             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)}.` : ""}`,
-        };
+        }, siteCount(scan.violate));
     }
     if (nJ > 0) {
         const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`;
@@ -320,15 +322,19 @@ export function scanR25(files) {
 //   authority-tier / boundary-key declaration: rag has only an import comment; the
 //   agentEngine block documents durability/versioning ("long-task survival",
 //   "Pinned exactly at 0.1.0-alpha.2"), not an isolation contract. Per §8 an
-//   undeclared seam is non-conforming as an app-owned table with a blank field —
-//   but the DISPOSITION (whether the library's tables are in fact used
-//   fleet-internal/master only, which would justify the silence) is human. So the
-//   detector flags an undeclared mount as could-not-judge WITH a reason (never a
-//   silent pass); a mount whose window declares an authority tier + boundary key
-//   is conform.
+//   undeclared seam is non-conforming as an app-owned table with a blank field.
+// judgement retired (task k179jnhx, §23): whether the library's tables are in
+// fact used fleet-internal/master only (which would justify the silence) is no
+// longer a human disposition — it decides on the PRESENCE of a written
+// JUSTIFIÉ:/JUSTIFIED: token in the seam's comment window (that window IS this
+// site's remediation cell, the same mechanism R-7/R-8 use on an oracle row). No
+// token → non-conforming; token present → present. could-not-judge is reserved
+// for a seam the instrument could not read, never reached here (a parsed
+// app.use() call always resolves to one of the two).
 // PATTERN: each `app.use(<component>)` line in a *.config.ts seam is conform iff its
 // surrounding window (comments included — the seam contract is documented prose)
-// declares an authority tier + boundary key; else could-not-judge.
+// declares an authority tier + boundary key, OR carries a written justification
+// token; else non-conforming.
 // ---------------------------------------------------------------------------
 const MOUNT_CALL = /app\.use\s*\(\s*(\w+)/;
 const SEAM_CONTRACT = /authority tier|boundary key|isolation contract|org-scoped|fleet-internal|master-only|namespace-bound|tenant boundary/i;
@@ -350,14 +356,16 @@ export function scanR26(files) {
                 continue;
             const comp = m[1];
             // seam contract is documented as prose — scan ALL lines in the window.
-            const declared = f.lines
-                .slice(Math.max(0, i - R26_WINDOW), i + R26_WINDOW)
-                .some((x) => SEAM_CONTRACT.test(x.raw));
+            const window = f.lines.slice(Math.max(0, i - R26_WINDOW), i + R26_WINDOW);
+            const declared = window.some((x) => SEAM_CONTRACT.test(x.raw));
             if (declared) {
                 scan.conform.push({ rel: f.rel, n: l.n, note: `component "${comp}" mount declares an authority tier + boundary key at the seam` });
             }
+            else if (hasJustificationTokenInText(window.map((x) => x.raw).join("\n"))) {
+                scan.conform.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key, but the seam's comment window carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed` });
+            }
             else {
-                scan.cnj.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key at the seam — usable fleet-internal/master only; org-scoped disposition needs a human ruling (§8)` });
+                scan.violate.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key at the seam, and no written JUSTIFIÉ:/JUSTIFIED: token in the seam's comment window — usable fleet-internal/master only; §8 owes a fix or a recorded justification` });
             }
         }
     }

package/dist/detectors/source/cross-tenant-write.d.ts

@@ -0,0 +1,46 @@
+import * as ts from "typescript";
+import type { Detector } from "../../engine-types.js";
+import { type FnDef, type Parsed, type SchemaTable, type SrcFile } from "./_ast.js";
+import { type Scan, type SourceDetectorEntry } from "./_scan.js";
+export declare const R52_ID = "R-52 a write reaching a row with no tenant value through a caller-choosable value checks the target's tenant first";
+export declare function fleetOnlyExpr(e0: ts.Expression, isFleetHelper: (name: string) => boolean, isFleetLocal?: (name: string) => boolean): boolean;
+export interface R52Facts {
+    parsed: Parsed[];
+    schema: Map<string, SchemaTable> | undefined;
+    schemaRel: string | undefined;
+    callerChosen: Map<string, Set<string>>;
+    fns: Map<string, FnDef[]>;
+    readsTenant: Set<string>;
+    refusing: Set<string>;
+    /** helpers every truthy return of which is a fleet-scope decision. */
+    fleetOnly: Set<string>;
+    fleetRefusal: Set<string>;
+    singleTable: Map<string, string>;
+    /** helpers that hand their table argument to `db.normalizeId`. */
+    normalizers: Set<string>;
+    /** per table carrying a `namespace` and no required tenant column: whether
+     * that namespace is checked against the caller's allowed prefixes. */
+    namespace: Map<string, NamespaceDecision>;
+}
+/** Standard 2825122 R-52 counts a `namespace` as a tenant column only when it is
+ * "checked against the caller's allowed prefixes". Decided per table from the
+ * public doors (query/mutation/action) that read or write it:
+ *   checked    every door runs a prefix check (or refuses every non-master);
+ *   unchecked  no door does — the namespace is a label, the table is untenanted;
+ *   undecided  some do and some do not, or no public door reaches the table —
+ *              every site targeting it is could-not-judge, never green. */
+export interface NamespaceDecision {
+    verdict: "checked" | "unchecked" | "undecided";
+    why: string;
+}
+export declare function r52Facts(files: SrcFile[]): R52Facts;
+export interface R52Detail {
+    scan: Scan;
+    /** tables carrying no tenant value (none, or optional), as read from schema. */
+    untenanted: string[];
+    schemaRel: string | undefined;
+}
+export declare function scanR52(files: SrcFile[]): Scan;
+export declare function scanR52Detailed(files: SrcFile[]): R52Detail;
+export declare const R52: Detector;
+export declare const SOURCE_CROSS_TENANT_WRITE_DETECTORS: SourceDetectorEntry[];