@tangle-network/agent-eval 0.126.1 → 0.126.2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to `@tangle-network/agent-eval` and its sibling `agent-eval-
 
 ## [Unreleased]
 
+## [0.126.2] - 2026-07-24 - fail-closed candidate ranking
+
+### Added
+
+- `runOptimization()` and `selfImprove()` accept a fixed-length `selectionRankKey` so domain-specific reliability metrics can choose candidates during every generation.
+
+### Fixed
+
+- Candidate rank keys must be non-empty, fixed-length, and finite.
+- A candidate must strictly beat the incumbent on the configured rank key before it can become the next parent or final winner.
+- Method-reported spend above `costCeiling` is rejected before final scoring.
+
 ## [0.126.1] - 2026-07-24 - optimizer lifecycle integrity
 
 ### Changed

package/dist/benchmarks/index.js

@@ -17,8 +17,8 @@ import {
   runBenchmarkAdapter,
   summarizeBenchmarkCampaign
 } from "../chunk-W4L6C2XT.js";
-import "../chunk-NGUYT5CI.js";
-import "../chunk-VMUENW6F.js";
+import "../chunk-Y5CLI4PY.js";
+import "../chunk-7AN2E7BU.js";
 import "../chunk-UCLVDLCH.js";
 import "../chunk-WGXIEX7P.js";
 import "../chunk-ARU2PZFM.js";

package/dist/campaign/index.d.ts

@@ -4457,6 +4457,24 @@ interface RunOptimizationBaseOptions<TScenario extends Scenario, TArtifact> exte
         costLedger?: CostLedgerHandle;
         costPhase?: string;
     }) => Promise<unknown[]>;
+    /**
+     * Optional override for how the WINNER is selected among coverage-complete
+     * candidates (and how the incumbent bar is set). Returns a lexicographic rank
+     * key — each element higher-is-better; candidates are ranked by descending key
+     * (`compareRankKeys`) and the top must STRICTLY beat the incumbent's key to
+     * promote. Defaults to `[campaignMeanComposite(campaign)]`, i.e. the historical
+     * scalar-mean ranking (single-element key ⇒ identical behavior).
+     *
+     * A binary-with-replicates consumer (e.g. swe-arena, whose ship-gate counts an
+     * instance resolved only when EVERY replicate resolved) passes a fail-closed
+     * key built from the SAME reduction its gate uses, so winner-selection and the
+     * ship-gate rank on the identical metric and can never invert — the selector
+     * cannot promote a flaky per-cell-mean candidate the gate would reject over a
+     * fail-closed candidate the gate would accept. Only the winner CHOICE changes;
+     * the descriptive `composite` (mean) on every record and the Pareto objective
+     * vectors are untouched, so proposer diversity and reporting are unaffected.
+     */
+    selectionRankKey?: (campaign: CampaignResult<TArtifact, TScenario>) => number[];
 }
 type RunOptimizationOptions<TScenario extends Scenario, TArtifact> = RunOptimizationBaseOptions<TScenario, TArtifact>;
 interface RunOptimizationResult<TArtifact, TScenario extends Scenario> {
@@ -5487,6 +5505,10 @@ declare function selectDiscriminative(signals: ScenarioSignal[], k: number, opts
  *  descriptive aggregate with NaN. Cells with no valid scores are skipped.
  *  Empty ⇒ 0. */
 declare function campaignMeanComposite<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): number;
+/** Compare fixed-length lexicographic rank keys where each element is higher-is-better.
+ *  Returns a positive number when `a` ranks above `b`, negative when below, and
+ *  zero when equal. */
+declare function compareRankKeys(a: readonly number[], b: readonly number[]): number;
 interface CampaignBreakdown {
     /** Mean score per judge dimension across all cells. */
     dimensions: Record<string, number>;
@@ -6054,4 +6076,4 @@ declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string):
  *  identity against the checkout at `worktreeRef`. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareOptimizationMethodsOptions, type ComparisonCost, type ComponentSurface, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type ExternalOptimizationExample, type ExternalTextEvaluationResponse, type ExternalTextOptimizationMethodConfig, type ExternalTextOptimizerContext, type ExternalTextOptimizerResult, type FailureModeRecallJudgeOptions, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaAdaptiveEngineRun, type GepaEngineOptions, type GepaEngineRun, type GepaOptimizationMethodConfig, type GepaOptimizationRecipe, type GepaRunnerCommand, type GitWorktreeAdapterOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, type LlmJudgeDimension, type LlmJudgeOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceOptimizationMethod, type LoopProvenanceRecord, type MutableSurface, type NeutralizationGateOptions, type ObjectiveSource, type OpenAICompatibleOptimizerModel, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationMethod, type OptimizationMethodComparison, type OptimizationMethodInput, type OptimizationMethodPairwise, type OptimizationMethodProvenance, type OptimizationMethodResult, type OptimizationMethodRunOptions, type OptimizationMethodScore, type OptimizationPackageSource, type OptimizationProposer, type OptimizationTokenUsage, type OptimizerConfig, type OptimizerModelBudget, type PairedHoldout, type ParetoParent, type ParetoSignificanceGateOptions, type PendingCostCallView, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposalTrackContext, type ProposeContext, type ProposedCandidate, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptOptimizationMethodConfig, type SkillOptRunnerCommand, type SkillOptTrainerConfig, type SurfaceProposer, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, acquireSingleRunLock, analyzeCrossSurfaceInteractions, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertComponentSurface, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, campaignBreakdown, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareOptimizationMethods, componentSurfaceIdentityMaterial, composeGate, costFromLedgerSummary, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, externalTextOptimizationMethod, failureModeRecallJudge, fsCampaignStorage, gepaOptimizationMethod, gitWorktreeAdapter, heldOutGate, heldoutSignificance, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, llmJudge, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, optimizationTokenUsageFromSummary, pairHoldout, paretoPolicy, paretoSignificanceGate, planCampaignRun, planEvalFixtureRun, powerPreflight, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runOptimization, runProfileMatrix, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptOptimizationMethod, surfaceContentHash, surfaceHash, tangleTracesRoot, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };
+export { type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareOptimizationMethodsOptions, type ComparisonCost, type ComponentSurface, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type ExternalOptimizationExample, type ExternalTextEvaluationResponse, type ExternalTextOptimizationMethodConfig, type ExternalTextOptimizerContext, type ExternalTextOptimizerResult, type FailureModeRecallJudgeOptions, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaAdaptiveEngineRun, type GepaEngineOptions, type GepaEngineRun, type GepaOptimizationMethodConfig, type GepaOptimizationRecipe, type GepaRunnerCommand, type GitWorktreeAdapterOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, type LlmJudgeDimension, type LlmJudgeOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceOptimizationMethod, type LoopProvenanceRecord, type MutableSurface, type NeutralizationGateOptions, type ObjectiveSource, type OpenAICompatibleOptimizerModel, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationMethod, type OptimizationMethodComparison, type OptimizationMethodInput, type OptimizationMethodPairwise, type OptimizationMethodProvenance, type OptimizationMethodResult, type OptimizationMethodRunOptions, type OptimizationMethodScore, type OptimizationPackageSource, type OptimizationProposer, type OptimizationTokenUsage, type OptimizerConfig, type OptimizerModelBudget, type PairedHoldout, type ParetoParent, type ParetoSignificanceGateOptions, type PendingCostCallView, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposalTrackContext, type ProposeContext, type ProposedCandidate, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptOptimizationMethodConfig, type SkillOptRunnerCommand, type SkillOptTrainerConfig, type SurfaceProposer, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, acquireSingleRunLock, analyzeCrossSurfaceInteractions, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertComponentSurface, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, campaignBreakdown, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareOptimizationMethods, compareRankKeys, componentSurfaceIdentityMaterial, composeGate, costFromLedgerSummary, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, externalTextOptimizationMethod, failureModeRecallJudge, fsCampaignStorage, gepaOptimizationMethod, gitWorktreeAdapter, heldOutGate, heldoutSignificance, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, llmJudge, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, optimizationTokenUsageFromSummary, pairHoldout, paretoPolicy, paretoSignificanceGate, planCampaignRun, planEvalFixtureRun, powerPreflight, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runOptimization, runProfileMatrix, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptOptimizationMethod, surfaceContentHash, surfaceHash, tangleTracesRoot, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };

package/dist/campaign/index.js

@@ -32,7 +32,7 @@ import {
   userStoryScoreboard,
   validateSearchLedgerEvent,
   verifyCodeSurface
-} from "../chunk-NGUYT5CI.js";
+} from "../chunk-Y5CLI4PY.js";
 import {
   acquireSingleRunLock,
   assertCodeSurfaceIdentity,
@@ -45,6 +45,7 @@ import {
   canonicalDigest,
   codeSurfaceIdentityMaterial,
   compareOptimizationMethods,
+  compareRankKeys,
   componentSurfaceIdentityMaterial,
   composeGate,
   costFromLedgerSummary,
@@ -78,7 +79,7 @@ import {
   surfaceContentHash,
   surfaceHash,
   verifyLoopProvenanceRecord
-} from "../chunk-VMUENW6F.js";
+} from "../chunk-7AN2E7BU.js";
 import {
   SearchLedgerConflictError,
   SearchLedgerError,
@@ -141,6 +142,7 @@ export {
   classifyUngroundedLiterals,
   codeSurfaceIdentityMaterial,
   compareOptimizationMethods,
+  compareRankKeys,
   componentSurfaceIdentityMaterial,
   composeGate,
   costFromLedgerSummary,

package/dist/{chunk-VMUENW6F.js → chunk-7AN2E7BU.js}

@@ -1514,6 +1514,29 @@ function campaignMeanComposite(campaign) {
   }
   return composites.length === 0 ? 0 : composites.reduce((a, b) => a + b, 0) / composites.length;
 }
+function assertFiniteRankKey(key, label, expectedLength) {
+  if (!Array.isArray(key) || key.length === 0) {
+    throw new Error(`${label} must return a non-empty array`);
+  }
+  if (expectedLength !== void 0 && key.length !== expectedLength) {
+    throw new Error(`${label} returned ${key.length} elements; expected ${expectedLength}`);
+  }
+  for (let index = 0; index < key.length; index++) {
+    if (!Number.isFinite(key[index])) {
+      throw new Error(`${label}[${index}] must be finite`);
+    }
+  }
+}
+function compareRankKeys(a, b) {
+  assertFiniteRankKey(a, "rank key a");
+  assertFiniteRankKey(b, "rank key b", a.length);
+  for (let i = 0; i < a.length; i++) {
+    const av = a[i];
+    const bv = b[i];
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
 function campaignBreakdown(campaign) {
   const dimSums = {};
   const dimCounts = {};
@@ -1775,6 +1798,16 @@ async function compareOptimizationMethods(opts) {
       throw error;
     }
   });
+  assertReportedCostWithinCeiling(
+    combineCosts(
+      optimized.map((result) => ({
+        label: `method '${result.name}'`,
+        cost: result.cost
+      }))
+    ).totalCostUsd,
+    opts.costCeiling,
+    "optimization"
+  );
   const testCostPhase = finalCostPhase(opts, baselineSurface, optimized, seed);
   const baselineArr = align(
     await scoreOnTest(baselineSurface, "test/baseline", testCostPhase),
@@ -1869,6 +1902,7 @@ async function compareOptimizationMethods(opts) {
     { label: "optimization", cost: optimizationCost },
     { label: "final test", cost: testCost }
   ]);
+  assertReportedCostWithinCeiling(totalCost.totalCostUsd, opts.costCeiling, "total");
   return {
     scores,
     best,
@@ -1885,6 +1919,14 @@ async function compareOptimizationMethods(opts) {
     reps: opts.reps ?? 1
   };
 }
+function assertReportedCostWithinCeiling(totalCostUsd, costCeiling, phase) {
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(totalCostUsd), Math.abs(costCeiling ?? 0)) * 8;
+  if (costCeiling !== void 0 && totalCostUsd > costCeiling + tolerance) {
+    throw new Error(
+      `compareOptimizationMethods: reported ${phase} cost ${totalCostUsd} exceeds costCeiling ${costCeiling}`
+    );
+  }
+}
 function assertOptimizationMethods(methods) {
   if (!Array.isArray(methods) || methods.length === 0) {
     throw new Error("compareOptimizationMethods: no methods to compare");
@@ -5739,9 +5781,12 @@ async function runOptimization(opts) {
   const generations = [];
   const history = [];
   let currentFindings = opts.findings ?? [];
+  const selectionRankKey = opts.selectionRankKey ?? ((campaign) => [campaignMeanComposite(campaign)]);
   let winnerSurface = opts.baselineSurface;
   let winnerSurfaceHash = surfaceHash(opts.baselineSurface);
   let winnerComposite = campaignMeanComposite(baselineCampaign);
+  let winnerRankKey = selectionRankKey(baselineCampaign);
+  assertFiniteRankKey(winnerRankKey, "selectionRankKey for baseline");
   const baselineOutcome = toScoredSurfaceOutcome(
     winnerSurfaceHash,
     baselineCampaign,
@@ -5808,6 +5853,12 @@ async function runOptimization(opts) {
           runDir: `${opts.runDir}/gen-${gen}/candidate-${i}`
         });
         const composite = campaignMeanComposite(campaign);
+        const rankKey = selectionRankKey(campaign);
+        assertFiniteRankKey(
+          rankKey,
+          `selectionRankKey for generation ${gen} candidate ${i}`,
+          winnerRankKey.length
+        );
         const coverage = campaignCoverage(
           campaign.cells,
           opts.scenarios,
@@ -5821,6 +5872,7 @@ async function runOptimization(opts) {
           rationale,
           campaign,
           composite,
+          rankKey,
           coverage
         };
       }
@@ -5835,16 +5887,17 @@ async function runOptimization(opts) {
     }
     surfaceResults.sort((a, b) => {
       if (a.coverage.complete !== b.coverage.complete) return a.coverage.complete ? -1 : 1;
-      return b.composite - a.composite;
+      return compareRankKeys(b.rankKey, a.rankKey);
     });
     const eligibleResults = surfaceResults.filter((result) => result.coverage.complete);
     const top = eligibleResults[0];
-    const promoted = top && top.composite > winnerComposite ? [top] : [];
+    const promoted = top && compareRankKeys(top.rankKey, winnerRankKey) > 0 ? [top] : [];
     if (promoted[0]) {
       const top2 = promoted[0];
       winnerSurface = top2.surface;
       winnerSurfaceHash = top2.surfaceHash;
       winnerComposite = top2.composite;
+      winnerRankKey = top2.rankKey;
       winnerOutcome = toScoredSurfaceOutcome(top2.surfaceHash, top2.campaign, top2.coverage, gen);
       winnerLabel = top2.label || void 0;
       winnerRationale = top2.rationale || void 0;
@@ -7228,6 +7281,7 @@ export {
   buildReflectionPrompt,
   parseReflectionResponse,
   campaignMeanComposite,
+  compareRankKeys,
   campaignBreakdown,
   assertCodeSurfaceIdentity,
   assertComponentSurface,
@@ -7271,4 +7325,4 @@ export {
   emitLoopProvenance,
   skillOptOptimizationMethod
 };
-//# sourceMappingURL=chunk-VMUENW6F.js.map
+//# sourceMappingURL=chunk-7AN2E7BU.js.map