@vantageos/backend-doctor 0.1.10 → 0.1.12

package/dist/detectors/source/writesafety.js

@@ -116,10 +116,85 @@ export function scanR18(files) {
 // atomic invariant (the bundle imported wholesale) is implied — flagged
 // non-conforming (judgement: a human confirms the invariant truly needs
 // atomicity). An action with ≤1 runMutation conforms.
+//
+// WRITTEN-EXCEPTION CARVE-OUT (Eta R-29 ruling, task k173kmwbr1r8x2h7bkk7xek4z18dhtqj,
+// approved 2026-08-31 — mirrors the R-23 rate-adjacent carve-out #1248/#21 and the
+// R-51 write-contract marker disposition #141): the <=1-runMutation bar has NO room
+// for two shapes that are legitimately more than one runMutation yet carry no cross-
+// write invariant to violate —
+//   (1) pre-io-gate-then-single-atomic-write: a security/existence GATE runMutation
+//       that must precede an I/O read (e.g. ctx.storage.get) followed by ONE atomic
+//       write — the gate is not part of the write's transaction and cannot be folded
+//       into it (kb.ts storeDocumentChunked shape); and
+//   (2) independent-per-item-loop-writes: a loop whose per-item writes are each
+//       independently atomic, where NO invariant spans two of them, so collapsing
+//       them into one mutation "would game the regex without changing atomicity"
+//       (okfBundleNode importOkfBundle shape).
+// An action that would be flagged non-conforming may carry an `atomicity-exception:`
+// marker naming EXACTLY ONE of those two shapes. Per Eta's three conditions:
+//   COND 1 — the disposition is COULD-NOT-JUDGE, never conform. A marker records a
+//     CLAIM that reaches a human reviewer; it never closes the rule green (same as
+//     the R-51 marker, #141).
+//   COND 2 — the marker MUST name which shape it claims, because the two are checked
+//     differently and the reviewer must know which question to ask.
+//   COND 3 — the dangerous shape is (2): "unbounded loop, each write independently
+//     atomic" is a sentence anyone can write about a split invariant. So shape (2)
+//     is only honoured when the region ALSO names the loop (for/for-of/.forEach/.map)
+//     AND states the independence (no invariant spans two writes). A shape-(2) marker
+//     that names neither the loop nor the independence is INCOMPLETE — it does not buy
+//     could-not-judge; the site stays non-conforming until the claim is well-formed.
+// A well-formed marker → could-not-judge (the reviewer verifies the per-site claim).
+// No marker, an unknown shape, or an incomplete shape-(2) claim → non-conforming.
 // ---------------------------------------------------------------------------
 const ACTION_OPEN = /export\s+const\s+(\w+)\s*=\s*action\s*\(/;
 const NEXT_EXPORT = /export\s+const\s+\w+\s*=/;
 const RUN_MUTATION = /ctx\.runMutation\s*\(/;
+// The carve-out marker + the two shape names it may claim (COND 2).
+const ATOMICITY_MARKER = /atomicity-exception:\s*(pre-io-gate-then-single-atomic-write|independent-per-item-loop-writes|gate-then-idempotent-reingest)/i;
+const SHAPE_PER_ITEM_LOOP = "independent-per-item-loop-writes";
+const SHAPE_PRE_IO_GATE = "pre-io-gate-then-single-atomic-write";
+// Shape (3) — gate-then-idempotent-reingest (Eta ruling #26 follow-up, 2026-08-31,
+// task k1725z23c095p08q7nxp74mkhn8dg8e2). kb.ts storeDocumentChunked is a leading
+// gate mutation, a conditional supersede/dedup keyed on a STABLE namespace, and a
+// per-item re-insert loop — there IS an invariant between the supersede and the loop
+// (so it is NOT shape 2's "no invariant spans two"), but a re-ingest of the same
+// stable key converges on exactly one current set (supersede is a no-op when already
+// applied; the loop re-creates the full set; residue is orphaned rows, not corruption).
+// Eta accepted this as a THIRD checkable shape, NOT an atomic-ingest task (forcing one
+// batched mutation over an unbounded chunk set trades a self-healing transient for a
+// transaction-limit failure on large documents). Its sub-conditions a reader can check:
+// (a) a leading gate runMutation, (b) a supersede/dedup keyed on a stable namespace,
+// (c) the recovering re-insert loop — AND the marker MUST STATE THE CONVERGENCE
+// explicitly, not merely name the shape (or the carve-out becomes a vocabulary).
+const SHAPE_GATE_REINGEST = "gate-then-idempotent-reingest";
+const REINGEST_SUPERSEDE = /supersede|dedup|find-?or-?create|isLatest|\.unique\s*\(/i;
+const STABLE_KEY = /namespace|docId|content-?hash|by_namespace/i;
+// NB: deliberately EXCLUDES the bare token "reingest" — the shape name itself is
+// "gate-then-idempotent-reingest", so matching "re-?ingest" would let the token satisfy
+// its own convergence sub-condition. Convergence must be stated BEYOND naming the shape.
+const CONVERGENCE_STATED = /converge|one current set|full (?:current )?set|self-?heal|no-?op when already|re-?creates the full/i;
+// Shape-(2) sub-conditions (COND 3): the region must NAME the loop and STATE the
+// write independence — neither is inferable, both are required of the claim.
+const LOOP_NAMED = /\bfor\s*\(|\bfor\s+(?:const|let|var|await)\b|\.forEach\s*\(|\.map\s*\(|\bwhile\s*\(/;
+const INDEPENDENCE_STATED = /no\s+invariant\s+spans|invariant\s+spans\s+no|writes?\s+are\s+independent|independently\s+atomic|no\s+cross-write\s+invariant/i;
+// Shape-(1) sub-condition (Eta REVISE #26, 2026-08-31): "a pre-I/O gate mutation
+// precedes a single atomic write" describes itself CHECKABLY — it is EXACTLY TWO
+// ctx.runMutation calls, the FIRST a gate (require*/assert*/ensure*/bind*). A shape-1
+// marker on anything else (three calls, an unbounded loop, a first call that is not a
+// gate) is INCOMPLETE and stays non-conforming, exactly as an incomplete shape-2 does
+// — otherwise eleven words in a comment remove a real violation from the #1250 prod
+// gate (abstentions do not block; mechanical_violations is the sole driver), and the
+// mechanical count that gate rests on is no longer honest.
+const GATE_CALLEE = /\b(require|assert|ensure|bind)\w*/i;
+// Shape (3) narrows the gate stems: `ensure*` is the standard prefix for an UPSERT
+// WRITE helper (ensureUser/ensureWorkspace/ensureRow), so on the reingest shape — whose
+// FIRST runMutation is the gate — accepting `ensure*` lets a first WRITE renamed the
+// usual way (e.g. _insertImportedMemory -> ensureImportedMemory) masquerade as the gate
+// and buy the exemption, removing a real violation from the #1250 prod gate (Eta REVISE
+// #27, probe B). `bind` STAYS (bindOrAssertStorageOwnership is kb.ts's real gate, the
+// case this shape exists for); `require`/`assert` are unambiguous. Shapes 1/2 keep the
+// broader GATE_CALLEE.
+const GATE_CALLEE_REINGEST = /\b(require|assert|bind)\w*/i;
 export function scanR29(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -129,15 +204,91 @@ export function scanR29(files) {
         let openLine = 0;
         let count = 0;
         let firstMut = 0;
+        let firstMutCallee = "";
+        let calleeNeedsMore = false;
+        let region = "";
         const flush = () => {
             if (!inAction)
                 return;
             if (count > 1) {
-                scan.violate.push({
-                    rel: f.rel,
-                    n: firstMut || openLine,
-                    note: `action ${inAction} orchestrates ${count} ctx.runMutation calls — several mutations across a race window, not one atomic transaction`,
-                });
+                const marker = ATOMICITY_MARKER.exec(region);
+                const shape = marker?.[1]?.toLowerCase();
+                // Shape (1) is honoured ONLY as exactly two runMutations whose first is a
+                // gate call; shape (2) only when the loop is named and independence stated.
+                const shapeGate = count === 2 && GATE_CALLEE.test(firstMutCallee);
+                // Shape (3) sub-conditions: a leading gate runMutation, a supersede/dedup on
+                // a stable namespace, a re-insert loop, AND an explicit convergence statement.
+                const shapeReingest = GATE_CALLEE_REINGEST.test(firstMutCallee) &&
+                    REINGEST_SUPERSEDE.test(region) &&
+                    STABLE_KEY.test(region) &&
+                    LOOP_NAMED.test(region) &&
+                    CONVERGENCE_STATED.test(region);
+                const shapeComplete = shape === SHAPE_PER_ITEM_LOOP
+                    ? LOOP_NAMED.test(region) && INDEPENDENCE_STATED.test(region)
+                    : shape === SHAPE_PRE_IO_GATE
+                        ? shapeGate
+                        : shape === SHAPE_GATE_REINGEST
+                            ? shapeReingest
+                            : false;
+                if (shape && shapeComplete) {
+                    // COND 1: a well-formed marker yields COULD-NOT-JUDGE, never conform —
+                    // the claim is deferred to the reviewer, who verifies it per site.
+                    scan.cnj.push({
+                        rel: f.rel,
+                        n: firstMut || openLine,
+                        note: `action ${inAction} issues ${count} ctx.runMutation calls AND carries an atomicity-exception marker claiming shape "${shape}" — ${shape === SHAPE_PER_ITEM_LOOP
+                            ? "the region names its loop and states the per-item writes are independently atomic (no invariant spans two)"
+                            : shape === SHAPE_GATE_REINGEST
+                                ? "a leading gate runMutation, a supersede/dedup keyed on a stable namespace, and a recovering re-insert loop, with the convergence stated explicitly — a re-ingest of the same stable key converges on one current set"
+                                : "exactly two runMutations, the first a gate (require*/assert*/ensure*/bind*) preceding a single atomic write, which R-29's <=1 bar has no room for"}. R-29 refuses (a reviewer verifies the claim per site) — never a silent green (Eta ruling 2026-08-31)`,
+                    });
+                }
+                else if (shape === SHAPE_GATE_REINGEST) {
+                    // Shape (3) claimed but a sub-condition is absent — an incomplete claim does
+                    // NOT buy could-not-judge (Eta: a shape names a checkable sub-condition, or
+                    // the carve-out becomes a vocabulary).
+                    const missing = [
+                        !GATE_CALLEE_REINGEST.test(firstMutCallee) && "a leading gate runMutation (require*/assert*/bind* — ensure* is an upsert-write stem, excluded here)",
+                        !REINGEST_SUPERSEDE.test(region) && "a supersede/dedup call",
+                        !STABLE_KEY.test(region) && "a stable namespace key (namespace/docId/contentHash)",
+                        !LOOP_NAMED.test(region) && "a re-insert loop (for/for-of/.forEach/.map)",
+                        !CONVERGENCE_STATED.test(region) && "an explicit convergence statement (converges on one current set / re-ingest / self-heals)",
+                    ].filter(Boolean).join("; ");
+                    scan.violate.push({
+                        rel: f.rel,
+                        n: firstMut || openLine,
+                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls with an atomicity-exception "${SHAPE_GATE_REINGEST}" marker that is INCOMPLETE — missing: ${missing}. The marker must state the convergence, not merely name the shape`,
+                    });
+                }
+                else if (shape === SHAPE_PRE_IO_GATE) {
+                    // Eta REVISE #26: shape (1) claimed but NOT exactly-two-with-a-gate-first
+                    // — an incomplete claim does NOT buy could-not-judge.
+                    scan.violate.push({
+                        rel: f.rel,
+                        n: firstMut || openLine,
+                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls with an atomicity-exception "${SHAPE_PRE_IO_GATE}" marker that is INCOMPLETE — this shape is EXACTLY TWO runMutations whose FIRST is a gate (require*/assert*/ensure*/bind*); here ${count !== 2
+                            ? `there are ${count}, not two`
+                            : "the first runMutation is not a gate call"}. A gate-then-single-write is checkable; a marker cannot remove a >2-call or loop site from the gate`,
+                    });
+                }
+                else if (shape === SHAPE_PER_ITEM_LOOP) {
+                    // COND 3: shape (2) claimed but the loop and/or independence is not stated
+                    // — an incomplete claim does NOT buy could-not-judge.
+                    scan.violate.push({
+                        rel: f.rel,
+                        n: firstMut || openLine,
+                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls with an atomicity-exception "${SHAPE_PER_ITEM_LOOP}" marker that is INCOMPLETE — the per-item-loop shape must NAME the loop (for/for-of/.forEach/.map) AND STATE the write independence (no invariant spans two writes). Complete the claim or split the invariant into one mutation`,
+                    });
+                }
+                else {
+                    scan.violate.push({
+                        rel: f.rel,
+                        n: firstMut || openLine,
+                        note: `action ${inAction} orchestrates ${count} ctx.runMutation calls — several mutations across a race window, not one atomic transaction${marker === null && /atomicity-exception:/i.test(region)
+                            ? " (an atomicity-exception marker is present but names no known shape — it must name pre-io-gate-then-single-atomic-write or independent-per-item-loop-writes)"
+                            : ""}`,
+                    });
+                }
             }
             else if (count === 1) {
                 scan.conform.push({
@@ -148,8 +299,6 @@ export function scanR29(files) {
             }
         };
         for (const l of f.lines) {
-            if (!code(l))
-                continue;
             const open = ACTION_OPEN.exec(l.raw);
             if (open) {
                 flush();
@@ -157,17 +306,41 @@ export function scanR29(files) {
                 openLine = l.n;
                 count = 0;
                 firstMut = 0;
+                firstMutCallee = "";
+                calleeNeedsMore = false;
+                region = l.raw;
                 continue;
             }
-            if (inAction && NEXT_EXPORT.test(l.raw) && !ACTION_OPEN.test(l.raw)) {
+            if (inAction && code(l) && NEXT_EXPORT.test(l.raw) && !ACTION_OPEN.test(l.raw)) {
                 flush();
                 inAction = "";
+                region = "";
                 continue;
             }
-            if (inAction && RUN_MUTATION.test(l.raw)) {
+            if (!inAction)
+                continue;
+            // Accumulate the WHOLE region (comments included) so the marker — which
+            // lives in a comment — is visible; only count runMutation on code lines.
+            region += `\n${l.raw}`;
+            // The callee of the FIRST runMutation identifies the gate (shape 1). It may
+            // sit on the same line (`ctx.runMutation(internal.kb.assertX, {`) or wrap to
+            // the next code line (`const id = await ctx.runMutation(\n  internal.kb.assertX,`);
+            // grab the paren-tail here and one more code line if the tail was empty.
+            if (code(l) && calleeNeedsMore) {
+                firstMutCallee += ` ${l.raw.trim()}`;
+                calleeNeedsMore = false;
+            }
+            if (code(l) && RUN_MUTATION.test(l.raw)) {
                 count++;
-                if (!firstMut)
+                if (!firstMut) {
                     firstMut = l.n;
+                    const tail = l.raw.slice(l.raw.search(RUN_MUTATION)).replace(RUN_MUTATION, "");
+                    firstMutCallee = tail;
+                    // If the paren-tail carries no identifier yet, the callee wrapped — take
+                    // the next code line too.
+                    if (!/\w/.test(tail))
+                        calleeNeedsMore = true;
+                }
             }
         }
         flush();

package/package.json

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