enigma-memory 0.1.17 → 0.1.22

package/packages/mcp-server/swarm-bridge.mjs

@@ -0,0 +1,361 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+export const SWARM_PERMISSIONS = Object.freeze({ READ: 1, WRITE: 2, SYNC: 4, GRAPH: 8, CLUSTER: 16, ADMIN: 32 });
+const ALL_PERMISSIONS = Object.values(SWARM_PERMISSIONS).reduce((mask, value) => mask | value, 0);
+const DEFAULT_PERMISSIONS = SWARM_PERMISSIONS.READ | SWARM_PERMISSIONS.WRITE | SWARM_PERMISSIONS.SYNC | SWARM_PERMISSIONS.GRAPH | SWARM_PERMISSIONS.CLUSTER;
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+function sha256(value) { return `sha256:${createHash('sha256').update(typeof value === 'string' ? value : canonical(value)).digest('hex')}`; }
+function clone(value) { return value === undefined ? undefined : structuredClone(value); }
+function requiredString(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} is required`);
+  return value.trim();
+}
+function normalizePermissionMask(value) {
+  if (value === undefined || value === null) return DEFAULT_PERMISSIONS;
+  if (Number.isInteger(value) && value >= 0 && value <= ALL_PERMISSIONS) return value;
+  const names = Array.isArray(value) ? value : String(value).split(/[|,\s]+/);
+  let mask = 0;
+  for (const rawName of names) {
+    const name = String(rawName).trim().toUpperCase();
+    if (!name) continue;
+    if (!(name in SWARM_PERMISSIONS)) throw new Error(`unknown swarm permission: ${rawName}`);
+    mask |= SWARM_PERMISSIONS[name];
+  }
+  return mask;
+}
+function permissionNames(mask) { return Object.entries(SWARM_PERMISSIONS).filter(([, bit]) => (mask & bit) === bit).map(([name]) => name.toLowerCase()); }
+function atomId(atom) {
+  const value = atom?.memory_addr ?? atom?.memoryAddr ?? atom?.atom_id ?? atom?.atomId ?? atom?.id;
+  return requiredString(value, 'memory atom id');
+}
+function atomContent(atom) { return String(atom?.content ?? atom?.text ?? atom?.summary ?? atom?.metadata?.summary ?? ''); }
+const TOKEN_STOPWORDS = new Set(['a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'in', 'is', 'it', 'of', 'on', 'or', 'that', 'the', 'this', 'to', 'was', 'were', 'with']);
+function tokens(value) { return new Set(String(value).toLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu)?.filter((token) => !TOKEN_STOPWORDS.has(token)) ?? []); }
+function similarity(left, right) {
+  if (left.size === 0 && right.size === 0) return 1;
+  let intersection = 0;
+  for (const token of left) if (right.has(token)) intersection += 1;
+  const union = left.size + right.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function entityEntry(value) {
+  if (typeof value === 'string') return { id: value, label: value, type: 'entity' };
+  if (!value || typeof value !== 'object') return null;
+  const id = value.id ?? value.entity_id ?? value.entityId ?? value.name ?? value.label;
+  if (typeof id !== 'string' || !id.trim()) return null;
+  return { id: id.trim(), label: String(value.label ?? value.name ?? id), type: String(value.type ?? value.kind ?? 'entity') };
+}
+function relationEntry(value) {
+  if (!value || typeof value !== 'object') return null;
+  const from = value.from ?? value.source ?? value.subject ?? value.source_id;
+  const to = value.to ?? value.target ?? value.object ?? value.target_id;
+  if (typeof from !== 'string' || !from.trim() || typeof to !== 'string' || !to.trim()) return null;
+  return { from: from.trim(), to: to.trim(), type: String(value.type ?? value.relation ?? value.predicate ?? 'related_to'), directed: value.directed !== false };
+}
+function atomRelations(atom) {
+  return [...(Array.isArray(atom.relations) ? atom.relations : []), ...(Array.isArray(atom.metadata?.relations) ? atom.metadata.relations : [])].map(relationEntry).filter(Boolean);
+}
+function atomEntities(atom) {
+  const raw = [...(Array.isArray(atom.entities) ? atom.entities : []), ...(Array.isArray(atom.metadata?.entities) ? atom.metadata.entities : [])];
+  const entries = raw.map(entityEntry).filter(Boolean);
+  const seen = new Set(entries.map((entry) => entry.id));
+  for (const relation of atomRelations(atom)) for (const id of [relation.from, relation.to]) if (!seen.has(id)) { entries.push({ id, label: id, type: 'entity' }); seen.add(id); }
+  return entries;
+}
+function publicAtom(atom) {
+  const copy = clone(atom);
+  delete copy.plaintext;
+  delete copy._swarm_hash;
+  return copy;
+}
+
+const COMMITMENT_ATOM_STRING_FIELDS = Object.freeze([
+  'schema',
+  'memory_addr',
+  'memory_id',
+  'atom_id',
+  'swarm_id',
+  'namespace',
+  'owner_agent_id',
+  'source_addr',
+  'successor_addr',
+  'kind',
+  'state',
+  'status',
+  'confidence',
+  'sensitivity',
+  'retention',
+  'created_at',
+  'updated_at',
+  'tombstoned_at',
+]);
+const COMMITMENT_HASH_FIELDS = Object.freeze(['content_hash', 'content_commitment']);
+const COMMITMENT_ATOM_KEYS = new Set([...COMMITMENT_ATOM_STRING_FIELDS, ...COMMITMENT_HASH_FIELDS, 'entities', 'relations']);
+const COMMITMENT_RELATION_KEYS = new Set(['from', 'to', 'type', 'directed']);
+const SAFE_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,255}$/;
+const SHA256_VALUE_PATTERN = /^sha256:[a-f0-9]{64}$/i;
+const COMMITMENT_VALUE_PATTERN = /^(?:sha256|hmac-sha256):[a-f0-9]{64}$/i;
+
+function safeIdentifier(value) {
+  return typeof value === 'string' && SAFE_IDENTIFIER_PATTERN.test(value);
+}
+
+export function projectSwarmCommitmentAtom(atom) {
+  const projected = {};
+  for (const key of COMMITMENT_ATOM_STRING_FIELDS) {
+    if (safeIdentifier(atom?.[key])) projected[key] = atom[key];
+  }
+  const memoryAddr = atomId(atom);
+  if (!safeIdentifier(memoryAddr)) throw new Error('memory atom id is not a safe stable identifier');
+  projected.memory_addr = memoryAddr;
+  if (SHA256_VALUE_PATTERN.test(atom?.content_hash ?? '')) projected.content_hash = atom.content_hash;
+  if (COMMITMENT_VALUE_PATTERN.test(atom?.content_commitment ?? '')) projected.content_commitment = atom.content_commitment;
+  const entities = atomEntities(atom).map((entity) => entity.id).filter(safeIdentifier);
+  if (entities.length > 0) projected.entities = [...new Set(entities)].sort();
+  const relations = atomRelations(atom)
+    .filter(({ from, to, type }) => safeIdentifier(from) && safeIdentifier(to) && safeIdentifier(type))
+    .map(({ from, to, type, directed }) => ({ from, to, type, directed }));
+  if (relations.length > 0) projected.relations = relations;
+  return projected;
+}
+
+export function validateSwarmCommitmentAtom(atom) {
+  if (!atom || typeof atom !== 'object' || Array.isArray(atom)) throw new Error('commitment-only snapshot atom must be an object');
+  for (const key of Object.keys(atom)) {
+    if (!COMMITMENT_ATOM_KEYS.has(key)) throw new Error(`commitment-only snapshot atom contains unsafe field: ${key}`);
+  }
+  for (const key of COMMITMENT_ATOM_STRING_FIELDS) {
+    if (atom[key] !== undefined && !safeIdentifier(atom[key])) throw new Error(`commitment-only snapshot atom ${key} is not a safe stable identifier`);
+  }
+  if (atom.content_hash !== undefined && !SHA256_VALUE_PATTERN.test(atom.content_hash)) throw new Error('commitment-only snapshot atom content_hash is invalid');
+  if (atom.content_commitment !== undefined && !COMMITMENT_VALUE_PATTERN.test(atom.content_commitment)) throw new Error('commitment-only snapshot atom content_commitment is invalid');
+  const memoryAddr = atomId(atom);
+  if (!safeIdentifier(memoryAddr)) throw new Error('commitment-only snapshot atom memory_addr is not a safe stable identifier');
+  if (atom.entities !== undefined && (!Array.isArray(atom.entities) || atom.entities.some((entity) => !safeIdentifier(entity)))) {
+    throw new Error('commitment-only snapshot atom entities must be an array of safe string identifiers');
+  }
+  if (atom.relations !== undefined) {
+    if (!Array.isArray(atom.relations)) throw new Error('commitment-only snapshot atom relations must be an array');
+    for (const relation of atom.relations) {
+      if (!relation || typeof relation !== 'object' || Array.isArray(relation)) throw new Error('commitment-only snapshot relation must be an object');
+      for (const key of Object.keys(relation)) {
+        if (!COMMITMENT_RELATION_KEYS.has(key)) throw new Error(`commitment-only snapshot relation contains unsafe field: ${key}`);
+      }
+      if (!safeIdentifier(relation.from) || !safeIdentifier(relation.to) || !safeIdentifier(relation.type) || typeof relation.directed !== 'boolean') {
+        throw new Error('commitment-only snapshot relation has invalid identifiers');
+      }
+    }
+  }
+  return atom;
+}
+
+function replicationAtom(atom, includeContent) {
+  return includeContent ? publicAtom(atom) : projectSwarmCommitmentAtom(atom);
+}
+function atomLeaf(atom) { const copy = publicAtom(atom); delete copy._swarm_hash; return sha256(copy); }
+function merkleRootFromLeaves(leaves) {
+  if (leaves.length === 0) return sha256('');
+  let level = [...leaves].sort();
+  while (level.length > 1) {
+    const next = [];
+    for (let index = 0; index < level.length; index += 2) next.push(sha256(`${level[index]}|${level[index + 1] ?? level[index]}`));
+    level = next;
+  }
+  return level[0];
+}
+export function computeSwarmMerkleRoot(atoms = []) { return merkleRootFromLeaves(atoms.map(atomLeaf)); }
+
+export class SwarmMemoryBridge {
+  constructor(state = {}) {
+    this.swarmId = String(state.swarm_id ?? state.swarmId ?? `swarm_${randomUUID()}`);
+    this.agents = new Map();
+    this.namespaces = new Map();
+    for (const agent of state.agents ?? []) this.registerAgent(agent, { restoring: true });
+    for (const [namespace, atoms] of Object.entries(state.namespaces ?? {})) {
+      const store = new Map();
+      for (const rawAtom of atoms ?? []) {
+        const atom = clone(rawAtom);
+        atom._swarm_hash = atomLeaf(atom);
+        store.set(atomId(atom), atom);
+      }
+      this.namespaces.set(namespace, store);
+    }
+  }
+
+  registerAgent(input = {}, options = {}) {
+    const agentId = requiredString(input.agent_id ?? input.agentId, 'agent_id');
+    const domain = requiredString(input.swarm_id ?? input.swarmId ?? input.domain ?? this.swarmId, 'swarm_id');
+    if (domain !== this.swarmId) throw new Error(`agent swarm domain mismatch: ${domain}`);
+    const namespace = requiredString(input.namespace ?? agentId, 'namespace');
+    const permissionMask = normalizePermissionMask(input.permission_mask ?? input.permissionMask ?? input.permissions);
+    const existing = this.agents.get(agentId);
+    if (existing && existing.namespace !== namespace && !options.restoring) throw new Error(`agent ${agentId} is already fenced to namespace ${existing.namespace}`);
+    const agent = { agent_id: agentId, swarm_id: this.swarmId, namespace, permission_mask: permissionMask, permissions: permissionNames(permissionMask), registered_at: existing?.registered_at ?? input.registered_at ?? new Date().toISOString() };
+    this.agents.set(agentId, agent);
+    if (!this.namespaces.has(namespace)) this.namespaces.set(namespace, new Map());
+    return clone(agent);
+  }
+
+  requireAgent(agentId, permission, namespace) {
+    const agent = this.agents.get(requiredString(agentId, 'agent_id'));
+    if (!agent) throw new Error(`unregistered swarm agent: ${agentId}`);
+    if ((agent.permission_mask & SWARM_PERMISSIONS.ADMIN) !== SWARM_PERMISSIONS.ADMIN && (agent.permission_mask & permission) !== permission) throw new Error(`agent ${agent.agent_id} lacks ${permissionNames(permission)[0]} permission`);
+    const requestedNamespace = namespace ?? agent.namespace;
+    if ((agent.permission_mask & SWARM_PERMISSIONS.ADMIN) !== SWARM_PERMISSIONS.ADMIN && requestedNamespace !== agent.namespace) throw new Error(`namespace fence violation for agent ${agent.agent_id}`);
+    return { agent, namespace: requestedNamespace };
+  }
+
+  writeMemory(input = {}) {
+    const { agent, namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.WRITE, input.namespace);
+    const atom = clone(input.atom ?? input.memory ?? input); delete atom.agent_id; delete atom.agentId;
+    const id = atomId(atom);
+    const fenced = { ...atom, memory_addr: id, swarm_id: this.swarmId, namespace, owner_agent_id: atom.owner_agent_id ?? agent.agent_id };
+    fenced._swarm_hash = atomLeaf(fenced);
+    this.namespaces.get(namespace).set(id, fenced);
+    return publicAtom(fenced);
+  }
+
+  ingestMemories(input = {}) {
+    const { agent, namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.WRITE, input.namespace);
+    const store = this.namespaces.get(namespace); let added = 0; let unchanged = 0;
+    for (const rawAtom of input.atoms ?? input.memories ?? []) {
+      const id = atomId(rawAtom);
+      const atom = { ...clone(rawAtom), memory_addr: id, swarm_id: this.swarmId, namespace, owner_agent_id: rawAtom.owner_agent_id ?? agent.agent_id };
+      atom._swarm_hash = atomLeaf(atom);
+      if (store.get(id)?._swarm_hash === atom._swarm_hash) unchanged += 1; else { store.set(id, atom); added += 1; }
+    }
+    return { added, unchanged, namespace, merkle_root: computeSwarmMerkleRoot([...store.values()]) };
+  }
+
+  hydrateCanonicalMemories(namespace, atoms = []) {
+    const store = this.namespaces.get(requiredString(namespace, 'namespace'));
+    if (!store) throw new Error(`unknown swarm namespace: ${namespace}`);
+    for (const rawAtom of atoms) {
+      const id = atomId(rawAtom);
+      const atom = { ...clone(rawAtom), memory_addr: id, swarm_id: this.swarmId, namespace };
+      atom._swarm_hash = atomLeaf(atom);
+      store.set(id, atom);
+    }
+  }
+
+  readMemory(input = {}) {
+    const { namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.READ, input.namespace);
+    const atom = this.namespaces.get(namespace).get(requiredString(input.memory_addr ?? input.memoryAddr ?? input.id, 'memory_addr'));
+    return atom ? publicAtom(atom) : null;
+  }
+  listMemories(input = {}) {
+    const { namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.READ, input.namespace);
+    return [...this.namespaces.get(namespace).values()].map(publicAtom).sort((a, b) => atomId(a).localeCompare(atomId(b)));
+  }
+
+  graphQuery(input = {}) {
+    const { namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.GRAPH, input.namespace);
+    const atoms = [...this.namespaces.get(namespace).values()]; const entities = new Map(); const edges = []; const entityAtoms = new Map();
+    for (const atom of atoms) {
+      const id = atomId(atom);
+      for (const entity of atomEntities(atom)) { entities.set(entity.id, entity); if (!entityAtoms.has(entity.id)) entityAtoms.set(entity.id, new Set()); entityAtoms.get(entity.id).add(id); }
+      for (const relation of atomRelations(atom)) edges.push({ ...relation, memory_addr: id, associative: false });
+    }
+    for (const [entityId, addresses] of entityAtoms) {
+      const sorted = [...addresses].sort();
+      for (let left = 0; left < sorted.length; left += 1) for (let right = left + 1; right < sorted.length; right += 1) edges.push({ from: sorted[left], to: sorted[right], type: 'shares_entity', entity_id: entityId, directed: false, associative: true });
+    }
+    const start = input.start ?? input.entity_id ?? input.entityId ?? input.query;
+    const maxDepth = Math.max(0, Math.min(12, Number(input.max_depth ?? input.maxDepth ?? 3)));
+    const limit = Math.max(1, Math.min(500, Number(input.limit ?? 100)));
+    const adjacency = new Map(); const link = (from, edge, to) => { if (!adjacency.has(from)) adjacency.set(from, []); adjacency.get(from).push({ edge, to }); };
+    for (const edge of edges) { link(edge.from, edge, edge.to); if (!edge.directed || input.direction !== 'out') link(edge.to, edge, edge.from); }
+    for (const [entityId, addresses] of entityAtoms) for (const address of addresses) { const edge = { from: entityId, to: address, type: 'mentioned_in', directed: false, associative: true }; link(entityId, edge, address); link(address, edge, entityId); }
+    const starts = start ? [String(start)] : [...entities.keys()].sort().slice(0, 1);
+    const queue = starts.map((node) => ({ node, depth: 0 })); const visited = new Map(); const traversedEdges = [];
+    while (queue.length && visited.size < limit) {
+      const current = queue.shift();
+      if (visited.has(current.node) && visited.get(current.node).depth <= current.depth) continue;
+      visited.set(current.node, current); if (current.depth >= maxDepth) continue;
+      for (const next of adjacency.get(current.node) ?? []) { traversedEdges.push(next.edge); queue.push({ node: next.to, depth: current.depth + 1 }); }
+    }
+    const memoryById = new Map(atoms.map((atom) => [atomId(atom), atom]));
+    return { schema: 'enigma.swarm_graph_query.v1', swarm_id: this.swarmId, namespace, start: start ?? null, max_depth: maxDepth,
+      nodes: [...visited].map(([id, visit]) => ({ id, kind: memoryById.has(id) ? 'memory' : 'entity', depth: visit.depth, ...(entities.get(id) ?? {}) })), edges: [...new Map(traversedEdges.map((edge) => [canonical(edge), edge])).values()], memories: [...visited.keys()].filter((id) => memoryById.has(id)).map((id) => publicAtom(memoryById.get(id))) };
+  }
+
+  clusterMemories(input = {}) {
+    const { namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.CLUSTER, input.namespace);
+    const threshold = Math.max(0, Math.min(1, Number(input.threshold ?? 0.22))); const maxClusters = Math.max(1, Math.min(100, Number(input.max_clusters ?? input.maxClusters ?? 20)));
+    const atoms = [...this.namespaces.get(namespace).values()].sort((a, b) => atomId(a).localeCompare(atomId(b))); const clusters = [];
+    for (const atom of atoms) {
+      const atomTokens = tokens(`${atomContent(atom)} ${(atom.purpose_tags ?? atom.tags ?? []).join(' ')} ${atomEntities(atom).map((entity) => entity.label).join(' ')}`);
+      let best = null; for (const cluster of clusters) { const score = similarity(atomTokens, cluster.centroidTokens); if (!best || score > best.score) best = { cluster, score }; }
+      if (!best || (best.score < threshold && clusters.length < maxClusters)) clusters.push({ members: [atom], tokenSets: [atomTokens], centroidTokens: new Set(atomTokens) });
+      else {
+        best.cluster.members.push(atom); best.cluster.tokenSets.push(atomTokens); const counts = new Map();
+        for (const set of best.cluster.tokenSets) for (const token of set) counts.set(token, (counts.get(token) ?? 0) + 1);
+        best.cluster.centroidTokens = new Set([...counts].filter(([, count]) => count * 2 >= best.cluster.tokenSets.length).map(([token]) => token));
+      }
+    }
+    return { schema: 'enigma.swarm_clusters.v1', swarm_id: this.swarmId, namespace, threshold, clusters: clusters.map((cluster, index) => {
+      const centroidTerms = [...cluster.centroidTokens].sort(); const addresses = cluster.members.map(atomId).sort();
+      return { cluster_id: `cluster_${index + 1}_${sha256(addresses).slice(7, 15)}`, size: addresses.length, memory_addresses: addresses, centroid_terms: centroidTerms, centroid_fingerprint: sha256({ centroid_terms: centroidTerms, memory_addresses: addresses }) };
+    }) };
+  }
+
+  createSnapshot(input = {}) {
+    const { agent, namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.SYNC, input.namespace);
+    const contentIncluded = input.include_content === true;
+    const atoms = [...this.namespaces.get(namespace).values()].map((atom) => replicationAtom(atom, contentIncluded)).sort((a, b) => atomId(a).localeCompare(atomId(b)));
+    return { schema: 'enigma.swarm_snapshot.v1', swarm_id: this.swarmId, namespace, source_agent_id: agent.agent_id, sequence: Number(input.sequence ?? 0), generated_at: input.generated_at ?? new Date().toISOString(), local_simulator: true, network_transmission: false, content_included: contentIncluded, atoms, atom_hashes: Object.fromEntries(atoms.map((atom) => [atomId(atom), atomLeaf(atom)])), merkle_root: computeSwarmMerkleRoot(atoms) };
+  }
+
+  sync(input = {}) {
+    const { namespace } = this.requireAgent(input.agent_id ?? input.agentId, SWARM_PERMISSIONS.SYNC, input.namespace);
+    const snapshot = input.snapshot ?? input.peer_snapshot ?? input.peerSnapshot;
+    if (!snapshot || snapshot.schema !== 'enigma.swarm_snapshot.v1') throw new Error('sync requires an enigma.swarm_snapshot.v1 snapshot');
+    if (snapshot.swarm_id !== this.swarmId) throw new Error('snapshot swarm domain mismatch');
+    if (snapshot.namespace !== namespace) throw new Error('snapshot namespace fence mismatch');
+    if (typeof snapshot.content_included !== 'boolean') throw new Error('snapshot content_included must be a boolean');
+    if (snapshot.content_included === true && input.allow_content !== true) throw new Error('content-bearing snapshot requires explicit allow_content authorization');
+    if (!Array.isArray(snapshot.atoms)) throw new Error('snapshot atoms must be an array');
+    const remoteAtoms = snapshot.atoms;
+    const contentIncluded = snapshot.content_included;
+    if (!contentIncluded) remoteAtoms.forEach(validateSwarmCommitmentAtom);
+    const remoteRoot = computeSwarmMerkleRoot(remoteAtoms);
+    if (remoteRoot !== snapshot.merkle_root) throw new Error('snapshot Merkle root validation failed');
+    const local = this.namespaces.get(namespace);
+    const localProjection = () => [...local.values()].map((atom) => replicationAtom(atom, contentIncluded));
+    const beforeRoot = computeSwarmMerkleRoot(localProjection());
+    const added = []; const updated = []; const unchanged = [];
+    for (const remoteAtom of remoteAtoms) {
+      const id = atomId(remoteAtom); const remoteHash = atomLeaf(remoteAtom);
+      if (!local.has(id)) added.push(id);
+      else if (atomLeaf(replicationAtom(local.get(id), contentIncluded)) !== remoteHash) updated.push(id);
+      else unchanged.push(id);
+      if (input.apply === true && !unchanged.includes(id)) {
+        const next = contentIncluded ? clone(remoteAtom) : { ...(local.get(id) ?? {}), ...clone(remoteAtom) };
+        local.set(id, { ...next, _swarm_hash: atomLeaf(next) });
+      }
+    }
+    const afterRoot = input.apply === true ? computeSwarmMerkleRoot(localProjection()) : beforeRoot;
+    return { schema: 'enigma.swarm_sync_result.v1', swarm_id: this.swarmId, namespace, local_simulator: true, network_transmission: false, validated: true, applied: input.apply === true, content_included: snapshot.content_included === true, before_merkle_root: beforeRoot, peer_merkle_root: remoteRoot, after_merkle_root: afterRoot,
+      diff: { added, updated, unchanged, local_only: [...local.keys()].filter((id) => !remoteAtoms.some((atom) => atomId(atom) === id)).sort() } };
+  }
+
+  status() {
+    const namespaces = [...this.namespaces].map(([namespace, atoms]) => ({ namespace, agent_count: [...this.agents.values()].filter((agent) => agent.namespace === namespace).length, memory_count: atoms.size, merkle_root: computeSwarmMerkleRoot([...atoms.values()]) })).sort((a, b) => a.namespace.localeCompare(b.namespace));
+    return { schema: 'enigma.swarm_status.v1', swarm_id: this.swarmId, local_simulator: true, network_transmission: false, agent_count: this.agents.size, namespace_count: namespaces.length, namespaces };
+  }
+  exportState() {
+    return { schema: 'enigma.swarm_bridge_state.v1', swarm_id: this.swarmId, agents: [...this.agents.values()].map(clone).sort((a, b) => a.agent_id.localeCompare(b.agent_id)), namespaces: Object.fromEntries([...this.namespaces].sort(([a], [b]) => a.localeCompare(b)).map(([namespace, atoms]) => [namespace, [...atoms.values()].map(publicAtom).sort((a, b) => atomId(a).localeCompare(atomId(b)))])) };
+  }
+}
+
+export function createSwarmBridge(state = {}) { return new SwarmMemoryBridge(state); }
+export function enigma_graph_search(bridge, input = {}) {
+  if (!(bridge instanceof SwarmMemoryBridge)) throw new Error('enigma_graph_search requires a SwarmMemoryBridge');
+  return bridge.graphQuery(input);
+}
+export const enigma_graph_query = enigma_graph_search;

package/packages/mesh/index.d.ts

@@ -0,0 +1,283 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export interface MeshIdentity {
+  publicKey: Buffer;
+  secretKey: Buffer;
+  encryptionPublicKey: Buffer;
+  encryptionSecretKey: Buffer;
+  destination: Buffer;
+  destinationHex: string;
+  scope: string;
+}
+
+export declare function generateMeshIdentity(scope?: string): MeshIdentity;
+
+export interface SealedPayload {
+  ciphertext: Buffer;
+  authTag: Buffer;
+  ephemeralPubkey: Buffer;
+}
+
+export declare function sealPayload(
+  plaintext: string | Buffer,
+  recipientX25519PubBytes: Buffer | string,
+  opts?: { aad?: Buffer | string; [key: string]: unknown }
+): SealedPayload;
+
+export declare function unsealPayload(
+  ciphertext: Buffer,
+  authTag: Buffer,
+  ephemeralPubkey: Buffer,
+  recipientX25519PrivBytes: Buffer | string,
+  opts?: { aad?: Buffer | string; [key: string]: unknown }
+): Buffer;
+
+export declare function signPacket(packetBuffer: Buffer, secretKey: Buffer): Buffer;
+export declare function verifyPacketSignature(signedPacketBuffer: Buffer): boolean;
+
+export declare class InMemoryBus {
+  nodes: Map<string, InMemoryTransport>;
+  constructor();
+  register(nodeId: string, transport: InMemoryTransport): void;
+  unregister(nodeId: string): void;
+  deliver(fromNodeId: string, toNodeId: string, packetBuffer: Buffer): void;
+  broadcast(fromNodeId: string, packetBuffer: Buffer): void;
+}
+
+export declare class InMemoryTransport extends EventEmitter {
+  id: string;
+  nodeId: string;
+  bus: InMemoryBus;
+  running: boolean;
+  constructor(nodeId: string, bus: InMemoryBus, id?: string);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  send(rawPacketBuffer: Buffer, peerId?: string): Promise<boolean>;
+  broadcast(rawPacketBuffer: Buffer): Promise<boolean>;
+}
+
+export declare class WebSocketTransport extends EventEmitter {
+  id: string;
+  port?: number;
+  host?: string;
+  running: boolean;
+  constructor(options?: { port?: number; host?: string; id?: string; peers?: string[] });
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  connectToPeer(address: string): Promise<string>;
+  send(rawPacketBuffer: Buffer, peerId?: string): Promise<boolean>;
+  broadcast(rawPacketBuffer: Buffer): Promise<boolean>;
+}
+
+export declare class MeshGossipNode extends EventEmitter {
+  scope: string;
+  identity: MeshIdentity;
+  nodeId: string;
+  router: unknown;
+  transports: Map<string, unknown>;
+  discoveredPeers: Map<string, unknown>;
+
+  constructor(options?: {
+    identity?: MeshIdentity;
+    nodeId?: string;
+    scope?: string;
+    transports?: unknown[];
+  });
+
+  addTransport(transport: unknown): void;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  announce(metadata?: Record<string, unknown>): Promise<Buffer>;
+  sendEncryptedCapsule(
+    destination: Buffer | string,
+    recipientX25519Pub: Buffer | string,
+    memoryContent: string | Record<string, unknown>,
+    opts?: Record<string, unknown>
+  ): Promise<{ packetId: string; deliveredLocally: boolean; routed: boolean }>;
+  getPeers(): Array<Record<string, unknown>>;
+  broadcastZkProof(proofPayload: Record<string, unknown> | Buffer): Promise<Buffer>;
+  broadcastSealedSaleOffer(saleListing: Record<string, unknown> | Buffer): Promise<Buffer>;
+  getStatus(): Record<string, unknown>;
+}
+
+export declare const PROTOCOL_MAGIC: number;
+export declare const PROTOCOL_VERSION: number;
+export declare const HEADER_SIZE: number;
+export declare const MAX_PACKET_SIZE: number;
+export declare const DEFAULT_HOP_TTL: number;
+export declare const PACKET_TYPES: Readonly<{
+  ANNOUNCE: number;
+  MEMORY_CAPSULE: number;
+  ZK_PROOF_GOSSIP: number;
+  SEALED_SALE_OFFER: number;
+  TREE_SYNC_REQ: number;
+  TREE_SYNC_RESP: number;
+  STORE_FORWARD_CHUNK: number;
+  ACK: number;
+  CAPABILITY_GRANT: number;
+  FEDERATED_QUERY_REQUEST: number;
+  FEDERATED_QUERY_RESPONSE: number;
+  CAPABILITY_REVOCATION: number;
+}>;
+
+export interface MeshPacket {
+  magic: number;
+  version: number;
+  type: number;
+  typeName: string;
+  flags: number;
+  hopTtl: number;
+  seqId: number;
+  destination: Buffer;
+  destinationHex: string;
+  senderPubkey: Buffer;
+  senderPubkeyHex: string;
+  ephemeralPubkey: Buffer;
+  ephemeralPubkeyHex: string;
+  payloadLength: number;
+  chunkIndex: number;
+  chunkTotal: number;
+  payload: Buffer;
+  authTag: Buffer;
+  signature: Buffer;
+  rawBytes: Buffer;
+}
+
+export declare function deriveDestination(
+  ed25519PublicKey: Buffer | Uint8Array | string,
+  encryptionPublicKey?: Buffer | Uint8Array | string | { x: string | bigint; y: string | bigint } | null,
+  scope?: string
+): Buffer;
+export declare function encodePacket(packet: {
+  type: number;
+  destination: Buffer | Uint8Array;
+  senderPubkey: Buffer | Uint8Array;
+  ephemeralPubkey?: Buffer | Uint8Array;
+  payload: Buffer | Uint8Array;
+  authTag?: Buffer | Uint8Array;
+  signature?: Buffer | Uint8Array;
+  hopTtl?: number;
+  seqId?: number;
+  chunkIndex?: number;
+  chunkTotal?: number;
+  flags?: number;
+}): Buffer;
+export declare function decodePacket(packetBuffer: Buffer | Uint8Array): MeshPacket;
+export declare function getSignableBytes(packetBuffer: Buffer): Buffer;
+export declare function getPacketReplayIdentity(packetBuffer: Buffer): string;
+
+export type FederationPacketKind =
+  | 'capability_grant'
+  | 'query_request'
+  | 'query_response'
+  | 'capability_revocation';
+
+export interface CapabilityGrantPacketBody {
+  grant: Record<string, unknown>;
+}
+
+export interface FederatedQueryRequestPacketBody {
+  request: Record<string, unknown>;
+  top_k: number;
+}
+
+export interface FederatedQueryResponsePacketBody {
+  ok: boolean;
+  result: Record<string, unknown> | null;
+  error: string | null;
+  request_hash: string;
+}
+
+export interface CapabilityRevocationPacketBody {
+  grant_id: string;
+  revoked_at: string;
+}
+
+export type FederationPacketBody =
+  | CapabilityGrantPacketBody
+  | FederatedQueryRequestPacketBody
+  | FederatedQueryResponsePacketBody
+  | CapabilityRevocationPacketBody;
+
+export interface MeshEndpoint {
+  publicKey: Buffer | Uint8Array | string;
+  encryptionPublicKey: Buffer | Uint8Array | string;
+  destination?: Buffer | Uint8Array | string;
+  destinationHex?: string;
+  scope: string;
+}
+
+export interface FederationPacketCreation {
+  packetId: string;
+  kind: FederationPacketKind;
+  correlationId: string | null;
+  destinationHex: string;
+  packetBuffer: Buffer;
+}
+
+export interface OpenFederationPacket<T = Record<string, unknown>> {
+  packetId: string;
+  correlationId: string | null;
+  kind: FederationPacketKind;
+  body: T;
+  createdAt: string;
+  sender: {
+    publicKey: Buffer;
+    encryptionPublicKey: Buffer;
+    destination: Buffer;
+    destinationHex: string;
+    scope: string;
+  };
+  recipientDestinationHex: string;
+  replayIdentity: string;
+  decoded: MeshPacket;
+}
+
+export declare const GHOSTMESH_FEDERATION_PACKET_SCHEMA: string;
+export declare const FEDERATION_PACKET_KINDS: Readonly<{
+  CAPABILITY_GRANT: 'capability_grant';
+  QUERY_REQUEST: 'query_request';
+  QUERY_RESPONSE: 'query_response';
+  CAPABILITY_REVOCATION: 'capability_revocation';
+}>;
+export declare function hashFederationValue(value: unknown): string;
+export declare function createFederationPacket(options: {
+  kind: FederationPacketKind;
+  body: FederationPacketBody;
+  senderIdentity: MeshIdentity;
+  senderScope?: string;
+  recipient: MeshEndpoint;
+  packetId?: string;
+  correlationId?: string | null;
+  createdAt?: string;
+  hopTtl?: number;
+  seqId?: number;
+}): FederationPacketCreation;
+export declare function openFederationPacket<T = Record<string, unknown>>(
+  packetBuffer: Buffer,
+  options: {
+    recipientIdentity: MeshIdentity;
+    recipientScope?: string;
+    expectedKind?: FederationPacketKind;
+    expectedCorrelationId?: string | null;
+    expectedSenderPublicKey?: Buffer | Uint8Array | string;
+  }
+): OpenFederationPacket<T>;
+
+export declare class PacketRouter {
+  constructor(options?: { nodeIdentity?: MeshIdentity; nodeId?: string });
+  handleIncomingPacket(
+    rawPacket: Buffer,
+    fromPeerId?: string,
+    transportId?: string
+  ): Promise<{
+    action: 'DELIVERED' | 'ROUTED' | 'DROPPED' | 'QUEUED' | 'ANNOUNCED';
+    packet?: MeshPacket;
+    reason?: string;
+    nextHopPeerId?: string;
+    transportId?: string;
+    forwardBuffer?: Buffer;
+  }>;
+  getRoutingStats(): Record<string, unknown>;
+}

package/packages/mesh/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@enigma/mesh",
+  "version": "0.1.22",
+  "description": "GhostMesh: Encrypted P2P Relay Layer with X25519 ECDH and Ed25519 Envelope Signatures",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@enigma/core": "workspace:*",
+    "ws": "^8.21.0"
+  }
+}