@vantageos/backend-doctor 0.1.14 → 0.2.0

package/dist/detectors/source/isolation.d.ts

@@ -1,6 +1,16 @@
 import type { Detector } from "../../engine-types.js";
-import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+import { type Scan, type Site, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare const SCOPE_REFUSED_RETURN: RegExp;
+export declare function noOrgEarlyReturn(text: string): boolean;
+/** R-50's scan plus the public queries it found OUTSIDE its scope (no org-throw,
+ *  no resolver, no marker — standard 4bcd605 :653). The out-of-scope list never
+ *  reaches a verdict; it only words the empty-subject abstain truthfully. */
+export interface R50Scan {
+    scan: Scan;
+    outOfScope: Site[];
+}
 export declare function scanR50(files: SrcFile[]): Scan;
+export declare function scanR50Detailed(files: SrcFile[]): R50Scan;
 export declare const R50: Detector;
 /** In the form the orchestrator spreads into REGISTRY. */
 export declare const SOURCE_ISOLATION_DETECTORS: SourceDetectorEntry[];

package/dist/detectors/source/isolation.js

@@ -1,4 +1,4 @@
-import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+import { code, decide, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, } from "./_scan.js";
 // A public reactive read is DEFINED, not read. R-50 governs a query DEFINITION —
 // `export const NAME = <builder>({ ... })` — never a `ctx.db.query(...)` table READ
 // inside a handler (the pre-fix opener `/\bquery\(/` matched `.query(` reads
@@ -194,6 +194,54 @@ function namedValueDomination(before) {
     }
     return false;
 }
+// Form C (VP shape — the typed-empty PRE-ORG path). `withOrgScope(ctx, {
+// refuseWithoutThrow: true })` marks a signed-in caller with no organisation as
+// `scope.refused` instead of throwing; the handler then answers that caller with a
+// typed value BEFORE any org-throw:
+//   const scope = await withOrgScope(ctx, { refuseWithoutThrow: true });
+//   if (scope.refused) { return null; }        // or `return [];` / `return { … }`
+//   if (!scope.isMaster && scope.orgSlug === null) throw new ConvexError("RBAC_DENIED…");
+// The throw below the guard is then unreachable for the no-org caller R-50 protects
+// (a mounted, subscribed shell); it fires only for a caller with no identity at all.
+// NARROW on purpose: the guard must test a `.refused` flag (bare or on a binding)
+// and its body must be a bare `return` of `null`, an empty array, or an object
+// literal — never `return <identifier>`, never a call, never a throw.
+export const SCOPE_REFUSED_RETURN = /if\s*\(\s*(?:[A-Za-z_$][\w$]*\.)?refused\s*\)\s*(?:\{\s*)?return\s+(?:null\b|\[\s*\]|\{)/;
+// Form D (vCRM shape — an EARLY GUARD that answers the no-org caller with a typed
+// value before the org resolver/throw is reached):
+//   if (!ctx.workspaceId) { return emptySummary(args.presetKey, CURRENCY); }   reports.ts
+//   const workspaceId = requireWorkspaceId(ctx.workspaceId);                   (now unreachable on no-org)
+//   if (!ctx.workspaceId || !company || company.workspaceId !== ctx.workspaceId) { return []; }  activities.ts
+// NARROW on purpose: the condition must contain a no-org NEGATION as a disjunct and
+// NO `&&` anywhere (a conjunction could leave the no-org caller to fall through),
+// and the guarded statement must be a `return` of `null`, `[]`, an object literal,
+// or a CALL whose name marks the empty/unauthorised case — never `return <ident>`,
+// never an arbitrary call, never a throw.
+const NO_ORG_NEGATION = /!\s*(?:scope\.|ctx\.[A-Za-z0-9_.]*)?(?:org|orgId|orgSlug|workspaceId|workspace)\b|\b(?:org|orgId|orgSlug|workspaceId)\s*(?:===|==)\s*(?:null|undefined)\b/;
+const EARLY_TYPED_RETURN = /^\s*\{?\s*return\s+(?:null\b|\[\s*\]|\{|(?:[A-Za-z0-9_$]+\.)*[A-Za-z0-9_$]*(?:[Ee]mpty|[Uu]nauthori[sz]ed|NoOrg|NoWorkspace)[A-Za-z0-9_$]*\s*\()/;
+export function noOrgEarlyReturn(text) {
+    const opener = /\bif\s*\(/g;
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = opener.exec(text)) !== null) {
+        let depth = 1;
+        let j = m.index + m[0].length;
+        for (; j < text.length && depth > 0; j++) {
+            if (text[j] === "(")
+                depth += 1;
+            else if (text[j] === ")")
+                depth -= 1;
+        }
+        if (depth !== 0)
+            return false;
+        const cond = text.slice(m.index + m[0].length, j - 1);
+        if (cond.includes("&&") || !NO_ORG_NEGATION.test(cond))
+            continue;
+        if (EARLY_TYPED_RETURN.test(text.slice(j)))
+            return true;
+    }
+    return false;
+}
 function throwDomination(blockText) {
     const t1 = ORG_THROW.exec(blockText);
     const t2 = ORG_THROW_HELPER.exec(blockText);
@@ -204,6 +252,12 @@ function throwDomination(blockText) {
     // Form B (CRM helper-returned value, guard bound to the value) — decisive on its own.
     if (namedValueDomination(before))
         return "dominated";
+    // Form C (VP pre-org `scope.refused` typed-empty return) — decisive on its own.
+    if (SCOPE_REFUSED_RETURN.test(before))
+        return "dominated";
+    // Form D (early no-org guard returning a typed value) — decisive on its own.
+    if (noOrgEarlyReturn(before))
+        return "dominated";
     // Form A (inline typed-empty object literal + a no-org guard).
     if (!TYPED_EMPTY_RETURN.test(before))
         return "none";
@@ -232,6 +286,9 @@ function queryBlock(lines, i) {
     return { lines: body, unterminated: seenOpen };
 }
 export function scanR50(files) {
+    return scanR50Detailed(files).scan;
+}
+export function scanR50Detailed(files) {
     const scan = emptyScan();
     // Pass 1: discover the tree's query/mutation builders so a customQuery wrapper
     // (authedQuery, orgQuery, …) is recognised, not just the bare `query` base.
@@ -333,16 +390,37 @@ export function scanR50(files) {
             const throwsOnNoOrg = ORG_THROW.test(blockText) || ORG_THROW_HELPER.test(blockText);
             const hasResolver = SAFE_RESOLVER.test(blockText);
             const hasMarker = CONTRACT_MARKER.test(blockTextWithComments);
+            if (!throwsOnNoOrg &&
+                !hasResolver &&
+                !hasMarker &&
+                noOrgEarlyReturn(blockText)) {
+                // No throw at all, and the no-org caller is answered by an early guard
+                // with a typed value: the standard's green verbatim (4bcd605 :653, "returns
+                // a typed empty/unauthorised context on the no-org path"). An R-50
+                // subject that conforms — not an out-of-scope read.
+                scan.conform.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: public query answers the no-org caller with a typed value from an early no-org guard (no throw anywhere in the handler) — the subscribing client receives a shape`,
+                });
+                continue;
+            }
             if (!throwsOnNoOrg && !hasResolver && !hasMarker) {
-                // query does neither org-isolation throw nor fail-closed resolve nor
-                // declare a contract — not R-50's subject (too ambiguous to judge
-                // mechanically; never a violation). Recorded so a tree whose ENTIRE
-                // public-read surface is bare is judged (CNJ-with-sites) rather than
-                // falsely abstained as "no public query matched".
+                // A query that does neither an org-isolation throw nor a fail-closed
+                // resolve nor declares a contract is OUT OF R-50's SCOPE — the pinned
+                // standard says so in its detector spec (backend-standard-4bcd605.md
+                // :653, "*out of scope:* … a query that does neither org-throw nor
+                // fail-closed resolve (not this rule's subject)"). R-50 asks how a
+                // REFUSAL is shaped; a read with no guard has no refusal to shape.
+                // Whether such a read resolves its caller AT ALL is CR-1's question
+                // (src/caller-resolution.ts — an unresolved public read is a CR-1
+                // NO-IDENTITY violation and drives the exit code), so the instrument
+                // still goes red on it, under the control that owns it. Counted only
+                // to name the empty-subject abstain truthfully.
                 ungated.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public query with no org-throw, no fail-closed resolver, and no isolation-contract marker — an UNMARKED public read. No org-isolation handling and no client contract is visible in convex/; an instrument that abstains here protects nothing (a fully-unmarked read is exactly the surface a subscribing client can hit before an org exists). NON-CONFORMING until the author resolves org via a fail-closed non-throwing path (\`withOrgScope\`), returns a typed empty/unauthorized shape, or records an isolation-contract marker`,
+                    note: `${fn}: public query with no org-throw, no fail-closed resolver, no isolation-contract marker — not an R-50 subject (standard 4bcd605 :653); caller resolution is CR-1's control`,
                 });
                 continue;
             }
@@ -403,25 +481,28 @@ export function scanR50(files) {
             }
         }
     }
-    // A tree whose ENTIRE public-read surface is ungated (no throw / resolver / marker
-    // on ANY query) leaves the scan otherwise empty. The legacy abstain then claimed
-    // "no public query matched" — FALSE when bare public queries exist, and a silent
-    // pass over a fully-ungated backend. Surface those reads as could-not-judge sites
-    // so the verdict is CNJ-with-sites, not a misleading empty abstain. Gated on "scan
-    // otherwise empty" so a tree that already produced subjects (VP: 20 conform) is
-    // byte-for-byte unchanged.
-    // An UNMARKED bare public read (no throw / resolver / marker) is NON-CONFORMING,
-    // never an abstention — whether the scan is otherwise empty (a fully-unmarked
-    // backend) OR mixed (bare reads alongside gated subjects). Laurent doctrine: "an
-    // instrument that cannot go red protects nothing; CNJ is for UNREADABLE input
-    // only." A bare read is fully READABLE — its two absences (no isolation, no
-    // contract) are the defect, not a could-not-read. Push to violate; the author's
-    // exit is a resolver, a typed-empty return, or a recorded isolation-contract marker.
-    for (const u of ungated)
-        scan.violate.push(u);
-    return scan;
+    // Unmarked public reads are NOT pushed anywhere: they are outside R-50's scope
+    // (standard 4bcd605 :653). Until 0.1.16 they were pushed to `violate` (the Day-158
+    // "an instrument that cannot go red protects nothing" correction), which predates
+    // CR-1; CR-1 now carries exactly that obligation for a read that resolves no
+    // caller, so keeping it here too double-counted it under a rule whose text
+    // excludes it. A tree whose ONLY public reads are unmarked abstains with the
+    // empty-subject reason below, naming the count — never a clean bill.
+    return { scan, outOfScope: ungated };
 }
-export const R50 = srcDetector("R-50", "R-50 org isolation on a reactively-subscribed read returns a typed empty/unauthorized result, never an uncaught throw", "a public query that resolves org via a fail-closed non-throwing path or documents its client contract — it never throws on the missing-org path a subscribing client cannot catch", scanR50, "R-50: no public query matched in the scanned tree — no reactive read to certify. NOT a clean bill.");
+const R50_ID = "R-50 org isolation on a reactively-subscribed read returns a typed empty/unauthorized result, never an uncaught throw";
+const R50_CHECK = "a public query that resolves org via a fail-closed non-throwing path or documents its client contract — it never throws on the missing-org path a subscribing client cannot catch";
+export const R50 = {
+    id: R50_ID,
+    run: (tree) => {
+        const { scan, outOfScope } = scanR50Detailed(tree.files);
+        const n = outOfScope.length;
+        const empty = n > 0
+            ? `R-50: no R-50 subject in the scanned tree — ${n} public query(ies) matched, none org-throws, resolves via withOrgScope, or carries an isolation-contract marker (out of scope per standard 4bcd605 :653; caller resolution is CR-1's control). NOT a clean bill.`
+            : "R-50: no public query matched in the scanned tree — no reactive read to certify. NOT a clean bill.";
+        return decide("R-50", R50_ID, R50_CHECK, scan, empty);
+    },
+};
 /** In the form the orchestrator spreads into REGISTRY. */
 export const SOURCE_ISOLATION_DETECTORS = [
     { detector: R50, ruleId: "R-50", standardPin: SOURCE_STANDARD_PIN },

package/dist/detectors/source/jobs.js

@@ -92,7 +92,9 @@ export function scanR19(files) {
 // file that collects unbounded or logs nothing is the violation.
 // ---------------------------------------------------------------------------
 const JOB_FILE = /recurring|monitor|sweep|poll|resolver|cleanup|digest|cron/i;
-const RUN_BOUND = /\.take\s*\(|_cap\b|\blimit\b/i;
+// `.paginate(` is a per-run bound too: a page of `numItems` + a self-reschedule is
+// the platform's continuation pattern the standard names for R-20 (4bcd605 :256).
+const RUN_BOUND = /\.take\s*\(|\.paginate\s*\(|_cap\b|\blimit\b/i;
 const OUTCOME_LOG = /console\.(log|error|warn|info)\s*\(/;
 // ACTUAL job content — a Convex data operation, a scheduler/cron registration, or
 // a scheduled-function handler. Eta ruling (2026-08-31): a file is a background-job
@@ -108,10 +110,171 @@ function isJobFile(f) {
     // require job CONTENT on an executing line, not a filename match alone.
     return f.lines.some((l) => code(l) && JOB_CONTENT.test(l.raw));
 }
+// ---- REGISTRATION files are followed to their handlers ---------------------
+//
+// The misread: R-20 judged FILE BY FILE, so `convex/crons.ts` — which only
+// REGISTERS schedules (`crons.interval("…", { minutes: 15 },
+// internal.recurringTasks.processDueTasks, {})`) and does no work — was scored as an
+// unbounded job because the registration file itself carries no `.take(`. The job
+// is the HANDLER the registration names. A file whose job content is only cron
+// registrations is therefore not judged as a job; each registration becomes a site
+// judged on its handler's own body, following `ctx.runMutation/runAction/runQuery
+// (internal.…)` delegations up to R20_MAX_HOP hops (a cron action that delegates
+// its bounded drain to an internalMutation is bounded). A registration whose
+// handler (or a delegate needed for the verdict) cannot be found in the tree is
+// could-not-judge naming it — never green, never an accusation on a guess.
+const CRON_FILE = /\bcronJobs\s*\(/;
+const CRON_REGISTRATION = /\bcrons\.(?:interval|cron|hourly|daily|weekly|monthly)\s*\(/g;
+const INTERNAL_REF = /\binternal\.([A-Za-z0-9_$.]+)/;
+const DELEGATION = /ctx\.run(?:Mutation|Action|Query)\s*\(\s*internal\.([A-Za-z0-9_$.]+)/g;
+const R20_MAX_HOP = 2;
+/** A file whose executing job content is ONLY schedule registration. */
+function isRegistrationOnly(f) {
+    const text = f.lines
+        .filter(code)
+        .map((l) => l.raw)
+        .join("\n");
+    if (!CRON_FILE.test(text))
+        return false;
+    return !/ctx\.db\.|\.collect\s*\(|\.paginate\s*\(|ctx\.scheduler\./.test(text);
+}
+/** Resolve `a.b.fn` (an `internal.` path) to the handler block's text + site. */
+function findHandler(files, path) {
+    const parts = path.split(".");
+    if (parts.length < 2)
+        return undefined;
+    const fn = parts[parts.length - 1];
+    const mod = parts.slice(0, -1).join("/");
+    const file = files.find((f) => f.rel === `${mod}.ts` || f.rel.endsWith(`/${mod}.ts`));
+    if (!file)
+        return undefined;
+    const open = new RegExp(`export\\s+const\\s+${fn}\\s*=`);
+    const lines = file.lines;
+    const i = lines.findIndex((l) => code(l) && open.test(l.raw));
+    if (i < 0)
+        return undefined;
+    let depth = 0;
+    let started = false;
+    const body = [];
+    for (let j = i; j < lines.length; j++) {
+        if (code(lines[j]))
+            body.push(lines[j].raw);
+        for (const ch of lines[j].raw) {
+            if (ch === "{") {
+                depth++;
+                started = true;
+            }
+            else if (ch === "}")
+                depth--;
+        }
+        if (started && depth <= 0)
+            break;
+    }
+    return { rel: file.rel, n: lines[i].n, text: body.join("\n") };
+}
+function judgeHandler(files, path, depth, seen) {
+    const h = findHandler(files, path);
+    if (!h)
+        return { bound: false, log: false, unresolved: [path] };
+    const out = {
+        bound: RUN_BOUND.test(h.text),
+        log: OUTCOME_LOG.test(h.text),
+        unresolved: [],
+    };
+    if ((out.bound && out.log) || depth >= R20_MAX_HOP)
+        return out;
+    DELEGATION.lastIndex = 0;
+    let m = DELEGATION.exec(h.text);
+    while (m !== null) {
+        const next = m[1];
+        if (!seen.has(next)) {
+            seen.add(next);
+            const sub = judgeHandler(files, next, depth + 1, seen);
+            out.bound ||= sub.bound;
+            out.log ||= sub.log;
+            out.unresolved.push(...sub.unresolved);
+        }
+        m = DELEGATION.exec(h.text);
+    }
+    return out;
+}
+/** Each `crons.<kind>(…, internal.x.fn, …)` registration in a registration file,
+ * judged on its handler. */
+function scanRegistrations(f, files, scan) {
+    const codeLines = f.lines.filter(code);
+    const text = codeLines.map((l) => l.raw).join("\n");
+    // map a text offset back to its source line number.
+    const starts = [];
+    let off = 0;
+    for (const l of codeLines) {
+        starts.push(off);
+        off += l.raw.length + 1;
+    }
+    const lineAt = (o) => {
+        let k = 0;
+        while (k + 1 < starts.length && starts[k + 1] <= o)
+            k++;
+        return codeLines[k].n;
+    };
+    CRON_REGISTRATION.lastIndex = 0;
+    let m = CRON_REGISTRATION.exec(text);
+    while (m !== null) {
+        const n = lineAt(m.index);
+        const ref = INTERNAL_REF.exec(text.slice(m.index, m.index + 400));
+        if (!ref) {
+            scan.cnj.push({
+                rel: f.rel,
+                n,
+                note: "schedule registration names no `internal.<module>.<fn>` handler readable at the site — its bound and observability cannot be followed (could-not-judge)",
+            });
+        }
+        else {
+            const path = ref[1];
+            const j = judgeHandler(files, path, 0, new Set([path]));
+            const h = findHandler(files, path);
+            const at = h ? `${h.rel}:${h.n}` : "not found";
+            if (j.bound && j.log) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n,
+                    note: `scheduled handler internal.${path} (${at}) bounds its run and logs its outcome (followed from the registration, delegations included)`,
+                });
+            }
+            else if (j.unresolved.length > 0) {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n,
+                    note: `scheduled handler internal.${path} (${at}): ${j.bound ? "bounded" : "no bound found"}${j.log ? ", logs" : ", no log found"} — but ${j.unresolved.map((u) => `internal.${u}`).join(", ")} could not be found in the tree, so the verdict cannot be completed (could-not-judge)`,
+                });
+            }
+            else if (!j.bound) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n,
+                    note: `scheduled handler internal.${path} (${at}) declares no per-run bound (.take/_CAP/limit) in its body or its delegates — an unbounded run does not ship`,
+                });
+            }
+            else {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n,
+                    note: `scheduled handler internal.${path} (${at}) bounds its run but no outcome log (console.*) found — observability not statically confirmed`,
+                });
+            }
+        }
+        m = CRON_REGISTRATION.exec(text);
+    }
+}
 export function scanR20(files) {
     const scan = emptyScan();
     for (const f of files) {
-        if (!isJudgeable(f) || !isJobFile(f))
+        if (!isJudgeable(f))
+            continue;
+        if (isRegistrationOnly(f)) {
+            scanRegistrations(f, files, scan);
+            continue;
+        }
+        if (!isJobFile(f))
             continue;
         let boundLine = 0;
         let logLine = 0;

package/dist/detectors/source/readbudget.d.ts

@@ -1,5 +1,6 @@
 import type { Detector } from "../../engine-types.js";
 import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare const READ_BOUND_TOKEN: RegExp;
 export declare function scanR31(files: SrcFile[]): Scan;
 export declare const R31: Detector;
 /** In the form the orchestrator spreads into REGISTRY. */

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,44 @@ 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;
+}
 /** 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) {
@@ -92,14 +138,31 @@ export function scanR31(files) {
             const reschedules = RESCHEDULE.test(blockText);
             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)) {

package/dist/detectors/source/security.d.ts

@@ -25,6 +25,22 @@ export declare function scanR22(files: SrcFile[]): Scan;
 export declare function scanR33(files: SrcFile[]): Scan;
 export declare function scanR34(files: SrcFile[]): Scan;
 export declare function scanR35(files: SrcFile[]): Scan;
+/**
+ * The directories R-36 searches, nearest first: the scanned root, then each
+ * ancestor up to and INCLUDING the git root (the first ancestor holding `.git`).
+ *
+ * The misread this closes: the documented invocation points the doctor at
+ * `<repo>/convex`, while the lockfile and `.github/workflows` are REPOSITORY
+ * artifacts living at the repo root. Reading only `tree.root` reported "no lockfile
+ * — dependencies are not pinned" on a repository with a committed `bun.lock`.
+ *
+ * The walk stops at the git root and never goes above it: a lockfile in some
+ * unrelated parent directory (a home directory, a monorepo host that is not this
+ * repository) does not pin this repository's dependencies. With no `.git` ancestor
+ * at all, only the scanned root itself is read (the pre-fix behaviour) — the walk
+ * is never widened on a guess.
+ */
+export declare function r36SearchDirs(root: string): string[];
 export declare function evalR36(root: string): Scan;
 export declare const R21: Detector;
 export declare const R22: Detector;