@anuma/sdk 6.19.2 → 6.20.0

package/dist/server/index.d.mts

@@ -5795,6 +5795,15 @@ interface RecallDiagnostics {
     degraded: RecallDegradation[];
 }
 type RetainAction = "create" | "merge" | "update" | "skip" | "suppressed" | "supersede";
+/**
+ * The consolidation LLM's decision for a candidate, when it made one. Reported
+ * on {@link RetainResult.consolidation} so a host can tell an LLM `noop` (the
+ * fact already exists) from a cosine auto-merge — both arrive as
+ * `action: "merge"` — and can read how often the model reaches for `supersede`
+ * or `update` versus `create`. A degraded fallback create (LLM error, bad
+ * response) carries no decision; `onFallback` reports those.
+ */
+type ConsolidationAction = "create" | "update" | "noop" | "supersede";
 type RetainSource = "manual" | "auto-extracted" | "capsule";
 /**
  * Why a retain returned "create" instead of applying a consolidation decision.
@@ -5934,6 +5943,33 @@ interface RetainResult {
     tombstoneId?: string;
     /** Updated proof_count after this write. 0 when nothing was written (suppressed). */
     proofCount: number;
+    /**
+     * How close the write was to the threshold that allowed it. Absent on the
+     * actions that have no such score (`create`, `update`, `supersede`, `skip`).
+     *
+     * The two paths report DIFFERENT things and a dashboard has to know which:
+     *
+     * - `suppressed` — an exact cosine against the tombstone, computed in
+     *   `findTombstoneMatch`.
+     * - `merge` — the RANKER's score for the target, not a pure cosine. The
+     *   cosine is what cleared `minSimilarity`, but the supersession pass may
+     *   then adjust it (`oldScore - delta` / `newScore + delta`) before this
+     *   value is read, and can in principle reorder the winner. Read it as
+     *   "the score the merge was chosen on", within the supersession delta of
+     *   the cosine — not as the raw pairwise similarity.
+     */
+    similarity?: number;
+    /**
+     * What the consolidation LLM decided for this candidate, when consolidation
+     * ran — see {@link ConsolidationAction}.
+     *
+     * Reported for the DECISION, not for what the write ended up doing, so the
+     * two can disagree and be read as such: a `merge` carrying
+     * `consolidation: "create"` is the model saying "new fact" and the strict
+     * cosine stage merging anyway. Absent when consolidation did not run, and
+     * absent on a degraded fallback create (`onFallback` owns that signal).
+     */
+    consolidation?: ConsolidationAction;
 }
 
 /**
@@ -6160,6 +6196,61 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * callers may leave it unset.
      */
     onAttempt?: (attempt: PortalLlmAttempt) => void;
+    /**
+     * Fired once per successful completion with how many candidates the model
+     * emitted (`rawCount`) and how many survived {@link validateCandidates}
+     * (`validCount`) — the non-string / empty / over-cap / low-signal / bad-
+     * confidence drops that until now were a bare `continue` nobody counted.
+     *
+     * Without it a `no-facts` turn cannot be split into "the model found nothing"
+     * and "the model found things we threw away", which is the difference between
+     * a prompt problem and a validator problem. Counts only; never content.
+     */
+    onCandidatesParsed?: (stats: {
+        rawCount: number;
+        validCount: number;
+    }) => void;
+}
+/**
+ * Where a turn's candidates went between the model's completion and the vault —
+ * every stage that can drop one, as a count. Returned by {@link extractAndRetain}
+ * and forwarded on `TurnCompleteEvent` so a host can emit it; nothing here is
+ * content.
+ *
+ * Reads as a funnel: `raw ≥ valid ≥ afterRedaction ≥ aboveConfidence`, then
+ * `aboveConfidence = quarantined + retained + failed`.
+ * @public
+ */
+interface ExtractionFunnel {
+    /** Candidates in the model's completion, before any validation. */
+    rawCandidateCount: number;
+    /** Survivors of {@link validateCandidates} (shape, length, low-signal, confidence-is-a-number). */
+    validCandidateCount: number;
+    /** Survivors of PII de-anonymization (equals `validCandidateCount` when redaction is off). */
+    afterRedactionCount: number;
+    /** Survivors of the `minConfidence` floor — the candidates that reached the injection screen. */
+    aboveConfidenceCount: number;
+    /**
+     * Held for review by the injection screen and SUCCESSFULLY persisted — the
+     * same set as `extractAndRetain`'s `quarantined`. A screened candidate whose
+     * `retain()` threw is in `failedCount` instead, never both.
+     */
+    quarantinedCount: number;
+    /** Written through `retain()` (any disposition). */
+    retainedCount: number;
+    /** `retain()` threw. */
+    failedCount: number;
+}
+/**
+ * Wall-clock split of one {@link extractAndRetain} call. The worker's
+ * `durationMs` is the sum plus the screen; these say which half is slow.
+ * @public
+ */
+interface ExtractionTimings {
+    /** The extraction LLM call, all attempts and backoff included. */
+    extractMs: number;
+    /** The retain loop — embeddings, consolidation LLM calls, writes — over every candidate. */
+    retainMs: number;
 }
 /**
  * Stage 1 — call the LLM to extract candidate facts from the recent
@@ -6277,6 +6368,12 @@ declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: Ret
      * the give-up, so "extraction is failing" can be reported as *why* it failed.
      */
     failure?: PortalLlmFailure;
+    /** Where the candidates went, stage by stage — see {@link ExtractionFunnel}. */
+    funnel: ExtractionFunnel;
+    /** Extract vs. retain wall-clock — see {@link ExtractionTimings}. */
+    timings: ExtractionTimings;
+    /** The extraction model this call asked for (the resolved default when unset). */
+    model: string;
 }>;
 
 /**
@@ -8072,6 +8169,16 @@ interface TurnCompleteEvent {
      * carries content.
      */
     failure?: PortalLlmFailure;
+    /**
+     * Where the candidates went between the model and the vault, as counts — the
+     * drops before `retain()` that `candidates`/`results` cannot show. See
+     * {@link ExtractionFunnel}.
+     */
+    funnel?: ExtractionFunnel;
+    /** Extract vs. retain wall-clock split of `durationMs`. See {@link ExtractionTimings}. */
+    timings?: ExtractionTimings;
+    /** The extraction model this turn asked for. */
+    model?: string;
 }
 /** @public */
 /**
@@ -10734,4 +10841,4 @@ declare function sanitizeQuotes(s: string): string;
 declare function renderTemplate(value: string | null | undefined, template: string): string | null;
 declare function buildSystemPrompt(ctx: PromptContext, options?: BuildPromptOptions): BuildPromptResult;
 
-export { type AnalyzeStyleOptions, type AnalyzeStyleResult, type ApiResponse, type ApiType, type AutoExecutedToolResult, type AutoExtractMessage, type AutoExtractor, type Budget, type BuildPromptOptions, type BuildPromptResult, type CachedChunkVectors, type CachedServerTools, type ChatCompletionUsage, type ChatRole, type ChunkSearchResult, type ChunkVectorCache, type ChunkingOptions, type ConnectorGuidance, type ConnectorGuidanceInput, type ConsolidationFallbackReason, Conversation, ConversationSummary, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMediaOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateProjectOptions, type CreateUserPreferenceOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_ANALYSIS_PROMPT, DEFAULT_ANALYZE_AFTER_MESSAGES, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_DOCUMENT_PATTERN, DEFAULT_EXCLUDED_SERVER_TOOLS, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MAX_INPUT_MESSAGES, DEFAULT_MAX_PROFILE_LENGTH, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_MIN_MESSAGES, DEFAULT_PERSONALITY_SETTINGS, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_PROMPT_TEMPLATES, DEFAULT_REFRESH_EVERY_MESSAGES, DEFAULT_SERVER_TOOLS_MATCH_OPTIONS, DEFAULT_SUMMARY_MIN_WINDOW_MESSAGES, DEFAULT_SUMMARY_MODEL, DEFAULT_SUMMARY_TOKEN_THRESHOLD, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, ExcelProcessor, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FileProcessor, type FileTypeQuery, type FileWithData, type FlushResult, type GetConversationsPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type LlmTokenUsage, MAX_HOPS, MAX_MESSAGES_PER_SUMMARIZATION, MEDIUM_TTL_MS, Media, type MediaDimensions, type MediaFilterOptions, type MediaMetadata, type MediaOperationsContext, type MediaRole, type MediaType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, Message, type MessageChunk, type MessageFeedback, type MessageOrigin, type ModelCallEndEvent, type ModelCallStartEvent, ModelPreference, NEVER_TTL_MS, NODE_BUDGET, type NeighborRefiner, type NowSource, type ObservationTrend, type ObservationTrendInput, type OperationExecutor, PAST_EVENT_GRACE_MS, PROFILE_DOC_VERSION, type ParsedServerToolsResponse, PdfProcessor, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type PgClientLike, type PgPoolLike, type PhotoIngestResult, type PhotoMediaRef, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, PostgreSQLAdapter, type PostgreSQLAdapterOptions, type PreprocessingOptions, type PreprocessingResult, type ProcessedFileResult, ProcessorRegistry, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type ProfileUpdate, Project, type ProjectOperationsContext, type PromptContext, type PromptPreProcessor, type PromptPreProcessorContext, type PromptSection, type PromptTemplates, type PublishedPhotoMemory, type QuarantinedMemoryInfo, type QueueEncryptionContext, QueueManager, type QueueStatus, type QueuedOperation, type QueuedOperationType, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, type RunEndEvent, type RunErrorEvent, type RunHooks, type RunStartEvent, type RunTerminalState, type RunToolLoopOptions, type RunToolLoopResult, SDK_SCHEMA_VERSION, SERVER_TOOL_DEPENDENCY_SETS, SHORT_TTL_MS, SLIDER_CONFIG, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SelectServerToolsForPromptOptions, type ServerTool, type ServerToolCallEvent, type ServerToolsFilterFunction, type ServerToolsOptions, type ServerToolsResponse, type SettingsStorageOperationsContext, type SignMessageFn, type StepFinishEvent, type StockPriceClassification, type StockPricePreProcessorOptions, type StorageOperationsContext, type StoredConversation, type StoredConversationSummary, type StoredFileWithContext, type StoredMedia, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, type StoredProject, type StoredUserPreference, type StoredVaultMemory, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type StreamSmoothingConfig, type StreamingTransport, type StreamingTransportOptions, type StreamingTransportResult, type StyleAnalysisSchedule, type SynthesizeProfileOptions, TOOL_CATALOG, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, TextProcessor, type ToolConfig, type ToolExecutor, type ToolMatchOptions, type ToolMatchResult, type ToolSet, type ToolUseEndEvent, type ToolUseStartEvent, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateMediaOptions, type UpdateModelPreferenceOptions, type UpdateProjectOptions, type UpdateUserPreferenceOptions, type UpdateVaultMemoryOptions, UserPreference, type UserPreferencesStorageOperationsContext, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, VaultMemory, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, WordProcessor, ZipProcessor, type ZipProcessorOptions, activatedToolSetNames, analyzeStyle, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildConnectorGuidance, buildDeniedToolsRider, buildSystemPrompt, capHopsForDensity, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, cleanupConversationSummary, clearAllEncryptionKeys, clearAllEncryptionState, clearAllKeyPairs, clearEncryptionKey, clearKeyPair, clearLazyTitleCache, clearMessagesOp, clearServerToolsCache, composeHooks, createAutoExtractor, createChunkVectorCache, createConversationOp, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMediaBatchOp, createMediaOp, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageOp, createMessageSourceResolver, createPlatformCursorStore, createProjectOp, createRecallTool, createServerToolsFilter, createStockPricePreProcessor, createSummaryContext, createVaultEmbeddingCache, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, decryptData, decryptDataBatch, decryptDataBytes, decryptDataBytesFromBytes, decryptDataWithKey, defaultServerToolsFilter, deleteAllVaultMemoriesForUserOp, deleteConversationOp, deleteConversationSummaryOp, deleteMediaByConversationOp, deleteMediaByMessageOp, deleteMediaOp, deleteModelPreferenceOp, deleteProjectOp, deleteUserPreferenceOp, deleteVaultMemoryOp, eagerEmbedContent, embedAllMessages, embedMessage, encryptData, encryptDataBatch, encryptDataBytes, encryptDataWithKey, estimateMessagesTokens, estimateTokens, exportPublicKey, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, findMatchingTools, generateConversationId, generateEmbedding, generateEmbeddings, generateMediaId, generateProjectId, getAIGeneratedMediaOp, getAllFilesOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getAudioOp, getCachedServerTools, getConversationOp, getConversationSummaryOp, getConversationsByProjectLazyOp, getConversationsByProjectOp, getConversationsLazyOp, getConversationsOp, getConversationsPageOp, getDecayCandidatesRawOp, getDocumentsOp, getEncryptionKey, getImagesOp, getMediaByConversationOp, getMediaByIdOp, getMediaByIdsOp, getMediaByMessageOp, getMediaByModelOp, getMediaByRoleOp, getMediaBySourceUrlOp, getMediaByTypeOp, getMediaCountOp, getMediaCountsByTypeOp, getMediaOp, getMediaTypeFromMime, getMemoriesNeedingTopicExtractionOp, getMessageOp, getMessagesOp, getModelPreferenceOp, getProjectConversationCountOp, getProjectConversationsOp, getProjectOp, getProjectsOp, getRecentMediaOp, getServerTools, getSupportedFileTypes, getToolsChecksum, getUnfiledVaultMemoriesOp, getUserPreferenceOp, getUserUploadedMediaOp, getVaultMemoryOp, getVideosOp, hardDeleteDecayedOp, hardDeleteMediaOp, hasEncryptionKey, hasKeyPair, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isRerankerAvailable, isSupportedFile, isSupportedMediaType, makeSyntheticStoredConversation, makeSyntheticStoredMessage, maybeSummarizeHistory, mediaToStored, migrateFromModelPreferencesOp, onKeyAvailable, parseMedia, preEmbedVaultMemories, preprocessFiles, progressiveSummarize, projectToStored, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, relinkMemoryTopicsOp, relinkMisclassifiedVideosOp, renderTemplate, requestEncryptionKey, requestKeyPair, restoreVaultMemoryOp, resumeStream, retain, runToolLoop, sanitizeQuotes, schemaToCreateSQL, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchChunksOp, searchMediaOp, searchMessagesOp, searchVaultMemories, seedEncryptionKeys, selectServerToolsForPrompt, serverPlatformStorage, setMemoryVisibilityOp, setModelPreferenceOp, setUserPreferenceOp, shouldAnalyzeStyle, shouldChunkMessage, shouldRefreshTools, splitMessagesAtThreshold, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, summaryToSystemMessage, supersedeVaultMemoryOp, synthesizeProfile, toolSetSystemPrompts, traverseGraphLane, ttlForType, updateConversationProjectOp, updateConversationTitleOp, updateMediaMessageIdBatchOp, updateMediaOp, updateMessageChunksOp, updateMessageEmbeddingOp, updateMessageErrorOp, updateMessageFeedbackOp, updateModelsOp, updatePersonalityOp, updateProfileOp, updateProjectNameOp, updateProjectOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertConversationSummaryOp, upsertMessageOp, verifyMemoriesForPublish };
+export { type AnalyzeStyleOptions, type AnalyzeStyleResult, type ApiResponse, type ApiType, type AutoExecutedToolResult, type AutoExtractMessage, type AutoExtractor, type Budget, type BuildPromptOptions, type BuildPromptResult, type CachedChunkVectors, type CachedServerTools, type ChatCompletionUsage, type ChatRole, type ChunkSearchResult, type ChunkVectorCache, type ChunkingOptions, type ConnectorGuidance, type ConnectorGuidanceInput, type ConsolidationAction, type ConsolidationFallbackReason, Conversation, ConversationSummary, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMediaOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateProjectOptions, type CreateUserPreferenceOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_ANALYSIS_PROMPT, DEFAULT_ANALYZE_AFTER_MESSAGES, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_DOCUMENT_PATTERN, DEFAULT_EXCLUDED_SERVER_TOOLS, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MAX_INPUT_MESSAGES, DEFAULT_MAX_PROFILE_LENGTH, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_MIN_MESSAGES, DEFAULT_PERSONALITY_SETTINGS, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_PROMPT_TEMPLATES, DEFAULT_REFRESH_EVERY_MESSAGES, DEFAULT_SERVER_TOOLS_MATCH_OPTIONS, DEFAULT_SUMMARY_MIN_WINDOW_MESSAGES, DEFAULT_SUMMARY_MODEL, DEFAULT_SUMMARY_TOKEN_THRESHOLD, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, ExcelProcessor, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type ExtractionFunnel, type ExtractionTimings, type FactType, type FileMetadata, type FileProcessor, type FileTypeQuery, type FileWithData, type FlushResult, type GetConversationsPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type LlmTokenUsage, MAX_HOPS, MAX_MESSAGES_PER_SUMMARIZATION, MEDIUM_TTL_MS, Media, type MediaDimensions, type MediaFilterOptions, type MediaMetadata, type MediaOperationsContext, type MediaRole, type MediaType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, Message, type MessageChunk, type MessageFeedback, type MessageOrigin, type ModelCallEndEvent, type ModelCallStartEvent, ModelPreference, NEVER_TTL_MS, NODE_BUDGET, type NeighborRefiner, type NowSource, type ObservationTrend, type ObservationTrendInput, type OperationExecutor, PAST_EVENT_GRACE_MS, PROFILE_DOC_VERSION, type ParsedServerToolsResponse, PdfProcessor, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type PgClientLike, type PgPoolLike, type PhotoIngestResult, type PhotoMediaRef, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, PostgreSQLAdapter, type PostgreSQLAdapterOptions, type PreprocessingOptions, type PreprocessingResult, type ProcessedFileResult, ProcessorRegistry, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type ProfileUpdate, Project, type ProjectOperationsContext, type PromptContext, type PromptPreProcessor, type PromptPreProcessorContext, type PromptSection, type PromptTemplates, type PublishedPhotoMemory, type QuarantinedMemoryInfo, type QueueEncryptionContext, QueueManager, type QueueStatus, type QueuedOperation, type QueuedOperationType, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, type RunEndEvent, type RunErrorEvent, type RunHooks, type RunStartEvent, type RunTerminalState, type RunToolLoopOptions, type RunToolLoopResult, SDK_SCHEMA_VERSION, SERVER_TOOL_DEPENDENCY_SETS, SHORT_TTL_MS, SLIDER_CONFIG, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SelectServerToolsForPromptOptions, type ServerTool, type ServerToolCallEvent, type ServerToolsFilterFunction, type ServerToolsOptions, type ServerToolsResponse, type SettingsStorageOperationsContext, type SignMessageFn, type StepFinishEvent, type StockPriceClassification, type StockPricePreProcessorOptions, type StorageOperationsContext, type StoredConversation, type StoredConversationSummary, type StoredFileWithContext, type StoredMedia, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, type StoredProject, type StoredUserPreference, type StoredVaultMemory, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type StreamSmoothingConfig, type StreamingTransport, type StreamingTransportOptions, type StreamingTransportResult, type StyleAnalysisSchedule, type SynthesizeProfileOptions, TOOL_CATALOG, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, TextProcessor, type ToolConfig, type ToolExecutor, type ToolMatchOptions, type ToolMatchResult, type ToolSet, type ToolUseEndEvent, type ToolUseStartEvent, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateMediaOptions, type UpdateModelPreferenceOptions, type UpdateProjectOptions, type UpdateUserPreferenceOptions, type UpdateVaultMemoryOptions, UserPreference, type UserPreferencesStorageOperationsContext, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, VaultMemory, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, WordProcessor, ZipProcessor, type ZipProcessorOptions, activatedToolSetNames, analyzeStyle, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildConnectorGuidance, buildDeniedToolsRider, buildSystemPrompt, capHopsForDensity, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, cleanupConversationSummary, clearAllEncryptionKeys, clearAllEncryptionState, clearAllKeyPairs, clearEncryptionKey, clearKeyPair, clearLazyTitleCache, clearMessagesOp, clearServerToolsCache, composeHooks, createAutoExtractor, createChunkVectorCache, createConversationOp, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMediaBatchOp, createMediaOp, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageOp, createMessageSourceResolver, createPlatformCursorStore, createProjectOp, createRecallTool, createServerToolsFilter, createStockPricePreProcessor, createSummaryContext, createVaultEmbeddingCache, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, decryptData, decryptDataBatch, decryptDataBytes, decryptDataBytesFromBytes, decryptDataWithKey, defaultServerToolsFilter, deleteAllVaultMemoriesForUserOp, deleteConversationOp, deleteConversationSummaryOp, deleteMediaByConversationOp, deleteMediaByMessageOp, deleteMediaOp, deleteModelPreferenceOp, deleteProjectOp, deleteUserPreferenceOp, deleteVaultMemoryOp, eagerEmbedContent, embedAllMessages, embedMessage, encryptData, encryptDataBatch, encryptDataBytes, encryptDataWithKey, estimateMessagesTokens, estimateTokens, exportPublicKey, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, findMatchingTools, generateConversationId, generateEmbedding, generateEmbeddings, generateMediaId, generateProjectId, getAIGeneratedMediaOp, getAllFilesOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getAudioOp, getCachedServerTools, getConversationOp, getConversationSummaryOp, getConversationsByProjectLazyOp, getConversationsByProjectOp, getConversationsLazyOp, getConversationsOp, getConversationsPageOp, getDecayCandidatesRawOp, getDocumentsOp, getEncryptionKey, getImagesOp, getMediaByConversationOp, getMediaByIdOp, getMediaByIdsOp, getMediaByMessageOp, getMediaByModelOp, getMediaByRoleOp, getMediaBySourceUrlOp, getMediaByTypeOp, getMediaCountOp, getMediaCountsByTypeOp, getMediaOp, getMediaTypeFromMime, getMemoriesNeedingTopicExtractionOp, getMessageOp, getMessagesOp, getModelPreferenceOp, getProjectConversationCountOp, getProjectConversationsOp, getProjectOp, getProjectsOp, getRecentMediaOp, getServerTools, getSupportedFileTypes, getToolsChecksum, getUnfiledVaultMemoriesOp, getUserPreferenceOp, getUserUploadedMediaOp, getVaultMemoryOp, getVideosOp, hardDeleteDecayedOp, hardDeleteMediaOp, hasEncryptionKey, hasKeyPair, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isRerankerAvailable, isSupportedFile, isSupportedMediaType, makeSyntheticStoredConversation, makeSyntheticStoredMessage, maybeSummarizeHistory, mediaToStored, migrateFromModelPreferencesOp, onKeyAvailable, parseMedia, preEmbedVaultMemories, preprocessFiles, progressiveSummarize, projectToStored, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, relinkMemoryTopicsOp, relinkMisclassifiedVideosOp, renderTemplate, requestEncryptionKey, requestKeyPair, restoreVaultMemoryOp, resumeStream, retain, runToolLoop, sanitizeQuotes, schemaToCreateSQL, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchChunksOp, searchMediaOp, searchMessagesOp, searchVaultMemories, seedEncryptionKeys, selectServerToolsForPrompt, serverPlatformStorage, setMemoryVisibilityOp, setModelPreferenceOp, setUserPreferenceOp, shouldAnalyzeStyle, shouldChunkMessage, shouldRefreshTools, splitMessagesAtThreshold, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, summaryToSystemMessage, supersedeVaultMemoryOp, synthesizeProfile, toolSetSystemPrompts, traverseGraphLane, ttlForType, updateConversationProjectOp, updateConversationTitleOp, updateMediaMessageIdBatchOp, updateMediaOp, updateMessageChunksOp, updateMessageEmbeddingOp, updateMessageErrorOp, updateMessageFeedbackOp, updateModelsOp, updatePersonalityOp, updateProfileOp, updateProjectNameOp, updateProjectOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertConversationSummaryOp, upsertMessageOp, verifyMemoriesForPublish };

package/dist/server/index.d.ts

@@ -5795,6 +5795,15 @@ interface RecallDiagnostics {
     degraded: RecallDegradation[];
 }
 type RetainAction = "create" | "merge" | "update" | "skip" | "suppressed" | "supersede";
+/**
+ * The consolidation LLM's decision for a candidate, when it made one. Reported
+ * on {@link RetainResult.consolidation} so a host can tell an LLM `noop` (the
+ * fact already exists) from a cosine auto-merge — both arrive as
+ * `action: "merge"` — and can read how often the model reaches for `supersede`
+ * or `update` versus `create`. A degraded fallback create (LLM error, bad
+ * response) carries no decision; `onFallback` reports those.
+ */
+type ConsolidationAction = "create" | "update" | "noop" | "supersede";
 type RetainSource = "manual" | "auto-extracted" | "capsule";
 /**
  * Why a retain returned "create" instead of applying a consolidation decision.
@@ -5934,6 +5943,33 @@ interface RetainResult {
     tombstoneId?: string;
     /** Updated proof_count after this write. 0 when nothing was written (suppressed). */
     proofCount: number;
+    /**
+     * How close the write was to the threshold that allowed it. Absent on the
+     * actions that have no such score (`create`, `update`, `supersede`, `skip`).
+     *
+     * The two paths report DIFFERENT things and a dashboard has to know which:
+     *
+     * - `suppressed` — an exact cosine against the tombstone, computed in
+     *   `findTombstoneMatch`.
+     * - `merge` — the RANKER's score for the target, not a pure cosine. The
+     *   cosine is what cleared `minSimilarity`, but the supersession pass may
+     *   then adjust it (`oldScore - delta` / `newScore + delta`) before this
+     *   value is read, and can in principle reorder the winner. Read it as
+     *   "the score the merge was chosen on", within the supersession delta of
+     *   the cosine — not as the raw pairwise similarity.
+     */
+    similarity?: number;
+    /**
+     * What the consolidation LLM decided for this candidate, when consolidation
+     * ran — see {@link ConsolidationAction}.
+     *
+     * Reported for the DECISION, not for what the write ended up doing, so the
+     * two can disagree and be read as such: a `merge` carrying
+     * `consolidation: "create"` is the model saying "new fact" and the strict
+     * cosine stage merging anyway. Absent when consolidation did not run, and
+     * absent on a degraded fallback create (`onFallback` owns that signal).
+     */
+    consolidation?: ConsolidationAction;
 }
 
 /**
@@ -6160,6 +6196,61 @@ interface ExtractFactsOptions extends PortalLlmAuth {
      * callers may leave it unset.
      */
     onAttempt?: (attempt: PortalLlmAttempt) => void;
+    /**
+     * Fired once per successful completion with how many candidates the model
+     * emitted (`rawCount`) and how many survived {@link validateCandidates}
+     * (`validCount`) — the non-string / empty / over-cap / low-signal / bad-
+     * confidence drops that until now were a bare `continue` nobody counted.
+     *
+     * Without it a `no-facts` turn cannot be split into "the model found nothing"
+     * and "the model found things we threw away", which is the difference between
+     * a prompt problem and a validator problem. Counts only; never content.
+     */
+    onCandidatesParsed?: (stats: {
+        rawCount: number;
+        validCount: number;
+    }) => void;
+}
+/**
+ * Where a turn's candidates went between the model's completion and the vault —
+ * every stage that can drop one, as a count. Returned by {@link extractAndRetain}
+ * and forwarded on `TurnCompleteEvent` so a host can emit it; nothing here is
+ * content.
+ *
+ * Reads as a funnel: `raw ≥ valid ≥ afterRedaction ≥ aboveConfidence`, then
+ * `aboveConfidence = quarantined + retained + failed`.
+ * @public
+ */
+interface ExtractionFunnel {
+    /** Candidates in the model's completion, before any validation. */
+    rawCandidateCount: number;
+    /** Survivors of {@link validateCandidates} (shape, length, low-signal, confidence-is-a-number). */
+    validCandidateCount: number;
+    /** Survivors of PII de-anonymization (equals `validCandidateCount` when redaction is off). */
+    afterRedactionCount: number;
+    /** Survivors of the `minConfidence` floor — the candidates that reached the injection screen. */
+    aboveConfidenceCount: number;
+    /**
+     * Held for review by the injection screen and SUCCESSFULLY persisted — the
+     * same set as `extractAndRetain`'s `quarantined`. A screened candidate whose
+     * `retain()` threw is in `failedCount` instead, never both.
+     */
+    quarantinedCount: number;
+    /** Written through `retain()` (any disposition). */
+    retainedCount: number;
+    /** `retain()` threw. */
+    failedCount: number;
+}
+/**
+ * Wall-clock split of one {@link extractAndRetain} call. The worker's
+ * `durationMs` is the sum plus the screen; these say which half is slow.
+ * @public
+ */
+interface ExtractionTimings {
+    /** The extraction LLM call, all attempts and backoff included. */
+    extractMs: number;
+    /** The retain loop — embeddings, consolidation LLM calls, writes — over every candidate. */
+    retainMs: number;
 }
 /**
  * Stage 1 — call the LLM to extract candidate facts from the recent
@@ -6277,6 +6368,12 @@ declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: Ret
      * the give-up, so "extraction is failing" can be reported as *why* it failed.
      */
     failure?: PortalLlmFailure;
+    /** Where the candidates went, stage by stage — see {@link ExtractionFunnel}. */
+    funnel: ExtractionFunnel;
+    /** Extract vs. retain wall-clock — see {@link ExtractionTimings}. */
+    timings: ExtractionTimings;
+    /** The extraction model this call asked for (the resolved default when unset). */
+    model: string;
 }>;
 
 /**
@@ -8072,6 +8169,16 @@ interface TurnCompleteEvent {
      * carries content.
      */
     failure?: PortalLlmFailure;
+    /**
+     * Where the candidates went between the model and the vault, as counts — the
+     * drops before `retain()` that `candidates`/`results` cannot show. See
+     * {@link ExtractionFunnel}.
+     */
+    funnel?: ExtractionFunnel;
+    /** Extract vs. retain wall-clock split of `durationMs`. See {@link ExtractionTimings}. */
+    timings?: ExtractionTimings;
+    /** The extraction model this turn asked for. */
+    model?: string;
 }
 /** @public */
 /**
@@ -10734,4 +10841,4 @@ declare function sanitizeQuotes(s: string): string;
 declare function renderTemplate(value: string | null | undefined, template: string): string | null;
 declare function buildSystemPrompt(ctx: PromptContext, options?: BuildPromptOptions): BuildPromptResult;
 
-export { type AnalyzeStyleOptions, type AnalyzeStyleResult, type ApiResponse, type ApiType, type AutoExecutedToolResult, type AutoExtractMessage, type AutoExtractor, type Budget, type BuildPromptOptions, type BuildPromptResult, type CachedChunkVectors, type CachedServerTools, type ChatCompletionUsage, type ChatRole, type ChunkSearchResult, type ChunkVectorCache, type ChunkingOptions, type ConnectorGuidance, type ConnectorGuidanceInput, type ConsolidationFallbackReason, Conversation, ConversationSummary, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMediaOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateProjectOptions, type CreateUserPreferenceOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_ANALYSIS_PROMPT, DEFAULT_ANALYZE_AFTER_MESSAGES, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_DOCUMENT_PATTERN, DEFAULT_EXCLUDED_SERVER_TOOLS, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MAX_INPUT_MESSAGES, DEFAULT_MAX_PROFILE_LENGTH, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_MIN_MESSAGES, DEFAULT_PERSONALITY_SETTINGS, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_PROMPT_TEMPLATES, DEFAULT_REFRESH_EVERY_MESSAGES, DEFAULT_SERVER_TOOLS_MATCH_OPTIONS, DEFAULT_SUMMARY_MIN_WINDOW_MESSAGES, DEFAULT_SUMMARY_MODEL, DEFAULT_SUMMARY_TOKEN_THRESHOLD, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, ExcelProcessor, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FileProcessor, type FileTypeQuery, type FileWithData, type FlushResult, type GetConversationsPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type LlmTokenUsage, MAX_HOPS, MAX_MESSAGES_PER_SUMMARIZATION, MEDIUM_TTL_MS, Media, type MediaDimensions, type MediaFilterOptions, type MediaMetadata, type MediaOperationsContext, type MediaRole, type MediaType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, Message, type MessageChunk, type MessageFeedback, type MessageOrigin, type ModelCallEndEvent, type ModelCallStartEvent, ModelPreference, NEVER_TTL_MS, NODE_BUDGET, type NeighborRefiner, type NowSource, type ObservationTrend, type ObservationTrendInput, type OperationExecutor, PAST_EVENT_GRACE_MS, PROFILE_DOC_VERSION, type ParsedServerToolsResponse, PdfProcessor, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type PgClientLike, type PgPoolLike, type PhotoIngestResult, type PhotoMediaRef, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, PostgreSQLAdapter, type PostgreSQLAdapterOptions, type PreprocessingOptions, type PreprocessingResult, type ProcessedFileResult, ProcessorRegistry, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type ProfileUpdate, Project, type ProjectOperationsContext, type PromptContext, type PromptPreProcessor, type PromptPreProcessorContext, type PromptSection, type PromptTemplates, type PublishedPhotoMemory, type QuarantinedMemoryInfo, type QueueEncryptionContext, QueueManager, type QueueStatus, type QueuedOperation, type QueuedOperationType, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, type RunEndEvent, type RunErrorEvent, type RunHooks, type RunStartEvent, type RunTerminalState, type RunToolLoopOptions, type RunToolLoopResult, SDK_SCHEMA_VERSION, SERVER_TOOL_DEPENDENCY_SETS, SHORT_TTL_MS, SLIDER_CONFIG, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SelectServerToolsForPromptOptions, type ServerTool, type ServerToolCallEvent, type ServerToolsFilterFunction, type ServerToolsOptions, type ServerToolsResponse, type SettingsStorageOperationsContext, type SignMessageFn, type StepFinishEvent, type StockPriceClassification, type StockPricePreProcessorOptions, type StorageOperationsContext, type StoredConversation, type StoredConversationSummary, type StoredFileWithContext, type StoredMedia, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, type StoredProject, type StoredUserPreference, type StoredVaultMemory, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type StreamSmoothingConfig, type StreamingTransport, type StreamingTransportOptions, type StreamingTransportResult, type StyleAnalysisSchedule, type SynthesizeProfileOptions, TOOL_CATALOG, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, TextProcessor, type ToolConfig, type ToolExecutor, type ToolMatchOptions, type ToolMatchResult, type ToolSet, type ToolUseEndEvent, type ToolUseStartEvent, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateMediaOptions, type UpdateModelPreferenceOptions, type UpdateProjectOptions, type UpdateUserPreferenceOptions, type UpdateVaultMemoryOptions, UserPreference, type UserPreferencesStorageOperationsContext, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, VaultMemory, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, WordProcessor, ZipProcessor, type ZipProcessorOptions, activatedToolSetNames, analyzeStyle, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildConnectorGuidance, buildDeniedToolsRider, buildSystemPrompt, capHopsForDensity, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, cleanupConversationSummary, clearAllEncryptionKeys, clearAllEncryptionState, clearAllKeyPairs, clearEncryptionKey, clearKeyPair, clearLazyTitleCache, clearMessagesOp, clearServerToolsCache, composeHooks, createAutoExtractor, createChunkVectorCache, createConversationOp, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMediaBatchOp, createMediaOp, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageOp, createMessageSourceResolver, createPlatformCursorStore, createProjectOp, createRecallTool, createServerToolsFilter, createStockPricePreProcessor, createSummaryContext, createVaultEmbeddingCache, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, decryptData, decryptDataBatch, decryptDataBytes, decryptDataBytesFromBytes, decryptDataWithKey, defaultServerToolsFilter, deleteAllVaultMemoriesForUserOp, deleteConversationOp, deleteConversationSummaryOp, deleteMediaByConversationOp, deleteMediaByMessageOp, deleteMediaOp, deleteModelPreferenceOp, deleteProjectOp, deleteUserPreferenceOp, deleteVaultMemoryOp, eagerEmbedContent, embedAllMessages, embedMessage, encryptData, encryptDataBatch, encryptDataBytes, encryptDataWithKey, estimateMessagesTokens, estimateTokens, exportPublicKey, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, findMatchingTools, generateConversationId, generateEmbedding, generateEmbeddings, generateMediaId, generateProjectId, getAIGeneratedMediaOp, getAllFilesOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getAudioOp, getCachedServerTools, getConversationOp, getConversationSummaryOp, getConversationsByProjectLazyOp, getConversationsByProjectOp, getConversationsLazyOp, getConversationsOp, getConversationsPageOp, getDecayCandidatesRawOp, getDocumentsOp, getEncryptionKey, getImagesOp, getMediaByConversationOp, getMediaByIdOp, getMediaByIdsOp, getMediaByMessageOp, getMediaByModelOp, getMediaByRoleOp, getMediaBySourceUrlOp, getMediaByTypeOp, getMediaCountOp, getMediaCountsByTypeOp, getMediaOp, getMediaTypeFromMime, getMemoriesNeedingTopicExtractionOp, getMessageOp, getMessagesOp, getModelPreferenceOp, getProjectConversationCountOp, getProjectConversationsOp, getProjectOp, getProjectsOp, getRecentMediaOp, getServerTools, getSupportedFileTypes, getToolsChecksum, getUnfiledVaultMemoriesOp, getUserPreferenceOp, getUserUploadedMediaOp, getVaultMemoryOp, getVideosOp, hardDeleteDecayedOp, hardDeleteMediaOp, hasEncryptionKey, hasKeyPair, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isRerankerAvailable, isSupportedFile, isSupportedMediaType, makeSyntheticStoredConversation, makeSyntheticStoredMessage, maybeSummarizeHistory, mediaToStored, migrateFromModelPreferencesOp, onKeyAvailable, parseMedia, preEmbedVaultMemories, preprocessFiles, progressiveSummarize, projectToStored, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, relinkMemoryTopicsOp, relinkMisclassifiedVideosOp, renderTemplate, requestEncryptionKey, requestKeyPair, restoreVaultMemoryOp, resumeStream, retain, runToolLoop, sanitizeQuotes, schemaToCreateSQL, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchChunksOp, searchMediaOp, searchMessagesOp, searchVaultMemories, seedEncryptionKeys, selectServerToolsForPrompt, serverPlatformStorage, setMemoryVisibilityOp, setModelPreferenceOp, setUserPreferenceOp, shouldAnalyzeStyle, shouldChunkMessage, shouldRefreshTools, splitMessagesAtThreshold, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, summaryToSystemMessage, supersedeVaultMemoryOp, synthesizeProfile, toolSetSystemPrompts, traverseGraphLane, ttlForType, updateConversationProjectOp, updateConversationTitleOp, updateMediaMessageIdBatchOp, updateMediaOp, updateMessageChunksOp, updateMessageEmbeddingOp, updateMessageErrorOp, updateMessageFeedbackOp, updateModelsOp, updatePersonalityOp, updateProfileOp, updateProjectNameOp, updateProjectOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertConversationSummaryOp, upsertMessageOp, verifyMemoriesForPublish };
+export { type AnalyzeStyleOptions, type AnalyzeStyleResult, type ApiResponse, type ApiType, type AutoExecutedToolResult, type AutoExtractMessage, type AutoExtractor, type Budget, type BuildPromptOptions, type BuildPromptResult, type CachedChunkVectors, type CachedServerTools, type ChatCompletionUsage, type ChatRole, type ChunkSearchResult, type ChunkVectorCache, type ChunkingOptions, type ConnectorGuidance, type ConnectorGuidanceInput, type ConsolidationAction, type ConsolidationFallbackReason, Conversation, ConversationSummary, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateDecaySweeperOptions, type CreateMediaOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, type CreateProjectOptions, type CreateUserPreferenceOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_ANALYSIS_PROMPT, DEFAULT_ANALYZE_AFTER_MESSAGES, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_DECAY_POLICY, DEFAULT_DOCUMENT_PATTERN, DEFAULT_EXCLUDED_SERVER_TOOLS, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MAX_INPUT_MESSAGES, DEFAULT_MAX_PROFILE_LENGTH, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_MIN_MESSAGES, DEFAULT_PERSONALITY_SETTINGS, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_PROMPT_TEMPLATES, DEFAULT_REFRESH_EVERY_MESSAGES, DEFAULT_SERVER_TOOLS_MATCH_OPTIONS, DEFAULT_SUMMARY_MIN_WINDOW_MESSAGES, DEFAULT_SUMMARY_MODEL, DEFAULT_SUMMARY_TOKEN_THRESHOLD, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, ExcelProcessor, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type ExtractionFunnel, type ExtractionTimings, type FactType, type FileMetadata, type FileProcessor, type FileTypeQuery, type FileWithData, type FlushResult, type GetConversationsPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type LlmTokenUsage, MAX_HOPS, MAX_MESSAGES_PER_SUMMARIZATION, MEDIUM_TTL_MS, Media, type MediaDimensions, type MediaFilterOptions, type MediaMetadata, type MediaOperationsContext, type MediaRole, type MediaType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, Message, type MessageChunk, type MessageFeedback, type MessageOrigin, type ModelCallEndEvent, type ModelCallStartEvent, ModelPreference, NEVER_TTL_MS, NODE_BUDGET, type NeighborRefiner, type NowSource, type ObservationTrend, type ObservationTrendInput, type OperationExecutor, PAST_EVENT_GRACE_MS, PROFILE_DOC_VERSION, type ParsedServerToolsResponse, PdfProcessor, type PersonalitySettings, type PersonalitySliders, type PersonalityStyle, type PgClientLike, type PgPoolLike, type PhotoIngestResult, type PhotoMediaRef, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, PostgreSQLAdapter, type PostgreSQLAdapterOptions, type PreprocessingOptions, type PreprocessingResult, type ProcessedFileResult, ProcessorRegistry, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type ProfileUpdate, Project, type ProjectOperationsContext, type PromptContext, type PromptPreProcessor, type PromptPreProcessorContext, type PromptSection, type PromptTemplates, type PublishedPhotoMemory, type QuarantinedMemoryInfo, type QueueEncryptionContext, QueueManager, type QueueStatus, type QueuedOperation, type QueuedOperationType, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, type RunEndEvent, type RunErrorEvent, type RunHooks, type RunStartEvent, type RunTerminalState, type RunToolLoopOptions, type RunToolLoopResult, SDK_SCHEMA_VERSION, SERVER_TOOL_DEPENDENCY_SETS, SHORT_TTL_MS, SLIDER_CONFIG, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, type SearchSource, type SelectServerToolsForPromptOptions, type ServerTool, type ServerToolCallEvent, type ServerToolsFilterFunction, type ServerToolsOptions, type ServerToolsResponse, type SettingsStorageOperationsContext, type SignMessageFn, type StepFinishEvent, type StockPriceClassification, type StockPricePreProcessorOptions, type StorageOperationsContext, type StoredConversation, type StoredConversationSummary, type StoredFileWithContext, type StoredMedia, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, type StoredProject, type StoredUserPreference, type StoredVaultMemory, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, type StreamSmoothingConfig, type StreamingTransport, type StreamingTransportOptions, type StreamingTransportResult, type StyleAnalysisSchedule, type SynthesizeProfileOptions, TOOL_CATALOG, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, TextProcessor, type ToolConfig, type ToolExecutor, type ToolMatchOptions, type ToolMatchResult, type ToolSet, type ToolUseEndEvent, type ToolUseStartEvent, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateMediaOptions, type UpdateModelPreferenceOptions, type UpdateProjectOptions, type UpdateUserPreferenceOptions, type UpdateVaultMemoryOptions, UserPreference, type UserPreferencesStorageOperationsContext, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, VaultMemory, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, WordProcessor, ZipProcessor, type ZipProcessorOptions, activatedToolSetNames, analyzeStyle, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildConnectorGuidance, buildDeniedToolsRider, buildSystemPrompt, capHopsForDensity, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, cleanupConversationSummary, clearAllEncryptionKeys, clearAllEncryptionState, clearAllKeyPairs, clearEncryptionKey, clearKeyPair, clearLazyTitleCache, clearMessagesOp, clearServerToolsCache, composeHooks, createAutoExtractor, createChunkVectorCache, createConversationOp, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMediaBatchOp, createMediaOp, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageOp, createMessageSourceResolver, createPlatformCursorStore, createProjectOp, createRecallTool, createServerToolsFilter, createStockPricePreProcessor, createSummaryContext, createVaultEmbeddingCache, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, decryptData, decryptDataBatch, decryptDataBytes, decryptDataBytesFromBytes, decryptDataWithKey, defaultServerToolsFilter, deleteAllVaultMemoriesForUserOp, deleteConversationOp, deleteConversationSummaryOp, deleteMediaByConversationOp, deleteMediaByMessageOp, deleteMediaOp, deleteModelPreferenceOp, deleteProjectOp, deleteUserPreferenceOp, deleteVaultMemoryOp, eagerEmbedContent, embedAllMessages, embedMessage, encryptData, encryptDataBatch, encryptDataBytes, encryptDataWithKey, estimateMessagesTokens, estimateTokens, exportPublicKey, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, findMatchingTools, generateConversationId, generateEmbedding, generateEmbeddings, generateMediaId, generateProjectId, getAIGeneratedMediaOp, getAllFilesOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getAudioOp, getCachedServerTools, getConversationOp, getConversationSummaryOp, getConversationsByProjectLazyOp, getConversationsByProjectOp, getConversationsLazyOp, getConversationsOp, getConversationsPageOp, getDecayCandidatesRawOp, getDocumentsOp, getEncryptionKey, getImagesOp, getMediaByConversationOp, getMediaByIdOp, getMediaByIdsOp, getMediaByMessageOp, getMediaByModelOp, getMediaByRoleOp, getMediaBySourceUrlOp, getMediaByTypeOp, getMediaCountOp, getMediaCountsByTypeOp, getMediaOp, getMediaTypeFromMime, getMemoriesNeedingTopicExtractionOp, getMessageOp, getMessagesOp, getModelPreferenceOp, getProjectConversationCountOp, getProjectConversationsOp, getProjectOp, getProjectsOp, getRecentMediaOp, getServerTools, getSupportedFileTypes, getToolsChecksum, getUnfiledVaultMemoriesOp, getUserPreferenceOp, getUserUploadedMediaOp, getVaultMemoryOp, getVideosOp, hardDeleteDecayedOp, hardDeleteMediaOp, hasEncryptionKey, hasKeyPair, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isRerankerAvailable, isSupportedFile, isSupportedMediaType, makeSyntheticStoredConversation, makeSyntheticStoredMessage, maybeSummarizeHistory, mediaToStored, migrateFromModelPreferencesOp, onKeyAvailable, parseMedia, preEmbedVaultMemories, preprocessFiles, progressiveSummarize, projectToStored, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, relinkMemoryTopicsOp, relinkMisclassifiedVideosOp, renderTemplate, requestEncryptionKey, requestKeyPair, restoreVaultMemoryOp, resumeStream, retain, runToolLoop, sanitizeQuotes, schemaToCreateSQL, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchChunksOp, searchMediaOp, searchMessagesOp, searchVaultMemories, seedEncryptionKeys, selectServerToolsForPrompt, serverPlatformStorage, setMemoryVisibilityOp, setModelPreferenceOp, setUserPreferenceOp, shouldAnalyzeStyle, shouldChunkMessage, shouldRefreshTools, splitMessagesAtThreshold, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, summaryToSystemMessage, supersedeVaultMemoryOp, synthesizeProfile, toolSetSystemPrompts, traverseGraphLane, ttlForType, updateConversationProjectOp, updateConversationTitleOp, updateMediaMessageIdBatchOp, updateMediaOp, updateMessageChunksOp, updateMessageEmbeddingOp, updateMessageErrorOp, updateMessageFeedbackOp, updateModelsOp, updatePersonalityOp, updateProfileOp, updateProjectNameOp, updateProjectOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertConversationSummaryOp, upsertMessageOp, verifyMemoriesForPublish };

package/dist/server/index.mjs

@@ -5496,6 +5496,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) {
@@ -5523,8 +5524,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) {
@@ -5574,7 +5579,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);
@@ -5587,12 +5599,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 = {
@@ -5659,7 +5677,8 @@ async function retain(content, ctx, options = {}) {
         action: "supersede",
         memoryId: created2.uniqueId,
         targetId: primaryTargetId,
-        proofCount: 1
+        proofCount: 1,
+        consolidation: "supersede"
       };
     }
     notifyConsolidationFallback(
@@ -5673,7 +5692,8 @@ async function retain(content, ctx, options = {}) {
   return {
     action: "create",
     memoryId: created.uniqueId,
-    proofCount: 1
+    proofCount: 1,
+    ...consolidationDecidedCreate && { consolidation: "create" }
   };
 }
 function unionStrings(a, b) {
@@ -5703,7 +5723,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;
@@ -5745,7 +5765,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
   }));
   const { consolidateMemory: doConsolidate } = await import("./consolidate-54P6QZKU.mjs");
   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;
@@ -5804,7 +5824,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"
       }
     };
   }
@@ -5857,7 +5878,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"
       }
     };
   }
@@ -5999,6 +6021,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) {
@@ -6035,8 +6062,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) => {
@@ -6047,8 +6078,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);
@@ -6096,6 +6133,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, {
@@ -6162,6 +6200,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.
@@ -6415,27 +6468,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;
@@ -6456,6 +6505,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.

package/package.json

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