@anuma/sdk 9.1.3 → 9.1.5

package/dist/expo/index.mjs

@@ -923,15 +923,16 @@ async function refreshEncryptionKeyIfMatches(walletAddress, probeCiphertext, sig
   if (!parsed) {
     return false;
   }
+  const startEpoch = sessionEpoch;
   const cached = refreshCandidatesByAddress.get(walletAddress);
   if (cached) {
-    return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, cached);
+    return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, cached, startEpoch);
   }
   let derivePromise = pendingCandidateDerives.get(walletAddress);
   if (!derivePromise) {
     derivePromise = (async () => {
       const candidates2 = await deriveRefreshCandidates(signMessage, embeddedWalletSigner);
-      if (candidates2) {
+      if (candidates2 && sessionEpoch === startEpoch) {
         refreshCandidatesByAddress.set(walletAddress, candidates2);
       }
       return candidates2;
@@ -943,10 +944,10 @@ async function refreshEncryptionKeyIfMatches(walletAddress, probeCiphertext, sig
     pendingCandidateDerives.set(walletAddress, derivePromise);
   }
   const candidates = await derivePromise;
-  if (!candidates) {
+  if (!candidates || sessionEpoch !== startEpoch) {
     return false;
   }
-  return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates);
+  return tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates, startEpoch);
 }
 function parsePrefixedCiphertext(probeCiphertext) {
   const version = probeCiphertext.startsWith("enc:v3:") ? "v3" : probeCiphertext.startsWith("enc:v2:") ? "v2" : null;
@@ -989,7 +990,7 @@ async function deriveRefreshCandidates(signMessage, embeddedWalletSigner) {
   }
   return { legacy: legacyKey, current: currentKey };
 }
-async function tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates) {
+async function tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidates, startEpoch) {
   const candidateHex = parsed.version === "v2" ? candidates.legacy : candidates.current;
   const keyBytes = hexToBytes(candidateHex);
   const candidateCryptoKey = await crypto.subtle.importKey(
@@ -1007,6 +1008,9 @@ async function tryCommitCandidatesIfProbeMatches(walletAddress, parsed, candidat
     );
     return false;
   }
+  if (sessionEpoch !== startEpoch) {
+    return false;
+  }
   setStoredKey(walletAddress, { legacy: candidates.legacy, current: candidates.current });
   cryptoKeyCache.delete(`${walletAddress}:v2`);
   cryptoKeyCache.delete(`${walletAddress}:v3`);
@@ -15635,6 +15639,104 @@ function validate(parsed, originalQuery) {
   return { mode, subQueries };
 }
 
+// src/lib/memoryVault/vaultPreparation.ts
+function createVaultPreparation() {
+  return { corpora: /* @__PURE__ */ new WeakMap(), rows: /* @__PURE__ */ new WeakMap() };
+}
+var pendingRows = /* @__PURE__ */ new WeakMap();
+function loadVaultCorpus(ctx, options, preparation) {
+  if (!preparation) return getAllVaultMemoriesOp(ctx, options);
+  const corpusCache = preparation.corpora;
+  let pending = corpusCache.get(ctx);
+  if (!pending) {
+    pending = /* @__PURE__ */ new Map();
+    corpusCache.set(ctx, pending);
+  }
+  const key = JSON.stringify(options ?? {});
+  let request = pending.get(key);
+  if (!request) {
+    const entries = pending;
+    request = getAllVaultMemoriesOp(ctx, options).catch((error) => {
+      entries.delete(key);
+      throw error;
+    });
+    pending.set(key, request);
+  }
+  return request;
+}
+function rowRequestsFor(registry2, ctx, maskInput) {
+  let byMask = registry2.get(ctx);
+  if (!byMask) {
+    byMask = /* @__PURE__ */ new Map();
+    registry2.set(ctx, byMask);
+  }
+  let requests = byMask.get(maskInput);
+  if (!requests) {
+    requests = /* @__PURE__ */ new Map();
+    byMask.set(maskInput, requests);
+  }
+  return requests;
+}
+function embedVaultRows(ctx, options, rows, preparation) {
+  const pending = rowRequestsFor(pendingRows, ctx, options.maskInput);
+  const prepared = preparation && rowRequestsFor(preparation.rows, ctx, options.maskInput);
+  const model = options.model ?? DEFAULT_API_EMBEDDING_MODEL;
+  const keys = rows.map(
+    (row) => JSON.stringify([
+      row.uniqueId,
+      row.updatedAt?.getTime(),
+      row.content,
+      model,
+      options.baseUrl,
+      options.timeoutMs,
+      options.tokenTimeoutMs,
+      options.totalTimeoutMs
+    ])
+  );
+  const missing = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    if (!pending.has(keys[index]) && !prepared?.has(keys[index])) missing.set(keys[index], row);
+  });
+  if (missing.size > 0) {
+    const entries = pending;
+    const batch = Promise.resolve().then(
+      () => generateEmbeddings(
+        [...missing.values()].map((row) => row.content),
+        options
+      )
+    );
+    [...missing].forEach(([key, row], index) => {
+      const request = batch.then((vectors) => {
+        const vector = vectors[index];
+        updateVaultMemoryEmbeddingOp(ctx, row.uniqueId, JSON.stringify(vector), model, {
+          content: row.content,
+          updatedAt: row.updatedAt?.getTime()
+        }).catch(() => {
+        });
+        return vector;
+      }).finally(() => {
+        entries.delete(key);
+        if (entries.size === 0) pendingRows.get(ctx)?.delete(options.maskInput);
+      });
+      pending.set(key, request);
+    });
+  }
+  return Promise.all(
+    keys.map((key) => {
+      const cached = prepared?.get(key);
+      if (cached) return cached;
+      const request = pending.get(key);
+      if (!prepared) return request;
+      const retained = request.catch((error) => {
+        prepared.delete(key);
+        throw error;
+      });
+      prepared.set(key, retained);
+      return retained;
+    })
+  );
+}
+
 // src/lib/memoryVault/vectorVersion.ts
 var vectorRowVersion = /* @__PURE__ */ new WeakMap();
 function contentFingerprint(content) {
@@ -16197,11 +16299,11 @@ async function rankComposite(originalQuery, originalQueryEmbedding, subQueries,
   return combined.slice(0, limit);
 }
 async function preEmbedVaultMemories(vaultCtx, embeddingOptions, cache, options) {
-  const memories = await getAllVaultMemoriesOp(vaultCtx, options);
+  const memories = await loadVaultCorpus(vaultCtx, options);
   const currentModel = embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   const uncachedTexts = [];
   const uncachedKeys = [];
-  const uncachedIds = [];
+  const uncachedRows = [];
   const uncachedVersions = [];
   for (const m of memories) {
     const content = m.content;
@@ -16220,12 +16322,12 @@ async function preEmbedVaultMemories(vaultCtx, embeddingOptions, cache, options)
       }
       uncachedTexts.push(m.content);
       uncachedKeys.push(m.uniqueId);
-      uncachedIds.push(m.uniqueId);
+      uncachedRows.push(m);
       uncachedVersions.push(m.updatedAt);
     }
   }
   if (uncachedTexts.length > 0) {
-    const embeddings = await generateEmbeddings(uncachedTexts, embeddingOptions);
+    const embeddings = await embedVaultRows(vaultCtx, embeddingOptions, uncachedRows);
     for (let i = 0; i < uncachedKeys.length; i++) {
       cacheRowVector(
         cache,
@@ -16234,13 +16336,6 @@ async function preEmbedVaultMemories(vaultCtx, embeddingOptions, cache, options)
         uncachedVersions[i],
         uncachedTexts[i]
       );
-      updateVaultMemoryEmbeddingOp(
-        vaultCtx,
-        uncachedIds[i],
-        JSON.stringify(embeddings[i]),
-        currentModel
-      ).catch(() => {
-      });
     }
   }
 }
@@ -16382,10 +16477,7 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
       let laneVecs;
       if (opts.embedStats) opts.embedStats.rowsEmbedded += laneRows.length;
       try {
-        laneVecs = await generateEmbeddings(
-          laneRows.map((m) => m.content),
-          embeddingOptions
-        );
+        laneVecs = await embedVaultRows(vaultCtx, embeddingOptions, laneRows);
       } catch (err) {
         laneEmbedFailed = true;
         getLogger().warn(
@@ -16399,13 +16491,6 @@ async function buildProjectedCorpus(query, vaultCtx, embeddingOptions, cache, qu
           cacheRowVector(cache, m.uniqueId, vec, m.updatedAt, m.content);
           resolvedThisCall.add(m.uniqueId);
           vectored.push({ uniqueId: m.uniqueId, embedding: vec, updatedAt: m.updatedAt });
-          updateVaultMemoryEmbeddingOp(
-            vaultCtx,
-            m.uniqueId,
-            JSON.stringify(vecs[i]),
-            currentModel
-          ).catch(() => {
-          });
         });
       }
     }
@@ -16597,9 +16682,10 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
       };
     }
   } else {
-    const loaded = await getAllVaultMemoriesOp(
+    const loaded = await loadVaultCorpus(
       vaultCtx,
-      Object.keys(queryOpts).length > 0 ? queryOpts : void 0
+      Object.keys(queryOpts).length > 0 ? queryOpts : void 0,
+      searchOptions?.vaultPreparation
     );
     vaultSize = loaded.length;
     rowsDecrypted = loaded.length;
@@ -16672,7 +16758,12 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
       let newEmbeddings;
       embedStats.rowsEmbedded += uncachedTexts.length;
       try {
-        newEmbeddings = await generateEmbeddings(uncachedTexts, embeddingOptions);
+        newEmbeddings = await embedVaultRows(
+          vaultCtx,
+          embeddingOptions,
+          uncachedIndices.map((index) => memories[index]),
+          searchOptions?.vaultPreparation
+        );
       } catch (err) {
         embeddingFailure = true;
         getLogger().warn(
@@ -16688,13 +16779,6 @@ async function prepareVaultCandidates(query, vaultCtx, embeddingOptions, cache,
             memories[uncachedIndices[j]].updatedAt,
             memories[uncachedIndices[j]].content
           );
-          updateVaultMemoryEmbeddingOp(
-            vaultCtx,
-            memories[uncachedIndices[j]].uniqueId,
-            JSON.stringify(newEmbeddings[j]),
-            currentModel
-          ).catch(() => {
-          });
         }
       }
     }
@@ -19235,6 +19319,7 @@ async function recall(query, ctx, options = {}) {
         },
         ...options.rrfK !== void 0 && { rrfK: options.rrfK },
         ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
+        ...options.vaultPreparation && { vaultPreparation: options.vaultPreparation },
         ...subQueries && { subQueries },
         ...options.scopes && { scopes: options.scopes },
         ...options.folderId !== void 0 && { folderId: options.folderId },
@@ -21252,6 +21337,8 @@ async function backfillTopics(ctx) {
   if (topicless.length > 0) await backfillMemoryTopicsOp(ctx, topicless);
 }
 async function migrateMemoriesToRemote(options) {
+  if (typeof options.withWriteBarrier !== "function" || typeof options.onActivated !== "function")
+    throw new Error("A write barrier and a remote store handoff are required");
   const { canonical, signal } = options;
   const rings = [canonical, ...options.fallbacks ?? []];
   const model = options.embeddingOptions?.model ?? DEFAULT_API_EMBEDDING_MODEL;
@@ -21279,93 +21366,98 @@ async function migrateMemoriesToRemote(options) {
   const placeholders = /* @__PURE__ */ new Set();
   const truncated = /* @__PURE__ */ new Set();
   let imported = 0;
-  for (let pass = 0; ; pass++) {
-    const rows = await getAllVaultMemoryRowsOp(options.vaultCtx);
-    for (const raw of rows) if (invalid2(raw)) skipped.set(String(raw.id), "invalid");
-    const candidates = rows.filter((raw) => !skipped.has(String(raw.id)));
-    const missing = await missingIds(request, candidates.map(revision), signal);
-    const pending = /* @__PURE__ */ new Map();
-    for (const raw of candidates)
-      if (missing.has(raw.id)) pending.set(raw.id, raw.updated_at);
-    if (pending.size === 0 && !active) {
-      const remote = await remoteMetadata(
-        request,
-        candidates.map((raw) => raw.id),
-        signal
-      );
-      const needsVector = (raw, server) => !!options.embeddingOptions && !embedding(raw, model) && server.embedding_model !== model;
-      for (const raw of candidates) {
-        const server = remote.get(raw.id);
-        if (server && server.updated_at === raw.updated_at && (!sameMetadata2(raw, server, model) || needsVector(raw, server)))
-          pending.set(raw.id, raw.updated_at + 1);
-      }
-    }
-    if (pending.size === 0) {
-      const result = (state) => ({
-        state,
-        total: rows.length,
-        imported,
-        skipped: [...skipped].map(([memoryId, reason]) => ({ memoryId, reason })),
-        reembedded: reembedded.size,
-        unembedded: unembedded.size,
-        placeholderTombstones: placeholders.size,
-        truncatedSourceChunkIds: truncated.size
-      });
-      if (skipped.size > 0 && !options.allowSkipped) return result("migrating");
-      if (!claimed) await importBatch(request, canonical.keyId, [], signal);
-      if (!active)
-        await request(
-          "/account",
-          { method: "PUT", body: JSON.stringify({ state: "active" }) },
+  const uploadPasses = async (finalizing = false) => {
+    for (let pass = 0; ; pass++) {
+      const rows = await getAllVaultMemoryRowsOp(options.vaultCtx);
+      for (const raw of rows) if (invalid2(raw)) skipped.set(String(raw.id), "invalid");
+      const candidates = rows.filter((raw) => !skipped.has(String(raw.id)));
+      const missing = await missingIds(request, candidates.map(revision), signal);
+      const pending = /* @__PURE__ */ new Map();
+      for (const raw of candidates)
+        if (missing.has(raw.id)) pending.set(raw.id, raw.updated_at);
+      if (pending.size === 0 && !active) {
+        const remote = await remoteMetadata(
+          request,
+          candidates.map((raw) => raw.id),
           signal
         );
-      return result("active");
-    }
-    if (pass >= MAX_UPLOAD_PASSES)
-      throw new RemoteMemoryError(
-        "Nearby still reports memories missing after importing them",
-        409,
-        "migration_incomplete"
-      );
-    const prepared = [];
-    for (const raw of candidates) {
-      const updatedAt = pending.get(raw.id);
-      if (updatedAt === void 0) continue;
-      try {
-        prepared.push(await prepareRow(raw, canonical, rings, model, updatedAt));
-      } catch (error) {
-        if (!(error instanceof MemoryKeyError)) throw error;
-        skipped.set(raw.id, "unreadable");
-      }
-    }
-    const usable = new Set(prepared.filter((p) => p.row.embedding).map((p) => p.row.memory_id));
-    if (options.embeddingOptions)
-      await embedMissing(prepared, options.embeddingOptions, model, signal);
-    const local = new Map(candidates.map((raw) => [raw.id, raw]));
-    const upload = [];
-    for (const { row, plaintext } of prepared) {
-      const id2 = row.memory_id;
-      if (!fitsNearby(row)) {
-        skipped.set(id2, "invalid");
-        continue;
+        const needsVector = (raw, server) => !!options.embeddingOptions && !embedding(raw, model) && server.embedding_model !== model;
+        for (const raw of candidates) {
+          const server = remote.get(raw.id);
+          if (server && server.updated_at === raw.updated_at && (!sameMetadata2(raw, server, model) || needsVector(raw, server)))
+            pending.set(raw.id, raw.updated_at + 1);
+        }
       }
-      upload.push(row);
-      const track = (set, on) => on ? set.add(id2) : set.delete(id2);
-      track(reembedded, !!row.embedding && !usable.has(id2));
-      track(unembedded, !row.embedding);
-      track(placeholders, plaintext === void 0);
-      track(truncated, row.source_chunk_ids !== text13(local.get(id2).source_chunk_ids));
-    }
-    let sent = 0;
-    options.onProgress?.({ imported: sent, toImport: upload.length });
-    for (const batch of chunks(upload, IMPORT_BATCH)) {
-      await importBatch(request, canonical.keyId, batch, signal);
-      claimed = true;
-      sent += batch.length;
+      if (pending.size === 0) {
+        const result = (state) => ({
+          state,
+          total: rows.length,
+          imported,
+          skipped: [...skipped].map(([memoryId, reason]) => ({ memoryId, reason })),
+          reembedded: reembedded.size,
+          unembedded: unembedded.size,
+          placeholderTombstones: placeholders.size,
+          truncatedSourceChunkIds: truncated.size
+        });
+        if (skipped.size > 0 && !options.allowSkipped) return result("migrating");
+        if (!finalizing) return options.withWriteBarrier(() => uploadPasses(true));
+        if (!claimed) await importBatch(request, canonical.keyId, [], signal);
+        if (!active)
+          await request(
+            "/account",
+            { method: "PUT", body: JSON.stringify({ state: "active" }) },
+            signal
+          );
+        await options.onActivated();
+        return result("active");
+      }
+      if (pass >= MAX_UPLOAD_PASSES)
+        throw new RemoteMemoryError(
+          "Nearby still reports memories missing after importing them",
+          409,
+          "migration_incomplete"
+        );
+      const prepared = [];
+      for (const raw of candidates) {
+        const updatedAt = pending.get(raw.id);
+        if (updatedAt === void 0) continue;
+        try {
+          prepared.push(await prepareRow(raw, canonical, rings, model, updatedAt));
+        } catch (error) {
+          if (!(error instanceof MemoryKeyError)) throw error;
+          skipped.set(raw.id, "unreadable");
+        }
+      }
+      const usable = new Set(prepared.filter((p) => p.row.embedding).map((p) => p.row.memory_id));
+      if (options.embeddingOptions)
+        await embedMissing(prepared, options.embeddingOptions, model, signal);
+      const local = new Map(candidates.map((raw) => [raw.id, raw]));
+      const upload = [];
+      for (const { row, plaintext } of prepared) {
+        const id2 = row.memory_id;
+        if (!fitsNearby(row)) {
+          skipped.set(id2, "invalid");
+          continue;
+        }
+        upload.push(row);
+        const track = (set, on) => on ? set.add(id2) : set.delete(id2);
+        track(reembedded, !!row.embedding && !usable.has(id2));
+        track(unembedded, !row.embedding);
+        track(placeholders, plaintext === void 0);
+        track(truncated, row.source_chunk_ids !== text13(local.get(id2).source_chunk_ids));
+      }
+      let sent = 0;
       options.onProgress?.({ imported: sent, toImport: upload.length });
+      for (const batch of chunks(upload, IMPORT_BATCH)) {
+        await importBatch(request, canonical.keyId, batch, signal);
+        claimed = true;
+        sent += batch.length;
+        options.onProgress?.({ imported: sent, toImport: upload.length });
+      }
+      imported += sent;
     }
-    imported += sent;
-  }
+  };
+  return uploadPasses();
 }
 
 // src/lib/memory/store/remoteStore.ts
@@ -22818,13 +22910,20 @@ async function synthesizeProfile(ctx, options = {}) {
       }
     }
   }
+  const vaultPreparation = createVaultPreparation();
   const settled = await Promise.allSettled(
     facets.map(async (facet) => {
       const prior = previous?.sections.find((s) => s.key === facet.key);
       if (prior && !staleKeys.has(facet.key)) {
         return prior;
       }
-      return synthesizeFacet(facet, recallCtx, options, fallbackPriors.get(facet.key));
+      return synthesizeFacet(
+        facet,
+        recallCtx,
+        options,
+        fallbackPriors.get(facet.key),
+        vaultPreparation
+      );
     })
   );
   const sections = settled.map((r, i) => {
@@ -22978,7 +23077,7 @@ async function attributeFacts(ctx, candidates, facets) {
   }
   return keys;
 }
-async function synthesizeFacet(facet, ctx, options, prior) {
+async function synthesizeFacet(facet, ctx, options, prior, vaultPreparation) {
   const scopes = options.scopes ?? DEFAULT_SCOPES;
   const limit = options.limit ?? DEFAULT_FACET_RECALL_LIMIT;
   const factTypeWeights = { ...DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, ...options.factTypeWeights };
@@ -22995,6 +23094,7 @@ async function synthesizeFacet(facet, ctx, options, prior) {
     };
   }
   const recalled = await recall(facet.query, ctx, {
+    vaultPreparation,
     scopes,
     limit: hasReviewGate ? RECALL_MAX_LIMIT : limit,
     types: ["fact"],

package/dist/memory/context.d.mts

@@ -183,6 +183,51 @@ interface EntityOperationsContext {
     canWrite?: () => Promise<boolean>;
 }
 
+/**
+ * Class-B task types — the vocabulary of the `X-Anuma-Task-Type` header.
+ *
+ * A Class-B flow has ONE fixed purpose and no conversation: extract memories
+ * from a snippet, pick a topic, consolidate duplicates, classify a query. Today
+ * each of those builds its own system prompt on the client and sends it as a
+ * `role:system` message, which makes the prompt a suggestion rather than a
+ * contract — a caller can reword it into "you are a general assistant" and get
+ * general chat at internal-endpoint prices.
+ *
+ * The fix is that the SERVER owns the text and the client only names the task.
+ * This header is the name. The portal allowlists it against its own copy of this
+ * enum (ai-portal `internal/systemprompt/tasks.go`) and DROPS anything it does
+ * not recognise, so an unknown value degrades to "no task declared" rather than
+ * failing the request.
+ *
+ * ⚠ These string values are a wire contract with ai-portal. Adding one here
+ * before the portal knows it is harmless (it is dropped); renaming or removing
+ * one silently stops that flow being counted. Keep them in step with
+ * `AllTaskTypes` on the portal side, and see ai-portal
+ * `docs/BACKEND_OWNED_TASK_PROMPTS.md` for the rollout.
+ *
+ * ⚠ RELEASE ORDER. This union is a PUBLIC type, so a split is breaking in both
+ * directions and has to be sequenced:
+ *
+ *   1. merge + publish this package;
+ *   2. bump `@anuma/sdk` in the consumer and switch its call sites to the new
+ *      names in the same commit.
+ *
+ * A consumer on the OLD version cannot compile the new names, and a consumer on
+ * the NEW version cannot compile the retired ones (`app_inspiration` is gone
+ * here, replaced by the three `app_inspiration_*` names). Both halves of that
+ * are type-only — the wire itself always degrades safely, because the portal
+ * drops any value it does not recognise. Concretely: ai-memoryless-client#5782
+ * is blocked on this publish for exactly that reason.
+ *
+ * Deliberately ABSENT: agent personas, `reflect()` when it answers the user, and
+ * the app-idea chat. Those carry an open conversation with the user, so a fixed
+ * server-owned prompt would be wrong rather than merely premature — the same
+ * boundary {@link INTERNAL_FLOW_MARKER} draws.
+ *
+ * @public
+ */
+type TaskType = "title" | "commit_message" | "memory_extract" | "memory_import_extract" | "memory_dedup" | "memory_decay" | "memory_injection_check" | "memory_verify_support" | "memory_autosort" | "memory_topic" | "memory_consolidate" | "memory_decompose" | "memory_profile_synth" | "memory_graph" | "memory_recall_embed" | "memory_retain_embed" | "folder_context" | "selection_memory" | "summarize" | "style_analysis" | "classify_search" | "app_inspiration_generate" | "app_inspiration_trends" | "app_inspiration_remix" | "spotlight_image" | "slide_image" | "slide_video" | "slide_music" | "slide_sfx" | "media_video" | "media_audio" | "media_bg_removal" | "media_image_preset" | "tool_app_builder" | "tool_document_builder" | "tool_slides" | "tool_slides_image_gen" | "connector_guidance" | "cf_task" | "xbot_intent" | "xbot_council" | "scheduled_task";
+
 /**
  * Auth for portal LLM calls (extraction, consolidation, decomposition,
  * reflection). Mirrors `memoryEngine`'s `EmbeddingOptions` dual-auth:
@@ -202,6 +247,76 @@ interface PortalLlmAuth {
     getToken?: () => Promise<string | null>;
 }
 
+/**
+ * Options for embedding generation
+ *
+ * Supports two auth methods:
+ * - `getToken`: For Privy identity tokens (uses Authorization: Bearer header)
+ * - `apiKey`: For direct API keys (uses X-API-Key header)
+ *
+ * At least one of `getToken` or `apiKey` must be provided.
+ */
+interface EmbeddingOptions {
+    taskType?: TaskType;
+    /** Function to get auth token (e.g., Privy's getIdentityToken). Uses Authorization: Bearer header. */
+    getToken?: () => Promise<string | null>;
+    /** Direct API key for server-side usage. Uses X-API-Key header. */
+    apiKey?: string;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Embedding model to use */
+    model?: string;
+    /** Max texts per API call for batch embeddings (default: 100). Larger arrays are split into chunks. */
+    batchSize?: number;
+    /**
+     * Optional in-memory cache for embedding vectors. When provided, texts
+     * are looked up in this map before calling the API, and new embeddings
+     * are stored after generation. Useful when the same texts are embedded
+     * repeatedly (e.g., across eval iterations or re-indexing runs).
+     *
+     * Values are stored as `Float32Array` (the embedding model's native
+     * precision) rather than a float64 `number[]`, halving the resident RAM of
+     * the cache with no precision loss. `generateEmbedding(s)` still return
+     * `number[]` at the API boundary, so callers are unaffected.
+     */
+    cache?: Map<string, Float32Array>;
+    /** Called after each embedding API call with the token usage from the response. */
+    onUsage?: (usage: {
+        promptTokens: number;
+        totalTokens: number;
+    }) => void;
+    /**
+     * Optional transform applied to each text immediately before it is sent to
+     * the embeddings endpoint (e.g. `PiiRedactor.maskText`). The cache and result
+     * ordering still key on the original text — only the API request body is
+     * transformed — so callers can keep storing/displaying the original value
+     * while real PII never reaches the server. Used when PII redaction is active.
+     */
+    maskInput?: (text: string) => string;
+    /**
+     * Deadline, in ms, for EACH embeddings HTTP attempt (default 15000). An
+     * attempt that exceeds it is aborted and counts as a transient failure, so the
+     * bounded retry still applies. `0` disables the deadline.
+     */
+    timeoutMs?: number;
+    /**
+     * Deadline, in ms, for the `getToken()` read that precedes a request (default
+     * 10000). A provider that never settles rejects instead of hanging the
+     * embedding — and the recall waiting on it. `0` disables the deadline.
+     */
+    tokenTimeoutMs?: number;
+    /**
+     * Overall deadline, in ms, for one `generateEmbedding` or `generateEmbeddings` call — the token read,
+     * every retry attempt and the backoff between them. Unset (the default) means
+     * only the per-attempt deadlines apply, which is right for background/bulk
+     * embeds. The recall query path sets it (see
+     * `RecallOptions.queryEmbedTotalTimeoutMs`) so an outage degrades a turn to
+     * BM25 within a few seconds instead of ~4 x `timeoutMs`. Batch calls share
+     * one budget across authentication, all chunks, retries and backoff.
+     */
+    totalTimeoutMs?: number;
+}
+
 interface RecencyOptions {
     /** Override "now" — useful for deterministic tests and back-dated benchmarks. */
     now?: Date;
@@ -213,6 +328,13 @@ interface RecencyOptions {
     noDateMultiplier?: number;
 }
 
+type VaultCorpusCache = WeakMap<VaultMemoryOperationsContext, Map<string, Promise<StoredVaultMemory[]>>>;
+type RowRequests = Map<EmbeddingOptions["maskInput"], Map<string, Promise<number[]>>>;
+interface VaultPreparation {
+    corpora: VaultCorpusCache;
+    rows: WeakMap<VaultMemoryOperationsContext, RowRequests>;
+}
+
 /**
  * How a fact's evidence has been evolving.
  *
@@ -300,6 +422,7 @@ interface RankedMemory {
     updatedAt: Date;
 }
 interface RecallOptions {
+    /** @internal */ vaultPreparation?: VaultPreparation;
     /** Embedding cache shared with the rest of the turn, so the query is embedded once across lanes and the send. */
     embeddingCache?: Map<string, Float32Array>;
     /** Which kinds to search. Default: ['fact']. */