textopt 0.0.0 → 0.2.0

package/dist/{optimizer-DqCoth_w.d.mts → optimizer-Ds5mzYjz.d.mts}

@@ -1,4 +1,4 @@
-import { d as UsageTotals, i as EvaluationBatch, n as Candidate, o as EvaluationPhase, s as EvaluationSplit, t as Adapter } from "./types-CWv4IQFF.mjs";
+import { S as UsageTotals, _ as EvaluationPhase, c as RunWarning, f as Adapter, h as EvaluationBatch, p as Candidate, v as EvaluationSplit } from "./reporting-bq007_2z.mjs";
 import { n as EvaluationCache, t as CachedScore } from "./cache-CuSo0NJ8.mjs";
 //#region src/budget.d.ts
 interface Budget {
@@ -106,8 +106,24 @@ interface Evaluator<Datum, Trajectory, Output, K extends string> {
   cacheHits(): number;
   /** Rollouts made with `charge: false`, tracked apart from the budget. */
   unchargedCalls(): number;
-  /** Tokens and money the run has spent, as far as adapters have reported it. */
+  /**
+   * Tokens and money the search has spent, as far as adapters have reported
+   * it. `maxCostUsd` is checked against this, so what the ceiling does not
+   * bound is not counted in it: rollouts made with `charge: false` are in
+   * `unchargedUsage` instead.
+   */
   usage(): UsageTotals;
+  /**
+   * What the rollouts made with `charge: false` cost. Held-out measurement is
+   * taken after the search has stopped, so no ceiling bounds it and reporting
+   * it inside `usage` would describe a run as having overrun one.
+   */
+  unchargedUsage(): UsageTotals;
+  /**
+   * Folds in usage spent outside this evaluator — harvesting runs its own, and
+   * a cost ceiling that cannot see it bounds only part of the run.
+   */
+  absorbUsage(spent: UsageTotals): void;
   /** Cache contents for checkpointing, when the cache can enumerate them. */
   entries(): [string, CachedScore][] | undefined;
   restore(entries: Iterable<readonly [string, CachedScore]>): void;
@@ -140,6 +156,12 @@ declare function createEvaluator<Datum, Trajectory, Output, K extends string>(ar
   signal?: AbortSignal;
   /** Resumed counters, so a continued run reports totals rather than deltas. */
   cacheHits?: number;
+  /**
+   * Usage the interrupted run had already spent. Without it `maxCostUsd` is a
+   * ceiling on the segment rather than on the run, and resuming repeatedly
+   * spends it again each time.
+   */
+  usage?: UsageTotals;
   /**
    * Rate limits and 5xx responses are the common case in a long run, and a
    * transient row costs the instance whichever optimizer is driving: it is
@@ -192,8 +214,28 @@ declare function requireMeasuredMean(args: {
  */
 interface OptimizerTask<Datum, Trajectory = unknown, Output = unknown, K extends string = string> {
   seedCandidate: Candidate<K>;
+  /**
+   * Instances the search draws evidence from. Reflective optimizers mine these
+   * for what a candidate got wrong, so a training row earns its place by being
+   * diagnostic — a row every candidate already passes teaches the rewriter
+   * nothing.
+   *
+   * @see docs/data-prep.md
+   */
   trainingSet: readonly Datum[];
-  validationSet?: readonly Datum[];
+  /**
+   * Instances the search selects candidates against. Defaults to
+   * `trainingSet`, which is the right default for a first run and the wrong
+   * number to report from one — the result carries a warning saying so.
+   * `"reuseTraining"` is that same default with the caller's name on it, and
+   * carries no warning.
+   *
+   * Split by group rather than by row: near-duplicate instances that straddle
+   * the boundary leak, and the run reports a score nothing earned.
+   *
+   * @see docs/data-prep.md
+   */
+  validationSet?: readonly Datum[] | "reuseTraining";
   /**
    * `NoInfer` keeps the adapter out of `K`'s inference: an adapter built by a
    * factory knows nothing about component names, and one inference candidate of
@@ -207,6 +249,18 @@ interface OptimizerTask<Datum, Trajectory = unknown, Output = unknown, K extends
    * number in a result that no candidate was ever selected against.
    */
   testSet?: readonly Datum[];
+  /**
+   * Scored rollouts the search may spend. Cache hits do not count, and test
+   * rollouts are outside it entirely.
+   *
+   * Spending it is only worth anything if the metric separates candidates
+   * first: a metric that scores every candidate alike turns the whole budget
+   * into ranked ties, and the run reports a stop reason that looks like any
+   * other.
+   *
+   * @see docs/metric-preflight.md
+   * @see docs/tuning.md
+   */
   maxMetricCalls: number;
   /**
    * Dollars the run may spend, as reported by the adapter's usage. Checked
@@ -252,8 +306,25 @@ interface OptimizerResult<K extends string, Stop extends string, Output = unknow
   bestOutputs?: (Output | undefined)[];
   metricCalls: number;
   /**
-   * Tokens and dollars the run spent, summed from what the adapter reported.
-   * Zero throughout when the adapter reports no usage.
+   * Rollouts served from the cache rather than charged to `metricCalls`. Every
+   * optimizer here caches by default, so the same `maxMetricCalls` can buy a
+   * search that revisits scored candidates a longer effective run than one
+   * that never does — a comparison over `metricCalls` alone hides that. Zero
+   * for a run with caching disabled.
+   */
+  cacheHits: number;
+  /**
+   * Calls made to a proposal or reflection model, which no metric budget
+   * covers — see each optimizer's own accounting for what a call costs there.
+   * Absent from a search that proposes nothing of its own: bootstrap search
+   * only accepts or rejects rollouts the metric already scored.
+   */
+  reflectionCalls?: number;
+  /**
+   * Tokens and dollars the search spent, summed from what the adapter reported.
+   * Zero throughout when the adapter reports no usage. `maxCostUsd` is checked
+   * against this, so the held-out sweep — which runs after the search has
+   * stopped, under no ceiling — is reported apart from it, in `testUsage`.
    */
   usage: UsageTotals;
   /**
@@ -267,7 +338,21 @@ interface OptimizerResult<K extends string, Stop extends string, Output = unknow
    * measurement rather than search, and so is not charged to `maxMetricCalls`.
    */
   testMetricCalls?: number;
+  /**
+   * Tokens and dollars the held-out sweep cost, for the same reason: no ceiling
+   * bounds it, so a caller adding up what a run spent has to see it as its own
+   * number rather than find it folded into one `maxCostUsd` was supposed to
+   * hold. Absent when no testSet was given.
+   */
+  testUsage?: UsageTotals;
   stopReason: Stop;
+  /**
+   * What this run cannot say about itself from its own numbers — selection
+   * that reused the training instances, a seed the metric could not separate.
+   * Empty when there is nothing to say. Never fatal, and repeated on the
+   * `finish` event so a reporter sees them next to the score.
+   */
+  warnings: RunWarning[];
 }
 /**
  * An optimizer: a task in, the best candidate it found out. Exactly one method.

package/dist/random-search/index.cjs

@@ -1,5 +1,5 @@
 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_text = require("../text-CK_HB3su.cjs");
 //#region src/random-search/optimize.ts
@@ -33,10 +33,14 @@ var RandomSearchOptimizer = class {
 		this.#config = config;
 	}
 	async optimize(task) {
-		return runRandomSearch({
-			config: this.#config,
-			task
-		});
+		try {
+			return await runRandomSearch({
+				config: this.#config,
+				task
+			});
+		} finally {
+			await require_warnings.flushReporters(task.reporters ?? []);
+		}
 	}
 };
 /**
@@ -63,9 +67,14 @@ function buildParaphrasePrompt(args) {
 async function runRandomSearch(args) {
 	const { config, task } = args;
 	const { variants = DEFAULT_VARIANTS, concurrency = 1, maxRounds = Number.POSITIVE_INFINITY, buildPrompt = buildParaphrasePrompt, trackBestOutputs = false, checkpointCache = true } = config;
-	const { seedCandidate, trainingSet, validationSet = trainingSet, testSet, adapter, reflect, maxMetricCalls, cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = defaultInstanceId, onEvent, onCheckpoint, resumeFrom, signal } = task;
-	const deadline = require_evaluation.createDeadline({ maxWallClockMs });
-	const components = require_evaluation.componentNames(seedCandidate);
+	const { seedCandidate, trainingSet, validationSet: requestedValidationSet, testSet, adapter, reflect, maxMetricCalls, cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = require_warnings.defaultInstanceId, reporters = [], onCheckpoint, resumeFrom, signal } = task;
+	const { validationSet, warnings } = require_warnings.resolveValidationSet({
+		validationSet: requestedValidationSet,
+		trainingSet
+	});
+	const emit = require_warnings.createEmitter(reporters);
+	const deadline = require_warnings.createDeadline({ maxWallClockMs });
+	const components = require_warnings.componentNames(seedCandidate);
 	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");
 	if (components.length === 0) throw new Error("optimize requires a seed candidate with at least one component");
@@ -78,7 +87,7 @@ async function runRandomSearch(args) {
 		datum,
 		index
 	})) ?? [];
-	const fingerprint = require_evaluation.runFingerprint({
+	const fingerprint = require_warnings.runFingerprint({
 		seedCandidate,
 		trainingIds: trainingSet.map((datum, index) => instanceId({
 			datum,
@@ -87,16 +96,16 @@ async function runRandomSearch(args) {
 		validationIds,
 		...cacheNamespace === void 0 ? {} : { cacheNamespace }
 	});
-	require_evaluation.assertResumable({
+	require_warnings.assertResumable({
 		fingerprint,
 		...resumeFrom === void 0 ? {} : { snapshot: resumeFrom }
 	});
-	const budget = require_evaluation.createBudget({
+	const budget = require_warnings.createBudget({
 		maxMetricCalls,
 		spent: resumeFrom?.metricCalls ?? 0
 	});
-	const evaluationCache = cache === false ? void 0 : cache ?? require_evaluation.createMemoryCache();
-	const evaluator = require_evaluation.createEvaluator({
+	const evaluationCache = cache === false ? void 0 : cache ?? require_warnings.createMemoryCache();
+	const evaluator = require_warnings.createEvaluator({
 		adapter,
 		budget,
 		...retry === void 0 ? {} : { retry },
@@ -104,8 +113,9 @@ async function runRandomSearch(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) => onEvent?.({
+		onEvaluation: (event) => emit({
 			type: "evaluation",
 			...event
 		})
@@ -123,7 +133,7 @@ async function runRandomSearch(args) {
 	* no budget here bounds.
 	*/
 	let stalledRounds = 0;
-	onEvent?.({
+	emit({
 		type: "start",
 		components,
 		validationSetSize: validationSet.length
@@ -152,6 +162,8 @@ async function runRandomSearch(args) {
 			reflectionCalls,
 			metricCalls: budget.spent(),
 			cacheHits: evaluator.cacheHits(),
+			usage: evaluator.usage(),
+			acceptedCandidates,
 			...cached === void 0 ? {} : { cache: cached }
 		};
 	}
@@ -163,21 +175,31 @@ async function runRandomSearch(args) {
 		candidate: seedCandidate,
 		phase: "seed"
 	}) : void 0;
-	const seedScore = seedEvaluation === void 0 ? resumeFrom.seedScore : require_evaluation.requireMeasuredMean({
+	const seedScore = seedEvaluation === void 0 ? resumeFrom.seedScore : require_warnings.requireMeasuredMean({
 		batch: seedEvaluation,
 		phase: "seed"
 	});
+	if (seedEvaluation !== void 0) emit({
+		type: "candidateAccepted",
+		round: 0,
+		candidateId: 0,
+		candidate: seedCandidate,
+		aggregateScore: seedScore,
+		instanceScores: require_warnings.instanceRow(seedEvaluation),
+		...trackBestOutputs ? { outputs: seedEvaluation.outputs } : {}
+	});
 	let best = resumeFrom?.best ?? seedCandidate;
 	let bestScore = resumeFrom?.bestScore ?? seedScore;
 	/** Absent on a resumed run until a variant wins: outputs are not checkpointed. */
 	let bestOutputs = seedEvaluation?.outputs;
+	let acceptedCandidates = resumeFrom?.acceptedCandidates ?? 0;
 	await checkpoint();
 	while (round < maxRounds) {
 		if (signal?.aborted) {
 			stopReason = "aborted";
 			break;
 		}
-		if (require_evaluation.costExhausted({
+		if (require_warnings.costExhausted({
 			usage: evaluator.usage(),
 			maxCostUsd
 		})) {
@@ -188,12 +210,12 @@ async function runRandomSearch(args) {
 			stopReason = "deadlineReached";
 			break;
 		}
-		if (!budget.canAfford(variants * validationSet.length)) {
+		if (!budget.canAfford(validationSet.length)) {
 			stopReason = "budgetExhausted";
 			break;
 		}
 		const component = components[round % components.length];
-		onEvent?.({
+		emit({
 			type: "roundStart",
 			round,
 			component
@@ -220,41 +242,64 @@ async function runRandomSearch(args) {
 		});
 		const unique = [...new Set(drawn)].filter((text) => text.length > 0 && text !== currentText);
 		let roundStop;
+		const scheduled = [];
+		let owed = 0;
 		for (const text of unique) {
 			const candidate = {
 				...best,
 				[component]: text
 			};
-			let evaluation;
-			try {
-				evaluation = await sweep({
-					candidate,
-					phase: "validation"
-				});
-			} catch (err) {
-				if (err instanceof require_evaluation.BudgetExhausted) {
-					roundStop = "budgetExhausted";
-					break;
-				}
-				if (signal?.aborted) {
-					roundStop = "aborted";
-					break;
+			const uncached = evaluator.countUncached({
+				candidate,
+				ids: validationIds,
+				split: "val"
+			});
+			if (!budget.canAfford(owed + uncached)) {
+				roundStop = "budgetExhausted";
+				break;
+			}
+			owed += uncached;
+			scheduled.push(candidate);
+		}
+		const swept = await require_concurrency.mapWithConcurrency({
+			items: scheduled,
+			limit: concurrency,
+			task: async (candidate) => {
+				if (signal?.aborted) return { stop: "aborted" };
+				try {
+					return { evaluation: await sweep({
+						candidate,
+						phase: "validation"
+					}) };
+				} catch (err) {
+					if (err instanceof require_warnings.BudgetExhausted) return { stop: "budgetExhausted" };
+					if (signal?.aborted) return { stop: "aborted" };
+					throw err;
 				}
-				throw err;
+			}
+		});
+		for (const [index, outcome] of swept.entries()) {
+			if (outcome.stop !== void 0) {
+				roundStop = outcome.stop;
+				break;
 			}
 			variantsEvaluated += 1;
-			const score = require_evaluation.measuredMean(evaluation);
+			const score = require_warnings.measuredMean(outcome.evaluation);
 			if (score !== void 0 && score > bestScore) {
-				onEvent?.({
+				const candidate = scheduled[index];
+				acceptedCandidates += 1;
+				emit({
 					type: "candidateAccepted",
 					round,
-					component,
-					score,
-					previousScore: bestScore
+					candidateId: acceptedCandidates,
+					candidate,
+					aggregateScore: score,
+					instanceScores: require_warnings.instanceRow(outcome.evaluation),
+					...trackBestOutputs ? { outputs: outcome.evaluation.outputs } : {}
 				});
 				best = candidate;
 				bestScore = score;
-				bestOutputs = evaluation.outputs;
+				bestOutputs = outcome.evaluation.outputs;
 			}
 		}
 		round += 1;
@@ -270,7 +315,7 @@ async function runRandomSearch(args) {
 		}
 	}
 	if (signal?.aborted) stopReason = "aborted";
-	const testScore = testSet === void 0 ? void 0 : require_evaluation.measuredMean(await evaluator.evaluate({
+	const heldOut = testSet === void 0 ? void 0 : await evaluator.evaluate({
 		candidate: best,
 		batch: testSet,
 		ids: testIds,
@@ -279,13 +324,18 @@ async function runRandomSearch(args) {
 		candidateId: null,
 		iteration: round,
 		charge: false
-	}));
-	onEvent?.({
+	});
+	const testScore = heldOut === void 0 ? void 0 : require_warnings.measuredMean(heldOut);
+	emit({
 		type: "finish",
 		reason: stopReason,
+		warnings,
+		bestCandidateId: acceptedCandidates,
 		bestScore,
 		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 }
 	});
 	return {
 		bestCandidate: best,
@@ -296,13 +346,15 @@ async function runRandomSearch(args) {
 		...trackBestOutputs ? { bestOutputs } : {},
 		...testScore === void 0 ? {} : {
 			testScore,
-			testMetricCalls: evaluator.unchargedCalls()
+			testMetricCalls: evaluator.unchargedCalls(),
+			testUsage: evaluator.unchargedUsage()
 		},
 		rounds: round,
 		variantsEvaluated,
 		metricCalls: budget.spent(),
 		reflectionCalls,
 		cacheHits: evaluator.cacheHits(),
+		warnings,
 		stopReason
 	};
 }
@@ -312,10 +364,8 @@ function assertConfig(config) {
 	if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error(`concurrency must be a positive integer, received ${concurrency}`);
 	if (maxRounds !== void 0 && (!Number.isInteger(maxRounds) || maxRounds < 1)) throw new Error(`maxRounds must be a positive integer, received ${maxRounds}`);
 }
-function defaultInstanceId(args) {
-	const hash = require_evaluation.stableHash(args.datum);
-	return hash === "" ? String(args.index) : hash;
-}
 //#endregion
 exports.RandomSearchOptimizer = RandomSearchOptimizer;
 exports.buildParaphrasePrompt = buildParaphrasePrompt;
+exports.isCandidateAccepted = require_warnings.isCandidateAccepted;
+exports.isRunFinished = require_warnings.isRunFinished;

package/dist/random-search/index.d.cts

@@ -1,6 +1,6 @@
-import { n as Candidate, t as Adapter, u as TextModel } from "../types-CWv4IQFF.cjs";
+import { S as UsageTotals, a as RunFinished, f as Adapter, i as Reporter, n as OptimizerEvent, o as isCandidateAccepted, p as Candidate, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, x as TextModel } from "../reporting-bq007_2z.cjs";
 import { n as EvaluationCache, t as CachedScore } from "../cache-CuSo0NJ8.cjs";
-import { n as OptimizerResult, r as OptimizerTask, s as EvaluationEvent, t as Optimizer } from "../optimizer-B7SpRwl7.cjs";
+import { n as OptimizerResult, r as OptimizerTask, s as EvaluationEvent, t as Optimizer } from "../optimizer-4Zv-Zt2t.cjs";
 //#region src/random-search/optimize.d.ts
 /** Builds the prompt one variant is drawn from. */
 type ParaphrasePromptBuilder = (args: {
@@ -54,6 +54,13 @@ interface RandomSearchSnapshot {
   reflectionCalls: number;
   metricCalls: number;
   cacheHits: number;
+  /** Usage already spent, so a resumed run reports totals and honours ceilings. */
+  usage?: UsageTotals;
+  /**
+   * Candidates accepted so far. Reporters key rows by this id, so restarting it
+   * at zero makes a resumed run collide with the run it continues.
+   */
+  acceptedCandidates?: number;
   /** Cached instance scores, when the cache can enumerate them. */
   cache?: [string, CachedScore][];
 }
@@ -71,7 +78,8 @@ interface RandomSearchTask<Datum, Trajectory = unknown, Output = unknown, K exte
   }) => string;
   /** Pass `false` to disable caching entirely. */
   cache?: EvaluationCache | false;
-  onEvent?: (event: RandomSearchEvent<NoInfer<K>>) => void;
+  /** Observers of the run. Every one sees every event; none can fail it. */
+  reporters?: readonly Reporter<RandomSearchEvent<NoInfer<K>>>[];
   /**
    * Called with a resumable snapshot after the seed is scored and after every
    * round. Persist it and a killed run costs the last round, not all of them.
@@ -91,19 +99,13 @@ type RandomSearchEvent<K extends string = string> = {
   component: K;
 } | ({
   type: "evaluation";
-} & EvaluationEvent) | {
+} & EvaluationEvent) | ({
   type: "candidateAccepted";
   round: number;
-  component: K;
-  score: number;
-  previousScore: number;
-} | {
+} & CandidateAccepted<K>) | ({
   type: "finish";
   reason: RandomSearchStopReason;
-  bestScore: number;
-  metricCalls: number;
-  testScore?: number;
-};
+} & RunFinished);
 interface RandomSearchResult<K extends string = string, Output = unknown> extends OptimizerResult<K, RandomSearchStopReason, Output> {
   /** The seed's score, so the lift the search bought is readable directly. */
   seedScore: number;
@@ -153,4 +155,4 @@ declare function buildParaphrasePrompt(args: {
   attempt: number;
 }): string;
 //#endregion
-export { type ParaphrasePromptBuilder, type RandomSearchConfig, type RandomSearchEvent, RandomSearchOptimizer, type RandomSearchResult, type RandomSearchSnapshot, type RandomSearchStopReason, type RandomSearchTask, buildParaphrasePrompt };
+export { type CandidateAccepted, type OptimizerEvent, type ParaphrasePromptBuilder, type RandomSearchConfig, type RandomSearchEvent, RandomSearchOptimizer, type RandomSearchResult, type RandomSearchSnapshot, type RandomSearchStopReason, type RandomSearchTask, type ReportableEvent, type Reporter, type RunFinished, buildParaphrasePrompt, isCandidateAccepted, isRunFinished };

package/dist/random-search/index.d.mts

@@ -1,6 +1,6 @@
-import { n as Candidate, t as Adapter, u as TextModel } from "../types-CWv4IQFF.mjs";
+import { S as UsageTotals, a as RunFinished, f as Adapter, i as Reporter, n as OptimizerEvent, o as isCandidateAccepted, p as Candidate, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, x as TextModel } from "../reporting-bq007_2z.mjs";
 import { n as EvaluationCache, t as CachedScore } from "../cache-CuSo0NJ8.mjs";
-import { n as OptimizerResult, r as OptimizerTask, s as EvaluationEvent, t as Optimizer } from "../optimizer-DqCoth_w.mjs";
+import { n as OptimizerResult, r as OptimizerTask, s as EvaluationEvent, t as Optimizer } from "../optimizer-Ds5mzYjz.mjs";
 //#region src/random-search/optimize.d.ts
 /** Builds the prompt one variant is drawn from. */
 type ParaphrasePromptBuilder = (args: {
@@ -54,6 +54,13 @@ interface RandomSearchSnapshot {
   reflectionCalls: number;
   metricCalls: number;
   cacheHits: number;
+  /** Usage already spent, so a resumed run reports totals and honours ceilings. */
+  usage?: UsageTotals;
+  /**
+   * Candidates accepted so far. Reporters key rows by this id, so restarting it
+   * at zero makes a resumed run collide with the run it continues.
+   */
+  acceptedCandidates?: number;
   /** Cached instance scores, when the cache can enumerate them. */
   cache?: [string, CachedScore][];
 }
@@ -71,7 +78,8 @@ interface RandomSearchTask<Datum, Trajectory = unknown, Output = unknown, K exte
   }) => string;
   /** Pass `false` to disable caching entirely. */
   cache?: EvaluationCache | false;
-  onEvent?: (event: RandomSearchEvent<NoInfer<K>>) => void;
+  /** Observers of the run. Every one sees every event; none can fail it. */
+  reporters?: readonly Reporter<RandomSearchEvent<NoInfer<K>>>[];
   /**
    * Called with a resumable snapshot after the seed is scored and after every
    * round. Persist it and a killed run costs the last round, not all of them.
@@ -91,19 +99,13 @@ type RandomSearchEvent<K extends string = string> = {
   component: K;
 } | ({
   type: "evaluation";
-} & EvaluationEvent) | {
+} & EvaluationEvent) | ({
   type: "candidateAccepted";
   round: number;
-  component: K;
-  score: number;
-  previousScore: number;
-} | {
+} & CandidateAccepted<K>) | ({
   type: "finish";
   reason: RandomSearchStopReason;
-  bestScore: number;
-  metricCalls: number;
-  testScore?: number;
-};
+} & RunFinished);
 interface RandomSearchResult<K extends string = string, Output = unknown> extends OptimizerResult<K, RandomSearchStopReason, Output> {
   /** The seed's score, so the lift the search bought is readable directly. */
   seedScore: number;
@@ -153,4 +155,4 @@ declare function buildParaphrasePrompt(args: {
   attempt: number;
 }): string;
 //#endregion
-export { type ParaphrasePromptBuilder, type RandomSearchConfig, type RandomSearchEvent, RandomSearchOptimizer, type RandomSearchResult, type RandomSearchSnapshot, type RandomSearchStopReason, type RandomSearchTask, buildParaphrasePrompt };
+export { type CandidateAccepted, type OptimizerEvent, type ParaphrasePromptBuilder, type RandomSearchConfig, type RandomSearchEvent, RandomSearchOptimizer, type RandomSearchResult, type RandomSearchSnapshot, type RandomSearchStopReason, type RandomSearchTask, type ReportableEvent, type Reporter, type RunFinished, buildParaphrasePrompt, isCandidateAccepted, isRunFinished };