dsh-vibe-math 2.7.2 → 2.8.0

package/tests/audit-readme-bilingual.test.mjs

@@ -0,0 +1,152 @@
+// ============================================================================================
+// BILINGUAL README — the Chinese README is the default; README.en.md is a full translation of it.
+// Two documents that are supposed to say the same thing rot apart silently, so this suite pins the
+// parts that must stay identical no matter how either side is edited:
+//
+//   · a switcher line near the top of each file linking to the other;
+//   · identical heading STRUCTURE (same ordered sequence of heading levels, ignoring fenced code —
+//     a `#` shell comment inside a code fence is not a heading);
+//   · identical image lists, identical local link targets, identical table-row and code-fence counts
+//     (a translation preserves rows 1:1, so a mismatch means content was dropped or merged);
+//   · the English file must actually be English outside code (CJK characters are only allowed in
+//     fenced/inline code, where the rules keep user-facing example strings in the original language);
+//   · both files ship in `package.json` `files`;
+//   · the Chinese README is still the default `README.md` (npm and GitHub render that one).
+//
+// Usage: node tests/audit-readme-bilingual.test.mjs
+// ============================================================================================
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, resolve } from 'node:path'
+
+const HERE = fileURLToPath(new URL('./', import.meta.url))
+const REPO = resolve(HERE, '..')
+const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), '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.error('  FAIL ' + label + (detail ? ' — ' + detail : ''))
+  return false
+}
+
+const ZH = 'README.md'
+const EN = 'README.en.md'
+if (!ok(existsSync(join(REPO, ZH)) && existsSync(join(REPO, EN)), 'both README.md and README.en.md exist')) {
+  console.log('\n=== BILINGUAL README: ' + passed + ' passed, ' + failed + ' failed ===')
+  process.exit(1)
+}
+const zh = readFileSync(join(REPO, ZH), 'utf8')
+const en = readFileSync(join(REPO, EN), 'utf8')
+
+// ---- 1. switcher ------------------------------------------------------------
+{
+  const head = (t) => t.split(/\r?\n/).slice(0, 12).join('\n')
+  ok(/\[English\]\(README\.en\.md\)/.test(head(zh)), 'the Chinese README links to the English one near the top')
+  ok(/\[中文\]\(README\.md\)/.test(head(en)) || /\[简体中文\]\(README\.md\)/.test(head(en)),
+    'the English README links back to the Chinese one near the top')
+  ok(zh.trimStart().startsWith('# ') && en.trimStart().startsWith('# '), 'both files start with an H1 title')
+}
+
+// ---- 2. strip code before structure comparison ------------------------------
+/** Markdown with fenced blocks and inline code replaced by placeholders (so their contents — which
+ *  are allowed to differ in language — cannot influence counting or CJK checks). */
+function stripCode(t) {
+  return t
+    .replace(/```[\s\S]*?```/g, '\n```CODE```\n')
+    .replace(/`[^`\n]*`/g, '`CODE`')
+}
+const zhPlain = stripCode(zh)
+const enPlain = stripCode(en)
+
+// ---- 3. structure -----------------------------------------------------------
+const headingLevels = (t) => [...t.matchAll(/^(#{1,6})\s+/gm)].map((m) => m[1].length)
+const zhH = headingLevels(zhPlain), enH = headingLevels(enPlain)
+ok(zhH.length === enH.length && zhH.every((l, i) => l === enH[i]),
+  `the heading structure matches (${zhH.length} headings, levels in the same order)`,
+  `zh=[${zhH.join(',')}] en=[${enH.join(',')}]`)
+
+const tableRows = (t) => t.split('\n').filter((l) => /^\s*\|/.test(l)).length
+ok(tableRows(zhPlain) === tableRows(enPlain), 'the table-row count matches (translations preserve rows 1:1)',
+  `zh=${tableRows(zhPlain)} en=${tableRows(enPlain)}`)
+
+const fences = (t) => (t.match(/^```/gm) || []).length
+ok(fences(zh) === fences(en), 'the code-fence count matches', `zh=${fences(zh)} en=${fences(en)}`)
+
+// ---- 4. assets and links ----------------------------------------------------
+const images = (t) => [...t.matchAll(/!\[[^\]]*\]\(([^)\s]+)\)/g)].map((m) => m[1])
+const zhImg = images(zh), enImg = images(en)
+// The four architecture diagrams deliberately differ by language: the English README points at the
+// `-en` asset of the same diagram, every other image must be the very same file.
+const enVariant = (p) => p.replace(/^(示例图\/框架图-v[0-9]+)\.(png|svg)$/, '$1-en.svg')
+ok(zhImg.length > 0 && zhImg.length === enImg.length, 'both READMEs show the same number of images',
+  `zh=[${zhImg.join(', ')}] en=[${enImg.join(', ')}]`)
+const imgMismatch = zhImg.filter((p, i) => enImg[i] !== p && enImg[i] !== enVariant(p))
+ok(imgMismatch.length === 0,
+  'every English image is the same asset as the Chinese one, or its -en variant, in the same order',
+  `mismatch=[${imgMismatch.join(', ')}] en=[${enImg.join(', ')}]`)
+const enDiagrams = enImg.filter((p) => /示例图\/框架图-v[0-9]+-en\.svg$/.test(p))
+ok(enDiagrams.length === 4, 'the English README references all four English architecture diagrams',
+  `en=[${enImg.join(', ')}]`)
+
+// Internal anchors must resolve inside their OWN file: translating a heading renames its slug, so
+// an anchor copied from the Chinese README breaks. (GitHub maps EVERY whitespace to a hyphen and
+// does not collapse runs — a slugger that collapses them reports valid anchors as broken.)
+const slug = (heading) => heading.replace(/^#{1,6}\s+/, '').trim().toLowerCase()
+  .replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/\s/g, '-')
+const headingsWithSlugs = (file) => {
+  const text = readFileSync(join(REPO, file), 'utf8')
+  const inFence = []
+  let fence = false
+  for (const l of text.split('\n')) { if (/^```/.test(l)) { fence = !fence; inFence.push(false); continue } inFence.push(fence) }
+  return { text, slugs: text.split('\n').filter((l, i) => !inFence[i] && /^#{1,6}\s+/.test(l)).map(slug) }
+}
+for (const file of [ZH, EN]) {
+  const { text, slugs } = headingsWithSlugs(file)
+  const anchors = [...new Set([...text.matchAll(/\]\(#([^)]+)\)/g)].map((m) => m[1]))]
+  const broken = anchors.filter((a) => !slugs.includes(a))
+  ok(broken.length === 0, `${file}: every internal anchor matches one of its own headings (${anchors.length} anchors)`,
+    'broken: #' + broken.join(', #'))
+}
+
+const localLinks = (t) => [...new Set([...t.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)].map((m) => m[1]))]
+  .filter((p) => !/^[a-z][a-z0-9+.-]*:/i.test(p) && !p.startsWith('#'))
+  .filter((p) => p !== 'README.md' && p !== 'README.en.md') // the switcher is intentionally asymmetric
+  .sort()
+const zhLinks = localLinks(zh), enLinks = localLinks(en)
+// The four architecture diagrams are the single documented exception: the English README points at
+// the `-en` asset of the same diagram. Normalizing just that difference keeps the guard strict about
+// every other local target (a genuinely missing or extra link still fails).
+const diagramKey = (p) => {
+  const m = /^示例图\/框架图-(v[0-9]+)(?:-en)?\.(?:png|svg)$/.exec(p)
+  return m ? '示例图/框架图-' + m[1] + '.<diagram>' : p
+}
+const zhKeys = zhLinks.map(diagramKey).sort(), enKeys = enLinks.map(diagramKey).sort()
+ok(zhKeys.join('|') === enKeys.join('|'),
+  'both READMEs link to the same local targets, up to the four language-specific diagrams',
+  'only in zh: ' + zhLinks.filter((p) => !enKeys.includes(diagramKey(p))).join(', ')
+  + ' | only in en: ' + enLinks.filter((p) => !zhKeys.includes(diagramKey(p))).join(', '))
+
+// ---- 5. the English file is actually English outside code --------------------
+{
+  // Link and image TARGETS legitimately stay Chinese (real file and directory names), as do the real
+  // JSON keys, the literal session-rebuild marker and the switcher label. What is left is that small
+  // set of literals — a real untranslated paragraph would be in the hundreds.
+  const withoutTargets = enPlain.replace(/\]\([^)\s]+\)/g, '](TARGET)').replace(/!\[[^\]]*\](\([^)\s]+\))/g, '![img]($1)')
+  const cjk = (withoutTargets.match(/[\u3400-\u9fff\uf900-\ufaff]/g) || []).length
+  ok(cjk <= 150, `no untranslated prose outside code and link targets (${cjk} CJK characters, budget 150)`,
+    'a count in the hundreds means a section was left in Chinese')
+}
+
+// ---- 6. packaging + default -------------------------------------------------
+ok((pkg.files || []).includes(ZH) && (pkg.files || []).includes(EN), 'both READMEs are listed in package.json files',
+  JSON.stringify((pkg.files || []).filter((f) => /^README/.test(f))))
+ok(existsSync(join(REPO, 'README.zh.md')) === false,
+  'the Chinese README is still the default README.md (no README.zh.md duplicate to maintain)')
+
+console.log('')
+console.log('=== BILINGUAL README: ' + passed + ' passed, ' + failed + ' failed ===')
+if (failed) { for (const f of failures) console.error('  - ' + f); process.exit(1) }
+console.log('ALL GREEN')

package/tests/audit-readme-counts.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * README/COUNT CONSISTENCY — the numbers quoted in shipped docs are DERIVED, not typed, and each is
+ * labelled as a JOB count or a FILE count.
+ *
+ * DEFECT CLASS: "documented count drifts from the tree" (D1). README quoted `TOTAL 57` (39 suites /
+ * 18 probes, "18 items ship") while the runner produced 65, then 85/86, and docs/test-timing.md and
+ * docs/AUDIT-CHECKLIST.md disagreed with each other. Authority: `node tests/run-tests.mjs --counts`
+ * (the gate's own JOB list — base jobs + VARIANTS jobs) plus `package.json#files` (shipped FILE counts).
+ * Shapes come from tests/helpers/doc-counts-format.mjs, the same module the writer
+ * (scripts/update-doc-counts.mjs) and the mutant harness use, so the three cannot disagree.
+ *
+ * Run: node tests/audit-readme-counts.mjs
+ * Env (mutant harness): COUNTS_README / COUNTS_README_EN / COUNTS_TIMING / COUNTS_CHECKLIST / COUNTS_FIELDS /
+ * COUNTS_PAPER / COUNTS_MATH (absolute or repo-relative). The last three serve the F-C live-doc sweep.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { claims } from './helpers/doc-counts-format.mjs'
+
+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 derivedRaw = spawnSync(process.execPath, [join(HERE, 'run-tests.mjs'), '--counts'], { cwd: REPO, encoding: 'utf8' })
+let derived = null
+try { derived = JSON.parse(String(derivedRaw.stdout || '').trim()) } catch (e) { /* reported below */ }
+ok(!!derived && derived.total > 0 && derived.suites > 0,
+  'the runner --counts mode produces the derived JOB totals (suites/probes/total)', String(derivedRaw.stdout || '').slice(0, 70))
+
+const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'))
+const shippedFiles = pkg.files.filter((f) => f.startsWith('tests/') && f.endsWith('.mjs'))
+const shipped = { total: shippedFiles.length, suites: shippedFiles.filter((f) => f.endsWith('.test.mjs')).length }
+shipped.probes = shipped.total - shipped.suites
+ok(shipped.total > 0 && shipped.suites > 0, 'package.json#files yields the shipped FILE split',
+  JSON.stringify({ shipped: shipped.total, suites: shipped.suites, probes: shipped.probes }))
+
+const read = (envName, rel) => {
+  const v = process.env[envName]
+  return readFileSync(v ? (isAbsolute(v) ? v : join(REPO, v)) : join(REPO, rel), 'utf8')
+}
+const zh = read('COUNTS_README', 'README.md')
+const en = read('COUNTS_README_EN', 'README.en.md')
+const tt = read('COUNTS_TIMING', 'docs/test-timing.md')
+const ck = read('COUNTS_CHECKLIST', 'docs/AUDIT-CHECKLIST.md')
+
+if (derived) {
+  const c = claims(derived, shipped)
+  const has = (doc, label, needle) => ok(doc.indexOf(needle) !== -1, label, 'looked for ' + needle)
+  has(zh, '★ README.md carries the canonical JOB-count bullet (derived totals + shipped FILE count)', c.zhBullet)
+  has(en, '★ README.en.md carries the canonical JOB-count bullet', c.enBullet)
+  has(tt, '★ docs/test-timing.md carries the canonical runner row (derived JOB counts + output shape)', c.ttRow)
+  has(ck, '★ docs/AUDIT-CHECKLIST.md quotes the derived JOB counts', c.ckClaim)
+  has(ck, '★ docs/AUDIT-CHECKLIST.md quotes the derived shipped FILE counts (published subset)', c.ckShipped)
+  has(ck, '★ docs/AUDIT-CHECKLIST.md D1 row carries the derived counts', c.d1Row)
+  ok(!/TOTAL 57/.test(zh), 'the stale README claim (TOTAL 57) is gone')
+  ok(!/TOTAL 65  PASS 65/.test(tt), 'the old test-timing baseline row (TOTAL 65 PASS 65) is gone')
+  ok(!/\*\*65 项\*\* = 44 套件 \+ 21/.test(tt + ck), 'no bolded stale 65-item claim remains (prose about the migration is fine)')
+
+  // ── F-C: EVERY `TOTAL <n>` in a LIVE doc equals the derived job count ────────────────────────────
+  // Published release notes under `docs/release-notes/**` are FROZEN history: they record what the gate
+  // read at their own release (`TOTAL 65` in 2.7.0/2.7.1), so they are excluded BY NAME — and the
+  // exclusion is asserted non-empty and reported, so the sweep cannot silently skip everything.
+  const FROZEN_EXCLUDED = ['docs/release-notes/RELEASE-NOTES-2.7.0.md', 'docs/release-notes/RELEASE-NOTES-2.7.0.en.md', 'docs/release-notes/RELEASE-NOTES-2.7.1.md', 'docs/release-notes/RELEASE-NOTES-2.7.1.en.md', 'docs/release-notes/RELEASE-NOTES-2.7.2.md']
+  const LIVE_DOCS = [
+    ['COUNTS_README', 'README.md'], ['COUNTS_README_EN', 'README.en.md'], ['COUNTS_TIMING', 'docs/test-timing.md'],
+    ['COUNTS_CHECKLIST', 'docs/AUDIT-CHECKLIST.md'],
+    ['COUNTS_FIELDS', 'docs/status-report-fields.md'], ['COUNTS_PAPER', 'docs/final-paper.md'], ['COUNTS_MATH', 'docs/math-computation.md'],
+  ]
+  let occurrences = 0, scanned = 0
+  for (const [env, rel] of LIVE_DOCS) {
+    let text = ''
+    try { text = read(env, rel) } catch (e) { continue }
+    scanned++
+    for (const m of text.matchAll(/TOTAL\s+(\d+)/g)) {
+      occurrences++
+      ok(Number(m[1]) === derived.total, '★ ' + rel + ': every TOTAL <n> equals the derived job count (' + m[1] + ' vs ' + derived.total + ')',
+        'occurrence: ' + m[0])
+    }
+  }
+  console.log('  live-docs scanned=' + scanned + ' TOTAL-occurrences=' + occurrences + ' frozen-excluded=' + FROZEN_EXCLUDED.length)
+  ok(scanned > 0 && occurrences > 0, '★ the F-C sweep is non-vacuous (it scanned live docs and found TOTAL occurrences)',
+    'scanned=' + scanned + ' occurrences=' + occurrences)
+  ok(FROZEN_EXCLUDED.length > 0, '★ the frozen release notes are excluded BY NAME, not by a pattern that could swallow the sweep',
+    JSON.stringify(FROZEN_EXCLUDED.length))
+}
+
+console.log('')
+console.log('=== README COUNTS: ' + passed + ' passed, ' + failed + ' failed ===')
+for (const f of failures) console.error('  - ' + f)
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-readme-counts.mutants.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Mutant harness for tests/audit-readme-counts.mjs (ships: `tests/*.mutants.mjs`).
+ *
+ * It proves the count guard can REDDEN: tamper the quoted TOTAL in a COPY of README.md (via the
+ * guard's COUNTS_README seam) and require the NAMED assertion "README.md quotes the DERIVED totals"
+ * in the failure list. Expected reds must name the LOAD-BEARING assertion, not any substring.
+ *
+ * Run: node tests/audit-readme-counts.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'
+import { claims } from './helpers/doc-counts-format.mjs'
+
+const HERE = fileURLToPath(new URL('./', import.meta.url))
+const REPO = join(HERE, '..')
+const GUARD = join(HERE, 'audit-readme-counts.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 base = spawnSync(process.execPath, [GUARD], { cwd: REPO, encoding: 'utf8' })
+const baseOut = String(base.stdout || '') + String(base.stderr || '')
+ok(base.status === 0 && /10 passed, 0 failed|passed, 0 failed/.test(baseOut), 'baseline: the count guard is green',
+  (baseOut.trim().split('\n').filter(Boolean).slice(-1)[0] || '').slice(0, 80))
+
+// Tamper the EXACT quoted needle (not a random first match), so the red names the load-bearing check.
+const derived = JSON.parse(spawnSync(process.execPath, [join(HERE, 'run-tests.mjs'), '--counts'], { cwd: REPO, encoding: 'utf8' }).stdout.trim())
+const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'))
+const dir = mkdtempSync(join(tmpdir(), 'counts-mut-'))
+const zh = readFileSync(join(REPO, 'README.md'), 'utf8')
+const shippedFiles = pkg.files.filter((f) => f.startsWith('tests/') && f.endsWith('.mjs'))
+const shipped = { total: shippedFiles.length, suites: shippedFiles.filter((f) => f.endsWith('.test.mjs')).length }
+shipped.probes = shipped.total - shipped.suites
+const needle = claims(derived, shipped).zhTotal
+if (zh.indexOf(needle) === -1) {
+  ok(false, 'the tamper anchor is present in README.md (the guard and the harness agree on the shape)', 'ANCHOR MISS: ' + needle)
+} else {
+  writeFileSync(join(dir, 'README.md'), zh.replace(needle, '`TOTAL 57`（39 套件 + 18 探针/变体）'))
+  const mut = spawnSync(process.execPath, [GUARD], { cwd: REPO, encoding: 'utf8', env: Object.assign({}, process.env, { COUNTS_README: join(dir, 'README.md') }) })
+  const out = String(mut.stdout || '') + String(mut.stderr || '')
+  const failLines = out.split('\n').filter((l) => /^  - /.test(l))
+  const named = failLines.some((l) => l.indexOf('README.md carries the canonical JOB-count bullet') !== -1)
+  ok(mut.status !== 0 && named, '★ tampering the quoted TOTAL makes the count guard RED by name', 'exit=' + mut.status)
+  if (!named) for (const l of failLines.slice(0, 4)) console.log('      guard failure: ' + l.trim().slice(0, 130))
+}
+rmSync(dir, { recursive: true, force: true })
+console.log('')
+console.log('=== README COUNTS MUTANTS: ' + passed + ' passed, ' + failed + ' failed ===')
+process.exit(failed === 0 ? 0 : 1)

package/tests/audit-registration.mjs

@@ -0,0 +1,78 @@
+/**
+ * ROUND 2 — verify the tool-registration surface against the REAL host contract.
+ *
+ * `dsh-tools` register(): "duplicates within one layer ... fail". So if a preset
+ * registers the same tool name twice in the same scope, the preset cannot mount.
+ * The e2e mocks only push to an array, so they cannot see this. This counts what the
+ * plugin actually registers and reports duplicates.
+ */
+import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const WS = mkdtempSync(join(tmpdir(), 'reg-'));
+const toolRegs = [];
+const cmdRegs = [];
+const ctx = {
+  get(n) {
+    if (n === 'subprocess') return { async spawn({ argv }) {
+      const s = argv[argv.length - 1] || '';
+      if (/New-Item/.test(s)) { const m = s.match(/-Path\s+'((?:[^']|'')*)'/); if (m) m[1].split(',').forEach((p) => { if (p) mkdirSync(p.replace(/''/g, "'"), { recursive: true }); }); }
+      return { done: Promise.resolve({ exitCode: 0 }) };
+    } };
+    return undefined;
+  },
+  on() {}, effect(fn) { const d = fn(); return () => { if (typeof d === 'function') d(); } },
+  logger: { info() {}, warn() {}, error() {} },
+  tools: { register(spec) { toolRegs.push(spec); } },
+  commands: { register(spec) { cmdRegs.push(spec); } },
+  subagents: { list() { return ['spawn']; }, async startContinuable() { return { childId: 'c1' }; }, async sendMessage() {}, async followup() {}, interrupt() {} },
+  agents: { roots() { return []; }, get() { return undefined; } },
+  fs: {
+    async resolve(rel, o) { return join((o && o.cwd) || WS, ...String(rel).split('/')); },
+    async stat(t) { return existsSync(t) ? { type: 'file' } : undefined; },
+    async readText(t) { return readFileSync(t, 'utf8'); },
+    async writeText(t, c) { mkdirSync(dirname(t), { recursive: true }); writeFileSync(t, c, 'utf8'); },
+    async listDir(t) { if (!existsSync(t)) return []; return readdirSync(t, { withFileTypes: true }).map((e) => ({ name: e.name, type: e.isDirectory() ? 'directory' : 'file' })); },
+  },
+};
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const FILE = process.argv[2] || 'vibe-math-v3/vibe-math-v3.js';
+const TARGET = isAbsolute(FILE) ? FILE : resolve(REPO, FILE);
+const mod = await import(pathToFileURL(TARGET).href + '?t=' + Date.now());
+const plugin = mod.default || mod;
+
+console.log(`=== ${FILE} ===`);
+console.log(`exported name   : ${plugin.name}`);
+console.log(`exported inject : ${JSON.stringify(plugin.inject)}`);
+
+let applyError = null;
+try { plugin.apply(ctx); } catch (e) { applyError = e; }
+if (applyError) { console.log(`apply() threw  : ${applyError.message}`); }
+
+console.log(`tools.register calls   : ${toolRegs.length}`);
+console.log(`commands.register calls: ${cmdRegs.length}`);
+
+const dup = (specs) => {
+  const seen = new Map();
+  for (const s of specs) seen.set(s.name, (seen.get(s.name) || 0) + 1);
+  return [...seen.entries()].filter(([, c]) => c > 1);
+};
+const toolDup = dup(toolRegs);
+const cmdDup = dup(cmdRegs);
+
+console.log(`DUPLICATE tool names   : ${toolDup.length === 0 ? 'none' : JSON.stringify(toolDup)}`);
+console.log(`DUPLICATE command names: ${cmdDup.length === 0 ? 'none' : JSON.stringify(cmdDup)}`);
+
+// Every registered tool must satisfy the host's mandatory output contract.
+const missingOutput = toolRegs.filter((s) => !s.output || typeof s.output.render !== 'function' || !s.output.schema);
+console.log(`tools missing output{}/render: ${missingOutput.length === 0 ? 'none' : missingOutput.map((s) => s.name).join(', ')}`);
+const badName = toolRegs.filter((s) => typeof s.name !== 'string' || s.name === '');
+console.log(`tools with a bad name  : ${badName.length === 0 ? 'none' : badName.length}`);
+
+console.log(`\nfirst 8 tool names: ${toolRegs.slice(0, 8).map((s) => s.name).join(', ')}`);
+
+rmSync(WS, { recursive: true, force: true });
+process.exit(toolDup.length > 0 || cmdDup.length > 0 || missingOutput.length > 0 ? 1 : 0);