@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/readbudget.js

@@ -12,6 +12,29 @@ const QUERY_TABLE = /\.query\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]/;
 const RESCHEDULE = /ctx\.scheduler\.runAfter\s*\(/;
 // the exported function name the mutation opener belongs to — `export const NAME =`.
 const EXPORT_NAME = /export\s+const\s+([A-Za-z0-9_]+)\s*=/;
+// ---- the DECLARED BOUND (the misread: every `.collect()` was flagged) -------
+//
+// R-31 governs "a bulk operation over an UNBOUNDED set" (standard 4bcd605 :266).
+// A `.collect()` over an index range keyed on equality — the receipts of ONE
+// message, the tokens of ONE client — reads a partition, not the table, and is not
+// a bulk operation in that sense. But the partition's size is not readable from
+// source (Convex has no unique index; `by_namespace` can hold thousands), so the
+// detector does not GUESS that it is small. Per §23 (the disposition control: a
+// flagged site carries a written justification token, and the token's PRESENCE is
+// the control), the author declares the bound in the source:
+//
+//     // read-bound: one row per recipient of a single message (≤ fleet size)
+//     const receipts = await ctx.db.query("messageReceipts")
+//       .withIndex("by_message", (q) => q.eq("messageId", id)).collect();
+//
+// The token is honoured ONLY on an index-range read (`.withIndex(…, q => q.eq(…))`).
+// A FULL-TABLE `.query("t").collect()` is never rescued by it: there the set is the
+// table, and a written "harmless at N" is, per R-32 (standard :270), "the trigger for
+// that proof, never the waiver". The token must carry a reason of ≥ 10 characters.
+// It is read on the statement's own lines or the comment lines directly above it.
+export const READ_BOUND_TOKEN = /read-bound\s*:\s*(\S.{8,}\S)/i;
+// an index-range read keyed on at least one equality — a partition, not the table.
+const INDEX_EQ_RANGE = /\.withIndex\s*\(\s*["'`][A-Za-z0-9_]+["'`]\s*,(?:\([^()]*\)|[^()])*?\.eq\s*\(/;
 /** Group a block's CODE lines into logical statements (joined until a `;`), each
  * keeping its start line. Robust to the multi-line `.query(...).collect()` chain
  * the real migration uses. */
@@ -19,21 +42,327 @@ function statements(lines) {
     const out = [];
     let buf = "";
     let start = 0;
+    let last = 0;
     for (const l of lines) {
         if (!code(l))
             continue;
         if (buf === "")
             start = l.n;
         buf += (buf ? " " : "") + l.raw.trim();
+        last = l.n;
         if (l.raw.includes(";")) {
-            out.push({ n: start, text: buf });
+            out.push({ n: start, end: l.n, text: buf });
             buf = "";
         }
     }
     if (buf)
-        out.push({ n: start, text: buf });
+        out.push({ n: start, end: last, text: buf });
     return out;
 }
+/** The `read-bound:` reason written for the statement spanning [n, end] — on its
+ * own lines (a trailing comment) or the contiguous comment lines directly above it.
+ * Returns undefined when no token is written. */
+function readBoundFor(all, n, end) {
+    const idx = all.findIndex((l) => l.n === n);
+    if (idx < 0)
+        return undefined;
+    for (const l of all) {
+        if (l.n < n || l.n > end)
+            continue;
+        const m = READ_BOUND_TOKEN.exec(l.raw);
+        if (m)
+            return m[1];
+    }
+    for (let j = idx - 1; j >= 0 && all[j].comment; j--) {
+        const m = READ_BOUND_TOKEN.exec(all[j].raw);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+// ---- the CALLER-DRIVEN drain ------------------------------------------------
+//
+// A second drain shape R-31 can judge statically: the mutation reads exactly ONE
+// page with `.paginate(...)` and returns that page's continuation to its caller —
+// BOTH the cursor (`continueCursor`, under any field name) and the done flag
+// (`isDone`, under any field name) — and the caller re-invokes it with the cursor
+// until done. Each page is one transaction, visible and resumable from its cursor
+// (vantage-peers `convex/migrations/backfill_org_stamp.ts`). It conforms only when
+// the page result flows to ONE return statement carrying both fields; a dropped
+// cursor, a missing done flag, or the two split across different returns stay
+// could-not-judge. A `.take(n)` has no continuation and is never this shape.
+const PAGINATE = /\.paginate\s*\(/;
+const IDENT = "[A-Za-z_$][\\w$]*";
+// `const page = await ….paginate(` — the whole page result bound to one local.
+const PAGINATE_BIND = new RegExp(`\\b(?:const|let|var)\\s+(${IDENT})\\s*=\\s*(?:await\\s+)?[^;{]*\\.paginate\\s*\\(`);
+// `const { page, isDone, continueCursor: cur } = await ….paginate(`.
+const PAGINATE_DESTRUCT = /\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?[^;{]*\.paginate\s*\(/;
+// `return [await] ctx.db.query(…)….paginate(` — the page result returned whole.
+const PAGINATE_RETURNED = new RegExp(`\\breturn\\s+(?:await\\s+)?${IDENT}[^;{]*\\.paginate\\s*\\(`);
+const escapeRe = (x) => x.replace(/[$]/g, "\\$");
+/** A bare reference to local `name` in `text`: not a member (`x.name`), not part
+ * of a longer identifier, and not an object KEY (`{ name: …`, `, name: …`). */
+function refersTo(text, name) {
+    const re = new RegExp(`(?<![.\\w$])${escapeRe(name)}(?![\\w$])`, "g");
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+        const before = text.slice(0, m.index).trimEnd();
+        const after = text.slice(m.index + name.length).trimStart();
+        const keyPos = (before.endsWith("{") || before.endsWith(",")) &&
+            after.startsWith(":") &&
+            !after.startsWith("::");
+        if (!keyPos)
+            return true;
+    }
+    return false;
+}
+// `(…) {` opens a block, not a function body, after these keywords.
+const BLOCK_PAREN_KEYWORDS = new Set([
+    "if",
+    "for",
+    "while",
+    "switch",
+    "catch",
+    "with",
+]);
+/** The handler's OWN returns in a mutation block (origin: Argus REVISE #54, P1).
+ * A `return` inside a nested arrow function, `function`, or method body belongs to
+ * that function — a callback's return is not what the mutation hands its caller.
+ * Braces are classified while walking the block's code (strings and comments
+ * skipped): a `{` after `=>`, after the `)` of a parameter list (not an
+ * `if`/`for`/`while`/`switch`/`catch` head), or after a `function` keyword opens a
+ * FUNCTION body. The first function body is the handler; a return counts only when
+ * exactly one function body encloses it. */
+function handlerReturns(lines) {
+    let text = "";
+    const lineAt = [];
+    for (const l of lines) {
+        if (!code(l))
+            continue;
+        for (const ch of `${l.raw}\n`) {
+            text += ch;
+            lineAt.push(l.n);
+        }
+    }
+    // blank comments; mark string bodies as non-structural.
+    const chars = text.split("");
+    const quoted = new Uint8Array(chars.length);
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (ch === "/" && chars[i + 1] === "/") {
+            while (i < chars.length && chars[i] !== "\n")
+                chars[i++] = " ";
+        }
+        else if (ch === "/" && chars[i + 1] === "*") {
+            while (i < chars.length && !(chars[i] === "*" && chars[i + 1] === "/")) {
+                if (chars[i] !== "\n")
+                    chars[i] = " ";
+                i++;
+            }
+            if (i < chars.length)
+                chars[i] = " ";
+            if (i + 1 < chars.length)
+                chars[++i] = " ";
+        }
+        else if (ch === '"' || ch === "'" || ch === "`") {
+            for (i++; i < chars.length && chars[i] !== ch; i++) {
+                quoted[i] = 1;
+                if (chars[i] === "\\")
+                    quoted[++i] = 1;
+            }
+        }
+    }
+    const clean = chars.join("");
+    /** From the `return` at `at`, its text up to the `;` closing it or the brace
+     * closing its block, whichever comes first. */
+    const sliceReturn = (at) => {
+        let nest = 0;
+        let i = at;
+        for (; i < clean.length; i++) {
+            if (quoted[i])
+                continue;
+            const ch = clean[i];
+            if (ch === "(" || ch === "{" || ch === "[")
+                nest += 1;
+            else if (ch === ")" || ch === "}" || ch === "]") {
+                if (nest === 0)
+                    break;
+                nest -= 1;
+            }
+            else if (ch === ";" && nest === 0) {
+                i += 1;
+                break;
+            }
+        }
+        return clean.slice(at, i).replace(/\s+/g, " ").trim();
+    };
+    const out = [];
+    const braces = []; // true = a function body
+    const parens = []; // the word before each open `(`
+    let fnDepth = 0;
+    let prev = ""; // the previous significant token
+    let closedParenWord = "";
+    let pendingFunction = false;
+    let returnType = false; // a `)` of a parameter list followed by `:` — a typed signature
+    let lastWord = "";
+    for (let i = 0; i < clean.length; i++) {
+        if (quoted[i])
+            continue;
+        const ch = clean[i];
+        if (/\s/.test(ch))
+            continue;
+        if (/[A-Za-z_$]/.test(ch)) {
+            let j = i;
+            while (j < clean.length && !quoted[j] && /[\w$]/.test(clean[j]))
+                j++;
+            const word = clean.slice(i, j);
+            const isMember = i > 0 && clean[i - 1] === ".";
+            if (!isMember && word === "function")
+                pendingFunction = true;
+            if (!isMember && word === "return" && fnDepth === 1) {
+                out.push({ line: lineAt[i], text: sliceReturn(i) });
+            }
+            lastWord = word;
+            prev = "word";
+            i = j - 1;
+            continue;
+        }
+        if (ch === "(") {
+            parens.push(prev === "word" ? lastWord : "");
+            prev = "(";
+        }
+        else if (ch === ")") {
+            closedParenWord = parens.pop() ?? "";
+            prev = ")";
+        }
+        else if (ch === "{") {
+            const fn = prev === "=>" ||
+                pendingFunction ||
+                returnType ||
+                (prev === ")" && !BLOCK_PAREN_KEYWORDS.has(closedParenWord));
+            returnType = false;
+            if (fn) {
+                pendingFunction = false;
+                fnDepth += 1;
+            }
+            braces.push(fn);
+            prev = "{";
+        }
+        else if (ch === "}") {
+            if (braces.pop())
+                fnDepth -= 1;
+            prev = "}";
+        }
+        else if (ch === "=" && clean[i + 1] === ">") {
+            prev = "=>";
+            returnType = false;
+            i += 1;
+        }
+        else if (ch === ":" && prev === ")" && !BLOCK_PAREN_KEYWORDS.has(closedParenWord)) {
+            returnType = true;
+            prev = ch;
+        }
+        else if (ch === ";") {
+            returnType = false;
+            prev = ch;
+        }
+        else {
+            prev = ch;
+        }
+    }
+    return out;
+}
+/** The handler's own returns that start inside the given statements. */
+function returnsOf(stmts, own) {
+    return own
+        .filter((r) => stmts.some((st) => r.line >= st.n && r.line <= st.end))
+        .map((r) => r.text);
+}
+// A call that runs another function INSIDE this transaction.
+// `ctx.runMutation(`, `ctx["runMutation"](`, or a destructured `runMutation(`.
+const RUN_IN_TXN = /\brun(?:Mutation|Action)["'`]?\s*\]?\s*\(/;
+/** True when a statement after the read hands the page's cursor to, or names the
+ * mutation itself in, a `ctx.runMutation` / `ctx.runAction` call (origin: Argus
+ * REVISE #54, P3). That walks the pages inside ONE transaction — the drain is not
+ * caller-driven, whatever the mutation returns afterwards. */
+function selfDrains(later, self, carriesCursor) {
+    const selfRef = new RegExp(`\\.\\s*${escapeRe(self)}(?![\\w$])`);
+    // a local bound to the cursor carries it too: `const next = page.continueCursor`
+    const aliases = [];
+    for (const x of later) {
+        const d = /^\s*(?:const|let|var)\s+([\w$]+)\s*=/.exec(x.text);
+        if (d && carriesCursor(x.text.slice(d[0].length)))
+            aliases.push(d[1]);
+    }
+    const carries = (t) => carriesCursor(t) || aliases.some((a) => new RegExp(`(?<![\\w$.])${escapeRe(a)}(?![\\w$])`).test(t));
+    return later.some((x) => {
+        const m = RUN_IN_TXN.exec(x.text);
+        if (!m)
+            return false;
+        const call = x.text.slice(m.index);
+        return selfRef.test(call) || carries(call);
+    });
+}
+/** True when the paginated read in `st` flows to a return statement (among the
+ * statements after it in the mutation) carrying BOTH its continuation cursor and
+ * its done flag. */
+function returnsContinuation(st, later, own, self) {
+    if (!PAGINATE.test(st.text))
+        return false;
+    if (PAGINATE_RETURNED.test(st.text)) {
+        // the read itself is the handler's own return, never a callback's.
+        return (own.some((r) => r.line >= st.n && r.line <= st.end) &&
+            !selfDrains(later, self, () => false));
+    }
+    // the returns this read can reach: up to the next statement that re-declares
+    // one of its locals (a second `const page = …` in another branch is another read).
+    const until = (locals) => {
+        const names = locals.filter((x) => x !== undefined);
+        const cut = later.findIndex((x) => names.some((nm) => new RegExp(`\\b(?:const|let|var)\\s*(?:\\{[^}]*)?(?<![\\w$])${escapeRe(nm)}(?![\\w$])`).test(x.text)));
+        return returnsOf(cut < 0 ? later : later.slice(0, cut), own);
+    };
+    const bound = PAGINATE_BIND.exec(st.text)?.[1];
+    if (bound !== undefined) {
+        const rets = until([bound]);
+        const b = escapeRe(bound);
+        const cursor = new RegExp(`(?<![.\\w$])${b}\\s*\\.\\s*continueCursor\\b`);
+        const done = new RegExp(`(?<![.\\w$])${b}\\s*\\.\\s*isDone\\b`);
+        const whole = new RegExp(`^return\\s+${b}\\s*;?\\s*$|\\.\\.\\.\\s*${b}(?![\\w$]|\\s*[.[])`);
+        if (selfDrains(later, self, (t) => cursor.test(t)))
+            return false;
+        return rets.some((r) => whole.test(r.trim()) || (cursor.test(r) && done.test(r)));
+    }
+    const destruct = PAGINATE_DESTRUCT.exec(st.text)?.[1];
+    if (destruct !== undefined) {
+        let cursorLocal;
+        let doneLocal;
+        let rest;
+        for (const part of destruct.split(",")) {
+            const p = part.trim();
+            if (p.startsWith("...")) {
+                rest = p.slice(3).trim();
+                continue;
+            }
+            const m = new RegExp(`^(${IDENT})\\s*(?::\\s*(${IDENT}))?`).exec(p);
+            if (!m)
+                continue;
+            const local = m[2] ?? m[1];
+            if (m[1] === "continueCursor")
+                cursorLocal = local;
+            if (m[1] === "isDone")
+                doneLocal = local;
+        }
+        const rets = until([cursorLocal, doneLocal, rest]);
+        const carries = (r, local, field) => local !== undefined
+            ? refersTo(r, local)
+            : rest !== undefined &&
+                new RegExp(`(?<![.\\w$])${escapeRe(rest)}\\s*\\.\\s*${field}\\b`).test(r);
+        if (selfDrains(later, self, (t) => carries(t, cursorLocal, "continueCursor")))
+            return false;
+        return rets.some((r) => carries(r, cursorLocal, "continueCursor") &&
+            carries(r, doneLocal, "isDone"));
+    }
+    return false;
+}
 /** From the mutation opener at index `i`, delimit its body by matching braces.
  * Returns the block's lines and whether it closed cleanly. */
 function mutationBlock(lines, i) {
@@ -90,16 +419,34 @@ export function scanR31(files) {
                 .map((l) => l.raw)
                 .join("\n");
             const reschedules = RESCHEDULE.test(blockText);
+            const own = handlerReturns(block.lines);
             for (const st of stmts) {
                 if (COLLECT.test(st.text) && !BOUNDED.test(st.text)) {
+                    const table = QUERY_TABLE.exec(st.text)?.[1] ?? "<unknown table>";
+                    const indexRange = INDEX_EQ_RANGE.test(st.text);
+                    const bound = readBoundFor(lines, st.n, st.end);
+                    if (indexRange && bound !== undefined) {
+                        // A partition read whose bound the author DECLARED in source (§23
+                        // token control) — not a bulk operation over an unbounded set.
+                        scan.conform.push({
+                            rel: f.rel,
+                            n: st.n,
+                            note: `${fn}: \`.collect()\` over an index-equality range on "${table}" with a declared \`read-bound:\` (${bound.slice(0, 80)}) — a partition read whose bound is written in source, not a bulk read over an unbounded set (R-31 conforming by the §23 token)`,
+                        });
+                        continue;
+                    }
                     // An UNBOUNDED read inside a mutation. It aborts on the read cap
                     // whether or not the loop writes — the read budget binds
                     // INDEPENDENTLY of the write budget (refined R-31). Non-conforming.
-                    const table = QUERY_TABLE.exec(st.text)?.[1] ?? "<unknown table>";
+                    const exit = indexRange
+                        ? " — or, for a partition whose size is bounded by construction, declare it with a `// read-bound: <reason>` comment on the read"
+                        : bound !== undefined
+                            ? " — a `read-bound:` token is NOT accepted on a full-table read (the set IS the table; R-32 makes a stated bound the trigger for proof, never the waiver)"
+                            : "";
                     scan.violate.push({
                         rel: f.rel,
                         n: st.n,
-                        note: `${fn}: unbounded read \`.query("${table}").collect()\` inside a mutation — loads every row (and every field, R-4) in ONE transaction; exceeds the per-execution read-byte cap independently of the write budget (an unbounded read that writes NOTHING still aborts on the read cap). Bound it with \`.take(n)\`/\`.paginate\` + \`ctx.scheduler.runAfter(0, self)\``,
+                        note: `${fn}: unbounded read \`.query("${table}").collect()\` inside a mutation — loads every row (and every field, R-4) in ONE transaction; exceeds the per-execution read-byte cap independently of the write budget (an unbounded read that writes NOTHING still aborts on the read cap). Bound it with \`.take(n)\`/\`.paginate\` + \`ctx.scheduler.runAfter(0, self)\`${exit}`,
                     });
                 }
                 else if (BOUNDED.test(st.text)) {
@@ -113,6 +460,13 @@ export function scanR31(files) {
                             note: `${fn}: bounded read on "${table}" via \`.take(n)\`/\`.paginate\` with a \`ctx.scheduler.runAfter\` self-reschedule — the read stays within the per-transaction read budget across the drain (R-31 conforming)`,
                         });
                     }
+                    else if (returnsContinuation(st, stmts.filter((x) => x.n > st.n), own, fn)) {
+                        scan.conform.push({
+                            rel: f.rel,
+                            n: st.n,
+                            note: `${fn}: bounded read on "${table}" via \`.paginate\` — caller-driven drain: the page's continuation (cursor + isDone) is returned to the caller, which re-invokes the mutation with the cursor until done; each page is one transaction, visible and resumable (R-31 conforming)`,
+                        });
+                    }
                     else {
                         scan.cnj.push({
                             rel: f.rel,

package/dist/detectors/source/recipient-by-id.d.ts

@@ -0,0 +1,40 @@
+import { type FnDef, type Parsed } from "./_ast.js";
+/** Argument fields that NAME the recipient / target agent of a write. */
+export declare const RECIPIENT_ARGS: ReadonlySet<string>;
+/** Stored fields that ROUTE a row to its recipient. */
+export declare const ROUTING_FIELDS: ReadonlySet<string>;
+/** Argument fields that NAME the reader / owner whose data a door selects. */
+export declare const READER_ARGS: ReadonlySet<string>;
+/** Stored agent-identity fields: keying or matching one with a typed value
+ * SELECTS an agent's data by name, whatever the argument is called. */
+export declare const SELECTOR_FIELDS: ReadonlySet<string>;
+/** Fields that route (or select an agent) only on a named table — the bare
+ * word is an author elsewhere (`diary.orchestrator`), so it is declared here
+ * and never added to the global sets. */
+export declare const ROUTING_BY_TABLE: ReadonlyMap<string, ReadonlySet<string>>;
+export interface RecipientSite {
+    rel: string;
+    n: number;
+    note: string;
+}
+export declare class RecipientFlow {
+    private readonly parsed;
+    private readonly fns;
+    private readonly relOf;
+    private readonly done;
+    private readonly queue;
+    readonly sites: Map<string, RecipientSite>;
+    constructor(parsed: Parsed[], fns: Map<string, FnDef[]>);
+    run(): RecipientSite[];
+    private key;
+    /** Analyse one function under seeded parameters; returns its return taint. */
+    private analyse;
+    /** A field of an obj taint: a door's recipient argument, or a carried name. */
+    private field;
+    /** A function declared INSIDE `unit` (shares its environment). */
+    private localFn;
+    /** Module-level definitions a callee names: same file first, else by name. */
+    private defsFor;
+}
+/** Every recipient-by-name site reachable from a convex/ write door. */
+export declare function recipientByNameSites(parsed: Parsed[], fns: Map<string, FnDef[]>): RecipientSite[];