@vantageos/backend-doctor 0.1.0

package/dist/detectors/source/lifecycle.js

@@ -0,0 +1,147 @@
+import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+// An ADMIN-PROVISIONABLE resource: a config/template row an admin creates —
+// profiles, clients, tenants, templates, mappings, filter rules, allowlists.
+// Deliberately NOT org/user data (tasks, messages, memories, licenses) and NOT
+// issued credentials (tokens, codes) which have their own issue/expire lifecycle.
+const ADMIN_TABLE = /profile|client|tenant|template|mapping|filterrule|allowlist/i;
+const INSERT_TABLE = /ctx\.db\.insert\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]/;
+const QUERY_TABLE = /\.query\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]/;
+const DB_DELETE = /ctx\.db\.delete\s*\(/;
+// a soft-delete / GC by tombstone patch — the revoke/deleted-at convention.
+const SOFT_DELETE = /revokedat|deletedat/i;
+// a function whose NAME declares it removes a resource.
+const DELETE_NAMED = /delete|remove|purge|\bgc\b/i;
+const EXPORT_FN = /export\s+const\s+(\w+)\s*=\s*(?:internal)?(?:mutation|action)\s*\(/;
+const NEXT_EXPORT = /export\s+const\s+\w+\s*=/;
+// the rule's second limb — a written out-of-scope reason.
+const ALLOW_OPT_OUT = /allow-no-delete-path/i;
+/**
+ * Build the set of tables that have a delete/GC path. Association is scoped to a
+ * function so a delete on a NEIGHBOUR table never resolves a resource the
+ * function merely reads:
+ *   • a DELETE-NAMED function (deleteClient, softDelete) that also deletes or
+ *     tombstones associates its FIRST queried table — the subject it removes;
+ *   • an UNNAMED function that calls ctx.db.delete associates a table only when
+ *     it queries EXACTLY ONE distinct table (an unambiguous single-subject
+ *     delete, e.g. consumeAuthorizationCode). A multi-table function
+ *     (patchScopeProfileEmergency: reads the profile, deletes tokens) resolves
+ *     nothing, because which table it deletes is not statically unambiguous.
+ */
+function deletePaths(files) {
+    const paths = new Map();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        let fnName = "";
+        let openLine = 0;
+        let queried = [];
+        let hasDelete = false;
+        let softDelete = false;
+        const flush = () => {
+            if (!fnName)
+                return;
+            const distinct = [...new Set(queried)];
+            const nameDelete = DELETE_NAMED.test(fnName);
+            let subject;
+            if (nameDelete && (hasDelete || softDelete)) {
+                subject = distinct[0];
+            }
+            else if (hasDelete && distinct.length === 1) {
+                subject = distinct[0];
+            }
+            if (subject && !paths.has(subject)) {
+                paths.set(subject, {
+                    rel: f.rel,
+                    n: openLine,
+                    note: `${fnName} removes ${subject} (${hasDelete ? "ctx.db.delete" : "tombstone patch"})`,
+                });
+            }
+        };
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            const open = EXPORT_FN.exec(l.raw);
+            if (open) {
+                flush();
+                fnName = open[1];
+                openLine = l.n;
+                queried = [];
+                hasDelete = false;
+                softDelete = false;
+                continue;
+            }
+            if (fnName && NEXT_EXPORT.test(l.raw) && !EXPORT_FN.test(l.raw)) {
+                flush();
+                fnName = "";
+                continue;
+            }
+            if (!fnName)
+                continue;
+            const q = QUERY_TABLE.exec(l.raw);
+            if (q)
+                queried.push(q[1]);
+            if (DB_DELETE.test(l.raw))
+                hasDelete = true;
+            if (SOFT_DELETE.test(l.raw))
+                softDelete = true;
+        }
+        flush();
+    }
+    return paths;
+}
+/** Every admin-provisionable create/upsert site (first per table), and the set
+ * of files carrying a written out-of-scope reason. */
+function adminCreates(files) {
+    const creates = new Map();
+    const optOutFiles = new Set();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        for (const l of f.lines) {
+            if (ALLOW_OPT_OUT.test(l.raw))
+                optOutFiles.add(f.rel);
+            if (!code(l))
+                continue;
+            const m = INSERT_TABLE.exec(l.raw);
+            if (m && ADMIN_TABLE.test(m[1]) && !creates.has(m[1])) {
+                creates.set(m[1], { table: m[1], rel: f.rel, n: l.n });
+            }
+        }
+    }
+    return { creates, optOutFiles };
+}
+export function scanR43(files) {
+    const scan = emptyScan();
+    const dels = deletePaths(files);
+    const { creates, optOutFiles } = adminCreates(files);
+    for (const c of creates.values()) {
+        const del = dels.get(c.table);
+        if (del) {
+            scan.conform.push({
+                rel: c.rel,
+                n: c.n,
+                note: `admin resource ${c.table} is create/upsert-provisioned AND has a delete/GC path (${del.rel}:${del.n})`,
+            });
+        }
+        else if (optOutFiles.has(c.rel)) {
+            scan.conform.push({
+                rel: c.rel,
+                n: c.n,
+                note: `admin resource ${c.table} has no delete/GC path but carries a written out-of-scope reason (allow-no-delete-path) in ${c.rel}`,
+            });
+        }
+        else {
+            scan.cnj.push({
+                rel: c.rel,
+                n: c.n,
+                note: `admin resource ${c.table} is create/upsert-provisioned but exposes NO delete/GC path and carries no written out-of-scope reason — admin-resource lifecycle asymmetry (a resource you can create but never remove, orphaning any dependents)`,
+            });
+        }
+    }
+    return scan;
+}
+export const R43 = srcDetector("R-43", "R-43 an admin-provisionable resource exposes a delete/GC path or a written out-of-scope reason", "every admin create/upsert-provisioned resource has a delete/GC path (master-gated) or a written out-of-scope reason", scanR43, "R-43: no admin-provisionable resource (create/upsert on a config/profile/client/tenant table) matched in the scanned tree — cannot certify lifecycle symmetry. NOT a clean bill.");
+/** In the form the orchestrator spreads into REGISTRY. */
+export const SOURCE_LIFECYCLE_DETECTORS = [
+    { detector: R43, ruleId: "R-43", standardPin: SOURCE_STANDARD_PIN },
+];

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

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

package/dist/detectors/source/readbudget.js

@@ -0,0 +1,133 @@
+import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+// A mutation opener — the function class R-31 governs (a write-capable ctx).
+const MUTATION_OPEN = /\b(?:internalMutation|mutation)\s*\(/;
+// An UNBOUNDED terminal read — loads every matching row (and, per R-4's field
+// axis, every field). `.collect()` is unbounded by construction.
+const COLLECT = /\.collect\s*\(\s*\)/;
+// A BOUNDED read — a page or a capped take, the shape R-31 requires.
+const BOUNDED = /\.(?:take|paginate)\s*\(/;
+// the table a query names.
+const QUERY_TABLE = /\.query\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]/;
+// the self-reschedule that continues a bulk drain across transactions.
+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*=/;
+/** 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. */
+function statements(lines) {
+    const out = [];
+    let buf = "";
+    let start = 0;
+    for (const l of lines) {
+        if (!code(l))
+            continue;
+        if (buf === "")
+            start = l.n;
+        buf += (buf ? " " : "") + l.raw.trim();
+        if (l.raw.includes(";")) {
+            out.push({ n: start, text: buf });
+            buf = "";
+        }
+    }
+    if (buf)
+        out.push({ n: start, text: buf });
+    return out;
+}
+/** 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) {
+    let depth = 0;
+    let seenOpen = false;
+    const body = [];
+    for (let j = i; j < lines.length; j++) {
+        const l = lines[j];
+        body.push(l);
+        for (const ch of l.raw) {
+            if (ch === "{") {
+                depth += 1;
+                seenOpen = true;
+            }
+            else if (ch === "}") {
+                depth -= 1;
+            }
+        }
+        if (seenOpen && depth <= 0)
+            return { lines: body, unterminated: false };
+    }
+    return { lines: body, unterminated: seenOpen };
+}
+export function scanR31(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const lines = f.lines;
+        for (let i = 0; i < lines.length; i++) {
+            if (!code(lines[i]))
+                continue;
+            if (!MUTATION_OPEN.test(lines[i].raw))
+                continue;
+            // the exported function name this mutation belongs to — on the opener line
+            // or the line just above it (`export const NAME = internalMutation({`).
+            const fn = EXPORT_NAME.exec(lines[i].raw)?.[1] ??
+                (i > 0 ? EXPORT_NAME.exec(lines[i - 1].raw)?.[1] : undefined) ??
+                "<anonymous>";
+            const block = mutationBlock(lines, i);
+            // advance the outer cursor past this block so nested scans don't double-open.
+            i += block.lines.length - 1;
+            if (block.unterminated) {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: lines[Math.min(i, lines.length - 1)].n,
+                    note: "a mutation block could not be delimited (unbalanced braces) — its read budget is not statically decidable; a human must judge whether its reads are bounded (never a silent green)",
+                });
+                continue;
+            }
+            const stmts = statements(block.lines);
+            const blockText = block.lines
+                .filter(code)
+                .map((l) => l.raw)
+                .join("\n");
+            const reschedules = RESCHEDULE.test(blockText);
+            for (const st of stmts) {
+                if (COLLECT.test(st.text) && !BOUNDED.test(st.text)) {
+                    // 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>";
+                    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)\``,
+                    });
+                }
+                else if (BOUNDED.test(st.text)) {
+                    // A bounded read. Conforming only when the mutation also
+                    // self-reschedules (the read side pages exactly as the write side).
+                    const table = QUERY_TABLE.exec(st.text)?.[1] ?? "<unknown table>";
+                    if (reschedules) {
+                        scan.conform.push({
+                            rel: f.rel,
+                            n: st.n,
+                            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 {
+                        scan.cnj.push({
+                            rel: f.rel,
+                            n: st.n,
+                            note: `${fn}: bounded read on "${table}" via \`.take(n)\`/\`.paginate\` but no \`ctx.scheduler.runAfter\` self-reschedule visible in the mutation — whether one page covers the whole set or the drain is continued elsewhere is not statically decidable (human verifies)`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return scan;
+}
+export const R31 = srcDetector("R-31", "R-31 a bulk operation over an unbounded set batches BOTH its reads and its writes (`.take(n)`/`.paginate` + `ctx.scheduler.runAfter(0, self)`); the read budget and the write budget are distinct and both bind", "every mutation over an unbounded set bounds its reads (never a bare `.collect()`) and self-reschedules — an unbounded read aborts on the read cap independently of whether it writes", scanR31, "R-31: no mutation with a database read matched in the scanned tree — no bulk-operation read budget to certify. NOT a clean bill.");
+/** In the form the orchestrator spreads into REGISTRY. */
+export const SOURCE_READBUDGET_DETECTORS = [
+    { detector: R31, ruleId: "R-31", standardPin: SOURCE_STANDARD_PIN },
+];

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

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

package/dist/detectors/source/refusal.js

@@ -0,0 +1,125 @@
+import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+// a read-only query opener — the function class R-47 governs.
+const QUERY_OPEN = /\b(?:internalQuery|query)\s*\(/;
+// an UNBOUNDED terminal read.
+const COLLECT = /\.collect\s*\(\s*\)/;
+// a BOUNDED read — a page or a capped take (out of R-47's wide-scan scope).
+const BOUNDED = /\.(?:take|paginate|first|unique)\s*\(/;
+// an index-narrowing predicate — a wide range is one WITHOUT this.
+const INDEX_NARROW = /\.withIndex\s*\(/;
+const QUERY_TABLE = /\.query\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]/;
+const EXPORT_NAME = /export\s+const\s+([A-Za-z0-9_]+)\s*=/;
+// the REFUSAL contract — the correct behaviour R-47 requires. A throw naming an
+// incomplete/uncertain scan, or the SCAN_CAP token the incident used, or prose
+// that the result would be indistinguishable from a complete one.
+const REFUSAL = /SCAN_CAP|scan cap|incomplete|indistinguishable|would (?:be )?(?:narrow|truncat)|narrow(?:ing)? (?:the )?(?:scan|args|arguments)|refus/i;
+/** group a block's CODE lines into `;`-terminated statements, each with a start line. */
+function statements(lines) {
+    const out = [];
+    let buf = "";
+    let start = 0;
+    for (const l of lines) {
+        if (!code(l))
+            continue;
+        if (buf === "")
+            start = l.n;
+        buf += (buf ? " " : "") + l.raw.trim();
+        if (l.raw.includes(";")) {
+            out.push({ n: start, text: buf });
+            buf = "";
+        }
+    }
+    if (buf)
+        out.push({ n: start, text: buf });
+    return out;
+}
+/** delimit a query body from its opener at index i by matching braces. */
+function queryBlock(lines, i) {
+    let depth = 0;
+    let seenOpen = false;
+    const body = [];
+    for (let j = i; j < lines.length; j++) {
+        const l = lines[j];
+        body.push(l);
+        for (const ch of l.raw) {
+            if (ch === "{") {
+                depth += 1;
+                seenOpen = true;
+            }
+            else if (ch === "}") {
+                depth -= 1;
+            }
+        }
+        if (seenOpen && depth <= 0)
+            return { lines: body, unterminated: false };
+    }
+    return { lines: body, unterminated: seenOpen };
+}
+export function scanR47(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const lines = f.lines;
+        for (let i = 0; i < lines.length; i++) {
+            if (!code(lines[i]))
+                continue;
+            if (!QUERY_OPEN.test(lines[i].raw))
+                continue;
+            // exclude a mutation opener that also matches "query(" as a substring only —
+            // QUERY_OPEN's word boundary already handles internalQuery/query.
+            const fn = EXPORT_NAME.exec(lines[i].raw)?.[1] ??
+                (i > 0 ? EXPORT_NAME.exec(lines[i - 1].raw)?.[1] : undefined) ??
+                "<anonymous>";
+            const block = queryBlock(lines, i);
+            i += block.lines.length - 1;
+            if (block.unterminated) {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: lines[Math.min(i, lines.length - 1)].n,
+                    note: `${fn}: a query block could not be delimited (unbalanced braces) — whether its scan is refusal-guarded is not statically decidable; a human must judge (never a silent green)`,
+                });
+                continue;
+            }
+            const blockText = block.lines
+                .filter(code)
+                .map((l) => l.raw)
+                .join("\n");
+            const hasRefusal = REFUSAL.test(blockText);
+            for (const st of statements(block.lines)) {
+                const isUnbounded = COLLECT.test(st.text) && !BOUNDED.test(st.text);
+                if (!isUnbounded)
+                    continue;
+                const table = QUERY_TABLE.exec(st.text)?.[1] ?? "<unknown table>";
+                const indexNarrowed = INDEX_NARROW.test(st.text);
+                if (indexNarrowed) {
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: st.n,
+                        note: `${fn}: unbounded \`.collect()\` on "${table}" is index-narrowed (\`.withIndex\`) — a bounded range, not the wide scan R-47 governs`,
+                    });
+                }
+                else if (hasRefusal) {
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: st.n,
+                        note: `${fn}: wide non-index-bounded scan on "${table}" but the handler carries a REFUSAL path (R-16 error contract naming the narrowing args) — the correct R-47 behaviour (the tasks.list SCAN_CAP_EXCEEDED shape)`,
+                    });
+                }
+                else {
+                    scan.cnj.push({
+                        rel: f.rel,
+                        n: st.n,
+                        note: `${fn}: wide, non-index-bounded \`.query("${table}").collect()\` in a query with NO refusal path — the read cap can truncate it BEFORE any filter runs, returning a fraction indistinguishable from a full match. The human half is owed: refuse (R-16), add a tighter index, or declare a bound (R-30)? Never a silent green`,
+                    });
+                }
+            }
+        }
+    }
+    return scan;
+}
+export const R47 = srcDetector("R-47", "R-47 an incompletable read refuses, naming what would narrow it, never returns a partial set indistinguishable from a complete one", "a wide, non-index-bounded query scan either refuses (R-16 error contract naming the narrowing args) or is bounded/index-narrowed — it never silently returns a truncated fraction", scanR47, "R-47: no unbounded query read matched in the scanned tree — no incompletable scan to certify. NOT a clean bill.");
+/** In the form the orchestrator spreads into REGISTRY. */
+export const SOURCE_REFUSAL_DETECTORS = [
+    { detector: R47, ruleId: "R-47", standardPin: SOURCE_STANDARD_PIN },
+];

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

@@ -0,0 +1,37 @@
+import type { Detector, Tree } from "../../engine-types.js";
+/** The standard all six are pinned against (short hash a9d7877b). */
+export declare const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A715";
+type SrcFile = Tree["files"][number];
+/** A registrable entry — structurally the RegistryEntry the orchestrator spreads
+ * into REGISTRY. We do NOT import registry.ts; we mirror its shape so the
+ * orchestrator owns the integration. */
+export interface SourceDetectorEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}
+interface Site {
+    rel: string;
+    n: number;
+    note: string;
+}
+interface Scan {
+    conform: Site[];
+    violate: Site[];
+    cnj: Site[];
+}
+export declare function scanR21(files: SrcFile[]): Scan;
+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;
+export declare function evalR36(root: string): Scan;
+export declare const R21: Detector;
+export declare const R22: Detector;
+export declare const R33: Detector;
+export declare const R34: Detector;
+export declare const R35: Detector;
+export declare const R36: Detector;
+/** The six, in a form the orchestrator spreads into REGISTRY. */
+export declare const SOURCE_SECURITY_DETECTORS: SourceDetectorEntry[];
+export {};