@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/recipient-by-id.js

@@ -0,0 +1,1108 @@
+// R-53 clause 1, RECIPIENT side — a message recipient / target agent is
+// resolved by its unique ID, never by a name the caller typed.
+//
+// Standard 2825122 §4 R-53 clause 1: "A typed or matched name (...) never
+// selects a row and never authorises a write; a name is a display label only."
+// The detector spec's red (a)–(d) read the ACTING principal and the write's
+// admission; a recipient picked by name from a channel string, a roster or a
+// name index is the same clause seen from the target, and it was invisible
+// (operator decision 2026-10-08, task k1716f01f9g1a0scz7nj30118h8fx32c). The
+// sites land under R-53 because the standard text already binds them; no new
+// rule id is minted for a clause the pinned standard states.
+//
+// HOW IT READS. Every convex/ write door (mutation, action and their internal
+// twins) seeds its args object. A value is a RECIPIENT NAME when it is a
+// recipient-shaped argument field (RECIPIENT_ARGS) that is not a `v.id(...)`
+// argument, followed by value — never by spelling — through renames,
+// destructures, consts, reassignments, `for…of`, iteration callbacks, string
+// and array transforms (split/trim/normalize/replace/toLowerCase/…), local
+// normalisers (a helper whose return derives from its parameter), object
+// literals handed to a helper, a helper's parameter, a local arrow, and the
+// closure a helper returns. A recipient name is RED where it decides a row or
+// a route:
+//   membership  `set.has(n)`, `list.includes(n)`, `map.get(n)`, `indexOf`, over
+//               a collection that is not a list of literals;
+//   equality    `x === n` / `!==` / `startsWith` / `endsWith` / `localeCompare`
+//               against a non-literal that is not an ID (`_id`, `…Id`);
+//   index key   `q.eq(field, n)` inside `.withIndex` / `.filter` /
+//               `.withSearchIndex`;
+//   routing     a routing field (ROUTING_FIELDS) of an object literal handed to
+//               `db.insert|patch|replace`, written from a name.
+//   lookup      `byName[n]` (read, not an assignment target), `n in obj`;
+//   switch      `switch (n) { case x: }` with a case that is not a literal/ID.
+//
+// READ SIDE (operator gate 2026-10-08, same task). A door that SELECTS an
+// agent's data — an inbox, an unread count, a receipt to mark, a message to
+// delete — does so by the reader's verified identity or by an ID, never by a
+// name the caller typed. Query doors (`query`, `internalQuery`) are seeded
+// beside the write doors, and READER_ARGS (`orchestratorId`, `instanceId`,
+// `recipientInstanceId`, `agentName`, `agent`) join RECIPIENT_ARGS. Any OTHER
+// non-ID argument, whatever its spelling, is a WEAK name: it is red only where
+// it selects by a stored agent-identity field — `q.eq(f, n)` with `f` in
+// SELECTOR_FIELDS (or the table's declared fields), `row.f === n` with `f` in
+// SELECTOR_FIELDS, or a routing field written from it. So `callerOrchestrator`
+// matched against `receipt.recipient` (markAsRead) or `message.from`
+// (deleteMessage) is red, while the same argument checked against a roster is
+// left to clauses (a)/(b)/(d). A write door's own sender (SENDER_ARGS) is not
+// seeded weak: it is the acting principal.
+// ROUTING IS DECLARED PER TABLE where a field name is ambiguous
+// (ROUTING_BY_TABLE): `githubRepoMapping.orchestrator` routes webhook issues,
+// `diary.orchestrator` / `monitoredDeployments.orchestrator` record an author.
+//
+// CONFORMANT: `ctx.db.normalizeId("agents", x)` + `ctx.db.get` (the result is a
+// row, not a name), an ID read from a verified principal, a `v.id("agents")`
+// argument, a name rendered only (message text, log, an error string, a label
+// field outside ROUTING_FIELDS), a literal keyword test, and a NARROWING: a
+// typed name compared with a VERIFIED value (read from `ctx.auth.
+// getUserIdentity()` or a PACKAGE_RESOLVERS result) in an `if` that throws on
+// mismatch is conform, and so is every later use of that name in the same
+// block. A guard that refuses only some names (`a && n !== v`) does not narrow.
+// `user:<subject>` is an ID only when read from the authenticated identity;
+// typed, it is a name.
+// OUT OF SCOPE, stated: a write door's SENDER (`from`, `fromInstanceId`,
+// `createdBy`) — clauses (a)/(b)/(d) govern it; a narrowing performed inside a
+// helper (the door is read, not the helper's guard: errs red); a table's
+// author field read by a query (`diary.orchestrator`) unless it is declared;
+// `mcp-server/src` is not read by this clause.
+import * as ts from "typescript";
+import { dotted, lineOf, registrations, unwrap, walk, } from "./_ast.js";
+/** Argument fields that NAME the recipient / target agent of a write. */
+export const RECIPIENT_ARGS = new Set([
+    "channel",
+    "to",
+    "recipient",
+    "recipients",
+    "target",
+    "targetAgent",
+    "targetOrchestrator",
+    "assignedTo",
+    "assignedToInstance",
+    "assignedOrchestrator",
+    "assignee",
+    "reviewer",
+    "fallbackReviewer",
+    "delegateTo",
+]);
+/** Stored fields that ROUTE a row to its recipient. */
+export const ROUTING_FIELDS = new Set([
+    "recipient",
+    "recipients",
+    "recipientInstanceId",
+    "to",
+    "target",
+    "assignedTo",
+    "assignedToInstance",
+    "assignedOrchestrator",
+    "lastAssignedTo",
+    "assignee",
+    "reviewer",
+    "fallbackReviewer",
+]);
+/** Argument fields that NAME the reader / owner whose data a door selects. */
+export const READER_ARGS = new Set([
+    "orchestratorId",
+    "instanceId",
+    "recipientInstanceId",
+    "agentName",
+    "agent",
+]);
+/** A write door's own sender: the acting principal, never seeded as a name. */
+const SENDER_ARGS = new Set([
+    "from",
+    "fromInstanceId",
+    "createdBy",
+]);
+/** Stored agent-identity fields: keying or matching one with a typed value
+ * SELECTS an agent's data by name, whatever the argument is called. */
+export const SELECTOR_FIELDS = new Set([
+    ...ROUTING_FIELDS,
+    "orchestratorId",
+    "from",
+    "fromInstanceId",
+    "createdBy",
+]);
+/** Fields that route (or select an agent) only on a named table — the bare
+ * word is an author elsewhere (`diary.orchestrator`), so it is declared here
+ * and never added to the global sets. */
+export const ROUTING_BY_TABLE = new Map([["githubRepoMapping", new Set(["orchestrator"])]]);
+const SELECTOR_BY_TABLE = new Map([
+    ...ROUTING_BY_TABLE,
+    ["agents", new Set(["name", "normalizedName"])],
+    ["profiles", new Set(["name"])],
+]);
+const WRITE_DOORS = new Set([
+    "mutation",
+    "action",
+    "internalMutation",
+    "internalAction",
+]);
+const READ_DOORS = new Set(["query", "internalQuery"]);
+/** Methods whose result, on a name receiver, is still the name(s). */
+const TRANSFORMS = new Set([
+    "split",
+    "map",
+    "filter",
+    "flatMap",
+    "flat",
+    "slice",
+    "concat",
+    "sort",
+    "at",
+    "trim",
+    "trimStart",
+    "trimEnd",
+    "toLowerCase",
+    "toUpperCase",
+    "toLocaleLowerCase",
+    "toLocaleUpperCase",
+    "normalize",
+    "replace",
+    "replaceAll",
+    "substring",
+    "padStart",
+    "padEnd",
+    "join",
+    "find",
+    "findLast",
+]);
+/** Methods whose first callback parameter receives one name of the receiver. */
+const ITERATORS = new Set([
+    "map",
+    "filter",
+    "forEach",
+    "some",
+    "every",
+    "find",
+    "findIndex",
+    "findLast",
+    "flatMap",
+]);
+const MEMBERSHIP = new Set([
+    "has",
+    "includes",
+    "get",
+    "indexOf",
+    "lastIndexOf",
+]);
+const STRING_COMPARE = new Set([
+    "startsWith",
+    "endsWith",
+    "localeCompare",
+]);
+const INDEX_CALLS = new Set([
+    "withIndex",
+    "withSearchIndex",
+    "filter",
+]);
+/** An unresolvable callee spelled like a normaliser passes the name through. */
+const NORMALISER = /normali[sz]e|canonical|fold|lower|upper|slug|strip|clean|sanitiz|trim|dedupe/i;
+/** Labels whose name ends in `Id` but which carry a NAME, not an ID. */
+const NAME_LIKE_IDS = new Set([
+    "orchestratorId",
+    "instanceId",
+    "fromInstanceId",
+    "recipientInstanceId",
+]);
+const DB_WRITE = /\bdb\.(insert|patch|replace)$/;
+/** Calls whose result is a VERIFIED identity: the host's authenticated
+ * identity and the package's principal resolvers (mirrors PACKAGE_RESOLVERS
+ * in identity-by-id.ts, which imports this module). */
+const VERIFIED_SOURCES = new Set([
+    "getUserIdentity",
+    "resolveActingPrincipal",
+    "resolvePersonPrincipal",
+]);
+const moduleOf = (rel) => rel.replace(/^.*?(^|\/)convex\//, "").replace(/\.tsx?$/, "");
+function isIdish(e) {
+    const u = unwrap(e);
+    const last = ts.isPropertyAccessExpression(u)
+        ? u.name.text
+        : ts.isIdentifier(u)
+            ? u.text
+            : undefined;
+    if (last === undefined)
+        return false;
+    return last === "_id" || (/Id$/.test(last) && !NAME_LIKE_IDS.has(last));
+}
+function isLiteralish(e) {
+    const u = unwrap(e);
+    return (ts.isStringLiteralLike(u) ||
+        ts.isNumericLiteral(u) ||
+        u.kind === ts.SyntaxKind.NullKeyword ||
+        u.kind === ts.SyntaxKind.TrueKeyword ||
+        u.kind === ts.SyntaxKind.FalseKeyword ||
+        (ts.isIdentifier(u) && u.text === "undefined"));
+}
+/** The argument names a registration declares (`args: { … }`, inline, through
+ * a same-file const, or spreading one), or undefined when they cannot be read. */
+function declaredArgs(handler) {
+    const cfg = handler.parent?.parent;
+    if (!cfg || !ts.isObjectLiteralExpression(cfg))
+        return undefined;
+    for (const pr of cfg.properties)
+        if (ts.isPropertyAssignment(pr) &&
+            ts.isIdentifier(pr.name) &&
+            pr.name.text === "args")
+            return objectKeys(pr.initializer, 0);
+    return new Set();
+}
+function objectKeys(e, depth) {
+    let o = unwrap(e);
+    if (ts.isIdentifier(o)) {
+        const d = resolveDecl(o);
+        const vd = d?.parent;
+        if (depth > 4 || !vd || !ts.isVariableDeclaration(vd) || !vd.initializer)
+            return undefined;
+        o = unwrap(vd.initializer);
+    }
+    if (!ts.isObjectLiteralExpression(o))
+        return undefined;
+    const out = new Set();
+    for (const m of o.properties) {
+        if (ts.isSpreadAssignment(m)) {
+            const inner = objectKeys(m.expression, depth + 1);
+            if (!inner)
+                return undefined;
+            for (const k of inner)
+                out.add(k);
+        }
+        else if (m.name &&
+            (ts.isIdentifier(m.name) || ts.isStringLiteral(m.name)))
+            out.add(m.name.text);
+    }
+    return out;
+}
+/** The top-level declaration a node sits in: its function or registration. */
+function ownerName(n) {
+    let x = n;
+    while (x.parent && !ts.isSourceFile(x.parent))
+        x = x.parent;
+    if (ts.isFunctionDeclaration(x) && x.name)
+        return x.name.text;
+    if (ts.isVariableStatement(x)) {
+        const d = x.declarationList.declarations[0];
+        if (d && ts.isIdentifier(d.name))
+            return d.name.text;
+    }
+    return "<module>";
+}
+/** The identifiers a binding name introduces. */
+function boundIds(b, out = []) {
+    if (ts.isIdentifier(b))
+        out.push(b);
+    else
+        for (const el of b.elements)
+            if (!ts.isOmittedExpression(el))
+                boundIds(el.name, out);
+    return out;
+}
+/** The declaring identifier of `id`'s binding, by lexical scope. */
+function resolveDecl(id) {
+    const name = id.text;
+    const pick = (b) => boundIds(b).find((x) => x.text === name);
+    const inStatements = (sts) => {
+        for (const st of sts) {
+            if (ts.isVariableStatement(st))
+                for (const d of st.declarationList.declarations) {
+                    const hit = pick(d.name);
+                    if (hit)
+                        return hit;
+                }
+            if (ts.isFunctionDeclaration(st) && st.name?.text === name)
+                return st.name;
+        }
+        return undefined;
+    };
+    for (let q = id.parent; q; q = q.parent) {
+        if (ts.isFunctionLike(q)) {
+            for (const p of q.parameters) {
+                const hit = pick(p.name);
+                if (hit)
+                    return hit;
+            }
+        }
+        if (ts.isBlock(q) || ts.isSourceFile(q) || ts.isCaseClause(q)) {
+            const hit = inStatements(q.statements);
+            if (hit)
+                return hit;
+        }
+        if ((ts.isForOfStatement(q) ||
+            ts.isForInStatement(q) ||
+            ts.isForStatement(q)) &&
+            q.initializer &&
+            ts.isVariableDeclarationList(q.initializer))
+            for (const d of q.initializer.declarations) {
+                const hit = pick(d.name);
+                if (hit)
+                    return hit;
+            }
+        if (ts.isCatchClause(q) && q.variableDeclaration) {
+            const hit = pick(q.variableDeclaration.name);
+            if (hit)
+                return hit;
+        }
+    }
+    return undefined;
+}
+/** The function a declaring identifier names, when it names one. */
+function fnOfDecl(d) {
+    const p = d.parent;
+    if (ts.isFunctionDeclaration(p) && p.name === d)
+        return p;
+    if (ts.isVariableDeclaration(p) && p.name === d && p.initializer) {
+        const i = unwrap(p.initializer);
+        if (ts.isArrowFunction(i) || ts.isFunctionExpression(i))
+            return i;
+    }
+    return undefined;
+}
+/** A NON-EMPTY collection spelled only of literals (`["a","b"]`,
+ * `new Set(["a"])`), directly or through a `const`. An empty one is filled
+ * later from somewhere else, so it is never a list of literals. */
+function isLiteralCollection(e, depth = 0) {
+    const u = unwrap(e);
+    if (ts.isArrayLiteralExpression(u))
+        return u.elements.length > 0 && u.elements.every((x) => isLiteralish(x));
+    if (ts.isNewExpression(u) &&
+        ts.isIdentifier(u.expression) &&
+        u.expression.text === "Set" &&
+        u.arguments?.[0])
+        return isLiteralCollection(u.arguments[0], depth + 1);
+    if (ts.isIdentifier(u) && depth < 4) {
+        const d = resolveDecl(u);
+        const vd = d?.parent;
+        if (vd &&
+            ts.isVariableDeclaration(vd) &&
+            vd.name === d &&
+            vd.initializer &&
+            ts.isVariableDeclarationList(vd.parent) &&
+            (vd.parent.flags & ts.NodeFlags.Const) !== 0)
+            return isLiteralCollection(vd.initializer, depth + 1);
+    }
+    return false;
+}
+/** The `.withIndex` / `.filter` call whose callback `x` sits in, if any. */
+function indexCallOf(x) {
+    for (let q = x.parent; q; q = q.parent) {
+        if ((ts.isArrowFunction(q) || ts.isFunctionExpression(q)) &&
+            q.parent &&
+            ts.isCallExpression(q.parent) &&
+            ts.isPropertyAccessExpression(q.parent.expression) &&
+            INDEX_CALLS.has(q.parent.expression.name.text))
+            return q.parent;
+    }
+    return undefined;
+}
+/** The table a query chain reads: the `.query("<table>")` it starts from. */
+function tableOfChain(e0) {
+    let e = unwrap(e0);
+    for (let i = 0; i < 40; i++) {
+        if (ts.isCallExpression(e)) {
+            const c = unwrap(e.expression);
+            const a0 = e.arguments[0];
+            if (ts.isPropertyAccessExpression(c) &&
+                c.name.text === "query" &&
+                a0 &&
+                ts.isStringLiteralLike(a0))
+                return a0.text;
+            e = c;
+        }
+        else if (ts.isPropertyAccessExpression(e))
+            e = unwrap(e.expression);
+        else
+            return undefined;
+    }
+    return undefined;
+}
+/** The table a row expression (`existing`, `existing._id`) was read from. */
+function tableOfRow(e0) {
+    let e = unwrap(e0);
+    if (ts.isPropertyAccessExpression(e) && e.name.text === "_id")
+        e = unwrap(e.expression);
+    if (!ts.isIdentifier(e))
+        return undefined;
+    const vd = resolveDecl(e)?.parent;
+    return vd && ts.isVariableDeclaration(vd) && vd.initializer
+        ? tableOfChain(vd.initializer)
+        : undefined;
+}
+/** The table a `db.insert|patch|replace` call writes, when it can be read. */
+function tableOfWrite(call) {
+    const a0 = call.arguments[0];
+    if (!a0)
+        return undefined;
+    if (ts.isStringLiteralLike(a0))
+        return a0.text;
+    return /insert$/.test(dotted(call.expression) ?? "")
+        ? undefined
+        : tableOfRow(a0);
+}
+/** The field an index/filter `q.eq(field, value)` keys: a literal or
+ * `q.field("<f>")`. */
+function eqField(call) {
+    const a0 = call.arguments[0] && unwrap(call.arguments[0]);
+    if (!a0)
+        return undefined;
+    if (ts.isStringLiteralLike(a0))
+        return a0.text;
+    if (ts.isCallExpression(a0) &&
+        ts.isPropertyAccessExpression(a0.expression) &&
+        a0.expression.name.text === "field" &&
+        a0.arguments[0] &&
+        ts.isStringLiteralLike(a0.arguments[0]))
+        return a0.arguments[0].text;
+    return undefined;
+}
+/** Does `f` select an agent's data on `table` (undefined: table unknown)? */
+function isSelectorField(f, table) {
+    return (SELECTOR_FIELDS.has(f) ||
+        (table !== undefined && !!SELECTOR_BY_TABLE.get(table)?.has(f)));
+}
+/** A read of a stored agent-identity field off a row: `receipt.recipient`. */
+function isSelectorProp(e) {
+    const u = unwrap(e);
+    return ts.isPropertyAccessExpression(u) && SELECTOR_FIELDS.has(u.name.text);
+}
+/** Does a statement refuse (throw) on every path through it? */
+function refuses(s) {
+    if (ts.isThrowStatement(s))
+        return true;
+    if (ts.isBlock(s)) {
+        const last = s.statements[s.statements.length - 1];
+        return !!last && ts.isThrowStatement(last);
+    }
+    return false;
+}
+/** The disjuncts of a condition: `a || (b || c)` -> [a, b, c]. */
+function disjuncts(e0, out = []) {
+    const e = unwrap(e0);
+    if (ts.isBinaryExpression(e) &&
+        e.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+        disjuncts(e.left, out);
+        disjuncts(e.right, out);
+    }
+    else
+        out.push(e);
+    return out;
+}
+/** The db write call a routing object literal is handed to, if any. */
+function dbWriteOf(obj) {
+    let x = obj;
+    while (x.parent &&
+        (ts.isParenthesizedExpression(x.parent) ||
+            ts.isConditionalExpression(x.parent) ||
+            ts.isSpreadAssignment(x.parent) ||
+            ts.isPropertyAssignment(x.parent) ||
+            ts.isObjectLiteralExpression(x.parent) ||
+            ts.isAsExpression(x.parent)))
+        x = x.parent;
+    const call = x.parent;
+    return call &&
+        ts.isCallExpression(call) &&
+        call.arguments.includes(x) &&
+        DB_WRITE.test(dotted(call.expression) ?? "")
+        ? call
+        : undefined;
+}
+/** The routing fields of a write to `table`: the global set plus the table's
+ * declared ones. */
+function routingFieldsOf(table) {
+    const own = table === undefined ? undefined : ROUTING_BY_TABLE.get(table);
+    return own ? [...ROUTING_FIELDS, ...own] : [...ROUTING_FIELDS];
+}
+const snippet = (n) => n.getText().replace(/\s+/g, " ").slice(0, 90);
+export class RecipientFlow {
+    parsed;
+    fns;
+    relOf = new Map();
+    done = new Map();
+    queue = [];
+    sites = new Map();
+    constructor(parsed, fns) {
+        this.parsed = parsed;
+        this.fns = fns;
+        for (const p of parsed)
+            this.relOf.set(p.sf, p.rel);
+    }
+    run() {
+        for (const p of this.parsed) {
+            if (!/(^|\/)convex\//.test(p.rel))
+                continue;
+            for (const reg of registrations(p)) {
+                const write = WRITE_DOORS.has(reg.builder);
+                if (!write && !READ_DOORS.has(reg.builder))
+                    continue;
+                if (reg.handler.parameters.length < 2)
+                    continue;
+                this.queue.push({
+                    fn: reg.handler,
+                    seeds: new Map([
+                        [
+                            1,
+                            {
+                                kind: "obj",
+                                origin: `${moduleOf(p.rel)}:${reg.name} args`,
+                                idArgs: new Set(reg.argIdTable.keys()),
+                                declared: declaredArgs(reg.handler),
+                                write,
+                            },
+                        ],
+                    ]),
+                });
+            }
+        }
+        for (let item = this.queue.shift(); item; item = this.queue.shift())
+            this.analyse(item.fn, item.seeds);
+        return [...this.sites.values()].sort((a, b) => a.rel === b.rel ? a.n - b.n : a.rel < b.rel ? -1 : 1);
+    }
+    key(fn, seeds) {
+        const sig = [...seeds]
+            .sort((a, b) => a[0] - b[0])
+            .map(([i, t]) => `${i}:${t.kind}${t.weak ? "~" : ""}${t.write ? "w" : ""}${t.fields
+            ? `{${[...t.fields]
+                .map(([f, v]) => `${f}${v.weak ? "~" : ""}`)
+                .sort()
+                .join(",")}}`
+            : ""}`)
+            .join(";");
+        return `${fn.getSourceFile().fileName}:${fn.pos}|${sig}`;
+    }
+    /** Analyse one function under seeded parameters; returns its return taint. */
+    analyse(fn, seeds) {
+        const k = this.key(fn, seeds);
+        const memo = this.done.get(k);
+        if (memo)
+            return memo.returns;
+        const slot = { returns: undefined };
+        this.done.set(k, slot); // in progress: a recursive call reads "no taint"
+        const body = fn.body;
+        if (!body)
+            return undefined;
+        const rel = this.relOf.get(fn.getSourceFile()) ?? "";
+        const env = new Map();
+        const closures = new Map();
+        const bind = (b, t) => {
+            if (!t)
+                return false;
+            let grew = false;
+            if (ts.isIdentifier(b)) {
+                const had = env.get(b);
+                if (!had || (had.weak && t.kind === "name" && !t.weak)) {
+                    env.set(b, t);
+                    grew = true;
+                }
+                return grew;
+            }
+            for (const el of b.elements) {
+                if (ts.isOmittedExpression(el))
+                    continue;
+                if (t.kind === "name")
+                    grew = bind(el.name, t) || grew;
+                else if (ts.isObjectBindingPattern(b) && !el.dotDotDotToken) {
+                    const key = (el.propertyName ?? el.name).getText();
+                    grew = bind(el.name, this.field(t, key)) || grew;
+                }
+                else
+                    grew = bind(el.name, t) || grew;
+            }
+            return grew;
+        };
+        const bindParams = (f, args) => {
+            let grew = false;
+            f.parameters.forEach((p, i) => {
+                const a = args[i];
+                if (a)
+                    grew = bind(p.name, taintOf(a)) || grew;
+            });
+            return grew;
+        };
+        for (const [i, t] of seeds) {
+            const p = fn.parameters[i];
+            if (p)
+                bind(p.name, t);
+        }
+        const lookup = (id) => {
+            const d = resolveDecl(id);
+            return d ? env.get(d) : undefined;
+        };
+        const taintOf = (e0) => {
+            const e = unwrap(e0);
+            if (ts.isIdentifier(e))
+                return lookup(e);
+            if (ts.isPropertyAccessExpression(e)) {
+                const base = taintOf(e.expression);
+                return base?.kind === "obj" ? this.field(base, e.name.text) : undefined;
+            }
+            if (ts.isElementAccessExpression(e)) {
+                const base = taintOf(e.expression);
+                return base?.kind === "name" ? base : undefined;
+            }
+            if (ts.isConditionalExpression(e))
+                return best(taintOf(e.whenTrue), taintOf(e.whenFalse));
+            if (ts.isBinaryExpression(e)) {
+                const op = e.operatorToken.kind;
+                if (op === ts.SyntaxKind.PlusToken ||
+                    op === ts.SyntaxKind.QuestionQuestionToken ||
+                    op === ts.SyntaxKind.BarBarToken)
+                    return best(taintOf(e.left), taintOf(e.right));
+                return undefined;
+            }
+            if (ts.isTemplateExpression(e)) {
+                return best(...e.templateSpans.map((s) => taintOf(s.expression)));
+            }
+            if (ts.isArrayLiteralExpression(e)) {
+                return best(...e.elements.map((x) => taintOf(ts.isSpreadElement(x) ? x.expression : x)));
+            }
+            if (ts.isObjectLiteralExpression(e)) {
+                const fields = new Map();
+                let whole;
+                for (const pr of e.properties) {
+                    if (ts.isPropertyAssignment(pr) && ts.isIdentifier(pr.name)) {
+                        const t = taintOf(pr.initializer);
+                        if (t?.kind === "name")
+                            fields.set(pr.name.text, t);
+                    }
+                    else if (ts.isShorthandPropertyAssignment(pr)) {
+                        const t = lookup(pr.name);
+                        if (t?.kind === "name")
+                            fields.set(pr.name.text, t);
+                    }
+                    else if (ts.isSpreadAssignment(pr)) {
+                        const t = taintOf(pr.expression);
+                        if (t?.kind === "obj")
+                            whole = t;
+                    }
+                }
+                if (whole && !fields.size)
+                    return whole;
+                if (!fields.size)
+                    return undefined;
+                const origin = [...fields.values()][0]?.origin ?? "";
+                return { kind: "obj", origin, fields };
+            }
+            if (ts.isNewExpression(e)) {
+                if (ts.isIdentifier(e.expression) &&
+                    /^(Set|Array)$/.test(e.expression.text) &&
+                    e.arguments?.[0])
+                    return asName(taintOf(e.arguments[0]));
+                return undefined;
+            }
+            if (ts.isCallExpression(e)) {
+                const c = unwrap(e.expression);
+                if (ts.isPropertyAccessExpression(c)) {
+                    const recv = taintOf(c.expression);
+                    if (recv?.kind === "name" && TRANSFORMS.has(c.name.text))
+                        return recv;
+                    if (dotted(c) === "Array.from" &&
+                        e.arguments[0] &&
+                        taintOf(e.arguments[0])?.kind === "name")
+                        return taintOf(e.arguments[0]);
+                    return undefined;
+                }
+                if (ts.isIdentifier(c)) {
+                    const tainted = e.arguments
+                        .map((a, i) => [i, taintOf(a)])
+                        .filter((x) => x[1] !== undefined);
+                    if (!tainted.length)
+                        return undefined;
+                    const local = this.localFn(c, fn);
+                    const targets = local
+                        ? [local]
+                        : this.defsFor(c, rel).map((d) => d.fn);
+                    if (!targets.length) {
+                        const n = tainted.find((x) => x[1].kind === "name");
+                        return n && NORMALISER.test(c.text) ? n[1] : undefined;
+                    }
+                    if (local)
+                        return undefined; // shares this env; read via returns below
+                    // The memo is keyed by taint SHAPE, so a returned name carries the
+                    // origin of whichever caller analysed the helper first; re-attach
+                    // THIS caller's origin.
+                    const mine = best(...tainted.map((x) => x[1]));
+                    for (const f of targets) {
+                        const r = this.analyse(f, new Map(tainted));
+                        if (r?.kind === "name")
+                            return mine ? { ...r, origin: mine.origin } : r;
+                    }
+                }
+            }
+            return undefined;
+        };
+        // ---- verified values: the authenticated identity, the package principal
+        const verified = new Set();
+        const isVerified = (e0) => {
+            const e = unwrap(e0);
+            if (ts.isIdentifier(e)) {
+                const d = resolveDecl(e);
+                return !!d && verified.has(d);
+            }
+            if (ts.isPropertyAccessExpression(e) || ts.isElementAccessExpression(e))
+                return isVerified(e.expression);
+            if (ts.isCallExpression(e)) {
+                const c = unwrap(e.expression);
+                const name = ts.isPropertyAccessExpression(c)
+                    ? c.name.text
+                    : ts.isIdentifier(c)
+                        ? c.text
+                        : "";
+                if (VERIFIED_SOURCES.has(name))
+                    return true;
+                // a normaliser of a verified value is still that value
+                return (ts.isPropertyAccessExpression(c) &&
+                    TRANSFORMS.has(c.name.text) &&
+                    isVerified(c.expression));
+            }
+            if (ts.isTemplateExpression(e))
+                return (e.templateSpans.length > 0 &&
+                    e.templateSpans.every((s) => isVerified(s.expression)));
+            return false;
+        };
+        // ---- fixpoint over bindings --------------------------------------
+        for (let round = 0, grew = true; grew && round < 30; round++) {
+            grew = false;
+            walk(body, (x) => {
+                if (ts.isVariableDeclaration(x) && x.initializer) {
+                    grew = bind(x.name, taintOf(x.initializer)) || grew;
+                    if (isVerified(x.initializer))
+                        for (const id of boundIds(x.name))
+                            if (!verified.has(id)) {
+                                verified.add(id);
+                                grew = true;
+                            }
+                    // a helper's returned closure: `const r = helper(…)`
+                    const i = unwrap(x.initializer);
+                    if (ts.isIdentifier(x.name) &&
+                        ts.isCallExpression(i) &&
+                        ts.isIdentifier(unwrap(i.expression)) &&
+                        !closures.has(x.name)) {
+                        for (const d of this.defsFor(unwrap(i.expression), rel)) {
+                            const ret = returnedFn(d.fn);
+                            if (ret) {
+                                closures.set(x.name, ret);
+                                grew = true;
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (ts.isBinaryExpression(x) &&
+                    ts.isIdentifier(x.left) &&
+                    (x.operatorToken.kind === ts.SyntaxKind.EqualsToken ||
+                        x.operatorToken.kind ===
+                            ts.SyntaxKind.QuestionQuestionEqualsToken ||
+                        x.operatorToken.kind === ts.SyntaxKind.BarBarEqualsToken)) {
+                    const d = resolveDecl(x.left);
+                    if (d)
+                        grew = bind(d, taintOf(x.right)) || grew;
+                }
+                if (ts.isForOfStatement(x) &&
+                    ts.isVariableDeclarationList(x.initializer) &&
+                    x.initializer.declarations[0]) {
+                    const t = asName(taintOf(x.expression));
+                    grew = bind(x.initializer.declarations[0].name, t) || grew;
+                }
+                if (ts.isCallExpression(x)) {
+                    const c = unwrap(x.expression);
+                    if (ts.isPropertyAccessExpression(c) && ITERATORS.has(c.name.text)) {
+                        const recv = asName(taintOf(c.expression));
+                        const cb = x.arguments[0] && unwrap(x.arguments[0]);
+                        if (recv &&
+                            cb &&
+                            (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb)) &&
+                            cb.parameters[0])
+                            grew = bind(cb.parameters[0].name, recv) || grew;
+                    }
+                    if (ts.isIdentifier(c)) {
+                        const local = this.localFn(c, fn);
+                        if (local)
+                            grew = bindParams(local, x.arguments) || grew;
+                    }
+                }
+            });
+        }
+        // ---- narrowing guards ----------------------------------------------
+        // `if (… || n !== <verified> || …) throw …` refuses every name but the
+        // caller's own: `n` is conform from the end of that `if` to the end of
+        // its block.
+        const narrowings = [];
+        walk(body, (x) => {
+            if (!ts.isIfStatement(x) || !refuses(x.thenStatement))
+                return;
+            for (const d of disjuncts(x.expression)) {
+                let cmp = d;
+                if (ts.isPrefixUnaryExpression(cmp) &&
+                    cmp.operator === ts.SyntaxKind.ExclamationToken)
+                    cmp = unwrap(cmp.operand);
+                if (!ts.isBinaryExpression(cmp))
+                    continue;
+                const op = cmp.operatorToken.kind;
+                const negated = d !== cmp;
+                const mismatch = negated
+                    ? op === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+                        op === ts.SyntaxKind.EqualsEqualsToken
+                    : op === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+                        op === ts.SyntaxKind.ExclamationEqualsToken;
+                if (!mismatch)
+                    continue;
+                const lt = asName(taintOf(cmp.left));
+                const rt = asName(taintOf(cmp.right));
+                const t = lt && isVerified(cmp.right)
+                    ? lt
+                    : rt && isVerified(cmp.left)
+                        ? rt
+                        : undefined;
+                if (t)
+                    narrowings.push({
+                        origin: t.origin,
+                        block: x.parent,
+                        after: x.end,
+                    });
+            }
+        }, true);
+        const narrowed = (t, node) => narrowings.some((g) => g.origin === t.origin &&
+            node.pos >= g.after &&
+            node.end <= g.block.end &&
+            node.pos >= g.block.pos);
+        // ---- sinks and onward calls --------------------------------------
+        const site = (node, kind, t) => {
+            if (narrowed(t, node))
+                return;
+            const n = lineOf(node);
+            const key = `${rel}:${n}`;
+            if (this.sites.has(key))
+                return;
+            this.sites.set(key, {
+                rel,
+                n,
+                note: `${ownerName(node)}: (1) recipient resolved by name — ${kind} (\`${snippet(node)}\`, line ${n}) from ${t.origin}, instead of ctx.db.normalizeId + ctx.db.get on the agent's ID`,
+            });
+        };
+        /** `n` compared with `other`: red when `n` is a listed name and `other`
+         * is not a literal, an ID or a verified value — or, for any name, when
+         * `other` is a stored agent-identity field of a row. */
+        const compared = (node, n, other) => {
+            const t = asName(taintOf(n));
+            if (!t || asName(taintOf(other)))
+                return false;
+            if (isLiteralish(other) || isIdish(other) || isVerified(other))
+                return false;
+            if (t.weak && !isSelectorProp(other))
+                return false;
+            site(node, "name equality", t);
+            return true;
+        };
+        const routedIn = (t, table) => routingFieldsOf(table).filter((f) => this.field(t, f));
+        walk(body, (x) => {
+            if (ts.isBinaryExpression(x)) {
+                const op = x.operatorToken.kind;
+                if (op === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+                    op === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+                    op === ts.SyntaxKind.EqualsEqualsToken ||
+                    op === ts.SyntaxKind.ExclamationEqualsToken) {
+                    if (!compared(x, x.left, x.right))
+                        compared(x, x.right, x.left);
+                }
+                // `n in byName`
+                if (op === ts.SyntaxKind.InKeyword) {
+                    const t = strong(taintOf(x.left));
+                    if (t && !taintOf(x.right) && !isLiteralCollection(x.right))
+                        site(x, "membership in a set of names", t);
+                }
+            }
+            // `byName[n]` read as a lookup (an assignment target builds, not reads)
+            if (ts.isElementAccessExpression(x)) {
+                const t = strong(taintOf(x.argumentExpression));
+                const assigned = ts.isBinaryExpression(x.parent) &&
+                    x.parent.left === x &&
+                    x.parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                    x.parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment;
+                if (t &&
+                    !assigned &&
+                    !taintOf(x.expression) &&
+                    !isLiteralCollection(x.expression))
+                    site(x, "membership in a set of names", t);
+            }
+            // `switch (n) { case x: }` — each non-literal case is an equality
+            if (ts.isCaseClause(x) &&
+                ts.isSwitchStatement(x.parent.parent) &&
+                !asName(taintOf(x.expression))) {
+                const t = strong(taintOf(x.parent.parent.expression));
+                if (t &&
+                    !isLiteralish(x.expression) &&
+                    !isIdish(x.expression) &&
+                    !isVerified(x.expression))
+                    site(x, "name equality", t);
+            }
+            if ((ts.isPropertyAssignment(x) || ts.isShorthandPropertyAssignment(x)) &&
+                ts.isIdentifier(x.name) &&
+                ts.isObjectLiteralExpression(x.parent)) {
+                const write = dbWriteOf(x.parent);
+                if (write &&
+                    routingFieldsOf(tableOfWrite(write)).includes(x.name.text)) {
+                    const t = asName(ts.isPropertyAssignment(x)
+                        ? taintOf(x.initializer)
+                        : lookup(x.name));
+                    if (t)
+                        site(x, "routing field written from a name", t);
+                }
+            }
+            // `{ ...args }` into a write carries every routing argument it holds
+            if (ts.isSpreadAssignment(x) && ts.isObjectLiteralExpression(x.parent)) {
+                const write = dbWriteOf(x.parent);
+                const t = write && taintOf(x.expression);
+                if (write && t?.kind === "obj") {
+                    const routed = routedIn(t, tableOfWrite(write));
+                    const first = routed[0] && this.field(t, routed[0]);
+                    if (first)
+                        site(x, `routing field written from a name (spread carries ${routed.join(", ")})`, first);
+                }
+            }
+            if (!ts.isCallExpression(x))
+                return;
+            const c = unwrap(x.expression);
+            // `db.patch(id, fields)` with `fields` the args object (or a rest of it)
+            const data = x.arguments[x.arguments.length - 1];
+            if (data &&
+                DB_WRITE.test(dotted(c) ?? "") &&
+                !ts.isObjectLiteralExpression(unwrap(data))) {
+                const t = taintOf(data);
+                if (t?.kind === "obj") {
+                    const routed = routedIn(t, tableOfWrite(x));
+                    const first = routed[0] && this.field(t, routed[0]);
+                    if (first)
+                        site(data, `routing field written from a name (the written object carries ${routed.join(", ")})`, first);
+                }
+            }
+            if (ts.isPropertyAccessExpression(c)) {
+                const m = c.name.text;
+                const a0 = x.arguments[0];
+                if (MEMBERSHIP.has(m) && a0) {
+                    const t = strong(taintOf(a0));
+                    if (t && !taintOf(c.expression) && !isLiteralCollection(c.expression))
+                        site(x, "membership in a set of names", t);
+                }
+                if (STRING_COMPARE.has(m) && a0) {
+                    if (!compared(x, c.expression, a0))
+                        compared(x, a0, c.expression);
+                }
+                const ix = m === "eq" && x.arguments[1] ? indexCallOf(x) : undefined;
+                if (ix && x.arguments[1]) {
+                    const t = asName(taintOf(x.arguments[1]));
+                    const f = eqField(x);
+                    const table = ts.isPropertyAccessExpression(ix.expression)
+                        ? tableOfChain(ix.expression.expression)
+                        : undefined;
+                    if (t && (!t.weak || (f !== undefined && isSelectorField(f, table))))
+                        site(x.arguments[1], "index/filter keyed by a name", t);
+                }
+                return;
+            }
+            if (!ts.isIdentifier(c))
+                return;
+            const seedsOut = new Map();
+            x.arguments.forEach((a, i) => {
+                const t = taintOf(a);
+                if (t && !(t.kind === "name" && narrowed(t, x)))
+                    seedsOut.set(i, t);
+            });
+            if (!seedsOut.size || this.localFn(c, fn))
+                return;
+            const d = resolveDecl(c);
+            const closure = d ? closures.get(d) : undefined;
+            if (closure) {
+                this.queue.push({ fn: closure, seeds: seedsOut });
+                return;
+            }
+            for (const def of this.defsFor(c, rel))
+                this.queue.push({ fn: def.fn, seeds: seedsOut });
+        });
+        // ---- what this function returns ------------------------------------
+        const rets = [];
+        if (!ts.isBlock(body))
+            rets.push(body);
+        else
+            walk(body, (y) => {
+                if (ts.isReturnStatement(y) && y.expression)
+                    rets.push(y.expression);
+            }, true);
+        for (const r of rets) {
+            const t = taintOf(r);
+            if (t) {
+                slot.returns = t;
+                break;
+            }
+        }
+        return slot.returns;
+    }
+    /** A field of an obj taint: a door's recipient argument, or a carried name. */
+    field(t, key) {
+        if (t.kind !== "obj")
+            return undefined;
+        if (t.fields)
+            return t.fields.get(key);
+        if (t.idArgs?.has(key))
+            return undefined;
+        if (t.declared && !t.declared.has(key))
+            return undefined;
+        const origin = `${t.origin}.${key}`;
+        if (RECIPIENT_ARGS.has(key) || READER_ARGS.has(key))
+            return { kind: "name", origin };
+        // Any other declared argument is a weak name; a write door's own sender
+        // is the acting principal, never a name of this clause.
+        if (!t.declared?.has(key) || (t.write && SENDER_ARGS.has(key)))
+            return undefined;
+        return { kind: "name", origin, weak: true };
+    }
+    /** A function declared INSIDE `unit` (shares its environment). */
+    localFn(c, unit) {
+        const d = resolveDecl(c);
+        const f = d && fnOfDecl(d);
+        if (!f)
+            return undefined;
+        for (let q = f.parent; q; q = q.parent)
+            if (q === unit)
+                return f;
+        return undefined;
+    }
+    /** Module-level definitions a callee names: same file first, else by name. */
+    defsFor(c, rel) {
+        const all = this.fns.get(c.text) ?? [];
+        const same = all.filter((d) => d.rel === rel);
+        return same.length ? same : all;
+    }
+}
+function asName(t) {
+    return t?.kind === "name" ? t : undefined;
+}
+/** The strongest name among candidates: a listed name before a weak one. */
+function best(...ts0) {
+    const names = ts0.map(asName).filter((t) => t !== undefined);
+    return names.find((t) => !t.weak) ?? names[0];
+}
+/** A listed (strong) name: red at every sink, not only at a selector field. */
+function strong(t) {
+    return t?.kind === "name" && !t.weak ? t : undefined;
+}
+/** The function a helper returns (`return async (name) => …`), if any. */
+function returnedFn(fn) {
+    const body = fn.body;
+    if (!body)
+        return undefined;
+    if (!ts.isBlock(body)) {
+        const u = unwrap(body);
+        return ts.isArrowFunction(u) || ts.isFunctionExpression(u) ? u : undefined;
+    }
+    let found;
+    walk(body, (y) => {
+        if (found || !ts.isReturnStatement(y) || !y.expression)
+            return;
+        const u = unwrap(y.expression);
+        if (ts.isArrowFunction(u) || ts.isFunctionExpression(u))
+            found = u;
+    }, true);
+    return found;
+}
+/** Every recipient-by-name site reachable from a convex/ write door. */
+export function recipientByNameSites(parsed, fns) {
+    return new RecipientFlow(parsed, fns).run();
+}