@vantageos/backend-doctor 0.2.0 → 0.4.0

package/dist/detectors/source/cross-tenant-write.js

@@ -0,0 +1,1408 @@
+// R-52 — a write that reaches a row carrying no tenant value, through a value the
+// caller can choose, checks the tenant on that target before it writes.
+//
+// Standard 2825122 §4 (R-52) and its Detector spec, read literally:
+//   reads   schema.ts — per table, whether a tenant column (orgId/tenantId/
+//           workspaceId/orgSlug, or a namespace checked against the caller's
+//           allowed prefixes) exists and whether it is optional; per table, which
+//           fields a public write sets from its arguments (what makes a stored
+//           field caller-chosen); every public mutation/action handler; per write
+//           (ctx.db.patch/replace/delete/insert, a scheduled or run effect) the
+//           provenance of the id or key that selected its target.
+//   red     a write whose target carries no tenant value, selected by an
+//           argument-derived value or a caller-chosen stored field, with no guard
+//           on its path that reads a server-stamped tenant and refuses or skips it.
+//   green   such a guard dominates the write; or the selector is not
+//           caller-choosable; or the target has a REQUIRED tenant column.
+//   cnj     a selector whose provenance the walk cannot resolve, or an
+//           unreadable schema — never a readable site.
+//   No justification-token exit. Coverage fails on itself.
+//
+// HOW THE WALK DECIDES (each piece is read from the delivered source):
+//   * the namespace column — a tenant column only where it is prefix-checked
+//     (ElPi-Corp #228). Per table carrying a `namespace` and no required tenant
+//     column, every public query/mutation/action that reads or writes it is
+//     read: it is checked when it calls a prefix test (a function taking a
+//     namespace parameter and testing it with `.startsWith`, closed over calls —
+//     vantage-peers `isNamespaceAllowedForScope`, convex/lib/auth.ts) or refuses
+//     every non-master. All doors checked -> tenant column; none -> untenanted;
+//     mixed, or no public door -> every site targeting it is could-not-judge.
+//   * provenance — every local of a handler is evaluated from its initializer:
+//     `args.x` is an argument; `row.f` of a table T is a caller-chosen stored field
+//     when some public write sets T.f from its arguments (insert literal, `...args`
+//     spread, patch literal through an `args.<id>`); a row fetched or queried by a
+//     caller-choosable key carries that provenance into every value read off it —
+//     `mapping.repo` of a `githubRepoMapping` row looked up by `task.project` is
+//     caller-choosable, and so is the `issues` row it then selects.
+//   * the target — a patch/replace/delete reaches the row its selector names; an
+//     insert or a scheduled/run effect is ATTRIBUTED to a selected row when its
+//     payload, or a condition enclosing it, reads that row.
+//   * the guard — it must DOMINATE the write: an enclosing `if`/`&&` gate, an
+//     earlier `if (…) throw|return|continue`, or an earlier call to a refusing
+//     helper. What it must read depends on the target:
+//       - optional tenant column (the row may be unstamped): the TARGET'S OWN
+//         tenant, directly (`row.orgId`) or through a helper handed the target row;
+//       - no tenant column: the caller's or the source row's server-stamped tenant
+//         AND a fleet-scope decision (the standard: "a row with no tenant value is
+//         reachable only by a tenant the code names as fleet-scoped") — read as an
+//         `isMaster`/`orgKind`/operator/fleet test, or an unconditional master-only
+//         refusal (`if (!scope.isMaster) throw`). A visibility check on a DIFFERENT
+//         row (the source task's own tenant gate) is not a check on the target.
+import * as ts from "typescript";
+import { calledNames, calleeName, closeOverCalls, dotted, indexFunctions, lineOf, NAMESPACE_COLUMN, parseFile, readSchema, registrations, TENANT_COLUMNS, unwrap, walk, } from "./_ast.js";
+import { decide, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, } from "./_scan.js";
+import { possessionGate } from "./r6-shapes.js";
+export 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";
+const R52_CHECK = "a patch/replace/delete, an attributed insert or a scheduled effect whose target carries no tenant value and is selected by an argument or a caller-chosen stored field is dominated by a guard reading a server-stamped tenant";
+/** Array methods whose result holds the receiver's own elements. */
+const PRESERVING = new Set([
+    "slice",
+    "concat",
+    "reverse",
+    "sort",
+    "toSorted",
+    "toReversed",
+]);
+const ITERATORS = new Set([
+    "map",
+    "forEach",
+    "filter",
+    "find",
+    "some",
+    "every",
+    "flatMap",
+    "findLast",
+]);
+const SAFE = { kind: "value", vias: [] };
+function mergeVias(a, b) {
+    const out = [...a];
+    for (const v of b)
+        if (!out.some((x) => x.table === v.table && x.line === v.line))
+            out.push(v);
+    return out;
+}
+/** Both provenances, when the two halves name different ones (capped). */
+function joinReasons(a, b) {
+    if (!a)
+        return b;
+    if (!b || a.includes(b))
+        return a;
+    if (a.split(" + ").length >= 3)
+        return a;
+    return `${a} + ${b}`;
+}
+function merge(a, b) {
+    return {
+        kind: "value",
+        choosable: joinReasons(a.choosable, b.choosable),
+        vias: mergeVias(a.vias, b.vias),
+        unresolved: a.unresolved ?? b.unresolved,
+        gate: a.gate || b.gate
+            ? {
+                tables: new Set([
+                    ...(a.gate?.tables ?? []),
+                    ...(b.gate?.tables ?? []),
+                ]),
+                fleet: Boolean(a.gate?.fleet || b.gate?.fleet),
+            }
+            : undefined,
+    };
+}
+// ---- fleet scope ----------------------------------------------------------
+//
+// "A row with no tenant value is reachable only by a tenant the code names as
+// fleet-scoped." A condition is FLEET-ONLY when it can hold for no caller but a
+// fleet-scoped one: a positive `isMaster` read, an `orgKind ===` test, a tenant
+// column tested `=== undefined` (the unstamped, fleet-created row), a call to a
+// fleet-only helper or a local bound to one; a `||` chain needs EVERY disjunct
+// fleet-only, a `&&` chain needs ONE conjunct. A name allow-list
+// (`allowedOrchestrators.includes(name)`) is not a fleet decision.
+function isUndefinedLit(e) {
+    const u = unwrap(e);
+    return ts.isIdentifier(u) && u.text === "undefined";
+}
+export function fleetOnlyExpr(e0, isFleetHelper, isFleetLocal = () => false) {
+    const e = unwrap(e0);
+    const rec = (x) => fleetOnlyExpr(x, isFleetHelper, isFleetLocal);
+    if (e.kind === ts.SyntaxKind.FalseKeyword ||
+        e.kind === ts.SyntaxKind.NullKeyword ||
+        isUndefinedLit(e))
+        return true;
+    if (ts.isBinaryExpression(e)) {
+        const op = e.operatorToken.kind;
+        if (op === ts.SyntaxKind.BarBarToken)
+            return rec(e.left) && rec(e.right);
+        if (op === ts.SyntaxKind.AmpersandAmpersandToken)
+            return rec(e.left) || rec(e.right);
+        if (op === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+            op === ts.SyntaxKind.EqualsEqualsToken) {
+            const sides = [e.left, e.right].map(unwrap);
+            if (sides.some((x) => ts.isPropertyAccessExpression(x) && x.name.text === "orgKind"))
+                return true;
+            if (sides.some((x) => ts.isPropertyAccessExpression(x) && TENANT_COLUMNS.has(x.name.text)) &&
+                sides.some(isUndefinedLit))
+                return true;
+        }
+        return false;
+    }
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text === "isMaster";
+    if (ts.isIdentifier(e))
+        return e.text === "isMaster" || isFleetLocal(e.text);
+    if (ts.isCallExpression(e)) {
+        const f = unwrap(e.expression);
+        return ts.isIdentifier(f) && isFleetHelper(f.text);
+    }
+    return false;
+}
+/** A helper every truthy `return` of which is fleet-only: a fleet-only
+ * expression, or a bare `true` inside an `if` whose condition is fleet-only. */
+function fleetOnlyFunction(fn, known) {
+    const body = fn.body;
+    if (!body || !ts.isBlock(body))
+        return false;
+    const isHelper = (n) => known.has(n);
+    let returns = 0;
+    let ok = true;
+    walk(body, (x) => {
+        if (!ts.isReturnStatement(x))
+            return;
+        returns++;
+        const r = x.expression;
+        if (!r) {
+            ok = false;
+            return;
+        }
+        if (fleetOnlyExpr(r, isHelper))
+            return;
+        if (unwrap(r).kind === ts.SyntaxKind.TrueKeyword) {
+            let c = x;
+            for (let p = x.parent; p && p !== body; c = p, p = p.parent)
+                if (ts.isIfStatement(p) && p.thenStatement === c) {
+                    if (fleetOnlyExpr(p.expression, isHelper))
+                        return;
+                    break;
+                }
+        }
+        ok = false;
+    }, true);
+    return ok && returns > 0;
+}
+/** `if (C) refuse` admits only a fleet caller past it: C is `!F` with F
+ * fleet-only, or a `||` chain one of whose disjuncts is. */
+function refusesNonFleet(c0, isFleetHelper, isFleetLocal) {
+    const c = unwrap(c0);
+    if (ts.isBinaryExpression(c) &&
+        c.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+        return (refusesNonFleet(c.left, isFleetHelper, isFleetLocal) ||
+            refusesNonFleet(c.right, isFleetHelper, isFleetLocal));
+    if (ts.isPrefixUnaryExpression(c) &&
+        c.operator === ts.SyntaxKind.ExclamationToken)
+        return fleetOnlyExpr(c.operand, isFleetHelper, isFleetLocal);
+    return false;
+}
+function isConvexFile(f) {
+    return /(^|\/)convex\//.test(f.rel) && f.rel.endsWith(".ts");
+}
+/** A property access reading a tenant column off anything but the arguments. */
+function tenantReadsIn(n) {
+    const out = [];
+    walk(n, (x) => {
+        if (ts.isPropertyAccessExpression(x) &&
+            TENANT_COLUMNS.has(x.name.text) &&
+            !/^args\b/.test(dotted(x.expression) ?? ""))
+            out.push(x);
+    });
+    return out;
+}
+function ownThrows(n) {
+    let t = false;
+    walk(n, (x) => {
+        if (ts.isThrowStatement(x))
+            t = true;
+    }, true);
+    return t;
+}
+function exitsIn(n) {
+    let t = false;
+    walk(n, (x) => {
+        if (ts.isThrowStatement(x) ||
+            ts.isReturnStatement(x) ||
+            ts.isContinueStatement(x))
+            t = true;
+    }, true);
+    return t;
+}
+/** True when the condition holds for EVERY non-master caller: `!x.isMaster`,
+ * `x.isMaster === false`, or a `||` chain one of whose disjuncts is that. A
+ * conjunction (`a && !x.isMaster`) refuses only some non-masters and is not it. */
+function refusesNonMaster(c0) {
+    const c = unwrap(c0);
+    if (ts.isBinaryExpression(c) &&
+        c.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+        return refusesNonMaster(c.left) || refusesNonMaster(c.right);
+    const isMasterRead = (e) => {
+        const u = unwrap(e);
+        return ((ts.isPropertyAccessExpression(u) && u.name.text === "isMaster") ||
+            (ts.isIdentifier(u) && u.text === "isMaster"));
+    };
+    if (ts.isPrefixUnaryExpression(c) &&
+        c.operator === ts.SyntaxKind.ExclamationToken)
+        return isMasterRead(c.operand);
+    if (ts.isBinaryExpression(c) &&
+        (c.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+            c.operatorToken.kind === ts.SyntaxKind.EqualsEqualsToken) &&
+        c.right.kind === ts.SyntaxKind.FalseKeyword)
+        return isMasterRead(c.left);
+    return false;
+}
+/** `if (!x.isMaster) throw` (or `isMaster === false`) in the function's own body. */
+function ownMasterRefusal(fn) {
+    let hit = false;
+    walk(fn, (x) => {
+        if (!ts.isIfStatement(x))
+            return;
+        if (refusesNonMaster(x.expression) && ownThrows(x.thenStatement))
+            hit = true;
+    }, true);
+    return hit;
+}
+/** Calls made UNCONDITIONALLY: in the function body's own top-level statements. */
+function topLevelCalls(fn) {
+    const out = new Set();
+    const body = fn.body;
+    if (!body || !ts.isBlock(body))
+        return out;
+    for (const st of body.statements) {
+        if (ts.isIfStatement(st))
+            continue;
+        walk(st, (x) => {
+            if (ts.isCallExpression(x)) {
+                const e = unwrap(x.expression);
+                if (ts.isIdentifier(e))
+                    out.add(e.text);
+            }
+        }, true);
+    }
+    return out;
+}
+/** A prefix check of its own: the function takes a namespace-named parameter
+ * and tests it with `.startsWith(…)` (vantage-peers `isNamespaceAllowedForScope`,
+ * convex/lib/auth.ts). Read from the shape, never from the helper's name. */
+function ownPrefixTest(fn) {
+    const params = new Set(fn.parameters
+        .map((p) => (ts.isIdentifier(p.name) ? p.name.text : ""))
+        .filter((n) => /namespace/i.test(n)));
+    if (params.size === 0)
+        return false;
+    let hit = false;
+    walk(fn, (x) => {
+        if (ts.isCallExpression(x) &&
+            ts.isPropertyAccessExpression(x.expression) &&
+            x.expression.name.text === "startsWith" &&
+            ts.isIdentifier(unwrap(x.expression.expression)) &&
+            params.has(unwrap(x.expression.expression).text))
+            hit = true;
+    });
+    return hit;
+}
+/** Every `ctx.db.query("T")` / `ctx.db.insert("T", …)` in the node, plus, given
+ * the handler's `v.id` arguments, every `db.get/patch/replace/delete(args.k)`
+ * whose `k` is a `v.id("T")` — an id argument that is only STORED (a list of
+ * linked ids) reaches no row of T and is not a touch. */
+function touchSites(n, table, argIdTable) {
+    const out = [];
+    walk(n, (x) => {
+        if (!ts.isCallExpression(x) || !x.arguments[0])
+            return;
+        const a0 = x.arguments[0];
+        const c = calleeName(x);
+        if ((c === "query" || c === "insert") &&
+            ts.isStringLiteralLike(a0) &&
+            a0.text === table)
+            out.push(x);
+        else if (argIdTable &&
+            /\bdb\.(get|patch|replace|delete)$/.test(dotted(x.expression) ?? "")) {
+            const m = /^args\.(\w+)$/.exec(dotted(a0) ?? "");
+            if (m && argIdTable.get(m[1]) === table)
+                out.push(x);
+        }
+    });
+    return out;
+}
+const ownTouches = (n, table) => touchSites(n, table).length > 0;
+/** The site runs only on the TRUE side of a fleet-only condition, up to the
+ * handler: `isMaster ? <site> : []`, `if (isMaster) { <site> }`, `isMaster && <site>`. */
+function fleetGated(site, stop, isFleetHelper) {
+    let child = site;
+    for (let x = site.parent; x && x !== stop; child = x, x = x.parent) {
+        const c = ts.isIfStatement(x)
+            ? x.thenStatement === child
+                ? x.expression
+                : undefined
+            : ts.isConditionalExpression(x)
+                ? x.whenTrue === child
+                    ? x.condition
+                    : undefined
+                : ts.isBinaryExpression(x) &&
+                    x.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+                    x.right === child
+                    ? x.left
+                    : undefined;
+        if (c && fleetOnlyExpr(c, isFleetHelper))
+            return true;
+    }
+    return false;
+}
+/** Does an argument carry a NAMESPACE VALUE rather than a constant? It reads a
+ * namespace-named field (`args.namespace`, `row.namespace`, `e.namespace`), or
+ * is a local / destructured binding / callback parameter that does. A literal,
+ * a template with no substitution, or a local initialised to one, does not:
+ * a prefix test on a constant bounds nothing the caller reads or writes. */
+function derivesNamespace(e0, scope, depth = 0) {
+    if (depth > 4)
+        return false;
+    const e = unwrap(e0);
+    if (ts.isPropertyAccessExpression(e))
+        return /namespace/i.test(e.name.text);
+    if (ts.isElementAccessExpression(e))
+        return (ts.isStringLiteralLike(e.argumentExpression) &&
+            /namespace/i.test(e.argumentExpression.text));
+    if (!ts.isIdentifier(e))
+        return false;
+    let found;
+    walk(scope, (x) => {
+        if (found !== undefined)
+            return;
+        if (ts.isVariableDeclaration(x) &&
+            ts.isIdentifier(x.name) &&
+            x.name.text === e.text)
+            found = x.initializer
+                ? derivesNamespace(x.initializer, scope, depth + 1)
+                : false;
+        else if (ts.isBindingElement(x) &&
+            ts.isIdentifier(x.name) &&
+            x.name.text === e.text) {
+            const key = x.propertyName && ts.isIdentifier(x.propertyName)
+                ? x.propertyName.text
+                : x.name.text;
+            found = /namespace/i.test(key);
+        }
+        else if (ts.isParameter(x) &&
+            ts.isIdentifier(x.name) &&
+            x.name.text === e.text)
+            found = /namespace/i.test(x.name.text);
+    });
+    return found ?? false;
+}
+/** The prefix checkers a handler calls ON A NAMESPACE VALUE: the argument at
+ * the checker's own namespace-named parameter derives from a namespace field
+ * (ElPi-Corp #228: "a `namespace` checked against the caller's allowed
+ * prefixes"; Argus, backend-doctor #49 issuecomment-6022240186 — a call on a
+ * constant used to pass). A checker with no namespace-named parameter (a
+ * helper that only closes over one) is not bound at its call and counts for
+ * nothing here. */
+function boundPrefixChecks(handler, prefixCheckers, fns) {
+    const out = [];
+    walk(handler, (x) => {
+        if (!ts.isCallExpression(x))
+            return;
+        const e = unwrap(x.expression);
+        if (!ts.isIdentifier(e) || !prefixCheckers.has(e.text))
+            return;
+        const def = (fns.get(e.text) ?? []).find((d) => d.fn.parameters.some((q) => ts.isIdentifier(q.name) && /namespace/i.test(q.name.text)));
+        if (!def)
+            return;
+        const i = def.fn.parameters.findIndex((q) => ts.isIdentifier(q.name) && /namespace/i.test(q.name.text));
+        const a = x.arguments[i];
+        if (a && derivesNamespace(a, handler) && !out.includes(e.text))
+            out.push(e.text);
+    });
+    return out;
+}
+function namespaceDecisions(parsed, schema, fns, fleetRefusal, fleetOnly) {
+    const out = new Map();
+    const tables = [...schema.values()].filter((t) => t.namespace !== "none" && t.tenant !== "required");
+    if (tables.length === 0)
+        return out;
+    const prefixCheckers = closeOverCalls(fns, (d) => ownPrefixTest(d.fn));
+    const doors = parsed.flatMap((p) => registrations(p).filter((r) => r.builder === "query" ||
+        r.builder === "mutation" ||
+        r.builder === "action"));
+    for (const t of tables) {
+        const touchers = closeOverCalls(fns, (d) => ownTouches(d.fn, t.name));
+        const checked = [];
+        const unchecked = [];
+        for (const r of doors) {
+            const calls = calledNames(r.handler);
+            const own = touchSites(r.handler, t.name, r.argIdTable);
+            const viaHelper = [...calls].some((c) => touchers.has(c));
+            if (own.length === 0 && !viaHelper)
+                continue;
+            const label = `${r.rel.replace(/^.*convex\//, "")}:${r.name}`;
+            const checker = boundPrefixChecks(r.handler, prefixCheckers, fns)[0] ??
+                [...calls].find((c) => fleetRefusal.has(c));
+            if (checker || ownMasterRefusal(r.handler))
+                checked.push(`${label} (${checker ?? "master-only"})`);
+            else if (!viaHelper &&
+                own.every((x) => fleetGated(x, r.handler, (n) => fleetOnly.has(n))))
+                checked.push(`${label} (master-gated)`);
+            else
+                unchecked.push(label);
+        }
+        const list = (xs) => `${xs.slice(0, 3).join(", ")}${xs.length > 3 ? `, … ${xs.length} in all` : ""}`;
+        if (checked.length === 0 && unchecked.length === 0)
+            out.set(t.name, {
+                verdict: "undecided",
+                why: "no public query/mutation/action reads or writes it, so no prefix check can be read",
+            });
+        else if (unchecked.length === 0)
+            out.set(t.name, {
+                verdict: "checked",
+                why: `every public door runs a prefix check: ${list(checked)}`,
+            });
+        else if (checked.length === 0)
+            out.set(t.name, {
+                verdict: "unchecked",
+                why: `no public door runs a prefix check: ${list(unchecked)}`,
+            });
+        else
+            out.set(t.name, {
+                verdict: "undecided",
+                why: `prefix-checked at ${list(checked)} but not at ${list(unchecked)}`,
+            });
+    }
+    return out;
+}
+/** The schema as R-52 reads it: a table whose namespace is prefix-checked
+ * carries that namespace as a tenant column. */
+function effectiveSchema(raw, ns) {
+    const out = new Map();
+    for (const [k, t] of raw) {
+        if (ns.get(k)?.verdict !== "checked") {
+            out.set(k, t);
+            continue;
+        }
+        const tenant = t.namespace === "required"
+            ? "required"
+            : t.tenant === "none"
+                ? "optional"
+                : t.tenant;
+        out.set(k, { ...t, tenant });
+    }
+    return out;
+}
+export function r52Facts(files) {
+    const parsed = files
+        .filter((f) => isConvexFile(f) && isJudgeable(f))
+        .map(parseFile);
+    const schemaP = parsed.find((p) => /(^|\/)convex\/schema\.ts$/.test(p.rel));
+    const rawSchema = schemaP ? readSchema(schemaP) : undefined;
+    const fns = indexFunctions(parsed);
+    const readsTenant = closeOverCalls(fns, (d) => tenantReadsIn(d.fn).length > 0);
+    const refusing = closeOverCalls(fns, (d) => ownThrows(d.fn));
+    const fleetOnly = new Set();
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const [n, ds] of fns) {
+            if (fleetOnly.has(n))
+                continue;
+            if (ds.length === 1 && fleetOnlyFunction(ds[0].fn, fleetOnly)) {
+                fleetOnly.add(n);
+                grew = true;
+            }
+        }
+    }
+    const fleetRefusal = new Set();
+    for (const [n, ds] of fns)
+        if (ds.some((d) => ownMasterRefusal(d.fn)))
+            fleetRefusal.add(n);
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const [n, ds] of fns) {
+            if (fleetRefusal.has(n))
+                continue;
+            if (ds.some((d) => [...topLevelCalls(d.fn)].some((c) => fleetRefusal.has(c)))) {
+                fleetRefusal.add(n);
+                grew = true;
+            }
+        }
+    }
+    const namespace = rawSchema
+        ? namespaceDecisions(parsed, rawSchema, fns, fleetRefusal, fleetOnly)
+        : new Map();
+    const schema = rawSchema ? effectiveSchema(rawSchema, namespace) : undefined;
+    // a helper whose body reads exactly one table returns a row of that table.
+    const singleTable = new Map();
+    for (const [n, ds] of fns) {
+        if (ds.length !== 1)
+            continue;
+        const tables = new Set();
+        walk(ds[0].fn, (x) => {
+            if (ts.isCallExpression(x) &&
+                calleeName(x) === "query" &&
+                x.arguments[0] &&
+                ts.isStringLiteralLike(x.arguments[0]))
+                tables.add(x.arguments[0].text);
+        });
+        if (tables.size === 1)
+            singleTable.set(n, [...tables][0]);
+    }
+    const callerChosen = new Map();
+    const mark = (t, f) => {
+        const s = callerChosen.get(t) ?? new Set();
+        s.add(f);
+        callerChosen.set(t, s);
+    };
+    for (const p of parsed) {
+        const internal = registrations(p)
+            .filter((r) => r.builder.startsWith("internal"))
+            .map((r) => r.handler);
+        const inInternal = (n) => {
+            for (let x = n; x; x = x.parent)
+                if (internal.includes(x))
+                    return true;
+            return false;
+        };
+        const argIds = new Map();
+        for (const r of registrations(p))
+            for (const [k, t] of r.argIdTable)
+                argIds.set(k, t);
+        walk(p.sf, (x) => {
+            if (!ts.isCallExpression(x) || inInternal(x))
+                return;
+            const callee = dotted(x.expression) ?? "";
+            let table;
+            let obj;
+            if (/\.db\.insert$/.test(callee) &&
+                x.arguments[0] &&
+                ts.isStringLiteralLike(x.arguments[0])) {
+                table = x.arguments[0].text;
+                obj = x.arguments[1];
+            }
+            else if (/\.db\.(patch|replace)$/.test(callee) && x.arguments[0]) {
+                const sel = dotted(x.arguments[0]) ?? "";
+                const m = /^args\.(\w+)$/.exec(sel);
+                if (m)
+                    table = argIds.get(m[1]);
+                obj = x.arguments[1];
+            }
+            if (!table || !obj)
+                return;
+            const o = unwrap(obj);
+            if (!ts.isObjectLiteralExpression(o))
+                return;
+            const explicit = new Set();
+            for (const prop of o.properties) {
+                if (ts.isPropertyAssignment(prop) ||
+                    ts.isShorthandPropertyAssignment(prop)) {
+                    const k = ts.isIdentifier(prop.name) ? prop.name.text : undefined;
+                    if (!k)
+                        continue;
+                    explicit.add(k);
+                    const valText = ts.isPropertyAssignment(prop)
+                        ? prop.initializer.getText()
+                        : k;
+                    if (/\bargs\b|\b\w*Args\b/.test(valText))
+                        mark(table, k);
+                }
+            }
+            for (const prop of o.properties) {
+                if (!ts.isSpreadAssignment(prop))
+                    continue;
+                const t = prop.expression.getText();
+                if (/^(?:args|\w*Args|rest)$/.test(t)) {
+                    for (const f of schema?.get(table)?.fields ?? [])
+                        if (!explicit.has(f))
+                            mark(table, f);
+                }
+            }
+        });
+    }
+    return {
+        parsed,
+        schema,
+        schemaRel: schemaP?.rel,
+        callerChosen,
+        fns,
+        readsTenant,
+        refusing,
+        fleetOnly,
+        normalizers: new Set([...fns]
+            .filter(([, ds]) => ds.some((d) => /\.normalizeId\(/.test(d.fn.getText())))
+            .map(([n]) => n)),
+        fleetRefusal,
+        singleTable,
+        namespace,
+    };
+}
+// ---- per-handler evaluation -----------------------------------------------
+/** The node a declaration is visible in: its block, loop, or function. */
+function scopeOf(n) {
+    for (let x = n.parent; x; x = x.parent)
+        if (ts.isBlock(x) ||
+            ts.isForStatement(x) ||
+            ts.isForOfStatement(x) ||
+            ts.isForInStatement(x) ||
+            ts.isArrowFunction(x) ||
+            ts.isFunctionExpression(x) ||
+            ts.isFunctionDeclaration(x) ||
+            ts.isMethodDeclaration(x) ||
+            ts.isSourceFile(x))
+            return x;
+    return n.getSourceFile();
+}
+/** Bindings keyed by name AND the scope they are declared in: a reference
+ * resolves to the innermost declaration whose scope contains it, so two
+ * `const task` in sibling blocks never share a provenance. */
+class ScopedEnv {
+    m = new Map();
+    entry(name, at) {
+        const xs = this.m.get(name);
+        if (!xs || xs.length === 0)
+            return undefined;
+        if (!at)
+            return xs[xs.length - 1];
+        let best;
+        for (const x of xs)
+            if (x.scope.pos <= at.pos && at.end <= x.scope.end)
+                if (!best ||
+                    x.scope.end - x.scope.pos <= best.scope.end - best.scope.pos)
+                    best = x;
+        return best;
+    }
+    get(name, at) {
+        return this.entry(name, at)?.val;
+    }
+    set(name, val, scope) {
+        const xs = this.m.get(name) ?? [];
+        const i = xs.findIndex((x) => x.scope === scope);
+        if (i >= 0)
+            xs[i] = { scope, val };
+        else
+            xs.push({ scope, val });
+        this.m.set(name, xs);
+    }
+    remove(name, scope) {
+        const xs = this.m.get(name);
+        if (xs)
+            this.m.set(name, xs.filter((x) => x.scope !== scope));
+    }
+}
+class HandlerWalk {
+    reg;
+    facts;
+    env = new ScopedEnv();
+    declared = new Set();
+    constructor(reg, facts) {
+        this.reg = reg;
+        this.facts = facts;
+    }
+    selectedBy(v, table, n) {
+        if (v.choosable && table !== undefined)
+            return mergeVias(v.vias, [
+                { table, reason: v.choosable, line: lineOf(n) },
+            ]);
+        return v.vias;
+    }
+    /** Root of a `ctx.db.query("T")…` chain, with every call in the chain. */
+    queryChain(c) {
+        const calls = [];
+        let x = c;
+        for (;;) {
+            const u = unwrap(x);
+            if (!ts.isCallExpression(u))
+                return undefined;
+            calls.push(u);
+            const callee = unwrap(u.expression);
+            if (!ts.isPropertyAccessExpression(callee))
+                return undefined;
+            if (callee.name.text === "query" &&
+                /\bdb$/.test(dotted(callee.expression) ?? "") &&
+                u.arguments[0] &&
+                ts.isStringLiteralLike(u.arguments[0]))
+                return { table: u.arguments[0].text, calls };
+            x = callee.expression;
+        }
+    }
+    evalCb(cb, param) {
+        let out = SAFE;
+        const f = cb;
+        const names = new Set();
+        for (const p of f.parameters ?? [])
+            if (ts.isIdentifier(p.name))
+                names.add(p.name.text);
+        for (const n of names)
+            this.env.set(n, param, cb);
+        walk(f.body, (x) => {
+            if (ts.isBinaryExpression(x)) {
+                for (const side of [x.left, x.right]) {
+                    const root = dotted(side)?.split(".")[0];
+                    if (root !== undefined && names.has(root))
+                        continue;
+                    out = merge(out, this.eval(side));
+                }
+            }
+        });
+        for (const n of names)
+            this.env.remove(n, cb);
+        return out;
+    }
+    eval(e0) {
+        const e = unwrap(e0);
+        if (ts.isStringLiteralLike(e) ||
+            ts.isNumericLiteral(e) ||
+            ts.isRegularExpressionLiteral(e) ||
+            e.kind === ts.SyntaxKind.TrueKeyword ||
+            e.kind === ts.SyntaxKind.FalseKeyword ||
+            e.kind === ts.SyntaxKind.NullKeyword ||
+            ts.isArrowFunction(e) ||
+            ts.isFunctionExpression(e))
+            return SAFE;
+        if (ts.isIdentifier(e)) {
+            if (e.text === "args")
+                return {
+                    kind: "value",
+                    choosable: "the handler's arguments",
+                    vias: [],
+                };
+            const v = this.env.get(e.text, e);
+            if (v)
+                return v;
+            if (this.declared.has(e.text))
+                return {
+                    kind: "value",
+                    vias: [],
+                    unresolved: `local \`${e.text}\` has no provenance the walk can read`,
+                };
+            return SAFE;
+        }
+        if (ts.isPropertyAccessExpression(e)) {
+            const name = e.name.text;
+            const head = unwrap(e.expression);
+            if (ts.isIdentifier(head) && head.text === "args") {
+                const t = this.reg.argIdTable.get(name);
+                return {
+                    kind: t ? "id" : "value",
+                    table: t,
+                    choosable: `argument args.${name}`,
+                    vias: [],
+                };
+            }
+            const obj = this.eval(e.expression);
+            if (obj.kind === "row" && obj.table !== undefined) {
+                if (name === "_id")
+                    return { ...obj, kind: "id", gate: undefined };
+                const st = this.facts.schema?.get(obj.table);
+                // `rows.length` and other non-column reads are aggregates, not a
+                // value read off a row: no attribution travels with them.
+                if (st !== undefined &&
+                    !st.fields.includes(name) &&
+                    name !== "_creationTime")
+                    return { kind: "value", choosable: obj.choosable, vias: [] };
+                const chosen = this.facts.callerChosen.get(obj.table)?.has(name);
+                const ref = st?.idRef.get(name);
+                return {
+                    kind: ref ? "id" : "value",
+                    table: ref,
+                    choosable: chosen
+                        ? `stored field ${obj.table}.${name}, which a public write sets from its arguments`
+                        : obj.choosable,
+                    vias: obj.vias,
+                    unresolved: obj.unresolved,
+                };
+            }
+            // a field of an argument whose validator names exactly one table
+            // (`args.relations[i].targetId: v.id("memories")`) is still that id.
+            if (obj.kind === "id" &&
+                obj.table !== undefined &&
+                obj.choosable?.startsWith("argument args."))
+                return { ...obj, gate: undefined };
+            return { ...obj, kind: "value", table: undefined, gate: undefined };
+        }
+        if (ts.isElementAccessExpression(e)) {
+            const recv = this.eval(e.expression);
+            const m = merge(recv, this.eval(e.argumentExpression));
+            if (recv.table !== undefined)
+                return {
+                    ...m,
+                    kind: recv.kind,
+                    table: recv.table,
+                    tenantChecked: recv.tenantChecked,
+                };
+            return m;
+        }
+        if (ts.isCallExpression(e))
+            return this.evalCall(e);
+        if (ts.isBinaryExpression(e) &&
+            (e.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
+                e.operatorToken.kind === ts.SyntaxKind.BarBarToken)) {
+            const a = this.eval(e.left);
+            const b = this.eval(e.right);
+            const m = merge(a, b);
+            if (a.table !== undefined &&
+                (b.table === undefined || b.table === a.table))
+                return {
+                    ...m,
+                    kind: a.kind,
+                    table: a.table,
+                    tenantChecked: a.tenantChecked,
+                };
+            return m;
+        }
+        if (ts.isConditionalExpression(e)) {
+            const a = this.eval(e.whenTrue);
+            const b = this.eval(e.whenFalse);
+            const m = merge(merge(a, b), this.eval(e.condition));
+            if (a.table !== undefined && a.table === b.table && a.kind === b.kind)
+                return { ...m, kind: a.kind, table: a.table };
+            return m;
+        }
+        let out = SAFE;
+        ts.forEachChild(e, (c) => {
+            if (ts.isExpression(c))
+                out = merge(out, this.eval(c));
+            else if (ts.isPropertyAssignment(c) ||
+                ts.isShorthandPropertyAssignment(c) ||
+                ts.isSpreadAssignment(c) ||
+                ts.isSpreadElement(c) ||
+                ts.isTemplateSpan(c))
+                ts.forEachChild(c, (cc) => {
+                    if (ts.isExpression(cc))
+                        out = merge(out, this.eval(cc));
+                });
+        });
+        return out;
+    }
+    evalCall(c) {
+        const callee = dotted(c.expression) ?? "";
+        if (/\bdb\.get$/.test(callee) && c.arguments[0]) {
+            const s = this.eval(c.arguments[0]);
+            return {
+                kind: "row",
+                table: s.table,
+                choosable: s.choosable,
+                vias: this.selectedBy(s, s.table, c),
+                unresolved: s.unresolved,
+            };
+        }
+        // ctx.db.normalizeId("T", x), or a helper that wraps it: an id of table T.
+        const lit = c.arguments.find((a) => ts.isStringLiteralLike(a) && this.facts.schema?.has(a.text) === true);
+        const fnName = calleeName(c);
+        if (lit &&
+            fnName !== undefined &&
+            (fnName === "normalizeId" || this.facts.normalizers.has(fnName))) {
+            let a = SAFE;
+            for (const arg of c.arguments)
+                if (arg !== lit)
+                    a = merge(a, this.eval(arg));
+            return { ...a, kind: "id", table: lit.text, gate: undefined };
+        }
+        const q = this.queryChain(c);
+        if (q) {
+            let sel = SAFE;
+            for (const call of q.calls)
+                for (const a of call.arguments)
+                    walk(a, (x) => {
+                        if (ts.isCallExpression(x) &&
+                            calleeName(x) === "eq" &&
+                            x.arguments.length === 2)
+                            sel = merge(sel, this.eval(x.arguments[1]));
+                    });
+            return {
+                kind: "row",
+                table: q.table,
+                choosable: sel.choosable,
+                vias: this.selectedBy(sel, q.table, c),
+                unresolved: sel.unresolved,
+            };
+        }
+        const fnExpr = unwrap(c.expression);
+        if (ts.isPropertyAccessExpression(fnExpr) &&
+            ITERATORS.has(fnExpr.name.text)) {
+            const recv = this.eval(fnExpr.expression);
+            const cb = c.arguments[0];
+            const elem = { ...recv, gate: undefined };
+            if (fnExpr.name.text === "map" &&
+                cb &&
+                ts.isArrowFunction(cb) &&
+                !ts.isBlock(cb.body)) {
+                const p0 = cb.parameters[0];
+                if (p0 && ts.isIdentifier(p0.name))
+                    this.env.set(p0.name.text, elem, cb);
+                const out = this.eval(cb.body);
+                if (p0 && ts.isIdentifier(p0.name))
+                    this.env.remove(p0.name.text, cb);
+                return {
+                    ...out,
+                    choosable: out.choosable ?? recv.choosable,
+                    vias: mergeVias(out.vias, recv.vias),
+                };
+            }
+            const byCb = cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))
+                ? this.evalCb(cb, elem)
+                : SAFE;
+            if ((fnExpr.name.text === "find" ||
+                fnExpr.name.text === "filter" ||
+                fnExpr.name.text === "findLast") &&
+                recv.table !== undefined) {
+                const choosable = recv.choosable ?? byCb.choosable;
+                const v = {
+                    kind: "row",
+                    table: recv.table,
+                    choosable,
+                    vias: mergeVias(recv.vias, byCb.vias),
+                    unresolved: recv.unresolved ?? byCb.unresolved,
+                };
+                return {
+                    ...v,
+                    vias: this.selectedBy({ ...v, vias: v.vias }, recv.table, c),
+                };
+            }
+            return merge(recv, byCb);
+        }
+        if (ts.isIdentifier(fnExpr) && this.facts.fns.has(fnExpr.text)) {
+            const name = fnExpr.text;
+            let a = SAFE;
+            const tables = new Set();
+            for (const arg of c.arguments) {
+                if (ts.isIdentifier(arg) && arg.text === "ctx")
+                    continue;
+                const v = this.eval(arg);
+                if (v.table)
+                    tables.add(v.table);
+                a = merge(a, v);
+            }
+            const table = this.facts.singleTable.get(name);
+            const gate = this.facts.readsTenant.has(name)
+                ? { tables, fleet: this.facts.fleetOnly.has(name) }
+                : undefined;
+            const tenantChecked = this.facts.readsTenant.has(name) ? name : undefined;
+            if (table !== undefined)
+                return {
+                    kind: "row",
+                    table,
+                    choosable: a.choosable,
+                    // a helper that reads the tenant of what it returns does not
+                    // hand back a row the caller chose across tenants.
+                    vias: tenantChecked ? a.vias : this.selectedBy(a, table, c),
+                    unresolved: a.unresolved,
+                    gate,
+                    tenantChecked,
+                };
+            return { ...a, gate, tenantChecked };
+        }
+        if (ts.isPropertyAccessExpression(fnExpr) &&
+            PRESERVING.has(fnExpr.name.text)) {
+            const recv = this.eval(fnExpr.expression);
+            let a = SAFE;
+            for (const arg of c.arguments)
+                a = merge(a, this.eval(arg));
+            return { ...recv, choosable: recv.choosable ?? a.choosable };
+        }
+        let out = SAFE;
+        if (ts.isPropertyAccessExpression(fnExpr))
+            out = merge(out, this.eval(fnExpr.expression));
+        for (const arg of c.arguments)
+            out = merge(out, this.eval(arg));
+        return out;
+    }
+    bind(name, v, scope) {
+        if (ts.isIdentifier(name)) {
+            const prev = this.env.entry(name.text, name);
+            const same = prev && prev.scope === scope ? prev.val : undefined;
+            this.env.set(name.text, same
+                ? {
+                    ...merge(same, v),
+                    kind: v.table !== undefined ? v.kind : same.kind,
+                    table: v.table ?? same.table,
+                    tenantChecked: v.tenantChecked ?? same.tenantChecked,
+                }
+                : v, scope);
+            return;
+        }
+        for (const el of name.elements) {
+            if (ts.isOmittedExpression(el))
+                continue;
+            if (ts.isObjectBindingPattern(name) &&
+                ts.isIdentifier(el.name) &&
+                v.choosable === "the handler's arguments") {
+                const key = el.propertyName && ts.isIdentifier(el.propertyName)
+                    ? el.propertyName.text
+                    : el.name.text;
+                const t = this.reg.argIdTable.get(key);
+                this.env.set(el.name.text, {
+                    kind: t ? "id" : "value",
+                    table: t,
+                    choosable: `argument args.${key}`,
+                    vias: [],
+                }, scope);
+                continue;
+            }
+            this.bind(el.name, v, scope);
+        }
+    }
+    /** Pass 1: declared names; pass 2: bind every declaration in source order. */
+    build() {
+        const body = this.reg.handler.body;
+        if (!body)
+            return;
+        walk(body, (x) => {
+            if (ts.isVariableDeclaration(x) || ts.isParameter(x)) {
+                const collect = (n) => {
+                    if (ts.isIdentifier(n))
+                        this.declared.add(n.text);
+                    else
+                        for (const el of n.elements)
+                            if (!ts.isOmittedExpression(el))
+                                collect(el.name);
+                };
+                collect(x.name);
+            }
+        });
+        walk(body, (x) => {
+            if (ts.isVariableDeclaration(x) && x.initializer) {
+                const forOf = x.parent?.parent;
+                if (forOf &&
+                    ts.isForOfStatement(forOf) &&
+                    forOf.initializer === x.parent)
+                    return;
+                this.bind(x.name, this.eval(x.initializer), scopeOf(x));
+            }
+            if (ts.isForOfStatement(x) &&
+                ts.isVariableDeclarationList(x.initializer)) {
+                const v = this.eval(x.expression);
+                for (const d of x.initializer.declarations)
+                    this.bind(d.name, v, x);
+            }
+            if (ts.isCallExpression(x) &&
+                ts.isPropertyAccessExpression(unwrap(x.expression)) &&
+                ITERATORS.has(unwrap(x.expression).name.text)) {
+                const recv = this.eval(unwrap(x.expression).expression);
+                const cb = x.arguments[0];
+                if (cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))) {
+                    const p0 = cb.parameters[0];
+                    if (p0)
+                        this.bind(p0.name, { ...recv, gate: undefined }, cb);
+                }
+            }
+            // `rows.push(row)`: the array holds that row; a push gated by a
+            // condition reading the row's tenant makes the array tenant-checked.
+            if (ts.isCallExpression(x) &&
+                ts.isPropertyAccessExpression(x.expression) &&
+                x.expression.name.text === "push" &&
+                ts.isIdentifier(x.expression.expression) &&
+                x.arguments[0]) {
+                const arr = x.expression.expression;
+                const target = this.env.entry(arr.text, arr);
+                const pv = this.eval(x.arguments[0]);
+                if (target && pv.table !== undefined) {
+                    const gate = enclosingConditions(x, this.reg.handler).find((c) => tenantTablesRead(this, c).has(pv.table));
+                    this.env.set(arr.text, {
+                        ...merge(target.val, pv),
+                        kind: pv.kind,
+                        table: pv.table,
+                        tenantChecked: gate
+                            ? `the push gated by \`${gate.getText().slice(0, 60)}\` (line ${lineOf(gate)})`
+                            : target.val.tenantChecked,
+                    }, target.scope);
+                }
+            }
+            if (ts.isBinaryExpression(x) &&
+                x.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                ts.isIdentifier(x.left)) {
+                const at = this.env.entry(x.left.text, x.left);
+                if (at)
+                    this.bind(x.left, this.eval(x.right), at.scope);
+            }
+        });
+    }
+}
+// ---- guards ---------------------------------------------------------------
+/** The tables whose server-stamped tenant a condition reads. */
+function tenantTablesRead(w, cond) {
+    const out = new Set();
+    for (const pa of tenantReadsIn(cond)) {
+        const v = w.eval(pa.expression);
+        if (v.kind === "row" && v.table)
+            out.add(v.table);
+    }
+    walk(cond, (x) => {
+        const g = ts.isIdentifier(x)
+            ? w.env.get(x.text, x)?.gate
+            : ts.isCallExpression(x)
+                ? w.eval(x).gate
+                : undefined;
+        for (const t of g?.tables ?? [])
+            out.add(t);
+    });
+    return out;
+}
+/** Conditions that gate `node` (enclosing if/ternary/&&) up to the handler. */
+function enclosingConditions(node, stop) {
+    const out = [];
+    let child = node;
+    for (let x = node.parent; x && x !== stop; child = x, x = x.parent) {
+        if (ts.isIfStatement(x) && child !== x.expression)
+            out.push(x.expression);
+        if (ts.isConditionalExpression(x) && child !== x.condition)
+            out.push(x.condition);
+        if (ts.isBinaryExpression(x) &&
+            x.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+            child === x.right)
+            out.push(x.left);
+    }
+    return out;
+}
+/** Statements that precede `node` in each enclosing block, up to the handler. */
+function precedingStatements(node, stop) {
+    const out = [];
+    let child = node;
+    for (let x = node.parent; x && x !== stop.parent; child = x, x = x.parent) {
+        if (ts.isBlock(x))
+            for (const st of x.statements) {
+                if (st === child)
+                    break;
+                out.push(st);
+            }
+    }
+    return out;
+}
+function guarded(w, node, target, kind) {
+    const stop = w.reg.handler;
+    const isHelper = (n) => w.facts.fleetOnly.has(n);
+    const isLocal = (n) => w.env.get(n, node)?.gate?.fleet === true;
+    const gates = (c) => kind === "none"
+        ? fleetOnlyExpr(c, isHelper, isLocal)
+        : tenantTablesRead(w, c).has(target);
+    const refuses = (c) => kind === "none"
+        ? refusesNonFleet(c, isHelper, isLocal)
+        : tenantTablesRead(w, c).has(target);
+    for (const c of enclosingConditions(node, stop)) {
+        if (gates(c))
+            return `gated by \`${c.getText().slice(0, 80)}\` (line ${lineOf(c)})`;
+    }
+    for (const st of precedingStatements(node, stop)) {
+        if (ts.isIfStatement(st) &&
+            exitsIn(st.thenStatement) &&
+            refuses(st.expression))
+            return `early exit on \`${st.expression.getText().slice(0, 80)}\` (line ${lineOf(st)})`;
+        let hit;
+        walk(st, (x) => {
+            if (hit || !ts.isCallExpression(x))
+                return;
+            const f = unwrap(x.expression);
+            if (!ts.isIdentifier(f))
+                return;
+            const n = f.text;
+            if (w.facts.fleetRefusal.has(n)) {
+                hit = `master-only refusal \`${n}\` (line ${lineOf(x)})`;
+                return;
+            }
+            if (kind === "optional" &&
+                w.facts.refusing.has(n) &&
+                w.facts.readsTenant.has(n) &&
+                x.arguments.some((a) => {
+                    const v = w.eval(a);
+                    return v.kind === "row" && v.table === target;
+                }))
+                hit = `refusing tenant check \`${n}\` handed the ${target} row (line ${lineOf(x)})`;
+        }, true);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+export function scanR52(files) {
+    return scanR52Detailed(files).scan;
+}
+const WRITE_RE = /\bdb\.(patch|replace|delete|insert)$/;
+const EFFECT_RE = /\b(scheduler\.(runAfter|runAt)|runMutation|runAction)$/;
+export function scanR52Detailed(files) {
+    const scan = emptyScan();
+    const facts = r52Facts(files);
+    if (facts.schema === undefined || facts.schema.size === 0) {
+        scan.cnj.push({
+            rel: facts.schemaRel ?? "convex/schema.ts",
+            n: 0,
+            note: "schema: convex/schema.ts absent or no defineTable read — the tenant-column test cannot be made",
+        });
+        return { scan, untenanted: [], schemaRel: facts.schemaRel };
+    }
+    const untenanted = [...facts.schema.values()]
+        .filter((t) => t.tenant !== "required")
+        .map((t) => t.name);
+    for (const p of facts.parsed) {
+        for (const reg of registrations(p)) {
+            if (reg.builder !== "mutation" && reg.builder !== "action")
+                continue;
+            const gate = possessionGate(reg);
+            const w = new HandlerWalk(reg, facts);
+            w.build();
+            const body = reg.handler.body;
+            if (!body)
+                continue;
+            walk(body, (x) => {
+                if (!ts.isCallExpression(x))
+                    return;
+                const callee = dotted(x.expression) ?? "";
+                const wm = WRITE_RE.exec(callee);
+                const em = EFFECT_RE.exec(callee);
+                if (!wm && !em)
+                    return;
+                const n = lineOf(x);
+                const site = (note) => ({
+                    rel: p.rel,
+                    n,
+                    note: `${reg.name}: ${note}`,
+                });
+                const conds = enclosingConditions(x, reg.handler);
+                // the targets this write reaches, with the provenance of each.
+                const targets = [];
+                if (wm && wm[1] !== "insert") {
+                    const sel = x.arguments[0];
+                    if (!sel)
+                        return;
+                    const v = w.eval(sel);
+                    if (v.table === undefined) {
+                        if (v.unresolved)
+                            scan.cnj.push(site(`${wm[1]} — selector \`${sel.getText()}\`: ${v.unresolved}`));
+                        else if (v.choosable)
+                            scan.cnj.push(site(`${wm[1]} — selector \`${sel.getText()}\` is caller-choosable (${v.choosable}) but its table cannot be resolved`));
+                        return;
+                    }
+                    if (gate && dotted(sel) === `${gate.rowVar}._id`) {
+                        scan.conform.push(site(`${wm[1]} ${gate.table} — possession-gated: the row is selected by the hash of a presented secret through a unique index on ${gate.table}.${gate.field} (line ${gate.rowLine}), and the handler writes only that row`));
+                        return;
+                    }
+                    if (!v.choosable) {
+                        scan.conform.push(site(`${wm[1]} ${v.table} — selector \`${sel.getText()}\` is not caller-choosable`));
+                        return;
+                    }
+                    if (v.tenantChecked &&
+                        facts.schema?.get(v.table)?.tenant === "optional") {
+                        scan.conform.push(site(`${wm[1]} ${v.table} — selected through ${/^the push/.test(v.tenantChecked) ? v.tenantChecked : `${v.tenantChecked}(), whose body reads the tenant of the ${v.table} rows it returns`}`));
+                        return;
+                    }
+                    targets.push({
+                        table: v.table,
+                        reason: v.choosable,
+                        what: `${wm[1]} ${v.table}`,
+                    });
+                }
+                else {
+                    // insert / scheduled effect: attributed to a row it reads. An
+                    // insert into a table that carries a tenant value, or whose
+                    // literal stamps one, belongs to that tenant (R-6 governs the
+                    // stamp) — it is not a row left to every tenant.
+                    if (wm) {
+                        const t0 = x.arguments[0];
+                        const intoName = t0 && ts.isStringLiteralLike(t0) ? t0.text : undefined;
+                        const into = intoName !== undefined
+                            ? facts.schema?.get(intoName)?.tenant
+                            : undefined;
+                        // a `namespace` stamps a tenant only where that table's
+                        // namespace is prefix-checked (standard 2825122 R-52).
+                        const nsOf = intoName !== undefined
+                            ? facts.namespace.get(intoName)
+                            : undefined;
+                        const stampCol = (k) => TENANT_COLUMNS.has(k) ||
+                            (k === NAMESPACE_COLUMN && nsOf?.verdict === "checked");
+                        let nsUndecided = false;
+                        const lit = x.arguments[1] && unwrap(x.arguments[1]);
+                        const stamps = lit !== undefined &&
+                            ts.isObjectLiteralExpression(lit) &&
+                            lit.properties.some((pr) => {
+                                const col = (k) => {
+                                    if (k === NAMESPACE_COLUMN && nsOf?.verdict === "undecided")
+                                        nsUndecided = true;
+                                    return stampCol(k);
+                                };
+                                if ((ts.isPropertyAssignment(pr) ||
+                                    ts.isShorthandPropertyAssignment(pr)) &&
+                                    ts.isIdentifier(pr.name))
+                                    return col(pr.name.text);
+                                // `...(org ? { orgId: org } : {})` stamps when set.
+                                let hit = false;
+                                if (ts.isSpreadAssignment(pr))
+                                    walk(pr.expression, (y) => {
+                                        if ((ts.isPropertyAssignment(y) ||
+                                            ts.isShorthandPropertyAssignment(y)) &&
+                                            ts.isIdentifier(y.name) &&
+                                            col(y.name.text))
+                                            hit = true;
+                                    });
+                                return hit;
+                            });
+                        if (into === "required" || stamps)
+                            return;
+                        if (nsUndecided && nsOf) {
+                            scan.cnj.push(site(`insert ${intoName} — stamps only a namespace column of ${intoName}: prefix check not statically decidable (${nsOf.why})`));
+                            return;
+                        }
+                    }
+                    let payload = SAFE;
+                    const args = wm ? x.arguments.slice(1) : x.arguments.slice(1);
+                    for (const a of args)
+                        payload = merge(payload, w.eval(a));
+                    for (const c of conds)
+                        payload = merge(payload, w.eval(c));
+                    const label = wm
+                        ? `insert ${x.arguments[0]?.text ?? "?"}`
+                        : `scheduled effect ${x.arguments[em && /scheduler/.test(em[1]) ? 1 : 0]?.getText() ?? "?"}`;
+                    for (const via of payload.vias)
+                        targets.push({
+                            table: via.table,
+                            reason: `${via.reason} (row selected at line ${via.line})`,
+                            what: `${label} attributed to a ${via.table} row`,
+                        });
+                    if (targets.length === 0)
+                        return;
+                }
+                const reds = [];
+                const greens = [];
+                for (const t of targets) {
+                    const kind = facts.schema?.get(t.table)?.tenant;
+                    if (kind === undefined) {
+                        scan.cnj.push(site(`${t.what} — table ${t.table} not in schema.ts`));
+                        continue;
+                    }
+                    const ns = facts.namespace.get(t.table);
+                    if (ns?.verdict === "undecided") {
+                        scan.cnj.push(site(`${t.what} — namespace column of ${t.table}: prefix check not statically decidable (${ns.why})`));
+                        continue;
+                    }
+                    if (kind === "required") {
+                        greens.push(ns?.verdict === "checked"
+                            ? `${t.what} — ${t.table} carries a required tenant column (namespace, checked against the caller's allowed prefixes: ${ns.why}) (R-6/R-11 govern)`
+                            : `${t.what} — ${t.table} carries a required tenant column (R-6/R-11 govern)`);
+                        continue;
+                    }
+                    const g = guarded(w, x, t.table, kind);
+                    if (g)
+                        greens.push(`${t.what} — ${g}`);
+                    else
+                        reds.push(`${t.what} (${kind === "none" ? "no tenant column" : "optional tenant column"}), selected by ${t.reason}; no dominating guard reads a server-stamped tenant${kind === "none" ? " and names fleet scope" : ` of the ${t.table} row`}`);
+                }
+                if (reds.length)
+                    scan.violate.push(site(reds.join(" | ")));
+                else if (greens.length)
+                    scan.conform.push(site(greens.join(" | ")));
+            });
+        }
+    }
+    return { scan, untenanted, schemaRel: facts.schemaRel };
+}
+export const R52 = {
+    id: R52_ID,
+    run: (tree) => {
+        const d = scanR52Detailed(tree.files);
+        const empty = d.untenanted.length === 0 && d.schemaRel
+            ? `R-52: no applicable site — ${d.schemaRel} declares no table without a required tenant column, so no write can reach an untenanted row. NOT a clean bill.`
+            : `R-52: no applicable site — no public mutation/action write reached a table without a tenant value (untenanted tables read: ${d.untenanted.slice(0, 20).join(", ")}${d.untenanted.length > 20 ? ", …" : ""}). NOT a clean bill.`;
+        return decide("R-52", R52_ID, R52_CHECK, d.scan, empty);
+    },
+};
+export const SOURCE_CROSS_TENANT_WRITE_DETECTORS = [
+    { detector: R52, ruleId: "R-52", standardPin: SOURCE_STANDARD_PIN },
+];