textopt 0.0.0

package/dist/gepa/index.mjs

@@ -0,0 +1,1652 @@
+import { c as candidateFingerprint, d as createMemoryCache, f as stableHash, i as measuredMean, l as runFingerprint, n as costExhausted, o as createDeadline, p as createBudget, r as createEvaluator, s as assertResumable, t as BudgetExhausted, u as componentNames } from "../evaluation-BV0nSZVx.mjs";
+import { t as mapWithConcurrency } from "../concurrency-D58PWeSk.mjs";
+import { i as sum, n as mean, r as signFlipPValue, t as argmax } from "../math-DhrDmpFS.mjs";
+import { n as formatDemos, r as parseDemos } from "../demos-Degx6UmP.mjs";
+import { t as createSeededRng } from "../rng-Dtc5eZ_W.mjs";
+import { a as createDefaultProposer, i as buildSimplifyPrompt, n as buildReflectionPrompt, o as diverseReflectionStrategies, r as buildRewritePrompt, t as buildGeneralizePrompt } from "../reflection-mwMhrjs_.mjs";
+import { t as createEpochShuffledSampler } from "../sampling-CfHt7Gue.mjs";
+//#region src/gepa/demos.ts
+const DEFAULT_MAX_DEMOS = 4;
+const DEFAULT_MIN_SCORE = 1;
+/**
+* A proposer that fills demonstration components from rollouts the run has
+* already paid for.
+*
+* The reflective dataset carries every minibatch rollout's input, output and
+* score, so the successful ones are a few-shot block sitting in memory. Taking
+* them costs no rollout and no reflection call — the search buys demos as a
+* side effect of the evaluations it was making anyway.
+*
+* A proposal appends to the block its parent already holds rather than
+* replacing it: a block built from one minibatch alone would hold three or
+* four examples and forget every earlier one. Accumulation therefore follows
+* the accepted lineage — a demo only persists if the candidate carrying it
+* beat its parent, which is the same bar every other component is held to.
+*/
+function createDemoProposer(args) {
+	const { components, minScore = DEFAULT_MIN_SCORE, maxDemos = DEFAULT_MAX_DEMOS, render, fallback = createDefaultProposer() } = args;
+	if (components.length === 0) throw new Error("createDemoProposer requires at least one component");
+	const demoComponents = new Set(components);
+	return async (proposeArgs) => {
+		const { candidate, reflectiveDataset, componentsToUpdate } = proposeArgs;
+		const demoTargets = componentsToUpdate.filter((name) => demoComponents.has(name));
+		const others = componentsToUpdate.filter((name) => !demoComponents.has(name));
+		const patch = others.length === 0 ? {} : await fallback({
+			...proposeArgs,
+			componentsToUpdate: others
+		});
+		for (const name of demoTargets) {
+			const harvested = harvestDemos({
+				records: reflectiveDataset[name] ?? [],
+				minScore
+			});
+			if (harvested.length === 0) continue;
+			const kept = mergeDemos({
+				existing: parseDemos(candidate[name] ?? ""),
+				harvested,
+				maxDemos
+			});
+			const block = formatDemos(kept, render === void 0 ? {} : { render });
+			if (block !== candidate[name]) patch[name] = block;
+		}
+		return patch;
+	};
+}
+function harvestDemos(args) {
+	const { records, minScore } = args;
+	return records.filter((record) => (record.score ?? Number.NEGATIVE_INFINITY) >= minScore).map((record) => ({
+		input: record.inputs,
+		output: record.generatedOutputs,
+		score: record.score
+	}));
+}
+/**
+* Newest wins on overflow. A demo harvested later came from a stronger
+* candidate, since a weaker one would not have scored highly enough to be
+* harvested at all — so the tail of the block is the better end of it.
+*/
+function mergeDemos(args) {
+	const { existing, harvested, maxDemos } = args;
+	const merged = [...existing];
+	const seen = new Set(existing.map((demo) => keyOf(demo.input)));
+	for (const demo of harvested) {
+		const key = keyOf(demo.input);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		merged.push(demo);
+	}
+	return merged.slice(Math.max(0, merged.length - maxDemos));
+}
+function keyOf(input) {
+	try {
+		return JSON.stringify(input) ?? String(input);
+	} catch {
+		return String(input);
+	}
+}
+//#endregion
+//#region src/gepa/pipeline.ts
+const DEFAULT_CONCURRENCY = 1;
+/**
+* A GEPA adapter for a system built from several modules in sequence, where
+* each module's instruction is its own candidate component.
+*
+* The work this saves is attribution. Reflection on a multi-module system is
+* only as good as the evidence it sees, and the evidence a module needs is what
+* *it* received and produced — not the pipeline's input and final answer, which
+* is what an adapter written in a hurry ends up showing every component.
+*
+* The feedback is end-to-end, and every module sees the same string. That is
+* the honest default rather than a shortcut: a metric scores the final output,
+* so nothing in a score alone says which module lost the point. A caller who
+* can attribute better should score the steps themselves — `score` is handed
+* the whole trace for exactly that.
+*
+* Errors from a module are not caught. A helper cannot tell a rate limit from a
+* bug in a module, and guessing wrong either buries the bug or fails the run
+* over a blip. Classify inside `run` and return a transient `ScoreResult` from
+* `score`, or let the optimizer's `raiseOnError` decide.
+*/
+function createPipelineAdapter(args) {
+	const { modules, input = (datum) => datum, score, concurrency = DEFAULT_CONCURRENCY } = args;
+	if (modules.length === 0) throw new Error("createPipelineAdapter requires at least one module");
+	return {
+		evaluate: async ({ batch, candidate, captureTraces, signal }) => {
+			const rollouts = await mapWithConcurrency({
+				items: batch,
+				limit: concurrency,
+				signal,
+				task: async (datum) => {
+					const trace = await runPipeline({
+						modules,
+						candidate,
+						datum,
+						input,
+						signal
+					});
+					const output = trace.steps.at(-1).output;
+					return {
+						trace,
+						output,
+						scored: await score({
+							datum,
+							output,
+							steps: trace.steps
+						})
+					};
+				}
+			});
+			const batchResult = {
+				outputs: rollouts.map((rollout) => rollout.output),
+				scores: rollouts.map((rollout) => rollout.scored.score),
+				feedback: rollouts.map((rollout) => rollout.scored.feedback ?? ""),
+				usage: rollouts.map((rollout) => rollout.scored.usage ?? {}),
+				transient: rollouts.map((rollout) => rollout.scored.transient ?? false),
+				objectiveScores: rollouts.map((rollout) => rollout.scored.objectiveScores ?? {})
+			};
+			return captureTraces ? {
+				...batchResult,
+				trajectories: rollouts.map((r) => r.trace)
+			} : batchResult;
+		},
+		makeReflectiveDataset: ({ evaluation, componentsToUpdate }) => {
+			const dataset = {};
+			for (const component of componentsToUpdate) dataset[component] = recordsFor({
+				component,
+				evaluation
+			});
+			return dataset;
+		}
+	};
+}
+async function runPipeline(args) {
+	const { modules, candidate, datum, input, signal } = args;
+	const steps = [];
+	let carried = input(datum);
+	for (const module of modules) {
+		const output = await module.run({
+			instruction: candidate[module.component],
+			input: carried,
+			datum,
+			signal
+		});
+		steps.push({
+			component: module.component,
+			input: carried,
+			output
+		});
+		carried = output;
+	}
+	return { steps };
+}
+function recordsFor(args) {
+	const { component, evaluation } = args;
+	return (evaluation.trajectories ?? []).map((trace, index) => {
+		const step = trace.steps.find((entry) => entry.component === component);
+		return {
+			inputs: step?.input,
+			generatedOutputs: step?.output,
+			feedback: evaluation.feedback?.[index] ?? "",
+			score: evaluation.scores[index],
+			evidence: { component }
+		};
+	});
+}
+//#endregion
+//#region src/gepa/merge.ts
+const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_VAL_OVERLAP_FLOOR = 5;
+/**
+* System-aware merge (GEPA's crossover). Two dominator lineages that descend
+* from a common ancestor neither of them regressed against can be recombined
+* for free: for every component, take the version from whichever descendant
+* actually moved it. Sampling is random rather than greedy — always merging the
+* two strongest lineages collapses the frontier's diversity, which is the thing
+* merge exists to exploit.
+*
+* Returns a proposal to be *tested*, not an accepted candidate: the caller
+* still has to score it.
+*/
+function proposeMerge(args) {
+	const { records, pool, rng, attempted, attemptedDescriptions, maxAttempts = DEFAULT_MAX_ATTEMPTS, valOverlapFloor = DEFAULT_VAL_OVERLAP_FLOOR } = args;
+	if (pool.length < 2 || records.length < 3) return null;
+	const ancestries = buildAncestries(records);
+	const existing = new Set(records.map((record) => fingerprint(record.candidate)));
+	for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+		const triplet = sampleTriplet({
+			records,
+			pool,
+			rng,
+			attempted,
+			ancestries,
+			maxAttempts,
+			valOverlapFloor
+		});
+		if (triplet === null) continue;
+		const { parentIds, ancestorId } = triplet;
+		const merged = mergeComponents({
+			records,
+			parentIds,
+			ancestorId,
+			rng
+		});
+		const descriptionKey = `${parentIds[0]}:${parentIds[1]}:${merged.sources.join(",")}`;
+		if (attemptedDescriptions.has(descriptionKey) || existing.has(fingerprint(merged.candidate))) continue;
+		return {
+			candidate: merged.candidate,
+			parentIds,
+			ancestorId,
+			attemptKey: `${parentIds[0]}:${parentIds[1]}:${ancestorId}`,
+			descriptionKey
+		};
+	}
+	return null;
+}
+/**
+* Picks the validation instances a merge is judged on: up to `size` ids, drawn
+* evenly from the instances each parent uniquely wins plus the ones they tie
+* on. A uniform sample would usually miss the handful of instances that
+* distinguish the parents at all, which is exactly where a merge either pays
+* off or breaks.
+*/
+function selectMergeSubsample(args) {
+	const { scores1, scores2, rng, size = 5 } = args;
+	const ids = scores1.map((_, index) => index).filter((index) => scores1[index] !== void 0 && scores2[index] !== void 0);
+	if (ids.length === 0) return [];
+	const firstWins = ids.filter((id) => scores1[id] > scores2[id]);
+	const secondWins = ids.filter((id) => scores2[id] > scores1[id]);
+	const ties = ids.filter((id) => !firstWins.includes(id) && !secondWins.includes(id));
+	const perBucket = Math.max(1, Math.ceil(size / 3));
+	const selected = [];
+	for (const bucket of [
+		firstWins,
+		secondWins,
+		ties
+	]) {
+		if (selected.length >= size) break;
+		const available = bucket.filter((id) => !selected.includes(id));
+		const take = Math.min(available.length, perBucket, size - selected.length);
+		if (take > 0) selected.push(...rng.sample(available, take));
+	}
+	const remaining = size - selected.length;
+	if (remaining > 0) {
+		const unused = ids.filter((id) => !selected.includes(id));
+		if (unused.length >= remaining) selected.push(...rng.sample(unused, remaining));
+		else for (let index = 0; index < remaining; index += 1) selected.push(rng.pick(ids));
+	}
+	return selected.slice(0, size);
+}
+function sampleTriplet(args) {
+	const { records, pool, rng, attempted, ancestries, maxAttempts, valOverlapFloor } = args;
+	for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+		const [first, second] = rng.sample(pool, 2);
+		if (first === second) continue;
+		const left = Math.min(first, second);
+		const right = Math.max(first, second);
+		const leftAncestry = ancestries[left];
+		const rightAncestry = ancestries[right];
+		if (leftAncestry.has(right) || rightAncestry.has(left)) continue;
+		if (overlap({
+			records,
+			left,
+			right
+		}) < valOverlapFloor) continue;
+		const eligible = [...leftAncestry].filter((id) => rightAncestry.has(id)).filter((ancestorId) => isEligibleAncestor({
+			records,
+			left,
+			right,
+			ancestorId,
+			attempted
+		}));
+		if (eligible.length === 0) continue;
+		return {
+			parentIds: [left, right],
+			ancestorId: rng.weighted(eligible, eligible.map((id) => records[id].aggregateScore))
+		};
+	}
+	return null;
+}
+function overlap(args) {
+	const leftScores = args.records[args.left].instanceScores;
+	const rightScores = args.records[args.right].instanceScores;
+	let shared = 0;
+	for (let index = 0; index < leftScores.length; index += 1) if (leftScores[index] !== void 0 && rightScores[index] !== void 0) shared += 1;
+	return shared;
+}
+function isEligibleAncestor(args) {
+	const { records, left, right, ancestorId, attempted } = args;
+	if (attempted.has(`${left}:${right}:${ancestorId}`)) return false;
+	const ancestor = records[ancestorId];
+	const leftRecord = records[left];
+	const rightRecord = records[right];
+	if (ancestor.aggregateScore > leftRecord.aggregateScore || ancestor.aggregateScore > rightRecord.aggregateScore) return false;
+	return hasComplementaryComponent({
+		ancestor: ancestor.candidate,
+		left: leftRecord.candidate,
+		right: rightRecord.candidate
+	});
+}
+/**
+* True when at least one component was changed by exactly one descendant. Two
+* lineages that rewrote every shared component give the merge nothing to
+* attribute an improvement to.
+*/
+function hasComplementaryComponent(args) {
+	const { ancestor, left, right } = args;
+	return componentNames(ancestor).some((name) => {
+		const base = ancestor[name];
+		return (base === left[name] || base === right[name]) && left[name] !== right[name];
+	});
+}
+function mergeComponents(args) {
+	const { records, parentIds, ancestorId, rng } = args;
+	const [leftId, rightId] = parentIds;
+	const ancestor = records[ancestorId].candidate;
+	const leftRecord = records[leftId];
+	const rightRecord = records[rightId];
+	const candidate = { ...ancestor };
+	const sources = [];
+	for (const name of componentNames(ancestor)) {
+		const base = ancestor[name];
+		const leftText = leftRecord.candidate[name];
+		const rightText = rightRecord.candidate[name];
+		const sourceId = resolveComponentSource({
+			base,
+			leftText,
+			rightText,
+			leftRecord,
+			rightRecord,
+			rng
+		});
+		candidate[name] = records[sourceId].candidate[name];
+		sources.push(sourceId);
+	}
+	return {
+		candidate,
+		sources
+	};
+}
+function resolveComponentSource(args) {
+	const { base, leftText, rightText, leftRecord, rightRecord, rng } = args;
+	if ((base === leftText || base === rightText) && leftText !== rightText) return base === leftText ? rightRecord.id : leftRecord.id;
+	if (base !== leftText && base !== rightText) {
+		if (leftRecord.aggregateScore > rightRecord.aggregateScore) return leftRecord.id;
+		if (rightRecord.aggregateScore > leftRecord.aggregateScore) return rightRecord.id;
+		return rng.pick([leftRecord.id, rightRecord.id]);
+	}
+	return leftRecord.id;
+}
+/** Strict ancestors of each record, keyed by record id. */
+function buildAncestries(records) {
+	const ancestries = [];
+	for (const record of records) {
+		const ancestry = /* @__PURE__ */ new Set();
+		for (const parentId of record.parentIds) {
+			ancestry.add(parentId);
+			for (const id of ancestries[parentId] ?? []) ancestry.add(id);
+		}
+		ancestries[record.id] = ancestry;
+	}
+	return ancestries;
+}
+function fingerprint(candidate) {
+	return JSON.stringify(componentNames(candidate).sort().map((name) => [name, candidate[name]]));
+}
+//#endregion
+//#region src/gepa/pareto.ts
+function computeInstanceBests(scoreMatrix) {
+	const first = scoreMatrix[0];
+	if (first === void 0) return [];
+	const bests = first.map((score) => score ?? Number.NEGATIVE_INFINITY);
+	for (let candidate = 1; candidate < scoreMatrix.length; candidate += 1) {
+		const row = scoreMatrix[candidate];
+		for (let instance = 0; instance < bests.length; instance += 1) {
+			const score = row[instance] ?? Number.NEGATIVE_INFINITY;
+			if (score > bests[instance]) bests[instance] = score;
+		}
+	}
+	return bests;
+}
+/**
+* For each instance, the set of candidates achieving the best score on it.
+* Candidates within `epsilon` of the best count as tied, which keeps noisy
+* metrics from collapsing the frontier to a single lineage.
+*/
+function buildInstanceFronts(args) {
+	const { scoreMatrix, epsilon = 0 } = args;
+	return computeInstanceBests(scoreMatrix).map((best, instance) => {
+		const front = /* @__PURE__ */ new Set();
+		for (let candidate = 0; candidate < scoreMatrix.length; candidate += 1) {
+			const score = scoreMatrix[candidate][instance];
+			if (score !== void 0 && score >= best - epsilon) front.add(candidate);
+		}
+		return front;
+	});
+}
+/** The best value any candidate reached on each objective. */
+function objectiveBests(objectiveScores) {
+	const bests = {};
+	for (const scores of objectiveScores) for (const [objective, value] of Object.entries(scores ?? {})) {
+		const best = bests[objective];
+		if (best === void 0 || value > best) bests[objective] = value;
+	}
+	return bests;
+}
+/**
+* The objective-wise counterpart of `buildInstanceFronts`: one front per named
+* objective, holding the candidates that lead it. Optimizing a system against
+* several metrics at once — accuracy against cost, quality against latency —
+* means the interesting candidates are the ones that lead *an* objective, which
+* an average over instances hides.
+*/
+function buildObjectiveFronts(args) {
+	const { objectiveScores, epsilon = 0 } = args;
+	const bests = objectiveBests(objectiveScores);
+	return Object.entries(bests).map(([objective, best]) => {
+		const front = /* @__PURE__ */ new Set();
+		for (let candidate = 0; candidate < objectiveScores.length; candidate += 1) {
+			const value = objectiveScores[candidate]?.[objective];
+			if (value !== void 0 && value >= best - epsilon) front.add(candidate);
+		}
+		return front;
+	});
+}
+/**
+* Drop candidates that contribute nothing unique: a candidate is dominated when
+* every instance it wins is also won by some surviving candidate. Candidates are
+* considered in ascending aggregate score, so weaker duplicates are removed
+* first. Mirrors `remove_dominated_programs` in the reference implementation.
+*/
+function pruneDominatedFronts(args) {
+	const { fronts, aggregateScores } = args;
+	const frontsByCandidate = indexFrontsByCandidate(fronts);
+	const ordered = [...frontsByCandidate.keys()].sort((a, b) => (aggregateScores[a] ?? 0) - (aggregateScores[b] ?? 0));
+	const survivors = new Set(ordered);
+	for (const candidate of ordered) {
+		survivors.delete(candidate);
+		if (!frontsByCandidate.get(candidate).every((index) => hasSurvivor({
+			front: fronts[index],
+			survivors
+		}))) survivors.add(candidate);
+	}
+	return fronts.map((front) => new Set([...front].filter((candidate) => survivors.has(candidate))));
+}
+/**
+* Sample a parent candidate with probability proportional to the number of
+* instances it is best on, after dominated candidates are pruned.
+*/
+function selectParetoCandidate(args) {
+	const { fronts, aggregateScores, rng } = args;
+	const pruned = pruneDominatedFronts({
+		fronts,
+		aggregateScores
+	});
+	const samplingPool = [];
+	for (const front of pruned) for (const candidate of front) samplingPool.push(candidate);
+	if (samplingPool.length === 0) return argmax(aggregateScores);
+	return rng.pick(samplingPool);
+}
+function indexFrontsByCandidate(fronts) {
+	const index = /* @__PURE__ */ new Map();
+	fronts.forEach((front, position) => {
+		for (const candidate of front) {
+			const owned = index.get(candidate);
+			if (owned === void 0) index.set(candidate, [position]);
+			else owned.push(position);
+		}
+	});
+	return index;
+}
+function hasSurvivor(args) {
+	const { front, survivors } = args;
+	for (const candidate of front) if (survivors.has(candidate)) return true;
+	return false;
+}
+//#endregion
+//#region src/gepa/strategies.ts
+/**
+* Default parent selection: sample from the instance-wise Pareto frontier with
+* probability proportional to how many validation instances a candidate is best
+* on. This is what keeps GEPA from tunnelling into one lineage.
+*
+* `frontier` chooses what the fronts are taken over. "instance" is GEPA as
+* published. "objective" tracks candidates leading each named objective the
+* adapter reports, and "hybrid" pools both — a candidate then earns selection
+* weight for every instance it wins *and* every objective it leads.
+*/
+function paretoSelector(args = {}) {
+	const { epsilon = 0, frontier = "instance" } = args;
+	return ({ state, rng }) => {
+		const fronts = [];
+		if (frontier !== "objective") fronts.push(...buildInstanceFronts({
+			scoreMatrix: state.scoreMatrix,
+			epsilon
+		}));
+		if (frontier !== "instance") {
+			const objectiveFronts = buildObjectiveFronts({
+				objectiveScores: state.objectiveScores ?? [],
+				epsilon
+			});
+			if (objectiveFronts.length === 0) throw new Error(`paretoSelector frontier "${frontier}" needs objective scores, but no candidate has any; have the adapter return objectiveScores or use frontier "instance"`);
+			fronts.push(...objectiveFronts);
+		}
+		return selectParetoCandidate({
+			fronts,
+			aggregateScores: state.aggregateScores,
+			rng
+		});
+	};
+}
+/** Greedy hill climbing. Useful as an ablation baseline. */
+function currentBestSelector() {
+	return ({ state }) => argmax(state.aggregateScores);
+}
+function epsilonGreedySelector(args) {
+	const { epsilon } = args;
+	return ({ state, rng }) => {
+		if (rng.next() < epsilon) return rng.nextInt(state.aggregateScores.length);
+		return argmax(state.aggregateScores);
+	};
+}
+/** Pareto selection restricted to the top k candidates by aggregate score. */
+function topKParetoSelector(args) {
+	const { k, epsilon = 0 } = args;
+	return ({ state, rng }) => {
+		const ranked = state.aggregateScores.map((score, index) => ({
+			score,
+			index
+		})).sort((a, b) => b.score - a.score).slice(0, k).map((entry) => entry.index);
+		const allowed = new Set(ranked);
+		const nonEmpty = buildInstanceFronts({
+			scoreMatrix: state.scoreMatrix,
+			epsilon
+		}).map((front) => new Set([...front].filter((id) => allowed.has(id)))).filter((front) => front.size > 0);
+		if (nonEmpty.length === 0) return argmax(state.aggregateScores);
+		return selectParetoCandidate({
+			fronts: nonEmpty,
+			aggregateScores: state.aggregateScores,
+			rng
+		});
+	};
+}
+/**
+* Score every accepted candidate on the whole validation set. This is GEPA as
+* published: the frontier is exact, and the cost is one full sweep per
+* acceptance.
+*/
+function fullEvaluationPolicy() {
+	return {
+		selectInstances: ({ validationSet }) => validationSet.map((_, index) => index),
+		bestCandidate: bestByMeanThenCoverage
+	};
+}
+/**
+* A full sweep, with the winner chosen by a lower confidence bound on its mean
+* rather than by the mean itself: `mean - z * standardError`, over the
+* instances the candidate was scored on.
+*
+* The reference picks the highest mean. That is an argmax over every candidate
+* a run produced, all measured on the same instances, so the winner is
+* systematically the one whose instance-level noise happened to land in its
+* favour — the gap this library reports between `bestScore` and `testScore`.
+* Penalising spread prefers a candidate that was even across the set to one
+* carried by a few instances, at the cost of sometimes returning a genuinely
+* better but less consistent candidate. It changes only which candidate is
+* reported, never which ones the search explores.
+*/
+function lowerBoundEvaluationPolicy(args = {}) {
+	const { z = 1 } = args;
+	return {
+		selectInstances: ({ validationSet }) => validationSet.map((_, index) => index),
+		bestCandidate: (records) => bestByLowerBound({
+			records,
+			z
+		})
+	};
+}
+/**
+* Score each candidate on a random subset of the validation set. Cheaper per
+* acceptance, at the cost of comparing candidates measured on different
+* instances — coverage breaks ties, so a candidate cannot win by having been
+* asked fewer questions.
+*/
+function subsampledEvaluationPolicy(args) {
+	const { size } = args;
+	if (!Number.isFinite(size) || size <= 0) throw new Error(`subsampledEvaluationPolicy requires a positive size, received ${size}`);
+	return {
+		selectInstances: ({ validationSet, rng }) => rng.sample(validationSet.map((_, index) => index), size),
+		bestCandidate: bestByMeanThenCoverage
+	};
+}
+/**
+* One component per selection, cycling in declaration order from the parent's
+* own cursor. Updating a single component at a time is what makes the minibatch
+* acceptance test attributable; keying off the parent's cursor rather than the
+* global iteration is what guarantees every component of a rarely-selected
+* lineage eventually gets a turn.
+*/
+function roundRobinComponentSelector() {
+	return ({ candidate, cursor }) => {
+		const names = componentNames(candidate);
+		if (names.length === 0) throw new Error("Candidate has no components to update");
+		return [names[cursor % names.length]];
+	};
+}
+/** Update every component in a single reflection call. */
+function allComponentsSelector() {
+	return ({ candidate }) => componentNames(candidate);
+}
+/**
+* Accept a mutation only when it beats its parent on the same minibatch. Cheap
+* gate that keeps full validation sweeps for candidates that showed a signal.
+*/
+function improvementAcceptance(args = {}) {
+	const { minImprovement = 0 } = args;
+	return ({ parentScores, childScores }) => sum(childScores) > sum(parentScores) + minImprovement;
+}
+/**
+* Accepts a child only when a paired permutation test over the minibatch says
+* its gain is unlikely to be noise. Pairs are the same instances run by both
+* candidates, so the test is over the per-instance differences.
+*
+* The reference accepts on any sum improvement. On a minibatch of three that
+* promotes a candidate one lucky rollout ahead, which is what fills a pool
+* with children the validation sweep then discards. The cost is that small
+* batches cannot produce small p-values at all — with three instances the
+* smallest attainable is 0.125 — so this accepts only a clean sweep there.
+* That is the honest reading of three rollouts, not a limitation to tune
+* around: raise `minibatchSize` to buy the power to detect smaller gains.
+*/
+function pairedPermutationAcceptance(args = {}) {
+	const { alpha = .2, maxExact = 16 } = args;
+	return ({ parentScores, childScores }) => {
+		const differences = [];
+		for (let index = 0; index < parentScores.length; index += 1) differences.push(childScores[index] - parentScores[index]);
+		const observed = sum(differences);
+		if (observed <= 0) return false;
+		return signFlipPValue({
+			differences,
+			observed,
+			maxExact
+		}) <= alpha;
+	};
+}
+/**
+* Highest mean over the instances it was scored on, with wider coverage
+* winning a tie: a candidate measured on more instances has earned the same
+* mean against more evidence.
+*/
+function bestByMeanThenCoverage(records) {
+	let bestId = 0;
+	let bestScore = Number.NEGATIVE_INFINITY;
+	let bestCoverage = -1;
+	for (const record of records) {
+		const coverage = record.instanceScores.filter((score) => score !== void 0).length;
+		if (record.aggregateScore > bestScore || record.aggregateScore === bestScore && coverage > bestCoverage) {
+			bestId = record.id;
+			bestScore = record.aggregateScore;
+			bestCoverage = coverage;
+		}
+	}
+	return bestId;
+}
+/**
+* Highest lower bound on the mean, over the instances each candidate was
+* scored on. The bound is `mean - z * standardError`; a candidate scored on
+* one instance has no spread to measure, so it is ranked on its mean alone
+* rather than being flattered by an undefined variance.
+*/
+function bestByLowerBound(args) {
+	const { records, z } = args;
+	let bestId = 0;
+	let bestBound = Number.NEGATIVE_INFINITY;
+	for (const record of records) {
+		const scored = record.instanceScores.filter((score) => score !== void 0);
+		if (scored.length === 0) continue;
+		const bound = scored.length < 2 ? record.aggregateScore : record.aggregateScore - z * standardError(scored);
+		if (bound > bestBound) {
+			bestBound = bound;
+			bestId = record.id;
+		}
+	}
+	return bestId;
+}
+function standardError(scores) {
+	const mean = scores.reduce((total, score) => total + score, 0) / scores.length;
+	const variance = scores.reduce((total, score) => total + (score - mean) ** 2, 0) / (scores.length - 1);
+	return Math.sqrt(variance / scores.length);
+}
+//#endregion
+//#region src/gepa/optimize.ts
+const DEFAULT_MINIBATCH_SIZE = 3;
+const DEFAULT_REJECTED_PROPOSAL_MEMORY = 3;
+const DEFAULT_MAX_MERGES = 5;
+const MERGE_SUBSAMPLE_SIZE = 5;
+var ReflectionBudgetExhausted = class extends Error {};
+/**
+* Reflective prompt evolution: propose, screen on a minibatch, promote what
+* survives, and track the Pareto frontier of everything promoted.
+*
+* One instance is a configured search that can be run against any number of
+* tasks. It holds no run state, so two runs never share a shuffle position, a
+* budget or a candidate pool.
+*/
+var GepaOptimizer = class {
+	#config;
+	constructor(config = {}) {
+		assertGepaConfig(config);
+		this.#config = config;
+	}
+	async optimize(task) {
+		return runGepa({
+			config: this.#config,
+			task
+		});
+	}
+};
+async function runGepa(args) {
+	const { config, task } = args;
+	const { minibatchSize = DEFAULT_MINIBATCH_SIZE, maxIterations = Number.POSITIVE_INFINITY, seed = 0, candidateSelector = paretoSelector(), acceptance = improvementAcceptance(), merge, skipPerfectScore = true, perfectScore = 1, rejectedProposalMemory = DEFAULT_REJECTED_PROPOSAL_MEMORY, proposals, reflection, checkpointCache = true, trackBestOutputs = false, raiseOnError = true } = config;
+	const { seedCandidate, trainingSet, validationSet = trainingSet, testSet, adapter, reflect, maxMetricCalls, componentSelector = roundRobinComponentSelector(), batchSampler = createEpochShuffledSampler({ minibatchSize }), valEvaluationPolicy = fullEvaluationPolicy(), cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = defaultInstanceId, onEvent, onCheckpoint, resumeFrom, signal } = task;
+	const deadline = createDeadline({ maxWallClockMs });
+	const seedComponents = componentNames(seedCandidate);
+	const mergeConfig = {
+		enabled: merge?.enabled ?? seedComponents.length > 1,
+		maxInvocations: merge?.maxInvocations ?? DEFAULT_MAX_MERGES,
+		...merge?.valOverlapFloor === void 0 ? {} : { valOverlapFloor: merge.valOverlapFloor }
+	};
+	const proposalsPerIteration = proposals?.perIteration ?? 1;
+	const proposalConcurrency = proposals?.concurrency ?? 1;
+	const survivorsPerIteration = keepCount(proposals?.selection ?? "all");
+	if (trainingSet.length === 0) throw new Error("optimize requires a non-empty trainingSet");
+	if (validationSet.length === 0) throw new Error("optimize requires a non-empty validationSet; the Pareto frontier is tracked over validation instances");
+	if (seedComponents.length === 0) throw new Error("optimize requires a seed candidate with at least one component");
+	if (testSet !== void 0 && testSet.length === 0) throw new Error("optimize requires a non-empty testSet when one is given; omit it to skip held-out evaluation");
+	const evaluationCache = cache === false ? void 0 : cache ?? createMemoryCache();
+	const propose = adapter.proposeNewTexts?.bind(adapter) ?? createDefaultProposer({
+		...reflection?.buildPrompt === void 0 ? {} : { buildPrompt: reflection.buildPrompt },
+		...reflection?.strategies === void 0 ? {} : { strategies: reflection.strategies },
+		limits: {
+			...reflection?.maxRecords === void 0 ? {} : { maxRecords: reflection.maxRecords },
+			...reflection?.maxCharacters === void 0 ? {} : { maxCharacters: reflection.maxCharacters }
+		}
+	});
+	const trainingIds = trainingSet.map((datum, index) => instanceId({
+		datum,
+		index
+	}));
+	const validationIds = validationSet.map((datum, index) => instanceId({
+		datum,
+		index
+	}));
+	const testIds = testSet?.map((datum, index) => instanceId({
+		datum,
+		index
+	})) ?? [];
+	const fingerprint = runFingerprint({
+		seedCandidate,
+		trainingIds,
+		validationIds,
+		seed,
+		...cacheNamespace === void 0 ? {} : { cacheNamespace }
+	});
+	assertResumable({
+		fingerprint,
+		...resumeFrom === void 0 ? {} : { snapshot: resumeFrom }
+	});
+	const rng = createSeededRng(seed, resumeFrom?.rngState);
+	const budget = createBudget({
+		maxMetricCalls,
+		spent: resumeFrom?.metricCalls ?? 0
+	});
+	if (resumeFrom?.sampler !== void 0) batchSampler.restore?.(resumeFrom.sampler);
+	let reflectionCalls = resumeFrom?.reflectionCalls ?? 0;
+	/**
+	* The reflection budget is enforced at the call, not at the proposal: an
+	* adapter's own proposer may make any number of calls, and a cap that only
+	* counted proposals would not bound it.
+	*/
+	const countedReflect = async (args) => {
+		if (reflection?.maxCalls !== void 0 && reflectionCalls >= reflection.maxCalls) throw new ReflectionBudgetExhausted();
+		reflectionCalls += 1;
+		return reflect(args);
+	};
+	const records = restoreRecords({
+		records: resumeFrom?.records ?? [],
+		seedCandidate
+	});
+	const seenCandidates = new Set(records.map((record) => candidateFingerprint(record.candidate)));
+	const outputsByCandidate = /* @__PURE__ */ new Map();
+	const rejectedProposals = restoreRejections({
+		rejections: resumeFrom?.rejectedProposals ?? {},
+		components: seedComponents
+	});
+	let iteration = resumeFrom?.iteration ?? 0;
+	const mergeAttempts = new Set(resumeFrom?.merge.attempts);
+	const mergeDescriptions = new Set(resumeFrom?.merge.descriptions);
+	let mergesDue = resumeFrom?.merge.due ?? 0;
+	let totalMergesTested = resumeFrom?.merge.tested ?? 0;
+	let lastIterationAccepted = resumeFrom?.merge.lastIterationAccepted ?? false;
+	function emit(event) {
+		onEvent?.(event);
+	}
+	/**
+	* Copies everything mutable: a snapshot handed to `onCheckpoint` is a record
+	* of that moment, and would otherwise keep growing as the run continues.
+	*/
+	function takeSnapshot() {
+		const cached = checkpointCache ? evaluationCache?.entries?.() : void 0;
+		const samplerState = batchSampler.state?.();
+		return {
+			version: 1,
+			fingerprint,
+			records: copyRecords(records),
+			iteration,
+			metricCalls: budget.spent(),
+			reflectionCalls,
+			cacheHits: evaluator.cacheHits(),
+			...samplerState === void 0 ? {} : { sampler: samplerState },
+			rejectedProposals: snapshotRejections({
+				rejections: rejectedProposals,
+				components: seedComponents
+			}),
+			rngState: rng.state(),
+			merge: {
+				attempts: [...mergeAttempts],
+				descriptions: [...mergeDescriptions],
+				due: mergesDue,
+				tested: totalMergesTested,
+				lastIterationAccepted
+			},
+			...cached === void 0 ? {} : { cache: cached }
+		};
+	}
+	async function checkpoint() {
+		if (onCheckpoint === void 0) return;
+		await onCheckpoint(takeSnapshot());
+	}
+	const evaluator = createEvaluator({
+		adapter,
+		budget,
+		...retry === void 0 ? {} : { retry },
+		...cacheNamespace === void 0 ? {} : { cacheNamespace },
+		...evaluationCache === void 0 ? {} : { cache: evaluationCache },
+		trackOutputs: trackBestOutputs,
+		cacheHits: resumeFrom?.cacheHits ?? 0,
+		...signal === void 0 ? {} : { signal },
+		onEvaluation: (event) => emit({
+			type: "evaluation",
+			...event
+		})
+	});
+	evaluator.restore(resumeFrom?.cache ?? []);
+	/**
+	* Evaluates a candidate on a batch at the current iteration. The cache, the
+	* budget and the transient-failure rules live in the shared evaluator; what
+	* belongs to GEPA is only which batch, and when.
+	*/
+	async function evaluateCached(args) {
+		return evaluator.evaluate({
+			...args,
+			iteration
+		});
+	}
+	/**
+	* Scores a candidate on the validation instances the policy selects, and
+	* spreads the result back over the full validation set — instances the
+	* policy skipped stay `undefined`, which every consumer reads as unknown
+	* rather than as a zero.
+	*/
+	async function evaluateValidation(args) {
+		const { candidate, instances, phase, candidateId } = args;
+		const dense = await evaluateCached({
+			candidate,
+			batch: instances.map((index) => validationSet[index]),
+			ids: instances.map((index) => validationIds[index]),
+			split: "val",
+			phase,
+			candidateId
+		});
+		const scores = new Array(validationSet.length).fill(void 0);
+		const objectiveScores = new Array(validationSet.length).fill(void 0);
+		const outputs = new Array(validationSet.length).fill(void 0);
+		instances.forEach((instance, position) => {
+			if (dense.transient[position] === true) return;
+			scores[instance] = dense.scores[position];
+			objectiveScores[instance] = dense.objectiveScores[position];
+			outputs[instance] = dense.outputs[position];
+		});
+		return {
+			scores,
+			objectiveScores,
+			outputs
+		};
+	}
+	/** The validation instances this candidate should be scored on. */
+	function selectValInstances(candidate) {
+		const selected = valEvaluationPolicy.selectInstances({
+			validationSet,
+			candidate,
+			records,
+			iteration,
+			rng
+		});
+		if (selected.length === 0) throw new Error("valEvaluationPolicy selected no validation instances; a candidate cannot be scored");
+		return selected;
+	}
+	function addCandidate(args) {
+		const objectiveScores = meanObjectives({
+			rows: args.evaluation.objectiveScores,
+			scores: args.evaluation.scores
+		});
+		const record = {
+			id: records.length,
+			candidate: args.candidate,
+			parentIds: args.parentIds,
+			instanceScores: args.evaluation.scores,
+			aggregateScore: mean(args.evaluation.scores),
+			...objectiveScores === void 0 ? {} : { objectiveScores },
+			source: args.source,
+			updatedComponents: args.updatedComponents,
+			iteration,
+			componentCursor: inheritedCursor(args.parentIds)
+		};
+		records.push(record);
+		seenCandidates.add(candidateFingerprint(args.candidate));
+		if (trackBestOutputs) outputsByCandidate.set(record.id, args.evaluation.outputs);
+		if (args.source !== "merge") {
+			lastIterationAccepted = true;
+			if (mergeConfig.enabled && totalMergesTested < mergeConfig.maxInvocations) mergesDue += 1;
+		}
+		return record;
+	}
+	/** Keeps the most recent rejections per component, oldest dropped first. */
+	function rememberRejection(args) {
+		const { proposed, parentScore, childScore } = args;
+		if (rejectedProposalMemory <= 0) return;
+		for (const component of componentNames(proposed)) {
+			const text = proposed[component];
+			if (text === void 0) continue;
+			const history = rejectedProposals[component] ?? [];
+			history.unshift({
+				text,
+				parentScore,
+				childScore
+			});
+			rejectedProposals[component] = history.slice(0, rejectedProposalMemory);
+		}
+	}
+	function inheritedCursor(parentIds) {
+		let cursor = 0;
+		for (const parentId of parentIds) {
+			const parent = records[parentId];
+			if (parent !== void 0 && parent.componentCursor > cursor) cursor = parent.componentCursor;
+		}
+		return cursor;
+	}
+	emit({
+		type: "start",
+		components: seedComponents,
+		validationSetSize: validationSet.length
+	});
+	if (records.length === 0) {
+		const seedInstances = selectValInstances(seedCandidate);
+		if (!budget.canAfford(seedInstances.length)) throw new Error(`maxMetricCalls (${maxMetricCalls}) is smaller than the ${seedInstances.length} validation instances selected for scoring; the seed candidate cannot be scored`);
+		addCandidate({
+			candidate: seedCandidate,
+			parentIds: [],
+			evaluation: await evaluateValidation({
+				candidate: seedCandidate,
+				instances: seedInstances,
+				phase: "seed",
+				candidateId: 0
+			}),
+			source: "seed",
+			updatedComponents: []
+		});
+		lastIterationAccepted = false;
+		mergesDue = 0;
+		await checkpoint();
+	}
+	let stopReason = "budgetExhausted";
+	/**
+	* Proposes and gates one merge. Returns "none" when nothing was tested — the
+	* iteration then falls through to reflective mutation, exactly as it would
+	* have without merging enabled. A merge that cannot be afforded is skipped,
+	* never treated as the end of the run.
+	*/
+	async function tryMerge() {
+		const proposal = proposeMerge({
+			records,
+			pool: collectDominatorIds(records),
+			rng,
+			attempted: mergeAttempts,
+			attemptedDescriptions: mergeDescriptions,
+			...mergeConfig.valOverlapFloor === void 0 ? {} : { valOverlapFloor: mergeConfig.valOverlapFloor }
+		});
+		if (proposal === null) return "none";
+		const [leftId, rightId] = proposal.parentIds;
+		const left = records[leftId];
+		const right = records[rightId];
+		const subsample = selectMergeSubsample({
+			scores1: left.instanceScores,
+			scores2: right.instanceScores,
+			rng,
+			size: MERGE_SUBSAMPLE_SIZE
+		});
+		if (subsample.length === 0) return "none";
+		const unique = [...new Set(subsample)];
+		const uniqueIds = unique.map((index) => validationIds[index]);
+		if (!budget.canAfford(evaluator.countUncached({
+			candidate: proposal.candidate,
+			ids: uniqueIds,
+			split: "val"
+		}))) return "none";
+		emit({
+			type: "iterationStart",
+			iteration,
+			parentIds: [...proposal.parentIds]
+		});
+		mergeAttempts.add(proposal.attemptKey);
+		mergeDescriptions.add(proposal.descriptionKey);
+		const uniqueEvaluation = await evaluateCached({
+			candidate: proposal.candidate,
+			batch: unique.map((index) => validationSet[index]),
+			ids: uniqueIds,
+			split: "val",
+			phase: "minibatch",
+			candidateId: null
+		});
+		const scoreByIndex = new Map(unique.map((index, position) => [index, uniqueEvaluation.scores[position]]));
+		const mergedSum = sum(subsample.map((index) => scoreByIndex.get(index)));
+		const parentBest = Math.max(sum(subsample.map((index) => left.instanceScores[index])), sum(subsample.map((index) => right.instanceScores[index])));
+		if (mergedSum < parentBest) {
+			emit({
+				type: "candidateRejected",
+				iteration,
+				parentId: leftId,
+				parentScore: parentBest,
+				childScore: mergedSum,
+				source: "merge",
+				reason: "worse"
+			});
+			return "attempted";
+		}
+		const mergeInstances = selectValInstances(proposal.candidate);
+		if (!budget.canAfford(evaluator.countUncached({
+			candidate: proposal.candidate,
+			ids: mergeInstances.map((index) => validationIds[index]),
+			split: "val"
+		}))) return "attempted";
+		const evaluation = await evaluateValidation({
+			candidate: proposal.candidate,
+			instances: mergeInstances,
+			phase: "validation",
+			candidateId: records.length
+		});
+		const ancestor = records[proposal.ancestorId];
+		const record = addCandidate({
+			candidate: proposal.candidate,
+			parentIds: [...proposal.parentIds],
+			evaluation,
+			source: "merge",
+			updatedComponents: componentNames(proposal.candidate).filter((name) => proposal.candidate[name] !== ancestor.candidate[name])
+		});
+		mergesDue -= 1;
+		totalMergesTested += 1;
+		emit({
+			type: "candidateAccepted",
+			iteration,
+			candidateId: record.id,
+			parentIds: record.parentIds,
+			aggregateScore: record.aggregateScore,
+			source: "merge"
+		});
+		return "attempted";
+	}
+	/**
+	* Draws every proposal an iteration will make, before any of them runs.
+	*
+	* Each draw consumes the random stream — parent, minibatch, component — so
+	* they all happen here, in order, on the same frontier snapshot. Doing it
+	* inside the concurrent phase instead would make the whole run's trajectory
+	* depend on which network call returned first.
+	*/
+	function planProposals() {
+		const state = {
+			scoreMatrix: records.map((record) => record.instanceScores),
+			aggregateScores: records.map((record) => record.aggregateScore),
+			objectiveScores: records.map((record) => record.objectiveScores)
+		};
+		const plans = [];
+		for (let slot = 0; slot < proposalsPerIteration; slot += 1) {
+			const parent = records[candidateSelector({
+				state,
+				rng
+			})];
+			const batchIndices = batchSampler({
+				trainingSet,
+				iteration: iteration * proposalsPerIteration + slot,
+				rng
+			});
+			const componentsToUpdate = componentSelector({
+				candidate: parent.candidate,
+				cursor: parent.componentCursor,
+				iteration,
+				rng
+			});
+			assertComponents({
+				names: componentsToUpdate,
+				candidate: parent.candidate,
+				source: "componentSelector"
+			});
+			parent.componentCursor = (parent.componentCursor + 1) % Math.max(1, componentNames(parent.candidate).length);
+			plans.push({
+				parent,
+				batch: batchIndices.map((index) => trainingSet[index]),
+				batchIds: batchIndices.map((index) => trainingIds[index]),
+				componentsToUpdate,
+				attempt: iteration * proposalsPerIteration + slot
+			});
+		}
+		return plans;
+	}
+	/**
+	* Reflects on one parent and screens the result on that parent's own
+	* minibatch. Everything here is IO the run can overlap; nothing here mutates
+	* the candidate pool, which is what makes overlapping it safe.
+	*/
+	async function runProposal(plan) {
+		const { parent, batch, batchIds, componentsToUpdate, attempt } = plan;
+		const parentEvaluation = await evaluator.evaluateTraced({
+			batch,
+			candidate: parent.candidate,
+			split: "train",
+			phase: "minibatch",
+			candidateId: parent.id,
+			iteration
+		});
+		if (parentEvaluation === null) return { status: "budgetExhausted" };
+		if (skipPerfectScore && parentEvaluation.scores.every((score) => score >= perfectScore)) return { status: "skipped" };
+		const reflectiveDataset = await adapter.makeReflectiveDataset({
+			candidate: parent.candidate,
+			batch,
+			evaluation: parentEvaluation,
+			componentsToUpdate
+		});
+		let proposed;
+		try {
+			proposed = await propose({
+				candidate: parent.candidate,
+				reflectiveDataset,
+				componentsToUpdate,
+				rejectedProposals,
+				attempt,
+				reflect: countedReflect,
+				signal
+			});
+		} catch (err) {
+			if (err instanceof ReflectionBudgetExhausted) return { status: "reflectionExhausted" };
+			throw err;
+		}
+		assertComponents({
+			names: componentNames(proposed),
+			candidate: parent.candidate,
+			source: "proposeNewTexts"
+		});
+		const child = {
+			...parent.candidate,
+			...proposed
+		};
+		const changed = componentNames(proposed).length > 0 && !seenCandidates.has(candidateFingerprint(child));
+		emit({
+			type: "proposal",
+			iteration,
+			parentId: parent.id,
+			componentsToUpdate: [...componentsToUpdate],
+			changed
+		});
+		if (!changed) return { status: "skipped" };
+		let childEvaluation;
+		try {
+			childEvaluation = await evaluateCached({
+				candidate: child,
+				batch,
+				ids: batchIds,
+				split: "train",
+				phase: "minibatch",
+				candidateId: null
+			});
+		} catch (err) {
+			if (err instanceof BudgetExhausted) return { status: "budgetExhausted" };
+			throw err;
+		}
+		const screened = pairMeasured({
+			parent: parentEvaluation,
+			child: childEvaluation
+		});
+		if (screened.parentScores.length === 0) return { status: "skipped" };
+		return {
+			status: "screened",
+			plan,
+			child,
+			proposed,
+			parentScore: mean(screened.parentScores),
+			childScore: mean(screened.childScores),
+			improvement: sum(screened.childScores) - sum(screened.parentScores),
+			accepted: acceptance(screened)
+		};
+	}
+	/**
+	* Turns screened proposals into candidates: rejections first, then the
+	* survivors the selection policy keeps, each paying for its own validation
+	* sweep. Returns a stop reason when the iteration ran the run out of budget.
+	*/
+	async function commitProposals(outcomes) {
+		let stop;
+		const improved = [];
+		/**
+		* Children two siblings converged on. Resolved here rather than while the
+		* proposals were in flight: the first one in plan order keeps the child,
+		* whichever of them finished first.
+		*/
+		const claimed = /* @__PURE__ */ new Set();
+		for (const outcome of outcomes) {
+			if (outcome.status === "skipped") continue;
+			if (outcome.status === "budgetExhausted") {
+				stop ??= "budgetExhausted";
+				continue;
+			}
+			if (outcome.status === "reflectionExhausted") {
+				stop ??= "reflectionBudgetExhausted";
+				continue;
+			}
+			const fingerprint = candidateFingerprint(outcome.child);
+			if (claimed.has(fingerprint)) continue;
+			claimed.add(fingerprint);
+			if (!outcome.accepted) {
+				rememberRejection({
+					proposed: outcome.proposed,
+					parentScore: outcome.parentScore,
+					childScore: outcome.childScore
+				});
+				emit({
+					type: "candidateRejected",
+					iteration,
+					parentId: outcome.plan.parent.id,
+					parentScore: outcome.parentScore,
+					childScore: outcome.childScore,
+					source: "mutation",
+					reason: "worse"
+				});
+				continue;
+			}
+			improved.push(outcome);
+		}
+		const survivors = selectSurvivors(improved);
+		for (const outcome of improved) {
+			if (survivors.includes(outcome)) continue;
+			emit({
+				type: "candidateRejected",
+				iteration,
+				parentId: outcome.plan.parent.id,
+				parentScore: outcome.parentScore,
+				childScore: outcome.childScore,
+				source: "mutation",
+				reason: "notSelected"
+			});
+		}
+		const baseId = records.length;
+		const scheduled = [];
+		let owed = 0;
+		for (const outcome of survivors) {
+			const instances = selectValInstances(outcome.child);
+			const uncached = evaluator.countUncached({
+				candidate: outcome.child,
+				ids: instances.map((index) => validationIds[index]),
+				split: "val"
+			});
+			if (!budget.canAfford(owed + uncached)) {
+				stop ??= "budgetExhausted";
+				break;
+			}
+			owed += uncached;
+			scheduled.push({
+				outcome,
+				candidateId: baseId + scheduled.length,
+				instances
+			});
+		}
+		const scored = await mapWithConcurrency({
+			items: scheduled,
+			limit: proposalConcurrency,
+			signal,
+			task: async (item) => {
+				try {
+					return {
+						item,
+						evaluation: await evaluateValidation({
+							candidate: item.outcome.child,
+							instances: item.instances,
+							phase: "validation",
+							candidateId: item.candidateId
+						})
+					};
+				} catch (err) {
+					if (err instanceof BudgetExhausted) return {
+						item,
+						evaluation: void 0
+					};
+					throw err;
+				}
+			}
+		});
+		for (const { item, evaluation } of scored) {
+			if (evaluation === void 0) {
+				stop ??= "budgetExhausted";
+				break;
+			}
+			const record = addCandidate({
+				candidate: item.outcome.child,
+				parentIds: [item.outcome.plan.parent.id],
+				evaluation,
+				source: "mutation",
+				updatedComponents: componentNames(item.outcome.proposed)
+			});
+			emit({
+				type: "candidateAccepted",
+				iteration,
+				candidateId: record.id,
+				parentIds: record.parentIds,
+				aggregateScore: record.aggregateScore,
+				source: "mutation"
+			});
+		}
+		return stop;
+	}
+	/** The improving proposals an iteration keeps, in the order they were made. */
+	function selectSurvivors(improved) {
+		if (improved.length <= survivorsPerIteration) return [...improved];
+		return improved.map((outcome, index) => ({
+			outcome,
+			index
+		})).sort((a, b) => b.outcome.improvement - a.outcome.improvement || a.index - b.index).slice(0, survivorsPerIteration).sort((a, b) => a.index - b.index).map((entry) => entry.outcome);
+	}
+	while (true) {
+		if (signal?.aborted) {
+			stopReason = "aborted";
+			break;
+		}
+		if (costExhausted({
+			usage: evaluator.usage(),
+			maxCostUsd
+		})) {
+			stopReason = "costExhausted";
+			break;
+		}
+		if (deadline.exceeded()) {
+			stopReason = "deadlineReached";
+			break;
+		}
+		if (iteration >= maxIterations) {
+			stopReason = "maxIterations";
+			break;
+		}
+		if (!budget.canAfford(proposalsPerIteration * minibatchSize * 2 + validationSet.length)) {
+			stopReason = "budgetExhausted";
+			break;
+		}
+		if (reflection?.maxCalls !== void 0 && reflectionCalls >= reflection.maxCalls) {
+			stopReason = "reflectionBudgetExhausted";
+			break;
+		}
+		const spentBeforeIteration = budget.spent();
+		let pendingStop;
+		try {
+			const mergeScheduled = mergeConfig.enabled && mergesDue > 0 && lastIterationAccepted && totalMergesTested < mergeConfig.maxInvocations;
+			lastIterationAccepted = false;
+			if (!(mergeScheduled && await tryMerge() === "attempted")) {
+				const plans = planProposals();
+				emit({
+					type: "iterationStart",
+					iteration,
+					parentIds: plans.map((plan) => plan.parent.id)
+				});
+				pendingStop = await commitProposals(await mapWithConcurrency({
+					items: plans,
+					limit: proposalConcurrency,
+					task: runProposal,
+					signal
+				}));
+			}
+		} catch (err) {
+			if (signal?.aborted) {
+				stopReason = "aborted";
+				break;
+			}
+			if (err instanceof BudgetExhausted) {
+				stopReason = "budgetExhausted";
+				break;
+			}
+			if (raiseOnError || budget.spent() === spentBeforeIteration) throw err;
+			emit({
+				type: "error",
+				iteration,
+				err
+			});
+		}
+		iteration += 1;
+		await checkpoint();
+		if (pendingStop !== void 0) {
+			stopReason = pendingStop;
+			break;
+		}
+	}
+	const bestCandidateId = valEvaluationPolicy.bestCandidate(records);
+	const best = records[bestCandidateId];
+	const testScore = testSet === void 0 ? void 0 : measuredMean(await evaluateCached({
+		candidate: best.candidate,
+		batch: testSet,
+		ids: testIds,
+		split: "test",
+		phase: "test",
+		candidateId: bestCandidateId,
+		charge: false
+	}));
+	emit({
+		type: "finish",
+		reason: stopReason,
+		bestCandidateId,
+		metricCalls: budget.spent(),
+		...testScore === void 0 ? {} : { testScore }
+	});
+	const perObjectiveBest = collectPerObjectiveBest(records);
+	const bestOutputs = outputsByCandidate.get(bestCandidateId);
+	return {
+		bestCandidate: best.candidate,
+		bestScore: best.aggregateScore,
+		usage: evaluator.usage(),
+		bestCandidateId,
+		...testScore === void 0 ? {} : {
+			testScore,
+			testMetricCalls: evaluator.unchargedCalls()
+		},
+		...bestOutputs === void 0 ? {} : { bestOutputs },
+		candidates: records,
+		paretoFrontier: collectDominatorIds(records).map((id) => records[id]),
+		...perObjectiveBest === void 0 ? {} : { perObjectiveBest },
+		scoreMatrix: records.map((record) => [...record.instanceScores]),
+		metricCalls: budget.spent(),
+		reflectionCalls,
+		cacheHits: evaluator.cacheHits(),
+		iterations: iteration,
+		stopReason,
+		snapshot: takeSnapshot()
+	};
+}
+/**
+* Range checks on the search knobs, run at construction so a configuration
+* that could never terminate is refused before a task is ever handed to it.
+* Task-shaped checks stay in `runGepa`, where the data is.
+*/
+function assertGepaConfig(config) {
+	if (config.reflection?.buildPrompt !== void 0 && config.reflection.strategies !== void 0) throw new Error("reflection takes buildPrompt or strategies, not both");
+	if (config.reflection?.strategies?.length === 0) throw new Error("reflection.strategies must not be empty");
+	const { minibatchSize = DEFAULT_MINIBATCH_SIZE, maxIterations = Number.POSITIVE_INFINITY, perfectScore = 1, rejectedProposalMemory = DEFAULT_REJECTED_PROPOSAL_MEMORY, proposals } = config;
+	const proposalsPerIteration = proposals?.perIteration ?? 1;
+	const proposalConcurrency = proposals?.concurrency ?? 1;
+	if (!Number.isInteger(proposalsPerIteration) || proposalsPerIteration < 1) throw new Error(`proposals.perIteration must be a positive integer, received ${proposalsPerIteration}`);
+	if (!Number.isInteger(proposalConcurrency) || proposalConcurrency < 1) throw new Error(`proposals.concurrency must be a positive integer, received ${proposalConcurrency}`);
+	keepCount(proposals?.selection ?? "all");
+	if (!Number.isInteger(minibatchSize) || minibatchSize < 1) throw new Error(`minibatchSize must be a positive integer, received ${minibatchSize}`);
+	if (!Number.isFinite(perfectScore)) throw new Error(`perfectScore must be a finite number, received ${perfectScore}`);
+	if (!Number.isInteger(rejectedProposalMemory) || rejectedProposalMemory < 0) throw new Error(`rejectedProposalMemory must be a non-negative integer, received ${rejectedProposalMemory}`);
+	if (maxIterations !== Number.POSITIVE_INFINITY && (!Number.isInteger(maxIterations) || maxIterations < 0)) throw new Error(`maxIterations must be a non-negative integer or Infinity, received ${maxIterations}`);
+}
+/**
+* The single narrowing point for a snapshot's candidate pool. A snapshot is
+* JSON that left the process and came back with plain string keys, so every
+* record is checked against the seed's components before it is read as one of
+* them — behind the fingerprint check, which has already established that the
+* snapshot belongs to this run.
+*/
+function restoreRecords(args) {
+	const { records, seedCandidate } = args;
+	const known = new Set(componentNames(seedCandidate));
+	for (const record of records) {
+		const named = [...Object.keys(record.candidate), ...record.updatedComponents];
+		for (const name of named) if (!known.has(name)) throw new Error(`checkpoint names the component "${name}", which the seed candidate does not have (${[...known].join(", ")})`);
+	}
+	return copyRecords(records);
+}
+/**
+* Rejections arrive from a snapshot keyed by plain strings. Reading them
+* through the seed's own component names narrows them without an assertion,
+* and drops anything the seed no longer has.
+*/
+function restoreRejections(args) {
+	const { rejections, components } = args;
+	const restored = {};
+	for (const component of components) {
+		const history = rejections[component];
+		if (history !== void 0) restored[component] = history.map((entry) => ({ ...entry }));
+	}
+	return restored;
+}
+/** The inverse: back to the plain string keys a snapshot is written with. */
+function snapshotRejections(args) {
+	const { rejections, components } = args;
+	const copy = {};
+	for (const component of components) {
+		const history = rejections[component];
+		if (history !== void 0) copy[component] = history.map((entry) => ({ ...entry }));
+	}
+	return copy;
+}
+/**
+* Patches are merged over the parent, so a name the candidate does not have is
+* added rather than refused: the run would go on optimizing text the system
+* under optimization never reads, and every descendant would carry it.
+*/
+function assertComponents(args) {
+	const { names, candidate, source } = args;
+	for (const name of names) if (!Object.hasOwn(candidate, name)) throw new Error(`${source} named "${name}", which is not a component of the candidate (${Object.keys(candidate).join(", ")})`);
+}
+/** Copies everything a run mutates in place, so a snapshot never aliases one. */
+function copyRecords(records) {
+	return records.map((record) => ({
+		...record,
+		parentIds: [...record.parentIds],
+		instanceScores: [...record.instanceScores],
+		updatedComponents: [...record.updatedComponents],
+		...record.objectiveScores === void 0 ? {} : { objectiveScores: { ...record.objectiveScores } }
+	}));
+}
+/** How many improving proposals an iteration is allowed to keep. */
+function keepCount(selection) {
+	if (selection === "all") return Number.POSITIVE_INFINITY;
+	if (selection === "best") return 1;
+	if (!Number.isInteger(selection.keep) || selection.keep < 1) throw new Error(`proposals.selection.keep must be a positive integer, received ${selection.keep}`);
+	return selection.keep;
+}
+/**
+* Mean of each objective over the instances this candidate was scored on.
+*
+* An objective only some of those instances reported is left out rather than
+* averaged over the ones that did: candidates are compared objective by
+* objective on the frontier, and a mean over one instance is not the same
+* measurement as a mean over forty.
+*/
+function meanObjectives(args) {
+	const { rows, scores } = args;
+	const measured = rows.filter((_, index) => scores[index] !== void 0);
+	const totals = /* @__PURE__ */ new Map();
+	for (const row of measured) for (const [objective, value] of Object.entries(row ?? {})) {
+		const running = totals.get(objective) ?? {
+			total: 0,
+			count: 0
+		};
+		running.total += value;
+		running.count += 1;
+		totals.set(objective, running);
+	}
+	const complete = [...totals].filter(([, { count }]) => count === measured.length);
+	if (complete.length === 0) return;
+	return Object.fromEntries(complete.map(([objective, { total, count }]) => [objective, total / count]));
+}
+function collectPerObjectiveBest(records) {
+	const bests = objectiveBests(records.map((record) => record.objectiveScores));
+	if (Object.keys(bests).length === 0) return;
+	return Object.fromEntries(Object.entries(bests).map(([objective, score]) => [objective, {
+		score,
+		candidateIds: records.filter((record) => record.objectiveScores?.[objective] === score).map((record) => record.id)
+	}]));
+}
+/**
+* Candidates that uniquely win at least one validation instance once dominated
+* lineages are pruned. This is both the reported frontier and the pool merge
+* draws its parents from.
+*/
+function collectDominatorIds(records) {
+	const fronts = pruneDominatedFronts({
+		fronts: buildInstanceFronts({ scoreMatrix: records.map((record) => record.instanceScores) }),
+		aggregateScores: records.map((record) => record.aggregateScore)
+	});
+	const ids = /* @__PURE__ */ new Set();
+	for (const front of fronts) for (const id of front) ids.add(id);
+	return [...ids].sort((a, b) => a - b);
+}
+/**
+* Names an instance by a hash of its content rather than by the content
+* itself: the id ends up inside every cache key and inside the checkpoint
+* fingerprint, and embedding whole examples there costs memory proportional to
+* the dataset for no benefit. Data that will not serialize falls back to its
+* position, which is stable for as long as the dataset order is.
+*/
+function defaultInstanceId(args) {
+	const hash = stableHash(args.datum);
+	return hash === "" ? String(args.index) : hash;
+}
+/**
+* The two rollout sets restricted to the instances both of them measured.
+*
+* Screening is a paired comparison over one minibatch: a transient row is a
+* rollout that never happened, and leaving it in scores the candidate that ran
+* against the infrastructure failure of the one that did not.
+*/
+function pairMeasured(args) {
+	const { parent, child } = args;
+	const parentScores = [];
+	const childScores = [];
+	for (let index = 0; index < parent.scores.length; index += 1) {
+		if (parent.transient?.[index] === true || child.transient?.[index] === true) continue;
+		parentScores.push(parent.scores[index]);
+		childScores.push(child.scores[index]);
+	}
+	return {
+		parentScores,
+		childScores
+	};
+}
+//#endregion
+export { GepaOptimizer, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };