@tangle-network/agent-knowledge 3.1.0 → 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,14 +2376,17 @@ 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))
+          })
+        )
       )
     );
   });
@@ -2325,6 +2403,7 @@ async function transitionKnowledgeCandidate(options, target) {
     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}`,
@@ -2346,7 +2425,8 @@ async function transitionKnowledgeCandidate(options, target) {
           leaseTtlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
           assertRunOwned: lease.assertOwned,
           now,
-          onState: options.onState
+          onState: options.onState,
+          activation
         },
         target
       );
@@ -2405,16 +2485,7 @@ 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: knowledgeCandidateTransitionPurpose(resumableCandidateRef, "candidate"),
-        validate: (transaction) => assertCandidateTransitionTransaction(transaction, resumableCandidateRef, "candidate")
-      } : void 0
-    });
+    await withKnowledgeMutation(options.root, () => void 0);
     await ensureBaselineSnapshot(runDir, options.root, state.baseHash);
     if (state.status === "promoted") {
       const promoted = promotedCandidate;
@@ -2532,19 +2603,85 @@ 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 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"}'`
@@ -2562,9 +2699,31 @@ async function applyKnowledgeCandidateTarget(input, target) {
       }
       if (currentHash !== state.baseHash && currentHash !== candidateRef.candidateHash) {
         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);
+        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,
+          target,
+          reason,
+          currentHash
+        );
+        return activationResult2 ? { ...blocked, activationResult: activationResult2 } : blocked;
       }
-      if (currentHash !== desiredHash) {
+      if (currentHash !== desiredHash && !pending) {
         pending = await withMeasuredCandidateSnapshot(
           input.root,
           runDir,
@@ -2579,6 +2738,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
               root: input.root,
               transactionRoot,
               purpose,
+              recoveryOwner,
               mutations: await knowledgePlanMutations(targetRoot, plan),
               includeUnchanged: true,
               now: input.now
@@ -2588,6 +2748,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
         if (!pending) {
           throw new Error(`knowledge ${action} plan unexpectedly contained no file changes`);
         }
+        transactionId = pending.transactionId;
         try {
           assertCandidateTransitionTransaction(pending, candidateRef, target);
         } catch (error) {
@@ -2596,19 +2757,13 @@ async function applyKnowledgeCandidateTarget(input, target) {
               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(
@@ -2625,23 +2780,19 @@ async function applyKnowledgeCandidateTarget(input, target) {
             root: input.root,
             transactionRoot,
             transaction: pending,
-            beforeCommit() {
-              mutationLock.assertOwned();
-              input.assertRunOwned();
-            }
+            beforeCommit: assertOwned
           });
         }
-        mutationLock.assertOwned();
-        input.assertRunOwned();
+        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],
@@ -2653,19 +2804,13 @@ async function applyKnowledgeCandidateTarget(input, target) {
             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) {
@@ -2685,29 +2830,64 @@ async function applyKnowledgeCandidateTarget(input, target) {
       state.updatedAt = input.now().toISOString();
       await saveState(runDir, state, input.onState);
       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 candidateTransitionResult(input, candidate, target === "candidate", 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) => assertCandidateTransitionTransaction(transaction, candidateRef, target)
+        recoveryOwner,
+        validate: (transaction) => assertCandidateTransitionTransaction(transaction, candidateRef, target),
+        deferFinish: input.activation !== void 0
       }
     }
   );
 }
-async function blockCandidateTransition(input, candidate, target, 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();
@@ -2720,19 +2900,194 @@ async function blockCandidateTransition(input, candidate, target, reason) {
     candidateId: candidate.candidateId,
     reason
   });
-  return candidateTransitionResult(input, candidate, false, true);
+  return candidateTransitionResult(input, candidate, false, true, {
+    target,
+    beforeHash: currentHash,
+    afterHash: currentHash,
+    changed: false,
+    transactionId: null,
+    recovered: false
+  });
 }
-function candidateTransitionResult(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`);
   }
@@ -2742,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,
@@ -2784,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 {
@@ -3534,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
@@ -5966,6 +6318,7 @@ export {
   layoutFor,
   lensDistribution,
   lintKnowledgeIndex,
+  loadKnowledgeImprovementActivationResult,
   loadKnowledgeImprovementEvents,
   loadKnowledgeImprovementState,
   loadKnowledgePages,
@@ -6036,6 +6389,7 @@ export {
   validateKnowledgeIndex,
   withCitedClaim,
   withKnowledgeImprovementCandidate,
+  withKnowledgeImprovementComparison,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry