enigma-memory 0.1.17 → 0.1.22

package/packages/core/src/index.js

@@ -16,6 +16,37 @@ const ED25519 = 'Ed25519';
 const GENESIS = 'GENESIS';
 const ROOT_RE = /^sha256:[a-f0-9]{64}$/;
 const HASH_RE = /^[a-f0-9]{64}$/;
+const NULLIFIER_RE = /^nullifier:hmac-sha256:[a-f0-9]{64}$/;
+const SECRET_VALUE_RE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:sk|pk|rk)_(?:live|test|proj)_[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|bearer\s+[A-Za-z0-9._~+/=-]{20,})/i;
+const LOCAL_PATH_RE = /^(?:[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|tmp|var|etc|private|Volumes)\/)/;
+const FORBIDDEN_PUBLIC_CLAIM_RE = /\b(?:provider(?:-native)?\s+(?:deletion|memory\s+control)|model\s+forgetting|compliance\s+certification|certif(?:y|ies|ied)\s+compliance|benchmark\s+superiority|hosted\s+(?:saas|cloud)\s+ready|byoc\s+ready|patent(?:ability|able)|legal\s+conclusion|raw\s+embeddings?\s+(?:are\s+)?safe|hardware\s+tamper[-\s]?proof|tamper[-\s]?proof\s+hardware)\b/i;
+const PUBLIC_FORBIDDEN_KEYS = new Set([
+  'api_key',
+  'authorization',
+  'body',
+  'content',
+  'cookie',
+  'credential',
+  'credentials',
+  'embedding',
+  'embeddings',
+  'file_path',
+  'local_path',
+  'password',
+  'plaintext',
+  'private_key',
+  'prompt',
+  'provider_response',
+  'raw',
+  'raw_memory',
+  'response',
+  'secret',
+  'text',
+  'token',
+  'transcript',
+  'vector',
+  'vectors'
+]);
 const RECEIPT_TOP_LEVEL_FIELDS = new Set([
   'schema',
   'receipt_id',
@@ -80,7 +111,7 @@ function canonicalizeValue(value, seen) {
     }
 
     const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null) {
+    if (prototype !== Object.prototype && prototype !== null && prototype.constructor?.name !== 'Object') {
       throw new TypeError('canonical JSON only accepts plain objects, arrays, and primitives');
     }
 
@@ -155,12 +186,12 @@ export function createReceipt(receiptOrArgs, maybeOptions = {}) {
   const previous_receipt_hash = normalizePreviousHash(
     options.previous_receipt_hash ?? options.previousReceiptHash ?? (sequence === 0 ? GENESIS : undefined)
   );
-  const signer = normalizeSigner(options.signer, options.key_id ?? options.keyId, options.privateKey);
   const event_hash = normalizeSha256Root(options.event_hash ?? options.eventHash ?? source.event_hash ?? eventHash(source), 'event_hash');
   const active_set_root = normalizeSha256Root(options.active_set_root ?? options.activeSetRoot ?? EMPTY_MERKLE_ROOT, 'active_set_root');
   const receipt_log_root = normalizeSha256Root(options.receipt_log_root ?? options.receiptLogRoot ?? EMPTY_MERKLE_ROOT, 'receipt_log_root');
   const operation = requiredString(options.operation ?? source.operation, 'operation');
   const timestamp = requiredString(options.timestamp ?? source.timestamp ?? new Date().toISOString(), 'timestamp');
+  const signer = normalizeSigner(options.signer, options.key_id ?? options.keyId, options.privateKey);
 
   const body = {
     schema: RECEIPT_SCHEMA,
@@ -503,6 +534,132 @@ export function createMemoryAddress(args = {}, maybeValue, maybeOptions = {}) {
   return `${prefix}:hmac-sha256:${digest}`;
 }
 
+export function sha256Root(value) {
+  return prefixedSha256(value);
+}
+
+export function publicSafeHash(value, options = {}) {
+  assertPublicSafeFields(value, options);
+  return prefixedSha256(canonicalize(value));
+}
+
+export function merkleSetRoot(values = []) {
+  if (!Array.isArray(values)) throw new TypeError('merkleSetRoot requires an array');
+  return new MerkleSet(values).root();
+}
+
+export function createMerkleRoot(values = []) {
+  return merkleSetRoot(values);
+}
+
+export function createMerkleMembershipProof(valuesOrArgs, maybeValue) {
+  const args = Array.isArray(valuesOrArgs) ? { values: valuesOrArgs, value: maybeValue } : valuesOrArgs ?? {};
+  if (!Array.isArray(args.values)) throw new TypeError('createMerkleMembershipProof requires values');
+  return new MerkleSet(args.values).proveMembership(args.value);
+}
+
+export function verifyMerkleMembershipProof(proofOrArgs, maybeExpectedRoot) {
+  const args = isPlainRecord(proofOrArgs) && Object.prototype.hasOwnProperty.call(proofOrArgs, 'proof')
+    ? proofOrArgs
+    : { proof: proofOrArgs, expectedRoot: maybeExpectedRoot };
+  return MerkleSet.verifyMembership(args.proof, args.expectedRoot ?? args.expected_root ?? args.proof?.root);
+}
+
+export function createMerkleProof(valuesOrArgs, maybeValue) {
+  return createMerkleMembershipProof(valuesOrArgs, maybeValue);
+}
+
+export function verifyMerkleProof(proofOrArgs, maybeExpectedRoot) {
+  return verifyMerkleMembershipProof(proofOrArgs, maybeExpectedRoot);
+}
+
+export function createMerkleNonMembershipProof(valuesOrArgs, maybeValue) {
+  const args = Array.isArray(valuesOrArgs) ? { values: valuesOrArgs, value: maybeValue } : valuesOrArgs ?? {};
+  if (!Array.isArray(args.values)) throw new TypeError('createMerkleNonMembershipProof requires values');
+  return new MerkleSet(args.values).proveNonMembership(args.value);
+}
+
+export function verifyMerkleNonMembershipProof(proofOrArgs, maybeExpectedRoot) {
+  const args = isPlainRecord(proofOrArgs) && Object.prototype.hasOwnProperty.call(proofOrArgs, 'proof')
+    ? proofOrArgs
+    : { proof: proofOrArgs, expectedRoot: maybeExpectedRoot };
+  return MerkleSet.verifyNonMembership(args.proof, args.expectedRoot ?? args.expected_root ?? args.proof?.root);
+}
+
+export function deriveNullifier(args = {}, maybeValue, maybeOptions = {}) {
+  const options = isPlainRecord(args) && (Object.prototype.hasOwnProperty.call(args, 'secret') || Object.prototype.hasOwnProperty.call(args, 'key'))
+    ? args
+    : { secret: args, value: maybeValue, ...maybeOptions };
+  const secret = options.secret ?? options.key;
+  if (secret === undefined) throw new TypeError('deriveNullifier requires a secret key');
+  const payload = {
+    domain: 'enigma.nullifier.v1',
+    scope: options.scope ?? options.namespace ?? 'memory-boundary',
+    subject_ref: options.subject_ref ?? options.subjectRef ?? null,
+    capability_id: options.capability_id ?? options.capabilityId ?? null,
+    policy_id: options.policy_id ?? options.policyId ?? null,
+    value: options.value ?? options.claim ?? options.ref ?? options.components ?? null
+  };
+  return `nullifier:hmac-sha256:${hmacSha256Hex({ key: secret, value: payload })}`;
+}
+
+export function isSha256Root(value) {
+  return ROOT_RE.test(value ?? '');
+}
+
+export function isNullifier(value) {
+  return NULLIFIER_RE.test(value ?? '');
+}
+
+export function verifySha256Root(value, field = 'root') {
+  const ok = isSha256Root(value);
+  return verificationResult(ok, ok ? [] : [`${field} must be a sha256 root`]);
+}
+
+export function verifyNullifier(value, field = 'nullifier') {
+  const ok = isNullifier(value);
+  return verificationResult(ok, ok ? [] : [`${field} must be a nullifier`]);
+}
+
+export function scanPublicSafeFields(value, options = {}) {
+  const errors = [];
+  const forbidden_paths = [];
+  scanPublicSafeValue(value, '$', errors, forbidden_paths, new WeakSet(), options);
+  return verificationResult(errors.length === 0, errors, { forbidden_paths });
+}
+
+export function assertPublicSafeFields(value, options = {}) {
+  const result = scanPublicSafeFields(value, options);
+  if (!result.ok) throw new TypeError(`public-safe scan failed: ${result.errors.join('; ')}`);
+  return value;
+}
+
+export function verifyPublicSafeArtifact(value, options = {}) {
+  const result = scanPublicSafeFields(value, options);
+  return verificationResult(result.ok, result.errors, {
+    forbidden_paths: result.forbidden_paths,
+    public_hash: result.ok ? prefixedSha256(canonicalize(value)) : null
+  });
+}
+
+export function verifyPublicSafeHash(value, maybeExpectedHash, options = {}) {
+  const expected = options.expected_hash ?? options.expectedHash ?? options.hash ?? options.public_hash ?? options.publicHash ?? maybeExpectedHash;
+  const scan = scanPublicSafeFields(value, options);
+  if (!scan.ok) {
+    return verificationResult(false, scan.errors, { forbidden_paths: scan.forbidden_paths, public_hash: null });
+  }
+  const publicHash = prefixedSha256(canonicalize(value));
+  const errors = [];
+  if (expected !== undefined) {
+    try {
+      if (normalizeSha256Root(expected, 'expectedHash') !== publicHash) errors.push('public hash mismatch');
+    } catch {
+      errors.push('expectedHash must be a sha256 root');
+    }
+  }
+  return verificationResult(errors.length === 0, errors, { forbidden_paths: [], public_hash: publicHash });
+}
+
 function bytesForHash(value) {
   if (typeof value === 'string') return value;
   if (Buffer.isBuffer(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
@@ -761,6 +918,96 @@ function withoutUndefinedFields(record) {
   return cleaned;
 }
 
+function scanPublicSafeValue(value, path, errors, forbiddenPaths, seen, options) {
+  if (value === null) return;
+  if (value === undefined) {
+    addPublicSafeError(errors, forbiddenPaths, path, 'undefined is not public-safe JSON');
+    return;
+  }
+  const type = typeof value;
+  if (type === 'string') {
+    scanPublicSafeString(value, path, errors, forbiddenPaths, options);
+    return;
+  }
+  if (type === 'number') {
+    if (!Number.isFinite(value)) addPublicSafeError(errors, forbiddenPaths, path, 'number must be finite');
+    return;
+  }
+  if (type === 'boolean') return;
+  if (type !== 'object') {
+    addPublicSafeError(errors, forbiddenPaths, path, `${type} is not public-safe JSON`);
+    return;
+  }
+  if (seen.has(value)) {
+    addPublicSafeError(errors, forbiddenPaths, path, 'value must not be circular');
+    return;
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (looksLikeEmbeddingVector(value)) addPublicSafeError(errors, forbiddenPaths, path, 'numeric vector-like arrays are not public-safe');
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, index)) {
+          addPublicSafeError(errors, forbiddenPaths, `${path}[${index}]`, 'sparse arrays are not public-safe');
+          continue;
+        }
+        scanPublicSafeValue(value[index], `${path}[${index}]`, errors, forbiddenPaths, seen, options);
+      }
+      return;
+    }
+    if (!isPlainRecord(value)) {
+      addPublicSafeError(errors, forbiddenPaths, path, 'unsupported object is not public-safe JSON');
+      return;
+    }
+    for (const key of Object.keys(value)) {
+      const childPath = `${path}.${key}`;
+      if (isForbiddenPublicKey(key)) addPublicSafeError(errors, forbiddenPaths, childPath, 'field name is not public-safe');
+      scanPublicSafeValue(value[key], childPath, errors, forbiddenPaths, seen, options);
+    }
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function scanPublicSafeString(value, path, errors, forbiddenPaths, options) {
+  if (SECRET_VALUE_RE.test(value)) addPublicSafeError(errors, forbiddenPaths, path, 'secret-shaped string is not public-safe');
+  if (LOCAL_PATH_RE.test(value)) addPublicSafeError(errors, forbiddenPaths, path, 'local absolute path is not public-safe');
+  if (FORBIDDEN_PUBLIC_CLAIM_RE.test(value)) addPublicSafeError(errors, forbiddenPaths, path, 'forbidden public claim is not allowed');
+  if (options.strictStrings === true && !isPublicSafeString(value)) {
+    addPublicSafeError(errors, forbiddenPaths, path, 'string is outside public artifact grammar');
+  }
+}
+
+function isForbiddenPublicKey(key) {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+  if (PUBLIC_FORBIDDEN_KEYS.has(normalized)) return true;
+  return /(?:^|_)(?:plaintext|prompt|response|transcript|embedding|embeddings|vector|vectors|private_key|token|secret|password|api_key|credential|credentials|cookie|authorization)$/.test(normalized);
+}
+
+function looksLikeEmbeddingVector(value) {
+  if (value.length < 32) return false;
+  let numeric = 0;
+  for (const item of value) {
+    if (typeof item === 'number' && Number.isFinite(item)) numeric += 1;
+    else return false;
+  }
+  return numeric === value.length;
+}
+
+function isPublicSafeString(value) {
+  if (value.length === 0) return true;
+  if (ROOT_RE.test(value) || HASH_RE.test(value) || NULLIFIER_RE.test(value)) return true;
+  if (/^[a-z][a-z0-9_]*(?:\.[a-z0-9_]+)*\.v\d+$/u.test(value)) return true;
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u.test(value)) return true;
+  if (/^(?:ok|valid|invalid|active|quarantine|quarantined|tombstone|tombstoned|revoked|granted|omitted|selected|provided|missing|blocked|pass|fail|unknown)$/u.test(value)) return true;
+  return /^[a-z][a-z0-9+.-]*:[A-Za-z0-9._~:@/+?#[\]!$&'()*%,;=-]{1,256}$/u.test(value);
+}
+
+function addPublicSafeError(errors, forbiddenPaths, path, message) {
+  errors.push(`${path}: ${message}`);
+  forbiddenPaths.push(path);
+}
+
 function isPlainRecord(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/packages/core/src/version.mjs

@@ -0,0 +1,7 @@
+// Single source of truth for the package version at runtime.
+// Derived from the repository root package.json — never hard-code versions elsewhere.
+import { readFileSync } from 'node:fs';
+
+const PACKAGE_JSON_URL = new URL('../../../package.json', import.meta.url);
+
+export const ENIGMA_VERSION = JSON.parse(readFileSync(PACKAGE_JSON_URL, 'utf8')).version;

package/packages/dev-tools/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@enigma/dev-tools",
+  "version": "0.1.22",
+  "description": "Enigma Developer Tooling: Vector Benchmarks, Vault Inspectors, and Swarm Simulators",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./benchmark": "./src/vector-benchmark.js",
+    "./inspector": "./src/vault-inspector.js",
+    "./simulator": "./src/swarm-simulator.js"
+  },
+  "dependencies": {
+    "@enigma/core": "workspace:*",
+    "@enigma/rag": "workspace:*",
+    "@enigma/mesh": "workspace:*",
+    "@enigma/vault": "workspace:*"
+  }
+}

package/packages/dev-tools/src/index.js

@@ -0,0 +1,4 @@
+export { runVectorBenchmark } from './vector-benchmark.js';
+export { inspectVaultBundle } from './vault-inspector.js';
+export { simulateSwarmNetwork } from './swarm-simulator.js';
+export { runMemoryBenchmarkSuite } from './memory-benchmark-suite.js';

package/packages/dev-tools/src/memory-benchmark-suite.js

@@ -0,0 +1,112 @@
+// Enigma Developer Tooling: Comprehensive Quantitative Memory Benchmark Suite.
+// Evaluates Recall@10, Temporal Accuracy, Contradiction Resolution,
+// Search Latency Percentiles (P50/P95/P99), and RAM Efficiency.
+import { Enigma } from '../../sdk/src/index.js';
+
+/**
+ * @param {Object} [options]
+ * @param {number} [options.corpusSize]
+ * @param {(options: Object) => Promise<Enigma>} [options.enigmaFactory]
+ */
+export async function runMemoryBenchmarkSuite(options = {}) {
+  const corpusSize = Math.max(10, Math.min(options.corpusSize || 50, 1000));
+  const enigmaFactory = options.enigmaFactory || ((connectOptions) => Enigma.connect(connectOptions));
+  const enigma = await enigmaFactory({ scope: 'benchmark.eval.suite' });
+
+  // 1. Ingest Synthetic Ground Truth Benchmark Dataset
+  const startIngest = Date.now();
+  const testFacts = [
+    // Standard semantic facts
+    { text: 'Solana block production slot duration is targeted at 400 milliseconds.', query: 'What is the slot time on Solana?', expect: true },
+    { text: 'Enigma vaults utilize AES-256-GCM authenticated encryption at rest.', query: 'How does Enigma encrypt vault data?', expect: true },
+    { text: 'GhostMesh implements ephemeral X25519 ECDH session key agreement.', query: 'What key exchange does GhostMesh use?', expect: true },
+    { text: 'The Sealed Sale marketplace compiles an 87,422-constraint Groth16 circuit.', query: 'How many constraints are in the Sealed Sale circuit?', expect: true },
+    { text: 'Aztec-style Indexed Merkle Trees prevent double-spend of revoked nullifiers.', query: 'How does Enigma handle nullifier revocations?', expect: true },
+  ];
+
+  for (let i = 0; i < corpusSize; i++) {
+    const fact = testFacts[i % testFacts.length];
+    await enigma.remember(`${fact.text} [Fact #${i + 1}]`, {
+      type: i % 3 === 0 ? 'policy' : (i % 2 === 0 ? 'preference' : 'semantic'),
+      importance: 1.0 + (i % 5) * 0.2,
+    });
+  }
+  const ingestDurationMs = Date.now() - startIngest;
+  const ingestThroughput = Math.round((corpusSize / (ingestDurationMs / 1000 || 0.001)) * 10) / 10;
+
+  // 2. Measure Recall@10 & Latency Percentiles
+  const queryLatencies = [];
+  let recallHits = 0;
+
+  for (const item of testFacts) {
+    const qStart = performance.now();
+    const results = await enigma.recall(item.query, { topK: 10 });
+    const qDuration = performance.now() - qStart;
+    queryLatencies.push(qDuration);
+
+    const hit = results.some(r => r.text.toLowerCase().includes(item.text.slice(0, 20).toLowerCase()));
+    if (hit) recallHits++;
+  }
+
+  queryLatencies.sort((a, b) => a - b);
+  const p50 = Math.round(queryLatencies[Math.floor(queryLatencies.length * 0.5)] * 100) / 100;
+  const p95 = Math.round(queryLatencies[Math.floor(queryLatencies.length * 0.95)] * 100) / 100;
+  const p99 = Math.round(queryLatencies[queryLatencies.length - 1] * 100) / 100;
+  const recallAt10Percent = Math.round((recallHits / testFacts.length) * 100);
+
+  // 3. Measure Temporal Accuracy
+  // Add historical memory vs current memory
+  const t1 = Date.parse('2026-01-01T00:00:00Z');
+  const t2 = Date.parse('2026-08-01T00:00:00Z');
+
+  const oldLoc = await enigma.remember('User primary residence is Austin, Texas.', {
+    validFrom: t1,
+    validUntil: t2,
+    observedAt: t1,
+  });
+
+  const newLoc = await enigma.remember('User moved and current primary residence is Dallas, Texas.', {
+    validFrom: t2,
+    validUntil: null,
+    observedAt: t2,
+    supersedes: [oldLoc.id],
+  });
+
+  // Query as of Jan 2026 (historical) vs August 2026 (current)
+  const currentRecall = await enigma.recall('primary residence', { asOfTime: Date.parse('2026-08-15T00:00:00Z') });
+  const temporalAccuracy = currentRecall.length > 0 && currentRecall[0].text.includes('Dallas') ? 100 : 0;
+
+  // 4. Measure Contradiction Resolution Rate
+  const activeRecall = await enigma.recall('primary residence', { filterSuperseded: true });
+  const contradictionResolved = activeRecall.every(r => !r.text.includes('Austin')) ? 100 : 0;
+
+  // 5. Memory Footprint Calculation
+  const uncompressedBytes = corpusSize * 384 * 4; // Float32
+  const quantizedBytes = corpusSize * 384 * 1;    // Int8
+  const memoryReductionPercent = Math.round(((uncompressedBytes - quantizedBytes) / uncompressedBytes) * 100);
+
+  return {
+    ok: true,
+    benchmark: 'enigma_memory_intelligence_v1',
+    corpusSize,
+    ingest: {
+      totalDurationMs: ingestDurationMs,
+      throughputPerSecond: ingestThroughput,
+    },
+    retrieval: {
+      queriesEvaluated: testFacts.length,
+      recallAt10Percent,
+      latencyMs: {
+        p50,
+        p95,
+        p99,
+      },
+    },
+    intelligence: {
+      temporalAccuracyPercent: temporalAccuracy,
+      contradictionResolutionRatePercent: contradictionResolved,
+      memoryReductionPercent,
+    },
+    timestamp: Date.now(),
+  };
+}

package/packages/dev-tools/src/swarm-simulator.js

@@ -0,0 +1,101 @@
+// Enigma GhostMesh Multi-Node Swarm Simulator.
+// Simulates P2P routing convergence, multi-hop packet dispatching,
+// and delivery success metrics across N autonomous agent nodes.
+import {
+  MeshGossipNode,
+  InMemoryBus,
+  InMemoryTransport,
+  generateMeshIdentity,
+} from '../../mesh/src/index.js';
+
+export async function simulateSwarmNetwork(options = {}) {
+  const nodeCount = Math.max(2, Math.min(options.nodeCount || 5, 20));
+  const messageCount = Math.max(1, options.messageCount || 10);
+  const bus = new InMemoryBus();
+
+  const nodes = [];
+  const identities = [];
+  const receivedMessages = new Map(); // targetDestinationHex -> Array<plaintext>
+
+  // 1. Initialize nodes
+  for (let i = 0; i < nodeCount; i++) {
+    const identity = generateMeshIdentity();
+    const nodeId = `sim_node_${i + 1}`;
+    const transport = new InMemoryTransport(nodeId, bus);
+    const node = new MeshGossipNode({
+      nodeId,
+      identity,
+      transports: [transport],
+    });
+
+    const destHex = identity.destinationHex;
+    receivedMessages.set(destHex, []);
+    node.on('capsule', ({ plaintext }) => {
+      const list = receivedMessages.get(destHex);
+      if (list) list.push(plaintext);
+    });
+
+    await node.start();
+    nodes.push(node);
+    identities.push(identity);
+  }
+
+  // 2. Announce routes sequentially to establish topology
+  for (let i = 0; i < nodeCount; i++) {
+    await nodes[i].announce({ name: `Agent-${i + 1}`, index: i });
+  }
+  await new Promise(r => setTimeout(r, 60));
+
+  // 3. Dispatch simulated messages across random pairs
+  let deliveredCount = 0;
+  const deliveryLatenciesMs = [];
+
+  for (let m = 0; m < messageCount; m++) {
+    const senderIdx = m % nodeCount;
+    let targetIdx = (m + 1) % nodeCount;
+    if (senderIdx === targetIdx) targetIdx = (targetIdx + 1) % nodeCount;
+
+    const sender = nodes[senderIdx];
+    const target = identities[targetIdx];
+    const payload = `Swarm message #${m + 1} from Node ${senderIdx + 1} to Node ${targetIdx + 1}`;
+
+    const start = Date.now();
+    const res = await sender.sendEncryptedCapsule(
+      target.destinationHex,
+      target.encryptionPublicKey,
+      payload
+    );
+
+    // Wait briefly for in-memory delivery to process
+    await new Promise(r => setTimeout(r, 10));
+
+    const targetInbox = receivedMessages.get(target.destinationHex) || [];
+    const received = targetInbox.includes(payload);
+
+    if (res.routed && received) {
+      deliveredCount++;
+      deliveryLatenciesMs.push(Date.now() - start);
+    }
+  }
+
+  // 4. Teardown
+  for (const n of nodes) {
+    await n.stop();
+  }
+
+  const successRate = Math.round((deliveredCount / messageCount) * 100);
+  const meanLatency = deliveryLatenciesMs.length > 0
+    ? Math.round((deliveryLatenciesMs.reduce((a, b) => a + b, 0) / deliveryLatenciesMs.length) * 10) / 10
+    : 0;
+
+  return {
+    ok: true,
+    simulation: 'ghostmesh_swarm_simulation_v1',
+    nodeCount,
+    messageCount,
+    deliveredCount,
+    deliverySuccessRatePercent: successRate,
+    meanLatencyMs: meanLatency,
+    timestamp: Date.now(),
+  };
+}

package/packages/dev-tools/src/vault-inspector.js

@@ -0,0 +1,114 @@
+// Enigma Vault Bundle Inspector.
+// Analyzes encrypted vault headers, KDF metadata, scope distribution,
+// and Merkle tree roots with strict zero-leakage boundaries.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { deriveKeysFromPassphrase, PBKDF2_KDF_SPEC } from '../../vault/src/index.js';
+
+export async function inspectVaultBundle(bundlePath, options = {}) {
+  const resolved = path.resolve(bundlePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Vault file not found at path: ${resolved}`);
+  }
+
+  const fileStats = fs.statSync(resolved);
+  const rawText = fs.readFileSync(resolved, 'utf8');
+
+  let bundle;
+  try {
+    bundle = JSON.parse(rawText);
+  } catch (err) {
+    throw new Error(`Corrupt JSON in vault file: ${err.message}`);
+  }
+
+  const format = bundle.format || 'unknown';
+  const version = bundle.version || 1;
+  const isEncrypted = typeof bundle.ciphertext === 'string' && typeof bundle.authTag === 'string';
+  const kdf = bundle.kdf || null;
+
+  const inspectionReport = {
+    ok: true,
+    file: {
+      path: resolved,
+      sizeBytes: fileStats.size,
+      updatedAt: fileStats.mtime.toISOString(),
+    },
+    envelope: {
+      format,
+      version,
+      isEncrypted,
+      count: bundle.count || 0,
+      kdf: kdf ? {
+        algorithm: kdf.algorithm,
+        iterations: kdf.iterations,
+        hash: kdf.hash,
+        saltPresent: Boolean(kdf.salt),
+      } : null,
+      ivLengthBytes: bundle.iv ? Buffer.from(bundle.iv, 'hex').length : 0,
+      authTagLengthBytes: bundle.authTag ? Buffer.from(bundle.authTag, 'hex').length : 0,
+    },
+    contents: null,
+  };
+
+  // If passphrase is provided, perform deep inspection
+  if (options.passphrase && isEncrypted) {
+    try {
+      if (!kdf || !kdf.salt) throw new Error('Missing KDF salt in bundle');
+      const saltBuf = /^[0-9a-fA-F]+$/.test(kdf.salt)
+        ? Buffer.from(kdf.salt, 'hex')
+        : Buffer.from(kdf.salt, 'base64');
+      const kdfSpec = {
+        algorithm: kdf.algorithm || 'scrypt',
+        n: kdf.n || 16384,
+        r: kdf.r || 8,
+        p: kdf.p || 1,
+        iterations: kdf.iterations || 600000,
+        hash: kdf.hash || 'sha256',
+      };
+      const vaultKey = deriveKeysFromPassphrase(options.passphrase, saltBuf, kdfSpec).vaultKey;
+
+      const iv = Buffer.from(bundle.iv, 'hex');
+      const authTag = Buffer.from(bundle.authTag, 'hex');
+      const ciphertext = Buffer.from(bundle.ciphertext, 'base64');
+
+      const decipher = crypto.createDecipheriv('aes-256-gcm', vaultKey, iv);
+      if (bundle.aad) {
+        decipher.setAAD(Buffer.isBuffer(bundle.aad) ? bundle.aad : Buffer.from(bundle.aad));
+      }
+      decipher.setAuthTag(authTag);
+      const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      const data = JSON.parse(decrypted.toString('utf8'));
+
+      const scopes = {};
+      const memories = data.memories || [];
+      let oldest = Infinity;
+      let newest = 0;
+
+      for (const m of memories) {
+        const sc = m.scope || 'default';
+        scopes[sc] = (scopes[sc] || 0) + 1;
+        if (m.createdAt && m.createdAt < oldest) oldest = m.createdAt;
+        if (m.createdAt && m.createdAt > newest) newest = m.createdAt;
+      }
+
+      inspectionReport.contents = {
+        unlocked: true,
+        memoryCount: memories.length,
+        scopeDistribution: scopes,
+        timeline: {
+          oldestMemory: oldest !== Infinity ? new Date(oldest).toISOString() : null,
+          newestMemory: newest !== 0 ? new Date(newest).toISOString() : null,
+        },
+        hasVectorBundle: Boolean(data.vectorBundle),
+      };
+    } catch (err) {
+      inspectionReport.contents = {
+        unlocked: false,
+        error: `Decryption failed: ${err.message}`,
+      };
+    }
+  }
+
+  return inspectionReport;
+}