@vantageos/backend-doctor 0.1.4 → 0.1.6

package/dist/detectors/source/isolation.js

@@ -139,6 +139,74 @@ const CONTRACT_MARKER = /isolation-contract:|client-safe-empty|@client-must-not-
 // A TYPED EMPTY / UNAUTHORIZED RETURN in a wrapper's customCtx (or a handler): the
 // no-org path returns a shape the subscribing client can render instead of throwing.
 const TYPED_EMPTY_RETURN = /return\s+\{[^}]*\b(?:unauthorized|forbidden|noOrg|no_org|denied|empty)\b|return\s+\{[^}]*\b(?:orgSlug|orgId)\s*:\s*null\b|return\s+\{\s*items\s*:\s*\[\s*\]/i;
+// A NO-ORG GUARD condition — an `if (!org…)` / `if (org === null)` shape that owns
+// the no-org branch of a handler. Used only by the domination heuristic below to
+// establish that a typed-empty return which precedes an org-throw plausibly owns the
+// no-org path (rather than sitting behind some unrelated condition).
+const NO_ORG_GUARD = /if\s*\(\s*!\s*(?:scope\.|ctx\.[A-Za-z0-9_.]*)?(?:org|orgId|orgSlug|workspaceId|workspace|identity)\b|if\s*\([^)]*\b(?:org|orgId|orgSlug|workspaceId)\s*(?:===|==)\s*null/i;
+// DOMINATION heuristic (Eta false-positive — a DOMINATED no-org throw). A public
+// query whose handler RETURNS a typed empty/unauthorized shape on the no-org branch
+// BEFORE it ever reaches the org-throw does NOT fire that throw into the subscription
+// on the no-org path — the throw guards an org-PRESENT path (a CRM `dashboard.ts`
+// shape: `if (!org) return { items: [], unauthorized: true }` at the top, then a
+// later `requireWorkspaceId(...)` / `throw` that only runs once an org IS present, so
+// the subscribing client never receives an uncaught Server Error). Judged TEXTUALLY
+// and CONSERVATIVELY — we never silently flip a real throw to green:
+//   "dominated"  a typed-empty return lexically precedes the first org-throw AND a
+//                no-org guard also precedes that throw → the early return plausibly
+//                owns the no-org path; the throw is unreachable when there is no org.
+//                → conform.
+//   "ambiguous"  a typed-empty return precedes the throw but NO no-org guard is
+//                visible before it → we cannot establish the return dominates the
+//                no-org path (interleaved/complex control flow) → could-not-judge,
+//                preferred over a false green (and over a false red the throw might
+//                not deserve).
+//   "none"       no typed-empty return precedes the throw → the throw IS the no-org
+//                behaviour; the existing verdict (violate) is unchanged.
+// The SECOND dominated form (Eta #20 REVISE — the CRM `dashboard.ts` actual shape):
+// the no-org branch is a VALUE returned from a helper CALL whose NAME marks the no-org
+// case, guarded on that same value —
+//   `const empty = typedEmptyIfNoWorkspace(ctx.workspaceId, EMPTY_DASHBOARD_SUMMARY);
+//    if (empty) return empty;`
+// then a later `requireWorkspaceId(...)` throw that only runs once a workspace IS
+// present. The inline matcher (a `return { … }` object literal behind `if (!org…)`)
+// misses this entirely. The widening is deliberately NARROW: the initializer must be a
+// CALL whose name marks the no-org/empty case (never any `return <identifier>`), AND the
+// guard must be on THAT bound value returning THAT value — the guard is bound to its
+// control, so an unrelated `const x = f(); if (x) return x;` cannot dominate.
+const NO_ORG_EMPTY_HELPER = /(?:typedEmpty|emptyIfNo|ifNoWorkspace|ifNoOrg|noWorkspace|noOrg|unauthorizedIf|whenNoOrg|whenNoWorkspace|emptyWhenNo)/i;
+function namedValueDomination(before) {
+    // `const VAR = [await] [ns.]<helper-whose-name-marks-no-org>( …`
+    const decl = /const\s+([A-Za-z0-9_]+)\s*=\s*(?:await\s+)?(?:[A-Za-z0-9_]+\.)*([A-Za-z0-9_]+)\s*\(/g;
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = decl.exec(before)) !== null) {
+        const varName = m[1];
+        const helperName = m[2];
+        if (!NO_ORG_EMPTY_HELPER.test(helperName))
+            continue;
+        // guarded on THAT value, returning THAT value: `if ([!]VAR) [{] return VAR`
+        const guard = new RegExp(`if\\s*\\(\\s*!?\\s*${varName}\\s*\\)\\s*(?:\\{\\s*)?return\\s+${varName}\\b`);
+        if (guard.test(before))
+            return true;
+    }
+    return false;
+}
+function throwDomination(blockText) {
+    const t1 = ORG_THROW.exec(blockText);
+    const t2 = ORG_THROW_HELPER.exec(blockText);
+    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY);
+    if (!Number.isFinite(throwIdx))
+        return "none";
+    const before = blockText.slice(0, throwIdx);
+    // Form B (CRM helper-returned value, guard bound to the value) — decisive on its own.
+    if (namedValueDomination(before))
+        return "dominated";
+    // Form A (inline typed-empty object literal + a no-org guard).
+    if (!TYPED_EMPTY_RETURN.test(before))
+        return "none";
+    return NO_ORG_GUARD.test(before) ? "dominated" : "ambiguous";
+}
 /** delimit a function body from its opener at index i by matching braces. */
 function queryBlock(lines, i) {
     let depth = 0;
@@ -280,11 +348,36 @@ export function scanR50(files) {
                 });
             }
             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`,
-                });
+                const dom = throwDomination(blockText);
+                if (dom === "dominated") {
+                    // The no-org branch RETURNS a typed empty/unauthorized shape before
+                    // the throw is reached, and a no-org guard owns that branch — the
+                    // throw guards an org-PRESENT path and never fires on the no-org path
+                    // a subscribing client can hit. Conform (dominated throw).
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: block.lines[0].n,
+                        note: `${fn}: public query returns a typed empty/unauthorized shape on the no-org branch (an early no-org guard) BEFORE the org-throw is reachable — the throw guards an org-present path and never fires into the subscription on the no-org path. The subscribing client receives a shape, not an uncaught Server Error`,
+                    });
+                }
+                else if (dom === "ambiguous") {
+                    // A typed-empty return precedes the throw but no no-org guard is visible
+                    // before it — whether the return dominates the no-org path (vs. sitting
+                    // behind an unrelated condition while the throw still fires on no-org)
+                    // is not statically decidable. Could-not-judge, never a silent green.
+                    scan.cnj.push({
+                        rel: f.rel,
+                        n: block.lines[0].n,
+                        note: `${fn}: a typed empty/unauthorized return precedes the org-throw but no no-org guard is visible ahead of the throw — whether the return dominates the no-org path or the throw still fires on it is not statically decidable; a human must judge (never a silent green)`,
+                    });
+                }
+                else {
+                    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

package/dist/detectors/source/jobs.js

@@ -142,57 +142,128 @@ export function scanR20(files) {
 //
 // SOURCE READ: convex/credentials.ts issues a Bearer under a rate limit of
 // `maxPerWindow: 5` over `windowMs: 60_000` (lines 513-514), rejecting with a
-// `429` (line 523) — numeric rate + numeric window. PATTERN: a file that
-// references a rate-limit control (`rateLimit` / `maxPerWindow` / `windowMs`) is
-// conform iff BOTH a numeric window and a numeric max are present; a rate-limit
-// control whose bounds are only non-numeric placeholders (no numeric literal) is
-// the violation (unless a written exception is on file).
+// `429` (line 523); mcp-server/server-http.ts declares the DCR `/register`
+// limiter as the `REGISTER_RATE_LIMIT = 5` / `REGISTER_RATE_WINDOW_MS = 60_000`
+// const pair (lines 297-298) — numeric rate + numeric window at ONE site.
+//
+// SITE-scoped, not file-scoped. Two defects the old file-wide scan carried:
+//  (1) FALSE POSITIVE — `referencesRate` was true for ANY file containing the
+//      substring `rateLimit`, so the schema TABLE NAME `credentialsRateLimits`
+//      (convex/schema.ts) dragged schema.ts into the scan, and the file-wide
+//      window pattern then matched the unrelated `2000` in
+//      `body: v.string(), // truncated to 2000 chars` (schema.ts:540) — a
+//      phantom R-23 violation on a v.string() field. A schema table declaration
+//      is NOT a rate-limit control, and a numeric elsewhere in the file is not
+//      "this control's window".
+//  (2) FILE→SITE leak — because window/max/exception were found file-wide, ONE
+//      `rate-limit exception:` marker anywhere conformed EVERY control in the
+//      file. The window was never bound to its own max/control.
+//
+// PATTERN: locate each CONTROL SITE (a local region declaring/enforcing a
+// limiter — a `maxPerWindow:` key, a `*_RATE_LIMIT =` numeric const, a
+// `per minute/second/hour` check, or a written-exception marker). A schema
+// `defineTable(...)` block or a validator field (`v.number()`) is NEVER a
+// control site. Each site is judged WITHIN its own local line span: a numeric
+// max AND a numeric window there -> conform; else an exception marker bound to
+// THAT site -> conform; else -> violate. A numeric/exception on a DIFFERENT
+// site does not carry.
 // ---------------------------------------------------------------------------
-const RATE_REF = /ratelimit|maxperwindow|windowms|per\s+(minute|second|hour)/i;
-const NUMERIC_WINDOW = /windowms\s*:\s*\d|(\d[\d_]*)\s*(ms|_?000)\b|per\s+(minute|second|hour)/i;
-const NUMERIC_MAX = /maxperwindow\s*:\s*\d|\b\d+\s*(req|requests|per)\b/i;
+const NUMERIC_WINDOW = /windowms\s*:\s*\d|\brate_?window\w*\s*=\s*\d|(\d[\d_]*)\s*(ms|_?000)\b|per\s+(minute|second|hour)/i;
+const NUMERIC_MAX = /maxperwindow\s*:\s*\d|\brate_?limit\w*\s*=\s*\d|\b\d+\s*(req|requests|per)\b/i;
 const WRITTEN_EXCEPTION = /allow-unbounded|written exception|rate-limit exception/i;
-function referencesRate(f) {
-    return f.lines.some((l) => code(l) && RATE_REF.test(l.raw));
+// A limiter DECLARATION/enforcement, not a mere keyword mention:
+//  - `maxPerWindow:` — the per-window MAX key (the definitive throttle signal;
+//    a lone `windowMs` is only a duration and appears everywhere, so it is
+//    never an anchor by itself — only a window CONFIRMATION inside a site).
+//  - `*_RATE_LIMIT = <numeric>` — the const-pair form (server-http.ts).
+// A `per minute/second/hour` phrase is NOT an anchor: it appears in
+// human-readable rejection strings (`"...5 registrations per minute per IP."`)
+// that are not control declarations. It survives only as a WINDOW confirmation
+// inside a site already anchored by a real limiter declaration.
+const RATE_CONTROL_DECL = /maxperwindow\s*:|\brate_?limit\w*\s*=\s*\d/i;
+// A schema table declaration or a validator field is never a control SITE —
+// this is what excludes `credentialsRateLimits: defineTable(...)` and
+// `maxPerWindow: v.number()` from anchoring a site.
+const SCHEMA_DECL = /definetable\s*\(|v\.\w+\s*\(/i;
+// Local span geometry: consecutive anchors within MERGE_GAP lines collapse into
+// ONE site (a const group / a single call's arg object); the site's judgement
+// window is that anchor run padded by CONTEXT lines each side — never the file.
+const CONTEXT = 3;
+const MERGE_GAP = 3;
+function isControlAnchor(raw) {
+    // An explicit written exception always marks a site, even on an odd line.
+    if (WRITTEN_EXCEPTION.test(raw))
+        return true;
+    // A schema table decl / validator field is never a control site.
+    if (SCHEMA_DECL.test(raw))
+        return false;
+    return RATE_CONTROL_DECL.test(raw);
 }
 export function scanR23(files) {
     const scan = emptyScan();
     for (const f of files) {
-        if (!isJudgeable(f) || !referencesRate(f))
+        if (!isJudgeable(f))
             continue;
-        let windowLine = 0;
-        let maxLine = 0;
-        let exception = 0;
-        for (const l of f.lines) {
-            if (!code(l))
-                continue;
-            if (!windowLine && NUMERIC_WINDOW.test(l.raw))
-                windowLine = l.n;
-            if (!maxLine && NUMERIC_MAX.test(l.raw))
-                maxLine = l.n;
-            if (!exception && WRITTEN_EXCEPTION.test(l.raw))
-                exception = l.n;
-        }
-        if (windowLine && maxLine) {
-            scan.conform.push({
-                rel: f.rel,
-                n: maxLine,
-                note: `rate control declares a numeric max (line ${maxLine}) and window (line ${windowLine})`,
-            });
+        // 1. Collect the code-line indices that anchor a control site.
+        const anchors = [];
+        for (let i = 0; i < f.lines.length; i++) {
+            const l = f.lines[i];
+            if (code(l) && isControlAnchor(l.raw))
+                anchors.push(i);
         }
-        else if (exception) {
-            scan.conform.push({
-                rel: f.rel,
-                n: exception,
-                note: `rate bound absent but a written exception is on file (line ${exception})`,
-            });
+        if (anchors.length === 0)
+            continue;
+        // 2. Merge adjacent anchors (gap <= MERGE_GAP) into one site.
+        const sites = [];
+        for (const idx of anchors) {
+            const open = sites[sites.length - 1];
+            if (open && idx - open.last <= MERGE_GAP) {
+                open.last = idx;
+            }
+            else {
+                sites.push({ first: idx, last: idx });
+            }
         }
-        else {
-            scan.violate.push({
-                rel: f.rel,
-                n: windowLine || maxLine || 1,
-                note: "rate-limit control present but its bound is not numeric (placeholder) and no written exception on file",
-            });
+        // 3. Judge each site WITHIN its own local span — never file-wide.
+        for (const site of sites) {
+            const from = Math.max(0, site.first - CONTEXT);
+            const to = Math.min(f.lines.length - 1, site.last + CONTEXT);
+            let windowLine = 0;
+            let maxLine = 0;
+            let exception = 0;
+            for (let j = from; j <= to; j++) {
+                const l = f.lines[j];
+                if (!code(l))
+                    continue;
+                if (!windowLine && NUMERIC_WINDOW.test(l.raw))
+                    windowLine = l.n;
+                if (!maxLine && NUMERIC_MAX.test(l.raw))
+                    maxLine = l.n;
+                if (!exception && WRITTEN_EXCEPTION.test(l.raw))
+                    exception = l.n;
+            }
+            const repLine = f.lines[site.first].n;
+            if (windowLine && maxLine) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: maxLine,
+                    note: `rate control site declares a numeric max (line ${maxLine}) and window (line ${windowLine}) bound to the same site`,
+                });
+            }
+            else if (exception) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: exception,
+                    note: `rate bound absent but a written exception is bound to THIS control site (line ${exception})`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: windowLine || maxLine || repLine,
+                    note: "rate-limit control site present but its bound is not numeric (placeholder) and no written exception is bound to this site",
+                });
+            }
         }
     }
     return scan;

package/dist/detectors/source/write-isolation.js

@@ -13,6 +13,62 @@ const GATE_HELPER = /\b(?:require|ensure|assert)[A-Z][A-Za-z0-9_]*\s*\(/;
 // a TYPED unauthorized RESULT — the write returns a shape instead of throwing.
 const TYPED_UNAUTH_RETURN = /return\s+\{[^}]*\b(?:unauthorized|forbidden|noOrg|no_org|denied|ok\s*:\s*false)\b/i;
 const CONTRACT_MARKER = /write-contract:|client-must-not-write-before-org|isolation-contract:/i;
+// A TYPED EMPTY / UNAUTHORIZED RETURN broad enough to catch the CRM no-org branch
+// shape `return { items: [], unauthorized: true }` / `{ orgId: null }` — mirrors
+// R-50's TYPED_EMPTY_RETURN. TYPED_UNAUTH_RETURN above matches the explicit
+// unauthorized/denied vocabulary anywhere in the block (the write-returns-a-shape
+// green); this broader form is used ONLY by the domination heuristic, to recognise a
+// typed-empty return that lexically DOMINATES a later org-throw on the no-org branch.
+const TYPED_EMPTY_RETURN = /return\s+\{[^}]*\b(?:unauthorized|forbidden|noOrg|no_org|denied|empty)\b|return\s+\{[^}]*\b(?:orgSlug|orgId)\s*:\s*null\b|return\s+\{\s*items\s*:\s*\[\s*\]|return\s+\{[^}]*\bok\s*:\s*false\b/i;
+// A NO-ORG GUARD condition owning the no-org branch — used by the domination
+// heuristic to establish that a typed-empty return preceding the org-throw plausibly
+// owns the no-org path.
+const NO_ORG_GUARD = /if\s*\(\s*!\s*(?:scope\.|ctx\.[A-Za-z0-9_.]*)?(?:org|orgId|orgSlug|workspaceId|workspace|identity)\b|if\s*\([^)]*\b(?:org|orgId|orgSlug|workspaceId)\s*(?:===|==)\s*null/i;
+// DOMINATION heuristic (mirror of R-50 — a DOMINATED no-org throw). A bare public
+// mutation whose handler RETURNS a typed empty/unauthorized shape on the no-org
+// branch BEFORE it reaches the org-throw is NOT the two-absence violation: the throw
+// guards an org-PRESENT path (the CRM shape `if (!org) return { items: [] }` at the
+// top, then a later `requireWorkspaceId(...)` / `throw` reachable only once an org
+// exists). Judged TEXTUALLY and CONSERVATIVELY — a real throw is never silently
+// flipped to green:
+//   "dominated"  a typed-empty return lexically precedes the first org-throw AND a
+//                no-org guard also precedes that throw → conform (dominated throw).
+//   "ambiguous"  a typed-empty return precedes the throw but NO no-org guard is
+//                visible before it → could-not-judge (domination not established),
+//                never a silent green and never a false red.
+//   "none"       no typed-empty return precedes the throw → unchanged (the existing
+//                two-absence violate / marker CNJ chain stands).
+// Form B (Eta #20 REVISE — a no-org VALUE returned from a helper CALL whose NAME marks
+// the no-org case, guarded on that same value: `const empty = typedEmptyIfNoWorkspace(…);
+// if (empty) return empty;`). NARROW: the initializer is a call whose name marks no-org
+// (never any `return <identifier>`), and the guard is bound to THAT value returning it.
+const NO_ORG_EMPTY_HELPER = /(?:typedEmpty|emptyIfNo|ifNoWorkspace|ifNoOrg|noWorkspace|noOrg|unauthorizedIf|whenNoOrg|whenNoWorkspace|emptyWhenNo)/i;
+function namedValueDomination(before) {
+    const decl = /const\s+([A-Za-z0-9_]+)\s*=\s*(?:await\s+)?(?:[A-Za-z0-9_]+\.)*([A-Za-z0-9_]+)\s*\(/g;
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = decl.exec(before)) !== null) {
+        if (!NO_ORG_EMPTY_HELPER.test(m[2]))
+            continue;
+        const guard = new RegExp(`if\\s*\\(\\s*!?\\s*${m[1]}\\s*\\)\\s*(?:\\{\\s*)?return\\s+${m[1]}\\b`);
+        if (guard.test(before))
+            return true;
+    }
+    return false;
+}
+function throwDomination(blockText) {
+    const t1 = ORG_THROW.exec(blockText);
+    const t2 = WRITE_GATE_HELPER.exec(blockText);
+    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY);
+    if (!Number.isFinite(throwIdx))
+        return "none";
+    const before = blockText.slice(0, throwIdx);
+    if (namedValueDomination(before))
+        return "dominated";
+    if (!TYPED_EMPTY_RETURN.test(before))
+        return "none";
+    return NO_ORG_GUARD.test(before) ? "dominated" : "ambiguous";
+}
 function discoverWriteBuilders(files) {
     const b = {
         publicMutation: new Set([BASE_PUBLIC_MUTATION]),
@@ -191,6 +247,27 @@ export function scanR51(files) {
                     note: `${fn}: public mutation returns a typed unauthorized result on the no-org path — a pre-org client receives a shape it can render, not an uncaught Server Error`,
                 });
             }
+            else if (throwsOnNoOrg && throwDomination(blockText) === "dominated") {
+                // The no-org branch RETURNS a typed empty/unauthorized shape (behind an
+                // early no-org guard) BEFORE the org-throw is reachable — the throw guards
+                // an org-PRESENT path and never fires on the no-org render path. Not the
+                // two-absence violation. Conform (dominated throw).
+                scan.conform.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: public mutation returns a typed empty/unauthorized shape on the no-org branch (an early no-org guard) BEFORE the org-throw is reachable — the throw guards an org-present path and never fires on the no-org render path. A pre-org client receives a shape, not an uncaught Server Error`,
+                });
+            }
+            else if (throwsOnNoOrg && throwDomination(blockText) === "ambiguous") {
+                // A typed-empty return precedes the throw but no no-org guard is visible
+                // ahead of it — whether the return dominates the no-org path is not
+                // statically decidable. Could-not-judge, never a silent green.
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: block.lines[0].n,
+                    note: `${fn}: a typed empty/unauthorized return precedes the org-throw but no no-org guard is visible ahead of the throw — whether the return dominates the no-org path or the throw still fires on it is not statically decidable; a human must judge (never a silent green)`,
+                });
+            }
             else if (hasMarker) {
                 // A throwing write that CARRIES a write-contract marker: the marker is the
                 // author's recorded claim that a client cannot reach this write pre-org —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A conformance instrument that measures the VantagePeers backend against the pinned backend standard. The THIRD doctor built ON the @vantageos/mcp-doctor engine — never a third engine. It consumes runDoctor/renderTable and adds only detectors.",
   "type": "module",
   "main": "./dist/cli.js",