@vantageos/backend-doctor 0.4.0 → 0.4.3

package/dist/build-stamp.json

@@ -1,4 +1,4 @@
 {
-  "sourceDigest": "ed2e814dc6a69cc3ee7ddbb354981dfc9a8fb66e36390f50f4b498ba62ca0c26",
-  "builtAt": "2026-10-11T00:31:27.173Z"
+  "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).
 //
@@ -20,6 +20,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { siteCount, withCount } from "../../violation-count.js";
 import { hasJustificationTokenInText } from "../oracle-axis2.js";
+import { scanR11UnboundedReads } from "./isolation-read.js";
 /** The standard all four are pinned against (short hash a9d7877b). */
 export const SOURCE_CONTRACT_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 function emptyScan() {
@@ -179,6 +180,13 @@ export function scanR11(files) {
             }
         }
     }
+    // The unbounded-read arm (isolation-read.ts): a `.collect()` / `for await` read
+    // of a tenant table in a door a non-master caller is served, with no index range
+    // on the tenant key. R-55 hands this shape to R-11 by name.
+    const unboundedArm = scanR11UnboundedReads(files);
+    scan.conform.push(...unboundedArm.conform);
+    scan.violate.push(...unboundedArm.violate);
+    scan.cnj.push(...unboundedArm.cnj);
     return scan;
 }
 // ---------------------------------------------------------------------------
@@ -375,7 +383,7 @@ export function scanR26(files) {
 function srcDetector(ruleId, id, check, scanFn, emptyReason) {
     return { id, run: (tree) => decide(ruleId, id, check, scanFn(tree.files), emptyReason) };
 }
-export const R11 = srcDetector("R-11", "R-11 tenant isolation is an in-query index predicate, not a post-query filter", "a .filter on a scope key is paired with an adjacent .withIndex/.withSearchIndex .eq on that key", scanR11, "R-11: zero scope-key .filter sites matched in the scanned convex tree — cannot certify the isolation locus. NOT a clean bill.");
+export const R11 = srcDetector("R-11", "R-11 tenant isolation is an in-query index predicate, not a post-query filter", "a .filter on a scope key is paired with an adjacent .withIndex/.withSearchIndex .eq on that key; an unbounded read of a tenant table in a door a non-master caller is served carries the tenant key in its index range", scanR11, "R-11: zero scope-key .filter sites and zero unbounded tenant-table reads matched in the scanned convex tree — cannot certify the isolation locus. NOT a clean bill.");
 export const R24 = srcDetector("R-24", "R-24 filter-selected bulk-write defaults to dry run", "a bulk-write mutation defaults dryRun true and gates apply behind an explicit flag + caller guard", scanR24, "R-24: zero bulk-write mutations matched in the scanned convex tree — cannot certify dry-run-by-default. NOT a clean bill.");
 export const R25 = srcDetector("R-25", "R-25 minted address / cross-boundary bundle org-bound at both ends", "a storage mint or bundle redemption is org-bound by an auth guard; a minted bundle URL expires", scanR25, "R-25: zero storage mint/redemption sites matched (kb*/okfBundle*) — cannot certify org-binding. NOT a clean bill.");
 export const R26 = srcDetector("R-26", "R-26 library-owned component declares its seam boundary", "each app.use(component) seam declares an authority tier + boundary key", scanR26, "R-26: no component mount seam (*.config.ts app.use) found — cannot certify the component seam contract. NOT a clean bill.");

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/isolation-read.d.ts

@@ -0,0 +1,2 @@
+import { type Scan, type SrcFile } from "./_scan.js";
+export declare function scanR11UnboundedReads(files: SrcFile[]): Scan;