@tangle-network/agent-knowledge 4.0.1 → 5.0.0

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as SourceRegistry, f as KnowledgeEvent, g as KnowledgeLintFinding, h as KnowledgeEventType, i as KnowledgePage, b as KnowledgeGraph, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as KnowledgeWriteParseResult } from './types-6x0OpfW6.js';
 export { C as ClaimRef, n as KnowledgeBaseCandidate, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-6x0OpfW6.js';
-import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult, RunRecord, AnalystSeverity, AnalystFinding, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard } from '@tangle-network/agent-eval';
-import { AgentImprovementActivation, AgentImprovementActivationResult, AgentCandidateKnowledgeRef } from '@tangle-network/agent-interface';
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult, RunRecord, AnalystSeverity, AnalystFinding, ReleaseTraceEvidence, GateDecision, DatasetScenario, ReleaseConfidenceScorecard } from '@tangle-network/agent-eval';
+import { AgentCandidateJsonValue, AgentImprovementActivation, AgentImprovementActivationResult, AgentCandidateKnowledgeRef } from '@tangle-network/agent-interface';
 import { z } from 'zod';
-import { JsonValue, Scenario, JudgeConfig } from '@tangle-network/agent-eval/campaign';
-import { R as RunRetrievalImprovementLoopResult, a as RunRetrievalImprovementLoopOptions } from './types-ZzY_x0r7.js';
-export { A as AgentMemoryAcquireRunLease, b as AgentMemoryAdapter, c as AgentMemoryBranchIsolation, d as AgentMemoryContext, e as AgentMemoryControllerMode, f as AgentMemoryHit, g as AgentMemoryKind, h as AgentMemoryRunLease, i as AgentMemoryScope, j as AgentMemorySearchOptions, k as AgentMemoryWriteInput, l as AgentMemoryWriteResult, B as BuildRetrievalBenchmarkCasesFromQrelsOptions, m as BuildRetrievalEvalDispatchOptions, n as BuildRetrievalParameterCandidatesOptions, K as KnowledgeAnswerBenchmarkCase, o as KnowledgeAnswerBenchmarkTaskKind, p as KnowledgeBenchmarkArtifact, q as KnowledgeBenchmarkCase, r as KnowledgeBenchmarkCaseBase, s as KnowledgeBenchmarkDistribution, t as KnowledgeBenchmarkEvaluation, u as KnowledgeBenchmarkFamily, v as KnowledgeBenchmarkReport, w as KnowledgeBenchmarkResponder, x as KnowledgeBenchmarkScenario, y as KnowledgeBenchmarkSliceSummary, z as KnowledgeBenchmarkSource, C as KnowledgeBenchmarkSpec, D as KnowledgeBenchmarkSplit, E as KnowledgeBenchmarkTaskKind, F as KnowledgeClaimMatcher, G as KnowledgeMemoryBenchmarkCase, H as KnowledgeMemoryBenchmarkTaskKind, I as KnowledgeMemoryEvent, J as KnowledgeMemoryFactMatcher, L as KnowledgeRetrievalBenchmarkCase, M as KnowledgeRetrievalBenchmarkQrel, N as KnowledgeRetrievalBenchmarkQuery, O as MemoryAdapterBenchmarkCandidate, P as MemoryAdapterBenchmarkRankingRow, Q as OwnedAgentMemoryRunLease, S as RetrievalConfig, T as RetrievalEvalArtifact, U as RetrievalEvalRetriever, V as RetrievalEvalRetrieverInput, W as RetrievalEvalRetrieverResult, X as RetrievalEvalScenario, Y as RetrievalGoldTarget, Z as RetrievalHoldoutBypassReason, _ as RetrievalHoldoutCallContext, $ as RetrievalHoldoutConfig, a0 as RetrievalHoldoutEligibleItem, a1 as RetrievalHoldoutEvent, a2 as RetrievalHoldoutResult, a3 as RetrievalHoldoutSessionState, a4 as RetrievalMetricSummary, a5 as RetrievalMetricWeights, a6 as RetrievalParameterSearchSpace, a7 as RetrievalParameterSweepProposerOptions, a8 as RetrievalRecallJudgeOptions, a9 as RetrievedKnowledgeHit, aa as RetrievedSourceSpan, ab as RunKnowledgeBenchmarkSuiteOptions, ac as RunKnowledgeBenchmarkSuiteResult, ad as RunMemoryAdapterBenchmarkOptions, ae as RunMemoryAdapterBenchmarkResult, af as acquireAgentMemoryRunLease, ag as buildRetrievalEvalDispatch, ah as buildRetrievalParameterCandidates, ai as retrievalConfigFromSurface, aj as retrievalConfigSurface, ak as retrievalParameterSweepProposer, al as retrievalRecallJudge, am as runRetrievalImprovementLoop, an as scoreRetrievalArtifact } from './types-ZzY_x0r7.js';
+import { OptimizationMethod, DispatchContext, JudgeConfig, ComparisonCost, Scenario } from '@tangle-network/agent-eval/campaign';
+import { R as RunSerializedKnowledgeOptimizationResult, a as RunSerializedKnowledgeOptimizationOptions } from './index-Cf7txrYP.js';
+export { A as AgentMemoryActivation, b as AgentMemoryActivationDriver, c as AgentMemoryAttemptEvent, d as AgentMemoryBranch, e as AgentMemoryBranchLifetime, f as AgentMemoryBranchSnapshot, g as AgentMemoryDimensionComparison, h as AgentMemoryExecutionContext, i as AgentMemoryExecutionCostMeter, j as AgentMemoryExecutionCostReceipt, k as AgentMemoryExecutionPaidCallInput, l as AgentMemoryExecutionPaidCallResult, m as AgentMemoryExecutionStep, n as AgentMemoryExperimentCandidate, o as AgentMemoryExperimentRankingRow, p as AgentMemoryExperimentRunLease, q as AgentMemoryFinalEvaluation, r as AgentMemoryFinalPair, s as AgentMemoryHitSchema, t as AgentMemoryImprovementRunLease, u as AgentMemoryJournalEntry, v as AgentMemoryKindSchema, w as AgentMemoryLifecycleTimeoutError, x as AgentMemoryLifecycleUnsafeError, y as AgentMemoryPromotionDecision, z as AgentMemoryScopeSchema, B as AgentMemorySequence, C as AgentMemorySequenceArtifact, D as AgentMemorySequenceProbe, E as AgentMemorySequenceProbeResult, F as AgentMemorySequenceScenario, G as AgentMemorySequenceStep, H as AgentMemorySharingPolicy, I as AgentMemoryVisibility, J as AgentMemoryWriteInputSchema, K as BuildAgentMemorySequencesFromBenchmarkCasesOptions, L as CreateAgentMemoryBranchOptions, M as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, N as ForkAgentMemoryBranchSnapshotOptions, O as GraphitiMcpClientLike, P as GraphitiMemoryAdapterOptions, Q as GraphitiToolNames, S as Mem0ClientLike, T as Mem0ClientMode, U as Mem0MemoryAdapterOptions, V as MemoryConfigScenario, W as Neo4jAgentMemoryAdapterOptions, X as RetrievalHoldoutOffPolicyOptions, Y as RetrievalHoldoutOffPolicyResult, Z as RetrievalHoldoutSessionSummary, _ as RunAgentMemoryExperimentOptions, $ as RunAgentMemoryExperimentResult, a0 as RunAgentMemoryImprovementOptions, a1 as RunAgentMemoryImprovementResult, a2 as SerializedCandidate, a3 as SerializedCandidateCodec, a4 as agentMemorySequenceJudge, a5 as applyRetrievalHoldout, a6 as applySessionStickyRetrievalHoldout, a7 as buildAgentMemorySequenceScenarios, a8 as buildAgentMemorySequencesFromBenchmarkCases, a9 as createAgentMemoryBranch, aa as createGraphitiMemoryAdapter, ab as createMem0MemoryAdapter, ac as createMemoryExecutionPool, ad as createNeo4jAgentMemoryAdapter, ae as defaultGetMemoryContext, af as deterministicRng, ag as emitRetrievalHoldoutBypass, ah as forkAgentMemoryBranchSnapshot, ai as graphitiMemoryAdapterIdentity, aj as jsonCandidateCodec, ak as jsonObjectCandidateCodec, al as mem0MemoryAdapterIdentity, am as memoryHitToSourceRecord, an as memoryRecoveryDelayMs, ao as memoryWriteResultToSourceRecord, ap as renderMemoryContext, aq as resetRetrievalHoldoutRegistry, ar as resolveMemoryCleanupTimeoutMs, as as retrievalHoldoutConfigHash, at as runAgentMemoryExperiment, au as runAgentMemoryImprovement, av as runBoundedMemoryLifecycle, aw as runSerializedKnowledgeOptimization, ax as scenarioContentFingerprint, ay as sleepForMemoryRecovery, az as toOffPolicyTrajectory } from './index-Cf7txrYP.js';
+import { R as RetrievalConfig, a as RetrievalEvalScenario, b as RetrievalEvalArtifact, c as RetrievalEvalRetriever, d as RetrievalMetricWeights, e as RetrievedKnowledgeHit } from './types-BY-xLVw-.js';
+export { A as AgentMemoryAcquireRunLease, f as AgentMemoryAdapter, g as AgentMemoryBranchIsolation, h as AgentMemoryContext, i as AgentMemoryControllerMode, j as AgentMemoryHit, k as AgentMemoryKind, l as AgentMemoryRunLease, m as AgentMemoryScope, n as AgentMemorySearchOptions, o as AgentMemoryWriteInput, p as AgentMemoryWriteResult, B as BuildRetrievalBenchmarkCasesFromQrelsOptions, q as BuildRetrievalEvalDispatchOptions, K as KnowledgeAnswerBenchmarkCase, r as KnowledgeAnswerBenchmarkTaskKind, s as KnowledgeBenchmarkArtifact, t as KnowledgeBenchmarkCase, u as KnowledgeBenchmarkCaseBase, v as KnowledgeBenchmarkDistribution, w as KnowledgeBenchmarkEvaluation, x as KnowledgeBenchmarkFamily, y as KnowledgeBenchmarkReport, z as KnowledgeBenchmarkResponder, C as KnowledgeBenchmarkScenario, D as KnowledgeBenchmarkSliceSummary, E as KnowledgeBenchmarkSource, F as KnowledgeBenchmarkSpec, G as KnowledgeBenchmarkSplit, H as KnowledgeBenchmarkTaskKind, I as KnowledgeClaimMatcher, J as KnowledgeMemoryBenchmarkCase, L as KnowledgeMemoryBenchmarkTaskKind, M as KnowledgeMemoryEvent, N as KnowledgeMemoryFactMatcher, O as KnowledgeRetrievalBenchmarkCase, P as KnowledgeRetrievalBenchmarkQrel, Q as KnowledgeRetrievalBenchmarkQuery, S as MemoryAdapterBenchmarkCandidate, T as MemoryAdapterBenchmarkRankingRow, U as OwnedAgentMemoryRunLease, V as PartitionRetrievalScenariosOptions, W as RetrievalEvalRetrieverInput, X as RetrievalEvalRetrieverResult, Y as RetrievalGoldTarget, Z as RetrievalHoldoutBypassReason, _ as RetrievalHoldoutCallContext, $ as RetrievalHoldoutConfig, a0 as RetrievalHoldoutEligibleItem, a1 as RetrievalHoldoutEvent, a2 as RetrievalHoldoutResult, a3 as RetrievalHoldoutSessionState, a4 as RetrievalMetricSummary, a5 as RetrievalRecallJudgeOptions, a6 as RetrievalScenarioPartitions, a7 as RetrievedSourceSpan, a8 as RunKnowledgeBenchmarkSuiteOptions, a9 as RunKnowledgeBenchmarkSuiteResult, aa as RunMemoryAdapterBenchmarkOptions, ab as RunMemoryAdapterBenchmarkResult, ac as acquireAgentMemoryRunLease, ad as buildRetrievalEvalDispatch, ae as partitionRetrievalScenarios, af as retrievalConfigFromSurface, ag as retrievalConfigSurface, ah as retrievalRecallJudge, ai as scoreRetrievalArtifact } from './types-BY-xLVw-.js';
 export { INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildRetrievalBenchmarkCasesFromQrels, createInMemoryBenchmarkAdapter, createNoopMemoryBenchmarkAdapter, isKnowledgeMemoryBenchmarkCase, knowledgeBenchmarkJudge, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, renderKnowledgeBenchmarkReportMarkdown, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, runKnowledgeBenchmarkSuite, runMemoryAdapterBenchmark, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, summarizeKnowledgeBenchmarkCampaign } from './benchmarks/index.js';
 import { KnowledgeFragment } from './sources/index.js';
 export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from './sources/index.js';
-export { AgentMemoryActivation, AgentMemoryActivationDriver, AgentMemoryAttemptEvent, AgentMemoryBranch, AgentMemoryBranchLifetime, AgentMemoryBranchSnapshot, AgentMemoryDimensionComparison, AgentMemoryExperimentCandidate, AgentMemoryExperimentRankingRow, AgentMemoryExperimentRunLease, AgentMemoryGovernor, AgentMemoryHitSchema, AgentMemoryImprovementRunLease, AgentMemoryImprovementSeed, AgentMemoryJournalEntry, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryPromotionDecision, AgentMemoryScopeSchema, AgentMemorySequence, AgentMemorySequenceArtifact, AgentMemorySequenceProbe, AgentMemorySequenceProbeResult, AgentMemorySequenceScenario, AgentMemorySequenceStep, AgentMemorySharingPolicy, AgentMemoryVisibility, AgentMemoryWriteInputSchema, BuildAgentMemorySequencesFromBenchmarkCasesOptions, CreateAgentMemoryBranchOptions, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, ForkAgentMemoryBranchSnapshotOptions, GraphitiMcpClientLike, GraphitiMemoryAdapterOptions, GraphitiToolNames, Mem0ClientLike, Mem0ClientMode, Mem0MemoryAdapterOptions, Neo4jAgentMemoryAdapterOptions, RetrievalHoldoutOffPolicyOptions, RetrievalHoldoutOffPolicyResult, RetrievalHoldoutSessionSummary, RunAgentMemoryExperimentOptions, RunAgentMemoryExperimentResult, RunAgentMemoryImprovementOptions, RunAgentMemoryImprovementResult, agentMemorySequenceJudge, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, createAgentMemoryBranch, createGraphitiMemoryAdapter, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, deterministicRng, emitRetrievalHoldoutBypass, forkAgentMemoryBranchSnapshot, graphitiMemoryAdapterIdentity, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, renderMemoryContext, resetRetrievalHoldoutRegistry, resolveMemoryCleanupTimeoutMs, retrievalHoldoutConfigHash, runAgentMemoryExperiment, runAgentMemoryImprovement, runBoundedMemoryLifecycle, sleepForMemoryRecovery, toOffPolicyTrajectory } from './memory/index.js';
 import '@tangle-network/agent-eval/rl';
 
 interface SourceAdapterInput {
@@ -633,6 +634,33 @@ interface AdaptiveResearchDriver {
  */
 declare function createAdaptiveResearchDriver(options?: AdaptiveDriverOptions): AdaptiveResearchDriver;
 
+type RagOptimizationConfig = Record<string, AgentCandidateJsonValue>;
+type RagOptimizationBaseOptions = Omit<RunSerializedKnowledgeOptimizationOptions<RagOptimizationConfig, RagAnswerEvalScenario, RagAnswerEvalArtifact>, 'baseline' | 'method' | 'trainScenarios' | 'selectionScenarios' | 'finalScenarios' | 'dispatchCandidate' | 'judges' | 'codec' | 'scenarioFingerprint'>;
+interface RunRagOptimizationOptions extends RagOptimizationBaseOptions {
+    baseline: RagOptimizationConfig;
+    method: OptimizationMethod<RagAnswerEvalScenario, RagAnswerEvalArtifact>;
+    trainScenarios: readonly RagAnswerEvalScenario[];
+    selectionScenarios: readonly RagAnswerEvalScenario[];
+    finalScenarios: readonly RagAnswerEvalScenario[];
+    run(input: {
+        config: RagOptimizationConfig;
+        configSurface: string;
+        configSurfaceHash: string;
+        scenario: RagAnswerEvalScenario;
+        context: DispatchContext;
+    }): Promise<RagAnswerEvalArtifact>;
+    judges?: readonly JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>[];
+}
+interface RunRagOptimizationResult extends RunSerializedKnowledgeOptimizationResult<RagOptimizationConfig> {
+    baselineConfig: RagOptimizationConfig;
+    winnerConfig: RagOptimizationConfig;
+    trainScenarios: readonly RagAnswerEvalScenario[];
+    selectionScenarios: readonly RagAnswerEvalScenario[];
+    finalScenarios: readonly RagAnswerEvalScenario[];
+}
+/** Optimizes retrieval and answer behavior together as one serialized RAG configuration. */
+declare function runRagOptimization(options: RunRagOptimizationOptions): Promise<RunRagOptimizationResult>;
+
 interface ApplyWriteBlocksResult {
     written: string[];
     warnings: string[];
@@ -746,7 +774,29 @@ type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoo
 declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
 declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
 
-type RagKnowledgeImprovementPhase = 'retrieval-tuning' | 'gap-diagnosis' | 'knowledge-acquisition' | 'knowledge-update' | 'answer-quality' | 'promotion';
+type RetrievalOptimizationBaseOptions = Omit<RunSerializedKnowledgeOptimizationOptions<RetrievalConfig, RetrievalEvalScenario, RetrievalEvalArtifact>, 'baseline' | 'method' | 'trainScenarios' | 'selectionScenarios' | 'finalScenarios' | 'dispatchCandidate' | 'judges' | 'codec' | 'scenarioFingerprint'>;
+interface RunRetrievalImprovementLoopOptions extends RetrievalOptimizationBaseOptions {
+    baseline: RetrievalConfig;
+    trainScenarios: readonly RetrievalEvalScenario[];
+    selectionScenarios: readonly RetrievalEvalScenario[];
+    finalScenarios: readonly RetrievalEvalScenario[];
+    method: OptimizationMethod<RetrievalEvalScenario, RetrievalEvalArtifact>;
+    index?: KnowledgeIndex;
+    defaultK?: number;
+    retrieve?: RetrievalEvalRetriever;
+    judges?: readonly JudgeConfig<RetrievalEvalArtifact, RetrievalEvalScenario>[];
+    metricWeights?: RetrievalMetricWeights;
+}
+interface RunRetrievalImprovementLoopResult extends RunSerializedKnowledgeOptimizationResult<RetrievalConfig> {
+    baselineConfig: RetrievalConfig;
+    winnerConfig: RetrievalConfig;
+    trainScenarios: readonly RetrievalEvalScenario[];
+    selectionScenarios: readonly RetrievalEvalScenario[];
+    finalScenarios: readonly RetrievalEvalScenario[];
+}
+declare function runRetrievalImprovementLoop(options: RunRetrievalImprovementLoopOptions): Promise<RunRetrievalImprovementLoopResult>;
+
+type RagKnowledgeImprovementPhase = 'rag-optimization' | 'retrieval-tuning' | 'gap-diagnosis' | 'knowledge-acquisition' | 'knowledge-update' | 'answer-quality' | 'promotion';
 type RagKnowledgeImprovementPhaseStatus = 'completed' | 'skipped' | 'failed';
 type RagGapKind = 'missing-source' | 'stale-source' | 'retrieval-miss' | 'retrieval-noise' | 'chunking-mismatch' | 'missing-multihop-evidence' | 'generator-unsupported-claim' | 'citation-mismatch' | 'incorrect-abstention' | 'unknown';
 type RagGapSeverity = 'info' | 'warning' | 'error' | 'critical';
@@ -756,7 +806,7 @@ interface RagGapFinding {
     severity: RagGapSeverity;
     message: string;
     scenarioId?: string;
-    evidence?: Record<string, JsonValue>;
+    evidence?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagKnowledgeImprovementPhaseResult {
     phase: RagKnowledgeImprovementPhase;
@@ -764,22 +814,26 @@ interface RagKnowledgeImprovementPhaseResult {
     summary: string;
     startedAt: string;
     finishedAt: string;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
+type RagOptimizationSelection = Pick<RunRagOptimizationResult, 'methodName' | 'baseline' | 'winner' | 'baselineConfig' | 'winnerConfig'>;
+type RetrievalOptimizationSelection = Pick<RunRetrievalImprovementLoopResult, 'methodName' | 'baseline' | 'winner' | 'baselineConfig' | 'winnerConfig'>;
 interface RagPhaseInputBase {
     goal: string;
     phases: readonly RagKnowledgeImprovementPhaseResult[];
+    /** Selected candidate only. Adaptive update callbacks run before final scoring starts. */
+    optimization?: RagOptimizationSelection;
     signal?: AbortSignal;
 }
 interface RagDiagnosisInput extends RagPhaseInputBase {
-    retrieval?: RunRetrievalImprovementLoopResult;
+    retrieval?: RetrievalOptimizationSelection;
 }
 interface RagKnowledgeAcquisitionInput extends RagPhaseInputBase {
-    retrieval?: RunRetrievalImprovementLoopResult;
+    retrieval?: RetrievalOptimizationSelection;
     findings: readonly RagGapFinding[];
 }
 interface RagKnowledgeUpdateInput extends RagPhaseInputBase {
-    retrieval?: RunRetrievalImprovementLoopResult;
+    retrieval?: RetrievalOptimizationSelection;
     findings: readonly RagGapFinding[];
     acquisition?: KnowledgeResearchLoopDecision;
 }
@@ -787,10 +841,10 @@ interface RagKnowledgeUpdateResult {
     applied: boolean;
     summary: string;
     research?: KnowledgeResearchLoopResult;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagAnswerQualityInput extends RagPhaseInputBase {
-    retrieval?: RunRetrievalImprovementLoopResult;
+    retrieval?: RetrievalOptimizationSelection;
     findings: readonly RagGapFinding[];
     acquisition?: KnowledgeResearchLoopDecision;
     knowledgeUpdate?: RagKnowledgeUpdateResult;
@@ -798,11 +852,19 @@ interface RagAnswerQualityInput extends RagPhaseInputBase {
 interface RagAnswerQualityResult {
     passed: boolean;
     metrics: Record<string, number>;
+    finalScenarioIds: readonly string[];
+    datasetRef: string;
+    evaluatorRef: string;
+    cost: ComparisonCost;
     findings?: readonly RagGapFinding[];
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagPromotionInput extends RagPhaseInputBase {
-    retrieval?: RunRetrievalImprovementLoopResult;
+    retrieval?: RetrievalOptimizationSelection;
+    /** Full final-case result available only to the terminal promotion decision. */
+    optimizationComparison?: RunRagOptimizationResult['comparison'];
+    /** Full final-case result available only to the terminal promotion decision. */
+    retrievalComparison?: RunRetrievalImprovementLoopResult['comparison'];
     findings: readonly RagGapFinding[];
     acquisition?: KnowledgeResearchLoopDecision;
     knowledgeUpdate?: RagKnowledgeUpdateResult;
@@ -811,7 +873,7 @@ interface RagPromotionInput extends RagPhaseInputBase {
 interface RagPromotionResult {
     promoted: boolean;
     reason: string;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagKnowledgeResearchOptions extends Omit<RunKnowledgeResearchLoopOptions, 'goal' | 'signal' | 'step'> {
     goal?: string;
@@ -819,13 +881,20 @@ interface RagKnowledgeResearchOptions extends Omit<RunKnowledgeResearchLoopOptio
 }
 interface RunRagKnowledgeImprovementLoopOptions {
     goal: string;
+    optimization?: RunRagOptimizationOptions;
     retrieval?: RunRetrievalImprovementLoopOptions;
     diagnose?: (input: RagDiagnosisInput) => MaybePromise$1<readonly RagGapFinding[]>;
     acquireKnowledge?: (input: RagKnowledgeAcquisitionInput) => MaybePromise$1<KnowledgeResearchLoopDecision>;
     knowledgeResearch?: RagKnowledgeResearchOptions;
     updateKnowledge?: (input: RagKnowledgeUpdateInput) => MaybePromise$1<RagKnowledgeUpdateResult>;
     evaluateAnswers?: (input: RagAnswerQualityInput) => MaybePromise$1<RagAnswerQualityResult>;
-    promote?: (input: RagPromotionInput) => MaybePromise$1<RagPromotionResult>;
+    /** Maximum total answer-evaluation spend accepted for promotion. */
+    answerQualityCostCeiling?: number;
+    /**
+     * Makes a side-effect-free promotion decision after the library has rejected
+     * missing, regressing, unaccounted, or over-budget final evidence.
+     */
+    decidePromotion?: (input: RagPromotionInput) => MaybePromise$1<RagPromotionResult>;
     enabledPhases?: readonly RagKnowledgeImprovementPhase[];
     requiredPhases?: readonly RagKnowledgeImprovementPhase[];
     signal?: AbortSignal;
@@ -834,6 +903,7 @@ interface RunRagKnowledgeImprovementLoopOptions {
 interface RunRagKnowledgeImprovementLoopResult {
     goal: string;
     phases: readonly RagKnowledgeImprovementPhaseResult[];
+    optimization?: RunRagOptimizationResult;
     retrieval?: RunRetrievalImprovementLoopResult;
     findings: readonly RagGapFinding[];
     acquisition?: KnowledgeResearchLoopDecision;
@@ -855,7 +925,7 @@ interface RagEvalContext {
     sourceId?: string;
     anchorId?: string;
     stale?: boolean;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagEvalCitation {
     id: string;
@@ -865,13 +935,13 @@ interface RagEvalCitation {
     sourceId?: string;
     anchorId?: string;
     quote?: string;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagEvalClaim {
     id: string;
     text: string;
     citationIds?: readonly string[];
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagRequiredContext {
     id?: string;
@@ -896,7 +966,7 @@ interface ExternalRagEvalScore {
     provider: RagEvalProvider | string;
     scores: Record<string, number>;
     reasons?: Record<string, string>;
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagAnswerEvalArtifact {
     query: string;
@@ -908,7 +978,7 @@ interface RagAnswerEvalArtifact {
     durationMs?: number;
     costUsd?: number;
     externalScores?: readonly ExternalRagEvalScore[];
-    metadata?: Record<string, JsonValue>;
+    metadata?: Record<string, AgentCandidateJsonValue>;
 }
 interface RagAnswerMetricSummary {
     metrics: Record<RagEvalMetricKey, number>;
@@ -936,6 +1006,10 @@ interface RagAnswerEvalCase {
 }
 interface RagAnswerQualityHookOptions {
     scenarios: readonly RagAnswerEvalScenario[];
+    /** Immutable identity of generation, scoring, models, and external evaluator behavior. */
+    evaluatorRef: string;
+    /** Return observed spend after all generation and evaluation calls finish. */
+    cost: ComparisonCost | (() => MaybePromise<ComparisonCost>);
     run: (scenario: RagAnswerEvalScenario) => MaybePromise<RagAnswerEvalArtifact>;
     externalEvaluator?: (item: RagAnswerEvalCase) => MaybePromise<ExternalRagEvalScore | readonly ExternalRagEvalScore[] | undefined>;
     thresholds?: Partial<Record<RagEvalMetricKey, number>>;
@@ -977,11 +1051,12 @@ interface KnowledgeBaseQualityReport {
     findings: readonly RagGapFinding[];
 }
 type MaybePromise<T> = T | Promise<T>;
-declare function ragAnswerQualityJudge(options?: RagAnswerQualityJudgeOptions): JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
-declare function scoreRagAnswerArtifact(artifact: RagAnswerEvalArtifact, scenario: RagAnswerEvalScenario, options?: RagAnswerQualityJudgeOptions): RagAnswerMetricSummary;
-declare function diagnoseRagAnswerFailure(metrics: Record<RagEvalMetricKey, number>, scenario: RagAnswerEvalScenario, thresholds?: Partial<Record<RagEvalMetricKey, number>>): RagGapFinding[];
+
 declare function createRagAnswerQualityHook(options: RagAnswerQualityHookOptions): () => Promise<RagAnswerQualityResult>;
 declare function calibrateRagAnswerJudge(options: RagCalibrationOptions): Promise<RagCalibrationResult>;
+
+declare function scoreKnowledgeBaseIndex(index: KnowledgeIndex, options?: KnowledgeBaseQualityOptions): KnowledgeBaseQualityReport;
+
 declare function normalizeExternalRagScores(scores: readonly ExternalRagEvalScore[]): Record<string, Record<RagEvalMetricKey, number>>;
 declare function toRagasEvaluationRows(cases: readonly RagAnswerEvalCase[]): {
     user_input: string;
@@ -1013,7 +1088,10 @@ declare function toRagCheckerRecords(cases: readonly RagAnswerEvalCase[]): {
     }[];
     claims: string[];
 }[];
-declare function scoreKnowledgeBaseIndex(index: KnowledgeIndex, options?: KnowledgeBaseQualityOptions): KnowledgeBaseQualityReport;
+
+declare function ragAnswerQualityJudge(options?: RagAnswerQualityJudgeOptions): JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
+declare function scoreRagAnswerArtifact(artifact: RagAnswerEvalArtifact, scenario: RagAnswerEvalScenario, options?: RagAnswerQualityJudgeOptions): RagAnswerMetricSummary;
+declare function diagnoseRagAnswerFailure(metrics: Record<RagEvalMetricKey, number>, scenario: RagAnswerEvalScenario, thresholds?: Partial<Record<RagEvalMetricKey, number>>): RagGapFinding[];
 
 type KnowledgeImprovementStatus = 'running' | 'candidate-ready' | 'promoted' | 'rejected' | 'blocked';
 interface KnowledgeImprovementMetricProvenanceBase {
@@ -1063,6 +1141,8 @@ interface KnowledgeImprovementCandidateRecord {
     candidateHash?: string;
     evidenceHash?: string;
     promotionPlanHash?: string;
+    /** Durable one-way boundary preventing final-case reuse after interruption. */
+    finalEvaluationStartedAt?: string;
     status: KnowledgeImprovementStatus;
     createdAt: string;
     updatedAt: string;
@@ -1071,6 +1151,7 @@ interface KnowledgeImprovementRunState {
     runId: string;
     root: string;
     goal: string;
+    implementationRef: string;
     status: KnowledgeImprovementStatus;
     baseHash: string;
     createdAt: string;
@@ -1114,6 +1195,7 @@ declare const KnowledgeImprovementRunStateSchema: z.ZodObject<{
     runId: z.ZodString;
     root: z.ZodString;
     goal: z.ZodString;
+    implementationRef: z.ZodString;
     status: z.ZodEnum<{
         rejected: "rejected";
         promoted: "promoted";
@@ -1132,6 +1214,7 @@ declare const KnowledgeImprovementRunStateSchema: z.ZodObject<{
         candidateHash: z.ZodOptional<z.ZodString>;
         evidenceHash: z.ZodOptional<z.ZodString>;
         promotionPlanHash: z.ZodOptional<z.ZodString>;
+        finalEvaluationStartedAt: z.ZodOptional<z.ZodISODateTime>;
         status: z.ZodEnum<{
             rejected: "rejected";
             promoted: "promoted";
@@ -1151,6 +1234,7 @@ declare const KnowledgeImprovementEvidenceSchema: z.ZodObject<{
     candidateId: z.ZodString;
     iteration: z.ZodNumber;
     goalHash: z.ZodString;
+    implementationRef: z.ZodString;
     baseHash: z.ZodString;
     candidateHash: z.ZodString;
     promotionPlanHash: z.ZodString;
@@ -1237,6 +1321,20 @@ interface ResolvedKnowledgeImprovementCandidate {
 interface KnowledgeImprovementRetrievalOptions extends Omit<RunRetrievalImprovementLoopOptions, 'index' | 'runDir'> {
     runDir?: RunRetrievalImprovementLoopOptions['runDir'];
 }
+type KnowledgeImprovementRagOptimizationRunInput = Parameters<RunRagOptimizationOptions['run']>[0] & {
+    runId: string;
+    iteration: number;
+    candidateId: string;
+    root: string;
+    baselineRoot: string;
+    candidateRoot: string;
+    candidateIndex: KnowledgeIndex;
+    baseHash: string;
+};
+interface KnowledgeImprovementRagOptimizationOptions extends Omit<RunRagOptimizationOptions, 'run' | 'runDir'> {
+    runDir?: RunRagOptimizationOptions['runDir'];
+    run(input: KnowledgeImprovementRagOptimizationRunInput): Promise<RagAnswerEvalArtifact>;
+}
 interface KnowledgeImprovementUpdateInput extends RagKnowledgeUpdateInput {
     runId: string;
     iteration: number;
@@ -1250,6 +1348,11 @@ type KnowledgeImprovementUpdate = (input: KnowledgeImprovementUpdateInput) => Pr
 interface KnowledgeImprovementOptions {
     root: string;
     goal: string;
+    /**
+     * Immutable identity covering callbacks, evaluation policy, models, indexes,
+     * external services, and all other behavior that can affect this run.
+     */
+    implementationRef: string;
     runId?: string;
     ownerId?: string;
     leaseTtlMs?: number;
@@ -1263,40 +1366,93 @@ interface KnowledgeImprovementOptions {
     kbQuality?: KnowledgeBaseQualityOptions;
     step?: RunKnowledgeResearchLoopOptions['step'];
     knowledgeResearch?: Omit<RagKnowledgeResearchOptions, 'root'>;
+    ragOptimization?: KnowledgeImprovementRagOptimizationOptions;
     retrieval?: KnowledgeImprovementRetrievalOptions;
     diagnose?: NonNullable<RunRagKnowledgeImprovementLoopOptions['diagnose']>;
     acquireKnowledge?: NonNullable<RunRagKnowledgeImprovementLoopOptions['acquireKnowledge']>;
     updateKnowledge?: KnowledgeImprovementUpdate;
     evaluateAnswers?: NonNullable<RunRagKnowledgeImprovementLoopOptions['evaluateAnswers']>;
-    decidePromotion?: NonNullable<RunRagKnowledgeImprovementLoopOptions['promote']>;
+    answerQualityCostCeiling?: RunRagKnowledgeImprovementLoopOptions['answerQualityCostCeiling'];
+    decidePromotion?: NonNullable<RunRagKnowledgeImprovementLoopOptions['decidePromotion']>;
     enabledPhases?: readonly RagKnowledgeImprovementPhase[];
     requiredPhases?: readonly RagKnowledgeImprovementPhase[];
+    /** Repeatable candidate screening that must not use final cases. */
+    evaluateDevelopment?: KnowledgeImprovementEvaluator;
+    /** Single-use final evaluator. A failure ends the run. */
     evaluate?: KnowledgeImprovementEvaluator;
     signal?: AbortSignal;
     now?: () => Date;
     onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
 }
+
+/** Load the durable result for one exact activation without changing knowledge or run state. */
+declare function loadKnowledgeImprovementActivationResult(options: LoadKnowledgeImprovementActivationResultOptions): Promise<AgentImprovementActivationResult | null>;
+
+type PolicyCandidateOptions = Omit<KnowledgeImprovementOptions, 'root' | 'goal' | 'implementationRef' | 'runId' | 'maxCandidates' | 'step' | 'knowledgeResearch' | 'updateKnowledge'>;
+type PolicyOptimizationBaseOptions<TPolicy extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact> = Omit<RunSerializedKnowledgeOptimizationOptions<TPolicy, TScenario, TArtifact>, 'baseline' | 'method' | 'trainScenarios' | 'selectionScenarios' | 'finalScenarios' | 'executionRef'>;
+interface OptimizeKnowledgeBasePolicyOptions<TPolicy extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact> extends PolicyOptimizationBaseOptions<TPolicy, TScenario, TArtifact> {
+    root: string;
+    goal: string;
+    baselinePolicy: TPolicy;
+    method: OptimizationMethod<TScenario, TArtifact>;
+    trainScenarios: readonly TScenario[];
+    selectionScenarios: readonly TScenario[];
+    finalScenarios: readonly TScenario[];
+    /** Commit or content identity for evaluation, applyPolicy, and external dependencies. */
+    policyApplicationRef: string;
+    /** Optional namespace for parallel materialization of the same measured policy. */
+    candidateRunLabel?: string;
+    candidate?: PolicyCandidateOptions;
+    applyPolicy(input: KnowledgeImprovementUpdateInput & {
+        policy: TPolicy;
+        policySurface: string;
+        policySurfaceHash: string;
+        optimizationMethod: string;
+    }): Promise<{
+        applied: boolean;
+        summary: string;
+        metadata?: Record<string, AgentCandidateJsonValue>;
+    }>;
+}
+interface OptimizeKnowledgeBasePolicyResult<TPolicy extends AgentCandidateJsonValue> {
+    optimization: RunSerializedKnowledgeOptimizationResult<TPolicy>;
+    improvement: KnowledgeImprovementResult;
+}
+/**
+ * Optimizes a serialized KB-maintenance policy, then materializes the selected
+ * policy in one isolated knowledge candidate. Activation remains explicit.
+ */
+declare function optimizeKnowledgeBasePolicy<TPolicy extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact>(options: OptimizeKnowledgeBasePolicyOptions<TPolicy, TScenario, TArtifact>): Promise<OptimizeKnowledgeBasePolicyResult<TPolicy>>;
+type KnowledgePolicyDispatch<TPolicy extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact> = (input: {
+    candidate: TPolicy;
+    candidateSurface: string;
+    candidateSurfaceHash: string;
+    scenario: TScenario;
+    context: DispatchContext;
+}) => Promise<TArtifact>;
+
+declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
+
 declare function knowledgeImprovementRunId(root: string, goal: string): string;
 declare function knowledgeImprovementRunDir(root: string, runId: string): string;
 declare function loadKnowledgeImprovementState(root: string, runId: string): Promise<KnowledgeImprovementRunState | null>;
-/** Load the durable result for one exact activation without changing knowledge or run state. */
-declare function loadKnowledgeImprovementActivationResult(options: LoadKnowledgeImprovementActivationResultOptions): Promise<AgentImprovementActivationResult | null>;
+interface KnowledgeImprovementEvent extends Record<string, unknown> {
+    at: string;
+    type: string;
+}
+declare function loadKnowledgeImprovementEvents(root: string, runId: string): Promise<KnowledgeImprovementEvent[]>;
+
+/** Promote one previously measured candidate without rerunning research or evaluation. */
+declare function promoteKnowledgeCandidate(options: PromoteKnowledgeCandidateOptions): Promise<KnowledgeImprovementMutationResult>;
+/** Restore the frozen baseline paired with one previously measured candidate. */
+declare function restoreKnowledgeCandidateBaseline(options: RestoreKnowledgeCandidateBaselineOptions): Promise<KnowledgeImprovementMutationResult>;
+
 /** Freeze the exact knowledge bytes and measured evidence a later approval may promote. */
 declare function knowledgeImprovementCandidateRef(result: Pick<KnowledgeImprovementResult, 'runId' | 'state' | 'candidate'>): KnowledgeImprovementCandidateRef;
 /** Use both frozen sides of one measured comparison in isolated, integrity-checked copies. */
 declare function withKnowledgeImprovementComparison<T>(options: UseKnowledgeImprovementCandidateOptions, use: (comparison: ResolvedKnowledgeImprovementComparison) => Promise<T> | T): Promise<T>;
 /** Use the frozen candidate side of one measured comparison. */
 declare function withKnowledgeImprovementCandidate<T>(options: UseKnowledgeImprovementCandidateOptions, use: (candidate: ResolvedKnowledgeImprovementCandidate) => Promise<T> | T): Promise<T>;
-/** Promote one previously measured candidate without rerunning research or evaluation. */
-declare function promoteKnowledgeCandidate(options: PromoteKnowledgeCandidateOptions): Promise<KnowledgeImprovementMutationResult>;
-/** Restore the frozen baseline paired with one previously measured candidate. */
-declare function restoreKnowledgeCandidateBaseline(options: RestoreKnowledgeCandidateBaselineOptions): Promise<KnowledgeImprovementMutationResult>;
-declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
-interface KnowledgeImprovementEvent extends Record<string, unknown> {
-    at: string;
-    type: string;
-}
-declare function loadKnowledgeImprovementEvents(root: string, runId: string): Promise<KnowledgeImprovementEvent[]>;
 declare function hashKnowledgeBase(root: string): Promise<string>;
 
 /** Convert a measured knowledge candidate into the shared review and execution identity. */
@@ -1510,8 +1666,7 @@ interface ClaimGroundingDriverOptions extends GroundClaimOptions {
      * What to do when a proposal carries NO cited claim. `'reject'` (default) is
      * fail-closed: in claim-grounding mode every source must declare what it is
      * cited for, so an un-annotated source is treated as ungrounded. `'accept'`
-     * lets un-annotated sources through to the relevance verifier (if any) —
-     * useful when mixing annotated and legacy proposals.
+     * lets unannotated sources through to the relevance verifier, if present.
      */
     onMissingClaim?: 'reject' | 'accept';
 }
@@ -1660,11 +1815,48 @@ declare function createKnowledgeEvent(input: {
     now?: () => Date;
 }): KnowledgeEvent;
 
+interface FileSystemSearchProviderOptions {
+    /** Knowledge-base root containing `knowledge/` and `.agent-knowledge/`. */
+    root: string;
+    /** Optional warm index, useful when the caller already built one. */
+    index?: KnowledgeIndex;
+    /** Default result count for `search()`. Defaults to 10. */
+    defaultLimit?: number;
+    /**
+     * `manual` caches the index until `refresh: true` or `invalidate()`.
+     * `always` rebuilds from disk on every search.
+     */
+    refresh?: 'manual' | 'always';
+}
+interface FileSystemSearchOptions {
+    limit?: number;
+    refresh?: boolean;
+}
+/**
+ * File-first retrieval over an `agent-knowledge` KB.
+ *
+ * This is the simple backend for products that want deterministic search over
+ * markdown knowledge files before adding embeddings, rerankers, or a vector DB.
+ */
+declare class FileSystemSearchProvider {
+    readonly root: string;
+    private index;
+    private readonly defaultLimit;
+    private readonly refreshMode;
+    constructor(options: FileSystemSearchProviderOptions);
+    getIndex(options?: FileSystemSearchOptions): Promise<KnowledgeIndex>;
+    search(query: string, options?: FileSystemSearchOptions): Promise<KnowledgeSearchResult[]>;
+    retrieve(query: string, options?: FileSystemSearchOptions): Promise<RetrievedKnowledgeHit[]>;
+    asRetrievalEvalRetriever(): RetrievalEvalRetriever;
+    invalidate(): void;
+}
+declare function createFileSystemSearchProvider(options: FileSystemSearchProviderOptions): FileSystemSearchProvider;
+
 /**
  * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
  * was last successfully refreshed, and reports staleness against a TTL.
  *
- * The contract is intentionally minimal — just enough to drive a cron loop:
+ * The contract is intentionally minimal and supports scheduled refresh loops:
  *
  *   ```ts
  *   const store = createFileSystemFreshnessStore({ root: '.agent-knowledge' })
@@ -1677,20 +1869,16 @@ declare function createKnowledgeEvent(input: {
  *   }
  *   ```
  *
- * Per-tenant isolation is enforced by `workspaceId` keying — there is no
+ * Per-tenant isolation is enforced by `workspaceId` keying. There is no
  * global mutable state across workspaces.
  *
  * Two adapters ship in-package:
  *
- *   - `createFileSystemFreshnessStore` — JSON file under the knowledge root,
+ *   - `createFileSystemFreshnessStore`: JSON file under the knowledge root,
  *     mirrors the layout convention already used by `sources.json`.
- *   - `createD1FreshnessStoreStub` — adapter scaffold for Cloudflare D1 /
- *     Postgres. Production consumers should implement the `D1Adapter`
- *     interface inside their own app; this stub exists to anchor the shape.
- *
- * @stable contract — interface is frozen at 0.x within this major.
- * @stable filesystem adapter
- * @experimental D1 stub — interface will evolve as real consumers wire it.
+ *   - `createD1FreshnessStoreStub`: complete bridge from the `D1Adapter` port
+ *     to this package's freshness interface. The port can be backed by D1,
+ *     PostgreSQL, SQLite, or another application-owned store.
  */
 /** Identity for one freshness record. */
 interface FreshnessKey {
@@ -1699,7 +1887,7 @@ interface FreshnessKey {
 }
 /** TTL bound for staleness checks. */
 interface FreshnessTtl extends FreshnessKey {
-    /** Milliseconds — `Date.now() - last() > ttlMs` ⇒ stale. */
+    /** Milliseconds; the record is stale when `Date.now() - last() > ttlMs`. */
     ttlMs: number;
     /** Injected clock for deterministic tests; defaults to system time. */
     now?: Date;
@@ -1717,7 +1905,7 @@ interface KnowledgeFreshnessStore {
     mark(input: FreshnessMark): Promise<void>;
     /** True iff `last(key)` is null or older than `ttlMs`. */
     stale(input: FreshnessTtl): Promise<boolean>;
-    /** All records for a workspace — useful for dashboards / debugging. */
+    /** All records for a workspace. */
     list(workspaceId: string): Promise<FreshnessRecord[]>;
 }
 interface FreshnessRecord {
@@ -1735,7 +1923,7 @@ interface FileSystemFreshnessStoreOptions {
 }
 /**
  * Filesystem-backed implementation. Single JSON file per knowledge root,
- * indexed by `${workspaceId}::${sourceId}`. Reads parse on every call —
+ * indexed by `${workspaceId}::${sourceId}`. Reads parse on every call;
  * cron tick rate is well below the cost of one JSON parse.
  *
  * Writes share the package-wide filesystem lock, so multiple workers cannot
@@ -1743,10 +1931,8 @@ interface FileSystemFreshnessStoreOptions {
  */
 declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
 /**
- * D1 / Postgres adapter scaffold. Production consumers implement
- * `D1Adapter` against their own driver (better-sqlite3, postgres,
- * Cloudflare D1 binding, ...). This factory wires the adapter to the
- * `KnowledgeFreshnessStore` interface.
+ * Bridge an application-owned database adapter to `KnowledgeFreshnessStore`.
+ * The adapter may use D1, PostgreSQL, SQLite, or another durable store.
  *
  * The expected schema:
  *
@@ -2311,12 +2497,8 @@ interface KnowledgeReleaseReport {
     baselineRuns: RunRecord[];
 }
 /**
- * Campaign-native release report. The caller (a consumer's KB self-improvement
- * loop) supplies the candidate/baseline `RunRecord[]` (e.g. via
- * `campaignToRunRecords`) + optional per-instance `ReleaseTraceEvidence` + the
- * gate decision; this folds them into a `ReleaseConfidenceScorecard` + a
- * `KnowledgeRelease`. Release confidence is computed from run records + traces,
- * independent of any optimizer result shape.
+ * Build a knowledge release report from candidate and baseline run records,
+ * optional trace evidence, and an optional decision record.
  */
 interface KnowledgeReleaseInput {
     candidateId: string;
@@ -2325,14 +2507,11 @@ interface KnowledgeReleaseInput {
     baselineRuns?: RunRecord[];
     traces?: ReleaseTraceEvidence[];
     gateDecision?: GateDecision | null;
+    /** Scenario corpus used to prove train and holdout split coverage. */
+    scenarios?: readonly DatasetScenario[];
     /**
-     * True when a held-out split was evaluated (drives the holdout threshold).
-     *
-     * Constraint: the substrate gate keys the holdout requirement off a scenario
-     * corpus, which this run-only report does not carry. With `hasHoldout: true`
-     * the gate fails closed (`missing_holdout_split`) even when holdout RunRecords
-     * are supplied. Callers that gate on a real held-out split should drive
-     * `evaluateReleaseConfidence` directly with a dataset/scenarios.
+     * Require both a holdout scenario and a holdout run.
+     * Provide `scenarios` with at least one `split: 'holdout'` item when true.
      */
     hasHoldout?: boolean;
     /** Candidate is the search-best variant — a promotion precondition. Default true. */
@@ -2710,4 +2889,4 @@ declare function normalizeLinkTarget(target: string): string;
 declare function isSafeKnowledgePath(path: string, allowedPrefixes?: string[]): boolean;
 declare function parseKnowledgeWriteBlocks(text: string, allowedPrefixes?: string[]): KnowledgeWriteParseResult;
 
-export { type AdaptiveDecision, type AdaptiveDriverOptions, type AdaptiveResearchDriver, type AdaptiveStats, type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type ClaimGroundingDriverOptions, type CompanyEvalCase, type D1Adapter, type DedupReason, type DeepQuestion, type DeepQuestionKind, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryLoopResult, type DiscoveryLoopRound, type DiscoveryLoopStopReason, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type EvaluateKnowledgeBaseReadinessOptions, type ExpectedGroup, type ExternalRagEvalScore, type FactResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeBaseQualityOptions, type KnowledgeBaseQualityReport, type KnowledgeBaseReadinessEvaluation, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, type KnowledgeImprovementActivationPersistence, type KnowledgeImprovementCandidateRecord, type KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementMutationReceipt, type KnowledgeImprovementMutationResult, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, type KnowledgeImprovementStatus, type KnowledgeImprovementTarget, type KnowledgeImprovementUpdate, type KnowledgeImprovementUpdateInput, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, type LoadKnowledgeImprovementActivationResultOptions, type MaterialFact, type MaterialFactLens, type MaterialFactsResult, MemoryKbStore, type ParsedFrontmatter, type PendingKnowledgeMutation, type PromoteKnowledgeCandidateOptions, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RagAnswerEvalArtifact, type RagAnswerEvalCase, type RagAnswerEvalScenario, type RagAnswerMetricSummary, type RagAnswerQualityHookOptions, type RagAnswerQualityInput, type RagAnswerQualityJudgeOptions, type RagAnswerQualityResult, type RagCalibrationOptions, type RagCalibrationResult, type RagDiagnosisInput, type RagEvalCitation, type RagEvalClaim, type RagEvalContext, type RagEvalMetricKey, type RagEvalProvider, type RagEvalSlice, type RagGapFinding, type RagGapKind, type RagGapSeverity, type RagKnowledgeAcquisitionInput, type RagKnowledgeImprovementPhase, type RagKnowledgeImprovementPhaseResult, type RagKnowledgeImprovementPhaseStatus, type RagKnowledgeResearchOptions, type RagKnowledgeUpdateInput, type RagKnowledgeUpdateResult, type RagPhaseInputBase, type RagPromotionInput, type RagPromotionResult, type RagRequiredContext, type RecoverPendingKnowledgeMutationOptions, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, type ResolvedKnowledgeImprovementCandidate, type ResolvedKnowledgeImprovementComparison, type ResolvedKnowledgeImprovementComparisonSnapshot, type RestoreKnowledgeCandidateBaselineOptions, type RouterClient, RouterError, type RouterUsage, type RunDiscoveryLoopOptions, type RunKnowledgeResearchLoopOptions, type RunRagKnowledgeImprovementLoopOptions, type RunRagKnowledgeImprovementLoopResult, RunRetrievalImprovementLoopOptions, RunRetrievalImprovementLoopResult, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type ThesisRunOptions, type ThesisRunResult, type ThesisTaskInput, type TrackedClaim, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type UseKnowledgeImprovementCandidateOptions, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifiedResearchLoopOptions, type VerifiedResearchLoopResult, type VerifiedResearchRound, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createRagAnswerQualityHook, createResearchDrivingDriver, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, diagnoseRagAnswerFailure, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, groundClaimInText, hashKnowledgeBase, improveKnowledgeBase, initKnowledgeBase, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementActivationResult, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, restoreKnowledgeCandidateBaseline, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeResearchLoop, runRagKnowledgeImprovementLoop, runTwoAgentResearchLoop, runVerifiedResearchLoop, scoreKnowledgeBaseIndex, scoreRagAnswerArtifact, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+export { type AdaptiveDecision, type AdaptiveDriverOptions, type AdaptiveResearchDriver, type AdaptiveStats, type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type ClaimGroundingDriverOptions, type CompanyEvalCase, type D1Adapter, type DedupReason, type DeepQuestion, type DeepQuestionKind, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryLoopResult, type DiscoveryLoopRound, type DiscoveryLoopStopReason, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type EvaluateKnowledgeBaseReadinessOptions, type ExpectedGroup, type ExternalRagEvalScore, type FactResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FileSystemSearchOptions, FileSystemSearchProvider, type FileSystemSearchProviderOptions, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeBaseQualityOptions, type KnowledgeBaseQualityReport, type KnowledgeBaseReadinessEvaluation, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, type KnowledgeImprovementActivationPersistence, type KnowledgeImprovementCandidateRecord, type KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementMutationReceipt, type KnowledgeImprovementMutationResult, type KnowledgeImprovementOptions, type KnowledgeImprovementRagOptimizationOptions, type KnowledgeImprovementRagOptimizationRunInput, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, type KnowledgeImprovementStatus, type KnowledgeImprovementTarget, type KnowledgeImprovementUpdate, type KnowledgeImprovementUpdateInput, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgePolicyDispatch, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, type LoadKnowledgeImprovementActivationResultOptions, type MaterialFact, type MaterialFactLens, type MaterialFactsResult, MemoryKbStore, type OptimizeKnowledgeBasePolicyOptions, type OptimizeKnowledgeBasePolicyResult, type ParsedFrontmatter, type PendingKnowledgeMutation, type PromoteKnowledgeCandidateOptions, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RagAnswerEvalArtifact, type RagAnswerEvalCase, type RagAnswerEvalScenario, type RagAnswerMetricSummary, type RagAnswerQualityHookOptions, type RagAnswerQualityInput, type RagAnswerQualityJudgeOptions, type RagAnswerQualityResult, type RagCalibrationOptions, type RagCalibrationResult, type RagDiagnosisInput, type RagEvalCitation, type RagEvalClaim, type RagEvalContext, type RagEvalMetricKey, type RagEvalProvider, type RagEvalSlice, type RagGapFinding, type RagGapKind, type RagGapSeverity, type RagKnowledgeAcquisitionInput, type RagKnowledgeImprovementPhase, type RagKnowledgeImprovementPhaseResult, type RagKnowledgeImprovementPhaseStatus, type RagKnowledgeResearchOptions, type RagKnowledgeUpdateInput, type RagKnowledgeUpdateResult, type RagOptimizationConfig, type RagOptimizationSelection, type RagPhaseInputBase, type RagPromotionInput, type RagPromotionResult, type RagRequiredContext, type RecoverPendingKnowledgeMutationOptions, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, type ResolvedKnowledgeImprovementCandidate, type ResolvedKnowledgeImprovementComparison, type ResolvedKnowledgeImprovementComparisonSnapshot, type RestoreKnowledgeCandidateBaselineOptions, RetrievalConfig, RetrievalEvalArtifact, RetrievalEvalRetriever, RetrievalEvalScenario, RetrievalMetricWeights, type RetrievalOptimizationSelection, RetrievedKnowledgeHit, type RouterClient, RouterError, type RouterUsage, type RunDiscoveryLoopOptions, type RunKnowledgeResearchLoopOptions, type RunRagKnowledgeImprovementLoopOptions, type RunRagKnowledgeImprovementLoopResult, type RunRagOptimizationOptions, type RunRagOptimizationResult, type RunRetrievalImprovementLoopOptions, type RunRetrievalImprovementLoopResult, RunSerializedKnowledgeOptimizationOptions, RunSerializedKnowledgeOptimizationResult, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type ThesisRunOptions, type ThesisRunResult, type ThesisTaskInput, type TrackedClaim, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type UseKnowledgeImprovementCandidateOptions, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifiedResearchLoopOptions, type VerifiedResearchLoopResult, type VerifiedResearchRound, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createFileSystemSearchProvider, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createRagAnswerQualityHook, createResearchDrivingDriver, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, diagnoseRagAnswerFailure, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, groundClaimInText, hashKnowledgeBase, improveKnowledgeBase, initKnowledgeBase, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementActivationResult, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, optimizeKnowledgeBasePolicy, parseFrontmatter, parseKnowledgeWriteBlocks, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, restoreKnowledgeCandidateBaseline, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeResearchLoop, runRagKnowledgeImprovementLoop, runRagOptimization, runRetrievalImprovementLoop, runTwoAgentResearchLoop, runVerifiedResearchLoop, scoreKnowledgeBaseIndex, scoreRagAnswerArtifact, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, writeJson, writeKnowledgeIndex, writeSourceRegistry };