@vantageos/backend-doctor 0.4.2 → 0.4.3

package/dist/build-stamp.json

@@ -1,4 +1,4 @@
 {
-  "sourceDigest": "d45a7d3884b503e47f03d312079a95b864e185f1ea8e0e21d2b8b008f59d020b",
-  "builtAt": "2026-10-11T10:37:03.282Z"
+  "sourceDigest": "bee564e05cd58fc5ee7437de55405225109b8011e71c05eadaa8d507207e505e",
+  "builtAt": "2026-10-11T16:49:36.400Z"
 }

package/dist/detectors/source/contract.js

@@ -3,7 +3,7 @@
 // Same kind as the six in security.ts: each reads the REAL backend SOURCE the
 // engine hands it in `run(tree)` — it does NOT consult the oracle CSV. Every
 // predicate below is derived from the ACTUAL convex source at
-// /root/coding/vantage-memory/convex, NEVER from the standard's §15 prose. Where
+// vantage-peers convex/, NEVER from the standard's §15 prose. Where
 // the standard's illustration disagrees with the source, the SOURCE wins and the
 // detector records the stale line (see R-11's stale note).
 //

package/dist/detectors/source/guard-helper-flow.d.ts

@@ -91,10 +91,14 @@ export declare function summarizeValidator(fn: ts.FunctionLikeDeclaration, o: {
     key: string;
     depth: number;
 }): ValidatorSummary;
+/** Exported for its tests: the definition-side judgement above. */
+export declare function isFleetStandingPredicate(fn: ts.FunctionLikeDeclaration): boolean;
 /** 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 declare function judgePredicateFunction(fn: ts.FunctionLikeDeclaration, identityIdx: number, boundIdx: number): HelperVerdict;
+export declare function judgePredicateFunction(fn: ts.FunctionLikeDeclaration, identityIdx: number, boundIdx: number, 
+/** names seen from `fn`'s file, to credit a fleet-standing predicate */
+resolve?: CallResolver): HelperVerdict;
 /** What a mutation handler's own body declares and refuses before `beforeLine`. */
 export interface HandlerGuards {
     /** Top-level `const` locals: whether bound straight to an identity read, or

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

@@ -30,6 +30,7 @@
 // carrying return/throw/break/continue, a `finally`, an expression-bodied
 // arrow) makes the verdict COULD-NOT-JUDGE — never honoured.
 import * as ts from "typescript";
+import { IDENTITY_PACKAGE } from "./identity-by-id.js";
 class Undecidable extends Error {
 }
 const isFunctionLike = (n) => ts.isFunctionDeclaration(n) ||
@@ -251,7 +252,7 @@ class Walker {
         const v = this.v;
         if (!v)
             return s;
-        if (positiveMasterTest(cond, v.pure))
+        if (positiveMasterTest(cond, v.pure, v.resolve))
             return { ...s, guarded: true, master: true };
         if (this.posBinds(cond, s.tainted))
             return { ...s, guarded: true, bound: true };
@@ -297,7 +298,7 @@ class Walker {
         const c = unwrap(cond);
         if (ts.isPrefixUnaryExpression(c) &&
             c.operator === ts.SyntaxKind.ExclamationToken)
-            return positiveMasterTest(c.operand, pure);
+            return positiveMasterTest(c.operand, pure, this.v?.resolve);
         if (ts.isBinaryExpression(c) &&
             c.operatorToken.kind === ts.SyntaxKind.BarBarToken)
             return this.negMaster(c.left, pure) || this.negMaster(c.right, pure);
@@ -321,7 +322,7 @@ class Walker {
         // 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";
+        return judgePredicateFunction(d.fn, i, j, d.resolve).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
@@ -451,7 +452,7 @@ class Walker {
                             : this.negBinds(cond, cs.tainted)),
                     master: p.master ||
                         (holds
-                            ? positiveMasterTest(cond, v.pure)
+                            ? positiveMasterTest(cond, v.pure, v.resolve)
                             : this.negMaster(cond, v.pure)),
                 };
                 if (alwaysThrows(a))
@@ -918,21 +919,282 @@ export function summarizeValidator(fn, o) {
 }
 /** `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) {
+function positiveMasterTest(cond, tainted, resolve) {
     const c = unwrap(cond);
     if (ts.isBinaryExpression(c) &&
         c.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
-        return (positiveMasterTest(c.left, tainted) ||
-            positiveMasterTest(c.right, tainted));
+        return (positiveMasterTest(c.left, tainted, resolve) ||
+            positiveMasterTest(c.right, tainted, resolve));
     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 positiveMasterTest(c.left, tainted, resolve);
+    if (resolve && fleetStandingCall(c, tainted, resolve))
+        return true;
     return (ts.isPropertyAccessExpression(c) &&
         c.name.text === "isMaster" &&
         dependsOnIdentity(c.expression, tainted));
 }
+// ---------------------------------------------------------------------------
+// THE FLEET STANDING. vantage-peers 6b44c8f (convex/lib/auth.ts) decides
+// "fleet" on `hasFleetStanding(scope)`: a standing `withOrgScope` attaches from
+// what @vantageos/cloud-identity resolved (a `fleet` principal, the
+// `operator-reader` person the package judged an org admin, or the explicit
+// `internal` marker). Read on its definition, that call is the same fleet
+// carve-out as a positive `scope.isMaster` test — never on its name.
+//
+// `F(<identity>)` is credited when F resolves in the tree and its definition:
+//  - takes ONE plain parameter P, handed the identity itself (not a value built
+//    from it), and makes no call;
+//  - reads nothing off P but `P.standing` (directly or through a const);
+//  - can be truthy only through `<standing>.principal… === <literal>` (the kind
+//    of the principal the package produced, or its absence for `internal`);
+//    every other return is a falsy literal, and at least one return reads
+//    `<standing>.principal.kind`;
+//  - returns the principal's ABSENCE (`<standing>.principal === undefined` /
+//    `null`) only inside a branch selected by the grant `internal`: the
+//    `case "internal":` clause of a `switch (<standing>.grant)` that no other
+//    case falls into, or the then-arm of `if (<standing>.grant === "internal")`
+//    (the else-arm of `!==`). An absence returned under `default:`, another
+//    case, an unrelated branch, or a concise arrow body makes every grant that
+//    carries no principal read as fleet, so the predicate is credited nothing.
+//    The guard-clause form (`if (<standing>.grant !== "internal") return false;`
+//    then the absence test) is NOT credited either: only then/else arms and
+//    `case` clauses are read. Fail-closed by design; write the `case` or `if`
+//    form to be credited (Eta on #68, probe V6);
+//  - lives in a file that imports @vantageos/cloud-identity AND produces that
+//    principal: a `principal: { …, kind: x.kind }` built from a parameter whose
+//    declared type is a name imported from the package.
+// A local boolean named the same (reads `isMaster`, returns `true`, reads only
+// `standing.grant`), a body in a file with no package producer, or a name with
+// no definition in the tree is credited nothing.
+// ---------------------------------------------------------------------------
+const standingMemo = new WeakMap();
+function fleetStandingCall(c, tainted, resolve) {
+    if (!ts.isCallExpression(c) || !ts.isIdentifier(c.expression))
+        return false;
+    if (c.arguments.length !== 1)
+        return false;
+    const a = unwrap(c.arguments[0]);
+    if (!ts.isIdentifier(a) || !tainted.has(a.text))
+        return false;
+    const d = resolve(c.expression.text);
+    if (!d)
+        return false;
+    let v = standingMemo.get(d.fn);
+    if (v === undefined) {
+        v = isFleetStandingPredicate(d.fn);
+        standingMemo.set(d.fn, v);
+    }
+    return v;
+}
+const EQ_OPS = new Set([
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+]);
+const NE_OPS = new Set([
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+]);
+const isLiteralValue = (e) => {
+    const u = unwrap(e);
+    return (ts.isStringLiteralLike(u) ||
+        u.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(u) && u.text === "undefined"));
+};
+/** Exported for its tests: the definition-side judgement above. */
+export function isFleetStandingPredicate(fn) {
+    if (fn.parameters.length !== 1)
+        return false;
+    const pn = fn.parameters[0].name;
+    if (!ts.isIdentifier(pn) || !fn.body)
+        return false;
+    const P = pn.text;
+    const sf = fn.getSourceFile();
+    if (!packageProducesPrincipal(sf))
+        return false;
+    // locals bound to `P.standing`
+    const standingLocals = new Set();
+    const isStanding = (e) => {
+        const u = unwrap(e);
+        if (ts.isIdentifier(u))
+            return standingLocals.has(u.text);
+        return (ts.isPropertyAccessExpression(u) &&
+            u.name.text === "standing" &&
+            ts.isIdentifier(unwrap(u.expression)) &&
+            unwrap(u.expression).text === P);
+    };
+    let ok = true;
+    walkOwn(fn.body, (x) => {
+        if (ts.isVariableDeclaration(x)) {
+            if (ts.isIdentifier(x.name) && x.initializer && isStanding(x.initializer))
+                standingLocals.add(x.name.text);
+            else
+                ok = false;
+        }
+        if (ts.isCallExpression(x) || ts.isNewExpression(x))
+            ok = false;
+        if (ts.isBinaryExpression(x) &&
+            x.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            x.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+            ok = false;
+        // nothing read off P but `standing`
+        if (ts.isIdentifier(x) &&
+            x.text === P &&
+            x.parent !== fn.parameters[0] &&
+            !(x.parent &&
+                ts.isPropertyAccessExpression(x.parent) &&
+                x.parent.expression === x &&
+                x.parent.name.text === "standing"))
+            ok = false;
+    });
+    if (!ok)
+        return false;
+    // `<standing>.principal` / `<standing>.principal.kind` against a literal
+    const principalSide = (e) => {
+        const u = unwrap(e);
+        if (!ts.isPropertyAccessExpression(u))
+            return undefined;
+        if (u.name.text === "principal" && isStanding(u.expression))
+            return "principal";
+        const inner = unwrap(u.expression);
+        if (u.name.text === "kind" &&
+            ts.isPropertyAccessExpression(inner) &&
+            inner.name.text === "principal" &&
+            isStanding(inner.expression))
+            return "kind";
+        return undefined;
+    };
+    // `<standing>.grant` compared with the literal "internal"
+    const isGrant = (g) => {
+        const x = unwrap(g);
+        return (ts.isPropertyAccessExpression(x) &&
+            x.name.text === "grant" &&
+            isStanding(x.expression));
+    };
+    const isInternal = (l) => {
+        const x = unwrap(l);
+        return ts.isStringLiteralLike(x) && x.text === "internal";
+    };
+    const isInternalTest = (e, ops) => {
+        const u = unwrap(e);
+        if (!ts.isBinaryExpression(u) || !ops.has(u.operatorToken.kind))
+            return false;
+        return ((isGrant(u.left) && isInternal(u.right)) ||
+            (isGrant(u.right) && isInternal(u.left)));
+    };
+    const endsBranch = (sts) => {
+        const last = sts[sts.length - 1];
+        return (last !== undefined &&
+            (ts.isReturnStatement(last) ||
+                ts.isThrowStatement(last) ||
+                ts.isBreakStatement(last)));
+    };
+    /** Is `at` inside a branch that only the grant `internal` selects? */
+    const underInternal = (at) => {
+        for (let c = at, p = at.parent; p && c !== fn.body;) {
+            if (ts.isCaseClause(p)) {
+                const sw = p.parent.parent;
+                const ix = p.parent.clauses.indexOf(p);
+                const prev = ix > 0 ? p.parent.clauses[ix - 1] : undefined;
+                if (ts.isSwitchStatement(sw) &&
+                    isGrant(sw.expression) &&
+                    isInternal(p.expression) &&
+                    // no other case falls into this one
+                    (prev === undefined || endsBranch(prev.statements)))
+                    return true;
+            }
+            if (ts.isIfStatement(p)) {
+                if (p.thenStatement === c && isInternalTest(p.expression, EQ_OPS))
+                    return true;
+                if (p.elseStatement === c && isInternalTest(p.expression, NE_OPS))
+                    return true;
+            }
+            c = p;
+            p = p.parent;
+        }
+        return false;
+    };
+    let readsKind = false;
+    const truthyOk = (e, at) => {
+        if (isFalsyLiteral(e))
+            return true;
+        const u = unwrap(e);
+        if (!ts.isBinaryExpression(u) || !EQ_OPS.has(u.operatorToken.kind))
+            return false;
+        const side = (isLiteralValue(u.right) && principalSide(u.left)) ||
+            (isLiteralValue(u.left) && principalSide(u.right));
+        if (!side)
+            return false;
+        if (side === "kind")
+            readsKind = true;
+        // the principal's absence is fleet standing for `internal` alone
+        if (side === "principal" && (at === undefined || !underInternal(at)))
+            return false;
+        return true;
+    };
+    if (!ts.isBlock(fn.body))
+        return truthyOk(fn.body, undefined) && readsKind;
+    let returnsAll = true;
+    walkOwn(fn.body, (x) => {
+        if (ts.isReturnStatement(x) && !truthyOk(x.expression, x))
+            returnsAll = false;
+    });
+    return returnsAll && readsKind;
+}
+/** The file imports @vantageos/cloud-identity and builds a standing principal
+ * from a value typed with one of the package's names:
+ * `principal: { …, kind: <param>.kind }` where `<param>: <PackageName>`. */
+function packageProducesPrincipal(sf) {
+    const fromPackage = new Set();
+    for (const st of sf.statements) {
+        if (!ts.isImportDeclaration(st) ||
+            !ts.isStringLiteral(st.moduleSpecifier) ||
+            st.moduleSpecifier.text !== IDENTITY_PACKAGE)
+            continue;
+        const b = st.importClause?.namedBindings;
+        if (b && ts.isNamedImports(b))
+            for (const e of b.elements)
+                fromPackage.add(e.name.text);
+    }
+    if (fromPackage.size === 0)
+        return false;
+    let found = false;
+    const visit = (x) => {
+        if (found)
+            return;
+        if (ts.isPropertyAssignment(x) &&
+            ts.isIdentifier(x.name) &&
+            x.name.text === "kind" &&
+            x.parent?.parent &&
+            ts.isPropertyAssignment(x.parent.parent) &&
+            ts.isIdentifier(x.parent.parent.name) &&
+            x.parent.parent.name.text === "principal") {
+            const v = unwrap(x.initializer);
+            const root = ts.isPropertyAccessExpression(v) && v.name.text === "kind"
+                ? unwrap(v.expression)
+                : undefined;
+            if (root && ts.isIdentifier(root)) {
+                // the parameter it reads, typed with a package name
+                for (let f = x.parent; f; f = f.parent) {
+                    if (!ts.isFunctionLike(f))
+                        continue;
+                    const prm = f.parameters.find((q) => ts.isIdentifier(q.name) && q.name.text === root.text);
+                    if (prm?.type &&
+                        ts.isTypeReferenceNode(prm.type) &&
+                        ts.isIdentifier(prm.type.typeName) &&
+                        fromPackage.has(prm.type.typeName.text))
+                        found = true;
+                    break;
+                }
+            }
+        }
+        x.forEachChild(visit);
+    };
+    visit(sf);
+    return found;
+}
 /** `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
@@ -986,7 +1248,9 @@ const isFalsyLiteral = (e) => {
 /** 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) {
+export function judgePredicateFunction(fn, identityIdx, boundIdx, 
+/** names seen from `fn`'s file, to credit a fleet-standing predicate */
+resolve) {
     if (!fn.body || !ts.isBlock(fn.body))
         return {
             verdict: "could-not-judge",
@@ -1020,7 +1284,7 @@ export function judgePredicateFunction(fn, identityIdx, boundIdx) {
             return null;
         const u = unwrap(e);
         if (u.kind === ts.SyntaxKind.TrueKeyword) {
-            if (cond && positiveMasterTest(cond, tainted))
+            if (cond && positiveMasterTest(cond, tainted, resolve))
                 return null;
             return {
                 verdict: "refused",

package/dist/detectors/source/identity.js

@@ -704,7 +704,7 @@ function predicateBoundValues(h, f, writeLine, fns, src) {
         const d = fns.lookup(r.predicate, f.rel);
         if (!d)
             continue;
-        const v = fns.judge(`P:${d.rel}:${d.f.line}:${i}:${j}`, () => judgePredicateFunction(d.f.fn, i, j));
+        const v = fns.judge(`P:${d.rel}:${d.f.line}:${i}:${j}`, () => judgePredicateFunction(d.f.fn, i, j, fns.callResolver(d.rel)));
         if (v.verdict === "honoured")
             out.set(value, `${r.predicate}() (definition ${d.rel}:${d.f.line})`);
     }

package/dist/detectors/source/local-identity.d.ts

@@ -1,3 +1,4 @@
+import * as ts from "typescript";
 import type { Detector, DetectorResult } from "../../engine-types.js";
 import { type Site, type SrcFile } from "./_scan.js";
 export declare const CR2_ID = "CR-2 no application defines its own identity primitive (tenant resolution, membership, scope filtering, credential validation, identification by name); identity lives only in @vantageos/cloud-identity";
@@ -18,6 +19,10 @@ export interface LocalIdentityScan {
     exempt: Site[];
     cnj: Site[];
 }
+export type DoorCheck = (call: ts.CallExpression) => boolean;
+/** Every reference to `name` in the tree (outside its declaration, imports and
+ * exports) is a call whose result goes into a call argument; at least one. */
+export type CallersForward = (name: string) => boolean;
 export declare function scanLocalIdentity(files: SrcFile[]): LocalIdentityScan;
 export declare function localIdentityResult(scan: LocalIdentityScan): DetectorResult;
 /** The rendered section: EVERY violation, exemption and abstention is named. */

package/dist/detectors/source/local-identity.js

@@ -71,7 +71,7 @@
 // per-module split, and gives a non-zero exit.
 import * as ts from "typescript";
 import { siteCount, withCount } from "../../violation-count.js";
-import { calleeName, dotted, lineOf, parseFile, propRead, propReadResolved, sourceOf, unwrap, walk, } from "./_ast.js";
+import { calleeName, dotted, indexFunctions, lineOf, parseFile, propRead, propReadResolved, sourceOf, unwrap, walk, } from "./_ast.js";
 import { isConvexOrMcp, isJudgeable, } from "./_scan.js";
 import { conformantMappingReads, IDENTITY_PACKAGE, scanR53Detailed, } from "./identity-by-id.js";
 export const CR2_ID = "CR-2 no application defines its own identity primitive (tenant resolution, membership, scope filtering, credential validation, identification by name); identity lives only in @vantageos/cloud-identity";
@@ -301,8 +301,435 @@ const isNormaliserCall = (e) => {
     const u = unwrap(e);
     return ts.isCallExpression(u) && NAME_NORMALISER.test(calleeName(u) ?? "");
 };
+// ---- forwarding a verified claim ------------------------------------------
+//
+// A function that copies a verified-claim field (`oauthCtx.fromAllowList`) into
+// the arguments of a backend call decides nothing from it: the door it calls
+// does the deciding. That is the CONFORMING shape — the claim travels to the
+// one place allowed to judge it. vantage-peers 9e224b2 `rosterClaimArgs`
+// (mcp-server/src/tools.ts:1849) needed an `allow-local-identity:` marker only
+// because the read was taken for a filter.
+//
+// Credited ONLY when, mechanically:
+//  - the call it reaches is a BACKEND DOOR (`doorCheckIn`:
+//    `convex|client|<x>Client .query/.mutation/.action`, `<ctx>.runQuery/
+//    runMutation/runAction`, on a receiver whose BINDING is a parameter, a
+//    package import, a constructed client or a judged client wrapper — never
+//    its name alone, Eta probe V5). A claim handed to a function defined in the tree,
+//    to an unknown helper, or to a storage write is NOT forwarded: that callee
+//    is where the decision would move (`etaAdmits(rosterClaimArgs(ctx), who)`),
+//    and nothing judges it here (Eta on #68, probe V2);
+//  - the read's value reaches a call ARGUMENT (or an object literal that is a
+//    call argument) through nothing but parentheses, casts, non-null, and a
+//    `?? <literal | [] | {}>` / `|| <…>` fallback — any other use (a `.filter`,
+//    `.includes`, a comparison, a local binding) is not a forward;
+//  - or that object literal is RETURNED by a named function (a declaration, or
+//    a `const` bound to an arrow / function expression) and EVERY reference to
+//    that name in the tree is a call whose result is itself handed to a
+//    backend door's argument — directly, spread into the arguments, or spread into an object
+//    literal that is a call argument. A function nobody calls, a callback, a
+//    property-assigned arrow, or one caller that keeps the result (to compare
+//    it, to bind it, to return it) credits nothing: a tool does not clear a
+//    site whose consumer nobody judged;
+//  - the receiver is not the caller's own `args` (a client-supplied list is not
+//    a verified claim);
+//  - the function holding it makes NO identity decision: no equality between
+//    two non-literal values, no equality reading a name or slug field, no
+//    membership test (`includes`/`has`/`indexOf`/`some`/`every`) on a
+//    non-literal, and no refusing `if` (then-arm returns or throws) whose
+//    condition reads a field of the object the claim is read off. Any one of
+//    these keeps the read red.
+const FALLBACK_OPS = new Set([
+    ts.SyntaxKind.QuestionQuestionToken,
+    ts.SyntaxKind.BarBarToken,
+]);
+const isInertFallback = (e) => {
+    const u = unwrap(e);
+    return (isLiteral(u) ||
+        (ts.isArrayLiteralExpression(u) && u.elements.length === 0) ||
+        (ts.isObjectLiteralExpression(u) && u.properties.length === 0));
+};
+const rootIdentifier = (e) => {
+    let x = unwrap(e);
+    for (;;) {
+        const r = propRead(x);
+        if (r)
+            x = unwrap(r.obj);
+        else if (ts.isCallExpression(x))
+            return undefined;
+        else
+            return ts.isIdentifier(x) ? x : undefined;
+    }
+};
+/** The calls allowed to judge a forwarded claim: a Convex door reached
+ * through a client (`convex.query/mutation/action`, `client.…`,
+ * `<x>Client.…`) or from a function context (`<ctx>.runQuery/runMutation/
+ * runAction`). Never a function defined in the tree, never a storage write
+ * (`ctx.db.patch` / `insert`), never an unknown helper: none of those judges
+ * the claim, so handing it to one is not forwarding it.
+ *
+ * The door is recognised by its receiver's BINDING, never by its name alone
+ * (Eta on #68, probe V5: a local `const etaClient = { query: <decides> }`
+ * named like a client). The receiver must be a plain identifier that resolves,
+ * in its own file, to one of:
+ *  - a parameter of an enclosing function (the caller hands the client in);
+ *  - an import from a PACKAGE (a non-relative specifier);
+ *  - a `const` built by a known client constructor (`new ConvexHttpClient(…)`,
+ *    `new ConvexClient(…)`, `new ConvexReactClient(…)`);
+ *  - a `const` built by a CLIENT WRAPPER `W(<receiver>, …)` whose first
+ *    argument itself qualifies, where every definition of `W` in the tree takes
+ *    the client as its first parameter and returns only that parameter or
+ *    `new Proxy(<that parameter>, …)` (vantage-peers `withVerifiedActor`).
+ *    A `W` with no definition in the tree credits nothing.
+ * Anything else is refused: an object literal, an arrow or function, a class,
+ * a `let`, a loop variable, a relative (tree) import, an unresolved name, or a
+ * property-access receiver (`ctx.db.query`, `deps.client.query`).
+ * NOT JUDGED (declared): the handler of a `new Proxy(<client>, handler)`
+ * wrapper; such a handler could decide, and is credited as a pass-through. */
+const CLIENT_DOOR_METHODS = new Set([
+    "query",
+    "mutation",
+    "action",
+]);
+const CTX_DOOR_METHODS = new Set([
+    "runQuery",
+    "runMutation",
+    "runAction",
+]);
+const CLIENT_RECEIVER = /^(convex|client|[A-Za-z_$][\w$]*Client)$/;
+const CLIENT_CONSTRUCTORS = new Set([
+    "ConvexHttpClient",
+    "ConvexClient",
+    "ConvexReactClient",
+]);
+/** Does a binding name (identifier or destructuring pattern) bind `name`? */
+function bindsName(b, name) {
+    if (ts.isIdentifier(b))
+        return b.text === name;
+    const els = b.elements;
+    return els.some((e) => !ts.isOmittedExpression(e) && bindsName(e.name, name));
+}
+/** The declaration `id` resolves to, by lexical scope, in its own file. */
+function bindingOf(id) {
+    const name = id.text;
+    for (let n = id.parent; n; n = n.parent) {
+        if (ts.isFunctionLike(n)) {
+            if (n.parameters.some((prm) => bindsName(prm.name, name)))
+                return { kind: "param" };
+            if (ts.isFunctionExpression(n) && n.name?.text === name)
+                return { kind: "other" };
+        }
+        if ((ts.isForStatement(n) || ts.isForOfStatement(n) || ts.isForInStatement(n)) &&
+            n.initializer &&
+            ts.isVariableDeclarationList(n.initializer) &&
+            n.initializer.declarations.some((d) => bindsName(d.name, name)))
+            return { kind: "other" };
+        if (ts.isCatchClause(n) &&
+            n.variableDeclaration &&
+            bindsName(n.variableDeclaration.name, name))
+            return { kind: "other" };
+        const stmts = ts.isBlock(n) ||
+            ts.isSourceFile(n) ||
+            ts.isModuleBlock(n) ||
+            ts.isCaseClause(n) ||
+            ts.isDefaultClause(n)
+            ? n.statements
+            : undefined;
+        if (!stmts)
+            continue;
+        for (const st of stmts) {
+            if (ts.isVariableStatement(st)) {
+                const isConst = (st.declarationList.flags & ts.NodeFlags.Const) !== 0;
+                for (const d of st.declarationList.declarations) {
+                    if (!bindsName(d.name, name))
+                        continue;
+                    return isConst && ts.isIdentifier(d.name)
+                        ? { kind: "const", init: d.initializer }
+                        : { kind: "other" };
+                }
+            }
+            if ((ts.isFunctionDeclaration(st) ||
+                ts.isClassDeclaration(st) ||
+                ts.isEnumDeclaration(st) ||
+                ts.isModuleDeclaration(st)) &&
+                st.name &&
+                ts.isIdentifier(st.name) &&
+                st.name.text === name)
+                return { kind: "other" };
+            if (ts.isImportDeclaration(st) &&
+                ts.isStringLiteral(st.moduleSpecifier)) {
+                const c = st.importClause;
+                const b = c?.namedBindings;
+                const hit = c?.name?.text === name ||
+                    (b !== undefined &&
+                        (ts.isNamespaceImport(b)
+                            ? b.name.text === name
+                            : b.elements.some((e) => e.name.text === name)));
+                if (hit)
+                    return { kind: "import", spec: st.moduleSpecifier.text };
+            }
+        }
+    }
+    return undefined;
+}
+/** Own return expressions of `fn` (nested functions excluded); a concise
+ * arrow body counts as its one return. */
+function ownReturns(fn) {
+    if (!fn.body)
+        return [];
+    if (!ts.isBlock(fn.body))
+        return [fn.body];
+    const out = [];
+    const visit = (x) => {
+        if (ts.isFunctionLike(x) || ts.isClassLike(x))
+            return;
+        if (ts.isReturnStatement(x))
+            out.push(x.expression);
+        ts.forEachChild(x, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return out;
+}
+/** `fn` takes the client first and hands back only that client, bare or behind
+ * `new Proxy(<client>, …)`. */
+function isClientWrapper(fn) {
+    const p0 = fn.parameters[0]?.name;
+    if (!p0 || !ts.isIdentifier(p0))
+        return false;
+    const isP0 = (e) => {
+        if (!e)
+            return false;
+        const u = unwrap(e);
+        return ts.isIdentifier(u) && u.text === p0.text;
+    };
+    const rets = ownReturns(fn);
+    return (rets.length > 0 &&
+        rets.every((r) => {
+            if (isP0(r))
+                return true;
+            const u = r && unwrap(r);
+            return (!!u &&
+                ts.isNewExpression(u) &&
+                ts.isIdentifier(u.expression) &&
+                u.expression.text === "Proxy" &&
+                isP0(u.arguments?.[0]));
+        }));
+}
+/** The door check over a parsed tree (client wrappers resolve by name). */
+function doorCheckIn(parsed) {
+    const idx = indexFunctions(parsed);
+    const wrapperMemo = new Map();
+    const wrapperOk = (name) => {
+        let v = wrapperMemo.get(name);
+        if (v === undefined) {
+            const defs = idx.get(name) ?? [];
+            v = defs.length > 0 && defs.every((d) => isClientWrapper(d.fn));
+            wrapperMemo.set(name, v);
+        }
+        return v;
+    };
+    const clientBinding = (id, depth) => {
+        if (depth > 4)
+            return false;
+        const b = bindingOf(id);
+        if (!b)
+            return false;
+        if (b.kind === "param")
+            return true;
+        if (b.kind === "import")
+            return !b.spec.startsWith(".") && !b.spec.startsWith("/");
+        if (b.kind !== "const" || !b.init)
+            return false;
+        const init = unwrap(b.init);
+        if (ts.isNewExpression(init) &&
+            ts.isIdentifier(init.expression) &&
+            CLIENT_CONSTRUCTORS.has(init.expression.text))
+            return true;
+        if (ts.isCallExpression(init) && ts.isIdentifier(init.expression)) {
+            const a0 = init.arguments[0] && unwrap(init.arguments[0]);
+            return (!!a0 &&
+                ts.isIdentifier(a0) &&
+                clientBinding(a0, depth + 1) &&
+                wrapperOk(init.expression.text));
+        }
+        return false;
+    };
+    return (call) => {
+        const c = unwrap(call.expression);
+        if (!ts.isPropertyAccessExpression(c))
+            return false;
+        const m = c.name.text;
+        const recv = unwrap(c.expression);
+        if (!ts.isIdentifier(recv))
+            return false;
+        if (CTX_DOOR_METHODS.has(m))
+            return clientBinding(recv, 0);
+        if (!CLIENT_DOOR_METHODS.has(m))
+            return false;
+        return CLIENT_RECEIVER.test(recv.text) && clientBinding(recv, 0);
+    };
+}
+/** Climb from `n` through wrappers and object-literal nesting; true when it
+ * lands in a BACKEND DOOR call's arguments (`isBackendDoor`). `inObject` reports whether an object literal was
+ * climbed (the caller of a returned literal needs one). */
+function climbToArgument(n, isBackendDoor, onReturn) {
+    let cur = n;
+    let inObject = false;
+    for (let p = cur.parent; p; cur = p, p = p.parent) {
+        if (ts.isParenthesizedExpression(p) ||
+            ts.isNonNullExpression(p) ||
+            ts.isAsExpression(p) ||
+            ts.isSatisfiesExpression(p) ||
+            ts.isAwaitExpression(p))
+            continue;
+        if (ts.isBinaryExpression(p) &&
+            FALLBACK_OPS.has(p.operatorToken.kind) &&
+            p.left === cur &&
+            isInertFallback(p.right))
+            continue;
+        if ((ts.isPropertyAssignment(p) && p.initializer === cur) ||
+            (ts.isSpreadAssignment(p) && p.expression === cur)) {
+            p = p.parent; // the object literal
+            inObject = true;
+            continue;
+        }
+        if (ts.isSpreadElement(p) && p.expression === cur) {
+            if (p.parent && ts.isCallExpression(p.parent))
+                return (isBackendDoor(p.parent) && p.parent.arguments.some((a) => a === p));
+            return false;
+        }
+        if (ts.isCallExpression(p))
+            return isBackendDoor(p) && p.arguments.some((a) => a === cur);
+        if (!onReturn)
+            return false;
+        if (ts.isReturnStatement(p) && p.expression === cur) {
+            let fn = p.parent;
+            while (fn && !ts.isFunctionLike(fn))
+                fn = fn.parent;
+            return !!fn && onReturn(fn, inObject);
+        }
+        if (ts.isArrowFunction(p) && p.body === cur)
+            return onReturn(p, inObject);
+        return false;
+    }
+    return false;
+}
+/** The name a function is called by: a declaration's, or the `const` an arrow /
+ * function expression initialises. */
+function calledName(fn) {
+    if (ts.isFunctionDeclaration(fn))
+        return fn.name?.text;
+    if ((ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) &&
+        fn.parent &&
+        ts.isVariableDeclaration(fn.parent) &&
+        fn.parent.initializer === fn &&
+        ts.isIdentifier(fn.parent.name))
+        return fn.parent.name.text;
+    return undefined;
+}
+function callersForwardIn(parsed, isBackendDoor) {
+    const memo = new Map();
+    return (name) => {
+        const hit = memo.get(name);
+        if (hit !== undefined)
+            return hit;
+        let calls = 0;
+        let ok = true;
+        for (const p of parsed) {
+            if (!ok)
+                break;
+            if (!p.sf.text.includes(name))
+                continue;
+            walk(p.sf, (x) => {
+                if (!ok || !ts.isIdentifier(x) || x.text !== name)
+                    return;
+                const par = x.parent;
+                if ((ts.isFunctionDeclaration(par) && par.name === x) ||
+                    (ts.isVariableDeclaration(par) && par.name === x) ||
+                    ts.isImportSpecifier(par) ||
+                    ts.isExportSpecifier(par) ||
+                    ts.isImportClause(par) ||
+                    (ts.isPropertyAccessExpression(par) && par.name === x) ||
+                    (ts.isPropertyAssignment(par) && par.name === x))
+                    return;
+                if (ts.isCallExpression(par) &&
+                    par.expression === x &&
+                    climbToArgument(par, isBackendDoor)) {
+                    calls++;
+                    return;
+                }
+                ok = false;
+            });
+        }
+        const v = ok && calls > 0;
+        memo.set(name, v);
+        return v;
+    };
+}
+/** Does the read `n` (receiver `obj`) only travel into a call's arguments? */
+function forwardsOnly(n, obj, callersForward, isBackendDoor) {
+    if (rootIdentifier(obj)?.text === "args")
+        return false;
+    return climbToArgument(n, isBackendDoor, (fn, inObject) => {
+        if (!inObject)
+            return false;
+        const name = calledName(fn);
+        return name !== undefined && callersForward(name);
+    });
+}
+const NAME_OR_SLUG = new Set([
+    ...NAME_FIELDS,
+    "slug",
+    "orgSlug",
+    "clerkOrgSlug",
+]);
+/** The first node of `owner` that decides on identity, or undefined. */
+function decidesOnIdentity(owner, 
+/** the root identifier the forwarded claim is read off (`mapping`) */
+root) {
+    let hit;
+    walk(owner, (x) => {
+        if (hit)
+            return;
+        // a refusing gate that judges a field of the very object the claim is
+        // forwarded from (`if (!mapping || !mapping.isActive) return …`): the
+        // function admits on that object, it does not merely forward it
+        if (root !== undefined && ts.isIfStatement(x) && exits(x.thenStatement)) {
+            let reads = false;
+            walk(x.expression, (y) => {
+                const r = propRead(y);
+                if (r && rootIdentifier(r.obj)?.text === root)
+                    reads = true;
+            });
+            if (reads) {
+                hit = x.expression;
+                return;
+            }
+        }
+        if (ts.isBinaryExpression(x) && EQ.has(x.operatorToken.kind)) {
+            const named = [x.left, x.right].some((s) => {
+                const r = propReadResolved(s);
+                return ((r !== undefined && NAME_OR_SLUG.has(r.name)) ||
+                    (ts.isIdentifier(unwrap(s)) &&
+                        NAME_OR_SLUG.has(unwrap(s).text)));
+            });
+            if (named || (!isLiteral(x.left) && !isLiteral(x.right)))
+                hit = x;
+            return;
+        }
+        if (ts.isCallExpression(x)) {
+            const c = unwrap(x.expression);
+            if (ts.isPropertyAccessExpression(c) &&
+                MEMBER_TEST.has(c.name.text) &&
+                x.arguments[0] &&
+                !isLiteral(x.arguments[0]))
+                hit = x;
+        }
+    });
+    return hit;
+}
 /** The primitives this module adds beside R-53's, one hit per deciding node. */
-function ownHits(p, okReads) {
+function ownHits(p, okReads, callersForward, isBackendDoor) {
     const out = [];
     const jwt = jwtBindings(p);
     walk(p.sf, (x) => {
@@ -389,10 +816,23 @@ function ownHits(p, okReads) {
                     });
             }
         }
-        // scope: a read of an allow-list field
+        // scope: a read of an allow-list field — unless it only FORWARDS the
+        // verified claim into call arguments from a function that decides nothing
         const rd = propRead(x);
-        if (rd && SCOPE_PROPS.has(rd.name))
-            out.push({ node: x, kind: "scope", why: `reads \`${snippet(x)}\`` });
+        if (rd && SCOPE_PROPS.has(rd.name)) {
+            const fwd = forwardsOnly(x, rd.obj, callersForward, isBackendDoor);
+            const decision = fwd
+                ? decidesOnIdentity(ownerOf(x, p.rel).node, rootIdentifier(rd.obj)?.text)
+                : undefined;
+            if (!fwd)
+                out.push({ node: x, kind: "scope", why: `reads \`${snippet(x)}\`` });
+            else if (decision)
+                out.push({
+                    node: x,
+                    kind: "scope",
+                    why: `reads \`${snippet(x)}\` (forwarded, but the same function also decides: \`${snippet(decision)}\`)`,
+                });
+        }
         // membership: a gate on a role / master field
         if (ts.isIfStatement(x) && exits(x.thenStatement)) {
             const r = readsProp(x.expression, ROLE_PROPS);
@@ -545,8 +985,10 @@ export function scanLocalIdentity(files) {
         const o = r.atOwner ? ownerAtDecl(node, p.rel, r.n) : ownerOf(node, p.rel);
         note(o, r.kind, r.why);
     }
+    const isBackendDoor = doorCheckIn(parsed);
+    const callersForward = callersForwardIn(parsed, isBackendDoor);
     for (const p of parsed)
-        for (const h of ownHits(p, okReads))
+        for (const h of ownHits(p, okReads, callersForward, isBackendDoor))
             note(ownerOf(h.node, p.rel), h.kind, `${h.why}, line ${lineOf(h.node)}`);
     for (const { owner, why } of [...sites.values()].sort((a, b) => a.owner.rel.localeCompare(b.owner.rel) || a.owner.n - b.owner.n)) {
         const site = { rel: owner.rel, n: owner.n };

package/dist/trigger.js

@@ -1,6 +1,6 @@
 // D6 — THE PATH-TRIGGER. Decides, given a list of changed paths, whether
 // backend-doctor MUST run. The backend-path shapes are DERIVED from what a
-// Convex backend actually IS (grounded against the real /root/coding/vantage-memory
+// Convex backend actually IS (grounded against the real vantage-peers repository
 // layout, read-only):
 //
 //   SHAPE (a) SCHEMA      — convex/schema.ts (the defineSchema file).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "A conformance instrument that measures the VantagePeers backend against the pinned backend standard. The THIRD doctor built ON the @vantageos/mcp-doctor engine — never a third engine. It consumes runDoctor/renderTable and adds only detectors.",
   "type": "module",
   "main": "./dist/cli.js",