@anuma/sdk 4.2.1 → 5.0.1

package/dist/server/index.cjs

@@ -20612,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 }
@@ -20628,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] };
@@ -21212,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) {
@@ -21236,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;
@@ -21260,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,
@@ -21373,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 },
@@ -21613,6 +21629,7 @@ var init_recall = __esm({
     init_logger();
     init_constants();
     init_embeddings();
+    init_decomposeQuery();
     init_searchTool();
     init_graphTraversal();
     init_observationTrend();
@@ -22558,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) {
@@ -22663,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,
@@ -22767,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(
@@ -22791,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(
@@ -22807,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) {
@@ -22839,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";
@@ -22857,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;
@@ -24496,7 +24525,7 @@ __decorateClass([
 ], VaultFolder.prototype, "context", 2);
 
 // src/lib/db/schema.ts
-var SDK_SCHEMA_VERSION = 42;
+var SDK_SCHEMA_VERSION = 43;
 var sdkSchema = (0, import_watermelondb12.appSchema)({
   version: SDK_SCHEMA_VERSION,
   tables: [
@@ -24544,7 +24573,16 @@ var sdkSchema = (0, import_watermelondb12.appSchema)({
         { name: "conversation_id", type: "string", isIndexed: true },
         { name: "title", type: "string" },
         { name: "project_id", type: "string", isOptional: true, isIndexed: true },
-        { name: "created_at", type: "number" },
+        // Indexed to match every other list-sorted created_at in this schema.
+        // Note this single-column index is NOT what makes the conversation list
+        // reads fast on native SQLite — they all filter is_deleted as well, and
+        // SQLite will not combine the two indexes, so the composite created by
+        // the v42 migration is what its planner actually uses. This declaration
+        // still earns its keep on the other two adapters: LokiJS builds its
+        // binary indices from `isIndexed` (and ignores `sql` migration steps
+        // outright), and Postgres gathers statistics via autovacuum, so its
+        // planner can use a single-column index the SQLite planner skips.
+        { name: "created_at", type: "number", isIndexed: true },
         { name: "updated_at", type: "number" },
         { name: "is_deleted", type: "boolean", isIndexed: true },
         { name: "pinned_at", type: "number", isOptional: true }
@@ -25411,6 +25449,49 @@ var sdkMigrations = (0, import_migrations.schemaMigrations)({
           ]
         })
       ]
+    },
+    // v42 -> v43: Give the conversation list reads an index they can actually
+    // sort on. All five of them (getConversationsOp, getConversationsLazyOp,
+    // getConversationsByProjectOp, getConversationsByProjectLazyOp and the
+    // keyset getConversationsPageOp) emit `where is_deleted is 0 ... order by
+    // created_at desc`, so before this they resolved is_deleted through its
+    // index and then built a temp B-tree over every live row just to return
+    // the newest page.
+    //
+    // The index is COMPOSITE, and that is the whole point — a bare index on
+    // created_at does not fix this. SQLite will not combine two single-column
+    // indexes here, so with `is_deleted` indexed and `created_at` indexed
+    // separately it still picks conversations_is_deleted and still temp-sorts.
+    // It only prefers a lone created_at index once ANALYZE has populated
+    // sqlite_stat1, and nothing ever runs ANALYZE: not WatermelonDB, not its
+    // native SQLite bindings, not this SDK. Every device is permanently in the
+    // no-statistics state, so the index has to satisfy the filter and the sort
+    // in one structure. `(is_deleted, created_at)` does: equality on the
+    // leading column, ordered scan on the second, and the keyset boundary
+    // becomes a range seek on the same index.
+    //
+    // unsafeExecuteSql, not addColumns: both columns already exist and
+    // WatermelonDB has no add-index migration step, so raw SQL is the only way
+    // to build one in place (same shape as the v19 -> v20 memory_vault
+    // migration). IF NOT EXISTS keeps the step idempotent.
+    //
+    // Two limits worth knowing before someone re-measures this and finds it
+    // missing. First, the LokiJS (web) adapter discards `sql` steps entirely,
+    // so existing browser databases gain nothing — web's only lever is the
+    // `isIndexed` flag on the column itself. Second, this index reaches
+    // MIGRATED databases only: WatermelonDB builds a fresh database purely from
+    // the encoded schema, and its schema format cannot express a composite
+    // index. The one hook that could (`unsafeSql` on the table) is a function,
+    // and the LokiJS adapter posts the schema to its worker, so attaching it
+    // makes the whole schema fail structuredClone and takes the database down
+    // at setup for anyone on `useWebWorker: true`. Not worth it for an index.
+    {
+      toVersion: 43,
+      steps: [
+        (0, import_migrations.unsafeExecuteSql)(
+          "CREATE INDEX IF NOT EXISTS conversations_is_deleted_created_at ON conversations (is_deleted, created_at);"
+        )
+      ]
     }
   ]
 });
@@ -29733,6 +29814,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;
@@ -29830,7 +29912,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: {
@@ -29885,6 +29967,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;
@@ -29898,10 +29987,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) {

package/dist/server/index.d.mts

@@ -87,8 +87,12 @@ import { ResultCallback } from '@nozbe/watermelondb/utils/fp/Result';
  *   `topics_updated_at` is a SECOND timestamp because every topic writer pins
  *   `updated_at` on purpose (recall's recency multiplier) and both sync paths
  *   key on `updated_at`, so a topic-only change would neither upload nor merge
+ * - v43: Added a (is_deleted, created_at) index to conversations. Every
+ *   conversation list read filters is_deleted and orders by created_at DESC,
+ *   which previously meant a temp B-tree sort of the whole live set on every
+ *   read. Structural only — no column added, no data rewritten
  */
-declare const SDK_SCHEMA_VERSION = 42;
+declare const SDK_SCHEMA_VERSION = 43;
 /**
  * Combined WatermelonDB schema for all SDK storage modules.
  *
@@ -175,6 +179,7 @@ declare const sdkSchema: Readonly<{
  * - v39 → v40: Added `fact_type`, `archived_at`, `trust_tier` columns to memory_vault for typed memory + decay + Tier-0 security (all nullable + plaintext, NULL backfill)
  * - v40 → v41: Added `visibility`, `twin_opt_in`, `published_at`, `geohash` columns to memory_vault for the People Nearby cross-user visibility axis (two-tier `private | public`; null/unknown grandfathered as 'private')
  * - v41 → v42: Added `topics` + `topics_updated_at` columns to memory_vault, making a memory's topics the durable synced record and `entity`/`memory_entity` a device-local index over it (null `topics` = pre-v42, backfilled from the row's current links by the sweep)
+ * - v42 → v43: Added a composite `(is_deleted, created_at)` index to conversations so the list reads stop temp-sorting (structural only, no data rewritten)
  */
 declare const sdkMigrations: Readonly<{
     validated: true;
@@ -4945,15 +4950,26 @@ interface MemoryVaultSearchOptions {
     /** RRF smoothing constant for lane fusion. Default 60. */
     rrfK?: number;
     /**
-     * LLM-based query decomposition for composite/abstract queries. When set,
-     * each query is classified + (if composite) decomposed into 3–5 facet
-     * sub-queries via gpt-5-mini, then ranked via {@link rankComposite}.
-     * Requires `decomposeOptions` (auth) when set to "llm".
+     * Pre-decomposed facet queries for the composite ranker (719/B4). When
+     * ≥2 are supplied (and embeddings are available), runs {@link rankComposite}
+     * over them — no LLM call inside the search path. Callers that want LLM
+     * rewrite (e.g. `createRecallTool`) call `decomposeQuery` first and pass
+     * the facets here.
+     */
+    subQueries?: string[];
+    /**
+     * @deprecated 719/B4 — ignored by {@link searchVaultMemories} /
+     * {@link searchVaultMemoriesWithSize}. Pass {@link MemoryVaultSearchOptions.subQueries}
+     * (or use `createRecallTool`). The legacy {@link createMemoryVaultSearchTool}
+     * executor still honors `decompose: "llm"` + `decomposeOptions` for eval
+     * parity, then forwards facets into the LLM-free search path.
      */
     decompose?: "off" | "llm";
-    /** Auth + endpoint for the decomposition LLM call. Required when
-     * decompose="llm". Auth is the dual pattern — one of `apiKey` /
-     * `getToken`; see {@link PortalLlmAuth}. */
+    /**
+     * @deprecated 719/B4 — see `decompose`. Ignored on the programmatic search
+     * path; tool-layer rewrite still reads this from the search-tool options.
+     * Prefer `RecallToolOptions.decomposeOptions` with `createRecallTool`.
+     */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
         model?: string;
@@ -5118,9 +5134,11 @@ type MemoryKind = "fact" | "chunk";
  * Budget controls retrieval depth/cost. Higher budgets enable more
  * candidate sources and the cross-encoder reranker.
  *
- * - `low`: cosine + BM25 fusion only. No reranker. Mobile default.
- * - `mid`: + recency boost. Demo default.
- * - `high`: + cross-encoder rerank stage. Demo `budget: high` path.
+ * - `low`: cosine + BM25 + recency. No reranker. Mobile default.
+ * - `mid`: + cross-encoder rerank.
+ * - `high`: + multi-hop graph traversal. LLM-free — query decomposition
+ *   (when wanted) lives in the tool/agent layer ({@link createRecallTool}),
+ *   not inside `recall()` itself (719/B4).
  */
 type Budget = "low" | "mid" | "high";
 interface ScoreBreakdown {
@@ -5220,10 +5238,28 @@ interface RecallOptions {
     /** Drop results below this score. Default: 0.1 for facts, 0.5 for chunks (mirrors today's defaults). */
     minScore?: number;
     /**
-     * Auth + endpoint for the LLM-based query decomposition pass. Without
-     * these, decompose is skipped even at `budget: 'high'`. Mirrors the
-     * shape used by `searchVaultMemories`. Auth is the dual pattern — one
-     * of `apiKey` / `getToken` is required; see {@link PortalLlmAuth}.
+     * Pre-decomposed facet queries for the composite ranker. When ≥2 are
+     * supplied, the vault lane runs `rankComposite` over them (no LLM call
+     * inside `recall()` — 719/B4). Callers that still want LLM rewrite
+     * (e.g. {@link createRecallTool} at `budget: 'high'`) call
+     * `decomposeQuery` themselves and pass the result here. A single entry
+     * (or omitting this) keeps the single-query path.
+     */
+    subQueries?: string[];
+    /**
+     * Auth + endpoint for optional LLM helpers that reuse portal auth —
+     * currently {@link RecallOptions.graphRefine} neighbor selection.
+     * Query decomposition is **not** driven by this field inside `recall()`
+     * (719/B4); {@link createRecallTool} reads the same shape from
+     * `RecallToolOptions.decomposeOptions` for tool-layer rewrite.
+     *
+     * Callers that still pass `{ budget: 'high', decomposeOptions }` without
+     * {@link RecallOptions.subQueries} keep compiling but no longer rewrite —
+     * `recall()` emits `decompose-moved` on {@link RecallDiagnostics.degraded}
+     * so upgrades without a changelog read still leave a telemetry breadcrumb.
+     *
+     * Auth is the dual pattern — one of `apiKey` / `getToken` is required;
+     * see {@link PortalLlmAuth}.
      */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
@@ -5327,9 +5363,22 @@ type RecallDegradation =
 /** Rerank was requested (budget mid/high) but the cross-encoder didn't run
  *  this call — unavailable (e.g. React Native) or a transient failure. */
 "rerank-unavailable"
-/** `budget: 'high'` requested but no `decomposeOptions`, so query
- *  decomposition was skipped and the budget downgraded to mid. */
+/**
+ * @deprecated 719/B4 moved query decomposition out of `recall()`. Budget
+ * `high` no longer requires `decomposeOptions` and this signal is never
+ * emitted. Prefer `"decompose-moved"` for the upgrade breadcrumb. Kept in
+ * the union so existing telemetry consumers stay typed.
+ */
  | "decompose-unavailable"
+/**
+ * `budget: 'high'` with `decomposeOptions` set but no usable
+ * {@link RecallOptions.subQueries}. Pre-B4 this call shape triggered LLM
+ * rewrite inside `recall()`; post-B4 it stays on the single-query high
+ * path (rerank + graph) and callers must pass facets (or use
+ * {@link createRecallTool}). Surfaced so silent quality regressions show
+ * up in diagnostics instead of looking healthier than before.
+ */
+ | "decompose-moved"
 /** There was no usable cosine lane, so results were ranked on BM25 (lexical)
  *  alone: either the query embedding failed (or came back empty), or no
  *  candidate had a vector to score against it because the row (re)embed failed.
@@ -8103,9 +8152,14 @@ declare function rankProfileCandidates(inputs: readonly ProfileSalienceInput[],
  * Unified Recall API — single retrieval surface above vault + engine.
  *
  * Budget maps to pipeline depth (mirrors Hindsight's tiered defaults):
- * - `low`  → V2 cosine + BM25 + recency (no rerank, no decompose)
+ * - `low`  → V2 cosine + BM25 + recency (no rerank)
  * - `mid`  → V2 + cross-encoder rerank
- * - `high` → V2 + rerank + LLM query decomposition for composite queries
+ * - `high` → V2 + rerank + multi-hop graph traversal
+ *
+ * LLM-free by design (719/B4): query decomposition for composite asks
+ * lives in the tool/agent layer (`createRecallTool`), which may pass
+ * pre-built `subQueries` into this API. `recall()` itself never pays an
+ * LLM RTT.
  *
  * Fact + chunk lanes are fused with RRF (k=60). The previous naive
  * "sort the union by raw score" path is gone — score scales differ
@@ -8160,7 +8214,8 @@ interface RecallToolOptions {
     folderId?: string | null;
     /** Exclude one conversation from chunk results (typically the active one). */
     excludeConversationId?: string;
-    /** LLM-decompose options; only used at budget="high". Auth follows the
+    /** LLM-decompose options; only used at budget="high". Runs in THIS tool
+     * executor (719/B4) — `recall()` itself is LLM-free. Auth follows the
      * dual pattern: apiKey (server/CLI) or getToken (browser identity
      * tokens) — at least one required. */
     decomposeOptions?: PortalLlmAuth & {