@tangle-network/agent-knowledge 4.1.0 → 5.0.0

package/dist/{chunk-CPMLJYA3.js → chunk-LMR53POQ.js}

@@ -11,14 +11,13 @@ import {
   memoryWriteResultToSourceRecord,
   readActiveAttemptJournal,
   reconcileInterruptedMemoryPaidCalls,
-  reconcileInterruptedRunPaidCalls,
   releaseMemoryAdapterCreatedAfterAbort,
   reserveRecoveryAttempts,
   resolveMemoryCleanupTimeoutMs,
   runBoundedMemoryLifecycle,
   scoreMemoryBenchmarkArtifact,
   sleepForMemoryRecovery
-} from "./chunk-BBCIB4UL.js";
+} from "./chunk-EYIA5PLQ.js";
 import {
   sha256,
   stableId
@@ -1198,6 +1197,165 @@ import {
 // src/memory/experiment/cell.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
+// src/memory/experiment/cost.ts
+function createAgentMemoryCostRecorder(input) {
+  let observedCostUsd = 0;
+  let receiptCount = 0;
+  return {
+    record(actualCostUsd) {
+      if (!Number.isFinite(actualCostUsd) || actualCostUsd < 0) {
+        throw new Error(
+          `${input.operation}: observed external cost must be non-negative and finite`
+        );
+      }
+      const next = observedCostUsd + actualCostUsd;
+      if (exceedsMaximum(next, input.maximumCostUsd)) {
+        throw new Error(
+          `${input.operation}: observed external cost ${next} exceeds declared maximum ${input.maximumCostUsd}`
+        );
+      }
+      observedCostUsd = next;
+      receiptCount += 1;
+    },
+    receipt(externalCallAttempted) {
+      const base = {
+        model: input.candidateRef,
+        inputTokens: 0,
+        outputTokens: 0
+      };
+      if (input.maximumCostUsd === 0 || !externalCallAttempted) {
+        return { ...base, actualCostUsd: 0 };
+      }
+      if (receiptCount === 0) {
+        return { ...base, costUnknown: true };
+      }
+      return { ...base, actualCostUsd: observedCostUsd };
+    }
+  };
+}
+function exceedsMaximum(actual, maximum) {
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(actual), Math.abs(maximum)) * 8;
+  return actual - maximum > tolerance;
+}
+
+// src/memory/experiment/execution-context.ts
+function createAgentMemoryExecutionContext(dispatch, sequence) {
+  const privateValues = memoryEvaluationPrivateValues(dispatch.cellId, sequence);
+  const signal = relayAbortWithoutReason(dispatch.signal);
+  const cost = Object.freeze({
+    async runPaidCall(input) {
+      const result = await dispatch.cost.runPaidCall({
+        ...input,
+        execute: (sourceSignal, callId) => withRedactedAbortSignal(
+          sourceSignal,
+          (redactedSignal) => input.execute(redactedSignal, callId)
+        )
+      });
+      return sanitizePaidCallResult(result, privateValues);
+    }
+  });
+  return {
+    context: Object.freeze({ signal: signal.signal, cost }),
+    dispose: signal.dispose
+  };
+}
+function sanitizePaidCallResult(result, privateValues) {
+  if (result.succeeded) {
+    return Object.freeze({
+      succeeded: true,
+      callId: result.callId,
+      value: result.value,
+      receipt: sanitizeCostReceipt(result.receipt, privateValues)
+    });
+  }
+  return Object.freeze({
+    succeeded: false,
+    ...result.callId === void 0 ? {} : { callId: result.callId },
+    error: sanitizeError(result.error, privateValues),
+    ...result.receipt === void 0 ? {} : { receipt: sanitizeCostReceipt(result.receipt, privateValues) }
+  });
+}
+function sanitizeCostReceipt(receipt, privateValues) {
+  const { tags: _tags, phase: _phase, error, ...visible } = receipt;
+  return Object.freeze({
+    ...visible,
+    ...error === void 0 ? {} : { error: redactPrivateValues(error, privateValues) }
+  });
+}
+function sanitizeError(error, privateValues) {
+  const sanitized = new Error(redactPrivateValues(error.message, privateValues));
+  sanitized.name = redactPrivateValues(error.name, privateValues);
+  return sanitized;
+}
+async function withRedactedAbortSignal(source, run) {
+  const relay = relayAbortWithoutReason(source);
+  try {
+    return await run(relay.signal);
+  } finally {
+    relay.dispose();
+  }
+}
+function relayAbortWithoutReason(source) {
+  const controller = new AbortController();
+  const abort = () => controller.abort(memoryExecutionAbortError());
+  if (source.aborted) abort();
+  else source.addEventListener("abort", abort, { once: true });
+  return {
+    signal: controller.signal,
+    dispose() {
+      source.removeEventListener("abort", abort);
+    }
+  };
+}
+function memoryExecutionAbortError() {
+  const error = new Error("memory execution aborted");
+  error.name = "AbortError";
+  return error;
+}
+function memoryEvaluationPrivateValues(cellId, sequence) {
+  const values = /* @__PURE__ */ new Set([cellId, sequence.id]);
+  collectUnknownStrings(sequence.metadata, values);
+  for (const step of sequence.steps) {
+    values.add(step.id);
+    collectUnknownStrings(step.metadata, values);
+    for (const probe of step.probes ?? []) {
+      values.add(probe.id);
+      values.add(probe.query);
+      if (probe.referenceAnswer !== void 0) values.add(probe.referenceAnswer);
+      for (const matcher of [...probe.requiredFacts ?? [], ...probe.forbiddenFacts ?? []]) {
+        values.add(matcher.id);
+        for (const expected of matcher.anyOf) values.add(expected);
+      }
+      for (const expected of probe.expectedEventIds ?? []) values.add(expected);
+      for (const expected of probe.expectedActorIds ?? []) values.add(expected);
+    }
+  }
+  return [...values].filter(Boolean).sort((left, right) => right.length - left.length);
+}
+function collectUnknownStrings(value, output, seen = /* @__PURE__ */ new WeakSet()) {
+  if (typeof value === "string") {
+    output.add(value);
+    return;
+  }
+  if (!value || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) collectUnknownStrings(item, output, seen);
+    return;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    output.add(key);
+    collectUnknownStrings(item, output, seen);
+  }
+}
+function redactPrivateValues(value, privateValues) {
+  let redacted = value;
+  for (const privateValue of privateValues) {
+    redacted = redacted.split(privateValue).join("[redacted]");
+  }
+  return redacted;
+}
+
 // src/memory/experiment/metrics.ts
 function rankAgentMemoryExperiment(candidates, scenarios, campaign, costByCandidate) {
   const scenarioById = new Map(scenarios.map((scenario) => [scenario.id, scenario]));
@@ -1451,6 +1609,11 @@ async function recoverAbandonedMemoryAttempts(input) {
           throw new Error(`missing recovery generation for memory branch '${attempt.branchId}'`);
         }
         let externalRecoveryAttempted = false;
+        const costRecorder = createAgentMemoryCostRecorder({
+          candidateRef: candidate.ref,
+          maximumCostUsd: recoveryCostUsd,
+          operation: `${candidate.id}: memory recovery`
+        });
         const recover = async () => {
           await recoverMemoryAttempt({
             options: input.options,
@@ -1460,6 +1623,10 @@ async function recoverAbandonedMemoryAttempts(input) {
             lease: input.lease,
             onExternalCall: () => {
               externalRecoveryAttempted = true;
+            },
+            recordExternalCost: (actualCostUsd) => {
+              externalRecoveryAttempted = true;
+              costRecorder.record(actualCostUsd);
             }
           });
           appendMemoryAttemptEvent(input.storage, input.attemptLogPath, {
@@ -1473,29 +1640,17 @@ async function recoverAbandonedMemoryAttempts(input) {
           await recover();
         } else {
           const tags = memoryRecoveryCostTags(input.runDir, candidate.id, attempt.branchId);
-          const receipt = {
-            model: candidate.id,
-            inputTokens: 0,
-            outputTokens: 0,
-            actualCostUsd: recoveryCostUsd
-          };
           const paid = await input.costLedger.runPaidCall({
             callId: memoryAttemptCostCallId(attempt, "recovery", recoveryGeneration),
             channel: "driver",
             phase: `${input.options.costPhase ?? "memory.experiment"}.recovery`,
             actor: `agent-knowledge:memory-recovery:${candidate.id}`,
-            model: candidate.id,
+            model: candidate.ref,
             tags,
             maximumCharge: { externallyEnforcedMaximumUsd: recoveryCostUsd },
             execute: recover,
-            receipt: () => ({
-              ...receipt,
-              actualCostUsd: externalRecoveryAttempted ? recoveryCostUsd : 0
-            }),
-            receiptFromError: () => ({
-              ...receipt,
-              actualCostUsd: externalRecoveryAttempted ? recoveryCostUsd : 0
-            })
+            receipt: () => costRecorder.receipt(externalRecoveryAttempted),
+            receiptFromError: () => costRecorder.receipt(externalRecoveryAttempted)
           });
           if (!paid.succeeded) throw paid.error;
         }
@@ -1511,7 +1666,7 @@ async function recoverAbandonedMemoryAttempts(input) {
   }
 }
 async function recoverMemoryAttempt(input) {
-  const { options, candidate, sequence, attempt, lease, onExternalCall } = input;
+  const { options, candidate, sequence, attempt, lease, onExternalCall, recordExternalCost } = input;
   const cleanupBranches = attempt.cleanupBranches;
   const cleanupTimeoutMs = resolveMemoryCleanupTimeoutMs(
     options.cleanupTimeoutMs,
@@ -1526,12 +1681,11 @@ async function recoverMemoryAttempt(input) {
     const creation = Promise.resolve().then(
       () => candidate.createAdapter({
         branchId: attempt.branchId,
-        sequence,
-        rep: attempt.rep,
-        seed: attempt.seed,
         purpose: "recovery",
         signal: abortController.signal,
-        markExternalCall: onExternalCall
+        maximumCostUsd: candidate.externalRecoveryCostUsdPerAttempt ?? 0,
+        markExternalCall: onExternalCall,
+        recordExternalCost
       })
     );
     releaseMemoryAdapterCreatedAfterAbort({
@@ -1666,7 +1820,6 @@ function memoryRecoveryCostTags(runDir, candidateId, branchId) {
 }
 function memoryAttemptEvent(input) {
   return {
-    schema: 2,
     status: input.status,
     branchId: input.branchId,
     candidateId: input.candidate.id,
@@ -1701,7 +1854,7 @@ function readActiveMemoryAttempts(storage, path) {
 }
 function parseMemoryAttemptEvent(value, path, line) {
   const event = value;
-  const valid = typeof event === "object" && event !== null && event.schema === 2 && (event.status === "started" || event.status === "cleaned") && typeof event.branchId === "string" && event.branchId.length > 0 && typeof event.candidateId === "string" && event.candidateId.length > 0 && typeof event.candidateRef === "string" && event.candidateRef.length > 0 && typeof event.sequenceId === "string" && event.sequenceId.length > 0 && Number.isSafeInteger(event.rep) && Number.isSafeInteger(event.seed) && typeof event.cleanupBranches === "boolean" && typeof event.externalCostUsdPerSequence === "number" && Number.isFinite(event.externalCostUsdPerSequence) && event.externalCostUsdPerSequence >= 0 && typeof event.externalRecoveryCostUsdPerAttempt === "number" && Number.isFinite(event.externalRecoveryCostUsdPerAttempt) && event.externalRecoveryCostUsdPerAttempt >= 0 && typeof event.recordedAt === "string" && !Number.isNaN(Date.parse(event.recordedAt)) && typeof event.recovery === "boolean";
+  const valid = typeof event === "object" && event !== null && (event.status === "started" || event.status === "cleaned") && typeof event.branchId === "string" && event.branchId.length > 0 && typeof event.candidateId === "string" && event.candidateId.length > 0 && typeof event.candidateRef === "string" && event.candidateRef.length > 0 && typeof event.sequenceId === "string" && event.sequenceId.length > 0 && Number.isSafeInteger(event.rep) && Number.isSafeInteger(event.seed) && typeof event.cleanupBranches === "boolean" && typeof event.externalCostUsdPerSequence === "number" && Number.isFinite(event.externalCostUsdPerSequence) && event.externalCostUsdPerSequence >= 0 && typeof event.externalRecoveryCostUsdPerAttempt === "number" && Number.isFinite(event.externalRecoveryCostUsdPerAttempt) && event.externalRecoveryCostUsdPerAttempt >= 0 && typeof event.recordedAt === "string" && !Number.isNaN(Date.parse(event.recordedAt)) && typeof event.recovery === "boolean";
   if (!valid) throw new Error(`invalid memory attempt event in '${path}' line ${line}`);
   return value;
 }
@@ -1762,6 +1915,11 @@ async function runSequenceCell(input) {
   });
   appendMemoryAttemptEvent(storage, attemptLogPath, attempt);
   let externalCallAttempted = false;
+  const costRecorder = createAgentMemoryCostRecorder({
+    candidateRef: candidate.ref,
+    maximumCostUsd: costUsd,
+    operation: `${candidate.id}: memory sequence`
+  });
   const appendCleanedAttempt = (priorError) => {
     try {
       appendMemoryAttemptEvent(storage, attemptLogPath, {
@@ -1789,13 +1947,15 @@ async function runSequenceCell(input) {
     try {
       const created = await candidate.createAdapter({
         branchId,
-        sequence: scenario.sequence,
-        rep: context.rep,
-        seed: context.seed,
         purpose: "execute",
         signal: context.signal,
+        maximumCostUsd: costUsd,
         markExternalCall: () => {
           externalCallAttempted = true;
+        },
+        recordExternalCost: (actualCostUsd) => {
+          externalCallAttempted = true;
+          costRecorder.record(actualCostUsd);
         }
       });
       if (!created) throw new Error(`${candidate.id}: createAdapter returned no execution adapter`);
@@ -1819,18 +1979,24 @@ async function runSequenceCell(input) {
         baseScope: memoryExperimentBaseScope(options, candidate, scenario.sequenceId)
       });
       const probes = [];
-      for (const step of scenario.sequence.steps) {
+      for (const [ordinal, step] of scenario.sequence.steps.entries()) {
         context.signal.throwIfAborted();
         await lease.assertOwned();
         await writeStep(memory, step);
         await lease.assertOwned();
-        await options.executeStep?.({
-          memory,
-          candidateId: candidate.id,
-          sequence: scenario.sequence,
-          step,
-          context
-        });
+        if (options.executeStep) {
+          const execution = createAgentMemoryExecutionContext(context, scenario.sequence);
+          try {
+            await options.executeStep({
+              memory,
+              candidateId: candidate.id,
+              step: executionStep(step, ordinal),
+              context: execution.context
+            });
+          } finally {
+            execution.dispose();
+          }
+        }
         context.signal.throwIfAborted();
         await lease.assertOwned();
         const stepProbes = await probeStep(memory, scenario.sequence, step);
@@ -1970,27 +2136,25 @@ async function runSequenceCell(input) {
     if (!artifact) throw new Error(`${candidate.id}: memory sequence produced no result`);
     return artifact;
   }
-  const receipt = {
-    model: candidate.id,
-    inputTokens: 0,
-    outputTokens: 0,
-    actualCostUsd: costUsd
-  };
   const paid = await context.cost.runPaidCall({
     callId: memoryAttemptCostCallId(attempt, "execute", 0),
     actor: `agent-knowledge:memory-experiment:${candidate.id}`,
-    model: candidate.id,
+    model: candidate.ref,
     maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
     execute,
-    receipt: () => receipt,
-    receiptFromError: () => ({
-      ...receipt,
-      actualCostUsd: externalCallAttempted ? costUsd : 0
-    })
+    receipt: () => costRecorder.receipt(externalCallAttempted),
+    receiptFromError: () => costRecorder.receipt(externalCallAttempted)
   });
   if (!paid.succeeded) throw paid.error;
   return paid.value;
 }
+function executionStep(step, ordinal) {
+  return {
+    ordinal,
+    ...step.instruction !== void 0 ? { instruction: step.instruction } : {},
+    ...step.scope !== void 0 ? { scope: structuredClone(step.scope) } : {}
+  };
+}
 async function writeStep(memory, step) {
   const writes = (step.writes ?? []).map((write) => ({
     ...write,
@@ -2093,6 +2257,12 @@ async function runAgentMemoryExperiment(options) {
         `${candidate.id}: externalRecoveryCostUsdPerAttempt must be a non-negative finite number`
       );
     }
+    if (candidate.externalCostAccounting !== void 0 && candidate.externalCostAccounting !== "exact") {
+      throw new Error(`${candidate.id}: externalCostAccounting must be 'exact'`);
+    }
+    if (((candidate.externalCostUsdPerSequence ?? 0) > 0 || (candidate.externalRecoveryCostUsdPerAttempt ?? 0) > 0) && candidate.externalCostAccounting !== "exact") {
+      throw new Error(`${candidate.id}: positive external charges require exact cost accounting`);
+    }
     assertNonEmptyString(candidate.ref, `${candidate.id} ref`);
   }
   const storage = options.storage ?? fsCampaignStorage();
@@ -2314,7 +2484,8 @@ function memoryExperimentDispatchRef(options) {
         policy: candidate.policy ?? null,
         baseScope: candidate.baseScope ?? null,
         externalCostUsdPerSequence: candidate.externalCostUsdPerSequence ?? 0,
-        externalRecoveryCostUsdPerAttempt: candidate.externalRecoveryCostUsdPerAttempt ?? 0
+        externalRecoveryCostUsdPerAttempt: candidate.externalRecoveryCostUsdPerAttempt ?? 0,
+        externalCostAccounting: candidate.externalCostAccounting ?? "exact"
       })).sort((a, b) => a.id.localeCompare(b.id))
     })
   );
@@ -2741,141 +2912,302 @@ function graphitiMemoryAdapterIdentity(options) {
   if (typeof options.backendRef !== "string" || !options.backendRef.trim()) {
     throw new Error("Graphiti backendRef must be a non-empty string");
   }
-  return stableId("graphiti", canonicalJson5(stripUndefined2(options)));
+  return `sha256:${sha256(canonicalJson5(stripUndefined2(options)))}`;
 }
 
 // src/memory/improvement/run.ts
-import { join as join3 } from "path";
-import { canonicalJson as canonicalJson7 } from "@tangle-network/agent-eval";
+import { join as join5 } from "path";
+import { canonicalJson as canonicalJson10 } from "@tangle-network/agent-eval";
 import {
-  campaignLineageStore,
-  createRunCostLedger as createRunCostLedger2,
   fsCampaignStorage as fsCampaignStorage2,
-  memLineageStore,
   resolveRunDir as resolveRunDir2,
-  runLineageLoop,
-  surfaceHash as surfaceHash2
+  surfaceHash as surfaceHash5
 } from "@tangle-network/agent-eval/campaign";
 
-// src/memory/improvement/activation.ts
-function appendMemoryActivationEvent(storage, path, event) {
-  appendDurableJournalEvent({
-    storage,
-    path,
-    event,
-    label: "memory activation journal"
+// src/optimization.ts
+import { canonicalJson as canonicalJson6 } from "@tangle-network/agent-eval";
+import {
+  compareOptimizationMethods,
+  surfaceHash
+} from "@tangle-network/agent-eval/campaign";
+
+// src/immutable-ref.ts
+var SHA256_REF = /^sha256:[a-f0-9]{64}$/;
+var GIT_REF = /^git:[a-f0-9]{40}$/;
+function assertImmutableRef(value, label) {
+  if (typeof value !== "string" || !SHA256_REF.test(value) && !GIT_REF.test(value)) {
+    throw new Error(`${label} must be lowercase sha256:<64 hex> or git:<40 hex>`);
+  }
+}
+
+// src/optimization.ts
+async function runSerializedKnowledgeOptimization(options) {
+  assertCompleteOptimizationMethod(options.method);
+  assertImmutableRef(options.executionRef, "knowledge optimization executionRef");
+  const codec = options.codec ?? jsonCandidateCodec();
+  const baseline = normalizeCandidate(options.baseline, codec, "baseline");
+  const dispatchRef = [
+    "knowledge-optimization",
+    options.executionRef,
+    baseline.surfaceHash,
+    surfaceHash(options.method.name)
+  ].join(":");
+  assertPartitionContent(
+    options.trainScenarios,
+    options.selectionScenarios,
+    options.finalScenarios,
+    options.scenarioFingerprint ?? scenarioContentFingerprint
+  );
+  const method = canonicalCandidateMethod(options.method, codec);
+  const {
+    baseline: _baseline,
+    method: _method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    dispatchCandidate,
+    executionRef: _executionRef,
+    codec: _codec,
+    scenarioFingerprint: _scenarioFingerprint,
+    ...comparisonOptions
+  } = options;
+  const optimizationRunOptions = {
+    ...comparisonOptions.reps !== void 0 ? { reps: comparisonOptions.reps } : {},
+    ...comparisonOptions.resumable !== void 0 ? { resumable: comparisonOptions.resumable } : {},
+    ...comparisonOptions.labeledStore !== void 0 ? { labeledStore: comparisonOptions.labeledStore } : {},
+    ...comparisonOptions.captureSource !== void 0 ? { captureSource: comparisonOptions.captureSource } : {},
+    ...comparisonOptions.captureSourceVersionHash !== void 0 ? { captureSourceVersionHash: comparisonOptions.captureSourceVersionHash } : {},
+    ...comparisonOptions.maxConcurrency !== void 0 ? { maxConcurrency: comparisonOptions.maxConcurrency } : {},
+    ...comparisonOptions.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: comparisonOptions.dispatchTimeoutMs } : {},
+    ...comparisonOptions.repo !== void 0 ? { repo: comparisonOptions.repo } : {},
+    ...comparisonOptions.tracing !== void 0 ? { tracing: comparisonOptions.tracing } : {},
+    ...comparisonOptions.expectUsage !== void 0 ? { expectUsage: comparisonOptions.expectUsage } : {},
+    ...comparisonOptions.now !== void 0 ? { now: comparisonOptions.now } : {},
+    ...comparisonOptions.buildTraceWriter !== void 0 ? { buildTraceWriter: comparisonOptions.buildTraceWriter } : {},
+    ...comparisonOptions.storage !== void 0 ? { storage: comparisonOptions.storage } : {},
+    ...comparisonOptions.cellPlacement !== void 0 ? { cellPlacement: comparisonOptions.cellPlacement } : {},
+    ...comparisonOptions.optimizationRunOptions ?? {},
+    dispatchRef
+  };
+  const comparison = await compareOptimizationMethods({
+    ...comparisonOptions,
+    dispatchRef,
+    optimizationRunOptions,
+    methods: [method],
+    baselineSurface: baseline.surface,
+    trainScenarios: trainScenarios.map((scenario) => structuredClone(scenario)),
+    selectionScenarios: selectionScenarios.map((scenario) => structuredClone(scenario)),
+    testScenarios: finalScenarios.map((scenario) => structuredClone(scenario)),
+    dispatchWithSurface: async (surface, scenario, context) => {
+      const candidate = normalizeSurface(surface, codec, "candidate");
+      return dispatchCandidate({
+        candidate: structuredClone(candidate.value),
+        candidateSurface: candidate.surface,
+        candidateSurfaceHash: candidate.surfaceHash,
+        scenario,
+        context
+      });
+    }
   });
+  const winner = normalizeSurface(comparison.best.winnerSurface, codec, "winner");
+  return {
+    methodName: options.method.name,
+    baseline,
+    winner,
+    comparison
+  };
 }
-function readMemoryActivationJournal(storage, path, expected) {
-  const stored = storage.read(path);
-  if (stored === void 0) {
-    if (storage.exists(path)) throw new Error(`cannot read memory activation journal '${path}'`);
-    return { prepared: false };
+function assertCompleteOptimizationMethod(method) {
+  const candidate = method;
+  if (!candidate || typeof candidate.name !== "string" || candidate.name.trim().length === 0 || typeof candidate.optimize !== "function") {
+    throw new Error(
+      "knowledge optimization requires a complete OptimizationMethod with a non-empty name and optimize()"
+    );
   }
-  let prepared = false;
-  let activated;
-  for (const [index, line] of stored.split("\n").entries()) {
-    if (!line) continue;
-    let raw;
-    try {
-      raw = JSON.parse(line);
-    } catch (error) {
-      throw new Error(`invalid memory activation journal '${path}' line ${index + 1}`, {
-        cause: error
-      });
+}
+function jsonCandidateCodec() {
+  return {
+    serialize: (candidate) => canonicalJson6(candidate),
+    parse(surface) {
+      let parsed;
+      try {
+        parsed = JSON.parse(surface);
+      } catch (error) {
+        throw new Error("serialized knowledge candidate is not valid JSON", { cause: error });
+      }
+      return parsed;
     }
-    const event = parseMemoryActivationEvent(raw, path, index + 1, expected);
-    if (event.status === "prepared") {
-      if (prepared || activated) {
-        throw new Error(`memory activation journal '${path}' repeats its prepared event`);
+  };
+}
+function jsonObjectCandidateCodec() {
+  const codec = jsonCandidateCodec();
+  return {
+    serialize: codec.serialize,
+    parse(surface) {
+      const candidate = codec.parse(surface);
+      if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+        throw new Error("serialized knowledge candidate must be a JSON object");
       }
-      prepared = true;
-      continue;
+      return candidate;
     }
-    if (!prepared || activated) {
-      throw new Error(`memory activation journal '${path}' has an out-of-order activated event`);
+  };
+}
+function scenarioContentFingerprint(scenario) {
+  const {
+    id: _id,
+    tags: _tags,
+    split: _split,
+    splitTag: _splitTag,
+    ...content
+  } = scenario;
+  return surfaceHash(canonicalJson6(content));
+}
+function canonicalCandidateMethod(method, codec) {
+  return {
+    name: method.name,
+    async optimize(input) {
+      const result = await method.optimize(input);
+      const winner = normalizeSurface(result.winnerSurface, codec, `${method.name} winner`);
+      return {
+        ...result,
+        winnerSurface: winner.surface
+      };
     }
-    activated = event;
-  }
-  return { prepared, ...activated ? { activated } : {} };
+  };
 }
-function parseMemoryActivationEvent(value, path, line, expected) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`invalid memory activation journal '${path}' line ${line}`);
+function normalizeCandidate(candidate, codec, label) {
+  let surface;
+  try {
+    surface = codec.serialize(candidate);
+  } catch (error) {
+    throw new Error(`${label} serializer failed`, { cause: error });
   }
-  const event = value;
-  for (const [key, expectedValue] of Object.entries(expected)) {
-    if (event[key] !== expectedValue) {
-      throw new Error(
-        `memory activation journal '${path}' line ${line} does not match the measured winner`
-      );
-    }
+  return normalizeSurface(surface, codec, label);
+}
+function normalizeSurface(surface, codec, label) {
+  if (typeof surface !== "string" || surface.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty serialized string`);
   }
-  if (event.status !== "prepared" && event.status !== "activated") {
-    throw new Error(`invalid memory activation journal '${path}' line ${line} status`);
+  let value;
+  try {
+    value = codec.parse(surface);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`${label} parser failed${detail}`, { cause: error });
   }
-  if (typeof event.recordedAt !== "string" || !Number.isFinite(Date.parse(event.recordedAt))) {
-    throw new Error(`invalid memory activation journal '${path}' line ${line} recordedAt`);
+  let canonicalSurface;
+  try {
+    canonicalSurface = codec.serialize(value);
+  } catch (error) {
+    throw new Error(`${label} serializer failed after parsing`, { cause: error });
   }
-  if (event.status === "activated" && event.outcome !== "applied" && event.outcome !== "recovered" && event.outcome !== "already-current") {
-    throw new Error(`invalid memory activation journal '${path}' line ${line} outcome`);
+  if (typeof canonicalSurface !== "string" || canonicalSurface.trim().length === 0) {
+    throw new Error(`${label} serializer must return a non-empty string`);
   }
-  if (event.status === "prepared" && event.outcome !== void 0) {
-    throw new Error(`invalid memory activation journal '${path}' line ${line} prepared outcome`);
+  const roundTrip = codec.serialize(codec.parse(canonicalSurface));
+  if (roundTrip !== canonicalSurface) {
+    throw new Error(`${label} codec must round-trip to one canonical surface`);
   }
-  return value;
-}
-
-// src/memory/improvement/candidate.ts
-function withCostContext(proposer, costLedger, lease, label) {
   return {
-    kind: proposer.kind,
-    async propose(context) {
-      await lease.assertOwned();
-      const proposal = await proposer.propose({
-        ...context,
-        costLedger,
-        costPhase: `memory.proposal.${context.track?.id ?? label}`
-      });
-      await lease.assertOwned();
-      return proposal;
-    },
-    ...proposer.decide ? { decide: (input) => proposer.decide(input) } : {}
+    value: structuredClone(value),
+    surface: canonicalSurface,
+    surfaceHash: surfaceHash(canonicalSurface)
   };
 }
-function withGovernorCostContext(governor, costLedger, lease) {
-  return {
-    async decide(context) {
-      await lease.assertOwned();
-      const decision = await governor.decide({
-        ...context,
-        costLedger,
-        costPhase: "memory.governor"
-      });
-      await lease.assertOwned();
-      return decision;
+function assertPartitionContent(train, selection, final, fingerprint) {
+  if (!fingerprint) return;
+  const owner = /* @__PURE__ */ new Map();
+  for (const [name, scenarios] of [
+    ["train", train],
+    ["selection", selection],
+    ["final", final]
+  ]) {
+    for (const scenario of scenarios) {
+      const identity = fingerprint(scenario);
+      if (typeof identity !== "string" || identity.trim().length === 0) {
+        throw new Error(`scenarioFingerprint returned no identity for '${scenario.id}'`);
+      }
+      const prior = owner.get(identity);
+      if (prior) {
+        const scope = prior.partition === name ? `${name} partition duplicates` : `${prior.partition}/${name} partitions duplicate`;
+        throw new Error(
+          `serialized knowledge optimization ${scope} scenario content at '${prior.scenarioId}'/'${scenario.id}'`
+        );
+      }
+      owner.set(identity, { partition: name, scenarioId: scenario.id });
     }
-  };
+  }
 }
-async function buildCandidate(options, config, hash, role) {
+
+// src/memory/improvement/activation.ts
+import { surfaceHash as surfaceHash4 } from "@tangle-network/agent-eval/campaign";
+
+// src/memory/improvement/evaluation.ts
+import { dirname as dirname2, join as join4 } from "path";
+import { canonicalJson as canonicalJson9 } from "@tangle-network/agent-eval";
+import {
+  surfaceHash as surfaceHash3
+} from "@tangle-network/agent-eval/campaign";
+
+// src/memory/improvement/candidate.ts
+import { dirname, join as join2 } from "path";
+import { canonicalJson as canonicalJson7 } from "@tangle-network/agent-eval";
+async function buildCandidate(options, config, hash) {
+  const id = `memory-config-${hash}`;
   const built = await options.createCandidate({
     config,
-    candidateId: `${role}-${hash}`,
+    candidateId: id,
     surfaceHash: hash
   });
+  assertImmutableRef(built.ref, `${id}: ref`);
+  assertDeclaredCost(built.externalCostUsdPerSequence, `${id}: externalCostUsdPerSequence`);
+  assertDeclaredCost(
+    built.externalRecoveryCostUsdPerAttempt,
+    `${id}: externalRecoveryCostUsdPerAttempt`
+  );
+  if (built.externalCostAccounting !== "exact") {
+    throw new Error(`${id}: memory improvement requires exact external cost accounting`);
+  }
   return {
     ...built,
-    id: `${role}-${hash}`,
+    id,
     ref: built.ref
   };
 }
-function experimentOptions(options, costLedger, storage, lease) {
+async function buildRegisteredCandidate(options, storage, runDir, config, hash) {
+  const candidate = await buildCandidate(options, config, hash);
+  const path = join2(runDir, "memory-candidate-identities", `${hash}.json`);
+  const record2 = { surfaceHash: hash, candidateRef: candidate.ref };
+  const stored = storage.read(path);
+  if (stored !== void 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(stored);
+    } catch (error) {
+      throw new Error(`invalid memory candidate identity '${path}'`, { cause: error });
+    }
+    if (canonicalJson7(parsed) !== canonicalJson7(record2)) {
+      throw new Error(
+        `memory config '${hash}' changed candidate identity within the same improvement run`
+      );
+    }
+    return candidate;
+  }
+  if (storage.exists(path)) throw new Error(`cannot read memory candidate identity '${path}'`);
+  storage.ensureDir(dirname(path));
+  storage.write(path, `${JSON.stringify(record2, null, 2)}
+`);
+  return candidate;
+}
+function assertDeclaredCost(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a declared non-negative finite number`);
+  }
+}
+function experimentOptions(options, storage, lease) {
   return {
     storage,
-    seed: options.seed,
-    reps: options.reps,
     resumable: options.resumable,
-    maxConcurrency: options.sequenceConcurrency,
     dispatchTimeoutMs: options.dispatchTimeoutMs,
     cleanupTimeoutMs: options.cleanupTimeoutMs,
     maxRecoveryAttempts: options.maxRecoveryAttempts,
@@ -2884,7 +3216,6 @@ function experimentOptions(options, costLedger, storage, lease) {
     executeStepRef: options.executeStepRef,
     onBranchSnapshot: options.onBranchSnapshot,
     cleanupBranches: options.cleanupBranches ?? true,
-    costLedger,
     acquireRunLease: async () => ({
       assertOwned: () => lease.assertOwned(),
       release() {
@@ -2895,11 +3226,9 @@ function experimentOptions(options, costLedger, storage, lease) {
 }
 
 // src/memory/improvement/identity.ts
-import { join as join2 } from "path";
-import { canonicalJson as canonicalJson6 } from "@tangle-network/agent-eval";
-import {
-  surfaceHash
-} from "@tangle-network/agent-eval/campaign";
+import { join as join3 } from "path";
+import { canonicalJson as canonicalJson8 } from "@tangle-network/agent-eval";
+import { surfaceHash as surfaceHash2 } from "@tangle-network/agent-eval/campaign";
 
 // src/memory/improvement/promotion.ts
 import { heldoutSignificance } from "@tangle-network/agent-eval/campaign";
@@ -2910,27 +3239,38 @@ var DEFAULT_CRITICAL_DIMENSIONS = [
   "memory_actor_recall",
   "memory_event_recall"
 ];
-var MEMORY_IMPROVEMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-improvement:v2";
 
 // src/memory/improvement/promotion.ts
 function decidePromotion(input) {
-  const { options, result, baselineId, winnerId } = input;
-  const baselineRow = result.rows.find((row) => row.candidateId === baselineId);
-  const winnerRow = result.rows.find((row) => row.candidateId === winnerId);
-  if (!baselineRow || !winnerRow) throw new Error("holdout result is missing a comparison arm");
-  const paired = pairedArtifacts(result, baselineId, winnerId, (artifact) => artifact.score);
-  const significance = heldoutSignificance(paired, options.significance);
+  const { options, finalEvaluation } = input;
+  const baselineScores = finalEvaluation.pairs.map((pair) => pair.baseline.score);
+  const winnerScores = finalEvaluation.pairs.map((pair) => pair.winner.score);
+  const baselineScore = mean2(baselineScores);
+  const winnerScore = mean2(winnerScores);
+  if (input.unchanged) {
+    return {
+      status: "no-change",
+      reasons: ["optimization selected the baseline configuration"],
+      baselineScore,
+      winnerScore,
+      lift: 0,
+      criticalDimensions: []
+    };
+  }
+  const significance = heldoutSignificance(
+    {
+      before: baselineScores,
+      after: winnerScores,
+      cellIds: finalEvaluation.pairs.map((pair) => `${pair.sequenceId}:${pair.rep}`)
+    },
+    options.significance
+  );
   const tolerance = options.criticalDimensionTolerance ?? 0.05;
   const criticalDimensions = (options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS).map(
     (dimension) => {
-      const expectedN = applicableSequenceCount(options.holdoutSequences, dimension) * (options.reps ?? 1);
-      const dimensionPairs = pairedArtifacts(
-        result,
-        baselineId,
-        winnerId,
-        (artifact) => (artifact.dimensionSampleCounts?.[dimension] ?? 0) > 0 ? artifact.dimensions[dimension] : void 0
-      );
-      const comparison = heldoutSignificance(dimensionPairs, {
+      const expectedN = applicableSequenceCount(options.finalSequences, dimension) * (options.reps ?? 1);
+      const pairs = pairedDimension(finalEvaluation, dimension);
+      const comparison = heldoutSignificance(pairs, {
         ...options.significance,
         deltaThreshold: 0
       });
@@ -2948,21 +3288,31 @@ function decidePromotion(input) {
     }
   );
   const reasons = [];
-  if (baselineRow.cellsFailed > 0 || winnerRow.cellsFailed > 0) {
-    reasons.push("at least one holdout cell failed");
+  const totalCost = input.optimization.comparison.totalCost;
+  if (!input.optimization.comparison.totalCost.accountingComplete && !options.allowIncompleteCostAccounting) {
+    reasons.push("optimization or final cost accounting is incomplete");
+  }
+  const optimizerSource = input.optimization.comparison.best.provenance?.source;
+  if (optimizerSource && optimizerSource.evidence !== "observed") {
+    reasons.push("external optimizer package identity was not observed");
+  }
+  if (totalCost.totalCostUsd > (options.maxTotalCostUsd ?? 0)) {
+    reasons.push(
+      `total cost ${totalCost.totalCostUsd} exceeds the configured limit ${options.maxTotalCostUsd ?? 0}`
+    );
   }
   if (!significance.significant) {
     reasons.push(
-      significance.fewRuns ? `only ${significance.n} paired holdout cells; more are required` : "holdout lift is not confidently above the promotion threshold"
+      significance.fewRuns ? `only ${significance.n} paired final cells; more are required` : "final lift is not confidently above the promotion threshold"
     );
   }
-  if (winnerRow.scoreMean < (options.minHoldoutScore ?? 0)) {
-    reasons.push(`winner holdout score ${winnerRow.scoreMean} is below the required minimum`);
+  if (winnerScore < (options.minFinalScore ?? 0)) {
+    reasons.push(`winner final score ${winnerScore} is below the required minimum`);
   }
   for (const dimension of criticalDimensions) {
     if (!dimension.measured) {
       reasons.push(
-        dimension.expectedN === 0 ? `critical dimension ${dimension.dimension} has no applicable holdout histories` : `critical dimension ${dimension.dimension} was measured on ${dimension.n}/${dimension.expectedN} applicable paired holdout cells`
+        dimension.expectedN === 0 ? `critical dimension ${dimension.dimension} has no applicable final histories` : `critical dimension ${dimension.dimension} was measured on ${dimension.n}/${dimension.expectedN} applicable paired final cells`
       );
     } else if (dimension.regressed) {
       reasons.push(`${dimension.dimension} may regress beyond ${tolerance}`);
@@ -2971,13 +3321,40 @@ function decidePromotion(input) {
   return {
     status: reasons.length === 0 ? "promote" : "hold",
     reasons,
-    baselineScore: baselineRow.scoreMean,
-    winnerScore: winnerRow.scoreMean,
-    lift: winnerRow.scoreMean - baselineRow.scoreMean,
+    baselineScore,
+    winnerScore,
+    lift: winnerScore - baselineScore,
     significance,
     criticalDimensions
   };
 }
+function normalizedPromotionPolicy(options) {
+  return {
+    significance: {
+      deltaThreshold: options.significance?.deltaThreshold ?? 0,
+      minProductiveRuns: options.significance?.minProductiveRuns ?? 3,
+      confidence: options.significance?.confidence ?? 0.95,
+      resamples: options.significance?.resamples ?? 2e3,
+      seed: options.significance?.seed ?? 1337,
+      statistic: options.significance?.statistic ?? "mean"
+    },
+    criticalDimensions: [...options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS],
+    criticalDimensionTolerance: options.criticalDimensionTolerance ?? 0.05,
+    minFinalScore: options.minFinalScore ?? 0,
+    maxTotalCostUsd: options.maxTotalCostUsd ?? 0,
+    allowIncompleteCostAccounting: options.allowIncompleteCostAccounting ?? false
+  };
+}
+function pairedDimension(result, dimension) {
+  const applicable = result.pairs.filter(
+    (pair) => (pair.baseline.dimensionSampleCounts[dimension] ?? 0) > 0 && (pair.winner.dimensionSampleCounts[dimension] ?? 0) > 0
+  );
+  return {
+    before: applicable.map((pair) => pair.baseline.dimensions[dimension]),
+    after: applicable.map((pair) => pair.winner.dimensions[dimension]),
+    cellIds: applicable.map((pair) => `${pair.sequenceId}:${pair.rep}`)
+  };
+}
 function applicableSequenceCount(sequences, dimension) {
   return sequences.filter(
     (sequence) => sequence.steps.some(
@@ -3006,89 +3383,36 @@ function probeAppliesToDimension(probe, dimension) {
       return true;
   }
 }
-function normalizedPromotionPolicy(options) {
-  return {
-    significance: {
-      deltaThreshold: options.significance?.deltaThreshold ?? 0,
-      minProductiveRuns: options.significance?.minProductiveRuns ?? 3,
-      confidence: options.significance?.confidence ?? 0.95,
-      resamples: options.significance?.resamples ?? 2e3,
-      seed: options.significance?.seed ?? 1337,
-      statistic: options.significance?.statistic ?? "mean"
-    },
-    criticalDimensions: [...options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS],
-    criticalDimensionTolerance: options.criticalDimensionTolerance ?? 0.05,
-    minHoldoutScore: options.minHoldoutScore ?? 0
-  };
-}
-function pairedArtifacts(result, baselineId, winnerId, select) {
-  const baseline = artifactValues(result, baselineId, select);
-  const winner = artifactValues(result, winnerId, select);
-  const keys = [...baseline.keys()].filter((key) => winner.has(key)).sort();
-  return {
-    before: keys.map((key) => baseline.get(key)),
-    after: keys.map((key) => winner.get(key)),
-    cellIds: keys
-  };
-}
-function artifactValues(result, candidateId, select) {
-  const values = /* @__PURE__ */ new Map();
-  for (const cell of result.campaign.cells) {
-    if (cell.error || cell.artifact.candidateId !== candidateId) continue;
-    const value = select(cell.artifact);
-    if (value === void 0 || !Number.isFinite(value)) continue;
-    values.set(`${cell.artifact.sequenceId}:${cell.rep}`, value);
-  }
-  return values;
-}
-function sequenceScores(result, sequences, candidateId) {
-  const bySequence = /* @__PURE__ */ new Map();
-  for (const cell of result.campaign.cells) {
-    if (cell.error || cell.artifact.candidateId !== candidateId) continue;
-    const bucket = bySequence.get(cell.artifact.sequenceId) ?? [];
-    bucket.push(cell.artifact.score);
-    bySequence.set(cell.artifact.sequenceId, bucket);
-  }
-  return sequences.map((sequence) => mean2(bySequence.get(sequence.id) ?? []));
-}
 function mean2(values) {
-  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
 }
 
 // src/memory/improvement/identity.ts
 function assertMemoryImprovementIdentity(options, storage, runDir, serialize) {
-  const path = join2(runDir, "memory-improvement-manifest.json");
+  const path = join3(runDir, "memory-improvement-manifest.json");
   const identity = {
-    schema: 6,
-    implementationRef: MEMORY_IMPROVEMENT_IMPLEMENTATION_REF,
     experimentId: options.experimentId,
-    improvementRef: options.improvementRef,
+    implementationRef: options.implementationRef,
+    method: options.method.name,
     activationRef: options.activation?.ref ?? null,
-    proposerKind: options.proposer.kind,
-    proposerKinds: Object.fromEntries(
-      Object.entries(options.proposers ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([name, proposer]) => [name, proposer.kind])
-    ),
-    populationSize: options.populationSize ?? 4,
-    budget: { maxSteps: options.budget.maxSteps },
+    baselineConfig: serialize(options.baselineConfig),
     executeStepRef: options.executeStepRef ?? null,
     cleanupBranches: options.cleanupBranches ?? true,
     promotionPolicy: normalizedPromotionPolicy(options),
-    seed: options.seed ?? null,
+    seed: options.seed ?? 42,
     reps: options.reps ?? 1,
-    seeds: options.seeds.map((entry) => ({
-      config: serialize(entry.config),
-      track: entry.track,
-      vision: entry.vision ?? null,
-      proposer: entry.proposer
-    })),
+    maxTotalCostUsd: options.maxTotalCostUsd ?? null,
+    maximumEvaluationCostUsd: options.maximumEvaluationCostUsd ?? null,
+    allowIncompleteCostAccounting: options.allowIncompleteCostAccounting ?? false,
     trainSequences: options.trainSequences,
-    holdoutSequences: options.holdoutSequences
+    selectionSequences: options.selectionSequences,
+    finalSequences: options.finalSequences
   };
-  const identityHash = surfaceHash(canonicalJson6(identity));
+  const identityHash = surfaceHash2(canonicalJson8(identity));
   const stored = storage.read(path);
   if (stored === void 0) {
     if (storage.exists(path)) throw new Error(`cannot read memory improvement manifest '${path}'`);
-    if (storage.exists(join2(runDir, "lineage.jsonl")) || storage.exists(join2(runDir, "memory-improvement-result.json"))) {
+    if (storage.exists(join3(runDir, "memory-improvement-result.json"))) {
       throw new Error(`memory improvement run '${runDir}' has state without an identity manifest`);
     }
     storage.write(path, `${JSON.stringify({ identityHash, identity }, null, 2)}
@@ -3101,18 +3425,12 @@ function assertMemoryImprovementIdentity(options, storage, runDir, serialize) {
   } catch (error) {
     throw new Error(`invalid memory improvement manifest '${path}'`, { cause: error });
   }
-  if (!manifest || typeof manifest !== "object" || manifest.identityHash !== identityHash || canonicalJson6(manifest.identity) !== canonicalJson6(identity)) {
+  if (!manifest || typeof manifest !== "object" || manifest.identityHash !== identityHash || canonicalJson8(manifest.identity) !== canonicalJson8(identity)) {
     throw new Error(
-      `memory improvement run '${runDir}' does not match its persisted inputs or implementationRef`
+      `memory improvement run '${runDir}' does not match its persisted inputs or implementation`
     );
   }
 }
-function requireStringSurface(surface) {
-  if (typeof surface !== "string" || surface.trim().length === 0) {
-    throw new Error("memory config proposer must return a JSON string surface");
-  }
-  return surface;
-}
 function serializeMemoryConfig(serialize, config) {
   let surface;
   try {
@@ -3138,12 +3456,465 @@ function assertMemoryConfigRoundTrip(config, serialize, parse) {
   const first = serialize(config);
   const second = serialize(parse(first));
   if (first !== second) {
-    throw new Error("memory config serializer and parser must round-trip seed configs exactly");
+    throw new Error("memory config serializer and parser must round-trip exactly");
   }
 }
 function memorySequenceFingerprint(sequence) {
   const { id: _id, split: _split, tags: _tags, ...content } = sequence;
-  return surfaceHash(canonicalJson6(content));
+  return surfaceHash2(canonicalJson8(content));
+}
+
+// src/memory/improvement/evaluation.ts
+function memoryConfigCodec(options) {
+  const serializeRaw = options.serializeConfig ?? ((config) => canonicalJson9(config));
+  const parseRaw = options.parseConfig ?? ((surface) => JSON.parse(surface));
+  return {
+    serialize: (config) => serializeMemoryConfig(serializeRaw, config),
+    parse: (surface) => parseMemoryConfig(parseRaw, surface)
+  };
+}
+function memoryConfigScenarios(sequences) {
+  return sequences.map(memoryConfigScenario);
+}
+async function evaluateMemoryCandidate(input) {
+  await input.lease.assertOwned();
+  const artifactPath = memoryArtifactPath(
+    input.runDir,
+    input.surfaceHash,
+    input.scenario,
+    input.rep,
+    input.seed
+  );
+  const stored = readStoredMemoryArtifact(input.storage, artifactPath, {
+    surfaceHash: input.surfaceHash,
+    candidateRef: input.candidate.ref,
+    scenario: input.scenario,
+    rep: input.rep,
+    seed: input.seed
+  });
+  if (stored) {
+    if (input.final) {
+      writeStoredMemoryArtifact(
+        input.storage,
+        memoryFinalArtifactPath(input.runDir, input.surfaceHash, input.scenario, input.rep),
+        storedMemoryArtifactRecord(input, stored)
+      );
+    }
+    return stored;
+  }
+  const evaluationCostLimit = input.options.maximumEvaluationCostUsd ?? 0;
+  const evaluationId = stableId(
+    "memory_eval",
+    canonicalJson9({
+      surfaceHash: input.surfaceHash,
+      sequence: memorySequenceFingerprint(input.scenario.sequence),
+      rep: input.rep,
+      seed: input.seed
+    })
+  );
+  const paid = await input.cost.runPaidCall({
+    actor: "agent-knowledge:memory-config-evaluation",
+    model: input.candidate.ref,
+    signal: input.signal,
+    maximumCharge: {
+      externallyEnforcedMaximumUsd: evaluationCostLimit
+    },
+    execute: async () => {
+      const experiment = await runAgentMemoryExperiment({
+        ...experimentOptions(input.options, input.storage, input.lease),
+        experimentId: `${input.options.experimentId}:${evaluationId}`,
+        experimentRunId: evaluationId,
+        sequences: [input.scenario.sequence],
+        candidates: [input.candidate],
+        runDir: join4(input.runDir, "evaluations", evaluationId),
+        seed: input.seed,
+        reps: 1,
+        maxConcurrency: 1,
+        costCeiling: evaluationCostLimit,
+        costPhase: `memory.config.${input.surfaceHash}`
+      });
+      const cell = experiment.campaign.cells[0];
+      if (!cell || cell.error || cell.artifact.candidateId !== input.candidate.id) {
+        throw new Error(
+          `${input.surfaceHash}/${input.scenario.sequenceId}: memory config evaluation did not complete`
+        );
+      }
+      const cost = experiment.campaign.aggregates.cost;
+      return {
+        artifact: cell.artifact,
+        costUsd: cell.cached ? 0 : experiment.totalCostUsd,
+        cost
+      };
+    },
+    receipt: (value) => ({
+      model: input.candidate.ref,
+      inputTokens: value.cost.inputTokens,
+      outputTokens: value.cost.outputTokens,
+      ...value.cost.reasoningTokens !== void 0 ? { reasoningTokens: value.cost.reasoningTokens } : {},
+      cachedTokens: value.cost.cachedTokens,
+      ...value.cost.cacheWriteTokens !== void 0 ? { cacheWriteTokens: value.cost.cacheWriteTokens } : {},
+      actualCostUsd: value.costUsd,
+      costUnknown: !value.cost.accountingComplete,
+      usageUnknown: !value.cost.usageComplete
+    })
+  });
+  if (!paid.succeeded) throw paid.error;
+  await input.lease.assertOwned();
+  const record2 = storedMemoryArtifactRecord(input, paid.value.artifact);
+  writeStoredMemoryArtifact(input.storage, artifactPath, record2);
+  if (input.final) {
+    writeStoredMemoryArtifact(
+      input.storage,
+      memoryFinalArtifactPath(input.runDir, input.surfaceHash, input.scenario, input.rep),
+      record2
+    );
+  }
+  return paid.value.artifact;
+}
+function loadFinalEvaluation(input) {
+  const pairs = [];
+  const reps = input.options.reps ?? 1;
+  for (const sequence of input.options.finalSequences) {
+    const scenario = memoryConfigScenario(sequence);
+    for (let rep = 0; rep < reps; rep += 1) {
+      const baseline = readStoredMemoryArtifact(
+        input.storage,
+        memoryFinalArtifactPath(input.runDir, input.baselineSurfaceHash, scenario, rep),
+        {
+          surfaceHash: input.baselineSurfaceHash,
+          candidateRef: input.baselineCandidateRef,
+          scenario,
+          rep
+        }
+      );
+      const winner = readStoredMemoryArtifact(
+        input.storage,
+        memoryFinalArtifactPath(input.runDir, input.winnerSurfaceHash, scenario, rep),
+        {
+          surfaceHash: input.winnerSurfaceHash,
+          candidateRef: input.winnerCandidateRef,
+          scenario,
+          rep
+        }
+      );
+      if (!baseline || !winner) {
+        throw new Error(
+          `memory final artifact is missing for sequence '${sequence.id}' repetition ${rep}`
+        );
+      }
+      pairs.push({ sequenceId: sequence.id, rep, baseline, winner });
+    }
+  }
+  return {
+    manifestHash: surfaceHash3(
+      canonicalJson9({
+        baselineSurfaceHash: input.baselineSurfaceHash,
+        baselineCandidateRef: input.baselineCandidateRef,
+        winnerSurfaceHash: input.winnerSurfaceHash,
+        winnerCandidateRef: input.winnerCandidateRef,
+        pairs
+      })
+    ),
+    baselineCandidateRef: input.baselineCandidateRef,
+    winnerCandidateRef: input.winnerCandidateRef,
+    pairs
+  };
+}
+function memoryArtifactPath(runDir, candidateSurfaceHash, scenario, rep, seed) {
+  return join4(
+    runDir,
+    "memory-config-artifacts",
+    candidateSurfaceHash,
+    stableId("sequence", scenario.sequenceId),
+    `rep-${rep}-${stableId("seed", String(seed))}.json`
+  );
+}
+function memoryFinalArtifactPath(runDir, candidateSurfaceHash, scenario, rep) {
+  return join4(
+    runDir,
+    "memory-final-artifacts",
+    candidateSurfaceHash,
+    stableId("sequence", scenario.sequenceId),
+    `rep-${rep}.json`
+  );
+}
+function memoryConfigScenario(sequence) {
+  return {
+    id: sequence.id,
+    kind: "agent-memory-config-search",
+    sequenceId: sequence.id,
+    sequence
+  };
+}
+function readStoredMemoryArtifact(storage, path, expected) {
+  const stored = storage.read(path);
+  if (stored === void 0) {
+    if (storage.exists(path)) throw new Error(`cannot read memory config artifact '${path}'`);
+    return void 0;
+  }
+  let record2;
+  try {
+    record2 = JSON.parse(stored);
+  } catch (error) {
+    throw new Error(`invalid memory config artifact '${path}'`, { cause: error });
+  }
+  if (!record2 || typeof record2 !== "object" || Array.isArray(record2)) {
+    throw new Error(`invalid memory config artifact '${path}'`);
+  }
+  const value = record2;
+  if (!hasExactKeys(record2, [
+    "surfaceHash",
+    "candidateRef",
+    "sequenceFingerprint",
+    "sequenceId",
+    "rep",
+    "seed",
+    "artifact"
+  ]) || value.surfaceHash !== expected.surfaceHash || value.candidateRef !== expected.candidateRef || value.sequenceFingerprint !== memorySequenceFingerprint(expected.scenario.sequence) || value.sequenceId !== expected.scenario.sequenceId || value.rep !== expected.rep || !Number.isSafeInteger(value.seed) || expected.seed !== void 0 && value.seed !== expected.seed) {
+    throw new Error(`memory config artifact '${path}' does not match its evaluation cell`);
+  }
+  return parseMemoryArtifact(
+    value.artifact,
+    `memory-config-${expected.surfaceHash}`,
+    expected.scenario.sequenceId,
+    path
+  );
+}
+function writeStoredMemoryArtifact(storage, path, record2) {
+  const serialized = `${JSON.stringify(record2, null, 2)}
+`;
+  const existing = storage.read(path);
+  if (existing !== void 0) {
+    if (canonicalJson9(JSON.parse(existing)) !== canonicalJson9(record2)) {
+      throw new Error(`memory config artifact '${path}' conflicts with durable content`);
+    }
+    return;
+  }
+  if (storage.exists(path)) throw new Error(`cannot read memory config artifact '${path}'`);
+  storage.ensureDir(dirname2(path));
+  storage.write(path, serialized);
+}
+function storedMemoryArtifactRecord(input, artifact) {
+  return {
+    surfaceHash: input.surfaceHash,
+    candidateRef: input.candidate.ref,
+    sequenceFingerprint: memorySequenceFingerprint(input.scenario.sequence),
+    sequenceId: input.scenario.sequenceId,
+    rep: input.rep,
+    seed: input.seed,
+    artifact
+  };
+}
+function parseMemoryArtifact(value, candidateId, sequenceId, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`memory config artifact '${path}' has no artifact`);
+  }
+  const artifact = value;
+  if (artifact.candidateId !== candidateId || artifact.sequenceId !== sequenceId || typeof artifact.score !== "number" || !Number.isFinite(artifact.score) || artifact.score < 0 || artifact.score > 1 || typeof artifact.passed !== "boolean" || !isFiniteNumberRecord(artifact.dimensions) || !isNonnegativeIntegerRecord(artifact.dimensionSampleCounts) || !Array.isArray(artifact.probes) || typeof artifact.branchDigest !== "string" || !artifact.branchDigest || typeof artifact.journalEntries !== "number" || !Number.isSafeInteger(artifact.journalEntries) || artifact.journalEntries < 0 || typeof artifact.durationMs !== "number" || !Number.isFinite(artifact.durationMs) || artifact.durationMs < 0) {
+    throw new Error(`memory config artifact '${path}' is malformed`);
+  }
+  return artifact;
+}
+function isFiniteNumberRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every((entry) => typeof entry === "number" && Number.isFinite(entry));
+}
+function isNonnegativeIntegerRecord(value) {
+  return isFiniteNumberRecord(value) && Object.values(value).every((entry) => Number.isSafeInteger(entry) && entry >= 0);
+}
+function hasExactKeys(value, expected) {
+  const keys = Object.keys(value);
+  return keys.length === expected.length && keys.every((key) => expected.includes(key));
+}
+
+// src/memory/improvement/activation.ts
+function appendMemoryActivationEvent(storage, path, event) {
+  appendDurableJournalEvent({
+    storage,
+    path,
+    event,
+    label: "memory activation journal"
+  });
+}
+function readMemoryActivationJournal(storage, path, expected) {
+  const stored = storage.read(path);
+  if (stored === void 0) {
+    if (storage.exists(path)) throw new Error(`cannot read memory activation journal '${path}'`);
+    return { prepared: false };
+  }
+  let prepared = false;
+  let activated;
+  for (const [index, line] of stored.split("\n").entries()) {
+    if (!line) continue;
+    let raw;
+    try {
+      raw = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`invalid memory activation journal '${path}' line ${index + 1}`, {
+        cause: error
+      });
+    }
+    const event = parseMemoryActivationEvent(raw, path, index + 1, expected);
+    if (event.status === "prepared") {
+      if (prepared || activated) {
+        throw new Error(`memory activation journal '${path}' repeats its prepared event`);
+      }
+      prepared = true;
+      continue;
+    }
+    if (!prepared || activated) {
+      throw new Error(`memory activation journal '${path}' has an out-of-order activated event`);
+    }
+    activated = event;
+  }
+  return { prepared, ...activated ? { activated } : {} };
+}
+async function assertActivatedMemoryWinner(input) {
+  const activationDriver = input.options.activation;
+  if (!activationDriver) {
+    throw new Error("an activated memory journal requires its activation driver");
+  }
+  await input.lease.assertOwned();
+  const currentConfig = await runBoundedMemoryLifecycle({
+    operation: `${activationDriver.ref}: confirm active memory configuration`,
+    timeoutMs: input.options.activationTimeoutMs ?? 6e4,
+    run: () => activationDriver.readCurrent()
+  });
+  await input.lease.assertOwned();
+  const currentHash = surfaceHash4(memoryConfigCodec(input.options).serialize(currentConfig));
+  if (currentHash !== input.result.winnerSurfaceHash) {
+    throw new Error(
+      `memory activation target '${activationDriver.ref}' drifted from measured winner '${input.result.winnerSurfaceHash}' to '${currentHash}'`
+    );
+  }
+}
+async function activateMemoryWinner(input) {
+  const activationDriver = input.options.activation;
+  const activationTimeoutMs = input.options.activationTimeoutMs ?? 6e4;
+  if (!input.hadPreparedEvent) {
+    await input.lease.assertOwned();
+    input.storage.ensureDir(input.activationJournalDir);
+    appendMemoryActivationEvent(input.storage, input.activationJournalPath, {
+      ...input.activationEventIdentity,
+      status: "prepared",
+      recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+    });
+  }
+  await input.lease.assertOwned();
+  const currentConfig = await runBoundedMemoryLifecycle({
+    operation: `${activationDriver.ref}: read current memory configuration`,
+    timeoutMs: activationTimeoutMs,
+    run: () => activationDriver.readCurrent()
+  });
+  await input.lease.assertOwned();
+  const codec = memoryConfigCodec(input.options);
+  const currentHash = surfaceHash4(codec.serialize(currentConfig));
+  if (currentHash !== input.result.baselineSurfaceHash && currentHash !== input.result.winnerSurfaceHash) {
+    throw new Error(
+      `memory activation target '${activationDriver.ref}' changed concurrently; expected '${input.result.baselineSurfaceHash}' or '${input.result.winnerSurfaceHash}', found '${currentHash}'`
+    );
+  }
+  let outcome;
+  if (currentHash === input.result.winnerSurfaceHash) {
+    outcome = input.hadPreparedEvent ? "recovered" : "already-current";
+    input.result.activation.status = "recovered";
+  } else {
+    let compareError;
+    try {
+      await runBoundedMemoryLifecycle({
+        operation: `${activationDriver.ref}: activate memory configuration`,
+        timeoutMs: activationTimeoutMs,
+        run: () => activationDriver.compareAndSet({
+          activationId: input.result.activation.id,
+          expectedConfig: input.result.baselineConfig,
+          expectedSurfaceHash: input.result.baselineSurfaceHash,
+          config: input.result.winnerConfig,
+          surfaceHash: input.result.winnerSurfaceHash,
+          decision: input.result.decision,
+          optimization: input.result.optimization,
+          finalEvaluation: input.result.finalEvaluation
+        })
+      });
+    } catch (error) {
+      compareError = error;
+    }
+    await input.lease.assertOwned();
+    let observedConfig;
+    try {
+      observedConfig = await runBoundedMemoryLifecycle({
+        operation: `${activationDriver.ref}: confirm memory configuration`,
+        timeoutMs: activationTimeoutMs,
+        run: () => activationDriver.readCurrent()
+      });
+    } catch (error) {
+      if (compareError) {
+        throw new AggregateError(
+          [compareError, error],
+          `memory activation '${input.result.activation.id}' failed and its live state could not be confirmed`
+        );
+      }
+      throw error;
+    }
+    await input.lease.assertOwned();
+    const observedHash = surfaceHash4(codec.serialize(observedConfig));
+    if (observedHash !== input.result.winnerSurfaceHash) {
+      const mismatch = new Error(
+        `memory activation '${input.result.activation.id}' did not install the measured winner; found '${observedHash}'`
+      );
+      if (compareError) {
+        throw new AggregateError(
+          [compareError, mismatch],
+          `memory activation '${input.result.activation.id}' failed without applying the measured winner`
+        );
+      }
+      throw mismatch;
+    }
+    outcome = compareError ? "recovered" : "applied";
+    input.result.activation.status = compareError ? "recovered" : "activated";
+  }
+  await input.lease.assertOwned();
+  appendMemoryActivationEvent(input.storage, input.activationJournalPath, {
+    ...input.activationEventIdentity,
+    status: "activated",
+    outcome,
+    recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+  });
+}
+function parseMemoryActivationEvent(value, path, line, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line}`);
+  }
+  const event = value;
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    if (event[key] !== expectedValue) {
+      throw new Error(
+        `memory activation journal '${path}' line ${line} does not match the measured winner`
+      );
+    }
+  }
+  if (event.status !== "prepared" && event.status !== "activated") {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} status`);
+  }
+  const expectedKeys = [
+    ...Object.keys(expected),
+    "status",
+    "recordedAt",
+    ...event.status === "activated" ? ["outcome"] : []
+  ];
+  const actualKeys = Object.keys(event);
+  if (actualKeys.length !== expectedKeys.length || actualKeys.some((key) => !expectedKeys.includes(key))) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} fields`);
+  }
+  if (typeof event.recordedAt !== "string" || !Number.isFinite(Date.parse(event.recordedAt))) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} recordedAt`);
+  }
+  if (event.status === "activated" && event.outcome !== "applied" && event.outcome !== "recovered" && event.outcome !== "already-current") {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} outcome`);
+  }
+  if (event.status === "prepared" && event.outcome !== void 0) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} prepared outcome`);
+  }
+  return value;
 }
 
 // src/memory/improvement/output.ts
@@ -3158,9 +3929,11 @@ function writeMemoryImprovementResult(storage, experimentId, result) {
         baselineSurface: result.baselineSurface,
         winnerSurface: result.winnerSurface,
         decision: result.decision,
+        method: result.optimization.methodName,
+        comparison: result.optimization.comparison,
+        finalEvaluation: result.finalEvaluation,
         activation: result.activation,
-        totalCostUsd: result.totalCostUsd,
-        lineage: result.lineage.toGraph()
+        totalCostUsd: result.totalCostUsd
       },
       null,
       2
@@ -3179,19 +3952,15 @@ function assertMemoryImprovementOptions(options) {
       throw new Error(`memory improvement ${name} must be a non-empty string`);
     }
   }
-  if (typeof options.proposer?.kind !== "string" || !options.proposer.kind.trim()) {
-    throw new Error("memory improvement proposer.kind must be a non-empty string");
-  }
-  if (typeof options.proposer?.propose !== "function") {
-    throw new Error("memory improvement proposer.propose must be a function");
+  assertImmutableRef(options.implementationRef, "memory improvement implementationRef");
+  if (!options.method || typeof options.method.name !== "string" || !options.method.name.trim() || typeof options.method.optimize !== "function") {
+    throw new Error("memory improvement method must be a complete OptimizationMethod");
   }
-  if (options.governor !== void 0 && typeof options.governor.decide !== "function") {
-    throw new Error("memory improvement governor.decide must be a function");
+  if (typeof options.createCandidate !== "function") {
+    throw new Error("memory improvement createCandidate must be a function");
   }
   if (options.activation !== void 0) {
-    if (typeof options.activation.ref !== "string" || !options.activation.ref.trim()) {
-      throw new Error("memory improvement activation.ref must be a non-empty string");
-    }
+    assertImmutableRef(options.activation.ref, "memory improvement activation.ref");
     if (typeof options.activation.readCurrent !== "function") {
       throw new Error("memory improvement activation.readCurrent must be a function");
     }
@@ -3199,11 +3968,8 @@ function assertMemoryImprovementOptions(options) {
       throw new Error("memory improvement activation.compareAndSet must be a function");
     }
   }
-  for (const [name, proposer] of Object.entries(options.proposers ?? {})) {
-    if (!name.trim()) throw new Error("memory improvement proposer labels must be non-empty");
-    if (!proposer || typeof proposer.kind !== "string" || !proposer.kind.trim() || typeof proposer.propose !== "function") {
-      throw new Error(`memory improvement proposer '${name}' is invalid`);
-    }
+  if (options.executeStep) {
+    assertImmutableRef(options.executeStepRef, "memory improvement executeStepRef");
   }
   if (options.serializeConfig !== void 0 && typeof options.serializeConfig !== "function") {
     throw new Error("memory improvement serializeConfig must be a function");
@@ -3211,12 +3977,7 @@ function assertMemoryImprovementOptions(options) {
   if (options.parseConfig !== void 0 && typeof options.parseConfig !== "function") {
     throw new Error("memory improvement parseConfig must be a function");
   }
-  if (!Number.isSafeInteger(options.budget.maxSteps) || options.budget.maxSteps < 0) {
-    throw new Error("memory improvement budget.maxSteps must be a non-negative safe integer");
-  }
   for (const [name, value] of [
-    ["populationSize", options.populationSize],
-    ["candidateConcurrency", options.candidateConcurrency],
     ["sequenceConcurrency", options.sequenceConcurrency],
     ["reps", options.reps],
     ["maxRecoveryAttempts", options.maxRecoveryAttempts],
@@ -3226,8 +3987,21 @@ function assertMemoryImprovementOptions(options) {
       throw new Error(`memory improvement ${name} must be a positive safe integer`);
     }
   }
-  if (options.maxTotalCostUsd !== void 0 && (!Number.isFinite(options.maxTotalCostUsd) || options.maxTotalCostUsd < 0)) {
-    throw new Error("memory improvement maxTotalCostUsd must be a non-negative finite number");
+  for (const [name, value] of [["maxTotalCostUsd", options.maxTotalCostUsd]]) {
+    if (value !== void 0 && (!Number.isFinite(value) || value < 0)) {
+      throw new Error(`memory improvement ${name} must be a non-negative finite number`);
+    }
+  }
+  if (options.maximumEvaluationCostUsd !== void 0 && (!Number.isFinite(options.maximumEvaluationCostUsd) || options.maximumEvaluationCostUsd <= 0)) {
+    throw new Error("memory improvement maximumEvaluationCostUsd must be a positive finite number");
+  }
+  if ((options.maxTotalCostUsd ?? 0) > 0 && options.maximumEvaluationCostUsd === void 0) {
+    throw new Error(
+      "memory improvement maximumEvaluationCostUsd is required when a spend limit is configured"
+    );
+  }
+  if (options.allowIncompleteCostAccounting !== void 0 && typeof options.allowIncompleteCostAccounting !== "boolean") {
+    throw new Error("memory improvement allowIncompleteCostAccounting must be boolean");
   }
   if (options.activationTimeoutMs !== void 0 && (!Number.isSafeInteger(options.activationTimeoutMs) || options.activationTimeoutMs <= 0)) {
     throw new Error("memory improvement activationTimeoutMs must be a positive safe integer");
@@ -3236,17 +4010,9 @@ function assertMemoryImprovementOptions(options) {
   if (tolerance !== void 0 && (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > 1)) {
     throw new Error("memory improvement criticalDimensionTolerance must be between 0 and 1");
   }
-  const minimum = options.minHoldoutScore;
+  const minimum = options.minFinalScore;
   if (minimum !== void 0 && (!Number.isFinite(minimum) || minimum < 0 || minimum > 1)) {
-    throw new Error("memory improvement minHoldoutScore must be between 0 and 1");
-  }
-  for (const seed of options.seeds) {
-    if (typeof seed.track !== "string" || !seed.track.trim() || typeof seed.proposer !== "string" || !seed.proposer.trim()) {
-      throw new Error("memory improvement seeds require non-empty track and proposer values");
-    }
-    if (seed.vision !== void 0 && (typeof seed.vision !== "string" || !seed.vision.trim())) {
-      throw new Error("memory improvement seed vision must be a non-empty string when provided");
-    }
+    throw new Error("memory improvement minFinalScore must be between 0 and 1");
   }
   const dimensions = options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS;
   if (dimensions.some((dimension) => typeof dimension !== "string" || !dimension.trim())) {
@@ -3255,57 +4021,47 @@ function assertMemoryImprovementOptions(options) {
   if (new Set(dimensions).size !== dimensions.length) {
     throw new Error("memory improvement criticalDimensions must be unique");
   }
-  assertDistinctSequenceContent(options.trainSequences, "train");
-  assertDistinctSequenceContent(options.holdoutSequences, "holdout");
+  assertIndependentSequences(
+    options.trainSequences,
+    options.selectionSequences,
+    options.finalSequences
+  );
 }
-function assertDistinctSequenceContent(sequences, split) {
-  const idsByFingerprint = /* @__PURE__ */ new Map();
-  for (const sequence of sequences) {
-    const fingerprint = memorySequenceFingerprint(sequence);
-    const prior = idsByFingerprint.get(fingerprint);
-    if (prior) {
-      throw new Error(
-        `memory improvement ${split} histories duplicate content: ${prior}/${sequence.id}`
-      );
+function assertIndependentSequences(train, selection, final) {
+  if (train.length === 0) throw new Error("memory improvement requires training sequences");
+  if (selection.length === 0) throw new Error("memory improvement requires selection sequences");
+  if (final.length < 2) {
+    throw new Error("memory improvement requires at least 2 final sequences");
+  }
+  const ids = /* @__PURE__ */ new Map();
+  const content = /* @__PURE__ */ new Map();
+  for (const [split, sequences] of [
+    ["train", train],
+    ["selection", selection],
+    ["final", final]
+  ]) {
+    for (const sequence of sequences) {
+      const priorId = ids.get(sequence.id);
+      if (priorId) {
+        throw new Error(
+          `memory improvement ${priorId}/${split} sequences share id '${sequence.id}'`
+        );
+      }
+      ids.set(sequence.id, split);
+      const fingerprint = memorySequenceFingerprint(sequence);
+      const priorContent = content.get(fingerprint);
+      if (priorContent) {
+        throw new Error(
+          `memory improvement ${priorContent.split}/${split} histories duplicate content at '${priorContent.sequenceId}'/'${sequence.id}'`
+        );
+      }
+      content.set(fingerprint, { split, sequenceId: sequence.id });
     }
-    idsByFingerprint.set(fingerprint, sequence.id);
   }
 }
 
 // src/memory/improvement/run.ts
 async function runAgentMemoryImprovement(options) {
-  if ("onPromote" in options) {
-    throw new Error(
-      "memory improvement onPromote was removed; use activation.readCurrent and activation.compareAndSet"
-    );
-  }
-  if (options.seeds.length === 0) throw new Error("memory improvement requires seed configs");
-  if (options.trainSequences.length === 0) {
-    throw new Error("memory improvement requires training sequences");
-  }
-  if (options.holdoutSequences.length === 0) {
-    throw new Error("memory improvement requires holdout sequences");
-  }
-  const trainIds = new Set(options.trainSequences.map((sequence) => sequence.id));
-  const overlap = options.holdoutSequences.map((sequence) => sequence.id).filter((id) => trainIds.has(id));
-  if (overlap.length > 0) {
-    throw new Error(`memory improvement train/holdout overlap: ${overlap.join(", ")}`);
-  }
-  const trainFingerprints = new Map(
-    options.trainSequences.map((sequence) => [memorySequenceFingerprint(sequence), sequence.id])
-  );
-  const duplicateHistories = options.holdoutSequences.flatMap((sequence) => {
-    const trainId = trainFingerprints.get(memorySequenceFingerprint(sequence));
-    return trainId ? [`${trainId}/${sequence.id}`] : [];
-  });
-  if (duplicateHistories.length > 0) {
-    throw new Error(
-      `memory improvement train/holdout histories duplicate content: ${duplicateHistories.join(", ")}`
-    );
-  }
-  if (typeof options.improvementRef !== "string" || !options.improvementRef.trim()) {
-    throw new Error("memory improvement improvementRef must be a non-empty string");
-  }
   assertMemoryImprovementOptions(options);
   const storage = options.storage ?? fsCampaignStorage2();
   const runDir = resolveRunDir2(options.runDir, options.repo);
@@ -3346,274 +4102,166 @@ async function runAgentMemoryImprovement(options) {
 }
 async function runAgentMemoryImprovementOwned(options, storage, runDir, lease) {
   await lease.assertOwned();
-  const serializeRaw = options.serializeConfig ?? ((config) => canonicalJson7(config));
-  const parseRaw = options.parseConfig ?? ((surface) => JSON.parse(surface));
-  const serialize = (config) => serializeMemoryConfig(serializeRaw, config);
-  const parse = (surface) => parseMemoryConfig(parseRaw, surface);
-  for (const seed of options.seeds) assertMemoryConfigRoundTrip(seed.config, serialize, parse);
+  const codec = memoryConfigCodec(options);
+  assertMemoryConfigRoundTrip(options.baselineConfig, codec.serialize, codec.parse);
   if (options.activation && !storage.append) {
     throw new Error("memory activation requires CampaignStorage.append");
   }
-  if (options.resumable !== false && !options.lineageStore && !storage.append) {
-    throw new Error("resumable memory improvement requires CampaignStorage.append");
-  }
-  assertMemoryImprovementIdentity(options, storage, runDir, serialize);
-  const costLedger = createRunCostLedger2({
-    storage,
-    runDir,
-    costCeilingUsd: options.maxTotalCostUsd ?? 0
-  });
-  reconcileInterruptedRunPaidCalls(costLedger, "memory improvement run");
-  assertNoInterruptedPaidCalls(costLedger, "memory improvement recovery");
-  const trainScenarios = options.trainSequences.map((sequence) => ({
-    id: sequence.id,
-    kind: "agent-memory-config-search",
-    sequenceId: sequence.id
-  }));
-  const evaluations = /* @__PURE__ */ new Map();
-  const evaluateSurface = async (surface) => {
-    await lease.assertOwned();
-    const text = requireStringSurface(surface);
-    const config = parse(text);
-    const canonicalSurface = serialize(config);
-    const hash = surfaceHash2(canonicalSurface);
-    let pending = evaluations.get(hash);
-    if (!pending) {
-      pending = (async () => {
-        const candidate = await buildCandidate(options, config, hash, `search-${hash}`);
-        await lease.assertOwned();
-        const experiment = await runAgentMemoryExperiment({
-          ...experimentOptions(options, costLedger, storage, lease),
-          experimentId: `${options.experimentId}:search:${hash}`,
-          sequences: options.trainSequences,
-          candidates: [candidate],
-          runDir: join3(runDir, "search", hash),
-          costPhase: `memory.search.${hash}`
-        });
-        await lease.assertOwned();
-        return experiment;
-      })();
-      evaluations.set(hash, pending);
-      void pending.catch(() => evaluations.delete(hash));
-    }
-    const result2 = await pending;
-    await lease.assertOwned();
-    const row = result2.rows[0];
-    if (!row || row.cellsFailed > 0) {
-      throw new Error(`${hash}: memory candidate did not complete every training cell`);
+  assertMemoryImprovementIdentity(options, storage, runDir, codec.serialize);
+  const trainScenarios = memoryConfigScenarios(options.trainSequences);
+  const selectionScenarios = memoryConfigScenarios(options.selectionSequences);
+  const finalScenarios = memoryConfigScenarios(options.finalSequences);
+  const finalScenarioIds = new Set(finalScenarios.map((scenario) => scenario.id));
+  const pending = /* @__PURE__ */ new Map();
+  const candidates = /* @__PURE__ */ new Map();
+  const candidateFor = (config, hash) => {
+    let candidate = candidates.get(hash);
+    if (!candidate) {
+      candidate = buildRegisteredCandidate(options, storage, runDir, config, hash);
+      candidates.set(hash, candidate);
+      void candidate.catch(() => candidates.delete(hash));
     }
-    return {
-      score: row.scoreMean,
-      scoreVector: sequenceScores(result2, options.trainSequences, row.candidateId)
-    };
+    return candidate;
   };
-  const lineageStore = options.lineageStore ?? (options.resumable === false ? memLineageStore() : campaignLineageStore(storage, join3(runDir, "lineage.jsonl")));
-  const lineageOptions = {
-    seeds: options.seeds.map((seed) => ({
-      surface: serialize(seed.config),
-      track: seed.track,
-      proposer: seed.proposer,
-      ...seed.vision !== void 0 ? { vision: seed.vision } : {}
-    })),
-    scenarios: trainScenarios,
-    proposer: withCostContext(options.proposer, costLedger, lease, "default"),
-    proposers: options.proposers ? Object.fromEntries(
-      Object.entries(options.proposers).map(([name, proposer]) => [
-        name,
-        withCostContext(proposer, costLedger, lease, name)
-      ])
-    ) : void 0,
-    scoreSurface: evaluateSurface,
-    governor: options.governor ? withGovernorCostContext(options.governor, costLedger, lease) : void 0,
-    budget: {
-      ...options.budget,
-      maxNodes: options.seeds.length + options.budget.maxSteps
-    },
-    store: lineageStore,
-    populationSize: options.populationSize,
-    candidateConcurrency: options.candidateConcurrency
+  const optimizationRunOptions = {
+    ...options.optimizationRunOptions ?? {},
+    storage,
+    ...options.reps !== void 0 ? { reps: options.reps } : {},
+    ...options.resumable !== void 0 ? { resumable: options.resumable } : {},
+    ...options.sequenceConcurrency !== void 0 ? { maxConcurrency: options.sequenceConcurrency } : {},
+    ...options.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: options.dispatchTimeoutMs } : {},
+    expectUsage: "off"
   };
-  const search = await runLineageLoop(lineageOptions);
+  const optimization = await runSerializedKnowledgeOptimization({
+    executionRef: options.implementationRef,
+    baseline: options.baselineConfig,
+    method: options.method,
+    trainScenarios,
+    selectionScenarios,
+    finalScenarios,
+    codec,
+    scenarioFingerprint: (scenario) => memorySequenceFingerprint(scenario.sequence),
+    dispatchCandidate: async ({ candidate, candidateSurfaceHash, scenario, context }) => {
+      const key = memoryArtifactPath(
+        runDir,
+        candidateSurfaceHash,
+        scenario,
+        context.rep,
+        context.seed
+      );
+      let operation = pending.get(key);
+      if (!operation) {
+        operation = candidateFor(candidate, candidateSurfaceHash).then(
+          (builtCandidate) => evaluateMemoryCandidate({
+            options,
+            storage,
+            runDir,
+            lease,
+            candidate: builtCandidate,
+            surfaceHash: candidateSurfaceHash,
+            scenario,
+            rep: context.rep,
+            seed: context.seed,
+            final: finalScenarioIds.has(scenario.id),
+            cost: context.cost,
+            signal: context.signal
+          })
+        );
+        pending.set(key, operation);
+        void operation.catch(() => pending.delete(key));
+      }
+      return operation;
+    },
+    judges: [agentMemorySequenceJudge()],
+    runDir,
+    repo: options.repo,
+    storage,
+    seed: options.seed,
+    reps: options.reps,
+    resumable: options.resumable,
+    costCeiling: options.maxTotalCostUsd ?? 0,
+    maxConcurrency: options.sequenceConcurrency,
+    dispatchTimeoutMs: options.dispatchTimeoutMs,
+    expectUsage: "off",
+    optimizationRunOptions,
+    now: options.now
+  });
   await lease.assertOwned();
-  const best = search.best;
-  if (!best) throw new Error("memory improvement produced no measured config");
-  const baselineSurface = serialize(options.seeds[0].config);
-  const baselineHash = surfaceHash2(baselineSurface);
-  const winnerConfig = parse(requireStringSurface(best.surface));
-  const winnerSurface = serialize(winnerConfig);
-  const winnerHash = surfaceHash2(winnerSurface);
-  const baselineConfig = parse(baselineSurface);
-  let holdout;
-  let decision;
-  if (winnerHash === baselineHash) {
-    const baselineMeasurement = await evaluateSurface(baselineSurface);
-    decision = {
-      status: "no-change",
-      reasons: ["search did not find a config better than the baseline"],
-      baselineScore: baselineMeasurement.score,
-      winnerScore: baselineMeasurement.score,
-      lift: 0,
-      criticalDimensions: []
-    };
-  } else {
-    await lease.assertOwned();
-    const [baselineCandidate, winnerCandidate] = await Promise.all([
-      buildCandidate(options, baselineConfig, baselineHash, "baseline"),
-      buildCandidate(options, winnerConfig, winnerHash, "winner")
-    ]);
-    await lease.assertOwned();
-    holdout = await runAgentMemoryExperiment({
-      ...experimentOptions(options, costLedger, storage, lease),
-      experimentId: `${options.experimentId}:holdout`,
-      sequences: options.holdoutSequences,
-      candidates: [baselineCandidate, winnerCandidate],
-      runDir: join3(runDir, "holdout"),
-      costPhase: "memory.holdout"
-    });
-    decision = decidePromotion({
-      options,
-      result: holdout,
-      baselineId: baselineCandidate.id,
-      winnerId: winnerCandidate.id
-    });
-  }
-  const resultJsonPath = join3(runDir, "memory-improvement-result.json");
+  const [baselineCandidate, winnerCandidate] = await Promise.all([
+    candidateFor(optimization.baseline.value, optimization.baseline.surfaceHash),
+    candidateFor(optimization.winner.value, optimization.winner.surfaceHash)
+  ]);
+  const finalEvaluation = loadFinalEvaluation({
+    options,
+    storage,
+    runDir,
+    baselineSurfaceHash: optimization.baseline.surfaceHash,
+    baselineCandidateRef: baselineCandidate.ref,
+    winnerSurfaceHash: optimization.winner.surfaceHash,
+    winnerCandidateRef: winnerCandidate.ref
+  });
+  const unchanged = optimization.baseline.surfaceHash === optimization.winner.surfaceHash;
+  const decision = decidePromotion({ options, optimization, finalEvaluation, unchanged });
+  const resultJsonPath = join5(runDir, "memory-improvement-result.json");
   const activationRef = options.activation?.ref ?? "not-configured";
-  const activationId = `memory-activation-${surfaceHash2(
-    canonicalJson7({
+  const activationId = `memory-activation-${surfaceHash5(
+    canonicalJson10({
       experimentId: options.experimentId,
-      improvementRef: options.improvementRef,
+      implementationRef: options.implementationRef,
+      method: optimization.methodName,
       activationRef,
-      baselineSurfaceHash: baselineHash,
-      winnerSurfaceHash: winnerHash,
-      holdoutManifestHash: holdout?.campaign.manifestHash ?? null,
+      baselineSurfaceHash: optimization.baseline.surfaceHash,
+      winnerSurfaceHash: optimization.winner.surfaceHash,
+      finalEvaluationHash: finalEvaluation.manifestHash,
       promotionPolicy: normalizedPromotionPolicy(options)
     })
   )}`;
-  const activationJournalDir = join3(runDir, "activations");
-  const activationJournalPath = join3(activationJournalDir, `${activationId}.jsonl`);
-  const activationEligible = decision.status === "promote" && holdout !== void 0;
-  const activationEventIdentity = holdout ? {
-    schema: 1,
+  const activationJournalDir = join5(runDir, "activations");
+  const activationJournalPath = join5(activationJournalDir, `${activationId}.jsonl`);
+  const activationEligible = decision.status === "promote";
+  const activationEventIdentity = {
     activationId,
     experimentId: options.experimentId,
     activationRef,
-    baselineSurfaceHash: baselineHash,
-    winnerSurfaceHash: winnerHash,
-    holdoutManifestHash: holdout.campaign.manifestHash
-  } : void 0;
-  const activationJournal = activationEligible && activationEventIdentity ? readMemoryActivationJournal(storage, activationJournalPath, activationEventIdentity) : { prepared: false };
+    baselineSurfaceHash: optimization.baseline.surfaceHash,
+    winnerSurfaceHash: optimization.winner.surfaceHash,
+    finalEvaluationHash: finalEvaluation.manifestHash
+  };
+  const activationJournal = activationEligible ? readMemoryActivationJournal(storage, activationJournalPath, activationEventIdentity) : { prepared: false };
   const activation = {
     id: activationId,
     status: !activationEligible ? "not-eligible" : activationJournal.activated ? "already-activated" : options.activation ? "pending" : "not-configured",
     journalPath: activationJournalPath
   };
   const result = {
-    lineage: search.lineage,
-    baselineConfig,
-    winnerConfig,
-    baselineSurface,
-    winnerSurface,
-    baselineSurfaceHash: baselineHash,
-    winnerSurfaceHash: winnerHash,
+    optimization,
+    baselineConfig: optimization.baseline.value,
+    winnerConfig: optimization.winner.value,
+    baselineSurface: optimization.baseline.surface,
+    winnerSurface: optimization.winner.surface,
+    baselineSurfaceHash: optimization.baseline.surfaceHash,
+    winnerSurfaceHash: optimization.winner.surfaceHash,
     decision,
+    finalEvaluation,
     activation,
-    ...holdout ? { holdout } : {},
-    totalCostUsd: costLedger.summary().totalCostUsd,
+    totalCostUsd: optimization.comparison.totalCost.totalCostUsd,
     resultJsonPath
   };
   await lease.assertOwned();
+  if (activationJournal.activated) {
+    await assertActivatedMemoryWinner({ options, lease, result });
+  }
   writeMemoryImprovementResult(storage, options.experimentId, result);
-  if (activationEligible && !activationJournal.activated && activationEventIdentity && holdout && options.activation) {
-    const activationDriver = options.activation;
-    const activationTimeoutMs = options.activationTimeoutMs ?? 6e4;
-    const hadPreparedEvent = activationJournal.prepared;
-    if (!hadPreparedEvent) {
-      await lease.assertOwned();
-      storage.ensureDir(activationJournalDir);
-      appendMemoryActivationEvent(storage, activationJournalPath, {
-        ...activationEventIdentity,
-        status: "prepared",
-        recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
-      });
-    }
-    await lease.assertOwned();
-    const currentConfig = await runBoundedMemoryLifecycle({
-      operation: `${activationDriver.ref}: read current memory configuration`,
-      timeoutMs: activationTimeoutMs,
-      run: () => activationDriver.readCurrent()
-    });
-    await lease.assertOwned();
-    const currentHash = surfaceHash2(serialize(currentConfig));
-    if (currentHash !== baselineHash && currentHash !== winnerHash) {
-      throw new Error(
-        `memory activation target '${activationDriver.ref}' changed concurrently; expected '${baselineHash}' or '${winnerHash}', found '${currentHash}'`
-      );
-    }
-    let outcome;
-    if (currentHash === winnerHash) {
-      outcome = hadPreparedEvent ? "recovered" : "already-current";
-      activation.status = "recovered";
-    } else {
-      let compareError;
-      try {
-        await runBoundedMemoryLifecycle({
-          operation: `${activationDriver.ref}: activate memory configuration`,
-          timeoutMs: activationTimeoutMs,
-          run: () => activationDriver.compareAndSet({
-            activationId,
-            expectedConfig: baselineConfig,
-            expectedSurfaceHash: baselineHash,
-            config: winnerConfig,
-            surfaceHash: winnerHash,
-            decision,
-            lineage: search.lineage,
-            holdout
-          })
-        });
-      } catch (error) {
-        compareError = error;
-      }
-      await lease.assertOwned();
-      let observedConfig;
-      try {
-        observedConfig = await runBoundedMemoryLifecycle({
-          operation: `${activationDriver.ref}: confirm memory configuration`,
-          timeoutMs: activationTimeoutMs,
-          run: () => activationDriver.readCurrent()
-        });
-      } catch (error) {
-        if (compareError) {
-          throw new AggregateError(
-            [compareError, error],
-            `memory activation '${activationId}' failed and its live state could not be confirmed`
-          );
-        }
-        throw error;
-      }
-      await lease.assertOwned();
-      const observedHash = surfaceHash2(serialize(observedConfig));
-      if (observedHash !== winnerHash) {
-        const mismatch = new Error(
-          `memory activation '${activationId}' did not install the measured winner; found '${observedHash}'`
-        );
-        if (compareError) {
-          throw new AggregateError(
-            [compareError, mismatch],
-            `memory activation '${activationId}' failed without applying the measured winner`
-          );
-        }
-        throw mismatch;
-      }
-      outcome = compareError ? "recovered" : "applied";
-      activation.status = compareError ? "recovered" : "activated";
-    }
-    await lease.assertOwned();
-    appendMemoryActivationEvent(storage, activationJournalPath, {
-      ...activationEventIdentity,
-      status: "activated",
-      outcome,
-      recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+  if (activationEligible && !activationJournal.activated && options.activation) {
+    await activateMemoryWinner({
+      options,
+      storage,
+      lease,
+      result,
+      activationEventIdentity,
+      activationJournalDir,
+      activationJournalPath,
+      hadPreparedEvent: activationJournal.prepared
     });
     writeMemoryImprovementResult(storage, options.experimentId, result);
   }
@@ -3622,7 +4270,7 @@ async function runAgentMemoryImprovementOwned(options, storage, runDir, lease) {
 
 // src/memory/mem0.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { canonicalJson as canonicalJson8 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson11 } from "@tangle-network/agent-eval";
 function createMem0MemoryAdapter(options) {
   assertMem0Options(options);
   const id = options.id ?? `mem0-${options.mode}`;
@@ -3938,7 +4586,7 @@ function normalizeMem0Hits(raw, adapterId, options) {
     if (options.minScore !== void 0 && (score === void 0 || score < options.minScore)) {
       return void 0;
     }
-    const memoryId = stringField2(item, ["id"]) ?? stableId("mem", canonicalJson8(compactRecord2({ adapterId, text, metadata, item })));
+    const memoryId = stringField2(item, ["id"]) ?? stableId("mem", canonicalJson11(compactRecord2({ adapterId, text, metadata, item })));
     const normalizedScore = score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
     return {
       id: memoryId,
@@ -4137,11 +4785,11 @@ function mem0MemoryAdapterIdentity(options) {
   if (typeof options.backendRef !== "string" || !options.backendRef.trim()) {
     throw new Error("Mem0 backendRef must be a non-empty string");
   }
-  return stableId("mem0", canonicalJson8(compactRecord2(options)));
+  return `sha256:${sha256(canonicalJson11(compactRecord2(options)))}`;
 }
 
 // src/memory/neo4j.ts
-import { canonicalJson as canonicalJson9 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson12 } from "@tangle-network/agent-eval";
 function createNeo4jAgentMemoryAdapter(options) {
   assertNeo4jOptions(options);
   const client = options.client;
@@ -4406,7 +5054,7 @@ async function writeNeo4jMemory(client, input, adapterId, transport, isolatedIns
   assertNeo4jWriteSucceeded(result, adapterId, input.kind);
   const id = idFromResult(result) ?? input.id ?? stableId(
     "mem",
-    canonicalJson9({ adapterId, kind: input.kind, text: input.text, scope: input.scope ?? {} })
+    canonicalJson12({ adapterId, kind: input.kind, text: input.text, scope: input.scope ?? {} })
   );
   return {
     accepted: true,
@@ -4755,6 +5403,11 @@ var AgentMemoryWriteInputSchema = z.object({
 });
 
 export {
+  assertImmutableRef,
+  runSerializedKnowledgeOptimization,
+  jsonCandidateCodec,
+  jsonObjectCandidateCodec,
+  scenarioContentFingerprint,
   deterministicRng,
   retrievalHoldoutConfigHash,
   applyRetrievalHoldout,
@@ -4781,4 +5434,4 @@ export {
   AgentMemoryHitSchema,
   AgentMemoryWriteInputSchema
 };
-//# sourceMappingURL=chunk-CPMLJYA3.js.map
+//# sourceMappingURL=chunk-LMR53POQ.js.map