enigma-memory 0.1.18 → 0.1.22

package/packages/terminal-tui/dashboard.mjs

@@ -0,0 +1,214 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { ANSI, renderMerkleTree, stripAnsi } from './merkle-tree-renderer.mjs';
+import { renderCallerTracker, renderMcpEventLog, renderZeroizationHud } from './telemetry-hud.mjs';
+
+export const OFFICIAL_SOLANA_TOKEN_CA = 'EknDj8VZUHL6FhV9pSk3m6xP2U2sDzwjRDVstKeQpump';
+
+function paint(value, code, color) {
+  return color ? `${code}${value}${ANSI.reset}` : String(value);
+}
+
+function countActive(bundle) {
+  if (Array.isArray(bundle?.active_memory_addresses)) return bundle.active_memory_addresses.length;
+  return (Array.isArray(bundle?.memory_objects) ? bundle.memory_objects : []).filter((memory) => !['deleted', 'tombstoned', 'inactive'].includes(String(memory?.state ?? 'active').toLowerCase())).length;
+}
+
+function countTombstones(bundle) {
+  return Array.isArray(bundle?.tombstones) ? bundle.tombstones.length : 0;
+}
+
+export function createDashboardSnapshot(bundle = {}) {
+  return {
+    activeMemories: countActive(bundle),
+    tombstones: countTombstones(bundle),
+    stateRoot: bundle?.vault?.active_set_root ?? bundle?.active_set_root ?? bundle?.merkle_root ?? '<not committed>',
+    receiptRoot: bundle?.vault?.receipt_log_root ?? bundle?.receipt_log_root ?? '<not committed>',
+    sequence: Number(bundle?.vault?.sequence ?? bundle?.sequence ?? 0),
+    vaultId: bundle?.vault?.vault_id ?? bundle?.vault_id ?? '<local vault>',
+    schema: bundle?.schema ?? '<unknown schema>',
+  };
+}
+
+function panel(title, lines, { color, width }) {
+  const inner = width - 4;
+  const top = `+-- ${title} ${'-'.repeat(Math.max(1, width - title.length - 7))}+`;
+  const body = lines.map((line) => {
+    const visible = stripAnsi(line).length;
+    return `| ${line}${' '.repeat(Math.max(0, inner - visible))} |`;
+  });
+  return [paint(top, ANSI.blue, color), ...body, paint(`+${'-'.repeat(width - 2)}+`, ANSI.blue, color)].join('\n');
+}
+
+function metric(label, value, colorCode, color) {
+  return `${paint(label, ANSI.dim, color)} ${paint(String(value).padStart(5), `${ANSI.bold}${colorCode}`, color)}`;
+}
+
+function solanaState(bundle) {
+  const state = bundle?.solana_anchor ?? bundle?.anchor ?? bundle?.solana ?? bundle?.chain?.solana;
+  if (!state || typeof state !== 'object') {
+    return {
+      available: false,
+      cluster: '<unavailable>',
+      programId: '<unavailable>',
+      escrows: '<unavailable>',
+      nullifiers: '<unavailable>',
+      slot: '<unavailable>',
+    };
+  }
+  const escrows = state?.escrows ?? state?.context_escrows ?? state?.accounts?.escrows;
+  const nullifiers = state?.nullifiers ?? state?.used_nullifiers ?? state?.accounts?.nullifiers;
+  const observedCount = (value) => Array.isArray(value) ? value.length : (Number.isFinite(Number(value?.count)) ? Number(value.count) : '<unavailable>');
+  return {
+    available: true,
+    cluster: state?.cluster ?? state?.network ?? '<unavailable>',
+    programId: state?.program_id ?? state?.programId ?? '<unavailable>',
+    escrows: observedCount(escrows),
+    nullifiers: observedCount(nullifiers),
+    slot: state?.slot ?? state?.last_slot ?? '<unavailable>',
+  };
+}
+
+export function renderSolanaExplorer(bundle, { color = true } = {}) {
+  const state = solanaState(bundle);
+  return [
+    `${paint('Roadmap', ANSI.dim, color)}     ${paint('BUILDING TOWARD / IN DEVELOPMENT', ANSI.yellow, color)}`,
+    `Cluster     ${state.cluster}  Slot: ${state.slot}`,
+    `Program     ${state.programId}`,
+    `Escrows     ${state.escrows} context accounts  Nullifiers: ${state.nullifiers}`,
+    `Token CA    ${OFFICIAL_SOLANA_TOKEN_CA}`,
+  ];
+}
+
+function dashboardHeader(snapshot, { color, frame, mode }) {
+  const spinner = ['|', '/', '-', '\\'][frame % 4];
+  const title = mode === 'monitor' ? 'ENIGMA MEMORY // LIVE MCP MONITOR' : 'ENIGMA MEMORY // LOCAL CONTROL PLANE';
+  return [
+    paint(title, `${ANSI.bold}${ANSI.cyan}`, color),
+    `${paint(spinner, ANSI.green, color)} standalone local snapshot  schema ${snapshot.schema}`,
+  ].join('\n');
+}
+
+export function renderDashboard(bundle, {
+  color = true,
+  width = 104,
+  frame = 0,
+  mode = 'dashboard',
+  bundleDisplay = '<local bundle>',
+} = {}) {
+  if (!bundle || typeof bundle !== 'object' || Array.isArray(bundle)) throw new Error('Terminal dashboard requires a JSON bundle object.');
+  const safeWidth = Math.max(80, Math.min(140, Number(width) || 104));
+  const snapshot = createDashboardSnapshot(bundle);
+  const metrics = [
+    `${metric('ACTIVE MEMORIES', snapshot.activeMemories, ANSI.green, color)}    ${metric('TOMBSTONES', snapshot.tombstones, ANSI.red, color)}    ${metric('SEQUENCE', snapshot.sequence, ANSI.cyan, color)}`,
+    `Bundle             ${bundleDisplay}`,
+    `Vault              ${snapshot.vaultId}`,
+    `Merkle state root  ${paint(snapshot.stateRoot, ANSI.cyan, color)}`,
+    `Receipt log root   ${paint(snapshot.receiptRoot, ANSI.magenta, color)}`,
+  ];
+  const sections = [
+    dashboardHeader(snapshot, { color, frame, mode }),
+    panel('MEMORY STATE', metrics, { color, width: safeWidth }),
+    panel('REAL-TIME MCP EVENT LOGGER', renderMcpEventLog(bundle, { color, limit: mode === 'monitor' ? 10 : 6 }), { color, width: safeWidth }),
+    panel('MCP CALLER TRACKER', renderCallerTracker(bundle, { color }), { color, width: safeWidth }),
+    panel('ENCLAVE KEY ZEROIZATION HUD', renderZeroizationHud(bundle, { color }), { color, width: safeWidth }),
+  ];
+  if (mode !== 'monitor') sections.push(panel('SOLANA ANCHOR STATE EXPLORER', renderSolanaExplorer(bundle, { color }), { color, width: safeWidth }));
+  sections.push(paint('q / Ctrl-C to exit  |  refreshes from disk  |  no network or tokens required', ANSI.dim, color));
+  return `${sections.join('\n\n')}\n`;
+}
+
+export async function readBundle(bundlePath) {
+  const path = resolve(String(bundlePath));
+  let source;
+  try {
+    source = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error(`Bundle not found: ${bundlePath}`);
+    throw error;
+  }
+  try {
+    return JSON.parse(source);
+  } catch {
+    throw new Error(`Bundle is not valid JSON: ${bundlePath}`);
+  }
+}
+
+export async function renderDashboardFromFile(bundlePath, options = {}) {
+  const bundle = await readBundle(bundlePath);
+  return renderDashboard(bundle, { ...options, bundleDisplay: options.bundleDisplay ?? String(bundlePath) });
+}
+
+export async function renderTreeFromFile(bundlePath, options = {}) {
+  const bundle = await readBundle(bundlePath);
+  return renderMerkleTree(bundle, options);
+}
+
+function canAnimate(io) {
+  return io?.stdout?.isTTY === true && typeof io?.stdout?.write === 'function';
+}
+
+export async function runDashboard({
+  bundlePath,
+  once = false,
+  interval = 1000,
+  mode = 'dashboard',
+  color = true,
+  depth,
+  io = { stdout: process.stdout, stderr: process.stderr },
+} = {}) {
+  if (!bundlePath) throw new Error('A bundle path is required.');
+  const refreshMs = Number(interval);
+  if (!Number.isInteger(refreshMs) || refreshMs < 100 || refreshMs > 60_000) throw new Error('--interval must be an integer from 100 to 60000 milliseconds.');
+
+  if (mode === 'tree') {
+    io.stdout.write(await renderTreeFromFile(bundlePath, { color, depth }));
+    return 0;
+  }
+
+  const initial = await renderDashboardFromFile(bundlePath, { color, mode, frame: 0 });
+  if (once || !canAnimate(io)) {
+    io.stdout.write(initial);
+    return 0;
+  }
+
+  io.stdout.write('\u001b[?25l\u001b[2J\u001b[H');
+  io.stdout.write(initial);
+  return new Promise((resolvePromise, rejectPromise) => {
+    let frame = 1;
+    let rendering = false;
+    let stopped = false;
+    const cleanup = (code = 0) => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+      if (io.stdin && typeof io.stdin.off === 'function') io.stdin.off('data', onInput);
+      io.stdout.write('\u001b[?25h\n');
+      resolvePromise(code);
+    };
+    const onSignal = () => cleanup(0);
+    const onInput = (chunk) => {
+      const value = String(chunk).toLowerCase();
+      if (value.includes('q') || value.includes('\u0003')) cleanup(0);
+    };
+    const timer = setInterval(async () => {
+      if (rendering || stopped) return;
+      rendering = true;
+      try {
+        const next = await renderDashboardFromFile(bundlePath, { color, mode, frame });
+        if (!stopped) io.stdout.write(`\u001b[H\u001b[2J${next}`);
+        frame += 1;
+      } catch (error) {
+        cleanup(1);
+        rejectPromise(error);
+      } finally {
+        rendering = false;
+      }
+    }, refreshMs);
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    if (io.stdin && typeof io.stdin.on === 'function') io.stdin.on('data', onInput);
+  });
+}

package/packages/terminal-tui/index.mjs

@@ -0,0 +1,28 @@
+export {
+  ANSI,
+  buildMerkleTree,
+  createMerkleProof,
+  renderMerkleTree,
+  stripAnsi,
+  verifyMerkleProof,
+} from './merkle-tree-renderer.mjs';
+
+export {
+  collectCallerStats,
+  collectMcpEvents,
+  enclaveZeroizationSnapshot,
+  renderCallerTracker,
+  renderMcpEventLog,
+  renderZeroizationHud,
+} from './telemetry-hud.mjs';
+
+export {
+  OFFICIAL_SOLANA_TOKEN_CA,
+  createDashboardSnapshot,
+  readBundle,
+  renderDashboard,
+  renderDashboardFromFile,
+  renderSolanaExplorer,
+  renderTreeFromFile,
+  runDashboard,
+} from './dashboard.mjs';

package/packages/terminal-tui/merkle-tree-renderer.mjs

@@ -0,0 +1,268 @@
+import { createHash } from 'node:crypto';
+
+export const ANSI = Object.freeze({
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[38;2;244;63;94m',
+  green: '\u001b[38;2;16;185;129m',
+  yellow: '\u001b[38;2;251;191;36m',
+  blue: '\u001b[38;2;56;189;248m',
+  magenta: '\u001b[38;2;244;114;182m',
+  cyan: '\u001b[38;2;6;182;212m',
+  white: '\u001b[38;2;244;242;239m',
+  gray: '\u001b[38;2;125;122;118m',
+  amber: '\u001b[38;2;255;122;26m',
+  amberGlow: '\u001b[38;2;255;176;102m',
+  dimText: '\u001b[38;2;185;182;177m',
+  bgDark: '\u001b[48;2;8;5;2m',
+});
+
+export function stripAnsi(value) {
+  return String(value).replace(/\u001b\[[0-9;]*m/gu, '');
+}
+
+function paint(value, code, color) {
+  return color ? `${code}${value}${ANSI.reset}` : String(value);
+}
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function digestBytes(hash) {
+  const hex = String(hash).replace(/^sha256:/u, '');
+  return /^[0-9a-f]{64}$/iu.test(hex) ? Buffer.from(hex, 'hex') : createHash('sha256').update(String(hash)).digest();
+}
+
+function canonicalLeafHash(leaf) {
+  return sha256(JSON.stringify({
+    memory_addr: leaf.memoryAddress,
+    status: leaf.status,
+    commitment: leaf.commitment,
+  }));
+}
+
+function combineHashes(left, right) {
+  return sha256(Buffer.concat([digestBytes(left), digestBytes(right)]));
+}
+
+function normalizeTombstone(entry) {
+  const memoryAddress = entry?.memory_addr ?? entry?.memoryAddress ?? entry?.address ?? entry?.id;
+  if (!memoryAddress) return null;
+  return {
+    memoryAddress: String(memoryAddress),
+    status: 'tombstoned',
+    commitment: entry?.tombstone_hash ?? entry?.commitment ?? entry?.event_hash ?? entry?.receipt_hash ?? memoryAddress,
+    source: entry,
+  };
+}
+
+function leafRecords(bundle) {
+  const activeAddresses = new Set(Array.isArray(bundle?.active_memory_addresses) ? bundle.active_memory_addresses.map(String) : []);
+  const tombstones = new Map();
+  for (const entry of Array.isArray(bundle?.tombstones) ? bundle.tombstones : []) {
+    const normalized = normalizeTombstone(entry);
+    if (normalized) tombstones.set(normalized.memoryAddress, normalized);
+  }
+
+  const records = [];
+  const seen = new Set();
+  for (const memory of Array.isArray(bundle?.memory_objects) ? bundle.memory_objects : []) {
+    const memoryAddress = String(memory?.memory_addr ?? memory?.memoryAddress ?? memory?.memory_id ?? `memory-${records.length + 1}`);
+    const tombstoned = tombstones.has(memoryAddress) || memory?.state === 'tombstoned' || memory?.state === 'deleted';
+    const status = tombstoned ? 'tombstoned' : (activeAddresses.size === 0 || activeAddresses.has(memoryAddress) || memory?.state === 'active' ? 'active' : 'inactive');
+    records.push({
+      memoryAddress,
+      status,
+      commitment: memory?.content_hash ?? memory?.content_commitment ?? memory?.commitment ?? memoryAddress,
+      source: memory,
+    });
+    seen.add(memoryAddress);
+  }
+  for (const [memoryAddress, tombstone] of tombstones) {
+    if (!seen.has(memoryAddress)) records.push(tombstone);
+  }
+  return records;
+}
+
+function aggregateStatus(children) {
+  const statuses = new Set(children.map((child) => child.status));
+  return statuses.size === 1 ? children[0].status : 'mixed';
+}
+
+/**
+ * Builds a deterministic visualization Merkle tree over public memory commitments.
+ * The computed visualization root is intentionally kept separate from the vault's
+ * committed active-set root because vault implementations may use a different
+ * canonical leaf encoding.
+ */
+export function buildMerkleTree(bundle = {}) {
+  const records = leafRecords(bundle);
+  const effectiveRecords = records.length > 0 ? records : [{
+    memoryAddress: '<empty-active-set>',
+    status: 'empty',
+    commitment: 'empty',
+    source: null,
+  }];
+  const leaves = effectiveRecords.map((record, index) => ({
+    ...record,
+    type: 'leaf',
+    level: 0,
+    index,
+    hash: canonicalLeafHash(record),
+    children: [],
+    leafStart: index,
+    leafEnd: index,
+  }));
+  const levels = [leaves];
+  let current = leaves;
+  let level = 1;
+  while (current.length > 1) {
+    const next = [];
+    for (let index = 0; index < current.length; index += 2) {
+      const left = current[index];
+      const right = current[index + 1] ?? left;
+      next.push({
+        type: 'internal',
+        level,
+        index: next.length,
+        hash: combineHashes(left.hash, right.hash),
+        status: aggregateStatus([left, right]),
+        children: [left, right],
+        duplicatedRight: left === right,
+        leafStart: left.leafStart,
+        leafEnd: right.leafEnd,
+      });
+    }
+    levels.push(next);
+    current = next;
+    level += 1;
+  }
+  const committedRoot = bundle?.vault?.active_set_root ?? bundle?.active_set_root ?? bundle?.merkle_root ?? null;
+  return {
+    leaves,
+    levels,
+    root: current[0],
+    computedRoot: current[0].hash,
+    committedRoot,
+    activeCount: records.filter((record) => record.status === 'active').length,
+    tombstoneCount: records.filter((record) => record.status === 'tombstoned').length,
+  };
+}
+
+export function createMerkleProof(tree, target = 0) {
+  let leafIndex = typeof target === 'number'
+    ? target
+    : tree.leaves.findIndex((leaf) => leaf.memoryAddress === target);
+  if (!Number.isInteger(leafIndex) || leafIndex < 0 || leafIndex >= tree.leaves.length) {
+    throw new Error(`Merkle proof target not found: ${target}`);
+  }
+  const originalIndex = leafIndex;
+  const steps = [];
+  for (let level = 0; level < tree.levels.length - 1; level += 1) {
+    const nodes = tree.levels[level];
+    const siblingIndex = leafIndex % 2 === 0 ? leafIndex + 1 : leafIndex - 1;
+    const sibling = nodes[siblingIndex] ?? nodes[leafIndex];
+    steps.push({
+      level,
+      position: leafIndex % 2 === 0 ? 'right' : 'left',
+      hash: sibling.hash,
+      duplicated: siblingIndex >= nodes.length,
+    });
+    leafIndex = Math.floor(leafIndex / 2);
+  }
+  return {
+    leafIndex: originalIndex,
+    memoryAddress: tree.leaves[originalIndex].memoryAddress,
+    leafHash: tree.leaves[originalIndex].hash,
+    steps,
+    expectedRoot: tree.computedRoot,
+  };
+}
+
+export function verifyMerkleProof(proof) {
+  let computed = proof.leafHash;
+  for (const step of proof.steps) {
+    computed = step.position === 'left'
+      ? combineHashes(step.hash, computed)
+      : combineHashes(computed, step.hash);
+  }
+  return { verified: computed === proof.expectedRoot, computedRoot: computed };
+}
+
+function shortHash(hash, size = 14) {
+  if (!hash) return '<not-committed>';
+  const text = String(hash);
+  const prefix = text.startsWith('sha256:') ? 'sha256:' : '';
+  const digest = prefix ? text.slice(prefix.length) : text;
+  return digest.length <= size ? text : `${prefix}${digest.slice(0, size)}...${digest.slice(-6)}`;
+}
+
+function shortAddress(address, size = 24) {
+  const text = String(address);
+  return text.length <= size ? text : `${text.slice(0, size - 9)}...${text.slice(-6)}`;
+}
+
+function statusBadge(status, color) {
+  if (status === 'active') return paint('[A] ACTIVE', ANSI.green, color);
+  if (status === 'tombstoned') return paint('[X] TOMBSTONED', ANSI.red, color);
+  if (status === 'inactive') return paint('[-] INACTIVE', ANSI.yellow, color);
+  if (status === 'mixed') return paint('[M] MIXED', ANSI.yellow, color);
+  return paint('[.] EMPTY', ANSI.gray, color);
+}
+
+function nodeOnProofPath(node, proof) {
+  return proof.leafIndex >= node.leafStart && proof.leafIndex <= node.leafEnd;
+}
+
+function renderNode(node, proof, options, prefix = '', isLast = true, depth = 0, root = false) {
+  const connector = root ? '' : `${prefix}${isLast ? '`-- ' : '|-- '}`;
+  const pathMark = nodeOnProofPath(node, proof) ? paint(' *PROOF', ANSI.magenta, options.color) : '';
+  const kind = node.type === 'leaf' ? 'LEAF' : (root ? 'ROOT' : 'NODE');
+  const label = node.type === 'leaf' ? ` ${shortAddress(node.memoryAddress)}` : ` L${node.level}:${node.index}`;
+  const line = `${connector}${paint(kind, node.type === 'leaf' ? ANSI.cyan : ANSI.blue, options.color)}${label} ${shortHash(node.hash)} ${statusBadge(node.status, options.color)}${pathMark}`;
+  const lines = [line];
+  if (node.children.length === 0) return lines;
+  if (depth >= options.depth - 1) {
+    const nextPrefix = root ? '' : `${prefix}${isLast ? '    ' : '|   '}`;
+    lines.push(`${nextPrefix}\`-- ... ${node.leafEnd - node.leafStart + 1} leaves below (increase --depth)`);
+    return lines;
+  }
+  const nextPrefix = root ? '' : `${prefix}${isLast ? '    ' : '|   '}`;
+  node.children.forEach((child, index) => {
+    lines.push(...renderNode(child, proof, options, nextPrefix, index === node.children.length - 1, depth + 1, false));
+  });
+  return lines;
+}
+
+export function renderMerkleTree(bundle, { depth = Number.POSITIVE_INFINITY, color = true, proofAddress } = {}) {
+  const parsedDepth = depth === Number.POSITIVE_INFINITY ? depth : Number(depth);
+  if (!(parsedDepth === Number.POSITIVE_INFINITY || (Number.isInteger(parsedDepth) && parsedDepth >= 1 && parsedDepth <= 64))) {
+    throw new Error('--depth must be an integer from 1 to 64.');
+  }
+  const tree = buildMerkleTree(bundle);
+  const target = proofAddress ?? tree.leaves.find((leaf) => leaf.status === 'active')?.memoryAddress ?? 0;
+  const proof = createMerkleProof(tree, target);
+  const verification = verifyMerkleProof(proof);
+  const options = { depth: parsedDepth, color };
+  const lines = [
+    paint('ENIGMA MEMORY // MERKLE STATE TREE', `${ANSI.bold}${ANSI.cyan}`, color),
+    `${paint('Committed active-set root', ANSI.dim, color)}  ${tree.committedRoot ?? '<not present in bundle>'}`,
+    `${paint('Visualization root', ANSI.dim, color)}       ${tree.computedRoot}`,
+    `${paint('Leaves', ANSI.dim, color)} ${tree.leaves.length}  ${paint('Active', ANSI.green, color)} ${tree.activeCount}  ${paint('Tombstoned', ANSI.red, color)} ${tree.tombstoneCount}`,
+    '',
+    ...renderNode(tree.root, proof, options, '', true, 0, true),
+    '',
+    paint('PROOF VERIFICATION PATH', `${ANSI.bold}${ANSI.magenta}`, color),
+    `Target  ${shortAddress(proof.memoryAddress, 48)}`,
+    `Leaf    ${proof.leafHash}`,
+  ];
+  if (proof.steps.length === 0) lines.push('Step 0  single-leaf tree (no siblings required)');
+  proof.steps.forEach((step, index) => {
+    lines.push(`Step ${index + 1}  ${step.position.toUpperCase().padEnd(5)} sibling ${shortHash(step.hash, 24)}${step.duplicated ? ' (duplicated)' : ''}`);
+  });
+  lines.push(`Result  ${verification.verified ? paint('VERIFIED', ANSI.green, color) : paint('FAILED', ANSI.red, color)} -> ${verification.computedRoot}`);
+  lines.push(paint('Proof verifies the visualization tree encoding; the vault root above remains the canonical state commitment.', ANSI.dim, color));
+  return `${lines.join('\n')}\n`;
+}

package/packages/terminal-tui/telemetry-hud.mjs

@@ -0,0 +1,137 @@
+import { ANSI } from './merkle-tree-renderer.mjs';
+
+function paint(value, code, color) {
+  return color ? `${code}${value}${ANSI.reset}` : String(value);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function eventPayload(entry) {
+  return entry?.event && typeof entry.event === 'object' ? entry.event : entry;
+}
+
+function eventIdentity(event, index) {
+  return event?.event_id ?? event?.id ?? event?.call_id ?? `${event?.timestamp ?? 'undated'}:${event?.operation ?? event?.tool ?? index}`;
+}
+
+function explicitMcpEvents(bundle) {
+  return [
+    ...asArray(bundle?.mcp_events),
+    ...asArray(bundle?.telemetry?.mcp_events),
+    ...asArray(bundle?.mcp?.events),
+    ...asArray(bundle?.swarm?.events),
+    ...asArray(bundle?.mcp_swarm?.events),
+  ];
+}
+
+function looksLikeMcpEvent(entry) {
+  const event = eventPayload(entry);
+  const source = `${event?.source ?? ''} ${event?.protocol ?? ''} ${event?.transport ?? ''} ${event?.actor_id ?? ''}`.toLowerCase();
+  const operation = String(event?.operation ?? event?.type ?? '').toLowerCase();
+  return source.includes('mcp') || operation.startsWith('mcp_') || operation === 'tool_call' || operation === 'tools/call';
+}
+
+export function collectMcpEvents(bundle = {}, { limit = 8 } = {}) {
+  const candidates = [...explicitMcpEvents(bundle), ...asArray(bundle?.events).filter(looksLikeMcpEvent)];
+  const seen = new Set();
+  const normalized = [];
+  candidates.forEach((entry, index) => {
+    const event = eventPayload(entry) ?? {};
+    const id = String(eventIdentity(event, index));
+    if (seen.has(id)) return;
+    seen.add(id);
+    normalized.push({
+      id,
+      timestamp: event.timestamp ?? event.created_at ?? entry?.timestamp ?? null,
+      caller: String(event.caller ?? event.caller_id ?? event.client_id ?? event.agent_id ?? event.actor_id ?? event.subject_id ?? 'anonymous-local'),
+      tool: String(event.tool ?? event.tool_name ?? event.method ?? event.operation ?? event.type ?? 'mcp_event'),
+      status: String(event.status ?? event.result?.status ?? (event.error ? 'error' : 'ok')),
+    });
+  });
+  normalized.sort((a, b) => String(a.timestamp ?? '').localeCompare(String(b.timestamp ?? '')));
+  return normalized.slice(-Math.max(0, Number(limit) || 0));
+}
+
+export function collectCallerStats(events) {
+  const counts = new Map();
+  for (const event of events) counts.set(event.caller, (counts.get(event.caller) ?? 0) + 1);
+  return [...counts.entries()]
+    .map(([caller, calls]) => ({ caller, calls }))
+    .sort((a, b) => b.calls - a.calls || a.caller.localeCompare(b.caller));
+}
+
+function zeroizationAttestations(bundle) {
+  return [
+    ...asArray(bundle?.enclave_attestations),
+    ...asArray(bundle?.zeroization_attestations),
+    ...asArray(bundle?.enclave?.attestations),
+    ...asArray(bundle?.enclave_runtime?.attestations),
+  ];
+}
+
+function actionOf(attestation) {
+  return String(attestation?.payload?.action ?? attestation?.action ?? attestation?.event ?? '').toUpperCase();
+}
+
+export function enclaveZeroizationSnapshot(bundle = {}) {
+  const attestations = zeroizationAttestations(bundle);
+  const zeroized = attestations.filter((entry) => actionOf(entry) === 'KEY_ZEROIZED');
+  const batches = attestations.filter((entry) => actionOf(entry) === 'BATCH_KEYS_ZEROIZED');
+  const batchKeys = batches.reduce((total, entry) => total + Number(entry?.payload?.batchSize ?? entry?.batchSize ?? 0), 0);
+  const records = [
+    ...asArray(bundle?.enclave?.records),
+    ...asArray(bundle?.enclave_runtime?.records),
+  ];
+  const activeKeys = records.filter((record) => !['zeroized', 'destroyed', 'tombstoned'].includes(String(record?.status ?? record?.state ?? '').toLowerCase())).length;
+  const explicitStatus = bundle?.enclave?.zeroization_status ?? bundle?.enclave_runtime?.zeroization_status ?? null;
+  let status = 'UNAVAILABLE';
+  if (zeroized.length + batchKeys > 0 || String(explicitStatus).toLowerCase() === 'zeroized') status = 'REPORTED / UNVERIFIED';
+  else if (activeKeys > 0) status = 'KEYS ACTIVE';
+  return {
+    status,
+    zeroizedKeys: zeroized.length + batchKeys,
+    activeKeys,
+    attestationCount: zeroized.length + batches.length,
+    provider: bundle?.enclave?.provider ?? bundle?.enclave_runtime?.provider ?? '<unavailable>',
+  };
+}
+
+function short(value, size) {
+  const text = String(value ?? '');
+  return text.length <= size ? text : `${text.slice(0, size - 3)}...`;
+}
+
+function shortTime(value) {
+  if (!value) return '--:--:--';
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? short(value, 8) : date.toISOString().slice(11, 19);
+}
+
+export function renderMcpEventLog(bundle, { color = true, limit = 6 } = {}) {
+  const events = collectMcpEvents(bundle, { limit });
+  if (events.length === 0) return [paint('No MCP calls observed in this local bundle snapshot.', ANSI.dim, color)];
+  return events.map((event) => {
+    const statusColor = event.status.toLowerCase() === 'error' ? ANSI.red : ANSI.green;
+    return `${paint(shortTime(event.timestamp), ANSI.gray, color)} ${paint(short(event.status.toUpperCase(), 7).padEnd(7), statusColor, color)} ${short(event.caller, 20).padEnd(20)} ${short(event.tool, 31)}`;
+  });
+}
+
+export function renderCallerTracker(bundle, { color = true, limit = 5 } = {}) {
+  const events = collectMcpEvents(bundle, { limit: Number.MAX_SAFE_INTEGER });
+  const callers = collectCallerStats(events).slice(0, limit);
+  if (callers.length === 0) return [paint('Callers: none observed', ANSI.dim, color)];
+  return callers.map((caller, index) => `${paint(`#${index + 1}`, ANSI.cyan, color)} ${short(caller.caller, 35).padEnd(35)} ${String(caller.calls).padStart(4)} calls`);
+}
+
+export function renderZeroizationHud(bundle, { color = true } = {}) {
+  const snapshot = enclaveZeroizationSnapshot(bundle);
+  const statusColor = snapshot.status === 'REPORTED / UNVERIFIED' || snapshot.status === 'KEYS ACTIVE' ? ANSI.yellow : ANSI.gray;
+  return [
+    `Status       ${paint(snapshot.status, `${ANSI.bold}${statusColor}`, color)}`,
+    `Key records  ${snapshot.activeKeys} active / ${snapshot.zeroizedKeys} zeroized`,
+    `Reports      ${snapshot.attestationCount}  Provider: ${snapshot.provider}`,
+    paint('Action/status fields are unverified reports; no hardware-RAM erasure claim.', ANSI.dim, color),
+  ];
+}