@anuma/sdk 4.2.1 → 5.0.1

package/dist/server/index.d.ts

@@ -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 & {

package/dist/server/index.mjs

@@ -43,6 +43,7 @@ import {
   createVaultEmbeddingCache,
   createVaultMemoriesBatchOp,
   createVaultMemoryOp,
+  decomposeQuery,
   decryptData,
   decryptDataBatch,
   decryptDataBytes,
@@ -136,7 +137,7 @@ import {
   updateVaultMemoryOp,
   upsertMessageOp,
   vaultMemoryToStored
-} from "./chunk-UQDYBQVF.mjs";
+} from "./chunk-FKVYUOSD.mjs";
 import {
   createStreamingDeAnonymizer,
   notifyConsolidationFallback,
@@ -1318,7 +1319,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: [
@@ -1366,7 +1367,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 }
@@ -2233,6 +2243,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);"
+        )
+      ]
     }
   ]
 });
@@ -6586,7 +6639,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: {
@@ -6641,6 +6694,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;
@@ -6654,10 +6714,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/{recall-ZHEPQNEU.mjs → recall-74L75BJ3.mjs}

@@ -1,6 +1,6 @@
 import {
   recall
-} from "./chunk-UQDYBQVF.mjs";
+} from "./chunk-FKVYUOSD.mjs";
 import "./chunk-OBDRKQQI.mjs";
 import "./chunk-3RPGXXPZ.mjs";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "4.2.1",
+  "version": "5.0.1",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",