fini-proof 0.3.0

package/src/engines/vendor/vacuous-spec-core.mjs

@@ -0,0 +1,1066 @@
+// PROVENANCE — ported, not rewritten.
+//   source : finipe/scripts/ci/check-vacuous-spec.mjs (EOS F4 vacuous-spec detector)
+//   commit : finipe 4ac53b367b348d23d000629cb14e19633beb9613 (branch claude/aeos-factory-batch-2026-09-26;
+//            file last changed in 04152854b; rule families from 4de27d974)
+//   kept   : lines 159-1210 verbatim (masking, block finder, all 11 rule families, helper resolution).
+//   changed: Finipe range resolution (resolveBase/changedSpecFiles) removed — the fini-proof runner owns scope;
+//            ROOT is settable (setRoot) instead of the Finipe repo root; CLI/self-test/guard dropped
+//            (self-test cases live on as negative controls in src/engines/hollow-tests.mjs + test/).
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+let ROOT = process.cwd()
+export function setRoot(r) { ROOT = r }
+
+// `}` `(` `)` that only exists inside text. Same technique this repo already
+// uses in backend/scripts/check-super-admin-root-only.ts's literals() /
+// backend/scripts/lib/strip-ts-comments.ts, reimplemented in plain .mjs here
+// because this gate must run without ts-node (host law §2 — no toolchain, no
+// jest, on the Mac).
+// ─────────────────────────────────────────────────────────────────────────
+function regexMayStart(source, i) {
+  let k = i - 1
+  while (k >= 0 && (source[k] === ' ' || source[k] === '\t')) k--
+  if (k < 0) return true
+  const p = source[k]
+  if ('(,=:[!&|?{};\n+-*%<>~^'.includes(p)) return true
+  const word = /([A-Za-z_$][\w$]*)$/.exec(source.slice(Math.max(0, k - 12), k + 1))
+  return !!word && ['return', 'typeof', 'case', 'in', 'of', 'delete', 'void', 'throw', 'new', 'else', 'do', 'await', 'yield'].includes(word[1])
+}
+
+export function maskStringsAndComments(source) {
+  const out = source.split('')
+  const n = out.length
+  let i = 0
+  while (i < n) {
+    const c = source[i]
+    if (c === '/' && source[i + 1] === '/') {
+      let j = i
+      while (j < n && source[j] !== '\n') { out[j] = ' '; j++ }
+      i = j
+      continue
+    }
+    if (c === '/' && source[i + 1] === '*') {
+      out[i] = ' '; out[i + 1] = ' '
+      let j = i + 2
+      while (j < n && !(source[j] === '*' && source[j + 1] === '/')) {
+        if (source[j] !== '\n') out[j] = ' '
+        j++
+      }
+      if (j < n) { out[j] = ' '; out[j + 1] = ' '; j += 2 }
+      i = j
+      continue
+    }
+    // REGEX LITERAL (factory batch 2026-09-26): `/\{([^}]*)\}/` holds braces the
+    // bracket matcher counted, so a test whose body carried such a literal was cut
+    // short at the first unbalanced `}` and read as NO_ASSERTION. A `/` starts a
+    // regex (not a division) when the previous significant character cannot end an
+    // operand, or the previous word is `return`/`typeof`/…; its contents — including
+    // a character class, where `/` does not end the literal — are blanked like a
+    // string's.
+    if (c === '/' && source[i + 1] !== '/' && source[i + 1] !== '*' && regexMayStart(source, i)) {
+      let j = i + 1
+      let inClass = false
+      let closed = false
+      while (j < n && source[j] !== '\n') {
+        const d = source[j]
+        if (d === '\\') { out[j] = ' '; if (j + 1 < n && source[j + 1] !== '\n') out[j + 1] = ' '; j += 2; continue }
+        if (d === '[') inClass = true
+        else if (d === ']') inClass = false
+        else if (d === '/' && !inClass) { closed = true; break }
+        out[j] = ' '
+        j++
+      }
+      if (closed) { i = j + 1; continue }
+      // not a regex after all (no closing `/` on the line): undo, treat as an operator
+      for (let k = i + 1; k < j; k++) out[k] = source[k]
+      i++
+      continue
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c
+      out[i] = ' '
+      let j = i + 1
+      while (j < n && source[j] !== quote) {
+        if (source[j] === '\\') {
+          if (source[j] !== '\n') out[j] = ' '
+          j++
+          if (j < n && source[j] !== '\n') out[j] = ' '
+          j++
+          continue
+        }
+        if (source[j] !== '\n') out[j] = ' '
+        j++
+      }
+      if (j < n) { out[j] = ' '; j++ }
+      i = j
+      continue
+    }
+    i++
+  }
+  return out.join('')
+}
+
+function lineAt(source, idx) {
+  let line = 1
+  for (let i = 0; i < idx && i < source.length; i++) if (source[i] === '\n') line++
+  return line
+}
+
+/** Find the index of the `{`/`(` matching the one at `openIdx`, scanning the
+ *  MASKED text so nothing inside a string/comment can desync the count. */
+function matchBracket(masked, openIdx, openCh, closeCh) {
+  let depth = 0
+  for (let i = openIdx; i < masked.length; i++) {
+    if (masked[i] === openCh) depth++
+    else if (masked[i] === closeCh) {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return -1
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Block extraction
+// ─────────────────────────────────────────────────────────────────────────
+const ACTIVE_RE = /\b(?:it|test|fit|ftest)\s*\(/g
+
+/**
+ * The test callback's BODY inside the call `(`…`)` at [callOpen, callClose] of the
+ * masked source → { start, end } (exclusive end), or null when no function literal.
+ *
+ * FALSE-POSITIVE CLASS (factory batch 2026-09-26, measured): this used to take the
+ * FIRST `{` among the call's arguments as the body. For an expression-bodied arrow —
+ * `it('x', async () => expect(await f({ a: 1 })).toBe(2))` — that `{` is an object
+ * literal INSIDE the assertion, so the "body" was `a: 1` and a real assertion read as
+ * NO_ASSERTION. The body is now the callback's own: after `=>` either its `{…}` block
+ * or, for an expression body, the expression itself; for a `function (…) {…}` the
+ * block after its parameter list.
+ */
+function functionBody(masked, callOpen, callClose) {
+  const args = masked.slice(callOpen + 1, callClose)
+  // top-level `=>` of the callback (depth 0 relative to the call's own parens)
+  let depth = 0
+  for (let i = 0; i < args.length - 1; i++) {
+    const ch = args[i]
+    if (ch === '(' || ch === '[' || ch === '{') depth++
+    else if (ch === ')' || ch === ']' || ch === '}') depth--
+    else if (depth === 0 && ch === '=' && args[i + 1] === '>') {
+      let p = i - 1
+      while (p >= 0 && /\s/.test(args[p])) p--
+      let params = ''
+      if (args[p] === ')') { const o = matchBracketBack(args, p, '(', ')'); if (o !== -1) params = args.slice(o + 1, p) }
+      else { let q = p; while (q >= 0 && /[\w$]/.test(args[q])) q--; params = args.slice(q + 1, p + 1) }
+      let j = i + 2
+      while (j < args.length && /\s/.test(args[j])) j++
+      if (args[j] === '{') {
+        const open = callOpen + 1 + j
+        const close = matchBracket(masked, open, '{', '}')
+        return close === -1 ? null : { start: open + 1, end: close, params }
+      }
+      // expression body: up to the next top-level `,` (a timeout argument) or the call's end
+      let d = 0
+      let k = j
+      for (; k < args.length; k++) {
+        const c = args[k]
+        if (c === '(' || c === '[' || c === '{') d++
+        else if (c === ')' || c === ']' || c === '}') d--
+        else if (d === 0 && c === ',') break
+      }
+      return { start: callOpen + 1 + j, end: callOpen + 1 + k, params }
+    }
+  }
+  const fn = /\bfunction\b[^(]*\(/.exec(args)
+  if (fn) {
+    const pOpen = callOpen + 1 + fn.index + fn[0].length - 1
+    const pClose = matchBracket(masked, pOpen, '(', ')')
+    if (pClose === -1) return null
+    const open = masked.indexOf('{', pClose)
+    if (open === -1 || open > callClose) return null
+    const close = matchBracket(masked, open, '{', '}')
+    return close === -1 ? null : { start: open + 1, end: close, params: masked.slice(pOpen + 1, pClose) }
+  }
+  return null
+}
+const SKIP_RE = /\b(?:it\.skip|test\.skip|xit|xtest|describe\.skip|xdescribe)\s*\(/g
+
+/**
+ * @returns {Array<{kind:'active', line:number, bodyText:string, bodyMasked:string}
+ *                | {kind:'skip', line:number, matchStart:number}>}
+ */
+export function findTestBlocks(source) {
+  const masked = maskStringsAndComments(source)
+  const blocks = []
+
+  SKIP_RE.lastIndex = 0
+  let m
+  while ((m = SKIP_RE.exec(masked)) !== null) {
+    blocks.push({ kind: 'skip', line: lineAt(source, m.index), matchStart: m.index })
+  }
+
+  ACTIVE_RE.lastIndex = 0
+  while ((m = ACTIVE_RE.exec(masked)) !== null) {
+    const callOpen = m.index + m[0].length - 1 // index of the call's own '('
+    const callClose = matchBracket(masked, callOpen, '(', ')')
+    if (callClose === -1) continue
+    const body = functionBody(masked, callOpen, callClose)
+    if (!body) continue // no function-literal argument (e.g. it.todo, a bare reference) — nothing to assert
+    blocks.push({
+      kind: 'active',
+      line: lineAt(source, m.index),
+      bodyText: source.slice(body.start, body.end),
+      bodyMasked: masked.slice(body.start, body.end),
+      bodyStart: body.start,
+      params: body.params || '',
+    })
+  }
+
+  return blocks.sort((a, b) => a.line - b.line)
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Criterion 1 + 2 — assertion presence / tautology
+// ─────────────────────────────────────────────────────────────────────────
+const EXPECT_CALL_RE = /\bexpect\s*\(/g
+// NOT global. A /g regex keeps `lastIndex` between `.test()` calls, so after one block
+// matched, the NEXT block was searched from the previous block's match offset — a
+// shorter block then "had no assert" (factory batch 2026-09-26: 130 of the 243 findings
+// on the release line were this one defect, in node:test `assert.*` specs).
+const ASSERT_CALL_RE = /\bassert(?:\.\w+)?\s*\(/
+
+function findExpectCalls(bodyText, bodyMasked) {
+  const calls = []
+  EXPECT_CALL_RE.lastIndex = 0
+  let m
+  while ((m = EXPECT_CALL_RE.exec(bodyMasked)) !== null) {
+    const argOpen = m.index + m[0].length - 1
+    const argClose = matchBracket(bodyMasked, argOpen, '(', ')')
+    if (argClose === -1) continue
+    const arg = bodyText.slice(argOpen + 1, argClose).trim()
+    // matcher: `.toBeX(...)` immediately following the expect(...) call.
+    const rest = bodyMasked.slice(argClose + 1)
+    const matcherM = /^\s*\.\s*(\w+)\s*\(/.exec(rest)
+    let matcherName = null
+    let matcherArg = null
+    if (matcherM) {
+      const matcherOpen = argClose + 1 + matcherM.index + matcherM[0].length - 1
+      const matcherClose = matchBracket(bodyMasked, matcherOpen, '(', ')')
+      matcherName = matcherM[1]
+      if (matcherClose !== -1) matcherArg = bodyText.slice(matcherOpen + 1, matcherClose).trim()
+    }
+    // F4 idioms (2026-09-26): the FULL matcher chain (`not.toBeUndefined`,
+    // `resolves.toBe`) and the MASKED argument texts, so a name that occurs only inside a
+    // quoted string (`toHaveProperty('status')`) is never read as the identifier itself.
+    const chainM = /^(?:\s*\.\s*\w+)+\s*\(/.exec(rest)
+    let chain = null
+    let matcherArgMasked = null
+    if (chainM) {
+      chain = chainM[0].replace(/[\s(]/g, '').replace(/^\./, '')
+      const cOpen = argClose + 1 + chainM[0].length - 1
+      const cClose = matchBracket(bodyMasked, cOpen, '(', ')')
+      if (cClose !== -1) matcherArgMasked = bodyMasked.slice(cOpen + 1, cClose).trim()
+    }
+    const argMasked = bodyMasked.slice(argOpen + 1, argClose).trim()
+    calls.push({ arg, matcherName, matcherArg, chain, argMasked, matcherArgMasked, index: m.index, argOpen, argClose })
+  }
+  return calls
+}
+
+function isBooleanTautology(call) {
+  if (call.arg === 'true' && (call.matcherName === 'toBe' && call.matcherArg === 'true')) return true
+  if (call.arg === 'true' && call.matcherName === 'toBeTruthy') return true
+  if (call.arg === 'false' && (call.matcherName === 'toBe' && call.matcherArg === 'false')) return true
+  if (call.arg === 'false' && call.matcherName === 'toBeFalsy') return true
+  return false
+}
+
+/** Is `ident`'s nearest same-block binding before `beforeIdx` a "just
+ *  constructed" literal (object/array/string/number/template literal or a
+ *  bare `new X(...)`), as opposed to a call to the unit under test? */
+function isJustConstructed(bodyText, bodyMasked, ident, beforeIdx) {
+  const bindRe = new RegExp(`\\b(?:const|let|var)\\s+${ident}\\s*=\\s*`, 'g')
+  let lastBind = null
+  let m
+  while ((m = bindRe.exec(bodyMasked)) !== null) {
+    if (m.index < beforeIdx) lastBind = m
+    else break
+  }
+  if (!lastBind) return false
+  const rhsStart = lastBind.index + lastBind[0].length
+  const rhsMasked = bodyMasked.slice(rhsStart).trimStart()
+  const rhsText = bodyText.slice(rhsStart).trimStart()
+  if (/^[{[]/.test(rhsMasked)) return true // object / array literal
+  if (/^["'`]/.test(rhsText) && !/^["'`]\s*[)+]/.test(rhsMasked)) return true // quote char survives only in bodyText (masked blanks it) — detect via original
+  if (/^-?\d/.test(rhsMasked)) return true // number literal
+  if (/^new\s+[A-Za-z_$][\w$.]*\s*\(/.test(rhsMasked)) return true // bare constructor
+  return false
+}
+
+/**
+ * `assertingHelpers` (optional): names of functions, defined in this spec file or
+ * imported from a RELATIVE module, whose own body asserts (expect/assert, or a call
+ * to another asserting helper). A test whose only assertion is `await
+ * expectRefusedAndNothingPersisted(...)` asserts; a test that calls a helper that
+ * asserts nothing is still NO_ASSERTION. (Factory batch 2026-09-26: 42 of the
+ * release line's NO_ASSERTION findings were assertions the detector could not see
+ * because they lived in a named helper — `qFail`, `expectRejectedBeforeSideEffects`,
+ * `assertNoNegativeBalances`, … — not missing assertions.)
+ */
+export function isNoAssertion(block, assertingHelpers = new Set(), ruleTesters = new Set()) {
+  if (findExpectCalls(block.bodyText, block.bodyMasked).length > 0) return false
+  if (ASSERT_CALL_RE.test(block.bodyMasked)) return false
+  for (const name of calledNames(block.bodyMasked)) if (assertingHelpers.has(name)) return false
+  // F4 idioms 2026-09-26 — [FAIL_CAPABLE_THROW] a hand-rolled `if (bad) throw …` at test
+  // level, or inside a SYNCHRONOUS array callback / an IIFE (the throw propagates), fails
+  // the test: it is an assertion. A throw inside `.then(…)`/`setTimeout(…)` does not.
+  if (hasPropagatingThrow(block.bodyMasked)) return false
+  // [RULE_TESTER] `<receiver>.run(name, rule, {valid, invalid})` asserts every case.
+  if (callsRuleTesterRun(block.bodyMasked, ruleTesters)) return false
+  return true
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Structural helpers for the idiom rules (F4 idioms, 2026-09-26).
+// ─────────────────────────────────────────────────────────────────────────
+function matchBracketBack(masked, closeIdx, openCh, closeCh) {
+  let depth = 0
+  for (let i = closeIdx; i >= 0; i--) {
+    if (masked[i] === closeCh) depth++
+    else if (masked[i] === openCh) {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return -1
+}
+
+/** Index of the innermost UNMATCHED `(`/`[`/`{` before `idx`, or -1. */
+function enclosingOpen(masked, idx) {
+  let depth = 0
+  for (let i = idx - 1; i >= 0; i--) {
+    const c = masked[i]
+    if (c === ')' || c === ']' || c === '}') depth++
+    else if (c === '(' || c === '[' || c === '{') {
+      if (depth === 0) return i
+      depth--
+    }
+  }
+  return -1
+}
+
+const CONTROL_KW = new Set(['if', 'for', 'while', 'switch', 'catch', 'with', 'return', 'typeof', 'await', 'new', 'else', 'do', 'try', 'finally'])
+
+/**
+ * Every BLOCK-bodied function literal in `masked`: { start, open, close, callee, iife }.
+ * `callee` = name of the call the literal is a direct argument of (`forEach`, `then`,
+ * `setTimeout`…), `iife` = the literal is invoked where it is written.
+ */
+export function functionLiterals(masked) {
+  const out = []
+  for (let i = 0; i < masked.length; i++) {
+    if (masked[i] !== '{') continue
+    let k = i - 1
+    while (k >= 0 && /\s/.test(masked[k])) k--
+    let start = -1
+    if (k >= 1 && masked[k] === '>' && masked[k - 1] === '=') {
+      let p = k - 2
+      while (p >= 0 && /\s/.test(masked[p])) p--
+      if (masked[p] === ')') { start = matchBracketBack(masked, p, '(', ')'); if (start === -1) continue }
+      else { let q = p; while (q >= 0 && /[\w$]/.test(masked[q])) q--; start = q + 1 }
+    } else if (masked[k] === ')') {
+      const o = matchBracketBack(masked, k, '(', ')')
+      if (o === -1) continue
+      const before = masked.slice(0, o)
+      const w = /([A-Za-z_$][\w$]*)\s*(?:<[^<>()]*>)?\s*$/.exec(before)
+      if (!w || CONTROL_KW.has(w[1])) continue
+      const fnKw = /(?:\basync\s+)?\bfunction\s*\*?\s*(?:[A-Za-z_$][\w$]*)?\s*$/.exec(before)
+      start = fnKw ? fnKw.index : w.index
+    } else continue
+    const am = /\basync\s*$/.exec(masked.slice(0, start))
+    if (am) start = am.index
+    const close = matchBracket(masked, i, '{', '}')
+    if (close === -1) continue
+    let callee = null
+    let iife = false
+    let b = start - 1
+    while (b >= 0 && /\s/.test(masked[b])) b--
+    const encl = enclosingOpen(masked, start)
+    if (encl !== -1 && masked[encl] === '(' && (masked[b] === '(' || masked[b] === ',')) {
+      const nm = /([A-Za-z_$][\w$]*)\s*$/.exec(masked.slice(0, encl))
+      if (masked[b] === '(' && b === encl) {
+        const pc = matchBracket(masked, encl, '(', ')')
+        let a = close + 1
+        while (a < masked.length && /\s/.test(masked[a])) a++
+        if (pc !== -1 && pc === a && /^\)\s*\(/.test(masked.slice(pc))) iife = true
+      }
+      if (nm && !CONTROL_KW.has(nm[1])) callee = nm[1]
+    }
+    out.push({ start, open: i, close, callee, iife })
+  }
+  return out
+}
+
+const SYNC_CALLBACK = new Set(['forEach', 'map', 'flatMap', 'filter', 'some', 'every', 'find', 'findIndex', 'findLast', 'findLastIndex', 'reduce', 'reduceRight', 'sort', 'toSorted'])
+const DEFERRED_CALLBACK = new Set(['then', 'catch', 'finally', 'setTimeout', 'setImmediate', 'setInterval', 'nextTick', 'queueMicrotask'])
+
+/** [{tryOpen, tryClose, catchOpen, catchClose, rethrows}] for every try/catch in `masked`. */
+function tryCatches(masked) {
+  const out = []
+  const re = /\btry\s*\{/g
+  let m
+  while ((m = re.exec(masked)) !== null) {
+    const tryOpen = m.index + m[0].length - 1
+    const tryClose = matchBracket(masked, tryOpen, '{', '}')
+    if (tryClose === -1) continue
+    const cm = /^\s*catch\s*(?:\([^)]*\))?\s*\{/.exec(masked.slice(tryClose + 1))
+    if (!cm) continue
+    const catchOpen = tryClose + 1 + cm.index + cm[0].length - 1
+    const catchClose = matchBracket(masked, catchOpen, '{', '}')
+    if (catchClose === -1) continue
+    out.push({ tryOpen, tryClose, catchOpen, catchClose, rethrows: ASSERT_IN_CATCH_RE.test(masked.slice(catchOpen + 1, catchClose)) })
+  }
+  return out
+}
+
+export function hasPropagatingThrow(masked) {
+  const fns = functionLiterals(masked)
+  const tcs = tryCatches(masked)
+  const re = /\bthrow\b/g
+  let m
+  while ((m = re.exec(masked)) !== null) {
+    const at = m.index
+    const enclosing = fns.filter((f) => f.open < at && at < f.close)
+    if (!enclosing.every((f) => f.iife || (f.callee && SYNC_CALLBACK.has(f.callee)))) continue
+    if (tcs.some((t) => t.tryOpen < at && at < t.tryClose && !t.rethrows)) continue
+    return true
+  }
+  return false
+}
+
+/** Local names bound to a RuleTester: `= new RuleTester(`, anything imported/required
+ *  from a `*rule-tester*` module (any case, any alias), or a name containing "ruletester". */
+export function ruleTesterNames(source) {
+  const masked = maskStringsAndComments(source)
+  const names = new Set()
+  for (const m of masked.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*new\s+(?:[\w$]+\.)?RuleTester\b/g)) names.add(m[1])
+  for (const m of source.matchAll(/import\s+(?:type\s+)?([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g)) {
+    if (!/rule[-_]?tester/i.test(m[2])) continue
+    const clause = m[1]
+    const def = /^([A-Za-z_$][\w$]*)/.exec(clause)
+    if (def) names.add(def[1])
+    const named = /\{([^}]*)\}/.exec(clause)
+    if (named) for (const part of named[1].split(',')) { const [o, a] = part.trim().split(/\s+as\s+/); if (o) names.add((a || o).trim()) }
+  }
+  for (const m of source.matchAll(/\b(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    if (!/rule[-_]?tester/i.test(m[2])) continue
+    if (m[1].startsWith('{')) for (const part of m[1].slice(1, -1).split(',')) { const [o, a] = part.trim().split(/\s*:\s*/); if (o) names.add((a || o).trim()) }
+    else names.add(m[1])
+  }
+  names.delete('')
+  return names
+}
+
+function callsRuleTesterRun(masked, ruleTesters) {
+  if (/(?<![.\w$])[\w$]*rule_?tester[\w$]*\s*\.\s*run\s*\(/i.test(masked)) return true
+  for (const n of ruleTesters) {
+    if (new RegExp(`(?<![.\\w$])${n.replace(/\$/g, '\\$')}\\s*\\.\\s*run\\s*\\(`).test(masked)) return true
+  }
+  return false
+}
+
+/** Strip TS-only syntax from a MASKED argument: `x as { status: T }`, `x as Foo<Bar>`,
+ *  `x satisfies T`, `x!` — a name that occurs only in a type is not a value read. */
+function stripTypeSyntax(maskedArg) {
+  let s = maskedArg
+  for (let guard = 0; guard < 20; guard++) {
+    const m = /\b(?:as|satisfies)\s+/.exec(s)
+    if (!m) break
+    let j = m.index + m[0].length
+    let d = 0
+    for (; j < s.length; j++) {
+      const c = s[j]
+      if (c === '{' || c === '<' || c === '(' || c === '[') d++
+      else if (c === '}' || c === '>' || c === ')' || c === ']') { if (d === 0) break; d-- }
+      else if (d === 0 && (c === ',' || c === ';' || c === '&' || c === '|' || c === '?' || c === '=' || c === '\n')) break
+    }
+    s = s.slice(0, m.index) + ' '.repeat(j - m.index) + s.slice(j)
+  }
+  return s
+}
+
+const CALL_NAME_RE = /(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(/g
+const NOT_A_CALL = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof', 'await', 'new', 'expect', 'assert'])
+function calledNames(masked) {
+  const out = new Set()
+  CALL_NAME_RE.lastIndex = 0
+  let m
+  while ((m = CALL_NAME_RE.exec(masked)) !== null) if (!NOT_A_CALL.has(m[1])) out.add(m[1])
+  return out
+}
+
+/** name → masked body of every function this source DEFINES:
+ *  `function NAME(…) {…}` and `const|let NAME = [async] (…|x) => {…}|expr` / `= [async] function (…) {…}`. */
+export function functionDefinitions(source) {
+  const masked = maskStringsAndComments(source)
+  const defs = new Map()
+  const fnRe = /\bfunction\s*\*?\s*([A-Za-z_$][\w$]*)\s*(?:<[^>(]*>)?\s*\(/g
+  let m
+  while ((m = fnRe.exec(masked)) !== null) {
+    const pOpen = m.index + m[0].length - 1
+    const pClose = matchBracket(masked, pOpen, '(', ')')
+    if (pClose === -1) continue
+    const open = masked.indexOf('{', pClose)
+    if (open === -1) continue
+    const close = matchBracket(masked, open, '{', '}')
+    if (close !== -1) defs.set(m[1], masked.slice(open + 1, close))
+  }
+  const constRe = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?/g
+  while ((m = constRe.exec(masked)) !== null) {
+    const at = m.index + m[0].length
+    const rest = masked.slice(at)
+    let open = -1
+    if (/^function\b/.test(rest) || /^\(/.test(rest) || /^[A-Za-z_$][\w$]*\s*=>/.test(rest)) {
+      const arrow = masked.indexOf('=>', at)
+      const fnKw = /^function\b/.test(rest)
+      if (fnKw) {
+        const pOpen = masked.indexOf('(', at)
+        const pClose = pOpen === -1 ? -1 : matchBracket(masked, pOpen, '(', ')')
+        open = pClose === -1 ? -1 : masked.indexOf('{', pClose)
+      } else if (arrow !== -1) {
+        let j = arrow + 2
+        while (j < masked.length && /\s/.test(masked[j])) j++
+        if (masked[j] === '{') open = j
+        else {
+          // expression body: to the end of the statement (newline at depth 0 or `;`)
+          let d = 0
+          let k = j
+          for (; k < masked.length; k++) {
+            const c = masked[k]
+            if (c === '(' || c === '[' || c === '{') d++
+            else if (c === ')' || c === ']' || c === '}') { if (d === 0) break; d-- }
+            else if (d === 0 && (c === ';' || c === '\n')) break
+          }
+          defs.set(m[1], masked.slice(j, k))
+          continue
+        }
+      }
+    }
+    if (open === -1) continue
+    const close = matchBracket(masked, open, '{', '}')
+    if (close !== -1) defs.set(m[1], masked.slice(open + 1, close))
+  }
+  return defs
+}
+
+/** Relative imports of a spec: local name → absolute module path (resolved on disk). */
+function relativeImports(relPath, source) {
+  const out = new Map()
+  const dir = path.dirname(path.join(ROOT, relPath))
+  const re = /import\s*(?:type\s+)?\{([^}]*)\}\s*from\s*['"](\.{1,2}\/[^'"]+)['"]/g
+  let m
+  while ((m = re.exec(source)) !== null) {
+    const base = path.resolve(dir, m[2])
+    const file = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '/index.ts', '/index.js'].map((e) => base + e).find((f) => existsSync(f) && !f.endsWith('/'))
+    if (!file) continue
+    for (const part of m[1].split(',')) {
+      const [orig, alias] = part.trim().split(/\s+as\s+/)
+      if (orig) out.set((alias || orig).trim(), { file, name: orig.trim() })
+    }
+  }
+  return out
+}
+
+/** The set of helper names, callable from this spec, whose body asserts (fixpoint, so a
+ *  helper that only calls an asserting helper asserts too). */
+export function assertingHelpersOf(relPath, source, readFile = (f) => readFileSync(f, 'utf8')) {
+  const bodies = new Map(functionDefinitions(source))
+  for (const [local, { file, name }] of relativeImports(relPath, source)) {
+    try {
+      const b = functionDefinitions(readFile(file)).get(name)
+      if (b !== undefined && !bodies.has(local)) bodies.set(local, b)
+    } catch { /* unreadable import: its helpers simply do not count */ }
+  }
+  const asserting = new Set()
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const [name, body] of bodies) {
+      if (asserting.has(name)) continue
+      EXPECT_CALL_RE.lastIndex = 0
+      const direct = EXPECT_CALL_RE.test(body) || ASSERT_CALL_RE.test(body)
+      EXPECT_CALL_RE.lastIndex = 0
+      if (direct || [...calledNames(body)].some((n) => n !== name && asserting.has(n))) { asserting.add(name); grew = true }
+    }
+  }
+  return asserting
+}
+
+export function isAllTautological(block) {
+  const calls = findExpectCalls(block.bodyText, block.bodyMasked)
+  if (calls.length === 0) return false // that's criterion 1, not 2
+  return calls.every((call) => {
+    if (isBooleanTautology(call)) return true
+    if (call.matcherName === 'toBeDefined' && /^[A-Za-z_$][\w$]*$/.test(call.arg)) {
+      // Need the call's position to bound "nearest binding before this call" —
+      // recompute it via indexOf since findExpectCalls doesn't carry position.
+      const callIdx = block.bodyMasked.indexOf(`${call.arg}`)
+      return isJustConstructed(block.bodyText, block.bodyMasked, call.arg, callIdx >= 0 ? callIdx : block.bodyMasked.length)
+    }
+    return false
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Criterion 3 — unlinked skip
+// ─────────────────────────────────────────────────────────────────────────
+const SKIP_LEDGER_RE = /SKIP-LEDGER:\s*\S+/
+
+export function skipLacksLedgerEntry(source, skipLine) {
+  const lines = source.split('\n')
+  const from = Math.max(0, skipLine - 1 - 3)
+  const window = lines.slice(from, skipLine).join('\n')
+  return !SKIP_LEDGER_RE.test(window)
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Criterion 4 — swallowed catch around the unit under test
+// ─────────────────────────────────────────────────────────────────────────
+const TRY_RE = /\btry\s*\{/g
+const ASSERT_IN_CATCH_RE = /\b(expect|assert|fail)\s*\(|\bthrow\b/
+
+/** Is any of `names` referenced inside an expect(…)/assert…(…) call (its arguments, or
+ *  the matcher's) in `seg`? */
+const EXISTENCE_ONLY = new Set(['toBeDefined', 'not.toBeUndefined', 'not.toBeNull'])
+function assertedAfter(seg, names, { excludeExistence = false } = {}) {
+  // V1 (Opus cert f66867f32, 2026-09-26): the binding must appear as a NAME, not as a
+  // property of something else — `res.status` / `row.error` must not count as asserting
+  // a captured `status` / `error`. Same lookbehind the capture side already uses.
+  // F4 idioms (cert A10 baecbbf7f gap): matched on the MASKED, type-stripped text — a
+  // name that occurs only in a quoted matcher arg (`toHaveProperty('status')`) or only in
+  // a TS type (`x as { status: T }`) is not an assertion on that binding.
+  const re = new RegExp(`(?<![.\\w$])(?:${names.map((n) => n.replace(/[$]/g, '\\$')).join('|')})\\b`)
+  for (const c of findExpectCalls(seg.text, seg.masked)) {
+    if (excludeExistence && EXISTENCE_ONLY.has(c.chain)) continue
+    if (re.test(stripTypeSyntax(c.argMasked)) || (c.matcherArgMasked && re.test(stripTypeSyntax(c.matcherArgMasked)))) return true
+  }
+  const aRe = /\bassert(?:\.\w+)?\s*\(/g
+  let m
+  while ((m = aRe.exec(seg.masked)) !== null) {
+    const open = m.index + m[0].length - 1
+    const close = matchBracket(seg.masked, open, '(', ')')
+    if (close !== -1 && re.test(stripTypeSyntax(seg.masked.slice(open + 1, close)))) return true
+  }
+  return false
+}
+
+export function hasSwallowedCatch(block) {
+  const masked = block.bodyMasked
+  TRY_RE.lastIndex = 0
+  let m
+  while ((m = TRY_RE.exec(masked)) !== null) {
+    const tryBraceOpen = m.index + m[0].length - 1
+    const tryBraceClose = matchBracket(masked, tryBraceOpen, '{', '}')
+    if (tryBraceClose === -1) continue
+    const tryBody = masked.slice(tryBraceOpen + 1, tryBraceClose)
+    if (!/\(/.test(tryBody)) continue // try body calls nothing — not "around the unit under test"
+
+    const afterTry = masked.slice(tryBraceClose + 1)
+    const catchM = /^\s*catch\s*(?:\([^)]*\))?\s*\{/.exec(afterTry)
+    if (!catchM) continue
+    const catchBraceOpen = tryBraceClose + 1 + catchM.index + catchM[0].length - 1
+    const catchBraceClose = matchBracket(masked, catchBraceOpen, '{', '}')
+    if (catchBraceClose === -1) continue
+    const catchBody = masked.slice(catchBraceOpen + 1, catchBraceClose)
+    if (ASSERT_IN_CATCH_RE.test(catchBody)) continue
+    // CAPTURE-THEN-ASSERT is not a swallow: `catch (e) { caught = e }` followed by
+    // `expect(caught).toBeInstanceOf(X)` asserts on exactly what the catch took. It
+    // counts ONLY when a binding the catch assigns is referenced inside an assertion
+    // AFTER the try/catch; a captured error that nothing asserts is still RED.
+    // (Factory batch 2026-09-26: 27 of the 41 SWALLOWED_CATCH findings were this.)
+    const assigned = [
+      ...[...catchBody.matchAll(/(?<![.\w$])([A-Za-z_$][\w$]*)\s*=(?![=>])/g)].map((x) => x[1]),
+      // …or collected into an outer list/set/map: `unparsed.push(err)`
+      ...[...catchBody.matchAll(/(?<![.\w$])([A-Za-z_$][\w$]*)\s*\.\s*(?:push|add|set)\s*\(/g)].map((x) => x[1]),
+    ]
+    const after = { text: block.bodyText.slice(catchBraceClose + 1), masked: masked.slice(catchBraceClose + 1) }
+    if (assigned.length && assertedAfter(after, assigned)) continue
+    // [SENTINEL] F4 idioms 2026-09-26: `try { unit(); return true } catch { return false }`
+    // inside an IIFE (or a named arrow) whose RESULT is asserted — `assert.ok((() => …)())`,
+    // `const ok = (() => …)(); expect(ok).toBe(true)`, `expect(probe()).toBeTruthy()` — is
+    // fail-capable: the catch turns the error into a value the assertion reads. It stays RED
+    // when the sentinel is discarded, or only asserted to exist (`toBeDefined`).
+    if (sentinelAsserted(block, m.index, catchBody)) continue
+    return true
+  }
+  return false
+}
+
+function sentinelAsserted(block, tryIdx, catchBody) {
+  if (!/^\s*return\b[^;{}]*;?\s*$/.test(catchBody)) return false
+  const masked = block.bodyMasked
+  const fns = functionLiterals(masked).filter((f) => f.open < tryIdx && tryIdx < f.close)
+  if (!fns.length) return false
+  const fn = fns.reduce((a, b) => (b.open > a.open ? b : a))
+  let exprStart = fn.start
+  let exprEnd = fn.close + 1
+  if (fn.iife) {
+    exprStart = enclosingOpen(masked, fn.start)
+    const pc = matchBracket(masked, exprStart, '(', ')')
+    const ao = masked.indexOf('(', pc + 1)
+    exprEnd = matchBracket(masked, ao, '(', ')') + 1
+  }
+  // (a) the IIFE is itself an assertion's argument
+  if (fn.iife) {
+    for (const c of findExpectCalls(block.bodyText, masked)) {
+      if (c.argOpen < exprStart && exprEnd <= c.argClose + 1 && !EXISTENCE_ONLY.has(c.chain)) return true
+    }
+    const aRe = /\bassert(?:\.\w+)?\s*\(/g
+    let m
+    while ((m = aRe.exec(masked)) !== null) {
+      const open = m.index + m[0].length - 1
+      const close = matchBracket(masked, open, '(', ')')
+      if (open < exprStart && exprEnd <= close + 1) return true
+    }
+  }
+  // (b) bound to a name that a later assertion reads (IIFE result, or the named function called)
+  const bind = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*$/.exec(masked.slice(0, exprStart))
+  if (!bind) return false
+  const after = { text: block.bodyText.slice(exprEnd), masked: masked.slice(exprEnd) }
+  return assertedAfter(after, [bind[1]], { excludeExistence: true })
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Idiom rules (F4 idioms, 2026-09-26). Evidence: aeos-live-status/reports/
+// aeos-a10-skill.md §10 — on 7 of 16 sealed-holdout cases F4 never fired, so no
+// repair skill (whose trigger IS F4) could do better. One rule per missed FAMILY,
+// written from the family, not from any holdout snippet. Each is proven RED, GREEN
+// (a control of the same shape that is fail-capable) and by a negative control
+// (rule neutered in a scratch copy ⇒ its RED fixture passes) — see the report
+// aeos-live-status/reports/aeos-f4-idioms.md.
+// ─────────────────────────────────────────────────────────────────────────
+
+/** Every assertion call in a block: expect(...) calls (with chain) and assert*(...) calls. */
+function assertionCalls(block) {
+  const out = findExpectCalls(block.bodyText, block.bodyMasked).map((c) => ({ kind: 'expect', ...c }))
+  const re = /\bassert(?:\.(\w+))?\s*\(/g
+  let m
+  while ((m = re.exec(block.bodyMasked)) !== null) {
+    const open = m.index + m[0].length - 1
+    const close = matchBracket(block.bodyMasked, open, '(', ')')
+    if (close === -1) continue
+    out.push({ kind: 'assert', method: m[1] || '', index: m.index, argOpen: open, argClose: close, argMasked: block.bodyMasked.slice(open + 1, close).trim(), arg: block.bodyText.slice(open + 1, close).trim() })
+  }
+  return out
+}
+
+function insideFunctionLiteral(fns, idx) {
+  return fns.some((f) => f.open < idx && idx < f.close)
+}
+
+const DONE_NAMES = new Set(['done', 'cb', 'callback', 'finish', 'next', 'end'])
+function doneParam(block) {
+  const ps = block.params.split(',').map((x) => x.trim().replace(/[:=][\s\S]*$/, '').trim()).filter(Boolean)
+  const last = ps[ps.length - 1]
+  return last && DONE_NAMES.has(last) ? last : null
+}
+
+/** Asserting deferred callbacks in a masked body: [{ callee, callOpen, callClose, nameIdx }]. */
+function assertingDeferredCalls(masked) {
+  const out = []
+  const re = /(?:\.\s*(then|catch|finally)|(?<![.\w$])(setTimeout|setImmediate|setInterval|queueMicrotask|(?:process\s*\.\s*)?nextTick))\s*\(/g
+  let m
+  while ((m = re.exec(masked)) !== null) {
+    const callOpen = m.index + m[0].length - 1
+    const callClose = matchBracket(masked, callOpen, '(', ')')
+    if (callClose === -1) continue
+    const inner = masked.slice(callOpen + 1, callClose)
+    EXPECT_CALL_RE.lastIndex = 0
+    const asserts = EXPECT_CALL_RE.test(inner) || ASSERT_CALL_RE.test(inner)
+    EXPECT_CALL_RE.lastIndex = 0
+    if (asserts) out.push({ callee: m[1] || m[2], callOpen, callClose, nameIdx: m.index })
+  }
+  return out
+}
+
+/** [PROMISE_NOT_AWAITED] an assertion lives in a `.then/.catch/.finally` (or timer)
+ *  callback whose chain the test neither awaits, returns, nor hands to anything — the
+ *  test ends before the callback runs, so the assertion can never fail it. */
+export function hasFloatingAsyncAssertion(block) {
+  if (doneParam(block)) return false // done-style: DONE_EARLY's territory
+  const masked = block.bodyMasked
+  const fns = functionLiterals(masked)
+  for (const d of assertingDeferredCalls(masked)) {
+    if (insideFunctionLiteral(fns, d.nameIdx)) continue // nested inside another callback: not judged here
+    // walk back over the chain `a.b(x).c[0]\n  .then` to the token before its root
+    let i = d.nameIdx - 1
+    let rootStart = d.nameIdx
+    for (;;) {
+      while (i >= 0 && /\s/.test(masked[i])) i--
+      if (i < 0) break
+      const c = masked[i]
+      if (c === ')' || c === ']') { const o = matchBracketBack(masked, i, c === ')' ? '(' : '[', c); if (o === -1) break; i = o - 1; continue }
+      if (c === '.') { i--; if (masked[i] === '?') i--; continue }
+      if (/[\w$]/.test(c)) {
+        let q = i
+        while (q >= 0 && /[\w$]/.test(masked[q])) q--
+        let r = q
+        while (r >= 0 && /\s/.test(masked[r])) r--
+        if (r >= 0 && masked[r] === '.') { i = r; continue } // `x\n  .y` — still the chain
+        rootStart = q + 1
+        i = r
+        // `new X(…).then`: step over `new`
+        const nw = /\bnew\s*$/.exec(masked.slice(0, i + 1))
+        if (nw) { i = nw.index - 1; while (i >= 0 && /\s/.test(masked[i])) i-- }
+        break
+      }
+      break
+    }
+    const prev = i < 0 ? '' : masked[i]
+    // a string/comment (blanked in the mask) ending the previous line is an ASI boundary
+    const gap = block.bodyText.slice(i + 1, rootStart)
+    if (/\S/.test(gap) && /\n/.test(gap.slice(gap.search(/\S/)))) return true
+    if (/[\w$]/.test(prev)) {
+      const w = /([\w$]+)$/.exec(masked.slice(0, i + 1))
+      if (w && ['await', 'return', 'yield'].includes(w[1])) continue // awaited / returned
+      return true // ASI statement boundary after a word
+    }
+    if (prev === '' || prev === ';' || prev === '{' || prev === '}' || prev === ')') return true
+    // `=`, `(`, `,`, `[`, `=>`, `:` … — the chain is assigned, passed, or returned: not judged
+  }
+  return false
+}
+
+/** [DONE_EARLY] a done-callback test calls `done()` synchronously at test level while an
+ *  assertion sits in a promise/timer callback — jest ends the test at `done()`, so that
+ *  assertion can never fail it. (A done that is NEVER called is not vacuous: jest times
+ *  the test out RED.) */
+export function hasDoneBeforeAsyncAssertion(block) {
+  const done = doneParam(block)
+  if (!done) return false
+  const masked = block.bodyMasked
+  const fns = functionLiterals(masked)
+  const re = new RegExp(`(?<![.\\w$])${done.replace(/\$/g, '\\$')}\\s*\\(`, 'g')
+  let early = false
+  let m
+  while ((m = re.exec(masked)) !== null) if (!insideFunctionLiteral(fns, m.index) && !/=>\s*$/.test(masked.slice(0, m.index))) early = true
+  if (!early) return false
+  return assertingDeferredCalls(masked).length > 0
+}
+
+/** [EARLY_RETURN] a bare `return` at test level (not inside a nested callback) that comes
+ *  BEFORE an assertion: whenever that path is taken the test passes having asserted
+ *  nothing — a skip in disguise. Linkable like a skip: `// SKIP-LEDGER: <ref>` on the
+ *  line or within 3 lines above exempts it. Returns the body offset of the return, or -1. */
+export function earlyReturnIndex(block, assertingHelpers = new Set()) {
+  const masked = block.bodyMasked
+  const fns = functionLiterals(masked)
+  const re = /\breturn\b/g
+  let m
+  while ((m = re.exec(masked)) !== null) {
+    if (insideFunctionLiteral(fns, m.index)) continue
+    const tail = masked.slice(m.index + 6).split('\n')[0].trim()
+    if (!(tail === '' || tail === ';' || tail.startsWith('}') || /^(?:undefined|void\s+0)\s*;?\s*(?:}|$)/.test(tail))) continue
+    // Only a return reached BEFORE anything was asserted is a vacuous path. A type-narrowing
+    // `expect(r.ok).toBe(true); if (!r.ok) return` or an `if (x) { expect(…); return }`
+    // branch has already asserted — measured on the release range, 2026-09-26. A
+    // tautological `expect(true).toBe(true); return` has not.
+    const before = { text: block.bodyText.slice(0, m.index), masked: masked.slice(0, m.index) }
+    const deferred = assertingDeferredCalls(before.masked)
+    const assertedBefore =
+      findExpectCalls(before.text, before.masked).some((c) => !isBooleanTautology(c) && !deferred.some((d) => d.callOpen < c.index && c.index < d.callClose)) ||
+      assertionCalls(before).some((c) => c.kind === 'assert' && !deferred.some((d) => d.callOpen < c.index && c.index < d.callClose)) ||
+      [...calledNames(before.masked)].some((n) => assertingHelpers.has(n))
+    if (assertedBefore) continue
+    // `test.skip(); return` / `t.skip(…); return` / `this.skip(); return`: a runtime skip the
+    // runner REPORTS as skipped — not a silent pass (UNLINKED_SKIP governs the skip call).
+    if (/(?:\b(?:test|it|t|ctx|context|this)\s*\.\s*skip\s*\([^;{}]*\)\s*;?\s*$)/.test(before.masked)) continue
+    const after = masked.slice(m.index)
+    EXPECT_CALL_RE.lastIndex = 0
+    let asserts = EXPECT_CALL_RE.test(after) || ASSERT_CALL_RE.test(after)
+    EXPECT_CALL_RE.lastIndex = 0
+    if (!asserts) for (const n of calledNames(after)) if (assertingHelpers.has(n)) { asserts = true; break }
+    if (asserts) return m.index
+  }
+  return -1
+}
+
+/** [MOCK_ONLY_ASSERTION] every assertion reads only what the TEST ITSELF got back from a
+ *  mock it defined (`const f = jest.fn().mockReturnValue(x); expect(f(…)).toBe(x)`) — the
+ *  code under test is never exercised, so the assertion is the mock echoing its setup. */
+export function isMockOnlyAssertion(block) {
+  const masked = block.bodyMasked
+  const mocks = new Set()
+  for (const m of masked.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:jest|vi|vitest)\s*\.\s*fn\b|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*sinon\s*\.\s*(?:stub|fake|spy)\b/g)) mocks.add(m[1] || m[2])
+  if (!mocks.size) return false
+  const alt = [...mocks].map((n) => n.replace(/\$/g, '\\$')).join('|')
+  const results = new Set()
+  for (const m of masked.matchAll(new RegExp(`\\b(?:const|let|var)\\s+(\\{[^}]*\\}|[A-Za-z_$][\\w$]*)\\s*(?::[^=]+)?=\\s*(?:await\\s+)?(?:${alt})\\s*\\(`, 'g'))) {
+    if (m[1].startsWith('{')) for (const part of m[1].slice(1, -1).split(',')) { const n = part.split(':').pop().trim(); if (n) results.add(n) }
+    else results.add(m[1])
+  }
+  const calls = assertionCalls(block)
+  if (!calls.length) return false
+  const direct = new RegExp(`^(?:await\\s+)?(?:${alt})\\s*\\(`)
+  return calls.every((c) => {
+    const a = stripTypeSyntax(c.argMasked)
+    if (direct.test(a)) return true
+    const root = /^(?:await\s+)?([A-Za-z_$][\w$]*)/.exec(a)
+    return !!root && results.has(root[1])
+  })
+}
+
+/** [TYPE_ONLY_ASSERTION] a binding annotated with an inline object type
+ *  (`const r: { status?: 'ok' } = await f()`) whose only assertions are existence checks
+ *  on the bare binding: the field the test is about appears only in the TYPE, which is
+ *  erased at runtime — nothing reads it. */
+export function isTypeOnlyAssertion(block) {
+  const masked = block.bodyMasked
+  const typed = new Set()
+  for (const m of masked.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*:\s*\{/g)) typed.add(m[1])
+  if (!typed.size) return false
+  const calls = assertionCalls(block)
+  if (!calls.length) return false
+  const EXIST = new Set(['toBeDefined', 'not.toBeUndefined', 'not.toBeNull', 'toBeTruthy'])
+  return calls.every((c) => {
+    const a = stripTypeSyntax(c.argMasked).trim()
+    if (!typed.has(a)) return false
+    if (c.kind === 'expect') return EXIST.has(c.chain)
+    return c.method === '' || c.method === 'ok'
+  })
+}
+
+/** [KEY_PRESENCE_ONLY] every assertion checks only that a QUOTED key exists
+ *  (`toHaveProperty('k')` with no value, `expect(Object.keys(x)).toContain('k')`,
+ *  `'k' in x`) — the value under that key is never read, so any value (null, the wrong
+ *  status, an error shape) passes. */
+export function isKeyPresenceOnly(block) {
+  const calls = assertionCalls(block)
+  if (!calls.length) return false
+  const STR = /^(['"`])[^'"`]*\1$/
+  return calls.every((c) => {
+    if (c.kind === 'assert') return (c.method === '' || c.method === 'ok') && /^(['"])[^'"]*\1\s+in\s+/.test(c.arg) && !/,/.test(c.argMasked)
+    if (c.chain === 'toHaveProperty' && c.matcherArg && STR.test(c.matcherArg)) return true
+    if (/^Object\s*\.\s*(?:keys|getOwnPropertyNames)\s*\(/.test(c.argMasked) && ['toContain', 'toContainEqual'].includes(c.chain) && c.matcherArg && STR.test(c.matcherArg)) return true
+    if (/^(['"])[^'"]*\1\s+in\s+/.test(c.arg) && (c.chain === 'toBeTruthy' || (c.chain === 'toBe' && c.matcherArg === 'true'))) return true
+    return false
+  })
+}
+
+/** [CONDITIONAL_SKIP] a skip used as a VALUE — `(cond ? describe : describe.skip)(…)`,
+ *  `const d = ok ? it : xit`, `describe.skipIf(c)`, `it.runIf(c)`, `test.skip.each` —
+ *  the suite silently vanishes whenever the condition flips (e.g. in CI). Same
+ *  SKIP-LEDGER linkage as a plain skip. Returns masked-source offsets. */
+const CONDITIONAL_SKIP_RE = /\b(?:describe|it|test)\s*\.\s*skip\b(?!\s*\()|(?<![.\w$])(?:xdescribe|xit|xtest)\b(?!\s*\()|\b(?:describe|it|test)\s*\.\s*(?:skipIf|runIf)\s*\(/g
+export function conditionalSkipOffsets(masked) {
+  const out = []
+  CONDITIONAL_SKIP_RE.lastIndex = 0
+  let m
+  while ((m = CONDITIONAL_SKIP_RE.exec(masked)) !== null) {
+    out.push(m.index)
+  }
+  return out
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Orchestration
+// ─────────────────────────────────────────────────────────────────────────
+export function findVacuousSpecs(relPath, source, assertingHelpers = null) {
+  const violations = []
+  const helpers = assertingHelpers ?? (() => { try { return assertingHelpersOf(relPath, source) } catch { return new Set() } })()
+  const ruleTesters = ruleTesterNames(source)
+  const srcMasked = maskStringsAndComments(source)
+  for (const at of conditionalSkipOffsets(srcMasked)) {
+    const line = lineAt(source, at)
+    if (!skipLacksLedgerEntry(source, line)) continue
+    violations.push({
+      file: relPath,
+      line,
+      rule: 'CONDITIONAL_SKIP',
+      message:
+        'a skip used as a value (`cond ? describe : describe.skip`, `skipIf`, `runIf`, `xit` as a ' +
+        'variable) — whenever the condition flips (e.g. in CI) the suite silently disappears and ' +
+        'the run stays green. FIX: run it unconditionally, or add `// SKIP-LEDGER: <ref>` naming ' +
+        'why and where that decision is recorded.',
+    })
+  }
+  for (const block of findTestBlocks(source)) {
+    if (block.kind === 'skip') {
+      if (skipLacksLedgerEntry(source, block.line)) {
+        violations.push({
+          file: relPath,
+          line: block.line,
+          rule: 'UNLINKED_SKIP',
+          message:
+            `skipped test with no SKIP-LEDGER: tag. FIX: add ` +
+            `\`// SKIP-LEDGER: <doc path, work-order id, or ledger id>\` on this line ` +
+            `or within the 3 lines above it, naming why this is skipped and where that ` +
+            `decision is recorded.`,
+        })
+      }
+      continue
+    }
+    if (isNoAssertion(block, helpers, ruleTesters)) {
+      violations.push({
+        file: relPath,
+        line: block.line,
+        rule: 'NO_ASSERTION',
+        message: 'test body calls no expect(...)/assert(...) — it can never fail. FIX: assert the behaviour this test claims to cover, or remove it.',
+      })
+      continue
+    }
+    if (isAllTautological(block)) {
+      violations.push({
+        file: relPath,
+        line: block.line,
+        rule: 'TAUTOLOGICAL',
+        message:
+          'every assertion in this test is tautological (a literal compared to itself, or ' +
+          'toBeDefined() on a value the test just constructed) — it cannot fail regardless of ' +
+          'the code under test. FIX: assert against the real output of the unit under test.',
+      })
+      continue
+    }
+    if (hasSwallowedCatch(block)) {
+      violations.push({
+        file: relPath,
+        line: block.line,
+        rule: 'SWALLOWED_CATCH',
+        message:
+          'a try/catch around a call swallows the error with no assertion in the catch body — ' +
+          'if the unit under test throws, this test still passes. FIX: assert on the caught ' +
+          'error (expect(...).rejects/toThrow, or assert its shape), or remove the catch and let ' +
+          'a real failure fail the test.',
+      })
+      continue
+    }
+    const idiom = idiomViolation(source, block, helpers)
+    if (idiom) violations.push({ file: relPath, line: block.line, ...idiom })
+  }
+  return violations
+}
+
+/** The idiom rules, in order; the first that fires is reported (one rule per block). */
+function idiomViolation(source, block, helpers) {
+  const er = earlyReturnIndex(block, helpers)
+  if (er !== -1 && skipLacksLedgerEntry(source, lineAt(source, block.bodyStart + er))) {
+    return { rule: 'EARLY_RETURN', message: `a bare \`return\` at test level (line ${lineAt(source, block.bodyStart + er)}) comes before the assertions — on that path the test passes having asserted nothing. FIX: assert on both paths, make the precondition itself an assertion, or add \`// SKIP-LEDGER: <ref>\` if it is a recorded skip.` }
+  }
+  if (hasDoneBeforeAsyncAssertion(block)) {
+    return { rule: 'DONE_EARLY', message: 'done() is called synchronously while an assertion sits in a promise/timer callback — jest ends the test at done(), so that assertion can never fail it. FIX: make the test async and await the promise, or call done() inside the callback after the assertion.' }
+  }
+  if (hasFloatingAsyncAssertion(block)) {
+    return { rule: 'PROMISE_NOT_AWAITED', message: 'an assertion lives in a .then/.catch/.finally (or timer) callback whose promise the test never awaits or returns — the test finishes before the assertion runs. FIX: `await` (or `return`) the chain, or assert on `await`ed values.' }
+  }
+  if (isMockOnlyAssertion(block)) {
+    return { rule: 'MOCK_ONLY_ASSERTION', message: 'every assertion reads only what a mock this test defined returned when the test itself called it — the unit under test is never exercised. FIX: call the real unit (inject the mock as its dependency) and assert on its output.' }
+  }
+  if (isTypeOnlyAssertion(block)) {
+    return { rule: 'TYPE_ONLY_ASSERTION', message: 'the fields this test is about appear only in a TypeScript type annotation (erased at runtime); the only assertion is an existence check on the whole value. FIX: assert the field values, e.g. expect(r.status).toBe(...).' }
+  }
+  if (isKeyPresenceOnly(block)) {
+    return { rule: 'KEY_PRESENCE_ONLY', message: 'every assertion checks only that a quoted key EXISTS (toHaveProperty(\'k\') / Object.keys(x) toContain(\'k\') / \'k\' in x) — the value is never read, so any value passes. FIX: assert the value, e.g. toHaveProperty(\'k\', expected) or expect(x.k).toBe(...).' }
+  }
+  return null
+}
+