@tangle-network/agent-knowledge 3.0.0 → 3.1.0

package/dist/index.d.ts

@@ -1186,6 +1186,7 @@ interface PromoteKnowledgeCandidateOptions {
     now?: () => Date;
     onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
 }
+type RestoreKnowledgeCandidateBaselineOptions = PromoteKnowledgeCandidateOptions;
 interface UseKnowledgeImprovementCandidateOptions {
     root: string;
     candidate: KnowledgeImprovementCandidateRef;
@@ -1246,6 +1247,8 @@ declare function knowledgeImprovementCandidateRef(result: Pick<KnowledgeImprovem
 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<KnowledgeImprovementResult>;
+/** Restore the frozen baseline paired with one previously measured candidate. */
+declare function restoreKnowledgeCandidateBaseline(options: RestoreKnowledgeCandidateBaselineOptions): Promise<KnowledgeImprovementResult>;
 declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
 interface KnowledgeImprovementEvent extends Record<string, unknown> {
     at: string;
@@ -2664,4 +2667,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 KnowledgeImprovementCandidateRecord, type KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, type KnowledgeImprovementStatus, 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 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 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, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, 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, 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 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 KnowledgeImprovementCandidateRecord, type KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, type KnowledgeImprovementStatus, 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 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 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, 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, writeJson, writeKnowledgeIndex, writeSourceRegistry };

package/dist/index.js

@@ -2314,6 +2314,12 @@ async function withKnowledgeImprovementCandidate(options, use) {
   });
 }
 async function promoteKnowledgeCandidate(options) {
+  return transitionKnowledgeCandidate(options, "candidate");
+}
+async function restoreKnowledgeCandidateBaseline(options) {
+  return transitionKnowledgeCandidate(options, "baseline");
+}
+async function transitionKnowledgeCandidate(options, target) {
   assertExactCandidatePlatform();
   const candidateRef = Object.freeze(
     KnowledgeImprovementCandidateRefSchema.parse(options.candidate)
@@ -2331,16 +2337,19 @@ async function promoteKnowledgeCandidate(options) {
         candidateRef.runId,
         runDir
       );
-      return await promoteReadyCandidate({
-        root: options.root,
-        runDir,
-        state,
-        candidateRef,
-        leaseTtlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
-        assertRunOwned: lease.assertOwned,
-        now,
-        onState: options.onState
-      });
+      return await applyKnowledgeCandidateTarget(
+        {
+          root: options.root,
+          runDir,
+          state,
+          candidateRef,
+          leaseTtlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
+          assertRunOwned: lease.assertOwned,
+          now,
+          onState: options.onState
+        },
+        target
+      );
     } finally {
       await lease.release();
     }
@@ -2402,23 +2411,26 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
     const resumableCandidateRef = resumablePromotion ? candidateRefFor(runId, state, resumablePromotion) : void 0;
     await withKnowledgeMutation(options.root, () => void 0, {
       resumeTransaction: resumableCandidateRef ? {
-        purpose: promotionTransactionPurpose(resumableCandidateRef),
-        validate: (transaction) => assertPromotionTransaction(transaction, resumableCandidateRef)
+        purpose: knowledgeCandidateTransitionPurpose(resumableCandidateRef, "candidate"),
+        validate: (transaction) => assertCandidateTransitionTransaction(transaction, resumableCandidateRef, "candidate")
       } : void 0
     });
     await ensureBaselineSnapshot(runDir, options.root, state.baseHash);
     if (state.status === "promoted") {
       const promoted = promotedCandidate;
-      return await promoteReadyCandidate({
-        root: options.root,
-        runDir,
-        state,
-        candidateRef: candidateRefFor(runId, state, promoted),
-        leaseTtlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
-        assertRunOwned: lease.assertOwned,
-        now,
-        onState: options.onState
-      });
+      return await applyKnowledgeCandidateTarget(
+        {
+          root: options.root,
+          runDir,
+          state,
+          candidateRef: candidateRefFor(runId, state, promoted),
+          leaseTtlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
+          assertRunOwned: lease.assertOwned,
+          now,
+          onState: options.onState
+        },
+        "candidate"
+      );
     }
     if (state.status === "blocked") {
       return { runId, state, promoted: false, blocked: true };
@@ -2516,14 +2528,16 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
     await lease.release();
   }
 }
-async function promoteReadyCandidate(input) {
+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 || canonicalJson(candidateRefFor(candidateRef.runId, state, candidate)) !== canonicalJson(candidateRef)) {
     throw new Error("knowledge candidate approval does not match the measured candidate");
   }
-  const purpose = promotionTransactionPurpose(candidateRef);
+  const action = target === "candidate" ? "promotion" : "restore";
+  const desiredHash = target === "candidate" ? candidateRef.candidateHash : candidateRef.baseHash;
+  const purpose = knowledgeCandidateTransitionPurpose(candidateRef, target);
   return withKnowledgeMutation(
     input.root,
     async (mutationLock) => {
@@ -2536,49 +2550,46 @@ async function promoteReadyCandidate(input) {
           `knowledge run already promoted '${state.promotedCandidateId ?? "unknown"}'`
         );
       }
-      if (state.status === "promoted" && currentHash !== candidateRef.candidateHash) {
+      if (target === "candidate" && state.status === "promoted" && currentHash !== candidateRef.candidateHash) {
         throw new Error(
           `promoted knowledge base changed: expected ${candidateRef.candidateHash}, got ${currentHash}`
         );
       }
       if (state.status !== "promoted" && state.status !== "candidate-ready") {
         throw new Error(
-          `knowledge candidate is not ready for promotion: run=${state.status}, candidate=${candidate.status}`
+          `knowledge candidate is not ready for ${action}: run=${state.status}, candidate=${candidate.status}`
         );
       }
       if (currentHash !== state.baseHash && currentHash !== candidateRef.candidateHash) {
-        return await blockPromotion(
-          input,
-          candidate,
-          `base changed before promotion: expected ${state.baseHash}, got ${currentHash}`
-        );
+        const reason = target === "candidate" ? `base changed before promotion: expected ${state.baseHash}, got ${currentHash}` : `knowledge changed before restore: expected ${candidateRef.candidateHash}, got ${currentHash}`;
+        return await blockCandidateTransition(input, candidate, target, reason);
       }
-      if (currentHash !== candidateRef.candidateHash) {
+      if (currentHash !== desiredHash) {
         pending = await withMeasuredCandidateSnapshot(
           input.root,
           runDir,
           state,
           candidateRef,
           (resolved) => withBaselineSnapshot(runDir, state.baseHash, async (baselineRoot) => {
-            const plan = await promotionPlanEntries(baselineRoot, resolved.root);
-            if (knowledgeFileTransactionPlanHash(plan) !== candidateRef.promotionPlanHash) {
-              throw new Error("knowledge candidate promotion plan changed after approval");
-            }
+            const sourceRoot = target === "candidate" ? baselineRoot : resolved.root;
+            const targetRoot = target === "candidate" ? resolved.root : baselineRoot;
+            const plan = await knowledgeFilePlanEntries(sourceRoot, targetRoot);
+            assertCandidateTransitionPlan(plan, candidateRef, target);
             return prepareKnowledgeFileTransaction({
               root: input.root,
               transactionRoot,
               purpose,
-              mutations: await promotionMutations(resolved.root, plan),
+              mutations: await knowledgePlanMutations(targetRoot, plan),
               includeUnchanged: true,
               now: input.now
             });
           })
         );
         if (!pending) {
-          throw new Error("knowledge promotion plan unexpectedly contained no file changes");
+          throw new Error(`knowledge ${action} plan unexpectedly contained no file changes`);
         }
         try {
-          assertPromotionTransaction(pending, candidateRef);
+          assertCandidateTransitionTransaction(pending, candidateRef, target);
         } catch (error) {
           try {
             await rollbackKnowledgeFileTransaction({
@@ -2602,7 +2613,7 @@ async function promoteReadyCandidate(input) {
           } catch (cleanupError) {
             throw new AggregateError(
               [error, cleanupError],
-              "invalid knowledge promotion transaction could not be removed"
+              `invalid knowledge ${action} transaction could not be removed`
             );
           }
           throw error;
@@ -2622,8 +2633,8 @@ async function promoteReadyCandidate(input) {
         }
         mutationLock.assertOwned();
         input.assertRunOwned();
-        if (await hashKnowledgeBase(input.root) !== candidateRef.candidateHash) {
-          throw new Error("promoted knowledge content does not match the approved candidate");
+        if (await hashKnowledgeBase(input.root) !== desiredHash) {
+          throw new Error(`knowledge ${action} content does not match the approved target`);
         }
         await writeKnowledgeIndex(input.root);
       } catch (error) {
@@ -2634,7 +2645,7 @@ async function promoteReadyCandidate(input) {
         } catch (ownershipError) {
           throw new AggregateError(
             [error, ownershipError],
-            "knowledge promotion lost its lock and left the transaction pending"
+            `knowledge ${action} lost its lock and left the transaction pending`
           );
         }
         try {
@@ -2660,18 +2671,20 @@ async function promoteReadyCandidate(input) {
         } catch (rollbackError) {
           throw new AggregateError(
             [error, rollbackError],
-            "knowledge promotion failed and could not restore the previous files"
+            `knowledge ${action} failed and could not restore the previous files`
           );
         }
         throw error;
       }
-      candidate.status = "promoted";
+      candidate.status = target === "candidate" ? "promoted" : "candidate-ready";
       candidate.updatedAt = input.now().toISOString();
-      state.status = "promoted";
-      state.promotedCandidateId = candidate.candidateId;
+      state.status = candidate.status;
+      if (target === "candidate") state.promotedCandidateId = candidate.candidateId;
+      else delete state.promotedCandidateId;
+      delete state.blockedReason;
       state.updatedAt = input.now().toISOString();
       await saveState(runDir, state, input.onState);
-      await ensurePromotionEvent(runDir, candidateRef);
+      await ensureCandidateTransitionEvent(runDir, candidateRef, target);
       if (pending) {
         await finishKnowledgeFileTransaction({
           root: input.root,
@@ -2683,28 +2696,33 @@ async function promoteReadyCandidate(input) {
           }
         });
       }
-      return promotionResult(input, candidate, true, false);
+      return candidateTransitionResult(input, candidate, target === "candidate", false);
     },
     {
       staleMs: input.leaseTtlMs,
       resumeTransaction: {
         purpose,
-        validate: (transaction) => assertPromotionTransaction(transaction, candidateRef)
+        validate: (transaction) => assertCandidateTransitionTransaction(transaction, candidateRef, target)
       }
     }
   );
 }
-async function blockPromotion(input, candidate, reason) {
+async function blockCandidateTransition(input, candidate, target, reason) {
+  if (input.state.status === "promoted") {
+    candidate.status = "blocked";
+    candidate.updatedAt = input.now().toISOString();
+    delete input.state.promotedCandidateId;
+  }
   await blockRun(input.runDir, input.state, reason, input.onState, input.now);
   await appendLedger(input.runDir, {
-    type: "promotion.blocked",
+    type: target === "candidate" ? "promotion.blocked" : "restore.blocked",
     runId: input.candidateRef.runId,
     candidateId: candidate.candidateId,
     reason
   });
-  return promotionResult(input, candidate, false, true);
+  return candidateTransitionResult(input, candidate, false, true);
 }
-function promotionResult(input, candidate, promoted, blocked) {
+function candidateTransitionResult(input, candidate, promoted, blocked) {
   return {
     runId: input.candidateRef.runId,
     state: input.state,
@@ -3033,7 +3051,7 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
     }
     candidate.candidateHash = candidateHash;
     candidate.promotionPlanHash = knowledgeFileTransactionPlanHash(
-      await promotionPlanEntries(baselineRoot, snapshot.root)
+      await knowledgeFilePlanEntries(baselineRoot, snapshot.root)
     );
     const evidence = KnowledgeImprovementEvidenceSchema.parse(
       JSON.parse(
@@ -3243,13 +3261,14 @@ async function copyKnowledgeWorkspace(sourceRoot, targetRoot) {
   );
   await writeKnowledgeIndex(targetRoot);
 }
-function promotionTransactionPurpose(candidate) {
-  return `knowledge-promotion:${contentHash(candidate)}`;
+function knowledgeCandidateTransitionPurpose(candidate, target) {
+  const action = target === "candidate" ? "promotion" : "restore";
+  return `knowledge-${action}:${contentHash(candidate)}`;
 }
-async function promotionPlanEntries(baselineRoot, candidateRoot) {
+async function knowledgeFilePlanEntries(sourceRoot, targetRoot) {
   const [before, after] = await Promise.all([
-    knowledgeHashEntries(baselineRoot),
-    knowledgeHashEntries(candidateRoot)
+    knowledgeHashEntries(sourceRoot),
+    knowledgeHashEntries(targetRoot)
   ]);
   const beforeByPath = new Map(before.map((entry) => [entry.path, entry]));
   const afterByPath = new Map(after.map((entry) => [entry.path, entry]));
@@ -3269,31 +3288,44 @@ async function promotionPlanEntries(baselineRoot, candidateRoot) {
     };
   });
 }
-async function promotionMutations(candidateRoot, plan) {
+async function knowledgePlanMutations(targetRoot, plan) {
   return Promise.all(
     plan.map(async (entry) => {
       if (entry.afterHash === null) return { path: entry.path, content: null };
-      const file = await readRegularFileWithinRoot(candidateRoot, entry.path);
+      const file = await readRegularFileWithinRoot(targetRoot, entry.path);
       const actualHash = createHash("sha256").update(file.bytes).digest("hex");
       if (actualHash !== entry.afterHash || file.mode !== entry.afterMode) {
-        throw new Error(`knowledge candidate file changed before promotion: ${entry.path}`);
+        throw new Error(`knowledge target file changed before activation: ${entry.path}`);
       }
       return { path: entry.path, content: file.bytes, mode: file.mode };
     })
   );
 }
-function assertPromotionTransaction(transaction, candidate) {
-  const actualPlanHash = knowledgeFileTransactionPlanHash(transaction.entries);
+function assertCandidateTransitionPlan(plan, candidate, target) {
+  const approvedDirection = target === "candidate" ? plan : reverseKnowledgeFilePlan(plan);
+  const actualPlanHash = knowledgeFileTransactionPlanHash(approvedDirection);
   if (actualPlanHash !== candidate.promotionPlanHash) {
     throw new Error(
-      `knowledge promotion plan changed after approval: expected ${candidate.promotionPlanHash}, got ${actualPlanHash}`
+      `knowledge candidate plan changed after approval: expected ${candidate.promotionPlanHash}, got ${actualPlanHash}`
     );
   }
 }
-async function ensurePromotionEvent(runDir, candidateRef) {
-  if (await hasPromotionEvent(runDir, candidateRef)) return;
+function assertCandidateTransitionTransaction(transaction, candidate, target) {
+  assertCandidateTransitionPlan(transaction.entries, candidate, target);
+}
+function reverseKnowledgeFilePlan(plan) {
+  return plan.map((entry) => ({
+    path: entry.path,
+    beforeHash: entry.afterHash,
+    afterHash: entry.beforeHash,
+    ...entry.afterMode === void 0 ? {} : { beforeMode: entry.afterMode },
+    ...entry.beforeMode === void 0 ? {} : { afterMode: entry.beforeMode }
+  }));
+}
+async function ensureCandidateTransitionEvent(runDir, candidateRef, target) {
+  if (await hasCandidateTransitionEvent(runDir, candidateRef, target)) return;
   await appendLedger(runDir, {
-    type: "candidate.promoted",
+    type: target === "candidate" ? "candidate.promoted" : "candidate.restored",
     runId: candidateRef.runId,
     candidateId: candidateRef.candidateId,
     candidateHash: candidateRef.candidateHash,
@@ -3301,12 +3333,13 @@ async function ensurePromotionEvent(runDir, candidateRef) {
     promotionPlanHash: candidateRef.promotionPlanHash
   });
 }
-async function hasPromotionEvent(runDir, candidateRef) {
+async function hasCandidateTransitionEvent(runDir, candidateRef, target) {
+  const eventType = target === "candidate" ? "candidate.promoted" : "candidate.restored";
   let matched = false;
   for (const row of await loadKnowledgeImprovementEventsFromRun(runDir)) {
-    if (row.type !== "candidate.promoted" || row.candidateId !== candidateRef.candidateId) continue;
+    if (row.type !== eventType || row.candidateId !== candidateRef.candidateId) continue;
     if (row.runId !== candidateRef.runId || row.candidateHash !== candidateRef.candidateHash || row.evidenceHash !== candidateRef.evidenceHash || row.promotionPlanHash !== candidateRef.promotionPlanHash) {
-      throw new Error("persisted knowledge promotion event conflicts with the approved candidate");
+      throw new Error("persisted knowledge activation event conflicts with the approved candidate");
     }
     matched = true;
   }
@@ -5961,6 +5994,7 @@ export {
   resetRetrievalHoldoutRegistry,
   respondToIndustryMemoryBenchmarkSmokeCase,
   respondToIndustryRagBenchmarkSmokeCase,
+  restoreKnowledgeCandidateBaseline,
   retrievalConfigFromSurface,
   retrievalConfigSurface,
   retrievalHoldoutConfigHash,