@vantageos/backend-doctor 0.1.9 → 0.1.11

package/dist/detectors/source/jobs.js

@@ -94,8 +94,19 @@ export function scanR19(files) {
 const JOB_FILE = /recurring|monitor|sweep|poll|resolver|cleanup|digest|cron/i;
 const RUN_BOUND = /\.take\s*\(|_cap\b|\blimit\b/i;
 const OUTCOME_LOG = /console\.(log|error|warn|info)\s*\(/;
+// ACTUAL job content — a Convex data operation, a scheduler/cron registration, or
+// a scheduled-function handler. Eta ruling (2026-08-31): a file is a background-job
+// SUBJECT only if its content is a job, never its FILENAME alone — otherwise a pure
+// env/string helper whose basename merely contains "monitor" (errorMonitorGroupKey,
+// errorMonitorKillSwitch, errorMonitorDeployWindow — no ctx.db, no scheduler, no
+// cron) is scored as an unbounded job, and R-20 (unlike R-23) has no written-exception
+// carve-out to clear the false positive. Tighten the subject, do not add a carve-out.
+const JOB_CONTENT = /ctx\.db\.|\.collect\s*\(|\.paginate\s*\(|ctx\.scheduler\.|\bcron(s|Jobs)?\b|internalAction\s*\(|internalMutation\s*\(/i;
 function isJobFile(f) {
-    return JOB_FILE.test(base(f.rel));
+    if (!JOB_FILE.test(base(f.rel)))
+        return false;
+    // require job CONTENT on an executing line, not a filename match alone.
+    return f.lines.some((l) => code(l) && JOB_CONTENT.test(l.raw));
 }
 export function scanR20(files) {
     const scan = emptyScan();

package/dist/detectors/source/writesafety.js

@@ -116,10 +116,56 @@ 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)/i;
+const SHAPE_PER_ITEM_LOOP = "independent-per-item-loop-writes";
+const SHAPE_PRE_IO_GATE = "pre-io-gate-then-single-atomic-write";
+// 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;
 export function scanR29(files) {
     const scan = emptyScan();
     for (const f of files) {
@@ -129,15 +175,63 @@ 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);
+                const shapeComplete = shape === SHAPE_PER_ITEM_LOOP
+                    ? LOOP_NAMED.test(region) && INDEPENDENCE_STATED.test(region)
+                    : shape === SHAPE_PRE_IO_GATE
+                        ? shapeGate
+                        : 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)"
+                            : "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_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 +242,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 +249,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)
                 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 (inAction && RUN_MUTATION.test(l.raw)) {
+            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.9",
+  "version": "0.1.11",
   "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",