@tangle-network/agent-knowledge 5.0.4 → 6.1.0

package/dist/benchmarks-CmW6iORW.js

@@ -0,0 +1,2718 @@
+import { r as stableId, t as sha256 } from "./ids-DRqPZ42_.js";
+import { n as searchKnowledge } from "./search-CP0QtBJZ.js";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { canonicalJson } from "@tangle-network/agent-eval";
+import { acquireSingleRunLock, createRunCostLedger, fsCampaignStorage, resolveRunDir, runCampaign } from "@tangle-network/agent-eval/campaign";
+//#region src/retrieval-eval.ts
+function retrievalConfigSurface(config) {
+	return canonicalJson(config);
+}
+function retrievalConfigFromSurface(surface) {
+	if (typeof surface !== "string") throw new Error(`retrievalConfigFromSurface expected a JSON string surface, got ${typeof surface}`);
+	let parsed;
+	try {
+		parsed = JSON.parse(surface);
+	} catch (error) {
+		throw new Error(`retrievalConfigFromSurface could not parse JSON: ${error.message}`);
+	}
+	if (!isJsonObject(parsed)) throw new Error("retrievalConfigFromSurface expected a JSON object");
+	return parsed;
+}
+function buildRetrievalEvalDispatch(options) {
+	if (!options.retrieve && !options.index) throw new Error("buildRetrievalEvalDispatch requires either index or retrieve");
+	const defaultK = options.defaultK ?? 5;
+	const retrieve = options.retrieve ?? defaultSearchRetriever;
+	return async (surface, scenario, context) => {
+		const config = retrievalConfigFromSurface(surface);
+		const k = retrievalK(config, scenario, defaultK);
+		const startedAt = Date.now();
+		const normalized = normalizeRetrieverResult(await retrieve({
+			index: options.index,
+			config,
+			scenario,
+			k,
+			signal: context.signal,
+			context
+		}));
+		return {
+			config,
+			query: scenario.query,
+			requestedK: k,
+			hits: normalized.hits,
+			durationMs: Date.now() - startedAt,
+			costUsd: normalized.costUsd,
+			metadata: normalized.metadata
+		};
+	};
+}
+function retrievalRecallJudge(options = {}) {
+	const weights = normalizeWeights(options.weights ?? { recall: 1 });
+	return {
+		name: options.name ?? "retrieval-recall",
+		dimensions: [
+			{
+				key: "recall",
+				description: "fraction of expected knowledge targets retrieved"
+			},
+			{
+				key: "mrr",
+				description: "reciprocal rank of the first matching hit"
+			},
+			{
+				key: "ndcg",
+				description: "rank-aware gain for newly matched targets"
+			},
+			{
+				key: "precision_at_k",
+				description: "share of returned hits that match at least one target"
+			}
+		],
+		appliesTo: (scenario) => scenario.kind === "retrieval-eval",
+		async score({ artifact, scenario }) {
+			const metrics = scoreRetrievalArtifact(artifact, scenario);
+			const composite = (metrics.recall * weights.recall + metrics.mrr * weights.mrr + metrics.ndcg * weights.ndcg + metrics.precisionAtK * weights.precisionAtK) / (weights.recall + weights.mrr + weights.ndcg + weights.precisionAtK);
+			return {
+				dimensions: {
+					recall: metrics.recall,
+					mrr: metrics.mrr,
+					ndcg: metrics.ndcg,
+					precision_at_k: metrics.precisionAtK
+				},
+				composite,
+				notes: `matched ${metrics.matchedCount}/${metrics.expectedCount}; first_hit_rank=${metrics.firstHitRank ?? "none"}`
+			};
+		}
+	};
+}
+function scoreRetrievalArtifact(artifact, scenario) {
+	const targets = normalizeTargets(scenario.expected);
+	if (targets.length === 0) throw new Error(`retrieval eval scenario ${scenario.id} has no expected targets`);
+	const matchedTargetIds = /* @__PURE__ */ new Set();
+	let firstHitRank = null;
+	let relevantHitCount = 0;
+	let dcg = 0;
+	for (const hit of artifact.hits) {
+		const newlyMatched = targets.filter((target) => {
+			const targetId = retrievalTargetId(target);
+			return !matchedTargetIds.has(targetId) && hitMatchesTarget(hit, target);
+		});
+		if (newlyMatched.length === 0) continue;
+		relevantHitCount += 1;
+		if (firstHitRank === null) firstHitRank = hit.rank;
+		dcg += 1 / Math.log2(hit.rank + 1);
+		for (const target of newlyMatched) matchedTargetIds.add(retrievalTargetId(target));
+	}
+	const expectedCount = targets.length;
+	const matchedCount = matchedTargetIds.size;
+	const idcg = idealDcg(Math.min(expectedCount, Math.max(1, artifact.requestedK)));
+	return {
+		recall: matchedCount / expectedCount,
+		mrr: firstHitRank === null ? 0 : 1 / firstHitRank,
+		ndcg: idcg === 0 ? 0 : dcg / idcg,
+		precisionAtK: artifact.hits.length === 0 ? 0 : relevantHitCount / artifact.hits.length,
+		expectedCount,
+		matchedCount,
+		relevantHitCount,
+		firstHitRank,
+		matchedTargetIds: [...matchedTargetIds].sort()
+	};
+}
+function partitionRetrievalScenarios(scenarios, options = {}) {
+	if (scenarios.length < 4) throw new Error("partitionRetrievalScenarios requires at least 4 scenarios for non-empty train and selection partitions plus 2 final scenarios");
+	const selectionFraction = options.selectionFraction ?? .2;
+	const finalFraction = options.finalFraction ?? .2;
+	assertPartitionFraction(selectionFraction, "selectionFraction");
+	assertPartitionFraction(finalFraction, "finalFraction");
+	if (selectionFraction + finalFraction >= 1) throw new Error("selectionFraction + finalFraction must be less than 1");
+	const shuffled = seededShuffle(scenarios, options.seed ?? 42);
+	const finalCount = Math.max(2, Math.round(shuffled.length * finalFraction));
+	const selectionCount = Math.max(1, Math.round(shuffled.length * selectionFraction));
+	if (finalCount + selectionCount >= shuffled.length) throw new Error("retrieval scenario fractions leave no training scenarios");
+	const trainEnd = shuffled.length - selectionCount - finalCount;
+	return {
+		trainScenarios: shuffled.slice(0, trainEnd),
+		selectionScenarios: shuffled.slice(trainEnd, trainEnd + selectionCount),
+		finalScenarios: shuffled.slice(trainEnd + selectionCount)
+	};
+}
+function assertPartitionFraction(value, name) {
+	if (!Number.isFinite(value) || value <= 0 || value >= 1) throw new Error(`${name} must be greater than 0 and less than 1`);
+}
+function retrievalK(config, scenario, defaultK) {
+	const rawK = config.k ?? config.topK ?? scenario.k ?? defaultK;
+	if (typeof rawK !== "number" || !Number.isFinite(rawK) || rawK <= 0) throw new Error(`retrieval k must be a positive number, got ${String(rawK)}`);
+	return Math.floor(rawK);
+}
+async function defaultSearchRetriever(input) {
+	if (!input.index) throw new Error("default retrieval eval search requires an index");
+	return { hits: searchKnowledge(input.index, input.scenario.query, input.k).map(hitFromSearchResult) };
+}
+function hitFromSearchResult(result) {
+	return {
+		pageId: result.page.id,
+		path: result.page.path,
+		title: result.page.title,
+		rank: result.rank,
+		score: result.score,
+		normalizedScore: result.normalizedScore,
+		sourceIds: result.page.sourceIds,
+		snippet: result.snippet
+	};
+}
+function normalizeRetrieverResult(result) {
+	if (isHitArray(result)) return { hits: result };
+	return result;
+}
+function normalizeTargets(expected) {
+	return isTargetArray(expected) ? [...expected] : [expected];
+}
+function isHitArray(result) {
+	return Array.isArray(result);
+}
+function isTargetArray(expected) {
+	return Array.isArray(expected);
+}
+function hitMatchesTarget(hit, target) {
+	switch (target.kind) {
+		case "page": return hit.pageId === target.pageId;
+		case "page-path": return hit.path === target.path;
+		case "source": return Boolean(hit.sourceIds?.includes(target.sourceId));
+		case "source-anchor": return Boolean(hit.sourceSpans?.some((span) => span.sourceId === target.sourceId && span.anchorId === target.anchorId));
+		case "source-span": return Boolean(hit.sourceSpans?.some((span) => span.sourceId === target.sourceId && spanOverlaps(span, target)));
+	}
+}
+function spanOverlaps(hit, target) {
+	if (typeof hit.charStart !== "number" || typeof hit.charEnd !== "number") return false;
+	return hit.charStart < target.charEnd && target.charStart < hit.charEnd;
+}
+function retrievalTargetId(target) {
+	switch (target.kind) {
+		case "page": return `page:${target.pageId}`;
+		case "page-path": return `page-path:${target.path}`;
+		case "source": return `source:${target.sourceId}`;
+		case "source-anchor": return `source-anchor:${target.sourceId}:${target.anchorId}`;
+		case "source-span": return `source-span:${target.sourceId}:${target.charStart}:${target.charEnd}`;
+	}
+}
+function idealDcg(count) {
+	let score = 0;
+	for (let i = 1; i <= count; i += 1) score += 1 / Math.log2(i + 1);
+	return score;
+}
+function normalizeWeights(weights) {
+	const normalized = {
+		recall: normalizeWeight(weights.recall),
+		mrr: normalizeWeight(weights.mrr),
+		ndcg: normalizeWeight(weights.ndcg),
+		precisionAtK: normalizeWeight(weights.precisionAtK)
+	};
+	if (normalized.recall + normalized.mrr + normalized.ndcg + normalized.precisionAtK <= 0) throw new Error("retrievalRecallJudge requires at least one positive metric weight");
+	return normalized;
+}
+function normalizeWeight(value) {
+	if (value === void 0) return 0;
+	if (!Number.isFinite(value) || value < 0) throw new Error(`retrievalRecallJudge metric weights must be non-negative finite numbers, got ${String(value)}`);
+	return value;
+}
+function isJsonObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function seededShuffle(items, seed) {
+	const out = [...items];
+	let state = seed >>> 0;
+	for (let i = out.length - 1; i > 0; i -= 1) {
+		state = state * 1664525 + 1013904223 >>> 0;
+		const j = state % (i + 1);
+		[out[i], out[j]] = [out[j], out[i]];
+	}
+	return out;
+}
+//#endregion
+//#region src/memory/source-record.ts
+function memoryHitToSourceRecord(hit, options = {}) {
+	const contentHash = sha256(`${hit.uri}\n${hit.text}`);
+	return {
+		id: stableId("src", `${hit.uri}:${contentHash}`),
+		uri: hit.uri,
+		title: hit.title ?? `${hit.kind}:${hit.id}`,
+		mediaType: "text/plain",
+		contentHash,
+		text: hit.text,
+		validUntil: hit.validUntil,
+		lastVerifiedAt: hit.lastVerifiedAt,
+		createdAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+		metadata: {
+			...hit.metadata ?? {},
+			source: "agent-memory",
+			memoryId: hit.id,
+			memoryKind: hit.kind,
+			score: hit.score,
+			normalizedScore: hit.normalizedScore,
+			confidence: hit.confidence,
+			scope: options.scope
+		}
+	};
+}
+function memoryWriteResultToSourceRecord(result, text, options = {}) {
+	return memoryHitToSourceRecord({
+		id: result.id,
+		uri: result.uri,
+		kind: result.kind,
+		text,
+		metadata: result.metadata
+	}, options);
+}
+//#endregion
+//#region src/benchmarks/adapters.ts
+function createNoopMemoryBenchmarkAdapter(id = "no-memory") {
+	return {
+		id,
+		branchIsolation: { mode: "scoped" },
+		async search() {
+			return [];
+		},
+		async getContext(query) {
+			return {
+				query,
+				text: "",
+				hits: [],
+				sourceRecords: []
+			};
+		},
+		async write(input) {
+			return {
+				accepted: false,
+				id: input.id ?? `${id}:ignored`,
+				uri: `memory://${id}/ignored`,
+				kind: input.kind
+			};
+		},
+		async clear() {},
+		async flush() {}
+	};
+}
+function createInMemoryBenchmarkAdapter(options = {}) {
+	const id = options.id ?? "in-memory";
+	const rows = [];
+	let seq = 0;
+	const adapter = {
+		id,
+		branchIsolation: { mode: "scoped" },
+		async search(query, searchOptions = {}) {
+			return rows.filter((row) => memoryScopeMatches(row.input.scope, searchOptions.scope)).filter((row) => !searchOptions.kinds?.length || searchOptions.kinds.includes(row.hit.kind)).map((row) => {
+				const lexical = tokenOverlap(query, row.hit.text);
+				const recency = row.seq / Math.max(1, seq);
+				return {
+					...row.hit,
+					score: lexical + recency * .01,
+					normalizedScore: lexical
+				};
+			}).filter((hit) => searchOptions.minScore === void 0 ? true : hit.score >= searchOptions.minScore).sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, searchOptions.limit ?? 5);
+		},
+		async getContext(query, searchOptions = {}) {
+			const hits = await adapter.search(query, searchOptions);
+			return {
+				query,
+				hits,
+				sourceRecords: hits.map((hit) => memoryHitToSourceRecord(hit, { scope: searchOptions.scope })),
+				text: renderMemoryHits(hits)
+			};
+		},
+		async write(input) {
+			seq += 1;
+			const memoryId = input.id ?? `${id}:${seq}`;
+			const hit = {
+				id: memoryId,
+				uri: `memory://${id}/${encodeURIComponent(memoryId)}`,
+				kind: input.kind,
+				text: input.text,
+				title: input.title,
+				score: 1,
+				normalizedScore: 1,
+				createdAt: input.metadata?.timestamp,
+				metadata: {
+					...input.metadata ?? {},
+					scope: input.scope
+				}
+			};
+			rows.push({
+				seq,
+				input,
+				hit
+			});
+			return {
+				accepted: true,
+				id: memoryId,
+				uri: hit.uri,
+				kind: input.kind,
+				sourceRecord: memoryWriteResultToSourceRecord({
+					accepted: true,
+					id: memoryId,
+					uri: hit.uri,
+					kind: input.kind,
+					metadata: hit.metadata
+				}, input.text, { scope: input.scope }),
+				metadata: hit.metadata
+			};
+		},
+		async clear(scope) {
+			for (let index = rows.length - 1; index >= 0; index -= 1) if (memoryScopeMatches(rows[index].input.scope, scope)) rows.splice(index, 1);
+		},
+		async flush() {}
+	};
+	return adapter;
+}
+function memoryEventId(hit) {
+	const eventId = hit.metadata?.eventId;
+	return typeof eventId === "string" ? eventId : void 0;
+}
+function memoryActorId(hit) {
+	const actorId = hit.metadata?.actorId;
+	return typeof actorId === "string" ? actorId : void 0;
+}
+function memoryScopeMatches(stored, requested) {
+	if (!requested) return true;
+	if (requested.tenantId !== void 0 && stored?.tenantId !== requested.tenantId) return false;
+	if (requested.userId !== void 0 && stored?.userId !== requested.userId) return false;
+	if (requested.agentId !== void 0 && stored?.agentId !== requested.agentId) return false;
+	if (requested.teamId !== void 0 && stored?.teamId !== requested.teamId) return false;
+	if (requested.runId !== void 0 && stored?.runId !== requested.runId) return false;
+	if (requested.sessionId !== void 0 && stored?.sessionId !== requested.sessionId) return false;
+	if (requested.namespace !== void 0 && stored?.namespace !== requested.namespace) return false;
+	for (const [key, value] of Object.entries(requested.tags ?? {})) if (stored?.tags?.[key] !== value) return false;
+	return true;
+}
+function tokenOverlap(query, text) {
+	const queryTokens = new Set(tokenize(query));
+	if (queryTokens.size === 0) return 0;
+	const textTokens = new Set(tokenize(text));
+	let matched = 0;
+	for (const token of queryTokens) if (textTokens.has(token)) matched += 1;
+	return matched / queryTokens.size;
+}
+function tokenize(text) {
+	const stop = /* @__PURE__ */ new Set([
+		"the",
+		"and",
+		"for",
+		"this",
+		"that",
+		"with",
+		"what",
+		"should",
+		"agent",
+		"user",
+		"current",
+		"now",
+		"use"
+	]);
+	return text.toLowerCase().split(/[^a-z0-9/]+/).filter((token) => token.length > 2 && !stop.has(token));
+}
+function renderMemoryHits(hits) {
+	return hits.map((hit, index) => {
+		const eventId = memoryEventId(hit);
+		const actorId = memoryActorId(hit);
+		return [
+			`[${index + 1}] ${hit.title ?? hit.id}`,
+			eventId ? `event=${eventId}` : "",
+			actorId ? `actor=${actorId}` : "",
+			hit.text
+		].filter(Boolean).join("\n");
+	}).join("\n\n");
+}
+//#endregion
+//#region src/benchmarks/utils.ts
+function mean(values) {
+	const finite = values.filter(Number.isFinite);
+	if (finite.length === 0) return 0;
+	return finite.reduce((sum, value) => sum + value, 0) / finite.length;
+}
+function unique(values) {
+	return [...new Set(values.filter(Boolean))];
+}
+function formatNumber(value) {
+	if (!Number.isFinite(value)) return "0";
+	return value.toFixed(value === 0 || Math.abs(value) >= 10 ? 0 : 3);
+}
+function normalizeUsd(value) {
+	return Number(value.toFixed(12));
+}
+function compactObject(value) {
+	if (Array.isArray(value)) return value.map(compactObject);
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0).map(([key, entry]) => [key, compactObject(entry)]));
+}
+//#endregion
+//#region src/benchmarks/validation.ts
+function isKnowledgeMemoryBenchmarkCase(testCase) {
+	return testCase.taskKind.startsWith("memory-");
+}
+function assertKnowledgeBenchmarkCases(cases) {
+	if (cases.length === 0) throw new Error("knowledge benchmark requires cases");
+	assertUniqueNonEmptyStrings(cases.map((testCase) => testCase.id), "knowledge benchmark case id");
+	for (const testCase of cases) {
+		if (typeof testCase.family !== "string" || !testCase.family.trim()) throw new Error(`knowledge benchmark case ${testCase.id} requires a family`);
+		if (testCase.taskKind === "retrieval") continue;
+		if (isKnowledgeMemoryBenchmarkCase(testCase)) {
+			assertUniqueNonEmptyStrings(testCase.events.map((event) => event.id), `${testCase.id} memory event id`);
+			for (const event of testCase.events) assertNonEmptyBenchmarkString(event.text, `${testCase.id} memory event ${event.id} text`);
+			assertClaimMatchers(testCase.requiredFacts ?? [], `${testCase.id} requiredFacts`);
+			assertClaimMatchers(testCase.forbiddenFacts ?? [], `${testCase.id} forbiddenFacts`);
+			assertUniqueNonEmptyStrings(testCase.expectedEventIds ?? [], `${testCase.id} expected event id`);
+			assertUniqueNonEmptyStrings(testCase.expectedActorIds ?? [], `${testCase.id} expected actor id`);
+		} else {
+			assertClaimMatchers(testCase.requiredClaims ?? [], `${testCase.id} requiredClaims`);
+			assertClaimMatchers(testCase.forbiddenClaims ?? [], `${testCase.id} forbiddenClaims`);
+			assertUniqueNonEmptyStrings(testCase.expectedSourceIds ?? [], `${testCase.id} source id`);
+		}
+	}
+}
+function assertClaimMatchers(claims, label) {
+	assertUniqueNonEmptyStrings(claims.map((claim) => claim.id), `${label} matcher id`);
+	for (const claim of claims) {
+		if (claim.anyOf.length === 0) throw new Error(`${label} matcher ${claim.id} requires anyOf`);
+		assertUniqueNonEmptyStrings(claim.anyOf, `${label} matcher ${claim.id} anyOf`);
+		if (claim.weight !== void 0 && (!Number.isFinite(claim.weight) || claim.weight <= 0)) throw new Error(`${label} matcher ${claim.id} weight must be a positive finite number`);
+		const sourceEventIds = claim.sourceEventIds;
+		if (sourceEventIds !== void 0) assertUniqueNonEmptyStrings(sourceEventIds, `${label} matcher ${claim.id} source event id`);
+	}
+}
+function assertUniqueNonEmptyStrings(values, label) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of values) {
+		assertNonEmptyBenchmarkString(value, label);
+		if (seen.has(value)) throw new Error(`duplicate ${label}: ${value}`);
+		seen.add(value);
+	}
+}
+function assertNonEmptyBenchmarkString(value, label) {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be non-empty`);
+}
+//#endregion
+//#region src/benchmarks/catalog.ts
+const INDUSTRY_RAG_BENCHMARKS = [
+	{
+		id: "beir",
+		family: "beir",
+		taskKind: "retrieval",
+		primaryMetrics: [
+			"nDCG@10",
+			"Recall@100",
+			"MRR@10"
+		],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Classic zero-shot retrieval suites using query/corpus/qrels files."
+	},
+	{
+		id: "mteb-retrieval",
+		family: "mteb-retrieval",
+		taskKind: "retrieval",
+		primaryMetrics: ["nDCG@10", "Recall@100"],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "MTEB retrieval task shape; same qrels bridge, different dataset provenance."
+	},
+	{
+		id: "msmarco",
+		family: "msmarco",
+		taskKind: "retrieval",
+		primaryMetrics: ["MRR@10", "Recall@100"],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Passage retrieval and reranking smoke for web-style questions."
+	},
+	{
+		id: "trec-dl",
+		family: "trec-dl",
+		taskKind: "retrieval",
+		primaryMetrics: [
+			"nDCG@10",
+			"MAP",
+			"Recall@100"
+		],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Deep Learning Track judgments over MS MARCO-derived corpora."
+	},
+	{
+		id: "miracl",
+		family: "miracl",
+		taskKind: "retrieval",
+		primaryMetrics: ["nDCG@10", "Recall@100"],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Multilingual retrieval; use language tags on cases."
+	},
+	{
+		id: "lotte",
+		family: "lotte",
+		taskKind: "retrieval",
+		primaryMetrics: ["Success@5", "Recall@100"],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Long-tail search tasks; map collection/domain into tags."
+	},
+	{
+		id: "bright",
+		family: "bright",
+		taskKind: "retrieval",
+		primaryMetrics: ["nDCG@10", "Recall@100"],
+		adapter: "buildRetrievalBenchmarkCasesFromQrels",
+		notes: "Reasoning-heavy retrieval; preserve domain tags for slice reporting."
+	},
+	{
+		id: "crag",
+		family: "crag",
+		taskKind: "rag-answer",
+		primaryMetrics: [
+			"claim_recall",
+			"citation_recall",
+			"hallucination_safe"
+		],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Answer quality and freshness cases; use required/forbidden claims plus citations."
+	},
+	{
+		id: "hotpotqa",
+		family: "hotpotqa",
+		taskKind: "rag-answer",
+		primaryMetrics: ["claim_recall", "citation_recall"],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Multihop QA; encode each supporting fact as a required claim."
+	},
+	{
+		id: "kilt",
+		family: "kilt",
+		taskKind: "rag-answer",
+		primaryMetrics: ["claim_recall", "citation_recall"],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Knowledge-intensive generation with provenance; encode expected pages/sources."
+	},
+	{
+		id: "ragtruth",
+		family: "ragtruth",
+		taskKind: "hallucination",
+		primaryMetrics: ["hallucination_safe", "forbidden_claim_rate"],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Hallucination detection; encode hallucinated spans as forbidden claims."
+	},
+	{
+		id: "faithbench",
+		family: "faithbench",
+		taskKind: "hallucination",
+		primaryMetrics: ["hallucination_safe", "forbidden_claim_rate"],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Faithfulness benchmark; score unsupported claims as forbidden claims."
+	},
+	{
+		id: "first-party/kb-improvement",
+		family: "first-party",
+		taskKind: "kb-improvement",
+		primaryMetrics: [
+			"claim_recall",
+			"hallucination_safe",
+			"score"
+		],
+		adapter: "KnowledgeAnswerBenchmarkCase",
+		notes: "Project-owned candidate-KB validation; grade the produced KB text or answer bundle."
+	}
+];
+const INDUSTRY_MEMORY_BENCHMARKS = [
+	{
+		id: "locomo/qa",
+		family: "locomo",
+		taskKind: "memory-recall",
+		primaryMetrics: ["memory_fact_recall", "memory_event_recall"],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Long-term conversational QA over multi-session histories."
+	},
+	{
+		id: "locomo/event-summary",
+		family: "locomo",
+		taskKind: "memory-summarization",
+		primaryMetrics: ["memory_fact_recall", "memory_event_recall"],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Event summarization over long conversational histories."
+	},
+	{
+		id: "longmemeval",
+		family: "longmemeval",
+		taskKind: "memory-temporal",
+		primaryMetrics: [
+			"memory_fact_recall",
+			"memory_stale_safe",
+			"memory_event_recall"
+		],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Long-term assistant memory with temporal and update-sensitive probes."
+	},
+	{
+		id: "longmemeval-v2",
+		family: "longmemeval-v2",
+		taskKind: "memory-reasoning",
+		primaryMetrics: [
+			"memory_fact_recall",
+			"memory_event_recall",
+			"score"
+		],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Experience reuse from long agent histories; track accuracy and latency."
+	},
+	{
+		id: "memora",
+		family: "memora",
+		taskKind: "memory-update",
+		primaryMetrics: [
+			"memory_fact_recall",
+			"memory_stale_safe",
+			"memory_stale_rate"
+		],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Forgetting-aware memory accuracy: reward current facts and penalize obsolete ones."
+	},
+	{
+		id: "memoryagentbench",
+		family: "memoryagentbench",
+		taskKind: "memory-ingest",
+		primaryMetrics: ["memory_fact_recall", "memory_event_recall"],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Incremental multi-turn information intake before later recall."
+	},
+	{
+		id: "memorybank",
+		family: "memorybank",
+		taskKind: "memory-recommendation",
+		primaryMetrics: ["memory_fact_recall", "memory_stale_safe"],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Personalized memory use for preference-aware downstream choices."
+	},
+	{
+		id: "groupmembench",
+		family: "groupmembench",
+		taskKind: "memory-multiparty",
+		primaryMetrics: [
+			"memory_fact_recall",
+			"memory_actor_recall",
+			"memory_stale_safe"
+		],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Multi-party memory with speaker attribution, update, and term ambiguity pressure."
+	},
+	{
+		id: "first-party/memory-lifecycle",
+		family: "first-party",
+		taskKind: "memory-forgetting",
+		primaryMetrics: [
+			"memory_fact_recall",
+			"memory_stale_safe",
+			"memory_event_recall"
+		],
+		adapter: "KnowledgeMemoryBenchmarkCase",
+		notes: "Project-owned lifecycle pack for ingest, recall, update, forgetting, and ambiguity."
+	}
+];
+function buildIndustryRagBenchmarkSmokeCases(specs = INDUSTRY_RAG_BENCHMARKS) {
+	return specs.map((spec) => {
+		const source = {
+			name: spec.id,
+			version: "smoke"
+		};
+		const split = spec.taskKind === "retrieval" ? "search" : "holdout";
+		const tags = unique([
+			"industry-smoke",
+			spec.id,
+			spec.family,
+			spec.taskKind
+		]);
+		if (spec.taskKind === "retrieval") return {
+			id: `${spec.id}/smoke:q1`,
+			family: spec.family,
+			taskKind: "retrieval",
+			split,
+			tags,
+			source,
+			query: `${spec.id} smoke retrieval query`,
+			expected: [{
+				kind: "page",
+				pageId: `${spec.id}:doc-1`
+			}],
+			k: 5,
+			metadata: {
+				adapter: spec.adapter,
+				primaryMetrics: spec.primaryMetrics
+			}
+		};
+		return {
+			id: `${spec.id}/smoke:q1`,
+			family: spec.family,
+			taskKind: spec.taskKind,
+			split,
+			tags,
+			source,
+			prompt: `${spec.id} smoke benchmark prompt`,
+			requiredClaims: [{
+				id: `${spec.id}:required`,
+				anyOf: [`${spec.id} supported answer`]
+			}],
+			forbiddenClaims: [{
+				id: `${spec.id}:unsupported`,
+				anyOf: [`${spec.id} unsupported claim`]
+			}],
+			expectedSourceIds: [`${spec.id}:source-1`],
+			referenceAnswer: `${spec.id} supported answer`,
+			metadata: {
+				adapter: spec.adapter,
+				primaryMetrics: spec.primaryMetrics
+			}
+		};
+	});
+}
+function respondToIndustryRagBenchmarkSmokeCase(input) {
+	const testCase = input.case;
+	if (isKnowledgeMemoryBenchmarkCase(testCase)) return respondToIndustryMemoryBenchmarkSmokeCase({ case: testCase });
+	if (testCase.taskKind === "retrieval") return {
+		hits: [hitForExpectedTarget(Array.isArray(testCase.expected) ? testCase.expected[0] : testCase.expected, testCase.id)],
+		durationMs: 1,
+		metadata: { smoke: true }
+	};
+	return {
+		answer: (testCase.requiredClaims ?? []).map((claim) => claim.anyOf[0]).filter((fragment) => Boolean(fragment)).join(" "),
+		citedSourceIds: testCase.expectedSourceIds ?? [],
+		durationMs: 1,
+		metadata: { smoke: true }
+	};
+}
+function buildIndustryMemoryBenchmarkSmokeCases(specs = INDUSTRY_MEMORY_BENCHMARKS) {
+	return specs.map((spec) => {
+		const currentEventId = `${spec.id}:event-current`;
+		const staleEventId = `${spec.id}:event-stale`;
+		const actorId = spec.taskKind === "memory-multiparty" ? "teammate-ada" : "user";
+		const currentFact = `${spec.id} current memory`;
+		const staleFact = `${spec.id} stale memory`;
+		return {
+			id: `${spec.id}/smoke:q1`,
+			family: spec.family,
+			taskKind: spec.taskKind,
+			split: spec.taskKind === "memory-forgetting" ? "holdout" : "dev",
+			tags: unique([
+				"memory-smoke",
+				spec.id,
+				spec.family,
+				spec.taskKind
+			]),
+			source: {
+				name: spec.id,
+				version: "smoke"
+			},
+			events: [{
+				id: staleEventId,
+				actorId,
+				sessionId: `${spec.id}:session-1`,
+				timestamp: "2026-01-01T00:00:00.000Z",
+				text: `${actorId} once had this obsolete fact: ${staleFact}.`
+			}, {
+				id: currentEventId,
+				actorId,
+				sessionId: `${spec.id}:session-2`,
+				timestamp: "2026-02-01T00:00:00.000Z",
+				text: `${actorId} updated the durable fact to: ${currentFact}.`
+			}],
+			prompt: `Use memory to answer the ${spec.id} smoke probe.`,
+			requiredFacts: [{
+				id: `${spec.id}:current`,
+				anyOf: [currentFact],
+				sourceEventIds: [currentEventId]
+			}],
+			forbiddenFacts: [{
+				id: `${spec.id}:stale`,
+				anyOf: [staleFact],
+				sourceEventIds: [staleEventId],
+				obsolete: true
+			}],
+			expectedEventIds: [currentEventId],
+			expectedActorIds: [actorId],
+			referenceAnswer: currentFact,
+			metadata: {
+				adapter: spec.adapter,
+				primaryMetrics: spec.primaryMetrics
+			}
+		};
+	});
+}
+function respondToIndustryMemoryBenchmarkSmokeCase(input) {
+	const testCase = input.case;
+	const facts = testCase.requiredFacts?.map((fact) => fact.anyOf[0]).filter((fragment) => Boolean(fragment));
+	return {
+		answer: facts?.join(" ") ?? "",
+		rememberedFacts: facts ?? [],
+		citedEventIds: testCase.expectedEventIds ?? [],
+		actorIds: testCase.expectedActorIds ?? [],
+		durationMs: 1,
+		metadata: { smoke: true }
+	};
+}
+function buildFirstPartyMemoryLifecycleBenchmarkCases() {
+	const base = {
+		family: "first-party",
+		source: {
+			name: "first-party/memory-lifecycle",
+			version: "real-v1"
+		}
+	};
+	return [
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:allergy",
+			taskKind: "memory-ingest",
+			split: "dev",
+			actorId: "user",
+			prompt: "What food restriction should catering remember for this user?",
+			staleText: "The user said they had no food allergies on the first onboarding form.",
+			currentText: "The user later corrected the profile: they have a severe peanut allergy.",
+			required: "severe peanut allergy",
+			forbidden: "no food allergies"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:account-tier",
+			taskKind: "memory-recall",
+			split: "dev",
+			actorId: "sales-ops",
+			prompt: "What is the customer account tier now?",
+			staleText: "Sales ops originally marked the customer as starter tier.",
+			currentText: "Sales ops updated the customer to enterprise tier after procurement approval.",
+			required: "enterprise tier",
+			forbidden: "starter tier"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:launch-date",
+			taskKind: "memory-temporal",
+			split: "holdout",
+			actorId: "pm",
+			prompt: "What launch date should the agent use?",
+			staleText: "The PM first planned the launch for April 3.",
+			currentText: "The PM moved the launch date to April 17 after legal review.",
+			required: "April 17",
+			forbidden: "April 3"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:briefing-channel",
+			taskKind: "memory-update",
+			split: "holdout",
+			actorId: "user",
+			prompt: "How should daily briefings be delivered now?",
+			staleText: "The user used to want daily briefings by SMS.",
+			currentText: "The user changed daily briefings to email only.",
+			required: "email only",
+			forbidden: "SMS"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:shipping-address",
+			taskKind: "memory-forgetting",
+			split: "holdout",
+			actorId: "user",
+			prompt: "What shipping address is current?",
+			staleText: "The old shipping address was 14 Pine Street, Apartment 2.",
+			currentText: "The current shipping address is 88 Cedar Avenue, Suite 9.",
+			required: "88 Cedar Avenue, Suite 9",
+			forbidden: "14 Pine Street"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:approval-owner",
+			taskKind: "memory-reasoning",
+			split: "holdout",
+			actorId: "finance",
+			prompt: "Who owns travel approval now?",
+			staleText: "Finance said Liam owned travel approvals last quarter.",
+			currentText: "Finance reassigned travel approvals to Maya this quarter.",
+			required: "Maya",
+			forbidden: "Liam"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:project-summary",
+			taskKind: "memory-summarization",
+			split: "dev",
+			actorId: "pm",
+			prompt: "Summarize the current Project Orion risks.",
+			staleText: "The old Project Orion risk was logo color churn.",
+			currentText: "The current Project Orion risks are vendor delay and a QA staffing gap.",
+			required: "vendor delay",
+			extraRequired: "QA staffing gap",
+			forbidden: "logo color churn"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:meeting-format",
+			taskKind: "memory-recommendation",
+			split: "holdout",
+			actorId: "user",
+			prompt: "What meeting format should the agent recommend?",
+			staleText: "The user previously preferred long video calls for planning.",
+			currentText: "The user now prefers async docs for planning instead of video calls.",
+			required: "async docs",
+			forbidden: "long video calls"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:multiparty-ada",
+			taskKind: "memory-multiparty",
+			split: "holdout",
+			actorId: "ada",
+			prompt: "Which SDK language did Ada ask for?",
+			staleText: "Ben asked for a Python notebook example.",
+			currentText: "Ada asked for a Rust SDK example.",
+			required: "Rust SDK",
+			forbidden: "Python notebook"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:timezone",
+			taskKind: "memory-recall",
+			split: "dev",
+			actorId: "user",
+			prompt: "What timezone should scheduling use for this user?",
+			staleText: "The user profile originally listed Pacific time.",
+			currentText: "The user corrected scheduling to America/Denver time.",
+			required: "America/Denver",
+			forbidden: "Pacific time"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:dinner-preference",
+			taskKind: "memory-update",
+			split: "holdout",
+			actorId: "user",
+			prompt: "What dinner preference should the assistant use?",
+			staleText: "The user was previously vegetarian for team dinners.",
+			currentText: "The user updated dinner restrictions to no shellfish.",
+			required: "no shellfish",
+			forbidden: "vegetarian"
+		}),
+		memoryLifecycleCase({
+			...base,
+			id: "first-party/memory-lifecycle:support-sla",
+			taskKind: "memory-temporal",
+			split: "holdout",
+			actorId: "support-lead",
+			prompt: "What support SLA is current?",
+			staleText: "Support used to promise a 24 hour response SLA.",
+			currentText: "Support changed the current response SLA to 2 business hours.",
+			required: "2 business hours",
+			forbidden: "24 hour"
+		})
+	];
+}
+function hitForExpectedTarget(expected, fallbackId) {
+	if (!expected) return {
+		pageId: fallbackId,
+		path: `${fallbackId}.md`,
+		rank: 1
+	};
+	switch (expected.kind) {
+		case "page": return {
+			pageId: expected.pageId,
+			path: `${expected.pageId}.md`,
+			rank: 1
+		};
+		case "page-path": return {
+			pageId: expected.path,
+			path: expected.path,
+			rank: 1
+		};
+		case "source": return {
+			pageId: expected.sourceId,
+			path: `${expected.sourceId}.md`,
+			sourceIds: [expected.sourceId],
+			rank: 1
+		};
+		case "source-anchor": return {
+			pageId: expected.sourceId,
+			path: `${expected.sourceId}.md`,
+			sourceIds: [expected.sourceId],
+			sourceSpans: [{
+				sourceId: expected.sourceId,
+				anchorId: expected.anchorId
+			}],
+			rank: 1
+		};
+		case "source-span": return {
+			pageId: expected.sourceId,
+			path: `${expected.sourceId}.md`,
+			sourceIds: [expected.sourceId],
+			sourceSpans: [{
+				sourceId: expected.sourceId,
+				charStart: expected.charStart,
+				charEnd: expected.charEnd
+			}],
+			rank: 1
+		};
+	}
+}
+function memoryLifecycleCase(input) {
+	const staleEventId = `${input.id}:stale`;
+	const currentEventId = `${input.id}:current`;
+	return {
+		id: input.id,
+		family: input.family,
+		taskKind: input.taskKind,
+		split: input.split,
+		tags: unique([
+			"first-party-memory-lifecycle",
+			input.taskKind,
+			input.split
+		]),
+		source: input.source,
+		events: [{
+			id: staleEventId,
+			actorId: input.actorId,
+			sessionId: `${input.id}:session-1`,
+			timestamp: "2026-01-01T00:00:00.000Z",
+			text: input.staleText
+		}, {
+			id: currentEventId,
+			actorId: input.actorId,
+			sessionId: `${input.id}:session-2`,
+			timestamp: "2026-02-01T00:00:00.000Z",
+			text: input.currentText
+		}],
+		prompt: input.prompt,
+		requiredFacts: [{
+			id: `${input.id}:required-1`,
+			anyOf: [input.required],
+			sourceEventIds: [currentEventId]
+		}, ...input.extraRequired ? [{
+			id: `${input.id}:required-2`,
+			anyOf: [input.extraRequired],
+			sourceEventIds: [currentEventId]
+		}] : []],
+		forbiddenFacts: [{
+			id: `${input.id}:stale`,
+			anyOf: [input.forbidden],
+			sourceEventIds: [staleEventId],
+			obsolete: true
+		}],
+		expectedEventIds: [currentEventId],
+		expectedActorIds: [input.actorId],
+		referenceAnswer: input.required
+	};
+}
+//#endregion
+//#region src/memory/attempt-log.ts
+const journalByteLengths = /* @__PURE__ */ new WeakMap();
+const MEMORY_PROVIDER_ACTOR_PREFIXES = [
+	"agent-knowledge:memory-adapter:",
+	"agent-knowledge:memory-adapter-recovery:",
+	"agent-knowledge:memory-experiment:",
+	"agent-knowledge:memory-recovery:"
+];
+function reconcileInterruptedMemoryPaidCalls(costLedger) {
+	reconcileInterruptedPaidCallsAtMaximum(costLedger, (actor) => isMemoryProviderActor(actor), "external memory provider");
+}
+function reconcileInterruptedPaidCallsAtMaximum(costLedger, ownsActor, label) {
+	if (costLedger.summary().unresolvedCalls === 0) return;
+	const pending = requirePendingCostCallInspection(costLedger);
+	for (const call of pending) {
+		if (call.state !== "interrupted" || !ownsActor(call.actor)) continue;
+		if (call.maximumCostUsd === void 0) throw new Error(`cannot recover unbounded interrupted ${label} call '${call.callId}' for '${call.actor}'`);
+		try {
+			costLedger.reconcile(call.callId, {
+				model: call.model,
+				inputTokens: 0,
+				outputTokens: 0,
+				actualCostUsd: call.maximumCostUsd
+			}, { error: `process exited before the ${label} receipt for '${call.actor}' was recorded; charged the reserved maximum` });
+		} catch (error) {
+			if (isMissingPendingCostCall(error, call.callId)) continue;
+			throw error;
+		}
+	}
+}
+function assertNoInterruptedPaidCalls(costLedger, label) {
+	const unresolved = costLedger.summary().unresolvedCalls;
+	if (unresolved === 0) return;
+	const blocked = requirePendingCostCallInspection(costLedger).filter((call) => call.state !== "active");
+	throw new Error(`${label} has ${unresolved} unresolved paid call(s) that cannot be resumed: ${blocked.map((call) => `${call.callId} (${call.actor}, ${call.state})`).join(", ")}`);
+}
+function hasSettledPaidCall(costLedger, callId) {
+	return costLedger.list().some((receipt) => receipt.callId === callId);
+}
+function appendAttemptJournalEvent(input) {
+	appendDurableJournalEvent(input);
+}
+function appendDurableJournalEvent(input) {
+	const { storage, path, event, label } = input;
+	if (!storage.append) throw new Error(`${label} requires CampaignStorage.append`);
+	const line = `${JSON.stringify(event)}\n`;
+	const byteLengths = journalByteLengths.get(storage) ?? /* @__PURE__ */ new Map();
+	journalByteLengths.set(storage, byteLengths);
+	for (let retry = 0; retry < 100; retry += 1) {
+		let expectedBytes = byteLengths.get(path);
+		if (expectedBytes === void 0) {
+			const current = storage.read(path);
+			if (current === void 0 && storage.exists(path)) throw new Error(`cannot read ${label} '${path}'`);
+			expectedBytes = new TextEncoder().encode(current ?? "").byteLength;
+			byteLengths.set(path, expectedBytes);
+		}
+		const appendedBytes = storage.append(path, line, expectedBytes);
+		if (appendedBytes !== void 0) {
+			byteLengths.set(path, appendedBytes);
+			return;
+		}
+		byteLengths.delete(path);
+	}
+	throw new Error(`${label} '${path}' remained contended after 100 retries`);
+}
+/** Reserves one durable recovery generation per attempt before provider work starts. */
+function reserveRecoveryAttempts(input) {
+	const { storage, path, attemptIds, maxRetriesPerAttempt, label } = input;
+	if (!Number.isSafeInteger(maxRetriesPerAttempt) || maxRetriesPerAttempt <= 0) throw new Error(`${label} maxRetriesPerAttempt must be a positive safe integer`);
+	if (new Set(attemptIds).size !== attemptIds.length || attemptIds.some((id) => !id.trim())) throw new Error(`${label} attempt ids must be unique non-empty strings`);
+	const generations = readRecoveryAttemptGenerations(storage, path, label);
+	for (const attemptId of attemptIds) if ((generations.get(attemptId) ?? 0) >= maxRetriesPerAttempt) throw new Error(`${label} '${attemptId}' exhausted ${maxRetriesPerAttempt} recovery attempts; increase maxRecoveryRetriesPerAttempt only after inspecting provider state`);
+	const reserved = /* @__PURE__ */ new Map();
+	for (const attemptId of attemptIds) {
+		const generation = (generations.get(attemptId) ?? 0) + 1;
+		appendDurableJournalEvent({
+			storage,
+			path,
+			label,
+			event: {
+				attemptId,
+				generation,
+				recordedAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+			}
+		});
+		generations.set(attemptId, generation);
+		reserved.set(attemptId, generation);
+	}
+	return reserved;
+}
+function readActiveAttemptJournal(input) {
+	const { storage, path, label, parse, id, sameAttempt } = input;
+	const stored = storage.read(path);
+	if (stored === void 0) {
+		if (storage.exists(path)) throw new Error(`cannot read ${label} '${path}'`);
+		return [];
+	}
+	const active = /* @__PURE__ */ new Map();
+	const completed = /* @__PURE__ */ new Map();
+	for (const [index, line] of stored.split("\n").entries()) {
+		if (!line) continue;
+		let raw;
+		try {
+			raw = JSON.parse(line);
+		} catch (error) {
+			throw new Error(`invalid ${label} '${path}' line ${index + 1}`, { cause: error });
+		}
+		const event = parse(raw, path, index + 1);
+		const attemptId = id(event);
+		if (event.status === "started") {
+			if (active.has(attemptId) || completed.has(attemptId)) throw new Error(`${label} '${path}' repeats attempt '${attemptId}'`);
+			active.set(attemptId, event);
+			continue;
+		}
+		const started = active.get(attemptId);
+		if (started && sameAttempt(started, event)) {
+			active.delete(attemptId);
+			completed.set(attemptId, started);
+			continue;
+		}
+		const prior = completed.get(attemptId);
+		if (prior && sameAttempt(prior, event)) continue;
+		throw new Error(`${label} '${path}' has an unmatched cleanup for '${attemptId}'`);
+	}
+	return [...active.values()];
+}
+function readRecoveryAttemptGenerations(storage, path, label) {
+	const stored = storage.read(path);
+	if (stored === void 0) {
+		if (storage.exists(path)) throw new Error(`cannot read ${label} '${path}'`);
+		return /* @__PURE__ */ new Map();
+	}
+	const generations = /* @__PURE__ */ new Map();
+	for (const [index, line] of stored.split("\n").entries()) {
+		if (!line) continue;
+		let raw;
+		try {
+			raw = JSON.parse(line);
+		} catch (error) {
+			throw new Error(`invalid ${label} '${path}' line ${index + 1}`, { cause: error });
+		}
+		const event = parseRecoveryAttemptEvent(raw, path, index + 1, label);
+		const expected = (generations.get(event.attemptId) ?? 0) + 1;
+		if (event.generation !== expected) throw new Error(`${label} '${path}' has recovery generation ${event.generation} for '${event.attemptId}', expected ${expected}`);
+		generations.set(event.attemptId, event.generation);
+	}
+	return generations;
+}
+function parseRecoveryAttemptEvent(value, path, line, label) {
+	const event = value;
+	if (!(typeof event === "object" && event !== null && typeof event.attemptId === "string" && event.attemptId.length > 0 && Number.isSafeInteger(event.generation) && event.generation > 0 && typeof event.recordedAt === "string" && !Number.isNaN(Date.parse(event.recordedAt)))) throw new Error(`invalid ${label} '${path}' line ${line}`);
+	return value;
+}
+function isMissingPendingCostCall(error, callId) {
+	return error instanceof Error && error.message === `CostLedger: no pending call '${callId}'`;
+}
+function requirePendingCostCallInspection(costLedger) {
+	if (!costLedger.listPending) throw new Error("interrupted memory recovery requires CostLedger.listPending() support");
+	return costLedger.listPending();
+}
+function isMemoryProviderActor(actor) {
+	return MEMORY_PROVIDER_ACTOR_PREFIXES.some((prefix) => actor.startsWith(prefix));
+}
+//#endregion
+//#region src/memory/lifecycle.ts
+const DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS = 18e4;
+var AgentMemoryLifecycleTimeoutError = class extends Error {
+	operation;
+	timeoutMs;
+	constructor(operation, timeoutMs) {
+		super(`${operation} did not finish within ${timeoutMs}ms`);
+		this.operation = operation;
+		this.timeoutMs = timeoutMs;
+		this.name = "AgentMemoryLifecycleTimeoutError";
+	}
+};
+var AgentMemoryLifecycleUnsafeError = class extends Error {
+	operation;
+	priorTimeout;
+	constructor(operation, priorTimeout) {
+		super(`${operation} cannot start because '${priorTimeout.operation}' is still running after its ${priorTimeout.timeoutMs}ms timeout`, { cause: priorTimeout });
+		this.operation = operation;
+		this.priorTimeout = priorTimeout;
+		this.name = "AgentMemoryLifecycleUnsafeError";
+	}
+};
+const timedOutResources = /* @__PURE__ */ new WeakMap();
+function releaseMemoryAdapterCreatedAfterAbort(input) {
+	input.creation.then(async (adapter) => {
+		if (!adapter || !input.signal.aborted) return;
+		try {
+			await adapter.close?.();
+		} catch {}
+		try {
+			await input.dispose?.(adapter);
+		} catch {}
+	}, () => void 0);
+}
+function resolveMemoryCleanupTimeoutMs(value, label) {
+	const timeoutMs = value ?? 18e4;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error(`${label} cleanupTimeoutMs must be a positive safe integer`);
+	return timeoutMs;
+}
+async function runBoundedMemoryLifecycle(input) {
+	const priorTimeout = input.resource ? timedOutResources.get(input.resource) : void 0;
+	if (priorTimeout) throw new AgentMemoryLifecycleUnsafeError(input.operation, priorTimeout);
+	let timeout;
+	let timeoutError;
+	const work = Promise.resolve().then(input.run);
+	if (input.resource) {
+		const resource = input.resource;
+		work.then(() => {
+			if (timeoutError && timedOutResources.get(resource) === timeoutError) timedOutResources.delete(resource);
+		}, () => {
+			if (timeoutError && timedOutResources.get(resource) === timeoutError) timedOutResources.delete(resource);
+		});
+	}
+	const deadline = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			timeoutError = new AgentMemoryLifecycleTimeoutError(input.operation, input.timeoutMs);
+			if (input.resource) timedOutResources.set(input.resource, timeoutError);
+			input.abortController?.abort(timeoutError);
+			reject(timeoutError);
+		}, input.timeoutMs);
+	});
+	try {
+		return await Promise.race([work, deadline]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+function memoryRecoveryDelayMs(adapter) {
+	const isolation = adapter.branchIsolation;
+	if (isolation?.mode !== "scoped" || isolation.processExitSafe !== false) return 0;
+	const delayMs = isolation.recoveryDelayMs;
+	if (typeof delayMs !== "number" || !Number.isSafeInteger(delayMs) || delayMs <= 0) throw new Error(`${adapter.id}: processExitSafe=false requires a positive recoveryDelayMs for abandoned writes`);
+	return delayMs;
+}
+async function sleepForMemoryRecovery(delayMs, assertOwned, timeoutMs = delayMs, operation = "memory recovery visibility wait") {
+	if (delayMs <= 0) return;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error(`${operation} timeout must be a positive safe integer`);
+	await new Promise((resolve) => setTimeout(resolve, Math.min(delayMs, timeoutMs)));
+	await assertOwned();
+	if (delayMs > timeoutMs) throw new AgentMemoryLifecycleTimeoutError(operation, timeoutMs);
+}
+function createMemoryExecutionPool(limit) {
+	let active = 0;
+	const waiters = [];
+	return { async run(operation) {
+		if (active >= limit) await new Promise((resolve) => waiters.push(resolve));
+		active += 1;
+		try {
+			return await operation();
+		} finally {
+			active -= 1;
+			waiters.shift()?.();
+		}
+	} };
+}
+//#endregion
+//#region src/memory/run-control.ts
+const activeProcessLocalRuns = /* @__PURE__ */ new Set();
+async function acquireAgentMemoryRunLease(input) {
+	if (input.acquireRunLease && input.controllerMode) throw new Error(`${input.label} cannot combine acquireRunLease with controllerMode`);
+	if (input.acquireRunLease) {
+		const lease = await input.acquireRunLease({
+			experimentId: input.experimentId,
+			runDir: input.runDir
+		});
+		if (!lease || typeof lease.assertOwned !== "function" || typeof lease.release !== "function") throw new Error(`${input.label} acquireRunLease must return assertOwned and release`);
+		return {
+			async assertOwned() {
+				await lease.assertOwned();
+			},
+			async release() {
+				await lease.release();
+			}
+		};
+	}
+	if (!input.customStorage) {
+		if (input.controllerMode) throw new Error(`${input.label} controllerMode is only valid with custom storage`);
+		const lock = acquireSingleRunLock({
+			lockPath: join(input.runDir, input.lockFileName),
+			releaseOnExit: false
+		});
+		return {
+			async assertOwned() {},
+			async release() {
+				lock.release();
+			}
+		};
+	}
+	if (input.controllerMode !== "process-local") throw new Error(`${input.label} custom storage requires acquireRunLease or controllerMode='process-local'`);
+	const runKey = `${input.label}:${input.runDir}`;
+	if (activeProcessLocalRuns.has(runKey)) throw new Error(`${input.label} run '${input.runDir}' already has an active controller`);
+	activeProcessLocalRuns.add(runKey);
+	let released = false;
+	return {
+		async assertOwned() {
+			if (released || !activeProcessLocalRuns.has(runKey)) throw new Error(`${input.label} run '${input.runDir}' controller lease was lost`);
+		},
+		async release() {
+			if (released) return;
+			released = true;
+			activeProcessLocalRuns.delete(runKey);
+		}
+	};
+}
+//#endregion
+//#region src/benchmarks/memory-recovery.ts
+function memoryAdapterBenchmarkExpectedId(candidate) {
+	return candidate.adapterId ?? candidate.id;
+}
+async function recoverMemoryAdapterBenchmarkAttempts(input) {
+	let attempts = readActiveMemoryBenchmarkAttempts(input.storage, input.attemptLogPath);
+	if (attempts.length > input.maxRecoveryAttempts) throw new Error(`memory adapter benchmark has ${attempts.length} unfinished attempts; maxRecoveryAttempts is ${input.maxRecoveryAttempts}`);
+	const candidateById = new Map(input.candidates.map((candidate) => [candidate.id, candidate]));
+	for (const attempt of attempts) {
+		const candidate = candidateById.get(attempt.candidateId);
+		if (!candidate) throw new Error(`cannot recover memory benchmark attempts: candidate '${attempt.candidateId}' is missing; pass it in recoveryCandidates`);
+		assertMemoryBenchmarkAttemptCandidateMatches(attempt, candidate);
+	}
+	reconcileInterruptedMemoryPaidCalls(input.costLedger);
+	assertNoInterruptedPaidCalls(input.costLedger, "memory adapter benchmark recovery");
+	for (const attempt of attempts) if ((candidateById.get(attempt.candidateId).costUsdPerCase ?? 0) > 0 && !hasSettledPaidCall(input.costLedger, memoryBenchmarkCostCallId(attempt, "execute", 0))) appendMemoryBenchmarkAttemptEvent(input.storage, input.attemptLogPath, {
+		...attempt,
+		status: "cleaned",
+		recovery: true,
+		recordedAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+	});
+	attempts = readActiveMemoryBenchmarkAttempts(input.storage, input.attemptLogPath);
+	const recoveryGenerations = reserveRecoveryAttempts({
+		storage: input.storage,
+		path: input.recoveryLogPath,
+		attemptIds: attempts.map((attempt) => attempt.attemptId),
+		maxRetriesPerAttempt: input.maxRecoveryRetriesPerAttempt,
+		label: "memory benchmark recovery attempt log",
+		now: input.now
+	});
+	const grouped = groupMemoryBenchmarkAttempts(attempts);
+	const pool = createMemoryExecutionPool(input.maxConcurrency);
+	const failures = (await Promise.allSettled([...grouped].sort(([left], [right]) => left.localeCompare(right)).map(([candidateId, candidateAttempts]) => pool.run(async () => {
+		await input.lease.assertOwned();
+		const candidate = candidateById.get(candidateId);
+		if (!candidate) throw new Error(`cannot recover memory benchmark attempts: candidate '${candidateId}' is missing; pass it in recoveryCandidates`);
+		for (const attempt of candidateAttempts) {
+			assertMemoryBenchmarkAttemptCandidateMatches(attempt, candidate);
+			if (recoveryGenerations.get(attempt.attemptId) === void 0) throw new Error(`missing recovery generation for memory benchmark attempt '${attempt.attemptId}'`);
+		}
+		let recoveryAttemptsStarted = 0;
+		let adapterCreationExternalCallAttempted = false;
+		const cleared = [];
+		const recover = async () => {
+			let adapter;
+			let primaryError;
+			try {
+				const abortController = new AbortController();
+				const creation = Promise.resolve().then(() => candidate.createAdapter({
+					purpose: "recovery",
+					signal: abortController.signal,
+					markExternalCall: () => {
+						adapterCreationExternalCallAttempted = true;
+					}
+				}));
+				releaseMemoryAdapterCreatedAfterAbort({
+					creation,
+					signal: abortController.signal
+				});
+				adapter = await runBoundedMemoryLifecycle({
+					operation: `${candidate.id}: benchmark recovery adapter creation`,
+					timeoutMs: input.cleanupTimeoutMs,
+					abortController,
+					run: () => creation
+				});
+				assertScopedMemoryBenchmarkAdapter(adapter);
+				for (const attempt of candidateAttempts) if (adapter.id !== attempt.adapterId) throw new Error(`cannot recover memory benchmark attempt '${attempt.attemptId}': adapter changed from '${attempt.adapterId}' to '${adapter.id}'`);
+				await sleepForMemoryRecovery(memoryRecoveryDelayMs(adapter), () => input.lease.assertOwned(), input.cleanupTimeoutMs, `${candidate.id}: benchmark recovery visibility wait`);
+				for (const attempt of candidateAttempts.sort((left, right) => left.attemptId.localeCompare(right.attemptId))) {
+					await input.lease.assertOwned();
+					try {
+						recoveryAttemptsStarted += 1;
+						await runBoundedMemoryLifecycle({
+							operation: `${candidate.id}: abandoned benchmark attempt cleanup`,
+							timeoutMs: input.cleanupTimeoutMs,
+							resource: adapter,
+							run: () => adapter.clear(attempt.scope)
+						});
+						await input.lease.assertOwned();
+						cleared.push(attempt);
+					} catch (error) {
+						primaryError = primaryError ? new AggregateError([primaryError, error], `${candidate.id}: multiple benchmark attempts failed recovery`) : error;
+					}
+				}
+			} catch (error) {
+				primaryError = primaryError ? new AggregateError([primaryError, error], `${candidate.id}: benchmark recovery failed in multiple operations`) : error;
+			}
+			let closeError;
+			if (adapter) try {
+				await runBoundedMemoryLifecycle({
+					operation: `${candidate.id}: benchmark recovery adapter close`,
+					timeoutMs: input.cleanupTimeoutMs,
+					resource: adapter,
+					run: () => adapter.close?.()
+				});
+			} catch (error) {
+				closeError = error;
+			}
+			let journalError;
+			if (!closeError) try {
+				for (const attempt of cleared) {
+					await input.lease.assertOwned();
+					appendMemoryBenchmarkAttemptEvent(input.storage, input.attemptLogPath, {
+						...attempt,
+						status: "cleaned",
+						recovery: true,
+						recordedAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+					});
+				}
+			} catch (error) {
+				journalError = error;
+			}
+			const failures = [
+				primaryError,
+				closeError,
+				journalError
+			].filter((error) => error !== void 0);
+			if (failures.length > 1) throw new AggregateError(failures, `${candidate.id}: benchmark attempt recovery, adapter close, or cleanup journal failed`);
+			if (primaryError) throw primaryError;
+			if (closeError) throw closeError;
+			if (journalError) throw journalError;
+		};
+		const recoveryCostUsd = candidate.recoveryCostUsdPerAttempt ?? 0;
+		const adapterCreationCostUsd = candidate.adapterCreationCostUsd ?? 0;
+		const maximumCostUsd = adapterCreationCostUsd + recoveryCostUsd * candidateAttempts.length;
+		const actualCostUsd = () => (adapterCreationExternalCallAttempted ? adapterCreationCostUsd : 0) + recoveryCostUsd * recoveryAttemptsStarted;
+		let recoveryError;
+		if (maximumCostUsd === 0) try {
+			await recover();
+		} catch (error) {
+			recoveryError = error;
+		}
+		else {
+			const receipt = {
+				model: candidate.id,
+				inputTokens: 0,
+				outputTokens: 0
+			};
+			const tags = memoryBenchmarkRecoveryCostTags(input.runDir, candidate.id);
+			const paid = await input.costLedger.runPaidCall({
+				callId: memoryBenchmarkRecoveryCostCallId(candidate, candidateAttempts, recoveryGenerations),
+				channel: "driver",
+				phase: `${input.costPhase}.${candidate.id}.recovery`,
+				actor: `agent-knowledge:memory-adapter-recovery:${candidate.id}`,
+				model: candidate.id,
+				tags,
+				maximumCharge: { externallyEnforcedMaximumUsd: maximumCostUsd },
+				execute: recover,
+				receipt: () => ({
+					...receipt,
+					actualCostUsd: actualCostUsd()
+				}),
+				receiptFromError: () => ({
+					...receipt,
+					actualCostUsd: actualCostUsd()
+				})
+			});
+			if (!paid.succeeded) recoveryError = paid.error;
+		}
+		if (recoveryError) throw recoveryError;
+	})))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+	if (failures.length === 1) throw failures[0];
+	if (failures.length > 1) throw new AggregateError(failures, "multiple memory benchmark candidates failed recovery");
+}
+function groupMemoryBenchmarkAttempts(attempts) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const attempt of attempts) {
+		const group = grouped.get(attempt.candidateId) ?? [];
+		group.push(attempt);
+		grouped.set(attempt.candidateId, group);
+	}
+	return grouped;
+}
+function memoryBenchmarkCostCallId(attempt, purpose, generation) {
+	return stableId("memory_benchmark_cost_call", canonicalJson({
+		purpose,
+		generation,
+		attemptId: attempt.attemptId,
+		candidateId: attempt.candidateId,
+		candidateRef: attempt.candidateRef,
+		adapterId: attempt.adapterId,
+		adapterCreationCostUsd: attempt.adapterCreationCostUsd,
+		costUsdPerCase: attempt.costUsdPerCase,
+		recoveryCostUsdPerAttempt: attempt.recoveryCostUsdPerAttempt,
+		caseId: attempt.caseId,
+		cellId: attempt.cellId
+	}));
+}
+function memoryBenchmarkRecoveryCostCallId(candidate, attempts, generations) {
+	return stableId("memory_benchmark_recovery_cost_call", canonicalJson({
+		candidateId: candidate.id,
+		candidateRef: candidate.ref,
+		adapterCreationCostUsd: candidate.adapterCreationCostUsd ?? 0,
+		recoveryCostUsdPerAttempt: candidate.recoveryCostUsdPerAttempt ?? 0,
+		attempts: attempts.map((attempt) => ({
+			attemptId: attempt.attemptId,
+			generation: generations.get(attempt.attemptId)
+		})).sort((left, right) => left.attemptId.localeCompare(right.attemptId))
+	}));
+}
+function memoryBenchmarkRecoveryCostTags(runDir, candidateId) {
+	return {
+		runDir: join(runDir, candidateId),
+		candidateId,
+		memoryRecovery: "benchmark"
+	};
+}
+function appendMemoryBenchmarkAttemptEvent(storage, path, event) {
+	appendAttemptJournalEvent({
+		storage,
+		path,
+		event,
+		label: "memory benchmark attempt log"
+	});
+}
+function readActiveMemoryBenchmarkAttempts(storage, path) {
+	return readActiveAttemptJournal({
+		storage,
+		path,
+		label: "memory benchmark attempt log",
+		parse: parseMemoryBenchmarkAttemptEvent,
+		id: (event) => event.attemptId,
+		sameAttempt: sameMemoryBenchmarkAttempt
+	});
+}
+function parseMemoryBenchmarkAttemptEvent(value, path, line) {
+	const event = value;
+	if (!(typeof event === "object" && event !== null && (event.status === "started" || event.status === "cleaned") && isNonEmptyString(event.attemptId) && isNonEmptyString(event.candidateId) && isNonEmptyString(event.candidateRef) && isNonEmptyString(event.adapterId) && isNonEmptyString(event.caseId) && isNonEmptyString(event.cellId) && isAgentMemoryScope(event.scope) && typeof event.adapterCreationCostUsd === "number" && Number.isFinite(event.adapterCreationCostUsd) && event.adapterCreationCostUsd >= 0 && typeof event.costUsdPerCase === "number" && Number.isFinite(event.costUsdPerCase) && event.costUsdPerCase >= 0 && typeof event.recoveryCostUsdPerAttempt === "number" && Number.isFinite(event.recoveryCostUsdPerAttempt) && event.recoveryCostUsdPerAttempt >= 0 && typeof event.recordedAt === "string" && !Number.isNaN(Date.parse(event.recordedAt)) && typeof event.recovery === "boolean")) throw new Error(`invalid memory benchmark attempt event in '${path}' line ${line}`);
+	return value;
+}
+function sameMemoryBenchmarkAttempt(left, right) {
+	return left.attemptId === right.attemptId && left.candidateId === right.candidateId && left.candidateRef === right.candidateRef && left.adapterId === right.adapterId && left.caseId === right.caseId && left.cellId === right.cellId && canonicalJson(left.scope) === canonicalJson(right.scope) && left.adapterCreationCostUsd === right.adapterCreationCostUsd && left.costUsdPerCase === right.costUsdPerCase && left.recoveryCostUsdPerAttempt === right.recoveryCostUsdPerAttempt;
+}
+function assertMemoryBenchmarkAttemptCandidateMatches(attempt, candidate) {
+	if (attempt.candidateRef !== candidate.ref) throw new Error(`cannot recover memory benchmark attempt '${attempt.attemptId}': candidate ref changed from '${attempt.candidateRef}' to '${candidate.ref}'`);
+	const expectedAdapterId = memoryAdapterBenchmarkExpectedId(candidate);
+	if (attempt.adapterId !== expectedAdapterId) throw new Error(`cannot recover memory benchmark attempt '${attempt.attemptId}': adapter id changed from '${attempt.adapterId}' to '${expectedAdapterId}'`);
+	const executionCost = candidate.costUsdPerCase ?? 0;
+	const adapterCreationCost = candidate.adapterCreationCostUsd ?? 0;
+	const recoveryCost = candidate.recoveryCostUsdPerAttempt ?? 0;
+	if (adapterCreationCost !== attempt.adapterCreationCostUsd || executionCost !== attempt.costUsdPerCase || recoveryCost !== attempt.recoveryCostUsdPerAttempt) throw new Error(`cannot recover memory benchmark attempt '${attempt.attemptId}': candidate cost settings changed; start a new run or restore the recorded costs`);
+}
+function assertScopedMemoryBenchmarkAdapter(adapter) {
+	if (adapter.branchIsolation?.mode !== "scoped") throw new Error(`${adapter.id}: direct memory benchmark requires branchIsolation mode scoped; use runAgentMemoryExperiment for dedicated instances`);
+	if (!adapter.clear) throw new Error(`${adapter.id}: direct memory benchmark requires exact scoped clear`);
+}
+function isAgentMemoryScope(value) {
+	if (!isRecordValue(value)) return false;
+	const allowed = /* @__PURE__ */ new Set([
+		"tenantId",
+		"userId",
+		"agentId",
+		"teamId",
+		"runId",
+		"sessionId",
+		"namespace",
+		"tags"
+	]);
+	if (Object.keys(value).some((key) => !allowed.has(key))) return false;
+	for (const key of [
+		"tenantId",
+		"userId",
+		"agentId",
+		"teamId",
+		"runId",
+		"sessionId",
+		"namespace"
+	]) if (value[key] !== void 0 && typeof value[key] !== "string") return false;
+	if (value.tags === void 0) return true;
+	return isRecordValue(value.tags) && Object.values(value.tags).every((entry) => typeof entry === "string");
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isRecordValue(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/benchmarks/memory-responder.ts
+function createMemoryAdapterBenchmarkResponder(options) {
+	assertScopedMemoryBenchmarkAdapter(options.adapter);
+	return async ({ case: testCase, context: dispatchContext }) => {
+		if (!isKnowledgeMemoryBenchmarkCase(testCase)) return {
+			answer: "",
+			metadata: {
+				candidateId: options.candidateId,
+				skipped: true
+			}
+		};
+		const costUsd = options.costUsdPerCase ?? 0;
+		if (!Number.isFinite(costUsd) || costUsd < 0) throw new Error(`memory adapter costUsdPerCase must be non-negative finite, got ${costUsd}`);
+		dispatchContext.signal.throwIfAborted();
+		await options.lease.assertOwned();
+		const startedAt = Date.now();
+		const attemptId = randomUUID();
+		const scope = benchmarkMemoryScope(options.candidateId, testCase, dispatchContext.cellId, attemptId, options.scope);
+		const attempt = {
+			status: "started",
+			attemptId,
+			candidateId: options.candidateId,
+			candidateRef: options.candidateRef,
+			adapterId: options.adapter.id,
+			caseId: testCase.id,
+			cellId: dispatchContext.cellId,
+			scope,
+			adapterCreationCostUsd: options.adapterCreationCostUsd ?? 0,
+			costUsdPerCase: costUsd,
+			recoveryCostUsdPerAttempt: options.recoveryCostUsdPerAttempt ?? 0,
+			recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+			recovery: false
+		};
+		appendMemoryBenchmarkAttemptEvent(options.storage, options.attemptLogPath, attempt);
+		let externalCallAttempted = false;
+		const appendCleanedAttempt = (priorError) => {
+			try {
+				appendMemoryBenchmarkAttemptEvent(options.storage, options.attemptLogPath, {
+					...attempt,
+					status: "cleaned",
+					recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+				});
+			} catch (error) {
+				throw new MemoryAdapterBenchmarkCleanupError([...priorError ? [priorError] : [], error], `${options.candidateId}: memory benchmark cleanup could not be recorded`);
+			}
+		};
+		const execute = async () => {
+			dispatchContext.signal.throwIfAborted();
+			await options.lease.assertOwned();
+			let artifact;
+			let primaryError;
+			try {
+				for (const event of testCase.events) {
+					dispatchContext.signal.throwIfAborted();
+					await options.lease.assertOwned();
+					externalCallAttempted = true;
+					await options.adapter.write({
+						id: event.id,
+						kind: "message",
+						text: event.text,
+						role: event.actorId === "user" ? "user" : "assistant",
+						title: `${testCase.id}:${event.id}`,
+						scope,
+						metadata: compactObject({
+							benchmarkCaseId: testCase.id,
+							benchmarkCellId: dispatchContext.cellId,
+							benchmarkAttemptId: attemptId,
+							eventId: event.id,
+							actorId: event.actorId,
+							sessionId: event.sessionId,
+							timestamp: event.timestamp,
+							...event.metadata
+						})
+					});
+					dispatchContext.signal.throwIfAborted();
+					await options.lease.assertOwned();
+				}
+				externalCallAttempted = true;
+				await options.adapter.flush?.();
+				dispatchContext.signal.throwIfAborted();
+				await options.lease.assertOwned();
+				externalCallAttempted = true;
+				const adapterContext = await options.adapter.getContext(testCase.prompt, {
+					scope,
+					limit: options.searchLimit ?? 1,
+					metadata: {
+						benchmarkCaseId: testCase.id,
+						benchmarkCellId: dispatchContext.cellId,
+						benchmarkAttemptId: attemptId,
+						candidateId: options.candidateId
+					}
+				});
+				dispatchContext.signal.throwIfAborted();
+				await options.lease.assertOwned();
+				const hits = adapterContext.hits;
+				artifact = {
+					answer: adapterContext.text,
+					rememberedFacts: hits.map((hit) => hit.text),
+					citedEventIds: unique(hits.map(memoryEventId).filter((id) => Boolean(id))),
+					usedMemoryIds: hits.map((hit) => hit.id),
+					actorIds: unique(hits.map(memoryActorId).filter((id) => Boolean(id))),
+					costUsd,
+					durationMs: Math.max(0, Date.now() - startedAt),
+					metadata: {
+						candidateId: options.candidateId,
+						adapterId: options.adapter.id,
+						hitCount: hits.length
+					}
+				};
+			} catch (error) {
+				primaryError = error;
+			}
+			const cleanupErrors = [];
+			let cleanupOwned = true;
+			try {
+				await options.lease.assertOwned();
+			} catch (error) {
+				cleanupOwned = false;
+				cleanupErrors.push(error);
+			}
+			if (cleanupOwned) {
+				try {
+					await runBoundedMemoryLifecycle({
+						operation: `${options.candidateId}: benchmark attempt flush`,
+						timeoutMs: options.cleanupTimeoutMs,
+						resource: options.adapter,
+						run: () => {
+							externalCallAttempted = true;
+							return options.adapter.flush?.();
+						}
+					});
+				} catch (error) {
+					cleanupErrors.push(error);
+				}
+				try {
+					await runBoundedMemoryLifecycle({
+						operation: `${options.candidateId}: benchmark attempt cleanup`,
+						timeoutMs: options.cleanupTimeoutMs,
+						resource: options.adapter,
+						run: () => {
+							externalCallAttempted = true;
+							return options.adapter.clear(scope);
+						}
+					});
+				} catch (error) {
+					cleanupErrors.push(error);
+				}
+			}
+			if (cleanupOwned && cleanupErrors.length === 0) appendCleanedAttempt(primaryError);
+			if (cleanupErrors.length > 0) throw new MemoryAdapterBenchmarkCleanupError([...primaryError ? [primaryError] : [], ...cleanupErrors], `${options.candidateId}: memory benchmark attempt cleanup failed`);
+			if (primaryError) throw primaryError;
+			if (!artifact) throw new Error(`${options.candidateId}: memory benchmark produced no artifact`);
+			return artifact;
+		};
+		if (costUsd === 0) {
+			let artifact;
+			let error;
+			try {
+				artifact = await execute();
+			} catch (caught) {
+				error = caught;
+			}
+			if (error) throw error;
+			if (!artifact) throw new Error(`${options.candidateId}: memory benchmark produced no artifact`);
+			return artifact;
+		}
+		const receipt = {
+			model: options.adapter.id,
+			inputTokens: 0,
+			outputTokens: 0,
+			actualCostUsd: costUsd
+		};
+		const paid = await dispatchContext.cost.runPaidCall({
+			callId: memoryBenchmarkCostCallId(attempt, "execute", 0),
+			actor: `agent-knowledge:memory-adapter:${options.adapter.id}`,
+			model: options.adapter.id,
+			maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
+			execute,
+			receipt: () => receipt,
+			receiptFromError: () => ({
+				...receipt,
+				actualCostUsd: externalCallAttempted ? costUsd : 0
+			})
+		});
+		if (!paid.succeeded) throw paid.error;
+		return paid.value;
+	};
+}
+var MemoryAdapterBenchmarkCleanupError = class extends AggregateError {};
+function benchmarkMemoryScope(candidateId, testCase, cellId, attemptId, scope = {}) {
+	return {
+		...scope,
+		namespace: `${scope.namespace ?? "agent-knowledge-memory-benchmark"}:${attemptId}`,
+		tags: {
+			...scope.tags ?? {},
+			benchmarkCandidateId: candidateId,
+			benchmarkCaseId: testCase.id,
+			benchmarkCellId: cellId,
+			benchmarkAttemptId: attemptId
+		}
+	};
+}
+//#endregion
+//#region src/benchmarks/metrics.ts
+function summarizeKnowledgeBenchmarkCampaign(input) {
+	const scenariosById = new Map(input.scenarios.map((scenario) => [scenario.id, scenario]));
+	const successful = input.campaign.cells.map((cell) => {
+		const score = Object.values(cell.judgeScores)[0];
+		return {
+			cell,
+			scenario: scenariosById.get(cell.scenarioId),
+			composite: score?.composite ?? 0,
+			passed: (score?.dimensions.passed ?? 0) >= 1,
+			dimensions: score?.dimensions ?? {}
+		};
+	}).filter((row) => !row.cell.error);
+	return {
+		totalCases: input.scenarios.length,
+		totalCells: input.campaign.cells.length,
+		cellsFailed: input.campaign.aggregates.cellsFailed,
+		cellsCached: input.campaign.aggregates.cellsCached,
+		totalCostUsd: input.campaign.aggregates.cost.totalCostUsd,
+		bySplit: summarizeSlices(successful, (row) => row.scenario?.splitTag ?? "unknown"),
+		byFamily: summarizeSlices(successful, (row) => row.scenario?.family ?? "unknown"),
+		byTaskKind: summarizeSlices(successful, (row) => row.scenario?.taskKind ?? "unknown"),
+		dimensions: summarizeDimensions(successful.map((row) => row.dimensions)),
+		score: distribution(successful.map((row) => row.composite))
+	};
+}
+function summarizeDimensions(rows) {
+	const values = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const [key, value] of Object.entries(row)) {
+		if (!Number.isFinite(value)) continue;
+		const list = values.get(key) ?? [];
+		list.push(value);
+		values.set(key, list);
+	}
+	return Object.fromEntries([...values.entries()].map(([key, vals]) => [key, distribution(vals)]));
+}
+function summarizeSlices(rows, keyOf) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = keyOf(row);
+		const list = grouped.get(key) ?? [];
+		list.push(row);
+		grouped.set(key, list);
+	}
+	return Object.fromEntries([...grouped.entries()].map(([key, list]) => {
+		const withShape = list;
+		return [key, {
+			n: list.length,
+			meanScore: mean(withShape.map((row) => row.composite)),
+			passRate: mean(withShape.map((row) => row.passed ? 1 : 0)),
+			score: distribution(withShape.map((row) => row.composite))
+		}];
+	}));
+}
+function distribution(values) {
+	const finite = [...values].filter(Number.isFinite).sort((a, b) => a - b);
+	if (finite.length === 0) return {
+		n: 0,
+		min: 0,
+		mean: 0,
+		median: 0,
+		p90: 0,
+		max: 0
+	};
+	return {
+		n: finite.length,
+		min: finite[0],
+		mean: mean(finite),
+		median: percentile(finite, .5),
+		p90: percentile(finite, .9),
+		max: finite[finite.length - 1]
+	};
+}
+function percentile(sortedValues, p) {
+	if (sortedValues.length === 0) return 0;
+	return sortedValues[Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(p * sortedValues.length) - 1))];
+}
+function renderSliceTable(slices) {
+	const rows = Object.entries(slices).map(([key, slice]) => `| ${key} | ${slice.n} | ${formatNumber(slice.meanScore)} | ${formatNumber(slice.passRate)} | ${formatNumber(slice.score.p90)} |`);
+	return [
+		"| slice | n | mean score | pass rate | score p90 |",
+		"| --- | ---: | ---: | ---: | ---: |",
+		...rows.length ? rows : ["| none | 0 | 0 | 0 | 0 |"]
+	].join("\n");
+}
+//#endregion
+//#region src/benchmarks/scoring.ts
+function scoreKnowledgeBenchmarkArtifact(testCase, artifact) {
+	if (testCase.taskKind === "retrieval") {
+		const metrics = scoreRetrievalArtifact(normalizeRetrievalArtifact(testCase, artifact), retrievalScenarioForCase(testCase));
+		return {
+			score: metrics.recall,
+			passed: metrics.recall >= 1,
+			dimensions: {
+				recall: metrics.recall,
+				mrr: metrics.mrr,
+				ndcg: metrics.ndcg,
+				precision_at_k: metrics.precisionAtK,
+				expected_count: metrics.expectedCount,
+				matched_count: metrics.matchedCount
+			},
+			notes: `matched ${metrics.matchedCount}/${metrics.expectedCount}; first_hit_rank=${metrics.firstHitRank ?? "none"}`,
+			raw: { matchedTargetIds: metrics.matchedTargetIds }
+		};
+	}
+	if (isKnowledgeMemoryBenchmarkCase(testCase)) return scoreMemoryBenchmarkArtifact(testCase, artifact);
+	const answerArtifact = artifact;
+	const text = answerArtifact.text ?? answerArtifact.answer ?? "";
+	const required = scoreClaims(text, testCase.requiredClaims ?? []);
+	const forbidden = scoreForbiddenClaims(text, testCase.forbiddenClaims ?? []);
+	const citation = scoreCitationRecall(answerArtifact.citedSourceIds ?? [], testCase.expectedSourceIds ?? []);
+	const score = mean([
+		required.totalWeight > 0 ? required.recall : void 0,
+		testCase.expectedSourceIds && testCase.expectedSourceIds.length > 0 ? citation : void 0,
+		forbidden.safe
+	].filter((value) => value !== void 0));
+	return {
+		score,
+		passed: score >= 1,
+		dimensions: {
+			claim_recall: required.recall,
+			citation_recall: citation,
+			hallucination_safe: forbidden.safe,
+			forbidden_claim_rate: forbidden.rate,
+			required_claim_count: required.total,
+			matched_claim_count: required.matched,
+			forbidden_claim_count: forbidden.total,
+			matched_forbidden_claim_count: forbidden.matched
+		},
+		notes: `required=${required.matched}/${required.total}; forbidden=${forbidden.matched}/${forbidden.total}; citation_recall=${citation.toFixed(3)}`,
+		raw: {
+			matchedRequiredClaimIds: required.matchedIds,
+			matchedForbiddenClaimIds: forbidden.matchedIds
+		}
+	};
+}
+function scoreMemoryBenchmarkArtifact(testCase, artifact) {
+	const memoryArtifact = artifact;
+	const text = [
+		memoryArtifact.text,
+		memoryArtifact.answer,
+		...memoryArtifact.rememberedFacts ?? []
+	].filter((part) => typeof part === "string" && part.length > 0).join("\n");
+	const required = scoreClaims(text, testCase.requiredFacts ?? []);
+	const forbidden = scoreForbiddenClaims(text, testCase.forbiddenFacts ?? []);
+	const eventIds = unique([...memoryArtifact.citedEventIds ?? [], ...memoryArtifact.usedMemoryIds ?? []]);
+	const eventRecall = scoreCitationRecall(eventIds, testCase.expectedEventIds ?? []);
+	const actorRecall = scoreCitationRecall(memoryArtifact.actorIds ?? [], testCase.expectedActorIds ?? []);
+	const score = mean([
+		required.totalWeight > 0 ? required.recall : void 0,
+		testCase.expectedEventIds && testCase.expectedEventIds.length > 0 ? eventRecall : void 0,
+		testCase.expectedActorIds && testCase.expectedActorIds.length > 0 ? actorRecall : void 0,
+		testCase.forbiddenFacts && testCase.forbiddenFacts.length > 0 ? forbidden.safe : void 0
+	].filter((value) => value !== void 0));
+	const dimensions = {};
+	if (required.totalWeight > 0) {
+		dimensions.memory_fact_recall = required.recall;
+		dimensions.memory_required_fact_count = required.total;
+		dimensions.memory_matched_fact_count = required.matched;
+	}
+	if (testCase.expectedEventIds && testCase.expectedEventIds.length > 0) dimensions.memory_event_recall = eventRecall;
+	if (testCase.expectedActorIds && testCase.expectedActorIds.length > 0) dimensions.memory_actor_recall = actorRecall;
+	if (testCase.forbiddenFacts && testCase.forbiddenFacts.length > 0) {
+		dimensions.memory_stale_safe = forbidden.safe;
+		dimensions.memory_stale_rate = forbidden.rate;
+		dimensions.memory_forbidden_fact_count = forbidden.total;
+		dimensions.memory_matched_forbidden_fact_count = forbidden.matched;
+	}
+	return {
+		score,
+		passed: score >= 1,
+		dimensions,
+		applicableDimensions: Object.keys(dimensions),
+		notes: `memory required=${required.matched}/${required.total}; stale=${forbidden.matched}/${forbidden.total}; event_recall=${eventRecall.toFixed(3)}; actor_recall=${actorRecall.toFixed(3)}`,
+		raw: {
+			matchedRequiredFactIds: required.matchedIds,
+			matchedForbiddenFactIds: forbidden.matchedIds,
+			citedEventIds: eventIds,
+			actorIds: memoryArtifact.actorIds ?? []
+		}
+	};
+}
+function retrievalScenarioForCase(testCase) {
+	return {
+		id: testCase.id,
+		kind: "retrieval-eval",
+		query: testCase.query,
+		expected: testCase.expected,
+		...testCase.k !== void 0 ? { k: testCase.k } : {}
+	};
+}
+function normalizeRetrievalArtifact(testCase, artifact) {
+	const maybe = artifact;
+	const hits = maybe.hits ?? [];
+	if (Array.isArray(maybe.hits) && maybe.query && maybe.requestedK !== void 0) return maybe;
+	return {
+		config: {},
+		query: testCase.query,
+		requestedK: testCase.k ?? Math.max(1, hits.length),
+		hits,
+		durationMs: maybe.durationMs ?? 0,
+		...maybe.costUsd !== void 0 ? { costUsd: maybe.costUsd } : {},
+		...maybe.metadata ? { metadata: maybe.metadata } : {}
+	};
+}
+function scoreClaims(text, claims) {
+	let matched = 0;
+	let matchedWeight = 0;
+	let totalWeight = 0;
+	const matchedIds = [];
+	const haystack = text.toLowerCase();
+	for (const claim of claims) {
+		if (!claim.id.trim() || claim.anyOf.length === 0 || claim.anyOf.some((value) => !value.trim())) throw new Error("claim matchers require a non-empty id and at least one non-empty alternative");
+		const weight = claim.weight ?? 1;
+		if (!Number.isFinite(weight) || weight <= 0) throw new Error(`claim matcher ${claim.id} weight must be a positive finite number`);
+		totalWeight += weight;
+		if (claim.anyOf.some((fragment) => haystack.includes(fragment.toLowerCase()))) {
+			matched += 1;
+			matchedWeight += weight;
+			matchedIds.push(claim.id);
+		}
+	}
+	return {
+		total: claims.length,
+		matched,
+		totalWeight,
+		recall: totalWeight === 0 ? 1 : matchedWeight / totalWeight,
+		matchedIds
+	};
+}
+function scoreForbiddenClaims(text, claims) {
+	const matched = scoreClaims(text, claims);
+	return {
+		total: claims.length,
+		matched: matched.matched,
+		matchedIds: matched.matchedIds,
+		rate: claims.length === 0 ? 0 : matched.matched / claims.length,
+		safe: matched.matched === 0 ? 1 : 0
+	};
+}
+function scoreCitationRecall(citedSourceIds, expectedSourceIds) {
+	if (expectedSourceIds.length === 0) return 1;
+	const cited = new Set(citedSourceIds);
+	return expectedSourceIds.filter((sourceId) => cited.has(sourceId)).length / expectedSourceIds.length;
+}
+//#endregion
+//#region src/benchmarks/suite.ts
+const KNOWLEDGE_BENCHMARK_IMPLEMENTATION_REF = "agent-knowledge:benchmark-suite:v2";
+async function runKnowledgeBenchmarkSuite(options) {
+	assertKnowledgeBenchmarkCases(options.cases);
+	if (options.respondRef !== void 0) assertNonEmptyBenchmarkString(options.respondRef, "knowledge benchmark respondRef");
+	else if (options.resumable !== false) throw new Error("knowledge benchmark respondRef is required when resumable is enabled");
+	const storage = options.storage ?? fsCampaignStorage();
+	const costCeiling = options.costCeiling ?? options.costLedger?.costCeilingUsd ?? 0;
+	if (options.costLedger && options.costLedger.costCeilingUsd !== costCeiling) throw new Error("knowledge benchmark costCeiling must match the shared cost ledger ceiling");
+	const scenarios = buildKnowledgeBenchmarkScenarios(options.cases, options.splits);
+	const dispatch = async (scenario, context) => {
+		return await options.respond({
+			case: scenario.case,
+			scenario,
+			context
+		});
+	};
+	const campaign = await runCampaign({
+		scenarios,
+		dispatch,
+		dispatchRef: stableId("knowledge_benchmark", canonicalJson({
+			implementationRef: KNOWLEDGE_BENCHMARK_IMPLEMENTATION_REF,
+			respondRef: options.respondRef ?? "non-resumable"
+		})),
+		judges: [knowledgeBenchmarkJudge()],
+		runDir: options.runDir,
+		repo: options.repo,
+		seed: options.seed,
+		reps: options.reps,
+		resumable: options.resumable,
+		costCeiling,
+		costLedger: options.costLedger,
+		costPhase: options.costPhase,
+		maxConcurrency: options.maxConcurrency,
+		dispatchTimeoutMs: options.dispatchTimeoutMs,
+		expectUsage: options.expectUsage ?? "off",
+		storage,
+		now: options.now
+	});
+	const report = summarizeKnowledgeBenchmarkCampaign({
+		scenarios,
+		campaign
+	});
+	const reportJsonPath = join(campaign.runDir, "knowledge-benchmark-report.json");
+	const reportMarkdownPath = join(campaign.runDir, "knowledge-benchmark-report.md");
+	storage.write(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`);
+	storage.write(reportMarkdownPath, renderKnowledgeBenchmarkReportMarkdown(report));
+	return {
+		scenarios,
+		campaign,
+		report,
+		reportJsonPath,
+		reportMarkdownPath
+	};
+}
+function renderKnowledgeBenchmarkReportMarkdown(report) {
+	return [
+		"# Knowledge Benchmark Report",
+		"",
+		`- cases: ${report.totalCases}`,
+		`- cells: ${report.totalCells} total, ${report.cellsFailed} failed, ${report.cellsCached} cached`,
+		`- cost: $${formatNumber(report.totalCostUsd)}`,
+		`- score: mean ${formatNumber(report.score.mean)}, median ${formatNumber(report.score.median)}, p90 ${formatNumber(report.score.p90)}, n=${report.score.n}`,
+		"",
+		"## Task Kinds",
+		"",
+		renderSliceTable(report.byTaskKind),
+		"",
+		"## Splits",
+		"",
+		renderSliceTable(report.bySplit),
+		"",
+		"## Dimensions",
+		"",
+		"| dimension | n | mean | p90 |",
+		"| --- | ---: | ---: | ---: |",
+		...Object.entries(report.dimensions).sort(([a], [b]) => a.localeCompare(b)).map(([key, dist]) => `| ${key} | ${dist.n} | ${formatNumber(dist.mean)} | ${formatNumber(dist.p90)} |`),
+		""
+	].join("\n");
+}
+function buildKnowledgeBenchmarkScenarios(cases, splits) {
+	const splitSet = splits ? new Set(splits) : null;
+	return cases.flatMap((testCase) => {
+		const splitTag = testCase.split ?? "dev";
+		if (splitSet && !splitSet.has(splitTag)) return [];
+		return [compactObject({
+			id: testCase.id,
+			kind: "knowledge-benchmark",
+			family: testCase.family,
+			taskKind: testCase.taskKind,
+			splitTag,
+			tags: unique([splitTag, ...testCase.tags ?? []]),
+			case: compactObject(testCase)
+		})];
+	});
+}
+function knowledgeBenchmarkJudge() {
+	return {
+		name: "knowledge-benchmark",
+		judgeVersion: "agent-knowledge:knowledge-benchmark:v2",
+		dimensions: [
+			{
+				key: "score",
+				description: "primary knowledge benchmark score"
+			},
+			{
+				key: "passed",
+				description: "1 when the benchmark case passes"
+			},
+			{
+				key: "claim_recall",
+				description: "required claim coverage"
+			},
+			{
+				key: "citation_recall",
+				description: "expected citation/source coverage"
+			},
+			{
+				key: "hallucination_safe",
+				description: "1 when no forbidden claim appears"
+			},
+			{
+				key: "memory_fact_recall",
+				description: "current memory fact coverage"
+			},
+			{
+				key: "memory_event_recall",
+				description: "expected memory event/source coverage"
+			},
+			{
+				key: "memory_stale_safe",
+				description: "1 when obsolete memory is not reused"
+			},
+			{
+				key: "memory_actor_recall",
+				description: "expected speaker/user attribution coverage"
+			}
+		],
+		appliesTo: (scenario) => scenario.kind === "knowledge-benchmark",
+		score({ artifact, scenario }) {
+			const evaluation = scoreKnowledgeBenchmarkArtifact(scenario.case, artifact);
+			return {
+				dimensions: {
+					score: evaluation.score,
+					passed: evaluation.passed ? 1 : 0,
+					...evaluation.dimensions
+				},
+				composite: evaluation.score,
+				notes: evaluation.notes
+			};
+		}
+	};
+}
+//#endregion
+//#region src/benchmarks/memory-runner.ts
+const MEMORY_ADAPTER_BENCHMARK_IMPLEMENTATION_REF = "agent-knowledge:memory-adapter-benchmark:v7";
+async function runMemoryAdapterBenchmark(options) {
+	if (options.candidates.length === 0) throw new Error("memory adapter benchmark requires candidates");
+	const allCandidates = [...options.candidates, ...options.recoveryCandidates ?? []];
+	assertUniqueNonEmptyStrings(allCandidates.map((candidate) => candidate.id), "memory adapter candidate id");
+	for (const candidate of allCandidates) {
+		assertNonEmptyBenchmarkString(candidate.ref, `memory adapter candidate ${candidate.id} ref`);
+		if (candidate.adapterId !== void 0) assertNonEmptyBenchmarkString(candidate.adapterId, `memory adapter candidate ${candidate.id} adapterId`);
+		if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(candidate.id)) throw new Error(`memory adapter candidate id '${candidate.id}' must be a safe directory segment`);
+		if (candidate.adapterCreationCostUsd !== void 0 && (!Number.isFinite(candidate.adapterCreationCostUsd) || candidate.adapterCreationCostUsd < 0)) throw new Error(`${candidate.id}: adapterCreationCostUsd must be a non-negative finite number`);
+		if (candidate.costUsdPerCase !== void 0 && (!Number.isFinite(candidate.costUsdPerCase) || candidate.costUsdPerCase < 0)) throw new Error(`${candidate.id}: costUsdPerCase must be a non-negative finite number`);
+		if (candidate.recoveryCostUsdPerAttempt !== void 0 && (!Number.isFinite(candidate.recoveryCostUsdPerAttempt) || candidate.recoveryCostUsdPerAttempt < 0)) throw new Error(`${candidate.id}: recoveryCostUsdPerAttempt must be a non-negative finite number`);
+	}
+	const storage = options.storage ?? fsCampaignStorage();
+	if (!storage.append) throw new Error("memory adapter benchmark requires CampaignStorage.append");
+	const runDir = resolveRunDir(options.runDir, options.repo);
+	const cleanupTimeoutMs = resolveMemoryCleanupTimeoutMs(options.cleanupTimeoutMs, "memory adapter benchmark");
+	const maxRecoveryAttempts = options.maxRecoveryAttempts ?? 1e3;
+	if (!Number.isSafeInteger(maxRecoveryAttempts) || maxRecoveryAttempts <= 0) throw new Error("memory adapter benchmark maxRecoveryAttempts must be a positive safe integer");
+	const maxRecoveryRetriesPerAttempt = options.maxRecoveryRetriesPerAttempt ?? 3;
+	if (!Number.isSafeInteger(maxRecoveryRetriesPerAttempt) || maxRecoveryRetriesPerAttempt <= 0) throw new Error("memory adapter benchmark maxRecoveryRetriesPerAttempt must be a positive safe integer");
+	storage.ensureDir(runDir);
+	const lease = await acquireAgentMemoryRunLease({
+		experimentId: `memory-adapter-benchmark:${runDir}`,
+		runDir,
+		storage,
+		customStorage: options.storage !== void 0,
+		lockFileName: "memory-adapter-benchmark.lock",
+		label: "memory adapter benchmark",
+		controllerMode: options.controllerMode,
+		acquireRunLease: options.acquireRunLease
+	});
+	let result;
+	let primaryError;
+	try {
+		result = await runOwnedMemoryAdapterBenchmark(options, storage, runDir, lease, cleanupTimeoutMs, maxRecoveryAttempts, maxRecoveryRetriesPerAttempt);
+	} catch (error) {
+		primaryError = error;
+	}
+	let releaseError;
+	try {
+		await lease.release();
+	} catch (error) {
+		releaseError = error;
+	}
+	if (primaryError && releaseError) throw new AggregateError([primaryError, releaseError], "memory adapter benchmark failed and its controller lease could not be released");
+	if (primaryError) throw primaryError;
+	if (releaseError) throw releaseError;
+	if (!result) throw new Error("memory adapter benchmark produced no result");
+	return result;
+}
+async function runOwnedMemoryAdapterBenchmark(options, storage, runDir, lease, cleanupTimeoutMs, maxRecoveryAttempts, maxRecoveryRetriesPerAttempt) {
+	const maxConcurrency = options.maxConcurrency ?? 2;
+	if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) throw new Error("memory adapter benchmark maxConcurrency must be a positive safe integer");
+	const costCeiling = options.costCeiling ?? options.costLedger?.costCeilingUsd ?? 0;
+	const costLedger = options.costLedger ?? createRunCostLedger({
+		storage,
+		runDir,
+		costCeilingUsd: costCeiling
+	});
+	if (costLedger.costCeilingUsd !== costCeiling) throw new Error("memory adapter benchmark costCeiling must match the shared cost ledger ceiling");
+	const attemptLogPath = join(runDir, "memory-adapter-attempts.jsonl");
+	const recoveryLogPath = join(runDir, "memory-adapter-recovery-attempts.jsonl");
+	await recoverMemoryAdapterBenchmarkAttempts({
+		candidates: [...options.candidates, ...options.recoveryCandidates ?? []],
+		storage,
+		attemptLogPath,
+		lease,
+		cleanupTimeoutMs,
+		maxConcurrency,
+		now: options.now,
+		runDir,
+		costLedger,
+		costPhase: options.costPhase ?? "memory.adapter-benchmark",
+		maxRecoveryAttempts,
+		recoveryLogPath,
+		maxRecoveryRetriesPerAttempt
+	});
+	await lease.assertOwned();
+	const rows = [];
+	for (const candidate of options.candidates) {
+		await lease.assertOwned();
+		const expectedAdapterId = memoryAdapterBenchmarkExpectedId(candidate);
+		let adapter;
+		let adapterPromise;
+		let adapterCreationError;
+		const getAdapter = () => {
+			if (!adapterPromise) {
+				const abortController = new AbortController();
+				const creation = createMemoryAdapterBenchmarkAdapter({
+					candidate,
+					purpose: "execute",
+					signal: abortController.signal,
+					costLedger,
+					runDir,
+					costPhase: options.costPhase ?? "memory.adapter-benchmark"
+				});
+				releaseMemoryAdapterCreatedAfterAbort({
+					creation,
+					signal: abortController.signal
+				});
+				adapterPromise = runBoundedMemoryLifecycle({
+					operation: `${candidate.id}: benchmark execute adapter creation`,
+					timeoutMs: Math.min(cleanupTimeoutMs, options.dispatchTimeoutMs ?? cleanupTimeoutMs),
+					abortController,
+					run: () => creation
+				}).then((created) => {
+					adapter = created;
+					if (created.id !== expectedAdapterId) throw new Error(`${candidate.id}: createAdapter returned id '${created.id}', expected '${expectedAdapterId}'`);
+					assertScopedMemoryBenchmarkAdapter(created);
+					return created;
+				}).catch((error) => {
+					adapterCreationError = error;
+					throw error;
+				});
+			}
+			return adapterPromise;
+		};
+		const dispatchedExecutions = [];
+		let run;
+		let primaryError;
+		try {
+			await lease.assertOwned();
+			let respond;
+			run = await runKnowledgeBenchmarkSuite({
+				cases: options.cases,
+				respond(input) {
+					const operation = getAdapter().then((activeAdapter) => {
+						respond ??= createMemoryAdapterBenchmarkResponder({
+							adapter: activeAdapter,
+							candidateId: candidate.id,
+							candidateRef: candidate.ref,
+							storage,
+							attemptLogPath,
+							lease,
+							cleanupTimeoutMs,
+							searchLimit: candidate.searchLimit,
+							scope: candidate.scope,
+							adapterCreationCostUsd: candidate.adapterCreationCostUsd,
+							costUsdPerCase: candidate.costUsdPerCase,
+							recoveryCostUsdPerAttempt: candidate.recoveryCostUsdPerAttempt,
+							now: options.now
+						});
+						return respond(input);
+					});
+					dispatchedExecutions.push(operation);
+					return operation;
+				},
+				respondRef: stableId("memory_adapter_benchmark", canonicalJson({
+					implementationRef: MEMORY_ADAPTER_BENCHMARK_IMPLEMENTATION_REF,
+					candidateRef: candidate.ref,
+					adapterId: expectedAdapterId,
+					searchLimit: candidate.searchLimit ?? null,
+					adapterCreationCostUsd: candidate.adapterCreationCostUsd ?? 0,
+					costUsdPerCase: candidate.costUsdPerCase ?? 0,
+					recoveryCostUsdPerAttempt: candidate.recoveryCostUsdPerAttempt ?? 0,
+					scope: candidate.scope ?? null
+				})),
+				runDir: join(runDir, candidate.id),
+				storage,
+				seed: options.seed,
+				reps: options.reps,
+				resumable: options.resumable,
+				costCeiling,
+				costLedger,
+				costPhase: `${options.costPhase ?? "memory.adapter-benchmark"}.${candidate.id}`,
+				maxConcurrency: options.maxConcurrency,
+				dispatchTimeoutMs: options.dispatchTimeoutMs,
+				expectUsage: options.expectUsage ?? "off",
+				now: options.now
+			});
+		} catch (error) {
+			primaryError = error;
+		}
+		const dispatchCleanupErrors = (await Promise.allSettled(dispatchedExecutions)).flatMap((settled) => settled.status === "rejected" && settled.reason instanceof MemoryAdapterBenchmarkCleanupError ? [settled.reason] : []);
+		if (!primaryError && adapterCreationError) primaryError = adapterCreationError;
+		if (run) rows.push({
+			rank: 0,
+			candidateId: candidate.id,
+			label: candidate.label ?? candidate.id,
+			adapterId: expectedAdapterId,
+			scoreMean: run.report.score.mean,
+			passRate: run.report.dimensions.passed?.mean ?? 0,
+			totalCases: run.report.totalCases,
+			totalCells: run.report.totalCells,
+			cellsFailed: run.report.cellsFailed,
+			totalCostUsd: run.report.totalCostUsd,
+			reportJsonPath: run.reportJsonPath,
+			reportMarkdownPath: run.reportMarkdownPath,
+			report: run.report
+		});
+		const cleanupErrors = [];
+		let cleanupOwned = true;
+		try {
+			await lease.assertOwned();
+		} catch (error) {
+			cleanupOwned = false;
+			cleanupErrors.push(error);
+		}
+		if (cleanupOwned && adapter && !adapterCreationError) {
+			const activeAdapter = adapter;
+			try {
+				await runBoundedMemoryLifecycle({
+					operation: `${candidate.id}: benchmark adapter flush`,
+					timeoutMs: cleanupTimeoutMs,
+					resource: activeAdapter,
+					run: () => activeAdapter.flush?.()
+				});
+			} catch (error) {
+				cleanupErrors.push(error);
+			}
+		}
+		if (adapter) try {
+			await runBoundedMemoryLifecycle({
+				operation: `${candidate.id}: benchmark adapter close`,
+				timeoutMs: cleanupTimeoutMs,
+				resource: adapter,
+				run: () => adapter.close?.()
+			});
+		} catch (error) {
+			cleanupErrors.push(error);
+		}
+		if (primaryError || dispatchCleanupErrors.length > 0 || cleanupErrors.length > 0) {
+			const errors = [
+				...primaryError ? [primaryError] : [],
+				...dispatchCleanupErrors,
+				...cleanupErrors
+			];
+			if (errors.length === 1) throw errors[0];
+			throw new AggregateError(errors, `${candidate.id}: memory adapter benchmark cleanup failed`);
+		}
+		await lease.assertOwned();
+	}
+	const costByCandidate = memoryAdapterBenchmarkCostByCandidate(costLedger, runDir, [...options.candidates, ...options.recoveryCandidates ?? []]);
+	const ranked = rows.map((row) => {
+		const totalCostUsd = normalizeUsd(costByCandidate.get(row.candidateId) ?? 0);
+		return {
+			...row,
+			totalCostUsd
+		};
+	}).sort((a, b) => Number(a.cellsFailed > 0) - Number(b.cellsFailed > 0) || b.scoreMean - a.scoreMean || b.passRate - a.passRate || a.totalCostUsd - b.totalCostUsd || a.candidateId.localeCompare(b.candidateId)).map((row, index) => ({
+		...row,
+		rank: index + 1
+	}));
+	const rankingJsonPath = join(runDir, "memory-adapter-ranking.json");
+	const rankingMarkdownPath = join(runDir, "memory-adapter-ranking.md");
+	const unrankedRecoveryCostUsd = normalizeUsd((options.recoveryCandidates ?? []).reduce((sum, candidate) => sum + (costByCandidate.get(candidate.id) ?? 0), 0));
+	const totalCostUsd = normalizeUsd([...costByCandidate.values()].reduce((sum, cost) => sum + cost, 0));
+	storage.write(rankingJsonPath, `${JSON.stringify({
+		totalCostUsd,
+		unrankedRecoveryCostUsd,
+		rows: ranked
+	}, null, 2)}\n`);
+	storage.write(rankingMarkdownPath, renderMemoryAdapterRankingMarkdown(ranked, totalCostUsd, unrankedRecoveryCostUsd));
+	return {
+		rows: ranked,
+		totalCostUsd,
+		unrankedRecoveryCostUsd,
+		rankingJsonPath,
+		rankingMarkdownPath,
+		attemptLogPath,
+		recoveryLogPath
+	};
+}
+async function createMemoryAdapterBenchmarkAdapter(input) {
+	const { candidate, purpose, signal, costLedger, runDir, costPhase } = input;
+	const costUsd = candidate.adapterCreationCostUsd ?? 0;
+	let externalCallAttempted = false;
+	const create = async () => {
+		const adapter = await candidate.createAdapter({
+			purpose,
+			signal,
+			markExternalCall: () => {
+				externalCallAttempted = true;
+			}
+		});
+		if (!adapter || typeof adapter !== "object") throw new Error(`${candidate.id}: createAdapter returned no ${purpose} adapter`);
+		return adapter;
+	};
+	if (costUsd === 0) return create();
+	const tags = memoryAdapterCreationCostTags(runDir, candidate.id, purpose);
+	const generation = costLedger.list({ tags }).length;
+	const receipt = {
+		model: candidate.id,
+		inputTokens: 0,
+		outputTokens: 0,
+		actualCostUsd: costUsd
+	};
+	const paid = await costLedger.runPaidCall({
+		callId: memoryAdapterCreationCostCallId(candidate, purpose, generation),
+		channel: "driver",
+		phase: `${costPhase}.${candidate.id}.adapter-${purpose}`,
+		actor: `agent-knowledge:memory-adapter:${candidate.id}`,
+		model: candidate.id,
+		tags,
+		maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
+		execute: create,
+		receipt: () => ({
+			...receipt,
+			actualCostUsd: externalCallAttempted ? costUsd : 0
+		}),
+		receiptFromError: () => ({
+			...receipt,
+			actualCostUsd: externalCallAttempted ? costUsd : 0
+		})
+	});
+	if (!paid.succeeded) throw paid.error;
+	return paid.value;
+}
+function memoryAdapterCreationCostTags(runDir, candidateId, purpose) {
+	return {
+		runDir: join(runDir, candidateId),
+		candidateId,
+		memoryAdapterCreation: purpose
+	};
+}
+function memoryAdapterCreationCostCallId(candidate, purpose, generation) {
+	return stableId("memory_adapter_creation_cost_call", canonicalJson({
+		purpose,
+		generation,
+		candidateId: candidate.id,
+		candidateRef: candidate.ref,
+		adapterCreationCostUsd: candidate.adapterCreationCostUsd ?? 0
+	}));
+}
+function memoryAdapterBenchmarkCostByCandidate(costLedger, runDir, candidates) {
+	const candidateByRunDir = new Map(candidates.map((candidate) => [join(runDir, candidate.id), candidate.id]));
+	const totals = /* @__PURE__ */ new Map();
+	for (const receipt of costLedger.list()) {
+		const candidateId = receipt.tags?.runDir ? candidateByRunDir.get(receipt.tags.runDir) : void 0;
+		if (!candidateId) continue;
+		totals.set(candidateId, (totals.get(candidateId) ?? 0) + receipt.costUsd);
+	}
+	return totals;
+}
+function renderMemoryAdapterRankingMarkdown(rows, totalCostUsd, unrankedRecoveryCostUsd) {
+	return [
+		"# Memory Adapter Ranking",
+		"",
+		`- total cost: $${formatNumber(totalCostUsd)}`,
+		`- retired-candidate recovery cost: $${formatNumber(unrankedRecoveryCostUsd)}`,
+		"",
+		"| rank | candidate | adapter | cases | cells | failed | mean score | pass rate | cost |",
+		"| ---: | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+		...rows.map((row) => `| ${row.rank} | ${row.label} | ${row.adapterId} | ${row.totalCases} | ${row.totalCells} | ${row.cellsFailed} | ${formatNumber(row.scoreMean)} | ${formatNumber(row.passRate)} | $${formatNumber(row.totalCostUsd)} |`),
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/benchmarks/retrieval.ts
+function parseKnowledgeBenchmarkJsonl(text) {
+	return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line, index) => {
+		try {
+			return JSON.parse(line);
+		} catch (error) {
+			throw new Error(`invalid JSONL row ${index + 1}: ${error.message}`);
+		}
+	});
+}
+function parseKnowledgeBenchmarkQrels(text) {
+	return text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).flatMap((line, index) => {
+		const parts = line.split(/\t|\s+/);
+		if (parts.length < 3) return [];
+		const [queryId, maybeZeroOrDocId, maybeDocIdOrScore, maybeScore] = parts;
+		if (!queryId || !maybeZeroOrDocId || !maybeDocIdOrScore) return [];
+		if (queryId.toLowerCase() === "qid" || queryId.toLowerCase() === "query-id") return [];
+		const documentId = maybeScore === void 0 ? maybeZeroOrDocId : maybeDocIdOrScore;
+		const score = Number(maybeScore === void 0 ? maybeDocIdOrScore : maybeScore);
+		if (!documentId || !Number.isFinite(score)) throw new Error(`invalid qrels row ${index + 1}: expected query id, doc id, score`);
+		return [{
+			queryId,
+			documentId,
+			score
+		}];
+	});
+}
+function buildRetrievalBenchmarkCasesFromQrels(options) {
+	const qrelsByQuery = /* @__PURE__ */ new Map();
+	for (const qrel of options.qrels) {
+		if (qrel.score <= 0) continue;
+		const list = qrelsByQuery.get(qrel.queryId) ?? [];
+		list.push(qrel);
+		qrelsByQuery.set(qrel.queryId, list);
+	}
+	return options.queries.flatMap((query) => {
+		const qrels = qrelsByQuery.get(query.id) ?? [];
+		if (qrels.length === 0) return [];
+		const split = query.split ?? options.splitOf?.(query.id);
+		const expected = qrels.map((qrel) => options.documentTarget ? options.documentTarget(qrel.documentId, qrel) : defaultDocumentTarget(qrel.documentId, options.targetKind ?? "page"));
+		return [compactObject({
+			id: `${options.benchmarkId}:${query.id}`,
+			family: options.family,
+			taskKind: "retrieval",
+			query: query.text,
+			expected,
+			k: options.k,
+			split,
+			tags: unique([
+				...options.tags ?? [],
+				...query.tags ?? [],
+				...split ? [split] : []
+			]),
+			source: options.source,
+			metadata: query.metadata
+		})];
+	});
+}
+function defaultDocumentTarget(documentId, targetKind) {
+	switch (targetKind) {
+		case "page": return {
+			kind: "page",
+			pageId: documentId
+		};
+		case "page-path": return {
+			kind: "page-path",
+			path: documentId
+		};
+		case "source": return {
+			kind: "source",
+			sourceId: documentId
+		};
+	}
+}
+//#endregion
+export { INDUSTRY_RAG_BENCHMARKS as A, memoryWriteResultToSourceRecord as B, appendDurableJournalEvent as C, reconcileInterruptedMemoryPaidCalls as D, readActiveAttemptJournal as E, respondToIndustryRagBenchmarkSmokeCase as F, retrievalRecallJudge as G, partitionRetrievalScenarios as H, isKnowledgeMemoryBenchmarkCase as I, scoreRetrievalArtifact as K, createInMemoryBenchmarkAdapter as L, buildIndustryMemoryBenchmarkSmokeCases as M, buildIndustryRagBenchmarkSmokeCases as N, reserveRecoveryAttempts as O, respondToIndustryMemoryBenchmarkSmokeCase as P, createNoopMemoryBenchmarkAdapter as R, appendAttemptJournalEvent as S, hasSettledPaidCall as T, retrievalConfigFromSurface as U, buildRetrievalEvalDispatch as V, retrievalConfigSurface as W, memoryRecoveryDelayMs as _, buildKnowledgeBenchmarkScenarios as a, runBoundedMemoryLifecycle as b, runKnowledgeBenchmarkSuite as c, summarizeKnowledgeBenchmarkCampaign as d, acquireAgentMemoryRunLease as f, createMemoryExecutionPool as g, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as h, runMemoryAdapterBenchmark as i, buildFirstPartyMemoryLifecycleBenchmarkCases as j, INDUSTRY_MEMORY_BENCHMARKS as k, scoreKnowledgeBenchmarkArtifact as l, AgentMemoryLifecycleUnsafeError as m, parseKnowledgeBenchmarkJsonl as n, knowledgeBenchmarkJudge as o, AgentMemoryLifecycleTimeoutError as p, parseKnowledgeBenchmarkQrels as r, renderKnowledgeBenchmarkReportMarkdown as s, buildRetrievalBenchmarkCasesFromQrels as t, scoreMemoryBenchmarkArtifact as u, releaseMemoryAdapterCreatedAfterAbort as v, assertNoInterruptedPaidCalls as w, sleepForMemoryRecovery as x, resolveMemoryCleanupTimeoutMs as y, memoryHitToSourceRecord as z };
+
+//# sourceMappingURL=benchmarks-CmW6iORW.js.map