@vantageos/backend-doctor 0.1.11 → 0.1.13

package/dist/detectors/source/writesafety.js

@@ -150,22 +150,52 @@ 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)/i;
+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
+// ctx.runMutation calls, the FIRST a gate (require*/assert*/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;
+// The gate stem excludes `ensure*` — the standard prefix for an UPSERT WRITE helper
+// (ensureUser/ensureWorkspace/ensureRow). Both shapes whose FIRST runMutation is the gate
+// (shape 1 pre-io-gate, shape 3 gate-then-idempotent-reingest) checked the callee NAME, so
+// accepting `ensure*` let a first WRITE renamed the usual way (_insertImportedMemory ->
+// ensureImportedMemory) masquerade as the gate and buy the exemption — removing a real
+// violation from the #1250 prod gate. Fixed at the CLASS (Eta REVISE #27 probe B closed
+// shape 3; this closes the same hole in shape 1, task k179fmje8vb7y0tbjdmxbzg78h8dhj3q):
+// the defect was a gate sub-condition decided by a name stem that idiomatically names
+// writes, so the fix is one narrowed stem set for every gate check. `bind` STAYS
+// (bindOrAssertStorageOwnership is kb.ts's real gate); `require`/`assert` are unambiguous.
+const GATE_CALLEE = /\b(require|assert|bind)\w*/i;
 export function scanR29(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -187,11 +217,20 @@ export function scanR29(files) {
                 // 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.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
-                        : false;
+                        : 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.
@@ -200,7 +239,26 @@ export function scanR29(files) {
                         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)"
-                            : "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)`,
+                            : 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*/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.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) {
@@ -209,7 +267,7 @@ export function scanR29(files) {
                     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
+                        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*/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`,
                     });

package/package.json

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