textopt 0.0.0 → 0.2.0

package/dist/file-cache.mjs

@@ -12,20 +12,33 @@ import { dirname } from "node:path";
 * Append-only rather than rewritten: a score is never invalidated (the key
 * names the candidate, the instance, and the environment), and a log survives
 * a process killed mid-write, which a file rewritten in place does not.
+*
+* `namespace` is what makes that invariant true. A cached score measures a
+* whole system, not a candidate, and this log outlives every part of that
+* system a run does not pass through the key: the model id behind an alias the
+* provider upgraded, the decoding settings, the scorer's own version. It is
+* required rather than optional because the failure it prevents is silent —
+* scores from one system served to a run of another, with a normal-looking
+* result and no way to read afterwards that it happened.
 */
 function createFileCache(args) {
-	const { path, maxEntries = 1e6 } = args;
+	const { path, namespace, maxEntries = 1e6 } = args;
+	if (namespace.trim() === "") throw new Error("createFileCache requires a non-empty namespace naming the system these scores measure");
 	mkdirSync(dirname(path), { recursive: true });
-	const entries = readLog(path);
+	const log = readLog(path);
+	const entries = log.entries;
+	const scope = (key) => `${namespace}\u0000${key}`;
+	if (log.unterminated) appendFileSync(path, "\n");
 	return {
-		get: (key) => entries.get(key),
+		get: (key) => entries.get(scope(key)),
 		set: (key, cached) => {
-			if (entries.size >= maxEntries && !entries.has(key)) {
+			const scoped = scope(key);
+			if (entries.size >= maxEntries && !entries.has(scoped)) {
 				const oldest = entries.keys().next();
 				if (!oldest.done) entries.delete(oldest.value);
 			}
-			entries.set(key, cached);
-			appendFileSync(path, `${JSON.stringify([key, cached])}\n`);
+			entries.set(scoped, cached);
+			appendFileSync(path, `${JSON.stringify([scoped, cached])}\n`);
 		}
 	};
 }
@@ -41,14 +54,20 @@ function readLog(path) {
 	try {
 		contents = readFileSync(path, "utf8");
 	} catch {
-		return entries;
+		return {
+			entries,
+			unterminated: false
+		};
 	}
 	for (const line of contents.split("\n")) {
 		if (line.length === 0) continue;
 		const entry = parseEntry(line);
 		if (entry !== void 0) entries.set(entry[0], entry[1]);
 	}
-	return entries;
+	return {
+		entries,
+		unterminated: contents.length > 0 && !contents.endsWith("\n")
+	};
 }
 function parseEntry(line) {
 	let parsed;

package/dist/gepa/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_evaluation = require("../evaluation-OZOp6TB7.cjs");
+const require_warnings = require("../warnings-CWRJF-jA.cjs");
 const require_concurrency = require("../concurrency-C-cFzWW2.cjs");
-const require_math = require("../math-COOofUyv.cjs");
-const require_demos = require("../demos-B9BJiNKz.cjs");
+const require_math = require("../math-BhlziRPc.cjs");
+const require_demos = require("../demos-9v5ts7F3.cjs");
 const require_rng = require("../rng-DbA_rPIo.cjs");
 const require_reflection = require("../reflection-DRfbk6hu.cjs");
 const require_sampling = require("../sampling-Dars7ctR.cjs");
@@ -334,7 +334,7 @@ function isEligibleAncestor(args) {
 */
 function hasComplementaryComponent(args) {
 	const { ancestor, left, right } = args;
-	return require_evaluation.componentNames(ancestor).some((name) => {
+	return require_warnings.componentNames(ancestor).some((name) => {
 		const base = ancestor[name];
 		return (base === left[name] || base === right[name]) && left[name] !== right[name];
 	});
@@ -347,7 +347,7 @@ function mergeComponents(args) {
 	const rightRecord = records[rightId];
 	const candidate = { ...ancestor };
 	const sources = [];
-	for (const name of require_evaluation.componentNames(ancestor)) {
+	for (const name of require_warnings.componentNames(ancestor)) {
 		const base = ancestor[name];
 		const leftText = leftRecord.candidate[name];
 		const rightText = rightRecord.candidate[name];
@@ -391,7 +391,7 @@ function buildAncestries(records) {
 	return ancestries;
 }
 function fingerprint(candidate) {
-	return JSON.stringify(require_evaluation.componentNames(candidate).sort().map((name) => [name, candidate[name]]));
+	return JSON.stringify(require_warnings.componentNames(candidate).sort().map((name) => [name, candidate[name]]));
 }
 //#endregion
 //#region src/gepa/pareto.ts
@@ -513,7 +513,9 @@ function hasSurvivor(args) {
 * `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.
+* weight for every instance it wins *and* every objective it leads. The
+* objectives are whatever the adapter put in `objectiveScores`, which for a
+* judge is every criterion it graded, including any at `weight: 0`.
 */
 function paretoSelector(args = {}) {
 	const { epsilon = 0, frontier = "instance" } = args;
@@ -628,14 +630,14 @@ function subsampledEvaluationPolicy(args) {
 */
 function roundRobinComponentSelector() {
 	return ({ candidate, cursor }) => {
-		const names = require_evaluation.componentNames(candidate);
+		const names = require_warnings.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 }) => require_evaluation.componentNames(candidate);
+	return ({ candidate }) => require_warnings.componentNames(candidate);
 }
 /**
 * Accept a mutation only when it beats its parent on the same minibatch. Cheap
@@ -660,7 +662,8 @@ function improvementAcceptance(args = {}) {
 */
 function pairedPermutationAcceptance(args = {}) {
 	const { alpha = .2, maxExact = 16 } = args;
-	return ({ parentScores, childScores }) => {
+	if (!Number.isFinite(alpha) || alpha <= 0 || alpha > 1) throw new Error(`alpha must be greater than 0 and at most 1, received ${alpha}`);
+	const policy = ({ parentScores, childScores }) => {
 		const differences = [];
 		for (let index = 0; index < parentScores.length; index += 1) differences.push(childScores[index] - parentScores[index]);
 		const observed = require_math.sum(differences);
@@ -671,6 +674,33 @@ function pairedPermutationAcceptance(args = {}) {
 			maxExact
 		}) <= alpha;
 	};
+	policy.minimumPairs = smallestAcceptableBatch({
+		alpha,
+		maxExact
+	});
+	return policy;
+}
+/**
+* Smallest paired batch on which a sign-flip test at `alpha` could return a
+* verdict of "accept" at all.
+*
+* Enumerating n non-zero differences gives 2^n equally likely sign
+* assignments, so the smallest attainable p-value is 2^-n and no batch below
+* `log2(1/alpha)` pairs can clear the bar. Past `maxExact` the p-value comes
+* from a normal approximation, which has no such floor — so when the exact
+* requirement is out of that regime's reach, the first batch that leaves the
+* regime is the honest answer rather than an exact size that never applies.
+*/
+function smallestAcceptableBatch(args) {
+	const { alpha, maxExact } = args;
+	let pairs = 1;
+	let smallestPValue = .5;
+	while (smallestPValue > alpha) {
+		pairs += 1;
+		smallestPValue /= 2;
+		if (pairs > maxExact) return maxExact + 1;
+	}
+	return pairs;
 }
 /**
 * Highest mean over the instances it was scored on, with wider coverage
@@ -739,18 +769,26 @@ var GepaOptimizer = class {
 		this.#config = config;
 	}
 	async optimize(task) {
-		return runGepa({
-			config: this.#config,
-			task
-		});
+		try {
+			return await runGepa({
+				config: this.#config,
+				task
+			});
+		} finally {
+			await require_warnings.flushReporters(task.reporters ?? []);
+		}
 	}
 };
 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 = require_sampling.createEpochShuffledSampler({ minibatchSize }), valEvaluationPolicy = fullEvaluationPolicy(), cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = defaultInstanceId, onEvent, onCheckpoint, resumeFrom, signal } = task;
-	const deadline = require_evaluation.createDeadline({ maxWallClockMs });
-	const seedComponents = require_evaluation.componentNames(seedCandidate);
+	const { seedCandidate, trainingSet, validationSet: requestedValidationSet, testSet, adapter, reflect, maxMetricCalls, componentSelector = roundRobinComponentSelector(), batchSampler = require_sampling.createEpochShuffledSampler({ minibatchSize }), valEvaluationPolicy = fullEvaluationPolicy(), cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = require_warnings.defaultInstanceId, reporters = [], onCheckpoint, resumeFrom, signal } = task;
+	const { validationSet, warnings } = require_warnings.resolveValidationSet({
+		validationSet: requestedValidationSet,
+		trainingSet
+	});
+	const deadline = require_warnings.createDeadline({ maxWallClockMs });
+	const seedComponents = require_warnings.componentNames(seedCandidate);
 	const mergeConfig = {
 		enabled: merge?.enabled ?? seedComponents.length > 1,
 		maxInvocations: merge?.maxInvocations ?? DEFAULT_MAX_MERGES,
@@ -763,7 +801,7 @@ async function runGepa(args) {
 	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 ?? require_evaluation.createMemoryCache();
+	const evaluationCache = cache === false ? void 0 : cache ?? require_warnings.createMemoryCache();
 	const propose = adapter.proposeNewTexts?.bind(adapter) ?? require_reflection.createDefaultProposer({
 		...reflection?.buildPrompt === void 0 ? {} : { buildPrompt: reflection.buildPrompt },
 		...reflection?.strategies === void 0 ? {} : { strategies: reflection.strategies },
@@ -784,19 +822,19 @@ async function runGepa(args) {
 		datum,
 		index
 	})) ?? [];
-	const fingerprint = require_evaluation.runFingerprint({
+	const fingerprint = require_warnings.runFingerprint({
 		seedCandidate,
 		trainingIds,
 		validationIds,
 		seed,
 		...cacheNamespace === void 0 ? {} : { cacheNamespace }
 	});
-	require_evaluation.assertResumable({
+	require_warnings.assertResumable({
 		fingerprint,
 		...resumeFrom === void 0 ? {} : { snapshot: resumeFrom }
 	});
 	const rng = require_rng.createSeededRng(seed, resumeFrom?.rngState);
-	const budget = require_evaluation.createBudget({
+	const budget = require_warnings.createBudget({
 		maxMetricCalls,
 		spent: resumeFrom?.metricCalls ?? 0
 	});
@@ -816,7 +854,7 @@ async function runGepa(args) {
 		records: resumeFrom?.records ?? [],
 		seedCandidate
 	});
-	const seenCandidates = new Set(records.map((record) => require_evaluation.candidateFingerprint(record.candidate)));
+	const seenCandidates = new Set(records.map((record) => require_warnings.candidateFingerprint(record.candidate)));
 	const outputsByCandidate = /* @__PURE__ */ new Map();
 	const rejectedProposals = restoreRejections({
 		rejections: resumeFrom?.rejectedProposals ?? {},
@@ -828,8 +866,26 @@ async function runGepa(args) {
 	let mergesDue = resumeFrom?.merge.due ?? 0;
 	let totalMergesTested = resumeFrom?.merge.tested ?? 0;
 	let lastIterationAccepted = resumeFrom?.merge.lastIterationAccepted ?? false;
-	function emit(event) {
-		onEvent?.(event);
+	const emit = require_warnings.createEmitter(reporters);
+	/**
+	* Everything an acceptance means, in one event: the text, the aggregate, and
+	* the row it put on the frontier. Emitted from one place because the merge
+	* path and the mutation path accept candidates separately, and a payload
+	* assembled twice is a payload that drifts.
+	*/
+	function emitAccepted(record) {
+		const outputs = outputsByCandidate.get(record.id);
+		emit({
+			type: "candidateAccepted",
+			iteration,
+			candidateId: record.id,
+			parentIds: record.parentIds,
+			aggregateScore: record.aggregateScore,
+			source: record.source,
+			candidate: record.candidate,
+			instanceScores: record.instanceScores,
+			...outputs === void 0 ? {} : { outputs }
+		});
 	}
 	/**
 	* Copies everything mutable: a snapshot handed to `onCheckpoint` is a record
@@ -846,6 +902,7 @@ async function runGepa(args) {
 			metricCalls: budget.spent(),
 			reflectionCalls,
 			cacheHits: evaluator.cacheHits(),
+			usage: evaluator.usage(),
 			...samplerState === void 0 ? {} : { sampler: samplerState },
 			rejectedProposals: snapshotRejections({
 				rejections: rejectedProposals,
@@ -866,7 +923,7 @@ async function runGepa(args) {
 		if (onCheckpoint === void 0) return;
 		await onCheckpoint(takeSnapshot());
 	}
-	const evaluator = require_evaluation.createEvaluator({
+	const evaluator = require_warnings.createEvaluator({
 		adapter,
 		budget,
 		...retry === void 0 ? {} : { retry },
@@ -874,6 +931,7 @@ async function runGepa(args) {
 		...evaluationCache === void 0 ? {} : { cache: evaluationCache },
 		trackOutputs: trackBestOutputs,
 		cacheHits: resumeFrom?.cacheHits ?? 0,
+		...resumeFrom?.usage === void 0 ? {} : { usage: resumeFrom.usage },
 		...signal === void 0 ? {} : { signal },
 		onEvaluation: (event) => emit({
 			type: "evaluation",
@@ -953,7 +1011,7 @@ async function runGepa(args) {
 			componentCursor: inheritedCursor(args.parentIds)
 		};
 		records.push(record);
-		seenCandidates.add(require_evaluation.candidateFingerprint(args.candidate));
+		seenCandidates.add(require_warnings.candidateFingerprint(args.candidate));
 		if (trackBestOutputs) outputsByCandidate.set(record.id, args.evaluation.outputs);
 		if (args.source !== "merge") {
 			lastIterationAccepted = true;
@@ -965,7 +1023,7 @@ async function runGepa(args) {
 	function rememberRejection(args) {
 		const { proposed, parentScore, childScore } = args;
 		if (rejectedProposalMemory <= 0) return;
-		for (const component of require_evaluation.componentNames(proposed)) {
+		for (const component of require_warnings.componentNames(proposed)) {
 			const text = proposed[component];
 			if (text === void 0) continue;
 			const history = rejectedProposals[component] ?? [];
@@ -993,18 +1051,23 @@ async function runGepa(args) {
 	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({
+		const seedEvaluation = await evaluateValidation({
+			candidate: seedCandidate,
+			instances: seedInstances,
+			phase: "seed",
+			candidateId: 0
+		});
+		emitAccepted(addCandidate({
 			candidate: seedCandidate,
 			parentIds: [],
-			evaluation: await evaluateValidation({
-				candidate: seedCandidate,
-				instances: seedInstances,
-				phase: "seed",
-				candidateId: 0
-			}),
+			evaluation: seedEvaluation,
 			source: "seed",
 			updatedComponents: []
-		});
+		}));
+		warnings.push(...require_warnings.seedScoreWarnings({
+			scores: seedEvaluation.scores,
+			perfectScore
+		}));
 		lastIterationAccepted = false;
 		mergesDue = 0;
 		await checkpoint();
@@ -1091,18 +1154,11 @@ async function runGepa(args) {
 			parentIds: [...proposal.parentIds],
 			evaluation,
 			source: "merge",
-			updatedComponents: require_evaluation.componentNames(proposal.candidate).filter((name) => proposal.candidate[name] !== ancestor.candidate[name])
+			updatedComponents: require_warnings.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"
-		});
+		emitAccepted(record);
 		return "attempted";
 	}
 	/**
@@ -1141,7 +1197,7 @@ async function runGepa(args) {
 				candidate: parent.candidate,
 				source: "componentSelector"
 			});
-			parent.componentCursor = (parent.componentCursor + 1) % Math.max(1, require_evaluation.componentNames(parent.candidate).length);
+			parent.componentCursor = (parent.componentCursor + 1) % Math.max(1, require_warnings.componentNames(parent.candidate).length);
 			plans.push({
 				parent,
 				batch: batchIndices.map((index) => trainingSet[index]),
@@ -1191,7 +1247,7 @@ async function runGepa(args) {
 			throw err;
 		}
 		assertComponents({
-			names: require_evaluation.componentNames(proposed),
+			names: require_warnings.componentNames(proposed),
 			candidate: parent.candidate,
 			source: "proposeNewTexts"
 		});
@@ -1199,7 +1255,7 @@ async function runGepa(args) {
 			...parent.candidate,
 			...proposed
 		};
-		const changed = require_evaluation.componentNames(proposed).length > 0 && !seenCandidates.has(require_evaluation.candidateFingerprint(child));
+		const changed = require_warnings.componentNames(proposed).length > 0 && !seenCandidates.has(require_warnings.candidateFingerprint(child));
 		emit({
 			type: "proposal",
 			iteration,
@@ -1219,7 +1275,7 @@ async function runGepa(args) {
 				candidateId: null
 			});
 		} catch (err) {
-			if (err instanceof require_evaluation.BudgetExhausted) return { status: "budgetExhausted" };
+			if (err instanceof require_warnings.BudgetExhausted) return { status: "budgetExhausted" };
 			throw err;
 		}
 		const screened = pairMeasured({
@@ -1262,7 +1318,7 @@ async function runGepa(args) {
 				stop ??= "reflectionBudgetExhausted";
 				continue;
 			}
-			const fingerprint = require_evaluation.candidateFingerprint(outcome.child);
+			const fingerprint = require_warnings.candidateFingerprint(outcome.child);
 			if (claimed.has(fingerprint)) continue;
 			claimed.add(fingerprint);
 			if (!outcome.accepted) {
@@ -1334,7 +1390,7 @@ async function runGepa(args) {
 						})
 					};
 				} catch (err) {
-					if (err instanceof require_evaluation.BudgetExhausted) return {
+					if (err instanceof require_warnings.BudgetExhausted) return {
 						item,
 						evaluation: void 0
 					};
@@ -1347,21 +1403,13 @@ async function runGepa(args) {
 				stop ??= "budgetExhausted";
 				break;
 			}
-			const record = addCandidate({
+			emitAccepted(addCandidate({
 				candidate: item.outcome.child,
 				parentIds: [item.outcome.plan.parent.id],
 				evaluation,
 				source: "mutation",
-				updatedComponents: require_evaluation.componentNames(item.outcome.proposed)
-			});
-			emit({
-				type: "candidateAccepted",
-				iteration,
-				candidateId: record.id,
-				parentIds: record.parentIds,
-				aggregateScore: record.aggregateScore,
-				source: "mutation"
-			});
+				updatedComponents: require_warnings.componentNames(item.outcome.proposed)
+			}));
 		}
 		return stop;
 	}
@@ -1378,7 +1426,7 @@ async function runGepa(args) {
 			stopReason = "aborted";
 			break;
 		}
-		if (require_evaluation.costExhausted({
+		if (require_warnings.costExhausted({
 			usage: evaluator.usage(),
 			maxCostUsd
 		})) {
@@ -1425,7 +1473,7 @@ async function runGepa(args) {
 				stopReason = "aborted";
 				break;
 			}
-			if (err instanceof require_evaluation.BudgetExhausted) {
+			if (err instanceof require_warnings.BudgetExhausted) {
 				stopReason = "budgetExhausted";
 				break;
 			}
@@ -1445,7 +1493,7 @@ async function runGepa(args) {
 	}
 	const bestCandidateId = valEvaluationPolicy.bestCandidate(records);
 	const best = records[bestCandidateId];
-	const testScore = testSet === void 0 ? void 0 : require_evaluation.measuredMean(await evaluateCached({
+	const heldOut = testSet === void 0 ? void 0 : await evaluateCached({
 		candidate: best.candidate,
 		batch: testSet,
 		ids: testIds,
@@ -1453,13 +1501,18 @@ async function runGepa(args) {
 		phase: "test",
 		candidateId: bestCandidateId,
 		charge: false
-	}));
+	});
+	const testScore = heldOut === void 0 ? void 0 : require_warnings.measuredMean(heldOut);
 	emit({
 		type: "finish",
 		reason: stopReason,
+		warnings,
 		bestCandidateId,
+		bestScore: best.aggregateScore,
 		metricCalls: budget.spent(),
-		...testScore === void 0 ? {} : { testScore }
+		...testScore === void 0 ? {} : { testScore },
+		...heldOut === void 0 ? {} : { testInstanceScores: require_warnings.instanceRow(heldOut) },
+		...heldOut === void 0 || !trackBestOutputs ? {} : { testOutputs: heldOut.outputs }
 	});
 	const perObjectiveBest = collectPerObjectiveBest(records);
 	const bestOutputs = outputsByCandidate.get(bestCandidateId);
@@ -1470,7 +1523,8 @@ async function runGepa(args) {
 		bestCandidateId,
 		...testScore === void 0 ? {} : {
 			testScore,
-			testMetricCalls: evaluator.unchargedCalls()
+			testMetricCalls: evaluator.unchargedCalls(),
+			testUsage: evaluator.unchargedUsage()
 		},
 		...bestOutputs === void 0 ? {} : { bestOutputs },
 		candidates: records,
@@ -1481,6 +1535,7 @@ async function runGepa(args) {
 		reflectionCalls,
 		cacheHits: evaluator.cacheHits(),
 		iterations: iteration,
+		warnings,
 		stopReason,
 		snapshot: takeSnapshot()
 	};
@@ -1493,13 +1548,15 @@ async function runGepa(args) {
 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 { minibatchSize = DEFAULT_MINIBATCH_SIZE, maxIterations = Number.POSITIVE_INFINITY, acceptance, 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}`);
+	const minimumPairs = acceptance?.minimumPairs;
+	if (minimumPairs !== void 0 && minibatchSize < minimumPairs) throw new Error(`this acceptance policy cannot accept anything on fewer than ${minimumPairs} instances, but minibatchSize is ${minibatchSize}; raise minibatchSize or loosen the policy`);
 	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}`);
@@ -1513,7 +1570,7 @@ function assertGepaConfig(config) {
 */
 function restoreRecords(args) {
 	const { records, seedCandidate } = args;
-	const known = new Set(require_evaluation.componentNames(seedCandidate));
+	const known = new Set(require_warnings.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(", ")})`);
@@ -1618,17 +1675,6 @@ function collectDominatorIds(records) {
 	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 = require_evaluation.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
@@ -1663,6 +1709,8 @@ exports.diverseReflectionStrategies = require_reflection.diverseReflectionStrate
 exports.epsilonGreedySelector = epsilonGreedySelector;
 exports.fullEvaluationPolicy = fullEvaluationPolicy;
 exports.improvementAcceptance = improvementAcceptance;
+exports.isCandidateAccepted = require_warnings.isCandidateAccepted;
+exports.isRunFinished = require_warnings.isRunFinished;
 exports.lowerBoundEvaluationPolicy = lowerBoundEvaluationPolicy;
 exports.pairedPermutationAcceptance = pairedPermutationAcceptance;
 exports.paretoSelector = paretoSelector;

package/dist/gepa/index.d.cts

@@ -1,8 +1,8 @@
-import { l as ScoreResult, u as TextModel } from "../types-CWv4IQFF.cjs";
+import { a as RunFinished, b as ScoreResult, i as Reporter, n as OptimizerEvent, o as isCandidateAccepted, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, x as TextModel } from "../reporting-bq007_2z.cjs";
 import { n as EvaluationCache } from "../cache-CuSo0NJ8.cjs";
-import { r as DemoRenderer } from "../demos-BTuzFNsp.cjs";
-import { n as OptimizerResult, r as OptimizerTask, t as Optimizer } from "../optimizer-B7SpRwl7.cjs";
-import { C as RejectedProposal, S as ReflectiveRecord, T as ValEvaluationPolicy, _ as GepaStopReason, a as buildRewritePrompt, b as ProposeArgs, c as AcceptancePolicy, d as CandidateSource, f as ComponentPatch, g as GepaSnapshot, h as GepaEvent, i as buildReflectionPrompt, l as CandidateRecord, m as GepaAdapter, n as ReflectionPromptBuilder, o as buildSimplifyPrompt, p as ComponentSelector, r as buildGeneralizePrompt, s as diverseReflectionStrategies, t as ReflectionPromptArgs, u as CandidateSelector, v as MakeReflectiveDatasetArgs, w as SelectionState, x as ReflectiveDataset, y as ParetoFrontier } from "../reflection-CQToe-5B.cjs";
+import { r as DemoRenderer } from "../demos-ByaLZy-Z.cjs";
+import { n as OptimizerResult, r as OptimizerTask, t as Optimizer } from "../optimizer-4Zv-Zt2t.cjs";
+import { C as ReflectiveRecord, E as ValEvaluationPolicy, S as ReflectiveDataset, T as SelectionState, _ as GepaStopReason, a as buildRewritePrompt, b as ProposeArgs, c as AcceptancePolicy, d as CandidateSource, f as ComponentPatch, g as GepaSnapshot, h as GepaEvent, i as buildReflectionPrompt, l as CandidateRecord, m as GepaAdapter, n as ReflectionPromptBuilder, o as buildSimplifyPrompt, p as ComponentSelector, r as buildGeneralizePrompt, s as diverseReflectionStrategies, t as ReflectionPromptArgs, u as CandidateSelector, v as MakeReflectiveDatasetArgs, w as RejectedProposal, x as ReflectiveBatch, y as ParetoFrontier } from "../reflection-D0A7eahD.cjs";
 import { t as BatchSampler } from "../sampling-axOwfZf5.cjs";
 //#region src/gepa/demos.d.ts
 /**
@@ -246,7 +246,13 @@ interface GepaTask<Datum, Trajectory = unknown, Output = unknown, K extends stri
    * counts against a reference run directly.
    */
   cache?: EvaluationCache | false;
-  onEvent?: (event: GepaEvent<NoInfer<K>>) => void;
+  /**
+   * Where the run's events go. An array because a run usually has more than
+   * one audience — a progress line on the terminal and a permanent record
+   * somewhere else — and teeing one callback by hand is how one of them ends
+   * up silently dropped.
+   */
+  reporters?: readonly Reporter<GepaEvent<NoInfer<K>>>[];
   /**
    * Called with a resumable snapshot after the seed is scored and after every
    * iteration. Persist it and a killed run costs the last iteration, not all
@@ -299,7 +305,9 @@ declare class GepaOptimizer implements Optimizer<GepaStopReason> {
  * `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.
+ * weight for every instance it wins *and* every objective it leads. The
+ * objectives are whatever the adapter put in `objectiveScores`, which for a
+ * judge is every criterion it graded, including any at `weight: 0`.
  */
 declare function paretoSelector(args?: {
   epsilon?: number;
@@ -382,4 +390,4 @@ declare function pairedPermutationAcceptance(args?: {
   maxExact?: number;
 }): AcceptancePolicy;
 //#endregion
-export { type AcceptancePolicy, type CandidateRecord, type CandidateSelector, type CandidateSource, type ComponentPatch, type ComponentSelector, type GepaAdapter, type GepaConfig, type GepaEvent, GepaOptimizer, type GepaResult, type GepaSnapshot, type GepaStopReason, type GepaTask, type MakeReflectiveDatasetArgs, type PipelineModule, type PipelineStep, type PipelineTrace, type ProposeArgs, type ReflectionPromptArgs, type ReflectionPromptBuilder, type ReflectiveDataset, type ReflectiveRecord, type RejectedProposal, type SelectionState, type ValEvaluationPolicy, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };
+export { type AcceptancePolicy, type CandidateAccepted, type CandidateRecord, type CandidateSelector, type CandidateSource, type ComponentPatch, type ComponentSelector, type GepaAdapter, type GepaConfig, type GepaEvent, GepaOptimizer, type GepaResult, type GepaSnapshot, type GepaStopReason, type GepaTask, type MakeReflectiveDatasetArgs, type OptimizerEvent, type PipelineModule, type PipelineStep, type PipelineTrace, type ProposeArgs, type ReflectionPromptArgs, type ReflectionPromptBuilder, type ReflectiveBatch, type ReflectiveDataset, type ReflectiveRecord, type RejectedProposal, type ReportableEvent, type Reporter, type RunFinished, type SelectionState, type ValEvaluationPolicy, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, isCandidateAccepted, isRunFinished, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };

package/dist/gepa/index.d.mts

@@ -1,8 +1,8 @@
-import { l as ScoreResult, u as TextModel } from "../types-CWv4IQFF.mjs";
+import { a as RunFinished, b as ScoreResult, i as Reporter, n as OptimizerEvent, o as isCandidateAccepted, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, x as TextModel } from "../reporting-bq007_2z.mjs";
 import { n as EvaluationCache } from "../cache-CuSo0NJ8.mjs";
-import { r as DemoRenderer } from "../demos-B0pVQjYC.mjs";
-import { n as OptimizerResult, r as OptimizerTask, t as Optimizer } from "../optimizer-DqCoth_w.mjs";
-import { C as RejectedProposal, S as ReflectiveRecord, T as ValEvaluationPolicy, _ as GepaStopReason, a as buildRewritePrompt, b as ProposeArgs, c as AcceptancePolicy, d as CandidateSource, f as ComponentPatch, g as GepaSnapshot, h as GepaEvent, i as buildReflectionPrompt, l as CandidateRecord, m as GepaAdapter, n as ReflectionPromptBuilder, o as buildSimplifyPrompt, p as ComponentSelector, r as buildGeneralizePrompt, s as diverseReflectionStrategies, t as ReflectionPromptArgs, u as CandidateSelector, v as MakeReflectiveDatasetArgs, w as SelectionState, x as ReflectiveDataset, y as ParetoFrontier } from "../reflection-Cr_upzU0.mjs";
+import { r as DemoRenderer } from "../demos-ASsSXYXA.mjs";
+import { n as OptimizerResult, r as OptimizerTask, t as Optimizer } from "../optimizer-Ds5mzYjz.mjs";
+import { C as ReflectiveRecord, E as ValEvaluationPolicy, S as ReflectiveDataset, T as SelectionState, _ as GepaStopReason, a as buildRewritePrompt, b as ProposeArgs, c as AcceptancePolicy, d as CandidateSource, f as ComponentPatch, g as GepaSnapshot, h as GepaEvent, i as buildReflectionPrompt, l as CandidateRecord, m as GepaAdapter, n as ReflectionPromptBuilder, o as buildSimplifyPrompt, p as ComponentSelector, r as buildGeneralizePrompt, s as diverseReflectionStrategies, t as ReflectionPromptArgs, u as CandidateSelector, v as MakeReflectiveDatasetArgs, w as RejectedProposal, x as ReflectiveBatch, y as ParetoFrontier } from "../reflection-CMezGu6u.mjs";
 import { t as BatchSampler } from "../sampling-DFo_7RNJ.mjs";
 //#region src/gepa/demos.d.ts
 /**
@@ -246,7 +246,13 @@ interface GepaTask<Datum, Trajectory = unknown, Output = unknown, K extends stri
    * counts against a reference run directly.
    */
   cache?: EvaluationCache | false;
-  onEvent?: (event: GepaEvent<NoInfer<K>>) => void;
+  /**
+   * Where the run's events go. An array because a run usually has more than
+   * one audience — a progress line on the terminal and a permanent record
+   * somewhere else — and teeing one callback by hand is how one of them ends
+   * up silently dropped.
+   */
+  reporters?: readonly Reporter<GepaEvent<NoInfer<K>>>[];
   /**
    * Called with a resumable snapshot after the seed is scored and after every
    * iteration. Persist it and a killed run costs the last iteration, not all
@@ -299,7 +305,9 @@ declare class GepaOptimizer implements Optimizer<GepaStopReason> {
  * `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.
+ * weight for every instance it wins *and* every objective it leads. The
+ * objectives are whatever the adapter put in `objectiveScores`, which for a
+ * judge is every criterion it graded, including any at `weight: 0`.
  */
 declare function paretoSelector(args?: {
   epsilon?: number;
@@ -382,4 +390,4 @@ declare function pairedPermutationAcceptance(args?: {
   maxExact?: number;
 }): AcceptancePolicy;
 //#endregion
-export { type AcceptancePolicy, type CandidateRecord, type CandidateSelector, type CandidateSource, type ComponentPatch, type ComponentSelector, type GepaAdapter, type GepaConfig, type GepaEvent, GepaOptimizer, type GepaResult, type GepaSnapshot, type GepaStopReason, type GepaTask, type MakeReflectiveDatasetArgs, type PipelineModule, type PipelineStep, type PipelineTrace, type ProposeArgs, type ReflectionPromptArgs, type ReflectionPromptBuilder, type ReflectiveDataset, type ReflectiveRecord, type RejectedProposal, type SelectionState, type ValEvaluationPolicy, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };
+export { type AcceptancePolicy, type CandidateAccepted, type CandidateRecord, type CandidateSelector, type CandidateSource, type ComponentPatch, type ComponentSelector, type GepaAdapter, type GepaConfig, type GepaEvent, GepaOptimizer, type GepaResult, type GepaSnapshot, type GepaStopReason, type GepaTask, type MakeReflectiveDatasetArgs, type OptimizerEvent, type PipelineModule, type PipelineStep, type PipelineTrace, type ProposeArgs, type ReflectionPromptArgs, type ReflectionPromptBuilder, type ReflectiveBatch, type ReflectiveDataset, type ReflectiveRecord, type RejectedProposal, type ReportableEvent, type Reporter, type RunFinished, type SelectionState, type ValEvaluationPolicy, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, isCandidateAccepted, isRunFinished, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };