textopt 0.0.0 → 0.2.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { a as EvaluationContext, c as RolloutUsage, d as UsageTotals, f as componentNames, i as EvaluationBatch, l as ScoreResult, n as Candidate, o as EvaluationPhase, r as EvaluateArgs, s as EvaluationSplit, t as Adapter, u as TextModel } from "./types-CWv4IQFF.cjs";
+import { C as componentNames, S as UsageTotals, _ as EvaluationPhase, a as RunFinished, b as ScoreResult, c as RunWarning, d as seedScoreWarnings, f as Adapter, g as EvaluationContext, h as EvaluationBatch, i as Reporter, l as RunWarningCode, m as EvaluateArgs, n as OptimizerEvent, o as isCandidateAccepted, p as Candidate, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, u as resolveValidationSet, v as EvaluationSplit, x as TextModel, y as RolloutUsage } from "./reporting-bq007_2z.cjs";
 import { n as EvaluationCache, r as createMemoryCache, t as CachedScore } from "./cache-CuSo0NJ8.cjs";
 import { t as Rng } from "./rng-BR5MOedA.cjs";
-import { a as formatDemos, i as bootstrapDemos, n as Demo, o as parseDemos, r as DemoRenderer, t as BootstrapResult } from "./demos-BTuzFNsp.cjs";
-import { a as EvaluateBatchArgs, c as Evaluator, d as costExhausted, f as createEvaluator, g as createBudget, h as Budget, i as BudgetExhausted, l as RetryPolicy, m as requireMeasuredMean, n as OptimizerResult, o as EvaluateTracedArgs, p as measuredMean, r as OptimizerTask, s as EvaluationEvent, t as Optimizer, u as ScoredBatch } from "./optimizer-B7SpRwl7.cjs";
+import { a as harvestFewShotExamples, i as formatDemos, n as Demo, o as parseDemos, r as DemoRenderer, t as BootstrapResult } from "./demos-ByaLZy-Z.cjs";
+import { a as EvaluateBatchArgs, c as Evaluator, d as costExhausted, f as createEvaluator, g as createBudget, h as Budget, i as BudgetExhausted, l as RetryPolicy, m as requireMeasuredMean, n as OptimizerResult, o as EvaluateTracedArgs, p as measuredMean, r as OptimizerTask, s as EvaluationEvent, t as Optimizer, u as ScoredBatch } from "./optimizer-4Zv-Zt2t.cjs";
 import { t as BatchSampler } from "./sampling-axOwfZf5.cjs";
 //#region src/checkpoint.d.ts
 /**
@@ -46,6 +46,10 @@ interface ComparisonRun {
   bestScore: number;
   testScore?: number;
   metricCalls: number;
+  /** Rollouts this run got from the cache instead of paying for. */
+  cacheHits: number;
+  /** Calls to a proposal or reflection model, outside the metric budget. */
+  reflectionCalls: number;
   costUsd: number;
   stopReason: string;
 }
@@ -58,12 +62,33 @@ interface ComparisonSummary {
   maxScore: number;
   meanMetricCalls: number;
   meanCostUsd: number;
+  meanCacheHits: number;
+  meanReflectionCalls: number;
+  /**
+   * How many distinct values this entrant's score took across its seeds.
+   * 1 means every seed landed on the same number — the seed changed nothing
+   * about the outcome, whatever the search did internally with it.
+   */
+  distinctScores: number;
   /**
    * How often the winner's margin over this entrant would arise if the two
-   * were equally good and each seed's outcome were a coin flip. Absent for the
-   * winner itself.
+   * were equally good and each seed's outcome were a coin flip. Absent for
+   * the winner itself, and also absent when every seed produced the exact
+   * same margin: a sign-flip test over n seeds is answering a question about
+   * n independent trials, and identical margins mean the seed never actually
+   * put that to the test — there was one realization, repeated. Reporting a
+   * p-value there would state a precision (as fine as 2^-n) that the run
+   * never earned, so it is withheld rather than printed misleadingly small.
    */
   pValueVsWinner?: number;
+  /**
+   * `pValueVsWinner` after Holm-Bonferroni step-down across the other
+   * entrants in this same `compare()` call — the family the raw p-value
+   * would otherwise be read against in isolation. Absent wherever the raw
+   * p-value is: a withheld comparison has nothing to adjust, but it still
+   * occupies a slot in the family the other comparisons are corrected for.
+   */
+  pValueVsWinnerHolm?: number;
 }
 interface Comparison {
   /** Highest mean score. Read `pValueVsWinner` before believing it. */
@@ -85,7 +110,7 @@ interface Comparison {
  * seed is constructor config and every optimizer here is deterministic given
  * one — comparing two entrants at a single seed compares two anecdotes. It also
  * leaves the task where the caller builds it, which is the only place the
- * optimizer-specific parts of it (`reflect`, `cache`, `onEvent`) are known.
+ * optimizer-specific parts of it (`reflect`, `cache`, `reporters`) are known.
  */
 declare function compare<K extends string, Output = unknown>(args: {
   entrants: Record<string, (args: {
@@ -136,11 +161,156 @@ declare function createDeadline(args: {
   now?: () => number;
 }): Deadline;
 //#endregion
+//#region src/harvest.d.ts
+/**
+ * One rollout worth keeping: what went in, what the system produced, and how
+ * that output scored. Harvested, never written — the value of the pair is that
+ * the system actually produced the output and the metric actually rewarded it.
+ */
+interface Rollout<Datum = unknown, Output = unknown> {
+  input: Datum;
+  output: Output;
+  score: number;
+}
+interface HarvestResult<Datum, Output> {
+  rollouts: Rollout<Datum, Output>[];
+  /** Rollouts this cost. Harvesting is cheap, not free. */
+  metricCalls: number;
+  /**
+   * Tokens and dollars this cost. Harvesting runs on its own evaluator, so a
+   * caller that bounds spend has to fold these into its own totals.
+   */
+  usage: UsageTotals;
+  /** Instances run, including the ones the metric did not reward. */
+  attempted: number;
+}
+/**
+ * Run a candidate over data and keep the rollouts the metric rewarded.
+ *
+ * The library's one paid collection primitive, with two consumers: a few-shot
+ * block wants four of these, and a distillation set wants thousands. Both are
+ * the same pass — run the candidate, score it, keep what cleared the bar — so
+ * both share the budget, retry and transient-failure handling that pass needs.
+ *
+ * Which data to sweep is the caller's decision and the consequential one. A
+ * validation set is the wrong choice: it is the set that selected the candidate,
+ * so the rollouts it yields are enriched for the candidate's fit to those
+ * instances rather than to the task. Prefer the training set, or a pool held
+ * out of the run entirely.
+ */
+declare function harvestRollouts<Datum, Trajectory, Output, K extends string = string>(args: {
+  adapter: Adapter<Datum, Trajectory, Output, K>;
+  /** The candidate to run. Usually a run's winner, sometimes the seed. */
+  candidate: Candidate<K>;
+  data: readonly Datum[];
+  /**
+   * Score a rollout must reach to be kept. Unset keeps every rollout the
+   * metric rewarded at all, which is what MIPROv2's bootstrapper does without
+   * a `metric_threshold`: it keeps a trace on any truthy score and only
+   * compares against a number once one is configured.
+   *
+   * Demanding a perfect score instead is the right call for a boolean metric
+   * and the wrong one for a graded metric, where it throws away every rollout
+   * that was most of the way there — which on a hard task is all of them.
+   */
+  minScore?: number;
+  /** Rollouts to collect before stopping. Unset sweeps the whole pool. */
+  maxRollouts?: number;
+  /**
+   * Instances per rollout batch. Smaller batches stop closer to the moment
+   * enough rollouts exist, at the cost of less concurrency inside the adapter.
+   */
+  batchSize?: number;
+  /** Ceiling on rollouts run. Defaults to one pass over `data`. */
+  maxMetricCalls?: number;
+  /**
+   * Ceiling on dollars this pass may spend, checked between batches. Rollout
+   * counts are a poor proxy for spend, and a caller bounding dollars cannot
+   * bound this pass from outside: it runs on its own evaluator.
+   */
+  maxCostUsd?: number;
+  /** Shuffles `data` first, so rollouts are not all drawn from its head. */
+  rng?: Rng;
+  signal?: AbortSignal;
+}): Promise<HarvestResult<Datum, Output>>;
+//#endregion
+//#region src/distillation.d.ts
+/** A turn in a training example, in the shape trainers read. */
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+interface TrainingExample {
+  messages: ChatMessage[];
+}
+/**
+ * Turns one harvested rollout into the example to train on, or `null` to skip
+ * it. The callback exists because only the caller knows how to render a
+ * `Datum` — the library never sees inside one.
+ *
+ * It is also where the consequential decision lives: how much of the optimized
+ * candidate to leave in the input. Dropping it entirely moves the whole prompt
+ * into weights and gives up the ability to steer the model with text
+ * afterwards; keeping a short task statement distills away only the tokens the
+ * search accreted. See `docs/distillation.md` in this package.
+ */
+type TrainingExampleRenderer<Datum, Output> = (args: {
+  rollout: Rollout<Datum, Output>;
+  index: number;
+}) => TrainingExample | null;
+/**
+ * Serialize harvested rollouts as JSONL, one training example per line.
+ *
+ * The chat-messages shape rather than any one vendor's: it is what Axolotl,
+ * Together, Fireworks and the Hugging Face trainers all ingest, and the
+ * providers that read it outlive the ones that do not.
+ *
+ * Returns the text rather than writing it. Only `file-cache` touches the
+ * filesystem, and a caller uploading this straight to a provider should not
+ * have to round-trip it through a file to do so.
+ */
+declare function toTrainingJsonl<Datum, Output>(args: {
+  rollouts: readonly Rollout<Datum, Output>[];
+  render: TrainingExampleRenderer<Datum, Output>;
+}): string;
+//#endregion
 //#region src/judge.d.ts
 /** One thing the judge grades, and what a perfect answer looks like for it. */
 interface JudgeCriterion {
   name: string;
   description: string;
+  /**
+   * Share of the instance score this criterion carries, relative to the other
+   * criteria. Default 1, which is the unweighted mean.
+   *
+   * 0 removes a criterion from the aggregate, not from the search. It is still
+   * graded and still recorded in `objectiveScores`, which
+   * `paretoSelector({ frontier: "objective" })` and `"hybrid"` build their
+   * selection fronts from — so a candidate leading a zero-weight criterion
+   * still earns parent selection under those. Under the default instance
+   * frontier, 0 is enough. For a number that can never steer the search,
+   * compute it outside the judge.
+   */
+  weight?: number;
+  /**
+   * Grade, on the judge's own scale, that this criterion must reach for the
+   * instance to score at all. Below it the instance scores 0 whatever the
+   * other criteria said.
+   *
+   * A mean lets a search trade a hard requirement away: a candidate that tanks
+   * one non-negotiable criterion and aces three cosmetic ones outranks the
+   * incumbent that kept the rule. Anything a caller would not ship without is
+   * a gate rather than a term in the average.
+   *
+   * Enforce it once. A gate already makes the requirement non-negotiable, so a
+   * heavy `weight` on the same criterion redistributes score only among
+   * candidates that all cleared it — and pins that share of the aggregate near
+   * its ceiling, narrowing the range the search has left to move in. Gate it,
+   * then weight it low.
+   *
+   * @see docs/metric-preflight.md
+   */
+  gate?: number;
 }
 type JudgePromptBuilder = (args: {
   input: string;
@@ -218,4 +388,4 @@ declare function priceUsage(args: {
   pricing?: TokenPricing;
 }): RolloutUsage;
 //#endregion
-export { type Adapter, type BatchSampler, type BootstrapResult, type Budget, BudgetExhausted, type CachedScore, type Candidate, type Comparison, type ComparisonRun, type ComparisonSummary, type Deadline, type Demo, type DemoRenderer, type EvaluateArgs, type EvaluateBatchArgs, type EvaluateTracedArgs, type EvaluationBatch, type EvaluationCache, type EvaluationContext, type EvaluationEvent, type EvaluationPhase, type EvaluationSplit, type Evaluator, type Judge, type JudgeCriterion, type JudgePromptBuilder, type Optimizer, type OptimizerResult, type OptimizerTask, type RetryPolicy, type Rng, type RolloutUsage, type ScoreResult, type ScoredBatch, type TextModel, type TokenPricing, type UsageTotals, assertResumable, bootstrapDemos, buildJudgePrompt, candidateFingerprint, compare, componentNames, costExhausted, createBudget, createDeadline, createEvaluator, createJudge, createMemoryCache, formatDemos, mapWithConcurrency, measuredMean, parseDemos, parseProposedText, priceUsage, requireMeasuredMean, runFingerprint };
+export { type Adapter, type BatchSampler, type BootstrapResult, type Budget, BudgetExhausted, type CachedScore, type Candidate, type CandidateAccepted, type ChatMessage, type Comparison, type ComparisonRun, type ComparisonSummary, type Deadline, type Demo, type DemoRenderer, type EvaluateArgs, type EvaluateBatchArgs, type EvaluateTracedArgs, type EvaluationBatch, type EvaluationCache, type EvaluationContext, type EvaluationEvent, type EvaluationPhase, type EvaluationSplit, type Evaluator, type HarvestResult, type Judge, type JudgeCriterion, type JudgePromptBuilder, type Optimizer, type OptimizerEvent, type OptimizerResult, type OptimizerTask, type ReportableEvent, type Reporter, type RetryPolicy, type Rng, type Rollout, type RolloutUsage, type RunFinished, type RunWarning, type RunWarningCode, type ScoreResult, type ScoredBatch, type TextModel, type TokenPricing, type TrainingExample, type TrainingExampleRenderer, type UsageTotals, assertResumable, buildJudgePrompt, candidateFingerprint, compare, componentNames, costExhausted, createBudget, createDeadline, createEvaluator, createJudge, createMemoryCache, formatDemos, harvestFewShotExamples, harvestRollouts, isCandidateAccepted, isRunFinished, mapWithConcurrency, measuredMean, parseDemos, parseProposedText, priceUsage, requireMeasuredMean, resolveValidationSet, runFingerprint, seedScoreWarnings, toTrainingJsonl };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { a as EvaluationContext, c as RolloutUsage, d as UsageTotals, f as componentNames, i as EvaluationBatch, l as ScoreResult, n as Candidate, o as EvaluationPhase, r as EvaluateArgs, s as EvaluationSplit, t as Adapter, u as TextModel } from "./types-CWv4IQFF.mjs";
+import { C as componentNames, S as UsageTotals, _ as EvaluationPhase, a as RunFinished, b as ScoreResult, c as RunWarning, d as seedScoreWarnings, f as Adapter, g as EvaluationContext, h as EvaluationBatch, i as Reporter, l as RunWarningCode, m as EvaluateArgs, n as OptimizerEvent, o as isCandidateAccepted, p as Candidate, r as ReportableEvent, s as isRunFinished, t as CandidateAccepted, u as resolveValidationSet, v as EvaluationSplit, x as TextModel, y as RolloutUsage } from "./reporting-bq007_2z.mjs";
 import { n as EvaluationCache, r as createMemoryCache, t as CachedScore } from "./cache-CuSo0NJ8.mjs";
 import { t as Rng } from "./rng-BR5MOedA.mjs";
-import { a as formatDemos, i as bootstrapDemos, n as Demo, o as parseDemos, r as DemoRenderer, t as BootstrapResult } from "./demos-B0pVQjYC.mjs";
-import { a as EvaluateBatchArgs, c as Evaluator, d as costExhausted, f as createEvaluator, g as createBudget, h as Budget, i as BudgetExhausted, l as RetryPolicy, m as requireMeasuredMean, n as OptimizerResult, o as EvaluateTracedArgs, p as measuredMean, r as OptimizerTask, s as EvaluationEvent, t as Optimizer, u as ScoredBatch } from "./optimizer-DqCoth_w.mjs";
+import { a as harvestFewShotExamples, i as formatDemos, n as Demo, o as parseDemos, r as DemoRenderer, t as BootstrapResult } from "./demos-ASsSXYXA.mjs";
+import { a as EvaluateBatchArgs, c as Evaluator, d as costExhausted, f as createEvaluator, g as createBudget, h as Budget, i as BudgetExhausted, l as RetryPolicy, m as requireMeasuredMean, n as OptimizerResult, o as EvaluateTracedArgs, p as measuredMean, r as OptimizerTask, s as EvaluationEvent, t as Optimizer, u as ScoredBatch } from "./optimizer-Ds5mzYjz.mjs";
 import { t as BatchSampler } from "./sampling-DFo_7RNJ.mjs";
 //#region src/checkpoint.d.ts
 /**
@@ -46,6 +46,10 @@ interface ComparisonRun {
   bestScore: number;
   testScore?: number;
   metricCalls: number;
+  /** Rollouts this run got from the cache instead of paying for. */
+  cacheHits: number;
+  /** Calls to a proposal or reflection model, outside the metric budget. */
+  reflectionCalls: number;
   costUsd: number;
   stopReason: string;
 }
@@ -58,12 +62,33 @@ interface ComparisonSummary {
   maxScore: number;
   meanMetricCalls: number;
   meanCostUsd: number;
+  meanCacheHits: number;
+  meanReflectionCalls: number;
+  /**
+   * How many distinct values this entrant's score took across its seeds.
+   * 1 means every seed landed on the same number — the seed changed nothing
+   * about the outcome, whatever the search did internally with it.
+   */
+  distinctScores: number;
   /**
    * How often the winner's margin over this entrant would arise if the two
-   * were equally good and each seed's outcome were a coin flip. Absent for the
-   * winner itself.
+   * were equally good and each seed's outcome were a coin flip. Absent for
+   * the winner itself, and also absent when every seed produced the exact
+   * same margin: a sign-flip test over n seeds is answering a question about
+   * n independent trials, and identical margins mean the seed never actually
+   * put that to the test — there was one realization, repeated. Reporting a
+   * p-value there would state a precision (as fine as 2^-n) that the run
+   * never earned, so it is withheld rather than printed misleadingly small.
    */
   pValueVsWinner?: number;
+  /**
+   * `pValueVsWinner` after Holm-Bonferroni step-down across the other
+   * entrants in this same `compare()` call — the family the raw p-value
+   * would otherwise be read against in isolation. Absent wherever the raw
+   * p-value is: a withheld comparison has nothing to adjust, but it still
+   * occupies a slot in the family the other comparisons are corrected for.
+   */
+  pValueVsWinnerHolm?: number;
 }
 interface Comparison {
   /** Highest mean score. Read `pValueVsWinner` before believing it. */
@@ -85,7 +110,7 @@ interface Comparison {
  * seed is constructor config and every optimizer here is deterministic given
  * one — comparing two entrants at a single seed compares two anecdotes. It also
  * leaves the task where the caller builds it, which is the only place the
- * optimizer-specific parts of it (`reflect`, `cache`, `onEvent`) are known.
+ * optimizer-specific parts of it (`reflect`, `cache`, `reporters`) are known.
  */
 declare function compare<K extends string, Output = unknown>(args: {
   entrants: Record<string, (args: {
@@ -136,11 +161,156 @@ declare function createDeadline(args: {
   now?: () => number;
 }): Deadline;
 //#endregion
+//#region src/harvest.d.ts
+/**
+ * One rollout worth keeping: what went in, what the system produced, and how
+ * that output scored. Harvested, never written — the value of the pair is that
+ * the system actually produced the output and the metric actually rewarded it.
+ */
+interface Rollout<Datum = unknown, Output = unknown> {
+  input: Datum;
+  output: Output;
+  score: number;
+}
+interface HarvestResult<Datum, Output> {
+  rollouts: Rollout<Datum, Output>[];
+  /** Rollouts this cost. Harvesting is cheap, not free. */
+  metricCalls: number;
+  /**
+   * Tokens and dollars this cost. Harvesting runs on its own evaluator, so a
+   * caller that bounds spend has to fold these into its own totals.
+   */
+  usage: UsageTotals;
+  /** Instances run, including the ones the metric did not reward. */
+  attempted: number;
+}
+/**
+ * Run a candidate over data and keep the rollouts the metric rewarded.
+ *
+ * The library's one paid collection primitive, with two consumers: a few-shot
+ * block wants four of these, and a distillation set wants thousands. Both are
+ * the same pass — run the candidate, score it, keep what cleared the bar — so
+ * both share the budget, retry and transient-failure handling that pass needs.
+ *
+ * Which data to sweep is the caller's decision and the consequential one. A
+ * validation set is the wrong choice: it is the set that selected the candidate,
+ * so the rollouts it yields are enriched for the candidate's fit to those
+ * instances rather than to the task. Prefer the training set, or a pool held
+ * out of the run entirely.
+ */
+declare function harvestRollouts<Datum, Trajectory, Output, K extends string = string>(args: {
+  adapter: Adapter<Datum, Trajectory, Output, K>;
+  /** The candidate to run. Usually a run's winner, sometimes the seed. */
+  candidate: Candidate<K>;
+  data: readonly Datum[];
+  /**
+   * Score a rollout must reach to be kept. Unset keeps every rollout the
+   * metric rewarded at all, which is what MIPROv2's bootstrapper does without
+   * a `metric_threshold`: it keeps a trace on any truthy score and only
+   * compares against a number once one is configured.
+   *
+   * Demanding a perfect score instead is the right call for a boolean metric
+   * and the wrong one for a graded metric, where it throws away every rollout
+   * that was most of the way there — which on a hard task is all of them.
+   */
+  minScore?: number;
+  /** Rollouts to collect before stopping. Unset sweeps the whole pool. */
+  maxRollouts?: number;
+  /**
+   * Instances per rollout batch. Smaller batches stop closer to the moment
+   * enough rollouts exist, at the cost of less concurrency inside the adapter.
+   */
+  batchSize?: number;
+  /** Ceiling on rollouts run. Defaults to one pass over `data`. */
+  maxMetricCalls?: number;
+  /**
+   * Ceiling on dollars this pass may spend, checked between batches. Rollout
+   * counts are a poor proxy for spend, and a caller bounding dollars cannot
+   * bound this pass from outside: it runs on its own evaluator.
+   */
+  maxCostUsd?: number;
+  /** Shuffles `data` first, so rollouts are not all drawn from its head. */
+  rng?: Rng;
+  signal?: AbortSignal;
+}): Promise<HarvestResult<Datum, Output>>;
+//#endregion
+//#region src/distillation.d.ts
+/** A turn in a training example, in the shape trainers read. */
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+interface TrainingExample {
+  messages: ChatMessage[];
+}
+/**
+ * Turns one harvested rollout into the example to train on, or `null` to skip
+ * it. The callback exists because only the caller knows how to render a
+ * `Datum` — the library never sees inside one.
+ *
+ * It is also where the consequential decision lives: how much of the optimized
+ * candidate to leave in the input. Dropping it entirely moves the whole prompt
+ * into weights and gives up the ability to steer the model with text
+ * afterwards; keeping a short task statement distills away only the tokens the
+ * search accreted. See `docs/distillation.md` in this package.
+ */
+type TrainingExampleRenderer<Datum, Output> = (args: {
+  rollout: Rollout<Datum, Output>;
+  index: number;
+}) => TrainingExample | null;
+/**
+ * Serialize harvested rollouts as JSONL, one training example per line.
+ *
+ * The chat-messages shape rather than any one vendor's: it is what Axolotl,
+ * Together, Fireworks and the Hugging Face trainers all ingest, and the
+ * providers that read it outlive the ones that do not.
+ *
+ * Returns the text rather than writing it. Only `file-cache` touches the
+ * filesystem, and a caller uploading this straight to a provider should not
+ * have to round-trip it through a file to do so.
+ */
+declare function toTrainingJsonl<Datum, Output>(args: {
+  rollouts: readonly Rollout<Datum, Output>[];
+  render: TrainingExampleRenderer<Datum, Output>;
+}): string;
+//#endregion
 //#region src/judge.d.ts
 /** One thing the judge grades, and what a perfect answer looks like for it. */
 interface JudgeCriterion {
   name: string;
   description: string;
+  /**
+   * Share of the instance score this criterion carries, relative to the other
+   * criteria. Default 1, which is the unweighted mean.
+   *
+   * 0 removes a criterion from the aggregate, not from the search. It is still
+   * graded and still recorded in `objectiveScores`, which
+   * `paretoSelector({ frontier: "objective" })` and `"hybrid"` build their
+   * selection fronts from — so a candidate leading a zero-weight criterion
+   * still earns parent selection under those. Under the default instance
+   * frontier, 0 is enough. For a number that can never steer the search,
+   * compute it outside the judge.
+   */
+  weight?: number;
+  /**
+   * Grade, on the judge's own scale, that this criterion must reach for the
+   * instance to score at all. Below it the instance scores 0 whatever the
+   * other criteria said.
+   *
+   * A mean lets a search trade a hard requirement away: a candidate that tanks
+   * one non-negotiable criterion and aces three cosmetic ones outranks the
+   * incumbent that kept the rule. Anything a caller would not ship without is
+   * a gate rather than a term in the average.
+   *
+   * Enforce it once. A gate already makes the requirement non-negotiable, so a
+   * heavy `weight` on the same criterion redistributes score only among
+   * candidates that all cleared it — and pins that share of the aggregate near
+   * its ceiling, narrowing the range the search has left to move in. Gate it,
+   * then weight it low.
+   *
+   * @see docs/metric-preflight.md
+   */
+  gate?: number;
 }
 type JudgePromptBuilder = (args: {
   input: string;
@@ -218,4 +388,4 @@ declare function priceUsage(args: {
   pricing?: TokenPricing;
 }): RolloutUsage;
 //#endregion
-export { type Adapter, type BatchSampler, type BootstrapResult, type Budget, BudgetExhausted, type CachedScore, type Candidate, type Comparison, type ComparisonRun, type ComparisonSummary, type Deadline, type Demo, type DemoRenderer, type EvaluateArgs, type EvaluateBatchArgs, type EvaluateTracedArgs, type EvaluationBatch, type EvaluationCache, type EvaluationContext, type EvaluationEvent, type EvaluationPhase, type EvaluationSplit, type Evaluator, type Judge, type JudgeCriterion, type JudgePromptBuilder, type Optimizer, type OptimizerResult, type OptimizerTask, type RetryPolicy, type Rng, type RolloutUsage, type ScoreResult, type ScoredBatch, type TextModel, type TokenPricing, type UsageTotals, assertResumable, bootstrapDemos, buildJudgePrompt, candidateFingerprint, compare, componentNames, costExhausted, createBudget, createDeadline, createEvaluator, createJudge, createMemoryCache, formatDemos, mapWithConcurrency, measuredMean, parseDemos, parseProposedText, priceUsage, requireMeasuredMean, runFingerprint };
+export { type Adapter, type BatchSampler, type BootstrapResult, type Budget, BudgetExhausted, type CachedScore, type Candidate, type CandidateAccepted, type ChatMessage, type Comparison, type ComparisonRun, type ComparisonSummary, type Deadline, type Demo, type DemoRenderer, type EvaluateArgs, type EvaluateBatchArgs, type EvaluateTracedArgs, type EvaluationBatch, type EvaluationCache, type EvaluationContext, type EvaluationEvent, type EvaluationPhase, type EvaluationSplit, type Evaluator, type HarvestResult, type Judge, type JudgeCriterion, type JudgePromptBuilder, type Optimizer, type OptimizerEvent, type OptimizerResult, type OptimizerTask, type ReportableEvent, type Reporter, type RetryPolicy, type Rng, type Rollout, type RolloutUsage, type RunFinished, type RunWarning, type RunWarningCode, type ScoreResult, type ScoredBatch, type TextModel, type TokenPricing, type TrainingExample, type TrainingExampleRenderer, type UsageTotals, assertResumable, buildJudgePrompt, candidateFingerprint, compare, componentNames, costExhausted, createBudget, createDeadline, createEvaluator, createJudge, createMemoryCache, formatDemos, harvestFewShotExamples, harvestRollouts, isCandidateAccepted, isRunFinished, mapWithConcurrency, measuredMean, parseDemos, parseProposedText, priceUsage, requireMeasuredMean, resolveValidationSet, runFingerprint, seedScoreWarnings, toTrainingJsonl };