@tangle-network/agent-knowledge 1.12.0 → 2.0.0

package/dist/index.js

@@ -9,35 +9,53 @@ import {
   SourceAnchorSchema,
   SourceRecordSchema,
   WIKILINK_REGEX,
+  acquireDurableFileLock,
   addSourcePath,
   addSourceText,
+  applyKnowledgeFileTransaction,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
+  assertKnowledgeMutationPath,
   buildKnowledgeGraph,
   buildKnowledgeIndex,
   explainKnowledgeTarget,
   extractWikilinks,
+  finishKnowledgeFileTransaction,
   formatFrontmatter,
   initKnowledgeBase,
   inspectKnowledgeIndex,
+  inspectPendingKnowledgeMutation,
+  isMissingFile,
   isSafeKnowledgePath,
   isScaffoldPath,
+  knowledgeFileTransactionPlanHash,
   layoutFor,
   lintKnowledgeIndex,
+  listRegularFilesWithinRoot,
   loadKnowledgePages,
   loadSourceRegistry,
   mediaTypeFor,
   normalizeLinkTarget,
   parseFrontmatter,
   parseKnowledgeWriteBlocks,
+  prepareKnowledgeFileTransaction,
+  readRegularFileWithinRoot,
+  recoverPendingKnowledgeMutation,
+  renameDurable,
+  rollbackKnowledgeFileTransaction,
   sourceRegistryPath,
   stringMetadata,
   textSourceAdapter,
   validateKnowledgeIndex,
+  withKnowledgeMutation,
+  withKnowledgeRead,
+  withSafeDirectory,
+  writeFileDurableWithinRoot,
   writeJson,
+  writeJsonDurableWithinRoot,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-W6VWYTNH.js";
+} from "./chunk-QID2QVR5.js";
 import {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
@@ -101,7 +119,7 @@ import {
   scoreMemoryBenchmarkArtifact,
   scoreRetrievalArtifact,
   summarizeKnowledgeBenchmarkCampaign
-} from "./chunk-ULXZI235.js";
+} from "./chunk-RIHIYCX2.js";
 import {
   reciprocalRankFusion,
   searchKnowledge,
@@ -133,7 +151,7 @@ async function fetchWithRetry(url, init, opts) {
     await res.text().catch(() => "");
     const backoff = opts.retryBaseMs * 2 ** attempt;
     const jitter = backoff * (0.75 + Math.random() * 0.5);
-    await new Promise((resolve) => setTimeout(resolve, jitter));
+    await new Promise((resolve2) => setTimeout(resolve2, jitter));
   }
   if (lastRes) return lastRes;
   throw new RouterError(0, "fetchWithRetry produced no response");
@@ -1284,24 +1302,34 @@ function createKnowledgeEvent(input) {
 }
 
 // src/freshness.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname, join } from "path";
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { z } from "zod";
+var freshnessRecordSchema = z.object({
+  workspaceId: z.string().min(1),
+  sourceId: z.string().min(1),
+  lastRefreshedAt: z.iso.datetime(),
+  contentHash: z.string().min(1).optional()
+}).strict();
+var freshnessFileSchema = z.object({ records: z.record(z.string(), freshnessRecordSchema) }).strict();
 function createFileSystemFreshnessStore(options) {
   const path = join(options.root, ".agent-knowledge", "freshness.json");
-  let writeQueue = Promise.resolve();
   const read = async () => {
-    try {
-      const text = await readFile(path, "utf8");
-      const parsed = JSON.parse(text);
-      return parsed.records ?? {};
-    } catch {
-      return {};
-    }
+    return withKnowledgeRead(options.root, async () => {
+      try {
+        return freshnessFileSchema.parse(JSON.parse(await readFile(path, "utf8"))).records;
+      } catch (error) {
+        if (isMissingFile(error)) return {};
+        throw error;
+      }
+    });
   };
   const write = async (records) => {
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify({ records }, null, 2)}
-`, "utf8");
+    await writeJsonDurableWithinRoot(
+      options.root,
+      ".agent-knowledge/freshness.json",
+      freshnessFileSchema.parse({ records })
+    );
   };
   return {
     async last(key) {
@@ -1310,17 +1338,16 @@ function createFileSystemFreshnessStore(options) {
       return record ? new Date(record.lastRefreshedAt) : null;
     },
     async mark(input) {
-      writeQueue = writeQueue.then(async () => {
+      await withKnowledgeMutation(options.root, async () => {
         const records = await read();
         records[buildKey(input)] = {
           workspaceId: input.workspaceId,
           sourceId: input.sourceId,
           lastRefreshedAt: input.when.toISOString(),
-          contentHash: input.contentHash
+          ...input.contentHash === void 0 ? {} : { contentHash: input.contentHash }
         };
         await write(records);
       });
-      await writeQueue;
     },
     async stale(input) {
       const last = await this.last(input);
@@ -2056,7 +2083,6 @@ function lensDistribution(set = investmentThesisSet) {
 }
 
 // src/investment-thesis-task.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { join as join2 } from "path";
 
 // src/material-facts-metric.ts
@@ -2371,23 +2397,23 @@ function thesisSynthesisMessages(input, kbText) {
   ];
 }
 async function writeThesisPage(root, input, thesis) {
-  const { knowledgeDir } = layoutFor(root);
-  await mkdir2(knowledgeDir, { recursive: true });
-  const path = join2(knowledgeDir, `thesis-${input.ticker.toLowerCase()}.md`);
-  const body = [
-    "---",
-    `title: Investment thesis \u2014 ${input.company} (${input.ticker})`,
-    `ticker: ${input.ticker}`,
-    `cutoff: ${input.cutoff}`,
-    "kind: investment-thesis",
-    "---",
-    `# Investment thesis \u2014 ${input.company} (${input.ticker}), as of ${input.cutoff}`,
-    "",
-    thesis.trim(),
-    ""
-  ].join("\n");
-  await writeFile2(path, body, "utf8");
-  return path;
+  return withKnowledgeMutation(root, async () => {
+    const relativePath = `knowledge/thesis-${slugify(input.ticker)}.md`;
+    const body = [
+      "---",
+      `title: Investment thesis \u2014 ${input.company} (${input.ticker})`,
+      `ticker: ${input.ticker}`,
+      `cutoff: ${input.cutoff}`,
+      "kind: investment-thesis",
+      "---",
+      `# Investment thesis \u2014 ${input.company} (${input.ticker}), as of ${input.cutoff}`,
+      "",
+      thesis.trim(),
+      ""
+    ].join("\n");
+    await writeFileDurableWithinRoot(root, relativePath, body, { encoding: "utf8" });
+    return join2(root, relativePath);
+  });
 }
 async function runInvestmentThesisTask(input, options) {
   const worker = createWebResearchWorker({ ...options.workerOptions, router: options.router });
@@ -2410,8 +2436,16 @@ async function runInvestmentThesisTask(input, options) {
 }
 
 // src/kb-improvement.ts
-import { cp, mkdir as mkdir3, open, readdir, readFile as readFile2, rename, rm, stat, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname2, join as join3, relative } from "path";
+import { createHash } from "crypto";
+import { cp, lstat, mkdir, mkdtemp, rm, stat } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join as join3, relative, resolve, sep } from "path";
+import {
+  canonicalJson,
+  contentHash,
+  validateRunRecord
+} from "@tangle-network/agent-eval";
+import { z as z2 } from "zod";
 
 // src/rag-eval.ts
 var defaultThresholds = {
@@ -3453,6 +3487,198 @@ function assertNotAborted(signal) {
 }
 
 // src/kb-improvement.ts
+var digestSchema = z2.string().regex(/^[a-f0-9]{64}$/);
+var runIdSchema = z2.string().min(1).max(2048);
+var safePathSegmentSchema = z2.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+var improvementStatusSchema = z2.enum([
+  "running",
+  "candidate-ready",
+  "promoted",
+  "rejected",
+  "blocked"
+]);
+var runRecordSchema = z2.custom((value) => {
+  try {
+    validateRunRecord(value);
+    return true;
+  } catch {
+    return false;
+  }
+}, "invalid agent-eval RunRecord");
+var deterministicMetricProvenanceSchema = z2.object({
+  evaluator: z2.string().min(1),
+  version: z2.string().min(1),
+  method: z2.literal("deterministic")
+}).strict();
+var measuredMetricProvenanceSchema = z2.object({
+  evaluator: z2.string().min(1),
+  version: z2.string().min(1),
+  method: z2.enum(["sampled", "composite"]),
+  corpusHash: digestSchema,
+  runRecords: z2.array(runRecordSchema).min(1)
+}).strict();
+var modelMetricProvenanceSchema = z2.object({
+  evaluator: z2.string().min(1),
+  version: z2.string().min(1),
+  method: z2.literal("model"),
+  model: z2.string().min(1),
+  corpusHash: digestSchema,
+  runRecords: z2.array(runRecordSchema).min(1)
+}).strict();
+var improvementMetricSchema = z2.object({
+  score: z2.number().finite().min(0).max(1),
+  passed: z2.boolean(),
+  dimensions: z2.record(z2.string(), z2.number().finite()).optional(),
+  notes: z2.string().optional(),
+  provenance: z2.discriminatedUnion("method", [
+    deterministicMetricProvenanceSchema,
+    measuredMetricProvenanceSchema,
+    modelMetricProvenanceSchema
+  ])
+}).strict().superRefine((metric, context) => {
+  if (metric.provenance.method === "deterministic") return;
+  const actualCorpusHash = contentHash(metric.provenance.runRecords);
+  if (actualCorpusHash !== metric.provenance.corpusHash) {
+    context.addIssue({
+      code: "custom",
+      path: ["provenance", "corpusHash"],
+      message: "metric corpus hash must bind the complete RunRecord array"
+    });
+  }
+});
+var candidateRecordSchema = z2.object({
+  iteration: z2.number().int().positive(),
+  candidateId: safePathSegmentSchema,
+  baseHash: digestSchema,
+  candidateHash: digestSchema.optional(),
+  evidenceHash: digestSchema.optional(),
+  promotionPlanHash: digestSchema.optional(),
+  status: improvementStatusSchema,
+  createdAt: z2.iso.datetime(),
+  updatedAt: z2.iso.datetime()
+}).strict();
+var KnowledgeImprovementRunStateSchema = z2.object({
+  schemaVersion: z2.literal(1),
+  runId: runIdSchema,
+  root: z2.string().min(1),
+  goal: z2.string().min(1),
+  status: improvementStatusSchema,
+  baseHash: digestSchema,
+  createdAt: z2.iso.datetime(),
+  updatedAt: z2.iso.datetime(),
+  ownerId: z2.string().min(1).optional(),
+  candidates: z2.array(candidateRecordSchema),
+  promotedCandidateId: safePathSegmentSchema.optional(),
+  blockedReason: z2.string().min(1).optional()
+}).strict().superRefine((state, context) => {
+  const candidateIds = /* @__PURE__ */ new Set();
+  for (const [index, candidate] of state.candidates.entries()) {
+    if (candidateIds.has(candidate.candidateId)) {
+      context.addIssue({
+        code: "custom",
+        path: ["candidates", index, "candidateId"],
+        message: "candidate ids must be unique within an improvement run"
+      });
+    }
+    candidateIds.add(candidate.candidateId);
+    if (candidate.baseHash !== state.baseHash) {
+      context.addIssue({
+        code: "custom",
+        path: ["candidates", index, "baseHash"],
+        message: "candidate base hash must match its improvement run"
+      });
+    }
+    if (candidate.status === "candidate-ready") {
+      if (!candidate.candidateHash || !candidate.evidenceHash || !candidate.promotionPlanHash) {
+        context.addIssue({
+          code: "custom",
+          path: ["candidates", index],
+          message: "ready candidates require content, evidence, and promotion-plan identities"
+        });
+      }
+    }
+    if (candidate.status === "promoted" && (!candidate.candidateHash || !candidate.evidenceHash || !candidate.promotionPlanHash)) {
+      context.addIssue({
+        code: "custom",
+        path: ["candidates", index],
+        message: "promoted candidates require content, evidence, and promotion-plan identities"
+      });
+    }
+    if (candidate.status === "promoted" && Boolean(candidate.evidenceHash) !== Boolean(candidate.promotionPlanHash)) {
+      context.addIssue({
+        code: "custom",
+        path: ["candidates", index],
+        message: "promoted candidate evidence and promotion-plan identities must appear together"
+      });
+    }
+    if (candidate.status === "promoted" && state.status !== "promoted") {
+      context.addIssue({
+        code: "custom",
+        path: ["candidates", index, "status"],
+        message: "only a promoted run may contain a promoted candidate"
+      });
+    }
+  }
+  if (state.status === "promoted") {
+    const promoted = state.candidates.filter(
+      (candidate) => candidate.candidateId === state.promotedCandidateId
+    );
+    if (promoted.length !== 1 || promoted[0]?.status !== "promoted") {
+      context.addIssue({
+        code: "custom",
+        path: ["promotedCandidateId"],
+        message: "promoted state must identify exactly one promoted candidate"
+      });
+    }
+  } else if (state.promotedCandidateId !== void 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["promotedCandidateId"],
+      message: "only a promoted run may identify a promoted candidate"
+    });
+  }
+  if (state.status === "candidate-ready" && state.candidates.filter((candidate) => candidate.status === "candidate-ready").length !== 1) {
+    context.addIssue({
+      code: "custom",
+      path: ["status"],
+      message: "candidate-ready state must contain exactly one ready candidate"
+    });
+  }
+  if (state.status === "blocked" && state.blockedReason === void 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["blockedReason"],
+      message: "blocked state must include a reason"
+    });
+  }
+});
+var KnowledgeImprovementEvidenceSchema = z2.object({
+  schemaVersion: z2.literal(1),
+  kind: z2.literal("knowledge-improvement-evidence"),
+  runId: runIdSchema,
+  candidateId: safePathSegmentSchema,
+  iteration: z2.number().int().positive(),
+  goalHash: digestSchema,
+  baseHash: digestSchema,
+  candidateHash: digestSchema,
+  promotionPlanHash: digestSchema,
+  validation: z2.unknown(),
+  readiness: z2.unknown().nullable(),
+  kbQuality: z2.unknown(),
+  evaluation: improvementMetricSchema,
+  lifecycle: z2.unknown().nullable()
+}).strict();
+var KnowledgeImprovementCandidateRefSchema = z2.object({
+  schemaVersion: z2.literal(1),
+  kind: z2.literal("knowledge-improvement-candidate"),
+  runId: runIdSchema,
+  candidateId: safePathSegmentSchema,
+  goalHash: digestSchema,
+  baseHash: digestSchema,
+  candidateHash: digestSchema,
+  evidenceHash: digestSchema,
+  promotionPlanHash: digestSchema
+}).strict();
 var DEFAULT_LEASE_TTL_MS = 15 * 60 * 1e3;
 var UPDATE_PHASES = [
   "knowledge-acquisition",
@@ -3468,33 +3694,159 @@ function knowledgeImprovementRunId(root, goal) {
   return stableId("kimpr", `${root}:${goal}`);
 }
 function knowledgeImprovementRunDir(root, runId) {
-  return join3(layoutFor(root).cacheDir, "improvements", runId);
+  const parsedRunId = runIdSchema.parse(runId);
+  const safeRunId = safePathSegmentSchema.safeParse(parsedRunId);
+  const runSegment = safeRunId.success ? safeRunId.data : `${slugify(parsedRunId).slice(0, 72)}-${sha256(parsedRunId).slice(0, 16)}`;
+  const improvementsDir = join3(layoutFor(root).cacheDir, "improvements");
+  const runDir = join3(improvementsDir, runSegment);
+  const resolvedImprovementsDir = resolve(improvementsDir);
+  const resolvedRunDir = resolve(runDir);
+  if (!resolvedRunDir.startsWith(`${resolvedImprovementsDir}${sep}`)) {
+    throw new Error("knowledge improvement run directory escaped its root");
+  }
+  return runDir;
+}
+async function withKnowledgeImprovementRun(root, runId, create, use) {
+  const runDir = knowledgeImprovementRunDir(root, runId);
+  const relativePath = descendantPath(root, runDir);
+  if (!relativePath) throw new Error("knowledge improvement run directory escaped its root");
+  return withSafeDirectory(root, relativePath, create, async (openedRunDir) => {
+    const result = await use(openedRunDir);
+    const openedIdentity = await stat(openedRunDir);
+    const currentIdentity = await withSafeDirectory(
+      root,
+      relativePath,
+      false,
+      (currentRunDir) => stat(currentRunDir)
+    );
+    if (openedIdentity.dev !== currentIdentity.dev || openedIdentity.ino !== currentIdentity.ino) {
+      throw new Error("knowledge improvement run directory changed during use");
+    }
+    return result;
+  });
 }
-async function loadKnowledgeImprovementState(root, runId, runDir = knowledgeImprovementRunDir(root, runId)) {
+async function loadKnowledgeImprovementState(root, runId) {
+  const expectedRunId = runIdSchema.parse(runId);
   try {
-    return JSON.parse(await readFile2(statePath(runDir), "utf8"));
-  } catch {
-    return null;
+    return await withKnowledgeImprovementRun(
+      root,
+      expectedRunId,
+      false,
+      (runDir) => loadKnowledgeImprovementStateFromRun(root, expectedRunId, runDir)
+    );
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
   }
 }
+async function loadKnowledgeImprovementStateFromRun(root, runId, runDir) {
+  const stateFile = await readRegularFileWithinRoot(runDir, "state.json");
+  const raw = JSON.parse(stateFile.bytes.toString("utf8"));
+  const state = KnowledgeImprovementRunStateSchema.parse(raw);
+  if (state.runId !== runId) {
+    throw new Error("knowledge improvement state does not match the requested run");
+  }
+  if (resolve(state.root) !== resolve(root)) {
+    throw new Error("knowledge improvement state does not match the requested root");
+  }
+  for (const candidate of state.candidates) {
+    if (candidate.status === "running") await assertCandidateWorkspace(runDir, candidate);
+  }
+  return state;
+}
+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 withKnowledgeImprovementCandidate(options, use) {
+  assertExactCandidatePlatform();
+  const candidateRef = KnowledgeImprovementCandidateRefSchema.parse(options.candidate);
+  return withKnowledgeImprovementRun(options.root, candidateRef.runId, false, async (runDir) => {
+    const state = await loadKnowledgeImprovementStateFromRun(
+      options.root,
+      candidateRef.runId,
+      runDir
+    );
+    return withMeasuredCandidateSnapshot(
+      options.root,
+      runDir,
+      state,
+      candidateRef,
+      (resolved) => withIsolatedCandidateCopy(
+        resolved.root,
+        candidateRef.candidateHash,
+        (root) => use({
+          root,
+          candidate: candidateRef,
+          evaluation: resolved.evidence.evaluation
+        })
+      )
+    );
+  });
+}
+async function promoteKnowledgeCandidate(options) {
+  assertExactCandidatePlatform();
+  const candidateRef = Object.freeze(
+    KnowledgeImprovementCandidateRefSchema.parse(options.candidate)
+  );
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  return withKnowledgeImprovementRun(options.root, candidateRef.runId, false, async (runDir) => {
+    const lease = await acquireRunLease(runDir, {
+      ownerId: options.ownerId ?? `pid-${process.pid}`,
+      ttlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS
+    });
+    try {
+      lease.assertOwned();
+      const state = await loadKnowledgeImprovementStateFromRun(
+        options.root,
+        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
+      });
+    } finally {
+      await lease.release();
+    }
+  });
+}
 async function improveKnowledgeBase(options) {
+  assertExactCandidatePlatform();
   assertKnowledgeImprovementOptions(options);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
-  const runId = options.runId ?? knowledgeImprovementRunId(options.root, options.goal);
-  const runDir = options.runDir ?? knowledgeImprovementRunDir(options.root, runId);
-  await initKnowledgeBase(options.root);
-  await mkdir3(runDir, { recursive: true });
+  const runId = runIdSchema.parse(
+    options.runId ?? knowledgeImprovementRunId(options.root, options.goal)
+  );
+  return withKnowledgeImprovementRun(
+    options.root,
+    runId,
+    true,
+    (runDir) => improveKnowledgeBaseInRun(options, runId, runDir, now)
+  );
+}
+async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
   const lease = await acquireRunLease(runDir, {
     ownerId: options.ownerId ?? `pid-${process.pid}`,
-    ttlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
-    now
+    ttlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS
   });
   try {
-    let state = options.resume === false ? null : await loadKnowledgeImprovementState(options.root, runId, runDir);
+    lease.assertOwned();
+    let state = options.resume === false ? null : await loadKnowledgeImprovementStateFromRun(options.root, runId, runDir).catch((error) => {
+      if (isMissingFile(error)) return null;
+      throw error;
+    });
     if (!state) {
       const baseHash = await hashKnowledgeBase(options.root);
+      await createBaselineSnapshot(runDir, options.root, baseHash);
       state = {
-        version: 1,
+        schemaVersion: 1,
         runId,
         root: options.root,
         goal: options.goal,
@@ -3508,29 +3860,65 @@ async function improveKnowledgeBase(options) {
       await saveState(runDir, state, options.onState);
       await appendLedger(runDir, { type: "run.created", runId, baseHash });
     }
+    if (state.goal !== options.goal) {
+      throw new Error("knowledge improvement state does not match the requested goal");
+    }
+    const promotedCandidateId = state.promotedCandidateId;
+    const promotedCandidate = state.status === "promoted" ? state.candidates.find((candidate2) => candidate2.candidateId === promotedCandidateId) : void 0;
+    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 ensureBaselineSnapshot(runDir, options.root, state.baseHash);
     if (state.status === "promoted") {
-      return { runId, runDir, state, promoted: true, blocked: false };
+      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
+      });
     }
     if (state.status === "blocked") {
-      return { runId, runDir, state, promoted: false, blocked: true };
+      return { runId, state, promoted: false, blocked: true };
     }
     const maxCandidates = Math.max(1, options.maxCandidates ?? 1);
     let candidate = findActiveCandidate(state);
+    let lastRejectedCandidate;
+    let lastRejectedEvaluation;
     let lifecycle;
-    while (candidate?.status === "running" || !candidate && state.candidates.length < maxCandidates) {
+    while (candidate || state.candidates.length < maxCandidates) {
       if (!candidate) {
-        const currentHash2 = await hashKnowledgeBase(options.root);
-        if (currentHash2 !== state.baseHash) {
+        const currentHash = await hashKnowledgeBase(options.root);
+        if (currentHash !== state.baseHash) {
           state = await blockRun(
             runDir,
             state,
-            `base changed before candidate creation: expected ${state.baseHash}, got ${currentHash2}`,
+            `base changed before candidate creation: expected ${state.baseHash}, got ${currentHash}`,
             options.onState,
             now
           );
-          return { runId, runDir, state, promoted: false, blocked: true };
+          return { runId, state, promoted: false, blocked: true };
         }
-        candidate = await createCandidateWorkspace(runDir, state, options.root, now);
+        const activeState = state;
+        candidate = await withBaselineSnapshot(
+          runDir,
+          activeState.baseHash,
+          (baselineRoot) => createCandidateWorkspace(runDir, activeState, baselineRoot, now)
+        );
         state.candidates.push(candidate);
         state.status = "running";
         state.updatedAt = now().toISOString();
@@ -3542,79 +3930,377 @@ async function improveKnowledgeBase(options) {
           iteration: candidate.iteration
         });
       }
-      lifecycle = await runCandidateLifecycle(runDir, runId, candidate, options, now);
-      candidate.status = "candidate-ready";
-      candidate.updatedAt = now().toISOString();
-      state.status = "candidate-ready";
+      const measured = await measureCandidate(runId, runDir, state, candidate, options, now);
+      candidate = measured.candidate;
+      const evaluation = measured.evaluation;
+      lifecycle = measured.lifecycle;
+      if (evaluation.passed) {
+        candidate.status = "candidate-ready";
+        candidate.updatedAt = now().toISOString();
+        state.status = "candidate-ready";
+        state.updatedAt = now().toISOString();
+        await saveState(runDir, state, options.onState);
+        await appendLedger(runDir, {
+          type: "candidate.ready",
+          runId,
+          candidateId: candidate.candidateId
+        });
+        break;
+      }
+      candidate.status = "rejected";
+      state.status = "running";
       state.updatedAt = now().toISOString();
       await saveState(runDir, state, options.onState);
       await appendLedger(runDir, {
-        type: "candidate.ready",
+        type: "candidate.rejected",
         runId,
         candidateId: candidate.candidateId
       });
+      lastRejectedCandidate = candidate;
+      lastRejectedEvaluation = evaluation;
+      candidate = void 0;
     }
     if (!candidate) {
       state.status = "rejected";
       state.updatedAt = now().toISOString();
       await saveState(runDir, state, options.onState);
-      return { runId, runDir, state, promoted: false, blocked: false };
-    }
-    candidate = await evaluateCandidate(runDir, state, candidate, lifecycle, options, now);
-    state.updatedAt = now().toISOString();
-    await saveState(runDir, state, options.onState);
-    if (!candidate.evaluation?.passed) {
-      candidate.status = "rejected";
-      state.status = "rejected";
-      state.updatedAt = now().toISOString();
-      await saveState(runDir, state, options.onState);
-      await appendLedger(runDir, {
-        type: "candidate.rejected",
+      return {
         runId,
-        candidateId: candidate.candidateId
-      });
-      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: false };
-    }
-    if (options.promote === false) {
-      state.status = "candidate-ready";
-      state.updatedAt = now().toISOString();
-      await saveState(runDir, state, options.onState);
-      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: false };
-    }
-    const currentHash = await hashKnowledgeBase(options.root);
-    if (currentHash !== state.baseHash) {
-      state = await blockRun(
-        runDir,
         state,
-        `base changed before promotion: expected ${state.baseHash}, got ${currentHash}`,
-        options.onState,
-        now
-      );
-      await appendLedger(runDir, {
-        type: "promotion.blocked",
-        runId,
-        candidateId: candidate.candidateId,
-        reason: state.blockedReason
-      });
-      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: true };
+        candidate: lastRejectedCandidate,
+        ...lastRejectedEvaluation ? { evaluation: lastRejectedEvaluation } : {},
+        lifecycle,
+        promoted: false,
+        blocked: false
+      };
     }
-    await promoteCandidate(options.root, candidate.candidateRoot);
-    candidate.status = "promoted";
-    candidate.updatedAt = now().toISOString();
-    state.status = "promoted";
-    state.promotedCandidateId = candidate.candidateId;
-    state.updatedAt = now().toISOString();
-    await saveState(runDir, state, options.onState);
-    await appendLedger(runDir, {
-      type: "candidate.promoted",
+    const evidence = await assertCandidateEvidence(runDir, candidateRefFor(runId, state, candidate));
+    return {
       runId,
-      candidateId: candidate.candidateId
-    });
-    return { runId, runDir, state, candidate, lifecycle, promoted: true, blocked: false };
+      state,
+      candidate,
+      evaluation: evidence.evaluation,
+      lifecycle,
+      promoted: false,
+      blocked: false
+    };
   } finally {
     await lease.release();
   }
 }
+async function promoteReadyCandidate(input) {
+  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);
+  return withKnowledgeMutation(
+    input.root,
+    async (mutationLock) => {
+      input.assertRunOwned();
+      const transactionRoot = mutationLock.transactionRoot;
+      let pending = null;
+      const currentHash = await hashKnowledgeBase(input.root);
+      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) {
+        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}`
+        );
+      }
+      if (currentHash !== state.baseHash && currentHash !== candidateRef.candidateHash) {
+        return await blockPromotion(
+          input,
+          candidate,
+          `base changed before promotion: expected ${state.baseHash}, got ${currentHash}`
+        );
+      }
+      if (currentHash !== candidateRef.candidateHash) {
+        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");
+            }
+            return prepareKnowledgeFileTransaction({
+              root: input.root,
+              transactionRoot,
+              purpose,
+              mutations: await promotionMutations(resolved.root, plan),
+              includeUnchanged: true,
+              now: input.now
+            });
+          })
+        );
+        if (!pending) {
+          throw new Error("knowledge promotion plan unexpectedly contained no file changes");
+        }
+        try {
+          assertPromotionTransaction(pending, candidateRef);
+        } catch (error) {
+          try {
+            await rollbackKnowledgeFileTransaction({
+              root: input.root,
+              transactionRoot,
+              transaction: pending,
+              beforeCommit() {
+                mutationLock.assertOwned();
+                input.assertRunOwned();
+              }
+            });
+            await finishKnowledgeFileTransaction({
+              root: input.root,
+              transactionRoot,
+              transaction: pending,
+              assertOwned() {
+                mutationLock.assertOwned();
+                input.assertRunOwned();
+              }
+            });
+          } catch (cleanupError) {
+            throw new AggregateError(
+              [error, cleanupError],
+              "invalid knowledge promotion transaction could not be removed"
+            );
+          }
+          throw error;
+        }
+      }
+      try {
+        if (pending) {
+          await applyKnowledgeFileTransaction({
+            root: input.root,
+            transactionRoot,
+            transaction: pending,
+            beforeCommit() {
+              mutationLock.assertOwned();
+              input.assertRunOwned();
+            }
+          });
+        }
+        mutationLock.assertOwned();
+        input.assertRunOwned();
+        if (await hashKnowledgeBase(input.root) !== candidateRef.candidateHash) {
+          throw new Error("promoted knowledge content does not match the approved candidate");
+        }
+        await writeKnowledgeIndex(input.root);
+      } catch (error) {
+        if (!pending) throw error;
+        try {
+          mutationLock.assertOwned();
+          input.assertRunOwned();
+        } catch (ownershipError) {
+          throw new AggregateError(
+            [error, ownershipError],
+            "knowledge promotion lost its lock and left the transaction pending"
+          );
+        }
+        try {
+          await rollbackKnowledgeFileTransaction({
+            root: input.root,
+            transactionRoot,
+            transaction: pending,
+            beforeCommit() {
+              mutationLock.assertOwned();
+              input.assertRunOwned();
+            }
+          });
+          await finishKnowledgeFileTransaction({
+            root: input.root,
+            transactionRoot,
+            transaction: pending,
+            assertOwned() {
+              mutationLock.assertOwned();
+              input.assertRunOwned();
+            }
+          });
+          await writeKnowledgeIndex(input.root);
+        } catch (rollbackError) {
+          throw new AggregateError(
+            [error, rollbackError],
+            "knowledge promotion failed and could not restore the previous files"
+          );
+        }
+        throw error;
+      }
+      candidate.status = "promoted";
+      candidate.updatedAt = input.now().toISOString();
+      state.status = "promoted";
+      state.promotedCandidateId = candidate.candidateId;
+      state.updatedAt = input.now().toISOString();
+      await saveState(runDir, state, input.onState);
+      await ensurePromotionEvent(runDir, candidateRef);
+      if (pending) {
+        await finishKnowledgeFileTransaction({
+          root: input.root,
+          transactionRoot,
+          transaction: pending,
+          assertOwned() {
+            mutationLock.assertOwned();
+            input.assertRunOwned();
+          }
+        });
+      }
+      return promotionResult(input, candidate, true, false);
+    },
+    {
+      staleMs: input.leaseTtlMs,
+      resumeTransaction: {
+        purpose,
+        validate: (transaction) => assertPromotionTransaction(transaction, candidateRef)
+      }
+    }
+  );
+}
+async function blockPromotion(input, candidate, reason) {
+  await blockRun(input.runDir, input.state, reason, input.onState, input.now);
+  await appendLedger(input.runDir, {
+    type: "promotion.blocked",
+    runId: input.candidateRef.runId,
+    candidateId: candidate.candidateId,
+    reason
+  });
+  return promotionResult(input, candidate, false, true);
+}
+function promotionResult(input, candidate, promoted, blocked) {
+  return {
+    runId: input.candidateRef.runId,
+    state: input.state,
+    candidate,
+    ...input.lifecycle ? { lifecycle: input.lifecycle } : {},
+    promoted,
+    blocked
+  };
+}
+function candidateRefFor(runId, state, candidate) {
+  if (!candidate.candidateHash) {
+    throw new Error(`knowledge candidate '${candidate.candidateId}' has no content hash`);
+  }
+  if (!candidate.evidenceHash) {
+    throw new Error(`knowledge candidate '${candidate.candidateId}' has no evidence hash`);
+  }
+  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({
+    schemaVersion: 1,
+    kind: "knowledge-improvement-candidate",
+    runId,
+    candidateId: candidate.candidateId,
+    goalHash: sha256(state.goal),
+    baseHash: candidate.baseHash,
+    candidateHash: candidate.candidateHash,
+    evidenceHash: candidate.evidenceHash,
+    promotionPlanHash: candidate.promotionPlanHash
+  });
+}
+async function withMeasuredCandidateSnapshot(liveRoot, runDir, state, candidateRef, use) {
+  assertStateIdentity(liveRoot, candidateRef, state);
+  const candidate = state.candidates.find((entry) => entry.candidateId === candidateRef.candidateId);
+  if (!candidate) {
+    throw new Error(`knowledge candidate '${candidateRef.candidateId}' does not exist`);
+  }
+  const expectedRef = candidateRefFor(candidateRef.runId, state, candidate);
+  if (canonicalJson(expectedRef) !== canonicalJson(candidateRef)) {
+    throw new Error("knowledge candidate approval does not match the measured candidate");
+  }
+  const evidence = await assertCandidateEvidence(runDir, candidateRef);
+  const relativePath = join3(
+    "candidates",
+    candidate.candidateId,
+    "snapshots",
+    candidateRef.candidateHash
+  );
+  return withSafeDirectory(runDir, relativePath, false, async (root) => {
+    if (await hashKnowledgeBase(root) !== candidateRef.candidateHash) {
+      throw new Error("knowledge candidate snapshot changed after approval");
+    }
+    const result = await use({ root, candidate, evidence });
+    if (await hashKnowledgeBase(root) !== candidateRef.candidateHash) {
+      throw new Error("knowledge candidate snapshot changed during use");
+    }
+    return result;
+  });
+}
+async function withIsolatedCandidateCopy(sourceRoot, expectedHash, use) {
+  const isolationRoot = await mkdtemp(join3(tmpdir(), "agent-knowledge-candidate-"));
+  const candidateRoot = join3(isolationRoot, "candidate");
+  try {
+    await copyKnowledgeWorkspace(sourceRoot, candidateRoot);
+    if (await hashKnowledgeBase(candidateRoot) !== expectedHash) {
+      throw new Error("isolated knowledge candidate does not match its approved content");
+    }
+    const result = await use(candidateRoot);
+    if (await hashKnowledgeBase(candidateRoot) !== expectedHash) {
+      throw new Error("knowledge candidate snapshot changed during use");
+    }
+    return result;
+  } finally {
+    await rm(isolationRoot, { recursive: true, force: true });
+  }
+}
+async function assertCandidateEvidence(runDir, candidate) {
+  const evidence = KnowledgeImprovementEvidenceSchema.parse(
+    JSON.parse(
+      (await readRegularFileWithinRoot(
+        runDir,
+        candidateEvidenceRelativePath(candidate.candidateId)
+      )).bytes.toString("utf8")
+    )
+  );
+  const actualHash = contentHash(evidence);
+  if (actualHash !== candidate.evidenceHash) {
+    throw new Error(
+      `knowledge candidate evidence changed after approval: expected ${candidate.evidenceHash}, got ${actualHash}`
+    );
+  }
+  if (evidence.runId !== candidate.runId || evidence.candidateId !== candidate.candidateId || evidence.goalHash !== candidate.goalHash || evidence.baseHash !== candidate.baseHash || evidence.candidateHash !== candidate.candidateHash || evidence.promotionPlanHash !== candidate.promotionPlanHash || evidence.evaluation.passed !== true) {
+    throw new Error("knowledge candidate evidence does not match the approved candidate");
+  }
+  return evidence;
+}
+function assertStateIdentity(root, candidateRef, state) {
+  if (state.runId !== candidateRef.runId) {
+    throw new Error("knowledge candidate run identity does not match persisted state");
+  }
+  if (resolve(state.root) !== resolve(root)) {
+    throw new Error("knowledge candidate root does not match persisted state");
+  }
+  if (sha256(state.goal) !== candidateRef.goalHash) {
+    throw new Error("knowledge candidate goal does not match persisted state");
+  }
+  if (state.baseHash !== candidateRef.baseHash) {
+    throw new Error("knowledge candidate base does not match persisted state");
+  }
+}
+async function assertCandidateWorkspace(runDir, candidate) {
+  await withCandidateWorkspace(runDir, candidate, () => void 0);
+}
+async function withCandidateWorkspace(runDir, candidate, use) {
+  return withSafeDirectory(
+    runDir,
+    join3("candidates", safePathSegmentSchema.parse(candidate.candidateId), "workspace"),
+    false,
+    use
+  );
+}
 function assertKnowledgeImprovementOptions(options) {
   if (options.step && options.knowledgeResearch?.step) {
     throw new Error("improveKnowledgeBase accepts either step or knowledgeResearch.step, not both");
@@ -3629,43 +4315,84 @@ function assertKnowledgeImprovementOptions(options) {
     );
   }
 }
-async function runCandidateLifecycle(runDir, runId, candidate, options, now) {
-  const lifecycles = [];
-  if (shouldRunUpdateStage(options)) {
-    const updateLifecycle = await runRagKnowledgeImprovementLoop({
-      goal: options.goal,
-      acquireKnowledge: options.acquireKnowledge,
-      knowledgeResearch: candidateKnowledgeResearchOptions(candidate.candidateRoot, options),
-      updateKnowledge: candidateUpdateHook(runId, candidate, options),
-      enabledPhases: selectedStagePhases(options, UPDATE_PHASES),
-      requiredPhases: selectedStageRequiredPhases(options, UPDATE_PHASES),
-      signal: options.signal,
-      now
-    });
-    lifecycles.push(updateLifecycle);
-    recordLifecycle(candidate, "candidate-update", updateLifecycle);
-  }
-  if (shouldRunEvaluationStage(options)) {
-    const candidateIndex = await buildKnowledgeIndex(candidate.candidateRoot);
-    const evaluationLifecycle = await runRagKnowledgeImprovementLoop({
-      goal: options.goal,
-      retrieval: options.retrieval ? {
-        ...options.retrieval,
-        index: candidateIndex,
-        runDir: options.retrieval.runDir ?? join3(runDir, "retrieval", candidate.candidateId)
-      } : void 0,
-      diagnose: options.diagnose,
-      evaluateAnswers: options.evaluateAnswers,
-      promote: options.decidePromotion,
-      enabledPhases: selectedStagePhases(options, EVALUATION_PHASES),
-      requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
-      signal: options.signal,
-      now
+async function measureCandidate(runId, runDir, state, candidate, options, now) {
+  return withCandidateWorkspace(runDir, candidate, async (candidateRoot) => {
+    const currentCandidateHash = await hashKnowledgeBase(candidateRoot);
+    if (candidate.status === "candidate-ready" && candidate.candidateHash === currentCandidateHash && candidate.evidenceHash !== void 0 && candidate.promotionPlanHash !== void 0) {
+      const evidence = await assertCandidateEvidence(
+        runDir,
+        candidateRefFor(runId, state, candidate)
+      );
+      return { candidate, evaluation: evidence.evaluation };
+    }
+    clearCandidateMeasurement(candidate);
+    const lifecycles = [];
+    if (candidate.status === "running") {
+      const updateLifecycle = await runCandidateUpdateLifecycle(
+        runId,
+        candidate,
+        candidateRoot,
+        options,
+        now
+      );
+      if (updateLifecycle) lifecycles.push(updateLifecycle);
+    }
+    return withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, async (snapshot) => {
+      const evaluationLifecycle = await runCandidateEvaluationLifecycle(
+        runDir,
+        candidate,
+        snapshot.root,
+        options,
+        now
+      );
+      if (evaluationLifecycle) lifecycles.push(evaluationLifecycle);
+      const lifecycle = mergeLifecycleResults(options.goal, lifecycles);
+      const measured = await evaluateCandidate(
+        runDir,
+        state,
+        candidate,
+        snapshot,
+        lifecycle,
+        options,
+        now
+      );
+      return { ...measured, ...lifecycle ? { lifecycle } : {} };
     });
-    lifecycles.push(evaluationLifecycle);
-    recordLifecycle(candidate, "candidate-evaluation", evaluationLifecycle);
-  }
-  return mergeLifecycleResults(options.goal, lifecycles);
+  });
+}
+async function runCandidateUpdateLifecycle(runId, candidate, candidateRoot, options, now) {
+  if (!shouldRunUpdateStage(options)) return void 0;
+  const lifecycle = await runRagKnowledgeImprovementLoop({
+    goal: options.goal,
+    acquireKnowledge: options.acquireKnowledge,
+    knowledgeResearch: candidateKnowledgeResearchOptions(candidateRoot, options),
+    updateKnowledge: candidateUpdateHook(runId, candidate, candidateRoot, options),
+    enabledPhases: selectedStagePhases(options, UPDATE_PHASES),
+    requiredPhases: selectedStageRequiredPhases(options, UPDATE_PHASES),
+    signal: options.signal,
+    now
+  });
+  return lifecycle;
+}
+async function runCandidateEvaluationLifecycle(runDir, candidate, candidateRoot, options, now) {
+  if (!shouldRunEvaluationStage(options)) return void 0;
+  const candidateIndex = await buildKnowledgeIndex(candidateRoot);
+  const lifecycle = await runRagKnowledgeImprovementLoop({
+    goal: options.goal,
+    retrieval: options.retrieval ? {
+      ...options.retrieval,
+      index: candidateIndex,
+      runDir: options.retrieval.runDir ?? join3(runDir, "retrieval", candidate.candidateId)
+    } : void 0,
+    diagnose: options.diagnose,
+    evaluateAnswers: options.evaluateAnswers,
+    promote: options.decidePromotion,
+    enabledPhases: selectedStagePhases(options, EVALUATION_PHASES),
+    requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
+    signal: options.signal,
+    now
+  });
+  return lifecycle;
 }
 function candidateKnowledgeResearchOptions(candidateRoot, options) {
   if (!options.step && !options.knowledgeResearch) return void 0;
@@ -3682,16 +4409,16 @@ function candidateKnowledgeResearchOptions(candidateRoot, options) {
     readiness: rest.readiness ?? options.readiness
   };
 }
-function candidateUpdateHook(runId, candidate, options) {
+function candidateUpdateHook(runId, candidate, candidateRoot, options) {
   if (!options.updateKnowledge) return void 0;
   return (input) => options.updateKnowledge({
     ...input,
     runId,
     iteration: candidate.iteration,
     candidateId: candidate.candidateId,
-    root: candidate.candidateRoot,
+    root: candidateRoot,
     baselineRoot: options.root,
-    candidateRoot: candidate.candidateRoot,
+    candidateRoot,
     baseHash: candidate.baseHash
   });
 }
@@ -3716,20 +4443,6 @@ function selectedStagePhases(options, stagePhases) {
 function selectedStageRequiredPhases(options, stagePhases) {
   return (options.requiredPhases ?? []).filter((phase) => stagePhases.includes(phase));
 }
-function recordLifecycle(candidate, stage, lifecycle) {
-  const record = {
-    stage,
-    phases: lifecycle.phases,
-    findingCount: lifecycle.findings.length,
-    retrievalWinnerConfig: lifecycle.retrieval?.winnerConfig,
-    answerQuality: lifecycle.answerQuality,
-    promotionDecision: lifecycle.promotion
-  };
-  candidate.lifecycle = [...candidate.lifecycle ?? [], record];
-  candidate.retrievalWinnerConfig = lifecycle.retrieval?.winnerConfig ?? candidate.retrievalWinnerConfig;
-  candidate.answerQuality = lifecycle.answerQuality ?? candidate.answerQuality;
-  candidate.promotionDecision = lifecycle.promotion ?? candidate.promotionDecision;
-}
 function mergeLifecycleResults(goal, lifecycles) {
   if (lifecycles.length === 0) return void 0;
   return {
@@ -3749,54 +4462,88 @@ function lastDefined(values) {
   }
   return void 0;
 }
-async function evaluateCandidate(runDir, state, candidate, lifecycle, options, now) {
-  const [baselineIndex, candidateIndex] = await Promise.all([
-    buildKnowledgeIndex(options.root),
-    buildKnowledgeIndex(candidate.candidateRoot)
-  ]);
-  const validation = validateKnowledgeIndex(candidateIndex, { strict: options.strict });
-  const readiness = readinessFor(options, candidateIndex);
-  const kbQuality = scoreKnowledgeBaseIndex(candidateIndex, {
-    strict: options.strict,
-    ...options.kbQuality
-  });
-  const candidateHash = await hashKnowledgeBase(candidate.candidateRoot);
-  const metric = options.evaluate?.({
-    runId: state.runId,
-    iteration: candidate.iteration,
-    root: options.root,
-    baselineRoot: options.root,
-    candidateRoot: candidate.candidateRoot,
-    baselineIndex,
-    candidateIndex,
-    baseHash: state.baseHash,
-    candidateHash,
-    validation,
-    readiness,
-    kbQuality,
-    lifecycle,
-    signal: options.signal
-  }) ?? defaultKnowledgeImprovementMetric(
-    validation,
-    readiness,
-    options.readinessSpecs,
-    kbQuality,
-    lifecycle
-  );
-  candidate.validation = validation;
-  candidate.kbQuality = kbQuality;
-  candidate.readinessBlockingMissing = readiness?.report.blockingMissingRequirements.length;
-  candidate.evaluation = applyLifecycleFailures(normalizeMetric(await metric), lifecycle);
-  candidate.candidateHash = candidateHash;
-  candidate.updatedAt = now().toISOString();
-  await appendLedger(runDir, {
-    type: "candidate.evaluated",
-    runId: state.runId,
-    candidateId: candidate.candidateId,
-    score: candidate.evaluation.score,
-    passed: candidate.evaluation.passed
+async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle, options, now) {
+  return withBaselineSnapshot(runDir, state.baseHash, async (baselineRoot) => {
+    const [baselineIndex, candidateIndex] = await Promise.all([
+      buildKnowledgeIndex(baselineRoot),
+      buildKnowledgeIndex(snapshot.root)
+    ]);
+    const validation = validateKnowledgeIndex(candidateIndex, { strict: options.strict });
+    const readiness = readinessFor(options, candidateIndex);
+    const kbQuality = scoreKnowledgeBaseIndex(candidateIndex, {
+      strict: options.strict,
+      ...options.kbQuality
+    });
+    const candidateHash = snapshot.hash;
+    const metric = options.evaluate?.({
+      runId: state.runId,
+      iteration: candidate.iteration,
+      root: options.root,
+      baselineRoot,
+      candidateRoot: snapshot.root,
+      baselineIndex,
+      candidateIndex,
+      baseHash: state.baseHash,
+      candidateHash,
+      validation,
+      readiness,
+      kbQuality,
+      lifecycle,
+      signal: options.signal
+    }) ?? defaultKnowledgeImprovementMetric(
+      validation,
+      readiness,
+      options.readinessSpecs,
+      kbQuality,
+      lifecycle
+    );
+    const evaluation = applyLifecycleFailures(normalizeMetric(await metric), lifecycle);
+    const measuredHash = await hashKnowledgeBase(snapshot.root);
+    if (measuredHash !== candidateHash) {
+      throw new Error(
+        `knowledge candidate changed during evaluation: expected ${candidateHash}, got ${measuredHash}`
+      );
+    }
+    candidate.candidateHash = candidateHash;
+    candidate.promotionPlanHash = knowledgeFileTransactionPlanHash(
+      await promotionPlanEntries(baselineRoot, snapshot.root)
+    );
+    const evidence = KnowledgeImprovementEvidenceSchema.parse(
+      JSON.parse(
+        JSON.stringify({
+          schemaVersion: 1,
+          kind: "knowledge-improvement-evidence",
+          runId: state.runId,
+          candidateId: candidate.candidateId,
+          iteration: candidate.iteration,
+          goalHash: sha256(state.goal),
+          baseHash: candidate.baseHash,
+          candidateHash,
+          promotionPlanHash: candidate.promotionPlanHash,
+          validation,
+          readiness: readiness ?? null,
+          kbQuality,
+          evaluation,
+          lifecycle: lifecycle ?? null
+        })
+      )
+    );
+    candidate.evidenceHash = contentHash(evidence);
+    candidate.updatedAt = now().toISOString();
+    await writeJsonDurableWithinRoot(
+      runDir,
+      candidateEvidenceRelativePath(candidate.candidateId),
+      evidence
+    );
+    await appendLedger(runDir, {
+      type: "candidate.evaluated",
+      runId: state.runId,
+      candidateId: candidate.candidateId,
+      score: evaluation.score,
+      passed: evaluation.passed
+    });
+    return { candidate, evaluation };
   });
-  return candidate;
 }
 function defaultKnowledgeImprovementMetric(validation, readiness, readinessSpecs, kbQuality, lifecycle) {
   const blockingMissing = readiness?.report.blockingMissingRequirements.length ?? 0;
@@ -3814,15 +4561,18 @@ function defaultKnowledgeImprovementMetric(validation, readiness, readinessSpecs
   const failedReasons = [
     validation.ok ? void 0 : "candidate validation failed",
     kbQuality.ok ? void 0 : "candidate KB quality check failed",
-    blockingMissing === 0 ? void 0 : `${blockingMissing}/${blockingTotal} blocking knowledge requirements still missing`,
-    lifecycle?.answerQuality && !lifecycle.answerQuality.passed ? "answer quality failed" : void 0,
-    lifecycle?.promotion && !lifecycle.promotion.promoted ? `promotion decision held: ${lifecycle.promotion.reason}` : void 0
+    blockingMissing === 0 ? void 0 : `${blockingMissing}/${blockingTotal} blocking knowledge requirements still missing`
   ].filter((reason) => Boolean(reason));
   return {
     score: average2(Object.values(dimensions)),
     passed: failedReasons.length === 0,
     dimensions,
-    notes: failedReasons.length === 0 ? "candidate passed configured checks" : failedReasons.join("; ")
+    notes: failedReasons.length === 0 ? "candidate passed configured checks" : failedReasons.join("; "),
+    provenance: {
+      evaluator: "@tangle-network/agent-knowledge/default-knowledge-improvement-metric",
+      version: "1",
+      method: "deterministic"
+    }
   };
 }
 function applyLifecycleFailures(metric, lifecycle) {
@@ -3839,33 +4589,126 @@ function applyLifecycleFailures(metric, lifecycle) {
   };
 }
 function normalizeMetric(metric) {
-  if (!Number.isFinite(metric.score) || metric.score < 0 || metric.score > 1) {
-    throw new Error(`knowledge improvement score must be in [0, 1], got ${String(metric.score)}`);
-  }
-  return { ...metric, passed: Boolean(metric.passed) };
+  return improvementMetricSchema.parse(metric);
 }
 async function createCandidateWorkspace(runDir, state, root, now) {
   const iteration = state.candidates.length + 1;
   const candidateId = stableId("kcand", `${state.runId}:${iteration}:${now().toISOString()}`);
-  const candidateRoot = join3(runDir, "candidates", candidateId, "workspace");
+  const candidateRoot = candidateWorkspacePath(runDir, candidateId);
   await copyKnowledgeWorkspace(root, candidateRoot);
   const createdAt = now().toISOString();
   return {
     iteration,
     candidateId,
-    candidateRoot,
     baseHash: state.baseHash,
     status: "running",
     createdAt,
     updatedAt: createdAt
   };
 }
+function candidateWorkspacePath(runDir, candidateId) {
+  return join3(runDir, "candidates", safePathSegmentSchema.parse(candidateId), "workspace");
+}
+function baselineSnapshotPath(runDir) {
+  return join3(runDir, "baseline");
+}
+async function createBaselineSnapshot(runDir, root, expectedHash) {
+  const target = baselineSnapshotPath(runDir);
+  try {
+    await assertBaselineSnapshot(runDir, expectedHash);
+    return;
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+  const preparation = await mkdtemp(join3(runDir, "baseline-prepare-"));
+  let activated = false;
+  try {
+    await copyKnowledgeWorkspace(root, preparation);
+    const actualHash = await hashKnowledgeBase(preparation);
+    if (actualHash !== expectedHash) {
+      throw new Error(
+        `knowledge base changed while baseline was frozen: expected ${expectedHash}, got ${actualHash}`
+      );
+    }
+    await renameDurable(preparation, target);
+    activated = true;
+  } finally {
+    if (!activated) await rm(preparation, { recursive: true, force: true });
+  }
+}
+async function ensureBaselineSnapshot(runDir, root, expectedHash) {
+  try {
+    await assertBaselineSnapshot(runDir, expectedHash);
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+    const liveHash = await hashKnowledgeBase(root);
+    if (liveHash !== expectedHash) {
+      throw new Error(
+        "knowledge improvement baseline snapshot is missing and cannot be reconstructed"
+      );
+    }
+    await createBaselineSnapshot(runDir, root, expectedHash);
+  }
+}
+async function assertBaselineSnapshot(runDir, expectedHash) {
+  await withBaselineSnapshot(runDir, expectedHash, () => void 0);
+}
+async function withBaselineSnapshot(runDir, expectedHash, use) {
+  return withSafeDirectory(runDir, "baseline", false, async (baselineRoot) => {
+    const actualHash = await hashKnowledgeBase(baselineRoot);
+    if (actualHash !== expectedHash) {
+      throw new Error(
+        `knowledge improvement baseline changed: expected ${expectedHash}, got ${actualHash}`
+      );
+    }
+    return use(baselineRoot);
+  });
+}
+async function withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, use) {
+  const snapshotsPath = join3(
+    "candidates",
+    safePathSegmentSchema.parse(candidate.candidateId),
+    "snapshots"
+  );
+  return withSafeDirectory(runDir, snapshotsPath, true, async (snapshotsDir) => {
+    const preparation = await mkdtemp(join3(snapshotsDir, "prepare-"));
+    let activated = false;
+    try {
+      await copyKnowledgeWorkspace(candidateRoot, preparation);
+      const hash = await hashKnowledgeBase(preparation);
+      try {
+        const result = await withSafeDirectory(snapshotsDir, hash, false, async (existing) => {
+          if (await hashKnowledgeBase(existing) !== hash) {
+            throw new Error("knowledge candidate snapshot does not match its content identity");
+          }
+          return use({ root: existing, hash });
+        });
+        await rm(preparation, { recursive: true, force: true });
+        activated = true;
+        return result;
+      } catch (error) {
+        if (!isMissingFile(error)) throw error;
+      }
+      await renameDurable(preparation, join3(snapshotsDir, hash));
+      activated = true;
+      return withSafeDirectory(snapshotsDir, hash, false, (root) => use({ root, hash }));
+    } finally {
+      if (!activated) await rm(preparation, { recursive: true, force: true });
+    }
+  });
+}
+function clearCandidateMeasurement(candidate) {
+  delete candidate.candidateHash;
+  delete candidate.evidenceHash;
+  delete candidate.promotionPlanHash;
+}
 function findActiveCandidate(state) {
   return [...state.candidates].reverse().find((candidate) => candidate.status === "candidate-ready" || candidate.status === "running");
 }
 async function copyKnowledgeWorkspace(sourceRoot, targetRoot) {
   await rm(targetRoot, { recursive: true, force: true });
-  await initKnowledgeBase(targetRoot);
+  await mkdir(join3(targetRoot, "knowledge"), { recursive: true });
+  await mkdir(join3(targetRoot, "raw", "sources"), { recursive: true });
   await copyIfExists(join3(sourceRoot, "knowledge"), join3(targetRoot, "knowledge"));
   await copyIfExists(join3(sourceRoot, "raw"), join3(targetRoot, "raw"));
   await copyIfExists(
@@ -3874,106 +4717,180 @@ async function copyKnowledgeWorkspace(sourceRoot, targetRoot) {
   );
   await writeKnowledgeIndex(targetRoot);
 }
-async function promoteCandidate(root, candidateRoot) {
-  await copyIfExists(join3(candidateRoot, "knowledge"), join3(root, "knowledge"), { replace: true });
-  await copyIfExists(join3(candidateRoot, "raw"), join3(root, "raw"), { replace: true });
-  await copyIfExists(
-    join3(layoutFor(candidateRoot).cacheDir, "sources.json"),
-    join3(layoutFor(root).cacheDir, "sources.json"),
-    { replace: true }
+function promotionTransactionPurpose(candidate) {
+  return `knowledge-promotion:${contentHash(candidate)}`;
+}
+async function promotionPlanEntries(baselineRoot, candidateRoot) {
+  const [before, after] = await Promise.all([
+    knowledgeHashEntries(baselineRoot),
+    knowledgeHashEntries(candidateRoot)
+  ]);
+  const beforeByPath = new Map(before.map((entry) => [entry.path, entry]));
+  const afterByPath = new Map(after.map((entry) => [entry.path, entry]));
+  const paths = [
+    .../* @__PURE__ */ new Set([...before.map((entry) => entry.path), ...after.map((entry) => entry.path)])
+  ].sort((left, right) => left.localeCompare(right));
+  return paths.map((path) => {
+    assertKnowledgeMutationPath(path);
+    const beforeEntry = beforeByPath.get(path);
+    const afterEntry = afterByPath.get(path);
+    return {
+      path,
+      beforeHash: beforeEntry?.transactionHash ?? null,
+      afterHash: afterEntry?.transactionHash ?? null,
+      ...beforeEntry ? { beforeMode: beforeEntry.mode } : {},
+      ...afterEntry ? { afterMode: afterEntry.mode } : {}
+    };
+  });
+}
+async function promotionMutations(candidateRoot, 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 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}`);
+      }
+      return { path: entry.path, content: file.bytes, mode: file.mode };
+    })
   );
-  await writeKnowledgeIndex(root);
 }
-async function copyIfExists(source, target, options = {}) {
-  try {
-    await stat(source);
-  } catch {
-    return;
+function assertPromotionTransaction(transaction, candidate) {
+  const actualPlanHash = knowledgeFileTransactionPlanHash(transaction.entries);
+  if (actualPlanHash !== candidate.promotionPlanHash) {
+    throw new Error(
+      `knowledge promotion plan changed after approval: expected ${candidate.promotionPlanHash}, got ${actualPlanHash}`
+    );
   }
-  if (options.replace) await rm(target, { recursive: true, force: true });
-  await mkdir3(dirname2(target), { recursive: true });
-  await cp(source, target, { recursive: true });
 }
-async function hashKnowledgeBase(root) {
-  const entries = [];
-  for (const rel of ["knowledge", "raw"]) {
-    entries.push(...await hashTreeEntries(root, rel));
+async function ensurePromotionEvent(runDir, candidateRef) {
+  if (await hasPromotionEvent(runDir, candidateRef)) return;
+  await appendLedger(runDir, {
+    type: "candidate.promoted",
+    runId: candidateRef.runId,
+    candidateId: candidateRef.candidateId,
+    candidateHash: candidateRef.candidateHash,
+    evidenceHash: candidateRef.evidenceHash,
+    promotionPlanHash: candidateRef.promotionPlanHash
+  });
+}
+async function hasPromotionEvent(runDir, candidateRef) {
+  let matched = false;
+  for (const row of await loadKnowledgeImprovementEventsFromRun(runDir)) {
+    if (row.type !== "candidate.promoted" || 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");
+    }
+    matched = true;
   }
-  const sourceRegistry = relative(root, layoutFor(root).sourceRegistryPath).replace(/\\/g, "/");
-  entries.push(...await hashFileEntry(root, sourceRegistry));
-  entries.sort((a, b) => a.path.localeCompare(b.path));
-  return sha256(JSON.stringify(entries));
+  return matched;
 }
-async function hashTreeEntries(root, relDir) {
-  const abs = join3(root, relDir);
+async function loadKnowledgeImprovementEvents(root, runId) {
+  const parsedRunId = runIdSchema.parse(runId);
   try {
-    const s = await stat(abs);
-    if (!s.isDirectory()) return [];
-  } catch {
-    return [];
-  }
-  const out = [];
-  const entries = await readdir(abs, { withFileTypes: true });
-  for (const entry of entries) {
-    const rel = join3(relDir, entry.name).replace(/\\/g, "/");
-    if (entry.isDirectory()) out.push(...await hashTreeEntries(root, rel));
-    else if (entry.isFile()) out.push(...await hashFileEntry(root, rel));
+    return await withKnowledgeImprovementRun(
+      root,
+      parsedRunId,
+      false,
+      (runDir) => loadKnowledgeImprovementEventsFromRun(runDir)
+    );
+  } catch (error) {
+    if (isMissingFile(error)) return [];
+    throw error;
   }
-  return out;
 }
-async function hashFileEntry(root, rel) {
+async function loadKnowledgeImprovementEventsFromRun(runDir) {
+  const events = [];
   try {
-    const bytes = await readFile2(join3(root, rel));
-    return [{ path: rel, hash: sha256(bytes.toString("base64")) }];
-  } catch {
-    return [];
+    for (const file of await listRegularFilesWithinRoot(runDir, "events")) {
+      const name = file.path.slice("events/".length);
+      if (name.includes("/") || !name.endsWith(".json")) {
+        throw new Error(`knowledge event store contains an unsupported entry: ${name}`);
+      }
+      events.push(parseKnowledgeImprovementEvent(JSON.parse(file.bytes.toString("utf8"))));
+    }
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+  const unique2 = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const { at: _at, ...semantic } = event;
+    unique2.set(contentHash(semantic), event);
   }
+  return [...unique2.values()].sort((left, right) => left.at.localeCompare(right.at));
 }
-async function acquireRunLease(runDir, options) {
-  const path = join3(runDir, "run.lock");
-  const now = options.now();
-  const expiresAt = new Date(now.getTime() + options.ttlMs);
-  const payload = {
-    ownerId: options.ownerId,
-    acquiredAt: now.toISOString(),
-    expiresAt: expiresAt.toISOString(),
-    pid: process.pid
-  };
+function parseKnowledgeImprovementEvent(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("knowledge improvement event is not an object");
+  }
+  const event = value;
+  if (typeof event.at !== "string" || typeof event.type !== "string") {
+    throw new Error("knowledge improvement event is missing at or type");
+  }
+  return event;
+}
+async function copyIfExists(source, target) {
+  let sourceStat;
   try {
-    const handle = await open(path, "wx");
+    sourceStat = await lstat(source);
+  } catch (error) {
+    if (isMissingFile(error)) return;
+    throw error;
+  }
+  if (!sourceStat.isDirectory() && !sourceStat.isFile()) {
+    throw new Error(`knowledge surface contains an unsupported filesystem entry: ${source}`);
+  }
+  await mkdir(dirname(target), { recursive: true });
+  await cp(source, target, { recursive: sourceStat.isDirectory(), dereference: false });
+}
+async function hashKnowledgeBase(root) {
+  return withKnowledgeRead(root, () => hashKnowledgeBaseUnlocked(root));
+}
+async function hashKnowledgeBaseUnlocked(root) {
+  const entries = await knowledgeHashEntries(root);
+  return sha256(JSON.stringify(entries.map(({ path, hash, mode }) => ({ path, hash, mode }))));
+}
+async function knowledgeHashEntries(root) {
+  const entries = [];
+  for (const rel of ["knowledge", "raw"]) {
     try {
-      await handle.writeFile(`${JSON.stringify(payload, null, 2)}
-`, "utf8");
-    } finally {
-      await handle.close();
+      for (const file of await listRegularFilesWithinRoot(root, rel)) {
+        entries.push(knowledgeFileIdentity(file.path, file.bytes, file.mode));
+      }
+    } catch (error) {
+      if (!isMissingFile(error)) throw error;
     }
+  }
+  const sourceRegistry = relative(root, layoutFor(root).sourceRegistryPath).replace(/\\/g, "/");
+  try {
+    const file = await readRegularFileWithinRoot(root, sourceRegistry);
+    entries.push(knowledgeFileIdentity(sourceRegistry, file.bytes, file.mode));
   } catch (error) {
-    const code = error.code;
-    if (code !== "EEXIST") throw error;
-    const existing = await readLease(path);
-    if (existing && new Date(existing.expiresAt).getTime() > now.getTime()) {
-      throw new Error(
-        `knowledge improvement run is locked by ${existing.ownerId} until ${existing.expiresAt}`
-      );
-    }
-    await rm(path, { force: true });
-    return acquireRunLease(runDir, options);
+    if (!isMissingFile(error)) throw error;
   }
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  return entries;
+}
+function knowledgeFileIdentity(path, bytes, mode) {
   return {
-    ownerId: options.ownerId,
     path,
-    async release() {
-      const current = await readLease(path);
-      if (!current || current.ownerId === options.ownerId) await rm(path, { force: true });
-    }
+    hash: sha256(bytes.toString("base64")),
+    transactionHash: createHash("sha256").update(bytes).digest("hex"),
+    mode
   };
 }
-async function readLease(path) {
-  try {
-    return JSON.parse(await readFile2(path, "utf8"));
-  } catch {
-    return null;
-  }
+async function acquireRunLease(runDir, options) {
+  const path = join3(runDir, "run.lock.durable");
+  const acquired = await acquireDurableFileLock(runDir, {
+    lockfilePath: path,
+    staleMs: options.ttlMs
+  });
+  return {
+    ownerId: options.ownerId,
+    assertOwned: acquired.assertOwned,
+    release: acquired.release
+  };
 }
 async function blockRun(runDir, state, reason, onState, now) {
   state.status = "blocked";
@@ -3983,24 +4900,51 @@ async function blockRun(runDir, state, reason, onState, now) {
   return state;
 }
 async function saveState(runDir, state, onState) {
-  await writeJsonAtomic(statePath(runDir), state);
+  await writeJsonDurableWithinRoot(
+    runDir,
+    "state.json",
+    KnowledgeImprovementRunStateSchema.parse(state)
+  );
   await onState?.(state);
 }
 async function appendLedger(runDir, value) {
-  const row = { at: (/* @__PURE__ */ new Date()).toISOString(), ...value };
-  await mkdir3(runDir, { recursive: true });
-  await writeFile3(join3(runDir, "events.jsonl"), `${JSON.stringify(row)}
-`, { flag: "a" });
+  const type = value.type;
+  if (typeof type !== "string" || type.length === 0) {
+    throw new Error("knowledge improvement event requires a type");
+  }
+  const relativePath = join3("events", `${contentHash(value)}.json`).replace(/\\/g, "/");
+  try {
+    const file = await readRegularFileWithinRoot(runDir, relativePath);
+    const existing = parseKnowledgeImprovementEvent(JSON.parse(file.bytes.toString("utf8")));
+    const { at: _at, ...semantic } = existing;
+    if (canonicalJson(semantic) !== canonicalJson(value)) {
+      throw new Error("knowledge improvement event identity conflicts with durable content");
+    }
+    return;
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+  await writeJsonDurableWithinRoot(runDir, relativePath, {
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    ...value
+  });
 }
-async function writeJsonAtomic(path, value) {
-  await mkdir3(dirname2(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile3(tmp, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-  await rename(tmp, path);
+function candidateEvidenceRelativePath(candidateId) {
+  return join3("candidates", safePathSegmentSchema.parse(candidateId), "evidence.json").replace(
+    /\\/g,
+    "/"
+  );
+}
+function descendantPath(root, path) {
+  const value = relative(resolve(root), resolve(path)).replace(/\\/g, "/");
+  if (value === "" || value === ".." || value.startsWith("../") || isAbsolute(value))
+    return void 0;
+  return value;
 }
-function statePath(runDir) {
-  return join3(runDir, "state.json");
+function assertExactCandidatePlatform() {
+  if (process.platform !== "linux") {
+    throw new Error("exact knowledge candidate workflows require Linux directory descriptors");
+  }
 }
 function average2(values) {
   const finite = values.filter(Number.isFinite);
@@ -4009,8 +4953,7 @@ function average2(values) {
 }
 
 // src/kb-store.ts
-import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname3, join as join4 } from "path";
+import { z as z3 } from "zod";
 var MemoryKbStore = class {
   sources = /* @__PURE__ */ new Map();
   pages = /* @__PURE__ */ new Map();
@@ -4062,33 +5005,115 @@ var MemoryKbStore = class {
     return out.slice(-(query.limit ?? out.length)).map(clone);
   }
 };
-var FileSystemKbStore = class extends MemoryKbStore {
+var knowledgeEventsSchema = z3.array(KnowledgeEventSchema);
+var FileSystemKbStore = class {
   constructor(dir) {
-    super();
     this.dir = dir;
   }
   dir;
+  async putSource(source) {
+    const parsed = SourceRecordSchema.parse(source);
+    await this.updateIndex((index) => ({
+      ...index,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sources: [parsed, ...index.sources.filter((entry) => entry.id !== parsed.id)]
+    }));
+  }
+  async getSource(id) {
+    return withKnowledgeRead(this.dir, async () => {
+      const index = await this.readIndex();
+      return clone(index?.sources.find((source) => source.id === id) ?? null);
+    });
+  }
+  async listSources() {
+    return withKnowledgeRead(this.dir, async () => clone((await this.readIndex())?.sources ?? []));
+  }
+  async putPage(page) {
+    const parsed = KnowledgePageSchema.parse(page);
+    await this.updateIndex((index) => {
+      const pages = [parsed, ...index.pages.filter((entry) => entry.id !== parsed.id)];
+      return {
+        ...index,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        pages,
+        graph: buildKnowledgeGraph(pages)
+      };
+    });
+  }
+  async getPage(idOrPath) {
+    return withKnowledgeRead(this.dir, async () => {
+      const index = await this.readIndex();
+      return clone(
+        index?.pages.find((page) => page.id === idOrPath || page.path === idOrPath) ?? null
+      );
+    });
+  }
+  async listPages() {
+    return withKnowledgeRead(this.dir, async () => clone((await this.readIndex())?.pages ?? []));
+  }
   async putIndex(index) {
-    await super.putIndex(index);
-    await writeJson2(join4(this.dir, "index.json"), index);
+    const parsed = KnowledgeIndexSchema.parse(index);
+    await withKnowledgeMutation(
+      this.dir,
+      () => writeJsonDurableWithinRoot(this.dir, "index.json", parsed)
+    );
   }
   async getIndex() {
-    try {
-      return JSON.parse(await readFile3(join4(this.dir, "index.json"), "utf8"));
-    } catch {
-      return await super.getIndex();
-    }
+    return withKnowledgeRead(this.dir, () => this.readIndex());
   }
   async putEvent(event) {
-    await super.putEvent(event);
-    const events = await this.listEvents();
-    await writeJson2(join4(this.dir, "events.json"), events);
+    const parsed = KnowledgeEventSchema.parse(event);
+    await withKnowledgeMutation(this.dir, async () => {
+      const current = await this.readEvents();
+      const next = [...current.filter((entry) => entry.id !== parsed.id), parsed].sort(
+        (a, b) => a.createdAt.localeCompare(b.createdAt)
+      );
+      await writeJsonDurableWithinRoot(this.dir, "events.json", next);
+    });
+  }
+  async listEvents(query = {}) {
+    return withKnowledgeRead(this.dir, async () => {
+      let events = await this.readEvents();
+      if (query.type) events = events.filter((event) => event.type === query.type);
+      if (query.target) events = events.filter((event) => event.target === query.target);
+      return clone(events.slice(-(query.limit ?? events.length)));
+    });
+  }
+  async updateIndex(change) {
+    await withKnowledgeMutation(this.dir, async () => {
+      const current = await this.readIndex() ?? emptyIndex2(this.dir);
+      const next = KnowledgeIndexSchema.parse(change(current));
+      await writeJsonDurableWithinRoot(this.dir, "index.json", next);
+    });
+  }
+  async readIndex() {
+    return readJsonFile(
+      this.dir,
+      "index.json",
+      KnowledgeIndexSchema
+    );
+  }
+  async readEvents() {
+    return await readJsonFile(this.dir, "events.json", knowledgeEventsSchema) ?? [];
   }
 };
-async function writeJson2(path, value) {
-  await mkdir4(dirname3(path), { recursive: true });
-  await writeFile4(path, `${JSON.stringify(value, null, 2)}
-`, "utf8");
+function emptyIndex2(root) {
+  return {
+    root,
+    generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+    sources: [],
+    pages: [],
+    graph: { nodes: [], edges: [] }
+  };
+}
+async function readJsonFile(root, relativePath, schema) {
+  try {
+    const file = await readRegularFileWithinRoot(root, relativePath);
+    return schema.parse(JSON.parse(file.bytes.toString("utf8")));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
 }
 function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
@@ -4330,11 +5355,11 @@ async function evaluateKnowledgeBaseReadiness(options) {
 // src/release.ts
 import {
   evaluateReleaseConfidence,
-  validateRunRecord
+  validateRunRecord as validateRunRecord2
 } from "@tangle-network/agent-eval";
 function knowledgeReleaseReport(input) {
   const baselineRuns = input.baselineRuns ?? [];
-  const runRecords = [...input.candidateRuns, ...baselineRuns].map(validateRunRecord);
+  const runRecords = [...input.candidateRuns, ...baselineRuns].map(validateRunRecord2);
   const scorecard = evaluateReleaseConfidence({
     target: "agent-knowledge-base",
     candidateId: input.candidateId,
@@ -4782,6 +5807,9 @@ export {
   KnowledgeEventSchema,
   KnowledgeGraphEdgeSchema,
   KnowledgeGraphNodeSchema,
+  KnowledgeImprovementCandidateRefSchema,
+  KnowledgeImprovementEvidenceSchema,
+  KnowledgeImprovementRunStateSchema,
   KnowledgeIndexSchema,
   KnowledgePageSchema,
   KnowledgeProposalParseError,
@@ -4860,18 +5888,21 @@ export {
   initKnowledgeBase,
   innerHtmlById,
   inspectKnowledgeIndex,
+  inspectPendingKnowledgeMutation,
   investmentThesisSet,
   isKnowledgeMemoryBenchmarkCase,
   isSafeKnowledgePath,
   isScaffoldPath,
   kbIndexToText,
   knowledgeBenchmarkJudge,
+  knowledgeImprovementCandidateRef,
   knowledgeImprovementRunDir,
   knowledgeImprovementRunId,
   knowledgeReleaseReport,
   layoutFor,
   lensDistribution,
   lintKnowledgeIndex,
+  loadKnowledgeImprovementEvents,
   loadKnowledgeImprovementState,
   loadKnowledgePages,
   loadSourceRegistry,
@@ -4888,10 +5919,12 @@ export {
   parseKnowledgeBenchmarkQrels,
   parseKnowledgeWriteBlocks,
   politeFetch,
+  promoteKnowledgeCandidate,
   proposeFromFinding,
   proposeFromFindings,
   ragAnswerQualityJudge,
   reciprocalRankFusion,
+  recoverPendingKnowledgeMutation,
   renderKnowledgeBenchmarkReportMarkdown,
   renderMemoryContext,
   resetRetrievalHoldoutRegistry,
@@ -4936,6 +5969,7 @@ export {
   triageSource,
   validateKnowledgeIndex,
   withCitedClaim,
+  withKnowledgeImprovementCandidate,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry