@ours.network/notifications 0.1.1

package/mufl_code/core/tests/compat/README.md

@@ -0,0 +1,82 @@
+# tests/compat — cross-version back-compat matrix (M-legs) + upgrade-UX legs (U-legs)
+
+The DR-rollout ship gate (DR-ROLLOUT-PLAN.md §5/§5.1): prove that an OLD-core peer and a
+NEW-core peer interoperate (DoD D1) and that upgrades migrate seamlessly (D2/D3) — with the
+two peers running in **separate processes, each under its own SDK runtime and its own
+compiled unit**. That two-runtime split is what the rest of `tests/` deliberately avoids
+(single node_modules, both peers in-process) and what production actually is mid-rollout.
+
+## Peers
+
+- **OLD** — core `v0.2.0` (`faa2b52`, the OSP: the deployed ours-mcp/tg-connector repo pin;
+  no `$pv`, no DR, legacy `encrypted_channel`), compiled by and run under an 0.9.x-era
+  toolkit (`OLD_ADAPT_TOOLKIT` / `OLD_SDK_NM`).
+- **NEW** — THIS working tree's core, compiled by and run under the current pinned toolkit
+  (`ADAPT_TOOLKIT` / `OURS_SDK_NODE_MODULES`, same knobs as `run.sh`).
+
+Each peer's build dir gets its own `core/` sources, its own compiled `.muflo`, and its own
+`node_modules` symlink — a packet is only ever loaded by the runtime whose compiler built
+it (the eval_unit.h hash-check contract).
+
+## Env (run_compat.sh)
+
+| Var | Meaning | Default |
+|---|---|---|
+| `OLD_CORE_REF` | git ref for the OLD peer's core sources | `v0.2.0` |
+| `OLD_ADAPT_TOOLKIT` | toolkit checkout whose `mufl-compile` + stdlib build the OLD unit | required |
+| `OLD_SDK_NM` | node_modules with the OLD-era `@adapt-toolkit` sdk | required |
+| `ADAPT_TOOLKIT` / `OURS_SDK_NODE_MODULES` / `DEV_BROKER` / `PORT` | as in `run.sh` | required |
+
+## Leg inventory (status is explicit — an unimplemented leg FAILS, never skips silently)
+
+| Leg | Gate | DoD | Status |
+|---|---|---|---|
+| M1 invite gen→redeem, both directions | MP | D1 | implemented |
+| M2 first-contact message after redeem | MP | D1 | implemented |
+| M3 steady-state send/receive both ways | MP | D1 | implemented |
+| M4 file transfer both ways | MP | D1 | implemented |
+| M5 OLD restarts: v0-blob export→reimport, channel resumes | MP | D1,D2 | implemented |
+| M6 NEW restarts: stamped blob + DR sessions restore | MP | D1,D2 | implemented |
+| M7 NEW↔NEW DR handshake + ratchet + dual restart | MP | D1 | not-implemented (needs 2× NEW peers — trivial config once M1–M6 green) |
+| M8 stale-snapshot restore → self-heal | NTH | D2 | not-implemented |
+| M9 corrupt blob import reject-to-empty | MP(NEW) | D2 | not-implemented |
+| M10 version_error_t as data | NTH | D1 | not-implemented (assertion pattern exists in tests/test.mjs V-series) |
+| M11 pv re-learning on peer downgrade | NTH | D1 | not-implemented |
+| M12 cross-app tg-connector↔mcp | MP | D1,D4 | lives in the consumer repos (drives their packets, not this actor) |
+| U1/U2/U3 npm-bump upgrade legs | MP | D2,D3 | live in the consumer repos' CI (install old → state → bump → verify) |
+
+Related prior art this seeds from: control-plane `tests/blob-import.mjs` (old-unit→new-unit
+same-seed gate) and `tests/mixed-unit.mjs` (4-cell pairing matrix) — single-runtime versions
+of M5/M1; this harness generalizes them across runtimes.
+
+## Run
+
+```
+OLD_ADAPT_TOOLKIT=... OLD_SDK_NM=... ADAPT_TOOLKIT=... OURS_SDK_NODE_MODULES=... \
+DEV_BROKER=... bash tests/compat/run_compat.sh
+```
+
+## M12 — control-plane NEW ↔ mcp OLD (owner's named leg) — GREEN 2026-07-21
+
+Reuses this orchestrator with per-side flavors (`NEW_PEER_FLAVOR=messenger` switches the
+READ verbs to `::actor::get_conversation`; the whole `::a2a_messaging::` write surface is
+shared). Peers: NEW = the control-plane DR unit (dev5/dr-e2e-integration, sdk 0.10.10,
+core v0.8.0) · OLD = the REAL mcp actor (`packages/core/mufl_code/actor.mu`) at its
+deployed pins (core `faa2b52` = v0.2.0/OSP) compiled+run under published sdk/mufl 0.9.1.
+Result: M1–M6 all green (invites both ways, first-contact, steady both ways, files both
+ways, both restart-restore legs).
+
+```
+# build dirs: old = mcp actor + 0.9.1 stage; new = cp unit + its node_modules
+OLD_BUILD_DIR=<mcp-old> NEW_BUILD_DIR=<cp-new> NEW_PEER_FLAVOR=messenger \
+  LEG_FILTER=M1,M2,M3,M4,M5,M6 node tests/compat/compat.mjs
+```
+
+## U3 — control-plane upgrade path — GREEN 2026-07-21
+
+Under the fresh-address ruling (unpublished app, zero clients) the npm-bump leg's
+meaningful nucleus is the control-plane's own blob-import gate: main-era unit sources
+(messenger + core 0.7.1) compiled with the CURRENT toolchain → real state → import under
+the DR unit → same seed ⇒ same cid, history/contacts preserved, zero rejects, re-export
+round-trips. Run via the cp repo's tests/run-blob-import.sh with OLD_UNIT pointed at the
+main-era build.

package/mufl_code/core/tests/compat/compat.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Cross-version matrix orchestrator: spawns OLD-runtime and NEW-runtime peers
+// (compat_peer.mjs each, separate processes, own node_modules + own unit — see README),
+// then drives the M-legs against the pair. Scorecard semantics: an MP leg failing (or not
+// implemented) exits non-zero; NTH legs report but never gate. No leg ever silently skips.
+import { spawn } from 'node:child_process';
+import { openSync as fsOpenSync, appendFileSync as fsAppendFileSync } from 'node:fs';
+import * as readline from 'node:readline';
+import { resolve } from 'node:path';
+
+const OLD_DIR = process.env.OLD_BUILD_DIR;
+const NEW_DIR = process.env.NEW_BUILD_DIR;
+const BROKER_URL = process.env.BROKER_URL || 'ws://127.0.0.1:9797';
+if (!OLD_DIR || !NEW_DIR) { console.error('OLD_BUILD_DIR / NEW_BUILD_DIR required'); process.exit(2); }
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let nextId = 1;
+
+function spawnPeer(dir, name, extraEnv = {}) {
+  // stderr goes to a per-peer log — handshake rejects surface there, and
+  // discarding it turned real compat failures into blind timeouts.
+  const errLog = fsOpenSync(resolve(dir, `${name}.stderr.log`), 'a');
+  const child = spawn(process.execPath, [resolve(dir, 'compat_peer.mjs')], {
+    cwd: dir, stdio: ['pipe', 'pipe', errLog],
+    env: { ...process.env, BROKER_URL, PEER_NAME: name, PEER_SEED: `compat ${name} seed`,
+      PEER_FLAVOR: dir === NEW_DIR ? (process.env.NEW_PEER_FLAVOR || 'actor') : (process.env.OLD_PEER_FLAVOR || 'actor'),
+      ...extraEnv },
+  });
+  const peer = { name, dir, child, cid: '', events: [], waiters: new Map(), readyP: null, exited: null };
+  const rl = readline.createInterface({ input: child.stdout });
+  let readyResolve; peer.readyP = new Promise((r) => { readyResolve = r; });
+  child.on('exit', (code, signal) => {
+    peer.exited = { code, signal };
+    console.log(`  [peer ${name}] exited code=${code} signal=${signal} (${peer.waiters.size} call(s) in flight)`);
+    for (const [, w] of peer.waiters) w.reject(new Error(`peer ${name} exited (code=${code} signal=${signal})`));
+    peer.waiters.clear();
+    readyResolve(); // a dead peer resolves readyP; callers check peer.cid
+  });
+  rl.on('line', (line) => {
+    let msg; try { msg = JSON.parse(line); } catch {
+      // Non-JSON stdout (e.g. the sdk leak-detector dump on exit) must not
+      // vanish — append it to the peer's log so leak totals are auditable.
+      try { fsAppendFileSync(resolve(dir, `${name}.stderr.log`), `[stdout] ${line}\n`); } catch {}
+      return;
+    }
+    if (msg.ready) { peer.cid = msg.cid; return readyResolve(); }
+    if (msg.event) return void peer.events.push(msg.event);
+    if (msg.fatal) { console.error(`[${name}] FATAL ${msg.fatal}`); return readyResolve(); }
+    const w = peer.waiters.get(msg.id);
+    if (w) { peer.waiters.delete(msg.id); msg.ok ? w.resolve(msg.value) : w.reject(new Error(msg.error)); }
+  });
+  return peer;
+}
+
+function call(peer, op, fields = {}, timeoutMs = 90000) {
+  const id = nextId++;
+  return new Promise((resolveP, rejectP) => {
+    if (peer.exited && op !== 'exit') return rejectP(new Error(`peer ${peer.name} already exited`));
+    const timer = setTimeout(() => {
+      peer.waiters.delete(id);
+      rejectP(new Error(`call ${op} on ${peer.name} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    peer.waiters.set(id, {
+      resolve: (v) => { clearTimeout(timer); resolveP(v); },
+      reject: (e) => { clearTimeout(timer); rejectP(e); },
+    });
+    peer.child.stdin.write(JSON.stringify({ id, op, ...fields }) + '\n');
+  });
+}
+
+// ---- shared drive helpers --------------------------------------------------
+async function contactsInclude(peer, cid, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const contacts = String(await call(peer, 'contacts').catch(() => ''));
+    if (contacts.includes(cid)) return true;
+    if (Date.now() > deadline) return false;
+    await sleep(1500);
+  }
+}
+async function pair(inviter, redeemer) {
+  const inviteB64 = await call(inviter, 'invite', { name: redeemer.name });
+  await call(redeemer, 'redeem', { invite_b64: inviteB64, name: inviter.name });
+  // Handshake is multi-leg and cross-runtime — poll until BOTH sides list the
+  // peer instead of guessing a sleep. A timeout here is a real M1 verdict.
+  const a = await contactsInclude(inviter, redeemer.cid);
+  const b = await contactsInclude(redeemer, inviter.cid);
+  if (!a || !b) throw new Error(`pairing incomplete after 30s (inviter-sees=${a} redeemer-sees=${b})`);
+}
+async function roundTrip(from, to, text, expectRoute) {
+  const sent = await call(from, 'send', { cid: to.cid, text });
+  if (expectRoute && sent?.route !== expectRoute) {
+    throw new Error(`route mismatch: expected ${expectRoute}, got ${sent?.route} for "${text}"`);
+  }
+  await sleep(2500);
+  const inbox = await call(to, 'inbox', { cid: from.cid });
+  if (!String(inbox).includes(text)) throw new Error(`message not delivered: "${text}"`);
+  return sent;
+}
+
+// ---- legs ------------------------------------------------------------------
+const LEGS = [
+  { id: 'M1', gate: 'MP', dod: 'D1', name: 'invite gen→redeem, both directions',
+    run: async (ctx) => {
+      await pair(ctx.oldPeer, ctx.newPeer); // OLD invites, NEW redeems (primary pair, reused by later legs)
+      // Reverse direction on a fresh throwaway pair: NEW invites, OLD redeems.
+      const old2 = spawnPeer(OLD_DIR, 'old2', { PEER_SEED: 'compat old2 seed' });
+      const new2 = spawnPeer(NEW_DIR, 'new2', { PEER_SEED: 'compat new2 seed' });
+      try {
+        await old2.readyP; await new2.readyP;
+        if (!old2.cid || !new2.cid) throw new Error('reverse-pair peers failed to boot');
+        await pair(new2, old2);
+        await roundTrip(new2, old2, 'reverse-pair first-contact new2→old2');
+      } finally {
+        await call(old2, 'exit').catch(() => {}); await call(new2, 'exit').catch(() => {});
+      } } },
+  { id: 'M2', gate: 'MP', dod: 'D1', name: 'first-contact message after redeem (new→old)',
+    run: async (ctx) => { await roundTrip(ctx.newPeer, ctx.oldPeer, 'first-contact new->old'); } },
+  { id: 'M3', gate: 'MP', dod: 'D1', name: 'steady-state send/receive both ways',
+    run: async (ctx) => {
+      await roundTrip(ctx.oldPeer, ctx.newPeer, 'steady old->new');
+      await roundTrip(ctx.newPeer, ctx.oldPeer, 'steady new->old'); } },
+  { id: 'M4', gate: 'MP', dod: 'D1', name: 'file transfer both ways',
+    run: async (ctx) => {
+      const data_b64 = Buffer.from('compat file payload').toString('base64');
+      await call(ctx.oldPeer, 'send_file', { cid: ctx.newPeer.cid, filename: 'from-old.txt', data_b64 });
+      await call(ctx.newPeer, 'send_file', { cid: ctx.oldPeer.cid, filename: 'from-new.txt', data_b64 });
+      await sleep(3000);
+      const fNew = String(await call(ctx.newPeer, 'files', { cid: ctx.oldPeer.cid }));
+      const fOld = String(await call(ctx.oldPeer, 'files', { cid: ctx.newPeer.cid }));
+      if (!fNew.includes('from-old.txt')) throw new Error('old→new file not received');
+      if (!fOld.includes('from-new.txt')) throw new Error('new→old file not received'); } },
+  { id: 'M5', gate: 'MP', dod: 'D1,D2', name: 'OLD restart: v0-blob export→reimport, channel resumes',
+    run: async (ctx) => {
+      await call(ctx.oldPeer, 'export_state', { file: resolve(OLD_DIR, 'state.bin') });
+      await ctx.respawn('oldPeer', true);
+      await roundTrip(ctx.newPeer, ctx.oldPeer, 'post-old-restart new->old'); } },
+  { id: 'M6', gate: 'MP', dod: 'D1,D2', name: 'NEW restart: stamped blob + DR-session restore',
+    run: async (ctx) => {
+      await call(ctx.newPeer, 'export_state', { file: resolve(NEW_DIR, 'state.bin') });
+      await ctx.respawn('newPeer', true);
+      await roundTrip(ctx.oldPeer, ctx.newPeer, 'post-new-restart old->new'); } },
+  { id: 'M7', gate: 'MP', dod: 'D1', name: 'NEW↔NEW DR handshake + ratchet + dual restart',
+    run: async () => {
+      const A = spawnPeer(NEW_DIR, 'newA', { PEER_SEED: 'compat newA seed' });
+      const B = spawnPeer(NEW_DIR, 'newB', { PEER_SEED: 'compat newB seed' });
+      try {
+        await A.readyP; await B.readyP;
+        if (!A.cid || !B.cid) throw new Error('M7 peers failed to boot');
+        const CAPS = { advertise: ['core.e2e', 'core.e2e.migrate'] };
+        await call(A, 'tx', { verb: '::actor::qa_init_caps', targ: CAPS });
+        await call(B, 'tx', { verb: '::actor::qa_init_caps', targ: CAPS });
+        await pair(A, B);
+        // Drive migration sweeps until the route flips to the double ratchet.
+        let route = '';
+        const deadline = Date.now() + 45000;
+        for (let i = 1; Date.now() < deadline && route !== 'e2e'; i++) {
+          await call(A, 'tx', { verb: '::a2a_messaging::sweep_e2e_migrations', targ: {} }).catch(() => {});
+          await call(B, 'tx', { verb: '::a2a_messaging::sweep_e2e_migrations', targ: {} }).catch(() => {});
+          await sleep(2000);
+          route = (await roundTrip(A, B, `dr-probe-${i}`))?.route ?? '';
+        }
+        if (route !== 'e2e') throw new Error(`route never reached e2e (last: ${route || 'legacy'})`);
+        // Ratchet advance both directions on the live session.
+        await roundTrip(A, B, 'dr-ratchet-a1', 'e2e');
+        await roundTrip(B, A, 'dr-ratchet-b1', 'e2e');
+        await roundTrip(A, B, 'dr-ratchet-a2', 'e2e');
+        // Dual restart with state — DR sessions must survive on BOTH ends.
+        await call(A, 'export_state', { file: resolve(NEW_DIR, 'stateA.bin') });
+        await call(B, 'export_state', { file: resolve(NEW_DIR, 'stateB.bin') });
+        await call(A, 'exit').catch(() => {}); await call(B, 'exit').catch(() => {});
+        await sleep(1000);
+        const A2 = spawnPeer(NEW_DIR, 'newA', { PEER_SEED: 'compat newA seed', PEER_STATE_FILE: resolve(NEW_DIR, 'stateA.bin') });
+        const B2 = spawnPeer(NEW_DIR, 'newB', { PEER_SEED: 'compat newB seed', PEER_STATE_FILE: resolve(NEW_DIR, 'stateB.bin') });
+        try {
+          await A2.readyP; await B2.readyP;
+          if (!A2.cid || !B2.cid) throw new Error('M7 respawn failed');
+          await sleep(2000);
+          await roundTrip(A2, B2, 'dr-post-restart-a');
+          await roundTrip(B2, A2, 'dr-post-restart-b');
+        } finally {
+          await call(A2, 'exit').catch(() => {}); await call(B2, 'exit').catch(() => {});
+        }
+      } finally {
+        await call(A, 'exit').catch(() => {}); await call(B, 'exit').catch(() => {});
+      } } },
+  { id: 'M8', gate: 'NTH', dod: 'D2', name: 'stale-snapshot restore → self-heal',
+    run: async () => { throw new Error('NOT IMPLEMENTED'); } },
+  { id: 'M9', gate: 'MP', dod: 'D2', name: 'corrupt blob import reject-to-functional (NEW)',
+    run: async (ctx) => {
+      await call(ctx.newPeer, 'export_state', { file: resolve(NEW_DIR, 'state.bin') });
+      const { readFileSync, writeFileSync } = await import('node:fs');
+      const good = readFileSync(resolve(NEW_DIR, 'state.bin'));
+      writeFileSync(resolve(NEW_DIR, 'state.bin'), good.subarray(0, Math.floor(good.length / 2)));
+      await ctx.respawn('newPeer', true);
+      const failed = ctx.newPeer.events.some((e) => String(e).startsWith('import_failed'));
+      if (!failed) throw new Error('corrupt blob did not surface import_failed');
+      // Reject-to-FUNCTIONAL: the fresh identity must still pair + message.
+      const inviteB64 = await call(ctx.oldPeer, 'invite', { name: 'renew' });
+      await call(ctx.newPeer, 'redeem', { invite_b64: inviteB64, name: 'oldpeer-again' });
+      const seen = await contactsInclude(ctx.newPeer, ctx.oldPeer.cid);
+      if (!seen) throw new Error('post-corruption re-pairing failed');
+      // Restore the good blob so later runs/legs are unaffected.
+      writeFileSync(resolve(NEW_DIR, 'state.bin'), good);
+    } },
+  { id: 'M10', gate: 'NTH', dod: 'D1', name: 'version_error_t as data',
+    run: async () => { throw new Error('NOT IMPLEMENTED — assertion pattern in tests/test.mjs V-series'); } },
+  { id: 'M11', gate: 'NTH', dod: 'D1', name: 'pv re-learning on peer downgrade',
+    run: async () => { throw new Error('NOT IMPLEMENTED'); } },
+];
+
+// ---- main ------------------------------------------------------------------
+const ctx = {
+  oldPeer: spawnPeer(OLD_DIR, 'oldpeer'),
+  newPeer: spawnPeer(NEW_DIR, 'newpeer'),
+  async respawn(ref, withState) {
+    const prev = ctx[ref];
+    await call(prev, 'exit').catch(() => {});
+    await sleep(1000);
+    const dir = ref === 'oldPeer' ? OLD_DIR : NEW_DIR;
+    ctx[ref] = spawnPeer(dir, prev.name,
+      withState ? { PEER_STATE_FILE: resolve(dir, 'state.bin') } : {});
+    await ctx[ref].readyP;
+    if (!ctx[ref].cid) throw new Error(`${prev.name} failed to respawn`);
+    await sleep(2000);
+  },
+};
+
+const results = [];
+await ctx.oldPeer.readyP; await ctx.newPeer.readyP;
+if (!ctx.oldPeer.cid || !ctx.newPeer.cid) { console.error('peer boot failed'); process.exit(1); }
+console.log(`peers up: old=${ctx.oldPeer.cid.slice(0, 10)} new=${ctx.newPeer.cid.slice(0, 10)}`);
+// LEG_FILTER=M7,M9 runs a subset (unlisted legs report as skipped-by-filter, never silently)
+const filter = (process.env.LEG_FILTER || '').split(',').filter(Boolean);
+for (const leg of LEGS) {
+  if (filter.length && !filter.includes(leg.id)) {
+    console.log(`  - ${leg.id} skipped by LEG_FILTER (not a verdict)`); continue;
+  }
+  try { await leg.run(ctx); results.push({ leg, pass: true }); console.log(`  ✓ ${leg.id} [${leg.gate}/${leg.dod}] ${leg.name}`); }
+  catch (err) { results.push({ leg, pass: false, err }); console.log(`  ✗ ${leg.id} [${leg.gate}/${leg.dod}] ${leg.name}: ${err.message}`); }
+}
+await call(ctx.oldPeer, 'exit').catch(() => {}); await call(ctx.newPeer, 'exit').catch(() => {});
+const mpFails = results.filter((r) => !r.pass && r.leg.gate === 'MP');
+console.log(`\n${results.filter((r) => r.pass).length}/${LEGS.length} legs passed; MP failures: ${mpFails.length} (${mpFails.map((r) => r.leg.id).join(', ') || 'none'})`);
+process.exit(mpFails.length ? 1 : 0);

package/mufl_code/core/tests/compat/compat_peer.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Per-process peer driver for the compat matrix. One process = one runtime = one packet.
+//
+// Loaded from a build dir whose node_modules symlink points at THIS peer's sdk era and
+// whose cwd holds THIS peer's compiled unit — the orchestrator (compat.mjs) never mixes
+// runtimes in-process. Commands arrive as JSON lines on stdin; every command produces
+// exactly one JSON line on stdout: {id, ok, value?, error?}. Async inbound traffic is
+// surfaced via unsolicited {event} lines. Boot/mutate/ro shapes mirror tests/test_common.mjs
+// (the era-stable driver conventions: add_client_message + on_return_data pending queue).
+import { resolve } from 'node:path';
+import * as fs from 'node:fs';
+import * as readline from 'node:readline';
+import { adapt_wrapper } from '@adapt-toolkit/sdk/executables';
+import { PacketWrapperConfigurator } from '@adapt-toolkit/sdk/wrappers';
+import { object_to_adapt_value } from '@adapt-toolkit/sdk/wrapper';
+
+const BROKER_URL = process.env.BROKER_URL || 'ws://127.0.0.1:9797';
+const SEED = process.env.PEER_SEED || `compat seed ${process.env.PEER_NAME || 'peer'}`;
+const STATE_FILE = process.env.PEER_STATE_FILE || ''; // set ⇒ import on boot if present
+// PEER_FLAVOR=messenger switches the READ verbs to the control-plane messenger
+// surface (history keyed per contact via ::actor::get_conversation). The whole
+// ::a2a_messaging:: WRITE surface (invite/redeem/send/send_file) is shared.
+const FLAVOR = process.env.PEER_FLAVOR || 'actor';
+const UNIT_DIR = resolve('.');
+const unitHash = fs.readdirSync(UNIT_DIR).find((f) => f.endsWith('.muflo')).slice(0, -'.muflo'.length);
+const UNIT = new Uint8Array(fs.readFileSync(resolve(UNIT_DIR, `${unitHash}.muflo`)));
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const out = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+const pending = [];
+let pw = null;
+
+function wire() {
+  pw.on_return_data = (d) => {
+    const kind = d.Reduce('kind').Visualize();
+    if (kind === 'notify_agent') {
+      try { out({ event: d.Reduce('payload').Reduce('event').Visualize() }); } catch { out({ event: 'unparsed' }); }
+      return;
+    }
+    if (kind === 'save_state') return;
+    const w = pending.shift(); if (!w) return;
+    clearTimeout(w.timer); w.resolve(d.Reduce('payload'));
+  };
+  pw.on_transaction_failure = (msg) => {
+    const w = pending.shift();
+    if (w) { clearTimeout(w.timer); w.reject(new Error(msg)); }
+    else out({ event: `inbound-reject: ${String(msg).split('\n')[0]}` });
+  };
+}
+
+function mutate(name, targ) {
+  return new Promise((res, rej) => {
+    const timer = setTimeout(() => { rej(new Error(`timeout: ${name}`)); }, 20000);
+    pending.push({ resolve: res, reject: rej, timer });
+    pw.add_client_message(object_to_adapt_value({ name, targ }));
+  });
+}
+const ro = (name, targ) => pw.packet.ExecuteTransaction(object_to_adapt_value({ name, targ }));
+const binv = (buf) => pw.packet.NewBinaryFromBuffer(Buffer.from(buf));
+
+async function boot() {
+  const wrapper = await adapt_wrapper.start(['--broker_address', BROKER_URL, '--test_mode',
+    '--logger_config', '--level', 'WARNING', '--stdout', 'stderr', '--logger_config_end']);
+  wrapper.start();
+  await sleep(1500);
+  const cfg = new PacketWrapperConfigurator();
+  cfg.process_arguments(['--unit_hash', unitHash, '--seed_phrase', SEED, '--unit_dir_path', UNIT_DIR]);
+  await new Promise((res, rej) => {
+    const t = setTimeout(() => rej(new Error('create timeout')), 30000);
+    wrapper.packet_manager.create_packet(cfg, (p) => { clearTimeout(t); pw = p; wire(); res(); }, UNIT);
+  });
+  if (STATE_FILE && fs.existsSync(STATE_FILE)) {
+    // Import failure must not kill the peer — mirror the consumer posture
+    // (tg-connector: continue with the fresh identity, blob preserved): the
+    // M9 leg asserts exactly this reject-to-functional behavior.
+    try {
+      const bytes = fs.readFileSync(STATE_FILE);
+      await mutate('::actor::import_state', pw.packet.ParseValue(new Uint8Array(bytes)));
+      out({ event: 'state_imported' });
+    } catch (err) {
+      out({ event: `import_failed: ${String(err).split('\n')[0]}` });
+    }
+  }
+  out({ ready: true, cid: pw.packet.GetContainerID().Visualize() });
+}
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  let cmd;
+  try { cmd = JSON.parse(line); } catch { return out({ id: null, ok: false, error: 'bad json' }); }
+  const { id, op } = cmd;
+  try {
+    switch (op) {
+      case 'invite': {
+        const m = await mutate('::a2a_messaging::generate_invite', { name: cmd.name });
+        return out({ id, ok: true, value: Buffer.from(m.Reduce('invite').GetBinary()).toString('base64') });
+      }
+      case 'redeem': {
+        await mutate('::a2a_messaging::add_contact',
+          { invite: binv(Buffer.from(cmd.invite_b64, 'base64')), name: cmd.name });
+        return out({ id, ok: true });
+      }
+      case 'send': {
+        const m = await mutate('::a2a_messaging::send_message', { contact: cmd.cid, text: cmd.text });
+        // route: 'e2e' (double ratchet) | 'migrating' | absent/NIL = legacy box
+        return out({ id, ok: true, value: { wire_id: m.Reduce('wire_id').Visualize(), route: m.Reduce('route').Visualize() } });
+      }
+      case 'tx': {
+        const m = await mutate(cmd.verb, cmd.targ);
+        return out({ id, ok: true, value: m ? m.Visualize() : null });
+      }
+      case 'send_file': {
+        const m = await mutate('::a2a_messaging::send_file', {
+          contact: cmd.cid, filename: cmd.filename, mime: cmd.mime || 'application/octet-stream',
+          data: binv(Buffer.from(cmd.data_b64, 'base64')),
+        });
+        return out({ id, ok: true, value: m.Reduce('wire_id').Visualize() });
+      }
+      case 'contacts': return out({ id, ok: true, value: ro('::a2a_messaging::list_contacts', undefined).Visualize() });
+      case 'inbox': {
+        if (FLAVOR === 'messenger') {
+          return out({ id, ok: true, value: ro('::actor::get_conversation', { contact: cmd.cid }).Visualize() });
+        }
+        return out({ id, ok: true, value: ro('::actor::list_incoming_messages', undefined).Visualize() });
+      }
+      case 'files': {
+        if (FLAVOR === 'messenger') {
+          // messenger file receipts land as history entries carrying $filename
+          return out({ id, ok: true, value: ro('::actor::get_conversation', { contact: cmd.cid }).Visualize() });
+        }
+        return out({ id, ok: true, value: ro('::actor::list_incoming_files', undefined).Visualize() });
+      }
+      case 'export_state': {
+        const exported = ro('::actor::export_state', undefined);
+        fs.writeFileSync(cmd.file, Buffer.from(exported.Serialize()));
+        return out({ id, ok: true });
+      }
+      case 'exit': out({ id, ok: true }); return process.exit(0);
+      default: return out({ id, ok: false, error: `unknown op ${op}` });
+    }
+  } catch (err) {
+    return out({ id, ok: false, error: String(err) });
+  }
+});
+
+boot().catch((e) => { out({ fatal: String(e) }); process.exit(1); });

package/mufl_code/core/tests/compat/run_compat.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Cross-version compat matrix: build TWO units — OLD core (git ref, OLD-era toolchain) and
+# NEW core (this working tree, current toolchain) — each in its own build dir with its own
+# node_modules symlink, boot ONE broker, run tests/compat/compat.mjs against the pair.
+# See tests/compat/README.md for the env contract and leg inventory.
+#
+# Toolchain dirs auto-detect flavor (owner ruling: the OLD side should be the PUBLISHED
+# @adapt-toolkit packages production actually pinned, not a from-scratch build):
+#   - npm @adapt-toolkit/mufl package root  → prebuilds/linux-x64/mufl-compile
+#   - adapt toolkit checkout                → build.<platform>.release/mufl-compile
+set -u
+HERE=$(cd "$(dirname "$0")" && pwd)
+CORE_DIR=$(cd "$HERE/../.." && pwd)
+
+OLD_CORE_REF=${OLD_CORE_REF:-v0.2.0}
+OLD_TOOLCHAIN=${OLD_TOOLCHAIN:?set OLD_TOOLCHAIN (npm @adapt-toolkit/mufl pkg root of the OLD era, e.g. <stage>/node_modules/@adapt-toolkit/mufl — or an old toolkit checkout)}
+OLD_SDK_NM=${OLD_SDK_NM:?set OLD_SDK_NM (node_modules with the OLD-era @adapt-toolkit sdk, e.g. sdk@0.9.1)}
+NEW_TOOLCHAIN=${NEW_TOOLCHAIN:-${ADAPT_TOOLKIT:-}}
+[ -n "$NEW_TOOLCHAIN" ] || { echo "set NEW_TOOLCHAIN (current @adapt-toolkit/mufl pkg root or toolkit checkout)"; exit 2; }
+SDK_NM=${OURS_SDK_NODE_MODULES:?set OURS_SDK_NODE_MODULES (current sdk node_modules)}
+DEV_BROKER=${DEV_BROKER:?set DEV_BROKER (dev-broker.mjs launcher)}
+PORT=${PORT:-9797}
+
+# resolve_toolchain <dir> → sets RESOLVED_COMPILE / RESOLVED_ROOT
+resolve_toolchain() {
+  local dir=$1 platform
+  platform="$(uname | tr '[:upper:]' '[:lower:]')"
+  for cand in "$dir/prebuilds/linux-x64/mufl-compile" \
+              "$dir/build/mufl-compile" \
+              "$dir/build.$platform.release/mufl-compile"; do
+    if [ -x "$cand" ]; then RESOLVED_COMPILE="$cand"; RESOLVED_ROOT="$dir"; return 0; fi
+  done
+  echo "MISSING: no mufl-compile under $dir"; exit 2
+}
+
+for p in "$OLD_SDK_NM/@adapt-toolkit" "$SDK_NM/@adapt-toolkit" "$DEV_BROKER"; do
+  [ -e "$p" ] || { echo "MISSING: $p"; exit 2; }
+done
+
+WORK=$(mktemp -d); echo "WORK=$WORK (kept for post-mortem when KEEP_WORK=1)"; if [ "${KEEP_WORK:-0}" = "1" ]; then trap '[ -n "${BROKER_PID:-}" ] && kill "$BROKER_PID" 2>/dev/null' EXIT; else trap 'rm -rf "$WORK"; [ -n "${BROKER_PID:-}" ] && kill "$BROKER_PID" 2>/dev/null' EXIT; fi
+
+# build_unit <outdir> <core_src_dir> <toolchain_dir> <sdk_nm>
+# Uses the era's OWN tests/test_actor.mu + protocol_container.mm (the actor surface
+# matches its core), same compile shape as tests/run.sh / consumer compile-mufl.sh.
+build_unit() {
+  local out=$1 src=$2 tk=$3 nm=$4
+  resolve_toolchain "$tk"
+  mkdir -p "$out/core"
+  cp "$src"/*.mm "$out/core/"; cp "$src/config.mufl" "$out/core/" 2>/dev/null || true
+  cp "$src/tests/test_actor.mu" "$out/actor.mu"
+  # Cross-process peers must REGISTER with the broker (single-wrapper suites
+  # deliver locally and never need this): inject registration_proof, which the
+  # real consumer actors (messenger.mu, tg actor.mu) load explicitly and the
+  # core test actors deliberately omit. Without it, registration-message
+  # creation fails client-side and no traffic ever crosses the broker.
+  sed -i '0,/loads libraries/s//loads libraries\n    registration_proof,/' "$out/actor.mu"
+  if [ -f "$src/tests/protocol_container.mm" ]; then cp "$src/tests/protocol_container.mm" "$out/"
+  else cp "$CORE_DIR/tests/protocol_container.mm" "$out/"; fi
+  ln -sfn "$nm" "$out/node_modules"
+  cp "$HERE/compat_peer.mjs" "$out/"
+  cat > "$out/config.mufl" <<'CFG'
+config script
+{
+    stdlib_config = (config_load #$MUFL_STDLIB_PATH).
+    core_config = (config_load #"core").
+    (
+        $imports ->
+        (
+            $libraries -> (stdlib_config $exports $libraries)'(core_config $exports $libraries)'($protocol_container -> #"protocol_container.mm"),
+        ),
+        $exports -> ( $libraries -> (,), $applications -> (,) )
+    ).
+}
+CFG
+  ( cd "$out" && MUFL_STDLIB_PATH="$RESOLVED_ROOT/mufl_stdlib" "$RESOLVED_COMPILE" \
+      -mp "$RESOLVED_ROOT/meta" -mp "$RESOLVED_ROOT/transactions" -d-c actor.mu >/dev/null ) \
+    || { echo "COMPILE FAILED in $out"; exit 3; }
+}
+
+echo "== building OLD unit ($OLD_CORE_REF, $(basename "$OLD_TOOLCHAIN")) =="
+OLD_SRC="$WORK/old-src"; mkdir -p "$OLD_SRC"
+git -C "$CORE_DIR" archive "$OLD_CORE_REF" | tar -x -C "$OLD_SRC"
+build_unit "$WORK/old" "$OLD_SRC" "$OLD_TOOLCHAIN" "$OLD_SDK_NM"
+
+echo "== building NEW unit (working tree, $(basename "$NEW_TOOLCHAIN")) =="
+build_unit "$WORK/new" "$CORE_DIR" "$NEW_TOOLCHAIN" "$SDK_NM"
+
+echo "== broker on :$PORT =="
+# dev-broker contract: --host/--port REQUIRED, --test_mode skips attestation. Runs under
+# the NEW sdk (cwd with the current node_modules) — the broker relays opaque frames, so
+# one broker serves both eras.
+( cd "$WORK/new" && node "$DEV_BROKER" --host 127.0.0.1 --port "$PORT" --test_mode ) & BROKER_PID=$!
+sleep 2
+
+BROKER_URL="ws://127.0.0.1:$PORT" OLD_BUILD_DIR="$WORK/old" NEW_BUILD_DIR="$WORK/new" \
+  node "$HERE/compat.mjs"