@tangle-network/agent-runtime 0.240.0 → 0.247.0

package/dist/{improvement-cycle-BpSVwIJw.js → improvement-cycle-B049YmQ8.js}

@@ -1,17 +1,18 @@
-import { Sr as runSettledCommand, bi as detachedSnapshot, ut as createExecutor } from "./supervisor-CFSPj8rx.js";
+import { Bn as linkAbort, Nr as terminateProcessTreeAndConfirm, Sr as runSettledCommand, Vn as runAbortable, ia as armDeadlineTimer, ut as createExecutor, xi as detachedSnapshot } from "./supervisor-BIBWUFUr.js";
 import { i as ConfigError } from "./errors-DodWX-cb.js";
-import { A as collectAgentTurn, O as optimizerMethod, a as defaultStructuralRolloutPolicy, j as streamAgentTurn } from "./structural-rollout-CW67upUV.js";
+import { A as collectAgentTurn, O as optimizerMethod, a as defaultStructuralRolloutPolicy, j as streamAgentTurn } from "./structural-rollout-z1A0okaB.js";
 import { a as concreteProfileModel, t as assertExecutableAgentProfile } from "./model-policy-BbSCSak0.js";
-import { a as canonicalCandidateBytes, d as omitTopLevelDigest, o as canonicalCandidateDigest$1, p as verifyCanonicalCandidateDocument, s as canonicalCandidateDocument, u as immutableCandidateValue } from "./protected-redaction-wGo44k2K.js";
+import { i as syncDurableDirectory, r as publishExclusiveDurableFile } from "./durable-file-DWQA4ooo.js";
+import { a as canonicalCandidateBytes$1, d as omitTopLevelDigest, f as sha256Bytes, o as canonicalCandidateDigest$1, p as verifyCanonicalCandidateDocument, s as canonicalCandidateDocument, u as immutableCandidateValue } from "./protected-redaction-Fn1ETfJ-.js";
 import { t as runAnalystLoop } from "./analyst-loop-DZw5QWT9.js";
-import { A as omitUndefinedObjectFields, C as agentCandidateProfileAsAgentProfile, D as createAgentCandidateProfileActivation, M as parseExactAgentProfile, T as assertCandidateProfileBinding, c as executePreparedAgentCandidate, j as parseAgentCandidateProfileActivation, k as materializeAgentCandidateProfilePlan, o as verifiedResourceTextByDigest, s as verifyAgentCandidateBundle, t as prepareAgentCandidateExecution, w as applyExactAgentProfileDiff } from "./prepare-Dc30WRB0.js";
-import { AGENT_IMPROVEMENT_SOURCE_METADATA_KEY, agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, agentImprovementActivationSchema, agentImprovementProposalSchema, agentImprovementReviewSchema, agentImprovementSourceMetadata, agentImprovementSourceSchema, agentProfileDiffSchema, agentProfileImprovementArmSchema, agentProfileImprovementExecutionRefSchema, agentProfileModelHintsSchema, agentProfileSchema, applyAgentProfileDiff, candidateExecutionEvidenceSchema, canonicalAgentProfileDigest, canonicalCandidateDigest, changedProfileImprovementSurfaces, defineAgentProfileDiff, diffAgentProfiles, numbersApproximatelyEqual, sha256DigestSchema } from "@tangle-network/agent-interface";
+import { A as omitUndefinedObjectFields, C as agentCandidateProfileAsAgentProfile, D as createAgentCandidateProfileActivation, M as parseExactAgentProfile, T as assertCandidateProfileBinding, c as executePreparedAgentCandidate, j as parseAgentCandidateProfileActivation, k as materializeAgentCandidateProfilePlan, o as verifiedResourceTextByDigest, s as verifyAgentCandidateBundle, t as prepareAgentCandidateExecution, w as applyExactAgentProfileDiff } from "./prepare-CibQrhfi.js";
+import { AGENT_IMPROVEMENT_SOURCE_METADATA_KEY, agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, agentImprovementActivationSchema, agentImprovementProposalSchema, agentImprovementReviewSchema, agentImprovementSourceMetadata, agentImprovementSourceSchema, agentProfileDiffSchema, agentProfileEnvironmentSchema, agentProfileImprovementArmSchema, agentProfileImprovementExecutionRefSchema, agentProfileModelHintsSchema, agentProfileSchema, agentProfileTrainingSchema, agentTrainingDatasetIdentitySchema, agentTrainingParametersSchema, agentTrainingReceiptSchema, agentTrainingTaskKey, agentTrainingTaskSchema, applyAgentProfileDiff, candidateExecutionEvidenceSchema, canonicalAgentProfileDigest, canonicalCandidateBytes, changedProfileImprovementSurfaces, defineAgentProfileDiff, diffAgentProfiles, numbersApproximatelyEqual, sha256DigestSchema, snapshotAgentProfile, trainedModelIdForArtifact } from "@tangle-network/agent-interface";
 import { CostLedger, canonicalJson, makeProposalFinding } from "@tangle-network/agent-eval";
 import { createHash, randomUUID } from "node:crypto";
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { realpath } from "node:fs/promises";
+import { spawn, spawnSync } from "node:child_process";
+import { constants, existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { chmod, mkdir, mkdtemp, open, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isDeepStrictEqual } from "node:util";
 import { assertProposalFindings } from "@tangle-network/agent-eval/analyst";
@@ -1000,7 +1001,7 @@ function materializeImprovementProfileCandidate(profile, surface, winner, skills
 	if (isComponentSurface(winner)) {
 		if (surface !== "agent-profile" || !profileComponents) throw new ConfigError(`improve(): the '${surface}' candidate has no profile component mapping`);
 		const winnerComponents = immutableCandidateValue({ ...winner.components });
-		const validated = validateProfileCandidate(profileComponents.apply(profile, winnerComponents), surface);
+		const validated = parseMaterializedProfile(profileComponents.apply(profile, winnerComponents), surface);
 		const materializedComponents = Object.fromEntries(validateComponents(profileComponents.read(validated), "profileComponents.read after apply"));
 		const names = Object.keys(winnerComponents);
 		if (names.length !== Object.keys(materializedComponents).length || names.some((name) => materializedComponents[name] !== winnerComponents[name])) throw new ConfigError("improve(): profileComponents.apply must round-trip every winning component exactly");
@@ -1074,9 +1075,9 @@ function materializeImprovementProfileCandidate(profile, surface, winner, skills
 			break;
 		}
 	}
-	return validateProfileCandidate(candidate, surface);
+	return parseMaterializedProfile(candidate, surface);
 }
-function validateProfileCandidate(candidate, surface) {
+function parseMaterializedProfile(candidate, surface) {
 	const parsed = agentProfileSchema.safeParse(candidate);
 	if (!parsed.success) throw new ConfigError(`improve(): the '${surface}' candidate does not produce a valid AgentProfile: ${parsed.error.message}`);
 	return immutableCandidateValue(parsed.data);
@@ -1583,6 +1584,37 @@ async function runCodeImprovement(opts) {
 	};
 }
 //#endregion
+//#region src/improvement/candidate-validation.ts
+/** One spelling of the execution-identity rule for optimization, training, and the harness. */
+function parseExecutionRef(value, label) {
+	const parsed = sha256DigestSchema.safeParse(value);
+	if (!parsed.success) throw new ConfigError(`${label}: executionRef must be a lowercase sha256:<64 hex> digest`);
+	return parsed.data;
+}
+/** Validate the callback itself before any optimizer, trainer, or candidate work starts. */
+function assertCandidateValidator(validator) {
+	if (validator !== void 0 && typeof validator !== "function") throw new ConfigError("validateCandidate must be a function when present");
+}
+/** A validator accepts synchronously by returning void, or rejects by throwing. */
+function validateProfileCandidate(validator, input) {
+	assertCandidateValidator(validator);
+	const result = validator?.(Object.freeze(input));
+	if (result !== void 0) {
+		Promise.resolve(result).catch(() => {});
+		throw new ConfigError("candidate validators must return void synchronously or throw");
+	}
+}
+/**
+* Refuse exact held-out content digests already declared in this profile's training lineage.
+* Both training and trainer-visible validation rows are exposure. This is an exact
+* provenance check, not fuzzy decontamination or proof that undeclared training was fresh.
+*/
+function assertProfileTrainingIsHeldOut(profile, heldOutDigests) {
+	const training = profile.metadata?.training;
+	if (!training) return;
+	for (const receipt of [training.receipt, ...training.ancestors]) if (receipt.dataset.tasks.some((task) => heldOutDigests.has(task.contentDigest))) throw new ConfigError("known training exposure overlaps held-out evaluation");
+}
+//#endregion
 //#region src/improvement/method-controls.ts
 const methodRuntimeControls = Symbol("agent-runtime.improvement.method-runtime-controls");
 function withMethodRuntimeControls(method, controls) {
@@ -1750,14 +1782,6 @@ function resolveOptimizationMethod(source, context) {
 	if (!method || typeof method !== "object" || typeof method.name !== "string" || method.name.trim() !== method.name || method.name.length === 0 || typeof method.optimize !== "function") throw new ConfigError("improve(): method must be a complete OptimizationMethod with a trimmed name and optimize(input)");
 	return method;
 }
-function copyProvenance(provenance) {
-	return immutableCandidateValue(provenance);
-}
-function validateExecutionRef(value) {
-	const parsed = sha256DigestSchema.safeParse(value);
-	if (!parsed.success) throw new ConfigError("improve(): executionRef must be a lowercase sha256:<64 hex> digest");
-	return parsed.data;
-}
 function materializationError(error) {
 	if (error instanceof Error) return {
 		name: error.name,
@@ -1839,7 +1863,7 @@ function profileCandidatePopulation(provenance, baselineProfile, materializeProf
 				reason: "optimizer-did-not-report-candidate-lineage"
 			}
 		};
-		const surfaceDigest = canonicalCandidateDigest(entry.value);
+		const surfaceDigest = canonicalCandidateDigest$1(entry.value);
 		let candidateProfile;
 		try {
 			candidateProfile = materializeProfile(entry.value);
@@ -1853,9 +1877,9 @@ function profileCandidatePopulation(provenance, baselineProfile, materializeProf
 				error: materializationError(error)
 			};
 		}
-		const profileDigest = canonicalCandidateDigest(candidateProfile);
+		const profileDigest = canonicalCandidateDigest$1(candidateProfile);
 		const diffs = diffAgentProfiles(baselineProfile, candidateProfile);
-		if (canonicalCandidateDigest(diffs.reduce(applyAgentProfileDiff, baselineProfile)) !== profileDigest) throw new ConfigError(`improve(): Interface profile diffs do not reproduce optimizer candidate ${entry.candidateDigest}`);
+		if (canonicalCandidateDigest$1(diffs.reduce(applyAgentProfileDiff, baselineProfile)) !== profileDigest) throw new ConfigError(`improve(): Interface profile diffs do not reproduce optimizer candidate ${entry.candidateDigest}`);
 		materializedCandidates += 1;
 		return {
 			status: "materialized",
@@ -1865,7 +1889,7 @@ function profileCandidatePopulation(provenance, baselineProfile, materializeProf
 			profile: candidateProfile,
 			profileDigest,
 			diffs,
-			diffDigests: diffs.map(canonicalCandidateDigest)
+			diffDigests: diffs.map(canonicalCandidateDigest$1)
 		};
 	});
 	return immutableCandidateValue({
@@ -1891,9 +1915,10 @@ function profileCandidatePopulation(provenance, baselineProfile, materializeProf
 }
 async function runMethodImprovement(profile, opts) {
 	const { surface = "prompt", executionRef: inputExecutionRef, method: methodSource, agent, validateCandidate, findings: inputFindings = [], skills, profileComponents, optimizationRunOptions, minimumLift = 0, ...comparisonOptions } = opts;
+	assertCandidateValidator(validateCandidate);
 	if (!Number.isFinite(minimumLift) || minimumLift < 0) throw new ConfigError("improve(): minimumLift must be a finite number greater than or equal to 0");
 	if (profileComponents && surface !== "agent-profile") throw new ConfigError("improve(): profileComponents is valid only with surface 'agent-profile'");
-	const executionRef = validateExecutionRef(inputExecutionRef);
+	const executionRef = parseExecutionRef(inputExecutionRef, "improve()");
 	const findings = immutableCandidateValue([...assertProposalFindings(inputFindings, "improve() method findings")]);
 	const preparedSurface = prepareProfileSurface(profile, surface, skills, profileComponents);
 	const baselineSurface = preparedSurface.surface;
@@ -1927,34 +1952,38 @@ async function runMethodImprovement(profile, opts) {
 	}));
 	const rawMaterializeProfile = createProfileCandidateMaterializer(profile, surface, baselineSurface, skills, profileComponents);
 	const runtimeInvocationId = `runtime-optimization:${randomUUID()}`;
-	const method = resolveOptimizationMethod(methodSource, {
-		profile,
-		evaluationRef,
-		surface,
-		baselineSurface,
-		baselineValue,
-		findings
-	});
 	const baselineSurfaceDigest = canonicalCandidateDigest$1(baselineSurface);
+	const heldOutDigests = new Set(scenarioPartitions.finalTest.map((task) => task.scenarioDigest));
 	const validatedCandidates = /* @__PURE__ */ new Set();
+	const validateMaterialized = (validator, candidate, candidateSurface, isBaseline) => {
+		const prepared = prepareProfileSurface(candidate, surface, skills, profileComponents);
+		validateProfileCandidate(validator, {
+			profile: candidate,
+			surface,
+			candidateSurface,
+			value: immutableCandidateValue(prepared.value),
+			isBaseline
+		});
+	};
 	const materializeProfile = (candidateSurface) => {
 		const candidate = rawMaterializeProfile(candidateSurface);
 		const candidateDigest = canonicalCandidateDigest$1(candidateSurface);
 		if (!validatedCandidates.has(candidateDigest)) {
-			const prepared = prepareProfileSurface(candidate, surface, skills, profileComponents);
-			const validationInput = Object.freeze({
-				profile: candidate,
-				surface,
-				candidateSurface: immutableCandidateValue(candidateSurface),
-				value: immutableCandidateValue(prepared.value),
-				isBaseline: candidateDigest === baselineSurfaceDigest
-			});
-			validateCandidate?.(validationInput);
+			assertProfileTrainingIsHeldOut(candidate, heldOutDigests);
+			validateMaterialized(validateCandidate, candidate, immutableCandidateValue(candidateSurface), candidateDigest === baselineSurfaceDigest);
 			validatedCandidates.add(candidateDigest);
 		}
 		return candidate;
 	};
 	materializeProfile(baselineSurface);
+	const method = resolveOptimizationMethod(methodSource, {
+		profile,
+		evaluationRef,
+		surface,
+		baselineSurface,
+		baselineValue,
+		findings
+	});
 	const costScope = {
 		evaluationRef,
 		invocationId: runtimeInvocationId
@@ -1976,15 +2005,7 @@ async function runMethodImprovement(profile, opts) {
 			const rootSurface = toRoot(value);
 			const candidateDigest = canonicalCandidateDigest$1(rootSurface);
 			if (checked.has(candidateDigest)) return;
-			const candidate = materializeProfile(rootSurface);
-			const prepared = prepareProfileSurface(candidate, surface, skills, profileComponents);
-			controls?.validateCandidate(Object.freeze({
-				profile: immutableCandidateValue(candidate),
-				surface,
-				candidateSurface: rootSurface,
-				value: immutableCandidateValue(prepared.value),
-				isBaseline: candidateDigest === currentBaselineDigest
-			}));
+			validateMaterialized(controls?.validateCandidate, materializeProfile(rootSurface), rootSurface, candidateDigest === currentBaselineDigest);
 			checked.add(candidateDigest);
 		};
 		check(input.baselineSurface);
@@ -2044,7 +2065,7 @@ async function runMethodImprovement(profile, opts) {
 	return {
 		mode: "method",
 		method: method.name,
-		...score.provenance ? { provenance: copyProvenance(score.provenance) } : {},
+		...score.provenance ? { provenance: immutableCandidateValue(score.provenance) } : {},
 		candidate,
 		decision: cost.accountingComplete && score.decision.promote && score.decision.low > minimumLift ? "ship" : "hold",
 		lift: score.lift,
@@ -2066,6 +2087,375 @@ async function runMethodImprovement(profile, opts) {
 	};
 }
 //#endregion
+//#region src/improvement/training.ts
+function positiveLimit(value, label) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`invalid ${label}`);
+}
+async function hashFile(path, maximum, signal, capture = false) {
+	signal.throwIfAborted();
+	const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	try {
+		const before = await file.stat();
+		if (!before.isFile() || !Number.isSafeInteger(before.size) || before.size > maximum) throw new Error("artifact must be a bounded regular file");
+		const hash = createHash("sha256");
+		const chunks = [];
+		let bytes = 0;
+		for await (const chunk of file.createReadStream({
+			autoClose: false,
+			signal
+		})) {
+			bytes += chunk.length;
+			if (bytes > maximum) throw new Error("artifact exceeded its byte limit");
+			if (bytes > before.size) throw new Error("artifact changed while being hashed");
+			hash.update(chunk);
+			if (capture) chunks.push(Buffer.from(chunk));
+		}
+		const after = await file.stat();
+		if (before.size !== bytes || after.size !== bytes || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error("artifact changed while being hashed");
+		return {
+			digest: `sha256:${hash.digest("hex")}`,
+			bytes,
+			...capture ? { content: Buffer.concat(chunks) } : {}
+		};
+	} finally {
+		await file.close();
+	}
+}
+/** Execute one pinned command without a shell, in the runtime-owned job directory. POSIX only. */
+function createCommandProfileTrainer(input) {
+	const command = immutableCandidateValue(input);
+	positiveLimit(command.maxOutputBytes, "trainer output limit");
+	if (!command.id || command.id.trim() !== command.id || !Array.isArray(command.args) || !command.args.every((arg) => typeof arg === "string" && !arg.includes("\0"))) throw new Error("invalid trainer command");
+	for (const file of [command.executable, ...command.inputs]) {
+		if (!isAbsolute(file.path)) throw new Error("trainer files must use absolute paths");
+		sha256DigestSchema.parse(file.digest);
+	}
+	for (const [name, value] of Object.entries(command.environment)) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || value.includes("\0")) throw new Error("invalid trainer environment");
+	agentProfileEnvironmentSchema.parse(Object.fromEntries(Object.entries(command.environment).map(([key, value]) => [key, {
+		kind: "public",
+		value
+	}])));
+	const identity = immutableCandidateValue({
+		mode: "command",
+		id: command.id,
+		revision: canonicalCandidateDigest$1(command)
+	});
+	agentTrainingReceiptSchema.shape.trainer.parse({
+		...identity,
+		parameters: {}
+	});
+	return Object.freeze({
+		identity,
+		async execute(request, signal) {
+			try {
+				if (process.platform === "win32") throw new Error("controlled trainers require POSIX process-group cancellation");
+				const requestSnapshot = immutableCandidateValue(request);
+				const inputBytes = Buffer.from(canonicalCandidateBytes(requestSnapshot));
+				const verifyInputs = async () => {
+					for (const file of [command.executable, ...command.inputs]) if ((await hashFile(file.path, Number.MAX_SAFE_INTEGER, signal)).digest !== file.digest) throw new Error("trainer executable or input digest mismatch");
+				};
+				await verifyInputs();
+				signal.throwIfAborted();
+				await new Promise((resolve, reject) => {
+					const child = spawn(command.executable.path, command.args, {
+						cwd: dirname(requestSnapshot.checkpointPath),
+						env: command.environment,
+						shell: false,
+						detached: true,
+						stdio: [
+							"pipe",
+							"pipe",
+							"pipe"
+						]
+					});
+					let failure;
+					let outputBytes = 0;
+					let leaderClosed = false;
+					let termination;
+					const stop = () => {
+						if (!termination) {
+							termination = terminateProcessTreeAndConfirm(child, () => leaderClosed, "createCommandProfileTrainer");
+							termination.catch((error) => {
+								failure ??= error;
+							});
+						}
+						return termination;
+					};
+					const abort = () => {
+						failure ??= /* @__PURE__ */ new Error("trainer cancelled");
+						stop();
+					};
+					signal.addEventListener("abort", abort, { once: true });
+					if (signal.aborted) abort();
+					const count = (chunk) => {
+						outputBytes += chunk.length;
+						if (outputBytes > command.maxOutputBytes) {
+							failure ??= /* @__PURE__ */ new Error("trainer output limit exceeded");
+							stop();
+						}
+					};
+					child.stdout.on("data", count);
+					child.stderr.on("data", count);
+					child.stdin.on("error", (error) => {
+						failure ??= error;
+						stop();
+					});
+					child.on("error", (error) => {
+						failure ??= error;
+					});
+					child.on("exit", stop);
+					child.on("close", (code, exitSignal) => {
+						leaderClosed = true;
+						signal.removeEventListener("abort", abort);
+						stop().then(() => {
+							if (failure) reject(failure);
+							else if (code !== 0 || exitSignal !== null) reject(/* @__PURE__ */ new Error(`trainer exited unsuccessfully (${code ?? exitSignal})`));
+							else resolve();
+						}, reject);
+					});
+					child.stdin.end(inputBytes);
+				});
+				await verifyInputs();
+				return {
+					succeeded: true,
+					value: void 0
+				};
+			} catch (error) {
+				return {
+					succeeded: false,
+					reason: error instanceof Error ? error.message : "trainer failed"
+				};
+			}
+		}
+	});
+}
+function datasetIdentity(bytes) {
+	const dataset = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+	canonicalCandidateBytes(dataset);
+	if (!dataset || typeof dataset !== "object" || Object.keys(dataset).sort().join(",") !== "format,rows,version" || dataset.version !== 1 || ![
+		"sft",
+		"dpo",
+		"grpo"
+	].includes(dataset.format) || !Array.isArray(dataset.rows) || dataset.rows.length === 0 || dataset.rows.length > 1e6) throw new Error("invalid training dataset");
+	const tasks = /* @__PURE__ */ new Map();
+	const partitions = /* @__PURE__ */ new Map();
+	let trainingRows = 0;
+	for (const row of dataset.rows) {
+		if (!row || typeof row !== "object" || Object.keys(row).sort().join(",") !== "data,partition,task" || !["train", "validation"].includes(row.partition)) throw new Error("every dataset row needs its exposure identity and partition");
+		if (row.partition === "train") trainingRows++;
+		const task = agentTrainingTaskSchema.parse(row.task);
+		for (const identity of [JSON.stringify([task.benchmark, task.task]), task.contentDigest]) {
+			const previous = partitions.get(identity);
+			if (previous !== void 0 && previous !== row.partition) throw new Error("training and validation task partitions intersect");
+			partitions.set(identity, row.partition);
+		}
+		tasks.set(agentTrainingTaskKey(task), task);
+	}
+	if (trainingRows === 0) throw new Error("dataset contains no training rows");
+	const members = [...tasks.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, task]) => task);
+	return agentTrainingDatasetIdentitySchema.parse({
+		digest: sha256Bytes(bytes),
+		taskSetDigest: canonicalCandidateDigest$1(members),
+		tasks: members
+	});
+}
+/** Training materializes a candidate; it never emits a ship verdict or changes a live agent. */
+async function runProfileTraining(profile, options) {
+	let stage = "admission";
+	let jobDirectory;
+	const cancellation = linkAbort(...options.signal ? [options.signal] : []);
+	const signal = cancellation.signal;
+	const outputDirectory = options.outputDirectory;
+	const timeoutMs = options.timeoutMs;
+	let servingMayExist = false;
+	let trainingMayExist = false;
+	let clearTimer;
+	try {
+		if (options.mode !== "training") throw new Error("training mode is required");
+		const parent = snapshotAgentProfile(profile);
+		if (!parent.harness || !parent.model?.default?.trim() || !parent.model.provider?.trim()) throw new Error("training requires an explicit parent harness, provider and model");
+		const parentProfileDigest = canonicalAgentProfileDigest(parent);
+		const parentBytes = Buffer.from(JSON.stringify(parent), "utf8");
+		sha256DigestSchema.parse(options.dataset.digest);
+		if (timeoutMs !== void 0) positiveLimit(timeoutMs, "training timeout");
+		positiveLimit(options.maxCheckpointBytes, "checkpoint byte limit");
+		if (typeof options.trainer?.execute !== "function" || typeof options.serving?.serve !== "function") throw new Error("trainer and verified serving ports are required");
+		const trainer = immutableCandidateValue(options.trainer.identity);
+		const parameters = immutableCandidateValue(agentTrainingParametersSchema.parse(options.parameters));
+		agentTrainingReceiptSchema.shape.trainer.parse({
+			...trainer,
+			parameters
+		});
+		assertCandidateValidator(options.validateCandidate);
+		const execute = options.trainer.execute.bind(options.trainer);
+		const serve = options.serving.serve.bind(options.serving);
+		const executionRef = parseExecutionRef(options.executionRef, "training");
+		const expectedDatasetDigest = options.dataset.digest;
+		const sourceDataset = options.dataset.path;
+		const maxCheckpointBytes = options.maxCheckpointBytes;
+		const validateCandidate = options.validateCandidate;
+		const ancestry = agentProfileTrainingSchema.shape.ancestors.parse(parent.metadata?.training ? [parent.metadata.training.receipt, ...parent.metadata.training.ancestors] : []);
+		const validate = (candidate, isBaseline) => validateProfileCandidate(validateCandidate, {
+			profile: candidate,
+			surface: "agent-profile",
+			candidateSurface: JSON.stringify(candidate),
+			value: candidate,
+			isBaseline
+		});
+		if (timeoutMs !== void 0) clearTimer = armDeadlineTimer(timeoutMs, () => cancellation.abort(/* @__PURE__ */ new Error("training deadline exceeded")), true);
+		signal.throwIfAborted();
+		validate(parent, true);
+		await mkdir(outputDirectory, { recursive: true });
+		const outputRoot = await realpath(outputDirectory);
+		jobDirectory = await mkdtemp(join(outputRoot, "training-"));
+		await chmod(jobDirectory, 448);
+		syncDurableDirectory(outputRoot);
+		const datasetPath = join(jobDirectory, "dataset.json");
+		const parentProfilePath = join(jobDirectory, "parent-profile.json");
+		const artifactPath = join(jobDirectory, "checkpoint.bin");
+		stage = "dataset";
+		const source = await hashFile(sourceDataset, 128 * 1024 * 1024, signal, true);
+		if (source.digest !== expectedDatasetDigest) throw new Error("training dataset digest mismatch");
+		const bytes = source.content;
+		if (bytes.length !== source.bytes) throw new Error("training dataset snapshot is incomplete");
+		const dataset = datasetIdentity(bytes);
+		await writeFile(datasetPath, bytes, {
+			flag: "wx",
+			mode: 256
+		});
+		await writeFile(parentProfilePath, parentBytes, {
+			flag: "wx",
+			mode: 256
+		});
+		const request = immutableCandidateValue({
+			version: 1,
+			invocationId: jobDirectory,
+			datasetPath,
+			checkpointPath: artifactPath,
+			parentProfilePath,
+			parentProfileDigest,
+			parameters,
+			executionRef
+		});
+		stage = "training";
+		const trained = await runAbortable(() => {
+			trainingMayExist = true;
+			return execute(request, signal);
+		}, signal, "training cancelled");
+		signal.throwIfAborted();
+		if (trained?.succeeded !== true) throw new Error(trained?.reason ?? "trainer did not report success");
+		trainingMayExist = false;
+		stage = "checkpoint";
+		if ((await hashFile(datasetPath, 128 * 1024 * 1024, signal)).digest !== dataset.digest || (await hashFile(parentProfilePath, parentBytes.byteLength, signal)).digest !== sha256Bytes(parentBytes)) throw new Error("trainer changed its pinned inputs");
+		const artifact = await hashFile(artifactPath, maxCheckpointBytes, signal);
+		if (artifact.bytes === 0) throw new Error("checkpoint must be nonempty");
+		await chmod(artifactPath, 256);
+		const checkpoint = await open(artifactPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+		try {
+			await checkpoint.sync();
+		} finally {
+			await checkpoint.close();
+		}
+		stage = "serving";
+		const served = await runAbortable(() => {
+			servingMayExist = true;
+			return serve({
+				artifactPath,
+				artifactDigest: artifact.digest,
+				artifactBytes: artifact.bytes,
+				routerModelId: trainedModelIdForArtifact(artifact.digest),
+				signal
+			});
+		}, signal, "checkpoint serving cancelled");
+		signal.throwIfAborted();
+		if (served?.succeeded !== true) throw new Error(served?.reason ?? "checkpoint serving is unverified");
+		if (served.value.artifactDigest !== artifact.digest) throw new Error("Router serving evidence names a different checkpoint");
+		const receipt = immutableCandidateValue(agentTrainingReceiptSchema.parse({
+			version: 1,
+			dataset,
+			parentProfileDigest,
+			parentReceiptDigest: ancestry[0] ? canonicalCandidateDigest$1(ancestry[0]) : null,
+			executionRef,
+			trainer: {
+				...trainer,
+				parameters
+			},
+			checkpoint: {
+				artifactDigest: artifact.digest,
+				artifactBytes: artifact.bytes,
+				routerModelId: served.value.routerModelId,
+				servingDigest: served.value.evidenceDigest
+			}
+		}));
+		if ((await hashFile(artifactPath, maxCheckpointBytes, signal)).digest !== artifact.digest) throw new Error("checkpoint changed during serving");
+		stage = "profile";
+		const previousModel = parent.metadata?.training?.receipt.checkpoint.routerModelId;
+		const routerModelId = receipt.checkpoint.routerModelId;
+		const rebindModels = (entries) => Object.fromEntries(Object.entries(entries).map(([key, value]) => [key, previousModel && value.model === previousModel ? {
+			...value,
+			model: routerModelId
+		} : value]));
+		const candidate = snapshotAgentProfile({
+			...parent,
+			model: {
+				...parent.model,
+				default: routerModelId,
+				...previousModel && parent.model.small === previousModel ? { small: routerModelId } : {}
+			},
+			...parent.subagents && { subagents: rebindModels(parent.subagents) },
+			...parent.modes && { modes: rebindModels(parent.modes) },
+			metadata: {
+				...parent.metadata,
+				training: {
+					receipt,
+					ancestors: ancestry
+				}
+			}
+		});
+		validate(candidate, false);
+		if ((await hashFile(artifactPath, maxCheckpointBytes, signal)).digest !== artifact.digest) throw new Error("checkpoint changed during candidate validation");
+		stage = "persistence";
+		const receiptPath = join(jobDirectory, "receipt.json");
+		const profilePath = join(jobDirectory, "profile.json");
+		const profileDigest = canonicalAgentProfileDigest(candidate);
+		for (const [path, value] of [[receiptPath, receipt], [profilePath, candidate]]) {
+			signal.throwIfAborted();
+			if (!publishExclusiveDurableFile(path, JSON.stringify(value), { mode: 256 })) throw new Error("training publication path already exists");
+		}
+		return {
+			mode: "training",
+			succeeded: true,
+			profile: candidate,
+			profileDigest,
+			receipt,
+			artifactPath,
+			receiptPath,
+			profilePath
+		};
+	} catch (error) {
+		let cleanupError;
+		if (jobDirectory) try {
+			await rm(join(jobDirectory, "profile.json"), { force: true });
+			syncDurableDirectory(jobDirectory);
+		} catch (failure) {
+			cleanupError = failure instanceof Error ? failure.message : "profile cleanup failed";
+		}
+		return {
+			mode: "training",
+			succeeded: false,
+			stage,
+			reason: error instanceof Error ? error.message : typeof error === "string" ? error : "training failed",
+			servingMayExist,
+			trainingMayExist,
+			...cleanupError ? { cleanupError } : {},
+			...jobDirectory ? { outputDirectory: jobDirectory } : {}
+		};
+	} finally {
+		clearTimer?.();
+		cancellation.release();
+	}
+}
+//#endregion
 //#region src/improvement/improve.ts
 async function improve(profileOrCode, opts) {
 	if (opts === void 0) {
@@ -2073,6 +2463,11 @@ async function improve(profileOrCode, opts) {
 		if (code?.surface !== "code") throw new ConfigError("improve(): the one-argument form requires { surface: 'code', ... }");
 		return runCodeImprovement(code);
 	}
+	if (opts === null || typeof opts !== "object") throw new ConfigError("improve(): options must be an object");
+	if ("mode" in opts) {
+		if (opts.mode !== "training") throw new ConfigError("improve(): unsupported mode");
+		return runProfileTraining(profileOrCode, opts);
+	}
 	if (opts.surface === "code") throw new ConfigError("improve(): code takes one argument: improve({ surface: 'code', ... })");
 	const parsedProfile = agentProfileSchema.safeParse(profileOrCode);
 	if (!parsedProfile.success) throw new ConfigError(`improve(): input is not a valid AgentProfile: ${parsedProfile.error.message}`);
@@ -2967,6 +3362,12 @@ async function proposeAgentProfileImprovement(options) {
 	const baselineStateDigest = profileStateDigest(options.stateDigest, source.sourceIdentity, profile);
 	if (baselineStateDigest !== source.sourceDigest) throw new Error("profile improvement source digest does not match the measured profile state");
 	const policy = profilePolicyWithBudget(options.benchmark.policy, options.budgetUsd);
+	const benchmark = sealProfileImprovementBenchmark({
+		...options.benchmark,
+		policy
+	});
+	const heldOutDigests = new Set(benchmark.tasks.map((task) => task.scenario.digest));
+	assertProfileTrainingIsHeldOut(profile, heldOutDigests);
 	if (options.improvement.costCeiling !== void 0 && !numbersApproximatelyEqual(options.improvement.costCeiling, options.budgetUsd)) throw new Error("profile improvement costCeiling must equal the run budgetUsd");
 	const { analysis, findings } = await analyzeAgentImprovement(options.runId, options.analysis, costLedger, options.signal);
 	const proposalFindings = immutableCandidateValue([...inputFindings, ...findings]);
@@ -2994,10 +3395,7 @@ async function proposeAgentProfileImprovement(options) {
 			if (!step.id) throw new Error("profile improvement change requires an exact diff id");
 			return step.id;
 		});
-		const benchmark = sealProfileImprovementBenchmark({
-			...options.benchmark,
-			policy
-		});
+		assertProfileTrainingIsHeldOut(candidateProfile, heldOutDigests);
 		assertProfileReleaseWorkIsFresh(benchmark, improvement);
 		const experiment = sealAgentProfileImprovementExperiment({
 			kind: "agent-profile-improvement-experiment",
@@ -3294,17 +3692,17 @@ function assertExactExperimentInput(input, experiment, bundle) {
 	if (input.experiment.digest !== experiment.digest || input.bundle.digest !== bundle.digest || !task || input.task.digest !== task.digest || input.benchmarkCell.suiteDigest !== experiment.benchmark.suite.digest || input.seed !== experiment.benchmark.suite.seeds[index]) throw new Error("Runtime received a substituted candidate experiment cell");
 }
 function assertCapturedInput(captured, expected, label) {
-	const bytes = canonicalCandidateBytes(omitTopLevelDigest(expected));
+	const bytes = canonicalCandidateBytes$1(omitTopLevelDigest(expected));
 	if (captured.digest !== expected.digest || captured.material.sha256 !== expected.digest || captured.material.byteLength !== bytes.byteLength) throw new Error(`candidate materialization substituted its ${label}`);
 }
 function assertEvidenceMaterialDigest(evidence, label) {
-	const bytes = canonicalCandidateBytes(evidence.material);
+	const bytes = canonicalCandidateBytes$1(evidence.material);
 	if (canonicalCandidateDigest$1(evidence.material) !== evidence.digest || evidence.artifact.sha256 !== evidence.digest || evidence.artifact.byteLength !== bytes.byteLength) throw new Error(`${label} digest does not match its canonical material`);
 }
 function sameOrderedValues(left, right) {
 	return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 //#endregion
-export { agentImprovementTargetInput as A, ROLLOUT_POLICY_EXTENSION as B, optimizationActivationReceiptFromMetadata as C, agentImprovementProfileSurfaceDigest as D, agentImprovementProfileDiffs as E, isAgentImprovementProfileSurface as F, structuralRolloutPolicyFromProfile as G, normalizeRolloutPolicy as H, isAgentProfileMeasuredSurface as I, defaultBuildPrompt as J, agenticGenerator as K, improve as L, agentProfileImprovementStateDigest as M, assertProfileImprovementTargetsShareIdentity as N, agentImprovementProfileSurfaceInput as O, buildAgentImprovementActivationTargets as P, withMethodRuntimeControls as R, createOptimizationActivationReceipt as S, AGENT_PROFILE_MEASURED_SURFACES as T, parseRolloutPolicy as U, applyRolloutPolicyToProfile as V, serializeRolloutPolicy as W, profilePolicyWithBudget as _, executeAgentCandidateExperimentCell as a, profileTaskScenarioIdentity as b, requireSealedCandidateExperiment as c, verifyAgentImprovementActivation as d, verifyAgentImprovementProposal as f, profileImprovementMetadata as g, createProfileImprovementCostLedger as h, createAgentImprovementProposal as i, agentImprovementTargetProfileDiffs as j, agentImprovementTargetDigest as k, reviewAgentImprovementProposal as l, verifyCandidateExecutionEvidence as m, createAgentImprovementActivation as n, proposeAgentImprovement as o, verifyAgentImprovementReview as p, commandVerifier as q, createAgentImprovementMeasuredComparison as r, proposeAgentProfileImprovement as s, AgentCandidateExperimentCellExecutionError as t, runAgentCandidateExperiment as u, profilePreparationAccounting as v, AGENT_IMPROVEMENT_PROFILE_SURFACES as w, sealProfileImprovementBenchmark as x, profileStateDigest as y, rawTraceDistiller as z };
+export { agentImprovementTargetInput as A, assertCandidateValidator as B, optimizationActivationReceiptFromMetadata as C, agentImprovementProfileSurfaceDigest as D, agentImprovementProfileDiffs as E, isAgentImprovementProfileSurface as F, applyRolloutPolicyToProfile as G, parseExecutionRef as H, isAgentProfileMeasuredSurface as I, serializeRolloutPolicy as J, normalizeRolloutPolicy as K, improve as L, agentProfileImprovementStateDigest as M, assertProfileImprovementTargetsShareIdentity as N, agentImprovementProfileSurfaceInput as O, buildAgentImprovementActivationTargets as P, defaultBuildPrompt as Q, createCommandProfileTrainer as R, createOptimizationActivationReceipt as S, AGENT_PROFILE_MEASURED_SURFACES as T, rawTraceDistiller as U, assertProfileTrainingIsHeldOut as V, ROLLOUT_POLICY_EXTENSION as W, agenticGenerator as X, structuralRolloutPolicyFromProfile as Y, commandVerifier as Z, profilePolicyWithBudget as _, executeAgentCandidateExperimentCell as a, profileTaskScenarioIdentity as b, requireSealedCandidateExperiment as c, verifyAgentImprovementActivation as d, verifyAgentImprovementProposal as f, profileImprovementMetadata as g, createProfileImprovementCostLedger as h, createAgentImprovementProposal as i, agentImprovementTargetProfileDiffs as j, agentImprovementTargetDigest as k, reviewAgentImprovementProposal as l, verifyCandidateExecutionEvidence as m, createAgentImprovementActivation as n, proposeAgentImprovement as o, verifyAgentImprovementReview as p, parseRolloutPolicy as q, createAgentImprovementMeasuredComparison as r, proposeAgentProfileImprovement as s, AgentCandidateExperimentCellExecutionError as t, runAgentCandidateExperiment as u, profilePreparationAccounting as v, AGENT_IMPROVEMENT_PROFILE_SURFACES as w, sealProfileImprovementBenchmark as x, profileStateDigest as y, withMethodRuntimeControls as z };
 
-//# sourceMappingURL=improvement-cycle-BpSVwIJw.js.map
+//# sourceMappingURL=improvement-cycle-B049YmQ8.js.map