@tangle-network/agent-eval 0.126.1 → 0.126.3

package/CHANGELOG.md

@@ -4,7 +4,29 @@ All notable changes to `@tangle-network/agent-eval` and its sibling `agent-eval-
 
 ---
 
-## [Unreleased]
+## [0.126.3] - 2026-07-24 - execution-bound optimizer resume
+
+### Added
+
+- `runCampaign({ abortOnCellError: true })` stops scheduling after the first dispatch or judge error, aborts and drains active sibling cells, then rejects with the original error.
+- Failed cells write `<cell>/failure-receipt.json` before cancellation, including the exact cell result, call IDs, and settled agent-plus-judge cost and token totals.
+
+### Fixed
+
+- Official GEPA, SkillOpt, and generic external optimizer resume identities include the caller's exact dispatch identity, so changed agent, retrieval, judge, model, or service behavior cannot restore incompatible optimizer state.
+- `compareOptimizationMethods()` passes its final-scoring dispatch identity into method optimization and rejects conflicting identities.
+
+## [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
 

package/README.md

@@ -90,6 +90,26 @@ console.log(
 Each call runs every case, records the artifact, applies the same judge, and returns score distributions.
 The surface is the value being changed, such as a prompt, skill, or serialized configuration.
 
+### Stop after the first failed cell
+
+`runCampaign()` normally records a dispatch or judge error on that cell and continues the remaining cases.
+Set `abortOnCellError: true` when another failed cell would only waste time or money:
+
+```ts
+await runCampaign({
+  scenarios,
+  dispatch,
+  judges: [judge],
+  runDir: 'release-candidate',
+  abortOnCellError: true,
+})
+```
+
+The failed cell is written first to `<runDir>/<cell>/failure-receipt.json`.
+That receipt contains the original error, the cell result, exact call IDs, and settled agent-plus-judge cost and token totals.
+Active sibling cells are cancelled and allowed to finish recording their own receipts before the campaign rejects with the original cell error.
+Leaving `abortOnCellError` unset preserves continue-on-error behavior.
+
 ## Adapt Another Text Optimizer
 
 Use `externalTextOptimizationMethod()` when an existing package owns search and selection for a text prompt or named text components.
@@ -97,7 +117,7 @@ Its `run` callback receives the starting candidate plus serialized train and sel
 The optimizer must score candidates through `context.evaluate()` so Agent Eval can enforce the evaluation limit and use the configured execution and judges.
 Every optimizer-owned paid call must use `context.cost.runPaidCall()`.
 Set `source` to the package version and revision, and set `evaluationId` to a commit, content hash, or other stable identity for the execution and scoring behavior.
-Agent Eval derives the run identity from those values, the optimizer settings, the starting surface, the described data, and the seed.
+Agent Eval derives the run identity from those values, the exact dispatch identity, the optimizer settings, the starting surface, the described data, and the seed.
 The callback returns the selected candidate, whether compatible state was restored, and how optimizer spend was recorded.
 
 See [Adapt A Third-Party Text Optimizer](./docs/campaign-proposers.md#adapt-a-third-party-text-optimizer) for a complete minimal adapter.

package/dist/benchmarks/index.js

@@ -16,10 +16,10 @@ import {
   routing_exports,
   runBenchmarkAdapter,
   summarizeBenchmarkCampaign
-} from "../chunk-W4L6C2XT.js";
-import "../chunk-NGUYT5CI.js";
-import "../chunk-VMUENW6F.js";
-import "../chunk-UCLVDLCH.js";
+} from "../chunk-CGG5SLH3.js";
+import "../chunk-P6WN2KF5.js";
+import "../chunk-3I74FLK6.js";
+import "../chunk-ZVCHKKOP.js";
 import "../chunk-WGXIEX7P.js";
 import "../chunk-ARU2PZFM.js";
 import "../chunk-J5SQWP6Y.js";

package/dist/campaign/index.d.ts

@@ -2368,6 +2368,14 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
     costTags?: Readonly<Record<string, string>>;
     /** Max concurrent cells. Default 2. */
     maxConcurrency?: number;
+    /**
+     * Stop after the first dispatch or judge error. The failed cell is persisted
+     * before active sibling cells are aborted and drained, then the campaign
+     * rejects with the exact error thrown by that dispatch or judge.
+     * Default false preserves the normal behavior of returning failed cells and
+     * continuing the remaining schedule.
+     */
+    abortOnCellError?: boolean;
     /**
      * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
      * rejects within this window is a hang (a stalled model request, an
@@ -2432,6 +2440,26 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
         generation?: number;
     }) => string | undefined;
 }
+/** Durable `<cell>/failure-receipt.json` written before a failed cell can
+ * trigger campaign-wide cancellation. The cell keeps its dispatch-only usage
+ * fields for compatibility; `cost` covers every settled agent and judge call
+ * attributed to this exact run attempt. */
+interface CampaignCellFailureReceipt<TArtifact = unknown> {
+    schemaVersion: 1;
+    runAttemptId: string;
+    recordedAt: string;
+    failure: {
+        stage: 'dispatch' | 'judge';
+        judge?: string;
+        error: {
+            name: string;
+            message: string;
+            stack?: string;
+        };
+    };
+    cell: CampaignCellResult<TArtifact>;
+    cost: CostLedgerSummary;
+}
 /**
  * Core campaign orchestrator: fan scenarios through dispatch, score with judges, aggregate bootstrap CIs, and persist reproducible `CampaignResult` records.
  */
@@ -4457,6 +4485,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 +5533,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 +6104,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 CampaignCellFailureReceipt, 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-P6WN2KF5.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-3I74FLK6.js";
 import {
   SearchLedgerConflictError,
   SearchLedgerError,
@@ -95,7 +96,7 @@ import {
   resolveRunDir,
   runCampaign,
   tangleTracesRoot
-} from "../chunk-UCLVDLCH.js";
+} from "../chunk-ZVCHKKOP.js";
 import "../chunk-WGXIEX7P.js";
 import "../chunk-ARU2PZFM.js";
 import "../chunk-J5SQWP6Y.js";
@@ -141,6 +142,7 @@ export {
   classifyUngroundedLiterals,
   codeSurfaceIdentityMaterial,
   compareOptimizationMethods,
+  compareRankKeys,
   componentSurfaceIdentityMaterial,
   composeGate,
   costFromLedgerSummary,

package/dist/{chunk-VMUENW6F.js → chunk-3I74FLK6.js}

@@ -13,7 +13,7 @@ import {
   runCampaign,
   summarizeAgentReceiptIntegrity,
   tryAcquireAtomicFileLock
-} from "./chunk-UCLVDLCH.js";
+} from "./chunk-ZVCHKKOP.js";
 import {
   clamp01,
   combineAbortSignals,
@@ -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");
@@ -1998,6 +2040,17 @@ function assertComparisonControls(opts, seed, resamples, confidence) {
       "compareOptimizationMethods: dispatchRef must be trimmed and non-empty when provided"
     );
   }
+  const optimizationDispatchRef = opts.optimizationRunOptions?.dispatchRef;
+  if (optimizationDispatchRef !== void 0 && (typeof optimizationDispatchRef !== "string" || optimizationDispatchRef.trim().length === 0 || optimizationDispatchRef.trim() !== optimizationDispatchRef)) {
+    throw new Error(
+      "compareOptimizationMethods: optimizationRunOptions.dispatchRef must be trimmed and non-empty when provided"
+    );
+  }
+  if (opts.dispatchRef !== void 0 && optimizationDispatchRef !== void 0 && opts.dispatchRef !== optimizationDispatchRef) {
+    throw new Error(
+      "compareOptimizationMethods: dispatchRef must match optimizationRunOptions.dispatchRef when both are provided"
+    );
+  }
   try {
     surfaceContentHash(opts.baselineSurface);
   } catch (cause) {
@@ -2169,6 +2222,7 @@ function createOptimizationMethodInput(opts, methodName, resolvedRunDir, seed, b
     seed,
     runOptions: Object.freeze({
       ...opts.optimizationRunOptions ?? {},
+      ...opts.optimizationRunOptions?.dispatchRef === void 0 && opts.dispatchRef !== void 0 ? { dispatchRef: opts.dispatchRef } : {},
       ...signal ? { signal } : {}
     }),
     costLedger
@@ -3758,28 +3812,30 @@ function externalTextOptimizationMethod(config) {
         )
       );
       const methodDir = `${input.runDir}/external/${safePathComponent(snapshot.name)}`;
-      const runId = externalOptimizerRunKey({
-        material: {
-          optimizer: {
-            kind: snapshot.source.kind,
-            package: snapshot.source.package,
-            version: snapshot.source.version,
-            ...snapshot.source.sourceUrl ? { sourceUrl: snapshot.source.sourceUrl } : {},
-            ...snapshot.source.revision ? { revision: snapshot.source.revision } : {}
-          },
-          method: snapshot.name,
-          evaluationId: snapshot.evaluationId,
-          objective: snapshot.objective,
-          background: snapshot.background ?? "",
-          seed: input.seed,
-          seedCandidate,
-          trainSet,
-          selectionSet,
-          maxEvaluations: snapshot.maxEvaluations,
-          maxOptimizerCostUsd: snapshot.maxOptimizerCostUsd,
-          maxCandidateChars,
-          maxEvidenceChars
+      const runMaterial = {
+        optimizer: {
+          kind: snapshot.source.kind,
+          package: snapshot.source.package,
+          version: snapshot.source.version,
+          ...snapshot.source.sourceUrl ? { sourceUrl: snapshot.source.sourceUrl } : {},
+          ...snapshot.source.revision ? { revision: snapshot.source.revision } : {}
         },
+        method: snapshot.name,
+        evaluationId: snapshot.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
+        objective: snapshot.objective,
+        background: snapshot.background ?? "",
+        seed: input.seed,
+        seedCandidate,
+        trainSet,
+        selectionSet,
+        maxEvaluations: snapshot.maxEvaluations,
+        maxOptimizerCostUsd: snapshot.maxOptimizerCostUsd,
+        maxCandidateChars,
+        maxEvidenceChars
+      };
+      const runId = externalOptimizerRunKey({
+        material: runMaterial,
         attemptId,
         resumeEnabled: resume !== "never"
       });
@@ -5454,6 +5510,7 @@ function gepaOptimizationMethod(config) {
         runtime: runtimeIdentity,
         method: name,
         evaluationId: config.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
         seed: input.seed,
         recipe: snapshotJson(config.recipe, "GEPA run settings"),
         engineModules: config.engineModules ?? [],
@@ -5739,9 +5796,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 +5868,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 +5887,7 @@ async function runOptimization(opts) {
           rationale,
           campaign,
           composite,
+          rankKey,
           coverage
         };
       }
@@ -5835,16 +5902,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;
@@ -6037,7 +6105,7 @@ async function runImprovementLoop(opts) {
   const dispatchTimeoutMs = opts.dispatchTimeoutMs ?? DEFAULT_DISPATCH_TIMEOUT_MS;
   const optimization = await runOptimization({ ...opts, dispatchTimeoutMs, costLedger });
   const winnerIsBaseline = optimization.winnerSurfaceHash === surfaceHash(opts.baselineSurface);
-  const { runCampaign: runCampaign2 } = await import("./run-campaign-LVFKZCEU.js");
+  const { runCampaign: runCampaign2 } = await import("./run-campaign-FFRM3RH5.js");
   const holdoutDeferred = (opts.holdout ?? "measured") === "deferred";
   const baselineOnHoldout = holdoutDeferred ? await runCampaign2({
     ...opts,
@@ -6980,6 +7048,7 @@ function skillOptOptimizationMethod(config) {
         runtime: runtimeIdentity,
         method: name,
         evaluationId: config.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
         seed: input.seed,
         trainer: snapshotJson(config.trainer, "SkillOpt run settings"),
         objective: config.objective,
@@ -7228,6 +7297,7 @@ export {
   buildReflectionPrompt,
   parseReflectionResponse,
   campaignMeanComposite,
+  compareRankKeys,
   campaignBreakdown,
   assertCodeSurfaceIdentity,
   assertComponentSurface,
@@ -7271,4 +7341,4 @@ export {
   emitLoopProvenance,
   skillOptOptimizationMethod
 };
-//# sourceMappingURL=chunk-VMUENW6F.js.map
+//# sourceMappingURL=chunk-3I74FLK6.js.map