@anuma/sdk 6.19.2 → 6.21.0

package/dist/server/index.cjs

@@ -21668,7 +21668,22 @@ async function recall(query, ctx, options = {}) {
   let factLaneRankedOnCosine = false;
   let decryptLastRan;
   let vaultRowsDecrypted;
-  const emitDiagnostics = (candidateCount) => {
+  let graphLaneCount = 0;
+  let temporalLaneCount = 0;
+  let graphLaneFailed = false;
+  let temporalLaneFailed = false;
+  let hitLimit = false;
+  let factFloor = -1;
+  let chunkFloor = -1;
+  const emptyReasonFor = (admitted, laneRan) => {
+    if (admitted > 0) return "";
+    if (!query || typeof query !== "string" || query.trim().length === 0) return "empty-query";
+    if (!laneRan) return "no-lanes";
+    const chunkLaneCouldAnswer = types.includes("chunk") && !!ctx.storageCtx;
+    if (vaultSize === 0 && !chunkLaneCouldAnswer) return "vault-empty";
+    return "no-candidates";
+  };
+  const emitDiagnostics = (candidateCount, admitted) => {
     const cb = options.onDiagnostics;
     if (!cb) return;
     const degraded = [];
@@ -21679,6 +21694,11 @@ async function recall(query, ctx, options = {}) {
       degraded.push("decompose-moved");
     }
     if (embeddingsUnavailable) degraded.push("embeddings-unavailable");
+    if (graphLaneFailed) degraded.push("graph-lane-failed");
+    if (temporalLaneFailed) degraded.push("temporal-lane-failed");
+    const laneRan = types.includes("fact") && !!ctx.vaultCtx && !!ctx.vaultCache || types.includes("chunk") && !!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 = {
       usedBudget,
       reranked: didRerank,
@@ -21689,6 +21709,14 @@ async function recall(query, ctx, options = {}) {
       ...vaultRowsEmbedded !== void 0 && { vaultRowsEmbedded },
       factCount: factResults.length,
       chunkCount: chunkResults.length,
+      admittedCount: admitted.length,
+      topScore: scores.length > 0 ? Math.max(...scores) : -1,
+      lowestAdmittedScore: scores.length > 0 ? Math.min(...scores) : -1,
+      minScoreApplied,
+      truncated: hitLimit,
+      graphLaneCount,
+      temporalLaneCount,
+      emptyReason: emptyReasonFor(admitted.length, laneRan),
       timings: {
         total: nowMs() - t0,
         prep: prepMs,
@@ -21706,7 +21734,7 @@ async function recall(query, ctx, options = {}) {
     }
   };
   if (!query || typeof query !== "string" || query.trim().length === 0) {
-    emitDiagnostics(0);
+    emitDiagnostics(0, []);
     return { memories: [], usedBudget, reranked: false, candidateCount: 0 };
   }
   const needsChunkEmbedding = types.includes("chunk") && ctx.storageCtx;
@@ -21740,6 +21768,7 @@ async function recall(query, ctx, options = {}) {
     // empty ranking instead (mirrors safeCountVault's fail-soft posture).
     safeLane(
       "graph",
+      () => graphLaneFailed = true,
       () => buildGraphLaneRanking(query, ctx, flags.traverse, {
         ...options.maxHops !== void 0 && { maxHops: options.maxHops },
         ...options.entityFanout !== void 0 && { entityFanout: options.entityFanout },
@@ -21748,12 +21777,19 @@ async function recall(query, ctx, options = {}) {
         ...graphRefiner && { refineNeighbors: graphRefiner }
       })
     ),
-    wantsTemporal ? safeLane("temporal", () => buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)) : Promise.resolve([])
+    wantsTemporal ? safeLane(
+      "temporal",
+      () => temporalLaneFailed = true,
+      () => buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)
+    ) : Promise.resolve([])
   ]);
   prepMs = nowMs() - prepStart;
+  graphLaneCount = entityRanking.length;
+  temporalLaneCount = temporalRanking.length;
   if (types.includes("fact") && ctx.vaultCtx && ctx.vaultCache) {
     const factStart = nowMs();
     const vaultMinScore = options.minScore ?? DEFAULT_FACT_MIN_SCORE;
+    factFloor = vaultMinScore;
     const {
       results,
       vaultSize: size,
@@ -21833,6 +21869,7 @@ async function recall(query, ctx, options = {}) {
   if (types.includes("chunk") && ctx.storageCtx && queryEmbedding) {
     const chunkStart = nowMs();
     const chunkMinScore = options.minScore ?? DEFAULT_CHUNK_MIN_SCORE;
+    chunkFloor = chunkMinScore;
     const results = await searchChunksOp(ctx.storageCtx, queryEmbedding, {
       limit: types.includes("fact") ? Math.max(limit * 2, 16) : limit,
       minSimilarity: chunkMinScore,
@@ -21859,9 +21896,11 @@ async function recall(query, ctx, options = {}) {
     memories2.sort((a, b) => b.score - a.score);
     const candidateCount = factResults.length + chunkResults.length;
     fuseMs = nowMs() - fuseStart;
-    emitDiagnostics(candidateCount);
+    const admitted = memories2.slice(0, limit);
+    hitLimit = memories2.length > limit;
+    emitDiagnostics(candidateCount, admitted);
     return {
-      memories: memories2.slice(0, limit),
+      memories: admitted,
       usedBudget,
       reranked: didRerank,
       candidateCount,
@@ -21891,12 +21930,16 @@ async function recall(query, ctx, options = {}) {
   const ordered = [...byId.values()].sort((a, b) => b.score - a.score);
   const selectWith = (suppressed2) => {
     const out = [];
+    let cut = false;
     for (const m of ordered) {
-      if (out.length >= limit) break;
       if (m.kind === "chunk" && m.messageId && suppressed2.has(m.messageId)) continue;
+      if (out.length >= limit) {
+        cut = true;
+        break;
+      }
       out.push(m);
     }
-    return out;
+    return { out, cut };
   };
   const provenanceOf = (selected) => {
     const s = /* @__PURE__ */ new Set();
@@ -21906,15 +21949,18 @@ async function recall(query, ctx, options = {}) {
     return s;
   };
   let suppressed = /* @__PURE__ */ new Set();
-  let memories = selectWith(suppressed);
+  let selection = selectWith(suppressed);
+  let memories = selection.out;
   for (let i = 0; i < ordered.length; i++) {
     const next = provenanceOf(memories);
     if (next.size === suppressed.size && [...next].every((id) => suppressed.has(id))) break;
     suppressed = next;
-    memories = selectWith(suppressed);
+    selection = selectWith(suppressed);
+    memories = selection.out;
   }
+  hitLimit = selection.cut;
   fuseMs = nowMs() - fuseStart;
-  emitDiagnostics(byId.size);
+  emitDiagnostics(byId.size, memories);
   return {
     memories,
     usedBudget,
@@ -21998,10 +22044,11 @@ async function safeCountVault(ctx) {
     return void 0;
   }
 }
-async function safeLane(label, run) {
+async function safeLane(label, onFailure, run) {
   try {
     return await run();
   } catch (err) {
+    onFailure();
     getLogger().warn(
       `[memory/recall] ${label} lane failed; continuing without it: ${err instanceof Error ? err.message : String(err)}`
     );
@@ -29296,6 +29343,7 @@ async function retain(content, ctx, options = {}) {
   const threshold = options.autoMergeThreshold ?? DEFAULT_AUTO_MERGE_THRESHOLD;
   const resolvedScope = options.scope ?? DEFAULT_SCOPE;
   let supersedeTargetIds = [];
+  let consolidationDecidedCreate = false;
   let supersedeContent;
   let prepared;
   if (enableAutoMerge) {
@@ -29323,8 +29371,12 @@ async function retain(content, ctx, options = {}) {
       const outcome = await tryConsolidate(trimmed, ctx, options, prepared);
       if (outcome) {
         if ("done" in outcome) return outcome.done;
-        supersedeTargetIds = outcome.supersede;
-        supersedeContent = outcome.content;
+        if ("create" in outcome) {
+          consolidationDecidedCreate = true;
+        } else {
+          supersedeTargetIds = outcome.supersede;
+          supersedeContent = outcome.content;
+        }
       }
     }
     if (supersedeTargetIds.length === 0) {
@@ -29374,7 +29426,14 @@ async function retain(content, ctx, options = {}) {
               action: "merge",
               memoryId: targetId,
               targetId,
-              proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+              proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1,
+              similarity: matches[0].similarity,
+              // Stage 1 may have run and explicitly said `create`, and Stage 2
+              // then found a strict-cosine match anyway. Reporting the decision
+              // here is what makes that DISAGREEMENT visible — without it the
+              // model's create silently vanished from the distribution whenever
+              // the cosine stage won.
+              ...consolidationDecidedCreate && { consolidation: "create" }
             };
           }
           await assertMergeTargetGoneOrThrow(ctx, targetId);
@@ -29387,12 +29446,18 @@ async function retain(content, ctx, options = {}) {
   const embedding = reusableQueryEmbedding ?? await generateEmbedding(contentToWrite, ctx.embeddingOptions);
   const embeddingModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   if (options.respectTombstones) {
-    const tombstoneId = await findTombstoneMatch(embedding, embeddingModel, resolvedScope, ctx, {
+    const tombstone = await findTombstoneMatch(embedding, embeddingModel, resolvedScope, ctx, {
       threshold,
       folderId: options.folderId
     });
-    if (tombstoneId) {
-      return { action: "suppressed", memoryId: tombstoneId, tombstoneId, proofCount: 0 };
+    if (tombstone) {
+      return {
+        action: "suppressed",
+        memoryId: tombstone.id,
+        tombstoneId: tombstone.id,
+        proofCount: 0,
+        similarity: tombstone.similarity
+      };
     }
   }
   const createOpts = {
@@ -29459,7 +29524,8 @@ async function retain(content, ctx, options = {}) {
         action: "supersede",
         memoryId: created2.uniqueId,
         targetId: primaryTargetId,
-        proofCount: 1
+        proofCount: 1,
+        consolidation: "supersede"
       };
     }
     notifyConsolidationFallback(
@@ -29473,7 +29539,8 @@ async function retain(content, ctx, options = {}) {
   return {
     action: "create",
     memoryId: created.uniqueId,
-    proofCount: 1
+    proofCount: 1,
+    ...consolidationDecidedCreate && { consolidation: "create" }
   };
 }
 function unionStrings(a, b) {
@@ -29503,7 +29570,7 @@ async function findTombstoneMatch(embedding, embeddingModel, scope, ctx, opts) {
       bestId = row.uniqueId;
     }
   }
-  return bestId;
+  return bestId === null ? null : { id: bestId, similarity: bestSim };
 }
 function pickEventTimeUpdate(existing, incoming) {
   if (incoming === void 0 || incoming === null) return void 0;
@@ -29545,7 +29612,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
   }));
   const { consolidateMemory: doConsolidate } = await Promise.resolve().then(() => (init_consolidate(), consolidate_exports));
   const decision = await doConsolidate(trimmed, candidates, consolidateOptions);
-  if (decision.action === "create") return null;
+  if (decision.action === "create") return decision.fallbackReason ? null : { create: true };
   if (decision.action === "supersede" && decision.content) {
     const requestedIds = decision.targetIds?.length ? decision.targetIds : decision.targetId ? [decision.targetId] : [];
     if (requestedIds.length === 0) return null;
@@ -29604,7 +29671,8 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
         action: "merge",
         memoryId: decision.targetId,
         targetId: decision.targetId,
-        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1,
+        consolidation: "noop"
       }
     };
   }
@@ -29657,7 +29725,8 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
         action: "update",
         memoryId: decision.targetId,
         targetId: decision.targetId,
-        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1,
+        consolidation: "update"
       }
     };
   }
@@ -29799,6 +29868,11 @@ Extract durable user facts.`,
     fallbackSourceId,
     options.userIdentity ?? []
   );
+  const rawCandidates = parsed.candidates;
+  options.onCandidatesParsed?.({
+    rawCount: Array.isArray(rawCandidates) ? rawCandidates.length : 0,
+    validCount: candidates.length
+  });
   if (!redactor) return candidates;
   const restored = restoreCandidates(candidates, redactor, options.userIdentity ?? []);
   if (candidates.length > 0 && restored.length === 0) {
@@ -29835,8 +29909,12 @@ async function extractAndRetain(messages, retainCtx, options) {
   let exhaustedEmpty = false;
   let exhaustedFailure;
   let droppedAfterRedaction = false;
+  let rawCandidateCount = 0;
+  let validCandidateCount = 0;
   const callerOnExhaustedEmpty = options.extract.onExhaustedEmpty;
   const callerOnCandidatesDropped = options.extract.onCandidatesDropped;
+  const callerOnCandidatesParsed = options.extract.onCandidatesParsed;
+  const tExtract = Date.now();
   const candidates = await extractFacts(messages, {
     ...options.extract,
     onExhaustedEmpty: (failure) => {
@@ -29847,8 +29925,14 @@ async function extractAndRetain(messages, retainCtx, options) {
     onCandidatesDropped: () => {
       droppedAfterRedaction = true;
       callerOnCandidatesDropped?.();
+    },
+    onCandidatesParsed: (stats) => {
+      rawCandidateCount = stats.rawCount;
+      validCandidateCount = stats.validCount;
+      callerOnCandidatesParsed?.(stats);
     }
   });
+  const extractMs = Date.now() - tExtract;
   const filtered = candidates.filter((c) => c.confidence >= minConfidence);
   const log = getLogger();
   const screened = screenCandidatesForInjection(filtered);
@@ -29896,6 +29980,7 @@ async function extractAndRetain(messages, retainCtx, options) {
   const results = [];
   const quarantinedInfo = [];
   let failedWrites = 0;
+  const tRetain = Date.now();
   for (const { candidate, isQuarantined, reason, signature } of toRetain) {
     try {
       const result = await retain(candidate.content, retainCtx, {
@@ -29962,6 +30047,21 @@ async function extractAndRetain(messages, retainCtx, options) {
     failedCount: failedWrites,
     outcome,
     quarantined: quarantinedInfo,
+    funnel: {
+      rawCandidateCount,
+      validCandidateCount,
+      afterRedactionCount: candidates.length,
+      aboveConfidenceCount: filtered.length,
+      // The PERSISTED quarantines (`quarantinedInfo`), not the screened list: a
+      // screened candidate whose retain() throws is counted in `failedCount`,
+      // and counting it here too would double it and break the identity below.
+      // This also keeps the count equal to `quarantined.length` on the result.
+      quarantinedCount: quarantinedInfo.length,
+      retainedCount: results.length,
+      failedCount: failedWrites
+    },
+    timings: { extractMs, retainMs: Date.now() - tRetain },
+    model: options.extract.model ?? DEFAULT_EXTRACTION_MODEL,
     // Only meaningful alongside `outcome: "empty-after-retry"`. Returned as well
     // as pushed through the callback so a consumer that only inspects the result
     // (rather than wiring a hook) can still report WHY.
@@ -30217,27 +30317,23 @@ function createAutoExtractor(options) {
     const t0 = Date.now();
     void (async () => {
       try {
-        const { candidates, results, failedCount, outcome, failure } = await extractAndRetain(
-          window2,
-          retainCtx,
-          {
-            extract,
-            ...options.minConfidence !== void 0 && { minConfidence: options.minConfidence },
-            ...options.entityCtx !== void 0 && { entityCtx: options.entityCtx },
-            ...options.scope !== void 0 && { scope: options.scope },
-            ...options.folderId !== void 0 && { folderId: options.folderId },
-            ...consolidateOptions !== void 0 && { consolidateOptions },
-            ...injectionClassifierOptions !== void 0 && {
-              injectionClassifier: injectionClassifierOptions
-            },
-            ...options.onCandidateFailed && {
-              onCandidateFailed: (candidate, error) => options.onCandidateFailed?.({ candidate, error, conversationId })
-            },
-            ...options.onMemoryQuarantined && {
-              onQuarantined: (info) => options.onMemoryQuarantined?.({ ...info, conversationId })
-            }
+        const { candidates, results, failedCount, outcome, failure, funnel, timings, model } = await extractAndRetain(window2, retainCtx, {
+          extract,
+          ...options.minConfidence !== void 0 && { minConfidence: options.minConfidence },
+          ...options.entityCtx !== void 0 && { entityCtx: options.entityCtx },
+          ...options.scope !== void 0 && { scope: options.scope },
+          ...options.folderId !== void 0 && { folderId: options.folderId },
+          ...consolidateOptions !== void 0 && { consolidateOptions },
+          ...injectionClassifierOptions !== void 0 && {
+            injectionClassifier: injectionClassifierOptions
+          },
+          ...options.onCandidateFailed && {
+            onCandidateFailed: (candidate, error) => options.onCandidateFailed?.({ candidate, error, conversationId })
+          },
+          ...options.onMemoryQuarantined && {
+            onQuarantined: (info) => options.onMemoryQuarantined?.({ ...info, conversationId })
           }
-        );
+        });
         if (outcome !== "empty-after-retry") {
           const advancedTo = window2[window2.length - 1].id;
           stateFor(conversationId).watermark = advancedTo;
@@ -30258,6 +30354,9 @@ function createAutoExtractor(options) {
           durationMs: Date.now() - t0,
           conversationId,
           outcome,
+          funnel,
+          timings,
+          model,
           // Only set alongside `outcome: "empty-after-retry"`. Spread so the key
           // is absent rather than explicitly undefined on a healthy turn —
           // analytics backends store an explicit undefined as a real value.