dsh-vibe-math 2.7.2 → 2.8.0

package/tests/audit-spec-traceability.mjs

@@ -1,193 +1,193 @@
-#!/usr/bin/env node
-/**
- * SPEC/README ↔ CODE TRACEABILITY (all four presets).
- *
- * This class of drift has produced real bugs here twice: a `/v4` usage string that advertised a
- * `message` subcommand no branch implemented, and personas that never named registered tools. The
- * rule is asymmetric on purpose:
- *
- *   · a tool the SPEC/README advertises that the code does NOT register  → FAIL (a documented
- *     capability that does not exist is a lie the agent will act on);
- *   · a tool the code registers that the spec never names                   → NOTE (documenting
- *     every member-only tool in the spec is not always desirable, but the gap must be visible);
- *   · the four Lean parameters must be documented in the spec AND the README AND accepted by the
- *     code — a parameter nobody documents cannot be discovered, and one nobody accepts cannot be set.
- *
- * Run: node tests/audit-spec-traceability.mjs [--json]
- */
-import { readFileSync, existsSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join } from 'node:path'
-
-const HERE = fileURLToPath(new URL('../', import.meta.url))
-const read = (rel) => (existsSync(join(HERE, rel)) ? readFileSync(join(HERE, rel), 'utf8') : null)
-
-const PRESETS = [
-  { tag: 'v2', js: 'vibe-math-v2/vibe-math-v2.js', spec: 'vibe-math-v2/实现方案.md', prefix: 'vibe_math_' },
-  { tag: 'v3', js: 'vibe-math-v3/vibe-math-v3.js', spec: 'vibe-math-v3/实现方案.md', prefix: 'vibe_math_' },
-  { tag: 'v4', js: 'vibe-math-v4/vibe-math-v4.js', spec: 'vibe-math-v4/实现方案.md', prefix: 'vibe_v4_' },
-  { tag: 'v5', js: 'vibe-math-v5/vibe-math-v5.js', spec: 'vibe-math-v5/实现方案.md', prefix: 'vibe_v5_' },
-]
-// Tokens that look like tool names but are FILE names / namespace prose, not tools.
-const NOT_A_TOOL = new Set([
-  'vibe_math_setting.json', 'vibe_math_installed.json', 'vibe_math_lean', 'vibe_math_lean_',
-  'vibe_v4_setting.json', 'vibe_v5_state', 'vibe_v5_state.json', 'vibe_v5_lean', 'vibe_v5_lean_',
-  'vibe_v4_lean', 'vibe_v4_lean_', 'vibe_math_state', 'vibe_math_state.json',
-])
-const LEAN_PARAMS = ['formalVerify', 'leanCommand', 'leanArgs', 'leanTimeoutMs']
-
-const README = read('README.md') || ''
-const findings = []
-const notes = []
-let passed = 0
-const ok = (cond, label, detail) => {
-  if (cond) { passed++; return true }
-  findings.push(label + (detail ? ' — ' + detail : ''))
-  return false
-}
-// The README documents ALL FOUR presets at once, and v2/v3 share the `vibe_math_` prefix, so a
-// repo-wide token is legitimate if ANY preset registers it. The per-preset SPEC is checked strictly
-// against that preset's own registry.
-const ALL_TOOLS = new Set()
-for (const P of PRESETS) {
-  const src = read(P.js)
-  if (!src) continue
-  for (const m of src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)) ALL_TOOLS.add(m[1])
-}
-/** Collect `vibe_*` tokens that are used as TOOL names (not file names such as vibe_math_setting.json). */
-function toolTokens(text) {
-  const out = new Set()
-  for (const m of text.matchAll(/\b(vibe_(?:math|v4|v5)_[A-Za-z0-9_]+)/g)) {
-    const after = text[m.index + m[0].length] || ''
-    if (after === '.') continue // a file name, e.g. vibe_math_setting.json
-    // A doc may name a tool precisely to say it does NOT exist ("v4 没有 vibe_v4_propose_verify 这个工具",
-    // "写了不存在的工具 …"). That is documentation of the fix, not a phantom capability — skip it, or
-    // the guard would forbid the very sentence that records the correction.
-    const lineStart = text.lastIndexOf('\n', m.index) + 1
-    const lineEnd = text.indexOf('\n', m.index)
-    const line = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd)
-    if (/没有|不存在|并非|不是工具|未注册|从未注册|无此|does not exist|no such|never registered|not a tool/i.test(line)) continue
-    out.add(m[1])
-  }
-  return out
-}
-
-for (const P of PRESETS) {
-  const js = read(P.js)
-  const spec = read(P.spec)
-  if (!js || !spec) { findings.push(P.tag + ': missing plugin or spec file'); continue }
-
-  const codeTools = new Set([...js.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)].map((m) => m[1]))
-  ok(codeTools.size > 0, P.tag + ': the plugin registers tools at all')
-
-  // direction 1 (FAIL): anything the spec names as a tool must exist in THIS preset; anything the
-  // README names must exist in at least one preset (the README covers all four).
-  for (const [label, text, own] of [['实现方案', spec, true], ['README', README, false]]) {
-    for (const t of toolTokens(text)) {
-      if (NOT_A_TOOL.has(t)) continue
-      if (t.endsWith('_')) continue // a `vibe_x_*` wildcard placeholder
-      if (!t.startsWith(P.prefix)) continue
-      const known = own ? codeTools.has(t) : ALL_TOOLS.has(t)
-      if (!known) {
-        findings.push(P.tag + ' [' + label + ']: documents tool ' + t
-          + (own ? ' but the plugin never registers it' : ' but NO preset registers it'))
-      }
-    }
-  }
-
-  // direction 2 (NOTE): registered but not documented anywhere
-  const md = spec + '\n' + README
-  const undocumented = [...codeTools].filter((t) => !md.includes(t)).sort()
-  if (undocumented.length) notes.push(P.tag + ': registered but not named in spec/README: ' + undocumented.join(', '))
-
-  // the four Lean parameters: documented in spec + README, and accepted by the code
-  for (const prm of LEAN_PARAMS) {
-    ok(spec.includes(prm), P.tag + ': 实现方案 documents ' + prm)
-    ok(README.includes(prm), P.tag + ': README documents ' + prm)
-    ok(js.includes(prm), P.tag + ': the plugin accepts ' + prm)
-  }
-
-  // the Lean tools must appear in the spec's tool table AND in the code
-  for (const t of [P.prefix + 'lean_run', P.prefix + 'lean_archive', P.prefix + 'lean_lib']) {
-    ok(codeTools.has(t), P.tag + ': registers ' + t)
-    ok(spec.includes(t), P.tag + ': 实现方案 names ' + t)
-  }
-
-  // the contract §7 requires an ACTIVE stop on timeout: `handle.terminate()`. Relying on the
-  // host's `graceMs` alone lets a runaway Lean process linger while the framework reports
-  // LEAN_TIMEOUT — three of four presets shipped that way, so this is now guarded statically.
-  ok(/terminate\s*\(/.test(js), P.tag + ': the Lean run path actively terminates on timeout (contract §7)')
-
-  // the contract §8 puts the `require` gate at the ONE choke point that writes a Verified card.
-  // A card writer reachable WITHOUT passing a gated function would be a gate bypass, i.e. the
-  // framework could conclude a verdict that `require` is supposed to withhold.
-  {
-    const cfg = {
-      v2: { writers: ['writeVerifiedCardIfNeeded', 'writeVerifiedProblemCardIfNeeded'], gate: /formalRequired\s*\(|formalGateOk\s*\(|formalVerdictDeferred\s*\(/ },
-      v3: { writers: ['writeVerifiedCardIfChanged', 'writeVerifiedPropositionCardIfNeeded', 'writeVerifiedProblemCardIfNeeded'], gate: /formalBlocksConclusion\s*\(/ },
-      v4: { writers: ['writeVerifiedCard'], gate: /formalGateOk\s*\(/ },
-      v5: { writers: ['writeVerifiedCard'], gate: /formalGateOk\s*\(/ },
-    }[P.tag]
-    const lines = js.split(/\r?\n/)
-    const fns = []
-    for (let i = 0; i < lines.length; i++) {
-      const m = /^(\s*)(?:async\s+)?function\s+([A-Za-z0-9_$]+)\s*\(/.exec(lines[i])
-      if (m) fns.push({ name: m[2], indent: m[1].length, start: i })
-    }
-    for (let k = 0; k < fns.length; k++) {
-      const f = fns[k]
-      let end = lines.length
-      for (const g of fns) if (g.start > f.start && g.indent <= f.indent) { end = g.start; break }
-      f.body = lines.slice(f.start, end).join('\n')
-    }
-    const byName = (n) => fns.find((f) => f.name === n)
-    for (const w of cfg.writers) {
-      const f = byName(w)
-      if (!f) { ok(false, P.tag + ' §8: the documented card writer ' + w + ' does not exist'); continue }
-      const selfGated = cfg.gate.test(f.body)
-      const callers = fns.filter((g) => g !== f && new RegExp('(^|[^A-Za-z0-9_$])' + w + '\\s*\\(').test(g.body))
-      const allCallersGatedOrRecursive = callers.length > 0 && callers.every((c) => cfg.gate.test(c.body) || fns.some((d) => cfg.gate.test(d.body) && new RegExp('(^|[^A-Za-z0-9_$])' + c.name + '\\s*\\(').test(d.body)))
-      ok(selfGated || allCallersGatedOrRecursive,
-        P.tag + ' §8: ' + w + ' is reachable only through a gated function (no gate bypass)',
-        'callers: ' + callers.map((c) => c.name).join(', '))
-    }
-  }
-
-  notes.push(P.tag + ': ' + codeTools.size + ' tools registered; spec ' + spec.length + 'B')
-}
-
-// cross-preset: the shared contract must name the four parameters too
-const contract = read('docs/formal-verification.md') || ''
-for (const prm of LEAN_PARAMS) ok(contract.includes(prm), 'contract documents ' + prm)
-
-// The §4 transition table is the normative statement every preset implements. Two rows were WRONG
-// here (the code was right, the contract was not), and a wrong contract is how the next edit gets
-// written:
-//   · `used` must NOT withdraw an established proof (only a fidelity `defect` does). v2 actually
-//     shipped the downgrade, so the contract literal and reality disagreed in opposite directions.
-//   · a RED re-archive of kind='proof' overwrites the work file, so the old archived proof no longer
-//     corresponds to any code — it must be retracted, not left at the "everyone looks here" path.
-{
-  const usedRow = (contract.split(/\r?\n/).find((l) => /decision:'used'/.test(l)) || '')
-  ok(/不得/.test(usedRow) && /passed/.test(usedRow) && /blocked/.test(usedRow),
-    "contract §4: the `used` row says an existing passed/blocked is PRESERVED (only `defect` retracts)",
-    'row: ' + usedRow.slice(0, 120))
-  const runRows = contract.split(/\r?\n/).filter((l) => /^\|\s*`lean_run`/.test(l))
-  ok(runRows.length >= 2 && runRows.every((l) => /不降级|保持原状/.test(l)),
-    'contract §4: both `lean_run` rows say they do not downgrade an existing passed/blocked',
-    'rows: ' + runRows.map((l) => l.slice(0, 60)).join(' || '))
-  ok(/该文件最近一次运行\*\*失败\*\*/.test(contract) && /撤回/.test(contract),
-    'contract §4: a FAILED proof re-archive is documented as retracting the previous archived proof')
-}
-
-const out = { passed, failed: findings.length, findings, notes }
-if (process.argv.includes('--json')) console.log(JSON.stringify(out, null, 2))
-else {
-  console.log('-- spec/README ↔ code traceability --')
-  for (const n of notes) console.log('  note ' + n)
-  console.log('')
-  for (const f of findings) console.error('  FAIL ' + f)
-  console.log('')
-  console.log('TRACEABILITY: ' + passed + ' passed, ' + findings.length + ' failed')
-}
-process.exit(findings.length === 0 ? 0 : 1)
+#!/usr/bin/env node
+/**
+ * SPEC/README ↔ CODE TRACEABILITY (all four presets).
+ *
+ * This class of drift has produced real bugs here twice: a `/v4` usage string that advertised a
+ * `message` subcommand no branch implemented, and personas that never named registered tools. The
+ * rule is asymmetric on purpose:
+ *
+ *   · a tool the SPEC/README advertises that the code does NOT register  → FAIL (a documented
+ *     capability that does not exist is a lie the agent will act on);
+ *   · a tool the code registers that the spec never names                   → NOTE (documenting
+ *     every member-only tool in the spec is not always desirable, but the gap must be visible);
+ *   · the four Lean parameters must be documented in the spec AND the README AND accepted by the
+ *     code — a parameter nobody documents cannot be discovered, and one nobody accepts cannot be set.
+ *
+ * Run: node tests/audit-spec-traceability.mjs [--json]
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const HERE = fileURLToPath(new URL('../', import.meta.url))
+const read = (rel) => (existsSync(join(HERE, rel)) ? readFileSync(join(HERE, rel), 'utf8') : null)
+
+const PRESETS = [
+  { tag: 'v2', js: 'vibe-math-v2/vibe-math-v2.js', spec: 'vibe-math-v2/实现方案.md', prefix: 'vibe_math_' },
+  { tag: 'v3', js: 'vibe-math-v3/vibe-math-v3.js', spec: 'vibe-math-v3/实现方案.md', prefix: 'vibe_math_' },
+  { tag: 'v4', js: 'vibe-math-v4/vibe-math-v4.js', spec: 'vibe-math-v4/实现方案.md', prefix: 'vibe_v4_' },
+  { tag: 'v5', js: 'vibe-math-v5/vibe-math-v5.js', spec: 'vibe-math-v5/实现方案.md', prefix: 'vibe_v5_' },
+]
+// Tokens that look like tool names but are FILE names / namespace prose, not tools.
+const NOT_A_TOOL = new Set([
+  'vibe_math_setting.json', 'vibe_math_installed.json', 'vibe_math_lean', 'vibe_math_lean_',
+  'vibe_v4_setting.json', 'vibe_v5_state', 'vibe_v5_state.json', 'vibe_v5_lean', 'vibe_v5_lean_',
+  'vibe_v4_lean', 'vibe_v4_lean_', 'vibe_math_state', 'vibe_math_state.json',
+])
+const LEAN_PARAMS = ['formalVerify', 'leanCommand', 'leanArgs', 'leanTimeoutMs']
+
+const README = read('README.md') || ''
+const findings = []
+const notes = []
+let passed = 0
+const ok = (cond, label, detail) => {
+  if (cond) { passed++; return true }
+  findings.push(label + (detail ? ' — ' + detail : ''))
+  return false
+}
+// The README documents ALL FOUR presets at once, and v2/v3 share the `vibe_math_` prefix, so a
+// repo-wide token is legitimate if ANY preset registers it. The per-preset SPEC is checked strictly
+// against that preset's own registry.
+const ALL_TOOLS = new Set()
+for (const P of PRESETS) {
+  const src = read(P.js)
+  if (!src) continue
+  for (const m of src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)) ALL_TOOLS.add(m[1])
+}
+/** Collect `vibe_*` tokens that are used as TOOL names (not file names such as vibe_math_setting.json). */
+function toolTokens(text) {
+  const out = new Set()
+  for (const m of text.matchAll(/\b(vibe_(?:math|v4|v5)_[A-Za-z0-9_]+)/g)) {
+    const after = text[m.index + m[0].length] || ''
+    if (after === '.') continue // a file name, e.g. vibe_math_setting.json
+    // A doc may name a tool precisely to say it does NOT exist ("v4 没有 vibe_v4_propose_verify 这个工具",
+    // "写了不存在的工具 …"). That is documentation of the fix, not a phantom capability — skip it, or
+    // the guard would forbid the very sentence that records the correction.
+    const lineStart = text.lastIndexOf('\n', m.index) + 1
+    const lineEnd = text.indexOf('\n', m.index)
+    const line = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd)
+    if (/没有|不存在|并非|不是工具|未注册|从未注册|无此|does not exist|no such|never registered|not a tool/i.test(line)) continue
+    out.add(m[1])
+  }
+  return out
+}
+
+for (const P of PRESETS) {
+  const js = read(P.js)
+  const spec = read(P.spec)
+  if (!js || !spec) { findings.push(P.tag + ': missing plugin or spec file'); continue }
+
+  const codeTools = new Set([...js.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)].map((m) => m[1]))
+  ok(codeTools.size > 0, P.tag + ': the plugin registers tools at all')
+
+  // direction 1 (FAIL): anything the spec names as a tool must exist in THIS preset; anything the
+  // README names must exist in at least one preset (the README covers all four).
+  for (const [label, text, own] of [['实现方案', spec, true], ['README', README, false]]) {
+    for (const t of toolTokens(text)) {
+      if (NOT_A_TOOL.has(t)) continue
+      if (t.endsWith('_')) continue // a `vibe_x_*` wildcard placeholder
+      if (!t.startsWith(P.prefix)) continue
+      const known = own ? codeTools.has(t) : ALL_TOOLS.has(t)
+      if (!known) {
+        findings.push(P.tag + ' [' + label + ']: documents tool ' + t
+          + (own ? ' but the plugin never registers it' : ' but NO preset registers it'))
+      }
+    }
+  }
+
+  // direction 2 (NOTE): registered but not documented anywhere
+  const md = spec + '\n' + README
+  const undocumented = [...codeTools].filter((t) => !md.includes(t)).sort()
+  if (undocumented.length) notes.push(P.tag + ': registered but not named in spec/README: ' + undocumented.join(', '))
+
+  // the four Lean parameters: documented in spec + README, and accepted by the code
+  for (const prm of LEAN_PARAMS) {
+    ok(spec.includes(prm), P.tag + ': 实现方案 documents ' + prm)
+    ok(README.includes(prm), P.tag + ': README documents ' + prm)
+    ok(js.includes(prm), P.tag + ': the plugin accepts ' + prm)
+  }
+
+  // the Lean tools must appear in the spec's tool table AND in the code
+  for (const t of [P.prefix + 'lean_run', P.prefix + 'lean_archive', P.prefix + 'lean_lib']) {
+    ok(codeTools.has(t), P.tag + ': registers ' + t)
+    ok(spec.includes(t), P.tag + ': 实现方案 names ' + t)
+  }
+
+  // the contract §7 requires an ACTIVE stop on timeout: `handle.terminate()`. Relying on the
+  // host's `graceMs` alone lets a runaway Lean process linger while the framework reports
+  // LEAN_TIMEOUT — three of four presets shipped that way, so this is now guarded statically.
+  ok(/terminate\s*\(/.test(js), P.tag + ': the Lean run path actively terminates on timeout (contract §7)')
+
+  // the contract §8 puts the `require` gate at the ONE choke point that writes a Verified card.
+  // A card writer reachable WITHOUT passing a gated function would be a gate bypass, i.e. the
+  // framework could conclude a verdict that `require` is supposed to withhold.
+  {
+    const cfg = {
+      v2: { writers: ['writeVerifiedCardIfNeeded', 'writeVerifiedProblemCardIfNeeded'], gate: /formalRequired\s*\(|formalGateOk\s*\(|formalVerdictDeferred\s*\(/ },
+      v3: { writers: ['writeVerifiedCardIfChanged', 'writeVerifiedPropositionCardIfNeeded', 'writeVerifiedProblemCardIfNeeded'], gate: /formalBlocksConclusion\s*\(/ },
+      v4: { writers: ['writeVerifiedCard'], gate: /formalGateOk\s*\(/ },
+      v5: { writers: ['writeVerifiedCard'], gate: /formalGateOk\s*\(/ },
+    }[P.tag]
+    const lines = js.split(/\r?\n/)
+    const fns = []
+    for (let i = 0; i < lines.length; i++) {
+      const m = /^(\s*)(?:async\s+)?function\s+([A-Za-z0-9_$]+)\s*\(/.exec(lines[i])
+      if (m) fns.push({ name: m[2], indent: m[1].length, start: i })
+    }
+    for (let k = 0; k < fns.length; k++) {
+      const f = fns[k]
+      let end = lines.length
+      for (const g of fns) if (g.start > f.start && g.indent <= f.indent) { end = g.start; break }
+      f.body = lines.slice(f.start, end).join('\n')
+    }
+    const byName = (n) => fns.find((f) => f.name === n)
+    for (const w of cfg.writers) {
+      const f = byName(w)
+      if (!f) { ok(false, P.tag + ' §8: the documented card writer ' + w + ' does not exist'); continue }
+      const selfGated = cfg.gate.test(f.body)
+      const callers = fns.filter((g) => g !== f && new RegExp('(^|[^A-Za-z0-9_$])' + w + '\\s*\\(').test(g.body))
+      const allCallersGatedOrRecursive = callers.length > 0 && callers.every((c) => cfg.gate.test(c.body) || fns.some((d) => cfg.gate.test(d.body) && new RegExp('(^|[^A-Za-z0-9_$])' + c.name + '\\s*\\(').test(d.body)))
+      ok(selfGated || allCallersGatedOrRecursive,
+        P.tag + ' §8: ' + w + ' is reachable only through a gated function (no gate bypass)',
+        'callers: ' + callers.map((c) => c.name).join(', '))
+    }
+  }
+
+  notes.push(P.tag + ': ' + codeTools.size + ' tools registered; spec ' + spec.length + 'B')
+}
+
+// cross-preset: the shared contract must name the four parameters too
+const contract = read('docs/formal-verification.md') || ''
+for (const prm of LEAN_PARAMS) ok(contract.includes(prm), 'contract documents ' + prm)
+
+// The §4 transition table is the normative statement every preset implements. Two rows were WRONG
+// here (the code was right, the contract was not), and a wrong contract is how the next edit gets
+// written:
+//   · `used` must NOT withdraw an established proof (only a fidelity `defect` does). v2 actually
+//     shipped the downgrade, so the contract literal and reality disagreed in opposite directions.
+//   · a RED re-archive of kind='proof' overwrites the work file, so the old archived proof no longer
+//     corresponds to any code — it must be retracted, not left at the "everyone looks here" path.
+{
+  const usedRow = (contract.split(/\r?\n/).find((l) => /decision:'used'/.test(l)) || '')
+  ok(/不得/.test(usedRow) && /passed/.test(usedRow) && /blocked/.test(usedRow),
+    "contract §4: the `used` row says an existing passed/blocked is PRESERVED (only `defect` retracts)",
+    'row: ' + usedRow.slice(0, 120))
+  const runRows = contract.split(/\r?\n/).filter((l) => /^\|\s*`lean_run`/.test(l))
+  ok(runRows.length >= 2 && runRows.every((l) => /不降级|保持原状/.test(l)),
+    'contract §4: both `lean_run` rows say they do not downgrade an existing passed/blocked',
+    'rows: ' + runRows.map((l) => l.slice(0, 60)).join(' || '))
+  ok(/该文件最近一次运行\*\*失败\*\*/.test(contract) && /撤回/.test(contract),
+    'contract §4: a FAILED proof re-archive is documented as retracting the previous archived proof')
+}
+
+const out = { passed, failed: findings.length, findings, notes }
+if (process.argv.includes('--json')) console.log(JSON.stringify(out, null, 2))
+else {
+  console.log('-- spec/README ↔ code traceability --')
+  for (const n of notes) console.log('  note ' + n)
+  console.log('')
+  for (const f of findings) console.error('  FAIL ' + f)
+  console.log('')
+  console.log('TRACEABILITY: ' + passed + ' passed, ' + findings.length + ' failed')
+}
+process.exit(findings.length === 0 ? 0 : 1)

package/tests/audit-status-report-fields.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * STATUS/REPORT FIELD TABLE vs SOURCE (G-6) — the doc's per-preset field/scope rows must be exactly the
+ * fields the code declares, in BOTH directions, and each row's scope must match the source classification.
+ *
+ * DEFECT CLASS: "machine-face field documented nowhere / documented field that does not exist" (F12/F3):
+ * `实现方案.md §14.9` claimed every `status()` field had a row while >=13 top-level keys had none; and a
+ * table written by hand drifts the moment a field is added. Sources are derived BY MARKER (line numbers
+ * are claims, not anchors):
+ *   v2/v3 -> `fieldScopes: { session: [...], durable: [...] }`  (20 / 25 entries)
+ *   v5    -> the top-level keys of the object literal `status()` returns (its `fieldScopes` is coarse)
+ *   v4    -> has NO `fieldScopes`; the table must say so rather than invent rows
+ *
+ * Run: node tests/audit-status-report-fields.mjs
+ * Env (mutant harness): FIELD_DOC, FIELD_V2_JS, FIELD_V3_JS, FIELD_V5_JS, FIELD_V4_JS (absolute or relative).
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+let passed = 0, failed = 0
+const failures = []
+const ok = (cond, label, detail) => { if (cond) passed++; else { failed++; failures.push(label + (detail ? ' — ' + detail : '')) } }
+const read = (envName, rel) => {
+  const v = process.env[envName]
+  return readFileSync(v ? (isAbsolute(v) ? v : join(REPO, v)) : join(REPO, rel), 'utf8')
+}
+function fieldScopesOf(text) {
+  const lines = text.split(/\r?\n/)
+  const start = lines.findIndex((l) => /^\s*fieldScopes:\s*\{/.test(l))
+  if (start === -1) return null
+  let depth = 0
+  const buf = []
+  for (let i = start; i < lines.length; i++) {
+    buf.push(lines[i]); depth += (lines[i].match(/\{/g) || []).length - (lines[i].match(/\}/g) || []).length
+    if (i > start && depth <= 0) break
+  }
+  const out = {}
+  for (const m of buf.join('\n').matchAll(/(\w+):\s*\[([\s\S]*?)\]/g)) {
+    out[m[1]] = m[2].split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+  }
+  return out
+}
+function statusKeysOf(text) {
+  // Robust: brace/comment/string aware, and it reads SHORTHAND properties too —
+  // `institute: instituteName, project, key, phase,` is FOUR keys, not one. The earlier line-anchored
+  // version missed 8 real keys (R19 F-A: project/key/phase/running/autoDone/runId/lastProgressAt/params).
+  const fn = text.search(/function\s+status\s*\(/)
+  if (fn === -1) return null
+  const ret = text.indexOf('return {', fn)
+  if (ret === -1) return null
+  const start = text.indexOf('{', ret)
+  let d0 = 0, stop = start, k = start
+  while (k < text.length) {
+    const c = text[k]
+    if (c === '/' && text[k + 1] === '/') { while (k < text.length && text[k] !== '\n') k++; continue }
+    if (c === '/' && text[k + 1] === '*') { k += 2; while (k < text.length && !(text[k] === '*' && text[k + 1] === '/')) k++; k += 2; continue }
+    if (c === '"' || c === "'" || c === '`') { const q = c; k++; while (k < text.length) { if (text[k] === '\\') k += 2; else if (text[k] === q) break; else k++ } k++; continue }
+    if (c === '{' || c === '[' || c === '(') d0++
+    else if (c === '}' || c === ']' || c === ')') { d0--; if (d0 === 0) { stop = k; break } }
+    k++
+  }
+  if (d0 !== 0) return null
+  const body = text.slice(start + 1, stop)
+  const segs = []
+  let buf = '', d = 0, j = 0
+  while (j < body.length) {
+    const c = body[j]
+    if (c === '/' && body[j + 1] === '/') { while (j < body.length && body[j] !== '\n') j++; continue }
+    if (c === '/' && body[j + 1] === '*') { j += 2; while (j < body.length && !(body[j] === '*' && body[j + 1] === '/')) j++; j += 2; continue }
+    if (c === '"' || c === "'" || c === '`') { const q = c; buf += c; j++; while (j < body.length) { buf += body[j]; if (body[j] === '\\') { j++; buf += body[j] } else if (body[j] === q) break; j++ } j++; continue }
+    if (c === '{' || c === '[' || c === '(') d++
+    if (c === '}' || c === ']' || c === ')') d--
+    if (c === ',' && d === 0) { segs.push(buf); buf = ''; j++; continue }
+    buf += c; j++
+  }
+  if (buf.trim()) segs.push(buf)
+  const keys = []
+  for (const seg of segs) {
+    const t = seg.trim()
+    if (!t) continue
+    const m = /^([A-Za-z_$][\w$]*)\s*(?::|$|,)/.exec(t)
+    if (m) keys.push(m[1])
+  }
+  return [...new Set(keys)]
+}
+/** Rows of the doc section that starts with `headingPrefix`, up to the next `### `. */
+function docRows(doc, headingPrefix) {
+  const lines = doc.split(/\r?\n/)
+  const start = lines.findIndex((l) => l.startsWith(headingPrefix))
+  if (start === -1) return null
+  let end = lines.findIndex((l, i) => i > start && /^### /.test(l))
+  if (end === -1) end = lines.length
+  const rows = []
+  for (let i = start; i < end; i++) {
+    const m = /^\|\s*`([^`]+)`\s*\|\s*([^|]+?)\s*\|/.exec(lines[i])
+    if (m) rows.push({ name: m[1], scope: m[2] })
+  }
+  return rows
+}
+const diff = (a, b) => [...a].filter((x) => !b.has(x))
+
+const doc = read('FIELD_DOC', 'docs/status-report-fields.md')
+ok(doc.indexOf('G-6-FIELD-TABLE-START') !== -1 && doc.indexOf('G-6-FIELD-TABLE-END') !== -1,
+  'the doc carries the machine-generated field table between its markers (so the guard knows what to read)')
+
+const f2 = fieldScopesOf(read('FIELD_V2_JS', 'vibe-math-v2/vibe-math-v2.js'))
+const f3 = fieldScopesOf(read('FIELD_V3_JS', 'vibe-math-v3/vibe-math-v3.js'))
+const s5 = statusKeysOf(read('FIELD_V5_JS', 'vibe-math-v5/vibe-math-v5.js'))
+const v4 = read('FIELD_V4_JS', 'vibe-math-v4/vibe-math-v4.js')
+ok(!!f2 && !!f3 && !!s5, 'all three sources are parseable by marker (v2/v3 fieldScopes, v5 status())')
+
+if (f2 && f3 && s5) {
+  const cases = [
+    { preset: 'v2', src: [...(f2.session || []), ...(f2.durable || [])], head: '### v2 的字段与作用域', scopeMap: { session: '会话', durable: '耐久' }, fs: f2 },
+    { preset: 'v3', src: [...(f3.session || []), ...(f3.durable || [])], head: '### v3 的字段与作用域', scopeMap: { session: '会话', durable: '耐久' }, fs: f3 },
+    { preset: 'v5', src: s5, head: '### v5 的字段与作用域', scopeMap: null, fs: null },
+  ]
+  for (const c of cases) {
+    const rows = docRows(doc, c.head)
+    ok(!!rows && rows.length > 0, c.preset + ': the doc section exists and has rows', String(rows && rows.length))
+    if (!rows) continue
+    const docSet = new Set(rows.map((r) => r.name))
+    const srcSet = new Set(c.src)
+    const missingInDoc = diff(srcSet, docSet)
+    const extraInDoc = diff(docSet, srcSet)
+    ok(missingInDoc.length === 0, '★ ' + c.preset + ': every source field has a doc row (doc↔source, source→doc)', JSON.stringify(missingInDoc))
+    ok(extraInDoc.length === 0, '★ ' + c.preset + ': every doc row names a real source field (doc↔source, doc→source)', JSON.stringify(extraInDoc))
+    if (c.scopeMap && c.fs) {
+      const wrong = []
+      for (const scope of ['session', 'durable']) {
+        for (const name of c.fs[scope] || []) {
+          const r = rows.find((x) => x.name === name)
+          if (r && r.scope !== c.scopeMap[scope]) wrong.push(name + '=' + r.scope)
+        }
+      }
+      ok(wrong.length === 0, '★ ' + c.preset + ': every row scope matches the source classification', JSON.stringify(wrong))
+    }
+  }
+  // ---- code -> doc (R19 F-A): EVERY status() top-level key lands in the v5 table OR is an explicit
+  // exception. The exceptions list is empty today; adding one requires a reason HERE, in this file.
+  const V5_EXCEPTIONS = []
+  {
+    const v5DocRows = docRows(doc, '### v5 的字段与作用域') || []
+    const docSet5 = new Set(v5DocRows.map((r) => r.name))
+    const frozen = s5
+    const exceptions = V5_EXCEPTIONS
+    console.log('  counts: frozen=' + frozen.length + ' doc-rows=' + docSet5.size + ' exceptions=' + exceptions.length)
+    ok(frozen.length > 0 && docSet5.size > 0, '★ the three counts are non-zero (the comparison cannot pass vacuously)',
+      'frozen=' + frozen.length + ' doc-rows=' + docSet5.size + ' exceptions=' + exceptions.length)
+    const covered = new Set([...docSet5, ...exceptions])
+    const uncovered = frozen.filter((k) => !covered.has(k))
+    ok(uncovered.length === 0, '★ every status() top-level key is documented or an explicit exception (code->doc)',
+      JSON.stringify(uncovered))
+    const phantom = [...docSet5].filter((k) => frozen.indexOf(k) === -1 && exceptions.indexOf(k) === -1)
+    ok(phantom.length === 0, '★ no v5 doc row names a key status() does not return (doc->code)',
+      JSON.stringify(phantom))
+  }
+  // v4 must be stated as having none, and the source must agree
+  const v4Rows = docRows(doc, '### v4')
+  ok(!v4Rows || v4Rows.length === 0, '★ v4: no rows are invented (it has no fieldScopes to derive from)', String(v4Rows && v4Rows.length))
+  ok(doc.indexOf('**没有** `fieldScopes`') !== -1 || doc.indexOf('不存在** `fieldScopes`') !== -1,
+    '★ v4: the doc says explicitly that v4 has no fieldScopes')
+  ok(!/fieldScopes/.test(v4), '★ v4: the source confirms it (zero occurrences of fieldScopes)')
+}
+
+console.log('')
+console.log('=== STATUS FIELD TABLE: ' + passed + ' passed, ' + failed + ' failed ===')
+for (const f of failures) console.error('  - ' + f)
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-status-report-fields.mutants.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Mutant harness for tests/audit-status-report-fields.mjs (ships: `tests/*.mutants.mjs`).
+ *
+ * ONE MUTANT PER DIRECTION (the doc↔source comparison must bite both ways):
+ *   A) doc→source: delete one v2 row from a COPY of docs/status-report-fields.md -> the "every source
+ *      field has a doc row" assertion reddens by name
+ *   B) source→doc: add a field to a COPY of vibe-math-v2.js's `fieldScopes.session` -> the "every doc row
+ *      names a real source field" / missing-row assertion reddens by name
+ *
+ * Run: node tests/audit-status-report-fields.mutants.mjs
+ */
+import { mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = fileURLToPath(new URL('./', import.meta.url))
+const REPO = join(HERE, '..')
+const GUARD = join(HERE, 'audit-status-report-fields.mjs')
+let passed = 0, failed = 0
+const ok = (c, l, d) => { if (c) { passed++; console.log('  ok   ' + l) } else { failed++; console.log('  FAIL ' + l + (d ? ' — ' + d : '')) } }
+const run = (env) => {
+  const r = spawnSync(process.execPath, [GUARD], { cwd: REPO, encoding: 'utf8', env: Object.assign({}, process.env, env || {}) })
+  const out = String(r.stdout || '') + String(r.stderr || '')
+  return { status: r.status, failLines: out.split('\n').filter((l) => /^  - /.test(l)), tail: out.trim().split('\n').filter(Boolean).slice(-1)[0] || '' }
+}
+const baseline = run(null)
+ok(baseline.status === 0, 'baseline: the field-table guard is green', baseline.tail.slice(0, 80))
+
+const dir = mkdtempSync(join(tmpdir(), 'fieldtable-mut-'))
+// A) doc -> source
+const docPath = join(REPO, 'docs/status-report-fields.md')
+const docLines = readFileSync(docPath, 'utf8').split(/\r?\n/)
+const v2Head = docLines.findIndex((l) => l.startsWith('### v2 的字段与作用域'))
+const firstRow = docLines.findIndex((l, i) => i > v2Head && /^\|\s*`[^`]+`\s*\|/.test(l))
+if (v2Head === -1 || firstRow === -1) ok(false, 'A: the v2 section and its first row exist (harness and guard agree on the shape)', 'ANCHOR MISS')
+else {
+  const removed = docLines[firstRow]
+  const tampered = docLines.slice(0, firstRow).concat(docLines.slice(firstRow + 1)).join('\n')
+  writeFileSync(join(dir, 'status-report-fields.md'), tampered)
+  const a = run({ FIELD_DOC: join(dir, 'status-report-fields.md') })
+  const named = a.failLines.some((l) => l.indexOf('v2: every source field has a doc row') !== -1)
+  ok(a.status !== 0 && named, '★ A (doc→source): deleting a v2 row reddens the guard by name', 'removed=' + removed.trim().slice(0, 60) + ' exit=' + a.status)
+  if (!named) for (const l of a.failLines.slice(0, 3)) console.log('      guard failure: ' + l.trim().slice(0, 130))
+}
+// B) source -> doc
+const v2Path = join(REPO, 'vibe-math-v2/vibe-math-v2.js')
+const v2src = readFileSync(v2Path, 'utf8')
+const m = /(\n\s*session:\s*\[)([\s\S]*?)(\])/.exec(v2src)
+if (!m) ok(false, 'B: the v2 fieldScopes session array exists (anchor check)', 'ANCHOR MISS')
+else {
+  const injected = m[1] + m[2].replace(/\s*$/, '') + ", 'ghostFieldFromMutant'" + m[3]
+  writeFileSync(join(dir, 'vibe-math-v2.js'), v2src.replace(m[0], injected))
+  const b = run({ FIELD_V2_JS: join(dir, 'vibe-math-v2.js') })
+  const named = b.failLines.some((l) => l.indexOf('v2: every source field has a doc row') !== -1 || l.indexOf('v2: every doc row names a real source field') !== -1)
+  ok(b.status !== 0 && named, '★ B (source→doc): adding a field to the source reddens the guard by name', 'exit=' + b.status)
+  if (!named) for (const l of b.failLines.slice(0, 3)) console.log('      guard failure: ' + l.trim().slice(0, 130))
+}
+rmSync(dir, { recursive: true, force: true })
+console.log('')
+console.log('=== STATUS FIELD TABLE MUTANTS: ' + passed + ' passed, ' + failed + ' failed ===')
+process.exit(failed === 0 ? 0 : 1)