@snoai/memory 0.0.0-stage → 1.0.1

package/dist/retriever-ZoLvPRHq.js

@@ -0,0 +1,1757 @@
+import { CHUNKING_VERSION, DEFAULT_BM25_WEIGHT, DEFAULT_RECALL_LIFECYCLE, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_TIMEOUT_MS, DEFAULT_VECTOR_WEIGHT, IMPORTANCE_WEIGHT_BASE, LIGHTWEIGHT_COSINE_WEIGHT, LIGHTWEIGHT_FUSION_WEIGHT, LIGHTWEIGHT_RERANK_PENALTY, MMR_LAMBDA, RECENCY_WEIGHT, RERANK_BLEND_CROSS, RERANK_BLEND_VECTOR, TIME_DECAY_FLOOR, experimentCandidatePoolOverride, experimentMmrDisabled } from "./internal/config/index.js";
+import "./internal/engine/shared/types.js";
+import { RetrievalError } from "./internal/engine/shared/errors.js";
+import { o as isMemoryExpired, s as parseInsightMetadata } from "./memory-metadata-codec-DL1sbJiN.js";
+import { clamp01 } from "./internal/engine/shared/utils.js";
+import { i as memoryOperationSignal } from "./operation-cancellation-CTKWwNHk.js";
+import { classifyLlmFailure } from "./internal/model/llm-failure.js";
+import { appendQaTrace, computeConfigHash, isTraceEnabled } from "./internal/engine/eval/trace.js";
+import { computeEffectiveHalfLife, parseAccessMetadata } from "./internal/engine/retrieval/access-tracker.js";
+import { createLogger as createLogger$1, currentLogContext, privateLogReference, withLogContext } from "@snoai/utils/logger";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/engine/retrieval/retrieval-trace.ts
+var StageLifecycle = class StageLifecycle {
+	name;
+	inputOrder;
+	inputSet;
+	openedAt;
+	constructor(name, entryIds, openedAt) {
+		this.name = name;
+		this.inputOrder = Array.from(new Set(entryIds));
+		this.inputSet = new Set(this.inputOrder);
+		this.openedAt = openedAt;
+	}
+	static open(name, entryIds, openedAt) {
+		return new StageLifecycle(name, entryIds, openedAt);
+	}
+	closeUnchanged(closedAt) {
+		return this.closeWith(this.inputOrder, void 0, closedAt);
+	}
+	closeWith(survivingIds, scores, closedAt, metadata) {
+		const base = {
+			name: this.name,
+			inputCount: this.inputSet.size,
+			outputCount: survivingIds.length,
+			droppedIds: this.findDroppedIds(survivingIds),
+			outputIds: [...survivingIds],
+			scoreRange: getScoreRange(scores),
+			durationMs: closedAt - this.openedAt
+		};
+		return metadata ? {
+			...base,
+			metadata
+		} : base;
+	}
+	findDroppedIds(survivingIds) {
+		const survivors = new Set(survivingIds);
+		return this.inputOrder.filter((id) => !survivors.has(id));
+	}
+};
+function getScoreRange(scores) {
+	if (!scores || scores.length === 0) return null;
+	let min = scores[0] ?? 0;
+	let max = min;
+	for (const score of scores.slice(1)) {
+		if (score < min) min = score;
+		if (score > max) max = score;
+	}
+	return [min, max];
+}
+function finalOutputCount(stages) {
+	return stages.at(-1)?.outputCount ?? 0;
+}
+function formatScoreRange(scoreRange) {
+	return scoreRange ? ` scores=[${scoreRange[0].toFixed(3)}, ${scoreRange[1].toFixed(3)}]` : "";
+}
+function formatDroppedIds(droppedIds) {
+	if (droppedIds.length === 0) return null;
+	if (droppedIds.length <= 5) return `    dropped: ${droppedIds.join(", ")}`;
+	return `    dropped: ${droppedIds.slice(0, 5).join(", ")} (+${droppedIds.length - 5} more)`;
+}
+var TraceCollector = class {
+	startedAtMs;
+	startedMonotonicMs;
+	results = [];
+	lifecycle = [];
+	lifecycleEnabled;
+	activeStage = null;
+	/**
+	* Initializes retrieval tracing collaborators while keeping runtime work in explicit methods.
+	*/
+	constructor(options) {
+		this.startedAtMs = Date.now();
+		this.startedMonotonicMs = performance.now();
+		this.lifecycleEnabled = options?.lifecycleEnabled === true;
+	}
+	/**
+	* Begin tracking a pipeline stage.
+	* @param name - Stage identifier (e.g. "vector_search")
+	* @param entryIds - IDs of entries entering this stage
+	*/
+	startStage(name, entryIds) {
+		this.closeActiveStageAsUnchanged();
+		this.activeStage = StageLifecycle.open(name, entryIds, performance.now());
+	}
+	/**
+	* 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, scores, metadata) {
+		const stage = this.activeStage;
+		if (!stage) return;
+		this.results.push(stage.closeWith(survivingIds, scores, performance.now(), metadata));
+		this.activeStage = null;
+	}
+	/**
+	* Finalize the trace and produce the complete RetrievalTrace object.
+	*/
+	finalize(query, mode) {
+		this.closeActiveStageAsUnchanged();
+		const base = {
+			query,
+			mode,
+			startedAt: this.startedAtMs,
+			stages: this.results,
+			finalCount: finalOutputCount(this.results),
+			totalMs: performance.now() - this.startedMonotonicMs
+		};
+		if (this.lifecycleEnabled && this.lifecycle.length > 0) return {
+			...base,
+			lifecycleEvents: this.lifecycle
+		};
+		return base;
+	}
+	/** Append a retention-scorer outcome to the lifecycle stream. */
+	writeRetentionTrace(event) {
+		if (!this.lifecycleEnabled) return;
+		this.lifecycle.push({
+			kind: "retention-score-computed",
+			at: Date.now(),
+			...event
+		});
+	}
+	/** Append an access-tracker update to the lifecycle stream. */
+	writeAccessTrace(event) {
+		if (!this.lifecycleEnabled) return;
+		this.lifecycle.push({
+			kind: "access-tracker-update",
+			at: Date.now(),
+			...event
+		});
+	}
+	/** Append a tier-promotion evaluation outcome to the lifecycle stream. */
+	writeTierTrace(event) {
+		if (!this.lifecycleEnabled) return;
+		this.lifecycle.push({
+			kind: "tier-promotion-evaluated",
+			at: Date.now(),
+			...event
+		});
+	}
+	/** Access collected lifecycle events (read-only). */
+	get lifecycleEvents() {
+		return this.lifecycle;
+	}
+	/**
+	* Produce a human-readable summary of the trace.
+	*/
+	summarize() {
+		const lines = [`Retrieval trace (${this.results.length} stages):`];
+		for (const stage of this.results) {
+			lines.push(`  ${stage.name}: ${stage.inputCount} -> ${stage.outputCount} (-${stage.droppedIds.length}) ${stage.durationMs}ms${formatScoreRange(stage.scoreRange)}`);
+			const droppedLine = formatDroppedIds(stage.droppedIds);
+			if (droppedLine) lines.push(droppedLine);
+		}
+		lines.push(`  total: ${performance.now() - this.startedMonotonicMs}ms, final count: ${finalOutputCount(this.results)}`);
+		return lines.join("\n");
+	}
+	/** Access collected stages (read-only). */
+	get stages() {
+		return this.results;
+	}
+	closeActiveStageAsUnchanged() {
+		const stage = this.activeStage;
+		if (!stage) return;
+		this.results.push(stage.closeUnchanged(performance.now()));
+		this.activeStage = null;
+	}
+};
+//#endregion
+//#region src/engine/retrieval/retrieval-config.ts
+/** @file retrieval-config.ts
+* @purpose Defines retriever runtime configuration and request context contracts.
+* @boundary Types and defaults only; no ranking execution.
+*/
+/**
+* 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.
+*/
+function withServingValidityDefault(context) {
+	if (context.excludeInvalidatedBefore !== void 0 && context.includeRefused !== void 0) return context;
+	return {
+		...context,
+		excludeInvalidatedBefore: context.excludeInvalidatedBefore ?? Date.now(),
+		includeRefused: context.includeRefused ?? true
+	};
+}
+const DEFAULT_RETRIEVAL_CONFIG = {
+	temporalWeighting: false,
+	mmrWindowOnly: false,
+	mode: "precision-recall",
+	vectorWeight: DEFAULT_VECTOR_WEIGHT,
+	bm25Weight: DEFAULT_BM25_WEIGHT,
+	minScore: 0,
+	rerank: "cross-encoder",
+	candidatePoolSize: 64,
+	recencyHalfLifeDays: 14,
+	recencyWeight: RECENCY_WEIGHT,
+	temporalExpiry: false,
+	temporalDecay: true,
+	rerankModel: DEFAULT_RERANK_MODEL,
+	rerankTimeoutMs: DEFAULT_RERANK_TIMEOUT_MS,
+	rerankProvider: "voyage",
+	lengthNormAnchor: 0,
+	hardMinScore: 0,
+	timeDecayHalfLifeDays: 60,
+	rerankBlendVector: RERANK_BLEND_VECTOR,
+	rerankBlendCross: RERANK_BLEND_CROSS,
+	lightweightFusionWeight: LIGHTWEIGHT_FUSION_WEIGHT,
+	lightweightCosineWeight: LIGHTWEIGHT_COSINE_WEIGHT,
+	importanceWeightBase: IMPORTANCE_WEIGHT_BASE,
+	timeDecayFloor: TIME_DECAY_FLOOR,
+	mmrLambda: MMR_LAMBDA,
+	recallLifecycle: DEFAULT_RECALL_LIFECYCLE
+};
+//#endregion
+//#region src/engine/retrieval/retriever-core.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.
+*/
+const RERANK_FALLBACK_REASONS = [
+	"missing_api_key",
+	"no_endpoint",
+	"http_error",
+	"invalid_response",
+	"timeout",
+	"request_error",
+	"query_over_window"
+];
+var MemoryRetriever = class {
+	store;
+	embedder;
+	config;
+	_statsCollector;
+	_accessTracker;
+	_cachedConfigHash;
+	_retentionScorer;
+	_tierPromoter;
+	_recallLifecycle;
+	retrieve(_context) {
+		throw new Error("MemoryRetriever implementation modules were not loaded");
+	}
+	retrieveWithTrace(_context) {
+		throw new Error("MemoryRetriever implementation modules were not loaded");
+	}
+	/**
+	* Initializes precision recall retrieval ranking collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(store, embedder, _logger, config = DEFAULT_RETRIEVAL_CONFIG) {
+		this.store = store;
+		this.embedder = embedder;
+		this.config = config;
+	}
+	/** Enable aggregate retrieval statistics collection. */
+	setStatsCollector(collector) {
+		this._statsCollector = collector;
+	}
+	/** Get the stats collector (if set). */
+	getStatsCollector() {
+		return this._statsCollector;
+	}
+	/** Set the access tracker for recording manual retrieval accesses. */
+	setAccessTracker(tracker) {
+		this._accessTracker = tracker;
+	}
+	/**
+	* 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) {
+		this._tierPromoter = promoter;
+	}
+	/**
+	* 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) {
+		this._recallLifecycle = config;
+	}
+	/** Returns the immutable retrieval config for diagnostics and tests. */
+	getConfig() {
+		return this.config;
+	}
+};
+/** Creates the retriever with store, embedding, ranking config, and optional caller logger slot. */
+function createRetriever(store, embedder, logger, config = DEFAULT_RETRIEVAL_CONFIG) {
+	return new MemoryRetriever(store, embedder, logger, config);
+}
+//#endregion
+//#region src/engine/retrieval/retriever-query-tools.ts
+Object.assign(MemoryRetriever.prototype, {
+	throwIfAborted(context) {
+		if (!context.signal?.aborted) return;
+		const reason = context.signal.reason;
+		throw reason instanceof Error ? reason : /* @__PURE__ */ new Error("retrieval aborted");
+	},
+	filterExpired(results) {
+		if (!this.config.temporalExpiry) return results;
+		return results.filter((r) => !this.isEntryExpired(r.entry));
+	},
+	filterExpiredCandidates(results) {
+		if (!this.config.temporalExpiry) return results;
+		return results.filter((r) => !this.isEntryExpired(r.entry));
+	},
+	isEntryExpired(entry) {
+		const metadata = parseInsightMetadata(entry.metadata, entry);
+		return isMemoryExpired(metadata);
+	}
+});
+//#endregion
+//#region src/engine/retrieval/retrieval-scoring-utils.ts
+const log = createLogger$1("sno-station-mem:retriever");
+function dotProduct(a, b) {
+	let sum = 0;
+	const len = a.length;
+	for (let i = 0; i < len; i += 1) sum += (a[i] ?? 0) * (b[i] ?? 0);
+	return sum;
+}
+function collectParallelStage(results, key, fallbackIds) {
+	const omitted = [];
+	const values = [];
+	for (const [index, result] of results.entries()) {
+		const value = result[key];
+		if (typeof value !== "number" || !Number.isFinite(value)) omitted.push(fallbackIds[index] ?? "");
+		else values.push(value);
+	}
+	if (omitted.length === 0) return {
+		values,
+		omitted
+	};
+	return {
+		values: null,
+		omitted
+	};
+}
+//#endregion
+//#region src/engine/retrieval/retriever-search-modes.ts
+Object.assign(MemoryRetriever.prototype, {
+	async aggregationComplete(context, trace) {
+		trace?.startStage("aggregation_evidence", []);
+		const results = await this.store.searchAggregationEvidence({
+			limit: 640,
+			projectIdFilter: context.scopeFilter,
+			category: context.category,
+			includeRefused: context.includeRefused,
+			includeRetired: context.includeRetired,
+			aggregation: context.aggregation,
+			facetPolicy: context.facetPolicy,
+			...context.excludeInvalidatedBefore !== void 0 && { excludeInvalidatedBefore: context.excludeInvalidatedBefore },
+			...context.excludeSuperseded === void 0 ? {} : { excludeSuperseded: context.excludeSuperseded }
+		});
+		this.throwIfAborted(context);
+		const mapped = results.map((result) => ({
+			entry: result.entry,
+			score: result.score,
+			sources: {},
+			chunkId: result.chunkId,
+			chunkIndex: result.chunkIndex,
+			bestChunkScore: result.bestChunkScore,
+			denseScore: result.score,
+			snippet: result.snippet,
+			eventIdentity: result.eventIdentity,
+			scopeRowCount: result.scopeRowCount,
+			aggregationIncomplete: result.aggregationIncomplete
+		}));
+		trace?.endStage(mapped.map((result) => result.entry.id), mapped.map((result) => result.score));
+		log.info("aggregation evidence served", {
+			rows: mapped.length,
+			scopeRows: mapped[0]?.scopeRowCount ?? 0,
+			readingBudget: context.limit,
+			bounded: true,
+			scopes: context.scopeFilter?.length ?? 0,
+			...context.category ? { category: context.category } : {}
+		}, {
+			event_name: "memory.retriever_search_modes.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-search-modes.ts",
+			function: "aggregationComplete",
+			site_id: "retrieval.retriever-search-modes.aggregationComplete.5a3b7f9337"
+		});
+		return mapped;
+	},
+	async vectorOnly(context, trace) {
+		const vector = await this.embedder.embed(context.query);
+		this.throwIfAborted(context);
+		const searchLimit = this.config.temporalExpiry ? Math.max(this.config.candidatePoolSize, context.limit * 2) : context.limit;
+		trace?.startStage("vector_search", []);
+		const results = await this.store.searchSemantic(vector, {
+			limit: searchLimit,
+			projectIdFilter: context.scopeFilter,
+			category: context.category,
+			includeRefused: context.includeRefused,
+			includeRetired: context.includeRetired,
+			facetPolicy: context.facetPolicy,
+			...context.excludeInvalidatedBefore !== void 0 && { excludeInvalidatedBefore: context.excludeInvalidatedBefore },
+			...context.excludeSuperseded === void 0 ? {} : { excludeSuperseded: context.excludeSuperseded }
+		});
+		this.throwIfAborted(context);
+		let mapped = results.map((result, index) => ({
+			entry: result.entry,
+			score: result.score,
+			sources: { vector: {
+				score: result.score,
+				rank: index + 1
+			} },
+			chunkId: result.chunkId,
+			chunkIndex: result.chunkIndex,
+			bestChunkScore: result.bestChunkScore,
+			snippet: result.snippet,
+			denseScore: result.score
+		}));
+		trace?.endStage(mapped.map((r) => r.entry.id), mapped.map((r) => r.score));
+		trace?.startStage("expiry_filter", mapped.map((result) => result.entry.id));
+		mapped = this.filterExpired(mapped);
+		trace?.endStage(mapped.map((result) => result.entry.id));
+		mapped = this.applyScoringPipeline(mapped, trace, context.limit);
+		trace?.startStage("min_score_filter", mapped.map((result) => result.entry.id));
+		mapped = mapped.filter((result) => result.score >= (context.minScore ?? this.config.minScore));
+		trace?.endStage(mapped.map((result) => result.entry.id), mapped.map((result) => result.score));
+		trace?.startStage("limit_slice", mapped.map((result) => result.entry.id));
+		const served = mapped.slice(0, context.limit);
+		trace?.endStage(served.map((result) => result.entry.id), served.map((result) => result.score));
+		return served;
+	},
+	async precisionRecall(context, trace) {
+		trace?.startStage("embed_query", []);
+		const queryVector = await this.embedder.embed(context.query);
+		trace?.endStage([]);
+		this.throwIfAborted(context);
+		const bm25Query = context.query;
+		const sharedSearchOptions = {
+			limit: experimentCandidatePoolOverride() ?? Math.min(Math.max(this.config.candidatePoolSize, context.limit * 2), 2048),
+			projectIdFilter: context.scopeFilter,
+			category: context.category,
+			includeRefused: context.includeRefused,
+			includeRetired: context.includeRetired,
+			facetPolicy: context.facetPolicy,
+			...context.excludeInvalidatedBefore !== void 0 && { excludeInvalidatedBefore: context.excludeInvalidatedBefore },
+			...context.excludeSuperseded === void 0 ? {} : { excludeSuperseded: context.excludeSuperseded }
+		};
+		trace?.startStage("parallel_search", []);
+		const [vectorSettled, keywordSettled] = await Promise.allSettled([this.store.searchSemantic(queryVector, sharedSearchOptions), this.store.searchKeyword(bm25Query, sharedSearchOptions)]);
+		this.throwIfAborted(context);
+		const errorMessage = (reason) => reason instanceof Error ? reason.message : String(reason);
+		const vectorError = vectorSettled.status === "rejected" ? errorMessage(vectorSettled.reason) : void 0;
+		const keywordError = keywordSettled.status === "rejected" ? errorMessage(keywordSettled.reason) : void 0;
+		const branchMetadata = {
+			vectorStatus: vectorSettled.status,
+			vectorCount: vectorSettled.status === "fulfilled" ? vectorSettled.value.length : 0,
+			keywordStatus: keywordSettled.status,
+			keywordCount: keywordSettled.status === "fulfilled" ? keywordSettled.value.length : 0,
+			...vectorError === void 0 ? {} : { vectorError },
+			...keywordError === void 0 ? {} : { keywordError }
+		};
+		if (vectorSettled.status === "rejected" && keywordSettled.status === "rejected") {
+			trace?.endStage([], [], branchMetadata);
+			throw new RetrievalError("Both vector and keyword search failed", vectorSettled.reason);
+		}
+		let vectorResults = vectorSettled.status === "fulfilled" ? vectorSettled.value : [];
+		if (vectorSettled.status === "rejected") log.warn("vector search branch failed, using keyword-only", { error: vectorError }, {
+			event_name: "memory.retriever_search_modes.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-search-modes.ts",
+			function: "precisionRecall",
+			site_id: "retrieval.retriever-search-modes.precisionRecall.97b8770f50"
+		});
+		let keywordResults = keywordSettled.status === "fulfilled" ? keywordSettled.value : [];
+		if (keywordSettled.status === "rejected") log.warn("keyword search branch failed, using vector-only", { error: keywordError }, {
+			event_name: "memory.retriever_search_modes.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-search-modes.ts",
+			function: "precisionRecall",
+			site_id: "retrieval.retriever-search-modes.precisionRecall.c20ade60c4"
+		});
+		if (trace) {
+			const allIds = [...vectorResults.map((r) => r.entry.id), ...keywordResults.map((r) => r.entry.id)];
+			trace.endStage(allIds, [...vectorResults.map((r) => r.score), ...keywordResults.map((r) => r.score)], branchMetadata);
+		}
+		const beforeExpiry = [.../* @__PURE__ */ new Set([...vectorResults.map((result) => result.entry.id), ...keywordResults.map((result) => result.entry.id)])];
+		trace?.startStage("expiry_filter", beforeExpiry);
+		vectorResults = this.filterExpiredCandidates(vectorResults);
+		keywordResults = this.filterExpiredCandidates(keywordResults);
+		trace?.endStage([.../* @__PURE__ */ new Set([...vectorResults.map((result) => result.entry.id), ...keywordResults.map((result) => result.entry.id)])]);
+		trace?.startStage("rrf_fusion", [...vectorResults.map((r) => r.entry.id), ...keywordResults.map((r) => r.entry.id)]);
+		let fused = this.rrfFuse(vectorResults, keywordResults);
+		trace?.endStage(fused.map((r) => r.entry.id), fused.map((r) => r.score));
+		log.debug("precision recall search", {
+			vectorCount: vectorResults.length,
+			keywordCount: keywordResults.length,
+			fusedCount: fused.length,
+			queryExpanded: bm25Query !== context.query
+		}, {
+			event_name: "memory.retriever_search_modes.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-search-modes.ts",
+			function: "precisionRecall",
+			site_id: "retrieval.retriever-search-modes.precisionRecall.aaf0b2eb17"
+		});
+		trace?.startStage("rerank", fused.map((r) => r.entry.id));
+		const rerankOutcome = await this.rerank(context.query, fused, queryVector);
+		fused = rerankOutcome.candidates;
+		this.throwIfAborted(context);
+		const rerankStageMetadata = rerankOutcome.fallback ? {
+			...rerankOutcome.stats,
+			rerankFallbackReason: rerankOutcome.fallback.reason,
+			rerankFallbackProvider: rerankOutcome.fallback.provider
+		} : rerankOutcome.stats;
+		trace?.endStage(fused.map((r) => r.entry.id), fused.map((r) => r.score), rerankStageMetadata);
+		fused = this.applyScoringPipeline(fused, trace, context.limit);
+		trace?.startStage("min_score_filter", fused.map((result) => result.entry.id));
+		fused = fused.filter((result) => result.score >= (context.minScore ?? this.config.minScore));
+		trace?.endStage(fused.map((result) => result.entry.id), fused.map((result) => result.score));
+		const identifiers = context.query.match(/[\w./-]*\d[\w./-]*/g)?.filter((token) => token.length >= 6) ?? [];
+		const exact = fused.filter((result) => identifiers.some((token) => result.entry.text.includes(token)));
+		if (exact.length > 0) fused = [...exact, ...fused.filter((result) => !exact.includes(result))];
+		trace?.startStage("limit_slice", fused.map((result) => result.entry.id));
+		const served = fused.slice(0, context.limit);
+		trace?.endStage(served.map((result) => result.entry.id), served.map((result) => result.score));
+		return served;
+	},
+	rrfFuse(vector, keyword) {
+		const vectorMap = /* @__PURE__ */ new Map();
+		const keywordMap = /* @__PURE__ */ new Map();
+		for (const [index, result] of vector.entries()) vectorMap.set(result.entry.id, {
+			...result,
+			rank: index + 1
+		});
+		for (const [index, result] of keyword.entries()) keywordMap.set(result.entry.id, {
+			...result,
+			rank: index + 1
+		});
+		const allIds = /* @__PURE__ */ new Set([...vectorMap.keys(), ...keywordMap.keys()]);
+		const fused = [];
+		for (const id of allIds) {
+			const vectorHit = vectorMap.get(id);
+			const keywordHit = keywordMap.get(id);
+			const base = vectorHit ?? keywordHit;
+			if (!base) continue;
+			const vectorScore = vectorHit?.score ?? 0;
+			const keywordScore = keywordHit?.score ?? 0;
+			const weightedFusion = vectorScore * this.config.vectorWeight + keywordScore * this.config.bm25Weight;
+			const score = vectorHit ? clamp01(weightedFusion, .1) : clamp01(keywordScore, .1);
+			const vectorBest = vectorHit?.bestChunkScore ?? -1;
+			const keywordBest = keywordHit?.bestChunkScore ?? -1;
+			const anchor = vectorHit && keywordHit ? vectorBest >= keywordBest ? vectorHit : keywordHit : vectorHit ?? keywordHit;
+			fused.push({
+				entry: base.entry,
+				score,
+				sources: {
+					vector: vectorHit ? {
+						score: vectorHit.score,
+						rank: vectorHit.rank ?? 1
+					} : void 0,
+					bm25: keywordHit ? {
+						score: keywordHit.score,
+						rank: keywordHit.rank ?? 1
+					} : void 0,
+					fused: { score }
+				},
+				chunkId: anchor?.chunkId,
+				chunkIndex: anchor?.chunkIndex,
+				bestChunkScore: anchor?.bestChunkScore,
+				snippet: anchor?.snippet,
+				denseScore: vectorHit?.score,
+				bm25Score: keywordHit?.score,
+				fusedScore: score
+			});
+		}
+		return fused.sort((a, b) => {
+			const scoreDiff = b.score - a.score;
+			if (scoreDiff !== 0) return scoreDiff;
+			return a.entry.id.localeCompare(b.entry.id);
+		});
+	}
+});
+//#endregion
+//#region src/engine/retrieval/retrieval-rerank-provider.ts
+/** @file retrieval-rerank-provider.ts
+* @purpose Adapts external rerank provider request and response formats.
+* @boundary HTTP payload shaping and response parsing only.
+*/
+const RERANK_DEFAULT_ENDPOINTS = {
+	voyage: "https://api.voyageai.com/v1/rerank",
+	jina: "https://api.jina.ai/v1/rerank",
+	pinecone: "https://api.pinecone.io/rerank",
+	dashscope: "https://dashscope.aliyuncs.com/api/v1/services/rerank"
+};
+function buildRerankHttpError(status) {
+	if (classifyLlmFailure({ status }).category === "auth") return new RetrievalError(`Rerank API failed with status ${status}`);
+}
+function buildRerankRequest(provider, apiKey, model, query, candidates, topN) {
+	switch (provider) {
+		case "tei": return {
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`
+			},
+			body: {
+				query,
+				texts: candidates,
+				raw_scores: true
+			}
+		};
+		case "dashscope": return {
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`
+			},
+			body: {
+				model,
+				input: {
+					query,
+					documents: candidates
+				}
+			}
+		};
+		case "pinecone": return {
+			headers: {
+				"Content-Type": "application/json",
+				"Api-Key": apiKey,
+				"X-Pinecone-API-Version": "2024-10"
+			},
+			body: {
+				model,
+				query,
+				documents: candidates.map((text) => ({ text })),
+				top_n: topN,
+				rank_fields: ["text"]
+			}
+		};
+		case "voyage": return {
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`
+			},
+			body: {
+				model,
+				query,
+				documents: candidates,
+				top_k: topN
+			}
+		};
+		default: return {
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`
+			},
+			body: {
+				model,
+				query,
+				documents: candidates,
+				top_n: topN
+			}
+		};
+	}
+}
+function parseRerankResponse(provider, data) {
+	/** Parses items into the normalized shape used by precision recall retrieval ranking. */
+	const parseItems = (items, scoreKeys) => {
+		if (!Array.isArray(items)) return void 0;
+		const parsed = [];
+		for (const raw of items) {
+			const index = typeof raw?.index === "number" ? raw.index : Number(raw?.index);
+			if (!Number.isFinite(index)) continue;
+			let score;
+			for (const key of scoreKeys) {
+				const value = raw?.[key];
+				const n = typeof value === "number" ? value : Number(value);
+				if (Number.isFinite(n)) {
+					score = n;
+					break;
+				}
+			}
+			if (score === void 0) continue;
+			parsed.push({
+				index,
+				score
+			});
+		}
+		return parsed.length > 0 ? parsed : void 0;
+	};
+	const objectData = data && typeof data === "object" && !Array.isArray(data) ? data : void 0;
+	switch (provider) {
+		case "tei": return parseItems(data, ["score", "relevance_score"]) ?? parseItems(objectData?.results, ["score", "relevance_score"]) ?? parseItems(objectData?.data, ["score", "relevance_score"]);
+		case "dashscope": {
+			const output = objectData?.output;
+			if (output) return parseItems(output.results, ["relevance_score", "score"]);
+			return parseItems(objectData?.results, ["relevance_score", "score"]);
+		}
+		case "pinecone": return parseItems(objectData?.data, ["score", "relevance_score"]) ?? parseItems(objectData?.results, ["score", "relevance_score"]);
+		case "voyage": return parseItems(objectData?.data, ["relevance_score", "score"]) ?? parseItems(objectData?.results, ["relevance_score", "score"]);
+		default: return parseItems(objectData?.results, ["relevance_score", "score"]) ?? parseItems(objectData?.data, ["relevance_score", "score"]);
+	}
+}
+//#endregion
+//#region src/engine/retrieval/retriever-rerank.ts
+/** @file retriever-rerank.ts
+* @purpose Runs remote and local reranking.
+* @boundary Prototype-mounted MemoryRetriever methods; no constructor state ownership.
+*/
+const RERANK_TRANSIENT_ATTEMPTS = 3;
+const RERANK_TRANSIENT_BACKOFF_MS = 200;
+const RERANK_TRANSIENT_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+const RERANK_RETRY_AFTER_MAX_MS = 5e3;
+function isRerankTimeout(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+/**
+* The reranker's refusal when a pair is over its window, as the endpoint states it:
+* `{"detail":{"code":"input_token_limit_exceeded","max_input_tokens":512,
+* "candidates":[{"index":0,"input_tokens":728,"excess_tokens":216}]}}` (measured 2026-09-14).
+*
+* It names every offending text, so the batch can be repaired and sent again instead of
+* losing the scores of the 49 texts that were fine. The counts are the SERVER's, taken with
+* the ranking model's tokenizer — which is not the embedder's — so they are the only exact
+* measure available here of how far over the window a text is.
+*/
+const RERANK_OVER_WINDOW_CODE = "input_token_limit_exceeded";
+function parseOverWindowRefusal(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const detail = parsed.detail;
+	if (typeof detail !== "object" || detail === null) return void 0;
+	const shape = detail;
+	if (shape.code !== RERANK_OVER_WINDOW_CODE) return void 0;
+	if (typeof shape.max_input_tokens !== "number" || !Array.isArray(shape.candidates)) return;
+	const overLong = [];
+	for (const candidate of shape.candidates) {
+		if (typeof candidate !== "object" || candidate === null) continue;
+		const named = candidate;
+		if (typeof named.index !== "number" || typeof named.input_tokens !== "number") continue;
+		overLong.push({
+			index: named.index,
+			inputTokens: named.input_tokens
+		});
+	}
+	return overLong.length === 0 ? void 0 : {
+		maxInputTokens: shape.max_input_tokens,
+		overLong
+	};
+}
+function isTransientRerankError(error) {
+	if (isRerankTimeout(error)) return true;
+	return error instanceof TypeError && error.cause !== void 0;
+}
+async function fetchRerankWithRetry(send) {
+	let lastError;
+	for (let attempt = 1; attempt <= RERANK_TRANSIENT_ATTEMPTS; attempt += 1) {
+		let retryDelayMs = RERANK_TRANSIENT_BACKOFF_MS * attempt;
+		try {
+			const response = await send();
+			if (response.ok) return {
+				response,
+				data: await response.json()
+			};
+			if (!RERANK_TRANSIENT_STATUSES.has(response.status) || attempt === RERANK_TRANSIENT_ATTEMPTS) return { response };
+			if (response.status === 429) {
+				const retryAfter = response.headers.get("retry-after");
+				if (retryAfter !== null && /^\d+$/.test(retryAfter)) retryDelayMs = Math.min(Number.parseInt(retryAfter, 10) * 1e3, RERANK_RETRY_AFTER_MAX_MS);
+			}
+			await response.body?.cancel();
+			lastError = /* @__PURE__ */ new Error(`rerank API responded ${response.status}`);
+		} catch (error) {
+			if (!isTransientRerankError(error) || attempt === RERANK_TRANSIENT_ATTEMPTS) throw error;
+			lastError = error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+	}
+	throw lastError;
+}
+Object.assign(MemoryRetriever.prototype, {
+	async rerank(query, candidates, queryVector) {
+		if (candidates.length === 0) return { candidates };
+		if (this.config.rerank === "none") return { candidates };
+		const provider = this.config.rerankProvider ?? "none";
+		if (this.config.rerank === "cross-encoder" && !this.config.rerankApiKey) throw new RetrievalError(`rerank "cross-encoder" requires retrieval.rerankApiKey (provider: ${provider}); set the key, or set retrieval.rerank to "lightweight" to choose the local ranker`);
+		if (this.config.rerank === "lightweight" || !this.config.rerankApiKey) return { candidates: this.rerankLightweight(candidates, queryVector) };
+		const rerankEndpoint = this.config.rerankEndpoint ?? RERANK_DEFAULT_ENDPOINTS[provider];
+		if (!rerankEndpoint) {
+			log.warn("rerank skipped: no endpoint for provider", { provider }, {
+				event_name: "memory.retriever_rerank.diagnostic",
+				file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+				function: "rerank",
+				site_id: "retrieval.retriever-rerank.rerank.6fbc6b3a22"
+			});
+			return {
+				candidates,
+				fallback: {
+					reason: "no_endpoint",
+					provider
+				}
+			};
+		}
+		const rerankTimeoutMs = this.config.rerankTimeoutMs ?? 15e3;
+		const rerankApiKey = this.config.rerankApiKey;
+		const maxCandidates = this.config.rerankMaxCandidates;
+		const overCap = maxCandidates !== void 0 && candidates.length > maxCandidates;
+		const toRerank = overCap ? candidates.slice(0, maxCandidates) : candidates;
+		const beyondCap = overCap ? candidates.slice(maxCandidates) : [];
+		const batchSize = 50;
+		const queryTokens = this.embedder.countTokens(query);
+		const documentTokenBudget = 509 - queryTokens;
+		if (documentTokenBudget <= 0) {
+			log.warn("rerank skipped: the query alone fills the reranker token window", {
+				queryTokens,
+				window: 512,
+				templateTokens: 3
+			}, {
+				event_name: "memory.retriever_rerank.diagnostic",
+				file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+				function: "rerank",
+				site_id: "retrieval.retriever-rerank.rerank.query_over_window"
+			});
+			return {
+				candidates,
+				fallback: {
+					reason: "query_over_window",
+					provider
+				}
+			};
+		}
+		let truncatedCandidates = 0;
+		const rerankTexts = toRerank.map((c) => {
+			const bounded = this.embedder.truncateToTokens(c.entry.text, documentTokenBudget);
+			if (bounded !== c.entry.text) truncatedCandidates += 1;
+			return bounded;
+		});
+		if (truncatedCandidates > 0) log.warn("rerank candidates were cut to the document budget the query left", {
+			truncatedCandidates,
+			documentTokenBudget,
+			queryTokens
+		}, {
+			event_name: "memory.retriever_rerank.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+			function: "rerank",
+			site_id: "retrieval.retriever-rerank.rerank.candidate_over_ceiling"
+		});
+		try {
+			const runBatch = async (start) => {
+				let batchTexts = rerankTexts.slice(start, start + batchSize);
+				for (let pass = 0;; pass += 1) {
+					const { headers, body } = buildRerankRequest(provider, rerankApiKey, this.config.rerankModel ?? "rerank-2", query, batchTexts, batchTexts.length);
+					const { response, data } = await fetchRerankWithRetry(() => fetch(rerankEndpoint, {
+						method: "POST",
+						headers,
+						body: JSON.stringify(body),
+						signal: AbortSignal.timeout(rerankTimeoutMs)
+					}));
+					if (!response.ok) {
+						const retryAfter = response.headers.get("retry-after");
+						const fatalError = buildRerankHttpError(response.status);
+						if (fatalError) throw fatalError;
+						const errorBody = await response.text().catch(() => "<unreadable body>");
+						const refusal = pass === 0 ? parseOverWindowRefusal(errorBody) : void 0;
+						if (refusal) {
+							const allowed = refusal.maxInputTokens - 3;
+							batchTexts = batchTexts.map((text, index) => {
+								const named = refusal.overLong.find((c) => c.index === index);
+								if (!named) return text;
+								const localTokens = this.embedder.countTokens(text);
+								const localPairTokens = queryTokens + localTokens;
+								const target = Math.max(1, Math.floor(allowed * localPairTokens / named.inputTokens) - queryTokens);
+								return this.embedder.truncateToTokens(text, target);
+							});
+							log.warn("rerank batch refused over its token window; resending the named texts cut to fit", {
+								status: response.status,
+								overLongCount: refusal.overLong.length,
+								maxInputTokens: refusal.maxInputTokens,
+								sentToRerankCount: batchTexts.length,
+								batchStart: start
+							}, {
+								event_name: "memory.retriever_rerank.diagnostic",
+								file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+								function: "runBatch",
+								site_id: "retrieval.retriever-rerank.runBatch.over_window_repair"
+							});
+							continue;
+						}
+						log.warn("rerank API failed, using pre-rerank results", {
+							status: response.status,
+							endpoint_hash: createHash("sha256").update(rerankEndpoint).digest("hex"),
+							retryAfter,
+							sentToRerankCount: batchTexts.length,
+							batchStart: start,
+							body_length: errorBody.length
+						}, {
+							event_name: "memory.retriever_rerank.diagnostic",
+							file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+							function: "runBatch",
+							site_id: "retrieval.retriever-rerank.runBatch.76d7d1fac6"
+						});
+						return "http_error";
+					}
+					const parsed = parseRerankResponse(provider, data);
+					if (!parsed) {
+						log.warn("rerank API returned unparseable response", {
+							provider,
+							endpoint_hash: createHash("sha256").update(rerankEndpoint).digest("hex"),
+							batchStart: start
+						}, {
+							event_name: "memory.retriever_rerank.diagnostic",
+							file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+							function: "runBatch",
+							site_id: "retrieval.retriever-rerank.runBatch.4429b8bd8a"
+						});
+						return "invalid_response";
+					}
+					const batchItems = [];
+					for (const item of parsed) {
+						if (item.index < 0 || item.index >= batchTexts.length) continue;
+						batchItems.push({
+							index: start + item.index,
+							score: item.score
+						});
+					}
+					return batchItems;
+				}
+			};
+			const batchStarts = [];
+			for (let start = 0; start < rerankTexts.length; start += batchSize) batchStarts.push(start);
+			const items = [];
+			for (let wave = 0; wave < batchStarts.length; wave += 4) {
+				const waveStarts = batchStarts.slice(wave, wave + 4);
+				const settled = await Promise.allSettled(waveStarts.map(runBatch));
+				for (const outcome of settled) if (outcome.status === "rejected" && outcome.reason instanceof RetrievalError) throw outcome.reason;
+				for (const outcome of settled) if (outcome.status === "rejected") throw outcome.reason;
+				for (const outcome of settled) if (outcome.status === "fulfilled" && typeof outcome.value === "string") return {
+					candidates,
+					fallback: {
+						reason: outcome.value,
+						provider
+					}
+				};
+				for (const outcome of settled) if (outcome.status === "fulfilled" && typeof outcome.value !== "string") items.push(...outcome.value);
+			}
+			const blendCross = this.config.rerankBlendCross ?? .7;
+			const blendVector = this.config.rerankBlendVector ?? .3;
+			const returnedIndices = new Set(items.map((r) => r.index));
+			const reranked = [];
+			const seenIndices = /* @__PURE__ */ new Set();
+			for (const item of items) {
+				if (seenIndices.has(item.index)) continue;
+				seenIndices.add(item.index);
+				const candidate = toRerank[item.index];
+				if (!candidate) continue;
+				const sourceScore = this.getRerankSourceScore(candidate);
+				let crossScore = item.score;
+				if (provider === "tei") crossScore = 1 / (1 + Math.exp(-item.score));
+				const blendedScore = clamp01(crossScore * blendCross + sourceScore * blendVector, 0);
+				reranked.push({
+					...candidate,
+					score: blendedScore,
+					sources: {
+						...candidate.sources,
+						reranked: { score: item.score }
+					}
+				});
+			}
+			const unreturned = [...toRerank.filter((_, idx) => !returnedIndices.has(idx)), ...beyondCap].map((r) => ({
+				...r,
+				score: clamp01(this.getRerankSourceScore(r) * LIGHTWEIGHT_RERANK_PENALTY, 0)
+			}));
+			const merged = [...reranked, ...unreturned].sort((a, b) => b.score - a.score);
+			log.debug("reranked", {
+				totalCandidateCount: candidates.length,
+				sentToRerankCount: toRerank.length,
+				returnedCount: reranked.length,
+				provider
+			}, {
+				event_name: "memory.retriever_rerank.diagnostic",
+				file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+				function: "rerank",
+				site_id: "retrieval.retriever-rerank.rerank.7847c6248a"
+			});
+			return {
+				candidates: merged.length > 0 ? merged : candidates,
+				stats: {
+					rerankSentCount: toRerank.length,
+					rerankReturnedCount: reranked.length,
+					rerankBeyondCapCount: beyondCap.length
+				}
+			};
+		} catch (error) {
+			if (error instanceof RetrievalError) throw error;
+			let reason;
+			if (isRerankTimeout(error)) {
+				reason = "timeout";
+				log.warn("rerank API timed out, using pre-rerank results", {
+					timeoutMs: rerankTimeoutMs,
+					attempts: RERANK_TRANSIENT_ATTEMPTS
+				}, {
+					event_name: "memory.retriever_rerank.diagnostic",
+					file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+					function: "rerank",
+					site_id: "retrieval.retriever-rerank.rerank.4af9c17c75"
+				});
+			} else {
+				reason = "request_error";
+				log.warn("rerank error, using pre-rerank results", {
+					error,
+					attempts: RERANK_TRANSIENT_ATTEMPTS
+				}, {
+					event_name: "memory.retriever_rerank.diagnostic",
+					file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+					function: "rerank",
+					site_id: "retrieval.retriever-rerank.rerank.2c5fc67dbf"
+				});
+			}
+			return {
+				candidates,
+				fallback: {
+					reason,
+					provider
+				}
+			};
+		}
+	},
+	rerankLightweight(candidates, queryVector) {
+		if (queryVector.length === 0) return candidates;
+		if (candidates.length === 0) return candidates;
+		const chunkIds = candidates.map((c) => c.chunkId).filter((id) => id !== void 0);
+		const vectorMap = chunkIds.length > 0 ? this.store.getVectorsByIds(chunkIds) : /* @__PURE__ */ new Map();
+		const wF = this.config.lightweightFusionWeight ?? .7;
+		const wC = this.config.lightweightCosineWeight ?? .3;
+		let blendedCount = 0;
+		let dimMismatchCount = 0;
+		const reranked = candidates.map((candidate) => {
+			const fusedScore = candidate.fusedScore ?? candidate.score;
+			if (!candidate.chunkId) return {
+				...candidate,
+				rerankScore: fusedScore
+			};
+			const chunkVector = vectorMap.get(candidate.chunkId);
+			if (!chunkVector) return {
+				...candidate,
+				rerankScore: fusedScore
+			};
+			if (chunkVector.length !== queryVector.length) {
+				dimMismatchCount += 1;
+				return {
+					...candidate,
+					rerankScore: fusedScore
+				};
+			}
+			const cosine = clamp01(dotProduct(queryVector, chunkVector), 0);
+			const blended = fusedScore * wF + cosine * wC;
+			const finalScore = clamp01(blended, 0);
+			blendedCount += 1;
+			return {
+				...candidate,
+				score: finalScore,
+				rerankScore: finalScore,
+				sources: {
+					...candidate.sources,
+					reranked: { score: finalScore }
+				}
+			};
+		});
+		if (dimMismatchCount > 0) log.warn("lightweight rerank: chunk vector dim mismatch on some candidates", {
+			dimMismatchCount,
+			queryDim: queryVector.length
+		}, {
+			event_name: "memory.retriever_rerank.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+			function: "rerankLightweight",
+			site_id: "retrieval.retriever-rerank.rerankLightweight.70eb2031f1"
+		});
+		log.debug("lightweight rerank applied", {
+			candidateCount: candidates.length,
+			blendedCount,
+			fusionWeight: wF,
+			cosineWeight: wC
+		}, {
+			event_name: "memory.retriever_rerank.diagnostic",
+			file: "packages/memory/src/engine/retrieval/retriever-rerank.ts",
+			function: "rerankLightweight",
+			site_id: "retrieval.retriever-rerank.rerankLightweight.7e8d0eee29"
+		});
+		return reranked.sort((a, b) => {
+			const diff = b.score - a.score;
+			if (diff !== 0) return diff;
+			return a.entry.id.localeCompare(b.entry.id);
+		});
+	},
+	getRerankSourceScore(result) {
+		return clamp01(Math.max(result.sources.bm25?.score ?? 0, result.sources.vector?.score ?? 0), 0);
+	}
+});
+//#endregion
+//#region src/engine/operations/selective-forgetting-scorer.ts
+/** @file selective-forgetting-scorer.ts
+* @purpose Computes Selective Forgetting scores from age, access history, and intrinsic value.
+* @boundary Access history, importance, timestamps, and retrieval scoring inputs.
+* @see access-tracker.ts, retriever.ts, store.ts.
+*/
+/**
+* Selective Forgetting scorer — Weibull stretched-exponential retention model
+*
+* Composite score = recencyWeight * recency + frequencyWeight * frequency + intrinsicWeight * intrinsic
+*
+* - Recency: Weibull decay with importance-modulated half-life and tier-specific beta
+* - Frequency: Logarithmic saturation with time-weighted access pattern bonus
+* - Intrinsic: importance × confidence
+*/
+const MS_PER_DAY = 864e5;
+const DEFAULT_DECAY_CONFIG = {
+	temporalDecay: true,
+	recencyHalfLifeDays: 180,
+	recencyWeight: .4,
+	frequencyWeight: .3,
+	intrinsicWeight: .3,
+	staleThreshold: .3,
+	searchBoostMin: .85,
+	importanceModulation: 1.5,
+	betaCore: .8,
+	betaWorking: 1,
+	betaPeripheral: 1.3,
+	coreDecayFloor: .9,
+	workingDecayFloor: .7,
+	peripheralDecayFloor: .5
+};
+/** Creates the Selective Forgetting scorer that blends intrinsic value, age, tier, and temporal hints. */
+function createRetentionScorer(config = DEFAULT_DECAY_CONFIG) {
+	const { temporalDecay, recencyHalfLifeDays: halfLife, recencyWeight: rw, frequencyWeight: fw, intrinsicWeight: iw, staleThreshold, importanceModulation: mu, betaCore, betaWorking, betaPeripheral } = config;
+	function betaForTier(tier) {
+		switch (tier) {
+			case "core": return betaCore;
+			case "working": return betaWorking;
+			case "peripheral": return betaPeripheral;
+		}
+	}
+	function resolveTemporalType(memory) {
+		if (memory.temporalType) return memory.temporalType;
+		if (typeof memory.metadata !== "string" || memory.metadata.length === 0) return;
+		return parseInsightMetadata(memory.metadata).memory_temporal_type;
+	}
+	function activeTimestamp(memory) {
+		return memory.accessCount > 0 ? memory.lastAccessedAt : memory.createdAt;
+	}
+	function createScoringContext(memory, now) {
+		const lastActive = activeTimestamp(memory);
+		const temporalType = resolveTemporalType(memory);
+		const baseHalfLifeDays = temporalDecay && temporalType === "dynamic" ? halfLife / 3 : halfLife;
+		return {
+			memory,
+			now,
+			lastActiveAt: lastActive,
+			daysSinceActive: Math.max(0, (now - lastActive) / MS_PER_DAY),
+			temporalType,
+			tierBeta: betaForTier(memory.tier),
+			baseHalfLifeDays
+		};
+	}
+	function evaluateRecency(context) {
+		const effectiveHalfLife = context.baseHalfLifeDays * Math.exp(mu * context.memory.importance);
+		return Math.exp(-Math.LN2 * (context.daysSinceActive / effectiveHalfLife) ** context.tierBeta);
+	}
+	function evaluateFrequency(context) {
+		const { memory } = context;
+		const base = 1 - Math.exp(-memory.accessCount / 5);
+		if (memory.accessCount <= 1) return base;
+		const avgGapDays = Math.max(1, (context.lastActiveAt - memory.createdAt) / MS_PER_DAY) / Math.max(memory.accessCount - 1, 1);
+		return base * (.5 + .5 * Math.exp(-avgGapDays / 30));
+	}
+	function evaluateIntrinsic(context) {
+		return context.memory.importance * context.memory.confidence;
+	}
+	function evaluateComponents(context) {
+		return {
+			recency: evaluateRecency(context),
+			frequency: evaluateFrequency(context),
+			intrinsic: evaluateIntrinsic(context)
+		};
+	}
+	function combineComponents(components) {
+		return rw * components.recency + fw * components.frequency + iw * components.intrinsic;
+	}
+	function scoreOne(memory, now) {
+		const components = evaluateComponents(createScoringContext(memory, now));
+		return {
+			memoryId: memory.id,
+			...components,
+			composite: combineComponents(components)
+		};
+	}
+	return {
+		score(memory, now = Date.now()) {
+			return scoreOne(memory, now);
+		},
+		scoreAll(memories, now = Date.now()) {
+			return memories.map((m) => scoreOne(m, now));
+		},
+		getStaleMemories(memories, now = Date.now()) {
+			return memories.map((m) => scoreOne(m, now)).filter((s) => s.composite < staleThreshold).sort((a, b) => a.composite - b.composite);
+		}
+	};
+}
+//#endregion
+//#region src/engine/retrieval/retriever-scoring-pipeline.ts
+/** @file retriever-scoring-pipeline.ts
+* @purpose Applies post-retrieval scoring, decay, noise, and diversity transforms.
+* @boundary Prototype-mounted MemoryRetriever methods; no constructor state ownership.
+*/
+const SEARCH_BOOST_MIN = DEFAULT_DECAY_CONFIG.searchBoostMin;
+function getTierFloor(tier) {
+	switch (tier) {
+		case "core": return DEFAULT_DECAY_CONFIG.coreDecayFloor;
+		case "working": return DEFAULT_DECAY_CONFIG.workingDecayFloor;
+		case "peripheral": return DEFAULT_DECAY_CONFIG.peripheralDecayFloor;
+	}
+}
+/**
+* Multiplier formula + retention-
+* scoring spec §62. Bounded to `[SEARCH_BOOST_MIN, 1.0]`; never amplifies,
+* only suppresses, so existing scores are an upper bound after the stage.
+*
+* - `bare`: linear interpolation `searchBoostMin + (1 - searchBoostMin) * composite`.
+* - `withFloor`: same shape but the interpolated input is
+*   `max(getTierFloor(tier), composite, recency)` so highly-decayed core
+*   memories cannot fall below the tier floor.
+*/
+function boostMultiplier(score, mode, tier) {
+	if (mode === "bare") {
+		const linear = SEARCH_BOOST_MIN + (1 - SEARCH_BOOST_MIN) * score.composite;
+		return Math.min(1, Math.max(SEARCH_BOOST_MIN, linear));
+	}
+	const candidate = Math.max(getTierFloor(tier), score.composite, score.recency);
+	const linear = SEARCH_BOOST_MIN + (1 - SEARCH_BOOST_MIN) * candidate;
+	return Math.min(1, Math.max(SEARCH_BOOST_MIN, linear));
+}
+/**
+* Adapt a `RetrievalResult.entry` into the `DecayableMemory` shape the
+* Retention Scorer consumes. `MemoryEntry` lacks `tier`, `confidence`,
+* `accessCount`, `lastAccessedAt`, and `createdAt` as native columns; all
+* five come out of the same metadata JSON the rest of the scoring pipeline
+* already parses via `parseInsightMetadata` + `parseAccessMetadata`.
+*
+* `createdAt` maps to `entry.timestamp` because `MemoryStore.store` writes
+* the caller-provided `timestamp` (or `Date.now()`) into both the entry row
+* and the embedding's creation time — there is no separate `created_at`.
+*/
+function toDecayableMemory(entry) {
+	const insight = parseInsightMetadata(entry.metadata, entry);
+	const access = parseAccessMetadata(entry.metadata);
+	const tier = insight.tier ?? "peripheral";
+	const memory = {
+		id: entry.id,
+		importance: entry.importance,
+		confidence: insight.confidence,
+		tier,
+		accessCount: access.accessCount,
+		createdAt: entry.timestamp,
+		lastAccessedAt: access.lastAccessedAt > 0 ? access.lastAccessedAt : entry.timestamp
+	};
+	if (insight.memory_temporal_type !== void 0) memory.temporalType = insight.memory_temporal_type;
+	if (entry.metadata !== void 0) memory.metadata = entry.metadata;
+	return memory;
+}
+/**
+* Run one stage of the scoring pipeline and record what it did.
+*
+* Every stage mutates scores or removes candidates, and until 2026-08-26 not one of them left
+* a trace — so a memory that reached the model and lost, and a memory some stage quietly
+* dropped, were indistinguishable after the fact. `skipReason` matters just as much: a stage
+* disabled by config returns its input untouched, which looks identical to a stage that ran
+* and changed nothing. Ported from the upstream reference's `stageCounts` + `buildDropSummary`
+* (memory-memory-lancedb-pro/src/retriever.ts:655, :303).
+*/
+function tracedStage(trace, name, skipReason, run, input) {
+	if (!trace) return run(input);
+	trace.startStage(name, input.map((result) => result.entry.id));
+	const output = run(input);
+	trace.endStage(output.map((result) => result.entry.id), output.map((result) => result.score), skipReason === void 0 ? void 0 : { skipped: skipReason });
+	return output;
+}
+Object.assign(MemoryRetriever.prototype, {
+	applyScoringPipeline(results, trace, limit = results.length) {
+		const stage = (name, skipReason, run, input) => tracedStage(trace, name, skipReason, run, input);
+		const temporalOff = !this.config.temporalWeighting;
+		let scored = stage("recency_boost", temporalOff ? "temporalWeighting" : this.config.recencyHalfLifeDays <= 0 ? "recencyHalfLifeDays" : this.config.recencyWeight <= 0 ? "recencyWeight" : void 0, (input) => temporalOff ? input : this.applyRecencyBoost(input), results);
+		scored = stage("importance_weight", void 0, (input) => this.applyImportanceWeight(input), scored);
+		scored = stage("length_normalization", this.config.lengthNormAnchor <= 0 ? "lengthNormAnchor" : void 0, (input) => this.applyLengthNormalization(input), scored);
+		scored = stage("time_decay", temporalOff ? "temporalWeighting" : this.config.timeDecayHalfLifeDays <= 0 ? "timeDecayHalfLifeDays" : void 0, (input) => temporalOff ? input : this.applyTimeDecay(input), scored);
+		scored = stage("retention_boost", temporalOff ? "temporalWeighting" : this.config.recallLifecycle?.retentionScorer === true ? void 0 : "recallLifecycle.retentionScorer", (input) => temporalOff ? input : this.applyRetentionBoost(input), scored);
+		scored = stage("hard_min_score", void 0, (input) => input.filter((result) => result.score >= this.config.hardMinScore), scored);
+		const mmrOff = experimentMmrDisabled();
+		scored = stage("mmr_diversity", mmrOff ? "experiment.disableMmr" : void 0, (input) => {
+			if (mmrOff) return input;
+			if (!this.config.mmrWindowOnly) return this.applyMmrDiversity(input);
+			const windowIds = new Set(results.slice(0, limit).map((result) => result.entry.id));
+			const window = input.filter((result) => windowIds.has(result.entry.id));
+			const tail = input.filter((result) => !windowIds.has(result.entry.id));
+			return [...this.applyMmrDiversity(window), ...tail];
+		}, scored);
+		return scored;
+	},
+	applyRecencyBoost(results) {
+		if (this.config.recencyHalfLifeDays <= 0 || this.config.recencyWeight <= 0) return results;
+		const now = Date.now();
+		const halfLifeMs = this.config.recencyHalfLifeDays * 24 * 60 * 60 * 1e3;
+		return results.map((result) => {
+			const ageMs = Math.max(0, now - result.entry.timestamp);
+			const decay = Math.exp(-Math.log(2) * ageMs / halfLifeMs);
+			return {
+				...result,
+				score: result.score + decay * this.config.recencyWeight
+			};
+		});
+	},
+	applyImportanceWeight(results) {
+		const base = this.config.importanceWeightBase ?? .7;
+		return results.map((result) => ({
+			...result,
+			score: result.score * (base + (1 - base) * result.entry.importance)
+		}));
+	},
+	applyLengthNormalization(results) {
+		if (this.config.lengthNormAnchor <= 0) return results;
+		return results.map((result) => {
+			const length = result.entry.text.length;
+			const ratio = Math.max(1, length / this.config.lengthNormAnchor);
+			const normalization = 1 / (1 + .5 * Math.log2(ratio));
+			return {
+				...result,
+				score: result.score * normalization
+			};
+		});
+	},
+	applyTimeDecay(results) {
+		if (this.config.timeDecayHalfLifeDays <= 0) return results;
+		const floor = this.config.timeDecayFloor ?? .6;
+		const now = Date.now();
+		const baseHalfLifeDays = this.config.timeDecayHalfLifeDays;
+		const reinforcementFactor = this.config.reinforcementFactor ?? .5;
+		const maxMultiplier = this.config.maxHalfLifeMultiplier ?? 3;
+		return results.map((result) => {
+			const access = parseAccessMetadata(result.entry.metadata);
+			const meta = parseInsightMetadata(result.entry.metadata, result.entry);
+			const adjustedBase = this.config.temporalDecay && meta.memory_temporal_type === "dynamic" ? baseHalfLifeDays / 3 : baseHalfLifeDays;
+			const halfLifeMs = computeEffectiveHalfLife(adjustedBase, access.accessCount, access.lastAccessedAt, reinforcementFactor, maxMultiplier, now) * 24 * 60 * 60 * 1e3;
+			const ageMs = Math.max(0, now - result.entry.timestamp);
+			const factor = floor + (1 - floor) * Math.exp(-Math.log(2) * ageMs / halfLifeMs);
+			return {
+				...result,
+				score: result.score * factor
+			};
+		});
+	},
+	applyRetentionBoost(results) {
+		const lifecycle = this._recallLifecycle;
+		if (lifecycle?.retentionScorer !== true) return results;
+		if (this._retentionScorer === void 0) this._retentionScorer = createRetentionScorer();
+		const scorer = this._retentionScorer;
+		const mode = lifecycle.tierFloorMode;
+		const now = Date.now();
+		return results.map((result) => {
+			const decayable = toDecayableMemory(result.entry);
+			const multiplier = boostMultiplier(scorer.score(decayable, now), mode, decayable.tier);
+			return {
+				...result,
+				score: result.score * multiplier
+			};
+		});
+	},
+	applyMmrDiversity(results) {
+		if (results.length === 0) return results;
+		const lambda = this.config.mmrLambda ?? .7;
+		const chunkIds = results.map((r) => r.chunkId).filter((id) => id !== void 0);
+		const vectorMap = chunkIds.length > 0 ? this.store.getVectorsByIds(chunkIds) : /* @__PURE__ */ new Map();
+		const sorted = [...results].sort((a, b) => {
+			const diff = b.score - a.score;
+			if (diff !== 0) return diff;
+			return a.entry.id.localeCompare(b.entry.id);
+		});
+		const maxScore = Math.max(sorted[0]?.score ?? 0, 1e-9);
+		const n = sorted.length;
+		const vectors = new Array(n);
+		for (let i = 0; i < n; i += 1) {
+			const id = sorted[i]?.chunkId;
+			vectors[i] = id ? vectorMap.get(id) : void 0;
+		}
+		const comparableIndices = vectors.flatMap((vector, index) => vector ? [index] : []);
+		const firstComparableIndex = comparableIndices[0];
+		const dimension = firstComparableIndex === void 0 ? void 0 : vectors[firstComparableIndex]?.length;
+		const dimensionsMatch = dimension !== void 0 && comparableIndices.every((index) => vectors[index]?.length === dimension);
+		if (firstComparableIndex === void 0 || !dimensionsMatch || comparableIndices.length < 2) return sorted.map((result) => ({
+			...result,
+			mmrScore: result.score / maxScore
+		}));
+		const maxSim = new Float64Array(n);
+		const taken = new Uint8Array(n);
+		const selected = [];
+		const seed = sorted[firstComparableIndex];
+		if (!seed) return selected;
+		taken[firstComparableIndex] = 1;
+		selected.push({
+			...seed,
+			mmrScore: seed.score / maxScore
+		});
+		let lastAdmitted = firstComparableIndex;
+		while (selected.length < comparableIndices.length) {
+			const justAddedVec = vectors[lastAdmitted];
+			if (justAddedVec) for (const i of comparableIndices) {
+				if (taken[i] === 1) continue;
+				const v = vectors[i];
+				if (!v) continue;
+				const sim = clamp01(dotProduct(v, justAddedVec), 0);
+				if (sim > (maxSim[i] ?? 0)) maxSim[i] = sim;
+			}
+			let bestIndex = -1;
+			let bestMmrScore = Number.NEGATIVE_INFINITY;
+			for (const i of comparableIndices) {
+				if (taken[i] === 1) continue;
+				const candidate = sorted[i];
+				if (!candidate) continue;
+				const mmrScore = lambda * (candidate.score / maxScore) - (1 - lambda) * (maxSim[i] ?? 0);
+				if (mmrScore > bestMmrScore) {
+					bestMmrScore = mmrScore;
+					bestIndex = i;
+				}
+			}
+			if (bestIndex === -1) break;
+			const next = sorted[bestIndex];
+			if (!next) break;
+			taken[bestIndex] = 1;
+			selected.push({
+				...next,
+				mmrScore: bestMmrScore
+			});
+			lastAdmitted = bestIndex;
+		}
+		let selectedIndex = 0;
+		return sorted.map((result, index) => {
+			if (!vectors[index]) return {
+				...result,
+				mmrScore: result.score / maxScore
+			};
+			const diversified = selected[selectedIndex];
+			selectedIndex += 1;
+			return diversified ?? {
+				...result,
+				mmrScore: result.score / maxScore
+			};
+		});
+	}
+});
+//#endregion
+//#region src/engine/retrieval/retriever-execution.ts
+/** @file retriever-execution.ts
+* @purpose Runs retrieval entrypoints, traces, and stats recording.
+* @boundary Prototype-mounted MemoryRetriever methods; no constructor state ownership.
+*/
+Object.assign(MemoryRetriever.prototype, {
+	async retrieve(input) {
+		return withLogContext({
+			operation_id: currentLogContext().operation_id ?? randomUUID(),
+			...input.external_reference !== void 0 ? {
+				external_reference: input.external_reference,
+				external_reference_visibility: input.external_reference_visibility
+			} : {}
+		}, async () => {
+			const started = performance.now();
+			const context = withServingValidityDefault({
+				...input,
+				signal: memoryOperationSignal(input.signal)
+			});
+			log.info("retrieval started", {
+				queryLength: context.query.length,
+				limit: context.limit,
+				mode: this.config.mode,
+				source: context.source
+			}, {
+				event_name: "memory.retrieval.started",
+				file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+				function: "retrieve",
+				site_id: "memory.retrieval.started"
+			});
+			const traceStartMs = Date.now();
+			try {
+				this.throwIfAborted(context);
+				const trace = new TraceCollector();
+				const isExplicitAggregation = (context.allowAggregation === true || context.source === void 0) && context.aggregation !== void 0;
+				let results;
+				if (isExplicitAggregation) results = await this.aggregationComplete(context, trace);
+				else if (this.config.mode === "vector" || !this.store.hasFtsSupport) results = await this.vectorOnly(context, trace);
+				else results = await this.precisionRecall(context, trace);
+				const beforeFinalFilter = results.length;
+				results = results.filter((result) => this.store.isMemoryOnFactSurface(result.entry.id));
+				this.throwIfAborted(context);
+				if (!isExplicitAggregation && this._accessTracker && (this._recallLifecycle?.autoRecallAccessTracking === true || context.source === "manual") && results.length > 0) this._accessTracker.recordAccess(results.map((r) => r.entry.id));
+				if (!isExplicitAggregation && this._recallLifecycle?.tierPromoter && this._tierPromoter && results.length > 0) await this.evaluateTopKTierTransitions(results);
+				const mode = isExplicitAggregation ? "aggregation" : this.config.mode === "vector" || !this.store.hasFtsSupport ? "vector" : "precision-recall";
+				const finalTrace = trace?.finalize(context.query, mode);
+				if (finalTrace && this._statsCollector) this._statsCollector.recordQuery(finalTrace, context.source ?? "unknown");
+				if (isTraceEnabled()) {
+					if (this._cachedConfigHash === void 0) this._cachedConfigHash = computeConfigHash();
+					const fallbackIds = results.map((r, i) => r.chunkId ?? `__no_chunk_id__:${r.entry.id}#${i}`);
+					const dense = collectParallelStage(results, "denseScore", fallbackIds);
+					const bm25 = collectParallelStage(results, "bm25Score", fallbackIds);
+					const fused = collectParallelStage(results, "fusedScore", fallbackIds);
+					const rerank = collectParallelStage(results, "rerankScore", fallbackIds);
+					const mmr = collectParallelStage(results, "mmrScore", fallbackIds);
+					const omitted = {};
+					if (dense.omitted.length > 0) omitted.denseScores = dense.omitted;
+					if (bm25.omitted.length > 0) omitted.bm25Scores = bm25.omitted;
+					if (fused.omitted.length > 0) omitted.fusedScores = fused.omitted;
+					if (rerank.omitted.length > 0) omitted.rerankScores = rerank.omitted;
+					if (mmr.omitted.length > 0) omitted.mmrScores = mmr.omitted;
+					const traceMetadata = Object.keys(omitted).length > 0 ? { omittedScoreArrays: omitted } : void 0;
+					const stageRecord = finalTrace?.stages.map((stage) => ({
+						name: stage.name,
+						inputCount: stage.inputCount,
+						outputCount: stage.outputCount,
+						droppedIds: stage.droppedIds,
+						outputIds: stage.outputIds,
+						scoreRange: stage.scoreRange,
+						durationMs: stage.durationMs,
+						...typeof stage.metadata?.skipped === "string" && { skipped: stage.metadata.skipped }
+					}));
+					appendQaTrace({
+						query: context.query,
+						...stageRecord && stageRecord.length > 0 && { stages: stageRecord },
+						retrievedChunkIds: results.map((r) => r.chunkId ?? ""),
+						retrievedParentMemoryIds: results.map((r) => r.entry.id),
+						...dense.values && { denseScores: dense.values },
+						...bm25.values && { bm25Scores: bm25.values },
+						...fused.values && { fusedScores: fused.values },
+						...rerank.values && { rerankScores: rerank.values },
+						...mmr.values && { mmrScores: mmr.values },
+						finalMemoryScores: results.map((r) => r.score),
+						embedderProvider: this.embedder.providerKind,
+						embedderModel: this.embedder.model,
+						embedderDim: this.embedder.dimensions,
+						chunkingVersion: CHUNKING_VERSION,
+						configHash: this._cachedConfigHash,
+						timestampMs: traceStartMs,
+						latencyMs: performance.now() - started,
+						...traceMetadata && { traceMetadata }
+					});
+				}
+				log.info("Memory retrieval completed", {
+					store_reference: privateLogReference(this.store.dbPath),
+					outcome: results.length ? "success" : "empty_success",
+					duration_ms: performance.now() - started,
+					mode,
+					scope_count: context.scopeFilter?.length ?? "unavailable",
+					result_count: results.length,
+					final_filter_removed_count: beforeFinalFilter - results.length,
+					config_hash: this._cachedConfigHash ?? computeConfigHash(),
+					fts_available: this.store.hasFtsSupport,
+					stages: finalTrace?.stages.map(({ name, inputCount, outputCount, scoreRange, durationMs, metadata }) => ({
+						name,
+						inputCount,
+						outputCount,
+						scoreRange,
+						durationMs,
+						metadata
+					})),
+					trace_available: isTraceEnabled()
+				}, {
+					event_name: "memory.retrieval.completed",
+					file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+					function: "retrieve",
+					site_id: "memory.retrieval.completed"
+				});
+				return results;
+			} catch (error) {
+				log.error("Memory retrieval failed", {
+					outcome: "failed",
+					error,
+					duration_ms: performance.now() - started
+				}, {
+					event_name: "memory.retrieval.completed",
+					file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+					function: "retrieve",
+					site_id: "memory.retrieval.failed"
+				});
+				throw new RetrievalError("Failed to retrieve memories", error);
+			}
+		});
+	},
+	async retrieveWithTrace(input) {
+		return withLogContext({
+			operation_id: currentLogContext().operation_id ?? randomUUID(),
+			...input.external_reference !== void 0 ? {
+				external_reference: input.external_reference,
+				external_reference_visibility: input.external_reference_visibility
+			} : {}
+		}, async () => {
+			const started = performance.now();
+			const context = withServingValidityDefault({
+				...input,
+				signal: memoryOperationSignal(input.signal)
+			});
+			try {
+				this.throwIfAborted(context);
+				const trace = new TraceCollector();
+				const isExplicitAggregation = (context.allowAggregation === true || context.source === void 0) && context.aggregation !== void 0;
+				let results;
+				if (isExplicitAggregation) results = await this.aggregationComplete(context, trace);
+				else if (this.config.mode === "vector" || !this.store.hasFtsSupport) results = await this.vectorOnly(context, trace);
+				else results = await this.precisionRecall(context, trace);
+				results = results.filter((result) => this.store.isMemoryOnFactSurface(result.entry.id));
+				this.throwIfAborted(context);
+				const mode = isExplicitAggregation ? "aggregation" : this.config.mode === "vector" || !this.store.hasFtsSupport ? "vector" : "precision-recall";
+				const finalTrace = trace.finalize(context.query, mode);
+				if (!isExplicitAggregation && this._accessTracker && (this._recallLifecycle?.autoRecallAccessTracking === true || context.source === "manual") && results.length > 0) this._accessTracker.recordAccess(results.map((r) => r.entry.id));
+				if (!isExplicitAggregation && this._recallLifecycle?.tierPromoter && this._tierPromoter && results.length > 0) await this.evaluateTopKTierTransitions(results);
+				if (this._statsCollector) this._statsCollector.recordQuery(finalTrace, context.source ?? "debug");
+				log.info("Traced memory retrieval completed", {
+					outcome: results.length ? "success" : "empty_success",
+					store_reference: privateLogReference(this.store.dbPath),
+					duration_ms: performance.now() - started,
+					mode,
+					result_count: results.length,
+					stages: finalTrace.stages.map(({ name, inputCount, outputCount, scoreRange, durationMs, metadata }) => ({
+						name,
+						inputCount,
+						outputCount,
+						scoreRange,
+						durationMs,
+						metadata
+					}))
+				}, {
+					event_name: "memory.retrieval.completed",
+					file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+					function: "retrieveWithTrace",
+					site_id: "memory.retrieval.traced.completed"
+				});
+				return {
+					results,
+					trace: finalTrace
+				};
+			} catch (error) {
+				log.error("Traced memory retrieval failed", {
+					outcome: "failed",
+					error,
+					duration_ms: performance.now() - started
+				}, {
+					event_name: "memory.retrieval.completed",
+					file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+					function: "retrieveWithTrace",
+					site_id: "memory.retrieval.traced.failed"
+				});
+				throw new RetrievalError("Failed to retrieve memories", error);
+			}
+		});
+	},
+	/**
+	* Phase 0 §5: evaluate tier promotion/demotion for the top-K retrieved
+	* memories and persist any non-null transition via `store.updateTier`.
+	*
+	* Per-item try/catch isolates evaluator and persistence failures so one
+	* bad memory cannot block the rest. The retention scorer is instantiated
+	* lazily on the retriever instance — synthesizing `DecayableMemory` from
+	* `entry.metadata` keeps this hot-path read-only against the store.
+	*
+	* Callers gate on `recallLifecycle.tierPromoter`; this method assumes the
+	* flag is on and `_tierPromoter` is set.
+	*/
+	async evaluateTopKTierTransitions(results) {
+		const promoter = this._tierPromoter;
+		if (!promoter) return;
+		const topK = this._recallLifecycle?.tierPromotionTopK ?? results.length;
+		if (!this._retentionScorer) this._retentionScorer = createRetentionScorer();
+		const scorer = this._retentionScorer;
+		const now = Date.now();
+		const slice = results.slice(0, Math.max(0, topK));
+		for (const r of slice) try {
+			const entry = r.entry;
+			const access = parseAccessMetadata(entry.metadata);
+			const insight = parseInsightMetadata(entry.metadata, entry);
+			const tier = insight.tier ?? "peripheral";
+			const confidence = insight.confidence ?? .7;
+			const decayable = {
+				id: entry.id,
+				importance: entry.importance,
+				confidence,
+				tier,
+				accessCount: access.accessCount,
+				createdAt: entry.timestamp,
+				lastAccessedAt: access.lastAccessedAt || entry.timestamp,
+				metadata: entry.metadata,
+				...insight.memory_temporal_type && { temporalType: insight.memory_temporal_type }
+			};
+			const score = scorer.score(decayable, now);
+			const tierableMemory = {
+				id: entry.id,
+				tier,
+				importance: entry.importance,
+				accessCount: access.accessCount,
+				timestamp: entry.timestamp
+			};
+			const transition = promoter.evaluate(tierableMemory, score, now);
+			if (!transition || transition.toTier === tier) continue;
+			await this.store.updateTier(entry.id, transition.toTier, { writerAuthority: "offline-family" });
+		} catch (error) {
+			log.warn("tier evaluation failed for memory", {
+				memoryId: r.entry.id,
+				error
+			}, {
+				event_name: "memory.retrieval.tier.failed",
+				file: "packages/memory/src/engine/retrieval/retriever-execution.ts",
+				function: "evaluateTopKTierTransitions",
+				site_id: "memory.retrieval.tier.failed"
+			});
+		}
+	}
+});
+//#endregion
+export { DEFAULT_RETRIEVAL_CONFIG as a, createRetriever as i, MemoryRetriever as n, withServingValidityDefault as o, RERANK_FALLBACK_REASONS as r, collectParallelStage as t };