@mindrian_os/install 1.13.0-beta.11

package/lib/hmi/across-session-memory.cjs

@@ -0,0 +1,604 @@
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 103-02 -- Across-session memory layer (HMI-103-01).
+ *
+ * Read/write module for Layer 2 of the Mindrian three-layer memory model.
+ * Layer 1 (within-session) is owned by Phase 100 lib/hmi/jtbd-state.cjs.
+ * Layer 3 (cross-room) is built on top of this module by Phase 103-03
+ * lib/hmi/cross-room-memory.cjs.
+ *
+ * Storage: ~/MindrianRooms/.memory/jtbd-history.json (or MINDRIAN_ROOMS_HOME
+ * env override for hermetic tests).
+ *
+ * Concurrency: O_EXCL lockfile + 2s TTL stale-lock recovery + 200ms retry
+ * budget + content-merge fallback (RESEARCH §2.2). Two simultaneous Stop
+ * hooks in two rooms can race for the global file; the lockfile ensures
+ * neither write is lost.
+ *
+ * Canon Part 4: every promote/park/complete also intends a typed graph
+ * edge in the LOCAL graph. Phase 103-02 ships the side-log stub; Phase
+ * 103-05 wires the actual room-db.cjs HAS_JTBD edge write.
+ *
+ * Canon Part 8: this module does not query Brain. cross-room-memory.cjs
+ * (Phase 103-03) does, via Phase 90's buildBrainQueryContext chokepoint.
+ *
+ * D-01 invariant: this module NEVER writes to <roomDir>/.mindrian/
+ * jtbd-state.json. Phase 100 owns the within-session file. We READ it via
+ * jtbd-state.cjs to detect eligible transitions; the only writes go to
+ * ~/MindrianRooms/.memory/jtbd-history.json and audit.log.
+ *
+ * Pure CJS, Node built-ins only, zero new runtime dependencies (Phase 87
+ * invariant). Graceful degradation: every public function wraps body in
+ * try/catch; errors log to stderr and the function returns null/undefined
+ * safely (never throws upward).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// ---------------------------------------------------------------------
+// Path resolution (every call re-reads MINDRIAN_ROOMS_HOME so hermetic
+// tests can swap the root between calls without module reload).
+// ---------------------------------------------------------------------
+
+function ROOMS_HOME() {
+  return process.env.MINDRIAN_ROOMS_HOME || path.join(os.homedir(), 'MindrianRooms');
+}
+function MEMORY_DIR()    { return path.join(ROOMS_HOME(), '.memory'); }
+function MEMORY_FILE()   { return path.join(MEMORY_DIR(), 'jtbd-history.json'); }
+function ARCHIVE_FILE()  { return path.join(MEMORY_DIR(), 'jtbd-history.archive.json'); }
+function AUDIT_FILE()    { return path.join(MEMORY_DIR(), 'audit.log'); }
+function LOCK_FILE()     { return MEMORY_FILE() + '.lock'; }
+function OPT_OUT_FILE()  { return path.join(MEMORY_DIR(), '.opt-out'); }
+function ROOM_MD_FILE()  { return path.join(MEMORY_DIR(), 'ROOM.md'); }
+function GRAPH_EDGE_LOG(){ return path.join(MEMORY_DIR(), 'graph-edge-pending.log'); }
+function REGISTRY_FILE() { return path.join(ROOMS_HOME(), '.rooms', 'registry.json'); }
+
+// ---------------------------------------------------------------------
+// Constants.
+// ---------------------------------------------------------------------
+
+const LOCK_TTL_MS = 2000;
+const RETRY_BUDGET_MS = 200;
+const RETRY_SPIN_MS = 5;
+const PER_ROOM_ARRAY_BOUND = 100;
+const AUDIT_LOG_HARD_BOUND = 10000;
+const AUDIT_LOG_FLOOR = 9000;
+const ROOM_MEMORY_SCHEMA_VERSION = 1;
+const NOISE_FLOOR_TURNS = 3;
+const NOISE_FLOOR_CONFIDENCE = 0.6;
+
+// ---------------------------------------------------------------------
+// Helpers.
+// ---------------------------------------------------------------------
+
+function logStderr(scope, err) {
+  try {
+    const msg = err && err.message ? String(err.message) : String(err);
+    process.stderr.write('[across-session-memory] ' + scope + ': ' + msg.slice(0, 200) + '\n');
+  } catch (_) { /* swallow logger error */ }
+}
+
+function ensureDir() {
+  const dir = MEMORY_DIR();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  // Decision #15: every directory gets a ROOM.md.
+  if (!fs.existsSync(ROOM_MD_FILE())) {
+    const body = [
+      '---',
+      'type: directory-identity',
+      'name: .memory',
+      'section: .memory',
+      'purpose: Across-session memory layer (Phase 103). Per-USER, NOT per-team.',
+      'founding_phase: 103',
+      'phase: 103',
+      'milestone: v1.12.3',
+      'canon_parts: [4, 8]',
+      'created: 2026-05-01',
+      'scope: per-USER (NOT per-team; Cowork users each have their own home)',
+      '---',
+      '',
+      '# .memory -- Across-Session Memory Layer (Phase 103)',
+      '',
+      'This directory is the home for the Mindrian across-session memory layer (Layer 2 of the three-layer memory model).',
+      '',
+      '- jtbd-history.json: per-room in_flight / parked / completed JTBD aggregation. Survives Claude Code restarts.',
+      '- jtbd-history.archive.json: spillover when per-room arrays exceed 100 entries.',
+      '- audit.log: one line per write (FIFO bounded at 10000 lines).',
+      '- .opt-out: sentinel file. When present, all writes are no-ops (Gate 2 escape valve).',
+      '- graph-edge-pending.log: side-log of intended Canon Part 4 graph edges. Drained by Phase 103-05 PostToolUse.',
+      '',
+      '## Privacy contract',
+      '',
+      'This layer is per-USER. NOT per-team. In Cowork, each user has their own ~/MindrianRooms/.memory/ scoped to their home directory. Team-shared memory is out of scope (Canon Part 8 cross-user reasoning).',
+      '',
+      '## Disable',
+      '',
+      'Global: `touch ~/MindrianRooms/.memory/.opt-out` (or `/mos:memory --opt-out`).',
+      'Per-room: `touch <roomDir>/.mindrian/.memory-opt-out`.',
+      '',
+    ].join('\n');
+    try {
+      fs.writeFileSync(ROOM_MD_FILE(), body);
+    } catch (err) {
+      logStderr('ensureDir ROOM.md write', err);
+    }
+  }
+}
+
+function readJsonOrEmpty(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    return { version: ROOM_MEMORY_SCHEMA_VERSION, rooms: {}, last_updated: null };
+  }
+}
+
+function spinSleep(ms) {
+  const until = Date.now() + ms;
+  while (Date.now() < until) { /* busy-wait */ }
+}
+
+// ---------------------------------------------------------------------
+// Atomic update with O_EXCL lockfile (load-bearing).
+// ---------------------------------------------------------------------
+
+function atomicUpdateMemory(updateFn) {
+  ensureDir();
+  const filePath = MEMORY_FILE();
+  const lockPath = LOCK_FILE();
+  const tmpPath = filePath + '.tmp.' + process.pid + '.' + Date.now().toString(36);
+
+  const startedAt = Date.now();
+  let lockAcquired = false;
+
+  while (Date.now() - startedAt < RETRY_BUDGET_MS) {
+    let fd;
+    try {
+      fd = fs.openSync(
+        lockPath,
+        fs.constants.O_EXCL | fs.constants.O_CREAT | fs.constants.O_WRONLY
+      );
+      try { fs.writeSync(fd, String(process.pid)); } catch (_) { /* non-fatal */ }
+      try { fs.closeSync(fd); } catch (_) { /* non-fatal */ }
+      lockAcquired = true;
+      break;
+    } catch (err) {
+      if (err && err.code !== 'EEXIST') {
+        logStderr('lock open', err);
+        break;
+      }
+      // Stale-lock recovery: if the existing lock is older than TTL, unlink it.
+      try {
+        const lockStat = fs.statSync(lockPath);
+        if (Date.now() - lockStat.mtimeMs > LOCK_TTL_MS) {
+          try { fs.unlinkSync(lockPath); } catch (_) { /* race; just continue */ }
+          continue;
+        }
+      } catch (_) { /* stat race; continue */ }
+      spinSleep(RETRY_SPIN_MS);
+    }
+  }
+
+  if (!lockAcquired) {
+    return atomicUpdateMemoryUnsafe(updateFn);
+  }
+
+  try {
+    const cur = readJsonOrEmpty(filePath);
+    const next = updateFn(cur) || cur;
+    next.last_updated = new Date().toISOString();
+    if (!next.version) next.version = ROOM_MEMORY_SCHEMA_VERSION;
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2) + '\n');
+    fs.renameSync(tmpPath, filePath);
+    return next;
+  } catch (err) {
+    logStderr('atomic write', err);
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    return null;
+  } finally {
+    try { fs.unlinkSync(lockPath); } catch (_) { /* best-effort */ }
+  }
+}
+
+function atomicUpdateMemoryUnsafe(updateFn) {
+  // Lock-failed fallback: read-merge-write without lock. Worst case: 1 update
+  // is overwritten by a racing process. Better than throwing.
+  ensureDir();
+  const filePath = MEMORY_FILE();
+  const tmpPath = filePath + '.tmp.unsafe.' + process.pid + '.' + Date.now().toString(36);
+  try {
+    const cur = readJsonOrEmpty(filePath);
+    const next = updateFn(cur) || cur;
+    next.last_updated = new Date().toISOString();
+    if (!next.version) next.version = ROOM_MEMORY_SCHEMA_VERSION;
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2) + '\n');
+    fs.renameSync(tmpPath, filePath);
+    return next;
+  } catch (err) {
+    logStderr('atomic write (unsafe fallback)', err);
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------
+// Opt-out checks (D-16, D-17).
+// ---------------------------------------------------------------------
+
+function isGlobalOptOut() {
+  try { return fs.existsSync(OPT_OUT_FILE()); } catch (_) { return false; }
+}
+
+function isRoomOptOut(roomSlug) {
+  try {
+    if (!roomSlug || typeof roomSlug !== 'string') return false;
+    const reg = readJsonOrEmpty(REGISTRY_FILE());
+    const rooms = (reg && Array.isArray(reg.rooms)) ? reg.rooms : [];
+    const r = rooms.find(x => x && x.slug === roomSlug);
+    let roomDir = null;
+    if (r && r.path) {
+      roomDir = path.isAbsolute(r.path) ? r.path : path.join(ROOMS_HOME(), r.path);
+    } else {
+      // Defensive fallback: assume slug-equals-folder under ROOMS_HOME.
+      roomDir = path.join(ROOMS_HOME(), roomSlug);
+    }
+    return fs.existsSync(path.join(roomDir, '.mindrian', '.memory-opt-out'));
+  } catch (_) { return false; }
+}
+
+// ---------------------------------------------------------------------
+// Audit log + FIFO truncation (D-18, RESEARCH §7).
+// ---------------------------------------------------------------------
+
+function appendAudit(roomSlug, action, jtbd) {
+  try {
+    if (isGlobalOptOut()) return;
+    ensureDir();
+    const line = [new Date().toISOString(), roomSlug, action, jtbd].join(' | ');
+    fs.appendFileSync(AUDIT_FILE(), line + '\n');
+    // Periodic FIFO truncation (1% sample rate per RESEARCH §7).
+    if (Math.random() < 0.01) {
+      truncateAuditIfNeeded();
+    }
+  } catch (err) {
+    logStderr('appendAudit', err);
+  }
+}
+
+function truncateAuditIfNeeded() {
+  try {
+    if (!fs.existsSync(AUDIT_FILE())) return;
+    const raw = fs.readFileSync(AUDIT_FILE(), 'utf8');
+    const lines = raw.split('\n');
+    // Drop trailing empty line introduced by final \n
+    const realCount = lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+    if (realCount < AUDIT_LOG_HARD_BOUND) return;
+    const keep = lines.slice(realCount - AUDIT_LOG_FLOOR, realCount);
+    const tmp = AUDIT_FILE() + '.tmp.' + process.pid + '.' + Date.now().toString(36);
+    fs.writeFileSync(tmp, keep.join('\n') + '\n');
+    fs.renameSync(tmp, AUDIT_FILE());
+  } catch (err) {
+    logStderr('truncateAuditIfNeeded', err);
+  }
+}
+
+// ---------------------------------------------------------------------
+// Archive rotation (per-room arrays bounded at 100).
+// ---------------------------------------------------------------------
+
+function trimAndArchive(mem, roomSlug) {
+  const room = mem && mem.rooms && mem.rooms[roomSlug];
+  if (!room) return;
+  for (const stateKey of ['in_flight', 'parked', 'completed']) {
+    const arr = room[stateKey];
+    if (Array.isArray(arr) && arr.length > PER_ROOM_ARRAY_BOUND) {
+      const overflow = arr.slice(0, arr.length - PER_ROOM_ARRAY_BOUND);
+      room[stateKey] = arr.slice(arr.length - PER_ROOM_ARRAY_BOUND);
+      appendArchive(roomSlug, stateKey, overflow);
+    }
+  }
+}
+
+function appendArchive(roomSlug, stateKey, overflow) {
+  try {
+    ensureDir();
+    const archivePath = ARCHIVE_FILE();
+    let cur;
+    try { cur = JSON.parse(fs.readFileSync(archivePath, 'utf8')); } catch (_) { cur = { version: ROOM_MEMORY_SCHEMA_VERSION, rooms: {} }; }
+    if (!cur.rooms) cur.rooms = {};
+    if (!cur.rooms[roomSlug]) cur.rooms[roomSlug] = { in_flight: [], parked: [], completed: [] };
+    if (!Array.isArray(cur.rooms[roomSlug][stateKey])) cur.rooms[roomSlug][stateKey] = [];
+    cur.rooms[roomSlug][stateKey].push.apply(cur.rooms[roomSlug][stateKey], overflow);
+    const tmp = archivePath + '.tmp.' + process.pid + '.' + Date.now().toString(36);
+    fs.writeFileSync(tmp, JSON.stringify(cur, null, 2) + '\n');
+    fs.renameSync(tmp, archivePath);
+  } catch (err) {
+    logStderr('appendArchive', err);
+  }
+}
+
+// ---------------------------------------------------------------------
+// Canon Part 4 graph-edge stub.
+// Phase 103-05 wires this to lib/core/room-db.cjs HAS_JTBD edges. Until
+// then, append intent to a side-log so the Canon Part 4 connection is
+// auditable post-facto.
+// ---------------------------------------------------------------------
+
+function writeGraphEdge(action, roomSlug, jtbd, props) {
+  try {
+    ensureDir();
+    const line = JSON.stringify({
+      action: action,
+      roomSlug: roomSlug,
+      jtbd: jtbd,
+      props: props || {},
+      ts: new Date().toISOString(),
+    });
+    fs.appendFileSync(GRAPH_EDGE_LOG(), line + '\n');
+  } catch (err) {
+    logStderr('writeGraphEdge', err);
+  }
+}
+
+// ---------------------------------------------------------------------
+// Public API: promoteIfEligible (D-06).
+// ---------------------------------------------------------------------
+
+function promoteIfEligible(roomSlug, withinSessionState) {
+  try {
+    if (!roomSlug || typeof roomSlug !== 'string') return null;
+    if (isGlobalOptOut()) return null;
+    if (isRoomOptOut(roomSlug)) return null;
+    if (!withinSessionState || !withinSessionState.current || !withinSessionState.current.jtbd) return null;
+
+    const cur = withinSessionState.current;
+    const turnCount = (typeof cur.turn_count === 'number')
+      ? cur.turn_count
+      : ((withinSessionState.history || []).filter(h => h && h.to === cur.jtbd).length);
+    const manual = cur.manual_set === true || cur.trigger === 'manual';
+
+    // D-06: >= 3 turns OR manual override
+    if (!manual && turnCount < NOISE_FLOOR_TURNS) return null;
+    // Confidence noise floor (auto only; manual bypasses)
+    if (!manual && (typeof cur.confidence === 'number' ? cur.confidence : 0) < NOISE_FLOOR_CONFIDENCE) return null;
+
+    const now = new Date().toISOString();
+    const result = atomicUpdateMemory(function (mem) {
+      if (!mem.rooms) mem.rooms = {};
+      if (!mem.rooms[roomSlug]) {
+        mem.rooms[roomSlug] = { in_flight: [], parked: [], completed: [] };
+      }
+      const room = mem.rooms[roomSlug];
+      if (!Array.isArray(room.in_flight)) room.in_flight = [];
+      if (!Array.isArray(room.parked)) room.parked = [];
+      if (!Array.isArray(room.completed)) room.completed = [];
+      const existing = room.in_flight.find(r => r.jtbd === cur.jtbd);
+      if (existing) {
+        existing.last_seen = now;
+        existing.turn_count = turnCount;
+        existing.confidence_avg = (typeof cur.confidence === 'number') ? cur.confidence : existing.confidence_avg;
+      } else {
+        room.in_flight.push({
+          jtbd: cur.jtbd,
+          first_seen: now,
+          last_seen: now,
+          confidence_avg: (typeof cur.confidence === 'number') ? cur.confidence : 0,
+          turn_count: turnCount,
+          manual_set: manual,
+          evidence_summary: Array.isArray(cur.evidence) ? cur.evidence.slice(0, 5) : [],
+        });
+        trimAndArchive(mem, roomSlug);
+      }
+      return mem;
+    });
+
+    if (result === null) return null;
+
+    appendAudit(roomSlug, 'promote', cur.jtbd);
+    writeGraphEdge('promote', roomSlug, cur.jtbd, { state: 'in_flight', ts: now });
+    return { action: 'promoted', jtbd: cur.jtbd };
+  } catch (err) {
+    logStderr('promoteIfEligible', err);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------
+// Public API: parkJtbd (D-07).
+// ---------------------------------------------------------------------
+
+function parkJtbd(roomSlug, jtbd, reason) {
+  try {
+    if (!roomSlug || !jtbd) return null;
+    if (isGlobalOptOut()) return null;
+    if (isRoomOptOut(roomSlug)) return null;
+    const now = new Date().toISOString();
+    const reasonStr = (typeof reason === 'string' && reason.length) ? reason : 'unspecified';
+
+    const result = atomicUpdateMemory(function (mem) {
+      if (!mem.rooms) mem.rooms = {};
+      if (!mem.rooms[roomSlug]) {
+        mem.rooms[roomSlug] = { in_flight: [], parked: [], completed: [] };
+      }
+      const room = mem.rooms[roomSlug];
+      if (!Array.isArray(room.in_flight)) room.in_flight = [];
+      if (!Array.isArray(room.parked)) room.parked = [];
+      const idx = room.in_flight.findIndex(x => x.jtbd === jtbd);
+      const moved = (idx >= 0) ? room.in_flight.splice(idx, 1)[0] : { jtbd: jtbd };
+      moved.parked_at = now;
+      moved.reason = reasonStr;
+      room.parked.push(moved);
+      trimAndArchive(mem, roomSlug);
+      return mem;
+    });
+
+    if (result === null) return null;
+
+    appendAudit(roomSlug, 'park', jtbd);
+    writeGraphEdge('park', roomSlug, jtbd, { state: 'parked', reason: reasonStr, ts: now });
+    return { action: 'parked', jtbd: jtbd };
+  } catch (err) {
+    logStderr('parkJtbd', err);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------
+// Public API: completeJtbd (D-08).
+// ---------------------------------------------------------------------
+
+function completeJtbd(roomSlug, jtbd, completionShape, completionEvidence) {
+  try {
+    if (!roomSlug || !jtbd) return null;
+    if (isGlobalOptOut()) return null;
+    if (isRoomOptOut(roomSlug)) return null;
+    const now = new Date().toISOString();
+
+    const result = atomicUpdateMemory(function (mem) {
+      if (!mem.rooms) mem.rooms = {};
+      if (!mem.rooms[roomSlug]) {
+        mem.rooms[roomSlug] = { in_flight: [], parked: [], completed: [] };
+      }
+      const room = mem.rooms[roomSlug];
+      if (!Array.isArray(room.in_flight)) room.in_flight = [];
+      if (!Array.isArray(room.completed)) room.completed = [];
+      const idx = room.in_flight.findIndex(x => x.jtbd === jtbd);
+      const moved = (idx >= 0) ? room.in_flight.splice(idx, 1)[0] : { jtbd: jtbd };
+      moved.completed_at = now;
+      moved.completion_shape = completionShape || null;
+      moved.completion_evidence = (typeof completionEvidence === 'string') ? completionEvidence : null;
+      room.completed.push(moved);
+      trimAndArchive(mem, roomSlug);
+      return mem;
+    });
+
+    if (result === null) return null;
+
+    appendAudit(roomSlug, 'complete', jtbd);
+    writeGraphEdge('complete', roomSlug, jtbd, {
+      state: 'completed',
+      completion_shape: completionShape || null,
+      completion_evidence: (typeof completionEvidence === 'string') ? completionEvidence : null,
+      ts: now,
+    });
+    return { action: 'completed', jtbd: jtbd };
+  } catch (err) {
+    logStderr('completeJtbd', err);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------
+// Public API: read-only helpers.
+// ---------------------------------------------------------------------
+
+function getRoomMemory(roomSlug) {
+  try {
+    const mem = readJsonOrEmpty(MEMORY_FILE());
+    if (!mem || !mem.rooms || !mem.rooms[roomSlug]) {
+      return { in_flight: [], parked: [], completed: [] };
+    }
+    const r = mem.rooms[roomSlug];
+    return {
+      in_flight: Array.isArray(r.in_flight) ? r.in_flight : [],
+      parked:    Array.isArray(r.parked) ? r.parked : [],
+      completed: Array.isArray(r.completed) ? r.completed : [],
+    };
+  } catch (err) {
+    logStderr('getRoomMemory', err);
+    return { in_flight: [], parked: [], completed: [] };
+  }
+}
+
+function listInFlight(maxAgeDays) {
+  try {
+    const ageDays = (typeof maxAgeDays === 'number') ? maxAgeDays : 7;
+    const cutoff = Date.now() - ageDays * 24 * 60 * 60 * 1000;
+    const mem = readJsonOrEmpty(MEMORY_FILE());
+    const out = [];
+    if (!mem || !mem.rooms) return out;
+    for (const slug of Object.keys(mem.rooms)) {
+      const room = mem.rooms[slug];
+      if (!room || !Array.isArray(room.in_flight)) continue;
+      for (const row of room.in_flight) {
+        const lastSeen = Date.parse(row && row.last_seen);
+        if (Number.isFinite(lastSeen) && lastSeen >= cutoff) {
+          out.push({
+            room: slug,
+            jtbd: row.jtbd,
+            last_seen: row.last_seen,
+            confidence_avg: row.confidence_avg,
+            turn_count: row.turn_count,
+          });
+        }
+      }
+    }
+    out.sort((a, b) => Date.parse(b.last_seen) - Date.parse(a.last_seen));
+    return out;
+  } catch (err) {
+    logStderr('listInFlight', err);
+    return [];
+  }
+}
+
+function getJtbdAcrossRooms(jtbd) {
+  try {
+    if (!jtbd) return { by_room: {} };
+    const mem = readJsonOrEmpty(MEMORY_FILE());
+    const by_room = {};
+    if (!mem || !mem.rooms) return { by_room };
+    for (const slug of Object.keys(mem.rooms)) {
+      const r = mem.rooms[slug] || {};
+      const e = {};
+      const inFlight = Array.isArray(r.in_flight) ? r.in_flight.find(x => x && x.jtbd === jtbd) : null;
+      if (inFlight) e.in_flight = inFlight;
+      const parked = Array.isArray(r.parked) ? r.parked.filter(x => x && x.jtbd === jtbd) : [];
+      if (parked.length) e.parked = parked;
+      const completed = Array.isArray(r.completed) ? r.completed.filter(x => x && x.jtbd === jtbd) : [];
+      if (completed.length) e.completed = completed;
+      if (Object.keys(e).length) by_room[slug] = e;
+    }
+    return { by_room: by_room };
+  } catch (err) {
+    logStderr('getJtbdAcrossRooms', err);
+    return { by_room: {} };
+  }
+}
+
+// ---------------------------------------------------------------------
+// Module exports.
+// ---------------------------------------------------------------------
+
+module.exports = {
+  promoteIfEligible: promoteIfEligible,
+  parkJtbd: parkJtbd,
+  completeJtbd: completeJtbd,
+  getRoomMemory: getRoomMemory,
+  listInFlight: listInFlight,
+  getJtbdAcrossRooms: getJtbdAcrossRooms,
+  isGlobalOptOut: isGlobalOptOut,
+  isRoomOptOut: isRoomOptOut,
+  appendAudit: appendAudit,
+  // Internal helpers exposed for hermetic tests + future Phase 103-05 wiring.
+  _internal: {
+    truncateAuditIfNeeded: truncateAuditIfNeeded,
+    atomicUpdateMemory: atomicUpdateMemory,
+    ensureDir: ensureDir,
+    ROOMS_HOME: ROOMS_HOME,
+    MEMORY_DIR: MEMORY_DIR,
+    MEMORY_FILE: MEMORY_FILE,
+    constants: {
+      LOCK_TTL_MS: LOCK_TTL_MS,
+      RETRY_BUDGET_MS: RETRY_BUDGET_MS,
+      PER_ROOM_ARRAY_BOUND: PER_ROOM_ARRAY_BOUND,
+      AUDIT_LOG_HARD_BOUND: AUDIT_LOG_HARD_BOUND,
+      AUDIT_LOG_FLOOR: AUDIT_LOG_FLOOR,
+      ROOM_MEMORY_SCHEMA_VERSION: ROOM_MEMORY_SCHEMA_VERSION,
+    },
+  },
+};