dsh-vibe-math 2.7.1 → 2.7.3

package/tests/audit-math-computation-contract.mutants.mjs

@@ -0,0 +1,106 @@
+// Registered mutant harness for tests/audit-math-computation-contract.mjs — the audit carries its own proof.
+// Defect shapes (all real, from this project's history):
+//   (a) the SINGLE SOURCE (PARAM_PROPS_KEYS) drops a math param  ⇒ the derived schema loses it
+//   (b) the FIRST (session-layer) registration reverts to a hand-written literal without the math keys
+//   (c) the APPLY-LAYER registration does the same — only visible because the audit now checks EVERY site
+// Each family mutates a COPY of the tree (the audit's MC_CONTRACT_ROOT seam) and must make the audit redden
+// BY NAME. Child runs are bounded (a timeout is a HANG); skipped families are printed and counted.
+// Exit criterion: every family reddens by name; ALL MUTANTS RED AS REQUIRED + exit 0 only then.
+// Run: node tests/audit-math-computation-contract.mutants.mjs
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, rmSync, readdirSync } from 'node:fs'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const AUDIT = 'tests/audit-math-computation-contract.mjs'
+// Bound every child run: run-tests has no per-suite timeout, so an unbounded child hangs the gate.
+// A timeout is reported as HANG, counts as a failure for that family, and is listed in hangs=[].
+const CHILD_TIMEOUT_MS = Number(process.env.MUTANT_CHILD_TIMEOUT_MS || 120000)
+const TIMES = []
+const hangs = []
+const skipped = []
+function copyTree(from, to) {
+  mkdirSync(to, { recursive: true })
+  for (const e of readdirSync(from, { withFileTypes: true })) {
+    if (e.name === '.git' || e.name === 'node_modules' || e.name === '_oneoff') continue
+    if (e.isDirectory()) copyTree(join(from, e.name), join(to, e.name))
+    else copyFileSync(join(from, e.name), join(to, e.name))
+  }
+}
+function runFamily(f) {
+  const dest = join(tmpdir(), 'mc-contract-mut-' + Math.random().toString(36).slice(2, 10))
+  copyTree(REPO, dest)
+  const target = join(dest, f.rel)
+  const before = readFileSync(target, 'utf8')
+  const n = before.split(f.from).length - 1
+  if (f.firstOnly ? n < 1 : n !== 1) {
+    skipped.push(f.name + ' (anchor x' + n + ')')
+    console.error('  SKIP - ' + f.name + ' (anchor x' + n + ')')
+    rmSync(dest, { recursive: true, force: true })
+    return false
+  }
+  const mutated = f.firstOnly
+    ? (() => { const i = before.indexOf(f.from); return before.slice(0, i) + f.to + before.slice(i + f.from.length) })()
+    : before.split(f.from).join(f.to)
+  writeFileSync(target, mutated, 'utf8')
+  try { execFileSync(process.execPath, ['--check', target], { stdio: 'pipe' }) }
+  catch (e) {
+    writeFileSync(target, before, 'utf8')
+    skipped.push(f.name + ' (mutation did not compile)')
+    console.error('  SKIP - ' + f.name + ' (mutation did not compile; restored)')
+    rmSync(dest, { recursive: true, force: true })
+    return false
+  }
+  const t0 = Date.now()
+  const r = spawnSync(process.execPath, [AUDIT], {
+    cwd: REPO, encoding: 'utf8', timeout: CHILD_TIMEOUT_MS, killSignal: 'SIGKILL',
+    env: Object.assign({}, process.env, { MC_CONTRACT_ROOT: dest }),
+  })
+  const ms = Date.now() - t0
+  TIMES.push([f.name, ms])
+  const hang = !!(r.error && (r.error.code === 'ETIMEDOUT' || r.signal === 'SIGKILL'))
+  if (hang) hangs.push(f.name + '(' + Math.round(ms / 1000) + 's)')
+  const out = String(r.stdout || '') + String(r.stderr || '')
+  // this audit prints failures as `  - <label> — <detail>` (not `FAIL - ...`), so match the label itself
+  const named = out.split(/\r?\n/).filter((l) => f.expect.test(l)).map((l) => l.trim())
+  const ok = !hang && r.status === 1 && named.length > 0
+  console.log((hang ? '  HANG - ' : (ok ? '  ok - ' : '  FAIL - ')) + f.name + ' [' + ms + 'ms]' + (named.length ? ' :: ' + named[0].slice(0, 150) : ' :: no named red (exit=' + r.status + ')'))
+  rmSync(dest, { recursive: true, force: true })
+  return ok
+}
+const WITHOUT_MATH_KEYS = "objParams({ mode: { type: 'string', enum: ['manual', 'auto'] } })"
+const FAMILIES = [
+  {
+    name: 'the SINGLE SOURCE drops mathMode (derived key table)',
+    rel: 'vibe-math-v3/vibe-math-v3.js',
+    from: "'mathMode', 'mathEngines'",
+    to: "'mathEngines'",
+    expect: /set schema has the property mathMode/,
+  },
+  {
+    name: 'the FIRST (session-layer) registration reverts to a literal without the math keys',
+    rel: 'vibe-math-v3/vibe-math-v3.js',
+    from: 'objParams(paramProps()), async function',
+    to: WITHOUT_MATH_KEYS + ', async function',
+    firstOnly: true,
+    expect: /site#0 set schema has the property mathComputation/,
+  },
+  {
+    name: 'the APPLY-LAYER registration reverts to a literal without the math keys',
+    rel: 'vibe-math-v3/vibe-math-v3.js',
+    from: "objParams(paramProps()), 'vibe_math_set_params')",
+    to: WITHOUT_MATH_KEYS + ", 'vibe_math_set_params')",
+    expect: /site#1 set schema has the property mathComputation/,
+  },
+]
+let red = 0
+for (const f of FAMILIES) { const ok = runFamily(f); if (ok) red++ }
+console.log('')
+console.log('mutant families reddening the math-contract audit by name: ' + red + '/' + FAMILIES.length)
+console.log('timings: ' + TIMES.map((t) => String(t[0]).split('(')[0].trim().slice(0, 18) + '=' + t[1] + 'ms').join('  '))
+console.log('hangs=[' + hangs.join(' | ') + ']')
+console.log('skipped=[' + skipped.join(' | ') + ']')
+if (red !== FAMILIES.length || skipped.length || hangs.length) process.exit(1)
+console.log('ALL MUTANTS RED AS REQUIRED')

package/tests/audit-math-computation-parity.mjs

@@ -17,7 +17,7 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const HERE = fileURLToPath(new URL('./', import.meta.url))
 const REPO = resolve(HERE, '..')
@@ -37,6 +37,101 @@ function ok(cond, label, detail) {
 const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex')
 const read = (rel) => readFileSync(join(REPO, rel), 'utf8')
 
+// ---- extracted predicates (shared by the checks below AND by --self-probe) -----------------------
+// §7/§8 used to compute these inline; extracting them is what lets the self-probe feed the SAME
+// predicates deliberately broken strings. Keep the two users in sync by construction: both call these.
+const SUPPORTED_PLACEHOLDERS = {
+  '<script>': "split('<script>').join(",
+  '<expr>': "split('<expr>').join(",
+  '<pkgs>': "a === '<pkgs>'",
+  '<pkgs...>': "a === '<pkgs...>'",
+  '<probeCode>': "a === '<probeCode>'",
+  '<exe>': ".replace(/<exe>/g, exe)",
+  '<pkg>': ".replace(/<pkg>/g, pkg)",
+  '__PKGS__': ".replace(/__PKGS__/g, plain)",
+  '__QPKGS__': ".replace(/__QPKGS__/g, quoted)",
+  '__PKG__': ".replace(/__PKG__/g, pkg)",
+}
+const stringsOfDescriptor = (d) => [].concat(
+  Object.values(d.scriptArgv || {}).filter((x) => typeof x === 'string'),
+  Object.values(d.evalArgv || {}).filter((x) => typeof x === 'string'),
+  ((d.packageProbe && d.packageProbe.argv) || []).filter((x) => typeof x === 'string'),
+  typeof d.probeCode === 'string' ? [d.probeCode] : [],
+  (d.install ? [].concat(d.install.userArgv || [], d.install.systemArgv || [], d.install.uninstallArgv || []) : []).filter((x) => typeof x === 'string'),
+)
+/** Placeholders used by descriptors that the module does not KNOW about. Unit: placeholder occurrences. */
+function unknownPlaceholders(src, all) {
+  const out = []
+  for (const name of Object.keys(all)) {
+    for (const str of stringsOfDescriptor(all[name])) {
+      for (const m of (str.match(/<[a-z.]+>|__[A-Z]+__/g) || [])) if (!(m in SUPPORTED_PLACEHOLDERS)) out.push(name + ':' + m)
+    }
+  }
+  return out
+}
+/** Known placeholders whose implementation is missing from the module. Unit: placeholder occurrences. */
+function unimplementedPlaceholders(src, all) {
+  const out = []
+  for (const name of Object.keys(all)) {
+    for (const str of stringsOfDescriptor(all[name])) {
+      for (const m of (str.match(/<[a-z.]+>|__[A-Z]+__/g) || [])) {
+        if ((m in SUPPORTED_PLACEHOLDERS) && SUPPORTED_PLACEHOLDERS[m] && src.indexOf(SUPPORTED_PLACEHOLDERS[m]) === -1) out.push(name + ':' + m)
+      }
+    }
+  }
+  return out
+}
+/** The substitution must be STRING-level so embedded forms (matlab run('<script>')) are covered. */
+const stringLevelSubstitution = (src) => /String\(a\)\.split\('<script>'\)\.join\(/.test(src) && /String\(a\)\.split\('<expr>'\)\.join\(/.test(src)
+/** §8: the descriptor declares the policy / the module consumes it / nothing is hard-coded. */
+const cliDeclaresPolicy = (eng) => /policy:\s*\{\s*requiresMathMode:\s*'typed\+shell',\s*requiresEngineInList:\s*true\s*\}/.test(eng)
+const cliConsumesPolicy = (mod) => (mod.match(/CLI_POLICY\.requiresMathMode/g) || []).length >= 2 && (mod.match(/CLI_POLICY\.requiresEngineInList/g) || []).length >= 1
+const cliNoHardCoded = (mod) => !/mathMode !== 'typed\+shell'/.test(mod)
+/** §8: the shared refusal shape must surface the descriptor value (the OLD literal had only reason). */
+const refusalSurfacesPolicy = (n) => !!n && n.reason === 'policy' && n.requiresMathMode === 'typed+shell'
+
+// ---- `--self-probe`: the SAME predicates against deliberately broken inputs (shipped form of the
+// was-dev-only proofs `descriptor-sweep-proof.mjs` + `cli-policy-proof.mjs`). No repo mutation.
+async function selfProbe() {
+  const mod = read('vibe-math-v2/math-computation.js')
+  const eng = read('vibe-math-v2/math-engines.js')
+  const { MATH_ENGINES, MATH_P2_ENGINES } = await import(pathToFileURL(join(REPO, 'vibe-math-v2', 'math-engines.js')).href)
+  const all = Object.assign({}, MATH_ENGINES, MATH_P2_ENGINES)
+  const LIT = /<script>/
+  const matlabTemplate = ['-batch', "run('<script>')"]
+  const preFix = (tmpl, abs) => tmpl.map((a) => (a === '<script>' ? abs : a))
+  const postFix = (tmpl, abs) => tmpl.map((a) => String(a).split('<script>').join(abs))
+  const cases = [
+    ['§7 substitution is STRING-level (matlab embedding covered)', stringLevelSubstitution(mod),
+      stringLevelSubstitution(mod.replace("String(a).split('<script>').join(payload.scriptAbs)", "a === '<script>' ? payload.scriptAbs : a"))],
+    ['§7 descriptors use only KNOWN placeholders', unknownPlaceholders(mod, all).length === 0,
+      unknownPlaceholders(mod, Object.assign({}, all, { probe: { scriptArgv: { x: '<mysterySlot>' } } })).length > 0],
+    ['§7 known placeholders are IMPLEMENTED in the module', unimplementedPlaceholders(mod, all).length === 0,
+      unimplementedPlaceholders('/* no implementation */', all).length === 0],
+    ['§7 the guard predicate catches what the OLD substitution produced', postFix(matlabTemplate, 'ABS').every((a) => !LIT.test(a)),
+      preFix(matlabTemplate, 'ABS').every((a) => !LIT.test(a))],
+    ['§8 the module CONSUMES the descriptor policy', cliConsumesPolicy(mod),
+      cliConsumesPolicy(mod.replace(/CLI_POLICY\./g, 'HARDCODED.'))],
+    ['§8 no hard-coded policy comparison remains', cliNoHardCoded(mod),
+      cliNoHardCoded(mod + "\\n  if (params.mathMode !== 'typed+shell') { /* hard-coded revert */ }")],
+    ['§8 descriptor DECLARES the policy', cliDeclaresPolicy(eng),
+      cliDeclaresPolicy(eng.replace("policy: { requiresMathMode: 'typed+shell', requiresEngineInList: true }", 'policy: null'))],
+    ['§8 the shared refusal surfaces the descriptor value (OLD literal caught)',
+      refusalSurfacesPolicy({ reason: 'policy', requiresMathMode: 'typed+shell' }),
+      refusalSurfacesPolicy({ reason: 'policy' })],
+  ]
+  let bad = 0
+  for (const [name, greenNow, redWhenBroken] of cases) {
+    const good = greenNow === true && redWhenBroken === false
+    if (!good) bad++
+    console.log((good ? '  ok   ' : '  FAIL ') + name + ' :: green-now=' + greenNow + ' broken-goes-red=' + !redWhenBroken)
+  }
+  console.log('=== MATH PARITY SELF-PROBE: ' + (cases.length - bad) + '/' + cases.length + ' as required ===')
+  return bad === 0
+}
+if (process.argv.includes('--self-probe')) process.exit(await selfProbe() ? 0 : 1)
+
+
 console.log('-- math_computation parity --')
 
 // ---- 1/2. the four copies are identical, and match the canonical source ----
@@ -106,7 +201,12 @@ for (const f of MODULES) {
     : new URL('../vibe-math-v2/math-engines.js', import.meta.url).href)
   const order = E.MATH_ENGINE_ORDER
   ok(JSON.stringify(order) === JSON.stringify(['python', 'r', 'octave', 'julia', 'matlab', 'maple', 'wolfram', 'cli']), 'MATH_ENGINE_ORDER is exactly the P1 set')
-  ok(E.MATH_ENGINES.cli.defaultOn === true, 'cli is flagged defaultOn')
+  // Item-3 ruling: `defaultOn` was declared but never consumed - cli's default-on property is
+  // already pinned above through the REAL single source (MATH_PARAM_DEFAULTS.mathEngines).
+  const zombie = ['winPrefix', 'stdinArgv', 'defaultOn']
+    .filter((f) => JSON.stringify(E.MATH_ENGINES).indexOf('"' + f + '"') !== -1 || JSON.stringify(E.MATH_P2_ENGINES).indexOf('"' + f + '"') !== -1)
+  ok(zombie.length === 0, 'no zombie descriptor field is declared (winPrefix/stdinArgv/defaultOn were removed)', JSON.stringify(zombie))
+  ok(!/<cliArgv/.test(readFileSync(join(REPO, 'vibe-math-v2', 'math-engines.js'), 'utf8')), 'the decorative <cliArgv...> marker is gone from the descriptor table')
   ok(E.MATH_ENGINES.cli.policy && E.MATH_ENGINES.cli.policy.requiresMathMode === 'typed+shell' && E.MATH_ENGINES.cli.policy.requiresEngineInList === true, 'cli policy gate declared')
   ok(E.MATH_ENGINES.maple.verify === true && !!E.MATH_ENGINES.maple.verifyReason, 'Maple template is flagged VERIFY with a reason')
   for (const name of ['matlab', 'maple', 'wolfram']) {
@@ -192,7 +292,68 @@ for (const f of MODULES) {
   for (const r of reasons) ok(doc.indexOf('`' + r + '`') !== -1, 'docs/math-computation.md names next.reason ' + r)
 }
 
-console.log('')
+// ── 7. descriptor sweep: every argv placeholder dialect must be one the module IMPLEMENTS
+// Sweep finding (HIGH, fixed): substitution was exact-element (`a === '<script>'`), so matlab's embedded
+// `run('<script>')` reached the engine literally. The fix is string-level; this guard keeps the two
+// sides in sync: no descriptor may use a placeholder the module does not substitute.
+{
+  const E = await import(pathToFileURL(join(REPO, 'vibe-math-v2', 'math-engines.js')).href)
+  const modPath = join(REPO, 'vibe-math-v2', 'math-computation.js')
+  const src = existsSync(modPath) ? readFileSync(modPath, 'utf8') : ''
+  const all = Object.assign({}, E.MATH_ENGINES, E.MATH_P2_ENGINES)
+  const unknown = unknownPlaceholders(src, all)
+  const unimplemented = unimplementedPlaceholders(src, all)
+  ok(stringLevelSubstitution(src),
+    'substitution is STRING-level for <script>/<expr> (embedded forms like matlab run(\'<script>\') are covered)')
+}
+
+// ── 8. the cli policy is declared ONCE (descriptor) and consumed, never hard-coded
+// Sweep ruling: `cli.policy.{requiresMathMode,requiresEngineInList}` were declared but never consumed,
+// while the same rules were hard-coded twice in the module (so they could drift). The module now reads
+// the descriptor; this guard makes a hard-coded revert impossible to land.
+{
+  const engPath = join(REPO, 'vibe-math-v2', 'math-engines.js')
+  const modPath = join(REPO, 'vibe-math-v2', 'math-computation.js')
+  const eng = existsSync(engPath) ? readFileSync(engPath, 'utf8') : ''
+  const mod = existsSync(modPath) ? readFileSync(modPath, 'utf8') : ''
+  ok(cliDeclaresPolicy(eng),
+    'the cli descriptor DECLARES its policy (requiresMathMode + requiresEngineInList)')
+  ok(cliConsumesPolicy(mod),
+    'the module CONSUMES the descriptor policy (both refusal sites read CLI_POLICY)')
+  ok(cliNoHardCoded(mod),
+    'no hard-coded policy comparison is left in the module (the rule lives only in the descriptor)')
+}
+
+// ── 9. doc-sync: the v5 editor closed set and v2's single-source status/report helper are documented
+{
+  const v5 = existsSync(join(REPO, 'vibe-math-v5', 'vibe-math-v5.js')) ? readFileSync(join(REPO, 'vibe-math-v5', 'vibe-math-v5.js'), 'utf8') : ''
+  const fp = existsSync(join(REPO, 'docs', 'final-paper.md')) ? readFileSync(join(REPO, 'docs', 'final-paper.md'), 'utf8') : ''
+  // The closed set appears twice in v5 (the coerce call and the tool schema enum); the separator may be
+  // written with or without a space, so accept both rather than pinning one spelling.
+  ok(/\[\s*'office'\s*,\s*'academician'\s*\]/.test(v5) && /V5_INVALID_ARGUMENT/.test(v5), 'v5 validates the paper editor against the closed set and returns V5_INVALID_ARGUMENT')
+  ok(fp.indexOf('office|academician') !== -1 && fp.indexOf('V5_INVALID_ARGUMENT') !== -1, 'docs/final-paper.md documents the v5 editor closed set + its error code')
+  const v2src = existsSync(join(REPO, 'vibe-math-v2', 'vibe-math-v2.js')) ? readFileSync(join(REPO, 'vibe-math-v2', 'vibe-math-v2.js'), 'utf8') : ''
+  const v2doc = existsSync(join(REPO, 'vibe-math-v2', '实现方案.md')) ? readFileSync(join(REPO, 'vibe-math-v2', '实现方案.md'), 'utf8') : ''
+  ok((v2src.match(/verifyTasksView\(/g) || []).length >= 3, 'v2 produces status+report through ONE verifyTasksView helper')
+  ok(v2doc.indexOf('verifyTasksView') !== -1, 'the v2 design doc states the single-source status/report helper')
+}
+
+// S4/S5 (install-failure discrimination) is asserted in tests/math-computation-shared.test.mjs §33, NOT
+// here: parity reads the shipped copy unconditionally, so a mutant cannot reach what it reads (the
+// assertion would exist but could never redden). What parity keeps is the canonical<->copy byte identity,
+// which makes a canonical-only change impossible to ship unnoticed - a stronger defence than a text grep.
+// ── 11. S6: the version policy has ONE wording (constant + helper), not one per path.
+{
+  const mc = readFileSync(join(REPO, 'vibe-math-v2', 'math-computation.js'), 'utf8')
+  ok((mc.match(/version-constraints-are-existence-only: /g) || []).length === 1, '★ S6: the policy wording appears exactly ONCE (in MATH_VERSION_POLICY)')
+  ok(/function mathVersionPolicy\(/.test(mc), 'S6: the shared helper mathVersionPolicy() exists')
+  ok(mc.indexOf('版本求解交给包管理器（本工具只检查是否已安装') === -1, '★ S6: the old divergent install-plan wording is gone')
+  ok(/versionPolicy: mathVersionPolicy\(args\.packages/.test(mc), 'S6: the install plan builds its wording through the helper')
+  ok((mc.match(/只检查是否存在；版本求解交给包管理器/g) || []).length === 1, '★ S6: the policy clause literal appears exactly ONCE (MATH_VERSION_POLICY_CLAUSE)')
+  ok(/const MATH_VERSION_POLICY = .*MATH_VERSION_POLICY_CLAUSE/.test(mc), 'S6: the long policy sentence is DERIVED from the clause')
+  ok(/MATH_MISSING_PACKAGES[\s\S]{0,120}MATH_VERSION_POLICY_CLAUSE/.test(mc), 'S6: the missing-package detail derives the clause')
+}
+
 console.log('=== MATH COMPUTATION PARITY: ' + passed + ' passed, ' + failed + ' failed ===')
 if (failures.length) for (const f of failures) console.error('  - ' + f)
 process.exit(failed === 0 ? 0 : 1)

package/tests/audit-math-computation-sensitivity.mjs

@@ -34,8 +34,10 @@ const PROBES = [
   {
     name: 'cli-policy-ignored',
     file: 'math-computation.js',
-    from: "if (p.mathMode !== 'typed+shell') return bad('engine=cli is disabled while mathMode=' + p.mathMode, 'MATH_REFUSED', next('reason', { reason: 'policy' }))",
-    to: 'if (false) return bad(\'noop\')',
+    // Re-anchored after the single-source ruling: the policy now comes from the DESCRIPTOR (CLI_POLICY),
+    // so the probe disables the descriptor-driven guard. Ignoring it must turn the shared suite RED.
+    from: 'if (CLI_POLICY.requiresMathMode && p.mathMode !== CLI_POLICY.requiresMathMode)',
+    to: 'if (false && CLI_POLICY.requiresMathMode)',
     expect: 'cli refused while mathMode=typed',
   },
   {
@@ -77,8 +79,8 @@ const PROBES = [
   {
     name: 'script-fields-dropped-from-return',
     file: 'math-computation.js',
-    from: '    scriptPath: scriptRel, scriptHash: scriptHash,\n    attempt: attempt, attemptDir: dir, baseRunDir: baseDir,\n    scriptChanged: scriptChanged, scriptChangedDuringRun: scriptChangedDuringRun,\n    sourceFile: fileRel || null,\n    previousReceipt: receipt.previousReceipt,\n    cliScriptAppended: !!(receipt.cli && receipt.cli.scriptAppended),\n    packages: pk.found,',
-    to: '    packages: pk.found,',
+    from: '    engineInfo: receipt.engine,\n    argv: assembled.argv.slice(),\n    scriptPath: scriptRel, scriptHash: scriptHash,',
+    to: '    engineInfo: receipt.engine,\n    argv: assembled.argv.slice(),',
     expect: 'scriptPath + scriptHash are in the return value AND the receipt',
   },
   {

package/tests/audit-package-membership.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * PACKAGE MEMBERSHIP - every guard/harness meant to ship is listed in package.json#files.
+ *
+ * DEFECT CLASS: "shipped guard whose proving harness is not in the tarball" (the ship rule: a guard
+ * ships together with its harness). A package reader could not reproduce the proof.
+ *
+ * The intended shipped set is stated EXPLICITLY, not globbed blindly: every tests/*.mutants.mjs on
+ * disk must be listed, and every tests/*.mjs cited by the guard index must be listed unless it is in
+ * EXCLUDED (documented, deliberate exclusions - e.g. audit-market-metadata.test.mjs asserts its own
+ * absence because it checks repo-only image artifacts).
+ *
+ * Run: node tests/audit-package-membership.mjs
+ * Env: PACKAGE_JSON=<path>  (used by the mutants harness to point at a mutated copy)
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const PKG = process.env.PACKAGE_JSON || join(REPO, 'package.json')
+const EXCLUDED = new Set(['tests/audit-market-metadata.test.mjs', 'tests/audit-diagram-assets.test.mjs'])
+let passed = 0, failed = 0
+const failures = []
+const ok = (cond, label, detail) => { if (cond) { passed++ } else { failed++; failures.push(label + (detail ? ' — ' + detail : '')) } }
+const pkg = JSON.parse(readFileSync(PKG, 'utf8'))
+const listed = new Set(pkg.files)
+const disk = readdirSync(join(REPO, 'tests')).filter((f) => f.endsWith('.mjs'))
+const mutants = disk.filter((f) => /\.mutants\.mjs$/.test(f)).map((f) => 'tests/' + f).sort()
+const unlistedMutants = mutants.filter((f) => !listed.has(f) && !EXCLUDED.has(f))
+ok(mutants.length > 0, 'there is at least one proving harness on disk')
+ok(unlistedMutants.length === 0, 'every tests/*.mutants.mjs on disk is listed in package.json#files', JSON.stringify(unlistedMutants))
+// guard-index citations: tests/*.mjs paths mentioned in the checklist
+const idx = readFileSync(join(REPO, 'docs', 'AUDIT-CHECKLIST.md'), 'utf8')
+const cited = [...new Set((idx.match(/tests\/[A-Za-z0-9._-]+\.mjs/g) || []))]
+const unlistedCited = cited.filter((f) => !listed.has(f) && !EXCLUDED.has(f))
+ok(cited.length > 0, 'the guard index cites at least one test file')
+ok(unlistedCited.length === 0, 'every guard-index-cited test file is listed (or explicitly excluded)', JSON.stringify(unlistedCited))
+ok(listed.has('tests/audit-package-membership.mjs'), 'this audit itself ships')
+ok(!listed.has('tests/audit-market-metadata.test.mjs'), 'the self-excluded repo-only guard is NOT listed (its own assertion)')
+const missingPaths = [...listed].filter((f) => !existsSync(join(REPO, f)))
+// docs sibling rule: a doc cited by a SHIPPED file must ship too (docs/** was previously uncovered).
+const citers = ['README.md', 'README.en.md', 'docs/AUDIT-CHECKLIST.md', 'docs/COMPAT-AUDIT-ROUND2.md']
+const docRefs = new Set()
+for (const c of citers) {
+  const cp = join(REPO, c)
+  if (!existsSync(cp)) continue
+  for (const m of readFileSync(cp, 'utf8').matchAll(/docs\/[A-Za-z0-9._-]+\.md/g)) docRefs.add(m[0])
+}
+ok(docRefs.size > 0, 'shipped files cite at least one docs/*.md')
+const unlistedDocs = [...docRefs].filter((f) => !listed.has(f))
+ok(unlistedDocs.length === 0, 'every docs/*.md cited by a shipped file is listed in package.json#files', JSON.stringify(unlistedDocs))
+ok(missingPaths.length === 0, 'every listed path exists', JSON.stringify(missingPaths))
+console.log('')
+console.log('=== PACKAGE MEMBERSHIP: ' + passed + ' passed, ' + failed + ' failed ===')
+for (const f of failures) console.error('  - ' + f)
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-package-membership.mutants.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Mutant harness for the package-membership audit: drop one listed entry from a COPY of package.json
+ * and require the audit to go named-red. Run: node tests/audit-package-membership.mutants.mjs
+ */
+import { readFileSync, writeFileSync, mkdtempSync, 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, '..')
+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 base = spawnSync(process.execPath, [join(HERE, 'audit-package-membership.mjs')], { cwd: REPO, encoding: 'utf8' })
+ok(base.status === 0, 'baseline: the membership audit is green', String(base.stdout || '').trim().split('\n').slice(-1)[0])
+const dir = mkdtempSync(join(tmpdir(), 'pkgmem-'))
+const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'))
+const victim = 'tests/audit-package-membership.mjs'
+pkg.files = pkg.files.filter((f) => f !== victim)
+writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2))
+const mut = spawnSync(process.execPath, [join(HERE, 'audit-package-membership.mjs')], { cwd: REPO, encoding: 'utf8', env: Object.assign({}, process.env, { PACKAGE_JSON: join(dir, 'package.json') }) })
+const out = String(mut.stdout || '') + String(mut.stderr || '')
+ok(mut.status !== 0 && /this audit itself ships/.test(out), '★ removing a listed entry makes the membership audit RED (named assertion)', 'exit=' + mut.status)
+rmSync(dir, { recursive: true, force: true })
+console.log('')
+console.log('=== PACKAGE MEMBERSHIP MUTANTS: ' + passed + ' passed, ' + failed + ' failed ===')
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-participant-set-parity.mjs

@@ -0,0 +1,160 @@
+// ============================================================================================
+// CROSS-PRESET PARTICIPANT-SET PARITY (P4 / item 6.3)
+//
+// Expectation source: `_oneoff/review/participant-set-map.md` (table first, then this guard).
+//
+// The four presets deliberately use DIFFERENT names for the same concept - "which set of members is
+// this decision counting, and as of which roster state":
+//   · v2 `voteCount(t, round)`  -> { participants, expected, round, allParticipantsReported }
+//   · v3 `voteCount(t, round)`  -> { participants, expected, round }   (NO allParticipantsReported:
+//                                  its readers compose their own predicate - a deliberate difference)
+//   · v4 `activeRosterSnapshot()` -> `frozen: { version, participants, kind }` (atomic; deprecated
+//                                  alias `frozenParticipants`)
+//   · v5 `rosterSnapshot()` -> `quorumView(): { m, mode, voters, voterCount, started, phase, rosterVersion }`
+//
+// So a behavioural "the numbers agree" test would have to unify those contracts, which is exactly what
+// must NOT happen (v2's P2 regression came from collapsing two predicates). This guard is therefore
+// STATIC: it pins, per preset, (a) that the participant set has exactly ONE producer, (b) that the set
+// and its roster version/expectation are surfaced TOGETHER, and (c) the deliberate v2/v3 difference.
+//
+// Usage: node tests/audit-participant-set-parity.mjs
+// ============================================================================================
+import { readFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const REPO = resolve(fileURLToPath(new URL('..', import.meta.url)))
+const read = (rel) => existsSync(join(REPO, rel)) ? readFileSync(join(REPO, rel), 'utf8') : ''
+
+let passed = 0, failed = 0
+const failures = []
+function ok(cond, label, detail) {
+  if (cond) { passed++; console.log('  ok   ' + label); return true }
+  failed++; failures.push(label + (detail ? ' — ' + detail : '')); console.log('  FAIL ' + label + (detail ? ' — ' + detail : ''))
+  return false
+}
+const occurrences = (s, re) => (s.match(re) || []).length
+/** The body of a named function, by brace counting from its `function <name>(` occurrence. */
+function body(src, name) {
+  const i = src.indexOf('function ' + name + '(')
+  if (i === -1) return ''
+  let depth = 0, started = false
+  for (let j = i; j < src.length; j++) {
+    if (src[j] === '{') { depth++; started = true }
+    else if (src[j] === '}') { depth--; if (started && depth === 0) return src.slice(i, j + 1) }
+  }
+  return src.slice(i)
+}
+
+// ---- `--self-probe`: the SAME predicates against deliberately broken source strings -----------
+// Shipped form of the load-bearing proof (was `_oneoff/auditR2/participant-set-proof.mjs`): six cases,
+// each GREEN on the real source and RED on the mutated string. No repo mutation, no fixtures.
+// The predicates mirror the numbered assertions below — update them together.
+function selfProbe() {
+  const v2s = read('vibe-math-v2/vibe-math-v2.js')
+  const v3s = read('vibe-math-v3/vibe-math-v3.js')
+  const v4s = read('vibe-math-v4/vibe-math-v4.js')
+  const v5s = read('vibe-math-v5/vibe-math-v5.js')
+  const ATOMIC = /frozen:\s*\(function\(sn\)\{\s*return \{version: sn\?sn\.rosterVersion:null, participants: sn\?sn\.rosterSnapshot:null, kind:/
+  const cases = [
+    ['v2 produces allParticipantsReported',
+      /allParticipantsReported: participants\.length > 0 && thisRoundIds\.length === participants\.length/.test(v2s),
+      /allParticipantsReported: participants\.length > 0 && thisRoundIds\.length === participants\.length/.test(v2s.replace(/allParticipantsReported:/g, 'renamedField:'))],
+    ['v3 deliberately LACKS the field', !/allParticipantsReported/.test(v3s),
+      !/allParticipantsReported/.test(v3s.replace('function voteCount(t, round) {', 'function voteCount(t, round) { const allParticipantsReported = 1;'))],
+    ['v4 frozen is atomic', ATOMIC.test(v4s),
+      ATOMIC.test(v4s.replace(/frozen:\s*\(function\(sn\)\{\s*return \{version: sn\?sn\.rosterVersion:null, participants: sn\?sn\.rosterSnapshot:null, kind:/, 'frozen: {version: rosterVersion, participants: null, kind: null}, x: (function(sn){ return {version: sn?sn.rosterVersion:null, participants: sn?sn.rosterSnapshot:null, kind:'))],
+    ['v4 removal prunes both frozen sets', occurrences(v4s.slice(v4s.indexOf('function removeMember')), /rosterSnapshot\.filter\(x=>x!==id\)/g) >= 2,
+      occurrences(v4s.slice(v4s.indexOf('function removeMember')).replace(/rosterSnapshot\.filter\(x=>x!==id\)/g, 'noop()'), /rosterSnapshot\.filter\(x=>x!==id\)/g) >= 2],
+    ['v5 quorumView surfaces rosterVersion', /\brosterVersion:/.test(v5s.slice(v5s.indexOf('function quorumView'), v5s.indexOf('function quorumView') + 900)),
+      /\brosterVersion:/.test(v5s.slice(v5s.indexOf('function quorumView'), v5s.indexOf('function quorumView') + 900).replace(/rosterVersion:/g, 'ver:'))],
+    ['exactly ONE v2 producer', occurrences(v2s, /function voteCount\(t, round\)/g) === 1,
+      occurrences(v2s + '\n  function voteCount(t, round) { return null }\n', /function voteCount\(t, round\)/g) === 1],
+  ]
+  let bad = 0
+  for (const [name, greenNow, redWhenBroken] of cases) {
+    const good = greenNow === true && redWhenBroken === false
+    if (!good) bad++
+    console.log((good ? '  ok   ' : '  FAIL ') + name + ' :: green-now=' + greenNow + ' broken-goes-red=' + !redWhenBroken)
+  }
+  console.log('=== PARTICIPANT-SET SELF-PROBE: ' + (cases.length - bad) + '/' + cases.length + ' as required ===')
+  return bad === 0
+}
+if (process.argv.includes('--self-probe')) process.exit(selfProbe() ? 0 : 1)
+const v2 = read('vibe-math-v2/vibe-math-v2.js')
+const v3 = read('vibe-math-v3/vibe-math-v3.js')
+const v4 = read('vibe-math-v4/vibe-math-v4.js')
+const v5 = read('vibe-math-v5/vibe-math-v5.js')
+
+console.log('-- participant-set parity across the four presets --')
+
+// ---- 1. v2: one producer, set + expectation + the field, and it is CONSUMED ----
+{
+  const b = body(v2, 'voteCount')
+  ok(occurrences(v2, /function voteCount\(t, round\)/g) === 1, 'v2: exactly ONE participant-set producer (voteCount)')
+  ok(/participants: participants/.test(b) && /expected: expected/.test(b) && /round: r/.test(b),
+    'v2: voteCount returns the SET together with its expectation + round')
+  ok(/allParticipantsReported: participants\.length > 0 && thisRoundIds\.length === participants\.length/.test(b),
+    'v2: voteCount produces allParticipantsReported (its single predicate)')
+  ok(occurrences(v2, /voteCount\(t, (?:t|meta)\.round\)\.allParticipantsReported/g) >= 2,
+    'v2: the field is CONSUMED (both readers go through voteCount, not a re-derivation)')
+  const expectedLine = /const expected = Math\.max\(MIN_REVIEWERS, Number\(tt\.expectedCount\) \|\| 0\)/.test(b)
+  ok(expectedLine, 'v2: expected comes from the CREATION-TIME snapshot with the MIN_REVIEWERS floor (deliberately kept)')
+}
+
+// ---- 2. v3: one producer, NO allParticipantsReported (the documented difference), snapshot-only quorum ----
+{
+  const b = body(v3, 'voteCount')
+  ok(occurrences(v3, /function voteCount\(t, round\)/g) === 1, 'v3: exactly ONE participant-set producer (voteCount)')
+  ok(/participants: participants/.test(b) && /expected: expected/.test(b), 'v3: voteCount returns the SET together with its expectation')
+  ok(!/allParticipantsReported/.test(v3), 'v3: deliberately has NO allParticipantsReported (readers compose their own predicate - do not "unify" it away)')
+  const mv = body(v3, 'minVotes')
+  ok(mv.length > 0 && !/params\.verifierCount/.test(mv), 'v3: minVotes reads the SNAPSHOT only (live params.verifierCount must not leak back in)')
+}
+
+// ---- 3. v4: one producer, ATOMIC set+version, deprecated alias, removal prunes ----
+{
+  ok(occurrences(v4, /function activeRosterSnapshot\(/g) === 1, 'v4: exactly ONE participant-set producer (activeRosterSnapshot)')
+  ok(/frozen:\s*\(function\(sn\)\{\s*return \{version: sn\?sn\.rosterVersion:null, participants: sn\?sn\.rosterSnapshot:null, kind:/.test(v4),
+    'v4: `frozen` is the ATOMIC triple {version, participants, kind}')
+  ok(/frozenParticipants:\s*\(activeRosterSnapshot\(\)\|\|\{\}\)\.rosterSnapshot\|\|null/.test(v4) && /deprecated/.test(v4),
+    'v4: `frozenParticipants` stays only as a deprecated alias of frozen.participants')
+  const rm = body(v4, 'removeMember')
+  ok(occurrences(rm, /rosterSnapshot=(\w+)\.rosterSnapshot\.filter\(x=>x!==id\)|rosterSnapshot\.filter\(x=>x!==id\)/g) >= 2,
+    'v4: removal prunes BOTH frozen sets (that is what keeps "removal releases the wait" true)')
+  ok(/function bumpRoster\(/.test(v4) && /rosterVersion\+\+/.test(body(v4, 'bumpRoster')), 'v4: exactly one roster-version bump helper')
+}
+
+// ---- 4. v5: one producer, quorum view surfaces the set + version together ----
+{
+  ok(occurrences(v5, /function rosterSnapshot\(\)/g) === 1, 'v5: exactly ONE participant-set producer (rosterSnapshot)')
+  const qv = body(v5, 'quorumView')
+  const keys = ['m', 'mode', 'voters', 'voterCount', 'started', 'phase', 'rosterVersion']
+  const missing = keys.filter((k) => !new RegExp('\\b' + k + ':').test(qv))
+  ok(qv.length > 0 && missing.length === 0, 'v5: quorumView surfaces the set (voters/voterCount) TOGETHER with m + rosterVersion', 'missing: ' + JSON.stringify(missing))
+  ok(/return \{[\s\S]*?version: rosterVersion\(\)[\s\S]*?voters:/.test(body(v5, 'rosterSnapshot')),
+    'v5: the snapshot captures version + voters in one object (no re-derivation between them)')
+}
+
+// ---- 5. the two cross-preset invariants, stated once (so a future preset cannot skip them) ----
+{
+  const producers = [
+    ['v2', occurrences(v2, /function voteCount\(t, round\)/g)],
+    ['v3', occurrences(v3, /function voteCount\(t, round\)/g)],
+    ['v4', occurrences(v4, /function activeRosterSnapshot\(/g)],
+    ['v5', occurrences(v5, /function rosterSnapshot\(\)/g)],
+  ]
+  ok(producers.every(([, n]) => n === 1), 'every preset has EXACTLY ONE participant-set producer ("produced only once")', JSON.stringify(producers))
+  const setAndVersion = [
+    ['v2', /participants: participants/.test(body(v2, 'voteCount')) && /expected: expected/.test(body(v2, 'voteCount'))],
+    ['v3', /participants: participants/.test(body(v3, 'voteCount')) && /expected: expected/.test(body(v3, 'voteCount'))],
+    ['v4', /participants: sn\?sn\.rosterSnapshot:null/.test(v4) && /version: sn\?sn\.rosterVersion:null/.test(v4)],
+    ['v5', /voterCount: snap\.voterCount/.test(body(v5, 'quorumView')) && /rosterVersion: snap\.version/.test(body(v5, 'quorumView'))],
+  ]
+  ok(setAndVersion.every(([, b]) => b), 'every preset surfaces the set AND its roster version/expectation together', JSON.stringify(setAndVersion.filter(([, b]) => !b).map(([n]) => n)))
+}
+
+console.log('')
+console.log('=== PARTICIPANT SET PARITY: ' + passed + ' passed, ' + failed + ' failed ===')
+if (failures.length) for (const f of failures) console.error('  - ' + f)
+process.exit(failed === 0 ? 0 : 1)