@tangle-network/agent-knowledge 4.1.0 → 5.0.1

package/dist/index.js

@@ -64,6 +64,7 @@ import {
   agentMemorySequenceJudge,
   applyRetrievalHoldout,
   applySessionStickyRetrievalHoldout,
+  assertImmutableRef,
   buildAgentMemorySequenceScenarios,
   buildAgentMemorySequencesFromBenchmarkCases,
   createAgentMemoryBranch,
@@ -75,14 +76,18 @@ import {
   emitRetrievalHoldoutBypass,
   forkAgentMemoryBranchSnapshot,
   graphitiMemoryAdapterIdentity,
+  jsonCandidateCodec,
+  jsonObjectCandidateCodec,
   mem0MemoryAdapterIdentity,
   renderMemoryContext,
   resetRetrievalHoldoutRegistry,
   retrievalHoldoutConfigHash,
   runAgentMemoryExperiment,
   runAgentMemoryImprovement,
+  runSerializedKnowledgeOptimization,
+  scenarioContentFingerprint,
   toOffPolicyTrajectory
-} from "./chunk-CPMLJYA3.js";
+} from "./chunk-LMR53POQ.js";
 import {
   IRS_DIMENSION_HINTS,
   MAX_RESPONSE_BYTES,
@@ -112,7 +117,6 @@ import {
   buildKnowledgeBenchmarkScenarios,
   buildRetrievalBenchmarkCasesFromQrels,
   buildRetrievalEvalDispatch,
-  buildRetrievalParameterCandidates,
   createInMemoryBenchmarkAdapter,
   createMemoryExecutionPool,
   createNoopMemoryBenchmarkAdapter,
@@ -123,24 +127,23 @@ import {
   memoryWriteResultToSourceRecord,
   parseKnowledgeBenchmarkJsonl,
   parseKnowledgeBenchmarkQrels,
+  partitionRetrievalScenarios,
   renderKnowledgeBenchmarkReportMarkdown,
   resolveMemoryCleanupTimeoutMs,
   respondToIndustryMemoryBenchmarkSmokeCase,
   respondToIndustryRagBenchmarkSmokeCase,
   retrievalConfigFromSurface,
   retrievalConfigSurface,
-  retrievalParameterSweepProposer,
   retrievalRecallJudge,
   runBoundedMemoryLifecycle,
   runKnowledgeBenchmarkSuite,
   runMemoryAdapterBenchmark,
-  runRetrievalImprovementLoop,
   scoreKnowledgeBenchmarkArtifact,
   scoreMemoryBenchmarkArtifact,
   scoreRetrievalArtifact,
   sleepForMemoryRecovery,
   summarizeKnowledgeBenchmarkCampaign
-} from "./chunk-BBCIB4UL.js";
+} from "./chunk-EYIA5PLQ.js";
 import {
   reciprocalRankFusion,
   searchKnowledge,
@@ -691,6 +694,7 @@ import {
 } from "@tangle-network/agent-interface";
 import { z } from "zod";
 var digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+var immutableRefSchema = z.string().regex(/^(?:sha256:[a-f0-9]{64}|git:[a-f0-9]{40})$/);
 var runIdSchema = z.string().min(1).max(2048);
 var safePathSegmentSchema = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
 var knowledgeImprovementMutationReceiptSchema = z.object({
@@ -770,6 +774,7 @@ var candidateRecordSchema = z.object({
   candidateHash: digestSchema.optional(),
   evidenceHash: digestSchema.optional(),
   promotionPlanHash: digestSchema.optional(),
+  finalEvaluationStartedAt: z.iso.datetime().optional(),
   status: improvementStatusSchema,
   createdAt: z.iso.datetime(),
   updatedAt: z.iso.datetime()
@@ -778,6 +783,7 @@ var KnowledgeImprovementRunStateSchema = z.object({
   runId: runIdSchema,
   root: z.string().min(1),
   goal: z.string().min(1),
+  implementationRef: immutableRefSchema,
   status: improvementStatusSchema,
   baseHash: digestSchema,
   createdAt: z.iso.datetime(),
@@ -874,6 +880,7 @@ var KnowledgeImprovementEvidenceSchema = z.object({
   candidateId: safePathSegmentSchema,
   iteration: z.number().int().positive(),
   goalHash: digestSchema,
+  implementationRef: immutableRefSchema,
   baseHash: digestSchema,
   candidateHash: digestSchema,
   promotionPlanHash: digestSchema,
@@ -899,6 +906,7 @@ var UPDATE_PHASES = [
   "knowledge-update"
 ];
 var EVALUATION_PHASES = [
+  "rag-optimization",
   "retrieval-tuning",
   "gap-diagnosis",
   "answer-quality",
@@ -1279,7 +1287,60 @@ function immutableJsonValue(value) {
 
 // src/kb-improvement/evaluation.ts
 import { join as join3 } from "path";
-import { contentHash as contentHash5 } from "@tangle-network/agent-eval";
+import { contentHash as contentHash6 } from "@tangle-network/agent-eval";
+
+// src/rag-answer-evidence.ts
+function assertRagAnswerEvidence(result) {
+  if (!result || typeof result !== "object") {
+    throw new Error("answer-quality evidence must be an object");
+  }
+  if (typeof result.passed !== "boolean") {
+    throw new Error("answer-quality evidence requires a boolean passed verdict");
+  }
+  assertImmutableRef(result.datasetRef, "answer-quality datasetRef");
+  assertImmutableRef(result.evaluatorRef, "answer-quality evaluatorRef");
+  if (!Array.isArray(result.finalScenarioIds) || result.finalScenarioIds.length < 2 || new Set(result.finalScenarioIds).size !== result.finalScenarioIds.length || result.finalScenarioIds.some((id) => typeof id !== "string" || id.trim().length === 0)) {
+    throw new Error("answer-quality evidence requires at least 2 unique final scenario IDs");
+  }
+  if (!result.metrics || typeof result.metrics !== "object" || Array.isArray(result.metrics)) {
+    throw new Error("answer-quality evidence requires non-empty finite metrics");
+  }
+  const metrics = Object.entries(result.metrics);
+  if (metrics.length === 0 || metrics.some(([key, value]) => key.trim().length === 0 || !Number.isFinite(value))) {
+    throw new Error("answer-quality evidence requires non-empty finite metrics");
+  }
+  if (!result.cost || typeof result.cost !== "object") {
+    throw new Error("answer-quality evidence requires cost accounting");
+  }
+  if (!Number.isFinite(result.cost.totalCostUsd) || result.cost.totalCostUsd < 0 || typeof result.cost.accountingComplete !== "boolean" || !Array.isArray(result.cost.incompleteReasons) || result.cost.incompleteReasons.some((reason) => typeof reason !== "string" || !reason.trim())) {
+    throw new Error("answer-quality evidence has invalid cost accounting");
+  }
+  if (result.cost.accountingComplete && result.cost.incompleteReasons.length > 0) {
+    throw new Error("complete answer-quality cost accounting cannot include incomplete reasons");
+  }
+}
+function ragAnswerEvidenceRejectionReasons(evidence, costCeiling) {
+  const reasons = [];
+  if (!evidence.passed) reasons.push("answer-quality evaluation failed");
+  if (!evidence.cost.accountingComplete) {
+    reasons.push("answer-quality final comparison has incomplete cost accounting");
+  }
+  if (costCeiling === void 0) {
+    reasons.push("answer-quality promotion requires answerQualityCostCeiling");
+  } else if (exceedsCostCeiling(evidence.cost.totalCostUsd, costCeiling)) {
+    reasons.push(
+      `answer-quality final comparison cost ${evidence.cost.totalCostUsd} exceeds ${costCeiling}`
+    );
+  }
+  return reasons;
+}
+function exceedsCostCeiling(totalCostUsd, costCeiling) {
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(totalCostUsd), Math.abs(costCeiling)) * 8;
+  return totalCostUsd - costCeiling > tolerance;
+}
+
+// src/rag-eval/calibration.ts
+import { contentHash as contentHash3 } from "@tangle-network/agent-eval";
 
 // src/claim-grounding.ts
 var citedClaimKey = "citedClaim";
@@ -1911,6 +1972,12 @@ function below(metric, threshold) {
 
 // src/rag-eval/calibration.ts
 function createRagAnswerQualityHook(options) {
+  assertImmutableRef(options.evaluatorRef, "RAG answer evaluatorRef");
+  const finalScenarioIds = options.scenarios.map((scenario) => scenario.id);
+  if (finalScenarioIds.length < 2 || new Set(finalScenarioIds).size !== finalScenarioIds.length || finalScenarioIds.some((id) => !id.trim())) {
+    throw new Error("RAG answer quality requires at least 2 unique final scenarios");
+  }
+  const datasetRef = `sha256:${contentHash3(options.scenarios)}`;
   return async () => {
     const summaries = [];
     const findings = [];
@@ -1932,9 +1999,14 @@ function createRagAnswerQualityHook(options) {
       findings.push(...summary.findings);
     }
     const metrics = aggregateRagAnswerMetrics(summaries);
+    const cost = typeof options.cost === "function" ? await options.cost() : structuredClone(options.cost);
     return {
       passed: findings.length === 0,
       metrics,
+      finalScenarioIds,
+      datasetRef,
+      evaluatorRef: options.evaluatorRef,
+      cost,
       findings,
       metadata: { scenarioCount: options.scenarios.length }
     };
@@ -2034,6 +2106,46 @@ function sourceRefs(text) {
   return refs;
 }
 
+// src/rag-optimization.ts
+async function runRagOptimization(options) {
+  const {
+    baseline,
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    run,
+    judges,
+    ...runOptions
+  } = options;
+  const result = await runSerializedKnowledgeOptimization({
+    ...runOptions,
+    baseline,
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    codec: jsonObjectCandidateCodec(),
+    judges: [...judges ?? [ragAnswerQualityJudge()]],
+    scenarioFingerprint: scenarioContentFingerprint,
+    dispatchCandidate: ({ candidate, candidateSurface, candidateSurfaceHash, scenario, context }) => run({
+      config: candidate,
+      configSurface: candidateSurface,
+      configSurfaceHash: candidateSurfaceHash,
+      scenario,
+      context
+    })
+  });
+  return {
+    ...result,
+    baselineConfig: result.baseline.value,
+    winnerConfig: result.winner.value,
+    trainScenarios: [...trainScenarios],
+    selectionScenarios: [...selectionScenarios],
+    finalScenarios: [...finalScenarios]
+  };
+}
+
 // src/research-loop.ts
 import {
   blockingKnowledgeEval,
@@ -2347,33 +2459,74 @@ async function applyKnowledgeResearchDecision(options, decision, iteration = 1)
   };
 }
 
+// src/retrieval-optimization.ts
+import { canonicalJson as canonicalJson3 } from "@tangle-network/agent-eval";
+import {
+  surfaceHash
+} from "@tangle-network/agent-eval/campaign";
+async function runRetrievalImprovementLoop(options) {
+  const dispatch = buildRetrievalEvalDispatch({
+    index: options.index,
+    defaultK: options.defaultK,
+    retrieve: options.retrieve
+  });
+  const {
+    baseline,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    method,
+    index: _index,
+    defaultK: _defaultK,
+    retrieve: _retrieve,
+    judges,
+    metricWeights,
+    ...runOptions
+  } = options;
+  const result = await runSerializedKnowledgeOptimization({
+    ...runOptions,
+    baseline,
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    codec: jsonObjectCandidateCodec(),
+    judges: [...judges ?? [retrievalRecallJudge({ weights: metricWeights })]],
+    scenarioFingerprint: retrievalScenarioFingerprint,
+    dispatchCandidate: ({ candidateSurface, scenario, context }) => dispatch(candidateSurface, scenario, context)
+  });
+  return {
+    ...result,
+    baselineConfig: result.baseline.value,
+    winnerConfig: result.winner.value,
+    trainScenarios: [...trainScenarios],
+    selectionScenarios: [...selectionScenarios],
+    finalScenarios: [...finalScenarios]
+  };
+}
+function retrievalScenarioFingerprint(scenario) {
+  return surfaceHash(
+    canonicalJson3({
+      query: scenario.query,
+      expected: scenario.expected,
+      k: scenario.k ?? null
+    })
+  );
+}
+
 // src/rag-improvement-loop.ts
 async function runRagKnowledgeImprovementLoop(options) {
   assertConfiguredRequiredPhases(options);
+  assertOptionalCostCeiling(options.answerQualityCostCeiling, "answerQualityCostCeiling");
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const phases = [];
+  let optimization;
   let retrieval;
   let findings = [];
   let acquisition;
   let knowledgeUpdate;
   let answerQuality;
   let promotion;
-  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, "gap-diagnosis")) {
     if (options.diagnose) {
       findings = [
@@ -2386,8 +2539,9 @@ async function runRagKnowledgeImprovementLoop(options) {
             return options.diagnose({
               goal: options.goal,
               phases,
+              optimization: selectRagOptimization(optimization),
               signal: options.signal,
-              retrieval
+              retrieval: selectRetrievalOptimization(retrieval)
             });
           },
           (diagnosed) => `${diagnosed.length} finding(s)`
@@ -2408,8 +2562,9 @@ async function runRagKnowledgeImprovementLoop(options) {
           return options.acquireKnowledge({
             goal: options.goal,
             phases,
+            optimization: selectRagOptimization(optimization),
             signal: options.signal,
-            retrieval,
+            retrieval: selectRetrievalOptimization(retrieval),
             findings
           });
         },
@@ -2430,8 +2585,9 @@ async function runRagKnowledgeImprovementLoop(options) {
           return options.updateKnowledge({
             goal: options.goal,
             phases,
+            optimization: selectRagOptimization(optimization),
             signal: options.signal,
-            retrieval,
+            retrieval: selectRetrievalOptimization(retrieval),
             findings,
             acquisition
           });
@@ -2453,6 +2609,38 @@ async function runRagKnowledgeImprovementLoop(options) {
       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(
@@ -2461,15 +2649,18 @@ async function runRagKnowledgeImprovementLoop(options) {
         "answer-quality",
         async () => {
           assertNotAborted(options.signal);
-          return options.evaluateAnswers({
+          const result = await options.evaluateAnswers({
             goal: options.goal,
             phases,
+            optimization: selectRagOptimization(optimization),
             signal: options.signal,
-            retrieval,
+            retrieval: selectRetrievalOptimization(retrieval),
             findings,
             acquisition,
             knowledgeUpdate
           });
+          assertRagAnswerEvidence(result);
+          return result;
         },
         summarizeAnswerQuality
       );
@@ -2479,18 +2670,30 @@ async function runRagKnowledgeImprovementLoop(options) {
     }
   }
   if (phaseEnabled(options, "promotion")) {
-    if (options.promote) {
+    if (options.decidePromotion) {
       promotion = await runPhase(
         phases,
         now,
         "promotion",
         async () => {
           assertNotAborted(options.signal);
-          return options.promote({
+          const evidenceRejection = rejectUnsafePromotionEvidence({
+            optimization: optimization?.comparison,
+            optimizationCostCeiling: options.optimization?.costCeiling,
+            retrieval: retrieval?.comparison,
+            retrievalCostCeiling: options.retrieval?.costCeiling,
+            answerQuality,
+            answerQualityCostCeiling: options.answerQualityCostCeiling
+          });
+          if (evidenceRejection) return evidenceRejection;
+          return options.decidePromotion({
             goal: options.goal,
             phases,
+            optimization: selectRagOptimization(optimization),
+            optimizationComparison: optimization?.comparison,
             signal: options.signal,
-            retrieval,
+            retrieval: selectRetrievalOptimization(retrieval),
+            retrievalComparison: retrieval?.comparison,
             findings,
             acquisition,
             knowledgeUpdate,
@@ -2500,12 +2703,13 @@ async function runRagKnowledgeImprovementLoop(options) {
         (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`
       );
     } else {
-      skipPhase(phases, now, "promotion", "no promotion hook provided");
+      skipPhase(phases, now, "promotion", "no promotion decision hook provided");
     }
   }
   return {
     goal: options.goal,
     phases,
+    optimization,
     retrieval,
     findings,
     acquisition,
@@ -2514,6 +2718,58 @@ async function runRagKnowledgeImprovementLoop(options) {
     promotion
   };
 }
+function rejectUnsafePromotionEvidence(evidence) {
+  const reasons = [];
+  if (!evidence.optimization && !evidence.retrieval && !evidence.answerQuality) {
+    reasons.push("promotion requires final RAG, retrieval, or answer-quality evidence");
+  }
+  for (const [label, comparison, costCeiling] of [
+    ["RAG", evidence.optimization, evidence.optimizationCostCeiling],
+    ["retrieval", evidence.retrieval, evidence.retrievalCostCeiling]
+  ]) {
+    if (!comparison) continue;
+    if (!comparison.totalCost.accountingComplete) {
+      reasons.push(`${label} final comparison has incomplete cost accounting`);
+    }
+    const optimizerSource = comparison.best.provenance?.source;
+    if (optimizerSource && optimizerSource.evidence !== "observed") {
+      reasons.push(`${label} optimizer package identity was not observed`);
+    }
+    if (comparison.best.liftCi.low < 0) {
+      reasons.push(`${label} final comparison does not rule out a regression`);
+    }
+    if (costCeiling !== void 0 && exceedsCostCeiling2(comparison.totalCost.totalCostUsd, costCeiling)) {
+      reasons.push(
+        `${label} final comparison cost ${comparison.totalCost.totalCostUsd} exceeds ${costCeiling}`
+      );
+    }
+  }
+  if (evidence.answerQuality) {
+    reasons.push(
+      ...ragAnswerEvidenceRejectionReasons(
+        evidence.answerQuality,
+        evidence.answerQualityCostCeiling
+      )
+    );
+  }
+  if (reasons.length === 0) return void 0;
+  return {
+    promoted: false,
+    reason: reasons.join("; ")
+  };
+}
+function assertOptionalCostCeiling(value, label) {
+  if (value !== void 0 && (!Number.isFinite(value) || value < 0)) {
+    throw new Error(`${label} must be a non-negative finite number`);
+  }
+}
+function exceedsCostCeiling2(totalCostUsd, costCeiling) {
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(totalCostUsd), Math.abs(costCeiling)) * 8;
+  return totalCostUsd - costCeiling > tolerance;
+}
+function summarizeRagOptimization(result) {
+  return `${result.methodName}; winner=${result.winner.surfaceHash}`;
+}
 async function runKnowledgeResearchUpdate(options, acquisition) {
   const research = options.knowledgeResearch;
   if (!research) {
@@ -2573,7 +2829,27 @@ function skipPhase(phases, now, phase, summary) {
   phases.push({ phase, status: "skipped", summary, startedAt: timestamp, finishedAt: timestamp });
 }
 function summarizeRetrievalResult(result) {
-  return `${result.candidates.length} candidate(s); winner=${JSON.stringify(result.winnerConfig)}`;
+  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) {
+  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 summarizeAcquisitionDecision(decision) {
   const sourcePathCount = decision.sourcePaths?.length ?? 0;
@@ -2603,6 +2879,8 @@ function assertConfiguredRequiredPhases(options) {
 }
 function phaseConfigured(options, phase) {
   switch (phase) {
+    case "rag-optimization":
+      return Boolean(options.optimization);
     case "retrieval-tuning":
       return Boolean(options.retrieval);
     case "gap-diagnosis":
@@ -2614,11 +2892,13 @@ function phaseConfigured(options, phase) {
     case "answer-quality":
       return Boolean(options.evaluateAnswers);
     case "promotion":
-      return Boolean(options.promote);
+      return Boolean(options.decidePromotion);
   }
 }
 function requiredPhaseMessage(phase) {
   switch (phase) {
+    case "rag-optimization":
+      return "required phase rag-optimization requires optimization options";
     case "retrieval-tuning":
       return "required phase retrieval-tuning requires retrieval options";
     case "gap-diagnosis":
@@ -2630,7 +2910,7 @@ function requiredPhaseMessage(phase) {
     case "answer-quality":
       return "required phase answer-quality requires an evaluateAnswers hook";
     case "promotion":
-      return "required phase promotion requires a promote hook";
+      return "required phase promotion requires a decidePromotion hook";
   }
 }
 function assertNotAborted(signal) {
@@ -2641,14 +2921,14 @@ function assertNotAborted(signal) {
 
 // src/kb-improvement/transition.ts
 import { createHash as createHash2 } from "crypto";
-import { canonicalJson as canonicalJson4, contentHash as contentHash4 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson5, contentHash as contentHash5 } from "@tangle-network/agent-eval";
 
 // src/kb-improvement/workspace.ts
 import { createHash } from "crypto";
 import { cp, lstat, mkdir, mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname, join as join2, relative as relative2, resolve as resolve2 } from "path";
-import { canonicalJson as canonicalJson3, contentHash as contentHash3 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson4, contentHash as contentHash4 } from "@tangle-network/agent-eval";
 function knowledgeImprovementCandidateRef(result) {
   if (!result.candidate) throw new Error("knowledge improvement result has no candidate");
   return candidateRefFor(result.runId, result.state, result.candidate);
@@ -2753,10 +3033,10 @@ async function withMeasuredCandidateSnapshot(liveRoot, runDir, state, candidateR
     throw new Error(`knowledge candidate '${candidateRef.candidateId}' does not exist`);
   }
   const expectedRef = candidateRefFor(candidateRef.runId, state, candidate);
-  if (canonicalJson3(expectedRef) !== canonicalJson3(candidateRef)) {
+  if (canonicalJson4(expectedRef) !== canonicalJson4(candidateRef)) {
     throw new Error("knowledge candidate approval does not match the measured candidate");
   }
-  const evidence = await assertCandidateEvidence(runDir, candidateRef);
+  const evidence = await assertCandidateEvidence(runDir, candidateRef, state.implementationRef);
   const relativePath = join2(
     "candidates",
     candidate.candidateId,
@@ -2791,7 +3071,7 @@ async function withIsolatedKnowledgeCopy(sourceRoot, expectedHash, target, use)
     await rm(isolationRoot, { recursive: true, force: true });
   }
 }
-async function assertCandidateEvidence(runDir, candidate) {
+async function assertCandidateEvidence(runDir, candidate, expectedImplementationRef) {
   const evidence = KnowledgeImprovementEvidenceSchema.parse(
     JSON.parse(
       (await readRegularFileWithinRoot(
@@ -2800,13 +3080,13 @@ async function assertCandidateEvidence(runDir, candidate) {
       )).bytes.toString("utf8")
     )
   );
-  const actualHash = contentHash3(evidence);
+  const actualHash = contentHash4(evidence);
   if (actualHash !== candidate.evidenceHash) {
     throw new Error(
       `knowledge candidate evidence changed after approval: expected ${candidate.evidenceHash}, got ${actualHash}`
     );
   }
-  if (evidence.runId !== candidate.runId || evidence.candidateId !== candidate.candidateId || evidence.goalHash !== candidate.goalHash || evidence.baseHash !== candidate.baseHash || evidence.candidateHash !== candidate.candidateHash || evidence.promotionPlanHash !== candidate.promotionPlanHash || evidence.evaluation.passed !== true) {
+  if (evidence.runId !== candidate.runId || evidence.candidateId !== candidate.candidateId || evidence.goalHash !== candidate.goalHash || evidence.implementationRef !== expectedImplementationRef || evidence.baseHash !== candidate.baseHash || evidence.candidateHash !== candidate.candidateHash || evidence.promotionPlanHash !== candidate.promotionPlanHash || evidence.evaluation.passed !== true) {
     throw new Error("knowledge candidate evidence does not match the approved candidate");
   }
   return evidence;
@@ -3048,12 +3328,12 @@ async function applyKnowledgeCandidateTarget(input, target) {
   const { candidateRef, runDir, state } = input;
   assertStateIdentity(input.root, candidateRef, state);
   const candidate = state.candidates.find((entry) => entry.candidateId === candidateRef.candidateId);
-  if (!candidate || canonicalJson4(candidateIdentityFor(candidateRef.runId, state, candidate)) !== canonicalJson4(candidateRef)) {
+  if (!candidate || canonicalJson5(candidateIdentityFor(candidateRef.runId, state, candidate)) !== canonicalJson5(candidateRef)) {
     throw new Error("knowledge candidate approval does not match the measured candidate");
   }
   const action = target === "candidate" ? "promotion" : "restore";
   const desiredHash = target === "candidate" ? candidateRef.candidateHash : candidateRef.baseHash;
-  const purpose = knowledgeCandidateTransitionPurpose(candidateRef, target);
+  const purpose = knowledgeCandidateTransitionPurpose(candidateRef, state.implementationRef, target);
   const recoveryOwner = input.activation ? `knowledge-improvement-activation:${input.activation.activation.digest}` : "knowledge-improvement-candidate-transition";
   return withKnowledgeMutation(
     input.root,
@@ -3065,6 +3345,9 @@ async function applyKnowledgeCandidateTarget(input, target) {
       assertOwned();
       const transactionRoot = mutationLock.transactionRoot;
       const recovery = mutationLock.recovery?.purpose === purpose ? mutationLock.recovery : void 0;
+      if (!recovery) {
+        await assertCandidateEvidence(runDir, candidateRef, state.implementationRef);
+      }
       const existingActivation = input.activation ? await loadKnowledgeActivationRecord(
         runDir,
         candidateRef,
@@ -3366,9 +3649,9 @@ function candidateTransitionResult(input, candidate, promoted, blocked, mutation
     blocked
   };
 }
-function knowledgeCandidateTransitionPurpose(candidate, target) {
+function knowledgeCandidateTransitionPurpose(candidate, implementationRef, target) {
   const action = target === "candidate" ? "promotion" : "restore";
-  return `knowledge-${action}:${contentHash4(candidate)}`;
+  return `knowledge-${action}:${contentHash5({ candidate, implementationRef })}`;
 }
 async function knowledgeFilePlanEntries(sourceRoot, targetRoot) {
   const [before, after] = await Promise.all([
@@ -3453,6 +3736,24 @@ async function hasCandidateTransitionEvent(runDir, candidateRef, target) {
 
 // src/kb-improvement/evaluation.ts
 function assertKnowledgeImprovementOptions(options) {
+  assertImmutableRef(options.implementationRef, "knowledge improvement implementationRef");
+  if (options.answerQualityCostCeiling !== void 0 && (!Number.isFinite(options.answerQualityCostCeiling) || options.answerQualityCostCeiling < 0)) {
+    throw new Error(
+      "knowledge improvement answerQualityCostCeiling must be a non-negative finite number"
+    );
+  }
+  if (options.ragOptimization) {
+    assertImmutableRef(
+      options.ragOptimization.executionRef,
+      "knowledge improvement RAG executionRef"
+    );
+  }
+  if (options.retrieval) {
+    assertImmutableRef(
+      options.retrieval.executionRef,
+      "knowledge improvement retrieval executionRef"
+    );
+  }
   if (options.step && options.knowledgeResearch?.step) {
     throw new Error("improveKnowledgeBase accepts either step or knowledgeResearch.step, not both");
   }
@@ -3472,9 +3773,15 @@ async function measureCandidate(runId, runDir, state, candidate, options, now) {
     if (candidate.status === "candidate-ready" && candidate.candidateHash === currentCandidateHash && candidate.evidenceHash !== void 0 && candidate.promotionPlanHash !== void 0) {
       const evidence = await assertCandidateEvidence(
         runDir,
-        candidateRefFor(runId, state, candidate)
+        candidateRefFor(runId, state, candidate),
+        state.implementationRef
       );
-      return { candidate, evaluation: evidence.evaluation };
+      return {
+        candidate,
+        evaluation: evidence.evaluation,
+        ...evidence.lifecycle === null ? {} : { lifecycle: evidence.lifecycle },
+        finalEvaluated: shouldRunEvaluationStage(options)
+      };
     }
     clearCandidateMeasurement(candidate);
     const lifecycles = [];
@@ -3489,15 +3796,44 @@ async function measureCandidate(runId, runDir, state, candidate, options, now) {
       if (updateLifecycle) lifecycles.push(updateLifecycle);
     }
     return withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, async (snapshot) => {
+      let lifecycle = mergeLifecycleResults(options.goal, lifecycles);
+      const development = await evaluateCandidate(
+        runDir,
+        state,
+        candidate,
+        snapshot,
+        lifecycle,
+        options,
+        now,
+        false
+      );
+      if (!development.evaluation.passed || !shouldRunEvaluationStage(options)) {
+        return {
+          ...development,
+          ...lifecycle ? { lifecycle } : {},
+          finalEvaluated: false
+        };
+      }
+      candidate.finalEvaluationStartedAt = now().toISOString();
+      candidate.updatedAt = candidate.finalEvaluationStartedAt;
+      state.updatedAt = candidate.finalEvaluationStartedAt;
+      await saveState(runDir, state, options.onState);
+      await appendLedger(runDir, {
+        type: "candidate.final-evaluation-started",
+        runId: state.runId,
+        candidateId: candidate.candidateId
+      });
       const evaluationLifecycle = await runCandidateEvaluationLifecycle(
+        runId,
         runDir,
         candidate,
         snapshot.root,
+        snapshot.hash,
         options,
         now
       );
       if (evaluationLifecycle) lifecycles.push(evaluationLifecycle);
-      const lifecycle = mergeLifecycleResults(options.goal, lifecycles);
+      lifecycle = mergeLifecycleResults(options.goal, lifecycles);
       const measured = await evaluateCandidate(
         runDir,
         state,
@@ -3505,9 +3841,14 @@ async function measureCandidate(runId, runDir, state, candidate, options, now) {
         snapshot,
         lifecycle,
         options,
-        now
+        now,
+        true
       );
-      return { ...measured, ...lifecycle ? { lifecycle } : {} };
+      return {
+        ...measured,
+        ...lifecycle ? { lifecycle } : {},
+        finalEvaluated: true
+      };
     });
   });
 }
@@ -3525,25 +3866,53 @@ async function runCandidateUpdateLifecycle(runId, candidate, candidateRoot, opti
   });
   return lifecycle;
 }
-async function runCandidateEvaluationLifecycle(runDir, candidate, candidateRoot, options, now) {
+async function runCandidateEvaluationLifecycle(runId, runDir, candidate, candidateRoot, candidateHash, options, now) {
   if (!shouldRunEvaluationStage(options)) return void 0;
   const candidateIndex = await buildKnowledgeIndex(candidateRoot);
-  const lifecycle = await runRagKnowledgeImprovementLoop({
-    goal: options.goal,
-    retrieval: options.retrieval ? {
-      ...options.retrieval,
-      index: candidateIndex,
-      runDir: options.retrieval.runDir ?? join3(runDir, "retrieval", candidate.candidateId)
-    } : void 0,
-    diagnose: options.diagnose,
-    evaluateAnswers: options.evaluateAnswers,
-    promote: options.decidePromotion,
-    enabledPhases: selectedStagePhases(options, EVALUATION_PHASES),
-    requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
-    signal: options.signal,
-    now
-  });
-  return lifecycle;
+  return withBaselineSnapshot(
+    runDir,
+    candidate.baseHash,
+    (baselineRoot) => runRagKnowledgeImprovementLoop({
+      goal: options.goal,
+      optimization: options.ragOptimization ? {
+        ...options.ragOptimization,
+        executionRef: candidateExecutionRef(
+          options.ragOptimization.executionRef,
+          candidateHash
+        ),
+        runDir: options.ragOptimization.runDir ?? join3(runDir, "rag-optimization", candidate.candidateId),
+        run: (input) => options.ragOptimization.run({
+          ...input,
+          runId,
+          iteration: candidate.iteration,
+          candidateId: candidate.candidateId,
+          root: candidateRoot,
+          baselineRoot,
+          candidateRoot,
+          candidateIndex,
+          baseHash: candidate.baseHash
+        })
+      } : void 0,
+      retrieval: options.retrieval ? {
+        ...options.retrieval,
+        executionRef: candidateExecutionRef(options.retrieval.executionRef, candidateHash),
+        index: candidateIndex,
+        runDir: options.retrieval.runDir ?? join3(runDir, "retrieval", candidate.candidateId)
+      } : void 0,
+      diagnose: options.diagnose,
+      evaluateAnswers: options.evaluateAnswers,
+      answerQualityCostCeiling: options.answerQualityCostCeiling,
+      decidePromotion: options.decidePromotion,
+      enabledPhases: selectedStagePhases(options, EVALUATION_PHASES),
+      requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
+      signal: options.signal,
+      now
+    })
+  );
+}
+function candidateExecutionRef(executionRef, candidateHash) {
+  return `sha256:${sha256(`${executionRef}
+${candidateHash}`)}`;
 }
 function candidateKnowledgeResearchOptions(candidateRoot, options) {
   if (!options.step && !options.knowledgeResearch) return void 0;
@@ -3584,7 +3953,7 @@ function shouldRunEvaluationStage(options) {
   const phases = selectedStagePhases(options, EVALUATION_PHASES);
   if (phases.length === 0) return false;
   return Boolean(
-    options.retrieval || options.diagnose || options.evaluateAnswers || options.decidePromotion || selectedStageRequiredPhases(options, EVALUATION_PHASES).length > 0
+    options.ragOptimization || options.retrieval || options.diagnose || options.evaluateAnswers || options.decidePromotion || options.evaluate || selectedStageRequiredPhases(options, EVALUATION_PHASES).length > 0
   );
 }
 function selectedStagePhases(options, stagePhases) {
@@ -3599,6 +3968,7 @@ function mergeLifecycleResults(goal, lifecycles) {
   return {
     goal,
     phases: lifecycles.flatMap((lifecycle) => lifecycle.phases),
+    optimization: lastDefined(lifecycles.map((lifecycle) => lifecycle.optimization)),
     retrieval: lastDefined(lifecycles.map((lifecycle) => lifecycle.retrieval)),
     findings: lifecycles.flatMap((lifecycle) => lifecycle.findings),
     acquisition: lastDefined(lifecycles.map((lifecycle) => lifecycle.acquisition)),
@@ -3613,7 +3983,7 @@ function lastDefined(values) {
   }
   return void 0;
 }
-async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle, options, now) {
+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),
@@ -3626,7 +3996,8 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
       ...options.kbQuality
     });
     const candidateHash = snapshot.hash;
-    const metric = options.evaluate?.({
+    const evaluator = useConfiguredEvaluator ? options.evaluate : options.evaluateDevelopment;
+    const configuredMetric = evaluator ? evaluator({
       runId: state.runId,
       iteration: candidate.iteration,
       root: options.root,
@@ -3641,14 +4012,19 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
       kbQuality,
       lifecycle,
       signal: options.signal
-    }) ?? defaultKnowledgeImprovementMetric(
+    }) : void 0;
+    const metric = configuredMetric ?? defaultKnowledgeImprovementMetric(
       validation,
       readiness,
       options.readinessSpecs,
       kbQuality,
       lifecycle
     );
-    const evaluation = applyLifecycleFailures(normalizeMetric(await metric), lifecycle);
+    const evaluation = applyLifecycleFailures(
+      normalizeMetric(await metric),
+      lifecycle,
+      options.answerQualityCostCeiling
+    );
     const measuredHash = await hashKnowledgeBase(snapshot.root);
     if (measuredHash !== candidateHash) {
       throw new Error(
@@ -3667,6 +4043,7 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
           candidateId: candidate.candidateId,
           iteration: candidate.iteration,
           goalHash: sha256(state.goal),
+          implementationRef: state.implementationRef,
           baseHash: candidate.baseHash,
           candidateHash,
           promotionPlanHash: candidate.promotionPlanHash,
@@ -3678,7 +4055,7 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
         })
       )
     );
-    candidate.evidenceHash = contentHash5(evidence);
+    candidate.evidenceHash = contentHash6(evidence);
     candidate.updatedAt = now().toISOString();
     await writeJsonDurableWithinRoot(
       runDir,
@@ -3725,13 +4102,14 @@ function defaultKnowledgeImprovementMetric(validation, readiness, readinessSpecs
     }
   };
 }
-function applyLifecycleFailures(metric, lifecycle) {
+function applyLifecycleFailures(metric, lifecycle, answerQualityCostCeiling) {
+  const answerQualityFailures = lifecycle?.answerQuality ? ragAnswerEvidenceRejectionReasons(lifecycle.answerQuality, answerQualityCostCeiling) : [];
   const reasons = [
     metric.notes,
-    lifecycle?.answerQuality && !lifecycle.answerQuality.passed ? "answer quality failed" : void 0,
+    ...answerQualityFailures,
     lifecycle?.promotion && !lifecycle.promotion.promoted ? `promotion decision held: ${lifecycle.promotion.reason}` : void 0
   ].filter((reason) => Boolean(reason));
-  const forcedFailure = Boolean(lifecycle?.answerQuality && !lifecycle.answerQuality.passed) || Boolean(lifecycle?.promotion && !lifecycle.promotion.promoted);
+  const forcedFailure = answerQualityFailures.length > 0 || Boolean(lifecycle?.promotion && !lifecycle.promotion.promoted);
   return {
     ...metric,
     passed: metric.passed && !forcedFailure,
@@ -3780,6 +4158,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
         runId,
         root: options.root,
         goal: options.goal,
+        implementationRef: options.implementationRef,
         status: "running",
         baseHash,
         createdAt: now().toISOString(),
@@ -3793,6 +4172,9 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
     if (state.goal !== options.goal) {
       throw new Error("knowledge improvement state does not match the requested goal");
     }
+    if (state.implementationRef !== options.implementationRef) {
+      throw new Error("knowledge improvement state does not match the requested implementationRef");
+    }
     const promotedCandidateId = state.promotedCandidateId;
     const promotedCandidate = state.status === "promoted" ? state.candidates.find((candidate2) => candidate2.candidateId === promotedCandidateId) : void 0;
     if (state.status === "promoted" && !promotedCandidate) {
@@ -3810,7 +4192,8 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
         }
         const evidence2 = await assertCandidateEvidence(
           runDir,
-          candidateRefFor(runId, promotedState, promoted)
+          candidateRefFor(runId, promotedState, promoted),
+          promotedState.implementationRef
         );
         return {
           runId,
@@ -3833,6 +4216,22 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
     let lastRejectedEvaluation;
     let lifecycle;
     while (candidate || state.candidates.length < maxCandidates) {
+      if (candidate?.status === "running" && candidate.finalEvaluationStartedAt) {
+        state = await blockRun(
+          runDir,
+          state,
+          `candidate '${candidate.candidateId}' was interrupted after final evaluation started; refusing to reuse final cases`,
+          options.onState,
+          now
+        );
+        return {
+          runId,
+          state,
+          candidate,
+          promoted: false,
+          blocked: true
+        };
+      }
       if (!candidate) {
         const currentHash = await hashKnowledgeBase(options.root);
         if (currentHash !== state.baseHash) {
@@ -3891,6 +4290,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
       lastRejectedCandidate = candidate;
       lastRejectedEvaluation = evaluation;
       candidate = void 0;
+      if (measured.finalEvaluated) break;
     }
     if (!candidate) {
       state.status = "rejected";
@@ -3906,7 +4306,11 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
         blocked: false
       };
     }
-    const evidence = await assertCandidateEvidence(runDir, candidateRefFor(runId, state, candidate));
+    const evidence = await assertCandidateEvidence(
+      runDir,
+      candidateRefFor(runId, state, candidate),
+      state.implementationRef
+    );
     return {
       runId,
       state,
@@ -3921,6 +4325,93 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
   }
 }
 
+// src/kb-improvement/optimization.ts
+async function optimizeKnowledgeBasePolicy(options) {
+  const {
+    root,
+    goal,
+    baselinePolicy,
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    policyApplicationRef,
+    candidateRunLabel,
+    candidate,
+    applyPolicy,
+    ...optimizationOptions
+  } = options;
+  if (typeof root !== "string" || !root.trim()) {
+    throw new Error("optimizeKnowledgeBasePolicy root must be non-empty");
+  }
+  if (typeof goal !== "string" || !goal.trim()) {
+    throw new Error("optimizeKnowledgeBasePolicy goal must be non-empty");
+  }
+  assertImmutableRef(policyApplicationRef, "optimizeKnowledgeBasePolicy policyApplicationRef");
+  if (candidateRunLabel !== void 0 && (typeof candidateRunLabel !== "string" || !candidateRunLabel.trim())) {
+    throw new Error("optimizeKnowledgeBasePolicy candidateRunLabel must be non-empty");
+  }
+  const baseHash = await hashKnowledgeBase(root);
+  const optimization = await runSerializedKnowledgeOptimization({
+    ...optimizationOptions,
+    executionRef: policyApplicationRef,
+    baseline: baselinePolicy,
+    method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios
+  });
+  const winner = optimization.winner;
+  const currentBaseHash = await hashKnowledgeBase(root);
+  if (currentBaseHash !== baseHash) {
+    throw new Error(
+      `knowledge base changed during policy optimization: expected ${baseHash}, got ${currentBaseHash}`
+    );
+  }
+  const runId = stableId(
+    "kbpolicy",
+    `${candidateRunLabel ?? "default"}:${goal}:${optimization.methodName}:${winner.surfaceHash}:${policyApplicationRef}:${baseHash}`
+  );
+  const improvement = await improveKnowledgeBase({
+    ...candidate ?? {},
+    root,
+    goal,
+    implementationRef: `sha256:${sha256(
+      `${policyApplicationRef}
+${winner.surfaceHash}
+${optimization.methodName}`
+    )}`,
+    runId,
+    maxCandidates: 1,
+    updateKnowledge: async (input) => {
+      if (input.baseHash !== baseHash) {
+        throw new Error(
+          `knowledge base changed before policy materialization: expected ${baseHash}, got ${input.baseHash}`
+        );
+      }
+      const result = await applyPolicy({
+        ...input,
+        policy: structuredClone(winner.value),
+        policySurface: winner.surface,
+        policySurfaceHash: winner.surfaceHash,
+        optimizationMethod: optimization.methodName
+      });
+      return {
+        ...result,
+        metadata: {
+          ...result.metadata ?? {},
+          optimization: {
+            method: optimization.methodName,
+            policySurfaceHash: winner.surfaceHash,
+            policyApplicationRef
+          }
+        }
+      };
+    }
+  });
+  return { optimization, improvement };
+}
+
 // src/agent-candidate.ts
 function toAgentCandidateKnowledgeRef(candidate) {
   const parsed = KnowledgeImprovementCandidateRefSchema.parse(candidate);
@@ -4302,6 +4793,60 @@ function positiveInteger(value, name) {
   return value;
 }
 
+// src/filesystem-search-provider.ts
+var FileSystemSearchProvider = class {
+  root;
+  index;
+  defaultLimit;
+  refreshMode;
+  constructor(options) {
+    this.root = options.root;
+    this.index = options.index;
+    this.defaultLimit = options.defaultLimit ?? 10;
+    this.refreshMode = options.refresh ?? "manual";
+  }
+  async getIndex(options = {}) {
+    if (this.refreshMode === "always" || options.refresh || !this.index) {
+      this.index = await buildKnowledgeIndex(this.root);
+    }
+    return this.index;
+  }
+  async search(query, options = {}) {
+    const index = await this.getIndex(options);
+    return searchKnowledge(index, query, options.limit ?? this.defaultLimit);
+  }
+  async retrieve(query, options = {}) {
+    const hits = await this.search(query, options);
+    return hits.map(hitFromSearchResult);
+  }
+  asRetrievalEvalRetriever() {
+    return async ({ config, scenario, k }) => ({
+      hits: await this.retrieve(scenario.query, {
+        limit: k,
+        refresh: config.refresh === true
+      })
+    });
+  }
+  invalidate() {
+    this.index = void 0;
+  }
+};
+function createFileSystemSearchProvider(options) {
+  return new FileSystemSearchProvider(options);
+}
+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
+  };
+}
+
 // src/freshness.ts
 import { readFile } from "fs/promises";
 import { join as join4 } from "path";
@@ -6275,6 +6820,7 @@ export {
   AgentMemoryWriteInputSchema,
   DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS,
   FileSystemKbStore,
+  FileSystemSearchProvider,
   INDUSTRY_MEMORY_BENCHMARKS,
   INDUSTRY_RAG_BENCHMARKS,
   IRS_DIMENSION_HINTS,
@@ -6318,7 +6864,6 @@ export {
   buildKnowledgeIndex,
   buildRetrievalBenchmarkCasesFromQrels,
   buildRetrievalEvalDispatch,
-  buildRetrievalParameterCandidates,
   calibrateRagAnswerJudge,
   canonicalizeUrl,
   chunkMarkdown,
@@ -6333,6 +6878,7 @@ export {
   createCornellLiiSource,
   createD1FreshnessStoreStub,
   createFileSystemFreshnessStore,
+  createFileSystemSearchProvider,
   createGraphitiMemoryAdapter,
   createInMemoryBenchmarkAdapter,
   createIrsPublicationsSource,
@@ -6378,6 +6924,8 @@ export {
   isKnowledgeMemoryBenchmarkCase,
   isSafeKnowledgePath,
   isScaffoldPath,
+  jsonCandidateCodec,
+  jsonObjectCandidateCodec,
   kbIndexToText,
   knowledgeBenchmarkJudge,
   knowledgeImprovementCandidateRef,
@@ -6402,10 +6950,12 @@ export {
   memoryWriteResultToSourceRecord,
   normalizeExternalRagScores,
   normalizeLinkTarget,
+  optimizeKnowledgeBasePolicy,
   parseFrontmatter,
   parseKnowledgeBenchmarkJsonl,
   parseKnowledgeBenchmarkQrels,
   parseKnowledgeWriteBlocks,
+  partitionRetrievalScenarios,
   politeFetch,
   promoteKnowledgeCandidate,
   proposeFromFinding,
@@ -6423,7 +6973,6 @@ export {
   retrievalConfigFromSurface,
   retrievalConfigSurface,
   retrievalHoldoutConfigHash,
-  retrievalParameterSweepProposer,
   retrievalRecallJudge,
   runAgentMemoryExperiment,
   runAgentMemoryImprovement,
@@ -6434,9 +6983,12 @@ export {
   runKnowledgeResearchLoop,
   runMemoryAdapterBenchmark,
   runRagKnowledgeImprovementLoop,
+  runRagOptimization,
   runRetrievalImprovementLoop,
+  runSerializedKnowledgeOptimization,
   runTwoAgentResearchLoop,
   runVerifiedResearchLoop,
+  scenarioContentFingerprint,
   scoreKnowledgeBaseIndex,
   scoreKnowledgeBenchmarkArtifact,
   scoreMemoryBenchmarkArtifact,