enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/src/index.js

@@ -0,0 +1,1796 @@
+// Enigma Sovereign Agent SDK.
+// Unified entrypoint for local-first encrypted vaults, client-side semantic vector search,
+// GhostMesh P2P gossip, Sealed Sale (ZKCP) marketplace, and memory intelligence.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { EncryptedVectorStore } from '../../rag/src/index.js';
+import { MerkleSet } from '../../core/src/index.js';
+import { deriveDestination } from '../../mesh/src/index.js';
+import {
+  createVault,
+  remember as vaultRemember,
+  recall as vaultRecall,
+  deriveKeysFromPassphrase,
+  DEFAULT_KDF_SPEC,
+  createMemoryReceipt,
+  verifyMemoryReceipt,
+  computeHidingCommitment,
+  verifyCommitmentOpening,
+  MEMORY_RECEIPT_SCHEMA,
+  createErasureReceipt,
+  verifyErasureReceipt,
+  createErasureAttestation,
+  verifyErasureAttestation,
+  secureZeroizeBuffer,
+  ERASURE_RECEIPT_SCHEMA,
+  ERASURE_ATTESTATION_SCHEMA,
+} from '../../vault/src/index.js';
+import { createContextCarrier } from '../../snapcompact/src/index.js';
+import {
+  createBlindedMemoryGrant,
+  verifyBlindedMemoryGrant,
+  EnigmaFederationRouter,
+  BLINDED_GRANT_SCHEMA,
+  createFederatedQueryRequest,
+  verifyFederatedQueryRequest,
+  FEDERATED_QUERY_REQUEST_SCHEMA,
+} from './federation/index.js';
+import { EnigmaRagClient } from './rag-client.js';
+import { EnigmaMeshClient } from './mesh-client.js';
+import { EnigmaMarketClient } from './market-client.js';
+import {
+  normalizeMemoryType,
+  inferMemoryType,
+  createTemporalMetadata,
+  parseTimestamp,
+  isTemporallyActive,
+  computeTemporalDecay,
+  ContradictionGraph,
+  detectContradictions,
+  MemoryDecisionEngine,
+} from './intelligence/index.js';
+
+export const AGENT_TURN_RECEIPT_REF_SCHEMA = 'enigma.agent_turn_receipt_ref.v1';
+const VAULT_BUNDLE_AAD = Buffer.from('enigma.vault_bundle.v1', 'utf8');
+const MAX_RECALL_OVERFETCH = 256;
+
+function cloneStateValue(value) {
+  if (value === undefined) return undefined;
+  return structuredClone(value);
+}
+
+function decodeEnvelopeSalt(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error('Vault envelope KDF salt is missing');
+  }
+  if (/^[0-9a-fA-F]+$/.test(value) && value.length % 2 === 0) {
+    return Buffer.from(value, 'hex');
+  }
+  return Buffer.from(value, 'base64');
+}
+
+function serializeMeshIdentity(identity) {
+  if (!identity) throw new Error('Mesh identity is required for vault persistence');
+  return {
+    schema: 'enigma.mesh_identity.v1',
+    scope: identity.scope,
+    publicKey: Buffer.from(identity.publicKey).toString('hex'),
+    secretKey: Buffer.from(identity.secretKey).toString('hex'),
+    encryptionPublicKey: Buffer.from(identity.encryptionPublicKey).toString('hex'),
+    encryptionSecretKey: Buffer.from(identity.encryptionSecretKey).toString('hex'),
+    destination: Buffer.from(identity.destination).toString('hex'),
+  };
+}
+
+function deserializeMeshIdentity(value, expectedScope) {
+  if (!value || value.schema !== 'enigma.mesh_identity.v1' || value.scope !== expectedScope) {
+    throw new Error('Decrypted vault payload has an invalid mesh identity');
+  }
+  for (const field of ['publicKey', 'secretKey', 'encryptionPublicKey', 'encryptionSecretKey', 'destination']) {
+    if (typeof value[field] !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value[field])) {
+      throw new Error(`Decrypted vault payload has an invalid mesh identity ${field}`);
+    }
+  }
+  const publicKey = Buffer.from(value.publicKey, 'hex');
+  const secretKey = Buffer.from(value.secretKey, 'hex');
+  const encryptionPublicKey = Buffer.from(value.encryptionPublicKey, 'hex');
+  const encryptionSecretKey = Buffer.from(value.encryptionSecretKey, 'hex');
+  const destination = deriveDestination(publicKey, encryptionPublicKey, expectedScope);
+  if (!crypto.timingSafeEqual(destination, Buffer.from(value.destination, 'hex'))) {
+    throw new Error('Decrypted vault payload mesh destination does not match its public keys');
+  }
+  return {
+    publicKey,
+    secretKey,
+    encryptionPublicKey,
+    encryptionSecretKey,
+    destination,
+    destinationHex: destination.toString('hex'),
+    scope: expectedScope,
+  };
+}
+
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+function createBlindedValueCommitment(domain, value) {
+  const blindingFactor = crypto.randomBytes(32).toString('hex');
+  const digest = sha256(value);
+  const commitment = sha256([
+    'enigma.blinded_value_commitment.v1',
+    domain,
+    digest,
+    blindingFactor,
+  ].join('\0'));
+  return {
+    public: Object.freeze({
+      scheme: 'sha256-blinded-v1',
+      domain,
+      value: commitment,
+    }),
+    opening: Object.freeze({
+      schema: 'enigma.blinded_value_commitment.opening.v1',
+      domain,
+      commitment,
+      blindingFactor,
+      digest,
+    }),
+  };
+}
+
+
+function extractModelText(result) {
+  if (typeof result === 'string') return result;
+  if (!result || typeof result !== 'object') return null;
+  for (const key of ['text', 'outputText', 'output_text', 'content']) {
+    if (typeof result[key] === 'string') return result[key];
+  }
+  if (Array.isArray(result.content)) {
+    const text = result.content
+      .map(part => typeof part === 'string' ? part : part?.text)
+      .filter(part => typeof part === 'string')
+      .join('');
+    return text || null;
+  }
+  return null;
+}
+
+function createReceiptRef(receipt) {
+  return {
+    schema: AGENT_TURN_RECEIPT_REF_SCHEMA,
+    receiptId: receipt.receipt_id,
+    memoryId: receipt.memory_id,
+    operation: receipt.operation,
+    commitment: receipt.commitment,
+    previousRoot: receipt.previous_root,
+    newRoot: receipt.new_root,
+    agentPubkey: receipt.agent_pubkey,
+    receiptDigest: sha256(`${receipt.receipt_id}:${receipt.signature}`),
+  };
+}
+const CONTEXT_CARRIER_MODES = new Set(['text', 'bitmap-png', 'auto']);
+
+function publicContextCarrierDecision(decision, requested, reasonOverride = null) {
+  const selected = decision.selected === 'bitmap-png' ? 'bitmap-png' : 'text';
+  const safe = {
+    requested,
+    selected,
+    eligible: decision.eligible === true,
+    reason: reasonOverride || String(decision.reason || 'text-fallback'),
+    profile: typeof decision.profile === 'string' ? decision.profile : null,
+    preparationStatus: selected === 'bitmap-png' ? 'prepared' : 'text-fallback',
+    deliveryConfirmed: false,
+  };
+  if (Number.isInteger(decision.expectedReuse)) safe.expectedReuse = decision.expectedReuse;
+  if (Number.isInteger(decision.frameCount)) safe.frameCount = decision.frameCount;
+  if (decision.estimates && typeof decision.estimates === 'object') {
+    safe.estimates = {
+      textTokens: decision.estimates.textTokens,
+      imageTokens: decision.estimates.imageTokens,
+      textUsd: decision.estimates.textUsd,
+      imageInputUsd: decision.estimates.imageInputUsd,
+      oneTimeDecodeUsd: decision.estimates.oneTimeDecodeUsd,
+      imageUsd: decision.estimates.imageUsd,
+      assumptions: decision.estimates.assumptions,
+    };
+  }
+  return Object.freeze(safe);
+}
+
+function createCanonicalTextCarrier(source, provider, model) {
+  return createContextCarrier({
+    source,
+    provider: String(provider || ''),
+    model: String(model || ''),
+    vision: false,
+  });
+}
+
+function prepareAgentContextCarrier(source, options) {
+  const requested = options.mode === undefined ? 'text' : String(options.mode);
+  if (!CONTEXT_CARRIER_MODES.has(requested)) {
+    throw new TypeError('contextCarrier.mode must be "text", "bitmap-png", or "auto"');
+  }
+  const provider = String(options.provider || '');
+  const model = String(options.model || '');
+  if (requested === 'text') {
+    return { carrier: createCanonicalTextCarrier(source, provider, model), requested, reasonOverride: null };
+  }
+
+  const limits = options.limits ?? options.renderLimits;
+  if (
+    limits
+    && Number.isInteger(limits.maxCharacters)
+    && limits.maxCharacters < source.length
+  ) {
+    return {
+      carrier: createCanonicalTextCarrier(source, provider, model),
+      requested,
+      reasonOverride: 'render-limit-would-truncate-canonical-context',
+    };
+  }
+
+  try {
+    return {
+      carrier: createContextCarrier({
+        source,
+        provider,
+        model,
+        vision: options.vision === true,
+        costs: options.costs ?? options.costAssumptions,
+        expectedReuse: options.expectedReuse,
+        tokenEstimates: options.tokenEstimates,
+        limits,
+        tabWidth: options.tabWidth,
+        collapseRepeatedLines: options.collapseRepeatedLines,
+        repetition: options.repetition,
+      }),
+      requested,
+      reasonOverride: null,
+    };
+  } catch {
+    return {
+      carrier: createCanonicalTextCarrier(source, provider, model),
+      requested,
+      reasonOverride: 'carrier-preparation-failed-closed',
+    };
+  }
+}
+
+function cloneEphemeralProviderBlock(block) {
+  if (block?.source?.type === 'base64') {
+    return {
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: 'image/png',
+        data: block.source.data,
+      },
+    };
+  }
+  if (block?.inlineData?.mimeType === 'image/png') {
+    return { inlineData: { mimeType: 'image/png', data: block.inlineData.data } };
+  }
+  return {
+    type: 'input_image',
+    image_url: block?.image_url || '',
+    detail: block?.detail || 'original',
+  };
+}
+
+function clearEphemeralProviderBlocks(blocks) {
+  for (const block of blocks) {
+    if (block?.source?.type === 'base64') block.source.data = '';
+    if (block?.inlineData?.mimeType === 'image/png') block.inlineData.data = '';
+    if (block?.type === 'input_image') block.image_url = '';
+  }
+}
+
+function zeroizeContextCarrier(carrier, invocationCarrier) {
+  if (invocationCarrier) {
+    invocationCarrier.textFallback = '';
+    clearEphemeralProviderBlocks(invocationCarrier.blocks);
+  }
+  for (const page of carrier?.pages || []) {
+    if (Buffer.isBuffer(page.png)) page.png.fill(0);
+  }
+}
+function sanitizeCarrierEchoes(value, invocationCarrier, disclosure, seen = new WeakMap()) {
+  if (typeof value === 'string' && (
+    value === invocationCarrier?.descriptor?.contextDigest
+    || value === invocationCarrier?.descriptor?.payloadDigest
+  )) return undefined;
+  if (!value || typeof value !== 'object') return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
+  if (seen.has(value)) return seen.get(value);
+  if (
+    value === invocationCarrier
+    || (
+      typeof value.selected === 'string'
+      && typeof value.textFallback === 'string'
+      && Array.isArray(value.blocks)
+      && value.descriptor
+      && value.decision
+    )
+  ) {
+    return disclosure;
+  }
+  if (
+    value?.source?.type === 'base64'
+    || value?.inlineData?.mimeType === 'image/png'
+    || value?.type === 'input_image'
+  ) {
+    return Object.freeze({ omittedCarrierImage: true });
+  }
+
+  const entries = Array.isArray(value)
+    ? value.map((entry, index) => [index, entry])
+    : Object.entries(value);
+  let replacement = value;
+  seen.set(value, value);
+  for (const [entryKey, entryValue] of entries) {
+    const sanitized = sanitizeCarrierEchoes(entryValue, invocationCarrier, disclosure, seen);
+    if (sanitized === entryValue) continue;
+    if (replacement === value) {
+      replacement = Array.isArray(value) ? [...value] : { ...value };
+      seen.set(value, replacement);
+    }
+    replacement[entryKey] = sanitized;
+  }
+  return replacement;
+}
+
+
+function publicContextCarrier(carrier, requested, reasonOverride) {
+  const descriptor = carrier.descriptor;
+  const blindingFactor = crypto.randomBytes(32).toString('hex');
+  const commitment = sha256([
+    'enigma.context_carrier.hiding.v1',
+    descriptor.version,
+    descriptor.codec,
+    descriptor.profile || '',
+    descriptor.contextDigest,
+    descriptor.payloadDigest,
+    blindingFactor,
+  ].join('\0'));
+  return Object.freeze({
+    disclosure: Object.freeze({
+      descriptor: Object.freeze({
+        codec: descriptor.codec,
+        version: descriptor.version,
+        profile: descriptor.profile,
+        commitment: Object.freeze({
+          scheme: 'sha256-blinded-v1',
+          value: commitment,
+        }),
+        dimensions: descriptor.dimensions,
+        bytes: descriptor.bytes,
+        counts: descriptor.counts,
+      }),
+      decision: publicContextCarrierDecision(carrier.decision, requested, reasonOverride),
+    }),
+    opening: Object.freeze({
+      schema: 'enigma.context_carrier.opening.v1',
+      commitment,
+      blindingFactor,
+      contextDigest: descriptor.contextDigest,
+      payloadDigest: descriptor.payloadDigest,
+    }),
+  });
+}
+
+
+export class Enigma {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.scope='enigma.global'] - Memory namespace scope
+   * @param {string} [options.agentId] - Unique agent identifier
+   * @param {Buffer|string} [options.vaultKey] - 32-byte master encryption key
+   * @param {string} [options.passphrase] - Passphrase for automatic PBKDF2/scrypt key derivation
+   * @param {string} [options.storagePath] - Optional local file path for disk-backed encrypted persistence
+   * @param {string} [options.apiBase] - Local daemon URL
+   * @param {string} [options.authToken] - Local IPC authorization token
+   * @param {boolean} [options.ownRagClient=false] - Dispose a supplied RAG client with this Enigma instance
+   * @param {boolean} [options.ownMeshClient=false] - Stop a supplied mesh client with this Enigma instance
+   * @param {boolean} [options.ownMarketClient=false] - Close a supplied market client with this Enigma instance
+   */
+  constructor(options = {}) {
+    this.scope = options.scope || 'enigma.global';
+    this.agentId = options.agentId || `agent_${crypto.randomBytes(4).toString('hex')}`;
+    this.storagePath = options.storagePath ? path.resolve(options.storagePath) : null;
+    this.passphrase = options.passphrase ? String(options.passphrase) : null;
+    this.apiBase = options.apiBase || 'http://127.0.0.1:8787';
+    this.authToken = options.authToken || null;
+    this._kdfSalt = crypto.createHash('sha256')
+      .update(`enigma.vault.salt.${this.scope}`)
+      .digest()
+      .subarray(0, 16);
+    this._meshIdentitySupplied = Boolean(options.identity || options.meshClient);
+
+    if (this.storagePath && !options.vaultKey && !this.passphrase) {
+      throw new Error('Explicit passphrase or vaultKey is required when persistent storagePath is configured.');
+    }
+
+    if (options.vaultKey) {
+      this.vaultKey = Buffer.isBuffer(options.vaultKey) ? options.vaultKey : Buffer.from(options.vaultKey, 'hex');
+    } else if (this.passphrase) {
+      const derived = deriveKeysFromPassphrase(this.passphrase, this._kdfSalt, DEFAULT_KDF_SPEC);
+      this.vaultKey = derived.vaultKey;
+    } else {
+      // Ephemeral in-memory session key
+      this.vaultKey = crypto.randomBytes(32);
+    }
+
+    this.rag = options.ragClient || new EnigmaRagClient();
+    this.mesh = options.meshClient || new EnigmaMeshClient({ scope: this.scope, identity: options.identity, nodeId: this.agentId });
+    this.market = options.marketClient || new EnigmaMarketClient({ apiBase: this.apiBase, authToken: this.authToken });
+    this._ownsRagClient = !options.ragClient || options.ownRagClient === true;
+    this._ownsMeshClient = !options.meshClient || options.ownMeshClient === true;
+    this._ownsMarketClient = !options.marketClient || options.ownMarketClient === true;
+    this._disposePromise = null;
+    // Intelligence Engine components
+    this.contradictionGraph = new ContradictionGraph();
+    this.decisionEngine = new MemoryDecisionEngine();
+    this.federation = new EnigmaFederationRouter({
+      enigma: this,
+      onStateMutation: async () => {
+        if (this.storagePath) await this.save();
+      },
+    });
+
+    /** @type {Map<string, { id: string, text: string, scope: string, type: string, importance: number, createdAt: number, temporal: Object, metadata: Object }>} */
+    this._memories = new Map();
+    /** Receipt/context hiding-commitment openings. Encrypted at rest and never projected through RAG/recall/federation metadata. */
+    this._privateOpenings = new Map();
+    /** @type {string[]} */
+    this._activeCommitments = [];
+    /** @type {Set<string>} */
+    this._activeCommitmentSet = new Set();
+    this._currentRoot = new MerkleSet().root();
+    /** @type {number} */
+    this._sessionEpoch = 0;
+  }
+
+  _snapshotMutableState() {
+    const store = this.rag?.store;
+    const vectorState = store?.documents instanceof Map && store?.vectors instanceof Map
+      ? {
+        epoch: store.epoch,
+        documents: new Map(Array.from(store.documents, ([id, document]) => [id, cloneStateValue(document)])),
+        vectors: new Map(Array.from(store.vectors, ([id, vector]) => [
+          id,
+          ArrayBuffer.isView(vector) ? vector.slice() : cloneStateValue(vector),
+        ])),
+      }
+      : null;
+    return {
+      epoch: this._sessionEpoch,
+      memories: new Map(Array.from(this._memories, ([id, memory]) => [id, cloneStateValue(memory)])),
+      privateOpenings: new Map(Array.from(this._privateOpenings, ([id, opening]) => [id, cloneStateValue(opening)])),
+      activeCommitments: [...this._activeCommitments],
+      currentRoot: this._currentRoot,
+      graph: this.contradictionGraph.exportState(),
+      vectorState,
+    };
+  }
+
+  _restoreMutableState(snapshot) {
+    if (!snapshot || this._sessionEpoch !== snapshot.epoch) return false;
+    this._memories = new Map(Array.from(snapshot.memories, ([id, memory]) => [id, cloneStateValue(memory)]));
+    this._privateOpenings = new Map(Array.from(snapshot.privateOpenings || [], ([id, opening]) => [id, cloneStateValue(opening)]));
+    this._activeCommitments = [...snapshot.activeCommitments];
+    this._activeCommitmentSet = new Set(snapshot.activeCommitments);
+    this._currentRoot = snapshot.currentRoot;
+    const graph = new ContradictionGraph();
+    graph.importState(snapshot.graph);
+    this.contradictionGraph = graph;
+
+    if (snapshot.vectorState) {
+      const store = this.rag?.store;
+      if (!(store?.documents instanceof Map) || !(store?.vectors instanceof Map) || !store.bm25) {
+        throw new Error('Cannot restore vector state: incompatible RAG store');
+      }
+      store.documents.clear();
+      store.vectors.clear();
+      store.bm25.clear();
+      for (const [id, document] of snapshot.vectorState.documents) {
+        const restored = cloneStateValue(document);
+        store.documents.set(id, restored);
+        store.bm25.add(id, restored.text, restored.scope);
+      }
+      for (const [id, vector] of snapshot.vectorState.vectors) {
+        store.vectors.set(id, ArrayBuffer.isView(vector) ? vector.slice() : cloneStateValue(vector));
+      }
+      store.epoch = snapshot.vectorState.epoch;
+    }
+    return true;
+  }
+
+  /**
+   * 3-Line Quickstart Factory: Connects an autonomous agent to Enigma in a single call.
+   * Automatically rehydrates encrypted memories from disk if storagePath is provided.
+   * @param {Object} [options]
+   * @returns {Promise<Enigma>} Connected Enigma instance
+   */
+  static async connect(options = {}) {
+    const instance = new Enigma(options);
+    try {
+      if (instance.storagePath && fs.existsSync(instance.storagePath)) {
+        await instance.load();
+      }
+      if (options.autoStartMesh) {
+        await instance.mesh.start();
+      }
+      return instance;
+    } catch (error) {
+      try {
+        await instance.dispose();
+      } catch {
+        // Preserve the connection failure that triggered cleanup.
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Releases runtime resources owned by this SDK instance without changing
+   * in-memory state or persistent storage. Repeated calls share one cleanup.
+   * Supplied clients remain caller-owned unless their own*Client option is true.
+   * @returns {Promise<void>}
+   */
+  async dispose() {
+    if (this._disposePromise) return this._disposePromise;
+    this._disposePromise = (async () => {
+      const cleanup = [];
+      if (this._ownsRagClient && typeof this.rag?.dispose === 'function') {
+        cleanup.push(Promise.resolve().then(() => this.rag.dispose()));
+      }
+      if (this._ownsMeshClient && typeof this.mesh?.stop === 'function') {
+        cleanup.push(Promise.resolve().then(() => this.mesh.stop()));
+      }
+      if (this._ownsMarketClient) {
+        if (typeof this.market?.dispose === 'function') {
+          cleanup.push(Promise.resolve().then(() => this.market.dispose()));
+        } else if (typeof this.market?.close === 'function') {
+          cleanup.push(Promise.resolve().then(() => this.market.close()));
+        }
+      }
+      const results = await Promise.allSettled(cleanup);
+      const failures = results
+        .filter(result => result.status === 'rejected')
+        .map(result => result.reason);
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1) {
+        throw new AggregateError(failures, 'Failed to dispose Enigma runtime resources');
+      }
+    })();
+    return this._disposePromise;
+  }
+
+  /**
+   * Standalone offline verifier: Verifies cryptographic validity of a signed MemoryReceipt.
+   * @param {Object} receipt
+   * @param {Object} [options]
+   * @returns {Object}
+   */
+  static verifyReceipt(receipt, options = {}) {
+    return verifyMemoryReceipt(receipt, options);
+  }
+  /**
+   * Standalone offline verifier: Verifies cryptographic validity of an ErasureAttestation receipt.
+   * @param {Object} receipt
+   * @param {Object} [options]
+   * @returns {Object}
+   */
+  static verifyErasure(receipt, options = {}) {
+    return verifyErasureReceipt(receipt, options);
+  }
+
+  static verifyAttestation(receipt, options = {}) {
+    return verifyErasureReceipt(receipt, options);
+  }
+
+  /**
+   * Standalone offline verifier: Verifies cryptographic validity of a BlindedMemoryGrant.
+   * @param {Object} grant
+   * @param {Object} [options]
+   * @returns {Object}
+   */
+  static verifyCapability(grant, options = {}) {
+    return verifyBlindedMemoryGrant(grant, options);
+  }
+  /**
+   * Generates a cryptographically signed MemoryReceipt for a stored memory atom
+   * with a cryptographically hiding commitment and Merkle state transition proof.
+   * @param {string} memoryId
+   * @param {Object} [options]
+   * @param {'append'|'update'|'revoke'} [options.operation='append']
+   * @param {string|Buffer} [options.blindingFactor] - Optional custom blinding factor
+   * @returns {Promise<Object>} Signed MemoryReceipt
+   */
+  async createReceipt(memoryId, options = {}) {
+    const opEpoch = this._sessionEpoch;
+    if (Buffer.isBuffer(this.vaultKey) && this.vaultKey.every(b => b === 0)) {
+      throw new Error('Cannot create receipt: session has been reset or zeroized');
+    }
+    const meshIdentity = this.mesh.identity;
+    if (!meshIdentity) throw new Error('Mesh identity is required to sign memory receipts');
+    const mem = this._memories.get(memoryId);
+    if (!mem) throw new Error(`Memory atom ${memoryId} not found`);
+
+    const operation = options.operation ?? 'append';
+    if (!['append', 'update', 'revoke'].includes(operation)) {
+      throw new Error(`Unsupported memory receipt operation "${operation}"`);
+    }
+    const transaction = this._snapshotMutableState();
+    try {
+      let previousRoot = this._currentRoot;
+      let priorCommitments = [];
+      let priorCommitment;
+
+      if (operation === 'append') {
+        if (this._activeCommitmentSet.has(mem.commitment)) {
+          priorCommitments = this._activeCommitments.filter(c => c !== mem.commitment);
+          previousRoot = new MerkleSet(priorCommitments).root();
+        } else {
+          priorCommitments = [...this._activeCommitments];
+          previousRoot = this._currentRoot;
+        }
+      } else if (operation === 'revoke') {
+        if (mem.revoked || !this._activeCommitmentSet.has(mem.commitment)) {
+          throw new Error(`Cannot revoke inactive or already revoked memory atom "${memoryId}" (commitment ${mem.commitment}).`);
+        }
+        priorCommitments = [...this._activeCommitments];
+        previousRoot = this._currentRoot;
+      } else {
+        priorCommitment = options.priorCommitment || mem.commitment;
+        if (!this._activeCommitmentSet.has(priorCommitment)) {
+          throw new Error(`Cannot update inactive or already revoked target commitment "${priorCommitment}".`);
+        }
+        priorCommitments = [...this._activeCommitments];
+        previousRoot = this._currentRoot;
+      }
+
+      const { receipt, opening } = createMemoryReceipt({
+        memoryId,
+        operation,
+        plaintext: mem.text,
+        blindingFactor: options.blindingFactor ?? mem.blindingFactor,
+        previousRoot,
+        priorCommitments,
+        priorCommitment,
+        signingSecretKey: meshIdentity.secretKey,
+        signingPublicKey: meshIdentity.publicKey,
+        metadata: {
+          ...options.metadata,
+          scope: mem.scope,
+          type: mem.type,
+          sessionEpoch: mem.sessionEpoch,
+        },
+      });
+      if (operation === 'update' && receipt.commitment === priorCommitment) {
+        throw new Error('Memory update must produce a fresh commitment');
+      }
+
+      mem.commitment = receipt.commitment;
+      mem.blindingFactor = opening.blindingFactor;
+      this._currentRoot = receipt.new_root;
+
+      if (operation === 'append') {
+        if (!this._activeCommitmentSet.has(receipt.commitment)) {
+          this._activeCommitments.push(receipt.commitment);
+          this._activeCommitmentSet.add(receipt.commitment);
+        }
+      } else if (operation === 'revoke') {
+        this._activeCommitments = this._activeCommitments.filter(c => c !== receipt.commitment);
+        this._activeCommitmentSet.delete(receipt.commitment);
+        mem.revoked = true;
+        this.rag.store.delete(memoryId);
+      } else {
+        this._activeCommitments = this._activeCommitments
+          .filter(c => c !== priorCommitment)
+          .concat(receipt.commitment);
+        this._activeCommitmentSet.delete(priorCommitment);
+        this._activeCommitmentSet.add(receipt.commitment);
+      }
+      if (operation !== 'revoke') {
+        this.rag.updateMetadata(memoryId, {
+          ...mem.metadata,
+          scope: mem.scope,
+          type: mem.type,
+          importance: mem.importance,
+          createdAt: mem.createdAt,
+          updatedAt: mem.updatedAt,
+          temporal: mem.temporal,
+          commitment: mem.commitment,
+          sessionEpoch: mem.sessionEpoch,
+        });
+      }
+
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Operation aborted: session was reset concurrently');
+      }
+      if (options.persist !== false && this.storagePath) await this.save();
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Operation aborted: session was reset concurrently');
+      }
+      return receipt;
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+  }
+
+  /**
+   * Stores a persistent, encrypted memory atom in the local sovereign vault
+   * and indexes it in the local semantic vector store.
+   * Supports ontology types, temporal validity, and contradiction detection.
+   * @param {string} text - Memory content or rule
+   * @param {Object} [options]
+   * @param {string} [options.id] - Optional custom ID (auto-generated if omitted)
+   * @param {string} [options.scope] - Override scope
+   * @param {string} [options.type] - Memory ontology type ('episodic', 'semantic', 'preference', 'policy', etc.)
+   * @param {number} [options.importance=1.0] - Importance multiplier
+   * @param {number|string|Date} [options.validFrom] - Start of validity window
+   * @param {number|string|Date|null} [options.validUntil] - End of validity window
+   * @param {number|string|Date} [options.observedAt] - Time observation was recorded
+   * @param {number} [options.ttlMs] - Time-to-live in milliseconds
+   * @param {string[]} [options.supersedes] - Explicit list of prior memory IDs this atom supersedes
+   * @param {Object} [options.metadata={}] - Custom structured metadata
+   * @returns {Promise<{ id: string, scope: string, text: string, type: string, temporal: Object, createdAt: number }>}
+   */
+  async remember(text, options = {}) {
+    const opEpoch = this._sessionEpoch;
+    if (Buffer.isBuffer(this.vaultKey) && this.vaultKey.every(b => b === 0)) {
+      throw new Error('Cannot store memory: session has been reset or zeroized');
+    }
+    if (!text || typeof text !== 'string' || text.trim().length === 0) {
+      throw new Error('Memory text must be a non-empty string');
+    }
+    const id = options.id || `atom_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    if (this._memories.has(id)) throw new Error(`Memory atom ${id} already exists`);
+    const scope = options.scope || this.scope;
+    const importance = typeof options.importance === 'number' ? options.importance : 1.0;
+    const createdAt = Date.now();
+    const type = normalizeMemoryType(options.type || inferMemoryType(text));
+    const temporal = createTemporalMetadata({
+      validFrom: options.validFrom,
+      validUntil: options.validUntil,
+      observedAt: options.observedAt,
+      ttlMs: options.ttlMs,
+    });
+    const explicitSupersedes = Array.isArray(options.supersedes)
+      ? Array.from(new Set(options.supersedes))
+      : [];
+    for (const priorId of explicitSupersedes) {
+      if (priorId === id) throw new Error('A memory atom cannot supersede itself');
+      const prior = this._memories.get(priorId);
+      if (!prior) throw new Error(`Unknown supersession node: ${priorId}`);
+      if (prior.scope !== scope) {
+        throw new Error(`Cross-scope supersession is not allowed ("${scope}" -> "${prior.scope}")`);
+      }
+    }
+
+    const { commitment, blindingFactor } = computeHidingCommitment(text, options.blindingFactor);
+    const record = {
+      id,
+      text,
+      scope,
+      type,
+      importance,
+      commitment,
+      blindingFactor,
+      createdAt,
+      temporal,
+      sessionEpoch: opEpoch,
+      metadata: { ...options.metadata },
+    };
+
+    const candidates = Array.from(this._memories.values())
+      .filter(m => m.scope === scope && !m.revoked && !this.contradictionGraph.isSuperseded(m.id))
+      .map(m => ({ id: m.id, text: m.text }));
+    const conflicts = detectContradictions(text, candidates);
+    const transaction = this._snapshotMutableState();
+    try {
+      this.contradictionGraph.registerNode(id, { scope });
+      for (const conflict of conflicts) {
+        this.contradictionGraph.recordSupersession(id, conflict.priorId, conflict.reason);
+      }
+      for (const priorId of explicitSupersedes) {
+        this.contradictionGraph.recordSupersession(id, priorId, 'explicit_supersession');
+      }
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+
+    this._memories.set(id, record);
+    this._activeCommitments.push(commitment);
+    this._activeCommitmentSet.add(commitment);
+    this._currentRoot = new MerkleSet(this._activeCommitments).root();
+
+    let indexRes;
+    try {
+      indexRes = await this.rag.index(
+        id,
+        text,
+        {
+          ...options.metadata,
+          scope,
+          type,
+          importance,
+          createdAt,
+          temporal,
+          commitment,
+          sessionEpoch: opEpoch,
+        },
+        { epoch: this.rag.store.epoch }
+      );
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+
+    if (this._sessionEpoch !== opEpoch || !indexRes) {
+      this._restoreMutableState(transaction);
+      throw new Error('Operation aborted: session was reset concurrently');
+    }
+
+    try {
+      if (options.persist !== false && this.storagePath) await this.save();
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Operation aborted: session was reset concurrently');
+      }
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+
+    return { id, scope, text, type, temporal, createdAt };
+  }
+
+  /**
+   * Performs client-side semantic vector search and retrieves top-k relevant memory atoms.
+   * Supports active-state resolution, temporal filtering, and ontology type filtering.
+   * @param {string} query - Agent query or current prompt
+   * @param {Object} [options]
+   * @param {number} [options.topK=5] - Number of results
+   * @param {number} [options.threshold=-1.0] - Minimum similarity threshold
+   * @param {string} [options.scope] - Filter by scope
+   * @param {string} [options.type] - Filter by memory type ('policy', 'preference', 'semantic', etc.)
+   * @param {boolean} [options.filterSuperseded=true] - When true, omits superseded historical facts
+   * @param {number|string|Date} [options.asOfTime] - Target point in time for temporal validity
+   * @returns {Promise<Array<{ id: string, text: string, score: number, scope: string, type: string, superseded: boolean }>>}
+   */
+  async recall(query, options = {}) {
+    if (!query || typeof query !== 'string') return [];
+    const opEpoch = this._sessionEpoch;
+    const topK = options.topK ?? 5;
+    if (typeof topK !== 'number' || !Number.isFinite(topK) || topK < 0) {
+      throw new TypeError('topK must be a finite non-negative number');
+    }
+    if (topK === 0) return [];
+    const requestedCount = Math.ceil(topK);
+    const now = options.asOfTime === undefined
+      ? Date.now()
+      : parseTimestamp(options.asOfTime, null);
+    if (now === null) throw new TypeError('asOfTime must be a valid timestamp');
+    const overfetch = Math.min(
+      Math.max(requestedCount * 4, requestedCount + 16),
+      Math.max(requestedCount, MAX_RECALL_OVERFETCH),
+    );
+    const requestedScope = options.scope || this.scope;
+    const rawResults = await this.rag.search(query, {
+      scope: requestedScope,
+      topK: overfetch,
+      threshold: options.threshold,
+      signal: options.signal,
+    });
+    if (this._sessionEpoch !== opEpoch || options.signal?.aborted) return [];
+
+    const filterSuperseded = options.filterSuperseded !== false;
+    const typeFilter = options.type ? normalizeMemoryType(options.type) : null;
+    const filtered = [];
+    let examined = 0;
+    for (const res of rawResults) {
+      if (examined >= overfetch) break;
+      examined += 1;
+      const mem = this._memories.get(res.id);
+      if (!mem) continue;
+      if (mem.sessionEpoch !== undefined && mem.sessionEpoch !== opEpoch) continue;
+      if (mem.scope !== requestedScope && mem.scope !== 'enigma.global') continue;
+      if (mem.revoked || !mem.commitment || !this._activeCommitmentSet.has(mem.commitment)) continue;
+      const isSup = this.contradictionGraph.isSuperseded(mem.id);
+      if (filterSuperseded && isSup) continue;
+      if (typeFilter && mem.type !== typeFilter) continue;
+      if (!isTemporallyActive(mem, now)) continue;
+
+      const decay = computeTemporalDecay(mem, now);
+      filtered.push({
+        id: mem.id,
+        text: mem.text,
+        scope: mem.scope,
+        type: mem.type,
+        importance: mem.importance,
+        createdAt: mem.createdAt,
+        commitment: mem.commitment,
+        temporal: mem.temporal,
+        metadata: {
+          ...mem.metadata,
+          scope: mem.scope,
+          type: mem.type,
+          importance: mem.importance,
+          createdAt: mem.createdAt,
+          temporal: mem.temporal,
+          commitment: mem.commitment,
+          sessionEpoch: mem.sessionEpoch,
+        },
+        score: Math.round(res.score * decay * 1000) / 1000,
+        superseded: isSup,
+      });
+    }
+
+    if (this._sessionEpoch !== opEpoch || options.signal?.aborted) return [];
+    filtered.sort((a, b) => b.score - a.score);
+    return filtered.slice(0, requestedCount);
+  }
+
+  /**
+   * Evaluates an incoming observation for novelty, importance, and contradiction.
+   * @param {string} text
+   * @param {Object} [metadata={}]
+   */
+  evaluateObservation(text, metadata = {}) {
+    const candidates = Array.from(this._memories.values()).map(m => ({ id: m.id, text: m.text }));
+    return this.decisionEngine.evaluate(text, metadata, candidates);
+  }
+
+  /**
+   * Consolidates redundant memory atoms in the active vault.
+   */
+  consolidate() {
+    const list = Array.from(this._memories.values());
+    return this.decisionEngine.consolidate(list);
+  }
+
+  /**
+   * Compiles a token-budgeted prompt context pack from sovereign memory.
+   * @param {string} query
+   * @param {Object} [options]
+   * @param {number} [options.maxTokens=2000]
+   * @param {number} [options.topK=8]
+   * @returns {Promise<{ contextText: string, items: Array, estimatedTokens: number }>}
+   */
+  async getContextPack(query, options = {}) {
+    const opEpoch = this._sessionEpoch;
+    const maxTokens = options.maxTokens ?? 2000;
+    if (typeof maxTokens !== 'number' || !Number.isFinite(maxTokens) || maxTokens < 0) {
+      throw new TypeError('maxTokens must be a finite non-negative number');
+    }
+    const items = await this.recall(query, {
+      ...options,
+      topK: options.topK ?? 8,
+    });
+    if (this._sessionEpoch !== opEpoch || options.signal?.aborted) {
+      return { contextText: '', items: [], totalChars: 0, estimatedTokens: 0 };
+    }
+
+    const packedItems = [];
+    const sections = [];
+    const maxChars = maxTokens * 4;
+    for (const item of items) {
+      const section = `[Context #${packedItems.length + 1} (${item.scope})]: ${item.text}`;
+      const candidateLength = sections.length === 0
+        ? section.length
+        : sections.join('\n\n').length + 2 + section.length;
+      if (candidateLength > maxChars) break;
+      packedItems.push(item);
+      sections.push(section);
+    }
+    const contextText = sections.join('\n\n');
+    return {
+      contextText,
+      items: packedItems,
+      totalChars: contextText.length,
+      estimatedTokens: Math.ceil(contextText.length / 4),
+    };
+  }
+
+  /**
+   * Replaces a memory atom's plaintext and emits a signed update transition.
+   * @param {string} id
+   * @param {string} text
+   * @param {Object} [options]
+   */
+  async updateMemory(id, text, options = {}) {
+    const opEpoch = this._sessionEpoch;
+    if (!id || !this._memories.has(id)) throw new Error(`Memory atom ${id} not found`);
+    if (!text || typeof text !== 'string' || text.trim().length === 0) {
+      throw new Error('Memory text must be a non-empty string');
+    }
+    const mem = this._memories.get(id);
+    const priorCommitment = mem.commitment;
+    if (mem.revoked || !priorCommitment || !this._activeCommitmentSet.has(priorCommitment)) {
+      throw new Error(`Cannot update inactive or revoked memory atom "${id}"`);
+    }
+    const hasTemporalUpdate = ['validFrom', 'validUntil', 'observedAt', 'ttlMs']
+      .some(key => Object.prototype.hasOwnProperty.call(options, key));
+    const temporal = hasTemporalUpdate
+      ? createTemporalMetadata({
+        validFrom: options.validFrom ?? mem.temporal.validFrom,
+        validUntil: Object.prototype.hasOwnProperty.call(options, 'ttlMs')
+          ? undefined
+          : (Object.prototype.hasOwnProperty.call(options, 'validUntil')
+            ? options.validUntil
+            : mem.temporal.validUntil),
+        observedAt: options.observedAt ?? mem.temporal.observedAt,
+        ttlMs: options.ttlMs,
+      })
+      : mem.temporal;
+    const type = normalizeMemoryType(options.type || mem.type);
+    const importance = typeof options.importance === 'number' ? options.importance : mem.importance;
+    const updatedAt = Date.now();
+    const metadata = { ...mem.metadata, ...options.metadata };
+    const transaction = this._snapshotMutableState();
+
+    try {
+      const indexResult = await this.rag.index(id, text, {
+        ...metadata,
+        scope: mem.scope,
+        type,
+        importance,
+        createdAt: mem.createdAt,
+        updatedAt,
+        temporal,
+        sessionEpoch: opEpoch,
+      }, { epoch: this.rag.store.epoch });
+      if (this._sessionEpoch !== opEpoch || !indexResult) {
+        throw new Error('Memory update aborted: session was reset concurrently');
+      }
+
+      mem.text = text;
+      mem.type = type;
+      mem.importance = importance;
+      mem.temporal = temporal;
+      mem.metadata = metadata;
+      mem.updatedAt = updatedAt;
+      mem.sessionEpoch = opEpoch;
+
+      const receipt = await this.createReceipt(id, {
+        operation: 'update',
+        priorCommitment,
+        blindingFactor: crypto.randomBytes(32),
+        persist: false,
+        metadata: {
+          kind: 'content_update',
+          updatedAt,
+        },
+      });
+      const receiptRef = createReceiptRef(receipt);
+      mem.metadata = { ...mem.metadata, updateReceiptRef: receiptRef };
+      this.rag.updateMetadata(id, {
+        ...mem.metadata,
+        scope: mem.scope,
+        type: mem.type,
+        importance: mem.importance,
+        createdAt: mem.createdAt,
+        updatedAt,
+        temporal: mem.temporal,
+        commitment: mem.commitment,
+        sessionEpoch: opEpoch,
+      });
+
+      if (this.storagePath) await this.save();
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Memory update aborted: session was reset concurrently');
+      }
+      return {
+        memory: {
+          id,
+          scope: mem.scope,
+          text: mem.text,
+          type: mem.type,
+          temporal: mem.temporal,
+          createdAt: mem.createdAt,
+          updatedAt,
+        },
+        receipt,
+        receiptRef,
+      };
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+  }
+
+  /**
+   * Executes one provider-neutral retrieval/model/persistence turn.
+   * @param {{ prompt: string, invoke: Function, metadata?: Object, retrieval?: Object, rememberResponse?: boolean, contextCarrier?: Object }} input
+   */
+  async runAgentTurn(input = {}) {
+    if (!input.prompt || typeof input.prompt !== 'string') {
+      throw new TypeError('runAgentTurn prompt must be a non-empty string');
+    }
+    if (typeof input.invoke !== 'function') {
+      throw new TypeError('runAgentTurn invoke must be a function');
+    }
+    const opEpoch = this._sessionEpoch;
+    const suppliedMetadata = input.metadata && typeof input.metadata === 'object' ? { ...input.metadata } : {};
+    delete suppliedMetadata.contextCarrier;
+    const metadata = suppliedMetadata;
+    const retrieval = input.retrieval && typeof input.retrieval === 'object' ? { ...input.retrieval } : {};
+    const context = await this.getContextPack(input.prompt, retrieval);
+    if (this._sessionEpoch !== opEpoch) {
+      throw new Error('Agent turn aborted: session was reset during retrieval');
+    }
+
+    let carrier = null;
+    let invocationCarrier = null;
+    let disclosedCarrier = null;
+    let carrierOpening = null;
+    if (input.contextCarrier && typeof input.contextCarrier === 'object') {
+      const prepared = prepareAgentContextCarrier(context.contextText, input.contextCarrier);
+      carrier = prepared.carrier;
+      const protectedCarrier = publicContextCarrier(carrier, prepared.requested, prepared.reasonOverride);
+      disclosedCarrier = protectedCarrier.disclosure;
+      carrierOpening = protectedCarrier.opening;
+      invocationCarrier = {
+        selected: carrier.selected,
+        textFallback: carrier.textFallback,
+        blocks: carrier.blocks.map(cloneEphemeralProviderBlock),
+        descriptor: carrier.descriptor,
+        decision: disclosedCarrier.decision,
+      };
+    }
+
+    let result;
+    try {
+      result = await input.invoke({
+        prompt: input.prompt,
+        context: context.contextText,
+        contextPack: context,
+        metadata,
+        ...(invocationCarrier ? { contextCarrier: invocationCarrier } : {}),
+      });
+      if (invocationCarrier) {
+        result = sanitizeCarrierEchoes(result, invocationCarrier, disclosedCarrier);
+      }
+    } finally {
+      zeroizeContextCarrier(carrier, invocationCarrier);
+      carrier = null;
+      invocationCarrier = null;
+    }
+    if (this._sessionEpoch !== opEpoch) {
+      throw new Error('Agent turn aborted: session was reset during model invocation');
+    }
+
+    const receiptRefs = [];
+    let receipt = null;
+    let memory = null;
+    if (input.rememberResponse !== false) {
+      const responseText = extractModelText(result);
+      if (!responseText || responseText.trim().length === 0) {
+        throw new Error('Model result must contain textual output when rememberResponse is enabled');
+      }
+      const transaction = this._snapshotMutableState();
+      try {
+        const turnId = typeof metadata.turnId === 'string' && metadata.turnId
+          ? metadata.turnId
+          : `turn_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+        const promptBinding = createBlindedValueCommitment('agent_turn_prompt', input.prompt);
+        const resultBinding = createBlindedValueCommitment('agent_turn_result', responseText);
+        const contextRefs = context.items.map(item => ({
+          memoryId: item.id,
+          commitment: item.commitment,
+          receiptRef: item.metadata?.agentTurn?.receiptRef || item.metadata?.updateReceiptRef || null,
+        }));
+        const outcomeMetadata = disclosedCarrier
+          ? { ...metadata, contextCarrier: disclosedCarrier }
+          : metadata;
+        memory = await this.remember(responseText, {
+          scope: retrieval.scope || this.scope,
+          type: metadata.memoryType || 'episodic',
+          importance: typeof metadata.importance === 'number' ? metadata.importance : 1,
+          persist: false,
+          metadata: {
+            agentTurn: {
+              turnId,
+              promptCommitment: promptBinding.public,
+              resultCommitment: resultBinding.public,
+              contextRefs,
+              metadata: outcomeMetadata,
+              ...(disclosedCarrier ? { contextCarrier: disclosedCarrier } : {}),
+              ...(carrierOpening ? { contextCarrierCommitment: carrierOpening.commitment } : {}),
+            },
+          },
+        });
+        this._privateOpenings.set(memory.id, {
+          prompt: promptBinding.opening,
+          result: resultBinding.opening,
+          ...(carrierOpening ? { contextCarrier: carrierOpening } : {}),
+        });
+        receipt = await this.createReceipt(memory.id, {
+          persist: false,
+          metadata: {
+            kind: 'agent_turn_outcome',
+            turnId,
+            promptCommitment: promptBinding.public,
+            resultCommitment: resultBinding.public,
+            contextCommitments: contextRefs.map(ref => ref.commitment),
+            ...(disclosedCarrier ? { contextCarrier: disclosedCarrier } : {}),
+          },
+        });
+        const receiptRef = createReceiptRef(receipt);
+        receiptRefs.push(receiptRef);
+        const stored = this._memories.get(memory.id);
+        stored.metadata.agentTurn.receiptRef = receiptRef;
+        this.rag.updateMetadata(memory.id, {
+          ...stored.metadata,
+          scope: stored.scope,
+          type: stored.type,
+          importance: stored.importance,
+          createdAt: stored.createdAt,
+          temporal: stored.temporal,
+          commitment: stored.commitment,
+          sessionEpoch: stored.sessionEpoch,
+        });
+
+        if (this.storagePath) await this.save();
+        if (this._sessionEpoch !== opEpoch) {
+          throw new Error('Agent turn aborted: session was reset before completion');
+        }
+      } catch (error) {
+        this._restoreMutableState(transaction);
+        throw error;
+      }
+    }
+
+    if (this._sessionEpoch !== opEpoch) {
+      throw new Error('Agent turn aborted: session was reset before completion');
+    }
+    return {
+      context,
+      result,
+      memory,
+      receipts: {
+        refs: receiptRefs,
+        memory: receipt,
+      },
+      ...(disclosedCarrier ? { contextCarrier: disclosedCarrier } : {}),
+    };
+  }
+
+  /**
+   * Removes / tombstones a memory atom by ID.
+   * @param {string} id
+   * @returns {Promise<boolean>}
+   */
+  async forget(id) {
+    const opEpoch = this._sessionEpoch;
+    if (!id || !this._memories.has(id)) return false;
+    const mem = this._memories.get(id);
+    if (mem.revoked) return false;
+    const transaction = this._snapshotMutableState();
+    try {
+      if (mem.commitment) {
+        this._activeCommitments = this._activeCommitments.filter(c => c !== mem.commitment);
+        this._activeCommitmentSet.delete(mem.commitment);
+        this._currentRoot = new MerkleSet(this._activeCommitments).root();
+      }
+      mem.revoked = true;
+      mem.revokedAt = Date.now();
+      this.rag.store.delete(id);
+
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Operation aborted: session was reset concurrently');
+      }
+      if (this.storagePath) await this.save();
+      if (this._sessionEpoch !== opEpoch) {
+        throw new Error('Operation aborted: session was reset concurrently');
+      }
+      return true;
+    } catch (error) {
+      this._restoreMutableState(transaction);
+      throw error;
+    }
+  }
+
+  /**
+   * Issues a cryptographically signed BlindedMemoryGrant authorizing another agent
+   * to selectively query memory clusters under strict attribute-based access control (ABAC).
+   * @param {Buffer|string} granteePublicKey - 32-byte Ed25519 public key of receiving agent
+   * @param {Object} [options]
+   * @param {string[]} [options.allowedTypes] - Allowed ontology types ('policy', 'preference', etc.)
+   * @param {number} [options.maxAccessCount=100] - Usage limit (0 = unlimited)
+   * @param {number|string|Date} [options.validUntil] - Expiration timestamp
+   * @param {Object} [options.metadata]
+   * @returns {Object} Signed BlindedMemoryGrant
+   */
+  grantCapability(granteePublicKey, options = {}) {
+    if (!this.mesh.identity) throw new Error('Mesh identity is required to issue capability grants');
+    return createBlindedMemoryGrant({
+      granterAgentId: this.agentId,
+      granterSecretKey: this.mesh.identity.secretKey,
+      granterPublicKey: this.mesh.identity.publicKey,
+      granteePublicKey,
+      scope: options.scope || this.scope,
+      allowedTypes: options.allowedTypes,
+      maxAccessCount: options.maxAccessCount,
+      validUntil: options.validUntil,
+      metadata: options.metadata,
+    });
+  }
+
+  /**
+   * Resets local session state, wipes volatile keyrings/vector indices, unlinks
+   * on-disk vault storage, and emits a signed ErasureAttestation receipt.
+   * @param {Object} [options]
+   * @param {boolean} [options.wipeStorage=true] - Whether to scrub and unlink the on-disk storage file
+   * @param {Object} [options.metadata]
+   * @returns {Promise<Object>} Signed ErasureAttestation receipt
+   */
+  async resetSession(options = {}) {
+    ++this._sessionEpoch;
+    const meshIdentity = this.mesh.identity;
+    if (!meshIdentity) throw new Error('Mesh identity is required to sign erasure attestation receipts');
+
+    const preErasureRoot = this._currentRoot;
+    const memoryCount = this._memories.size;
+    const activeCommitments = [...this._activeCommitments];
+    const shouldWipeStorage = options.wipeStorage !== false;
+    let storageWiped = false;
+    if (shouldWipeStorage && this.storagePath && fs.existsSync(this.storagePath)) {
+      try {
+        const fileSize = fs.statSync(this.storagePath).size;
+        fs.writeFileSync(this.storagePath, crypto.randomBytes(Math.max(fileSize, 512)));
+        fs.unlinkSync(this.storagePath);
+        storageWiped = true;
+      } catch {
+        try {
+          fs.unlinkSync(this.storagePath);
+          storageWiped = true;
+        } catch {
+          storageWiped = false;
+        }
+      }
+    }
+
+    // 2. Generate signed cryptographic ErasureAttestation receipt before wiping key material
+    const erasureReceipt = createErasureReceipt({
+      agentId: this.agentId,
+      scope: this.scope,
+      erasedMemoryCount: memoryCount,
+      preErasureRoot,
+      activeCommitments,
+      storageWiped,
+      signingSecretKey: meshIdentity.secretKey,
+      signingPublicKey: meshIdentity.publicKey,
+      metadata: options.metadata,
+    });
+
+    // 3. Best-effort zeroize master key buffer in volatile memory
+    if (Buffer.isBuffer(this.vaultKey)) {
+      secureZeroizeBuffer(this.vaultKey);
+    }
+
+    // 4. Purge in-memory state collections, zero typed arrays, and reset BM25 indices
+    this._memories.clear();
+    this._privateOpenings.clear();
+    this._activeCommitments = [];
+    this._activeCommitmentSet.clear();
+    this._currentRoot = new MerkleSet().root();
+    this.contradictionGraph = new ContradictionGraph();
+    this.federation = new EnigmaFederationRouter({
+      enigma: this,
+      onStateMutation: async () => {
+        if (this.storagePath) await this.save();
+      },
+    });
+    if (this.rag?.store && typeof this.rag.store.clear === 'function') {
+      this.rag.store.clear();
+    }
+
+    return erasureReceipt;
+  }
+
+  async zeroizeSession(options = {}) {
+    return await this.resetSession(options);
+  }
+  /**
+   * Persists all memory atoms and vector embeddings encrypted-at-rest to disk using AES-256-GCM.
+   * @param {string} [targetPath]
+   */
+  async save(targetPath = this.storagePath) {
+    if (!targetPath) return;
+    if (Buffer.isBuffer(this.vaultKey) && this.vaultKey.every(b => b === 0)) {
+      return;
+    }
+    const saveEpoch = this._sessionEpoch;
+    const resolvedPath = path.resolve(targetPath);
+    const dir = path.dirname(resolvedPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const payload = JSON.stringify({
+      schema: 'enigma.agent_vault.v3',
+      version: 3,
+      agentId: this.agentId,
+      scope: this.scope,
+      sessionEpoch: this._sessionEpoch,
+      activeCommitments: this._activeCommitments,
+      memories: Array.from(this._memories.values()),
+      privateOpenings: Array.from(this._privateOpenings.entries()),
+      supersessionGraph: this.contradictionGraph.exportState(),
+      vectorBundle: this.rag.encryptAtRest(this.vaultKey),
+      meshIdentity: serializeMeshIdentity(this.mesh.identity),
+      federationState: this.federation.exportState(),
+    });
+
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.vaultKey, iv);
+    cipher.setAAD(VAULT_BUNDLE_AAD);
+    const ciphertext = Buffer.concat([cipher.update(Buffer.from(payload, 'utf8')), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const envelope = {
+      format: 'enigma.vault_bundle.v1',
+      version: 1,
+      kdf: {
+        algorithm: DEFAULT_KDF_SPEC.algorithm || 'scrypt',
+        n: DEFAULT_KDF_SPEC.n || 16384,
+        r: DEFAULT_KDF_SPEC.r || 8,
+        p: DEFAULT_KDF_SPEC.p || 1,
+        maxmem: DEFAULT_KDF_SPEC.maxmem,
+        salt: this._kdfSalt.toString('hex'),
+      },
+      aad: 'enigma.vault_bundle.v1',
+      ciphertext: ciphertext.toString('base64'),
+      iv: iv.toString('hex'),
+      authTag: authTag.toString('hex'),
+      count: this._memories.size,
+    };
+    if (this._sessionEpoch !== saveEpoch) return;
+
+    const serialized = JSON.stringify(envelope, null, 2);
+    let tempPath = path.join(
+      dir,
+      `.${path.basename(resolvedPath)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`,
+    );
+    let descriptor;
+    try {
+      descriptor = fs.openSync(tempPath, 'wx', 0o600);
+      fs.writeFileSync(descriptor, serialized, 'utf8');
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      if (this._sessionEpoch !== saveEpoch) return;
+      fs.renameSync(tempPath, resolvedPath);
+      tempPath = null;
+      try {
+        const directoryDescriptor = fs.openSync(dir, 'r');
+        try {
+          fs.fsyncSync(directoryDescriptor);
+        } finally {
+          fs.closeSync(directoryDescriptor);
+        }
+      } catch {
+        // Some platforms cannot open or fsync directory handles; the file itself is already synced.
+      }
+    } finally {
+      if (descriptor !== undefined) {
+        try {
+          fs.closeSync(descriptor);
+        } catch {
+          // Preserve the primary persistence error.
+        }
+      }
+      if (tempPath) {
+        try {
+          fs.unlinkSync(tempPath);
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+      }
+    }
+  }
+
+  /**
+   * Decrypts and rehydrates memories and vector embeddings from an on-disk vault file.
+   * @param {string} [sourcePath]
+   */
+  async load(sourcePath = this.storagePath) {
+    const loadEpoch = this._sessionEpoch;
+    if (!sourcePath) return;
+    const resolvedPath = path.resolve(sourcePath);
+    if (!fs.existsSync(resolvedPath)) return;
+
+    let envelope;
+    try {
+      envelope = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+    } catch (error) {
+      throw new Error(`Failed to parse vault file at ${resolvedPath}: ${error.message}`);
+    }
+    if (!envelope || (!envelope.format?.startsWith('enigma') && envelope.format !== 'enigma_encrypted_vault_v2')
+      || !envelope.ciphertext || !envelope.iv || !envelope.authTag) {
+      throw new Error(`Incompatible or corrupted vault format at ${resolvedPath}.`);
+    }
+    if (envelope.aad !== undefined && envelope.aad !== 'enigma.vault_bundle.v1') {
+      throw new Error(`Incompatible vault envelope AAD at ${resolvedPath}.`);
+    }
+    if (Buffer.isBuffer(this.vaultKey) && this.vaultKey.every(byte => byte === 0)) {
+      throw new Error(`Decryption failed for ${resolvedPath}: vault key is zeroed`);
+    }
+
+    const keyCandidates = [];
+    if (this.passphrase && envelope.kdf?.salt) {
+      const saltCandidates = [decodeEnvelopeSalt(envelope.kdf.salt)];
+      if (/^[0-9a-fA-F]+$/.test(envelope.kdf.salt) && envelope.kdf.salt.length % 2 === 0) {
+        const base64Salt = Buffer.from(envelope.kdf.salt, 'base64');
+        if (base64Salt.length >= 8 && base64Salt.length <= 64
+          && !base64Salt.equals(saltCandidates[0])) {
+          saltCandidates.push(base64Salt);
+        }
+      }
+      for (const salt of saltCandidates) {
+        const derived = deriveKeysFromPassphrase(this.passphrase, salt, envelope.kdf);
+        keyCandidates.push({ key: derived.vaultKey, salt });
+      }
+    }
+    keyCandidates.push({ key: this.vaultKey, salt: this._kdfSalt });
+    const uniqueKeyCandidates = [];
+    const seenKeys = new Set();
+    for (const candidate of keyCandidates) {
+      const keyHex = Buffer.from(candidate.key).toString('hex');
+      if (!seenKeys.has(keyHex)) {
+        seenKeys.add(keyHex);
+        uniqueKeyCandidates.push(candidate);
+      }
+    }
+    const aadCandidates = envelope.aad === 'enigma.vault_bundle.v1'
+      ? [VAULT_BUNDLE_AAD]
+      : [VAULT_BUNDLE_AAD, null];
+
+    let plaintextBytes;
+    let loadedKey;
+    let loadedSalt;
+    let loadedWithAad = false;
+    let decryptionError;
+    for (const candidate of uniqueKeyCandidates) {
+      for (const aad of aadCandidates) {
+        try {
+          const decipher = crypto.createDecipheriv(
+            'aes-256-gcm',
+            candidate.key,
+            Buffer.from(envelope.iv, 'hex'),
+          );
+          if (aad) decipher.setAAD(aad);
+          decipher.setAuthTag(Buffer.from(envelope.authTag, 'hex'));
+          plaintextBytes = Buffer.concat([
+            decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+            decipher.final(),
+          ]);
+          loadedKey = Buffer.from(candidate.key);
+          loadedSalt = candidate.salt;
+          loadedWithAad = Boolean(aad);
+          break;
+        } catch (error) {
+          decryptionError = error;
+        }
+      }
+      if (plaintextBytes) break;
+    }
+    if (!plaintextBytes) {
+      throw new Error(
+        `Decryption failed for ${resolvedPath}: invalid passphrase/key or corrupted ciphertext. (${decryptionError?.message || 'authentication failed'})`,
+      );
+    }
+    if (this._sessionEpoch !== loadEpoch) return;
+
+    let data;
+    try {
+      data = JSON.parse(plaintextBytes.toString('utf8'));
+    } catch (error) {
+      throw new Error(`Decrypted vault payload is invalid JSON: ${error.message}`);
+    }
+    if (!data || !['enigma.agent_vault.v2', 'enigma.agent_vault.v3'].includes(data.schema)
+      || !Array.isArray(data.memories)) {
+      throw new Error('Decrypted vault payload has an invalid schema or memory collection');
+    }
+    if (data.scope !== this.scope) {
+      throw new Error(`Decrypted vault scope "${data.scope}" does not match requested scope "${this.scope}"`);
+    }
+
+    const loadedEpoch = Number.isSafeInteger(data.sessionEpoch) && data.sessionEpoch >= 0
+      ? data.sessionEpoch
+      : 0;
+    const loadedMemories = new Map();
+    const knownNodes = new Map();
+    for (const value of data.memories) {
+      if (!value || typeof value.id !== 'string' || !value.id
+        || typeof value.text !== 'string' || !value.text
+        || typeof value.scope !== 'string' || !value.scope
+        || typeof value.commitment !== 'string') {
+        throw new Error('Decrypted vault payload contains an invalid memory atom');
+      }
+      if (loadedMemories.has(value.id)) {
+        throw new Error(`Decrypted vault payload contains duplicate memory atom "${value.id}"`);
+      }
+      if (value.temporal) {
+        createTemporalMetadata({
+          validFrom: value.temporal.validFrom,
+          validUntil: value.temporal.validUntil,
+          observedAt: value.temporal.observedAt,
+        });
+      }
+      const memory = {
+        ...value,
+        sessionEpoch: loadedEpoch,
+        metadata: value.metadata && typeof value.metadata === 'object' ? value.metadata : {},
+      };
+      loadedMemories.set(memory.id, memory);
+      knownNodes.set(memory.id, memory.scope);
+    }
+    const loadedPrivateOpenings = new Map();
+    if (data.privateOpenings !== undefined) {
+      if (!Array.isArray(data.privateOpenings)) {
+        throw new Error('Decrypted vault payload has an invalid private opening collection');
+      }
+      for (const entry of data.privateOpenings) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string'
+          || !loadedMemories.has(entry[0]) || !entry[1] || typeof entry[1] !== 'object'
+          || loadedPrivateOpenings.has(entry[0])) {
+          throw new Error('Decrypted vault payload contains an invalid private opening entry');
+        }
+        loadedPrivateOpenings.set(entry[0], cloneStateValue(entry[1]));
+      }
+    }
+
+    const activeCommitments = Array.isArray(data.activeCommitments)
+      ? [...data.activeCommitments]
+      : Array.from(loadedMemories.values())
+        .filter(memory => !memory.revoked)
+        .map(memory => memory.commitment);
+    const activeCommitmentSet = new Set(activeCommitments);
+    if (activeCommitments.some(value => typeof value !== 'string')
+      || activeCommitmentSet.size !== activeCommitments.length) {
+      throw new Error('Decrypted vault payload has invalid active commitments');
+    }
+    const commitmentOwners = new Map();
+    for (const memory of loadedMemories.values()) {
+      if (commitmentOwners.has(memory.commitment)) {
+        throw new Error(`Decrypted vault payload reuses commitment "${memory.commitment}"`);
+      }
+      commitmentOwners.set(memory.commitment, memory);
+    }
+    for (const commitment of activeCommitments) {
+      const owner = commitmentOwners.get(commitment);
+      if (!owner) {
+        throw new Error(`Decrypted vault payload references unknown active commitment "${commitment}"`);
+      }
+      if (owner.revoked) {
+        throw new Error(`Decrypted vault payload marks revoked commitment "${commitment}" as active`);
+      }
+    }
+
+    const loadedGraph = new ContradictionGraph();
+    if (data.supersessionGraph) {
+      loadedGraph.importState(data.supersessionGraph, knownNodes);
+    } else {
+      for (const [id, scope] of knownNodes) loadedGraph.registerNode(id, { scope });
+    }
+    const loadedRag = data.vectorBundle
+      ? EnigmaRagClient.fromEncryptedBundle(data.vectorBundle, loadedKey)
+      : new EnigmaRagClient();
+    for (const id of Array.from(loadedRag.store.documents.keys())) {
+      const memory = loadedMemories.get(id);
+      if (!memory || memory.revoked || !activeCommitmentSet.has(memory.commitment)) {
+        loadedRag.store.delete(id);
+      }
+    }
+    for (const memory of loadedMemories.values()) {
+      if (activeCommitmentSet.has(memory.commitment) && !loadedRag.store.documents.has(memory.id)) {
+        throw new Error(`Decrypted vault payload is missing the vector record for active memory "${memory.id}"`);
+      }
+    }
+
+    let loadedMesh = this.mesh;
+    if (data.meshIdentity) {
+      const identity = deserializeMeshIdentity(data.meshIdentity, this.scope);
+      if (this._meshIdentitySupplied) {
+        const sameSigningKey = crypto.timingSafeEqual(Buffer.from(this.mesh.identity.publicKey), identity.publicKey);
+        const sameEncryptionKey = crypto.timingSafeEqual(
+          Buffer.from(this.mesh.identity.encryptionPublicKey),
+          identity.encryptionPublicKey,
+        );
+        if (!sameSigningKey || !sameEncryptionKey) {
+          throw new Error('Decrypted vault mesh identity does not match the supplied local mesh identity');
+        }
+      } else {
+        loadedMesh = new EnigmaMeshClient({
+          scope: this.scope,
+          identity,
+          nodeId: typeof data.agentId === 'string' && data.agentId ? data.agentId : this.agentId,
+        });
+      }
+    } else if (data.federationState) {
+      throw new Error('Decrypted vault federation state is missing its bound mesh identity');
+    }
+
+    const federationOwner = { mesh: loadedMesh };
+    const loadedFederation = new EnigmaFederationRouter({
+      enigma: federationOwner,
+      state: data.federationState,
+      onStateMutation: async () => {
+        if (this.storagePath) await this.save();
+      },
+    });
+    loadedFederation.enigma = this;
+
+    if (this._sessionEpoch !== loadEpoch) return;
+    this._memories = loadedMemories;
+    this._privateOpenings = loadedPrivateOpenings;
+    this._activeCommitments = activeCommitments;
+    this._activeCommitmentSet = activeCommitmentSet;
+    this._currentRoot = new MerkleSet(activeCommitments).root();
+    this.contradictionGraph = loadedGraph;
+    this.rag = loadedRag;
+    this.mesh = loadedMesh;
+    this.federation = loadedFederation;
+    this.vaultKey = loadedKey;
+    if (loadedSalt) this._kdfSalt = Buffer.from(loadedSalt);
+    if (typeof data.agentId === 'string' && data.agentId) this.agentId = data.agentId;
+    this._sessionEpoch = loadedEpoch;
+
+    const needsMigration = envelope.aad !== 'enigma.vault_bundle.v1'
+      || !loadedWithAad
+      || !data.meshIdentity
+      || !data.federationState;
+    if (needsMigration) await this.save(resolvedPath);
+  }
+  /**
+   * Returns current local agent sovereign memory metrics and active status.
+   * @returns {Object}
+   */
+  status() {
+    return {
+      agentId: this.agentId,
+      scope: this.scope,
+      memoryCount: this._memories.size,
+      vectorCount: this.rag.store.documents.size,
+      storagePath: this.storagePath,
+      meshConnected: this.mesh.status().peersCount > 0,
+      activeRules: Array.from(this._memories.values()).filter(m => m.type === 'policy').length,
+      contradictionsTracked: this.contradictionGraph.edges.size,
+    };
+  }
+}
+
+// Re-export intelligence sub-modules and cryptographic receipt utilities
+export * from './intelligence/index.js';
+export * from './federation/index.js';
+export * from './rag-client.js';
+export * from './mesh-client.js';
+export * from './market-client.js';
+export * from './swarm-orchestrator.js';
+export * from './middleware/index.js';
+export * from '../../snapcompact/src/index.js';
+export {
+  createMemoryReceipt,
+  verifyMemoryReceipt,
+  computeHidingCommitment,
+  verifyCommitmentOpening,
+  MEMORY_RECEIPT_SCHEMA,
+  createErasureReceipt,
+  verifyErasureReceipt,
+  createErasureAttestation,
+  verifyErasureAttestation,
+  secureZeroizeBuffer,
+  ERASURE_RECEIPT_SCHEMA,
+  ERASURE_ATTESTATION_SCHEMA,
+  createBlindedMemoryGrant,
+  verifyBlindedMemoryGrant,
+  BLINDED_GRANT_SCHEMA,
+  createFederatedQueryRequest,
+  verifyFederatedQueryRequest,
+  FEDERATED_QUERY_REQUEST_SCHEMA,
+};