@vantageos/backend-doctor 0.1.4 → 0.1.5

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/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.5",
   "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",