@vantageos/backend-doctor 0.1.0 → 0.1.2

package/dist/detectors/source/isolation.js

@@ -0,0 +1,285 @@
+import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } 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
+// incidentally, naming a helper's internal read as the site while missing the real
+// subscribed queries — Eta k170q03p). The builder is `query` OR a `customQuery`
+// wrapper the tree declares (the standard Convex idiom: `export const authedQuery =
+// customQuery(query, ...)`, then `export const summary = authedQuery({...})`). A
+// rule about subscribed reads that matches only the bare `query` builder is blind on
+// most real Convex codebases, so R-50 DISCOVERS the builders first, and REFUSES
+// (could-not-judge naming the file) when a builder's base cannot be resolved rather
+// than return a green obtained by not looking.
+// `export const X = customQuery(` — the wrapper opener. The BASE identifier may sit
+// on the SAME line or a FOLLOWING one (the idiom often breaks the call across lines:
+// `customQuery(\n  query,\n  …)`), so the base is resolved by a short look-ahead, not
+// captured here.
+const CUSTOM_QUERY_OPEN = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customQuery\s*\(/;
+// the first identifier token — used to read the BASE after a `customQuery(` opener.
+const FIRST_IDENT = /([A-Za-z_][A-Za-z0-9_]*)/;
+// `export const X = customMutation(...)` — a write builder, never an R-50 subject.
+const CUSTOM_MUTATION_DEF = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customMutation\s*\(/;
+// the base builders the platform ships. `query` is the only public read base.
+const BASE_PUBLIC_QUERY = "query";
+const BASE_INTERNAL_QUERY = "internalQuery";
+// An auth/org GATE helper a customQuery customCtx runs before the handler — a
+// require*/ensure*/assert* access check (requireReadAccess, requireWorkspaceId,
+// ensureCurrentOrg, …). Its presence in the wrapper means the wrapper, not the
+// handler, owns the no-org disposition of every query built from it.
+const GATE_HELPER = /\b(?:require|ensure|assert)[A-Z][A-Za-z0-9_]*\s*\(/;
+/** Discover the query/mutation builders a tree declares BEFORE classifying any
+ *  definition — `query` is always a public read base; a `customQuery(query,…)`
+ *  wrapper is public; a `customQuery(internalQuery,…)` wrapper is non-subject; any
+ *  other base is ambiguous (refuse). */
+function discoverBuilders(files) {
+    const b = {
+        publicQuery: new Set([BASE_PUBLIC_QUERY]),
+        nonSubject: new Set([
+            BASE_INTERNAL_QUERY,
+            "mutation",
+            "internalMutation",
+            "action",
+            "internalAction",
+            "httpAction",
+        ]),
+        gated: new Map(),
+        ambiguous: [],
+    };
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const codeLines = f.lines.filter(code);
+        // full-block text (comments included) for the marker check on a builder region.
+        const allLines = f.lines;
+        for (let i = 0; i < codeLines.length; i++) {
+            const l = codeLines[i];
+            const cm = CUSTOM_MUTATION_DEF.exec(l.raw);
+            if (cm) {
+                b.nonSubject.add(cm[1]);
+                continue;
+            }
+            const cq = CUSTOM_QUERY_OPEN.exec(l.raw);
+            if (!cq)
+                continue;
+            const name = cq[1];
+            // the BASE is the first identifier AFTER `customQuery(` — on this line's
+            // remainder, else on the following code lines (the call is often wrapped).
+            const afterOpen = l.raw.slice((cq.index ?? 0) + cq[0].length);
+            let base = FIRST_IDENT.exec(afterOpen)?.[1];
+            for (let j = i + 1; !base && j < codeLines.length && j <= i + 4; j++) {
+                base = FIRST_IDENT.exec(codeLines[j].raw)?.[1];
+            }
+            if (base === BASE_PUBLIC_QUERY) {
+                b.publicQuery.add(name);
+                // Does the wrapper's customCtx run an auth/org gate that can throw, with
+                // no documented contract? The builder region is the opener line plus the
+                // following few CODE lines (the customCtx body is short). The marker is a
+                // comment, so check it against the raw region INCLUDING comments.
+                const codeRegion = codeLines
+                    .slice(i, i + 10)
+                    .map((x) => x.raw)
+                    .join("\n");
+                const startAbs = allLines.indexOf(l);
+                // include up to 3 lines ABOVE the opener: a builder's isolation-contract
+                // marker is conventionally the comment immediately above its declaration.
+                const rawRegion = startAbs >= 0
+                    ? allLines
+                        .slice(Math.max(0, startAbs - 3), startAbs + 14)
+                        .map((x) => x.raw)
+                        .join("\n")
+                    : codeRegion;
+                const gates = ORG_THROW.test(codeRegion) ||
+                    ORG_THROW_HELPER.test(codeRegion) ||
+                    GATE_HELPER.test(codeRegion);
+                if (gates && !CONTRACT_MARKER.test(rawRegion))
+                    b.gated.set(name, { rel: f.rel, n: l.n });
+            }
+            else if (base === BASE_INTERNAL_QUERY)
+                b.nonSubject.add(name);
+            else
+                b.ambiguous.push({
+                    rel: f.rel,
+                    n: l.n,
+                    name,
+                    base: base ?? "<unresolved>",
+                });
+        }
+    }
+    return b;
+}
+/** `export const NAME = <builder>(` for a builder in `set`. A DEFINITION opener,
+ *  never a `.query(` read (there is no `const NAME =` before a `ctx.db.query(`). */
+function definitionOpener(raw, set) {
+    // longest builder names first so `authedQuery` wins over a `query` substring.
+    const names = [...set].sort((a, z) => z.length - a.length);
+    const alt = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const re = new RegExp(`(?:export\\s+)?const\\s+([A-Za-z0-9_]+)\\s*=\\s*(${alt})\\s*\\(`);
+    const m = re.exec(raw);
+    return m ? { name: m[1], builder: m[2] } : null;
+}
+// An ORG-ISOLATION THROW: a throw keyed on the caller having no org/identity, or a
+// helper that throws on the missing-org path. This is the behaviour a subscribed
+// client receives as an uncaught Server Error.
+const ORG_THROW = /throw\b[^;]*\b(?:NO_ORG|ORG_REQUIRED|RBAC_DENIED|no org|missing org|organization is required|not in (?:an )?org)/i;
+const ORG_THROW_HELPER = /\b(?:requireWorkspaceId|requireOrgId|requireOrgSlug|getOrgIdOrThrow|ensureCurrentOrg|ensureCurrent)\s*\(/;
+// The NON-throwing, fail-closed org resolver (VP's `withOrgScope` returns a typed
+// empty scope on no identity — never throws) OR a documented isolation contract
+// OR an explicit typed-empty return on the no-org branch. Any of these means the
+// subscribing client always receives a shape it can render.
+const SAFE_RESOLVER = /\bwithOrgScope\s*\(/;
+const CONTRACT_MARKER = /isolation-contract:|client-safe-empty|@client-must-not-subscribe/i;
+/** delimit a function 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 scanR50(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.
+    const builders = discoverBuilders(files);
+    // A customQuery wrapper whose base is neither query nor internalQuery leaves the
+    // public-query surface unknowable — REFUSE (could-not-judge), never a silent green.
+    for (const a of builders.ambiguous) {
+        scan.cnj.push({
+            rel: a.rel,
+            n: a.n,
+            note: `builder "${a.name}" = customQuery(${a.base}, …) — its base "${a.base}" resolves to neither \`query\` (public) nor \`internalQuery\`, so whether definitions using it are subscribed queries cannot be enumerated; R-50 refuses rather than certify a surface it cannot see (never a silent green)`,
+        });
+    }
+    // A GATED public customQuery builder: its customCtx runs an auth/org gate that can
+    // throw, so every subscribed query built from it inherits that throw in the shared
+    // wrapper — invisible to a per-handler scan. REFUSE per builder (could-not-judge),
+    // naming it and counting its dependent subscribed queries, so a customQuery
+    // codebase never reads "R-50 clean" by the opener simply not looking into the
+    // wrapper. (The remedy a human confirms: the wrapper returns a typed empty/unauth
+    // context on the no-org path, or documents an isolation-contract on the builder.)
+    for (const [name, at] of builders.gated) {
+        let deps = 0;
+        for (const f of files) {
+            if (!isJudgeable(f))
+                continue;
+            for (const l of f.lines) {
+                if (!code(l))
+                    continue;
+                const o = definitionOpener(l.raw, new Set([name]));
+                if (o)
+                    deps += 1;
+            }
+        }
+        scan.cnj.push({
+            rel: at.rel,
+            n: at.n,
+            note: `customQuery builder "${name}" gates every query built from it in its customCtx (an auth/org require*/throw), and ${deps} subscribed query(ies) route through it — whether that wrapper THROWS into a subscription or returns a typed empty/unauthorized context on the no-org path is not decidable from the query surface. R-50 refuses (a human confirms the wrapper's no-org shape, or the builder carries an isolation-contract marker) — never a silent green obtained by not looking into the wrapper`,
+        });
+    }
+    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;
+            // R-50's subject is a public-query DEFINITION: `const NAME = <publicBuilder>(`.
+            // This never matches a `ctx.db.query(...)` read (no `const NAME =` there) nor
+            // an internal/mutation/action definition (those builders are not in the set).
+            const opener = definitionOpener(lines[i].raw, builders.publicQuery);
+            if (!opener)
+                continue;
+            // A query declared through a GATED customQuery builder inherits its no-org
+            // disposition from the shared customCtx wrapper (an auth/org gate that can
+            // throw), NOT from this handler — so a per-handler scan cannot see it. The
+            // builder-level refusal below covers these; skip the per-handler pass here.
+            if (builders.gated.has(opener.builder))
+                continue;
+            // exclude the builder DEFINITION line itself (`const authedQuery = query(`?
+            // no — customQuery defs use `customQuery(`, filtered above; but guard a
+            // `const x = query(` that is a re-export, not a `query({config})`): require
+            // the block to open a config object, handled by queryBlock below).
+            const fn = opener.name;
+            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 public query block could not be delimited (unbalanced braces) — whether its no-org path throws or returns a typed empty 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");
+            // The org-throw and the resolver are CODE (read from executing lines only,
+            // so a commented-out throw does not count). The contract marker is, by
+            // definition, a COMMENT — so it is read from the full block text INCLUDING
+            // comment lines, not the code-only blockText.
+            const blockTextWithComments = block.lines
+                .map((l) => l.raw)
+                .join("\n");
+            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) {
+                // 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).
+                continue;
+            }
+            // PRECEDENCE (Eta #13 REVISE seam): the THROW wins over a fail-closed
+            // resolver. `withOrgScope` returning a typed empty scope is a property of
+            // the RESOLVER, not of the handler — a handler that calls withOrgScope AND
+            // then `throw`s on the no-org path still fires that throw into the
+            // subscription, so the resolver's presence must NOT clear it. Only a
+            // documented CONTRACT_MARKER — a CLAIM the reviewer checks, never a proof —
+            // clears a throwing handler (a declared "the layout must not subscribe").
+            if (hasMarker) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: public query carries a documented isolation-contract marker (a declared divergence — a CLAIM the reviewer verifies, not a proof of behaviour) — accepted, the layout is asserted not to subscribe on the no-org path`,
+                });
+            }
+            else if (throwsOnNoOrg) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: public query throws on the missing-org path (org-keyed ConvexError or a throw-on-no-org helper) with no documented contract${hasResolver ? " — a `withOrgScope` resolver is ALSO present, but a fail-closed resolver returning a typed empty scope does NOT rescue an explicit throw that still fires into the subscription (Eta #13 seam)" : ""}. A subscribing client receives an uncaught Server Error. Return a typed empty/unauthorized shape (do not throw), or document that the layout must not subscribe`,
+                });
+            }
+            else {
+                // hasResolver, no throw, no marker — the fail-closed resolver is the
+                // whole no-org handling; the subscribing client receives a typed shape.
+                scan.conform.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: public query resolves org via the fail-closed non-throwing resolver (\`withOrgScope\`) and does NOT throw on the no-org path — the subscribing client receives a typed shape, not an uncaught throw`,
+                });
+            }
+        }
+    }
+    return scan;
+}
+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.");
+/** 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/standard/_doc.d.ts

@@ -1,11 +1,26 @@
 import type { Detector, DetectorResult } from "../../engine-types.js";
 /** The vendored-fixture basename used as the anchor file for every doc site. */
-export declare const STANDARD_FILE = "backend-standard-51ec7af1.md";
+export declare const STANDARD_FILE = "backend-standard-4265226e.md";
 export declare const VENDORED_STANDARD_PATH: string;
 /** The standard all four are pinned against (short hash a9d7877b). */
 export declare const STANDARD_DOC_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A714/\u00A711/\u00A710/\u00A73";
 /** Read the vendored standard's raw text. Injectable for tests. */
 export declare function readStandard(path?: string): string;
+/**
+ * The instrument's own readability check. A backend-doctor run reads its pinned
+ * standard fixture as material; if that fixture is ABSENT or UNREADABLE the tool
+ * has nothing to judge against, and letting `readFileSync` throw exits the CLI
+ * with code 1 — indistinguishable from "a violation was found" (Eta #12 REVISE).
+ * This returns a REFUSAL the CLI maps to exit 2 (could-not-judge) with a line
+ * NAMING what it could not read, mirroring the fleet leak_guard.py form. `ok`
+ * means the instrument is readable; a run may then legitimately pass or fail a pole.
+ */
+export declare function checkStandardReadable(path?: string): {
+    ok: true;
+} | {
+    ok: false;
+    refusal: string;
+};
 export interface DocLine {
     /** 1-based line number in the vendored file. */
     n: number;

package/dist/detectors/standard/_doc.js

@@ -2,7 +2,7 @@
 // detectors that read THE STANDARD ITSELF as their material — R-42, R-15, R-32,
 // R-39. Unlike the source-tree detectors (which read convex/ via `tree.files`)
 // and the oracle detectors (which read the CSV), these read the VENDORED standard
-// fixture `fixtures/backend-standard-a9d7877b.md` — the material at the pin. The
+// fixture `fixtures/backend-standard-4265226e.md` — the material at the pin. The
 // engine's contract types are DERIVED from engine-types.ts, never re-spelled.
 //
 // THE LAW (the one that caught R-5): every predicate is derived from the ACTUAL
@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 /** The vendored-fixture basename used as the anchor file for every doc site. */
-export const STANDARD_FILE = "backend-standard-51ec7af1.md";
+export const STANDARD_FILE = "backend-standard-4265226e.md";
 /** The vendored standard at the pin — DATA on the same footing as the oracle CSV.
  * Resolved locally (not via coverage.ts) so this module carries no import cycle
  * with registry.ts. Same file coverage.ts's VENDORED_STANDARD_PATH points at. */
@@ -25,6 +25,33 @@ export const STANDARD_DOC_PIN = "analysis/vantagepeers/backend-standard/backend-
 export function readStandard(path = VENDORED_STANDARD_PATH) {
     return readFileSync(path, "utf8");
 }
+/**
+ * The instrument's own readability check. A backend-doctor run reads its pinned
+ * standard fixture as material; if that fixture is ABSENT or UNREADABLE the tool
+ * has nothing to judge against, and letting `readFileSync` throw exits the CLI
+ * with code 1 — indistinguishable from "a violation was found" (Eta #12 REVISE).
+ * This returns a REFUSAL the CLI maps to exit 2 (could-not-judge) with a line
+ * NAMING what it could not read, mirroring the fleet leak_guard.py form. `ok`
+ * means the instrument is readable; a run may then legitimately pass or fail a pole.
+ */
+export function checkStandardReadable(path = VENDORED_STANDARD_PATH) {
+    try {
+        const text = readFileSync(path, "utf8");
+        if (text.trim().length === 0) {
+            return {
+                ok: false,
+                refusal: `REFUSING TO JUDGE: standard fixture ${STANDARD_FILE} is EMPTY — the instrument cannot read its own pin (${path})`,
+            };
+        }
+        return { ok: true };
+    }
+    catch {
+        return {
+            ok: false,
+            refusal: `REFUSING TO JUDGE: standard fixture ${STANDARD_FILE} is ABSENT or UNREADABLE — the instrument cannot read its own pin (${path})`,
+        };
+    }
+}
 /** Split the standard text into 1-based numbered lines. */
 export function toLines(text) {
     return text.split("\n").map((raw, i) => ({ n: i + 1, raw }));

package/dist/not-checkable.js

@@ -16,7 +16,7 @@
 // gentler word — it was emptied.
 import { STANDARD_FILE } from "./detectors/standard/_doc.js";
 export const NOT_MECHANICALLY_CHECKABLE = {
-    "R-48": "R-48 authority-totality detector pending — task k17chpr4kzp399j3s7r7edpm4s8cscbz; text pinned at 51ec7af1 so coverage cannot pretend 47 is complete. No mechanical control yet; R-48 is enumerated and visible, never silently dropped.",
+    "R-48": "R-48 authority-totality detector pending — task k17chpr4kzp399j3s7r7edpm4s8cscbz; text pinned at 4265226e so coverage cannot pretend 47 is complete. No mechanical control yet; R-48 is enumerated and visible, never silently dropped.",
 };
 /**
  * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 import type { Detector } from "./engine-types.js";
 /** The standard both pins the whole wave against. */
-export declare const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp)";
+export declare const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4265226eb6698c7dfbae3ced77df564e877908ad (elpiarthera/ElPi-Corp)";
 export interface RegistryEntry {
     detector: Detector;
     ruleId: string;

package/dist/registry.js

@@ -8,6 +8,7 @@ import { makeOracleDetector } from "./detectors/shared.js";
 import { SOURCE_BACKFILL_DETECTORS } from "./detectors/source/backfill.js";
 import { SOURCE_CONTRACT_DETECTORS } from "./detectors/source/contract.js";
 import { IDENTITY_DETECTORS } from "./detectors/source/identity.js";
+import { SOURCE_ISOLATION_DETECTORS } from "./detectors/source/isolation.js";
 import { SOURCE_JOBS_DETECTORS } from "./detectors/source/jobs.js";
 import { SOURCE_LIFECYCLE_DETECTORS } from "./detectors/source/lifecycle.js";
 import { SOURCE_READBUDGET_DETECTORS } from "./detectors/source/readbudget.js";
@@ -19,7 +20,7 @@ import { R46_STANDARD_PIN, STANDARD_SOURCE_DETECTORS, } from "./detectors/standa
 import { STANDARD_DOC_DETECTORS } from "./detectors/standard/standard-doc.js";
 import { makeR14, makeR38 } from "./detectors/structural.js";
 /** The standard both pins the whole wave against. */
-export const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp)";
+export const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4265226eb6698c7dfbae3ced77df564e877908ad (elpiarthera/ElPi-Corp)";
 export const REGISTRY = [
     ...PER_ROW_PREDICATES.map((spec) => ({
         detector: makeOracleDetector(spec),
@@ -98,6 +99,15 @@ export const REGISTRY = [
         // site (the human decides refusal vs a tighter index vs a declared bound),
         // present on a wide scan that DOES refuse (the tasks.list SCAN_CAP shape).
         ...SOURCE_REFUSAL_DETECTORS,
+        // R-50 — org isolation on a reactively-subscribed read must be a TYPED EMPTY /
+        // UNAUTHORIZED RESULT, never an uncaught throw. Reads the convex source: a
+        // public `query` (subscribed via useQuery) whose no-org path throws an
+        // org-keyed ConvexError / a throw-on-no-org helper, with no fail-closed
+        // resolver (`withOrgScope`) or documented contract, hands the subscribing
+        // client an uncaught Server Error (the 2026-08-30 vCRM-Preview incident:
+        // workspaces:ensureCurrent + prefs:sidebar). Extends the R-11 isolation
+        // family; a mutation refusing an unauthorized write (R-16) is out of scope.
+        ...SOURCE_ISOLATION_DETECTORS,
         ...SOURCE_CONTRACT_DETECTORS,
         ...IDENTITY_DETECTORS,
         // The four STANDARD-DOCUMENT detectors (R-42/R-15/R-32/R-39): each reads the