@tangle-network/agent-knowledge 3.0.1 → 3.2.0

package/dist/index.js

@@ -55,7 +55,7 @@ import {
   writeJsonDurableWithinRoot,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-2BJ5JR3L.js";
+} from "./chunk-EUAXSBMH.js";
 import {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
@@ -653,7 +653,7 @@ function createAdaptiveResearchDriver(options = {}) {
 
 // src/agent-candidate.ts
 import {
-  sha256DigestSchema
+  sha256DigestSchema as sha256DigestSchema2
 } from "@tangle-network/agent-interface";
 
 // src/kb-improvement.ts
@@ -666,6 +666,13 @@ import {
   contentHash,
   validateRunRecord
 } from "@tangle-network/agent-eval";
+import {
+  agentImprovementActivationResultSchema,
+  agentImprovementActivationSchema,
+  canonicalCandidateDigest,
+  omitTopLevelDigest,
+  sha256DigestSchema
+} from "@tangle-network/agent-interface";
 import { z } from "zod";
 
 // src/claim-grounding.ts
@@ -2022,6 +2029,20 @@ function assertNotAborted(signal) {
 var digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
 var runIdSchema = z.string().min(1).max(2048);
 var safePathSegmentSchema = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+var knowledgeImprovementMutationReceiptSchema = z.object({
+  target: z.enum(["candidate", "baseline"]),
+  beforeHash: digestSchema,
+  afterHash: digestSchema,
+  changed: z.boolean(),
+  transactionId: z.string().uuid().nullable(),
+  recovered: z.boolean()
+}).strict();
+var knowledgeImprovementActivationRecordSchema = z.object({
+  kind: z.literal("knowledge-improvement-activation-result"),
+  candidateId: safePathSegmentSchema,
+  mutation: knowledgeImprovementMutationReceiptSchema,
+  result: agentImprovementActivationResultSchema
+}).strict();
 var improvementStatusSchema = z.enum([
   "running",
   "candidate-ready",
@@ -2268,6 +2289,23 @@ async function loadKnowledgeImprovementState(root, runId) {
     throw error;
   }
 }
+async function loadKnowledgeImprovementActivationResult(options) {
+  assertExactCandidatePlatform();
+  const candidate = Object.freeze(KnowledgeImprovementCandidateRefSchema.parse(options.candidate));
+  const activation = verifyCanonicalKnowledgeActivation(options.activation);
+  const target = targetForKnowledgeActivation(activation);
+  assertKnowledgeActivationAuthority(activation, candidate, target, options.identity);
+  return withKnowledgeImprovementRun(options.root, candidate.runId, false, async (runDir) => {
+    const record = await loadKnowledgeActivationRecord(
+      runDir,
+      candidate,
+      activation,
+      target,
+      options.identity
+    );
+    return record?.result ?? null;
+  });
+}
 async function loadKnowledgeImprovementStateFromRun(root, runId, runDir) {
   const stateFile = await readRegularFileWithinRoot(runDir, "state.json");
   const raw = JSON.parse(stateFile.bytes.toString("utf8"));
@@ -2287,9 +2325,46 @@ function knowledgeImprovementCandidateRef(result) {
   if (!result.candidate) throw new Error("knowledge improvement result has no candidate");
   return candidateRefFor(result.runId, result.state, result.candidate);
 }
+async function withKnowledgeImprovementComparison(options, use) {
+  assertExactCandidatePlatform();
+  const reference = Object.freeze(KnowledgeImprovementCandidateRefSchema.parse(options.candidate));
+  return withKnowledgeImprovementRun(options.root, reference.runId, false, async (runDir) => {
+    const state = await loadKnowledgeImprovementStateFromRun(options.root, reference.runId, runDir);
+    return withMeasuredCandidateSnapshot(
+      options.root,
+      runDir,
+      state,
+      reference,
+      (resolved) => withBaselineSnapshot(
+        runDir,
+        reference.baseHash,
+        (baselineRoot) => withIsolatedKnowledgeCopy(
+          baselineRoot,
+          reference.baseHash,
+          "baseline",
+          (baseline) => withIsolatedKnowledgeCopy(
+            resolved.root,
+            reference.candidateHash,
+            "candidate",
+            (candidate) => use(
+              Object.freeze({
+                reference,
+                evaluation: immutableJsonValue(structuredClone(resolved.evidence.evaluation)),
+                baseline: Object.freeze({ root: baseline, hash: reference.baseHash }),
+                candidate: Object.freeze({ root: candidate, hash: reference.candidateHash })
+              })
+            )
+          )
+        )
+      )
+    );
+  });
+}
 async function withKnowledgeImprovementCandidate(options, use) {
   assertExactCandidatePlatform();
-  const candidateRef = KnowledgeImprovementCandidateRefSchema.parse(options.candidate);
+  const candidateRef = Object.freeze(
+    KnowledgeImprovementCandidateRefSchema.parse(options.candidate)
+  );
   return withKnowledgeImprovementRun(options.root, candidateRef.runId, false, async (runDir) => {
     const state = await loadKnowledgeImprovementStateFromRun(
       options.root,
@@ -2301,24 +2376,34 @@ async function withKnowledgeImprovementCandidate(options, use) {
       runDir,
       state,
       candidateRef,
-      (resolved) => withIsolatedCandidateCopy(
+      (resolved) => withIsolatedKnowledgeCopy(
         resolved.root,
         candidateRef.candidateHash,
-        (root) => use({
-          root,
-          candidate: candidateRef,
-          evaluation: resolved.evidence.evaluation
-        })
+        "candidate",
+        (root) => use(
+          Object.freeze({
+            root,
+            candidate: candidateRef,
+            evaluation: immutableJsonValue(structuredClone(resolved.evidence.evaluation))
+          })
+        )
       )
     );
   });
 }
 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)
   );
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const activation = options.activation ? resolveKnowledgeActivationPersistence(options.activation, candidateRef, target) : void 0;
   return withKnowledgeImprovementRun(options.root, candidateRef.runId, false, async (runDir) => {
     const lease = await acquireRunLease(runDir, {
       ownerId: options.ownerId ?? `pid-${process.pid}`,
@@ -2331,16 +2416,20 @@ 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,
+          activation
+        },
+        target
+      );
     } finally {
       await lease.release();
     }
@@ -2396,29 +2485,23 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
     if (state.status === "promoted" && !promotedCandidate) {
       throw new Error("promoted knowledge state has no promoted candidate");
     }
-    const resumablePromotion = state.candidates.find(
-      (candidate2) => (candidate2.status === "candidate-ready" || candidate2.status === "promoted") && candidate2.evidenceHash !== void 0 && candidate2.promotionPlanHash !== void 0
-    );
-    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)
-      } : void 0
-    });
+    await withKnowledgeMutation(options.root, () => 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,93 +2599,176 @@ 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)) {
+  if (!candidate || canonicalJson(candidateIdentityFor(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);
+  const recoveryOwner = input.activation ? `knowledge-improvement-activation:${input.activation.activation.digest}` : "knowledge-improvement-candidate-transition";
   return withKnowledgeMutation(
     input.root,
     async (mutationLock) => {
-      input.assertRunOwned();
+      const assertOwned = () => {
+        mutationLock.assertOwned();
+        input.assertRunOwned();
+      };
+      assertOwned();
       const transactionRoot = mutationLock.transactionRoot;
-      let pending = null;
+      const recovery = mutationLock.recovery?.purpose === purpose ? mutationLock.recovery : void 0;
+      const existingActivation = input.activation ? await loadKnowledgeActivationRecord(
+        runDir,
+        candidateRef,
+        input.activation.activation,
+        target,
+        input.activation.identity
+      ) : null;
+      if (existingActivation) {
+        if (recovery?.direction === "rollback") {
+          throw new Error("stored knowledge activation result conflicts with a pending rollback");
+        }
+        if (recovery) {
+          const recoveredHash = await hashKnowledgeBase(input.root);
+          if (recoveredHash !== existingActivation.mutation.afterHash) {
+            throw new Error("stored knowledge activation result does not match the recovered files");
+          }
+          await finishKnowledgeFileTransaction({
+            root: input.root,
+            transactionRoot,
+            transaction: recovery.transaction,
+            assertOwned
+          });
+        }
+        if (existingActivation.result.outcome.status === "conflict") {
+          const reason = candidateTransitionConflictReason(
+            target,
+            candidateRef,
+            existingActivation.mutation.afterHash
+          );
+          const blocked = await blockCandidateTransition(
+            input,
+            candidate,
+            target,
+            reason,
+            existingActivation.mutation.afterHash
+          );
+          return { ...blocked, activationResult: existingActivation.result };
+        }
+        return candidateTransitionResult(
+          input,
+          candidate,
+          target === "candidate" && state.status === "promoted",
+          false,
+          existingActivation.mutation,
+          existingActivation.result
+        );
+      }
+      if (recovery?.direction === "rollback") {
+        await finishKnowledgeFileTransaction({
+          root: input.root,
+          transactionRoot,
+          transaction: recovery.transaction,
+          assertOwned
+        });
+      }
+      const recovered = recovery?.direction === "apply" ? recovery : void 0;
+      let pending = input.activation && recovered ? recovered.transaction : null;
       const currentHash = await hashKnowledgeBase(input.root);
+      let transactionId = recovered?.transactionId ?? null;
+      if (recovered && currentHash !== desiredHash) {
+        throw new Error(`recovered knowledge ${action} does not match the approved target`);
+      }
       if (state.status === "promoted" && state.promotedCandidateId !== candidate.candidateId) {
         throw new Error(
           `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(
+        const reason = target === "candidate" ? `base changed before promotion: expected ${state.baseHash}, got ${currentHash}` : `knowledge changed before restore: expected ${candidateRef.candidateHash}, got ${currentHash}`;
+        const mutation2 = Object.freeze({
+          target,
+          beforeHash: currentHash,
+          afterHash: currentHash,
+          changed: false,
+          transactionId: null,
+          recovered: false
+        });
+        const activationResult2 = input.activation ? await persistKnowledgeActivationResult(
+          runDir,
+          candidateRef,
+          input.activation,
+          target,
+          mutation2
+        ) : void 0;
+        const blocked = await blockCandidateTransition(
           input,
           candidate,
-          `base changed before promotion: expected ${state.baseHash}, got ${currentHash}`
+          target,
+          reason,
+          currentHash
         );
+        return activationResult2 ? { ...blocked, activationResult: activationResult2 } : blocked;
       }
-      if (currentHash !== candidateRef.candidateHash) {
+      if (currentHash !== desiredHash && !pending) {
         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),
+              recoveryOwner,
+              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`);
         }
+        transactionId = pending.transactionId;
         try {
-          assertPromotionTransaction(pending, candidateRef);
+          assertCandidateTransitionTransaction(pending, candidateRef, target);
         } catch (error) {
           try {
             await rollbackKnowledgeFileTransaction({
               root: input.root,
               transactionRoot,
               transaction: pending,
-              beforeCommit() {
-                mutationLock.assertOwned();
-                input.assertRunOwned();
-              }
+              beforeCommit: assertOwned
             });
             await finishKnowledgeFileTransaction({
               root: input.root,
               transactionRoot,
               transaction: pending,
-              assertOwned() {
-                mutationLock.assertOwned();
-                input.assertRunOwned();
-              }
+              assertOwned
             });
           } 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;
@@ -2614,27 +2780,23 @@ async function promoteReadyCandidate(input) {
             root: input.root,
             transactionRoot,
             transaction: pending,
-            beforeCommit() {
-              mutationLock.assertOwned();
-              input.assertRunOwned();
-            }
+            beforeCommit: assertOwned
           });
         }
-        mutationLock.assertOwned();
-        input.assertRunOwned();
-        if (await hashKnowledgeBase(input.root) !== candidateRef.candidateHash) {
-          throw new Error("promoted knowledge content does not match the approved candidate");
+        assertOwned();
+        if (await hashKnowledgeBase(input.root) !== desiredHash) {
+          throw new Error(`knowledge ${action} content does not match the approved target`);
         }
         await writeKnowledgeIndex(input.root);
       } catch (error) {
         if (!pending) throw error;
+        if (recovered && input.activation) throw error;
         try {
-          mutationLock.assertOwned();
-          input.assertRunOwned();
+          assertOwned();
         } 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 {
@@ -2642,79 +2804,290 @@ async function promoteReadyCandidate(input) {
             root: input.root,
             transactionRoot,
             transaction: pending,
-            beforeCommit() {
-              mutationLock.assertOwned();
-              input.assertRunOwned();
-            }
+            beforeCommit: assertOwned
           });
           await finishKnowledgeFileTransaction({
             root: input.root,
             transactionRoot,
             transaction: pending,
-            assertOwned() {
-              mutationLock.assertOwned();
-              input.assertRunOwned();
-            }
+            assertOwned
           });
           await writeKnowledgeIndex(input.root);
         } 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);
+      let finalHash = await hashKnowledgeBase(input.root);
+      if (finalHash !== desiredHash) {
+        throw new Error(`knowledge ${action} changed before its result was returned`);
+      }
+      const mutation = Object.freeze({
+        target,
+        beforeHash: transactionId ? sourceKnowledgeHash(candidateRef, target) : currentHash,
+        afterHash: finalHash,
+        changed: transactionId !== null,
+        transactionId,
+        recovered: recovered !== void 0
+      });
+      const activationResult = input.activation ? await persistKnowledgeActivationResult(
+        runDir,
+        candidateRef,
+        input.activation,
+        target,
+        mutation
+      ) : void 0;
+      if (await hashKnowledgeBase(input.root) !== finalHash) {
+        throw new Error(`knowledge ${action} changed while its result was persisted`);
+      }
       if (pending) {
         await finishKnowledgeFileTransaction({
           root: input.root,
           transactionRoot,
           transaction: pending,
-          assertOwned() {
-            mutationLock.assertOwned();
-            input.assertRunOwned();
-          }
+          assertOwned
         });
       }
-      return promotionResult(input, candidate, true, false);
+      finalHash = await hashKnowledgeBase(input.root);
+      if (finalHash !== desiredHash) {
+        throw new Error(`knowledge ${action} changed before its result was returned`);
+      }
+      return candidateTransitionResult(
+        input,
+        candidate,
+        target === "candidate",
+        false,
+        mutation,
+        activationResult
+      );
     },
     {
       staleMs: input.leaseTtlMs,
       resumeTransaction: {
         purpose,
-        validate: (transaction) => assertPromotionTransaction(transaction, candidateRef)
+        recoveryOwner,
+        validate: (transaction) => assertCandidateTransitionTransaction(transaction, candidateRef, target),
+        deferFinish: input.activation !== void 0
       }
     }
   );
 }
-async function blockPromotion(input, candidate, reason) {
+function candidateTransitionConflictReason(target, candidate, currentHash) {
+  return target === "candidate" ? `base changed before promotion: expected ${candidate.baseHash}, got ${currentHash}` : `knowledge changed before restore: expected ${candidate.candidateHash}, got ${currentHash}`;
+}
+async function blockCandidateTransition(input, candidate, target, reason, currentHash) {
+  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, {
+    target,
+    beforeHash: currentHash,
+    afterHash: currentHash,
+    changed: false,
+    transactionId: null,
+    recovered: false
+  });
 }
-function promotionResult(input, candidate, promoted, blocked) {
+function candidateTransitionResult(input, candidate, promoted, blocked, mutation, activationResult) {
   return {
     runId: input.candidateRef.runId,
     state: input.state,
     candidate,
     ...input.lifecycle ? { lifecycle: input.lifecycle } : {},
+    mutation,
+    ...activationResult ? { activationResult } : {},
     promoted,
     blocked
   };
 }
+function sourceKnowledgeHash(candidate, target) {
+  return target === "candidate" ? candidate.baseHash : candidate.candidateHash;
+}
+function targetForKnowledgeActivation(activation) {
+  return activation.intent === "activate-candidate" ? "candidate" : "baseline";
+}
+function resolveKnowledgeActivationPersistence(input, candidate, target) {
+  const activation = verifyCanonicalKnowledgeActivation(input.activation);
+  assertKnowledgeActivationAuthority(activation, candidate, target, input.identity);
+  const attemptedAt = z.iso.datetime().parse(input.attemptedAt);
+  if (Date.parse(attemptedAt) < Date.parse(activation.authorizedAt) || Date.parse(attemptedAt) >= Date.parse(activation.expiresAt)) {
+    throw new Error("knowledge activation attempt is outside its authorization window");
+  }
+  return Object.freeze({
+    activation,
+    attemptedAt,
+    identity: input.identity,
+    createResult: input.createResult
+  });
+}
+function assertKnowledgeActivationAuthority(activation, candidate, target, identity) {
+  if (!identity.trim()) throw new Error("knowledge activation identity is required");
+  if (targetForKnowledgeActivation(activation) !== target) {
+    throw new Error("knowledge activation intent does not match the requested transition");
+  }
+  if (activation.targets.length !== 1) {
+    throw new Error("knowledge activation requires exactly one target");
+  }
+  const authorizedTarget = activation.targets[0];
+  if (authorizedTarget.surface !== "knowledge" || authorizedTarget.identity !== identity) {
+    throw new Error("knowledge activation target does not match this knowledge base");
+  }
+  if (authorizedTarget.expectedBaseDigest !== prefixedKnowledgeDigest(sourceKnowledgeHash(candidate, target))) {
+    throw new Error("knowledge activation does not authorize the measured source state");
+  }
+}
+function verifyCanonicalKnowledgeActivation(value) {
+  const activation = agentImprovementActivationSchema.parse(value);
+  if (canonicalCandidateDigest(omitTopLevelDigest(activation)) !== activation.digest) {
+    throw new Error("knowledge activation digest does not match its canonical content");
+  }
+  return immutableJsonValue(structuredClone(activation));
+}
+function verifyCanonicalKnowledgeActivationResult(value) {
+  const result = agentImprovementActivationResultSchema.parse(value);
+  if (canonicalCandidateDigest(omitTopLevelDigest(result)) !== result.digest) {
+    throw new Error("knowledge activation result digest does not match its canonical content");
+  }
+  return immutableJsonValue(structuredClone(result));
+}
+async function persistKnowledgeActivationResult(runDir, candidate, persistence, target, mutation) {
+  const result = assertKnowledgeActivationResult(
+    persistence.activation,
+    candidate,
+    target,
+    persistence.identity,
+    mutation,
+    await persistence.createResult(Object.freeze({ ...mutation })),
+    persistence.attemptedAt
+  );
+  const record = knowledgeImprovementActivationRecordSchema.parse({
+    kind: "knowledge-improvement-activation-result",
+    candidateId: candidate.candidateId,
+    mutation,
+    result
+  });
+  const existing = await loadKnowledgeActivationRecord(
+    runDir,
+    candidate,
+    persistence.activation,
+    target,
+    persistence.identity
+  );
+  if (existing) {
+    if (canonicalJson(existing) !== canonicalJson(record)) {
+      throw new Error("knowledge activation result identity conflicts with durable content");
+    }
+    return existing.result;
+  }
+  await writeJsonDurableWithinRoot(
+    runDir,
+    knowledgeActivationResultPath(persistence.activation.digest),
+    record
+  );
+  const stored = await loadKnowledgeActivationRecord(
+    runDir,
+    candidate,
+    persistence.activation,
+    target,
+    persistence.identity
+  );
+  if (!stored || canonicalJson(stored) !== canonicalJson(record)) {
+    throw new Error("knowledge activation result was not durably persisted");
+  }
+  return stored.result;
+}
+async function loadKnowledgeActivationRecord(runDir, candidate, activation, target, identity) {
+  let raw;
+  try {
+    const file = await readRegularFileWithinRoot(
+      runDir,
+      knowledgeActivationResultPath(activation.digest)
+    );
+    raw = JSON.parse(file.bytes.toString("utf8"));
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+  const record = knowledgeImprovementActivationRecordSchema.parse(raw);
+  if (record.candidateId !== candidate.candidateId) {
+    throw new Error("knowledge activation result belongs to another candidate");
+  }
+  const result = assertKnowledgeActivationResult(
+    activation,
+    candidate,
+    target,
+    identity,
+    record.mutation,
+    record.result
+  );
+  return immutableJsonValue({ ...record, result });
+}
+function assertKnowledgeActivationResult(activation, candidate, target, identity, mutationInput, resultInput, attemptedAt) {
+  assertKnowledgeActivationAuthority(activation, candidate, target, identity);
+  const mutation = knowledgeImprovementMutationReceiptSchema.parse(mutationInput);
+  const result = verifyCanonicalKnowledgeActivationResult(resultInput);
+  if (result.idempotencyKey !== activation.digest || attemptedAt !== void 0 && result.attemptedAt !== attemptedAt || Date.parse(result.attemptedAt) < Date.parse(activation.authorizedAt) || Date.parse(result.attemptedAt) >= Date.parse(activation.expiresAt) || mutation.target !== target || mutation.changed !== (mutation.beforeHash !== mutation.afterHash) || !mutation.changed && (mutation.transactionId !== null || mutation.recovered)) {
+    throw new Error("knowledge activation result does not bind its authorized mutation");
+  }
+  const sourceDigest = prefixedKnowledgeDigest(sourceKnowledgeHash(candidate, target));
+  const desiredDigest = prefixedKnowledgeDigest(
+    target === "candidate" ? candidate.candidateHash : candidate.baseHash
+  );
+  const beforeDigest = prefixedKnowledgeDigest(mutation.beforeHash);
+  const afterDigest = prefixedKnowledgeDigest(mutation.afterHash);
+  const outcome = result.outcome;
+  if (mutation.changed) {
+    if (mutation.transactionId === null || beforeDigest !== sourceDigest || afterDigest !== desiredDigest || outcome.status !== "applied" || outcome.transactionId !== mutation.transactionId || outcome.targets.length !== 1 || outcome.targets[0]?.surface !== "knowledge" || outcome.targets[0]?.identity !== identity || outcome.targets[0]?.beforeDigest !== beforeDigest || outcome.targets[0]?.afterDigest !== afterDigest) {
+      throw new Error("knowledge activation result does not prove the applied transaction");
+    }
+    return result;
+  }
+  const expectedStatus = afterDigest === desiredDigest ? "already-applied" : "conflict";
+  if (afterDigest === sourceDigest || outcome.status !== expectedStatus || outcome.targets.length !== 1 || outcome.targets[0]?.surface !== "knowledge" || outcome.targets[0]?.identity !== identity || outcome.targets[0]?.currentDigest !== afterDigest) {
+    throw new Error("knowledge activation result does not prove the observed target state");
+  }
+  return result;
+}
+function knowledgeActivationResultPath(digest) {
+  const parsed = sha256DigestSchema.parse(digest);
+  return `activation-results/${parsed.slice("sha256:".length)}.json`;
+}
+function prefixedKnowledgeDigest(hash) {
+  return sha256DigestSchema.parse(`sha256:${digestSchema.parse(hash)}`);
+}
+function immutableJsonValue(value) {
+  if (value === null || typeof value !== "object") return value;
+  for (const child of Object.values(value)) immutableJsonValue(child);
+  return Object.freeze(value);
+}
 function candidateRefFor(runId, state, candidate) {
+  if (candidate.status !== "candidate-ready" && candidate.status !== "promoted") {
+    throw new Error(`knowledge candidate '${candidate.candidateId}' is not ready`);
+  }
+  return candidateIdentityFor(runId, state, candidate);
+}
+function candidateIdentityFor(runId, state, candidate) {
   if (!candidate.candidateHash) {
     throw new Error(`knowledge candidate '${candidate.candidateId}' has no content hash`);
   }
@@ -2724,9 +3097,6 @@ function candidateRefFor(runId, state, candidate) {
   if (!candidate.promotionPlanHash) {
     throw new Error(`knowledge candidate '${candidate.candidateId}' has no promotion plan hash`);
   }
-  if (candidate.status !== "candidate-ready" && candidate.status !== "promoted") {
-    throw new Error(`knowledge candidate '${candidate.candidateId}' is not ready`);
-  }
   return Object.freeze({
     kind: "knowledge-improvement-candidate",
     runId,
@@ -2766,17 +3136,17 @@ async function withMeasuredCandidateSnapshot(liveRoot, runDir, state, candidateR
     return result;
   });
 }
-async function withIsolatedCandidateCopy(sourceRoot, expectedHash, use) {
-  const isolationRoot = await mkdtemp(join(tmpdir(), "agent-knowledge-candidate-"));
-  const candidateRoot = join(isolationRoot, "candidate");
+async function withIsolatedKnowledgeCopy(sourceRoot, expectedHash, target, use) {
+  const isolationRoot = await mkdtemp(join(tmpdir(), "agent-knowledge-snapshot-"));
+  const snapshotRoot = join(isolationRoot, "snapshot");
   try {
-    await copyKnowledgeWorkspace(sourceRoot, candidateRoot);
-    if (await hashKnowledgeBase(candidateRoot) !== expectedHash) {
-      throw new Error("isolated knowledge candidate does not match its approved content");
+    await copyKnowledgeWorkspace(sourceRoot, snapshotRoot);
+    if (await hashKnowledgeBase(snapshotRoot) !== expectedHash) {
+      throw new Error(`isolated knowledge ${target} does not match its measured content`);
     }
-    const result = await use(candidateRoot);
-    if (await hashKnowledgeBase(candidateRoot) !== expectedHash) {
-      throw new Error("knowledge candidate snapshot changed during use");
+    const result = await use(snapshotRoot);
+    if (await hashKnowledgeBase(snapshotRoot) !== expectedHash) {
+      throw new Error(`knowledge ${target} snapshot changed during use`);
     }
     return result;
   } finally {
@@ -3033,7 +3403,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 +3613,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 +3640,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 +3685,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;
   }
@@ -3501,10 +3886,10 @@ function fromAgentCandidateKnowledgeRef(candidate) {
   });
 }
 function prefixedDigest(value) {
-  return sha256DigestSchema.parse(`sha256:${value}`);
+  return sha256DigestSchema2.parse(`sha256:${value}`);
 }
 function rawDigest(value) {
-  return sha256DigestSchema.parse(value).slice("sha256:".length);
+  return sha256DigestSchema2.parse(value).slice("sha256:".length);
 }
 
 // src/changes.ts
@@ -5933,6 +6318,7 @@ export {
   layoutFor,
   lensDistribution,
   lintKnowledgeIndex,
+  loadKnowledgeImprovementActivationResult,
   loadKnowledgeImprovementEvents,
   loadKnowledgeImprovementState,
   loadKnowledgePages,
@@ -5961,6 +6347,7 @@ export {
   resetRetrievalHoldoutRegistry,
   respondToIndustryMemoryBenchmarkSmokeCase,
   respondToIndustryRagBenchmarkSmokeCase,
+  restoreKnowledgeCandidateBaseline,
   retrievalConfigFromSurface,
   retrievalConfigSurface,
   retrievalHoldoutConfigHash,
@@ -6002,6 +6389,7 @@ export {
   validateKnowledgeIndex,
   withCitedClaim,
   withKnowledgeImprovementCandidate,
+  withKnowledgeImprovementComparison,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry