@vantageos/backend-doctor 0.1.11 → 0.1.12

package/dist/detectors/source/writesafety.js

@@ -150,9 +150,29 @@ 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*\(/;
@@ -166,6 +186,15 @@ const INDEPENDENCE_STATED = /no\s+invariant\s+spans|invariant\s+spans\s+no|write
 // 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) {
@@ -187,11 +216,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_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
-                        : 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 +238,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*/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) {

package/package.json

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