@vantageos/backend-doctor 0.1.14 → 0.2.0

package/dist/detectors/source/identity.js

@@ -1,3 +1,4 @@
+import { conditionalBoundaries, findHelperDefinitions, judgePredicateFunction, judgeResolverFunction, readHandlerGuards, summarizeValidator, topLevelFunctions, topLevelHelperCalls, } from "./guard-helper-flow.js";
 /** The standard both are pinned against (short hash a9d7877b), §15/§18. */
 export const IDENTITY_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15/§18";
 function emptyScan() {
@@ -17,8 +18,32 @@ function isJudgeable(f) {
 function code(l) {
     return !l.comment;
 }
-/** convex source only — R-6/R-16 govern the data layer's write handlers. */
-function isConvex(f) {
+/**
+ * True when the ENGINE's scan root is itself a convex directory. loadTree sets
+ * `tree.root` to the target the CLI was pointed at, and computes every file's
+ * `rel` relative to that root. So the SAME convex file yields two different rels
+ * under the two documented invocations:
+ *   - pointed at the repo ROOT   → rel = `convex/messages.ts` (carries `convex/`)
+ *   - pointed at the CONVEX dir   → rel = `messages.ts`        (bare, no segment)
+ * The bare-rel case is the normal, documented invocation, and it is precisely
+ * where a `rel`-only `isConvex` guard (see below) returned FALSE for 100% of
+ * files — silently skipping R-6/R-16 (Path-B C1 blind spot 1). When the root IS
+ * a convex dir, EVERY collected file is by construction under that convex tree,
+ * so no non-convex file (mcp-server/app/src) can be pulled in by trusting it.
+ */
+function rootIsConvexDir(root) {
+    // Any `convex` path SEGMENT of the scan root (`.../convex` or `.../convex/…`).
+    // A repo root (`/…/vantage-memory`) has no such segment, so this stays FALSE
+    // there and the per-file `convex/` rel prefix does the scoping instead.
+    return /(^|\/)convex(\/|$)/.test(root.replace(/\/+$/, ""));
+}
+/** convex source only — R-6/R-16 govern the data layer's write handlers. When
+ * the scan root is itself a convex dir every file is convex source (bare rels);
+ * otherwise a file qualifies only by a `convex/` rel prefix — so a repo-root
+ * scan still EXCLUDES non-convex source (mcp-server/src/*, app/*, src/*). */
+function isConvex(f, rootIsConvex) {
+    if (rootIsConvex)
+        return true;
     return /(^|\/)convex\//.test(f.rel);
 }
 /**
@@ -73,10 +98,11 @@ function decide(ruleId, id, check, scan, emptyReason) {
 }
 /** Split a convex file into its top-level mutation/internalMutation handler
  * blocks. A block runs from `export const <name> = mutation(` to the next
- * top-level `export ` (or EOF). Queries/actions are not R-6 write handlers. */
-function splitMutationHandlers(f) {
+ * top-level `export ` (or EOF). Queries/actions are not R-6 write handlers.
+ * Each block records whether it is an `internalMutation` registration. */
+export function splitMutationHandlers(f) {
     const out = [];
-    const open = /export\s+const\s+(\w+)\s*=\s*(?:internalMutation|mutation)\s*\(/;
+    const open = /export\s+const\s+(\w+)\s*=\s*(internalMutation|mutation)\s*\(/;
     const topExport = /^export\s+/;
     let cur = null;
     for (const l of f.lines) {
@@ -84,7 +110,12 @@ function splitMutationHandlers(f) {
         if (m) {
             if (cur)
                 out.push(cur);
-            cur = { name: m[1], startN: l.n, lines: [l] };
+            cur = {
+                name: m[1],
+                startN: l.n,
+                lines: [l],
+                internal: m[2] === "internalMutation",
+            };
             continue;
         }
         if (cur) {
@@ -117,15 +148,591 @@ const R6_WRITE = /ctx\.db\.(?:insert|patch|replace|delete)\s*\(/;
 const R6_IDENTITY_GUARD = /getUserIdentity|resolveOrgId|resolveOrgContext|assertNamespaceAllowed|expectedOrgIdForNamespace|tenantSlug|organizationId|organizationSlug|AUTH_NO_ORG|AUTH_NAMESPACE_DENIED/;
 const R6_RESOURCE_GUARD = /assertTaskCallerAuthorized|RBAC_DENIED|\.createdBy\s*===|\.assignedTo\s*===|\.orchestratorId\s*===|callerOrchestrator\s*===\s*["']system["']|note\.createdBy/;
 const R6_BOUNDARY_ARG = /\b(?:createdBy|orgId|orgSlug|namespace|orchestratorId|ownerId|tenantId)\b/;
-export function scanR6(files) {
-    const scan = emptyScan();
+// ---- WRITE-SITE provenance (blind spot 2) ---------------------------------
+//
+// Guard-PRESENCE alone cannot distinguish the historical tenant-write defect
+// from its fix: BOTH `messages.sendMessage` versions call `withOrgScope(ctx)`.
+// The real discriminator is the tenant-scoping boundary field's RHS AT THE
+// WRITE SITE. `tenantId: args.tenantId` (raw caller arg, written directly) is
+// the defect; `tenantId: derivedTenantId` (a scope-derived local) is the fix —
+// even though a `derivedTenantId = args.tenantId` ASSIGNMENT exists inside the
+// master carve-out branch, that assignment is not a ctx.db write and is never
+// flagged. So a direct-arg tenant write is decisive VIOLATE regardless of any
+// guard, and a derived-local tenant write (with scope resolved) is CONFORM.
+// `args.x`, and a COMPUTED subscript `args[k]` (whatever the key, the value is
+// read off the caller's arguments). A literal-keyed subscript (`args["x"]`) never
+// reaches this regex: normalizeArgsAccess rewrites it to `args.x` first.
+const R6_TENANT_FIELDS = new Set([
+    "tenantId",
+    "orgId",
+    "orgSlug",
+]);
+const R6_TENANT_FROM_ARG = /\b(?:tenantId|orgId|orgSlug)\s*:\s*args(?:\.\w+|\s*\[)/;
+// ---- literal-keyed subscript (task k179nydvbdxm40ps7g0y18mwhs8dje91) -------
+//
+// `args["orgSlug"]`, `args['orgSlug']` and args[`orgSlug`] are the SAME property
+// read as `args.orgSlug`. Every R-6 regex below was written against the dotted
+// form, so the subscript form was invisible: `const t = args["orgSlug"]` kept
+// its `\borgSlug\b` token after the `args.<field>` strip and read SCOPE-derived,
+// and `tenantId: args["orgSlug"]` matched no direct-arg regex at all. Rewriting
+// the literal subscript to the dotted form BEFORE any regex runs makes every
+// existing rule see one shape. A template literal is rewritten only when it has
+// no `\${…}` interpolation (the key must be a plain identifier).
+export function normalizeArgsAccess(raw) {
+    return raw.replace(/\bargs\s*\[\s*(["'`])([A-Za-z_$][\w$]*)\1\s*\]/g, "args.$2");
+}
+function normalizeLines(lines) {
+    return lines.map((l) => {
+        const raw = normalizeArgsAccess(l.raw);
+        return raw === l.raw ? l : { ...l, raw };
+    });
+}
+const R6_SCOPE_RESOLUTION = /withOrgScope|getUserIdentity|resolveOrgId|resolveOrgContext|assertNamespaceAllowed|RBAC_DENIED/;
+// ---- follow-the-local taint (blind spot 2b — the ONE-HOP rename) ----------
+//
+// Write-site RHS provenance alone is defeated by a single rename:
+//   const t = args.tenantId;  ...  ctx.db.insert(..., { tenantId: t })
+// The boundary field is now a LOCAL, so R6_TENANT_FROM_ARG does not match and
+// R6_TENANT_FROM_LOCAL wrongly reads CONFORM — the caller's argument reaches the
+// write untouched, wearing another name. Same file, same defect, laundered.
+//
+// The fix follows the local ONE hop: collect every assignment/declaration of the
+// local written as a boundary field, and discriminate on whether ANY of them is
+// SCOPE-derived. A local fed ONLY from args (fromScope === 0) is the argument
+// under an alias → TAINTED → VIOLATE. A local that receives at least one
+// scope/identity-derived value (fromScope >= 1) is genuinely derived → CONFORM.
+// This is exactly what keeps the master carve-out safe (its non-master branch
+// assigns from scope.orgSlug → fromScope >= 1) WITHOUT rescuing the laundering
+// (whose sole assignment is `= args.tenantId` → fromScope === 0).
+// The verified-identity CLAIM names (`identity.organizationId`, `.organizationSlug`,
+// `.tenantSlug`) are the same tokens R6_IDENTITY_GUARD already trusts. Without
+// them a shorthand `{ orgId }` fed from `identity.organizationId` read TAINTED —
+// the false positive the shorthand read (k176ewgwrbc6mg1y4h42rg25gn8dja1p)
+// surfaced in tests/source-identity.test.ts "neuter-proof". An argument whose
+// field carries such a name is stripped below before this test, as for orgSlug.
+const R6_SCOPE_RHS = /\bscope\b|withOrgScope|getUserIdentity|resolveOrgId|resolveOrgContext|\borgSlug\b|assertNamespaceAllowed|\b(?:organizationId|organizationSlug|tenantSlug)\b/;
+/** The non-`args` LOCAL identifiers written to a tenant-scoping boundary field
+ * at this write-site text (`tenantId: <local>`). `tenantId: args.tenantId` is
+ * excluded here — it is the DIRECT-arg case handled by R6_TENANT_FROM_ARG. */
+function boundaryLocalsInWrite(text) {
+    const out = [];
+    const re = /\b(?:tenantId|orgId|orgSlug)\s*:\s*([A-Za-z_$][\w$]*)/g;
+    let m = re.exec(text);
+    while (m !== null) {
+        if (m[1] !== "args")
+            out.push(m[1]);
+        m = re.exec(text);
+    }
+    // ES6 SHORTHAND (task k176ewgwrbc6mg1y4h42rg25gn8dja1p): `{ tenantId }` is
+    // `{ tenantId: tenantId }` — the boundary field written from a LOCAL of the
+    // same name. The keyed regex above needs a `:` and never saw it, so
+    // `const tenantId = args.namespace; insert({ tenantId })` read CONFORM. The
+    // shorthand member sits after `{` or `,` and before `,` or `}` (or a line
+    // end, for a multi-line literal); its local then goes through the SAME
+    // provenance analysis as a keyed local.
+    const short = /(?:^|[{,])\s*(tenantId|orgId|orgSlug)\s*(?=[,}]|$)/gm;
+    let s = short.exec(text);
+    while (s !== null) {
+        out.push(s[1]);
+        s = short.exec(text);
+    }
+    return out;
+}
+/** If `local` is bound by destructuring the HANDLER'S OWN PARAMETER —
+ * `handler: async (ctx, { tenantId }) =>` / `async handler(ctx, { tenantId })`
+ * — it IS a caller argument under its own name. Returns true when this line is
+ * such a binding of `local`. */
+function boundFromHandlerParam(raw, local) {
+    const m = /\bhandler\b[^(\n]*\(\s*[A-Za-z_$][\w$]*\s*(?::\s*[\w.<>]+\s*)?,\s*\{([^}]*)\}/.exec(raw);
+    if (!m)
+        return false;
+    for (const rawPart of m[1].split(",")) {
+        const part = rawPart.trim().split("=")[0].trim();
+        if (!part)
+            continue;
+        const bound = part.includes(":") ? (part.split(":")[1] ?? "").trim() : part;
+        if (bound === local)
+            return true;
+    }
+    return false;
+}
+/** Max bare-identifier hops chased before exhaustion is declared could-not-judge
+ * (defect 3): `const t = orgSlug; const orgSlug = args.x` resolves in one extra
+ * hop; deeper indirection or a cycle stops and is reported cnj, never guessed. */
+const R6_MAX_HOP = 2;
+/** If `local` is bound by an object-destructuring declaration on `raw`, return
+ * the destructuring RHS (the expression after `} =`) so it can be tested for
+ * scope-ness EXACTLY as a plain assignment RHS is (Eta REVISE #3 defect 1).
+ * Recognises the shorthand (`const { orgSlug } = ...`), the keyed/renamed form
+ * (`const { orgSlug: t } = ...`), and a defaulted binding (`const { x = d } = `).
+ * Returns null when this line does not destructure `local`. */
+function destructuredRhs(raw, local) {
+    const m = /(?:const|let|var)\s*\{([^}]*)\}\s*=(?!=)\s*([\s\S]+)$/.exec(raw);
+    if (!m)
+        return null;
+    for (const rawPart of m[1].split(",")) {
+        const part = rawPart.trim().split("=")[0].trim(); // drop any default value
+        if (!part)
+            continue;
+        const bound = part.includes(":") ? (part.split(":")[1] ?? "").trim() : part;
+        if (bound === local)
+            return m[2];
+    }
+    return null;
+}
+/** Follow ONE hop (plus one bounded bare-identifier hop): classify every
+ * assignment/declaration of `local` in the handler as scope-derived, arg-derived,
+ * or could-not-judge. Reads a PLAIN assignment RHS and a DESTRUCTURING RHS with
+ * the same scope test (defect 1). Exposes `matched` so a local with NO resolvable
+ * assignment is a third state, not silently tainted (defect 2). A bare-identifier
+ * RHS (`const t = orgSlug`) is NOT scope evidence on its own — the identifier's
+ * own provenance is resolved one further, bounded, cycle-guarded hop (defect 3);
+ * exhaustion is `cnj`, never a guess. */
+export function analyzeLocalTaint(h, local, isResolver) {
+    return analyzeLocalTaintInner({ ...h, lines: normalizeLines(h.lines) }, local, 0, new Set(), isResolver);
+}
+/** `rhs` is exactly `await <name>(…)` closed on this line (nothing after the
+ * call but `;`): the whole value is that function's return. */
+function wholeAwaitedCall(rhs) {
+    const m = /^\s*await\s+([A-Za-z_$][\w$]*)\s*\(/.exec(rhs);
+    if (!m)
+        return null;
+    let depth = 0;
+    for (let i = m[0].length - 1; i < rhs.length; i++) {
+        const ch = rhs[i];
+        if (ch === "(")
+            depth++;
+        else if (ch === ")") {
+            depth--;
+            if (depth === 0)
+                return /^\s*;?\s*$/.test(rhs.slice(i + 1)) ? m[1] : null;
+        }
+    }
+    return null;
+}
+function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
+    let fromArgs = 0;
+    let fromScope = 0;
+    let matched = 0;
+    let cnj = 0;
+    let fromResolver = 0;
+    const esc = local.replace(/[$]/g, "\\$&");
+    const assign = new RegExp(`(?:^|[^\\w.$])${esc}\\s*(?::[^=\\n]*)?=(?!=)`);
+    const decl = new RegExp(`\\b(?:const|let|var)\\s+${esc}\\b`);
+    const classify = (rhs) => {
+        // A BARE IDENTIFIER RHS carries no scope evidence on its own — its NAME
+        // (even `orgSlug`) never counts as scope; the identifier's own provenance
+        // decides, or the scan refuses (defect 3, Eta pole 2).
+        const bare = rhs
+            .trim()
+            .replace(/;+\s*$/, "")
+            .trim();
+        if (/^[A-Za-z_$][\w$]*$/.test(bare) && bare !== "args") {
+            if (visited.has(bare) || depth >= R6_MAX_HOP) {
+                cnj++; // cycle or hop exhausted — could-not-judge, never a guess.
+                return;
+            }
+            const next = new Set(visited);
+            next.add(local);
+            const sub = analyzeLocalTaintInner(h, bare, depth + 1, next, isResolver);
+            if (sub.matched === 0)
+                cnj++; // the referenced local has no resolvable assignment.
+            else if (sub.fromScope > 0 && sub.fromArgs === 0)
+                fromScope++;
+            else if (sub.fromArgs > 0)
+                fromArgs++;
+            else
+                cnj++;
+            return;
+        }
+        // The whole value is the return of a function the tree shows to be an
+        // identity RESOLVER (it returns the verified scope itself and refuses an
+        // absent identity first): scope-derived, whatever arguments it was handed.
+        const called = isResolver ? wholeAwaitedCall(rhs) : null;
+        if (called && isResolver?.(called)) {
+            fromScope++;
+            fromResolver++;
+            return;
+        }
+        // Strip `args.<field>` from the RHS BEFORE the scope test so an argument
+        // whose FIELD is named like a scope key cannot launder itself:
+        // `const t = args.orgSlug` must not read scope-derived just because
+        // R6_SCOPE_RHS carries `\borgSlug\b`. The value is still an argument, and
+        // the law above (a local fed only from args is tainted) governs. Genuine
+        // `scope.orgSlug` / `withOrgScope(...)` RHS has no `args.` token to strip
+        // and still matches → fromScope.
+        const rhsForScope = rhs.replace(/\bargs\.\w+/g, "");
+        if (R6_SCOPE_RHS.test(rhsForScope))
+            fromScope++;
+        else
+            fromArgs++;
+    };
+    for (const l of h.lines) {
+        if (!code(l))
+            continue;
+        const raw = l.raw;
+        // The handler's own parameter destructured — the binding IS the argument.
+        if (boundFromHandlerParam(raw, local)) {
+            matched++;
+            fromArgs++;
+            continue;
+        }
+        // A destructuring binding of `local` — test its RHS as a plain RHS.
+        const dr = destructuredRhs(raw, local);
+        if (dr !== null) {
+            matched++;
+            classify(dr);
+            continue;
+        }
+        const isAssign = assign.test(raw);
+        const isBareDecl = !isAssign && decl.test(raw) && !raw.includes("=");
+        if (!isAssign && !isBareDecl)
+            continue;
+        matched++;
+        const rhs = isAssign ? raw.slice(raw.indexOf("=") + 1) : "";
+        classify(rhs);
+    }
+    return fromResolver > 0
+        ? { fromArgs, fromScope, matched, cnj, fromResolver }
+        : { fromArgs, fromScope, matched, cnj };
+}
+/** The full source text of every `ctx.db.insert|patch|replace(...)` call in a
+ * handler, each joined across the lines the call spans (parens balanced). The
+ * tenant-provenance regexes read THIS — never the args-declaration block or a
+ * plain local assignment — so `tenantId: args.tenantId` is only ever counted
+ * when it is the value actually handed to a write. */
+function writeSiteTexts(h) {
+    const out = [];
+    const codeLines = h.lines.filter(code);
+    for (let i = 0; i < codeLines.length; i++) {
+        if (!/ctx\.db\.(?:insert|patch|replace)\s*\(/.test(codeLines[i].raw))
+            continue;
+        let depth = 0;
+        let started = false;
+        let text = "";
+        for (let j = i; j < codeLines.length; j++) {
+            const raw = codeLines[j].raw;
+            text += (text ? "\n" : "") + raw;
+            for (const ch of raw) {
+                if (ch === "(") {
+                    depth++;
+                    started = true;
+                }
+                else if (ch === ")")
+                    depth--;
+            }
+            if (started && depth <= 0)
+                break;
+        }
+        out.push(text);
+    }
+    return out;
+}
+// ---- named guard HELPERS defined outside the handler ----------------------
+//
+// A public mutation frequently enforces its boundary in ONE line that calls a
+// helper defined elsewhere: `await requireOrgAdmin(ctx, args.orgSlug)` binds the
+// org argument to the verified identity's own org and throws RBAC_DENIED
+// otherwise; `requireFleetMaster` / `requireServiceAccount` refuse every caller
+// that is not the fleet master. The in-handler regexes above cannot see the
+// helper's body. The fix is a NAMED ALLOWLIST — never "any function whose name
+// starts with require" — and each listed helper is credited only when its OWN
+// DEFINITION is found in the scanned tree and its CONTROL FLOW refuses, on every
+// path to a normal exit, through a branch conditioned on the verified identity
+// (guard-helper-flow.ts). A helper the walk cannot decide is could-not-judge,
+// never credited; so is a call to a listed helper with no readable definition.
+//
+//  - "binds-arg": the helper compares its target parameter with the identity;
+//    it legitimises a direct-arg boundary write ONLY for an argument that was
+//    handed to it (`requireOrgAdmin(ctx, args.orgSlug)` then
+//    `orgSlug: args.orgSlug`). A different argument written as the boundary is
+//    still the argument.
+//  - "master-only": the helper admits the fleet master alone; the master's
+//    authority is fleet-wide by design (the documented carve-out), so a
+//    boundary argument it writes is the master's decision, not a forgery.
+//
+// The CALL is credited only when it is a direct `await` statement of the
+// handler's body, before the write: a call inside a branch, a try or a closure
+// of the handler is not run on every path.
+export const R6_GUARD_HELPERS = {
+    requireOrgAdmin: "binds-arg",
+    requireFleetMaster: "master-only",
+    requireServiceAccount: "master-only",
+};
+const sourceOf = (f) => f.lines.map((l) => l.raw).join("\n");
+/** Index every definition of an allowlisted helper in the tree. */
+export function indexGuardHelpers(files) {
+    const out = new Map();
+    const names = Object.keys(R6_GUARD_HELPERS);
     for (const f of files) {
-        if (!isJudgeable(f) || !isConvex(f))
+        if (!isJudgeable(f))
+            continue;
+        const src = sourceOf(f);
+        if (!names.some((n) => src.includes(n)))
+            continue;
+        for (const d of findHelperDefinitions(f.rel, src, R6_GUARD_HELPERS)) {
+            const list = out.get(d.name) ?? [];
+            list.push({
+                rel: f.rel,
+                n: d.line,
+                exported: d.exported,
+                judgement: d.judgement,
+            });
+            out.set(d.name, list);
+        }
+    }
+    return out;
+}
+const HELPER_NAMES = new Set(Object.keys(R6_GUARD_HELPERS));
+const HELPER_MENTION = new RegExp(`\\b(?:${Object.keys(R6_GUARD_HELPERS).join("|")})\\s*\\(`);
+/** `null` when the handler mentions a listed helper but its body could not be
+ * located for the statement-level read (could-not-judge, never credit). */
+function helperCalls(h, f, writeLine, index, src) {
+    if (!h.lines.some((l) => code(l) && HELPER_MENTION.test(l.raw)))
+        return [];
+    const calls = topLevelHelperCalls(f.rel, src(), h.name, HELPER_NAMES, writeLine);
+    if (calls === null)
+        return null;
+    return calls.map((c) => {
+        const defs = index.get(c.name) ?? [];
+        const def = defs.find((d) => d.rel === f.rel) ?? defs.find((d) => d.exported);
+        return { name: c.name, kind: R6_GUARD_HELPERS[c.name], args: c.args, def };
+    });
+}
+/** Every `args.<field>` written DIRECTLY to a boundary field at a write site. */
+function directBoundaryArgs(writes) {
+    const out = [];
+    const re = /\b(?:tenantId|orgId|orgSlug|createdBy|namespace|orchestratorId|ownerId)\s*:\s*(args\.\w+)/g;
+    for (const t of writes) {
+        re.lastIndex = 0;
+        let m = re.exec(t);
+        while (m !== null) {
+            out.push(m[1]);
+            m = re.exec(t);
+        }
+    }
+    return out;
+}
+/** The honoured helper call that covers this handler's boundary, if any.
+ * "master-only" covers any boundary write; "binds-arg" covers it only when every
+ * direct-arg boundary value written is an argument handed to the helper. */
+function coveringCall(calls, writes) {
+    const honoured = calls.filter((c) => c.def?.judgement.verdict === "honoured");
+    const master = honoured.find((c) => c.kind === "master-only");
+    if (master)
+        return master;
+    const bound = honoured.filter((c) => c.kind === "binds-arg");
+    if (bound.length === 0)
+        return undefined;
+    const direct = directBoundaryArgs(writes);
+    const all = direct.every((a) => bound.some((c) => new RegExp(`\\b${a.replace(".", "\\.")}\\b`).test(c.args)));
+    return all ? bound[0] : undefined;
+}
+class FunctionIndex {
+    files;
+    parsed = new Map();
+    judged = new Map();
+    resolvers = new Map();
+    constructor(files) {
+        this.files = files;
+    }
+    defsIn(f) {
+        let d = this.parsed.get(f.rel);
+        if (!d) {
+            d = topLevelFunctions(f.rel, sourceOf(f));
+            this.parsed.set(f.rel, d);
+        }
+        return d;
+    }
+    lookup(name, fromRel) {
+        if (!/^[A-Za-z_][\w]*$/.test(name))
+            return undefined;
+        const decl = new RegExp(`\\b(?:function\\s*\\*?\\s*${name}\\b|const\\s+${name}\\s*=)`);
+        const local = this.files.find((f) => f.rel === fromRel);
+        if (local) {
+            const own = this.defsIn(local).find((d) => d.name === name);
+            if (own)
+                return { rel: local.rel, f: own };
+        }
+        const found = [];
+        for (const f of this.files) {
+            if (f.rel === fromRel || !isJudgeable(f))
+                continue;
+            if (!f.lines.some((l) => decl.test(l.raw)))
+                continue;
+            for (const d of this.defsIn(f))
+                if (d.name === name && d.exported)
+                    found.push({ rel: f.rel, f: d });
+        }
+        return found.length === 1 ? found[0] : undefined;
+    }
+    judge(key, run) {
+        let v = this.judged.get(key);
+        if (!v) {
+            v = run();
+            this.judged.set(key, v);
+        }
+        return v;
+    }
+    /** Names seen from `fromRel`, resolved by `lookup` (same file first, else
+     * the single exported definition). */
+    callResolver(fromRel) {
+        let r = this.resolvers.get(fromRel);
+        if (!r) {
+            r = (name) => {
+                const d = this.lookup(name, fromRel);
+                return d
+                    ? {
+                        fn: d.f.fn,
+                        key: `${d.rel}:${d.f.line}`,
+                        resolve: this.callResolver(d.rel),
+                    }
+                    : undefined;
+            };
+            this.resolvers.set(fromRel, r);
+        }
+        return r;
+    }
+    resolver(name, fromRel) {
+        const d = this.lookup(name, fromRel);
+        if (!d)
+            return undefined;
+        const v = this.judge(`R:${d.rel}:${d.f.line}`, () => judgeResolverFunction(d.f.fn));
+        return v.verdict === "honoured" ? d : undefined;
+    }
+}
+/** The boundary RHS expressions (`mission.orgId`) that a refusing predicate
+ * bound to the caller's verified scope before the write, with the predicate
+ * that did it. */
+function predicateBoundValues(h, f, writeLine, fns, src) {
+    const out = new Map();
+    if (!h.lines.some((l) => code(l) && /\bif\s*\(\s*!\s*[A-Za-z_$][\w$]*\s*\(/.test(l.raw)))
+        return out;
+    const g = readHandlerGuards(f.rel, src(), h.name, writeLine);
+    if (!g)
+        return out;
+    const isIdentityLocal = (n) => {
+        if (!n)
+            return false;
+        const c = g.consts.get(n);
+        if (!c)
+            return false;
+        if (c.identityRead)
+            return true;
+        return !!c.awaitedCallee && !!fns.resolver(c.awaitedCallee, f.rel);
+    };
+    for (const r of g.refusals) {
+        const i = r.args.findIndex((a) => isIdentityLocal(a.ident));
+        const j = r.args.findIndex((a) => a.memberBase !== undefined && g.consts.has(a.memberBase));
+        if (i < 0 || j < 0)
+            continue;
+        const value = r.args[j].text.replace(/\s+/g, "");
+        // The bound property must not be re-assigned in the handler.
+        const esc = value.replace(/[.$]/g, "\\$&");
+        if (h.lines.some((l) => code(l) && new RegExp(`${esc}\\s*=(?!=)`).test(l.raw)))
+            continue;
+        const d = fns.lookup(r.predicate, f.rel);
+        if (!d)
             continue;
+        const v = fns.judge(`P:${d.rel}:${d.f.line}:${i}:${j}`, () => judgePredicateFunction(d.f.fn, i, j));
+        if (v.verdict === "honoured")
+            out.set(value, `${r.predicate}() (definition ${d.rel}:${d.f.line})`);
+    }
+    return out;
+}
+/** The caller arguments (`args.namespace`) a BINDING VALIDATOR bound to the
+ * caller's verified scope before the write: a direct `await V(…, args.x, …)`
+ * statement of the handler whose callee, read in the tree on its body
+ * (summarizeValidator), reaches a normal exit only when `args.x` passed a
+ * predicate over the verified scope (or for the fleet master). Name-free. */
+function validatorBoundArgs(h, f, writeLine, fns, src) {
+    const out = new Map();
+    const calls = topLevelHelperCalls(f.rel, src(), h.name, null, writeLine);
+    if (!calls)
+        return out;
+    let g;
+    for (const c of calls) {
+        const targets = c.argNodes
+            .map((a, k) => ({ k, text: a.getText().replace(/\s+/g, "") }))
+            .filter((a) => /^args\.[A-Za-z_$][\w$]*$/.test(a.text));
+        if (targets.length === 0)
+            continue;
+        const d = fns.lookup(c.name, f.rel);
+        if (!d)
+            continue;
+        // An argument that is the handler's own verified scope (a const bound to
+        // an identity read, or to a function judged an identity resolver).
+        g ??= readHandlerGuards(f.rel, src(), h.name, writeLine);
+        const identityIdx = c.argNodes.findIndex((a) => {
+            const t = a.getText();
+            const k = g?.consts.get(t);
+            return (!!k &&
+                (k.identityRead ||
+                    (!!k.awaitedCallee && !!fns.resolver(k.awaitedCallee, f.rel))));
+        });
+        for (const t of targets) {
+            const sum = summarizeValidator(d.f.fn, {
+                boundIdx: t.k,
+                identityIdx: identityIdx < 0 ? undefined : identityIdx,
+                callArgs: c.argNodes,
+                resolve: fns.callResolver(d.rel),
+                key: `${d.rel}:${d.f.line}`,
+                depth: 0,
+            });
+            if (sum.ok && sum.exitsBound && !sum.never)
+                out.set(t.text, `${c.name}() (definition ${d.rel}:${d.f.line})`);
+        }
+    }
+    return out;
+}
+/** The write texts with every boundary value that IS (completely) a validated
+ * argument replaced by a placeholder: what is left is what still reads args. */
+function maskValidated(writes, validated) {
+    return writes.map((t) => t.replace(/(\b(?:tenantId|orgId|orgSlug|createdBy|namespace|orchestratorId|ownerId)\s*:\s*)(args\.[A-Za-z_$][\w$]*)(?=\s*(?:,|\}|$))/gm, (m, field, arg) => validated.has(arg) ? `${field}__validated__` : m));
+}
+/** Every RHS of the boundary local `loc` at the write sites, when EACH is a
+ * complete member expression on it (`orgId: mission.orgId,`); null when any
+ * occurrence is something else (`orgId: mission.orgId ?? args.x`, `{ orgId }`). */
+function boundaryMemberRhs(writes, loc) {
+    const out = [];
+    const esc = loc.replace(/[$]/g, "\\$&");
+    const any = new RegExp(`\\b(?:tenantId|orgId|orgSlug)\\s*:\\s*${esc}\\b`, "g");
+    const full = new RegExp(`^\\s*(${esc}(?:\\.[A-Za-z_$][\\w$]*)+)\\s*(?:,|}|$)`);
+    for (const t of writes) {
+        any.lastIndex = 0;
+        let m = any.exec(t);
+        while (m !== null) {
+            const rest = t.slice(m.index + m[0].length - loc.length);
+            const fm = full.exec(rest.split("\n")[0]);
+            if (!fm)
+                return null;
+            out.push(fm[1]);
+            m = any.exec(t);
+        }
+    }
+    return out.length ? out : null;
+}
+export function scanR6(files, rootIsConvex = false) {
+    const scan = emptyScan();
+    const helperIndex = indexGuardHelpers(files);
+    const fns = new FunctionIndex(files);
+    for (const raw of files) {
+        if (!isJudgeable(raw) || !isConvex(raw, rootIsConvex))
+            continue;
+        // One shape for every argument read: `args["x"]` → `args.x`.
+        const f = { ...raw, lines: normalizeLines(raw.lines) };
         for (const h of splitMutationHandlers(f)) {
+            // An internalMutation has NO client caller: its arguments come from
+            // server code (a cron, a scheduler hop, another function), so "a
+            // caller-supplied argument" — the thing R-6 forbids (standard
+            // 4bcd605 :71, :252 "never accept a userId as a function argument")
+            // does not exist there. R-6 governs the client-callable write only.
+            if (h.internal)
+                continue;
             let writeLine = 0;
             let guard = false;
             let boundaryArg = false;
+            let resolvesScope = false;
             for (const l of h.lines) {
                 if (!code(l))
                     continue;
@@ -133,12 +740,196 @@ export function scanR6(files) {
                     writeLine = l.n;
                 if (R6_IDENTITY_GUARD.test(l.raw) || R6_RESOURCE_GUARD.test(l.raw))
                     guard = true;
+                if (R6_SCOPE_RESOLUTION.test(l.raw))
+                    resolvesScope = true;
                 if (R6_BOUNDARY_ARG.test(l.raw))
                     boundaryArg = true;
             }
             if (!writeLine)
                 continue; // not a write handler — R-6 does not govern it.
-            if (guard) {
+            const writes = writeSiteTexts(h);
+            let directTenant = writes.some((t) => R6_TENANT_FROM_ARG.test(t));
+            // Follow the local ONE hop: every non-`args` local written to a tenant
+            // boundary field, and its THREE-STATE provenance. A local fed from args
+            // (matched>0, fromScope===0, fromArgs>0) is TAINTED; a local with NO
+            // resolvable assignment (matched===0) or only unresolved indirections is
+            // COULD-NOT-JUDGE — never silently tainted (Eta REVISE #3 defect 2).
+            const boundaryLocals = [
+                ...new Set(writes.flatMap(boundaryLocalsInWrite)),
+            ];
+            let taintedLocal;
+            let cnjLocal;
+            let anyDerived = false;
+            let fileSrc;
+            const getSrc = () => {
+                fileSrc ??= sourceOf(f);
+                return fileSrc;
+            };
+            const resolvedBy = new Map();
+            const isResolver = (name) => {
+                const d = fns.resolver(name, f.rel);
+                if (d)
+                    resolvedBy.set(name, `${d.rel}:${d.f.line}`);
+                return !!d;
+            };
+            const credits = [];
+            // A boundary written straight from an argument a BINDING VALIDATOR
+            // bound to the verified scope before the write: credited only when
+            // EVERY argument written to a boundary field is so bound.
+            if (directBoundaryArgs(writes).length > 0) {
+                const validated = validatorBoundArgs(h, f, writeLine, fns, getSrc);
+                const masked = maskValidated(writes, validated);
+                if (validated.size > 0 &&
+                    directBoundaryArgs(masked).length === 0 &&
+                    !masked.some((t) => R6_TENANT_FROM_ARG.test(t))) {
+                    directTenant = false;
+                    boundaryArg = false;
+                    anyDerived = true;
+                    resolvesScope = true;
+                    const written = new Set(directBoundaryArgs(writes));
+                    for (const [arg, by] of validated)
+                        if (written.has(arg))
+                            credits.push(`\`${arg}\` bound to the verified scope by validator ${by}, which returns only when it passes a predicate over the verified scope (or for the fleet master) and refuses otherwise`);
+                }
+            }
+            let bound;
+            for (const loc of boundaryLocals) {
+                // A value a refusing predicate bound to the caller's scope before
+                // the write (`if (!P(scope, mission.orgId)) throw`), written
+                // unchanged: derived from the verified identity through the target.
+                const rhs = boundaryMemberRhs(writes, loc);
+                if (rhs) {
+                    bound ??= predicateBoundValues(h, f, writeLine, fns, getSrc);
+                    const by = rhs.map((x) => bound?.get(x));
+                    if (by.every((x) => x !== undefined)) {
+                        anyDerived = true;
+                        resolvesScope = true;
+                        credits.push(`\`${rhs[0]}\` bound to the verified scope by refusing predicate ${by[0]}`);
+                        continue;
+                    }
+                }
+                resolvedBy.clear();
+                const a = analyzeLocalTaint(h, loc, isResolver);
+                if (a.fromResolver) {
+                    resolvesScope = true;
+                    credits.push(`local "${loc}" is the return of identity resolver ${[...resolvedBy].map(([n, at]) => `${n}() (definition ${at})`).join(", ")}, which returns the verified scope itself and refuses an absent identity on every path`);
+                }
+                if (a.fromScope > 0) {
+                    anyDerived = true;
+                }
+                else if (a.matched === 0) {
+                    cnjLocal ??= loc; // no assignment/declaration found — cannot judge.
+                }
+                else if (a.fromArgs > 0) {
+                    taintedLocal ??= loc; // fed only from args — laundered argument.
+                }
+                else {
+                    cnjLocal ??= loc; // matched but only unresolved bare-id hops.
+                }
+            }
+            // A CONDITIONAL boundary value (`orgId: c ? a : b`): an arm that reads
+            // the caller's args is the argument, unless it is the TRUE arm of a
+            // positive `<scope>.isMaster` test on a scope-derived local (the
+            // fleet carve-out: the master's authority is fleet-wide by design).
+            let conditionalArg;
+            for (const cb of writes.flatMap((t) => conditionalBoundaries(t, R6_TENANT_FIELDS))) {
+                const base = cb.masterBase;
+                const masterArm = base !== undefined &&
+                    base !== "args" &&
+                    (() => {
+                        const a = analyzeLocalTaint(h, base, isResolver);
+                        return a.fromScope > 0 && a.fromArgs === 0;
+                    })();
+                if (cb.falseReadsArgs || (cb.trueReadsArgs && !masterArm)) {
+                    conditionalArg ??= cb.field;
+                }
+            }
+            const derivedTenant = anyDerived;
+            const accusable = directTenant ||
+                conditionalArg ||
+                taintedLocal ||
+                (!guard && boundaryArg);
+            const calls = helperCalls(h, f, writeLine, helperIndex, getSrc);
+            const violateBefore = scan.violate.length;
+            const cover = calls ? coveringCall(calls, writes) : undefined;
+            if (cover?.def) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: boundary enforced by allowlisted guard helper ${cover.name}() (${cover.kind}; definition ${cover.def.rel}:${cover.def.n} refuses on every path through a branch conditioned on the verified identity)`,
+                });
+                continue;
+            }
+            // The handler leans on an allowlisted helper the doctor cannot judge:
+            // its definition is not in the scanned tree, its control flow is not
+            // modelled, or the handler body itself could not be located. Neither
+            // credited nor accused.
+            const undecided = calls === null
+                ? "its handler body could not be located for the statement-level read"
+                : calls
+                    .map((c) => c.def === undefined
+                    ? `${c.name}() has no readable definition in the scanned tree`
+                    : c.def.judgement.verdict === "could-not-judge"
+                        ? `${c.name}() at ${c.def.rel}:${c.def.n} could not be judged — ${c.def.judgement.why}`
+                        : "")
+                    .find((x) => x !== "");
+            if (undecided && accusable) {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: relies on an allowlisted guard helper whose enforcement cannot be decided — ${undecided} (could-not-judge, not an accusation)`,
+                });
+                continue;
+            }
+            if (directTenant) {
+                // Decisive VIOLATE — the WRITE-SITE provenance, not guard presence,
+                // is what R-6 governs. A tenant-scoping field written straight from a
+                // caller arg is the boundary being the argument, even when the handler
+                // resolves scope elsewhere (the historical sendMessage defect).
+                scan.violate.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: writes a tenant-scoping boundary field (tenantId/orgId/orgSlug) directly from a caller argument AT THE WRITE SITE — provenance is the raw arg, not a resolved scope, even if a guard is present elsewhere`,
+                });
+            }
+            else if (conditionalArg) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: writes tenant-scoping boundary field "${conditionalArg}" from a conditional whose arm reads a caller argument outside a positive isMaster test on the resolved scope — that arm writes the argument`,
+                });
+            }
+            else if (taintedLocal) {
+                // LAUNDERED VIOLATE — the boundary field is a local (`tenantId: t`)
+                // but every assignment to that local is fed from args (fromScope===0):
+                // the caller's argument reaching the write under another name. A rename
+                // hop does not sanitise provenance; scope resolved elsewhere in the
+                // handler does not rescue it.
+                scan.violate.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: writes tenant-scoping boundary field from local "${taintedLocal}" whose every assignment is caller-arg-derived (fromScope=0) — the argument laundered through a rename, not a scope-derived value`,
+                });
+            }
+            else if (cnjLocal && !anyDerived) {
+                // THIRD STATE — a boundary local whose provenance could not be
+                // resolved (no assignment/declaration found in-handler, or only
+                // unresolved bare-identifier indirections). This is could-not-judge,
+                // NEVER an accusation (Eta REVISE #3 defect 2).
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: writes tenant-scoping boundary field from local "${cnjLocal}" whose provenance could not be resolved in-handler (no assignment/declaration found, or only unresolved indirections) — could-not-judge, not an accusation`,
+                });
+            }
+            else if (derivedTenant && resolvesScope) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: writeLine,
+                    note: `${h.name}: tenant boundary written from a scope-derived local at the write site (scope/identity resolved in-handler)${credits.length ? ` — ${credits.join("; ")}` : ""}`,
+                });
+            }
+            else if (guard) {
                 scan.conform.push({
                     rel: f.rel,
                     n: writeLine,
@@ -159,6 +950,16 @@ export function scanR6(files) {
                     note: `${h.name}: writes with no identity/resource guard and no clearly caller-supplied boundary field — deferred, not statically confirmed`,
                 });
             }
+            // A violation at a site calling a listed helper whose definition was
+            // read and NOT honoured says why, so the reader is not left believing
+            // the helper was simply missed.
+            const refused = calls?.find((c) => c.def?.judgement.verdict === "refused");
+            if (refused?.def &&
+                refused.def.judgement.verdict === "refused" &&
+                scan.violate.length > violateBefore) {
+                const v = scan.violate[scan.violate.length - 1];
+                v.note += `; allowlisted helper ${refused.name}() at ${refused.def.rel}:${refused.def.n} NOT honoured — ${refused.def.judgement.why}`;
+            }
         }
     }
     return scan;
@@ -199,10 +1000,10 @@ function collectConvexErrorThrows(f) {
     }
     return out;
 }
-export function scanR16(files) {
+export function scanR16(files, rootIsConvex = false) {
     const scan = emptyScan();
     for (const f of files) {
-        if (!isJudgeable(f) || !isConvex(f))
+        if (!isJudgeable(f) || !isConvex(f, rootIsConvex))
             continue;
         for (const t of collectConvexErrorThrows(f)) {
             if (R16_CODE_TOKEN.test(t.payload)) {
@@ -394,13 +1195,13 @@ function stringifyResult(res) {
 /** R-6 — static primary + live secondary (LiveDetector). */
 export const R6 = {
     id: R6_ID,
-    run: (tree) => decide("R-6", R6_ID, R6_CHECK, scanR6(tree.files), "R-6: zero convex write handlers matched in the scanned tree — cannot certify boundary derivation. NOT a clean bill."),
+    run: (tree) => decide("R-6", R6_ID, R6_CHECK, scanR6(tree.files, rootIsConvexDir(tree.root)), "R-6: zero convex write handlers matched in the scanned tree — cannot certify boundary derivation. NOT a clean bill."),
     runLive: r6RunLive,
 };
 /** R-16 — static primary + live secondary (LiveDetector). */
 export const R16 = {
     id: R16_ID,
-    run: (tree) => decide("R-16", R16_ID, R16_CHECK, scanR16(tree.files), "R-16: zero ConvexError throw sites matched in the scanned convex tree — cannot certify the error contract. NOT a clean bill."),
+    run: (tree) => decide("R-16", R16_ID, R16_CHECK, scanR16(tree.files, rootIsConvexDir(tree.root)), "R-16: zero ConvexError throw sites matched in the scanned convex tree — cannot certify the error contract. NOT a clean bill."),
     runLive: r16RunLive,
 };
 /** The two, in a form the orchestrator spreads into REGISTRY. */