@vantageos/backend-doctor 0.1.2 → 0.1.4

package/fixtures/{backend-standard-4265226e.md → backend-standard-dcec1ba.md}

@@ -334,6 +334,7 @@ The five: **production-ready · enterprise-grade · highly secure · token-effic
 | R-47 an incompletable read refuses, never returns a partial set | production-ready · highly secure |
 | R-48 authority total over its rows; a declared tier unused does not exist | highly secure · multi-organisation multi-tenant · enterprise-grade |
 | R-50 org isolation on a subscribed read is a typed empty result, never an uncaught throw | highly secure · multi-organisation multi-tenant · production-ready |
+| R-51 a public write returns a typed unauthorised result on no-org, never an uncaught throw into a pre-org client | highly secure · multi-organisation multi-tenant · production-ready |
 
 **Deletion candidates — rules serving none of the five: none.**
 
@@ -649,7 +650,10 @@ R-5 and R-10 make each mutation ask the right question caller-by-caller — *may
 **Detector spec.** *control kind:* static (+ delivery gate on the tier-usage half). *reads:* per governed table (derived from `schema.ts`), the set of caller tiers each mutation on it accepts, derived from the delivered mutation code — never a list the check keeps about itself; and the R-5 tier vocabulary from the pinned standard. *red:* a table whose union of accepting tiers cannot reach a row created by a non-actor (a `"system"`/webhook/migration/scheduler creator with no tier that governs it); OR a tier declared in the pinned vocabulary and used by zero mutations. *green:* every governed table has at least one tier reaching all its rows including non-actor-created ones, and every declared tier is used by at least one mutation. *kind:* judgement — deriving each mutation's accepting tiers and the tier-usage census is mechanical; whether a table's rows are genuinely all reachable (the non-actor-creator case, and whether an unreachable row is an accepted deliberate lock) is human, so the detector names the unreachable-row tables and the unused tiers as a work list and returns could-not-judge on the disposition, never present/absent by vacuity. **Coverage fails on itself:** the table list is derived from the schema; every table is ANALYSED or SKIPPED-with-a-written-reason; a table neither analysed nor exempted, or one the check cannot parse, FAILS — the whole point of this rule is a defect that reports nothing.
 
 **R-50 — org isolation on a reactively-subscribed read is a TYPED EMPTY / UNAUTHORISED RESULT, never an uncaught throw.** A public `query` a client subscribes to reactively (a layout's `useQuery`) that resolves the caller's organisation and, on the missing-org path, **throws** — an org-keyed `ConvexError`, or a `requireOrgId`/`requireWorkspaceId`/`ensureCurrent` helper that throws — hands the subscribing client an **uncaught Server Error** it has no imperative call site to catch. The isolation is correct in intent and wrong in shape: a subscription cannot `try/catch` a query the way a mutation's caller can, so the throw surfaces as a crashed render. Such a read returns a **typed empty / unauthorised result** the client can render (the fail-closed org resolver — VP's `withOrgScope` returns an empty scope on no identity, never throws), or it documents that the layout must not subscribe. This is the 2026-08-30 vCRM-Preview incident: `workspaces:ensureCurrent` and `prefs:sidebar` threw `ConvexError` uncaught while the app shell subscribed, and the page rendered "NoOrg copy, no org button" over an unhandled throw — the operator saw a broken screen, not a refusal. **Frontier — this EXTENDS the R-11 isolation family, it does not restate it.** **R-11** governs *where* the scope key is applied — an in-query index predicate, never a post-query `.filter` — a correctness/cost property of a query that already knows its org. R-50 governs the case *before* that: the caller has **no** org, and the question is the **shape of the answer**, not the locus of the predicate — a query fully R-11-conformant still fails R-50 if its no-org branch throws into a subscription. **R-16** is the error contract for a read that *may* refuse: R-50 is the narrower law that a **reactively-subscribed** read may not refuse by *throwing at all* — because its consumer is a subscription, the only honest refusal is a typed unauthorised *value*, not an exception. And R-50 is deliberately **narrower than "any org throw"**: a **mutation** that refuses an unauthorised write via `requireOrgAdmin` throwing `RBAC_DENIED` is **correct** and out of scope — a write refusal is caught by its imperative caller, never surfaced as an uncaught subscription error. Conflating the two would flag every legitimate admin-gated mutation; R-50 governs reactive reads only. *(Source: the 2026-08-30 vCRM-Preview operator report — `workspaces:ensureCurrent` + `prefs:sidebar` uncaught `ConvexError` on a subscribed layout; and VP's own `convex/lib/auth.ts` `withOrgScope`, the fail-closed non-throwing resolver that returns an empty scope rather than throw, the shape this rule requires.)*
-**Detector spec.** *control kind:* static (source scan over the public query surface). *reads:* the target's `convex/` source; every public `query` opener (not `internalQuery`, not `mutation`/`action`) and its brace-delimited handler body. *red:* a public query whose body throws on the missing-org path (an org-keyed `ConvexError` — `NO_ORG`/`ORG_REQUIRED`/`RBAC_DENIED` — or a throw-on-no-org helper) with **no** fail-closed non-throwing resolver (`withOrgScope`) and **no** documented isolation contract marker in the same handler. *green:* a public query that carries the fail-closed resolver or a documented client contract — the subscribing client always receives a typed shape. *out of scope:* a `mutation`/`action` (imperative caller can catch) and a query that does neither org-throw nor fail-closed resolve (not this rule's subject). *kind:* mechanical — the presence of an org-isolation throw and the presence of a fail-closed resolver / contract marker are both read from the delivered source; `could-not-judge` is reserved for a query block whose braces cannot be delimited, never for "a person should read this". **Coverage fails on itself:** a tree with no public query returns could-not-judge naming the empty scan, never a clean bill.
+**Detector spec.** *control kind:* static (source scan over the public query surface). *reads:* the target's `convex/` source; every public `query` opener (not `internalQuery`, not `mutation`/`action`) and its brace-delimited handler body. *red:* a public query whose body throws on the missing-org path (an org-keyed `ConvexError` — `NO_ORG`/`ORG_REQUIRED`/`RBAC_DENIED` — or a throw-on-no-org helper) with **no** fail-closed non-throwing resolver (`withOrgScope`) and **no** documented isolation contract marker in the same handler. *green:* a public query that carries the fail-closed resolver or a documented client contract — the subscribing client always receives a typed shape. *out of scope:* a `mutation`/`action` (imperative caller can catch — but see **R-51** for the write a client shell issues before an org exists) and a query that does neither org-throw nor fail-closed resolve (not this rule's subject). *kind:* mechanical — the presence of an org-isolation throw and the presence of a fail-closed resolver / contract marker are both read from the delivered source; `could-not-judge` is reserved for a query block whose braces cannot be delimited, never for "a person should read this". **Coverage fails on itself:** a tree with no public query returns could-not-judge naming the empty scan, never a clean bill.
+
+**R-51 — a public MUTATION whose no-org path throws NO_ORG into a pre-org client is a VIOLATION, not a refusal.** The write counterpart of R-50. A signed-in product write (`companies.create`, `contacts.create`, `fields.createDefinition`, `ask.send`) that resolves the org through `getEffectiveWorkspaceId` / `requireWriteAccess` and **throws** `ConvexError` NO_ORG when no org is resolved hands the client an **uncaught Server Error** on an ordinary render path — because the app **shell can issue the write before an org exists**. In the 2026-08-30 vCRM incident the reads were typed-empty (R-50 clean), so `/app` looked alive, and then every write on it threw NO_ORG: the second half of the same crash, which R-50 could not name because it excluded mutations. Such a write returns a **typed unauthorised result** the client can render, or it documents (a `write-contract:` marker) that a client cannot reach it before an org. **Frontier — R-51 is NOT R-16 and NOT R-50.** **R-16** is the error contract for a write that legitimately **refuses a chosen unauthorised action** — a `{code,field/scope,message}` throw is correct there, because an imperative caller catches it. R-51 is the narrower case where the caller is the **shell's ordinary render**, reaching the write **before** an org is resolved: the throw is then not a refusal of a chosen action but a crash, and the honest shape is a typed value, not an exception (or the write is specified unreachable pre-org). **R-50** is the same defect on the READ side (a subscribed query); R-51 is the WRITE side R-50's own frontier pointed at ("a `mutation`/`action` … out of scope"), so no gap-table cell is left blank. Because the React shell is **not in `convex/`**, the detector cannot see whether a client reaches a write pre-org, so it **never silent-PASSes a throwing write**: it refuses (could-not-judge) naming the write / its `customMutation` wrapper when it cannot judge the client obligation, and is red only on a bare throw with no typed-unauthorised return and no contract. *(Source: the 2026-08-30 vCRM operator report — four signed-in writes throwing `ConvexError` NO_ORG through `convex/model/access.ts` `requireWriteAccess` + `getEffectiveWorkspaceId`, while R-50-clean reads made the page look alive.)*
+**Detector spec.** *control kind:* static (source scan over the public mutation surface). *reads:* the target's `convex/` source; every public `mutation` opener and every write built through a `customMutation` wrapper (the `writeMutation = customMutation(mutation, customCtx(requireWriteAccess))` idiom), and its brace-delimited handler / the wrapper's `customCtx`. *red:* a bare public mutation whose no-org path throws (an org-keyed `ConvexError` or `requireWriteAccess`/`requireWorkspaceId`/`getEffectiveWorkspaceId`) with **no** typed-unauthorised return and **no** documented `write-contract` marker. *green:* a public mutation that returns a typed unauthorised result on the no-org path, or carries a documented client contract. *could-not-judge (never a silent PASS):* a write built through a **gated** `customMutation` wrapper (its `customCtx` runs a throwing write/org gate) — the throw lives in the shared wrapper and client reachability is not visible from `convex/`, so the detector names the wrapper and counts its dependent writes; also an unresolvable-base wrapper, and an undelimitable block. *out of scope:* a `query` (that is R-50), and a `customMutation(internalMutation, …)` wrapper. *kind:* mechanical. **Coverage fails on itself:** a tree with no public mutation returns could-not-judge naming the empty scan, never a clean bill.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",