@anuma/sdk 4.2.0 → 5.0.0

package/dist/server/index.cjs

@@ -15012,14 +15012,11 @@ function notifyKeyAvailable(address) {
     }
   }
 }
-function getStoredKey(address) {
-  const keys = encryptionKeyStore.get(address);
-  return keys?.current ?? null;
-}
 function getStoredKeyByVersion(address, version) {
   const keys = encryptionKeyStore.get(address);
   if (!keys) return null;
-  return version === "v2" ? keys.legacy : keys.current;
+  const value = version === "v2" ? keys.legacy : keys.current;
+  return value ?? null;
 }
 function setStoredKey(address, keys) {
   encryptionKeyStore.set(address, keys);
@@ -15028,6 +15025,8 @@ function clearEncryptionKey(address) {
   encryptionKeyStore.delete(address);
   cryptoKeyCache.delete(`${address}:v2`);
   cryptoKeyCache.delete(`${address}:v3`);
+  refreshCandidatesByAddress.delete(address);
+  divergentDeriveAddresses.delete(address);
 }
 function clearAllEncryptionState() {
   sessionEpoch += 1;
@@ -15035,6 +15034,9 @@ function clearAllEncryptionState() {
   cryptoKeyCache.clear();
   keyAvailableCallbacks.clear();
   pendingKeyRequests.clear();
+  pendingCandidateDerives.clear();
+  refreshCandidatesByAddress.clear();
+  divergentDeriveAddresses.clear();
   clearAllKeyPairs();
   for (const cb of clearAllEncryptionStateCallbacks) {
     try {
@@ -15218,9 +15220,7 @@ async function getEncryptionKey(address, version = "v3") {
   }
   const keyHex = getStoredKeyByVersion(address, version);
   if (!keyHex) {
-    throw new Error(
-      "Encryption key not found. Please sign a message to generate your encryption key."
-    );
+    throw new EncryptionKeyMissingError(address, version);
   }
   const keyBytes = hexToBytes(keyHex);
   const cryptoKey = await crypto.subtle.importKey(
@@ -15284,8 +15284,42 @@ async function decryptDataBytesFromBytes(encrypted, address, version = "v3") {
   );
   return new Uint8Array(decryptedData);
 }
-function hasEncryptionKey(address) {
-  return getStoredKey(address) !== null;
+function hasEncryptionKey(address, version) {
+  return getStoredKeyByVersion(address, version ?? "v3") !== null;
+}
+function seedEncryptionKeys(address, keys) {
+  if (!isValidWalletAddress(address)) {
+    throw new Error(
+      `Invalid wallet address: ${address}. Address must start with 0x and be 42 characters (0x + 40 hex characters).`
+    );
+  }
+  if (!keys.legacy && !keys.current) {
+    throw new Error("seedEncryptionKeys: at least one of legacy or current is required");
+  }
+  if (keys.legacy !== void 0) {
+    assertAes256KeyHex("legacy", keys.legacy);
+  }
+  if (keys.current !== void 0) {
+    assertAes256KeyHex("current", keys.current);
+  }
+  const existing = encryptionKeyStore.get(address);
+  const next = {
+    legacy: keys.legacy ?? existing?.legacy,
+    current: keys.current ?? existing?.current
+  };
+  setStoredKey(address, next);
+  if (keys.legacy !== void 0) cryptoKeyCache.delete(`${address}:v2`);
+  if (keys.current !== void 0) cryptoKeyCache.delete(`${address}:v3`);
+  refreshCandidatesByAddress.delete(address);
+  divergentDeriveAddresses.delete(address);
+  notifyKeyAvailable(address);
+}
+function assertAes256KeyHex(field10, value) {
+  if (!AES_256_KEY_HEX.test(value)) {
+    throw new Error(
+      `seedEncryptionKeys: ${field10} must be 64 hex characters (32-byte AES key), got length ${value.length}`
+    );
+  }
 }
 async function encryptBytesWithKey(plaintext, key) {
   const plaintextBytes = typeof plaintext === "string" ? SHARED_TEXT_ENCODER.encode(plaintext) : plaintext;
@@ -15334,20 +15368,23 @@ async function decryptDataBatch(encryptedValues, address) {
   const key = await getEncryptionKey(address);
   return Promise.all(encryptedValues.map((value) => decryptDataWithKey(value, key)));
 }
-async function requestEncryptionKey(walletAddress, signMessage, embeddedWalletSigner) {
+async function requestEncryptionKey(walletAddress, signMessage, embeddedWalletSigner, options) {
   if (!isValidWalletAddress(walletAddress)) {
     throw new Error(
       `Invalid wallet address: ${walletAddress}. Address must start with 0x and be 42 characters (0x + 40 hex characters).`
     );
   }
-  const existingKey = getStoredKey(walletAddress);
-  if (existingKey) {
-    return;
+  if (!options?.force && getStoredKeyByVersion(walletAddress, "v3") && getStoredKeyByVersion(walletAddress, "v2")) {
+    return true;
   }
-  const pending = pendingKeyRequests.get(walletAddress);
-  if (pending) {
-    await pending;
-    return;
+  if (!options?.force && divergentDeriveAddresses.has(walletAddress)) {
+    return false;
+  }
+  if (!options?.force) {
+    const pending = pendingKeyRequests.get(walletAddress);
+    if (pending) {
+      return pending;
+    }
   }
   const startEpoch = sessionEpoch;
   const promise = (async () => {
@@ -15375,20 +15412,143 @@ async function requestEncryptionKey(walletAddress, signMessage, embeddedWalletSi
       deriveKeyFromSignatureV3(signature)
     ]);
     if (sessionEpoch !== startEpoch) {
-      return;
+      return false;
     }
-    setStoredKey(walletAddress, { legacy: legacyKey, current: currentKey });
+    const existing = encryptionKeyStore.get(walletAddress);
+    if (!options?.force && existing && (existing.legacy || existing.current)) {
+      const matchesCurrent = Boolean(existing.current && existing.current === currentKey);
+      const matchesLegacy = Boolean(existing.legacy && existing.legacy === legacyKey);
+      if (!matchesCurrent && !matchesLegacy) {
+        getLogger().warn(
+          "requestEncryptionKey: derived keys do not match existing store; leaving unchanged"
+        );
+        divergentDeriveAddresses.add(walletAddress);
+        return false;
+      }
+      setStoredKey(walletAddress, {
+        legacy: existing.legacy ?? legacyKey,
+        current: existing.current ?? currentKey
+      });
+    } else {
+      setStoredKey(walletAddress, { legacy: legacyKey, current: currentKey });
+    }
+    cryptoKeyCache.delete(`${walletAddress}:v2`);
+    cryptoKeyCache.delete(`${walletAddress}:v3`);
+    refreshCandidatesByAddress.delete(walletAddress);
+    divergentDeriveAddresses.delete(walletAddress);
     notifyKeyAvailable(walletAddress);
+    return true;
   })();
   pendingKeyRequests.set(walletAddress, promise);
   try {
-    await promise;
+    return await promise;
   } finally {
     if (pendingKeyRequests.get(walletAddress) === promise) {
       pendingKeyRequests.delete(walletAddress);
     }
   }
 }
+async function refreshEncryptionKeyIfMatches(walletAddress, probeCiphertext, signMessage, embeddedWalletSigner) {
+  if (!isValidWalletAddress(walletAddress)) {
+    throw new Error(
+      `Invalid wallet address: ${walletAddress}. Address must start with 0x and be 42 characters (0x + 40 hex characters).`
+    );
+  }
+  const parsed = parsePrefixedCiphertext(probeCiphertext);
+  if (!parsed) {
+    return false;
+  }
+  const cached = refreshCandidatesByAddress.get(walletAddress);
+  if (cached) {
+    return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, cached);
+  }
+  let derivePromise = pendingCandidateDerives.get(walletAddress);
+  if (!derivePromise) {
+    derivePromise = (async () => {
+      const candidates2 = await deriveRefreshCandidates(signMessage, embeddedWalletSigner);
+      if (candidates2) {
+        refreshCandidatesByAddress.set(walletAddress, candidates2);
+      }
+      return candidates2;
+    })().finally(() => {
+      if (pendingCandidateDerives.get(walletAddress) === derivePromise) {
+        pendingCandidateDerives.delete(walletAddress);
+      }
+    });
+    pendingCandidateDerives.set(walletAddress, derivePromise);
+  }
+  const candidates = await derivePromise;
+  if (!candidates) {
+    return false;
+  }
+  return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates);
+}
+function parsePrefixedCiphertext(probeCiphertext) {
+  const version = probeCiphertext.startsWith("enc:v3:") ? "v3" : probeCiphertext.startsWith("enc:v2:") ? "v2" : null;
+  if (!version) return null;
+  const encryptedData = probeCiphertext.slice(
+    version === "v3" ? "enc:v3:".length : "enc:v2:".length
+  );
+  if (encryptedData.length < 56 || !/^[0-9a-f]+$/i.test(encryptedData)) {
+    return null;
+  }
+  return { version, encryptedData };
+}
+async function deriveRefreshCandidates(signMessage, embeddedWalletSigner) {
+  const startEpoch = sessionEpoch;
+  const signOptions = { showWalletUIs: false };
+  let signature;
+  try {
+    if (embeddedWalletSigner) {
+      signature = await embeddedWalletSigner(SIGN_MESSAGE, signOptions);
+    } else {
+      signature = await signMessage(SIGN_MESSAGE, signOptions);
+    }
+  } catch (error) {
+    if (embeddedWalletSigner && error instanceof Error) {
+      getLogger().warn(
+        "Embedded wallet signing failed during key refresh, falling back to standard signMessage:",
+        error.message
+      );
+      signature = await signMessage(SIGN_MESSAGE, signOptions);
+    } else {
+      throw error;
+    }
+  }
+  const [legacyKey, currentKey] = await Promise.all([
+    deriveKeyFromSignature(signature),
+    deriveKeyFromSignatureV3(signature)
+  ]);
+  if (sessionEpoch !== startEpoch) {
+    return null;
+  }
+  return { legacy: legacyKey, current: currentKey };
+}
+async function tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates) {
+  const candidateHex = parsed.version === "v2" ? candidates.legacy : candidates.current;
+  const keyBytes = hexToBytes(candidateHex);
+  const candidateCryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyBytes.buffer,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"]
+  );
+  try {
+    await decryptDataWithKey(parsed.encryptedData, candidateCryptoKey);
+  } catch {
+    getLogger().warn(
+      "refreshEncryptionKeyIfMatches: candidate keys failed to decrypt probe; leaving store unchanged"
+    );
+    return false;
+  }
+  setStoredKey(walletAddress, { legacy: candidates.legacy, current: candidates.current });
+  cryptoKeyCache.delete(`${walletAddress}:v2`);
+  cryptoKeyCache.delete(`${walletAddress}:v3`);
+  divergentDeriveAddresses.delete(walletAddress);
+  notifyKeyAvailable(walletAddress);
+  return true;
+}
 async function persistKeyPair(address, startEpoch) {
   if (typeof window === "undefined") {
     return;
@@ -15613,15 +15773,28 @@ function clearAllKeyPairs() {
     }
   }
 }
-var SIGN_MESSAGE, encryptionKeyStore, pendingKeyRequests, sessionEpoch, cryptoKeyCache, keyAvailableCallbacks, clearAllEncryptionStateCallbacks, keyPairStore, SHARED_TEXT_ENCODER, SHARED_TEXT_DECODER, KEYPAIR_STORAGE_PREFIX;
+var SIGN_MESSAGE, EncryptionKeyMissingError, encryptionKeyStore, pendingKeyRequests, pendingCandidateDerives, refreshCandidatesByAddress, divergentDeriveAddresses, sessionEpoch, cryptoKeyCache, keyAvailableCallbacks, clearAllEncryptionStateCallbacks, keyPairStore, SHARED_TEXT_ENCODER, SHARED_TEXT_DECODER, AES_256_KEY_HEX, KEYPAIR_STORAGE_PREFIX;
 var init_useEncryption = __esm({
   "src/react/useEncryption.ts"() {
     "use strict";
     "use client";
     init_logger();
     SIGN_MESSAGE = "The app is asking you to sign this message to generate a key, which will be used to encrypt data.";
+    EncryptionKeyMissingError = class extends Error {
+      constructor(address, version) {
+        super(
+          `Encryption key (${version}) not found for ${address}. Please sign a message to generate your encryption key.`
+        );
+        this.name = "EncryptionKeyMissingError";
+        this.address = address;
+        this.version = version;
+      }
+    };
     encryptionKeyStore = /* @__PURE__ */ new Map();
     pendingKeyRequests = /* @__PURE__ */ new Map();
+    pendingCandidateDerives = /* @__PURE__ */ new Map();
+    refreshCandidatesByAddress = /* @__PURE__ */ new Map();
+    divergentDeriveAddresses = /* @__PURE__ */ new Set();
     sessionEpoch = 0;
     cryptoKeyCache = /* @__PURE__ */ new Map();
     keyAvailableCallbacks = /* @__PURE__ */ new Map();
@@ -15629,6 +15802,7 @@ var init_useEncryption = __esm({
     keyPairStore = /* @__PURE__ */ new Map();
     SHARED_TEXT_ENCODER = new TextEncoder();
     SHARED_TEXT_DECODER = new TextDecoder();
+    AES_256_KEY_HEX = /^[0-9a-fA-F]{64}$/;
     KEYPAIR_STORAGE_PREFIX = "ecdh_keypair_";
   }
 });
@@ -15661,20 +15835,29 @@ async function encryptField(value, address, signMessage, embeddedWalletSigner, s
   const encrypted = await encryptData(value, address);
   return `${ENCRYPTION_PREFIX}${encrypted}`;
 }
-async function decryptField(value, address) {
-  if (!value) return value;
+async function decryptFieldDetailed(value, address) {
+  if (!value) return { status: "plaintext", value };
   const detected = detectEncryptionVersion(value);
-  if (!detected) return value;
+  if (!detected) return { status: "plaintext", value };
   if (detected.encryptedData.length < 56 || !/^[0-9a-f]+$/i.test(detected.encryptedData)) {
-    return value;
+    return { status: "invalid_payload", value, version: detected.version };
   }
   try {
-    return await decryptData(detected.encryptedData, address, detected.version);
+    const plaintext = await decryptData(detected.encryptedData, address, detected.version);
+    return { status: "ok", value: plaintext, version: detected.version };
   } catch (error) {
-    getLogger().warn("Failed to decrypt field, returning as-is:", error);
-    return value;
+    if (error instanceof EncryptionKeyMissingError) {
+      getLogger().warn("Failed to decrypt field (key missing for version):", error.message);
+      return { status: "key_missing", value, version: detected.version };
+    }
+    getLogger().warn("Failed to decrypt field (auth mismatch or crypto error):", error);
+    return { status: "auth_mismatch", value, version: detected.version };
   }
 }
+async function decryptField(value, address) {
+  const result = await decryptFieldDetailed(value, address);
+  return result.value;
+}
 async function encryptJsonField(value, address, signMessage, embeddedWalletSigner, skipKeyRequest) {
   if (!value) return void 0;
   const jsonString = JSON.stringify(value);
@@ -15811,20 +15994,40 @@ async function encryptMessageFields(message, address, signMessage, embeddedWalle
     throw error;
   }
 }
-async function decryptMaybeJsonField(value, address) {
-  if (value === void 0) return void 0;
-  if (value === null) return value;
+async function decryptMaybeJsonFieldDetailed(value, address) {
+  if (value === void 0) return { value: void 0, status: "plaintext" };
+  if (value === null) return { value, status: "plaintext" };
   if (typeof value === "string") {
     if (isEncrypted(value)) {
-      return await decryptJsonField(value, address);
+      const detailed = await decryptFieldDetailed(value, address);
+      if (detailed.status !== "ok") {
+        return { value: void 0, status: detailed.status, probe: value };
+      }
+      try {
+        return { value: JSON.parse(detailed.value), status: "ok" };
+      } catch (error) {
+        getLogger().warn("Failed to parse decrypted JSON field:", error);
+        return { value: void 0, status: "invalid_payload", probe: value };
+      }
     }
     try {
-      return JSON.parse(value);
+      return { value: JSON.parse(value), status: "plaintext" };
     } catch {
-      return void 0;
+      return { value: void 0, status: "plaintext" };
     }
   }
-  return value;
+  return { value, status: "plaintext" };
+}
+function worseDecryptStatus(a, b) {
+  if (b === "ok" || b === "plaintext") return a;
+  if (!a || a === "ok" || a === "plaintext") return b;
+  const rank = (s) => {
+    if (s === "auth_mismatch") return 3;
+    if (s === "key_missing") return 2;
+    if (s === "invalid_payload") return 1;
+    return 0;
+  };
+  return rank(b) >= rank(a) ? b : a;
 }
 async function decryptMessageFields(message, address, signMessage, embeddedWalletSigner) {
   if (!address) {
@@ -15837,33 +16040,82 @@ async function decryptMessageFields(message, address, signMessage, embeddedWalle
       getLogger().warn("Failed to request encryption key for decryption:", error);
     }
   }
-  const decryptedContent = await decryptField(message.content, address);
-  const decryptedThinking = message.thinking ? await decryptField(message.thinking, address) : message.thinking;
-  const decryptedVector = await decryptMaybeJsonField(
+  let assembled = await assembleDecryptedMessage(message, address);
+  const needsRefresh = assembled.decryptionStatus === "auth_mismatch" || assembled.decryptionStatus === "key_missing";
+  if (needsRefresh && signMessage && assembled.refreshProbe) {
+    try {
+      const refreshed = await refreshEncryptionKeyIfMatches(
+        address,
+        assembled.refreshProbe,
+        signMessage,
+        embeddedWalletSigner
+      );
+      if (refreshed) {
+        assembled = await assembleDecryptedMessage(message, address);
+      }
+    } catch (error) {
+      getLogger().warn("Failed to refresh encryption key after decrypt failure:", error);
+    }
+  }
+  const { refreshProbe: _probe, ...result } = assembled;
+  return result;
+}
+async function assembleDecryptedMessage(message, address) {
+  const contentResult = await decryptFieldDetailed(message.content, address);
+  const thinkingResult = message.thinking ? await decryptFieldDetailed(message.thinking, address) : null;
+  const vectorResult = await decryptMaybeJsonFieldDetailed(
     message.vector,
     address
   );
-  const decryptedChunks = await decryptMaybeJsonField(
+  const chunksResult = await decryptMaybeJsonFieldDetailed(
     message.chunks,
     address
   );
-  const decryptedSources = await decryptMaybeJsonField(
+  const sourcesResult = await decryptMaybeJsonFieldDetailed(
     message.sources,
     address
   );
-  const decryptedThoughtProcess = await decryptMaybeJsonField(
+  const thoughtProcessResult = await decryptMaybeJsonFieldDetailed(
     message.thoughtProcess,
     address
   );
-  return {
+  let decryptionStatus;
+  let refreshProbe;
+  const consider = (status, probe) => {
+    decryptionStatus = worseDecryptStatus(decryptionStatus, status);
+    if (!refreshProbe && probe && (status === "auth_mismatch" || status === "key_missing")) {
+      refreshProbe = probe;
+    }
+  };
+  consider(contentResult.status, isEncrypted(message.content) ? message.content : void 0);
+  if (thinkingResult && message.thinking && typeof message.thinking === "string") {
+    consider(thinkingResult.status, isEncrypted(message.thinking) ? message.thinking : void 0);
+  }
+  if (vectorResult.probe) consider(vectorResult.status, vectorResult.probe);
+  if (chunksResult.probe) consider(chunksResult.status, chunksResult.probe);
+  if (sourcesResult.probe) consider(sourcesResult.status, sourcesResult.probe);
+  if (thoughtProcessResult.probe) {
+    consider(thoughtProcessResult.status, thoughtProcessResult.probe);
+  }
+  const statusForConsumer = decryptionStatus === "ok" || decryptionStatus === "plaintext" || !decryptionStatus ? void 0 : decryptionStatus;
+  const result = {
     ...message,
-    content: decryptedContent,
-    thinking: decryptedThinking,
-    vector: decryptedVector,
-    chunks: decryptedChunks,
-    sources: decryptedSources,
-    thoughtProcess: decryptedThoughtProcess
+    content: contentResult.value,
+    thinking: thinkingResult ? thinkingResult.value : message.thinking,
+    vector: vectorResult.value,
+    chunks: chunksResult.value,
+    sources: sourcesResult.value,
+    thoughtProcess: thoughtProcessResult.value
   };
+  if (statusForConsumer) {
+    result.decryptionStatus = statusForConsumer;
+  } else {
+    delete result.decryptionStatus;
+  }
+  if (refreshProbe) {
+    result.refreshProbe = refreshProbe;
+  }
+  return result;
 }
 var init_encryption = __esm({
   "src/lib/db/chat/encryption.ts"() {
@@ -20360,11 +20612,11 @@ async function decomposeQuery(query, options) {
       userMessage: `Classify the following memory query and decompose if composite. Respond with JSON only \u2014 do not answer the question, do not ask for clarification.
 
 Query: ${trimmed}`,
-      // Decompose runs on the recall hot path — tighter than the
+      // Decompose runs ahead of recall in the tool layer — tighter than the
       // portalLlm default (consolidate/extract can wait longer).
       timeoutMs: 2e4,
       // No internal retry: a failure degrades to the safe `{specific,[query]}`
-      // fallback below, so retrying would only add latency on the hot path.
+      // fallback below. The agent/tool loop is the retry surface (719/B4).
       maxAttempts: 1,
       tag: "memory/decompose",
       ...options.fetchFn && { fetchFn: options.fetchFn }
@@ -20376,12 +20628,28 @@ Query: ${trimmed}`,
   if (parsed === null) return fallback;
   return validate(parsed, trimmed) ?? fallback;
 }
+function normalizeSubQueries(raw) {
+  if (!raw || raw.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const s of raw) {
+    if (typeof s !== "string") continue;
+    const t = s.trim();
+    if (t.length === 0) continue;
+    const key = t.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+    if (out.length >= MAX_SUB_QUERIES) break;
+  }
+  return out;
+}
 function validate(parsed, originalQuery) {
   if (typeof parsed !== "object" || parsed === null) return null;
   const obj = parsed;
   const mode = obj.mode === "composite" ? "composite" : "specific";
   if (!Array.isArray(obj.subQueries)) return null;
-  const subQueries = obj.subQueries.filter((s) => typeof s === "string").map((s) => s.trim()).filter((s) => s.length > 0).slice(0, MAX_SUB_QUERIES);
+  const subQueries = normalizeSubQueries(obj.subQueries);
   if (subQueries.length === 0) return null;
   if (mode === "specific") {
     return { mode: "specific", subQueries: [originalQuery] };
@@ -20960,12 +21228,12 @@ __export(recall_exports, {
 function flagsForBudget(budget) {
   switch (budget) {
     case "high":
-      return { rerank: true, decompose: true, traverse: true };
+      return { rerank: true, traverse: true };
     case "mid":
-      return { rerank: true, decompose: false, traverse: false };
+      return { rerank: true, traverse: false };
     case "low":
     default:
-      return { rerank: false, decompose: false, traverse: false };
+      return { rerank: false, traverse: false };
   }
 }
 function dedupeBy(items, ...keys) {
@@ -20984,10 +21252,10 @@ function dedupeBy(items, ...keys) {
 async function recall(query, ctx, options = {}) {
   const types = options.types ?? ["fact"];
   const limit = options.limit ?? DEFAULT_LIMIT;
-  const requestedBudget = options.budget ?? DEFAULT_BUDGET;
-  const flags = flagsForBudget(requestedBudget);
-  const decomposeAvailable = flags.decompose && !!options.decomposeOptions;
-  const usedBudget = requestedBudget === "high" && !decomposeAvailable ? "mid" : requestedBudget;
+  const usedBudget = options.budget ?? DEFAULT_BUDGET;
+  const flags = flagsForBudget(usedBudget);
+  const normalizedFacets = normalizeSubQueries(options.subQueries);
+  const subQueries = normalizedFacets.length >= 2 ? normalizedFacets : void 0;
   const t0 = nowMs();
   let prepMs = 0;
   let factLaneMs = 0;
@@ -21008,7 +21276,9 @@ async function recall(query, ctx, options = {}) {
     if (flags.rerank && factResults.length > 0 && hadV2Head && !didRerank) {
       degraded.push("rerank-unavailable");
     }
-    if (flags.decompose && !decomposeAvailable) degraded.push("decompose-unavailable");
+    if (usedBudget === "high" && options.decomposeOptions && !subQueries && !options.graphRefine) {
+      degraded.push("decompose-moved");
+    }
     if (embeddingsUnavailable) degraded.push("embeddings-unavailable");
     const diagnostics = {
       usedBudget,
@@ -21121,10 +21391,8 @@ async function recall(query, ctx, options = {}) {
         },
         ...options.rrfK !== void 0 && { rrfK: options.rrfK },
         ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
-        ...decomposeAvailable && {
-          decompose: "llm",
-          decomposeOptions: options.decomposeOptions
-        },
+        // 719/B4 — composite facets arrive pre-built; no LLM call here.
+        ...subQueries && { subQueries },
         ...options.scopes && { scopes: options.scopes },
         ...options.folderId !== void 0 && { folderId: options.folderId },
         ...options.factTypes?.length && { factTypes: options.factTypes },
@@ -21361,6 +21629,7 @@ var init_recall = __esm({
     init_logger();
     init_constants();
     init_embeddings();
+    init_decomposeQuery();
     init_searchTool();
     init_graphTraversal();
     init_observationTrend();
@@ -22306,52 +22575,51 @@ async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, se
     ...searchOptions?.rrfK !== void 0 && { rrfK: searchOptions.rrfK },
     ...searchOptions?.factTypeWeights && { factTypeWeights: searchOptions.factTypeWeights }
   };
-  if (useFusion && !embeddingsUnavailable && searchOptions?.decompose === "llm" && searchOptions.decomposeOptions) {
-    const decomp = await decomposeQuery(query, searchOptions.decomposeOptions);
-    if (decomp.mode === "composite") {
-      let subEmbeddings;
-      try {
-        subEmbeddings = await generateEmbeddings(decomp.subQueries, embeddingOptions);
-      } catch (err) {
-        getLogger().warn(
-          "memoryVault: sub-query embedding failed \u2014 falling back to single-query ranking: " + (err instanceof Error ? err.message : String(err))
-        );
-        subEmbeddings = [];
-      }
-      const subEmbeddingsUsable = decomp.subQueries.length > 0 && subEmbeddings.length === decomp.subQueries.length && subEmbeddings.every((v) => v.length > 0 && v.length === queryEmbedding.length);
-      if (subEmbeddings.length > 0 && !subEmbeddingsUsable) {
-        getLogger().warn(
-          `memoryVault: sub-query embedding returned ${subEmbeddings.length} vectors (dims ${subEmbeddings.map((v) => v.length).join(",")}) for ${decomp.subQueries.length} sub-queries against a ${queryEmbedding.length}-dim query \u2014 falling back to single-query ranking`
-        );
-      }
-      if (subEmbeddingsUsable) {
-        const subQueries = decomp.subQueries.map((sq, i) => ({
-          query: sq,
-          embedding: subEmbeddings[i]
-        }));
-        const v2HeadStats = { hadResults: false };
-        const composite = await rankComposite(query, queryEmbedding, subQueries, embeddedItems, {
-          limit,
-          minSimilarity,
-          rerank: !!searchOptions.rerank,
-          ...searchOptions.rerankTopN !== void 0 && {
-            rerankTopN: searchOptions.rerankTopN
-          },
-          ...searchOptions.ceWeight !== void 0 && { ceWeight: searchOptions.ceWeight },
-          ...searchOptions.mmr !== void 0 && { mmr: searchOptions.mmr },
-          ...tuning,
-          ...searchOptions.entityRanking && { entityRanking: searchOptions.entityRanking },
-          ...searchOptions.temporalRanking && { temporalRanking: searchOptions.temporalRanking },
-          rerankStats,
-          v2HeadStats
-        });
-        return stampTimestamps({
-          results: composite,
-          vaultSize,
-          reranked: rerankStats.applied,
-          hadV2Head: v2HeadStats.hadResults
-        });
-      }
+  const normalizedFacets = normalizeSubQueries(searchOptions?.subQueries);
+  const facetQueries = normalizedFacets.length >= 2 ? normalizedFacets : void 0;
+  if (useFusion && !embeddingsUnavailable && facetQueries) {
+    let subEmbeddings;
+    try {
+      subEmbeddings = await generateEmbeddings(facetQueries, embeddingOptions);
+    } catch (err) {
+      getLogger().warn(
+        "memoryVault: sub-query embedding failed \u2014 falling back to single-query ranking: " + (err instanceof Error ? err.message : String(err))
+      );
+      subEmbeddings = [];
+    }
+    const subEmbeddingsUsable = facetQueries.length > 0 && subEmbeddings.length === facetQueries.length && subEmbeddings.every((v) => v.length > 0 && v.length === queryEmbedding.length);
+    if (subEmbeddings.length > 0 && !subEmbeddingsUsable) {
+      getLogger().warn(
+        `memoryVault: sub-query embedding returned ${subEmbeddings.length} vectors (dims ${subEmbeddings.map((v) => v.length).join(",")}) for ${facetQueries.length} sub-queries against a ${queryEmbedding.length}-dim query \u2014 falling back to single-query ranking`
+      );
+    }
+    if (subEmbeddingsUsable) {
+      const subQueries = facetQueries.map((sq, i) => ({
+        query: sq,
+        embedding: subEmbeddings[i]
+      }));
+      const v2HeadStats = { hadResults: false };
+      const composite = await rankComposite(query, queryEmbedding, subQueries, embeddedItems, {
+        limit,
+        minSimilarity,
+        rerank: !!searchOptions?.rerank,
+        ...searchOptions?.rerankTopN !== void 0 && {
+          rerankTopN: searchOptions.rerankTopN
+        },
+        ...searchOptions?.ceWeight !== void 0 && { ceWeight: searchOptions.ceWeight },
+        ...searchOptions?.mmr !== void 0 && { mmr: searchOptions.mmr },
+        ...tuning,
+        ...searchOptions?.entityRanking && { entityRanking: searchOptions.entityRanking },
+        ...searchOptions?.temporalRanking && { temporalRanking: searchOptions.temporalRanking },
+        rerankStats,
+        v2HeadStats
+      });
+      return stampTimestamps({
+        results: composite,
+        vaultSize,
+        reranked: rerankStats.applied,
+        hadV2Head: v2HeadStats.hadResults
+      });
     }
   }
   if (useFusion && searchOptions?.rerank) {
@@ -22411,6 +22679,12 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       rankedOnCosine: false
     };
   }
+  if (searchOptions?.decompose === "llm" && normalizeSubQueries(searchOptions.subQueries).length < 2 && !warnedProgrammaticDecomposeIgnored) {
+    warnedProgrammaticDecomposeIgnored = true;
+    getLogger().warn(
+      'memoryVault: decompose:"llm" is ignored by searchVaultMemories \u2014 pass subQueries or use createMemoryVaultSearchTool / createRecallTool (719/B4)'
+    );
+  }
   const prepared = await prepareVaultCandidates(
     query,
     vaultCtx,
@@ -22515,7 +22789,8 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
         return "Error: A search query is required.";
       }
       try {
-        const budget = searchOptions?.decompose === "llm" && searchOptions.decomposeOptions ? "high" : searchOptions?.rerank ? "mid" : "low";
+        const wantsDecompose = searchOptions?.decompose === "llm" && !!searchOptions.decomposeOptions;
+        const budget = wantsDecompose ? "high" : searchOptions?.rerank ? "mid" : "low";
         const folderId = searchOptions?.folderId ?? argFolderId;
         if (searchOptions?.useFusion === false) {
           const { results: legacy, embeddingsUnavailable } = await searchVaultMemoriesWithSize(
@@ -22539,6 +22814,13 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             legacy.map((r) => ({ id: r.uniqueId, content: r.content, score: r.similarity }))
           );
         }
+        let subQueries;
+        if (wantsDecompose && searchOptions?.decomposeOptions) {
+          const decomp = await decomposeQuery(query, searchOptions.decomposeOptions);
+          if (decomp.mode === "composite" && decomp.subQueries.length >= 2) {
+            subQueries = decomp.subQueries;
+          }
+        }
         const { recall: recall2 } = await Promise.resolve().then(() => (init_recall(), recall_exports));
         let recallDegraded = [];
         const result = await recall2(
@@ -22555,9 +22837,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             ...tuningForward,
             ...folderId !== void 0 && { folderId },
             ...searchOptions?.scopes && { scopes: searchOptions.scopes },
-            ...searchOptions?.decompose === "llm" && searchOptions.decomposeOptions && {
-              decomposeOptions: searchOptions.decomposeOptions
-            }
+            ...subQueries && { subQueries }
           }
         );
         if (result.vaultSize === 0) {
@@ -22587,7 +22867,7 @@ ${formatted}`;
     }
   };
 }
-var SUPERSESSION_SIMILARITY_THRESHOLD, SUPERSESSION_MIN_AGE_GAP_MS, SUPERSESSION_BOOST_FACTOR, SUPERSESSION_MAX_WINDOW, EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL;
+var warnedProgrammaticDecomposeIgnored, SUPERSESSION_SIMILARITY_THRESHOLD, SUPERSESSION_MIN_AGE_GAP_MS, SUPERSESSION_BOOST_FACTOR, SUPERSESSION_MAX_WINDOW, EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL;
 var init_searchTool = __esm({
   "src/lib/memoryVault/searchTool.ts"() {
     "use strict";
@@ -22605,6 +22885,7 @@ var init_searchTool = __esm({
     init_bm25();
     init_decomposeQuery();
     init_lruCache();
+    warnedProgrammaticDecomposeIgnored = false;
     SUPERSESSION_SIMILARITY_THRESHOLD = 0.7;
     SUPERSESSION_MIN_AGE_GAP_MS = 30 * 24 * 60 * 60 * 1e3;
     SUPERSESSION_BOOST_FACTOR = 0.8;
@@ -23465,6 +23746,7 @@ __export(index_exports, {
   DEFAULT_VAULT_CACHE_SIZE: () => DEFAULT_VAULT_CACHE_SIZE,
   DatabaseManager: () => DatabaseManager,
   ENTITY_FANOUT: () => ENTITY_FANOUT,
+  EncryptionKeyMissingError: () => EncryptionKeyMissingError,
   ExcelProcessor: () => ExcelProcessor,
   HARD_DELETE_WINDOW_MS: () => HARD_DELETE_WINDOW_MS,
   INFERENCE_ID_HEADER: () => INFERENCE_ID_HEADER,
@@ -23665,6 +23947,7 @@ __export(index_exports, {
   rankProfileCandidates: () => rankProfileCandidates,
   recall: () => recall,
   reflect: () => reflect,
+  refreshEncryptionKeyIfMatches: () => refreshEncryptionKeyIfMatches,
   relinkMemoryTopicsOp: () => relinkMemoryTopicsOp,
   relinkMisclassifiedVideosOp: () => relinkMisclassifiedVideosOp,
   renderTemplate: () => renderTemplate,
@@ -23685,6 +23968,7 @@ __export(index_exports, {
   searchMediaOp: () => searchMediaOp,
   searchMessagesOp: () => searchMessagesOp,
   searchVaultMemories: () => searchVaultMemories,
+  seedEncryptionKeys: () => seedEncryptionKeys,
   selectServerToolsForPrompt: () => selectServerToolsForPrompt,
   serverPlatformStorage: () => serverPlatformStorage,
   setMemoryVisibilityOp: () => setMemoryVisibilityOp,
@@ -29478,6 +29762,7 @@ function rankProfileCandidates(inputs, now = Date.now(), options = {}) {
 init_recall();
 
 // src/lib/memory/recallTool.ts
+init_decomposeQuery();
 init_recall();
 init_recallConstants();
 var DEFAULT_LIMIT2 = 8;
@@ -29575,7 +29860,7 @@ function createRecallTool(ctx, toolOptions, callbacks) {
     type: "function",
     function: {
       name: RECALL_TOOL_NAME,
-      description: "Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an `id` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally.",
+      description: `Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an \`id\` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally. For multi-faceted / overview questions ("tell me about the user", "what's my tech stack"), prefer several targeted searches \u2014 one facet each (e.g. name, work, hobbies) \u2014 over a single broad query; fuse the results yourself.`,
       arguments: {
         type: "object",
         properties: {
@@ -29630,6 +29915,13 @@ function createRecallTool(ctx, toolOptions, callbacks) {
       let surfaced = 0;
       try {
         let recallDegraded = [];
+        let subQueries;
+        if (defaultBudget === "high" && toolOptions?.decomposeOptions) {
+          const decomp = await decomposeQuery(query, toolOptions.decomposeOptions);
+          if (decomp.mode === "composite" && decomp.subQueries.length >= 2) {
+            subQueries = decomp.subQueries;
+          }
+        }
         const recallOpts = {
           onDiagnostics: (d) => {
             recallDegraded = d.degraded;
@@ -29643,10 +29935,12 @@ function createRecallTool(ctx, toolOptions, callbacks) {
           ...toolOptions?.excludeConversationId && {
             excludeConversationId: toolOptions.excludeConversationId
           },
-          ...toolOptions?.decomposeOptions && {
-            decomposeOptions: toolOptions.decomposeOptions
-          },
-          ...toolOptions?.now !== void 0 && { now: toolOptions.now }
+          // Do NOT forward decomposeOptions into recall() — rewrite already
+          // ran above, and forwarding would falsely trip `decompose-moved`
+          // on every specific-mode high-budget call. graphRefine auth can
+          // be threaded later when the tool opts into that path.
+          ...toolOptions?.now !== void 0 && { now: toolOptions.now },
+          ...subQueries && { subQueries }
         };
         const result = await recall(query, ctx, recallOpts);
         if (callbacks?.onChunksRetrieved) {
@@ -36169,6 +36463,7 @@ function buildSystemPrompt(ctx, options) {
   DEFAULT_VAULT_CACHE_SIZE,
   DatabaseManager,
   ENTITY_FANOUT,
+  EncryptionKeyMissingError,
   ExcelProcessor,
   HARD_DELETE_WINDOW_MS,
   INFERENCE_ID_HEADER,
@@ -36369,6 +36664,7 @@ function buildSystemPrompt(ctx, options) {
   rankProfileCandidates,
   recall,
   reflect,
+  refreshEncryptionKeyIfMatches,
   relinkMemoryTopicsOp,
   relinkMisclassifiedVideosOp,
   renderTemplate,
@@ -36389,6 +36685,7 @@ function buildSystemPrompt(ctx, options) {
   searchMediaOp,
   searchMessagesOp,
   searchVaultMemories,
+  seedEncryptionKeys,
   selectServerToolsForPrompt,
   serverPlatformStorage,
   setMemoryVisibilityOp,