@tangle-network/agent-knowledge 22.0.1 → 22.0.3

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as snapshotSourceTextInput, $n as textSourceAdapter, $t as ClaimLedgerGoalConflictError, A as validateKnowledgePage, An as knowledgeFileTransactionPlanHash, At as knowledgePageFromMarkdown, B as DEADLINE_EXIT_CODE, Bn as readRegularFileNoFollow, Bt as KnowledgeGraphEdgeSchema, C as immutablePageDigest, Cn as withKnowledgeMutation, Ct as resolveKnowledgeCitations, D as normalizeVisibilityArtifact, Dn as assertKnowledgeMutationPath, Dt as initKnowledgeBase, E as nonEmpty$1, En as applyKnowledgeFileTransaction, Et as SCAFFOLD_PAGE_BASENAMES, F as detectNearDuplicatePages, Fn as canonicalPathsEqual, Ft as extractWikilinks, G as gradeFor, Gn as syncDirectory, Gt as KnowledgeRelationSchema, H as assertGradeableEvidence, Hn as relativeWithinRoot, Ht as KnowledgeIndexSchema, I as normalizePageText, In as canonicalRelativeWithinRoot, It as normalizeLinkTarget, J as buildKnowledgeIndex, Jn as writeFileDurable, Jt as ResearchClaimRecordSchema, K as verdictFor, Kn as withSafeDescendant, Kt as ResearchClaimEvidenceSchema, L as validateKnowledgeIndex, Ln as isKernelAnchoredPath, Lt as DeepQuestionSchema, M as verifyKnowledgeVisibilitySnapshot, Mn as rollbackKnowledgeFileTransaction, Mt as loadKnowledgePages, N as visibilityIdentity, Nn as DEFAULT_PAGES_DIRECTORY, Nt as writeJson, O as normalizeVisibilityRef, On as commitKnowledgeFileMutations, Ot as isKnowledgePagePath, P as visibilityIndexOf, Pn as normalizePagesDirectory, Pt as WIKILINK_REGEX, Q as loadSourceRegistry, Qn as mediaTypeFor, Qt as KNOWLEDGE_EVENT_TYPES, R as lintKnowledgeIndex, Rn as isMissingFile, Rt as KnowledgeBaseCandidateSchema, S as encodeKnowledgeVisibilitySnapshot, Sn as runInKnowledgeMutationScope, St as resolveKnowledgeCitation, T as knowledgeVisibilityArtifactRef, Tn as withKnowledgeRead, Tt as resolveRunScopedCitations, U as claimCheckKey, Un as removeDurable, Ut as KnowledgePageInvalidationSchema, V as UncheckableClaimError, Vn as readRegularFileWithinRoot, Vt as KnowledgeGraphNodeSchema, W as gradeClaims, Wn as renameDurable, Wt as KnowledgePageSchema, X as addSourcePath, Xn as writeJsonDurable, Xt as SourceAnchorSchema, Y as writeKnowledgeIndex, Yn as writeFileDurableWithinRoot, Yt as ResearchSourceVersionSchema, Z as addSourceText, Zn as writeJsonDurableWithinRoot, Zt as SourceRecordSchema, _ as KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION, _n as acquireDurableFileLock, _t as assertRunScopedCitationsResolved, a as applyKnowledgeWriteBlocksFile, an as claimId, at as KB_EVENTS_PATH, b as decodeKnowledgeVisibilitySnapshot, bn as measureKnowledgeMutation, bt as formatKnowledgeCitationReference, c as KnowledgeDuplicateIntakeError, cn as emptyClaimLedger, ct as MemoryKbStore, d as createFileRunLineageAuthority, dn as mergeClaimLedgers, dt as knowledgePageRelations, en as assertDeepQuestionIntegrity, et as sourceRegistryPath, f as createRunScopedStores, fn as mergeTrackedClaims, ft as KnowledgeCitationAuditError, g as KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM, gn as parseFrontmatter, gt as assertKnowledgeCitationsResolved, h as originatedPages, hn as formatFrontmatter, ht as assertKnowledgeCitationAudit, i as applyKnowledgeWriteBlocks, in as claimEvidenceId, it as KB_CLAIM_LEDGER_DIR, j as validateOrigin, jn as prepareKnowledgeFileTransaction, jt as layoutFor, k as snapshotImmutableVisibility, kn as finishKnowledgeFileTransaction, kt as isScaffoldPath, l as assertKnowledgeWriteIntake, ln as linkClaimContradictions, lt as assertClaimLedgerId, m as loadKnowledgeToolChain, mn as researchSourceVersionKey, mt as assertCurrentRunCitationsResolved, n as inspectKnowledgeIndex, nn as assertResearchClaimLedgerIntegrity, nt as ClaimLedgerMigrationRequiredError, o as isSafeKnowledgePath, on as claimSourceHost, ot as KB_INDEX_PATH, p as isKnowledgeToolChain, pn as normalizeClaimText, pt as KnowledgeCitationResolutionError, q as verifyGradeableEvidence, qn as withSafeDirectory, qt as ResearchClaimLedgerSchema, r as stringMetadata, rn as assertTrackedClaimIntegrity, rt as FileSystemKbStore, s as parseKnowledgeWriteBlocks, sn as deepQuestionId, st as KB_STORE_DIR, t as explainKnowledgeTarget, tn as assertResearchClaimEvidenceIntegrity, tt as writeSourceRegistry, u as RUN_LINEAGE_BASENAME, un as materializeRegisteredClaimEvidence, ut as buildKnowledgeGraph, v as assertSchemaVersion, vn as inspectPendingKnowledgeMutation, vt as auditCurrentRunCitations, w as knowledgePageDigest, wn as withKnowledgeMutationLabel, wt as resolveRunScopedCitation, x as digest, xn as recoverPendingKnowledgeMutation, xt as parseKnowledgeCitationReference, y as createKnowledgeVisibilitySnapshot, yn as isKnowledgeMutationHeld, yt as auditKnowledgeCitations, z as CHECKABLE_RUNG_THRESHOLD, zn as listRegularFilesWithinRoot, zt as KnowledgeEventSchema } from "./inspect-DBxyQSdt.js";
+import { $ as loadSourceRegistry, $n as mediaTypeFor, $t as KNOWLEDGE_EVENT_TYPES, A as validateKnowledgePage, An as finishKnowledgeFileTransaction, At as isScaffoldPath, B as CHECKABLE_RUNG_THRESHOLD, Bn as listRegularFilesWithinRoot, Bt as KnowledgeEventSchema, C as immutablePageDigest, Cn as runInKnowledgeMutationScope, Ct as resolveKnowledgeCitation, D as normalizeVisibilityArtifact, Dn as applyKnowledgeFileTransaction, Dt as SCAFFOLD_PAGE_BASENAMES, E as nonEmpty$1, En as withKnowledgeRead, Et as resolveRunScopedCitations, F as detectNearDuplicatePages, Fn as normalizePagesDirectory, Ft as WIKILINK_REGEX, G as gradeClaims, Gn as renameDurable, Gt as KnowledgePageSchema, H as UncheckableClaimError, Hn as readRegularFileWithinRoot, Ht as KnowledgeGraphNodeSchema, I as normalizePageText, In as canonicalPathsEqual, It as extractWikilinks, J as verifyGradeableEvidence, Jn as withSafeDirectory, Jt as ResearchClaimLedgerSchema, K as gradeFor, Kn as syncDirectory, Kt as KnowledgeRelationSchema, L as prepareKnowledgeValidation, Ln as canonicalRelativeWithinRoot, Lt as normalizeLinkTarget, M as verifyKnowledgeVisibilitySnapshot, Mn as prepareKnowledgeFileTransaction, Mt as layoutFor, N as visibilityIdentity, Nn as rollbackKnowledgeFileTransaction, Nt as loadKnowledgePages, O as normalizeVisibilityRef, On as assertKnowledgeMutationPath, Ot as initKnowledgeBase, P as visibilityIndexOf, Pn as DEFAULT_PAGES_DIRECTORY, Pt as writeJson, Q as addSourceText, Qn as writeJsonDurableWithinRoot, Qt as SourceRecordSchema, R as validateKnowledgeIndex, Rn as isKernelAnchoredPath, Rt as DeepQuestionSchema, S as encodeKnowledgeVisibilitySnapshot, Sn as recoverPendingKnowledgeMutation, St as parseKnowledgeCitationReference, T as knowledgeVisibilityArtifactRef, Tn as withKnowledgeMutationLabel, Tt as resolveRunScopedCitation, U as assertGradeableEvidence, Un as relativeWithinRoot, Ut as KnowledgeIndexSchema, V as DEADLINE_EXIT_CODE, Vn as readRegularFileNoFollow, Vt as KnowledgeGraphEdgeSchema, W as claimCheckKey, Wn as removeDurable, Wt as KnowledgePageInvalidationSchema, X as writeKnowledgeIndex, Xn as writeFileDurableWithinRoot, Xt as ResearchSourceVersionSchema, Y as buildKnowledgeIndex, Yn as writeFileDurable, Yt as ResearchClaimRecordSchema, Z as addSourcePath, Zn as writeJsonDurable, Zt as SourceAnchorSchema, _ as KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION, _n as parseFrontmatter, _t as assertKnowledgeCitationsResolved, a as applyKnowledgeWriteBlocksFile, an as claimEvidenceId, at as KB_CLAIM_LEDGER_DIR, b as decodeKnowledgeVisibilitySnapshot, bn as isKnowledgeMutationHeld, bt as auditKnowledgeCitations, c as KnowledgeDuplicateIntakeError, cn as deepQuestionId, ct as KB_STORE_DIR, d as createFileRunLineageAuthority, dn as materializeRegisteredClaimEvidence, dt as buildKnowledgeGraph, en as ClaimLedgerGoalConflictError, er as textSourceAdapter, et as snapshotSourceTextInput, f as createRunScopedStores, fn as mergeClaimLedgers, ft as knowledgePageRelations, g as KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM, gn as formatFrontmatter, gt as assertKnowledgeCitationAudit, h as originatedPages, hn as researchSourceVersionKey, ht as assertCurrentRunCitationsResolved, i as applyKnowledgeWriteBlocks, in as assertTrackedClaimIntegrity, it as FileSystemKbStore, j as validateOrigin, jn as knowledgeFileTransactionPlanHash, jt as knowledgePageFromMarkdown, k as snapshotImmutableVisibility, kn as commitKnowledgeFileMutations, kt as isKnowledgePagePath, l as assertKnowledgeWriteIntake, ln as emptyClaimLedger, lt as MemoryKbStore, m as loadKnowledgeToolChain, mn as normalizeClaimText, mt as KnowledgeCitationResolutionError, n as inspectKnowledgeIndex, nn as assertResearchClaimEvidenceIntegrity, nt as writeSourceRegistry, o as isSafeKnowledgePath, on as claimId, ot as KB_EVENTS_PATH, p as isKnowledgeToolChain, pn as mergeTrackedClaims, pt as KnowledgeCitationAuditError, q as verdictFor, qn as withSafeDescendant, qt as ResearchClaimEvidenceSchema, r as stringMetadata, rn as assertResearchClaimLedgerIntegrity, rt as ClaimLedgerMigrationRequiredError, s as parseKnowledgeWriteBlocks, sn as claimSourceHost, st as KB_INDEX_PATH, t as explainKnowledgeTarget, tn as assertDeepQuestionIntegrity, tt as sourceRegistryPath, u as RUN_LINEAGE_BASENAME, un as linkClaimContradictions, ut as assertClaimLedgerId, v as assertSchemaVersion, vn as acquireDurableFileLock, vt as assertRunScopedCitationsResolved, w as knowledgePageDigest, wn as withKnowledgeMutation, wt as resolveKnowledgeCitations, x as digest, xn as measureKnowledgeMutation, xt as formatKnowledgeCitationReference, y as createKnowledgeVisibilitySnapshot, yn as inspectPendingKnowledgeMutation, yt as auditCurrentRunCitations, z as lintKnowledgeIndex, zn as isMissingFile, zt as KnowledgeBaseCandidateSchema } from "./inspect-rnlXAb4O.js";
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
 import { a as buildKnowledgeLexicalIndex, c as tokenizeText, d as lexicalPageTerms, i as searchKnowledgePages, l as DEFAULT_FIELD_BOOSTS, n as reciprocalRankFusion, o as scoreBm25, r as searchKnowledge, s as tokenizeQuery, t as KNOWLEDGE_SEARCH_RETRIEVER_ID, u as assembleLexicalIndex } from "./search-aZdP2685.js";
 import { n as memoryWriteResultToSourceRecord, t as memoryHitToSourceRecord } from "./source-record-CdWvzvO6.js";
@@ -520,10 +520,177 @@ function exceedsCostCeiling$1(totalCostUsd, costCeiling) {
 	return totalCostUsd - costCeiling > tolerance;
 }
 //#endregion
+//#region src/optimization.ts
+/**
+* Runs one complete agent-eval method over a serialized knowledge candidate.
+* The method receives train and selection data; agent-eval owns final scoring.
+*/
+async function runSerializedKnowledgeOptimization(options) {
+	assertCompleteOptimizationMethod(options.method);
+	assertImmutableRef(options.executionRef, "knowledge optimization executionRef");
+	const codec = options.codec ?? jsonCandidateCodec();
+	const baseline = normalizeCandidate(options.baseline, codec, "baseline");
+	const dispatchRef = [
+		"knowledge-optimization",
+		options.executionRef,
+		baseline.surfaceHash,
+		surfaceHash(options.method.name)
+	].join(":");
+	assertPartitionContent(options.trainScenarios, options.selectionScenarios, options.finalScenarios, options.scenarioFingerprint ?? scenarioContentFingerprint);
+	const method = canonicalCandidateMethod(options.method, codec);
+	const { baseline: _baseline, method: _method, trainScenarios, selectionScenarios, finalScenarios, dispatchCandidate, executionRef: _executionRef, codec: _codec, scenarioFingerprint: _scenarioFingerprint, ...comparisonOptions } = options;
+	const optimizationRunOptions = {
+		...comparisonOptions.reps !== void 0 ? { reps: comparisonOptions.reps } : {},
+		...comparisonOptions.resumable !== void 0 ? { resumable: comparisonOptions.resumable } : {},
+		...comparisonOptions.labeledStore !== void 0 ? { labeledStore: comparisonOptions.labeledStore } : {},
+		...comparisonOptions.captureSource !== void 0 ? { captureSource: comparisonOptions.captureSource } : {},
+		...comparisonOptions.captureSourceVersionHash !== void 0 ? { captureSourceVersionHash: comparisonOptions.captureSourceVersionHash } : {},
+		...comparisonOptions.maxConcurrency !== void 0 ? { maxConcurrency: comparisonOptions.maxConcurrency } : {},
+		...comparisonOptions.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: comparisonOptions.dispatchTimeoutMs } : {},
+		...comparisonOptions.repo !== void 0 ? { repo: comparisonOptions.repo } : {},
+		...comparisonOptions.tracing !== void 0 ? { tracing: comparisonOptions.tracing } : {},
+		...comparisonOptions.expectUsage !== void 0 ? { expectUsage: comparisonOptions.expectUsage } : {},
+		...comparisonOptions.now !== void 0 ? { now: comparisonOptions.now } : {},
+		...comparisonOptions.buildTraceWriter !== void 0 ? { buildTraceWriter: comparisonOptions.buildTraceWriter } : {},
+		...comparisonOptions.storage !== void 0 ? { storage: comparisonOptions.storage } : {},
+		...comparisonOptions.cellPlacement !== void 0 ? { cellPlacement: comparisonOptions.cellPlacement } : {},
+		...comparisonOptions.optimizationRunOptions ?? {},
+		dispatchRef
+	};
+	const comparison = await compareOptimizationMethods({
+		...comparisonOptions,
+		dispatchRef,
+		optimizationRunOptions,
+		methods: [method],
+		baselineSurface: baseline.surface,
+		trainScenarios: trainScenarios.map((scenario) => structuredClone(scenario)),
+		selectionScenarios: selectionScenarios.map((scenario) => structuredClone(scenario)),
+		testScenarios: finalScenarios.map((scenario) => structuredClone(scenario)),
+		dispatchWithSurface: async (surface, scenario, context) => {
+			const candidate = normalizeSurface(surface, codec, "candidate");
+			return dispatchCandidate({
+				candidate: structuredClone(candidate.value),
+				candidateSurface: candidate.surface,
+				candidateSurfaceHash: candidate.surfaceHash,
+				scenario,
+				context
+			});
+		}
+	});
+	const winner = normalizeSurface(comparison.best.winnerSurface, codec, "winner");
+	return {
+		methodName: options.method.name,
+		baseline,
+		winner,
+		comparison
+	};
+}
+function assertCompleteOptimizationMethod(method) {
+	const candidate = method;
+	if (!candidate || typeof candidate.name !== "string" || candidate.name.trim().length === 0 || typeof candidate.optimize !== "function") throw new Error("knowledge optimization requires a complete OptimizationMethod with a non-empty name and optimize()");
+}
+function jsonCandidateCodec() {
+	return {
+		serialize: (candidate) => canonicalJson(candidate),
+		parse(surface) {
+			let parsed;
+			try {
+				parsed = JSON.parse(surface);
+			} catch (error) {
+				throw new Error("serialized knowledge candidate is not valid JSON", { cause: error });
+			}
+			return parsed;
+		}
+	};
+}
+function jsonObjectCandidateCodec() {
+	const codec = jsonCandidateCodec();
+	return {
+		serialize: codec.serialize,
+		parse(surface) {
+			const candidate = codec.parse(surface);
+			if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) throw new Error("serialized knowledge candidate must be a JSON object");
+			return candidate;
+		}
+	};
+}
+function scenarioContentFingerprint(scenario) {
+	const { id: _id, tags: _tags, split: _split, splitTag: _splitTag, ...content } = scenario;
+	return surfaceHash(canonicalJson(content));
+}
+function canonicalCandidateMethod(method, codec) {
+	return {
+		name: method.name,
+		async optimize(input) {
+			const result = await method.optimize(input);
+			const winner = normalizeSurface(result.winnerSurface, codec, `${method.name} winner`);
+			return {
+				...result,
+				winnerSurface: winner.surface
+			};
+		}
+	};
+}
+function normalizeCandidate(candidate, codec, label) {
+	let surface;
+	try {
+		surface = codec.serialize(candidate);
+	} catch (error) {
+		throw new Error(`${label} serializer failed`, { cause: error });
+	}
+	return normalizeSurface(surface, codec, label);
+}
+function normalizeSurface(surface, codec, label) {
+	if (typeof surface !== "string" || surface.trim().length === 0) throw new Error(`${label} must be a non-empty serialized string`);
+	let value;
+	try {
+		value = codec.parse(surface);
+	} catch (error) {
+		const detail = error instanceof Error ? `: ${error.message}` : "";
+		throw new Error(`${label} parser failed${detail}`, { cause: error });
+	}
+	let canonicalSurface;
+	try {
+		canonicalSurface = codec.serialize(value);
+	} catch (error) {
+		throw new Error(`${label} serializer failed after parsing`, { cause: error });
+	}
+	if (typeof canonicalSurface !== "string" || canonicalSurface.trim().length === 0) throw new Error(`${label} serializer must return a non-empty string`);
+	if (codec.serialize(codec.parse(canonicalSurface)) !== canonicalSurface) throw new Error(`${label} codec must round-trip to one canonical surface`);
+	return {
+		value: structuredClone(value),
+		surface: canonicalSurface,
+		surfaceHash: surfaceHash(canonicalSurface)
+	};
+}
+function assertPartitionContent(train, selection, final, fingerprint) {
+	if (!fingerprint) return;
+	const owner = /* @__PURE__ */ new Map();
+	for (const [name, scenarios] of [
+		["train", train],
+		["selection", selection],
+		["final", final]
+	]) for (const scenario of scenarios) {
+		const identity = fingerprint(scenario);
+		if (typeof identity !== "string" || identity.trim().length === 0) throw new Error(`scenarioFingerprint returned no identity for '${scenario.id}'`);
+		const prior = owner.get(identity);
+		if (prior) {
+			const scope = prior.partition === name ? `${name} partition duplicates` : `${prior.partition}/${name} partitions duplicate`;
+			throw new Error(`serialized knowledge optimization ${scope} scenario content at '${prior.scenarioId}'/'${scenario.id}'`);
+		}
+		owner.set(identity, {
+			partition: name,
+			scenarioId: scenario.id
+		});
+	}
+}
+//#endregion
 //#region src/rag-eval/knowledge-base.ts
 function scoreKnowledgeBaseIndex(index, options = {}) {
-	const validation = validateKnowledgeIndex(index, { strict: options.strict });
-	const lintFindings = lintKnowledgeIndex(index);
+	return scoreValidatedKnowledgeBaseIndex(index, options, validateKnowledgeIndex(index, options));
+}
+/** Internal scoring over the validation of this exact index and strictness policy. */
+function scoreValidatedKnowledgeBaseIndex(index, options, validation) {
 	const now = options.now ?? /* @__PURE__ */ new Date();
 	const staleSourceCount = index.sources.filter((source) => {
 		return source.validUntil ? Date.parse(source.validUntil) < now.getTime() : false;
@@ -543,7 +710,7 @@ function scoreKnowledgeBaseIndex(index, options = {}) {
 		stale_source_rate: index.sources.length === 0 ? 0 : staleSourceCount / index.sources.length,
 		duplicate_source_hash_rate: index.sources.length === 0 ? 0 : duplicateSourceHashCount / index.sources.length,
 		lint_error_count: validation.findings.filter((finding) => finding.severity === "error").length,
-		lint_warning_count: lintFindings.filter((finding) => finding.severity === "warning").length,
+		lint_warning_count: validation.findings.filter((finding) => finding.severity === "warning").length,
 		near_duplicate_page_rate: nearDuplicates.duplicatePageRate,
 		near_duplicate_page_count: nearDuplicates.duplicatePageCount,
 		near_duplicate_pair_count: nearDuplicates.duplicatePairCount
@@ -1233,171 +1400,6 @@ function below(metric, threshold) {
 	return threshold !== void 0 && metric < threshold;
 }
 //#endregion
-//#region src/optimization.ts
-/**
-* Runs one complete agent-eval method over a serialized knowledge candidate.
-* The method receives train and selection data; agent-eval owns final scoring.
-*/
-async function runSerializedKnowledgeOptimization(options) {
-	assertCompleteOptimizationMethod(options.method);
-	assertImmutableRef(options.executionRef, "knowledge optimization executionRef");
-	const codec = options.codec ?? jsonCandidateCodec();
-	const baseline = normalizeCandidate(options.baseline, codec, "baseline");
-	const dispatchRef = [
-		"knowledge-optimization",
-		options.executionRef,
-		baseline.surfaceHash,
-		surfaceHash(options.method.name)
-	].join(":");
-	assertPartitionContent(options.trainScenarios, options.selectionScenarios, options.finalScenarios, options.scenarioFingerprint ?? scenarioContentFingerprint);
-	const method = canonicalCandidateMethod(options.method, codec);
-	const { baseline: _baseline, method: _method, trainScenarios, selectionScenarios, finalScenarios, dispatchCandidate, executionRef: _executionRef, codec: _codec, scenarioFingerprint: _scenarioFingerprint, ...comparisonOptions } = options;
-	const optimizationRunOptions = {
-		...comparisonOptions.reps !== void 0 ? { reps: comparisonOptions.reps } : {},
-		...comparisonOptions.resumable !== void 0 ? { resumable: comparisonOptions.resumable } : {},
-		...comparisonOptions.labeledStore !== void 0 ? { labeledStore: comparisonOptions.labeledStore } : {},
-		...comparisonOptions.captureSource !== void 0 ? { captureSource: comparisonOptions.captureSource } : {},
-		...comparisonOptions.captureSourceVersionHash !== void 0 ? { captureSourceVersionHash: comparisonOptions.captureSourceVersionHash } : {},
-		...comparisonOptions.maxConcurrency !== void 0 ? { maxConcurrency: comparisonOptions.maxConcurrency } : {},
-		...comparisonOptions.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: comparisonOptions.dispatchTimeoutMs } : {},
-		...comparisonOptions.repo !== void 0 ? { repo: comparisonOptions.repo } : {},
-		...comparisonOptions.tracing !== void 0 ? { tracing: comparisonOptions.tracing } : {},
-		...comparisonOptions.expectUsage !== void 0 ? { expectUsage: comparisonOptions.expectUsage } : {},
-		...comparisonOptions.now !== void 0 ? { now: comparisonOptions.now } : {},
-		...comparisonOptions.buildTraceWriter !== void 0 ? { buildTraceWriter: comparisonOptions.buildTraceWriter } : {},
-		...comparisonOptions.storage !== void 0 ? { storage: comparisonOptions.storage } : {},
-		...comparisonOptions.cellPlacement !== void 0 ? { cellPlacement: comparisonOptions.cellPlacement } : {},
-		...comparisonOptions.optimizationRunOptions ?? {},
-		dispatchRef
-	};
-	const comparison = await compareOptimizationMethods({
-		...comparisonOptions,
-		dispatchRef,
-		optimizationRunOptions,
-		methods: [method],
-		baselineSurface: baseline.surface,
-		trainScenarios: trainScenarios.map((scenario) => structuredClone(scenario)),
-		selectionScenarios: selectionScenarios.map((scenario) => structuredClone(scenario)),
-		testScenarios: finalScenarios.map((scenario) => structuredClone(scenario)),
-		dispatchWithSurface: async (surface, scenario, context) => {
-			const candidate = normalizeSurface(surface, codec, "candidate");
-			return dispatchCandidate({
-				candidate: structuredClone(candidate.value),
-				candidateSurface: candidate.surface,
-				candidateSurfaceHash: candidate.surfaceHash,
-				scenario,
-				context
-			});
-		}
-	});
-	const winner = normalizeSurface(comparison.best.winnerSurface, codec, "winner");
-	return {
-		methodName: options.method.name,
-		baseline,
-		winner,
-		comparison
-	};
-}
-function assertCompleteOptimizationMethod(method) {
-	const candidate = method;
-	if (!candidate || typeof candidate.name !== "string" || candidate.name.trim().length === 0 || typeof candidate.optimize !== "function") throw new Error("knowledge optimization requires a complete OptimizationMethod with a non-empty name and optimize()");
-}
-function jsonCandidateCodec() {
-	return {
-		serialize: (candidate) => canonicalJson(candidate),
-		parse(surface) {
-			let parsed;
-			try {
-				parsed = JSON.parse(surface);
-			} catch (error) {
-				throw new Error("serialized knowledge candidate is not valid JSON", { cause: error });
-			}
-			return parsed;
-		}
-	};
-}
-function jsonObjectCandidateCodec() {
-	const codec = jsonCandidateCodec();
-	return {
-		serialize: codec.serialize,
-		parse(surface) {
-			const candidate = codec.parse(surface);
-			if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) throw new Error("serialized knowledge candidate must be a JSON object");
-			return candidate;
-		}
-	};
-}
-function scenarioContentFingerprint(scenario) {
-	const { id: _id, tags: _tags, split: _split, splitTag: _splitTag, ...content } = scenario;
-	return surfaceHash(canonicalJson(content));
-}
-function canonicalCandidateMethod(method, codec) {
-	return {
-		name: method.name,
-		async optimize(input) {
-			const result = await method.optimize(input);
-			const winner = normalizeSurface(result.winnerSurface, codec, `${method.name} winner`);
-			return {
-				...result,
-				winnerSurface: winner.surface
-			};
-		}
-	};
-}
-function normalizeCandidate(candidate, codec, label) {
-	let surface;
-	try {
-		surface = codec.serialize(candidate);
-	} catch (error) {
-		throw new Error(`${label} serializer failed`, { cause: error });
-	}
-	return normalizeSurface(surface, codec, label);
-}
-function normalizeSurface(surface, codec, label) {
-	if (typeof surface !== "string" || surface.trim().length === 0) throw new Error(`${label} must be a non-empty serialized string`);
-	let value;
-	try {
-		value = codec.parse(surface);
-	} catch (error) {
-		const detail = error instanceof Error ? `: ${error.message}` : "";
-		throw new Error(`${label} parser failed${detail}`, { cause: error });
-	}
-	let canonicalSurface;
-	try {
-		canonicalSurface = codec.serialize(value);
-	} catch (error) {
-		throw new Error(`${label} serializer failed after parsing`, { cause: error });
-	}
-	if (typeof canonicalSurface !== "string" || canonicalSurface.trim().length === 0) throw new Error(`${label} serializer must return a non-empty string`);
-	if (codec.serialize(codec.parse(canonicalSurface)) !== canonicalSurface) throw new Error(`${label} codec must round-trip to one canonical surface`);
-	return {
-		value: structuredClone(value),
-		surface: canonicalSurface,
-		surfaceHash: surfaceHash(canonicalSurface)
-	};
-}
-function assertPartitionContent(train, selection, final, fingerprint) {
-	if (!fingerprint) return;
-	const owner = /* @__PURE__ */ new Map();
-	for (const [name, scenarios] of [
-		["train", train],
-		["selection", selection],
-		["final", final]
-	]) for (const scenario of scenarios) {
-		const identity = fingerprint(scenario);
-		if (typeof identity !== "string" || identity.trim().length === 0) throw new Error(`scenarioFingerprint returned no identity for '${scenario.id}'`);
-		const prior = owner.get(identity);
-		if (prior) {
-			const scope = prior.partition === name ? `${name} partition duplicates` : `${prior.partition}/${name} partitions duplicate`;
-			throw new Error(`serialized knowledge optimization ${scope} scenario content at '${prior.scenarioId}'/'${scenario.id}'`);
-		}
-		owner.set(identity, {
-			partition: name,
-			scenarioId: scenario.id
-		});
-	}
-}
-//#endregion
 //#region src/rag-optimization.ts
 /** Optimizes retrieval and answer behavior together as one serialized RAG configuration. */
 async function runRagOptimization(options) {
@@ -1501,15 +1503,20 @@ function defineReadinessSpec(input) {
 function buildEvalKnowledgeBundle(options) {
 	const searchLimit = options.searchLimit ?? 5;
 	const now = options.now ?? /* @__PURE__ */ new Date();
+	const lexicalIndex = options.specs.some((spec) => spec.query.trim() !== "") ? buildKnowledgeLexicalIndex(options.index.pages) : void 0;
 	const searchResultsByRequirement = {};
 	const requirements = options.specs.map((spec) => {
-		const results = searchKnowledge(options.index, spec.query, searchLimit);
+		const results = searchKnowledge(options.index, spec.query, {
+			limit: searchLimit,
+			lexicalIndex
+		});
 		searchResultsByRequirement[spec.id] = results;
 		return requirementFromSearch(options.index, spec, results, now);
 	});
 	const report = scoreKnowledgeReadiness({
 		taskId: options.taskId,
 		requirements,
+		now,
 		userAnswers: options.userAnswers,
 		evidenceIds: requirements.flatMap((requirement) => requirement.evidenceIds),
 		claimIds: [],
@@ -1536,6 +1543,10 @@ function requirementFromSearch(index, spec, results, now) {
 	const hitCoverage = spec.minHits ? Math.min(1, hitCount / spec.minHits) : hitCount > 0 ? 1 : 0;
 	const freshness = sourceFreshness(sources, now);
 	const currentConfidence = round(Math.min(bestScore, sourceCoverage, hitCoverage, freshness.score));
+	const freshnessFields = {
+		...freshness.validUntil === void 0 ? {} : { validUntil: freshness.validUntil },
+		...freshness.lastVerifiedAt === void 0 ? {} : { lastVerifiedAt: freshness.lastVerifiedAt }
+	};
 	return {
 		id: spec.id,
 		description: spec.description,
@@ -1547,6 +1558,7 @@ function requirementFromSearch(index, spec, results, now) {
 		sensitivity: spec.sensitivity,
 		confidenceNeeded: spec.confidenceNeeded,
 		currentConfidence,
+		...freshnessFields,
 		evidenceIds: unique([...sourceIds.map((sourceId) => `source:${sourceId}`), ...results.map((result) => `page:${result.page.id}`)]),
 		fallbackPolicy: spec.fallbackPolicy ?? (spec.importance === "blocking" ? "block" : "continue_with_caveat"),
 		metadata: {
@@ -1557,8 +1569,7 @@ function requirementFromSearch(index, spec, results, now) {
 			bestNormalizedScore: bestScore,
 			expiredSourceIds: freshness.expiredSourceIds,
 			freshnessScore: freshness.score,
-			...freshness.validUntil === void 0 ? {} : { validUntil: freshness.validUntil },
-			...freshness.lastVerifiedAt === void 0 ? {} : { lastVerifiedAt: freshness.lastVerifiedAt }
+			...freshnessFields
 		}
 	};
 }
@@ -1610,9 +1621,24 @@ function readinessFor(options, index) {
 		...options.readiness ?? {},
 		taskId: options.readinessTaskId ?? options.goal,
 		index,
-		specs: options.readinessSpecs
+		specs: [...options.readinessSpecs]
 	});
 }
+/** Assess one index without repeating lint/schema work for its two policy gates. */
+function assessKnowledgeIndex(options, index) {
+	const prepared = prepareKnowledgeValidation(index);
+	const validation = prepared.validate({ strict: options.strict });
+	const readiness = readinessFor(options, index);
+	const qualityOptions = {
+		strict: options.strict,
+		...options.kbQuality
+	};
+	return {
+		validation,
+		readiness,
+		kbQuality: scoreValidatedKnowledgeBaseIndex(index, qualityOptions, Boolean(qualityOptions.strict) === Boolean(options.strict) ? validation : prepared.validate(qualityOptions))
+	};
+}
 //#endregion
 //#region src/research-loop.ts
 /**
@@ -1631,18 +1657,12 @@ function createKnowledgeControlLoopAdapter(options) {
 				await initKnowledgeBase(options.root);
 				initialized = true;
 			}
-			const index = await buildKnowledgeIndex(options.root, options);
-			const validation = validateKnowledgeIndex(index, { strict: options.strict });
-			const lintFindings = lintKnowledgeIndex(index);
-			const readiness = readinessFor(options, index);
+			const observation = await observeKnowledgeResearch(options);
 			return {
 				root: options.root,
 				goal: options.goal,
 				iteration: history.length + 1,
-				index,
-				lintFindings,
-				validation,
-				readiness,
+				...observation,
 				previousSteps: [...appliedSteps],
 				signal: abortSignal
 			};
@@ -1674,7 +1694,7 @@ function createKnowledgeControlLoopAdapter(options) {
 		},
 		stopPolicies: { stateFingerprint: ({ signal: _signal, ...observable }) => canonicalJson(observable) },
 		async act(action, ctx) {
-			const step = await applyKnowledgeResearchDecision(options, action, ctx.state.iteration);
+			const { step } = await applyKnowledgeResearchDecision(options, action, ctx.state.iteration);
 			appliedSteps.push(step);
 			return step;
 		}
@@ -1684,10 +1704,7 @@ async function runKnowledgeResearchLoop(options) {
 	const maxIterations = Math.max(1, options.maxIterations ?? 3);
 	await initKnowledgeBase(options.root);
 	const steps = [];
-	let index = await buildKnowledgeIndex(options.root, options);
-	let validation = validateKnowledgeIndex(index, { strict: options.strict });
-	let lintFindings = lintKnowledgeIndex(index);
-	let readiness = readinessFor(options, index);
+	let observation = await observeKnowledgeResearch(options);
 	let done = false;
 	for (let iteration = 1; iteration <= maxIterations; iteration++) {
 		if (options.signal?.aborted) throw new Error("Knowledge research loop aborted");
@@ -1695,19 +1712,14 @@ async function runKnowledgeResearchLoop(options) {
 			root: options.root,
 			goal: options.goal,
 			iteration,
-			index,
-			lintFindings,
-			validation,
-			readiness,
+			...observation,
 			previousSteps: steps,
 			signal: options.signal
 		});
 		done = Boolean(decision.done);
-		const step = await applyKnowledgeResearchDecision(options, decision, iteration);
-		index = await buildKnowledgeIndex(options.root, options);
-		validation = step.validation;
-		lintFindings = step.lintFindings;
-		readiness = step.readiness;
+		const applied = await applyKnowledgeResearchDecision(options, decision, iteration);
+		const { step } = applied;
+		observation = applied.observation;
 		steps.push(step);
 		await options.onStep?.(step);
 		if (done) break;
@@ -1718,10 +1730,7 @@ async function runKnowledgeResearchLoop(options) {
 		goal: options.goal,
 		iterations: steps.length,
 		done,
-		index,
-		lintFindings,
-		validation,
-		readiness,
+		...observation,
 		steps
 	};
 }
@@ -1730,10 +1739,8 @@ async function applyKnowledgeResearchDecision(options, decision, iteration = 1)
 	for (const sourcePath of decision.sourcePaths ?? []) addedSources.push(...await addSourcePath(options.root, sourcePath, options.sourceOptions));
 	for (const sourceText of decision.sourceTexts ?? []) addedSources.push(await addSourceText(options.root, sourceText, options.sourceOptions));
 	const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText, { pagesDirectory: options.pagesDirectory }) : void 0;
-	const index = await buildKnowledgeIndex(options.root, options);
-	const validation = validateKnowledgeIndex(index, { strict: options.strict });
-	const lintFindings = lintKnowledgeIndex(index);
-	const readiness = readinessFor(options, index);
+	const observation = await observeKnowledgeResearch(options);
+	const { validation, lintFindings, readiness } = observation;
 	const done = Boolean(decision.done);
 	const event = createKnowledgeEvent({
 		type: "research.iteration",
@@ -1750,16 +1757,29 @@ async function applyKnowledgeResearchDecision(options, decision, iteration = 1)
 		}
 	});
 	return {
-		iteration,
-		...decision.notes === void 0 ? {} : { notes: decision.notes },
-		addedSources,
-		...applied === void 0 ? {} : { applied },
-		lintFindings,
-		validation,
-		...readiness === void 0 ? {} : { readiness },
-		event,
-		done,
-		...decision.metadata === void 0 ? {} : { metadata: decision.metadata }
+		step: {
+			iteration,
+			...decision.notes === void 0 ? {} : { notes: decision.notes },
+			addedSources,
+			...applied === void 0 ? {} : { applied },
+			lintFindings,
+			validation,
+			...readiness === void 0 ? {} : { readiness },
+			event,
+			done,
+			...decision.metadata === void 0 ? {} : { metadata: decision.metadata }
+		},
+		observation
+	};
+}
+async function observeKnowledgeResearch(options) {
+	const index = await buildKnowledgeIndex(options.root, options);
+	const prepared = prepareKnowledgeValidation(index);
+	return {
+		index,
+		lintFindings: structuredClone(prepared.lintFindings),
+		validation: prepared.validate({ strict: options.strict }),
+		readiness: readinessFor(options, index)
 	};
 }
 //#endregion
@@ -2038,114 +2058,90 @@ async function runRagKnowledgeImprovementPhases(options, previous) {
 	let knowledgeUpdate = previous?.knowledgeUpdate;
 	let answerQuality = previous?.answerQuality;
 	let promotion = previous?.promotion;
-	if (phaseEnabled(options, "gap-diagnosis")) {
-		if (options.diagnose) findings = [...await runPhase(phases, now, "gap-diagnosis", async () => {
-			assertNotAborted(options.signal);
-			return options.diagnose({
-				goal: options.goal,
-				phases,
-				optimization: selectRagOptimization(optimization),
-				signal: options.signal,
-				retrieval: selectRetrievalOptimization(retrieval)
-			});
-		}, (diagnosed) => `${diagnosed.length} finding(s)`)];
-		else skipPhase(phases, now, "gap-diagnosis", "no diagnosis hook provided");
-	}
-	if (phaseEnabled(options, "knowledge-acquisition")) {
-		if (options.acquireKnowledge) acquisition = await runPhase(phases, now, "knowledge-acquisition", async () => {
-			assertNotAborted(options.signal);
-			return options.acquireKnowledge({
-				goal: options.goal,
-				phases,
-				optimization: selectRagOptimization(optimization),
-				signal: options.signal,
-				retrieval: selectRetrievalOptimization(retrieval),
-				findings
-			});
-		}, summarizeAcquisitionDecision);
-		else skipPhase(phases, now, "knowledge-acquisition", "no acquisition hook provided");
-	}
-	if (phaseEnabled(options, "knowledge-update")) {
-		if (options.updateKnowledge) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
-			assertNotAborted(options.signal);
-			return options.updateKnowledge({
-				goal: options.goal,
-				phases,
-				optimization: selectRagOptimization(optimization),
-				signal: options.signal,
-				retrieval: selectRetrievalOptimization(retrieval),
-				findings,
-				acquisition
+	const context = () => ({
+		goal: options.goal,
+		phases,
+		optimization: selectOptimization(optimization),
+		signal: options.signal,
+		retrieval: selectOptimization(retrieval)
+	});
+	async function runPhase(phase, previousValue, action, summarize, missing) {
+		if (!phaseEnabled(options, phase)) return previousValue;
+		const startedAt = now().toISOString();
+		if (!action) {
+			phases.push({
+				phase,
+				status: "skipped",
+				summary: missing,
+				startedAt,
+				finishedAt: startedAt
 			});
-		}, (result) => result.summary);
-		else if (options.knowledgeResearch) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
-			assertNotAborted(options.signal);
-			return runKnowledgeResearchUpdate(options, acquisition);
-		}, (result) => result.summary);
-		else skipPhase(phases, now, "knowledge-update", "no update hook or research loop provided");
-	}
-	if (phaseEnabled(options, "rag-optimization") && (options.optimization || options.enabledPhases?.includes("rag-optimization") || options.requiredPhases?.includes("rag-optimization"))) {
-		if (options.optimization) optimization = await runPhase(phases, now, "rag-optimization", async () => {
-			assertNotAborted(options.signal);
-			return runRagOptimization(options.optimization);
-		}, summarizeRagOptimization);
-		else skipPhase(phases, now, "rag-optimization", "no full RAG optimization options provided");
-	}
-	if (phaseEnabled(options, "retrieval-tuning")) {
-		if (options.retrieval) retrieval = await runPhase(phases, now, "retrieval-tuning", async () => {
-			assertNotAborted(options.signal);
-			return runRetrievalImprovementLoop(options.retrieval);
-		}, summarizeRetrievalResult);
-		else skipPhase(phases, now, "retrieval-tuning", "no retrieval options provided");
-	}
-	if (phaseEnabled(options, "answer-quality")) {
-		if (options.evaluateAnswers) {
-			answerQuality = await runPhase(phases, now, "answer-quality", async () => {
-				assertNotAborted(options.signal);
-				const result = await options.evaluateAnswers({
-					goal: options.goal,
-					phases,
-					optimization: selectRagOptimization(optimization),
-					signal: options.signal,
-					retrieval: selectRetrievalOptimization(retrieval),
-					findings,
-					acquisition,
-					knowledgeUpdate
-				});
-				assertRagAnswerEvidence(result);
-				return result;
-			}, summarizeAnswerQuality);
-			findings = [...findings, ...answerQuality.findings ?? []];
-		} else skipPhase(phases, now, "answer-quality", "no answer-quality hook provided");
-	}
-	if (phaseEnabled(options, "promotion")) {
-		if (options.decidePromotion) promotion = await runPhase(phases, now, "promotion", async () => {
+			return previousValue;
+		}
+		try {
 			assertNotAborted(options.signal);
-			const evidenceRejection = rejectUnsafePromotionEvidence({
-				optimization: optimization?.comparison,
-				optimizationCostCeiling: options.optimization?.costCeiling,
-				retrieval: retrieval?.comparison,
-				retrievalCostCeiling: options.retrieval?.costCeiling,
-				answerQuality,
-				answerQualityCostCeiling: options.answerQualityCostCeiling
+			const result = await action();
+			phases.push({
+				phase,
+				status: "completed",
+				summary: summarize(result),
+				startedAt,
+				finishedAt: now().toISOString()
 			});
-			if (evidenceRejection) return evidenceRejection;
-			return options.decidePromotion({
-				goal: options.goal,
-				phases,
-				optimization: selectRagOptimization(optimization),
-				optimizationComparison: optimization?.comparison,
-				signal: options.signal,
-				retrieval: selectRetrievalOptimization(retrieval),
-				retrievalComparison: retrieval?.comparison,
-				findings,
-				acquisition,
-				knowledgeUpdate,
-				answerQuality
+			return result;
+		} catch (error) {
+			phases.push({
+				phase,
+				status: "failed",
+				summary: error.message,
+				startedAt,
+				finishedAt: now().toISOString()
 			});
-		}, (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`);
-		else skipPhase(phases, now, "promotion", "no promotion decision hook provided");
+			throw error;
+		}
 	}
+	findings = [...await runPhase("gap-diagnosis", findings, options.diagnose && (() => options.diagnose(context())), (diagnosed) => `${diagnosed.length} finding(s)`, "no diagnosis hook provided")];
+	acquisition = await runPhase("knowledge-acquisition", acquisition, options.acquireKnowledge && (() => options.acquireKnowledge({
+		...context(),
+		findings
+	})), summarizeAcquisitionDecision, "no acquisition hook provided");
+	knowledgeUpdate = await runPhase("knowledge-update", knowledgeUpdate, options.updateKnowledge ? () => options.updateKnowledge({
+		...context(),
+		findings,
+		acquisition
+	}) : options.knowledgeResearch ? () => runKnowledgeResearchUpdate(options, acquisition) : void 0, (result) => result.summary, "no update hook or research loop provided");
+	if (options.optimization || options.enabledPhases?.includes("rag-optimization") || options.requiredPhases?.includes("rag-optimization")) optimization = await runPhase("rag-optimization", optimization, options.optimization && (() => runRagOptimization(options.optimization)), summarizeOptimization, "no full RAG optimization options provided");
+	retrieval = await runPhase("retrieval-tuning", retrieval, options.retrieval && (() => runRetrievalImprovementLoop(options.retrieval)), summarizeOptimization, "no retrieval options provided");
+	const runsAnswerQuality = phaseEnabled(options, "answer-quality") && Boolean(options.evaluateAnswers);
+	answerQuality = await runPhase("answer-quality", answerQuality, options.evaluateAnswers && (async () => {
+		const result = await options.evaluateAnswers({
+			...context(),
+			findings,
+			acquisition,
+			knowledgeUpdate
+		});
+		assertRagAnswerEvidence(result);
+		return result;
+	}), summarizeAnswerQuality, "no answer-quality hook provided");
+	if (runsAnswerQuality) findings = [...findings, ...answerQuality.findings ?? []];
+	promotion = await runPhase("promotion", promotion, options.decidePromotion && (() => {
+		return rejectUnsafePromotionEvidence({
+			optimization: optimization?.comparison,
+			optimizationCostCeiling: options.optimization?.costCeiling,
+			retrieval: retrieval?.comparison,
+			retrievalCostCeiling: options.retrieval?.costCeiling,
+			answerQuality,
+			answerQualityCostCeiling: options.answerQualityCostCeiling
+		}) ?? options.decidePromotion({
+			...context(),
+			optimizationComparison: optimization?.comparison,
+			retrievalComparison: retrieval?.comparison,
+			findings,
+			acquisition,
+			knowledgeUpdate,
+			answerQuality
+		});
+	}), (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`, "no promotion decision hook provided");
 	return {
 		goal: options.goal,
 		phases,
@@ -2191,7 +2187,7 @@ function exceedsCostCeiling(totalCostUsd, costCeiling) {
 	const tolerance = Number.EPSILON * Math.max(1, Math.abs(totalCostUsd), Math.abs(costCeiling)) * 8;
 	return totalCostUsd - costCeiling > tolerance;
 }
-function summarizeRagOptimization(result) {
+function summarizeOptimization(result) {
 	return `${result.methodName}; winner=${result.winner.surfaceHash}`;
 }
 async function runKnowledgeResearchUpdate(options, acquisition) {
@@ -2222,53 +2218,7 @@ function acquisitionBackedResearchStep(acquisition) {
 		done: acquisition.done ?? true
 	});
 }
-async function runPhase(phases, now, phase, action, summarize) {
-	const startedAt = now().toISOString();
-	try {
-		const result = await action();
-		phases.push({
-			phase,
-			status: "completed",
-			summary: summarize(result),
-			startedAt,
-			finishedAt: now().toISOString()
-		});
-		return result;
-	} catch (error) {
-		phases.push({
-			phase,
-			status: "failed",
-			summary: error.message,
-			startedAt,
-			finishedAt: now().toISOString()
-		});
-		throw error;
-	}
-}
-function skipPhase(phases, now, phase, summary) {
-	const timestamp = now().toISOString();
-	phases.push({
-		phase,
-		status: "skipped",
-		summary,
-		startedAt: timestamp,
-		finishedAt: timestamp
-	});
-}
-function summarizeRetrievalResult(result) {
-	return `${result.methodName}; winner=${result.winner.surfaceHash}`;
-}
-function selectRagOptimization(result) {
-	if (!result) return void 0;
-	return {
-		methodName: result.methodName,
-		baseline: structuredClone(result.baseline),
-		winner: structuredClone(result.winner),
-		baselineConfig: structuredClone(result.baselineConfig),
-		winnerConfig: structuredClone(result.winnerConfig)
-	};
-}
-function selectRetrievalOptimization(result) {
+function selectOptimization(result) {
 	if (!result) return void 0;
 	return {
 		methodName: result.methodName,
@@ -3109,12 +3059,7 @@ function selectedStageRequiredPhases(options, stagePhases) {
 async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle, options, now, useConfiguredEvaluator) {
 	return withBaselineSnapshot(runDir, state.baseHash, async (baselineRoot) => {
 		const [baselineIndex, candidateIndex] = await Promise.all([buildKnowledgeIndex(baselineRoot, options.stateScope), buildKnowledgeIndex(snapshot.root, options.stateScope)]);
-		const validation = validateKnowledgeIndex(candidateIndex, { strict: options.strict });
-		const readiness = readinessFor(options, candidateIndex);
-		const kbQuality = scoreKnowledgeBaseIndex(candidateIndex, {
-			strict: options.strict,
-			...options.kbQuality
-		});
+		const { validation, readiness, kbQuality } = assessKnowledgeIndex(options, candidateIndex);
 		const candidateHash = snapshot.hash;
 		const evaluator = useConfiguredEvaluator ? options.evaluate : options.evaluateDevelopment;
 		const evaluation = applyLifecycleFailures(normalizeMetric(await ((evaluator ? evaluator({
@@ -5409,15 +5354,7 @@ function createQmdKnowledgeTools(options) {
 //#region src/readiness-check.ts
 async function evaluateKnowledgeBaseReadiness(options) {
 	const index = await buildKnowledgeIndex(options.root);
-	const validation = validateKnowledgeIndex(index, { strict: options.strict });
-	const readiness = readinessFor({
-		...options,
-		readinessSpecs: options.readinessSpecs ? [...options.readinessSpecs] : void 0
-	}, index);
-	const kbQuality = scoreKnowledgeBaseIndex(index, {
-		strict: options.strict,
-		...options.kbQuality
-	});
+	const { validation, readiness, kbQuality } = assessKnowledgeIndex(options, index);
 	const blockingMissing = readiness?.report.blockingMissingRequirements.length ?? 0;
 	const blockingTotal = options.readinessSpecs?.filter((spec) => spec.importance === "blocking").length ?? 0;
 	const blockingReadiness = blockingTotal === 0 ? 1 : Math.max(0, blockingTotal - blockingMissing) / blockingTotal;