@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/detectors/source/guard-helper-flow.js

@@ -0,0 +1,1173 @@
+// R-6 guard helpers judged on CONTROL FLOW, never on the text of their body.
+//
+// A public mutation often enforces its boundary in one line that calls a helper
+// defined elsewhere (`await requireOrgAdmin(ctx, args.orgSlug)`). Crediting such
+// a helper by the presence of an identity read and a `throw` in its text is
+// wrong both ways (Eta, backend-doctor #36 @ a43e1bf):
+//  - a body wrapped in `try { … } catch {}` (R6T) or moved into a closure that is
+//    never called (R6N) still CONTAINS the read and the throw, yet refuses no
+//    one;
+//  - a `return` inside a `.filter((x) => { return … })` callback (R6Q) is not a
+//    return from the helper, yet a token scan reads it as one.
+//
+// So the helper's body is parsed with the TypeScript compiler API and walked as
+// structured control flow. Each path carries what it has PASSED:
+//  - `guarded` — a branch whose condition depends on the verified identity
+//    (a value derived from `ctx.auth.getUserIdentity()` / `withOrgScope(ctx)`)
+//    and whose other arm always throws (a refusal for the absent/mismatch case);
+//  - `bound` — such a guard whose condition also reads one of the helper's own
+//    non-context parameters (the target the helper binds the identity to);
+//  - `master` — such a guard whose condition tests `isMaster` on the identity.
+// A path ends at a `return` at the helper's OWN level, at the fall-through end of
+// the body, or at a `throw`. A `throw` inside a `try` goes to its `catch`, which
+// is entered from the state at the `try`'s entry (any statement of the try block
+// may raise before the guard). Nested functions and arrows are never executed:
+// their `return` and `throw` belong to them, and their reads read nothing here.
+//
+// The helper is HONOURED only when every path reaching a normal exit has passed
+// a guard (plus `bound` for a binds-arg helper, `master` for a master-only one).
+// Any construct the walk does not model (switch, labelled statements, a loop
+// carrying return/throw/break/continue, a `finally`, an expression-bodied
+// arrow) makes the verdict COULD-NOT-JUDGE — never honoured.
+import * as ts from "typescript";
+class Undecidable extends Error {
+}
+const isFunctionLike = (n) => ts.isFunctionDeclaration(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n) ||
+    ts.isGetAccessor(n) ||
+    ts.isSetAccessor(n) ||
+    ts.isConstructorDeclaration(n) ||
+    ts.isClassLike(n);
+/** Visit `n` and its descendants, never entering a nested function or class. */
+function walkOwn(n, visit) {
+    if (isFunctionLike(n))
+        return;
+    visit(n);
+    n.forEachChild((c) => walkOwn(c, visit));
+}
+/** A call that reads the verified identity, at this function's own level. */
+function isIdentityRead(n) {
+    if (!ts.isCallExpression(n))
+        return false;
+    const callee = n.expression;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text === "getUserIdentity";
+    return ts.isIdentifier(callee) && callee.text === "withOrgScope";
+}
+/** Does `expr` depend on the verified identity (a tainted local, or a read)? */
+function dependsOnIdentity(expr, tainted) {
+    let hit = false;
+    walkOwn(expr, (x) => {
+        if (hit)
+            return;
+        if (isIdentityRead(x))
+            hit = true;
+        else if (ts.isIdentifier(x) && tainted.has(x.text)) {
+            const p = x.parent;
+            // `foo.identity` names a property, it does not read a local.
+            if (!(p && ts.isPropertyAccessExpression(p) && p.name === x))
+                hit = true;
+        }
+    });
+    return hit;
+}
+function readsAny(expr, names) {
+    let hit = false;
+    walkOwn(expr, (x) => {
+        if (hit || !ts.isIdentifier(x) || !names.has(x.text))
+            return;
+        const p = x.parent;
+        if (!(p && ts.isPropertyAccessExpression(p) && p.name === x))
+            hit = true;
+    });
+    return hit;
+}
+function testsIsMaster(expr, tainted) {
+    let hit = false;
+    walkOwn(expr, (x) => {
+        if (hit)
+            return;
+        if (ts.isPropertyAccessExpression(x) &&
+            x.name.text === "isMaster" &&
+            dependsOnIdentity(x.expression, tainted))
+            hit = true;
+        else if (ts.isIdentifier(x) &&
+            x.text === "isMaster" &&
+            tainted.has("isMaster"))
+            hit = true;
+    });
+    return hit;
+}
+function bindingNames(b, out) {
+    if (ts.isIdentifier(b))
+        out.push(b.text);
+    else
+        for (const el of b.elements)
+            if (!ts.isOmittedExpression(el))
+                bindingNames(el.name, out);
+    return out;
+}
+function merge(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return {
+        tainted: new Set([...a.tainted].filter((t) => b.tainted.has(t))),
+        guarded: a.guarded && b.guarded,
+        bound: a.bound && b.bound,
+        master: a.master && b.master,
+        absent: a.absent && b.absent,
+    };
+}
+/** Statements that can transfer control out of a loop or switch body. */
+function hasAbrupt(n) {
+    let hit = false;
+    walkOwn(n, (x) => {
+        if (ts.isReturnStatement(x) ||
+            ts.isThrowStatement(x) ||
+            ts.isBreakStatement(x) ||
+            ts.isContinueStatement(x))
+            hit = true;
+    });
+    return hit;
+}
+/** Truth of `e` when it reads only the call-site constants (`opts?.masterOnly`
+ * where the call passed `{ masterOnly: true }`); `undefined` when it does not. */
+function constTruth(e, consts) {
+    if (ts.isParenthesizedExpression(e))
+        return constTruth(e.expression, consts);
+    if (e.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (e.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (ts.isPrefixUnaryExpression(e) &&
+        e.operator === ts.SyntaxKind.ExclamationToken) {
+        const v = constTruth(e.operand, consts);
+        return v === undefined ? undefined : !v;
+    }
+    if (ts.isBinaryExpression(e)) {
+        const op = e.operatorToken.kind;
+        if (op !== ts.SyntaxKind.AmpersandAmpersandToken &&
+            op !== ts.SyntaxKind.BarBarToken)
+            return undefined;
+        const a = constTruth(e.left, consts);
+        const b = constTruth(e.right, consts);
+        if (op === ts.SyntaxKind.AmpersandAmpersandToken) {
+            if (a === false || b === false)
+                return false;
+            return a === true && b === true ? true : undefined;
+        }
+        if (a === true || b === true)
+            return true;
+        return a === false && b === false ? false : undefined;
+    }
+    if (ts.isIdentifier(e) && consts.has(e.text))
+        return consts.get(e.text) !== null;
+    if (ts.isPropertyAccessExpression(e) &&
+        ts.isIdentifier(e.expression) &&
+        consts.has(e.expression.text)) {
+        const obj = consts.get(e.expression.text);
+        if (obj === null)
+            return false; // the argument was not passed
+        if (!obj)
+            return undefined;
+        let found;
+        for (const p of obj.properties) {
+            // A spread, a shorthand or a computed key: the literal is not readable.
+            if (!ts.isPropertyAssignment(p))
+                return undefined;
+            if (!ts.isIdentifier(p.name) && !ts.isStringLiteral(p.name))
+                return undefined;
+            if (p.name.text === e.name.text)
+                found = p.initializer;
+        }
+        if (!found)
+            return false; // absent key reads undefined
+        if (found.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (found.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        return undefined;
+    }
+    return undefined;
+}
+function awaitedCall(e) {
+    let x = e;
+    while (ts.isParenthesizedExpression(x))
+        x = x.expression;
+    return ts.isAwaitExpression(x);
+}
+/** `async`, or a declared `Promise<…>` return: its refusal is a rejection. */
+function returnsPromise(fn) {
+    const isAsync = (ts.getModifiers(fn) ?? []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword);
+    return isAsync || (fn.type?.getText().startsWith("Promise") ?? false);
+}
+class Walker {
+    params;
+    v;
+    constructor(params, v) {
+        this.params = params;
+        this.v = v;
+    }
+    /** The state entering the TRUE arm of `if (cond)`, for a validator: a
+     * positive `isMaster` test on the pure identity (the fleet carve-out) is a
+     * master path; a condition that is truthy only when the target parameter is
+     * owned by the identity (posBinds) is a bound path. */
+    positiveArm(cond, s) {
+        const v = this.v;
+        if (!v)
+            return s;
+        if (positiveMasterTest(cond, v.pure))
+            return { ...s, guarded: true, master: true };
+        if (this.posBinds(cond, s.tainted))
+            return { ...s, guarded: true, bound: true };
+        return s;
+    }
+    /** STRONG binding, for a name-free validator only: `cond` can be truthy only
+     * when the target parameter equals / lies under an identity-derived value,
+     * or a predicate judged on its body says the identity owns it. (#37's
+     * allowlisted helper walk credits any identity condition that merely READS
+     * the parameter; a function the doctor did not name earns no such latitude.) */
+    posBinds(cond, tainted) {
+        const v = this.v;
+        if (!v)
+            return false;
+        return (this.bindingPredicate(cond, v) ||
+            bindsByEquality(cond, tainted, this.params));
+    }
+    /** `cond` FALSE implies the target is bound: `!P(…)`, `x !== own`, or a
+     * disjunction any one of whose negations binds. */
+    negBinds(cond, tainted) {
+        const c = unwrap(cond);
+        if (ts.isPrefixUnaryExpression(c) &&
+            c.operator === ts.SyntaxKind.ExclamationToken)
+            return this.posBinds(c.operand, tainted);
+        if (!ts.isBinaryExpression(c))
+            return false;
+        const op = c.operatorToken.kind;
+        if (op === ts.SyntaxKind.BarBarToken)
+            return this.negBinds(c.left, tainted) || this.negBinds(c.right, tainted);
+        if (op === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+            op === ts.SyntaxKind.ExclamationEqualsToken) {
+            const side = (a, b) => readsAny(a, this.params) &&
+                !dependsOnIdentity(a, tainted) &&
+                dependsOnIdentity(b, tainted) &&
+                !readsAny(b, this.params);
+            return side(c.left, c.right) || side(c.right, c.left);
+        }
+        return false;
+    }
+    /** `cond` FALSE implies the caller is the fleet master: `!scope.isMaster`, or
+     * a disjunction carrying it. */
+    negMaster(cond, pure) {
+        const c = unwrap(cond);
+        if (ts.isPrefixUnaryExpression(c) &&
+            c.operator === ts.SyntaxKind.ExclamationToken)
+            return positiveMasterTest(c.operand, pure);
+        if (ts.isBinaryExpression(c) &&
+            c.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+            return this.negMaster(c.left, pure) || this.negMaster(c.right, pure);
+        return false;
+    }
+    bindingPredicate(cond, v) {
+        const c = unwrap(cond);
+        if (ts.isBinaryExpression(c) &&
+            c.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
+            return (this.bindingPredicate(c.left, v) || this.bindingPredicate(c.right, v));
+        if (!ts.isCallExpression(c) || !ts.isIdentifier(c.expression))
+            return false;
+        const args = c.arguments.map(unwrap);
+        const i = args.findIndex((a) => ts.isIdentifier(a) && v.pure.has(a.text));
+        const j = args.findIndex((a) => ts.isIdentifier(a) && this.params.has(a.text));
+        if (i < 0 || j < 0)
+            return false;
+        const d = v.resolve(c.expression.text);
+        if (!d)
+            return false;
+        // An un-awaited async predicate is a Promise: always truthy.
+        if (!awaitedCall(cond) && returnsPromise(d.fn))
+            return false;
+        return judgePredicateFunction(d.fn, i, j).verdict === "honoured";
+    }
+    /** A statement `[await] Q(…)` whose callee the tree defines: Q, walked as a
+     * validator with the identity and target this call hands it, either binds
+     * the target on every normal exit, admits the fleet master only, or never
+     * returns. `null` = not such a call (the statement is read as before). */
+    callStatement(e, s) {
+        const v = this.v;
+        if (!v)
+            return null;
+        const c = unwrap(e);
+        if (!ts.isCallExpression(c) || !ts.isIdentifier(c.expression))
+            return null;
+        const d = v.resolve(c.expression.text);
+        if (!d)
+            return null;
+        // An async validator that is not awaited refuses in a promise nobody
+        // waits on: the statement after it runs either way.
+        if (!awaitedCall(e) && returnsPromise(d.fn))
+            return null;
+        const args = c.arguments.map(unwrap);
+        const identityIdx = args.findIndex((a) => ts.isIdentifier(a) && v.pure.has(a.text));
+        const k = args.findIndex((a) => ts.isIdentifier(a) && this.params.has(a.text));
+        const sum = (boundIdx) => summarizeValidator(d.fn, {
+            boundIdx,
+            identityIdx: identityIdx < 0 ? undefined : identityIdx,
+            callArgs: args,
+            resolve: d.resolve,
+            key: d.key,
+            depth: v.depth + 1,
+        });
+        const master = sum(undefined);
+        if (master.ok && master.never)
+            return { normal: null, returns: [], throws: 1 };
+        let out = s;
+        if (master.ok && master.exitsMaster)
+            out = { ...out, guarded: true, master: true };
+        if (k >= 0) {
+            const b = sum(k);
+            if (b.ok && b.exitsBound)
+                out = { ...out, guarded: true, bound: true };
+        }
+        return out === s ? null : { normal: out, returns: [], throws: 0 };
+    }
+    /** Taint every local assigned from an identity-dependent expression. */
+    assign(s, names, rhs) {
+        if (!dependsOnIdentity(rhs, s.tainted)) {
+            // Re-assigned from something else: no longer the identity.
+            if (!names.some((n) => s.tainted.has(n)))
+                return s;
+            const t = new Set(s.tainted);
+            for (const n of names)
+                t.delete(n);
+            return { ...s, tainted: t };
+        }
+        return { ...s, tainted: new Set([...s.tainted, ...names]) };
+    }
+    expression(e, s) {
+        let out = s;
+        walkOwn(e, (x) => {
+            if (ts.isBinaryExpression(x) &&
+                x.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                ts.isIdentifier(x.left))
+                out = this.assign(out, [x.left.text], x.right);
+        });
+        return out;
+    }
+    list(stmts, s) {
+        let normal = s;
+        const returns = [];
+        let throws = 0;
+        for (const st of stmts) {
+            if (!normal)
+                break; // unreachable code adds no path
+            const f = this.stmt(st, normal);
+            returns.push(...f.returns);
+            throws += f.throws;
+            normal = f.normal;
+        }
+        return { normal, returns, throws };
+    }
+    stmt(st, s) {
+        const none = { returns: [], throws: 0 };
+        if (ts.isBlock(st))
+            return this.list(st.statements, s);
+        if (ts.isVariableStatement(st)) {
+            let out = s;
+            for (const d of st.declarationList.declarations)
+                if (d.initializer)
+                    out = this.assign(this.expression(d.initializer, out), bindingNames(d.name, []), d.initializer);
+            return { normal: out, ...none };
+        }
+        if (ts.isExpressionStatement(st)) {
+            const after = this.expression(st.expression, s);
+            return (this.callStatement(st.expression, after) ?? { normal: after, ...none });
+        }
+        if (ts.isReturnStatement(st))
+            return { normal: null, returns: [{ state: s, node: st }], throws: 0 };
+        if (ts.isThrowStatement(st))
+            return { normal: null, returns: [], throws: 1 };
+        if (ts.isIfStatement(st)) {
+            const cs = this.expression(st.expression, s);
+            if (this.v) {
+                // A condition fixed by the call site takes one arm only.
+                const k = constTruth(st.expression, this.v.consts);
+                if (k === true)
+                    return this.stmt(st.thenStatement, cs);
+                if (k === false)
+                    return st.elseStatement
+                        ? this.stmt(st.elseStatement, cs)
+                        : { normal: cs, ...none };
+            }
+            const a = this.stmt(st.thenStatement, this.positiveArm(st.expression, cs));
+            const b = st.elseStatement
+                ? this.stmt(st.elseStatement, cs)
+                : { normal: cs, returns: [], throws: 0 };
+            const alwaysThrows = (f) => f.normal === null && f.returns.length === 0 && f.throws > 0;
+            const v = this.v;
+            if (v && dependsOnIdentity(st.expression, cs.tainted)) {
+                // Validator walk: what the continuing arm KNOWS, by polarity.
+                const cond = st.expression;
+                const strong = (p, holds) => p && {
+                    ...p,
+                    guarded: true,
+                    bound: p.bound ||
+                        (holds
+                            ? this.posBinds(cond, cs.tainted)
+                            : this.negBinds(cond, cs.tainted)),
+                    master: p.master ||
+                        (holds
+                            ? positiveMasterTest(cond, v.pure)
+                            : this.negMaster(cond, v.pure)),
+                };
+                if (alwaysThrows(a))
+                    b.normal = strong(b.normal, false);
+                else if (alwaysThrows(b))
+                    a.normal = strong(a.normal, true);
+            }
+            else if (dependsOnIdentity(st.expression, cs.tainted)) {
+                const guard = (p) => p && {
+                    ...p,
+                    guarded: true,
+                    bound: p.bound ||
+                        (this.params.size > 0 && readsAny(st.expression, this.params)),
+                    master: p.master || testsIsMaster(st.expression, cs.tainted),
+                    absent: p.absent || !readsAny(st.expression, this.params),
+                };
+                // the arm that continues past a branch whose other arm always refuses
+                if (alwaysThrows(a))
+                    b.normal = guard(b.normal);
+                else if (alwaysThrows(b))
+                    a.normal = guard(a.normal);
+            }
+            return {
+                normal: merge(a.normal, b.normal),
+                returns: [...a.returns, ...b.returns],
+                throws: a.throws + b.throws,
+            };
+        }
+        if (ts.isTryStatement(st)) {
+            if (st.finallyBlock)
+                throw new Undecidable("a `finally` block (not modelled)");
+            const body = this.list(st.tryBlock.statements, s);
+            if (!st.catchClause)
+                return body;
+            // Any statement of the try block may raise before its guard ran, so the
+            // catch is entered from the state at the try's entry.
+            let cs = s;
+            const v = st.catchClause.variableDeclaration;
+            if (v) {
+                const t = new Set(cs.tainted);
+                for (const n of bindingNames(v.name, []))
+                    t.delete(n);
+                cs = { ...cs, tainted: t };
+            }
+            const c = this.list(st.catchClause.block.statements, cs);
+            return {
+                normal: merge(body.normal, c.normal),
+                returns: [...body.returns, ...c.returns],
+                throws: c.throws,
+            };
+        }
+        if (ts.isForStatement(st) ||
+            ts.isForOfStatement(st) ||
+            ts.isForInStatement(st) ||
+            ts.isWhileStatement(st) ||
+            ts.isDoStatement(st)) {
+            if (hasAbrupt(st))
+                throw new Undecidable("a loop carrying return/throw/break/continue");
+            // Runs zero or more times: nothing it does can be counted on.
+            const once = this.stmt(st.statement, s);
+            return { normal: merge(s, once.normal), ...none };
+        }
+        if (ts.isEmptyStatement(st) ||
+            ts.isFunctionDeclaration(st) ||
+            ts.isClassDeclaration(st) ||
+            ts.isTypeAliasDeclaration(st) ||
+            ts.isInterfaceDeclaration(st))
+            return { normal: s, ...none };
+        throw new Undecidable(`a ${ts.SyntaxKind[st.kind]} (not modelled)`);
+    }
+}
+function lineOf(n) {
+    const sf = n.getSourceFile();
+    return sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
+}
+/** Judge one helper function on its control flow. */
+export function judgeHelperFunction(fn, kind) {
+    if (!fn.body || !ts.isBlock(fn.body))
+        return {
+            verdict: "could-not-judge",
+            why: "an expression-bodied helper (not modelled)",
+        };
+    // The first parameter is the Convex context; the rest are what the helper
+    // binds the identity to.
+    const params = new Set();
+    for (const p of fn.parameters.slice(1))
+        for (const n of bindingNames(p.name, []))
+            params.add(n);
+    const start = {
+        tainted: new Set(),
+        guarded: false,
+        bound: false,
+        master: false,
+        absent: false,
+    };
+    let flow;
+    try {
+        flow = new Walker(params).list(fn.body.statements, start);
+    }
+    catch (e) {
+        if (e instanceof Undecidable)
+            return { verdict: "could-not-judge", why: `its body has ${e.message}` };
+        throw e;
+    }
+    const exits = flow.returns.map((r) => ({
+        state: r.state,
+        where: `the \`return\` at line ${lineOf(r.node)}`,
+    }));
+    if (flow.normal)
+        exits.push({ state: flow.normal, where: "the end of its body" });
+    if (exits.length === 0)
+        return {
+            verdict: "refused",
+            why: "it never completes normally (it refuses every caller), so it guards nothing",
+        };
+    for (const x of exits) {
+        if (!x.state.guarded)
+            return {
+                verdict: "refused",
+                why: `a path reaches ${x.where} without passing a refusal conditioned on the verified identity`,
+            };
+        if (kind === "binds-arg" && !x.state.bound)
+            return {
+                verdict: "refused",
+                why: `a path reaches ${x.where} without a refusal comparing the identity with the helper's target parameter`,
+            };
+        if (kind === "master-only" && !x.state.master)
+            return {
+                verdict: "refused",
+                why: `a path reaches ${x.where} without a refusal testing isMaster on the verified identity`,
+            };
+    }
+    return { verdict: "honoured" };
+}
+/** Every definition, in `source`, of a helper named in `kinds`. */
+export function findHelperDefinitions(fileName, source, kinds) {
+    const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const out = [];
+    const exportedMod = (n) => ts.canHaveModifiers(n) &&
+        (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    for (const st of sf.statements) {
+        if (ts.isFunctionDeclaration(st) && st.name && st.name.text in kinds) {
+            out.push({
+                name: st.name.text,
+                line: lineOf(st),
+                exported: exportedMod(st),
+                judgement: judgeHelperFunction(st, kinds[st.name.text]),
+            });
+        }
+        else if (ts.isVariableStatement(st)) {
+            for (const d of st.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name) || !(d.name.text in kinds))
+                    continue;
+                const init = d.initializer;
+                const judgement = init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))
+                    ? judgeHelperFunction(init, kinds[d.name.text])
+                    : {
+                        verdict: "could-not-judge",
+                        why: "its definition is not a function literal",
+                    };
+                out.push({
+                    name: d.name.text,
+                    line: lineOf(d),
+                    exported: exportedMod(st),
+                    judgement,
+                });
+            }
+        }
+    }
+    return out;
+}
+/** The arguments of each `await <helper>(…)` that is a DIRECT statement of the
+ * handler `name` (`export const name = mutation({ handler: … })`) and starts
+ * before `beforeLine`. A helper call nested in a branch, a try, or a closure of
+ * the handler is not a statement every path runs, so it is not returned.
+ * `null` = the handler's body could not be located in the file. */
+export function topLevelHelperCalls(fileName, source, handlerName, 
+/** `null` = any identifier callee (judged by the caller on its body). */
+helpers, beforeLine) {
+    const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let body;
+    for (const st of sf.statements) {
+        if (!ts.isVariableStatement(st))
+            continue;
+        for (const d of st.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name) || d.name.text !== handlerName)
+                continue;
+            const init = d.initializer;
+            if (!init || !ts.isCallExpression(init))
+                continue;
+            const cfg = init.arguments[0];
+            if (!cfg || !ts.isObjectLiteralExpression(cfg))
+                continue;
+            for (const p of cfg.properties) {
+                if (!p.name || !ts.isIdentifier(p.name) || p.name.text !== "handler")
+                    continue;
+                const fn = ts.isPropertyAssignment(p) ? p.initializer : p;
+                if ((ts.isArrowFunction(fn) ||
+                    ts.isFunctionExpression(fn) ||
+                    ts.isMethodDeclaration(fn)) &&
+                    fn.body &&
+                    ts.isBlock(fn.body))
+                    body = fn.body;
+            }
+        }
+    }
+    if (!body)
+        return null;
+    const out = [];
+    for (const st of body.statements) {
+        if (lineOf(st) >= beforeLine)
+            break;
+        let e;
+        if (ts.isExpressionStatement(st))
+            e = st.expression;
+        else if (ts.isVariableStatement(st))
+            e = st.declarationList.declarations[0]?.initializer;
+        if (!e || !ts.isAwaitExpression(e))
+            continue;
+        const call = e.expression;
+        if (ts.isCallExpression(call) &&
+            ts.isIdentifier(call.expression) &&
+            (helpers === null || helpers.has(call.expression.text)))
+            out.push({
+                name: call.expression.text,
+                args: call.arguments.map((a) => a.getText(sf)).join(", "),
+                argNodes: call.arguments,
+                line: lineOf(st),
+            });
+    }
+    return out;
+}
+const parse = (fileName, source) => ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+/** Every top-level function declaration and `const f = (…) => {…}` /
+ * `function (…) {…}` of a file. */
+export function topLevelFunctions(fileName, source) {
+    const sf = parse(fileName, source);
+    const out = [];
+    const exportedMod = (n) => ts.canHaveModifiers(n) &&
+        (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    for (const st of sf.statements) {
+        if (ts.isFunctionDeclaration(st) && st.name && st.body)
+            out.push({
+                name: st.name.text,
+                line: lineOf(st),
+                exported: exportedMod(st),
+                fn: st,
+            });
+        else if (ts.isVariableStatement(st))
+            for (const d of st.declarationList.declarations) {
+                const init = d.initializer;
+                if (ts.isIdentifier(d.name) &&
+                    init &&
+                    (ts.isArrowFunction(init) || ts.isFunctionExpression(init)))
+                    out.push({
+                        name: d.name.text,
+                        line: lineOf(d),
+                        exported: exportedMod(st),
+                        fn: init,
+                    });
+            }
+    }
+    return out;
+}
+/** Strip `await`, parentheses, `!` non-null and `as` casts. */
+function unwrap(e) {
+    let x = e;
+    for (;;) {
+        if (ts.isAwaitExpression(x) || ts.isParenthesizedExpression(x))
+            x = x.expression;
+        else if (ts.isNonNullExpression(x) || ts.isAsExpression(x))
+            x = x.expression;
+        else
+            return x;
+    }
+}
+/** Locals of `fn`'s own body bound ONLY to the verified identity: a `const`/
+ * `let` initialised from an identity read (or from another such local) and
+ * never re-assigned. A value BUILT from the identity (`{ ...scope, orgSlug: x }`)
+ * is not the identity. */
+function pureIdentityLocals(fn, seed = new Set()) {
+    const decls = new Map();
+    const reassigned = new Set();
+    if (!fn.body)
+        return new Set(seed);
+    walkOwn(fn.body, (x) => {
+        if (ts.isVariableDeclaration(x) && ts.isIdentifier(x.name) && x.initializer)
+            decls.set(x.name.text, x.initializer);
+        if (ts.isBinaryExpression(x) &&
+            x.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            x.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+            ts.isIdentifier(x.left))
+            reassigned.add(x.left.text);
+    });
+    const pure = new Set([...seed].filter((n) => !reassigned.has(n)));
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [n, init] of decls) {
+            if (pure.has(n) || reassigned.has(n))
+                continue;
+            const u = unwrap(init);
+            if (isIdentityRead(u) || (ts.isIdentifier(u) && pure.has(u.text))) {
+                pure.add(n);
+                grew = true;
+            }
+        }
+    }
+    return pure;
+}
+/** Judge a function as an IDENTITY RESOLVER (shape 1 above). */
+export function judgeResolverFunction(fn) {
+    if (!fn.body || !ts.isBlock(fn.body))
+        return {
+            verdict: "could-not-judge",
+            why: "an expression-bodied helper (not modelled)",
+        };
+    const params = new Set();
+    for (const p of fn.parameters.slice(1))
+        for (const n of bindingNames(p.name, []))
+            params.add(n);
+    let flow;
+    try {
+        flow = new Walker(params).list(fn.body.statements, {
+            tainted: new Set(),
+            guarded: false,
+            bound: false,
+            master: false,
+            absent: false,
+        });
+    }
+    catch (e) {
+        if (e instanceof Undecidable)
+            return { verdict: "could-not-judge", why: `its body has ${e.message}` };
+        throw e;
+    }
+    if (flow.normal)
+        return {
+            verdict: "refused",
+            why: "a path falls off the end of its body (returns undefined, not the identity)",
+        };
+    if (flow.returns.length === 0)
+        return { verdict: "refused", why: "it never returns a value" };
+    const pure = pureIdentityLocals(fn);
+    for (const r of flow.returns) {
+        const where = `the \`return\` at line ${lineOf(r.node)}`;
+        const e = ts.isReturnStatement(r.node) ? r.node.expression : undefined;
+        const u = e ? unwrap(e) : undefined;
+        if (!u || !(isIdentityRead(u) || (ts.isIdentifier(u) && pure.has(u.text))))
+            return {
+                verdict: "refused",
+                why: `${where} hands back a value that is not itself the verified identity/scope`,
+            };
+        if (!r.state.absent)
+            return {
+                verdict: "refused",
+                why: `a path reaches ${where} without refusing an absent identity (a guard on the identity alone)`,
+            };
+    }
+    return { verdict: "honoured" };
+}
+const MAX_VALIDATOR_DEPTH = 6;
+const validatorMemo = new WeakMap();
+export function summarizeValidator(fn, o) {
+    if (o.depth > MAX_VALIDATOR_DEPTH)
+        return { ok: false, why: "validator nesting deeper than modelled" };
+    if (!fn.body || !ts.isBlock(fn.body))
+        return { ok: false, why: "an expression-bodied function (not modelled)" };
+    const consts = new Map();
+    fn.parameters.forEach((p, i) => {
+        if (!ts.isIdentifier(p.name))
+            return;
+        if (i >= o.callArgs.length)
+            consts.set(p.name.text, null);
+        else {
+            const a = unwrap(o.callArgs[i]);
+            if (ts.isObjectLiteralExpression(a))
+                consts.set(p.name.text, a);
+        }
+    });
+    const sig = [
+        o.boundIdx,
+        o.identityIdx,
+        [...consts].map(([n, x]) => `${n}=${x ? x.getText() : "undefined"}`),
+    ].join("|");
+    let memo = validatorMemo.get(fn);
+    if (!memo) {
+        memo = new Map();
+        validatorMemo.set(fn, memo);
+    }
+    const hit = memo.get(sig);
+    if (hit)
+        return hit;
+    // A cycle reads as undecided while it is being judged.
+    memo.set(sig, { ok: false, why: "a recursive validator (not modelled)" });
+    const nameAt = (i) => {
+        if (i === undefined)
+            return undefined;
+        const p = fn.parameters[i];
+        return p && ts.isIdentifier(p.name) ? p.name.text : null;
+    };
+    const boundName = nameAt(o.boundIdx);
+    const identityName = nameAt(o.identityIdx);
+    let result;
+    if (boundName === null || identityName === null)
+        result = { ok: false, why: "a parameter that is not a plain identifier" };
+    else {
+        let reassigned = false;
+        walkOwn(fn.body, (x) => {
+            if (ts.isBinaryExpression(x) &&
+                x.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                x.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+                ts.isIdentifier(x.left) &&
+                (x.left.text === boundName || x.left.text === identityName))
+                reassigned = true;
+        });
+        if (reassigned)
+            result = {
+                ok: false,
+                why: "it re-assigns its scope or target parameter (not modelled)",
+            };
+        else {
+            const seed = new Set(identityName ? [identityName] : []);
+            const pure = pureIdentityLocals(fn, seed);
+            const walker = new Walker(new Set(boundName ? [boundName] : []), {
+                consts,
+                pure,
+                resolve: o.resolve,
+                depth: o.depth,
+            });
+            try {
+                const flow = walker.list(fn.body.statements, {
+                    tainted: seed,
+                    guarded: false,
+                    bound: false,
+                    master: false,
+                    absent: false,
+                });
+                const exits = flow.returns.map((r) => r.state);
+                if (flow.normal)
+                    exits.push(flow.normal);
+                result = {
+                    ok: true,
+                    exitsBound: boundName !== undefined &&
+                        exits.every((x) => x.master || (x.guarded && x.bound)),
+                    exitsMaster: exits.every((x) => x.master),
+                    never: exits.length === 0,
+                };
+            }
+            catch (e) {
+                if (!(e instanceof Undecidable))
+                    throw e;
+                result = { ok: false, why: `its body has ${e.message}` };
+            }
+        }
+    }
+    memo.set(sig, result);
+    return result;
+}
+/** `cond` is a POSITIVE test of `isMaster` on the identity (alone or as a
+ * conjunct): the arm it guards runs for the fleet master only. */
+function positiveMasterTest(cond, tainted) {
+    const c = unwrap(cond);
+    if (ts.isBinaryExpression(c) &&
+        c.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
+        return (positiveMasterTest(c.left, tainted) ||
+            positiveMasterTest(c.right, tainted));
+    if (ts.isBinaryExpression(c) &&
+        (c.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+            c.operatorToken.kind === ts.SyntaxKind.EqualsEqualsToken) &&
+        c.right.kind === ts.SyntaxKind.TrueKeyword)
+        return positiveMasterTest(c.left, tainted);
+    return (ts.isPropertyAccessExpression(c) &&
+        c.name.text === "isMaster" &&
+        dependsOnIdentity(c.expression, tainted));
+}
+/** `e` can only be truthy when the bound value EQUALS an identity-derived one,
+ * or lies UNDER an identity-derived prefix (`ns.startsWith(`${ownPrefix}/`)`).
+ * A conjunction binds when either conjunct does; a disjunction only when BOTH
+ * disjuncts do (either one alone admits the caller). */
+function bindsByEquality(e, tainted, bound) {
+    const x = unwrap(e);
+    // The bound value is the receiver, the identity-derived value the argument:
+    // `<bound>.startsWith(<identity>)`. A fallback inside the prefix
+    // (`scope.orgSlug ?? ""`) can widen it to everything, so it binds nothing.
+    if (ts.isCallExpression(x) &&
+        ts.isPropertyAccessExpression(x.expression) &&
+        x.expression.name.text === "startsWith" &&
+        x.arguments.length === 1) {
+        const recv = x.expression.expression;
+        const arg = unwrap(x.arguments[0]);
+        const fallback = ts.isBinaryExpression(arg) &&
+            (arg.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
+                arg.operatorToken.kind === ts.SyntaxKind.BarBarToken);
+        return (!fallback &&
+            readsAny(recv, bound) &&
+            !dependsOnIdentity(recv, tainted) &&
+            dependsOnIdentity(arg, tainted) &&
+            !readsAny(arg, bound));
+    }
+    if (!ts.isBinaryExpression(x))
+        return false;
+    const op = x.operatorToken.kind;
+    if (op === ts.SyntaxKind.AmpersandAmpersandToken)
+        return (bindsByEquality(x.left, tainted, bound) ||
+            bindsByEquality(x.right, tainted, bound));
+    if (op === ts.SyntaxKind.BarBarToken)
+        return (bindsByEquality(x.left, tainted, bound) &&
+            bindsByEquality(x.right, tainted, bound));
+    if (op !== ts.SyntaxKind.EqualsEqualsEqualsToken &&
+        op !== ts.SyntaxKind.EqualsEqualsToken)
+        return false;
+    const side = (a, b) => readsAny(a, bound) &&
+        !dependsOnIdentity(a, tainted) &&
+        dependsOnIdentity(b, tainted) &&
+        !readsAny(b, bound);
+    return side(x.left, x.right) || side(x.right, x.left);
+}
+const isFalsyLiteral = (e) => {
+    if (!e)
+        return true;
+    const u = unwrap(e);
+    return (u.kind === ts.SyntaxKind.FalseKeyword ||
+        u.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(u) && u.text === "undefined"));
+};
+/** Judge a function as a REFUSING PREDICATE (shape 2 above): parameter
+ * `identityIdx` receives the caller's verified scope, `boundIdx` the value the
+ * caller then writes. */
+export function judgePredicateFunction(fn, identityIdx, boundIdx) {
+    if (!fn.body || !ts.isBlock(fn.body))
+        return {
+            verdict: "could-not-judge",
+            why: "an expression-bodied predicate (not modelled)",
+        };
+    const ip = fn.parameters[identityIdx];
+    const bp = fn.parameters[boundIdx];
+    if (!ip || !bp || !ts.isIdentifier(ip.name) || !ts.isIdentifier(bp.name))
+        return {
+            verdict: "could-not-judge",
+            why: "its scope/value parameters are not plain identifiers",
+        };
+    const tainted = new Set([ip.name.text]);
+    const bound = new Set([bp.name.text]);
+    let reassigned = false;
+    walkOwn(fn.body, (x) => {
+        if (ts.isBinaryExpression(x) &&
+            x.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            x.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+            ts.isIdentifier(x.left) &&
+            (tainted.has(x.left.text) || bound.has(x.left.text)))
+            reassigned = true;
+    });
+    if (reassigned)
+        return {
+            verdict: "could-not-judge",
+            why: "it re-assigns its scope or value parameter (not modelled)",
+        };
+    const judgeReturn = (e, cond, line) => {
+        if (isFalsyLiteral(e))
+            return null;
+        const u = unwrap(e);
+        if (u.kind === ts.SyntaxKind.TrueKeyword) {
+            if (cond && positiveMasterTest(cond, tainted))
+                return null;
+            return {
+                verdict: "refused",
+                why: `the \`return true\` at line ${line} is not conditioned on isMaster of the scope parameter — it admits a caller whose scope does not own the value`,
+            };
+        }
+        if (bindsByEquality(u, tainted, bound))
+            return null;
+        return {
+            verdict: "refused",
+            why: `the \`return\` at line ${line} can be truthy without the value equalling an identity-derived one`,
+        };
+    };
+    for (const st of fn.body.statements) {
+        if (ts.isVariableStatement(st)) {
+            for (const d of st.declarationList.declarations) {
+                if (!d.initializer)
+                    continue;
+                const names = bindingNames(d.name, []);
+                if (dependsOnIdentity(d.initializer, tainted))
+                    for (const n of names)
+                        tainted.add(n);
+                else if (ts.isIdentifier(unwrap(d.initializer)) &&
+                    bound.has(unwrap(d.initializer).text))
+                    for (const n of names)
+                        bound.add(n);
+            }
+            continue;
+        }
+        if (ts.isIfStatement(st) && !st.elseStatement) {
+            let ret = st.thenStatement;
+            if (ts.isBlock(ret) && ret.statements.length === 1)
+                ret = ret.statements[0];
+            if (!ts.isReturnStatement(ret))
+                return {
+                    verdict: "could-not-judge",
+                    why: `the \`if\` at line ${lineOf(st)} does not simply return (not modelled)`,
+                };
+            const v = judgeReturn(ret.expression, st.expression, lineOf(ret));
+            if (v)
+                return v;
+            continue;
+        }
+        if (ts.isReturnStatement(st)) {
+            return (judgeReturn(st.expression, undefined, lineOf(st)) ?? {
+                verdict: "honoured",
+            });
+        }
+        return {
+            verdict: "could-not-judge",
+            why: `its body has a ${ts.SyntaxKind[st.kind]} (not modelled)`,
+        };
+    }
+    // Falling off the end returns undefined — a refusal.
+    return { verdict: "honoured" };
+}
+/** A statement that always throws: `throw …` or a block whose LAST statement
+ * is a throw and that holds no `return` of its own. */
+function alwaysThrowsStmt(st) {
+    if (ts.isThrowStatement(st))
+        return true;
+    if (!ts.isBlock(st) || st.statements.length === 0)
+        return false;
+    let ret = false;
+    walkOwn(st, (x) => {
+        if (ts.isReturnStatement(x))
+            ret = true;
+    });
+    return !ret && ts.isThrowStatement(st.statements[st.statements.length - 1]);
+}
+/** Read the direct statements of handler `name` before `beforeLine`. `null`
+ * when the handler's body cannot be located. */
+export function readHandlerGuards(fileName, source, handlerName, beforeLine) {
+    const sf = parse(fileName, source);
+    let body;
+    for (const st of sf.statements) {
+        if (!ts.isVariableStatement(st))
+            continue;
+        for (const d of st.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name) || d.name.text !== handlerName)
+                continue;
+            const init = d.initializer;
+            if (!init || !ts.isCallExpression(init))
+                continue;
+            const cfg = init.arguments[0];
+            if (!cfg || !ts.isObjectLiteralExpression(cfg))
+                continue;
+            for (const p of cfg.properties) {
+                if (!p.name || !ts.isIdentifier(p.name) || p.name.text !== "handler")
+                    continue;
+                const fn = ts.isPropertyAssignment(p) ? p.initializer : p;
+                if ((ts.isArrowFunction(fn) ||
+                    ts.isFunctionExpression(fn) ||
+                    ts.isMethodDeclaration(fn)) &&
+                    fn.body &&
+                    ts.isBlock(fn.body))
+                    body = fn.body;
+            }
+        }
+    }
+    if (!body)
+        return null;
+    const out = { consts: new Map(), refusals: [] };
+    for (const st of body.statements) {
+        if (lineOf(st) >= beforeLine)
+            break;
+        if (ts.isVariableStatement(st) &&
+            (st.declarationList.flags & ts.NodeFlags.Const) !== 0) {
+            for (const d of st.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name) || !d.initializer)
+                    continue;
+                const u = unwrap(d.initializer);
+                const awaited = ts.isAwaitExpression(d.initializer)
+                    ? unwrap(d.initializer)
+                    : undefined;
+                out.consts.set(d.name.text, {
+                    identityRead: isIdentityRead(u),
+                    awaitedCallee: awaited &&
+                        ts.isCallExpression(awaited) &&
+                        ts.isIdentifier(awaited.expression)
+                        ? awaited.expression.text
+                        : undefined,
+                });
+            }
+            continue;
+        }
+        if (!ts.isIfStatement(st) || st.elseStatement)
+            continue;
+        if (!alwaysThrowsStmt(st.thenStatement))
+            continue;
+        const c = unwrap(st.expression);
+        if (!ts.isPrefixUnaryExpression(c) ||
+            c.operator !== ts.SyntaxKind.ExclamationToken)
+            continue;
+        const call = unwrap(c.operand);
+        if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression))
+            continue;
+        out.refusals.push({
+            predicate: call.expression.text,
+            args: call.arguments.map((a) => {
+                const ua = unwrap(a);
+                return {
+                    text: ua.getText(sf),
+                    ident: ts.isIdentifier(ua) ? ua.text : undefined,
+                    memberBase: ts.isPropertyAccessExpression(ua) && ts.isIdentifier(ua.expression)
+                        ? ua.expression.text
+                        : undefined,
+                };
+            }),
+            line: lineOf(st),
+        });
+    }
+    return out;
+}
+export function conditionalBoundaries(text, fields) {
+    const sf = parse("write-site.ts", text);
+    const out = [];
+    const readsArgs = (e) => readsAny(e, new Set(["args"]));
+    const visit = (n) => {
+        if (ts.isPropertyAssignment(n) &&
+            ts.isIdentifier(n.name) &&
+            fields.has(n.name.text)) {
+            const c = unwrap(n.initializer);
+            if (ts.isConditionalExpression(c)) {
+                let cond = unwrap(c.condition);
+                if (ts.isBinaryExpression(cond) &&
+                    cond.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken &&
+                    cond.right.kind === ts.SyntaxKind.TrueKeyword)
+                    cond = unwrap(cond.left);
+                out.push({
+                    field: n.name.text,
+                    masterBase: ts.isPropertyAccessExpression(cond) &&
+                        cond.name.text === "isMaster" &&
+                        ts.isIdentifier(cond.expression)
+                        ? cond.expression.text
+                        : undefined,
+                    trueReadsArgs: readsArgs(c.whenTrue),
+                    falseReadsArgs: readsArgs(c.whenFalse),
+                });
+            }
+        }
+        n.forEachChild(visit);
+    };
+    visit(sf);
+    return out;
+}