@snoai/memory 0.0.0-stage → 1.0.1

package/dist/retriever-Dxss5fRv.d.ts

@@ -0,0 +1,469 @@
+import { h as MemoryCategory, l as DecayScore, r as AggregationQuery, u as DecayableMemory, x as RetrievalResult, y as MemorySearchResult } from "./types-CWdhXLxr.js";
+import { sn as RecallLifecycleConfig } from "./index-DL8AVj0Z.js";
+import { t as Embedder } from "./embedding-provider-client-vynZMuit.js";
+import "./trace-C1JxMfs-.js";
+import "./memory-metadata-codec-DUvsYe_X.js";
+import { K as RemFacetPolicy } from "./index-BO4RU_mc.js";
+import { C as MemoryStore } from "./memory-store-base-CQ_bHlYA.js";
+import "./store-C8sUTssE.js";
+import { n as AccessTracker } from "./access-tracker-BbEvEocb.js";
+import { r as TierPromoter } from "./memory-tier-promoter-CqGxCkue.js";
+import "@snoai/utils/logger";
+//#region src/engine/retrieval/retrieval-trace.d.ts
+/** @file retrieval-trace.ts
+ * @purpose Captures per-query retrieval trace details for debugging ranking decisions.
+ * @boundary Candidate scoring, filters, and retriever observability.
+ * @see retriever.ts, retrieval-stats.ts, store.ts.
+ */
+/**
+ * Retrieval Trace — Observable pipeline diagnostics
+ *
+ * Tracks entry IDs through each retrieval stage, computes drops,
+ * score ranges, and timing. Zero overhead when not used.
+ */
+/**
+ * Per-stage structured annotations. Keyed strings only — must survive
+ * JSON serialization and downstream aggregation. Used today for the
+ * rerank fallback reason; not a freeform diagnostic bag.
+ */
+type RetrievalStageMetadata = Readonly<Record<string, string | number | boolean>>;
+interface RetrievalStageResult {
+  /** Stage name, e.g. "vector_search", "bm25_search", "rrf_fusion" */
+  name: string;
+  /** Number of entries entering this stage */
+  inputCount: number;
+  /** Number of entries surviving this stage */
+  outputCount: number;
+  /** IDs that were present in input but not in output */
+  droppedIds: string[];
+  /**
+   * IDs that survived this stage, in the order the stage passed them on.
+   *
+   * `droppedIds` alone cannot place a memory at a stage it never entered, so a stage record
+   * fabricated by copying the final served ids backward reads as valid. This is the field
+   * that makes such a record fail.
+   */
+  outputIds: string[];
+  /** [min, max] score range of surviving entries, null if no scores */
+  scoreRange: [number, number] | null;
+  /** Wall-clock duration of this stage in milliseconds */
+  durationMs: number;
+  /** Optional structured stage annotations (e.g. rerank fallback reason). */
+  metadata?: RetrievalStageMetadata;
+}
+interface RetrievalTrace {
+  /** The original search query */
+  query: string;
+  /** Retrieval mode used */
+  mode: "precision-recall" | "vector" | "aggregation";
+  /** Timestamp when retrieval started (epoch ms) */
+  startedAt: number;
+  /** Per-stage results in pipeline order */
+  stages: RetrievalStageResult[];
+  /** Number of results after all stages */
+  finalCount: number;
+  /** Total wall-clock time in milliseconds */
+  totalMs: number;
+  /**
+   * Phase 0 §9 lifecycle event stream. Absent when `recallLifecycle.traceEnabled`
+   * is off so the trace shape stays bit-exact for existing consumers.
+   */
+  lifecycleEvents?: LifecycleTraceEvent[];
+}
+type RetrievalMode = RetrievalTrace["mode"];
+/** Retention scorer output for a single memory at scoring time. */
+interface RetentionScoreEvent {
+  kind: "retention-score-computed";
+  at: number;
+  memoryId: string;
+  tier: string;
+  composite: number;
+  multiplier: number;
+}
+/** Tier-transition evaluation outcome. `to === from` means "no change". */
+interface TierPromotionEvent {
+  kind: "tier-promotion-evaluated";
+  at: number;
+  memoryId: string;
+  from: string;
+  to: string;
+  promoted: boolean;
+}
+/** Access-tracker update event. `skipped` reflects rate-limit / ceiling gates. */
+interface AccessTrackerEvent {
+  kind: "access-tracker-update";
+  at: number;
+  memoryId: string;
+  accessCount: number;
+  skipped: boolean;
+  reason?: "rate-limited" | "ceiling" | "ok";
+}
+type LifecycleTraceEvent = RetentionScoreEvent | TierPromotionEvent | AccessTrackerEvent;
+interface TraceCollectorOptions {
+  /**
+   * Phase 0 §9 toggle — when false (the default) `writeRetentionTrace`,
+   * `writeAccessTrace`, and `writeTierTrace` are no-ops and the finalized
+   * trace omits `lifecycleEvents` entirely (existing format preserved).
+   */
+  lifecycleEnabled?: boolean;
+}
+declare class TraceCollector {
+  private readonly startedAtMs;
+  private readonly startedMonotonicMs;
+  private readonly results;
+  private readonly lifecycle;
+  private readonly lifecycleEnabled;
+  private activeStage;
+  /**
+   * Initializes retrieval tracing collaborators while keeping runtime work in explicit methods.
+   */
+  constructor(options?: TraceCollectorOptions);
+  /**
+   * Begin tracking a pipeline stage.
+   * @param name - Stage identifier (e.g. "vector_search")
+   * @param entryIds - IDs of entries entering this stage
+   */
+  startStage(name: string, entryIds: string[]): void;
+  /**
+   * End the current stage.
+   * @param survivingIds - IDs of entries that survived this stage
+   * @param scores - Optional scores for surviving entries (parallel to survivingIds)
+   * @param metadata - Optional structured annotations attached to this stage
+   */
+  endStage(survivingIds: string[], scores?: number[], metadata?: RetrievalStageMetadata): void;
+  /**
+   * Finalize the trace and produce the complete RetrievalTrace object.
+   */
+  finalize(query: string, mode: RetrievalMode): RetrievalTrace;
+  /** Append a retention-scorer outcome to the lifecycle stream. */
+  writeRetentionTrace(event: Omit<RetentionScoreEvent, "kind" | "at">): void;
+  /** Append an access-tracker update to the lifecycle stream. */
+  writeAccessTrace(event: Omit<AccessTrackerEvent, "kind" | "at">): void;
+  /** Append a tier-promotion evaluation outcome to the lifecycle stream. */
+  writeTierTrace(event: Omit<TierPromotionEvent, "kind" | "at">): void;
+  /** Access collected lifecycle events (read-only). */
+  get lifecycleEvents(): readonly LifecycleTraceEvent[];
+  /**
+   * Produce a human-readable summary of the trace.
+   */
+  summarize(): string;
+  /** Access collected stages (read-only). */
+  get stages(): readonly RetrievalStageResult[];
+  private closeActiveStageAsUnchanged;
+}
+//#endregion
+//#region src/engine/retrieval/retrieval-stats.d.ts
+interface AggregateStats {
+  /** Total number of queries recorded */
+  totalQueries: number;
+  /** Number of queries that returned zero results */
+  zeroResultQueries: number;
+  /** Average latency across all queries (ms) */
+  avgLatencyMs: number;
+  /** 95th percentile latency (ms) */
+  p95LatencyMs: number;
+  /** Average number of results returned */
+  avgResultCount: number;
+  /** Number of queries where reranking was applied */
+  rerankUsed: number;
+  /** Number of queries where noise filter removed results */
+  noiseFiltered: number;
+  /** Query counts broken down by source */
+  queriesBySource: Record<string, number>;
+  /** Stages that drop the most entries across all queries */
+  topDropStages: {
+    name: string;
+    totalDropped: number;
+  }[];
+  /**
+   * Counts of rerank stages that degraded to the pre-rerank ordering,
+   * keyed by the {@link RerankFallbackReason} that fired. Absent reasons
+   * are not enumerated — read consumers should treat a missing key as zero.
+   */
+  rerankFallbacksByReason: Record<string, number>;
+}
+declare class RetrievalStatsCollector {
+  private readonly _records;
+  private readonly _maxRecords;
+  /**
+   * Initializes retrieval telemetry collaborators while keeping runtime work in explicit
+   * methods.
+   */
+  constructor(maxRecords?: number);
+  /**
+   * Record a completed query trace.
+   * @param trace - The finalized retrieval trace
+   * @param source - Query source identifier (e.g. "manual", "auto-recall")
+   */
+  recordQuery(trace: RetrievalTrace, source: string): void;
+  /**
+   * Compute aggregate statistics from all recorded queries.
+   */
+  getStats(): AggregateStats;
+  /**
+   * Reset all collected statistics.
+   */
+  reset(): void;
+  /** Number of recorded queries. */
+  get count(): number;
+}
+//#endregion
+//#region src/engine/retrieval/retrieval-config.d.ts
+type RerankProvider = "jina" | "siliconflow" | "voyage" | "pinecone" | "dashscope" | "tei";
+interface RetrievalConfig {
+  /** Enable the historical recency, decay, and retention score transforms. */
+  temporalWeighting: boolean;
+  /** Diversify only within the request limit, preserving reranked window membership. */
+  mmrWindowOnly: boolean;
+  mode: "precision-recall" | "vector";
+  vectorWeight: number;
+  bm25Weight: number;
+  minScore: number;
+  rerank: "cross-encoder" | "lightweight" | "none";
+  candidatePoolSize: number;
+  recencyHalfLifeDays: number;
+  recencyWeight: number;
+  /** Drop memories past their valid_until timestamp (default OFF) */
+  temporalExpiry: boolean;
+  /** Dynamic memories decay 3× faster in time-decay scoring (default ON) */
+  temporalDecay: boolean;
+  rerankApiKey?: string;
+  rerankModel?: string;
+  rerankTimeoutMs?: number;
+  lengthNormAnchor: number;
+  hardMinScore: number;
+  timeDecayHalfLifeDays: number;
+  /** Weight for fusion score in rerank blend */
+  rerankBlendVector?: number;
+  /** Weight for cross-encoder score in rerank blend */
+  rerankBlendCross?: number;
+  /** Fusion-score weight when rerank="lightweight" (local cosine blend) */
+  lightweightFusionWeight?: number;
+  /** Cosine-score weight when rerank="lightweight" (local cosine blend) */
+  lightweightCosineWeight?: number;
+  /** Base multiplier for importance weighting */
+  importanceWeightBase?: number;
+  /** Minimum multiplier for old entries */
+  timeDecayFloor?: number;
+  /** Relevance vs diversity tradeoff (default: 0.7) */
+  mmrLambda?: number;
+  /** Custom rerank API endpoint URL */
+  rerankEndpoint?: string;
+  /** Rerank provider name */
+  rerankProvider?: RerankProvider | string;
+  /**
+   * Hard cap on how many candidates are sent to the cross-encoder rerank API
+   * in one request. Some rerank deployments (e.g. this repo's Sno TEI
+   * reranker) reject a batch above a fixed size instead of truncating it, so
+   * an unset value here must never silently violate that limit. Candidates
+   * beyond the cap are NOT dropped — they still flow through the standard
+   * `unreturned` preservation-floor path, same as a real reranker choosing
+   * not to return them.
+   */
+  rerankMaxCandidates?: number;
+  /** Scaling factor for access-based reinforcement (0 = disabled, default: 0.5) */
+  reinforcementFactor?: number;
+  /** Hard cap: effective half-life <= baseHalfLife * maxHalfLifeMultiplier (default: 3) */
+  maxHalfLifeMultiplier?: number;
+  /**
+   * Phase 0 retention-loop knobs.
+   * Optional so legacy `RetrievalConfig` literals keep parsing; resolved
+   * default in `DEFAULT_RETRIEVAL_CONFIG` is `DEFAULT_RECALL_LIFECYCLE`
+   * (all booleans `false`), making the new wire sites pass-through.
+   */
+  recallLifecycle?: RecallLifecycleConfig;
+}
+interface RetrievalContext {
+  external_reference?: string;
+  external_reference_visibility?: "public" | "private";
+  query: string;
+  limit: number;
+  minScore?: number;
+  scopeFilter?: string[];
+  category?: MemoryCategory;
+  /**
+   * Refused fallback rows carry the user's own words and are served by default; product
+   * entrypoints pass true, and only an explicit false hides them (owner ruling 2026-09-01,
+   * reversing an earlier default). Omitted low-level/internal reads preserve all rows.
+   */
+  includeRefused?: boolean;
+  signal?: AbortSignal;
+  sessionId?: string;
+  explicitLocale?: string;
+  /** Retrieval source: "manual" for user-triggered, "auto-recall" for system-initiated, "cli" for CLI commands */
+  source?: "manual" | "auto-recall" | "cli";
+  /** Allows the recall tool to use complete-population aggregation routing. */
+  allowAggregation?: boolean;
+  /** Structured predicate and reduction for bounded, query-complete aggregation. */
+  aggregation?: AggregationQuery;
+  /** Selects current chunks only unless a non-user consumer explicitly requests history. */
+  facetPolicy?: RemFacetPolicy;
+  /**
+   * Tombstone exclusion. When set, the store search
+   * drops candidates whose `metadata.invalidated_at <= excludeInvalidatedBefore`.
+   * A superseded fact is obsolete regardless of recall mode (OD-3, FAA binary),
+   * so omitting it on a serving path does not mean "serve everything": both
+   * retriever entrypoints run the context through `withServingValidityDefault`
+   * first. Pass `0` for a deliberate history read.
+   */
+  excludeInvalidatedBefore?: number;
+  includeRetired?: boolean;
+  /**
+   * Drops rows a group-CRUD close retired. Set by the two serving entries in
+   * `rem-consumer-retrieval.ts`; it has to reach the store because the candidate list is cut
+   * to `limit` before anything downstream can filter it.
+   */
+  excludeSuperseded?: boolean;
+}
+/**
+ * The serving-path validity default. This is the one named code
+ * point that supplies it: reading the default here is what makes the
+ * invalidated-row filter a property of the serving path rather than a parameter
+ * every caller has to remember, and the omission is no longer silent.
+ *
+ * An explicit value always wins — including `0`, the deliberate history read,
+ * where the store predicate becomes `invalidated_at > 0` and drops nothing.
+ *
+ * Scope is the retriever, never the store layer: six write-side consumers (dedup,
+ * reflection loops, observability, the REM batch executor) call the store search
+ * APIs directly and legitimately read invalidated rows. Do not move this
+ * down a layer.
+ */
+declare function withServingValidityDefault(context: RetrievalContext): RetrievalContext;
+declare const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig;
+//#endregion
+//#region src/engine/retrieval/retrieval-scoring-utils.d.ts
+declare function collectParallelStage(results: RetrievalResult[], key: "denseScore" | "bm25Score" | "fusedScore" | "rerankScore" | "mmrScore", fallbackIds: string[]): {
+  values: number[] | null;
+  omitted: string[];
+};
+//#endregion
+//#region src/engine/operations/selective-forgetting-scorer.d.ts
+interface RetentionScorer {
+  /** Calculate decay score for a single memory */
+  score(memory: DecayableMemory, now?: number): DecayScore;
+  /** Calculate decay scores for multiple memories */
+  scoreAll(memories: DecayableMemory[], now?: number): DecayScore[];
+  /** Find stale memories (composite below threshold) */
+  getStaleMemories(memories: DecayableMemory[], now?: number): DecayScore[];
+}
+//#endregion
+//#region src/engine/retrieval/retriever-core.d.ts
+/**
+ * Enumerates every branch in `rerank()` that fell back to the pre-rerank
+ * candidate ordering instead of applying the cross-encoder score. Aggregated
+ * via {@link RetrievalStatsCollector} and surfaced as trace stage metadata
+ * so callers can attribute degraded ranking without parsing log lines.
+ *
+ * - `missing_api_key`: cross-encoder configured but no rerankApiKey set;
+ *   call routes through the lightweight cosine path instead.
+ * - `no_endpoint`: provider has no known endpoint in `RERANK_DEFAULT_ENDPOINTS`
+ *   and `rerankEndpoint` was not overridden; rerank was skipped.
+ * - `http_error`: provider responded with a non-OK status that did not map
+ *   to a fatal RetrievalError (i.e. degraded but not propagated).
+ * - `invalid_response`: provider HTTP 2xx but response shape did not parse.
+ * - `timeout`: the per-call AbortSignal fired before the provider responded.
+ * - `request_error`: any other thrown error inside the fetch path.
+ * - `query_over_window`: the query alone fills the reranker's per-pair token window, so no
+ *   document could be sent with it. Nothing was requested.
+ */
+declare const RERANK_FALLBACK_REASONS: readonly ["missing_api_key", "no_endpoint", "http_error", "invalid_response", "timeout", "request_error", "query_over_window"];
+type RerankFallbackReason = (typeof RERANK_FALLBACK_REASONS)[number];
+interface RerankFallbackSignal {
+  reason: RerankFallbackReason;
+  provider: string;
+}
+interface RerankOutcome {
+  candidates: RetrievalResult[];
+  fallback?: RerankFallbackSignal;
+  stats?: {
+    rerankSentCount: number;
+    rerankReturnedCount: number;
+    rerankBeyondCapCount: number;
+  };
+}
+declare class MemoryRetriever {
+  readonly store: MemoryStore;
+  readonly embedder: Embedder;
+  private readonly config;
+  private _statsCollector;
+  _accessTracker: AccessTracker | undefined;
+  _cachedConfigHash: string | undefined;
+  _retentionScorer: RetentionScorer | undefined;
+  _tierPromoter: TierPromoter | undefined;
+  _recallLifecycle: RecallLifecycleConfig | undefined;
+  retrieve(_context: RetrievalContext): Promise<RetrievalResult[]>;
+  retrieveWithTrace(_context: RetrievalContext): Promise<{
+    results: RetrievalResult[];
+    trace: RetrievalTrace;
+  }>;
+  /**
+   * Initializes precision recall retrieval ranking collaborators while keeping runtime work in explicit
+   * methods.
+   */
+  constructor(store: MemoryStore, embedder: Embedder, _logger?: {
+    warn: (message: string, fields?: Record<string, unknown>) => void;
+  }, config?: RetrievalConfig);
+  /** Enable aggregate retrieval statistics collection. */
+  setStatsCollector(collector: RetrievalStatsCollector): void;
+  /** Get the stats collector (if set). */
+  getStatsCollector(): RetrievalStatsCollector | undefined;
+  /** Set the access tracker for recording manual retrieval accesses. */
+  setAccessTracker(tracker: AccessTracker): void;
+  /**
+   * Install the Phase 0 §5 tier-promoter dependency. Pure dependency injection;
+   * the post-retrieval evaluation hook only fires when both this setter has
+   * been called and `recallLifecycle.tierPromoter` is true.
+   */
+  setTierPromoter(promoter: TierPromoter): void;
+  /**
+   * Resolve the `recallLifecycle` block once at composition time so the hot
+   * retrieval path reads it without re-parsing config. All gates default
+   * false in `recallLifecycleSchema`, preserving the no-behavior-change
+   * Phase 0 contract for callers that never call this setter.
+   */
+  setRecallLifecycle(config: RecallLifecycleConfig): void;
+  /** Returns the immutable retrieval config for diagnostics and tests. */
+  getConfig(): RetrievalConfig;
+}
+interface MemoryRetrieverInternals {
+  store: MemoryStore;
+  embedder: Embedder;
+  config: RetrievalConfig;
+  _statsCollector: RetrievalStatsCollector | undefined;
+  _accessTracker: AccessTracker | undefined;
+  _cachedConfigHash: string | undefined;
+  _retentionScorer: RetentionScorer | undefined;
+  _tierPromoter: TierPromoter | undefined;
+  _recallLifecycle: RecallLifecycleConfig | undefined;
+  evaluateTopKTierTransitions(results: RetrievalResult[]): Promise<void>;
+  retrieve(context: RetrievalContext): Promise<RetrievalResult[]>;
+  retrieveWithTrace(context: RetrievalContext): Promise<{
+    results: RetrievalResult[];
+    trace: RetrievalTrace;
+  }>;
+  throwIfAborted(context: RetrievalContext): void;
+  filterExpired(results: RetrievalResult[]): RetrievalResult[];
+  filterExpiredCandidates(results: MemorySearchResult[]): MemorySearchResult[];
+  isEntryExpired(entry: MemorySearchResult["entry"] | RetrievalResult["entry"]): boolean;
+  vectorOnly(context: RetrievalContext, trace?: TraceCollector): Promise<RetrievalResult[]>;
+  precisionRecall(context: RetrievalContext, trace?: TraceCollector): Promise<RetrievalResult[]>;
+  aggregationComplete(context: RetrievalContext, trace?: TraceCollector): Promise<RetrievalResult[]>;
+  rrfFuse(vector: MemorySearchResult[], keyword: MemorySearchResult[]): RetrievalResult[];
+  rerank(query: string, candidates: RetrievalResult[], queryVector: Float32Array): Promise<RerankOutcome>;
+  rerankLightweight(candidates: RetrievalResult[], queryVector: Float32Array): RetrievalResult[];
+  getRerankSourceScore(result: RetrievalResult): number;
+  applyScoringPipeline(results: RetrievalResult[], trace?: TraceCollector, limit?: number): RetrievalResult[];
+  applyRecencyBoost(results: RetrievalResult[]): RetrievalResult[];
+  applyImportanceWeight(results: RetrievalResult[]): RetrievalResult[];
+  applyLengthNormalization(results: RetrievalResult[]): RetrievalResult[];
+  applyTimeDecay(results: RetrievalResult[]): RetrievalResult[];
+  applyRetentionBoost(results: RetrievalResult[]): RetrievalResult[];
+  applyMmrDiversity(results: RetrievalResult[]): RetrievalResult[];
+}
+/** Creates the retriever with store, embedding, ranking config, and optional caller logger slot. */
+declare function createRetriever(store: MemoryStore, embedder: Embedder, logger?: {
+  warn: (message: string, fields?: Record<string, unknown>) => void;
+}, config?: RetrievalConfig): MemoryRetriever;
+//#endregion
+export { RerankFallbackSignal as a, collectParallelStage as c, RetrievalConfig as d, RetrievalContext as f, RerankFallbackReason as i, DEFAULT_RETRIEVAL_CONFIG as l, MemoryRetrieverInternals as n, RerankOutcome as o, withServingValidityDefault as p, RERANK_FALLBACK_REASONS as r, createRetriever as s, MemoryRetriever as t, RerankProvider as u };