@anuma/sdk 6.33.2 → 6.34.0

package/dist/server/index.cjs

@@ -19969,7 +19969,7 @@ async function embedOne(text12, options, outer) {
 }
 var DEFAULT_EMBEDDING_BATCH_SIZE = 100;
 var DEFAULT_EMBEDDING_BATCH_CONCURRENCY = 3;
-async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs) {
+async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs, outer) {
   const response = await withEmbeddingRetry(
     () => withDeadline(
       (signal) => postApiV1Embeddings({
@@ -19979,8 +19979,10 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
         ...signal && { signal }
       }),
       timeoutMs,
-      "embedding batch request"
-    )
+      "embedding batch request",
+      outer
+    ),
+    outer
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -19998,6 +20000,11 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
 }
 async function generateEmbeddings(texts, options) {
   if (texts.length === 0) return [];
+  const total = options.totalTimeoutMs;
+  if (total === void 0) return embedMany(texts, options, void 0);
+  return withDeadline((signal) => embedMany(texts, options, signal), total, "embedding batch");
+}
+async function embedMany(texts, options, outer) {
   const { baseUrl = BASE_URL, model, batchSize, cache } = options;
   const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   const chunkSize = batchSize ?? DEFAULT_EMBEDDING_BATCH_SIZE;
@@ -20018,7 +20025,8 @@ async function generateEmbeddings(texts, options) {
   if (uncachedTexts.length === 0) {
     return results;
   }
-  const headers = await resolveAuthHeaders(options);
+  const headers = await resolveAuthHeaders(options, outer);
+  if (outer?.aborted) throw outer.reason;
   const embeddingModel = model ?? DEFAULT_API_EMBEDDING_MODEL;
   let newEmbeddings;
   if (uncachedTexts.length <= chunkSize) {
@@ -20029,7 +20037,8 @@ async function generateEmbeddings(texts, options) {
       embeddingModel,
       options.onUsage,
       options.maskInput,
-      timeoutMs
+      timeoutMs,
+      outer
     );
   } else {
     const chunks = [];
@@ -20040,6 +20049,7 @@ async function generateEmbeddings(texts, options) {
     let nextIndex = 0;
     const worker = async () => {
       while (nextIndex < chunks.length) {
+        if (outer?.aborted) throw outer.reason;
         const idx = nextIndex++;
         allEmbeddings[idx] = await generateEmbeddingsBatch(
           chunks[idx],
@@ -20048,7 +20058,8 @@ async function generateEmbeddings(texts, options) {
           embeddingModel,
           options.onUsage,
           options.maskInput,
-          timeoutMs
+          timeoutMs,
+          outer
         );
       }
     };
@@ -20059,6 +20070,7 @@ async function generateEmbeddings(texts, options) {
     await Promise.all(workers);
     newEmbeddings = allEmbeddings.flat();
   }
+  if (outer?.aborted) throw outer.reason;
   for (let i = 0; i < uncachedIndices.length; i++) {
     const f32Embedding = Float32Array.from(newEmbeddings[i]);
     results[uncachedIndices[i]] = Array.from(f32Embedding);
@@ -31574,7 +31586,7 @@ async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, se
   if (useFusion && !embeddingsUnavailable && facetQueries) {
     let subEmbeddings;
     try {
-      subEmbeddings = await generateEmbeddings(facetQueries, embeddingOptions);
+      subEmbeddings = prepared.facetEmbeddings ?? 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))
@@ -31760,6 +31772,35 @@ var DEFAULT_SCOPE = "private";
 var DEFAULT_CONSOLIDATE_THRESHOLD = 0.55;
 var DEFAULT_CONSOLIDATE_TOP_K = 20;
 async function retain(content, ctx, options = {}) {
+  return retainWithPersistence(
+    content,
+    {
+      embeddingOptions: ctx.embeddingOptions,
+      vaultCache: ctx.vaultCache,
+      persistence: {
+        prepare: (query, searchOptions) => prepareVaultCandidates(
+          query,
+          ctx.vaultCtx,
+          ctx.embeddingOptions,
+          ctx.vaultCache,
+          searchOptions
+        ),
+        get: (id) => getVaultMemoryOp(ctx.vaultCtx, id),
+        tombstones: (_embedding, _model, scope, folderId) => getAllVaultMemoriesOp(ctx.vaultCtx, {
+          includeDeleted: true,
+          scopes: [scope],
+          ...folderId !== void 0 && { folderId }
+        }),
+        create: (input) => createVaultMemoryOp(ctx.vaultCtx, input),
+        update: (id, patch) => updateVaultMemoryOp(ctx.vaultCtx, id, patch),
+        supersede: (id, successor) => supersedeVaultMemoryOp(ctx.vaultCtx, id, successor),
+        createSuperseding: (input, target) => createSupersedingMemoryOp(ctx.vaultCtx, input, target)
+      }
+    },
+    options
+  );
+}
+async function retainWithPersistence(content, ctx, options = {}) {
   const trimmed = content.trim();
   if (trimmed.length === 0) {
     throw new Error("retain: content cannot be empty");
@@ -31772,19 +31813,13 @@ async function retain(content, ctx, options = {}) {
   let supersedeContent;
   let prepared;
   if (enableAutoMerge) {
-    prepared = await prepareVaultCandidates(
-      trimmed,
-      ctx.vaultCtx,
-      ctx.embeddingOptions,
-      ctx.vaultCache,
-      {
-        limit: Math.max(options.consolidateTopK ?? DEFAULT_CONSOLIDATE_TOP_K, 1),
-        useFusion: false,
-        scopes: [resolvedScope],
-        includeArchived: true,
-        ...options.folderId !== void 0 && { folderId: options.folderId }
-      }
-    );
+    prepared = await ctx.persistence.prepare(trimmed, {
+      limit: Math.max(options.consolidateTopK ?? DEFAULT_CONSOLIDATE_TOP_K, 1),
+      useFusion: false,
+      scopes: [resolvedScope],
+      includeArchived: true,
+      ...options.folderId !== void 0 && { folderId: options.folderId }
+    });
     if (prepared.embeddingFailure || prepared.embeddingsUnavailable) {
       throw new Error(
         "retain: embeddings unavailable \u2014 refusing to auto-merge against an inert cosine lane, which would create a duplicate instead of merging into the existing memory. Retry when embeddings recover, or pass enableAutoMerge: false to force a create."
@@ -31815,7 +31850,7 @@ async function retain(content, ctx, options = {}) {
       );
       if (matches.length > 0) {
         const targetId = matches[0].uniqueId;
-        const existing = await getVaultMemoryOp(ctx.vaultCtx, targetId);
+        const existing = await ctx.persistence.get(targetId);
         if (existing && !existing.supersededBy) {
           const mergedSourceIds = unionStrings(
             existing.sourceChunkIds ?? [],
@@ -31824,7 +31859,7 @@ async function retain(content, ctx, options = {}) {
           const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
           const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
           const resurrect = resurrectFields(existing);
-          const updated = await updateVaultMemoryOp(ctx.vaultCtx, targetId, {
+          const updated = await ctx.persistence.update(targetId, {
             content: existing.content,
             proofCountIncrement: 1,
             observationSourceIds: options.sourceChunkIds,
@@ -31851,7 +31886,8 @@ async function retain(content, ctx, options = {}) {
   }
   const contentToWrite = supersedeContent ?? trimmed;
   const reusableQueryEmbedding = supersedeContent === void 0 && prepared && prepared.queryEmbedding.length > 0 ? prepared.queryEmbedding : void 0;
-  const embedding = reusableQueryEmbedding ?? await generateEmbedding(contentToWrite, ctx.embeddingOptions);
+  const generatedEmbedding = reusableQueryEmbedding ?? await generateEmbedding(contentToWrite, ctx.embeddingOptions);
+  const embedding = ctx.normalizeEmbedding?.(generatedEmbedding) ?? generatedEmbedding;
   const embeddingModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   if (options.respectTombstones) {
     const tombstone = await findTombstoneMatch(embedding, embeddingModel, resolvedScope, ctx, {
@@ -31891,8 +31927,7 @@ async function retain(content, ctx, options = {}) {
   };
   if (supersedeTargetIds.length > 0) {
     const [primaryTargetId, ...restTargetIds] = supersedeTargetIds;
-    const { created: created2, retired } = await createSupersedingMemoryOp(
-      ctx.vaultCtx,
+    const { created: created2, retired } = await ctx.persistence.createSuperseding(
       createOpts,
       primaryTargetId
     );
@@ -31908,11 +31943,11 @@ async function retain(content, ctx, options = {}) {
       for (const staleId of restTargetIds) {
         let ok = false;
         try {
-          ok = await supersedeVaultMemoryOp(ctx.vaultCtx, staleId, created2.uniqueId) === true;
+          ok = await ctx.persistence.supersede(staleId, created2.uniqueId) === true;
         } catch {
         }
         if (ok) continue;
-        const stillLive = await getVaultMemoryOp(ctx.vaultCtx, staleId).catch(() => null);
+        const stillLive = await (ctx.persistence.getFresh ? ctx.persistence.getFresh(staleId) : ctx.persistence.get(staleId)).catch(() => null);
         if (stillLive && !stillLive.supersededBy) liveLeftovers.push(staleId);
       }
       if (liveLeftovers.length > 0) {
@@ -31939,7 +31974,7 @@ async function retain(content, ctx, options = {}) {
       `supersede: primary target ${primaryTargetId} retired or deleted inside the atomic write`
     );
   }
-  const created = await createVaultMemoryOp(ctx.vaultCtx, createOpts);
+  const created = await ctx.persistence.create(createOpts);
   cacheRowVector(
     ctx.vaultCache,
     created.uniqueId,
@@ -31958,11 +31993,7 @@ function unionStrings(a, b) {
   return [.../* @__PURE__ */ new Set([...a, ...b])];
 }
 async function findTombstoneMatch(embedding, embeddingModel, scope, ctx, opts) {
-  const rows = await getAllVaultMemoriesOp(ctx.vaultCtx, {
-    includeDeleted: true,
-    scopes: [scope],
-    ...opts.folderId !== void 0 && { folderId: opts.folderId }
-  });
+  const rows = await ctx.persistence.tombstones(embedding, embeddingModel, scope, opts.folderId);
   let bestId = null;
   let bestSim = opts.threshold;
   for (const row of rows) {
@@ -32029,7 +32060,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     if (requestedIds.length === 0) return null;
     const valid = [];
     for (const id of requestedIds) {
-      const existing = await getVaultMemoryOp(ctx.vaultCtx, id);
+      const existing = await ctx.persistence.get(id);
       if (existing && !existing.supersededBy) valid.push(id);
     }
     if (valid.length === 0) {
@@ -32041,7 +32072,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     return { supersede: valid, content: decision.content };
   }
   if (decision.action === "noop" && decision.targetId) {
-    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
+    const existing = await ctx.persistence.get(decision.targetId);
     if (!existing || existing.supersededBy) {
       return abandonToRace(
         options,
@@ -32055,7 +32086,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
     const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
     const resurrect = resurrectFields(existing);
-    const updated = await updateVaultMemoryOp(ctx.vaultCtx, decision.targetId, {
+    const updated = await ctx.persistence.update(decision.targetId, {
       content: existing.content,
       proofCountIncrement: 1,
       observationSourceIds: options.sourceChunkIds,
@@ -32083,7 +32114,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     };
   }
   if (decision.action === "update" && decision.targetId && decision.content) {
-    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
+    const existing = await ctx.persistence.get(decision.targetId);
     if (!existing || existing.supersededBy) {
       return abandonToRace(
         options,
@@ -32094,12 +32125,13 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
       existing.sourceChunkIds ?? [],
       options.sourceChunkIds ?? []
     );
-    const newEmbedding = await generateEmbedding(decision.content, ctx.embeddingOptions);
+    const generatedEmbedding = await generateEmbedding(decision.content, ctx.embeddingOptions);
+    const newEmbedding = ctx.normalizeEmbedding?.(generatedEmbedding) ?? generatedEmbedding;
     const consolidatedModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
     const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
     const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
     const resurrect = resurrectFields(existing);
-    const updated = await updateVaultMemoryOp(ctx.vaultCtx, decision.targetId, {
+    const updated = await ctx.persistence.update(decision.targetId, {
       content: decision.content,
       proofCountIncrement: 1,
       observationSourceIds: options.sourceChunkIds,
@@ -32143,7 +32175,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
   return null;
 }
 async function assertMergeTargetGoneOrThrow(ctx, targetId) {
-  const stillExists = await getVaultMemoryOp(ctx.vaultCtx, targetId);
+  const stillExists = await (ctx.persistence.getFresh ? ctx.persistence.getFresh(targetId) : ctx.persistence.get(targetId));
   if (stillExists) {
     throw new Error(`retain: merge into memory ${targetId} failed to persist`);
   }
@@ -33642,7 +33674,7 @@ async function recall(query, ctx, options = {}) {
     if (graphLaneFailed) degraded.push("graph-lane-failed");
     if (temporalLaneFailed) degraded.push("temporal-lane-failed");
     if (chunksScopeRestricted) degraded.push("chunks-scope-restricted");
-    const laneRan = types.includes("fact") && !!ctx.vaultCtx && !!ctx.vaultCache || types.includes("chunk") && !!ctx.storageCtx || chunksScopeRestricted && !!ctx.storageCtx;
+    const laneRan = types.includes("fact") && (!!ctx.factSource || !!ctx.vaultCtx && !!ctx.vaultCache) || types.includes("chunk") && !!ctx.storageCtx || chunksScopeRestricted && !!ctx.storageCtx;
     const scores = admitted.map((m) => m.score);
     const minScoreApplied = factResults.length > 0 ? factFloor : chunkResults.length > 0 ? chunkFloor : factFloor >= 0 ? factFloor : chunkFloor;
     const diagnostics = {
@@ -33684,7 +33716,7 @@ async function recall(query, ctx, options = {}) {
     return { memories: [], usedBudget, reranked: false, candidateCount: 0 };
   }
   const needsChunkEmbedding = types.includes("chunk") && ctx.storageCtx;
-  const wantsTemporal = types.includes("fact") && ctx.vaultCtx;
+  const wantsTemporal = types.includes("fact") && (ctx.factSource || ctx.vaultCtx);
   const graphRefiner = flags.traverse && options.graphRefine && options.decomposeOptions ? createLlmNeighborRefiner(options.decomposeOptions) : void 0;
   const queryEmbedTotalTimeoutMs = options.queryEmbedTotalTimeoutMs ?? DEFAULT_QUERY_EMBED_TOTAL_TIMEOUT_MS;
   const prepStart = nowMs2();
@@ -33714,7 +33746,7 @@ async function recall(query, ctx, options = {}) {
     safeLane(
       "graph",
       () => graphLaneFailed = true,
-      () => buildGraphLaneRanking(query, ctx, flags.traverse, {
+      () => ctx.factSource ? ctx.factSource.graphRanking(query, flags.traverse, options) : buildGraphLaneRanking(query, ctx, flags.traverse, {
         ...options.maxHops !== void 0 && { maxHops: options.maxHops },
         ...options.entityFanout !== void 0 && { entityFanout: options.entityFanout },
         ...options.nodeBudget !== void 0 && { nodeBudget: options.nodeBudget },
@@ -33725,13 +33757,13 @@ async function recall(query, ctx, options = {}) {
     wantsTemporal ? safeLane(
       "temporal",
       () => temporalLaneFailed = true,
-      () => buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)
+      () => ctx.factSource ? ctx.factSource.temporalRanking(query, options.now) : buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)
     ) : Promise.resolve([])
   ]);
   prepMs = nowMs2() - prepStart;
   graphLaneCount = entityRanking.length;
   temporalLaneCount = temporalRanking.length;
-  if (types.includes("fact") && ctx.vaultCtx && ctx.vaultCache) {
+  if (types.includes("fact") && (ctx.factSource || ctx.vaultCtx && ctx.vaultCache)) {
     const factStart = nowMs2();
     const vaultMinScore = options.minScore ?? DEFAULT_FACT_MIN_SCORE;
     factFloor = vaultMinScore;
@@ -33747,50 +33779,50 @@ async function recall(query, ctx, options = {}) {
       rankedOnCosine: factRankedOnCosine,
       decryptLast: factDecryptLast,
       rowsDecrypted: factRowsDecrypted
-    } = await searchVaultMemoriesWithSize(
-      query,
+    } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
+      searchQuery,
       ctx.vaultCtx,
       ctx.embeddingOptions,
       ctx.vaultCache,
-      {
-        limit: types.includes("chunk") ? Math.max(limit * 2, 16) : limit,
-        minSimilarity: vaultMinScore,
-        useFusion: true,
-        rerank: flags.rerank,
-        ...options.rerankTopN !== void 0 && { rerankTopN: options.rerankTopN },
-        ...options.ceWeight !== void 0 && { ceWeight: options.ceWeight },
-        ...options.rerankLoadTimeoutMs !== void 0 && {
-          rerankLoadTimeoutMs: options.rerankLoadTimeoutMs
-        },
-        ...options.recencyAlpha !== void 0 && { recencyAlpha: options.recencyAlpha },
-        ...options.recency && { recency: options.recency },
-        ...options.mmr !== void 0 && { mmr: options.mmr },
-        ...options.supersessionBoost !== void 0 && {
-          supersessionBoost: options.supersessionBoost
-        },
-        ...options.supersessionWindow !== void 0 && {
-          supersessionWindow: options.supersessionWindow
-        },
-        ...options.proofCountAlpha !== void 0 && {
-          proofCountAlpha: options.proofCountAlpha
-        },
-        ...options.bm25AdmissionDivisor !== void 0 && {
-          bm25AdmissionDivisor: options.bm25AdmissionDivisor
-        },
-        ...options.rrfK !== void 0 && { rrfK: options.rrfK },
-        ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
-        ...subQueries && { subQueries },
-        ...options.scopes && { scopes: options.scopes },
-        ...options.folderId !== void 0 && { folderId: options.folderId },
-        ...options.factTypes?.length && { factTypes: options.factTypes },
-        ...options.memoryIds !== void 0 && { memoryIds: options.memoryIds },
-        ...options.factTypeWeights && { factTypeWeights: options.factTypeWeights },
-        ...entityRanking.length > 0 && { entityRanking },
-        ...temporalRanking.length > 0 && { temporalRanking },
-        ...needsChunkEmbedding && { queryEmbedding: queryEmbedding ?? [] },
-        queryEmbedTotalTimeoutMs
-      }
-    );
+      searchOptions
+    )))(query, {
+      limit: types.includes("chunk") ? Math.max(limit * 2, 16) : limit,
+      minSimilarity: vaultMinScore,
+      useFusion: true,
+      rerank: flags.rerank,
+      ...options.rerankTopN !== void 0 && { rerankTopN: options.rerankTopN },
+      ...options.ceWeight !== void 0 && { ceWeight: options.ceWeight },
+      ...options.rerankLoadTimeoutMs !== void 0 && {
+        rerankLoadTimeoutMs: options.rerankLoadTimeoutMs
+      },
+      ...options.recencyAlpha !== void 0 && { recencyAlpha: options.recencyAlpha },
+      ...options.recency && { recency: options.recency },
+      ...options.mmr !== void 0 && { mmr: options.mmr },
+      ...options.supersessionBoost !== void 0 && {
+        supersessionBoost: options.supersessionBoost
+      },
+      ...options.supersessionWindow !== void 0 && {
+        supersessionWindow: options.supersessionWindow
+      },
+      ...options.proofCountAlpha !== void 0 && {
+        proofCountAlpha: options.proofCountAlpha
+      },
+      ...options.bm25AdmissionDivisor !== void 0 && {
+        bm25AdmissionDivisor: options.bm25AdmissionDivisor
+      },
+      ...options.rrfK !== void 0 && { rrfK: options.rrfK },
+      ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
+      ...subQueries && { subQueries },
+      ...options.scopes && { scopes: options.scopes },
+      ...options.folderId !== void 0 && { folderId: options.folderId },
+      ...options.factTypes?.length && { factTypes: options.factTypes },
+      ...options.memoryIds !== void 0 && { memoryIds: options.memoryIds },
+      ...options.factTypeWeights && { factTypeWeights: options.factTypeWeights },
+      ...entityRanking.length > 0 && { entityRanking },
+      ...temporalRanking.length > 0 && { temporalRanking },
+      ...needsChunkEmbedding && { queryEmbedding: queryEmbedding ?? [] },
+      queryEmbedTotalTimeoutMs
+    });
     factResults.push(
       ...dedupeBy(
         results,

package/dist/server/index.d.mts

@@ -1227,13 +1227,13 @@ interface EmbeddingOptions {
      */
     tokenTimeoutMs?: number;
     /**
-     * Overall deadline, in ms, for one `generateEmbedding` call — the token read,
+     * 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`. Not applied by
-     * `generateEmbeddings`.
+     * BM25 within a few seconds instead of ~4 x `timeoutMs`. Batch calls share
+     * one budget across authentication, all chunks, retries and backoff.
      */
     totalTimeoutMs?: number;
 }
@@ -5998,6 +5998,55 @@ interface VaultSearchResult {
      * these to suppress the originating chunk in the chunk lane. */
     sourceChunkIds?: string[] | null;
 }
+/**
+ * Search + rank in one call. Thin wrapper over {@link prepareVaultCandidates} +
+ * {@link rankPreparedVaultCandidates}; behavior is unchanged.
+ */
+declare function searchVaultMemoriesWithSize(query: string, vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): Promise<{
+    results: VaultSearchResult[];
+    vaultSize: number;
+    reranked: boolean;
+    /**
+     * Wall-clock ms this search spent inside the cross-encoder.
+     *
+     * 0 on every path that did not reach the CE, which `reranked` already
+     * distinguishes from "ran and cost nothing". Reported because `factLane`
+     * timing alone could not separate the rerank from the query embed, the vault
+     * read and the fused ranking — see {@link RerankStats}.
+     */
+    rerankMs: number;
+    hadV2Head: boolean;
+    /** True when this search had no usable cosine lane and ranked on BM25 alone. */
+    embeddingsUnavailable: boolean;
+    /**
+     * True when this search actually scored rows against a real query vector.
+     *
+     * NOT the inverse of `embeddingsUnavailable`. That flag answers "did cosine
+     * break?", and it is `false` on the degenerate returns below — an invalid
+     * query, an empty scope, nothing decryptable — where cosine did not break so
+     * much as never run. A caller asking "can this lane vouch that semantic
+     * ranking happened?" (recall's chunk-lane reconciliation) must not read those
+     * as a healthy cosine pass.
+     */
+    rankedOnCosine: boolean;
+    /**
+     * Which vault read path ran — projected key scan (`true`) or legacy whole-vault
+     * load (`false`). See {@link PreparedVaultCandidates.decryptLast}.
+     */
+    decryptLast: boolean;
+    /**
+     * Rows this search paid to decrypt. Read against `vaultSize` — see
+     * {@link PreparedVaultCandidates.rowsDecrypted}.
+     */
+    rowsDecrypted: number;
+    /**
+     * Wall-clock ms spent embedding the query, and rows the lane had to re-embed
+     * because their stored vector was unusable — see
+     * {@link PreparedVaultCandidates.queryEmbedMs} and `rowsEmbedded`.
+     */
+    queryEmbedMs: number;
+    rowsEmbedded: number;
+}>;
 /**
  * Search vault memories by semantic similarity. Returns structured results
  * sorted by descending similarity, filtered by threshold and limit.
@@ -6262,7 +6311,15 @@ interface RecallOptions {
      */
     graphRefine?: boolean;
 }
+/** A fact source supplies bounded candidates; recall owns ranking and result handling. */
+interface RecallFactSource {
+    search: (query: string, options?: MemoryVaultSearchOptions) => ReturnType<typeof searchVaultMemoriesWithSize>;
+    graphRanking: (query: string, traverse: boolean, options: RecallOptions) => Promise<string[]>;
+    temporalRanking: (query: string, now?: number) => Promise<string[]>;
+}
 interface RecallContext {
+    /** Alternative to a WatermelonDB vault for fact-only recall. */
+    factSource?: RecallFactSource;
     /** Required when `types` includes 'fact'. */
     vaultCtx?: VaultMemoryOperationsContext;
     /** Required when `types` includes 'chunk'. */
@@ -10606,6 +10663,23 @@ interface PostgreSQLAdapterOptions {
  * @param pgSchema - PostgreSQL schema namespace (defaults to "public")
  */
 declare function schemaToCreateSQL(schema: AppSchema, pgSchema?: string): string[];
+/**
+ * WatermelonDB `DatabaseAdapter` backed by any `pg.Pool`-compatible pool, so SDK operations run unchanged on the server.
+ *
+ * @example
+ * ```typescript
+ * import pg from "pg";
+ * import { PostgreSQLAdapter, sdkSchema, sdkMigrations } from "@anuma/sdk/server";
+ *
+ * const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = new PostgreSQLAdapter({
+ *   pool,
+ *   schema: sdkSchema,
+ *   migrations: sdkMigrations,
+ *   dbName: "anuma-server-wallet123",
+ * });
+ * ```
+ */
 declare class PostgreSQLAdapter implements DatabaseAdapter {
     schema: AppSchema;
     dbName: string;

package/dist/server/index.d.ts

@@ -1227,13 +1227,13 @@ interface EmbeddingOptions {
      */
     tokenTimeoutMs?: number;
     /**
-     * Overall deadline, in ms, for one `generateEmbedding` call — the token read,
+     * 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`. Not applied by
-     * `generateEmbeddings`.
+     * BM25 within a few seconds instead of ~4 x `timeoutMs`. Batch calls share
+     * one budget across authentication, all chunks, retries and backoff.
      */
     totalTimeoutMs?: number;
 }
@@ -5998,6 +5998,55 @@ interface VaultSearchResult {
      * these to suppress the originating chunk in the chunk lane. */
     sourceChunkIds?: string[] | null;
 }
+/**
+ * Search + rank in one call. Thin wrapper over {@link prepareVaultCandidates} +
+ * {@link rankPreparedVaultCandidates}; behavior is unchanged.
+ */
+declare function searchVaultMemoriesWithSize(query: string, vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): Promise<{
+    results: VaultSearchResult[];
+    vaultSize: number;
+    reranked: boolean;
+    /**
+     * Wall-clock ms this search spent inside the cross-encoder.
+     *
+     * 0 on every path that did not reach the CE, which `reranked` already
+     * distinguishes from "ran and cost nothing". Reported because `factLane`
+     * timing alone could not separate the rerank from the query embed, the vault
+     * read and the fused ranking — see {@link RerankStats}.
+     */
+    rerankMs: number;
+    hadV2Head: boolean;
+    /** True when this search had no usable cosine lane and ranked on BM25 alone. */
+    embeddingsUnavailable: boolean;
+    /**
+     * True when this search actually scored rows against a real query vector.
+     *
+     * NOT the inverse of `embeddingsUnavailable`. That flag answers "did cosine
+     * break?", and it is `false` on the degenerate returns below — an invalid
+     * query, an empty scope, nothing decryptable — where cosine did not break so
+     * much as never run. A caller asking "can this lane vouch that semantic
+     * ranking happened?" (recall's chunk-lane reconciliation) must not read those
+     * as a healthy cosine pass.
+     */
+    rankedOnCosine: boolean;
+    /**
+     * Which vault read path ran — projected key scan (`true`) or legacy whole-vault
+     * load (`false`). See {@link PreparedVaultCandidates.decryptLast}.
+     */
+    decryptLast: boolean;
+    /**
+     * Rows this search paid to decrypt. Read against `vaultSize` — see
+     * {@link PreparedVaultCandidates.rowsDecrypted}.
+     */
+    rowsDecrypted: number;
+    /**
+     * Wall-clock ms spent embedding the query, and rows the lane had to re-embed
+     * because their stored vector was unusable — see
+     * {@link PreparedVaultCandidates.queryEmbedMs} and `rowsEmbedded`.
+     */
+    queryEmbedMs: number;
+    rowsEmbedded: number;
+}>;
 /**
  * Search vault memories by semantic similarity. Returns structured results
  * sorted by descending similarity, filtered by threshold and limit.
@@ -6262,7 +6311,15 @@ interface RecallOptions {
      */
     graphRefine?: boolean;
 }
+/** A fact source supplies bounded candidates; recall owns ranking and result handling. */
+interface RecallFactSource {
+    search: (query: string, options?: MemoryVaultSearchOptions) => ReturnType<typeof searchVaultMemoriesWithSize>;
+    graphRanking: (query: string, traverse: boolean, options: RecallOptions) => Promise<string[]>;
+    temporalRanking: (query: string, now?: number) => Promise<string[]>;
+}
 interface RecallContext {
+    /** Alternative to a WatermelonDB vault for fact-only recall. */
+    factSource?: RecallFactSource;
     /** Required when `types` includes 'fact'. */
     vaultCtx?: VaultMemoryOperationsContext;
     /** Required when `types` includes 'chunk'. */
@@ -10606,6 +10663,23 @@ interface PostgreSQLAdapterOptions {
  * @param pgSchema - PostgreSQL schema namespace (defaults to "public")
  */
 declare function schemaToCreateSQL(schema: AppSchema, pgSchema?: string): string[];
+/**
+ * WatermelonDB `DatabaseAdapter` backed by any `pg.Pool`-compatible pool, so SDK operations run unchanged on the server.
+ *
+ * @example
+ * ```typescript
+ * import pg from "pg";
+ * import { PostgreSQLAdapter, sdkSchema, sdkMigrations } from "@anuma/sdk/server";
+ *
+ * const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = new PostgreSQLAdapter({
+ *   pool,
+ *   schema: sdkSchema,
+ *   migrations: sdkMigrations,
+ *   dbName: "anuma-server-wallet123",
+ * });
+ * ```
+ */
 declare class PostgreSQLAdapter implements DatabaseAdapter {
     schema: AppSchema;
     dbName: string;