myxo-lang 1.5.0

package/polyglot-host.js

@@ -0,0 +1,39 @@
+'use strict';
+// polyglot-host.js — run an .myx script WITH the polyglot capabilities (python/node/perl/bridgeExec/sh) installed,
+// under the capability fence: the script must declare a `needs` manifest, and every foreign call is audited.
+//   node polyglot-host.js <file.myx> [--audit]
+// This is the "real host" for scripts that orchestrate other runtimes — the fence + audit are what make that safe.
+
+const fs = require('fs');
+const path = require('path');
+const { makeInterpreter } = require('./myxo');
+const { installPolyglot } = require('./polyglot');
+const { parse } = require('./parser');
+
+function main() {
+  const argv = process.argv.slice(2);
+  const showAudit = argv.includes('--audit');
+  const file = argv.find(a => !a.startsWith('--'));
+  if (!file) { process.stderr.write('usage: node polyglot-host.js <file.myx> [--audit]\n'); process.exit(2); }
+  let src;
+  try { src = fs.readFileSync(file, 'utf8'); }
+  catch { process.stderr.write(`polyglot-host: no such file: ${file}\n`); process.exit(2); }
+
+  let out = '';
+  const interp = makeInterpreter({ output: (s) => { out += s; }, dir: path.dirname(path.resolve(file)), requireManifest: true });
+  installPolyglot(interp);   // grant python/node/perl/bridgeExec/sh — all fenced by the script's `needs` + audited
+
+  let failed = null;
+  try { interp.run(parse(src)); }
+  catch (e) { failed = e && e.message ? e.message : String(e); }
+
+  process.stdout.write(out);
+  if (showAudit) {
+    process.stderr.write('--- audit ledger (every fenced capability call) ---\n');
+    for (const a of interp.audit) process.stderr.write(`  ${a.ok ? 'ok ' : 'XX '} ${a.cap}\n`);
+  }
+  if (failed) { process.stderr.write('nx: ' + failed + '\n'); process.exit(1); }
+}
+
+if (require.main === module) main();
+module.exports = { };

package/polyglot.js

@@ -0,0 +1,191 @@
+'use strict';
+// polyglot.js — Myxo as the connective layer for OTHER LANGUAGES. The keystone: an Myxo capability is just
+// `name -> fn`, so Myxo neither knows nor cares what language is behind it; each runner is a FENCED native, so the
+// one law governs every cross-language call. TWO tiers (honest — these are NOT one contract):
+//   1. RICH bridge via `defineLang()` -> `Xcall(file,func,...args)` + `Xeval(expr)`, value-mapped (mesh/list/
+//      number/bool round-trip, verified identical across languages) with structured returns. Needs a runtime
+//      with an eval-a-string flag. BUILT + TESTED: Python (-c), Node (-e), Perl (-e); Ruby (-e) fits the shape.
+//      Each harness is small but NOT trivial — it carries that language's module-load, hard-exit, JSON and eval
+//      quirks; adding a language means getting those right, not just pasting a string.
+//   2. WEAK bridge via `bridgeExec(cmd)` -> raw stdout string in/out, NO value mapping. This is the ONLY path
+//      for COMPILED languages with no eval flag (Go, Rust, C++ binaries) and for CLIs; plus `sh` for the shell.
+// Only Python/Node/Perl are installed + tested here; other languages are a forward design, not a present claim.
+// Non-finite numbers (NaN/Infinity) are an EXPLICIT error on every path (never a silent null): args via toJson,
+// Python via allow_nan=False, Node via a throwing replacer, Perl via parse. Anti-spoof hard-exit: Python os._exit
+// and Perl POSIX::_exit are TRUE hard exits (skip atexit/END); Node process.exit runs 'exit' handlers, so a
+// loaded module's exit-time stdout could (in trusted code) trail and, worst case, spoof the result.
+//
+// ⚠️  HONEST SECURITY MODEL — read before trusting this.  The fence bounds WHICH languages/verbs a script may
+// reach (needs-manifest), HOW MANY / HOW MUCH (value budgets: numeric first-arg = spend; otherwise = call count),
+// and LOGS every call (audit ledger). It does NOT sandbox the code that runs INSIDE a granted verb. `Xcall`/
+// `Xeval`/`sh` are ARBITRARY-CODE capabilities: granting one grants the FULL power of that runtime (filesystem,
+// network, subprocess). Use them only for code YOU trust. For untrusted / model-generated callers, expose only
+// STRUCTURED capabilities (one specific function/tool), where the fence is meaningful end to end. Calls are
+// synchronous (execFileSync, built on spawnSync); a persistent-worker fast path is a future plank. Note: Myxo
+// numbers are float64, so an integer above 2^53 returned from a language loses precision. Zero deps.
+// Built 2026-06-26 (two-agent gated).
+
+const { execFileSync, execSync } = require('child_process');
+const { MyxoError } = require('./errors');
+const { VOID } = require('./interpreter');
+
+const CAP = 8 * 1024 * 1024, TIMEOUT = 15000;
+const OK = String.fromCharCode(1), ERR = String.fromCharCode(2);   // result-framing markers (U+0001 / U+0002)
+
+function detail(e) { const s = e.stderr && String(e.stderr).trim(); return s || e.message || (e.code ? String(e.code) : 'failed'); }
+
+// ---- Myxo <-> JS value mapping (mesh<->object, list<->array, VOID<->null), with a cycle guard ----
+function nxToJs(v, seen) {
+  if (v === VOID) return null;
+  if (Array.isArray(v) || v instanceof Map) {
+    seen = seen || new Set();
+    if (seen.has(v)) throw new MyxoError('cannot send a cyclic value across the language bridge');
+    seen.add(v);
+    let out;
+    if (Array.isArray(v)) out = v.map(x => nxToJs(x, seen));
+    else { out = {}; for (const [k, val] of v) out[k] = nxToJs(val, seen); }
+    seen.delete(v);   // pop on exit: only the ACTIVE path is "seen" -> shared (diamond) refs are fine; true cycles still caught
+    return out;
+  }
+  return v;
+}
+// JSON for the wire, but a non-finite number is an explicit error (consistent across languages — never a silent null)
+function toJson(v) {
+  return JSON.stringify(v, (k, val) => {
+    if (typeof val === 'number' && !isFinite(val)) throw new MyxoError('cannot send a non-finite number across the language bridge');
+    return val;
+  });
+}
+function jsToNx(v) {
+  if (v === null || v === undefined) return VOID;
+  if (Array.isArray(v)) return v.map(jsToNx);
+  if (typeof v === 'object') { const m = new Map(); for (const k of Object.keys(v)) m.set(k, jsToNx(v[k])); return m; }
+  return v;
+}
+
+// A harness writes its framed result then HARD-EXITS, so nothing (atexit/threads/shutdown noise) can write
+// after it and spoof the marker. This parser is language-agnostic: U+0001 + JSON on success, U+0002 + msg on error.
+function parseFramed(out, what) {
+  const i = out.lastIndexOf(OK), j = out.lastIndexOf(ERR);
+  if (j > i) throw new MyxoError(`${what} error: ` + out.slice(j + 1).trim());
+  if (i < 0) throw new MyxoError(`${what} returned no result`);
+  try { return jsToNx(JSON.parse(out.slice(i + 1))); }
+  catch (e) { throw new MyxoError(`${what} returned a value Myxo can't represent (non-finite or non-JSON): ` + e.message); }
+}
+
+function runHarness(cmd, flag, harness, extraArgs, label) {
+  let out;
+  try { out = execFileSync(cmd, [flag, harness, ...extraArgs], { encoding: 'utf8', timeout: TIMEOUT, maxBuffer: CAP }); }
+  catch (e) { throw new MyxoError(`${label} failed: ` + detail(e)); }
+  return parseFramed(out, label);
+}
+
+// defineLang — the heart: turn any language into fenced `Xcall(file, func, ...args)` + `Xeval(expr)` natives.
+// `callHarness`/`evalHarness` are programs IN that language implementing the framing protocol above.
+function defineLang({ name, cmd, flag, callHarness, evalHarness }) {
+  const call = (args) => {
+    const [file, func, ...rest] = args;
+    if (typeof file !== 'string' || typeof func !== 'string') throw new MyxoError(`${name}call(file, func, ...args) needs file and func as strings`);
+    return runHarness(cmd, flag, callHarness, [file, func, toJson(rest.map(a => nxToJs(a)))], name);
+  };
+  const evl = (args) => {
+    if (typeof args[0] !== 'string') throw new MyxoError(`${name}eval(expr) needs a string`);
+    return runHarness(cmd, flag, evalHarness, [args[0]], name);
+  };
+  return { call, eval: evl };
+}
+
+// ---- Python (python -c) — json.dumps(allow_nan=False): non-finite -> clean framed error; os._exit -> no trailing spoof
+const PY = process.platform === 'win32' ? 'python' : 'python3';
+const python = defineLang({
+  name: 'python', cmd: PY, flag: '-c',
+  callHarness: [
+    'import sys, json, os, importlib.util',
+    'p, fn, a = sys.argv[1], sys.argv[2], sys.argv[3]',
+    'try:',
+    '    spec = importlib.util.spec_from_file_location("nx_mod", p)',
+    '    m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)',
+    '    o = "\\u0001" + json.dumps(getattr(m, fn)(*json.loads(a)), allow_nan=False)',
+    'except Exception as e:',
+    '    o = "\\u0002" + str(e).replace("\\u0001", "").replace("\\u0002", "")',
+    'sys.stdout.write(o); sys.stdout.flush(); os._exit(0)',
+  ].join('\n'),
+  evalHarness: [
+    'import sys, json, os',
+    'try: o = "\\u0001" + json.dumps(eval(sys.argv[1]), allow_nan=False)',
+    'except Exception as e: o = "\\u0002" + str(e).replace("\\u0001", "").replace("\\u0002", "")',
+    'sys.stdout.write(o); sys.stdout.flush(); os._exit(0)',
+  ].join('\n'),
+});
+
+// ---- Node (node -e) — the .js file must be a CommonJS module exporting the function; fs.writeSync + process.exit
+const node = defineLang({
+  name: 'node', cmd: 'node', flag: '-e',
+  callHarness: [
+    "const p=require('path'),fs=require('fs');",
+    "const J=x=>JSON.stringify(x,(k,v)=>{if(typeof v==='number'&&!isFinite(v))throw new Error('non-finite number');return v;});",
+    "try{const m=require(p.resolve(process.argv[1]));",
+    "let r=m[process.argv[2]](...JSON.parse(process.argv[3]));if(r===undefined)r=null;",
+    "fs.writeSync(1,'\\u0001'+J(r));}",
+    "catch(e){fs.writeSync(1,'\\u0002'+String(e&&e.message||e).replace(/[\\u0001\\u0002]/g,''));}process.exit(0);",
+  ].join(''),
+  evalHarness: [
+    "const fs=require('fs');",
+    "const J=x=>JSON.stringify(x,(k,v)=>{if(typeof v==='number'&&!isFinite(v))throw new Error('non-finite number');return v;});",
+    "try{let r=(0,eval)(process.argv[1]);if(r===undefined)r=null;",
+    "fs.writeSync(1,'\\u0001'+J(r));}",
+    "catch(e){fs.writeSync(1,'\\u0002'+String(e&&e.message||e).replace(/[\\u0001\\u0002]/g,''));}process.exit(0);",
+  ].join(''),
+});
+
+// ---- Perl (perl -e) — `do $file` loads subs; return a scalar or a ref (arrayref/hashref) for structured data
+const perl = defineLang({
+  name: 'perl', cmd: 'perl', flag: '-e',
+  callHarness: [
+    "use JSON::PP; use File::Spec; use POSIX; $|=1; my($f,$fn,$a)=@ARGV;",
+    "my $j=JSON::PP->new->allow_nonref->canonical; my $abs=File::Spec->rel2abs($f);",   // '.' left @INC in modern perl -> absolutize
+    "my $r=eval{ do $abs; die $@ if $@; no strict 'refs'; &{$fn}(@{$j->decode($a)}) };",
+    "if($@){ my $m=$@; $m=~s/[\\x01\\x02]//g; print \"\\x02\".$m } else { print \"\\x01\".$j->encode($r) } POSIX::_exit(0);",
+  ].join(' '),
+  evalHarness: [
+    "use JSON::PP; use POSIX; $|=1; my $j=JSON::PP->new->allow_nonref->canonical;",
+    "my $r=eval $ARGV[0]; if($@){ my $m=$@; $m=~s/[\\x01\\x02]//g; print \"\\x02\".$m } else { print \"\\x01\".$j->encode($r) } POSIX::_exit(0);",
+  ].join(' '),
+});
+
+const pycall = python.call, pyeval = python.eval;
+const jscall = node.call, jseval = node.eval;
+const plcall = perl.call, pleval = perl.eval;
+
+// argv is strings: scalars stringify; structured values go as JSON (no silent flattening to "[object Object]")
+function toArg(a) {
+  if (a === VOID) return '';
+  if (Array.isArray(a) || a instanceof Map) return JSON.stringify(nxToJs(a));
+  return String(a);
+}
+// bridgeExec('/path/to/binary' [, fixedArgs]) -> an Myxo native; how a compiled C++/Go/Rust binary or CLI plugs in
+function bridgeExec(cmd, fixedArgs = []) {
+  return function (args) {
+    let out;
+    try { out = execFileSync(cmd, [...fixedArgs, ...args.map(toArg)], { encoding: 'utf8', timeout: TIMEOUT, maxBuffer: CAP }); }
+    catch (e) { throw new MyxoError(`exec '${cmd}' failed: ` + detail(e)); }
+    return out.replace(/\r?\n$/, '');
+  };
+}
+// sh(command) -> run a shell command line, return stdout. (Shell parsing: hand only trusted strings.)
+function sh(args) {
+  if (typeof args[0] !== 'string') throw new MyxoError('sh(command) needs a string');
+  try { return execSync(args[0], { encoding: 'utf8', timeout: TIMEOUT, maxBuffer: CAP }).replace(/\r?\n$/, ''); }
+  catch (e) { throw new MyxoError('shell failed: ' + detail(e)); }
+}
+
+// Convenience: wire the bridges into an interpreter as FENCED capabilities (still gated by `needs`).
+function installPolyglot(interp, extra = {}) {
+  const fns = { pycall, pyeval, jscall, jseval, plcall, pleval, sh };
+  for (const [name, fn] of Object.entries({ ...fns, ...extra })) interp.registerNative(name, fn, true);
+}
+
+module.exports = {
+  pycall, pyeval, jscall, jseval, plcall, pleval, sh, bridgeExec,
+  defineLang, installPolyglot, nxToJs, jsToNx,
+};

package/receipt.js

@@ -0,0 +1,71 @@
+'use strict';
+// receipt.js -- a tamper-evident RECEIPT over an Myxo audit ledger.
+//
+// An Myxo run produces an audit array of { cap, args[], ok, error? } entries (every fenced capability call, allowed or
+// refused). This turns that ledger into a proof: a sha256 hash CHAIN (each entry commits the previous), SEALED with an
+// HMAC over {count, root} using a HOST-HELD key. In-place edits, reordering, and re-chaining change the root; dropping
+// or adding entries changes the count; and neither can be re-sealed without the key. So a saved/shared receipt can be
+// verified later as an untampered record of exactly what a (possibly untrusted) script did.
+//
+// Shared by Warden (warden/warden.js) and JAMES (james_nx_run) so both speak the same receipt.
+
+const crypto = require('crypto');
+const fs = require('fs');
+
+const GENESIS = crypto.createHash('sha256').update('nx-receipt-genesis-v1').digest('hex');
+
+// exactly the fields the receipt retains + reconciles on; any change to these breaks the chain
+function bodyOf(e) {
+  return JSON.stringify({ seq: e.seq, cap: e.cap, args: e.args, ok: e.ok, error: e.error || null });
+}
+
+function chain(audit) {
+  let prev = GENESIS;
+  return (audit || []).map((e, i) => {
+    const entry = { seq: i, cap: e.cap, args: e.args, ok: e.ok, error: e.error || null, prev };
+    entry.hash = crypto.createHash('sha256').update(prev + bodyOf(entry)).digest('hex');
+    prev = entry.hash;
+    return entry;
+  });
+}
+
+// commit LENGTH + final ROOT under an HMAC. Truncation changes count; any edit/re-chain changes root; forging needs the key.
+function sealReceipt(receipt, key) {
+  const root = receipt.length ? receipt[receipt.length - 1].hash : GENESIS;
+  return { count: receipt.length, root, mac: crypto.createHmac('sha256', key).update(receipt.length + ':' + root).digest('hex') };
+}
+
+function verifyChain(receipt, seal, key) {
+  let prev = GENESIS;
+  for (const e of receipt) {
+    if (e.prev !== prev) return { ok: false, brokeAt: e.seq, why: 'prev-hash mismatch' };
+    const h = crypto.createHash('sha256').update(prev + bodyOf(e)).digest('hex');
+    if (h !== e.hash) return { ok: false, brokeAt: e.seq, why: 'entry hash mismatch (tampered)' };
+    prev = e.hash;
+  }
+  if (seal) {
+    if (seal.count !== receipt.length) return { ok: false, brokeAt: receipt.length, why: 'length seal mismatch (truncated/extended)' };
+    if (seal.root !== prev) return { ok: false, brokeAt: receipt.length, why: 'root seal mismatch' };
+    if (key) {
+      const good = crypto.createHmac('sha256', key).update(seal.count + ':' + seal.root).digest('hex');
+      if (good !== seal.mac) return { ok: false, brokeAt: receipt.length, why: 'HMAC seal mismatch (forged without the key)' };
+    }
+  }
+  return { ok: true, root: prev };
+}
+
+// a persistent host key: prefer an env var (hex), else a 0600 keyfile created once. Persistent so receipts verify later.
+function hostKey(opts = {}) {
+  const envName = opts.env || 'NX_RECEIPT_KEY';
+  if (process.env[envName]) return Buffer.from(process.env[envName], 'hex');
+  const file = opts.file;
+  if (file) {
+    try { if (fs.existsSync(file)) return Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'hex'); } catch {}
+    const key = crypto.randomBytes(32);
+    try { fs.writeFileSync(file, key.toString('hex'), { mode: 0o600 }); } catch {}
+    return key;
+  }
+  return crypto.randomBytes(32);   // ephemeral (verify only within this process)
+}
+
+module.exports = { GENESIS, bodyOf, chain, sealReceipt, verifyChain, hostKey };

package/std.myx

@@ -0,0 +1,88 @@
+# std.myx — the Myxo standard library, written in Myxo itself.
+# Loaded before every program. These agents lean on the native builtins
+# (push, len, range, keys...) but everything here is plain Myxo.
+
+# Apply an agent to every item, collecting the results.
+agent map(xs, f) {
+  seed out = []
+  for each x in xs {
+    push(out, f(x))
+  }
+  report out
+}
+
+# Keep only the items an agent says are live.
+agent filter(xs, f) {
+  seed out = []
+  for each x in xs {
+    when f(x) {
+      push(out, x)
+    }
+  }
+  report out
+}
+
+# Fold a list down to a single value.
+agent reduce(xs, start, f) {
+  seed acc = start
+  for each x in xs {
+    acc = f(acc, x)
+  }
+  report acc
+}
+
+# Sum of a list of numbers.
+agent sum(xs) {
+  report reduce(xs, 0, agent(a, b) { report a + b })
+}
+
+# Largest value in a list.
+agent biggest(xs) {
+  seed best = xs[0]
+  for each x in xs {
+    when x > best {
+      best = x
+    }
+  }
+  report best
+}
+
+# Is a value present in a list?
+agent contains(xs, target) {
+  for each x in xs {
+    when x == target {
+      report live
+    }
+  }
+  report dead
+}
+
+# Count items that satisfy an agent.
+agent count(xs, f) {
+  seed n = 0
+  for each x in xs {
+    when f(x) {
+      n = n + 1
+    }
+  }
+  report n
+}
+
+# — constants —
+seed PI = 3.141592653589793
+seed E = 2.718281828459045
+
+# First and last of a list.
+agent first(xs) { report xs[0] }
+agent last(xs) { report xs[len(xs) - 1] }
+
+# Keep a number within a range.
+agent clamp(x, lo, hi) {
+  when x < lo { report lo }
+  when x > hi { report hi }
+  report x
+}
+
+# Split text into words and lines (leans on the native split/trim).
+agent words(s) { report split(trim(s), " ") }
+agent lines(s) { report split(s, "\n") }

package/tools/memo-fuzz.js

@@ -0,0 +1,224 @@
+'use strict';
+// ---------------------------------------------------------------------------------------------------
+// Memo-soundness differential fuzzer for Myxo.
+//
+// Myxo's load-bearing promise: memoization is INVISIBLE. A program's output with the hot-promotion
+// memoizer ON (promoteAt = 2) must equal its output with it OFF (promoteAt = 1e9). Every memo bug we
+// have found is a violation of exactly that equality:
+//     router-freeze .......... a pure agent wrapping route() cached the router's first pick forever
+//     prune/metabolize ghost .. a reaped/rebound dependency kept being served from a stale cache
+//     keyOf collision ......... two distinct arg lists forged the same memo key (\x1f join; -0 vs 0)
+// Instead of one hand-written repro per bug, we GENERATE programs that stress the memoizer, run each
+// ON and OFF, and flag any that disagree. It reproduces the router and keyOf classes on its own when
+// their fixes are reverted (see `node tools/memo-fuzz.js` against a reverted build), and the `reap`
+// family guards the epoch-invalidation class the same way.
+//
+// HONEST SCOPE: the invariant is "memo-invisible EXCEPT for documented mesh introspection" — strength()
+// / mesh() / metabolize()-return values are deliberately allowed to observe promotion (interpreter.js
+// disclaims mesh-strength invisibility). The generators therefore never EMIT those introspection values,
+// so the ON==OFF oracle stays a true soundness test and not a false alarm on intended behavior.
+//
+// COVERAGE IS MEASURED, NOT ASSUMED: each program's ON run reports its real memo cache-hit count, and a
+// family that never exercises the cache (hollow) is a test failure — that is exactly how the original
+// `reap` family (a free-DATA read that tainted purity and never promoted) hid behind a green suite.
+//
+// Pure JS, zero deps. Deterministic (seeded PRNG) so every failure reproduces byte-for-byte.
+// ---------------------------------------------------------------------------------------------------
+
+const { makeInterpreter } = require('../myxo');
+const { parse } = require('../parser');
+
+// --- deterministic PRNG (mulberry32) ---------------------------------------------------------------
+function makeRng(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6D2B79F5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const pick = (rnd, xs) => xs[Math.floor(rnd() * xs.length)];
+const rint = (rnd, lo, hi) => lo + Math.floor(rnd() * (hi - lo + 1));
+
+// --- run one program and report output + program-attributable memo cache HITS ----------------------
+// Replicates myxo.run()'s capture mode, but keeps the interpreter so we can read its memo records.
+// Boot hits (stdlib promoting during install) are discounted so `hits` reflects only the program.
+function runStats(src, promoteAt) {
+  const chunks = [];
+  const interp = makeInterpreter({ output: (s) => chunks.push(s), promoteAt });
+  let base = 0;
+  for (const rec of interp.memo.values()) base += rec.hits;
+  let r;
+  try { interp.run(parse(src)); r = { ok: true, v: chunks.join('') }; }
+  catch (e) { r = { ok: false, v: String((e && e.message) || e) }; }
+  let hits = 0;
+  for (const rec of interp.memo.values()) hits += rec.hits;
+  r.hits = hits - base;
+  return r;
+}
+
+// --- the oracle: one ON-vs-OFF differential run ----------------------------------------------------
+function differential(src) {
+  const on = runStats(src, 2);        // memoizer ON (default hot-promote threshold)
+  const off = runStats(src, 1e9);     // memoizer effectively OFF
+  const violation = (on.ok !== off.ok || on.v !== off.v) ? { on, off } : null;
+  return { violation, onHits: on.hits };
+}
+
+// "nasty" bytes: content that looks like keyOf's own tags/separator — most able to forge a key boundary.
+const SEP = '\x1f';
+// Myxo string literal preserving RAW bytes (incl. control bytes like \x1f). JSON.stringify would escape
+// \x1f to a 6-char sequence and defuse the very collision we hunt; only " and \ need escaping.
+const q = (s) => '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+
+// --- FAMILY: keyOf boundary-forge (string separator collision) -------------------------------------
+// Two DISTINCT arg lists that collide under a naive separator-join key:
+//   f(p+SEP+"s:"+w, r) and f(p, w+SEP+"s:"+r) both flatten to  s:<p><SEP>s:<w><SEP>s:<r>.
+function genKeyCollision(rnd) {
+  const p = pick(rnd, ['a', 'xy', '', 'k']);
+  const w = pick(rnd, ['b', 'q', '', 'm']);
+  const r = pick(rnd, ['c', 'r', 'z', '']);
+  const a1 = p + SEP + 's:' + w, b1 = r;
+  const a2 = p,                  b2 = w + SEP + 's:' + r;
+  return [
+    'agent f(a, b){ report a }',
+    `emit str(f(${q(a1)}, ${q(b1)}))`,
+    `emit str(f(${q(a1)}, ${q(b1)}))`,
+    `emit str(f(${q(a1)}, ${q(b1)}))`,   // promote + cache under the key
+    `emit str(f(${q(a2)}, ${q(b2)}))`,   // distinct args, old-collision -> must NOT return the cached value
+  ].join('\n');
+}
+
+// --- FAMILY: keyOf numeric collision (-0 vs 0) -----------------------------------------------------
+// pow(x,-1) is sign-observable: pow(0,-1)=Infinity, pow(-0,-1)=-Infinity. String(-0)==="0", so a naive
+// number tag keys -0 and 0 the same and a cached f(0) ghost-answers f(-0). Deterministically pair them.
+function genNumeric(rnd) {
+  const zeroFirst = rnd() < 0.5;
+  const first = zeroFirst ? '0' : '(0-1)*0';        // (0-1)*0 evaluates to -0
+  const second = zeroFirst ? '(0-1)*0' : '0';
+  return [
+    'agent f(x){ report pow(x, 0-1) }',
+    `emit str(f(${first}))`,
+    `emit str(f(${first}))`,
+    `emit str(f(${first}))`,   // promote + cache under the numeric key
+    `emit str(f(${second}))`,  // sign partner: a -0/0 key collision ghosts the cached answer
+  ].join('\n');
+}
+
+// --- FAMILY: router-freeze -------------------------------------------------------------------------
+// A pure agent wraps route() over two equally-good providers, driven with a constant arg. Sound runs
+// share traffic (the wrapping agent must be tainted, not cached); a frozen run monopolizes one provider.
+function genRouter(rnd) {
+  const drives = rint(rnd, 20, 60);
+  const arg = rint(rnd, 0, 3);
+  return [
+    'agent A(x){ report "A" }',
+    'agent B(x){ report "B" }',
+    'seed r = route("fz", [A, B])',
+    'agent ask(q){ report r(q) }',
+    'seed g = []',
+    `reinforce ${drives} times { push(g, ask(${arg})) }`,
+    'seed nA = count(g, agent(v){ report v == "A" })',   // count() promotes -> real cache hits
+    'emit nA > 0, nA < ' + drives,                        // sound: both seen -> "live live"; frozen -> a "dead"
+  ].join('\n');
+}
+
+// --- FAMILY: reap / epoch invalidation -------------------------------------------------------------
+// f reads a FREE AGENT g (the recursion exemption keeps f pure, so it genuinely PROMOTES and caches).
+// Then a dependency change must bump the epoch and drop f's stale cache: either g is rebound, or the
+// mesh is metabolized. If epoch invalidation regresses, ON ghost-serves the old answer -> divergence.
+function genReap(rnd) {
+  const n1 = rint(rnd, 1, 9), n2 = rint(rnd, 10, 99), a = rint(rnd, 0, 3);
+  const base = [
+    `agent g(x){ report x + ${n1} }`,
+    'agent f(x){ report g(x) }',
+    `emit f(${a})`, `emit f(${a})`, `emit f(${a})`,   // promote + cache f(${a}) under the current g
+  ];
+  if (rnd() < 0.5) {
+    // ghost-rebind: redefining g must invalidate f's cache (epoch bump)
+    return base.concat([`agent g(x){ report x + ${n2} }`, `emit f(${a})`]).join('\n');
+  }
+  // ghost-reap: metabolize reaps the mesh; a sound epoch invalidates so f re-runs (and finds g reaped)
+  return base.concat(['seed _ = metabolize(1000)', `attempt { emit f(${a}) } rescue e { emit "reaped" }`]).join('\n');
+}
+
+// --- FAMILY: broad nasty-arg coverage (pure agents, mixed types) -----------------------------------
+function genNasty(rnd) {
+  const arity = rint(rnd, 1, 3);
+  const params = ['a', 'b', 'c'].slice(0, arity);
+  const rep = pick(rnd, params);
+  const nasty = ['', 'a', SEP, 's:', 'n:1', 'v', 'b:true', 'a' + SEP + 's:b', SEP + 's:', 's:' + SEP];
+  const lit = () => {
+    const k = rnd();
+    if (k < 0.55) return q(pick(rnd, nasty));
+    if (k < 0.8) return String(rint(rnd, -3, 3));            // small ints incl. negatives
+    return pick(rnd, ['void', 'live', 'dead', '(0-1)*0']);   // incl. -0
+  };
+  const lines = [`agent f(${params.join(', ')}){ report ${rep} }`];
+  const nCalls = rint(rnd, 4, 9);
+  const pools = [];
+  for (let i = 0; i < 3; i++) pools.push(params.map(lit).join(', '));   // repeated lists -> promotion
+  for (let i = 0; i < nCalls; i++) {
+    const args = rnd() < 0.55 ? pick(rnd, pools) : params.map(lit).join(', ');
+    lines.push(`emit str(f(${args}))`);
+  }
+  return lines.join('\n');
+}
+
+const FAMILIES = [
+  { name: 'keyCollision', gen: genKeyCollision, weight: 3 },
+  { name: 'numeric',      gen: genNumeric,      weight: 2 },
+  { name: 'router',       gen: genRouter,       weight: 3 },
+  { name: 'reap',         gen: genReap,         weight: 2 },
+  { name: 'nasty',        gen: genNasty,        weight: 2 },
+];
+const WEIGHTED = FAMILIES.flatMap((f) => Array(f.weight).fill(f));
+
+// --- driver ----------------------------------------------------------------------------------------
+// fuzz({ seed, count }) -> { checked, violations, byFamily, byFamilyHits }
+//   byFamily     = programs generated per family
+//   byFamilyHits = programs per family whose ON run reached >=1 real memo cache hit (hollow-family guard)
+function fuzz({ seed = 0x1CE, count = 400 } = {}) {
+  const rnd = makeRng(seed);
+  const violations = [];
+  const byFamily = Object.fromEntries(FAMILIES.map((f) => [f.name, 0]));
+  const byFamilyHits = Object.fromEntries(FAMILIES.map((f) => [f.name, 0]));
+  let checked = 0;
+  for (let i = 0; i < count; i++) {
+    const fam = pick(rnd, WEIGHTED);
+    const src = fam.gen(rnd);
+    checked++;
+    byFamily[fam.name]++;
+    const { violation, onHits } = differential(src);
+    if (onHits > 0) byFamilyHits[fam.name]++;
+    if (violation) violations.push({ family: fam.name, src, on: violation.on, off: violation.off });
+  }
+  return { checked, violations, byFamily, byFamilyHits };
+}
+
+module.exports = { fuzz, differential, runStats, makeRng };
+
+// --- CLI: `node tools/memo-fuzz.js [seed] [count]` -------------------------------------------------
+if (require.main === module) {
+  const seed = process.argv[2] ? (parseInt(process.argv[2], 16) || parseInt(process.argv[2], 10)) : 0x1CE;
+  const count = process.argv[3] ? parseInt(process.argv[3], 10) : 400;
+  const { checked, violations, byFamily, byFamilyHits } = fuzz({ seed, count });
+  console.log(`memo-soundness fuzz: seed=0x${seed.toString(16)} programs=${checked}`);
+  console.log(`  generated : ${JSON.stringify(byFamily)}`);
+  console.log(`  cache-hit : ${JSON.stringify(byFamilyHits)} (programs that reached >=1 real memo hit)`);
+  if (!violations.length) {
+    console.log(`RESULT: SOUND — memo-ON == memo-OFF on all ${checked} programs.`);
+    process.exit(0);
+  }
+  console.log(`RESULT: ${violations.length} SOUNDNESS VIOLATION(S) — memo corrupted a result:`);
+  for (const v of violations.slice(0, 5)) {
+    console.log('\n--- family:', v.family, '---');
+    console.log(v.src);
+    console.log('  memo-ON :', JSON.stringify(v.on.ok ? v.on.v : 'THREW ' + v.on.v));
+    console.log('  memo-OFF:', JSON.stringify(v.off.ok ? v.off.v : 'THREW ' + v.off.v));
+  }
+  if (violations.length > 5) console.log(`\n... and ${violations.length - 5} more.`);
+  process.exit(1);
+}