@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/detectors/source/security.js

@@ -22,7 +22,7 @@
 // abstains (never a silent pass). Every zero-count branch names the real site it
 // matched so the branch is provably reachable.
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 /** The standard all six are pinned against (short hash a9d7877b). */
 export const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 function emptyScan() {
@@ -251,6 +251,181 @@ export function scanR33(files) {
 const INBOUND_JWT = /claims\.(aud|iss)\b|\.iss\b.*mismatch|verify\w*jwt/i;
 const AUD_ASSERT = /VP_CLERK_EXPECTED_AUD|aud claim mismatch|audMatches|expectedAud/i;
 const OUTBOUND_PASSTHROUGH = /["'`]?authorization["'`]?\s*[:=][^,\n]*(headers\.get\(\s*["'`]authorization|req(uest)?\.headers|callerToken|incomingToken|passthrough)/i;
+// An `audience` KEY in the options object of a JWT-verify call is an audience
+// assertion, judged on its VALUE, never on a name list (PR #44 follow-up: VP
+// 30e821b mcp-server/src/auth.ts:882-885 `jwtVerify(token, jwks, { issuer,
+// audience: CLERK_JWT_AUDIENCE })` with `CLERK_JWT_AUDIENCE =
+// process.env.CLERK_JWT_AUDIENCE ?? "convex"` was reported as unasserted).
+//   counts:  a non-empty string literal; a non-empty array literal; an identifier
+//            bound by a module-level `const` to either of those, or to
+//            `process.env.X ?? "<non-empty>"` / `|| "<non-empty>"`
+//   never:   `undefined`, `""`, a const whose fallback is empty, a bare env read
+//            with no fallback (undefined at runtime disables the check in jose)
+const VERIFY_CALL = /\b(?:jwtVerify|jwt\.verify|verifyToken|verify)\s*\(/;
+const NON_EMPTY_LITERAL = /^(?:"[^"]+"|'[^']+'|`[^`$]+`|\[\s*["'`][^\]]*\])$/;
+const ENV_WITH_FALLBACK = /^process\.env\.[A-Za-z0-9_]+\s*(?:\?\?|\|\|)\s*("[^"]+"|'[^']+'|`[^`$]+`)$/;
+function audienceValueCounts(value, f) {
+    const v = value.trim();
+    if (NON_EMPTY_LITERAL.test(v))
+        return true;
+    if (!/^[A-Za-z_$][\w$]*$/.test(v) || v === "undefined")
+        return false;
+    const decl = new RegExp(`^(?:export\\s+)?const\\s+${v}\\s*(?::[^=]+)?=\\s*(.+?);?\\s*$`);
+    for (const l of f.lines) {
+        if (!code(l))
+            continue;
+        const m = decl.exec(l.raw);
+        if (m) {
+            const init = m[1].trim();
+            return NON_EMPTY_LITERAL.test(init) || ENV_WITH_FALLBACK.test(init);
+        }
+    }
+    return false;
+}
+/**
+ * The source with comments blanked to spaces and string/template CONTENTS blanked
+ * to `_` (quotes kept, newlines kept), so offsets line up with the original. All
+ * structural matching runs on this mask; values are sliced from the original.
+ */
+function maskSource(src) {
+    const out = src.split("");
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const n = src[i + 1];
+        if (c === "/" && n === "/") {
+            while (i < src.length && src[i] !== "\n")
+                out[i++] = " ";
+        }
+        else if (c === "/" && n === "*") {
+            out[i++] = " ";
+            out[i++] = " ";
+            while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) {
+                if (src[i] !== "\n")
+                    out[i] = " ";
+                i++;
+            }
+            if (i < src.length) {
+                out[i++] = " ";
+                out[i++] = " ";
+            }
+        }
+        else if (c === '"' || c === "'" || c === "`") {
+            i++;
+            while (i < src.length && src[i] !== c) {
+                if (src[i] === "\\") {
+                    out[i++] = "_";
+                    if (i < src.length && src[i] !== "\n")
+                        out[i] = "_";
+                    i++;
+                    continue;
+                }
+                if (src[i] !== "\n")
+                    out[i] = "_";
+                i++;
+            }
+            i++;
+        }
+        else
+            i++;
+    }
+    return out.join("");
+}
+/** Index of the bracket closing the one opened at `open` in `masked`, or -1. */
+function closeOf(masked, open) {
+    let depth = 0;
+    for (let i = open; i < masked.length; i++) {
+        const c = masked[i];
+        if (c === "(" || c === "{" || c === "[")
+            depth += 1;
+        else if (c === ")" || c === "}" || c === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Split [from, to) of `masked` on commas at nesting depth 0 → [start, end) spans. */
+function topLevelParts(masked, from, to) {
+    const parts = [];
+    let depth = 0;
+    let start = from;
+    for (let i = from; i < to; i++) {
+        const c = masked[i];
+        if (c === "(" || c === "{" || c === "[")
+            depth += 1;
+        else if (c === ")" || c === "}" || c === "]")
+            depth -= 1;
+        else if (c === "," && depth === 0) {
+            parts.push([start, i]);
+            start = i + 1;
+        }
+    }
+    parts.push([start, to]);
+    return parts;
+}
+/** The `audience` property VALUE of the object literal whose `{` is at `open`
+ * (own properties only, never a nested object's), or undefined. A shorthand
+ * `{ audience }` yields the identifier `audience`. */
+function audienceProp(src, masked, open) {
+    const close = closeOf(masked, open);
+    if (close === -1)
+        return undefined;
+    for (const [st, en] of topLevelParts(masked, open + 1, close)) {
+        const m = /^\s*audience\s*(?::|$)/.exec(masked.slice(st, en));
+        if (!m)
+            continue;
+        const colon = masked.indexOf(":", st);
+        const value = colon !== -1 && colon < en ? src.slice(colon + 1, en) : "audience";
+        return { value: value.trim(), at: st + m[0].indexOf("audience") };
+    }
+    return undefined;
+}
+/**
+ * Line of an `audience` option that belongs to a JWT-verify call's OWN argument
+ * list and whose value counts, or 0. Bound to the call: the scan runs from the
+ * call's `(` to its balanced `)` (strings and comments masked), and the key is
+ * read only (a) as an own property of an object-literal argument, or (b) through
+ * an identifier argument bound by a module-level `const NAME = { … }` holding the
+ * key. An `audience` in a nested call, an unrelated object below the call, a
+ * different call on the same line, a string or a comment is never read
+ * (Eta REVISE #44, mutant A2).
+ */
+function audienceOptionLine(f) {
+    const src = f.lines.map((l) => l.raw).join("\n");
+    const masked = maskSource(src);
+    const lineAt = (idx) => src.slice(0, idx).split("\n").length;
+    const call = new RegExp(VERIFY_CALL.source, "g");
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = call.exec(masked)) !== null) {
+        const open = m.index + m[0].length - 1;
+        const close = closeOf(masked, open);
+        if (close === -1)
+            continue;
+        for (const [st, en] of topLevelParts(masked, open + 1, close)) {
+            const arg = masked.slice(st, en);
+            const lead = st + (arg.length - arg.trimStart().length);
+            let prop;
+            if (masked[lead] === "{") {
+                prop = audienceProp(src, masked, lead);
+            }
+            else {
+                const id = /^([A-Za-z_$][\w$]*)\s*$/.exec(arg.trim());
+                if (!id)
+                    continue;
+                const decl = new RegExp(`^(?:export\\s+)?const\\s+${id[1].replace(/\$/g, "\\$")}\\s*(?::[^=\\n]+)?=\\s*\\{`, "m");
+                const d = decl.exec(masked);
+                if (d)
+                    prop = audienceProp(src, masked, d.index + d[0].length - 1);
+            }
+            if (prop && audienceValueCounts(prop.value, f))
+                return lineAt(prop.at);
+        }
+    }
+    return 0;
+}
 export function scanR34(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -269,9 +444,11 @@ export function scanR34(files) {
                 scan.violate.push({ rel: f.rel, n: l.n, note: "outbound Authorization header forwards a caller-supplied token verbatim (token passthrough)" });
             }
         }
+        if (!audAssert)
+            audAssert = audienceOptionLine(f);
         if (inboundLine) {
             if (audAssert) {
-                scan.conform.push({ rel: f.rel, n: audAssert, note: "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD / aud claim mismatch)" });
+                scan.conform.push({ rel: f.rel, n: audAssert, note: "inbound JWT audience asserted (VP_CLERK_EXPECTED_AUD / aud claim mismatch / a verify call's audience option with a non-empty value)" });
             }
             else {
                 scan.violate.push({ rel: f.rel, n: inboundLine, note: "inbound JWT verified with no audience assertion — accepts a token minted for another party" });
@@ -328,16 +505,57 @@ export function scanR35(files) {
 const LOCKFILES = ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
 const WORKFLOW_DIR = ".github/workflows";
 const PUBLISH_HINT = /npm\s+publish|release|publish/i;
+/**
+ * The directories R-36 searches, nearest first: the scanned root, then each
+ * ancestor up to and INCLUDING the git root (the first ancestor holding `.git`).
+ *
+ * The misread this closes: the documented invocation points the doctor at
+ * `<repo>/convex`, while the lockfile and `.github/workflows` are REPOSITORY
+ * artifacts living at the repo root. Reading only `tree.root` reported "no lockfile
+ * — dependencies are not pinned" on a repository with a committed `bun.lock`.
+ *
+ * The walk stops at the git root and never goes above it: a lockfile in some
+ * unrelated parent directory (a home directory, a monorepo host that is not this
+ * repository) does not pin this repository's dependencies. With no `.git` ancestor
+ * at all, only the scanned root itself is read (the pre-fix behaviour) — the walk
+ * is never widened on a guess.
+ */
+export function r36SearchDirs(root) {
+    const chain = [];
+    let dir = resolve(root);
+    for (;;) {
+        chain.push(dir);
+        if (existsSync(join(dir, ".git")))
+            return chain;
+        const up = dirname(dir);
+        if (up === dir)
+            return [resolve(root)];
+        dir = up;
+    }
+}
 export function evalR36(root) {
     const scan = emptyScan();
-    const lock = LOCKFILES.find((n) => existsSync(join(root, n)));
+    const dirs = r36SearchDirs(root);
+    const relTo = (dir, name) => {
+        const r = relative(resolve(root), join(dir, name));
+        return r === "" ? name : r;
+    };
+    let lock;
+    for (const dir of dirs) {
+        const name = LOCKFILES.find((n) => existsSync(join(dir, n)));
+        if (name) {
+            lock = { dir, name };
+            break;
+        }
+    }
     if (!lock) {
-        scan.violate.push({ rel: "(root)", n: 0, note: "no lockfile present — dependencies are not pinned" });
+        scan.violate.push({ rel: "(root)", n: 0, note: `no lockfile present in the scanned root or any ancestor up to the git root (searched: ${dirs.join(", ")}) — dependencies are not pinned` });
     }
     else {
-        scan.conform.push({ rel: lock, n: 1, note: "lockfile present — every dependency pinned by the lockfile" });
+        scan.conform.push({ rel: relTo(lock.dir, lock.name), n: 1, note: "lockfile present — every dependency pinned by the lockfile" });
     }
-    const wfDir = join(root, WORKFLOW_DIR);
+    const wfBase = dirs.find((d) => existsSync(join(d, WORKFLOW_DIR))) ?? resolve(root);
+    const wfDir = join(wfBase, WORKFLOW_DIR);
     let publishFile = "";
     let provenance = false;
     let sawPublish = false;
@@ -348,7 +566,7 @@ export function evalR36(root) {
             const p = join(wfDir, name);
             if (!existsSync(p))
                 continue;
-            publishFile = `${WORKFLOW_DIR}/${name}`;
+            publishFile = relTo(wfBase, `${WORKFLOW_DIR}/${name}`);
             const body = readFileSync(p, "utf8");
             if (PUBLISH_HINT.test(body))
                 sawPublish = true;

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

@@ -1,5 +1,12 @@
 import type { Detector } from "../../engine-types.js";
-import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+import { type Scan, type Site, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+/** R-51's scan plus the public writes found OUTSIDE its scope (no no-org throw,
+ *  no typed-unauthorised return, no marker). The list never reaches a verdict. */
+export interface R51Scan {
+    scan: Scan;
+    outOfScope: Site[];
+}
 export declare function scanR51(files: SrcFile[]): Scan;
+export declare function scanR51Detailed(files: SrcFile[]): R51Scan;
 export declare const R51: Detector;
 export declare const SOURCE_WRITE_ISOLATION_DETECTORS: SourceDetectorEntry[];

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

@@ -1,4 +1,5 @@
-import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+import { SCOPE_REFUSED_RETURN } from "./isolation.js";
+import { code, decide, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, } from "./_scan.js";
 const CUSTOM_MUTATION_OPEN = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customMutation\s*\(/;
 const CUSTOM_QUERY_DEF = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customQuery\s*\(/;
 const FIRST_IDENT = /([A-Za-z_][A-Za-z0-9_]*)/;
@@ -6,7 +7,26 @@ const BASE_PUBLIC_MUTATION = "mutation";
 const BASE_INTERNAL_MUTATION = "internalMutation";
 // A no-org throw a write inherits: an org-keyed ConvexError, or a write/org gate
 // helper that throws when no org is resolved.
-const ORG_THROW = /throw\b[^;]*\b(?:NO_ORG|ORG_REQUIRED|RBAC_DENIED|no org|missing org|organization is required|not in (?:an )?org)/i;
+//
+// `RBAC_DENIED` is NOT in this vocabulary, and that is the standard's own line, not
+// a convenience. The pinned standard (backend-standard-4bcd605.md :652) says "a
+// mutation that refuses an unauthorised write via `requireOrgAdmin` throwing
+// `RBAC_DENIED` is **correct**", and R-51's own text (:655-656) keeps R-16's
+// `{code,field/scope,message}` refusal of a chosen unauthorised action correct and
+// names R-51's throw as NO_ORG (an org-keyed ConvexError or
+// requireWriteAccess/requireWorkspaceId/getEffectiveWorkspaceId). Counting every
+// RBAC_DENIED as a no-org throw contradicted both lines (isolation.ts header
+// :16-19 said CORRECT while this regex said RED). An RBAC_DENIED raised BECAUSE the
+// org is missing is still caught — by ORG_KEYED_GUARDED_THROW below, which reads
+// the CONDITION, not the code word.
+const ORG_THROW = /throw\b[^;]*\b(?:NO_ORG|ORG_REQUIRED|no org|missing org|organization is required|not in (?:an )?org)/i;
+// A throw (any code) whose governing `if` is an ORG-keyed absence test — the
+// no-org path itself, whatever the error string says:
+//   if (!scope.isMaster && scope.orgSlug === null) { throw new ConvexError("RBAC_DENIED…") }
+// The condition must test an org/workspace field for absence; an identity-absence
+// test (`if (!identity)`) is a caller with no credential at all, not the signed-in
+// pre-org shell R-51 protects, and is R-16's refusal.
+const ORG_KEYED_GUARDED_THROW = /if\s*\((?:[^()]|\([^()]*\))*?(?:!\s*(?:[A-Za-z_$][\w$]*\.)?(?:org|orgId|orgSlug|workspaceId|workspace)\b|\b(?:org|orgId|orgSlug|workspaceId)\s*(?:===|==)\s*(?:null|undefined))(?:[^()]|\([^()]*\))*\)\s*\{?\s*throw\b/i;
 const WRITE_GATE_HELPER = /\b(?:requireWriteAccess|requireWorkspaceId|requireOrgId|getEffectiveWorkspaceId|getOrgIdOrThrow|ensureCurrentOrg)\s*\(/;
 // a gate helper generally (any require*/ensure*/assert* access check in a wrapper).
 const GATE_HELPER = /\b(?:require|ensure|assert)[A-Z][A-Za-z0-9_]*\s*\(/;
@@ -59,12 +79,17 @@ function namedValueDomination(before) {
 function throwDomination(blockText) {
     const t1 = ORG_THROW.exec(blockText);
     const t2 = WRITE_GATE_HELPER.exec(blockText);
-    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY);
+    const t3 = ORG_KEYED_GUARDED_THROW.exec(blockText);
+    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY, t3 ? t3.index : Number.POSITIVE_INFINITY);
     if (!Number.isFinite(throwIdx))
         return "none";
     const before = blockText.slice(0, throwIdx);
     if (namedValueDomination(before))
         return "dominated";
+    // Form C — the VP pre-org `if (scope.refused) return …` typed value (shared
+    // definition with R-50, isolation.ts SCOPE_REFUSED_RETURN).
+    if (SCOPE_REFUSED_RETURN.test(before))
+        return "dominated";
     if (!TYPED_EMPTY_RETURN.test(before))
         return "none";
     return NO_ORG_GUARD.test(before) ? "dominated" : "ambiguous";
@@ -169,6 +194,9 @@ function mutationBlock(lines, i) {
     return { lines: body, unterminated: seenOpen };
 }
 export function scanR51(files) {
+    return scanR51Detailed(files).scan;
+}
+export function scanR51Detailed(files) {
     const scan = emptyScan();
     const builders = discoverWriteBuilders(files);
     // Public writes that matched a definition opener but exhibit NO org-throw, NO
@@ -242,19 +270,28 @@ export function scanR51(files) {
                 .map((l) => l.raw)
                 .join("\n");
             const blockAll = block.lines.map((l) => l.raw).join("\n");
-            const throwsOnNoOrg = ORG_THROW.test(blockText) || WRITE_GATE_HELPER.test(blockText);
+            const throwsOnNoOrg = ORG_THROW.test(blockText) ||
+                WRITE_GATE_HELPER.test(blockText) ||
+                ORG_KEYED_GUARDED_THROW.test(blockText);
             const typedUnauth = TYPED_UNAUTH_RETURN.test(blockText);
             const hasMarker = CONTRACT_MARKER.test(blockAll);
             if (!throwsOnNoOrg && !typedUnauth && !hasMarker) {
-                // A bare public write with no visible org isolation. Not a gated
-                // subject — but recorded so a tree whose ENTIRE public-write surface
-                // is bare is judged (CNJ-with-sites) rather than falsely abstained.
+                // A public write that neither throws on the no-org path, nor returns a
+                // typed unauthorised result, nor carries a marker is NOT an R-51
+                // subject. The pinned standard's red (backend-standard-4bcd605.md :656,
+                // clause b) is "a bare public mutation whose no-org path THROWS" with
+                // the two readable absences; a write with no no-org throw cannot
+                // crash a pre-org shell, which is the whole of R-51. Whether such a
+                // write resolves its caller at all is CR-1's control
+                // (src/caller-resolution.ts), which drives the exit code — the
+                // instrument still goes red on an unguarded write, under the control
+                // whose question it is. Counted only to word the empty abstain.
                 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 no-org throw, no typed-unauthorized return, no write-contract marker — not an R-51 subject (standard 4bcd605 :656 red requires a no-org throw); caller resolution is CR-1's control`,
                 });
-                continue; // not a gated subject
+                continue; // not a subject
             }
             if (typedUnauth) {
                 // The write returns a shape on the no-org path — a pre-org client can render
@@ -295,7 +332,7 @@ export function scanR51(files) {
                 scan.cnj.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public mutation throws on the missing-org path AND carries a write-contract marker — the marker records a claim that a client cannot reach this write before an org exists, which convex/ cannot verify. R-51 refuses (a reviewer checks the marker's claim) — never a silent green`,
+                    note: `${fn}: public mutation throws on the missing-org path AND carries a write-contract marker — the marker records a claim that a client cannot reach this write before an org exists, which convex/ cannot verify. R-51 refuses (a reviewer checks the marker's claim) — never a silent green. Why R-50 accepts its marker and R-51 does not: the pinned standard decides it per rule — R-50's green includes a query that "documents a client contract" (4bcd605 :653), while R-51 lists "a write … that carries a write-contract marker whose unreachability claim the detector cannot verify" under could-not-judge, never green (4bcd605 :656)`,
                 });
             }
             else {
@@ -313,27 +350,24 @@ export function scanR51(files) {
             }
         }
     }
-    // A tree whose ENTIRE public-write surface is ungated (no throw / typed-unauth /
-    // marker on ANY write) leaves the scan otherwise empty. The legacy abstain then
-    // claimed "no public mutation matched" — FALSE when bare public writes exist, and
-    // a silent pass over a fully-ungated backend. Surface those writes as
-    // could-not-judge sites 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: 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.)
-    for (const u of ungated)
-        scan.cnj.push(u);
-    return scan;
+    // Unmarked public writes are NOT pushed anywhere (standard 4bcd605 :656 — the red
+    // requires a no-org throw). Until 0.1.16 they were pushed to `violate`; that
+    // obligation is CR-1's now (a write resolving no caller is a CR-1 violation).
+    return { scan, outOfScope: ungated };
 }
-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.");
+const R51_ID = "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";
+const R51_CHECK = "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";
+export const R51 = {
+    id: R51_ID,
+    run: (tree) => {
+        const { scan, outOfScope } = scanR51Detailed(tree.files);
+        const n = outOfScope.length;
+        const empty = n > 0
+            ? `R-51: no R-51 subject in the scanned tree — ${n} public mutation(s) matched, none throws on the no-org path, returns a typed unauthorized result, or carries a write-contract marker (out of scope per standard 4bcd605 :656; caller resolution is CR-1's control). NOT a clean bill.`
+            : "R-51: no public mutation matched in the scanned tree — no write to certify. NOT a clean bill.";
+        return decide("R-51", R51_ID, R51_CHECK, scan, empty);
+    },
+};
 export const SOURCE_WRITE_ISOLATION_DETECTORS = [
     { detector: R51, ruleId: "R-51", standardPin: SOURCE_STANDARD_PIN },
 ];

package/dist/detectors/standard/r46-returns-validator.d.ts

@@ -23,6 +23,14 @@ export interface DocValidatorMatch {
     /** 1-based line span of the enclosing export — where a projection reason lives. */
     exportStartLine: number;
     exportEndLine: number;
+    /** 1-based line spans of every SHARED CONSTANT the export's `returns:` resolved
+     * through to reach this object (`returns: externalOpenReturns` →
+     * `const externalOpenReturns = v.object({…})`). A `returns-projection:` reason
+     * written on that constant governs every export that uses it. */
+    constSpans: {
+        start: number;
+        end: number;
+    }[];
 }
 export declare function extractDocMatches(name: string, text: string): DocValidatorMatch[];
 export declare function projectionReason(rawLines: string[], startLine: number, endLine: number): string | undefined;

package/dist/detectors/standard/r46-returns-validator.js

@@ -160,17 +160,35 @@ export function extractDocMatches(name, text) {
     const matches = [];
     const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
     const constMap = new Map();
+    const constSpan = new Map();
     function collectConsts(node) {
         if (ts.isVariableStatement(node)) {
             for (const decl of node.declarationList.declarations) {
                 if (ts.isIdentifier(decl.name) && decl.initializer) {
                     constMap.set(decl.name.text, decl.initializer);
+                    constSpan.set(decl.name.text, {
+                        start: lineOf(node.getStart(sf)),
+                        end: lineOf(node.getEnd()),
+                    });
                 }
             }
         }
         ts.forEachChild(node, collectConsts);
     }
     collectConsts(sf);
+    /** The span of every const an expression resolves THROUGH (the chain a
+     * `returns: X` takes to reach its validator). */
+    function constChain(expr) {
+        const out = [];
+        let cur = expr;
+        for (let d = 0; d <= 10 && ts.isIdentifier(cur) && constMap.has(cur.text); d++) {
+            const span = constSpan.get(cur.text);
+            if (span)
+                out.push(span);
+            cur = constMap.get(cur.text);
+        }
+        return out;
+    }
     function resolve(expr, depth = 0) {
         if (depth > 10)
             return expr;
@@ -179,10 +197,11 @@ export function extractDocMatches(name, text) {
         }
         return expr;
     }
-    function walkForDocObjects(expr, out, exportName, alias, span, depth = 0) {
+    function walkForDocObjects(expr, out, exportName, alias, span, depth = 0, consts = []) {
         if (depth > 20)
             return;
         const nextAlias = ts.isIdentifier(expr) ? expr.text : alias;
+        const chain = [...consts, ...constChain(expr)];
         const resolved = resolve(expr);
         if (ts.isCallExpression(resolved) &&
             ts.isPropertyAccessExpression(resolved.expression)) {
@@ -207,11 +226,12 @@ export function extractDocMatches(name, text) {
                             line: lineOf(objArg.getStart(sf)),
                             exportStartLine: span.start,
                             exportEndLine: span.end,
+                            constSpans: chain,
                         });
                     }
                     for (const prop of objArg.properties) {
                         if (ts.isPropertyAssignment(prop)) {
-                            walkForDocObjects(prop.initializer, out, exportName, undefined, span, depth + 1);
+                            walkForDocObjects(prop.initializer, out, exportName, undefined, span, depth + 1, chain);
                         }
                     }
                 }
@@ -219,7 +239,7 @@ export function extractDocMatches(name, text) {
             }
             if (method === "union" || method === "array" || method === "optional") {
                 for (const arg of resolved.arguments) {
-                    walkForDocObjects(arg, out, exportName, nextAlias, span, depth + 1);
+                    walkForDocObjects(arg, out, exportName, nextAlias, span, depth + 1, chain);
                 }
                 return;
             }
@@ -348,18 +368,29 @@ export function scanR46(files) {
             }
             // include the contiguous leading-comment block above the export — the
             // natural place a `returns-projection:` reason is written for the read path.
-            let leadStart = m.exportStartLine;
-            while (leadStart > 1) {
-                const prev = (rawLines[leadStart - 2] ?? "").trim();
-                if (prev.startsWith("//") ||
-                    prev.startsWith("*") ||
-                    prev.startsWith("/*")) {
-                    leadStart -= 1;
+            // The same holds for every SHARED CONSTANT the export's `returns:` resolves
+            // through: a reason written on `const externalOpenReturns = v.object(…)`
+            // is the author's written reason for every export that returns it. A
+            // reason on an UNRELATED const (one this export does not resolve through)
+            // governs nothing here.
+            const withLead = (start) => {
+                let lead = start;
+                while (lead > 1) {
+                    const prev = (rawLines[lead - 2] ?? "").trim();
+                    if (prev.startsWith("//") ||
+                        prev.startsWith("*") ||
+                        prev.startsWith("/*")) {
+                        lead -= 1;
+                    }
+                    else
+                        break;
                 }
-                else
-                    break;
-            }
-            const reason = projectionReason(rawLines, leadStart, m.exportEndLine);
+                return lead;
+            };
+            const reason = projectionReason(rawLines, withLead(m.exportStartLine), m.exportEndLine) ??
+                m.constSpans
+                    .map((c) => projectionReason(rawLines, withLead(c.start), c.end))
+                    .find((r) => r !== undefined);
             if (reason) {
                 inventory.push({
                     rel: f.rel,

package/dist/detectors/structural.js

@@ -5,8 +5,8 @@
 // column. Agreeing with the oracle here would be certifying the defect the
 // instrument exists to find — so these are NOT tuned to pass.
 import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, WRITER_AUTHORITY_COLUMN, authorityIsMerged } from "../contract.js";
-import { ORACLE_COLUMNS, readOracle } from "../oracle.js";
-const CSV_ANCHOR = "oracle:vp-by-tool-day158.csv col#9 rbac_qui";
+import { ORACLE_COLUMNS, oracleLabel, readOracle, refuseWithoutOracle, requireOracle, } from "../oracle.js";
+const csvAnchor = () => `${oracleLabel()} col#9 rbac_qui`;
 /**
  * R-14 — inventory-schema parity, contract → inventory, one direction.
  * A merged reader/writer authority column is "non-conforming by construction"
@@ -15,12 +15,15 @@ const CSV_ANCHOR = "oracle:vp-by-tool-day158.csv col#9 rbac_qui";
 export function makeR14(columns = ORACLE_COLUMNS) {
     return {
         id: "R-14 inventory-schema parity",
-        run: () => {
+        // The verdict is about the oracle's schema, so with no oracle bound there is
+        // no subject: refuse (could-not-judge), never a verdict on the tool's own constant.
+        run: () => refuseWithoutOracle("R-14 inventory-schema parity", () => {
+            requireOracle();
             const authorityColumns = columns.filter((c) => c === "rbac_qui");
             if (authorityIsMerged() || authorityColumns.length < 2) {
                 return {
                     id: "R-14 inventory-schema parity",
-                    anchor: CSV_ANCHOR,
+                    anchor: csvAnchor(),
                     state: "non-conforming",
                     verdict: "R-14: the inventory holds a SINGLE merged authority column `rbac_qui` (col#9), " +
                         "but §2 splits authority into two distinct contract fields — reader authority (R-5) " +
@@ -30,11 +33,11 @@ export function makeR14(columns = ORACLE_COLUMNS) {
             }
             return {
                 id: "R-14 inventory-schema parity",
-                anchor: "oracle:vp-by-tool-day158.csv",
+                anchor: oracleLabel(),
                 state: "present",
                 verdict: "R-14: every §2 contract field present; reader and writer authority are two separate columns.",
             };
-        },
+        }),
     };
 }
 /**
@@ -45,7 +48,8 @@ export function makeR14(columns = ORACLE_COLUMNS) {
 export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
     return {
         id: "R-38 thirteen-field completeness",
-        run: () => {
+        run: () => refuseWithoutOracle("R-38 thirteen-field completeness", () => {
+            requireOracle();
             const colSet = new Set(columns);
             const missing = [];
             for (const f of CONTRACT_FIELDS) {
@@ -64,7 +68,7 @@ export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
                     .join("; ");
                 return {
                     id: "R-38 thirteen-field completeness",
-                    anchor: CSV_ANCHOR,
+                    anchor: csvAnchor(),
                     state: "non-conforming",
                     verdict: `R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and ` +
                         `writer authority (R-10) are not two separate fields; both map to the single column ` +
@@ -74,10 +78,10 @@ export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
             }
             return {
                 id: "R-38 thirteen-field completeness",
-                anchor: "oracle:vp-by-tool-day158.csv",
+                anchor: oracleLabel(),
                 state: "present",
                 verdict: "R-38: all thirteen §2 contract fields present per table, each within its vocabulary.",
             };
-        },
+        }),
     };
 }