@tangle-network/agent-eval 0.192.0 → 0.193.0

package/dist/{promotion-policy-CfMNUro2.js.map → promotion-policy-Cy5OV8BV.js.map}

@@ -1 +1 @@
-{"version":3,"file":"promotion-policy-CfMNUro2.js","names":[],"sources":["../src/campaign/gates/promotion-policy.ts"],"sourcesContent":["/**\n * Build paired evidence for each objective and apply a promotion policy.\n * The default policy requires at least one gain and every regression floor to\n * clear. A floor can fail because a larger loss remains plausible; that does\n * not demonstrate an observed regression. Missing evidence stays unresolved.\n * Confidence intervals apply to each axis, without a multiplicity adjustment.\n *\n * Cost and latency remain aggregate constraints because GateContext does not\n * supply paired observations for them. Compose a budget gate when needed.\n */\n\nimport {\n  decidePairedPromotion,\n  type PairedDecisionMethod,\n  type PairedDecisionStatistic,\n  type PairedMcNemarEvidence,\n} from '../../paired-promotion-decision'\nimport type { Direction } from '../../pareto'\nimport {\n  DECISION_PAIRED_DELTA_STATISTIC,\n  type PairedBootstrapResult,\n  pairedBootstrap,\n} from '../../statistics'\nimport type { Gate, GateContext, GateDecision, GateResult, JudgeScore, Scenario } from '../types'\nimport { detectScale, pairHoldout } from './statistical-heldout'\n\n/** Where an objective's per-cell scalar comes from. `composite` reads the\n *  judge's composite; `dimension` reads a named per-dimension score. */\nexport type ObjectiveSource = { kind: 'composite' } | { kind: 'dimension'; dimension: string }\n\nexport interface PromotionObjective {\n  /** Stable label used in reports + `contributingGates`. */\n  name: string\n  source: ObjectiveSource\n  /** 'maximize' (quality dims) or 'minimize' (error/risk/length dims). Orients\n   *  the paired delta so a positive bootstrap always means \"candidate better\". */\n  direction: Direction\n  /** Declared binary support {0, binaryScale}, including zero-only observations.\n   *  Must be finite and positive; paired cell scores must be 0 or this scale.\n   *  Uses the risk-difference mean and rejects the 'median' statistic. */\n  binaryScale?: number\n  /** The good-direction paired-delta CI lower bound must EXCEED this to count\n   *  as a significant gain on this axis. Interpreted in the judge's native\n   *  scale. Default 0 (⇒ \"confidently better\"). */\n  gainThreshold?: number\n  /** A floor breach (regression) is declared when the good-direction CI lower\n   *  bound is below −floorTolerance, or when the exact small-sample test proves\n   *  a drop past it. Defaults to 0.05 times the declared binary scale, or\n   *  auto-scales off observed magnitudes (0.05 on [0,1], 5 on 0-100). */\n  floorTolerance?: number\n}\n\n/** Per-axis verdict from the shared paired decision rule.\n *  'regressed' includes uncertainty that prevents clearing the regression floor. */\nexport type AxisVerdict = 'improved' | 'regressed' | 'flat' | 'few_runs' | 'indeterminate'\n\nexport interface AxisEvidence {\n  name: string\n  source: ObjectiveSource\n  direction: Direction\n  /** Paired bootstrap on the GOOD-DIRECTION delta (oriented by `direction`):\n   *  a positive value means the candidate is better on this axis.\n   *\n   *  DIAGNOSTIC on a pass/fail axis: there the verdict is decided on Tango's\n   *  score interval instead, because a percentile bootstrap over a three-atom\n   *  delta lattice is not a valid interval at the nonzero margin `floorTolerance`\n   *  and `gainThreshold` create. `ci` carries the interval that decided. */\n  bootstrap: PairedBootstrapResult\n  /** Which paired statistic `bootstrap.low`/`.high` bracket. `'mean'` unless the\n   *  caller asked for the median — on a pass/fail axis the median and its whole\n   *  CI are pinned at 0 by tie domination and can see neither a gain nor a\n   *  regression. `bootstrap.median` still carries the median point estimate. */\n  bootstrapStatistic: 'median' | 'mean'\n  /** The interval the axis verdict was actually decided on, good-direction and\n   *  in the axis's native units. */\n  ci: { low: number; high: number }\n  /** Which estimator produced `ci`. */\n  decisionStatistic: PairedDecisionStatistic\n  /** McNemar's exact evidence on a pass/fail axis; null otherwise. */\n  mcnemar: PairedMcNemarEvidence | null\n  /** `ci` has zero width or non-finite bounds. It cannot establish a gain or\n   *  clear a regression floor, regardless of the point estimate. */\n  indeterminate: boolean\n  /** Paired observations contributing to this axis. */\n  n: number\n  minimumRequired: number\n  decisionMethod: PairedDecisionMethod\n  gainThreshold: number\n  floorTolerance: number\n  verdict: AxisVerdict\n}\n\nexport interface EvidenceVector {\n  /** One entry per objective — NOTHING averaged across axes. */\n  axes: AxisEvidence[]\n  /** Smallest paired n across axes that produced observations — the binding\n   *  evidence-sufficiency constraint. 0 when no axis produced observations. */\n  minN: number\n  /** Aggregate per-side cost from the gate context (a constraint input, not a\n   *  CI axis — see the module header). */\n  cost: { candidate: number; baseline: number }\n}\n\n/** A promotion strategy: a pure function from the evidence vector to a verdict.\n *  Many policies can run over the same `EvidenceVector` and disagree — that's\n *  the point (competing strategies, shared evidence). */\nexport type PromotionPolicy = (ev: EvidenceVector) => GateResult\n\nexport interface BuildEvidenceVectorOptions {\n  /** Minimum paired observations before an axis can claim significance; below\n   *  it the axis is `few_runs`. The exact small-sample test may require more\n   *  observations at the selected confidence. */\n  minProductiveRuns?: number\n  /** Confidence level for every axis bootstrap. Default 0.95. */\n  confidence?: number\n  /** Bootstrap resamples. Default 2000. */\n  resamples?: number\n  /** Fixed bootstrap seed for a deterministic, reproducible verdict. Default 1337. */\n  seed?: number\n  /** Paired statistic every axis CI is computed on. Default `'mean'` — see\n   *  {@link DECISION_PAIRED_DELTA_STATISTIC} for why the median is not. */\n  statistic?: 'mean' | 'median'\n}\n\n/**\n * The Evidence Bus. For each objective, pair candidate vs baseline by full\n * cellId and bootstrap a CI on the good-direction paired delta. Reuses the\n * exact `pairHoldout` + `pairedBootstrap` machinery the held-out gate uses, so\n * a single source of truth governs pairing granularity + scale handling.\n */\nexport function buildEvidenceVector<TArtifact, TScenario extends Scenario>(\n  ctx: GateContext<TArtifact, TScenario>,\n  objectives: PromotionObjective[],\n  opts: BuildEvidenceVectorOptions = {},\n): EvidenceVector {\n  if (objectives.length === 0) {\n    throw new Error('buildEvidenceVector: at least 1 objective required')\n  }\n  const confidence = opts.confidence ?? 0.95\n  const resamples = opts.resamples ?? 2000\n  const seed = opts.seed ?? 1337\n  const baseline = ctx.baselineJudgeScores ?? ctx.judgeScores\n  const scenarioIds = new Set(ctx.scenarios.map((s) => s.id))\n\n  const axes: AxisEvidence[] = []\n  for (const obj of objectives) {\n    let select: (s: JudgeScore) => number | undefined\n    if (obj.source.kind === 'composite') {\n      select = (s) => s.composite\n    } else {\n      const dim = obj.source.dimension\n      select = (s) => s.dimensions[dim]\n    }\n    const paired = pairHoldout(ctx.judgeScores, baseline, scenarioIds, select)\n    // Orient to the good direction: maximize ⇒ bootstrap (candidate − baseline);\n    // minimize ⇒ bootstrap (baseline − candidate) by swapping args, so a\n    // positive bootstrap always reads as \"candidate better on this axis\".\n    const before = obj.direction === 'maximize' ? paired.before : paired.after\n    const after = obj.direction === 'maximize' ? paired.after : paired.before\n    const n = paired.before.length\n    const binaryScale = obj.binaryScale\n    const floorTolerance =\n      obj.floorTolerance ?? 0.05 * (binaryScale ?? detectScale([...paired.before, ...paired.after]))\n    const gainThreshold = obj.gainThreshold ?? 0\n    // Axes are decided on the MEAN paired delta — which for a pass/fail axis is\n    // exactly the change in success rate. The median is structurally blind on\n    // the shapes eval data lands in: with most pairs tied its bootstrap CI\n    // collapses to [0,0] and the axis reads 'flat', hiding real gains AND real\n    // regressions — pass/fail axes on ANY encoding ({0,1} and the 0-100 one\n    // `detectScale` exists for), and low-cardinality axes even below half ties.\n    // Orthogonal to `pairedDeltaTest`'s own small-sample switch: that picks the\n    // TEST (bootstrap CI at n ≥ 20, exact sign test below), this picks the\n    // ESTIMATOR the test is applied to. Both are needed — an exact sign test on\n    // a tie-pinned median is still blind.\n    const bootstrapStatistic = opts.statistic ?? DECISION_PAIRED_DELTA_STATISTIC\n    // Both burdens of proof route through the ONE shared rule\n    // (`decidePairedPromotion`), so a pass/fail axis is judged on Tango's score\n    // interval — the only paired-binary construction valid at the nonzero\n    // margins `gainThreshold` / `floorTolerance` create — and a zero-width\n    // interval cannot buy a verdict in either direction.\n    const improvement = decidePairedPromotion(before, after, {\n      confidence,\n      resamples,\n      statistic: bootstrapStatistic,\n      seed,\n      threshold: gainThreshold,\n      minPairs: opts.minProductiveRuns,\n      binaryScale,\n    })\n    const regression = decidePairedPromotion(after, before, {\n      confidence,\n      resamples,\n      statistic: bootstrapStatistic,\n      seed,\n      threshold: floorTolerance,\n      minPairs: opts.minProductiveRuns,\n      binaryScale,\n    })\n    const bootstrap =\n      improvement.bootstrap ??\n      pairedBootstrap(before, after, {\n        confidence,\n        resamples,\n        statistic: bootstrapStatistic,\n        seed,\n      })\n    // A floor breach fires on EITHER burden of proof, because they cover\n    // different failures and the floor is the anti-Goodhart guard:\n    //   - `improvement.low < -floorTolerance` — the CREDIBLE WORST CASE exceeds\n    //     the tolerance. This is the contract `AxisEvidence.floorTolerance` and\n    //     `paretoPolicy`'s own reason string state, and it is the conservative\n    //     posture a safety axis needs: block unless the data can rule the\n    //     breach out, rather than waiting for the breach to be proven. Read off\n    //     the DECIDING interval, so a pass/fail axis is not screened by a\n    //     bootstrap that is pinned wherever ties dominate.\n    //   - `regression.promote` — a PROVEN drop past the tolerance. Adds the\n    //     small-sample path, where the decision is an exact sign test because\n    //     the bootstrap interval is descriptive only.\n    // A tied binary axis still has uncertainty about unseen discordant pairs.\n    // Its diagnostic bootstrap collapses to zero, so only the deciding score\n    // interval can establish that a regression stays within the declared floor.\n    const floorBreached = improvement.low < -floorTolerance || regression.promote\n    // Floor check precedes the gain check: a credible regression must never be\n    // masked as \"improved\". With the defaults (gainThreshold 0, positive floor)\n    // the regions are disjoint and order is moot, but a consumer who sets a\n    // negative gainThreshold (\"accept small dips\") could otherwise have a real\n    // floor breach classified as a gain — anti-Goodhart wins the tie.\n    const verdict: AxisVerdict = !improvement.sufficient\n      ? 'few_runs'\n      : improvement.indeterminate\n        ? 'indeterminate'\n        : floorBreached\n          ? 'regressed'\n          : improvement.promote\n            ? 'improved'\n            : 'flat'\n    axes.push({\n      name: obj.name,\n      source: obj.source,\n      direction: obj.direction,\n      bootstrap,\n      bootstrapStatistic,\n      ci: { low: improvement.low, high: improvement.high },\n      decisionStatistic: improvement.statistic,\n      mcnemar: improvement.mcnemar,\n      indeterminate: improvement.indeterminate,\n      n,\n      minimumRequired: improvement.minimumPairs,\n      decisionMethod: improvement.method,\n      gainThreshold,\n      floorTolerance,\n      verdict,\n    })\n  }\n  const ns = axes.map((a) => a.n).filter((n) => n > 0)\n  const minN = ns.length > 0 ? Math.min(...ns) : 0\n  return { axes, minN, cost: { candidate: ctx.cost.candidate, baseline: ctx.cost.baseline } }\n}\n\n/**\n * Require a supported gain and every configured regression floor to clear.\n * A failed floor holds the candidate, including when uncertainty permits a loss.\n * Missing or indeterminate evidence requires more work; no gain holds release.\n */\nexport const paretoPolicy: PromotionPolicy = (ev) => {\n  const contributingGates = ev.axes.map((ax) => ({\n    name: `objective:${ax.name}`,\n    status:\n      ax.verdict === 'regressed'\n        ? ('fail' as const)\n        : ax.verdict === 'few_runs' || ax.verdict === 'indeterminate'\n          ? ('not_evaluated' as const)\n          : ('pass' as const),\n    detail: {\n      direction: ax.direction,\n      source: ax.source,\n      verdict: ax.verdict,\n      n: ax.n,\n      deltaMedian: ax.bootstrap.median,\n      ciLow: ax.ci.low,\n      ciHigh: ax.ci.high,\n      decisionStatistic: ax.decisionStatistic,\n      decisionMethod: ax.decisionMethod,\n      mcnemar: ax.mcnemar,\n      indeterminate: ax.indeterminate,\n      bootstrapCiLow: ax.bootstrap.low,\n      bootstrapCiHigh: ax.bootstrap.high,\n      confidence: ax.bootstrap.confidence,\n      gainThreshold: ax.gainThreshold,\n      floorTolerance: ax.floorTolerance,\n    },\n  }))\n\n  const regressed = ev.axes.filter((a) => a.verdict === 'regressed')\n  const insufficient = ev.axes.filter(\n    (a) => a.verdict === 'few_runs' || a.verdict === 'indeterminate',\n  )\n  const improved = ev.axes.filter((a) => a.verdict === 'improved')\n\n  let decision: GateDecision\n  const reasons: string[] = []\n  if (regressed.length > 0) {\n    // A gain on another axis cannot excuse an unresolved regression floor.\n    decision = 'hold'\n    for (const a of regressed) {\n      reasons.push(\n        `objective '${a.name}' did not clear its regression floor -${a.floorTolerance}: good-direction CI [${a.ci.low.toFixed(3)}, ${a.ci.high.toFixed(3)}] (n=${a.n})`,\n      )\n    }\n  } else if (insufficient.length > 0) {\n    // An unresolved axis cannot establish either a gain or a safe floor.\n    decision = 'need_more_work'\n    for (const a of insufficient) {\n      reasons.push(\n        a.verdict === 'few_runs'\n          ? `objective '${a.name}' has only n=${a.n} paired runs — insufficient evidence to claim significance`\n          : `objective '${a.name}' has an indeterminate deciding CI [${a.ci.low}, ${a.ci.high}] — insufficient evidence to clear its regression floor (n=${a.n})`,\n      )\n    }\n  } else if (improved.length > 0) {\n    decision = 'ship'\n    reasons.push(\n      `Supported objective gain: ${improved\n        .map(\n          (a) =>\n            `'${a.name}' +${a.ci.low > 0 ? a.ci.low.toFixed(3) : a.bootstrap.mean.toFixed(3)} (CI.low ${a.ci.low.toFixed(3)})`,\n        )\n        .join(', ')}; every regression floor cleared`,\n    )\n  } else {\n    // Every floor cleared, but no objective demonstrated a significant gain.\n    decision = 'hold'\n    reasons.push(\n      'no Pareto improvement: no objective shows a significant gain; every regression floor cleared',\n    )\n  }\n\n  // `delta` surfaces the composite axis if present, else the first axis — a\n  // single convenience scalar; the vector lives in `contributingGates`.\n  const composite = ev.axes.find((a) => a.source.kind === 'composite') ?? ev.axes[0]\n  return { decision, reasons, contributingGates, delta: composite?.bootstrap.median }\n}\n\nexport interface ParetoSignificanceGateOptions extends BuildEvidenceVectorOptions {\n  /** The objective vector. Every axis is both a gain source and a safety floor. */\n  objectives: PromotionObjective[]\n  /** Strategy applied to the evidence vector. Default `paretoPolicy`. Override\n   *  to run a stricter/looser strategy over the SAME bus (competing policies). */\n  policy?: PromotionPolicy\n  /** Override the gate name in reports. */\n  name?: string\n}\n\n/**\n * Wrap the bus + a policy as a `Gate`. Plugs into the existing\n * `runImprovementLoop({ gate })` slot and composes via `composeGate`; default\n * loop behavior is unchanged because consumers opt in by passing this gate.\n */\nexport function paretoSignificanceGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(\n  options: ParetoSignificanceGateOptions,\n): Gate<TArtifact, TScenario> {\n  if (options.objectives.length === 0) {\n    throw new Error('paretoSignificanceGate: at least 1 objective required')\n  }\n  const policy = options.policy ?? paretoPolicy\n  return {\n    name: options.name ?? 'paretoSignificanceGate',\n    async decide(ctx: GateContext<TArtifact, TScenario>): Promise<GateResult> {\n      const ev = buildEvidenceVector(ctx, options.objectives, options)\n      return policy(ev)\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"promotion-policy-Cy5OV8BV.js","names":[],"sources":["../src/campaign/gates/promotion-policy.ts"],"sourcesContent":["/**\n * Build paired evidence for each objective and apply a promotion policy.\n * The default policy requires at least one gain and every regression floor to\n * clear. A floor can fail because a larger loss remains plausible; that does\n * not demonstrate an observed regression. Missing evidence stays unresolved.\n * Confidence intervals apply to each axis, without a multiplicity adjustment.\n *\n * Cost and latency remain aggregate constraints because GateContext does not\n * supply paired observations for them. Compose a budget gate when needed.\n */\n\nimport {\n  decidePairedPromotion,\n  type PairedDecisionMethod,\n  type PairedDecisionStatistic,\n  type PairedMcNemarEvidence,\n} from '../../paired-promotion-decision'\nimport type { Direction } from '../../pareto'\nimport {\n  DECISION_PAIRED_DELTA_STATISTIC,\n  type PairedBootstrapResult,\n  pairedBootstrap,\n} from '../../statistics'\nimport type { Gate, GateContext, GateDecision, GateResult, JudgeScore, Scenario } from '../types'\nimport { detectScale, pairHoldout } from './statistical-heldout'\n\n/** Where an objective's per-cell scalar comes from. `composite` reads the\n *  judge's composite; `dimension` reads a named per-dimension score. */\nexport type ObjectiveSource = { kind: 'composite' } | { kind: 'dimension'; dimension: string }\n\nexport interface PromotionObjective {\n  /** Stable label used in reports + `contributingGates`. */\n  name: string\n  source: ObjectiveSource\n  /** 'maximize' (quality dims) or 'minimize' (error/risk/length dims). Orients\n   *  the paired delta so a positive bootstrap always means \"candidate better\". */\n  direction: Direction\n  /** Declared binary support {0, binaryScale}, including zero-only observations.\n   *  Must be finite and positive; paired cell scores must be 0 or this scale.\n   *  Uses the risk-difference mean and rejects the 'median' statistic. */\n  binaryScale?: number\n  /** The good-direction paired-delta CI lower bound must EXCEED this to count\n   *  as a significant gain on this axis. Interpreted in the judge's native\n   *  scale. Default 0 (⇒ \"confidently better\"). */\n  gainThreshold?: number\n  /** A floor breach (regression) is declared when the good-direction CI lower\n   *  bound is below −floorTolerance, or when the exact small-sample test proves\n   *  a drop past it. Defaults to 0.05 times the declared binary scale, or\n   *  auto-scales off observed magnitudes (0.05 on [0,1], 5 on 0-100). */\n  floorTolerance?: number\n}\n\n/** Per-axis verdict from the shared paired decision rule.\n *  'regressed' includes uncertainty that prevents clearing the regression floor. */\nexport type AxisVerdict = 'improved' | 'regressed' | 'flat' | 'few_runs' | 'indeterminate'\n\nexport interface AxisEvidence {\n  name: string\n  source: ObjectiveSource\n  direction: Direction\n  /** Paired bootstrap on the GOOD-DIRECTION delta (oriented by `direction`):\n   *  a positive value means the candidate is better on this axis.\n   *\n   *  DIAGNOSTIC on a pass/fail axis: there the verdict is decided on Tango's\n   *  score interval instead, because a percentile bootstrap over a three-atom\n   *  delta lattice is not a valid interval at the nonzero margin `floorTolerance`\n   *  and `gainThreshold` create. `ci` carries the interval that decided. */\n  bootstrap: PairedBootstrapResult\n  /** Which paired statistic `bootstrap.low`/`.high` bracket. `'mean'` unless the\n   *  caller asked for the median — on a pass/fail axis the median and its whole\n   *  CI are pinned at 0 by tie domination and can see neither a gain nor a\n   *  regression. `bootstrap.median` still carries the median point estimate. */\n  bootstrapStatistic: 'median' | 'mean'\n  /** The interval the axis verdict was actually decided on, good-direction and\n   *  in the axis's native units. */\n  ci: { low: number; high: number }\n  /** Which estimator produced `ci`. */\n  decisionStatistic: PairedDecisionStatistic\n  /** McNemar's exact evidence on a pass/fail axis; null otherwise. */\n  mcnemar: PairedMcNemarEvidence | null\n  /** `ci` has zero width or non-finite bounds. It cannot establish a gain or\n   *  clear a regression floor, regardless of the point estimate. */\n  indeterminate: boolean\n  /** Paired observations contributing to this axis. */\n  n: number\n  minimumRequired: number\n  decisionMethod: PairedDecisionMethod\n  gainThreshold: number\n  floorTolerance: number\n  verdict: AxisVerdict\n}\n\nexport interface EvidenceVector {\n  /** One entry per objective — NOTHING averaged across axes. */\n  axes: AxisEvidence[]\n  /** Smallest paired n across axes that produced observations — the binding\n   *  evidence-sufficiency constraint. 0 when no axis produced observations. */\n  minN: number\n  /** Aggregate per-side cost from the gate context (a constraint input, not a\n   *  CI axis — see the module header). */\n  cost: { candidate: number; baseline: number }\n}\n\n/** A promotion strategy: a pure function from the evidence vector to a verdict.\n *  Many policies can run over the same `EvidenceVector` and disagree — that's\n *  the point (competing strategies, shared evidence). */\nexport type PromotionPolicy = (ev: EvidenceVector) => GateResult\n\nexport interface BuildEvidenceVectorOptions {\n  /** Minimum paired observations before an axis can claim significance; below\n   *  it the axis is `few_runs`. The exact small-sample test may require more\n   *  observations at the selected confidence. */\n  minProductiveRuns?: number\n  /** Confidence level for every axis bootstrap. Default 0.95. */\n  confidence?: number\n  /** Bootstrap resamples. Default 2000. */\n  resamples?: number\n  /** Fixed bootstrap seed for a deterministic, reproducible verdict. Default 1337. */\n  seed?: number\n  /** Paired statistic every axis CI is computed on. Default `'mean'` — see\n   *  {@link DECISION_PAIRED_DELTA_STATISTIC} for why the median is not. */\n  statistic?: 'mean' | 'median'\n}\n\n/**\n * The Evidence Bus. For each objective, pair candidate vs baseline by full\n * cellId and bootstrap a CI on the good-direction paired delta. Reuses the\n * exact `pairHoldout` + `pairedBootstrap` machinery the held-out gate uses, so\n * a single source of truth governs pairing granularity + scale handling.\n */\nexport function buildEvidenceVector<TArtifact, TScenario extends Scenario>(\n  ctx: GateContext<TArtifact, TScenario>,\n  objectives: PromotionObjective[],\n  opts: BuildEvidenceVectorOptions = {},\n): EvidenceVector {\n  if (objectives.length === 0) {\n    throw new Error('buildEvidenceVector: at least 1 objective required')\n  }\n  const confidence = opts.confidence ?? 0.95\n  const resamples = opts.resamples ?? 2000\n  const seed = opts.seed ?? 1337\n  const baseline = ctx.baselineJudgeScores ?? ctx.judgeScores\n  const scenarioIds = new Set(ctx.scenarios.map((s) => s.id))\n\n  const axes: AxisEvidence[] = []\n  for (const obj of objectives) {\n    let select: (s: JudgeScore) => number | undefined\n    if (obj.source.kind === 'composite') {\n      select = (s) => s.composite\n    } else {\n      const dim = obj.source.dimension\n      select = (s) => s.dimensions[dim]\n    }\n    const paired = pairHoldout(ctx.judgeScores, baseline, scenarioIds, select)\n    // Orient to the good direction: maximize ⇒ bootstrap (candidate − baseline);\n    // minimize ⇒ bootstrap (baseline − candidate) by swapping args, so a\n    // positive bootstrap always reads as \"candidate better on this axis\".\n    const before = obj.direction === 'maximize' ? paired.before : paired.after\n    const after = obj.direction === 'maximize' ? paired.after : paired.before\n    const n = paired.before.length\n    const binaryScale = obj.binaryScale\n    const floorTolerance =\n      obj.floorTolerance ?? 0.05 * (binaryScale ?? detectScale([...paired.before, ...paired.after]))\n    const gainThreshold = obj.gainThreshold ?? 0\n    // Axes are decided on the MEAN paired delta — which for a pass/fail axis is\n    // exactly the change in success rate. The median is structurally blind on\n    // the shapes eval data lands in: with most pairs tied its bootstrap CI\n    // collapses to [0,0] and the axis reads 'flat', hiding real gains AND real\n    // regressions — pass/fail axes on ANY encoding ({0,1} and the 0-100 one\n    // `detectScale` exists for), and low-cardinality axes even below half ties.\n    // Orthogonal to `pairedDeltaTest`'s own small-sample switch: that picks the\n    // TEST (bootstrap CI at n ≥ 20, exact sign test below), this picks the\n    // ESTIMATOR the test is applied to. Both are needed — an exact sign test on\n    // a tie-pinned median is still blind.\n    const bootstrapStatistic = opts.statistic ?? DECISION_PAIRED_DELTA_STATISTIC\n    // Both burdens of proof route through the ONE shared rule\n    // (`decidePairedPromotion`), so a pass/fail axis is judged on Tango's score\n    // interval — the only paired-binary construction valid at the nonzero\n    // margins `gainThreshold` / `floorTolerance` create — and a zero-width\n    // interval cannot buy a verdict in either direction.\n    const improvement = decidePairedPromotion(before, after, {\n      confidence,\n      resamples,\n      statistic: bootstrapStatistic,\n      seed,\n      threshold: gainThreshold,\n      minPairs: opts.minProductiveRuns,\n      binaryScale,\n    })\n    const regression = decidePairedPromotion(after, before, {\n      confidence,\n      resamples,\n      statistic: bootstrapStatistic,\n      seed,\n      threshold: floorTolerance,\n      minPairs: opts.minProductiveRuns,\n      binaryScale,\n    })\n    const bootstrap =\n      improvement.bootstrap ??\n      pairedBootstrap(before, after, {\n        confidence,\n        resamples,\n        statistic: bootstrapStatistic,\n        seed,\n      })\n    // A floor breach fires on EITHER burden of proof, because they cover\n    // different failures and the floor is the anti-Goodhart guard:\n    //   - `improvement.low < -floorTolerance` — the CREDIBLE WORST CASE exceeds\n    //     the tolerance. This is the contract `AxisEvidence.floorTolerance` and\n    //     `paretoPolicy`'s own reason string state, and it is the conservative\n    //     posture a safety axis needs: block unless the data can rule the\n    //     breach out, rather than waiting for the breach to be proven. Read off\n    //     the DECIDING interval, so a pass/fail axis is not screened by a\n    //     bootstrap that is pinned wherever ties dominate.\n    //   - `regression.promote` — a PROVEN drop past the tolerance. Adds the\n    //     small-sample path, where the decision is an exact sign test because\n    //     the bootstrap interval is descriptive only.\n    // A tied binary axis still has uncertainty about unseen discordant pairs.\n    // Its diagnostic bootstrap collapses to zero, so only the deciding score\n    // interval can establish that a regression stays within the declared floor.\n    const floorBreached = improvement.low < -floorTolerance || regression.promote\n    // Floor check precedes the gain check: a credible regression must never be\n    // masked as \"improved\". With the defaults (gainThreshold 0, positive floor)\n    // the regions are disjoint and order is moot, but a consumer who sets a\n    // negative gainThreshold (\"accept small dips\") could otherwise have a real\n    // floor breach classified as a gain — anti-Goodhart wins the tie.\n    const verdict: AxisVerdict = !improvement.sufficient\n      ? 'few_runs'\n      : improvement.indeterminate\n        ? 'indeterminate'\n        : floorBreached\n          ? 'regressed'\n          : improvement.promote\n            ? 'improved'\n            : 'flat'\n    axes.push({\n      name: obj.name,\n      source: obj.source,\n      direction: obj.direction,\n      bootstrap,\n      bootstrapStatistic,\n      ci: { low: improvement.low, high: improvement.high },\n      decisionStatistic: improvement.statistic,\n      mcnemar: improvement.mcnemar,\n      indeterminate: improvement.indeterminate,\n      n,\n      minimumRequired: improvement.minimumPairs,\n      decisionMethod: improvement.method,\n      gainThreshold,\n      floorTolerance,\n      verdict,\n    })\n  }\n  const ns = axes.map((a) => a.n).filter((n) => n > 0)\n  const minN = ns.length > 0 ? Math.min(...ns) : 0\n  return { axes, minN, cost: { candidate: ctx.cost.candidate, baseline: ctx.cost.baseline } }\n}\n\n/**\n * Require a supported gain and every configured regression floor to clear.\n * A failed floor holds the candidate, including when uncertainty permits a loss.\n * Missing or indeterminate evidence requires more work; no gain holds release.\n */\nexport const paretoPolicy: PromotionPolicy = (ev) => {\n  const contributingGates = ev.axes.map((ax) => ({\n    name: `objective:${ax.name}`,\n    status:\n      ax.verdict === 'regressed'\n        ? ('fail' as const)\n        : ax.verdict === 'few_runs' || ax.verdict === 'indeterminate'\n          ? ('not_evaluated' as const)\n          : ('pass' as const),\n    detail: {\n      direction: ax.direction,\n      source: ax.source,\n      verdict: ax.verdict,\n      n: ax.n,\n      deltaMedian: ax.bootstrap.median,\n      ciLow: ax.ci.low,\n      ciHigh: ax.ci.high,\n      decisionStatistic: ax.decisionStatistic,\n      decisionMethod: ax.decisionMethod,\n      mcnemar: ax.mcnemar,\n      indeterminate: ax.indeterminate,\n      bootstrapCiLow: ax.bootstrap.low,\n      bootstrapCiHigh: ax.bootstrap.high,\n      confidence: ax.bootstrap.confidence,\n      gainThreshold: ax.gainThreshold,\n      floorTolerance: ax.floorTolerance,\n    },\n  }))\n\n  const regressed = ev.axes.filter((a) => a.verdict === 'regressed')\n  const insufficient = ev.axes.filter(\n    (a) => a.verdict === 'few_runs' || a.verdict === 'indeterminate',\n  )\n  const improved = ev.axes.filter((a) => a.verdict === 'improved')\n\n  let decision: GateDecision\n  const reasons: string[] = []\n  if (regressed.length > 0) {\n    // A gain on another axis cannot excuse an unresolved regression floor.\n    decision = 'hold'\n    for (const a of regressed) {\n      reasons.push(\n        `objective '${a.name}' did not clear its regression floor -${a.floorTolerance}: good-direction CI [${a.ci.low.toFixed(3)}, ${a.ci.high.toFixed(3)}] (n=${a.n})`,\n      )\n    }\n  } else if (insufficient.length > 0) {\n    // An unresolved axis cannot establish either a gain or a safe floor.\n    decision = 'need_more_work'\n    for (const a of insufficient) {\n      reasons.push(\n        a.verdict === 'few_runs'\n          ? `objective '${a.name}' has only n=${a.n} paired runs — insufficient evidence to claim significance`\n          : `objective '${a.name}' has an indeterminate deciding CI [${a.ci.low}, ${a.ci.high}] — insufficient evidence to clear its regression floor (n=${a.n})`,\n      )\n    }\n  } else if (improved.length > 0) {\n    decision = 'ship'\n    reasons.push(\n      `Supported objective gain: ${improved\n        .map(\n          (a) =>\n            `'${a.name}' +${a.ci.low > 0 ? a.ci.low.toFixed(3) : a.bootstrap.mean.toFixed(3)} (CI.low ${a.ci.low.toFixed(3)})`,\n        )\n        .join(', ')}; every regression floor cleared`,\n    )\n  } else {\n    // Every floor cleared, but no objective demonstrated a significant gain.\n    decision = 'hold'\n    reasons.push(\n      'no Pareto improvement: no objective shows a significant gain; every regression floor cleared',\n    )\n  }\n\n  // `delta` surfaces the composite axis if present, else the first axis — a\n  // single convenience scalar; the vector lives in `contributingGates`.\n  const composite = ev.axes.find((a) => a.source.kind === 'composite') ?? ev.axes[0]\n  return { decision, reasons, contributingGates, delta: composite?.bootstrap.median }\n}\n\nexport interface ParetoSignificanceGateOptions extends BuildEvidenceVectorOptions {\n  /** The objective vector. Every axis is both a gain source and a safety floor. */\n  objectives: PromotionObjective[]\n  /** Strategy applied to the evidence vector. Default `paretoPolicy`. Override\n   *  to run a stricter/looser strategy over the SAME bus (competing policies). */\n  policy?: PromotionPolicy\n  /** Override the gate name in reports. */\n  name?: string\n}\n\n/**\n * Wrap the bus + a policy as a `Gate`. Plugs into the existing\n * `runImprovementLoop({ gate })` slot and composes via `composeGate`; default\n * loop behavior is unchanged because consumers opt in by passing this gate.\n */\nexport function paretoSignificanceGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(\n  options: ParetoSignificanceGateOptions,\n): Gate<TArtifact, TScenario> {\n  if (options.objectives.length === 0) {\n    throw new Error('paretoSignificanceGate: at least 1 objective required')\n  }\n  const policy = options.policy ?? paretoPolicy\n  return {\n    name: options.name ?? 'paretoSignificanceGate',\n    async decide(ctx: GateContext<TArtifact, TScenario>): Promise<GateResult> {\n      const ev = buildEvidenceVector(ctx, options.objectives, options)\n      return policy(ev)\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/rl.d.ts

@@ -1,10 +1,10 @@
 import { v as Span } from "./schema-2g7trUwH.js";
 import { a as RunRecord, c as RunSplitTag } from "./run-record-DF-fuu31.js";
 import { a as PairedPromotionDecision, d as PairedBootstrapResult } from "./paired-promotion-decision-DPKz8ZnF.js";
-import { a as CampaignResult } from "./types-C1CAD70_.js";
 import { s as TraceStore } from "./store-C4avFjIi.js";
 import { a as MintedRolloutLine, t as ChatMessage, y as RolloutSplit } from "./schema-B5LtYvn9.js";
 import { t as MintRolloutOptions } from "./mint-C9Lojt1V.js";
+import { a as CampaignResult } from "./types-BWwRXofp.js";
 import { s as VerificationReport } from "./multi-layer-verifier-BUaQ4C17.js";
 import { a as detectRewardHacking, c as VerifiableRewardSource, d as filterDeterministicallyRewarded, i as RewardHackingSignal, l as extractVerifiableReward, n as RewardHackingFinding, o as VerifiableReward, r as RewardHackingReport, s as VerifiableRewardExtractionOptions, t as DetectRewardHackingInput, u as extractVerifiableRewardsFromRecords } from "./reward-hacking-Cyk-QHk9.js";
 import { i as InMemoryOutcomeStore, n as FileSystemOutcomeStore, o as OutcomeStore, r as FileSystemOutcomeStoreOptions, t as DeploymentOutcome } from "./outcome-store-CNt4iZ67.js";

package/dist/rl.js

@@ -4,7 +4,7 @@ import { a as medianInPlace } from "./internal-BMFSR8Ns.js";
 import { t as mulberry32 } from "./random-Dn5fPWkt.js";
 import { l as wilcoxonSignedRank } from "./paired-arms-JSDcs2zx.js";
 import { r as pairedBootstrap } from "./paired-tests-C8iCsioC.js";
-import { t as decidePairedPromotion } from "./paired-promotion-decision-6cn3bLc3.js";
+import { t as decidePairedPromotion } from "./paired-promotion-decision-DTKl6-G8.js";
 import { r as observedSplitScore, s as trainingScore } from "./reward-nw2xZGZG.js";
 import { c as runTaskScore } from "./run-record-BRlM99rX.js";
 import { n as campaignCellToRunRecord } from "./run-record-tNnlQIrD.js";

package/dist/{search-ledger-Ck7tok0h.js → search-ledger-CJiAEU3j.js}

@@ -108,6 +108,10 @@ var SearchState = class {
 	operations = /* @__PURE__ */ new Map();
 	selectedNodeId = null;
 	claimUsedUsd = 0;
+	/** Nodes ever decided `finalist`. */
+	finalists = /* @__PURE__ */ new Set();
+	/** Claim cells allocated. Once one exists, the finalists are fixed. */
+	claimCells = 0;
 	audit;
 	constructor(searchId) {
 		this.searchId = searchId;
@@ -255,6 +259,7 @@ var SearchState = class {
 	}
 	startOperation(event) {
 		if (this.operations.has(event.operationId)) throw integrity(`operation ${event.operationId} was started twice`);
+		this.assertSearching(`operation ${event.operationId}`);
 		this.admit(event.reservation, false, `operation ${event.operationId}`);
 		this.operations.set(event.operationId, {
 			operationId: event.operationId,
@@ -262,7 +267,7 @@ var SearchState = class {
 			reservation: event.reservation,
 			recorded: false,
 			outcome: null,
-			artifacts: [],
+			artifacts: event.artifacts,
 			spentUsd: 0
 		});
 		this.audit.operations.started += 1;
@@ -281,7 +286,7 @@ var SearchState = class {
 		if (operation.reservation) this.audit.spend.overspendUsd += Math.max(0, cost.usd - reserved);
 		operation.recorded = true;
 		operation.outcome = event.outcome.status;
-		operation.artifacts = event.artifacts;
+		operation.artifacts = [...operation.artifacts, ...event.artifacts];
 		operation.spentUsd = cost.usd;
 		this.audit.operations.recorded += 1;
 		this.audit.operations.open -= 1;
@@ -290,6 +295,7 @@ var SearchState = class {
 		const expected = searchNodeId(this.searchId, event.artifactDigest);
 		if (event.nodeId !== expected) throw integrity(`node ${event.nodeId} does not match its artifact digest (expected ${expected})`);
 		if (this.nodes.has(event.nodeId)) throw integrity(`node ${event.nodeId} was registered twice; a re-proposal is a second edge into it`);
+		this.assertSearching(`node ${event.nodeId}`);
 		assertUnique(event.surfaces.map((surface) => surface.surfaceId), "surfaceId", event.eventId);
 		const maxNodes = this.header.budget.maxNodes;
 		if (maxNodes !== null && this.nodes.size + 1 > maxNodes) throw integrity(`node ${event.nodeId} exceeds the search's maxNodes ${maxNodes}`);
@@ -325,6 +331,7 @@ var SearchState = class {
 		if (this.edges.has(event.edgeId)) throw integrity(`edge ${event.edgeId} was recorded twice`);
 		const child = this.nodes.get(event.childNodeId);
 		if (!child) throw integrity(`edge ${event.edgeId} names unregistered child ${event.childNodeId}`);
+		this.assertSearching(`edge ${event.edgeId}`);
 		if (event.label.length > MAX_LABEL_CHARS) throw integrity(`edge ${event.edgeId} label exceeds ${MAX_LABEL_CHARS} characters`);
 		if (event.diffs.length !== event.parents.length) throw integrity(`edge ${event.edgeId} needs one diff per parent`);
 		assertUnique(event.parents.map((parent) => canonicalString(parent)), "parent", event.eventId);
@@ -348,6 +355,7 @@ var SearchState = class {
 			if (!record) throw integrity(`edge ${event.edgeId} names unregistered parent ${parent.nodeId}`);
 			if (record.ordinal >= child.ordinal) throw integrity(`edge ${event.edgeId}: parent ${parent.nodeId} registered after child ${child.event.nodeId}`);
 			if (record.edgeIds.length === 0) throw integrity(`edge ${event.edgeId}: parent ${parent.nodeId} has no edge of its own yet`);
+			if (record.decisions.at(-1)?.decision.status === "invalid") throw integrity(`edge ${event.edgeId}: parent ${parent.nodeId} was decided invalid, and an invalid node never becomes a parent`);
 			inSearch.push(record);
 		}
 		if (child.edgeIds.length === 0) {
@@ -381,6 +389,7 @@ var SearchState = class {
 		if (task.unitId !== event.unitId) throw integrity(`cell ${event.cellId}: task ${event.taskId} samples unit ${task.unitId}`);
 		assertStageSplit(event.cellId, event.stage, event.split, node.ordinal === 0);
 		if (event.split === "test" && node.ordinal !== 0 && !node.finalist) throw integrity(`cell ${event.cellId}: the test split is sealed; only the root and finalists run on it`);
+		if (event.stage !== "claim") this.assertSearching(`cell ${event.cellId}`);
 		const maxCells = this.header.budget.maxCells;
 		if (maxCells !== null && this.audit.cells.allocated + 1 > maxCells) throw integrity(`cell ${event.cellId} exceeds the search's maxCells ${maxCells}`);
 		this.admit(event.reservation, event.stage === "claim", `cell ${event.cellId}`);
@@ -411,7 +420,10 @@ var SearchState = class {
 		this.audit.cells.allocated += 1;
 		this.audit.cells.open += 1;
 		this.audit.spend.openReservationUsd += event.reservation?.usd ?? 0;
-		if (event.stage === "claim") this.claimUsedUsd += event.reservation?.usd ?? 0;
+		if (event.stage === "claim") {
+			this.claimUsedUsd += event.reservation?.usd ?? 0;
+			this.claimCells += 1;
+		}
 	}
 	settleCell(event, index) {
 		const cell = this.cells.get(event.cellId);
@@ -489,6 +501,12 @@ var SearchState = class {
 		if (!node) throw integrity(`decision ${event.eventId} names unregistered node ${event.nodeId}`);
 		if (node.edgeIds.length === 0) throw integrity(`decision ${event.eventId}: node ${event.nodeId} has no edge yet`);
 		const status = event.decision.status;
+		if (status === "finalist" && !this.finalists.has(event.nodeId)) {
+			if (node.ordinal === 0) throw integrity(`the root ${event.nodeId} is the claim's control and cannot be a finalist`);
+			if (this.claimCells > 0) throw integrity(`node ${event.nodeId} was decided finalist after a claim cell ran; the finalists are fixed before the test`);
+			if (this.finalists.size >= 3) throw integrity(`node ${event.nodeId} would be finalist ${this.finalists.size + 1}; at most 3 are allowed`);
+			this.finalists.add(event.nodeId);
+		}
 		if (status === "selected") {
 			if (this.selectedNodeId !== null && this.selectedNodeId !== event.nodeId) throw integrity(`node ${event.nodeId} was selected while ${this.selectedNodeId} is still selected`);
 			if (node.scoredCells === 0) throw integrity(`node ${event.nodeId} cannot be selected without a scored cell`);
@@ -520,20 +538,40 @@ var SearchState = class {
 		this.audit.spend.openReservationUsd = 0;
 	}
 	checkClaim(claim) {
-		if (claim.finalists.length > 3) throw integrity(`the claim names ${claim.finalists.length} finalists; at most 3 are allowed`);
-		assertUnique(claim.finalists.map((finalist) => finalist.nodeId), "claim finalist", "search-closed");
-		for (const finalist of claim.finalists) if (!this.nodes.get(finalist.nodeId)?.finalist) throw integrity(`claim finalist ${finalist.nodeId} was never decided finalist`);
-		if (claim.selected !== this.selectedNodeId) throw integrity(`the claim selects ${claim.selected ?? "nothing"} but the selected node is ${this.selectedNodeId ?? "none"}`);
+		const named = claim.finalists.map((finalist) => finalist.nodeId);
+		assertUnique(named, "claim finalist", "search-closed");
+		for (const nodeId of named) if (!this.finalists.has(nodeId)) throw integrity(`claim finalist ${nodeId} was never decided finalist`);
+		for (const nodeId of this.finalists) if (!named.includes(nodeId)) throw integrity(`finalist ${nodeId} is missing from the claim`);
 		const root = this.nodeOrder[0] ?? null;
+		const perFinalist = 1 - (1 - claim.confidence) / Math.max(1, named.length);
+		for (const finalist of claim.finalists) {
+			const { estimate, test } = finalist;
+			if (estimate && (estimate.against !== root || estimate.split !== "test")) throw integrity(`claim finalist ${finalist.nodeId} is estimated against something other than the root on test`);
+			if (test && Math.abs(test.confidence - perFinalist) > 1e-12) throw integrity(`claim finalist ${finalist.nodeId} is tested at confidence ${test.confidence}; ${named.length} finalists at family-wise ${claim.confidence} need ${perFinalist}`);
+			if (finalist.promote && test === null) throw integrity(`claim finalist ${finalist.nodeId} is promoted without a test`);
+		}
+		if (claim.selected !== this.selectedNodeId) throw integrity(`the claim selects ${claim.selected ?? "nothing"} but the selected node is ${this.selectedNodeId ?? "none"}`);
 		if (claim.decision === "ship") {
 			const shipped = claim.finalists.find((finalist) => finalist.nodeId === claim.selected);
 			if (claim.selected === null || claim.selected === root || !shipped?.promote) throw integrity("a ship claim must select a finalist that the paired test promoted");
 			if (!this.header.splits.heldOutUnits) throw integrity("a ship claim needs test units held out from train and selection");
+			if ("unknown" in this.header.objective.judge) throw integrity("a ship claim needs a pinned judge; with an unknown judge a resumed search could mix two judges' verdicts");
+			const testUnits = new Set(this.header.splits.test.tasks.map((task) => task.unitId));
+			for (const nodeId of [root, claim.selected]) {
+				const scored = new Set(this.readScoredCells(nodeId, "test").map((cell) => cell.unitId));
+				const missing = [...testUnits].filter((unit) => !scored.has(unit));
+				if (missing.length > 0) throw integrity(`a ship claim needs every test unit scored by the root and the finalist; ${nodeId} has none on ${missing.join(", ")}`);
+			}
 		} else if (claim.selected !== null && claim.selected !== root) throw integrity(`a ${claim.decision} claim keeps the root; it cannot select another node`);
 		if (claim.decision === "test-cannot-resolve") {
 			for (const cell of this.cells.values()) if (cell.split === "test" && cell.attempts > 0) throw integrity("a test-cannot-resolve claim spends nothing on test cells");
 		}
 	}
+	/** Once the first finalist is decided, the search only runs its claim:
+	* nothing new is proposed, registered or allocated outside the test. */
+	assertSearching(subject) {
+		if (this.finalists.size > 0 || this.claimCells > 0) throw integrity(`${subject} follows the start of the claim; the search stopped when its finalists were decided`);
+	}
 	/** @internal */
 	incompleteReasons() {
 		const reasons = [];
@@ -1273,6 +1311,48 @@ const NodeDecidedSchema = z.object({
 	rule: NON_EMPTY,
 	reason: NON_EMPTY
 }).strict();
+const CONFIDENCE = z.number().gt(0).lt(1);
+const ClaimEstimatorSchema = z.discriminatedUnion("kind", [z.object({ kind: z.literal("continuous") }).strict(), z.object({
+	kind: z.literal("binary"),
+	scale: z.number().finite().positive()
+}).strict()]);
+const ClaimSchema = z.object({
+	rule: SourceRefSchema,
+	confidence: CONFIDENCE,
+	power: z.union([z.object({
+		adequate: z.boolean(),
+		minimumEffect: z.number().finite().positive(),
+		powerAtMinimumEffect: z.number().min(0).max(1),
+		targetPower: z.number().gt(0).max(1),
+		units: NON_NEGATIVE_INT,
+		finalists: POSITIVE_INT,
+		pooledVariance: z.number().finite().nonnegative(),
+		estimator: ClaimEstimatorSchema
+	}).strict(), UnknownRefSchema]),
+	finalists: z.array(z.object({
+		nodeId: NODE_ID,
+		estimate: NodeEstimateSchema.nullable(),
+		test: z.object({
+			pairs: NON_NEGATIVE_INT,
+			confidence: CONFIDENCE,
+			method: z.enum([
+				"score-interval",
+				"bootstrap-ci",
+				"exact-sign"
+			]),
+			delta: FINITE_NUMBER,
+			interval: z.tuple([FINITE_NUMBER, FINITE_NUMBER])
+		}).strict().nullable(),
+		promote: z.boolean()
+	}).strict()),
+	selected: NODE_ID.nullable(),
+	decision: z.enum([
+		"ship",
+		"hold",
+		"test-cannot-resolve"
+	]),
+	reason: NON_EMPTY
+}).strict();
 const SearchClosedSchema = z.object({
 	...EventBaseShape,
 	kind: z.literal("search-closed"),
@@ -1284,25 +1364,7 @@ const SearchClosedSchema = z.object({
 		"converged",
 		"aborted"
 	]),
-	claim: z.object({
-		power: z.union([z.object({
-			adequate: z.boolean(),
-			minimumEffect: z.number().finite().positive(),
-			powerAtMinimumEffect: z.number().min(0).max(1),
-			units: NON_NEGATIVE_INT
-		}).strict(), UnknownRefSchema]),
-		finalists: z.array(z.object({
-			nodeId: NODE_ID,
-			estimate: NodeEstimateSchema.nullable(),
-			promote: z.boolean()
-		}).strict()),
-		selected: NODE_ID.nullable(),
-		decision: z.enum([
-			"ship",
-			"hold",
-			"test-cannot-resolve"
-		])
-	}).strict().nullable()
+	claim: ClaimSchema.nullable()
 }).strict();
 const EventSchema = z.discriminatedUnion("kind", [
 	SearchOpenedSchema,
@@ -1514,4 +1576,4 @@ function formatZodError(error) {
 //#endregion
 export { validateSearchLedgerEvent as a, SearchStateView as c, searchTaskSetDigest as d, searchUnitScores as f, replaySearchLedgerText as i, searchCellId as l, openSearchLedger as n, SEARCH_LEDGER_SCHEMA as o, parseSearchLedgerLine as r, SearchState as s, FileSearchLedger as t, searchNodeId as u };
 
-//# sourceMappingURL=search-ledger-Ck7tok0h.js.map
+//# sourceMappingURL=search-ledger-CJiAEU3j.js.map