@tangle-network/agent-eval 0.128.2 → 0.130.0

package/dist/contract/index.js

@@ -1,2097 +1,1890 @@
-import {
-  fromClaudeCodeSession,
-  fromCodexSession,
-  fromKimiCodeSession,
-  fromOpenCodeSession,
-  fromPiSession,
-  fromPigraphSession,
-  observeCodeAgentSession,
-  parseCodeAgentJsonl
-} from "../chunk-SZLVEKMJ.js";
-import {
-  createHostedClient
-} from "../chunk-DRYIUNWY.js";
-import {
-  analyzeRuns,
-  summarizeExecution
-} from "../chunk-NACAGYSY.js";
-import {
-  REFERENCE_EQUIVALENCE_INPUT_LIMITS,
-  REFERENCE_EQUIVALENCE_JUDGE_VERSION,
-  assertOptimizationResult,
-  buildEvidenceVector,
-  compareOptimizationMethods,
-  composeGate,
-  createReferenceEquivalenceJudge,
-  defaultProductionGate,
-  emitLoopProvenance,
-  externalTextOptimizationMethod,
-  gepaOptimizationMethod,
-  heldOutGate,
-  heldoutSignificance,
-  llmJudge,
-  loopProvenanceArgsFromResult,
-  paretoPolicy,
-  paretoSignificanceGate,
-  powerPreflight,
-  runEval,
-  runImprovementLoop,
-  runReferenceEquivalenceJudge,
-  skillOptOptimizationMethod,
-  surfaceContentHash,
-  surfaceHash
-} from "../chunk-NKAGIDE2.js";
-import {
-  campaignSplitDigest,
-  createRunCostLedger,
-  fsCampaignStorage,
-  inMemoryCampaignStorage,
-  resolveRunDir,
-  runCampaign
-} from "../chunk-EZJEIH2R.js";
-import {
-  buildDefaultAnalystRegistry,
-  createChatClient
-} from "../chunk-DJKY2TSY.js";
-import "../chunk-HHWE3POT.js";
-import "../chunk-WGXIEX7P.js";
-import {
-  FileSystemOutcomeStore,
-  InMemoryOutcomeStore
-} from "../chunk-3RF76KTD.js";
-import "../chunk-NYLOYM6N.js";
-import {
-  campaignCellExecutionEvidence,
-  campaignCellJudgeDimensions,
-  campaignCellTaskScore,
-  campaignCellToRunRecord
-} from "../chunk-2MKQIFS4.js";
-import "../chunk-PBE2LOSS.js";
-import "../chunk-VLOATJQ2.js";
-import "../chunk-DPUHNQLN.js";
-import {
-  pairedBootstrap
-} from "../chunk-MHELPNRP.js";
-import "../chunk-WS3NZZQQ.js";
-import "../chunk-VI2UW6B6.js";
-import {
-  readTaskFailureLabels,
-  recordAggregateMeasurements,
-  summarizeExecutionMeasurements,
-  summarizeTraceErrors
-} from "../chunk-7ZZMD7UK.js";
-import "../chunk-PXE2VKMX.js";
-import "../chunk-ZET2UAYW.js";
-import "../chunk-GGE4NNQT.js";
-import {
-  classifyOtlpSpanRole,
-  isOtlpModelCall
-} from "../chunk-P6FYH6K4.js";
-import "../chunk-PC4UYEBM.js";
-import {
-  modelHasSnapshot,
-  parseRunRecordSafe
-} from "../chunk-2JX3CFMB.js";
-import "../chunk-MA6HLL3S.js";
-import {
-  ValidationError
-} from "../chunk-ONWEPEDO.js";
-import {
-  LLM_MODEL_ATTR_KEYS,
-  SPAN_KIND_ATTR_KEYS
-} from "../chunk-K4DBDHLK.js";
-import "../chunk-PZ5AY32C.js";
-
-// src/contract/self-improve.ts
+import { s as ValidationError } from "../errors-8YnH8WlF.js";
+import { i as parseRunRecordSafe, r as modelHasSnapshot } from "../run-record-BuoE80Dq.js";
+import { L as createChatClient, t as buildDefaultAnalystRegistry } from "../default-registry-C-vFCSEc.js";
+import { LLM_MODEL_ATTR_KEYS, SPAN_KIND_ATTR_KEYS } from "../trace-attributes.js";
+import { b as classifyOtlpSpanRole, x as isOtlpModelCall } from "../tools-BmuN627J.js";
+import { B as surfaceContentHash, Ct as llmJudge, M as compareOptimizationMethods, O as composeGate, Q as inMemoryCampaignStorage, S as defaultProductionGate, T as heldoutSignificance, V as surfaceHash, X as createRunCostLedger, Y as runCampaign, Z as fsCampaignStorage, _ as buildEvidenceVector, a as emitLoopProvenance, b as powerPreflight, ct as campaignSplitDigest, d as runImprovementLoop, dt as REFERENCE_EQUIVALENCE_INPUT_LIMITS, ft as REFERENCE_EQUIVALENCE_JUDGE_VERSION, g as gepaOptimizationMethod, j as assertOptimizationResult, k as externalTextOptimizationMethod, mt as runReferenceEquivalenceJudge, o as loopProvenanceArgsFromResult, p as runEval, pt as createReferenceEquivalenceJudge, rt as resolveRunDir, t as skillOptOptimizationMethod, v as paretoPolicy, x as heldOutGate, y as paretoSignificanceGate } from "../skillopt-optimization-method-D4ODwFVV.js";
+import { v as pairedBootstrap } from "../statistics-CnnxdpOg.js";
+import { i as summarizeTraceErrors, n as recordAggregateMeasurements, r as summarizeExecutionMeasurements, t as readTaskFailureLabels } from "../task-failure-attributes-CQZlB3et.js";
+import { n as summarizeExecution, t as analyzeRuns } from "../analyze-runs-C1CavBMk.js";
+import { a as campaignCellExecutionEvidence, c as campaignCellToRunRecord, o as campaignCellJudgeDimensions, s as campaignCellTaskScore } from "../reward-hacking-qipEpKvY.js";
+import { n as InMemoryOutcomeStore, t as FileSystemOutcomeStore } from "../outcome-store-ChBKlTd_.js";
+import { a as fromPiSession, c as observeCodeAgentSession, i as fromOpenCodeSession, n as fromCodexSession, o as fromPigraphSession, r as fromKimiCodeSession, s as parseCodeAgentJsonl, t as fromClaudeCodeSession } from "../code-agent-session-BjkMTQ7H.js";
+import { t as createHostedClient } from "../client-CYzbdJOZ.js";
+import { dirname, join } from "node:path";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { agentCandidateBenchmarkSuiteSchema, agentCandidateBenchmarkTaskSchema, agentCandidateBundleSchema, agentCandidateEvaluationPolicySchema, agentCandidateExperimentSchema, agentImprovementMeasuredComparisonSchema, candidateExecutionEvidenceSchema, canonicalCandidateDigest, omitTopLevelDigest } from "@tangle-network/agent-interface";
+//#region src/contract/self-improve.ts
+/**
+* Run one complete improvement job.
+*
+* A caller-owned `proposer` can generate candidates across local generations.
+* An external `method`, such as official GEPA or SkillOpt, owns its complete
+* search and returns one candidate. Both paths remeasure the selected candidate
+* against cases that candidate generation never receives.
+*/
+/** Failed self-improvement run with an immutable receipt snapshot. */
 var SelfImproveRunError = class extends Error {
-  cost;
-  receipts;
-  constructor(cause, ledger) {
-    const original = cause instanceof Error ? cause : new Error(String(cause));
-    super(original.message, { cause: original });
-    this.name = "SelfImproveRunError";
-    this.cost = ledger.summary();
-    this.receipts = ledger.list();
-  }
+	cost;
+	receipts;
+	constructor(cause, ledger) {
+		const original = cause instanceof Error ? cause : new Error(String(cause));
+		super(original.message, { cause: original });
+		this.name = "SelfImproveRunError";
+		this.cost = ledger.summary();
+		this.receipts = ledger.list();
+	}
 };
 function assertSelfImproveSearchMode(opts) {
-  if (opts.method && opts.proposer) {
-    throw new Error("selfImprove: method and proposer are mutually exclusive");
-  }
-  if (!opts.method) {
-    if (opts.selectionScenarios !== void 0) {
-      throw new Error("selfImprove: selectionScenarios requires method");
-    }
-    return;
-  }
-  if (typeof opts.method.name !== "string" || !opts.method.name.trim() || opts.method.name.trim() !== opts.method.name || typeof opts.method.optimize !== "function") {
-    throw new Error("selfImprove: method must have a trimmed name and optimize(input)");
-  }
-  const budget = opts.budget;
-  if (budget?.generations !== void 0 && budget.generations !== 1) {
-    throw new Error("selfImprove: method owns its rounds; budget.generations must be 1 when set");
-  }
-  if (budget?.populationSize !== void 0 && budget.populationSize !== 1) {
-    throw new Error(
-      "selfImprove: method owns its candidates; budget.populationSize must be 1 when set"
-    );
-  }
-  if (budget?.candidateConcurrency !== void 0 || budget?.maxImprovementShots !== void 0 || opts.analyzeGeneration !== void 0 || opts.findings !== void 0) {
-    throw new Error(
-      "selfImprove: candidateConcurrency, maxImprovementShots, analyzeGeneration, and findings apply only to proposer mode"
-    );
-  }
+	if (opts.method && opts.proposer) throw new Error("selfImprove: method and proposer are mutually exclusive");
+	if (!opts.method) {
+		if (opts.selectionScenarios !== void 0) throw new Error("selfImprove: selectionScenarios requires method");
+		return;
+	}
+	if (typeof opts.method.name !== "string" || !opts.method.name.trim() || opts.method.name.trim() !== opts.method.name || typeof opts.method.optimize !== "function") throw new Error("selfImprove: method must have a trimmed name and optimize(input)");
+	const budget = opts.budget;
+	if (budget?.generations !== void 0 && budget.generations !== 1) throw new Error("selfImprove: method owns its rounds; budget.generations must be 1 when set");
+	if (budget?.populationSize !== void 0 && budget.populationSize !== 1) throw new Error("selfImprove: method owns its candidates; budget.populationSize must be 1 when set");
+	if (budget?.candidateConcurrency !== void 0 || budget?.maxImprovementShots !== void 0 || opts.analyzeGeneration !== void 0 || opts.findings !== void 0) throw new Error("selfImprove: candidateConcurrency, maxImprovementShots, analyzeGeneration, and findings apply only to proposer mode");
 }
 function splitMethodPartitions(searchScenarios, explicitSelection, fraction) {
-  if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
-    throw new Error("selfImprove: budget.selectionFraction must be in (0, 1)");
-  }
-  const byId = /* @__PURE__ */ new Map();
-  for (const scenario of searchScenarios) {
-    if (byId.has(scenario.id)) {
-      throw new Error(`selfImprove: duplicate scenario id '${scenario.id}'`);
-    }
-    byId.set(scenario.id, scenario);
-  }
-  if (explicitSelection) {
-    if (explicitSelection.length === 0) {
-      throw new Error("selfImprove: selectionScenarios must not be empty");
-    }
-    const selectionIds = /* @__PURE__ */ new Set();
-    for (const scenario of explicitSelection) {
-      if (!byId.has(scenario.id)) {
-        throw new Error(
-          `selfImprove: selection scenario '${scenario.id}' is absent from the non-final cases`
-        );
-      }
-      if (selectionIds.has(scenario.id)) {
-        throw new Error(`selfImprove: duplicate selection scenario id '${scenario.id}'`);
-      }
-      selectionIds.add(scenario.id);
-    }
-    const train = searchScenarios.filter((scenario) => !selectionIds.has(scenario.id));
-    if (train.length === 0) {
-      throw new Error("selfImprove: method train split is empty");
-    }
-    return {
-      train,
-      selection: explicitSelection.map((scenario) => byId.get(scenario.id))
-    };
-  }
-  if (searchScenarios.length < 2) {
-    throw new Error("selfImprove: method requires at least two non-final scenarios");
-  }
-  const sorted = [...searchScenarios].sort(
-    (a, b) => stableScenarioHash(a.id) - stableScenarioHash(b.id)
-  );
-  const count = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)));
-  return {
-    selection: sorted.slice(0, count),
-    train: sorted.slice(count)
-  };
+	if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) throw new Error("selfImprove: budget.selectionFraction must be in (0, 1)");
+	const byId = /* @__PURE__ */ new Map();
+	for (const scenario of searchScenarios) {
+		if (byId.has(scenario.id)) throw new Error(`selfImprove: duplicate scenario id '${scenario.id}'`);
+		byId.set(scenario.id, scenario);
+	}
+	if (explicitSelection) {
+		if (explicitSelection.length === 0) throw new Error("selfImprove: selectionScenarios must not be empty");
+		const selectionIds = /* @__PURE__ */ new Set();
+		for (const scenario of explicitSelection) {
+			if (!byId.has(scenario.id)) throw new Error(`selfImprove: selection scenario '${scenario.id}' is absent from the non-final cases`);
+			if (selectionIds.has(scenario.id)) throw new Error(`selfImprove: duplicate selection scenario id '${scenario.id}'`);
+			selectionIds.add(scenario.id);
+		}
+		const train = searchScenarios.filter((scenario) => !selectionIds.has(scenario.id));
+		if (train.length === 0) throw new Error("selfImprove: method train split is empty");
+		return {
+			train,
+			selection: explicitSelection.map((scenario) => byId.get(scenario.id))
+		};
+	}
+	if (searchScenarios.length < 2) throw new Error("selfImprove: method requires at least two non-final scenarios");
+	const sorted = [...searchScenarios].sort((a, b) => stableScenarioHash(a.id) - stableScenarioHash(b.id));
+	const count = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)));
+	return {
+		selection: sorted.slice(0, count),
+		train: sorted.slice(count)
+	};
 }
 function safeRunComponent(value) {
-  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+	return value.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 function stableScenarioHash(value) {
-  let hash = 2166136261 >>> 0;
-  for (let index = 0; index < value.length; index++) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619) >>> 0;
-  }
-  return hash;
-}
+	let hash = 2166136261;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return hash;
+}
+/**
+* Deterministic train/holdout split by a stable hash of `scenario.id`,
+* so the same scenario set always splits the same way across runs.
+*/
 function splitTrainHoldout(scenarios, fraction) {
-  const sorted = [...scenarios].sort((a, b) => stableScenarioHash(a.id) - stableScenarioHash(b.id));
-  const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)));
-  return {
-    holdout: sorted.slice(0, nHoldout),
-    train: sorted.slice(nHoldout)
-  };
+	const sorted = [...scenarios].sort((a, b) => stableScenarioHash(a.id) - stableScenarioHash(b.id));
+	const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)));
+	return {
+		holdout: sorted.slice(0, nHoldout),
+		train: sorted.slice(nHoldout)
+	};
 }
 function meanComposite(byScenario) {
-  const perScenario = {};
-  const values = [];
-  for (const [id, agg] of Object.entries(byScenario)) {
-    perScenario[id] = agg.meanComposite;
-    values.push(agg.meanComposite);
-  }
-  return {
-    compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,
-    perScenario
-  };
-}
+	const perScenario = {};
+	const values = [];
+	for (const [id, agg] of Object.entries(byScenario)) {
+		perScenario[id] = agg.meanComposite;
+		values.push(agg.meanComposite);
+	}
+	return {
+		compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,
+		perScenario
+	};
+}
+/**
+* Latest search campaign measured for the winner surface; the baseline search
+* campaign when the winner IS the baseline. Used by the deferred-holdout
+* summary, where no holdout campaign exists to summarize.
+*/
 function winnerSearchCampaign(result) {
-  for (let i = result.generations.length - 1; i >= 0; i--) {
-    const measured = result.generations[i]?.surfaces.find(
-      (s) => s.surfaceHash === result.winnerSurfaceHash
-    );
-    if (measured) return measured.campaign;
-  }
-  return result.baselineCampaign;
-}
+	for (let i = result.generations.length - 1; i >= 0; i--) {
+		const measured = result.generations[i]?.surfaces.find((s) => s.surfaceHash === result.winnerSurfaceHash);
+		if (measured) return measured.campaign;
+	}
+	return result.baselineCampaign;
+}
+/**
+* One-shot self-improvement loop. See module docstring for defaults +
+* extension points.
+*
+* @example Minimum:
+*
+*   const result = await selfImprove({
+*     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),
+*     scenarios,
+*     judge,
+*     baselineSurface: DEFAULT_PROMPT,
+*     proposer,
+*   })
+*   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)
+*
+* @example Distributed (workers in three regions):
+*
+*   await selfImprove({
+*     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),
+*     scenarios,
+*     judge,
+*     baselineSurface: DEFAULT_PROMPT,
+*     cellPlacement: ({ scenario }) => scenario.region,
+*     budget: { maxConcurrency: 12 },
+*   })
+*/
 async function selfImprove(opts) {
-  const startedAt = Date.now();
-  const requestedRunDir = opts.runDir ?? (opts.method ? `.agent-eval/runs/self-improve-${startedAt}` : `mem://selfImprove-${startedAt}`);
-  const runDir = resolveRunDir(requestedRunDir);
-  const storage = opts.storage ?? (runDir.startsWith("mem://") ? inMemoryCampaignStorage() : fsCampaignStorage());
-  const costLedger = createRunCostLedger({
-    storage,
-    runDir,
-    costCeilingUsd: opts.budget?.dollars
-  });
-  try {
-    return await runSelfImprove(opts, costLedger, startedAt, runDir, storage);
-  } catch (error) {
-    throw new SelfImproveRunError(error, costLedger);
-  }
+	const startedAt = Date.now();
+	const runDir = resolveRunDir(opts.runDir ?? (opts.method ? `.agent-eval/runs/self-improve-${startedAt}` : `mem://selfImprove-${startedAt}`));
+	const storage = opts.storage ?? (runDir.startsWith("mem://") ? inMemoryCampaignStorage() : fsCampaignStorage());
+	const costLedger = createRunCostLedger({
+		storage,
+		runDir,
+		costCeilingUsd: opts.budget?.dollars
+	});
+	try {
+		return await runSelfImprove(opts, costLedger, startedAt, runDir, storage);
+	} catch (error) {
+		throw new SelfImproveRunError(error, costLedger);
+	}
 }
 async function runSelfImprove(opts, costLedger, startedAt, runDir, storage) {
-  const budget = opts.budget ?? {};
-  assertSelfImproveSearchMode(opts);
-  const generations = opts.method ? 1 : budget.generations ?? 3;
-  const populationSize = opts.method ? 1 : budget.populationSize ?? 2;
-  const maxConcurrency = budget.maxConcurrency ?? 2;
-  const holdoutFraction = budget.holdoutFraction ?? 0.25;
-  const holdoutMode = budget.holdout ?? "measured";
-  const holdoutDeferred = holdoutMode === "deferred";
-  const expectUsage = opts.expectUsage ?? "assert";
-  const explicitHoldout = budget.holdoutScenarios;
-  const { train, holdout } = explicitHoldout ? {
-    train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),
-    holdout: explicitHoldout
-  } : holdoutDeferred ? { train: opts.scenarios, holdout: [] } : splitTrainHoldout(opts.scenarios, holdoutFraction);
-  if (train.length === 0) {
-    throw new Error(
-      "selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios."
-    );
-  }
-  if (holdout.length === 0 && !holdoutDeferred) {
-    throw new Error("selfImprove: holdout split is empty. Pass more scenarios.");
-  }
-  if (generations > 0 && !opts.proposer && !opts.method) {
-    throw new Error(
-      "selfImprove: method or proposer is required when budget.generations is greater than zero"
-    );
-  }
-  let optimizationResult;
-  const methodPartitions = opts.method ? splitMethodPartitions(train, opts.selectionScenarios, budget.selectionFraction ?? 0.25) : void 0;
-  const proposer = opts.method ? {
-    kind: `method:${opts.method.name}`,
-    propose: async (context) => {
-      if (context.generation > 0) return [];
-      const result2 = await opts.method.optimize(
-        Object.freeze({
-          baselineSurface: structuredClone(context.currentSurface),
-          trainScenarios: Object.freeze(
-            methodPartitions.train.map((scenario) => structuredClone(scenario))
-          ),
-          selectionScenarios: Object.freeze(
-            methodPartitions.selection.map((scenario) => structuredClone(scenario))
-          ),
-          dispatchWithSurface: opts.agent,
-          judges: Object.freeze([opts.judge]),
-          runDir: `${runDir}/optimization/${safeRunComponent(opts.method.name)}`,
-          seed: 42,
-          runOptions: Object.freeze({
-            storage,
-            maxConcurrency,
-            reps: budget.reps,
-            dispatchTimeoutMs: opts.dispatchTimeoutMs,
-            expectUsage,
-            costCeiling: budget.dollars
-          }),
-          costLedger
-        })
-      );
-      assertOptimizationResult(opts.method.name, result2);
-      optimizationResult = structuredClone(result2);
-      return [
-        {
-          surface: structuredClone(result2.winnerSurface),
-          label: opts.method.name,
-          rationale: `${opts.method.name} selected this surface without final cases.`
-        }
-      ];
-    }
-  } : opts.proposer ?? {
-    kind: "baseline-only",
-    propose: async () => []
-  };
-  const gate = opts.gate ?? defaultProductionGate({
-    holdoutScenarios: holdout,
-    deltaThreshold: 0.05
-  });
-  if (opts.onProgress) {
-    opts.onProgress({ kind: "baseline.started", scenarios: opts.scenarios.length });
-  }
-  const result = await runImprovementLoop({
-    scenarios: train,
-    baselineSurface: opts.baselineSurface,
-    premeasuredBaseline: opts.premeasuredBaseline,
-    dispatchWithSurface: opts.agent,
-    proposer,
-    judges: [opts.judge],
-    populationSize,
-    maxGenerations: generations,
-    candidateConcurrency: budget.candidateConcurrency,
-    reps: budget.reps,
-    maxImprovementShots: budget.maxImprovementShots,
-    holdoutScenarios: holdout,
-    holdout: holdoutMode,
-    gate,
-    neutralize: opts.neutralize,
-    autoOnPromote: opts.autoOnPromote ?? "none",
-    ghOwner: opts.ghOwner,
-    ghRepo: opts.ghRepo,
-    storage,
-    runDir,
-    maxConcurrency,
-    cellPlacement: opts.cellPlacement,
-    dispatchTimeoutMs: opts.dispatchTimeoutMs,
-    costLedger,
-    expectUsage,
-    labeledStore: opts.labeledStore,
-    captureSource: opts.captureSource,
-    analyzeGeneration: opts.analyzeGeneration,
-    findings: opts.findings,
-    selectionRankKey: opts.selectionRankKey
-  });
-  const reportSplit = holdoutDeferred ? "search" : "holdout";
-  const reportBaselineCampaign = holdoutDeferred ? result.baselineCampaign : result.baselineOnHoldout;
-  const reportWinnerCampaign = holdoutDeferred ? winnerSearchCampaign(result) : result.winnerOnHoldout;
-  const baseline = meanComposite(reportBaselineCampaign.aggregates.byScenario);
-  const winnerStats = meanComposite(reportWinnerCampaign.aggregates.byScenario);
-  let power;
-  const baselineHoldoutComposites = result.baselineOnHoldout.cells.filter((cell) => !cell.error).map((cell) => {
-    const scores = Object.values(cell.judgeScores);
-    return scores.length === 0 ? Number.NaN : scores.reduce((sum, s) => sum + s.composite, 0) / scores.length;
-  }).filter((v) => Number.isFinite(v));
-  if (baselineHoldoutComposites.length >= 3) {
-    power = powerPreflight({
-      baselineComposites: baselineHoldoutComposites,
-      sharedScorerChannel: true
-    });
-    if (opts.onProgress) {
-      opts.onProgress({
-        kind: "power.estimated",
-        n: power.n,
-        sd: power.sd,
-        mde: power.mde,
-        underpowered: power.underpowered
-      });
-    }
-    if (power.underpowered && generations > 0) {
-      console.warn(`[selfImprove] ${power.recommendation}`);
-    }
-  }
-  if (opts.onProgress) {
-    opts.onProgress({
-      kind: "baseline.completed",
-      compositeMean: baseline.compositeMean,
-      durationMs: Date.now() - startedAt
-    });
-    opts.onProgress({
-      kind: "gate.decided",
-      decision: result.gateResult.decision,
-      // Deferred holdout has no held-out measurement: in that mode the summary
-      // stats are search-split numbers, and emitting their delta as `lift`
-      // would misreport a train-split delta as a held-out one. Omit instead.
-      ...holdoutDeferred ? {} : { lift: winnerStats.compositeMean - baseline.compositeMean }
-    });
-  }
-  const cost = result.cost;
-  const totalCost = cost.totalCostUsd;
-  const insight = await analyzeRuns({
-    runs: [
-      ...cellsToRunRecords(
-        reportBaselineCampaign.cells,
-        "baseline",
-        runDir,
-        opts.baselineSurface,
-        reportSplit,
-        opts.model
-      ),
-      ...cellsToRunRecords(
-        reportWinnerCampaign.cells,
-        "winner",
-        runDir,
-        result.winnerSurface,
-        reportSplit,
-        opts.model
-      )
-    ],
-    baselineCandidateId: "baseline",
-    candidateCandidateId: "winner"
-  });
-  const durationMs = Date.now() - startedAt;
-  const { record: provenance } = await emitLoopProvenance({
-    ...loopProvenanceArgsFromResult({
-      runId: `${runDir}#${startedAt}`,
-      runDir,
-      timestamp: new Date(startedAt).toISOString(),
-      baselineSurface: opts.baselineSurface,
-      result,
-      costReceipts: costLedger.list(),
-      totalCostUsd: totalCost,
-      totalDurationMs: durationMs
-    }),
-    ...optimizationResult ? {
-      optimizationMethod: {
-        name: opts.method.name,
-        cost: structuredClone(optimizationResult.cost),
-        ...optimizationResult.durationMs === void 0 ? {} : { durationMs: optimizationResult.durationMs },
-        ...optimizationResult.provenance === void 0 ? {} : { provenance: structuredClone(optimizationResult.provenance) }
-      }
-    } : {},
-    storage,
-    hostedClient: opts.hostedTenant ? createHostedClient(opts.hostedTenant) : void 0
-  });
-  if (opts.onProvenance) opts.onProvenance(provenance);
-  const summary = {
-    baseline,
-    winner: {
-      ...winnerStats,
-      surface: result.winnerSurface,
-      ...result.winnerLabel ? { label: result.winnerLabel } : {},
-      ...result.winnerRationale ? { rationale: result.winnerRationale } : {}
-    },
-    ...holdoutDeferred ? {} : { lift: winnerStats.compositeMean - baseline.compositeMean },
-    diff: result.promotedDiff,
-    provenance,
-    gateDecision: result.gateResult.decision,
-    generationsExplored: result.generations.length,
-    durationMs,
-    totalCostUsd: totalCost,
-    cost,
-    receipts: costLedger.list(),
-    ...optimizationResult ? {
-      optimization: {
-        name: opts.method.name,
-        cost: structuredClone(optimizationResult.cost),
-        ...optimizationResult.durationMs === void 0 ? {} : { durationMs: optimizationResult.durationMs },
-        ...optimizationResult.provenance === void 0 ? {} : { provenance: structuredClone(optimizationResult.provenance) }
-      }
-    } : {},
-    insight,
-    ...power ? { power } : {},
-    raw: result
-  };
-  if (opts.hostedTenant) {
-    try {
-      await shipEvalRunToHosted(opts.hostedTenant, opts, summary, result, runDir);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`[agent-eval] hosted ingest failed (continuing): ${msg}`);
-    }
-  }
-  return summary;
+	const budget = opts.budget ?? {};
+	assertSelfImproveSearchMode(opts);
+	const generations = opts.method ? 1 : budget.generations ?? 3;
+	const populationSize = opts.method ? 1 : budget.populationSize ?? 2;
+	const maxConcurrency = budget.maxConcurrency ?? 2;
+	const holdoutFraction = budget.holdoutFraction ?? .25;
+	const holdoutMode = budget.holdout ?? "measured";
+	const holdoutDeferred = holdoutMode === "deferred";
+	const expectUsage = opts.expectUsage ?? "assert";
+	const explicitHoldout = budget.holdoutScenarios;
+	const { train, holdout } = explicitHoldout ? {
+		train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),
+		holdout: explicitHoldout
+	} : holdoutDeferred ? {
+		train: opts.scenarios,
+		holdout: []
+	} : splitTrainHoldout(opts.scenarios, holdoutFraction);
+	if (train.length === 0) throw new Error("selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.");
+	if (holdout.length === 0 && !holdoutDeferred) throw new Error("selfImprove: holdout split is empty. Pass more scenarios.");
+	if (generations > 0 && !opts.proposer && !opts.method) throw new Error("selfImprove: method or proposer is required when budget.generations is greater than zero");
+	let optimizationResult;
+	const methodPartitions = opts.method ? splitMethodPartitions(train, opts.selectionScenarios, budget.selectionFraction ?? .25) : void 0;
+	const proposer = opts.method ? {
+		kind: `method:${opts.method.name}`,
+		propose: async (context) => {
+			if (context.generation > 0) return [];
+			const result = await opts.method.optimize(Object.freeze({
+				baselineSurface: structuredClone(context.currentSurface),
+				trainScenarios: Object.freeze(methodPartitions.train.map((scenario) => structuredClone(scenario))),
+				selectionScenarios: Object.freeze(methodPartitions.selection.map((scenario) => structuredClone(scenario))),
+				dispatchWithSurface: opts.agent,
+				judges: Object.freeze([opts.judge]),
+				runDir: `${runDir}/optimization/${safeRunComponent(opts.method.name)}`,
+				seed: 42,
+				runOptions: Object.freeze({
+					storage,
+					maxConcurrency,
+					reps: budget.reps,
+					dispatchTimeoutMs: opts.dispatchTimeoutMs,
+					expectUsage,
+					costCeiling: budget.dollars
+				}),
+				costLedger
+			}));
+			assertOptimizationResult(opts.method.name, result);
+			optimizationResult = structuredClone(result);
+			return [{
+				surface: structuredClone(result.winnerSurface),
+				label: opts.method.name,
+				rationale: `${opts.method.name} selected this surface without final cases.`
+			}];
+		}
+	} : opts.proposer ?? {
+		kind: "baseline-only",
+		propose: async () => []
+	};
+	const gate = opts.gate ?? defaultProductionGate({
+		holdoutScenarios: holdout,
+		deltaThreshold: .05
+	});
+	if (opts.onProgress) opts.onProgress({
+		kind: "baseline.started",
+		scenarios: opts.scenarios.length
+	});
+	const result = await runImprovementLoop({
+		scenarios: train,
+		baselineSurface: opts.baselineSurface,
+		premeasuredBaseline: opts.premeasuredBaseline,
+		dispatchWithSurface: opts.agent,
+		proposer,
+		judges: [opts.judge],
+		populationSize,
+		maxGenerations: generations,
+		candidateConcurrency: budget.candidateConcurrency,
+		reps: budget.reps,
+		maxImprovementShots: budget.maxImprovementShots,
+		holdoutScenarios: holdout,
+		holdout: holdoutMode,
+		gate,
+		neutralize: opts.neutralize,
+		autoOnPromote: opts.autoOnPromote ?? "none",
+		ghOwner: opts.ghOwner,
+		ghRepo: opts.ghRepo,
+		storage,
+		runDir,
+		maxConcurrency,
+		cellPlacement: opts.cellPlacement,
+		dispatchTimeoutMs: opts.dispatchTimeoutMs,
+		costLedger,
+		expectUsage,
+		labeledStore: opts.labeledStore,
+		captureSource: opts.captureSource,
+		analyzeGeneration: opts.analyzeGeneration,
+		findings: opts.findings,
+		selectionRankKey: opts.selectionRankKey
+	});
+	const reportSplit = holdoutDeferred ? "search" : "holdout";
+	const reportBaselineCampaign = holdoutDeferred ? result.baselineCampaign : result.baselineOnHoldout;
+	const reportWinnerCampaign = holdoutDeferred ? winnerSearchCampaign(result) : result.winnerOnHoldout;
+	const baseline = meanComposite(reportBaselineCampaign.aggregates.byScenario);
+	const winnerStats = meanComposite(reportWinnerCampaign.aggregates.byScenario);
+	let power;
+	const baselineHoldoutComposites = result.baselineOnHoldout.cells.filter((cell) => !cell.error).map((cell) => {
+		const scores = Object.values(cell.judgeScores);
+		return scores.length === 0 ? NaN : scores.reduce((sum, s) => sum + s.composite, 0) / scores.length;
+	}).filter((v) => Number.isFinite(v));
+	if (baselineHoldoutComposites.length >= 3) {
+		power = powerPreflight({
+			baselineComposites: baselineHoldoutComposites,
+			sharedScorerChannel: true
+		});
+		if (opts.onProgress) opts.onProgress({
+			kind: "power.estimated",
+			n: power.n,
+			sd: power.sd,
+			mde: power.mde,
+			underpowered: power.underpowered
+		});
+		if (power.underpowered && generations > 0) console.warn(`[selfImprove] ${power.recommendation}`);
+	}
+	if (opts.onProgress) {
+		opts.onProgress({
+			kind: "baseline.completed",
+			compositeMean: baseline.compositeMean,
+			durationMs: Date.now() - startedAt
+		});
+		opts.onProgress({
+			kind: "gate.decided",
+			decision: result.gateResult.decision,
+			...holdoutDeferred ? {} : { lift: winnerStats.compositeMean - baseline.compositeMean }
+		});
+	}
+	const cost = result.cost;
+	const totalCost = cost.totalCostUsd;
+	const insight = await analyzeRuns({
+		runs: [...cellsToRunRecords(reportBaselineCampaign.cells, "baseline", runDir, opts.baselineSurface, reportSplit, opts.model), ...cellsToRunRecords(reportWinnerCampaign.cells, "winner", runDir, result.winnerSurface, reportSplit, opts.model)],
+		baselineCandidateId: "baseline",
+		candidateCandidateId: "winner"
+	});
+	const durationMs = Date.now() - startedAt;
+	const { record: provenance } = await emitLoopProvenance({
+		...loopProvenanceArgsFromResult({
+			runId: `${runDir}#${startedAt}`,
+			runDir,
+			timestamp: new Date(startedAt).toISOString(),
+			baselineSurface: opts.baselineSurface,
+			result,
+			costReceipts: costLedger.list(),
+			totalCostUsd: totalCost,
+			totalDurationMs: durationMs
+		}),
+		...optimizationResult ? { optimizationMethod: {
+			name: opts.method.name,
+			cost: structuredClone(optimizationResult.cost),
+			...optimizationResult.durationMs === void 0 ? {} : { durationMs: optimizationResult.durationMs },
+			...optimizationResult.provenance === void 0 ? {} : { provenance: structuredClone(optimizationResult.provenance) }
+		} } : {},
+		storage,
+		hostedClient: opts.hostedTenant ? createHostedClient(opts.hostedTenant) : void 0
+	});
+	if (opts.onProvenance) opts.onProvenance(provenance);
+	const summary = {
+		baseline,
+		winner: {
+			...winnerStats,
+			surface: result.winnerSurface,
+			...result.winnerLabel ? { label: result.winnerLabel } : {},
+			...result.winnerRationale ? { rationale: result.winnerRationale } : {}
+		},
+		...holdoutDeferred ? {} : { lift: winnerStats.compositeMean - baseline.compositeMean },
+		diff: result.promotedDiff,
+		provenance,
+		gateDecision: result.gateResult.decision,
+		generationsExplored: result.generations.length,
+		durationMs,
+		totalCostUsd: totalCost,
+		cost,
+		receipts: costLedger.list(),
+		...optimizationResult ? { optimization: {
+			name: opts.method.name,
+			cost: structuredClone(optimizationResult.cost),
+			...optimizationResult.durationMs === void 0 ? {} : { durationMs: optimizationResult.durationMs },
+			...optimizationResult.provenance === void 0 ? {} : { provenance: structuredClone(optimizationResult.provenance) }
+		} } : {},
+		insight,
+		...power ? { power } : {},
+		raw: result
+	};
+	if (opts.hostedTenant) try {
+		await shipEvalRunToHosted(opts.hostedTenant, opts, summary, result, runDir);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.warn(`[agent-eval] hosted ingest failed (continuing): ${msg}`);
+	}
+	return summary;
 }
 async function shipEvalRunToHosted(tenant, opts, summary, raw, runDir) {
-  const client = createHostedClient(tenant);
-  function snapshotFromCampaign(index, surface, campaign, durationMs) {
-    const cells = campaign.cells.map((cell) => {
-      const execution = campaignCellExecutionEvidence(cell);
-      return {
-        scenarioId: cell.scenarioId,
-        rep: cell.rep,
-        compositeMean: campaignCellTaskScore(cell) ?? null,
-        dimensions: campaignCellJudgeDimensions(cell),
-        terminalOutcome: execution.terminalOutcome,
-        executionErrorCount: execution.executionErrorCount ?? null,
-        errorMessage: cell.error ?? void 0
-      };
-    });
-    const scoredCells = cells.flatMap(
-      (cell) => cell.compositeMean === null ? [] : [cell.compositeMean]
-    );
-    const compositeMean = scoredCells.length === 0 ? null : scoredCells.reduce((sum, score) => sum + score, 0) / scoredCells.length;
-    return {
-      index,
-      surfaceHash: surfaceHash(surface),
-      surface,
-      cells,
-      compositeMean,
-      costUsd: campaign.aggregates.totalCostUsd,
-      durationMs
-    };
-  }
-  const generations = [];
-  generations.push(snapshotFromCampaign(0, opts.baselineSurface, raw.baselineCampaign, 0));
-  for (const gen of raw.generations) {
-    const winner = gen.surfaces.reduce(
-      (best, s) => s.campaign.aggregates.cellsExecuted > 0 && (best === void 0 || averageComposite(s.campaign) > averageComposite(best.campaign)) ? s : best,
-      gen.surfaces[0]
-    );
-    if (!winner) continue;
-    generations.push(
-      snapshotFromCampaign(gen.record.generationIndex + 1, winner.surface, winner.campaign, 0)
-    );
-  }
-  const event = {
-    runId: `${runDir}#${Date.now()}`,
-    runDir,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    status: "finished",
-    labels: opts.hostedLabels ?? {},
-    baseline: generations[0],
-    generations,
-    gateDecision: summary.gateDecision,
-    holdoutLift: summary.lift,
-    totalCostUsd: summary.totalCostUsd,
-    totalDurationMs: summary.durationMs,
-    insightReport: summary.insight
-  };
-  await client.ingestEvalRun(event);
+	const client = createHostedClient(tenant);
+	function snapshotFromCampaign(index, surface, campaign, durationMs) {
+		const cells = campaign.cells.map((cell) => {
+			const execution = campaignCellExecutionEvidence(cell);
+			return {
+				scenarioId: cell.scenarioId,
+				rep: cell.rep,
+				compositeMean: campaignCellTaskScore(cell) ?? null,
+				dimensions: campaignCellJudgeDimensions(cell),
+				terminalOutcome: execution.terminalOutcome,
+				executionErrorCount: execution.executionErrorCount ?? null,
+				errorMessage: cell.error ?? void 0
+			};
+		});
+		const scoredCells = cells.flatMap((cell) => cell.compositeMean === null ? [] : [cell.compositeMean]);
+		const compositeMean = scoredCells.length === 0 ? null : scoredCells.reduce((sum, score) => sum + score, 0) / scoredCells.length;
+		return {
+			index,
+			surfaceHash: surfaceHash(surface),
+			surface,
+			cells,
+			compositeMean,
+			costUsd: campaign.aggregates.cost.totalCostUsd,
+			durationMs
+		};
+	}
+	const generations = [];
+	generations.push(snapshotFromCampaign(0, opts.baselineSurface, raw.baselineCampaign, 0));
+	for (const gen of raw.generations) {
+		const winner = gen.surfaces.reduce((best, s) => s.campaign.aggregates.cellsExecuted > 0 && (best === void 0 || averageComposite(s.campaign) > averageComposite(best.campaign)) ? s : best, gen.surfaces[0]);
+		if (!winner) continue;
+		generations.push(snapshotFromCampaign(gen.record.generationIndex + 1, winner.surface, winner.campaign, 0));
+	}
+	const event = {
+		runId: `${runDir}#${Date.now()}`,
+		runDir,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		status: "finished",
+		labels: opts.hostedLabels ?? {},
+		baseline: generations[0],
+		generations,
+		gateDecision: summary.gateDecision,
+		holdoutLift: summary.lift,
+		totalCostUsd: summary.totalCostUsd,
+		totalDurationMs: summary.durationMs,
+		insightReport: summary.insight
+	};
+	await client.ingestEvalRun(event);
 }
 function averageComposite(campaign) {
-  const aggs = Object.values(campaign.aggregates.byScenario);
-  return aggs.length === 0 ? 0 : aggs.reduce((s, a) => s + a.meanComposite, 0) / aggs.length;
+	const aggs = Object.values(campaign.aggregates.byScenario);
+	return aggs.length === 0 ? 0 : aggs.reduce((s, a) => s + a.meanComposite, 0) / aggs.length;
 }
 function hashString(s) {
-  let h = 2166136261 >>> 0;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 16777619) >>> 0;
-  }
-  return h.toString(16).padStart(8, "0");
-}
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+/**
+* Adapt campaign cells into the `RunRecord` shape `analyzeRuns()` consumes.
+* Each cell becomes one run; `candidateId` is the caller-supplied label so
+* baseline + winner pair cleanly on `(experimentId, scenarioId, seed)`.
+*
+* `promptHash` is the REAL sha256 content hash of the surface this cell ran
+* (baseline vs winner are byte-distinguishable + byte-identical-verifiable);
+* `configHash` is the sha256 of the candidate label so the two candidates'
+* config rows differ. Both were previously the literal `'sha256:cell'`, which
+* made baseline and winner indistinguishable in every downstream record.
+*/
 function cellsToRunRecords(cells, candidateId, runId, surface, splitTag, fallbackModel) {
-  const promptHash = surfaceContentHash(surface);
-  const configHash = surfaceContentHash(candidateId);
-  return cells.map((cell) => {
-    const model = cell.resolvedModel ?? fallbackModel;
-    if (!model) {
-      throw new ValidationError(
-        `selfImprove.model is required when cell ${cell.cellId} has no paid-call model receipt`
-      );
-    }
-    if (!modelHasSnapshot(model)) {
-      throw new ValidationError(
-        `selfImprove model "${model}" lacks a snapshot version for cell ${cell.cellId}`
-      );
-    }
-    return campaignCellToRunRecord(cell, {
-      runId: `${runId}::${candidateId}::${cell.cellId}`,
-      experimentId: runId,
-      candidateId,
-      // scenarioId is explicit; seed keeps repeated runs distinct.
-      seed: cell.rep * 1e6 + hashString(cell.scenarioId).slice(0, 6).split("").reduce((a, c) => a * 31 + c.charCodeAt(0) >>> 0, 0),
-      model,
-      promptHash,
-      configHash,
-      commitSha: "cell",
-      splitTag
-    });
-  });
-}
-
-// src/contract/define-agent-eval.ts
+	const promptHash = surfaceContentHash(surface);
+	const configHash = surfaceContentHash(candidateId);
+	return cells.map((cell) => {
+		const model = cell.resolvedModel ?? fallbackModel;
+		if (!model) throw new ValidationError(`selfImprove.model is required when cell ${cell.cellId} has no paid-call model receipt`);
+		if (!modelHasSnapshot(model)) throw new ValidationError(`selfImprove model "${model}" lacks a snapshot version for cell ${cell.cellId}`);
+		return campaignCellToRunRecord(cell, {
+			runId: `${runId}::${candidateId}::${cell.cellId}`,
+			experimentId: runId,
+			candidateId,
+			seed: cell.rep * 1e6 + hashString(cell.scenarioId).slice(0, 6).split("").reduce((a, c) => a * 31 + c.charCodeAt(0) >>> 0, 0),
+			model,
+			promptHash,
+			configHash,
+			commitSha: "cell",
+			splitTag
+		});
+	});
+}
+//#endregion
+//#region src/contract/define-agent-eval.ts
+/**
+* Define an agent eval once, then either score a surface with `evaluate()` or
+* run the closed loop with `improve()`.
+*
+* This is a DX wrapper only: it delegates to `runEval()` and `selfImprove()` and
+* returns their native result shapes.
+*/
 function defineAgentEval(defaults) {
-  const defaultEvaluateOptions = evaluateDefaults(defaults);
-  return {
-    scenarios: defaults.scenarios,
-    baselineSurface: defaults.baselineSurface,
-    async evaluate(opts = {}) {
-      const { agent, judge, judges, runDir, scenarios, surface, ...campaignOpts } = opts;
-      const selectedAgent = agent ?? defaults.agent;
-      const selectedSurface = surface ?? defaults.baselineSurface;
-      const selectedRunDir = runDir ?? defaults.runDir ?? `mem://defineAgentEval-${Date.now()}`;
-      const selectedStorage = campaignOpts.storage ?? defaultEvaluateOptions.storage ?? (selectedRunDir.startsWith("mem://") ? inMemoryCampaignStorage() : void 0);
-      const evalOptions = {
-        ...defaultEvaluateOptions,
-        ...campaignOpts,
-        ...selectedStorage ? { storage: selectedStorage } : {},
-        runDir: selectedRunDir,
-        scenarios: scenarios ?? defaults.scenarios,
-        dispatch: (scenario, ctx) => selectedAgent(selectedSurface, scenario, ctx),
-        judges: evaluateJudges(judges, judge ?? defaults.judge)
-      };
-      if (evalOptions.reps !== void 0)
-        evalOptions.reps = requirePositiveInteger(evalOptions.reps, "reps");
-      return runEval(evalOptions);
-    },
-    async improve(opts = {}) {
-      const {
-        budget: budgetOverride,
-        hostedTenant: hostedTenantOverride,
-        ...topLevelOverrides
-      } = opts;
-      const merged = mergeDefined(defaults, topLevelOverrides);
-      const budget = mergeBudget(defaults.budget, budgetOverride);
-      const hostedTenant = mergeHostedTenant(defaults.hostedTenant, hostedTenantOverride);
-      return selfImprove({
-        ...merged,
-        ...budget ? { budget } : {},
-        ...hostedTenant ? { hostedTenant } : {}
-      });
-    }
-  };
+	const defaultEvaluateOptions = evaluateDefaults(defaults);
+	return {
+		scenarios: defaults.scenarios,
+		baselineSurface: defaults.baselineSurface,
+		async evaluate(opts = {}) {
+			const { agent, judge, judges, runDir, scenarios, surface, ...campaignOpts } = opts;
+			const selectedAgent = agent ?? defaults.agent;
+			const selectedSurface = surface ?? defaults.baselineSurface;
+			const selectedRunDir = runDir ?? defaults.runDir ?? `mem://defineAgentEval-${Date.now()}`;
+			const selectedStorage = campaignOpts.storage ?? defaultEvaluateOptions.storage ?? (selectedRunDir.startsWith("mem://") ? inMemoryCampaignStorage() : void 0);
+			const evalOptions = {
+				...defaultEvaluateOptions,
+				...campaignOpts,
+				...selectedStorage ? { storage: selectedStorage } : {},
+				runDir: selectedRunDir,
+				scenarios: scenarios ?? defaults.scenarios,
+				dispatch: (scenario, ctx) => selectedAgent(selectedSurface, scenario, ctx),
+				judges: evaluateJudges(judges, judge ?? defaults.judge)
+			};
+			if (evalOptions.reps !== void 0) evalOptions.reps = requirePositiveInteger(evalOptions.reps, "reps");
+			return runEval(evalOptions);
+		},
+		async improve(opts = {}) {
+			const { budget: budgetOverride, hostedTenant: hostedTenantOverride, ...topLevelOverrides } = opts;
+			const merged = mergeDefined(defaults, topLevelOverrides);
+			const budget = mergeBudget(defaults.budget, budgetOverride);
+			const hostedTenant = mergeHostedTenant(defaults.hostedTenant, hostedTenantOverride);
+			return selfImprove({
+				...merged,
+				...budget ? { budget } : {},
+				...hostedTenant ? { hostedTenant } : {}
+			});
+		}
+	};
 }
 function evaluateDefaults(defaults) {
-  const out = {};
-  if (defaults.storage) out.storage = defaults.storage;
-  if (defaults.labeledStore) out.labeledStore = defaults.labeledStore;
-  if (defaults.captureSource) out.captureSource = defaults.captureSource;
-  if (defaults.cellPlacement) out.cellPlacement = defaults.cellPlacement;
-  if (defaults.expectUsage) out.expectUsage = defaults.expectUsage;
-  if (defaults.budget?.dollars !== void 0) out.costCeiling = defaults.budget.dollars;
-  if (defaults.budget?.maxConcurrency !== void 0)
-    out.maxConcurrency = defaults.budget.maxConcurrency;
-  if (defaults.budget?.reps !== void 0)
-    out.reps = requirePositiveInteger(defaults.budget.reps, "budget.reps");
-  return out;
+	const out = {};
+	if (defaults.storage) out.storage = defaults.storage;
+	if (defaults.labeledStore) out.labeledStore = defaults.labeledStore;
+	if (defaults.captureSource) out.captureSource = defaults.captureSource;
+	if (defaults.cellPlacement) out.cellPlacement = defaults.cellPlacement;
+	if (defaults.expectUsage) out.expectUsage = defaults.expectUsage;
+	if (defaults.budget?.dollars !== void 0) out.costCeiling = defaults.budget.dollars;
+	if (defaults.budget?.maxConcurrency !== void 0) out.maxConcurrency = defaults.budget.maxConcurrency;
+	if (defaults.budget?.reps !== void 0) out.reps = requirePositiveInteger(defaults.budget.reps, "budget.reps");
+	return out;
 }
 function mergeBudget(defaults, overrides) {
-  const merged = mergeOptionalObject(defaults, overrides);
-  if (merged?.reps !== void 0) merged.reps = requirePositiveInteger(merged.reps, "budget.reps");
-  return merged;
+	const merged = mergeOptionalObject(defaults, overrides);
+	if (merged?.reps !== void 0) merged.reps = requirePositiveInteger(merged.reps, "budget.reps");
+	return merged;
 }
 function mergeHostedTenant(defaults, overrides) {
-  const merged = mergeOptionalObject(defaults, overrides);
-  if (!merged) return void 0;
-  if (!merged.endpoint?.trim() || !merged.apiKey?.trim() || !merged.tenantId?.trim()) {
-    throw new Error(
-      "defineAgentEval.improve: hostedTenant requires endpoint, apiKey, and tenantId after merging defaults and overrides"
-    );
-  }
-  return merged;
+	const merged = mergeOptionalObject(defaults, overrides);
+	if (!merged) return void 0;
+	if (!merged.endpoint?.trim() || !merged.apiKey?.trim() || !merged.tenantId?.trim()) throw new Error("defineAgentEval.improve: hostedTenant requires endpoint, apiKey, and tenantId after merging defaults and overrides");
+	return merged;
 }
 function mergeDefined(defaults, overrides) {
-  if (!overrides) return defaults;
-  const merged = { ...defaults };
-  for (const [key, value] of Object.entries(overrides)) {
-    if (value !== void 0) merged[key] = value;
-  }
-  return merged;
+	if (!overrides) return defaults;
+	const merged = { ...defaults };
+	for (const [key, value] of Object.entries(overrides)) if (value !== void 0) merged[key] = value;
+	return merged;
 }
 function mergeOptionalObject(defaults, overrides) {
-  if (!defaults && !overrides) return void 0;
-  return mergeDefined(defaults ?? {}, overrides);
+	if (!defaults && !overrides) return void 0;
+	return mergeDefined(defaults ?? {}, overrides);
 }
 function evaluateJudges(judges, defaultJudge) {
-  if (judges !== void 0) {
-    if (judges.length === 0) {
-      throw new Error("defineAgentEval.evaluate: judges must not be empty");
-    }
-    return judges;
-  }
-  return [defaultJudge];
+	if (judges !== void 0) {
+		if (judges.length === 0) throw new Error("defineAgentEval.evaluate: judges must not be empty");
+		return judges;
+	}
+	return [defaultJudge];
 }
 function requirePositiveInteger(value, field) {
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`defineAgentEval: ${field} must be a positive integer`);
-  }
-  return value;
+	if (!Number.isInteger(value) || value < 1) throw new Error(`defineAgentEval: ${field} must be a positive integer`);
+	return value;
 }
-
-// src/contract/measured-comparison.ts
-import {
-  agentCandidateBenchmarkSuiteSchema,
-  agentCandidateBenchmarkTaskSchema,
-  agentCandidateBundleSchema,
-  agentCandidateEvaluationPolicySchema,
-  agentCandidateExperimentSchema,
-  agentImprovementMeasuredComparisonSchema,
-  candidateExecutionEvidenceSchema,
-  canonicalCandidateDigest,
-  omitTopLevelDigest
-} from "@tangle-network/agent-interface";
+//#endregion
+//#region src/contract/measured-comparison.ts
+/** Content-address one task before any measured execution can see it. */
 function sealCandidateBenchmarkTask(material) {
-  return agentCandidateBenchmarkTaskSchema.parse({
-    ...material,
-    digest: canonicalCandidateDigest(material)
-  });
+	return agentCandidateBenchmarkTaskSchema.parse({
+		...material,
+		digest: canonicalCandidateDigest(material)
+	});
 }
+/** Freeze task order, repetitions, and every seed before either arm runs. */
 function sealCandidateBenchmarkSuite(options) {
-  for (const task of options.tasks) verifyCandidateBenchmarkTask(task);
-  const material = {
-    kind: "agent-candidate-benchmark-suite",
-    digestAlgorithm: "rfc8785-sha256",
-    taskDigests: options.tasks.map((task) => task.digest),
-    reps: options.reps,
-    seeds: options.seeds
-  };
-  const suite = agentCandidateBenchmarkSuiteSchema.parse({
-    ...material,
-    digest: canonicalCandidateDigest(material)
-  });
-  return { suite, tasks: options.tasks };
-}
+	for (const task of options.tasks) verifyCandidateBenchmarkTask(task);
+	const material = {
+		kind: "agent-candidate-benchmark-suite",
+		digestAlgorithm: "rfc8785-sha256",
+		taskDigests: options.tasks.map((task) => task.digest),
+		reps: options.reps,
+		seeds: options.seeds
+	};
+	return {
+		suite: agentCandidateBenchmarkSuiteSchema.parse({
+			...material,
+			digest: canonicalCandidateDigest(material)
+		}),
+		tasks: options.tasks
+	};
+}
+/** Freeze both complete agent states and their exact held-out work. */
 function sealCandidateExperiment(material) {
-  const parsed = agentCandidateExperimentSchema.parse({
-    ...material,
-    digest: canonicalCandidateDigest(material)
-  });
-  return verifyCandidateExperiment(parsed);
+	return verifyCandidateExperiment(agentCandidateExperimentSchema.parse({
+		...material,
+		digest: canonicalCandidateDigest(material)
+	}));
 }
 function verifyCandidateExperiment(input) {
-  const experiment = agentCandidateExperimentSchema.parse(input);
-  verifySelfAddressed(experiment, "candidate experiment");
-  verifyBundle(experiment.baseline, "baseline bundle");
-  verifyBundle(experiment.candidate, "candidate bundle");
-  if (experiment.baseline.digest === experiment.candidate.digest) {
-    throw new Error("candidate experiment baseline and candidate bundles are identical");
-  }
-  verifyCandidateBenchmarkSuiteInputs(experiment.benchmark);
-  return experiment;
-}
+	const experiment = agentCandidateExperimentSchema.parse(input);
+	verifySelfAddressed(experiment, "candidate experiment");
+	verifyBundle(experiment.baseline, "baseline bundle");
+	verifyBundle(experiment.candidate, "candidate bundle");
+	if (experiment.baseline.digest === experiment.candidate.digest) throw new Error("candidate experiment baseline and candidate bundles are identical");
+	verifyCandidateBenchmarkSuiteInputs(experiment.benchmark);
+	return experiment;
+}
+/** Execute each signed cell for both arms. The callback is Runtime's one executor. */
 async function runCandidateExperiment(options) {
-  const experiment = verifyCandidateExperiment(options.experiment);
-  const { suite, tasks } = experiment.benchmark;
-  const maxConcurrency = options.maxConcurrency ?? 2;
-  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1) {
-    throw new Error("candidate experiment maxConcurrency must be a positive integer");
-  }
-  const measurements = new Array(
-    suite.taskDigests.length * suite.reps
-  );
-  let nextIndex = 0;
-  const lanes = Array.from({ length: Math.min(maxConcurrency, measurements.length) }, async () => {
-    while (true) {
-      if (options.signal?.aborted) throw abortError(options.signal);
-      const index = nextIndex;
-      nextIndex += 1;
-      if (index >= measurements.length) return;
-      const taskIndex = Math.floor(index / suite.reps);
-      const repetition = index % suite.reps;
-      const task = tasks[taskIndex];
-      const seed = suite.seeds[index];
-      if (!task || seed === void 0) {
-        throw new Error(`candidate experiment cell ${index} has no signed task or seed`);
-      }
-      const benchmarkCell = {
-        suiteDigest: suite.digest,
-        taskIndex,
-        repetition
-      };
-      const [baseline, candidate] = await Promise.all([
-        options.execute({
-          experiment,
-          arm: "baseline",
-          bundle: experiment.baseline,
-          task,
-          benchmarkCell,
-          seed,
-          ...options.signal ? { signal: options.signal } : {}
-        }),
-        options.execute({
-          experiment,
-          arm: "candidate",
-          bundle: experiment.candidate,
-          task,
-          benchmarkCell,
-          seed,
-          ...options.signal ? { signal: options.signal } : {}
-        })
-      ]);
-      const measurement = { baseline, candidate };
-      verifyMeasurement(experiment, measurement, index);
-      measurements[index] = measurement;
-    }
-  });
-  await Promise.all(lanes);
-  return measurements;
-}
+	const experiment = verifyCandidateExperiment(options.experiment);
+	const { suite, tasks } = experiment.benchmark;
+	const maxConcurrency = options.maxConcurrency ?? 2;
+	if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1) throw new Error("candidate experiment maxConcurrency must be a positive integer");
+	const measurements = new Array(suite.taskDigests.length * suite.reps);
+	let nextIndex = 0;
+	const lanes = Array.from({ length: Math.min(maxConcurrency, measurements.length) }, async () => {
+		while (true) {
+			if (options.signal?.aborted) throw abortError(options.signal);
+			const index = nextIndex;
+			nextIndex += 1;
+			if (index >= measurements.length) return;
+			const taskIndex = Math.floor(index / suite.reps);
+			const repetition = index % suite.reps;
+			const task = tasks[taskIndex];
+			const seed = suite.seeds[index];
+			if (!task || seed === void 0) throw new Error(`candidate experiment cell ${index} has no signed task or seed`);
+			const benchmarkCell = {
+				suiteDigest: suite.digest,
+				taskIndex,
+				repetition
+			};
+			const [baseline, candidate] = await Promise.all([options.execute({
+				experiment,
+				arm: "baseline",
+				bundle: experiment.baseline,
+				task,
+				benchmarkCell,
+				seed,
+				...options.signal ? { signal: options.signal } : {}
+			}), options.execute({
+				experiment,
+				arm: "candidate",
+				bundle: experiment.candidate,
+				task,
+				benchmarkCell,
+				seed,
+				...options.signal ? { signal: options.signal } : {}
+			})]);
+			const measurement = {
+				baseline,
+				candidate
+			};
+			verifyMeasurement(experiment, measurement, index);
+			measurements[index] = measurement;
+		}
+	});
+	await Promise.all(lanes);
+	return measurements;
+}
+/**
+* Calculate the shared paired decision from any complete receipt shape.
+*
+* Callers still own sealing their tasks, verifying each receipt against its
+* expected arm and state, and proving every expected cell exists. This function
+* only validates the projected measurements and derives their shared decision.
+*/
 function evaluatePairedMeasurements(options) {
-  if (options.measurements.length === 0) {
-    throw new Error("paired measurement evaluation requires at least one paired cell");
-  }
-  const additionalCostUsd = options.additionalCostUsd ?? 0;
-  if (!Number.isFinite(additionalCostUsd) || additionalCostUsd < 0) {
-    throw new Error("paired measurement evaluation additionalCostUsd must be a non-negative number");
-  }
-  if (typeof options.sharedScorerChannel !== "boolean") {
-    throw new Error("paired measurement evaluation sharedScorerChannel must be a boolean");
-  }
-  const policy = agentCandidateEvaluationPolicySchema.parse(options.policy);
-  const measurements = options.measurements.map(
-    (measurement, index) => projectPairedMeasurement(measurement, index, options.adapter)
-  );
-  const cellIds2 = measurements.map((measurement) => measurement.cellId);
-  if (new Set(cellIds2).size !== cellIds2.length) {
-    throw new Error("paired measurement evaluation cell ids must be unique");
-  }
-  const dimensions = sharedProjectedDimensions(measurements);
-  const baselineScores = measurements.map((measurement) => measurement.baseline.score);
-  const candidateScores = measurements.map((measurement) => measurement.candidate.score);
-  const {
-    confidenceLevel: confidence,
-    resamples,
-    bootstrapSeed,
-    deltaThreshold,
-    minProductiveRuns,
-    budgetUsd,
-    criticalDimensions,
-    regressionTolerance
-  } = policy;
-  const significance = heldoutSignificance(
-    { before: baselineScores, after: candidateScores, cellIds: cellIds2 },
-    {
-      confidence,
-      resamples,
-      seed: bootstrapSeed,
-      statistic: "mean",
-      deltaThreshold,
-      minProductiveRuns
-    }
-  );
-  const overall = measuredEstimate(baselineScores, candidateScores, {
-    confidence,
-    resamples,
-    seed: bootstrapSeed
-  });
-  const objectives = [
-    {
-      kind: "objective",
-      name: "benchmark-score",
-      direction: "higher-is-better",
-      unit: "score",
-      availability: "measured",
-      ...overall
-    },
-    ...dimensions.map((name, index) => ({
-      kind: "dimension",
-      objective: "benchmark-score",
-      name,
-      direction: "higher-is-better",
-      unit: "score",
-      availability: "measured",
-      ...measuredEstimate(
-        measurements.map((measurement) => dimensionScore(measurement.baseline, name)),
-        measurements.map((measurement) => dimensionScore(measurement.candidate, name)),
-        {
-          confidence,
-          resamples,
-          seed: bootstrapSeed + index + 1
-        }
-      )
-    }))
-  ];
-  const cost = measuredEstimate(
-    measurements.map((measurement) => measurement.baseline.costUsd),
-    measurements.map((measurement) => measurement.candidate.costUsd),
-    {
-      confidence,
-      resamples,
-      seed: bootstrapSeed + dimensions.length + 1
-    }
-  );
-  const latency = measuredEstimate(
-    measurements.map((measurement) => measurement.baseline.latencyMs),
-    measurements.map((measurement) => measurement.candidate.latencyMs),
-    {
-      confidence,
-      resamples,
-      seed: bootstrapSeed + dimensions.length + 2
-    }
-  );
-  objectives.push(
-    {
-      kind: "cost",
-      name: "cost",
-      direction: "lower-is-better",
-      unit: "usd",
-      availability: "measured",
-      ...cost
-    },
-    {
-      kind: "latency",
-      name: "latency",
-      direction: "lower-is-better",
-      unit: "milliseconds",
-      availability: "measured",
-      ...latency
-    }
-  );
-  const power = baselineScores.length >= 3 ? powerPreflight({
-    baselineComposites: baselineScores,
-    pairedN: baselineScores.length,
-    deltaThreshold,
-    confidence,
-    sharedScorerChannel: options.sharedScorerChannel
-  }) : void 0;
-  const powerSufficient = baselineScores.length >= minProductiveRuns && power !== void 0 && !power.underpowered;
-  const guardedDimensions = new Set(criticalDimensions);
-  const missingCriticalDimensions = criticalDimensions.filter(
-    (dimension) => !dimensions.includes(dimension)
-  );
-  const regressions = objectives.filter(
-    (objective) => objective.kind === "dimension" && guardedDimensions.has(objective.name) && objective.availability === "measured" && objective.confidenceInterval.lower < -regressionTolerance
-  );
-  const executionCostUsd = measurements.reduce(
-    (sum, measurement) => sum + measurement.baseline.costUsd + measurement.candidate.costUsd,
-    0
-  );
-  const executionDurationMs = measurements.reduce(
-    (sum, measurement) => sum + measurement.baseline.latencyMs + measurement.candidate.latencyMs,
-    0
-  );
-  const completedRuns = measurements.flatMap((measurement) => [
-    measurement.baseline,
-    measurement.candidate
-  ]);
-  const incompleteRuns = completedRuns.filter((run) => !run.completed);
-  const failedCandidateResults = measurements.filter((measurement) => !measurement.candidate.passed);
-  const totalCostUsd = executionCostUsd + additionalCostUsd;
-  const budgetPassed = budgetUsd === void 0 || totalCostUsd <= budgetUsd;
-  const checks = [
-    { name: "paired-significance", passed: significance.significant },
-    { name: "statistical-power", passed: powerSufficient },
-    { name: "all-runs-completed", passed: incompleteRuns.length === 0 },
-    { name: "candidate-task-pass", passed: failedCandidateResults.length === 0 },
-    {
-      name: "critical-dimensions",
-      passed: regressions.length === 0 && missingCriticalDimensions.length === 0
-    },
-    { name: "budget", passed: budgetPassed }
-  ];
-  const shipped = checks.every((check) => check.passed);
-  const reasons = [
-    ...significance.significant ? [] : [
-      significance.fewRuns ? `only ${significance.n} paired runs; ${minProductiveRuns} required` : `paired interval lower bound ${significance.bootstrap.low} did not clear ${deltaThreshold}`
-    ],
-    ...powerSufficient ? [] : [power?.recommendation ?? `need at least ${Math.max(3, minProductiveRuns)} paired runs`],
-    ...regressions.length === 0 ? [] : [`critical dimensions regressed: ${regressions.map((entry) => entry.name).join(", ")}`],
-    ...missingCriticalDimensions.length === 0 ? [] : [`critical dimensions missing: ${missingCriticalDimensions.join(", ")}`],
-    ...incompleteRuns.length === 0 ? [] : [`${incompleteRuns.length} benchmark executions did not exit successfully`],
-    ...failedCandidateResults.length === 0 ? [] : [`candidate failed ${failedCandidateResults.length} benchmark tasks`],
-    ...budgetPassed ? [] : [`total cost ${totalCostUsd} exceeded budget ${budgetUsd}`]
-  ];
-  return {
-    overall: {
-      name: "composite",
-      direction: "higher-is-better",
-      unit: "score",
-      ...overall
-    },
-    objectives,
-    decision: {
-      outcome: shipped ? "ship" : significance.fewRuns || !powerSufficient ? "need_more_work" : "hold",
-      reasons: reasons.length > 0 ? reasons : ["all measured checks passed"],
-      contributingChecks: checks
-    },
-    power: {
-      sufficient: powerSufficient,
-      n: baselineScores.length,
-      minimumDetectableDelta: power?.mde ?? 1,
-      confidenceLevel: confidence,
-      scaleAssumed: power?.scaleAssumed ?? true,
-      sharedScorerChannel: options.sharedScorerChannel,
-      reason: power?.recommendation ?? `need at least ${Math.max(3, minProductiveRuns)} paired runs`
-    },
-    executionCostUsd,
-    totalCostUsd,
-    executionDurationMs
-  };
-}
+	if (options.measurements.length === 0) throw new Error("paired measurement evaluation requires at least one paired cell");
+	const additionalCostUsd = options.additionalCostUsd ?? 0;
+	if (!Number.isFinite(additionalCostUsd) || additionalCostUsd < 0) throw new Error("paired measurement evaluation additionalCostUsd must be a non-negative number");
+	if (typeof options.sharedScorerChannel !== "boolean") throw new Error("paired measurement evaluation sharedScorerChannel must be a boolean");
+	const policy = agentCandidateEvaluationPolicySchema.parse(options.policy);
+	const measurements = options.measurements.map((measurement, index) => projectPairedMeasurement(measurement, index, options.adapter));
+	const cellIds = measurements.map((measurement) => measurement.cellId);
+	if (new Set(cellIds).size !== cellIds.length) throw new Error("paired measurement evaluation cell ids must be unique");
+	const dimensions = sharedProjectedDimensions(measurements);
+	const baselineScores = measurements.map((measurement) => measurement.baseline.score);
+	const candidateScores = measurements.map((measurement) => measurement.candidate.score);
+	const { confidenceLevel: confidence, resamples, bootstrapSeed, deltaThreshold, minProductiveRuns, budgetUsd, criticalDimensions, regressionTolerance } = policy;
+	const significance = heldoutSignificance({
+		before: baselineScores,
+		after: candidateScores,
+		cellIds
+	}, {
+		confidence,
+		resamples,
+		seed: bootstrapSeed,
+		statistic: "mean",
+		deltaThreshold,
+		minProductiveRuns
+	});
+	const overall = measuredEstimate(baselineScores, candidateScores, {
+		confidence,
+		resamples,
+		seed: bootstrapSeed
+	});
+	const objectives = [{
+		kind: "objective",
+		name: "benchmark-score",
+		direction: "higher-is-better",
+		unit: "score",
+		availability: "measured",
+		...overall
+	}, ...dimensions.map((name, index) => ({
+		kind: "dimension",
+		objective: "benchmark-score",
+		name,
+		direction: "higher-is-better",
+		unit: "score",
+		availability: "measured",
+		...measuredEstimate(measurements.map((measurement) => dimensionScore(measurement.baseline, name)), measurements.map((measurement) => dimensionScore(measurement.candidate, name)), {
+			confidence,
+			resamples,
+			seed: bootstrapSeed + index + 1
+		})
+	}))];
+	const cost = measuredEstimate(measurements.map((measurement) => measurement.baseline.costUsd), measurements.map((measurement) => measurement.candidate.costUsd), {
+		confidence,
+		resamples,
+		seed: bootstrapSeed + dimensions.length + 1
+	});
+	const latency = measuredEstimate(measurements.map((measurement) => measurement.baseline.latencyMs), measurements.map((measurement) => measurement.candidate.latencyMs), {
+		confidence,
+		resamples,
+		seed: bootstrapSeed + dimensions.length + 2
+	});
+	objectives.push({
+		kind: "cost",
+		name: "cost",
+		direction: "lower-is-better",
+		unit: "usd",
+		availability: "measured",
+		...cost
+	}, {
+		kind: "latency",
+		name: "latency",
+		direction: "lower-is-better",
+		unit: "milliseconds",
+		availability: "measured",
+		...latency
+	});
+	const power = baselineScores.length >= 3 ? powerPreflight({
+		baselineComposites: baselineScores,
+		pairedN: baselineScores.length,
+		deltaThreshold,
+		confidence,
+		sharedScorerChannel: options.sharedScorerChannel
+	}) : void 0;
+	const powerSufficient = baselineScores.length >= minProductiveRuns && power !== void 0 && !power.underpowered;
+	const guardedDimensions = new Set(criticalDimensions);
+	const missingCriticalDimensions = criticalDimensions.filter((dimension) => !dimensions.includes(dimension));
+	const regressions = objectives.filter((objective) => objective.kind === "dimension" && guardedDimensions.has(objective.name) && objective.availability === "measured" && objective.confidenceInterval.lower < -regressionTolerance);
+	const executionCostUsd = measurements.reduce((sum, measurement) => sum + measurement.baseline.costUsd + measurement.candidate.costUsd, 0);
+	const executionDurationMs = measurements.reduce((sum, measurement) => sum + measurement.baseline.latencyMs + measurement.candidate.latencyMs, 0);
+	const incompleteRuns = measurements.flatMap((measurement) => [measurement.baseline, measurement.candidate]).filter((run) => !run.completed);
+	const failedCandidateResults = measurements.filter((measurement) => !measurement.candidate.passed);
+	const totalCostUsd = executionCostUsd + additionalCostUsd;
+	const budgetPassed = budgetUsd === void 0 || totalCostUsd <= budgetUsd;
+	const checks = [
+		{
+			name: "paired-significance",
+			passed: significance.significant
+		},
+		{
+			name: "statistical-power",
+			passed: powerSufficient
+		},
+		{
+			name: "all-runs-completed",
+			passed: incompleteRuns.length === 0
+		},
+		{
+			name: "candidate-task-pass",
+			passed: failedCandidateResults.length === 0
+		},
+		{
+			name: "critical-dimensions",
+			passed: regressions.length === 0 && missingCriticalDimensions.length === 0
+		},
+		{
+			name: "budget",
+			passed: budgetPassed
+		}
+	];
+	const shipped = checks.every((check) => check.passed);
+	const reasons = [
+		...significance.significant ? [] : [significance.fewRuns ? `only ${significance.n} paired runs; ${minProductiveRuns} required` : `paired interval lower bound ${significance.bootstrap.low} did not clear ${deltaThreshold}`],
+		...powerSufficient ? [] : [power?.recommendation ?? `need at least ${Math.max(3, minProductiveRuns)} paired runs`],
+		...regressions.length === 0 ? [] : [`critical dimensions regressed: ${regressions.map((entry) => entry.name).join(", ")}`],
+		...missingCriticalDimensions.length === 0 ? [] : [`critical dimensions missing: ${missingCriticalDimensions.join(", ")}`],
+		...incompleteRuns.length === 0 ? [] : [`${incompleteRuns.length} benchmark executions did not exit successfully`],
+		...failedCandidateResults.length === 0 ? [] : [`candidate failed ${failedCandidateResults.length} benchmark tasks`],
+		...budgetPassed ? [] : [`total cost ${totalCostUsd} exceeded budget ${budgetUsd}`]
+	];
+	return {
+		overall: {
+			name: "composite",
+			direction: "higher-is-better",
+			unit: "score",
+			...overall
+		},
+		objectives,
+		decision: {
+			outcome: shipped ? "ship" : significance.fewRuns || !powerSufficient ? "need_more_work" : "hold",
+			reasons: reasons.length > 0 ? reasons : ["all measured checks passed"],
+			contributingChecks: checks
+		},
+		power: {
+			sufficient: powerSufficient,
+			n: baselineScores.length,
+			minimumDetectableDelta: power?.mde ?? 1,
+			confidenceLevel: confidence,
+			scaleAssumed: power?.scaleAssumed ?? true,
+			sharedScorerChannel: options.sharedScorerChannel,
+			reason: power?.recommendation ?? `need at least ${Math.max(3, minProductiveRuns)} paired runs`
+		},
+		executionCostUsd,
+		totalCostUsd,
+		executionDurationMs
+	};
+}
+/** Build the only publishable comparison: paired statistics over Runtime receipts. */
 function measuredComparisonFromCandidateExperiment(options) {
-  const experiment = verifyCandidateExperiment(options.experiment);
-  const measurements = options.measurements.map(
-    (measurement, index) => verifyMeasurement(experiment, measurement, index)
-  );
-  const expectedN = experiment.benchmark.suite.taskDigests.length * experiment.benchmark.suite.reps;
-  if (measurements.length !== expectedN) {
-    throw new Error(
-      `candidate experiment is incomplete (${measurements.length}/${expectedN} paired cells)`
-    );
-  }
-  verifyStableProfileMaterialization(measurements);
-  if (!options.runId.trim()) throw new Error("candidate experiment runId is required");
-  const searchCostUsd = options.searchCostUsd ?? 0;
-  const evaluation = evaluatePairedMeasurements({
-    measurements: measurements.map((measurement, index) => ({
-      cellId: cellIds(experiment)[index],
-      ...measurement
-    })),
-    policy: experiment.policy,
-    adapter: candidateExecutionEvidenceAdapter,
-    sharedScorerChannel: true,
-    additionalCostUsd: searchCostUsd
-  });
-  const diff = deriveCandidateBundleDiff(experiment);
-  const searchDurationMs = options.searchDurationMs ?? 0;
-  const totalCostUsd = evaluation.totalCostUsd;
-  const durationMs = evaluation.executionDurationMs + searchDurationMs;
-  const provisional = agentImprovementMeasuredComparisonSchema.parse({
-    kind: "agent-improvement-measured-comparison",
-    experiment,
-    measurements,
-    overall: evaluation.overall,
-    objectives: evaluation.objectives,
-    ...options.candidate ? { candidate: options.candidate } : {},
-    decision: evaluation.decision,
-    power: evaluation.power,
-    provenance: {
-      kind: "agent-eval-loop",
-      schema: "agent-candidate-experiment",
-      runId: options.runId,
-      recordDigest: canonicalCandidateDigest({}),
-      baselineContentHash: experiment.baseline.digest,
-      candidateContentHash: experiment.candidate.digest
-    },
-    diff,
-    evaluation: {
-      generationsExplored: options.generationsExplored ?? 0,
-      searchDurationMs,
-      executionDurationMs: evaluation.executionDurationMs,
-      durationMs,
-      searchCostUsd,
-      executionCostUsd: evaluation.executionCostUsd,
-      totalCostUsd
-    },
-    ...options.metadata ? { metadata: options.metadata } : {}
-  });
-  const { recordDigest: _recordDigest, ...provenance } = provisional.provenance;
-  return agentImprovementMeasuredComparisonSchema.parse({
-    ...provisional,
-    provenance: {
-      ...provenance,
-      recordDigest: canonicalCandidateDigest({ ...provisional, provenance })
-    }
-  });
-}
+	const experiment = verifyCandidateExperiment(options.experiment);
+	const measurements = options.measurements.map((measurement, index) => verifyMeasurement(experiment, measurement, index));
+	const expectedN = experiment.benchmark.suite.taskDigests.length * experiment.benchmark.suite.reps;
+	if (measurements.length !== expectedN) throw new Error(`candidate experiment is incomplete (${measurements.length}/${expectedN} paired cells)`);
+	verifyStableProfileMaterialization(measurements);
+	if (!options.runId.trim()) throw new Error("candidate experiment runId is required");
+	const searchCostUsd = options.searchCostUsd ?? 0;
+	const evaluation = evaluatePairedMeasurements({
+		measurements: measurements.map((measurement, index) => ({
+			cellId: cellIds(experiment)[index],
+			...measurement
+		})),
+		policy: experiment.policy,
+		adapter: candidateExecutionEvidenceAdapter,
+		sharedScorerChannel: true,
+		additionalCostUsd: searchCostUsd
+	});
+	const diff = deriveCandidateBundleDiff(experiment);
+	const searchDurationMs = options.searchDurationMs ?? 0;
+	const totalCostUsd = evaluation.totalCostUsd;
+	const durationMs = evaluation.executionDurationMs + searchDurationMs;
+	const provisional = agentImprovementMeasuredComparisonSchema.parse({
+		kind: "agent-improvement-measured-comparison",
+		experiment,
+		measurements,
+		overall: evaluation.overall,
+		objectives: evaluation.objectives,
+		...options.candidate ? { candidate: options.candidate } : {},
+		decision: evaluation.decision,
+		power: evaluation.power,
+		provenance: {
+			kind: "agent-eval-loop",
+			schema: "agent-candidate-experiment",
+			runId: options.runId,
+			recordDigest: canonicalCandidateDigest({}),
+			baselineContentHash: experiment.baseline.digest,
+			candidateContentHash: experiment.candidate.digest
+		},
+		diff,
+		evaluation: {
+			generationsExplored: options.generationsExplored ?? 0,
+			searchDurationMs,
+			executionDurationMs: evaluation.executionDurationMs,
+			durationMs,
+			searchCostUsd,
+			executionCostUsd: evaluation.executionCostUsd,
+			totalCostUsd
+		},
+		...options.metadata ? { metadata: options.metadata } : {}
+	});
+	const { recordDigest: _recordDigest, ...provenance } = provisional.provenance;
+	return agentImprovementMeasuredComparisonSchema.parse({
+		...provisional,
+		provenance: {
+			...provenance,
+			recordDigest: canonicalCandidateDigest({
+				...provisional,
+				provenance
+			})
+		}
+	});
+}
+/** Recompute every statistic and decision from the signed experiment receipts. */
 function verifyCandidateExperimentComparison(input) {
-  const comparison = agentImprovementMeasuredComparisonSchema.parse(input);
-  const recomputed = measuredComparisonFromCandidateExperiment({
-    experiment: comparison.experiment,
-    measurements: comparison.measurements,
-    runId: comparison.provenance.runId,
-    ...comparison.candidate ? { candidate: comparison.candidate } : {},
-    generationsExplored: comparison.evaluation.generationsExplored,
-    searchDurationMs: comparison.evaluation.searchDurationMs,
-    searchCostUsd: comparison.evaluation.searchCostUsd,
-    ...comparison.metadata ? { metadata: comparison.metadata } : {}
-  });
-  if (canonicalCandidateDigest(recomputed) !== canonicalCandidateDigest(comparison)) {
-    throw new Error("candidate experiment comparison does not match its Runtime receipts");
-  }
-  return comparison;
+	const comparison = agentImprovementMeasuredComparisonSchema.parse(input);
+	if (canonicalCandidateDigest(measuredComparisonFromCandidateExperiment({
+		experiment: comparison.experiment,
+		measurements: comparison.measurements,
+		runId: comparison.provenance.runId,
+		...comparison.candidate ? { candidate: comparison.candidate } : {},
+		generationsExplored: comparison.evaluation.generationsExplored,
+		searchDurationMs: comparison.evaluation.searchDurationMs,
+		searchCostUsd: comparison.evaluation.searchCostUsd,
+		...comparison.metadata ? { metadata: comparison.metadata } : {}
+	})) !== canonicalCandidateDigest(comparison)) throw new Error("candidate experiment comparison does not match its Runtime receipts");
+	return comparison;
 }
 function deriveCandidateBundleDiff(experiment) {
-  const surfaces = ["profile", "code", "execution", "knowledge", "memory"];
-  const changed = surfaces.flatMap((surface) => {
-    const baseline = experiment.baseline[surface] ?? null;
-    const candidate = experiment.candidate[surface] ?? null;
-    const baselineDigest = canonicalCandidateDigest(baseline);
-    const candidateDigest = canonicalCandidateDigest(candidate);
-    if (baselineDigest === candidateDigest) return [];
-    return [
-      [
-        `--- baseline/${surface} (${baselineDigest})`,
-        `+++ candidate/${surface} (${candidateDigest})`,
-        JSON.stringify({ baseline, candidate }, null, 2)
-      ].join("\n")
-    ];
-  });
-  if (changed.length === 0) {
-    throw new Error("candidate experiment has no changed candidate surface");
-  }
-  return changed.join("\n\n");
+	const changed = [
+		"profile",
+		"code",
+		"execution",
+		"knowledge",
+		"memory"
+	].flatMap((surface) => {
+		const baseline = experiment.baseline[surface] ?? null;
+		const candidate = experiment.candidate[surface] ?? null;
+		const baselineDigest = canonicalCandidateDigest(baseline);
+		const candidateDigest = canonicalCandidateDigest(candidate);
+		if (baselineDigest === candidateDigest) return [];
+		return [[
+			`--- baseline/${surface} (${baselineDigest})`,
+			`+++ candidate/${surface} (${candidateDigest})`,
+			JSON.stringify({
+				baseline,
+				candidate
+			}, null, 2)
+		].join("\n")];
+	});
+	if (changed.length === 0) throw new Error("candidate experiment has no changed candidate surface");
+	return changed.join("\n\n");
 }
 function verifyCandidateBenchmarkTask(input) {
-  const task = agentCandidateBenchmarkTaskSchema.parse(input);
-  verifySelfAddressed(task, "candidate benchmark task");
-  return task;
+	const task = agentCandidateBenchmarkTaskSchema.parse(input);
+	verifySelfAddressed(task, "candidate benchmark task");
+	return task;
 }
 function verifyCandidateBenchmarkSuiteInputs(input) {
-  if (input === null || typeof input !== "object" || Array.isArray(input)) {
-    throw new Error("candidate benchmark suite inputs must be an object");
-  }
-  const candidate = input;
-  const suite = verifyCandidateBenchmarkSuite(candidate.suite);
-  if (!Array.isArray(candidate.tasks) || candidate.tasks.length !== suite.taskDigests.length) {
-    throw new Error("candidate benchmark suite task count does not match its signed digests");
-  }
-  candidate.tasks.forEach((task, index) => {
-    const verified = verifyCandidateBenchmarkTask(task);
-    if (verified.digest !== suite.taskDigests[index]) {
-      throw new Error(`candidate benchmark task ${index} does not match the signed suite`);
-    }
-  });
-  return { suite, tasks: candidate.tasks };
+	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("candidate benchmark suite inputs must be an object");
+	const candidate = input;
+	const suite = verifyCandidateBenchmarkSuite(candidate.suite);
+	if (!Array.isArray(candidate.tasks) || candidate.tasks.length !== suite.taskDigests.length) throw new Error("candidate benchmark suite task count does not match its signed digests");
+	candidate.tasks.forEach((task, index) => {
+		if (verifyCandidateBenchmarkTask(task).digest !== suite.taskDigests[index]) throw new Error(`candidate benchmark task ${index} does not match the signed suite`);
+	});
+	return {
+		suite,
+		tasks: candidate.tasks
+	};
 }
 function verifyCandidateBenchmarkSuite(input) {
-  const suite = agentCandidateBenchmarkSuiteSchema.parse(input);
-  verifySelfAddressed(suite, "candidate benchmark suite");
-  return suite;
+	const suite = agentCandidateBenchmarkSuiteSchema.parse(input);
+	verifySelfAddressed(suite, "candidate benchmark suite");
+	return suite;
 }
 function verifyBundle(input, label) {
-  const bundle = agentCandidateBundleSchema.parse(input);
-  verifySelfAddressed(bundle, label);
-  return bundle;
+	const bundle = agentCandidateBundleSchema.parse(input);
+	verifySelfAddressed(bundle, label);
+	return bundle;
 }
 function verifyMeasurement(experiment, input, index) {
-  const suite = experiment.benchmark.suite;
-  const taskIndex = Math.floor(index / suite.reps);
-  const repetition = index % suite.reps;
-  const task = experiment.benchmark.tasks[taskIndex];
-  const seed = suite.seeds[index];
-  if (!task || seed === void 0) {
-    throw new Error(`candidate experiment measurement ${index} is outside the signed suite`);
-  }
-  const baseline = verifyExecutionEvidence(input.baseline);
-  const candidate = verifyExecutionEvidence(input.candidate);
-  for (const [arm, evidence] of [
-    ["baseline", baseline],
-    ["candidate", candidate]
-  ]) {
-    const bundle = experiment[arm];
-    const materialization = evidence.materializationReceipt;
-    const plan = materialization.executionPlan.material;
-    const runCell = plan.runCell;
-    verifySelfAddressed(runCell, "candidate run cell");
-    if (runCell.experimentDigest !== experiment.digest || runCell.arm !== arm || runCell.bundleDigest !== bundle.digest || runCell.suiteDigest !== suite.digest || runCell.taskDigest !== task.digest || runCell.taskIndex !== taskIndex || runCell.repetition !== repetition || runCell.seed !== seed || runCell.attempt > task.attempt.maxAttempts || materialization.bundleDigest !== bundle.digest || materialization.benchmark.suite.digest !== suite.digest || materialization.benchmark.task.digest !== task.digest || materialization.codeKind !== bundle.code.kind || materialization.profileActivation.profilePlan.material.sourceProfileDigest !== canonicalCandidateDigest(bundle.profile) || evidence.receipt.runCellDigest !== runCell.digest || JSON.stringify(materialization.resolvedModel) !== JSON.stringify(task.model)) {
-      throw new Error(`candidate experiment measurement ${index} substituted its ${arm} arm`);
-    }
-    verifyTaskOutcome(task, evidence, index, arm);
-  }
-  const baselinePlan = baseline.materializationReceipt.executionPlan.material;
-  const candidatePlan = candidate.materializationReceipt.executionPlan.material;
-  if (baselinePlan.executionId === candidatePlan.executionId || baselinePlan.runCell.digest === candidatePlan.runCell.digest || baseline.materializationReceipt.digest === candidate.materializationReceipt.digest || baseline.receipt.digest === candidate.receipt.digest || baseline.digest === candidate.digest) {
-    throw new Error(`candidate experiment measurement ${index} reused one execution across arms`);
-  }
-  return { baseline, candidate };
+	const suite = experiment.benchmark.suite;
+	const taskIndex = Math.floor(index / suite.reps);
+	const repetition = index % suite.reps;
+	const task = experiment.benchmark.tasks[taskIndex];
+	const seed = suite.seeds[index];
+	if (!task || seed === void 0) throw new Error(`candidate experiment measurement ${index} is outside the signed suite`);
+	const baseline = verifyExecutionEvidence(input.baseline);
+	const candidate = verifyExecutionEvidence(input.candidate);
+	for (const [arm, evidence] of [["baseline", baseline], ["candidate", candidate]]) {
+		const bundle = experiment[arm];
+		const materialization = evidence.materializationReceipt;
+		const runCell = materialization.executionPlan.material.runCell;
+		verifySelfAddressed(runCell, "candidate run cell");
+		if (runCell.experimentDigest !== experiment.digest || runCell.arm !== arm || runCell.bundleDigest !== bundle.digest || runCell.suiteDigest !== suite.digest || runCell.taskDigest !== task.digest || runCell.taskIndex !== taskIndex || runCell.repetition !== repetition || runCell.seed !== seed || runCell.attempt > task.attempt.maxAttempts || materialization.bundleDigest !== bundle.digest || materialization.benchmark.suite.digest !== suite.digest || materialization.benchmark.task.digest !== task.digest || materialization.codeKind !== bundle.code.kind || materialization.profileActivation.profilePlan.material.sourceProfileDigest !== canonicalCandidateDigest(bundle.profile) || evidence.receipt.runCellDigest !== runCell.digest || JSON.stringify(materialization.resolvedModel) !== JSON.stringify(task.model)) throw new Error(`candidate experiment measurement ${index} substituted its ${arm} arm`);
+		verifyTaskOutcome(task, evidence, index, arm);
+	}
+	const baselinePlan = baseline.materializationReceipt.executionPlan.material;
+	const candidatePlan = candidate.materializationReceipt.executionPlan.material;
+	if (baselinePlan.executionId === candidatePlan.executionId || baselinePlan.runCell.digest === candidatePlan.runCell.digest || baseline.materializationReceipt.digest === candidate.materializationReceipt.digest || baseline.receipt.digest === candidate.receipt.digest || baseline.digest === candidate.digest) throw new Error(`candidate experiment measurement ${index} reused one execution across arms`);
+	return {
+		baseline,
+		candidate
+	};
 }
 function verifyExecutionEvidence(input) {
-  const evidence = candidateExecutionEvidenceSchema.parse(input);
-  verifySelfAddressed(evidence, "candidate execution evidence");
-  verifySelfAddressed(evidence.materializationReceipt, "candidate materialization receipt");
-  verifySelfAddressed(
-    evidence.materializationReceipt.profileActivation,
-    "candidate profile activation"
-  );
-  verifyMaterialAddressed(
-    evidence.materializationReceipt.profileActivation.profilePlan,
-    "candidate profile plan"
-  );
-  verifyMaterialAddressed(evidence.materializationReceipt.executionPlan, "candidate execution plan");
-  verifySelfAddressed(evidence.receipt, "candidate run receipt");
-  verifyMaterialAddressed(evidence.receipt.modelSettlement, "candidate model settlement");
-  verifyMaterialAddressed(evidence.receipt.taskOutcome, "candidate task outcome");
-  verifyMaterialAddressed(evidence.receipt.benchmarkResult, "candidate benchmark result");
-  return evidence;
+	const evidence = candidateExecutionEvidenceSchema.parse(input);
+	verifySelfAddressed(evidence, "candidate execution evidence");
+	verifySelfAddressed(evidence.materializationReceipt, "candidate materialization receipt");
+	verifySelfAddressed(evidence.materializationReceipt.profileActivation, "candidate profile activation");
+	verifyMaterialAddressed(evidence.materializationReceipt.profileActivation.profilePlan, "candidate profile plan");
+	verifyMaterialAddressed(evidence.materializationReceipt.executionPlan, "candidate execution plan");
+	verifySelfAddressed(evidence.receipt, "candidate run receipt");
+	verifyMaterialAddressed(evidence.receipt.modelSettlement, "candidate model settlement");
+	verifyMaterialAddressed(evidence.receipt.taskOutcome, "candidate task outcome");
+	verifyMaterialAddressed(evidence.receipt.benchmarkResult, "candidate benchmark result");
+	return evidence;
 }
 function verifySelfAddressed(document, label) {
-  if (canonicalCandidateDigest(omitTopLevelDigest(document)) !== document.digest) {
-    throw new Error(`${label} digest is invalid`);
-  }
+	if (canonicalCandidateDigest(omitTopLevelDigest(document)) !== document.digest) throw new Error(`${label} digest is invalid`);
 }
 function verifyTaskOutcome(task, evidence, index, arm) {
-  const outcome = evidence.receipt.taskOutcome.material.outcome;
-  const result = evidence.receipt.benchmarkResult.material;
-  const prefix = `candidate experiment measurement ${index} ${arm}`;
-  if (result.evidence.sha256 === task.grader.artifact.sha256) {
-    throw new Error(`${prefix} reused grader bytes as grading evidence`);
-  }
-  const usage = combinedUsage(evidence);
-  const usageChecks = [
-    [usage.modelCalls, task.limits.maxModelCalls, "model calls"],
-    [usage.inputTokens, task.limits.maxInputTokens, "input tokens"],
-    [usage.outputTokens, task.limits.maxOutputTokens, "output tokens"],
-    [usage.costUsdNanos, Math.round(task.limits.maxCostUsd * 1e9), "cost"]
-  ];
-  for (const [actual, maximum, label] of usageChecks) {
-    if (actual > maximum) {
-      throw new Error(`${prefix} ${label} ${actual} exceeds the signed limit ${maximum}`);
-    }
-  }
-  if (outcome.kind !== task.outcome.kind) {
-    throw new Error(`${prefix} returned an outcome outside the signed task contract`);
-  }
-  if (task.outcome.kind === "output") {
-    if (outcome.kind !== "output" || outcome.spec.mediaType !== task.outcome.mediaType || outcome.spec.maxBytes !== task.outcome.maxBytes) {
-      throw new Error(`${prefix} changed the signed output contract`);
-    }
-    return;
-  }
-  const repository = task.repository;
-  if (outcome.kind !== "workspace" || repository === void 0 || outcome.baseRepository.identity !== repository.identity || outcome.baseRepository.rootIdentity !== repository.rootIdentity || outcome.baseRepository.commit !== repository.baseCommit || outcome.baseRepository.tree !== repository.baseTree) {
-    throw new Error(`${prefix} did not start from the signed repository state`);
-  }
+	const outcome = evidence.receipt.taskOutcome.material.outcome;
+	const result = evidence.receipt.benchmarkResult.material;
+	const prefix = `candidate experiment measurement ${index} ${arm}`;
+	if (result.evidence.sha256 === task.grader.artifact.sha256) throw new Error(`${prefix} reused grader bytes as grading evidence`);
+	const usage = combinedUsage(evidence);
+	const usageChecks = [
+		[
+			usage.modelCalls,
+			task.limits.maxModelCalls,
+			"model calls"
+		],
+		[
+			usage.inputTokens,
+			task.limits.maxInputTokens,
+			"input tokens"
+		],
+		[
+			usage.outputTokens,
+			task.limits.maxOutputTokens,
+			"output tokens"
+		],
+		[
+			usage.costUsdNanos,
+			Math.round(task.limits.maxCostUsd * 1e9),
+			"cost"
+		]
+	];
+	for (const [actual, maximum, label] of usageChecks) if (actual > maximum) throw new Error(`${prefix} ${label} ${actual} exceeds the signed limit ${maximum}`);
+	if (outcome.kind !== task.outcome.kind) throw new Error(`${prefix} returned an outcome outside the signed task contract`);
+	if (task.outcome.kind === "output") {
+		if (outcome.kind !== "output" || outcome.spec.mediaType !== task.outcome.mediaType || outcome.spec.maxBytes !== task.outcome.maxBytes) throw new Error(`${prefix} changed the signed output contract`);
+		return;
+	}
+	const repository = task.repository;
+	if (outcome.kind !== "workspace" || repository === void 0 || outcome.baseRepository.identity !== repository.identity || outcome.baseRepository.rootIdentity !== repository.rootIdentity || outcome.baseRepository.commit !== repository.baseCommit || outcome.baseRepository.tree !== repository.baseTree) throw new Error(`${prefix} did not start from the signed repository state`);
 }
 function verifyStableProfileMaterialization(measurements) {
-  for (const arm of ["baseline", "candidate"]) {
-    const expected = measurements[0]?.[arm].materializationReceipt.profileActivation;
-    if (!expected) throw new Error("candidate experiment contains no profile materialization");
-    const expectedDigest = canonicalCandidateDigest({
-      profilePlanDigest: expected.profilePlan.digest,
-      files: expected.files
-    });
-    for (const [index, measurement] of measurements.entries()) {
-      const activation = measurement[arm].materializationReceipt.profileActivation;
-      if (canonicalCandidateDigest({
-        profilePlanDigest: activation.profilePlan.digest,
-        files: activation.files
-      }) !== expectedDigest) {
-        throw new Error(
-          `candidate experiment measurement ${index} ${arm} materialized a different profile`
-        );
-      }
-    }
-  }
+	for (const arm of ["baseline", "candidate"]) {
+		const expected = measurements[0]?.[arm].materializationReceipt.profileActivation;
+		if (!expected) throw new Error("candidate experiment contains no profile materialization");
+		const expectedDigest = canonicalCandidateDigest({
+			profilePlanDigest: expected.profilePlan.digest,
+			files: expected.files
+		});
+		for (const [index, measurement] of measurements.entries()) {
+			const activation = measurement[arm].materializationReceipt.profileActivation;
+			if (canonicalCandidateDigest({
+				profilePlanDigest: activation.profilePlan.digest,
+				files: activation.files
+			}) !== expectedDigest) throw new Error(`candidate experiment measurement ${index} ${arm} materialized a different profile`);
+		}
+	}
 }
 function completedSuccessfully(evidence) {
-  const termination = evidence.receipt.termination;
-  return termination.kind === "exit" && termination.exitCode === 0;
+	const termination = evidence.receipt.termination;
+	return termination.kind === "exit" && termination.exitCode === 0;
 }
 function verifyMaterialAddressed(evidence, label) {
-  if (canonicalCandidateDigest(evidence.material) !== evidence.digest) {
-    throw new Error(`${label} digest is invalid`);
-  }
+	if (canonicalCandidateDigest(evidence.material) !== evidence.digest) throw new Error(`${label} digest is invalid`);
 }
 function projectPairedMeasurement(measurement, index, adapter) {
-  if (typeof measurement.cellId !== "string" || !measurement.cellId.trim()) {
-    throw new Error(`paired measurement ${index} requires a cell id`);
-  }
-  return {
-    cellId: measurement.cellId,
-    baseline: projectRun(measurement.baseline, adapter, `paired measurement ${index} baseline`),
-    candidate: projectRun(measurement.candidate, adapter, `paired measurement ${index} candidate`)
-  };
+	if (typeof measurement.cellId !== "string" || !measurement.cellId.trim()) throw new Error(`paired measurement ${index} requires a cell id`);
+	return {
+		cellId: measurement.cellId,
+		baseline: projectRun(measurement.baseline, adapter, `paired measurement ${index} baseline`),
+		candidate: projectRun(measurement.candidate, adapter, `paired measurement ${index} candidate`)
+	};
 }
 function projectRun(run, adapter, label) {
-  const suppliedDimensions = adapter.dimensions(run);
-  if (!Array.isArray(suppliedDimensions)) {
-    throw new Error(`${label} dimensions must be an array`);
-  }
-  const dimensions = /* @__PURE__ */ new Map();
-  for (const dimension of suppliedDimensions) {
-    if (typeof dimension.name !== "string" || !dimension.name.trim()) {
-      throw new Error(`${label} contains an unnamed dimension`);
-    }
-    if (dimensions.has(dimension.name)) {
-      throw new Error(`${label} repeats dimension '${dimension.name}'`);
-    }
-    dimensions.set(dimension.name, finiteMeasurement(dimension.score, `${label} ${dimension.name}`));
-  }
-  const completed = adapter.completed(run);
-  const passed = adapter.passed(run);
-  if (typeof completed !== "boolean" || typeof passed !== "boolean") {
-    throw new Error(`${label} completion and pass values must be booleans`);
-  }
-  return {
-    score: finiteMeasurement(adapter.score(run), `${label} score`),
-    dimensions,
-    costUsd: nonNegativeMeasurement(adapter.costUsd(run), `${label} cost`),
-    latencyMs: nonNegativeMeasurement(adapter.latencyMs(run), `${label} latency`),
-    completed,
-    passed
-  };
+	const suppliedDimensions = adapter.dimensions(run);
+	if (!Array.isArray(suppliedDimensions)) throw new Error(`${label} dimensions must be an array`);
+	const dimensions = /* @__PURE__ */ new Map();
+	for (const dimension of suppliedDimensions) {
+		if (typeof dimension.name !== "string" || !dimension.name.trim()) throw new Error(`${label} contains an unnamed dimension`);
+		if (dimensions.has(dimension.name)) throw new Error(`${label} repeats dimension '${dimension.name}'`);
+		dimensions.set(dimension.name, finiteMeasurement(dimension.score, `${label} ${dimension.name}`));
+	}
+	const completed = adapter.completed(run);
+	const passed = adapter.passed(run);
+	if (typeof completed !== "boolean" || typeof passed !== "boolean") throw new Error(`${label} completion and pass values must be booleans`);
+	return {
+		score: finiteMeasurement(adapter.score(run), `${label} score`),
+		dimensions,
+		costUsd: nonNegativeMeasurement(adapter.costUsd(run), `${label} cost`),
+		latencyMs: nonNegativeMeasurement(adapter.latencyMs(run), `${label} latency`),
+		completed,
+		passed
+	};
 }
 function sharedProjectedDimensions(measurements) {
-  const expected = [...measurements[0].baseline.dimensions.keys()];
-  for (const [index, measurement] of measurements.entries()) {
-    for (const [arm, run] of [
-      ["baseline", measurement.baseline],
-      ["candidate", measurement.candidate]
-    ]) {
-      const actual = [...run.dimensions.keys()];
-      if (JSON.stringify(actual) !== JSON.stringify(expected)) {
-        throw new Error(`paired measurement ${index} ${arm} dimensions do not match the suite`);
-      }
-    }
-  }
-  return expected;
+	const expected = [...measurements[0].baseline.dimensions.keys()];
+	for (const [index, measurement] of measurements.entries()) for (const [arm, run] of [["baseline", measurement.baseline], ["candidate", measurement.candidate]]) {
+		const actual = [...run.dimensions.keys()];
+		if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error(`paired measurement ${index} ${arm} dimensions do not match the suite`);
+	}
+	return expected;
 }
 function dimensionScore(run, name) {
-  const value = run.dimensions.get(name);
-  if (value === void 0) throw new Error(`paired measurement is missing dimension '${name}'`);
-  return value;
+	const value = run.dimensions.get(name);
+	if (value === void 0) throw new Error(`paired measurement is missing dimension '${name}'`);
+	return value;
 }
 function measuredEstimate(baseline, candidate, options) {
-  const bootstrap = pairedBootstrap(baseline, candidate, {
-    confidence: options.confidence,
-    resamples: options.resamples,
-    statistic: "mean",
-    seed: options.seed
-  });
-  const baselineMean = mean(baseline);
-  const candidateMean = mean(candidate);
-  const delta = candidateMean - baselineMean;
-  return {
-    baseline: baselineMean,
-    candidate: candidateMean,
-    delta,
-    confidenceInterval: {
-      level: bootstrap.confidence,
-      lower: Math.min(bootstrap.low, delta),
-      upper: Math.max(bootstrap.high, delta),
-      method: "paired-bootstrap",
-      statistic: "mean",
-      resamples: bootstrap.resamples
-    },
-    n: bootstrap.n
-  };
+	const bootstrap = pairedBootstrap(baseline, candidate, {
+		confidence: options.confidence,
+		resamples: options.resamples,
+		statistic: "mean",
+		seed: options.seed
+	});
+	const baselineMean = mean(baseline);
+	const candidateMean = mean(candidate);
+	const delta = candidateMean - baselineMean;
+	return {
+		baseline: baselineMean,
+		candidate: candidateMean,
+		delta,
+		confidenceInterval: {
+			level: bootstrap.confidence,
+			lower: Math.min(bootstrap.low, delta),
+			upper: Math.max(bootstrap.high, delta),
+			method: "paired-bootstrap",
+			statistic: "mean",
+			resamples: bootstrap.resamples
+		},
+		n: bootstrap.n
+	};
 }
 function finiteMeasurement(value, label) {
-  if (!Number.isFinite(value)) throw new Error(`${label} must be finite`);
-  return value;
+	if (!Number.isFinite(value)) throw new Error(`${label} must be finite`);
+	return value;
 }
 function nonNegativeMeasurement(value, label) {
-  if (!Number.isFinite(value) || value < 0) throw new Error(`${label} must be non-negative`);
-  return value;
-}
-var candidateExecutionEvidenceAdapter = {
-  score: (evidence) => evidence.receipt.benchmarkResult.material.score,
-  dimensions: (evidence) => evidence.receipt.benchmarkResult.material.dimensions,
-  costUsd: costFromEvidence,
-  latencyMs: latencyFromEvidence,
-  completed: completedSuccessfully,
-  passed: (evidence) => evidence.receipt.benchmarkResult.material.passed
+	if (!Number.isFinite(value) || value < 0) throw new Error(`${label} must be non-negative`);
+	return value;
+}
+const candidateExecutionEvidenceAdapter = {
+	score: (evidence) => evidence.receipt.benchmarkResult.material.score,
+	dimensions: (evidence) => evidence.receipt.benchmarkResult.material.dimensions,
+	costUsd: costFromEvidence,
+	latencyMs: latencyFromEvidence,
+	completed: completedSuccessfully,
+	passed: (evidence) => evidence.receipt.benchmarkResult.material.passed
 };
 function costFromEvidence(evidence) {
-  return combinedUsage(evidence).costUsdNanos / 1e9;
+	return combinedUsage(evidence).costUsdNanos / 1e9;
 }
 function latencyFromEvidence(evidence) {
-  return evidence.receipt.timing.durationMs + evidence.receipt.benchmarkResult.material.grading.timing.durationMs;
+	return evidence.receipt.timing.durationMs + evidence.receipt.benchmarkResult.material.grading.timing.durationMs;
 }
 function combinedUsage(evidence) {
-  const candidate = evidence.receipt.modelSettlement.material.usage;
-  const grader = evidence.receipt.benchmarkResult.material.grading.usage;
-  return {
-    inputTokens: candidate.inputTokens + grader.inputTokens,
-    outputTokens: candidate.outputTokens + grader.outputTokens,
-    cachedInputTokens: candidate.cachedInputTokens + grader.cachedInputTokens,
-    reasoningTokens: candidate.reasoningTokens + grader.reasoningTokens,
-    modelCalls: candidate.modelCalls + grader.modelCalls,
-    costUsdNanos: candidate.costUsdNanos + grader.costUsdNanos
-  };
+	const candidate = evidence.receipt.modelSettlement.material.usage;
+	const grader = evidence.receipt.benchmarkResult.material.grading.usage;
+	return {
+		inputTokens: candidate.inputTokens + grader.inputTokens,
+		outputTokens: candidate.outputTokens + grader.outputTokens,
+		cachedInputTokens: candidate.cachedInputTokens + grader.cachedInputTokens,
+		reasoningTokens: candidate.reasoningTokens + grader.reasoningTokens,
+		modelCalls: candidate.modelCalls + grader.modelCalls,
+		costUsdNanos: candidate.costUsdNanos + grader.costUsdNanos
+	};
 }
 function cellIds(experiment) {
-  const { suite, tasks } = experiment.benchmark;
-  return suite.seeds.map((_, index) => {
-    const taskIndex = Math.floor(index / suite.reps);
-    const repetition = index % suite.reps;
-    return `${tasks[taskIndex]?.scenario.id ?? taskIndex}:${repetition}`;
-  });
+	const { suite, tasks } = experiment.benchmark;
+	return suite.seeds.map((_, index) => {
+		const taskIndex = Math.floor(index / suite.reps);
+		const repetition = index % suite.reps;
+		return `${tasks[taskIndex]?.scenario.id ?? taskIndex}:${repetition}`;
+	});
 }
 function mean(values) {
-  if (values.length === 0) throw new Error("candidate experiment requires measured values");
-  return values.reduce((sum, value) => sum + value, 0) / values.length;
+	if (values.length === 0) throw new Error("candidate experiment requires measured values");
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
 }
 function abortError(signal) {
-  return signal.reason instanceof Error ? signal.reason : new Error("candidate experiment aborted");
-}
-
-// src/contract/eval-reporting-suite.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, join as join2 } from "path";
-
-// src/contract/intake/run-record-dir.ts
-import { readdir, readFile, stat } from "fs/promises";
-import { join } from "path";
-var ANALYSIS_ARTIFACT = "analysis.json";
+	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("candidate experiment aborted");
+}
+//#endregion
+//#region src/contract/intake/run-record-dir.ts
+/**
+* # `intake/run-record-dir` — load a directory or file of `RunRecord`s.
+*
+* The on-disk counterpart to the in-memory intake adapters: point it at a
+* single `.json` (array) / `.jsonl` (one record per line) file or at a
+* directory of such files, and it returns the substrate-canonical
+* `RunRecord[]` ready for `analyzeRuns({ runs })`.
+*
+* Validation is at the boundary: each parsed object goes through
+* `parseRunRecordSafe`. By default an invalid record fails loud with its
+* file + index; pass `onInvalid: 'collect'` to keep the valid records and
+* receive the rejects as structured diagnostics instead.
+*/
+const ANALYSIS_ARTIFACT$1 = "analysis.json";
 function defaultInclude(fileName) {
-  if (fileName === ANALYSIS_ARTIFACT) return false;
-  return fileName.endsWith(".json") || fileName.endsWith(".jsonl");
-}
+	if (fileName === ANALYSIS_ARTIFACT$1) return false;
+	return fileName.endsWith(".json") || fileName.endsWith(".jsonl");
+}
+/**
+* Resolve a file or directory path into validated `RunRecord[]`.
+*
+* A `.json` file must parse to a top-level array; a `.jsonl` file is one
+* record per non-empty line. Directories are read shallowly by default
+* (set `recursive` to descend); the `analysis.json` output artifact is
+* always excluded.
+*/
 async function fromRunRecordDir(path, options = {}) {
-  const onInvalid = options.onInvalid ?? "throw";
-  const include = options.include ?? defaultInclude;
-  const stats = await stat(path);
-  const filePaths = stats.isDirectory() ? await collectFiles(path, include, options.recursive ?? false) : [path];
-  const runs = [];
-  const rejected = [];
-  for (const file of filePaths) {
-    const raw = await parseRecordFile(file);
-    for (const { index, value } of raw) {
-      const parsed = parseRunRecordSafe(value);
-      if (parsed.ok) {
-        runs.push(parsed.value);
-        continue;
-      }
-      const rejection = { file, index, reason: parsed.error.message };
-      if (onInvalid === "throw") {
-        throw new Error(
-          `fromRunRecordDir: invalid RunRecord in '${file}' at index ${index}: ${parsed.error.message}`
-        );
-      }
-      rejected.push(rejection);
-    }
-  }
-  return { runs, rejected, files: filePaths };
-}
+	const onInvalid = options.onInvalid ?? "throw";
+	const include = options.include ?? defaultInclude;
+	const filePaths = (await stat(path)).isDirectory() ? await collectFiles(path, include, options.recursive ?? false) : [path];
+	const runs = [];
+	const rejected = [];
+	for (const file of filePaths) {
+		const raw = await parseRecordFile(file);
+		for (const { index, value } of raw) {
+			const parsed = parseRunRecordSafe(value);
+			if (parsed.ok) {
+				runs.push(parsed.value);
+				continue;
+			}
+			const rejection = {
+				file,
+				index,
+				reason: parsed.error.message
+			};
+			if (onInvalid === "throw") throw new Error(`fromRunRecordDir: invalid RunRecord in '${file}' at index ${index}: ${parsed.error.message}`);
+			rejected.push(rejection);
+		}
+	}
+	return {
+		runs,
+		rejected,
+		files: filePaths
+	};
+}
+/** Read a single `.json` / `.jsonl` file into `{ index, value }` pairs. A
+*  malformed JSONL line throws with its line number rather than being skipped —
+*  silent line-dropping is how corpora quietly shrink. */
 async function parseRecordFile(file) {
-  const text = await readFile(file, "utf8");
-  const trimmed = text.trim();
-  if (trimmed.length === 0) return [];
-  if (trimmed.startsWith("[")) {
-    const parsed = JSON.parse(trimmed);
-    if (!Array.isArray(parsed)) {
-      throw new Error(`fromRunRecordDir: file '${file}' did not parse to an array`);
-    }
-    return parsed.map((value, index) => ({ index, value }));
-  }
-  const out = [];
-  const lines = trimmed.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-    if (line.length === 0) continue;
-    try {
-      out.push({ index: i, value: JSON.parse(line) });
-    } catch (err) {
-      throw new Error(
-        `fromRunRecordDir: file '${file}' line ${i + 1} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  return out;
-}
+	const trimmed = (await readFile(file, "utf8")).trim();
+	if (trimmed.length === 0) return [];
+	if (trimmed.startsWith("[")) {
+		const parsed = JSON.parse(trimmed);
+		if (!Array.isArray(parsed)) throw new Error(`fromRunRecordDir: file '${file}' did not parse to an array`);
+		return parsed.map((value, index) => ({
+			index,
+			value
+		}));
+	}
+	const out = [];
+	const lines = trimmed.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].trim();
+		if (line.length === 0) continue;
+		try {
+			out.push({
+				index: i,
+				value: JSON.parse(line)
+			});
+		} catch (err) {
+			throw new Error(`fromRunRecordDir: file '${file}' line ${i + 1} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return out;
+}
+/** Sorted file list under a directory, filtered by `include`. Sorted so the
+*  resulting `RunRecord` order — and any downstream fingerprint — is stable
+*  across filesystems. */
 async function collectFiles(dir, include, recursive) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  const files = [];
-  const subdirs = [];
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      if (recursive) subdirs.push(join(dir, entry.name));
-      continue;
-    }
-    if (include(entry.name)) files.push(join(dir, entry.name));
-  }
-  files.sort();
-  subdirs.sort();
-  for (const sub of subdirs) {
-    files.push(...await collectFiles(sub, include, recursive));
-  }
-  return files;
-}
-
-// src/contract/eval-reporting-suite.ts
-var ANALYSIS_ARTIFACT2 = "analysis.json";
+	const entries = await readdir(dir, { withFileTypes: true });
+	const files = [];
+	const subdirs = [];
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			if (recursive) subdirs.push(join(dir, entry.name));
+			continue;
+		}
+		if (include(entry.name)) files.push(join(dir, entry.name));
+	}
+	files.sort();
+	subdirs.sort();
+	for (const sub of subdirs) files.push(...await collectFiles(sub, include, recursive));
+	return files;
+}
+//#endregion
+//#region src/contract/eval-reporting-suite.ts
+/**
+* # `evalReportingSuite` — one call from runs (or a run dir) to `analysis.json`.
+*
+* A thin wrapper over the analysis primitive (`analyzeRuns`) and the on-disk
+* intake adapter (`fromRunRecordDir`). It does NOT reimplement any statistics,
+* distributions, or clustering — it resolves the input into validated
+* `RunRecord[]`, calls `analyzeRuns` with the options you'd pass it directly,
+* wraps the result in a small provenance envelope, and (optionally) writes a
+* single `analysis.json` artifact.
+*
+* ```ts
+* // From a directory of run files, write ./runs/analysis.json:
+* const suite = await evalReportingSuite('./runs', { write: true })
+* // From records already in memory, no write:
+* const suite = await evalReportingSuite(records, { analyze: { decisionThreshold: 0.03 } })
+* suite.report // the InsightReport — distributions, paired lift, findings rollup
+* ```
+*/
+const ANALYSIS_ARTIFACT = "analysis.json";
+/**
+* Resolve runs (or a run dir/file), run `analyzeRuns`, and optionally persist a
+* single `analysis.json`. The only analysis logic lives in `analyzeRuns`; this
+* function is composition + I/O.
+*/
 async function evalReportingSuite(input, options = {}) {
-  const fromPath = typeof input === "string";
-  let runs;
-  let files = [];
-  let rejected = [];
-  if (fromPath) {
-    const loaded = await fromRunRecordDir(input, options.load);
-    runs = loaded.runs;
-    files = loaded.files;
-    rejected = loaded.rejected;
-  } else {
-    runs = input;
-  }
-  if (runs.length === 0) {
-    throw new Error(
-      fromPath ? `evalReportingSuite: no RunRecords found at '${input}'` : "evalReportingSuite: no RunRecords to analyze"
-    );
-  }
-  const report = await analyzeRuns({ ...options.analyze, runs });
-  const result = {
-    report,
-    provenance: {
-      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      runCount: runs.length,
-      sourcePath: fromPath ? input : null,
-      files,
-      rejected
-    },
-    writtenTo: null
-  };
-  const target = resolveWriteTarget(options.write, fromPath ? input : null);
-  if (target) {
-    await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, `${JSON.stringify(result, null, 2)}
-`, "utf8");
-    result.writtenTo = target;
-  }
-  return result;
-}
+	const fromPath = typeof input === "string";
+	let runs;
+	let files = [];
+	let rejected = [];
+	if (fromPath) {
+		const loaded = await fromRunRecordDir(input, options.load);
+		runs = loaded.runs;
+		files = loaded.files;
+		rejected = loaded.rejected;
+	} else runs = input;
+	if (runs.length === 0) throw new Error(fromPath ? `evalReportingSuite: no RunRecords found at '${input}'` : "evalReportingSuite: no RunRecords to analyze");
+	const result = {
+		report: await analyzeRuns({
+			...options.analyze,
+			runs
+		}),
+		provenance: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			runCount: runs.length,
+			sourcePath: fromPath ? input : null,
+			files,
+			rejected
+		},
+		writtenTo: null
+	};
+	const target = resolveWriteTarget(options.write, fromPath ? input : null);
+	if (target) {
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+		result.writtenTo = target;
+	}
+	return result;
+}
+/** Resolve where (if anywhere) to write `analysis.json`. Returns null when
+*  writing is disabled. Throws on `write: true` with in-memory input — there is
+*  no directory to anchor the artifact to, and silently inventing `cwd` would
+*  scatter files. */
 function resolveWriteTarget(write, sourcePath) {
-  if (!write) return null;
-  if (typeof write === "string") {
-    const looksLikeDir = write.endsWith("/") || !write.endsWith(".json") && !write.endsWith(".jsonl");
-    return looksLikeDir ? join2(write, ANALYSIS_ARTIFACT2) : write;
-  }
-  if (sourcePath === null) {
-    throw new Error(
-      "evalReportingSuite: write:true needs a source path to anchor analysis.json \u2014 pass an explicit output path when analyzing in-memory records"
-    );
-  }
-  const isFile = sourcePath.endsWith(".json") || sourcePath.endsWith(".jsonl");
-  return isFile ? join2(dirname(sourcePath), ANALYSIS_ARTIFACT2) : join2(sourcePath, ANALYSIS_ARTIFACT2);
+	if (!write) return null;
+	if (typeof write === "string") return write.endsWith("/") || !write.endsWith(".json") && !write.endsWith(".jsonl") ? join(write, ANALYSIS_ARTIFACT) : write;
+	if (sourcePath === null) throw new Error("evalReportingSuite: write:true needs a source path to anchor analysis.json — pass an explicit output path when analyzing in-memory records");
+	return sourcePath.endsWith(".json") || sourcePath.endsWith(".jsonl") ? join(dirname(sourcePath), ANALYSIS_ARTIFACT) : join(sourcePath, ANALYSIS_ARTIFACT);
 }
-
-// src/contract/diff.ts
+//#endregion
+//#region src/contract/diff.ts
 function keyForCell(cell) {
-  return JSON.stringify([cell.scenarioId, cell.rep]);
+	return JSON.stringify([cell.scenarioId, cell.rep]);
 }
+/** Build the per-dimension delta map for a matched cell. Each judge name +
+*  dimension name encountered on EITHER side appears in the result. */
 function diffDimensions(before, after) {
-  const out = {};
-  const judges = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  for (const judge of judges) {
-    const beforeDims = before[judge] ?? {};
-    const afterDims = after[judge] ?? {};
-    const dims = /* @__PURE__ */ new Set([...Object.keys(beforeDims), ...Object.keys(afterDims)]);
-    const judgeOut = {};
-    for (const dim of dims) {
-      const rawBefore = beforeDims[dim];
-      const rawAfter = afterDims[dim];
-      const b = typeof rawBefore === "number" && Number.isFinite(rawBefore) ? rawBefore : null;
-      const a = typeof rawAfter === "number" && Number.isFinite(rawAfter) ? rawAfter : null;
-      judgeOut[dim] = {
-        before: b,
-        after: a,
-        delta: b !== null && a !== null ? a - b : null
-      };
-    }
-    out[judge] = judgeOut;
-  }
-  return out;
-}
+	const out = {};
+	const judges = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+	for (const judge of judges) {
+		const beforeDims = before[judge] ?? {};
+		const afterDims = after[judge] ?? {};
+		const dims = /* @__PURE__ */ new Set([...Object.keys(beforeDims), ...Object.keys(afterDims)]);
+		const judgeOut = {};
+		for (const dim of dims) {
+			const rawBefore = beforeDims[dim];
+			const rawAfter = afterDims[dim];
+			const b = typeof rawBefore === "number" && Number.isFinite(rawBefore) ? rawBefore : null;
+			const a = typeof rawAfter === "number" && Number.isFinite(rawAfter) ? rawAfter : null;
+			judgeOut[dim] = {
+				before: b,
+				after: a,
+				delta: b !== null && a !== null ? a - b : null
+			};
+		}
+		out[judge] = judgeOut;
+	}
+	return out;
+}
+/**
+* Diff two generation snapshots. Cells are matched on `(scenarioId, rep)`;
+* unmatched cells surface in `added` / `removed`. Aggregate fields are
+* recomputed from the snapshot's stored fields, not re-derived from cells —
+* this keeps the diff consistent with whatever aggregation the substrate
+* actually reported.
+*/
 function diffGenerations(before, after) {
-  const beforeMap = new Map(before.cells.map((c) => [keyForCell(c), c]));
-  const afterMap = new Map(after.cells.map((c) => [keyForCell(c), c]));
-  const matched = [];
-  const removed = [];
-  const added = [];
-  for (const [key, beforeCell] of beforeMap) {
-    const afterCell = afterMap.get(key);
-    if (!afterCell) {
-      removed.push(beforeCell);
-      continue;
-    }
-    matched.push({
-      scenarioId: beforeCell.scenarioId,
-      rep: beforeCell.rep,
-      compositeBefore: beforeCell.compositeMean,
-      compositeAfter: afterCell.compositeMean,
-      compositeDelta: beforeCell.compositeMean === null || afterCell.compositeMean === null ? null : afterCell.compositeMean - beforeCell.compositeMean,
-      dimensions: diffDimensions(beforeCell.dimensions, afterCell.dimensions)
-    });
-  }
-  for (const [key, afterCell] of afterMap) {
-    if (!beforeMap.has(key)) added.push(afterCell);
-  }
-  return {
-    beforeIndex: before.index,
-    afterIndex: after.index,
-    beforeSurfaceHash: before.surfaceHash,
-    afterSurfaceHash: after.surfaceHash,
-    surfaceChanged: before.surfaceHash !== after.surfaceHash,
-    matched,
-    removed,
-    added,
-    compositeBefore: before.compositeMean,
-    compositeAfter: after.compositeMean,
-    compositeDelta: before.compositeMean === null || after.compositeMean === null ? null : after.compositeMean - before.compositeMean,
-    costUsdBefore: before.costUsd,
-    costUsdAfter: after.costUsd,
-    costUsdDelta: after.costUsd - before.costUsd,
-    durationMsBefore: before.durationMs,
-    durationMsAfter: after.durationMs,
-    durationMsDelta: after.durationMs - before.durationMs
-  };
-}
+	const beforeMap = new Map(before.cells.map((c) => [keyForCell(c), c]));
+	const afterMap = new Map(after.cells.map((c) => [keyForCell(c), c]));
+	const matched = [];
+	const removed = [];
+	const added = [];
+	for (const [key, beforeCell] of beforeMap) {
+		const afterCell = afterMap.get(key);
+		if (!afterCell) {
+			removed.push(beforeCell);
+			continue;
+		}
+		matched.push({
+			scenarioId: beforeCell.scenarioId,
+			rep: beforeCell.rep,
+			compositeBefore: beforeCell.compositeMean,
+			compositeAfter: afterCell.compositeMean,
+			compositeDelta: beforeCell.compositeMean === null || afterCell.compositeMean === null ? null : afterCell.compositeMean - beforeCell.compositeMean,
+			dimensions: diffDimensions(beforeCell.dimensions, afterCell.dimensions)
+		});
+	}
+	for (const [key, afterCell] of afterMap) if (!beforeMap.has(key)) added.push(afterCell);
+	return {
+		beforeIndex: before.index,
+		afterIndex: after.index,
+		beforeSurfaceHash: before.surfaceHash,
+		afterSurfaceHash: after.surfaceHash,
+		surfaceChanged: before.surfaceHash !== after.surfaceHash,
+		matched,
+		removed,
+		added,
+		compositeBefore: before.compositeMean,
+		compositeAfter: after.compositeMean,
+		compositeDelta: before.compositeMean === null || after.compositeMean === null ? null : after.compositeMean - before.compositeMean,
+		costUsdBefore: before.costUsd,
+		costUsdAfter: after.costUsd,
+		costUsdDelta: after.costUsd - before.costUsd,
+		durationMsBefore: before.durationMs,
+		durationMsAfter: after.durationMs,
+		durationMsDelta: after.durationMs - before.durationMs
+	};
+}
+/** Highest-index generation, or null if the run recorded none. */
 function winnerOf(run) {
-  if (run.generations.length === 0) return null;
-  let winner = run.generations[0];
-  for (const gen of run.generations) {
-    if (gen.index > winner.index) winner = gen;
-  }
-  return winner;
-}
+	if (run.generations.length === 0) return null;
+	let winner = run.generations[0];
+	for (const gen of run.generations) if (gen.index > winner.index) winner = gen;
+	return winner;
+}
+/**
+* Diff two full eval-runs. Produces baseline-vs-baseline and
+* winner-vs-winner generation diffs when both sides expose them, plus
+* run-level cost / lift / gate-decision deltas.
+*/
 function diffRuns(before, after) {
-  const beforeWinner = winnerOf(before);
-  const afterWinner = winnerOf(after);
-  const baselineDiff = before.baseline && after.baseline ? diffGenerations(before.baseline, after.baseline) : null;
-  const winnersDiff = beforeWinner && afterWinner ? diffGenerations(beforeWinner, afterWinner) : null;
-  const beforeLift = before.holdoutLift ?? null;
-  const afterLift = after.holdoutLift ?? null;
-  return {
-    beforeRunId: before.runId,
-    afterRunId: after.runId,
-    beforeTimestamp: before.timestamp,
-    afterTimestamp: after.timestamp,
-    beforeGateDecision: before.gateDecision ?? null,
-    afterGateDecision: after.gateDecision ?? null,
-    beforeHoldoutLift: beforeLift,
-    afterHoldoutLift: afterLift,
-    holdoutLiftDelta: beforeLift !== null && afterLift !== null ? afterLift - beforeLift : null,
-    beforeTotalCostUsd: before.totalCostUsd,
-    afterTotalCostUsd: after.totalCostUsd,
-    totalCostUsdDelta: after.totalCostUsd - before.totalCostUsd,
-    beforeTotalDurationMs: before.totalDurationMs,
-    afterTotalDurationMs: after.totalDurationMs,
-    totalDurationMsDelta: after.totalDurationMs - before.totalDurationMs,
-    baselineDiff,
-    winnersDiff
-  };
-}
+	const beforeWinner = winnerOf(before);
+	const afterWinner = winnerOf(after);
+	const baselineDiff = before.baseline && after.baseline ? diffGenerations(before.baseline, after.baseline) : null;
+	const winnersDiff = beforeWinner && afterWinner ? diffGenerations(beforeWinner, afterWinner) : null;
+	const beforeLift = before.holdoutLift ?? null;
+	const afterLift = after.holdoutLift ?? null;
+	return {
+		beforeRunId: before.runId,
+		afterRunId: after.runId,
+		beforeTimestamp: before.timestamp,
+		afterTimestamp: after.timestamp,
+		beforeGateDecision: before.gateDecision ?? null,
+		afterGateDecision: after.gateDecision ?? null,
+		beforeHoldoutLift: beforeLift,
+		afterHoldoutLift: afterLift,
+		holdoutLiftDelta: beforeLift !== null && afterLift !== null ? afterLift - beforeLift : null,
+		beforeTotalCostUsd: before.totalCostUsd,
+		afterTotalCostUsd: after.totalCostUsd,
+		totalCostUsdDelta: after.totalCostUsd - before.totalCostUsd,
+		beforeTotalDurationMs: before.totalDurationMs,
+		afterTotalDurationMs: after.totalDurationMs,
+		totalDurationMsDelta: after.totalDurationMs - before.totalDurationMs,
+		baselineDiff,
+		winnersDiff
+	};
+}
+/**
+* Within-run baseline → winning-generation diff. The natural "what did the
+* improvement loop produce" view for a single run. Returns null when the
+* run never reached a generation past baseline (errored early, or the gate
+* shipped the baseline as-is).
+*/
 function diffRunBaselineToWinner(run) {
-  if (!run.baseline) return null;
-  const winner = winnerOf(run);
-  if (!winner || winner.index === run.baseline.index) return null;
-  return diffGenerations(run.baseline, winner);
+	if (!run.baseline) return null;
+	const winner = winnerOf(run);
+	if (!winner || winner.index === run.baseline.index) return null;
+	return diffGenerations(run.baseline, winner);
 }
-
-// src/contract/intake/agent-trace.ts
+//#endregion
+//#region src/contract/intake/agent-trace.ts
 function rangeLines(r) {
-  return Math.max(0, r.end_line - r.start_line + 1);
+	return Math.max(0, r.end_line - r.start_line + 1);
 }
+/**
+* Build a commit → provenance index from Agent Trace records. Multiple records
+* for the same revision are merged. Records without `vcs.revision` are skipped
+* (the SHA is the join key — without it there is nothing to correlate against).
+*/
 function parseAgentTrace(records) {
-  const acc = /* @__PURE__ */ new Map();
-  for (const record of records) {
-    const sha = record.vcs?.revision;
-    if (!sha) continue;
-    let a = acc.get(sha);
-    if (!a) {
-      a = {
-        models: /* @__PURE__ */ new Set(),
-        tools: /* @__PURE__ */ new Set(),
-        files: /* @__PURE__ */ new Set(),
-        conversationCount: 0,
-        lineCount: 0,
-        humanInvolved: false
-      };
-      acc.set(sha, a);
-    }
-    if (record.tool?.name) a.tools.add(record.tool.name);
-    for (const file of record.files ?? []) {
-      a.files.add(file.path);
-      for (const conv of file.conversations ?? []) {
-        a.conversationCount += 1;
-        for (const range of conv.ranges ?? []) {
-          const contributor = range.contributor ?? conv.contributor;
-          a.lineCount += rangeLines(range);
-          if (!contributor) continue;
-          if (contributor.type === "human" || contributor.type === "mixed") {
-            a.humanInvolved = true;
-          }
-          if ((contributor.type === "ai" || contributor.type === "mixed") && contributor.model_id) {
-            a.models.add(contributor.model_id);
-          }
-        }
-      }
-    }
-  }
-  const index = /* @__PURE__ */ new Map();
-  for (const [sha, a] of acc) {
-    index.set(sha, {
-      commitSha: sha,
-      aiModels: [...a.models].sort(),
-      tools: [...a.tools].sort(),
-      conversationCount: a.conversationCount,
-      fileCount: a.files.size,
-      lineCount: a.lineCount,
-      humanInvolved: a.humanInvolved
-    });
-  }
-  return index;
-}
+	const acc = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const sha = record.vcs?.revision;
+		if (!sha) continue;
+		let a = acc.get(sha);
+		if (!a) {
+			a = {
+				models: /* @__PURE__ */ new Set(),
+				tools: /* @__PURE__ */ new Set(),
+				files: /* @__PURE__ */ new Set(),
+				conversationCount: 0,
+				lineCount: 0,
+				humanInvolved: false
+			};
+			acc.set(sha, a);
+		}
+		if (record.tool?.name) a.tools.add(record.tool.name);
+		for (const file of record.files ?? []) {
+			a.files.add(file.path);
+			for (const conv of file.conversations ?? []) {
+				a.conversationCount += 1;
+				for (const range of conv.ranges ?? []) {
+					const contributor = range.contributor ?? conv.contributor;
+					a.lineCount += rangeLines(range);
+					if (!contributor) continue;
+					if (contributor.type === "human" || contributor.type === "mixed") a.humanInvolved = true;
+					if ((contributor.type === "ai" || contributor.type === "mixed") && contributor.model_id) a.models.add(contributor.model_id);
+				}
+			}
+		}
+	}
+	const index = /* @__PURE__ */ new Map();
+	for (const [sha, a] of acc) index.set(sha, {
+		commitSha: sha,
+		aiModels: [...a.models].sort(),
+		tools: [...a.tools].sort(),
+		conversationCount: a.conversationCount,
+		fileCount: a.files.size,
+		lineCount: a.lineCount,
+		humanInvolved: a.humanInvolved
+	});
+	return index;
+}
+/**
+* Partition runs by the AI model(s) that authored the code at each run's
+* `commitSha`. Feed `byModel.get(modelId)` to `analyzeRuns`, or compare two
+* model cohorts via `analyzeRuns({ runs: a, baselineRuns: b })` for a lift CI
+* on "model A's code vs model B's code".
+*/
 function partitionRunsByAuthoringModel(runs, index) {
-  const byModel = /* @__PURE__ */ new Map();
-  const unattributed = [];
-  for (const run of runs) {
-    const provenance = index.get(run.commitSha);
-    if (!provenance || provenance.aiModels.length === 0) {
-      unattributed.push(run);
-      continue;
-    }
-    for (const model of provenance.aiModels) {
-      const cohort = byModel.get(model) ?? [];
-      cohort.push(run);
-      byModel.set(model, cohort);
-    }
-  }
-  return { byModel, unattributed };
-}
-
-// src/contract/intake/feedback-table.ts
+	const byModel = /* @__PURE__ */ new Map();
+	const unattributed = [];
+	for (const run of runs) {
+		const provenance = index.get(run.commitSha);
+		if (!provenance || provenance.aiModels.length === 0) {
+			unattributed.push(run);
+			continue;
+		}
+		for (const model of provenance.aiModels) {
+			const cohort = byModel.get(model) ?? [];
+			cohort.push(run);
+			byModel.set(model, cohort);
+		}
+	}
+	return {
+		byModel,
+		unattributed
+	};
+}
+//#endregion
+//#region src/contract/intake/feedback-table.ts
 function fromFeedbackTable(opts) {
-  const { ratings, meta = [], scale, emitRaterScores = true } = opts;
-  const metaByRun = new Map(meta.map((m) => [m.runId, m]));
-  const normalise = (rating) => {
-    if (typeof rating === "boolean") return rating ? 1 : 0;
-    if (!Number.isFinite(rating)) return Number.NaN;
-    if (!scale) return rating;
-    const { min, max } = scale;
-    if (max === min) return rating;
-    return (rating - min) / (max - min);
-  };
-  const byRun = /* @__PURE__ */ new Map();
-  for (const row of ratings) {
-    const list = byRun.get(row.runId) ?? [];
-    list.push(row);
-    byRun.set(row.runId, list);
-  }
-  const runs = [];
-  const raterScores = [];
-  for (const [runId, rowsForRun] of byRun) {
-    const normalised = rowsForRun.map((r) => ({ rater: r.rater, score: normalise(r.rating) })).filter((r) => Number.isFinite(r.score));
-    if (normalised.length === 0) continue;
-    const meanScore = normalised.reduce((s, r) => s + r.score, 0) / normalised.length;
-    const runMeta = metaByRun.get(runId) ?? { runId };
-    const judgeScores = {
-      perJudge: Object.fromEntries(normalised.map((r) => [r.rater, { rating: r.score }])),
-      perDimMean: { rating: meanScore },
-      composite: meanScore
-    };
-    const splitTag = runMeta.splitTag ?? "holdout";
-    const outcome = {
-      ...splitTag === "holdout" ? { holdoutScore: meanScore } : { searchScore: meanScore },
-      raw: Object.fromEntries(normalised.map((r) => [`rater:${r.rater}`, r.score])),
-      judgeScores
-    };
-    const costUsd = runMeta.costUsd ?? null;
-    runs.push({
-      runId,
-      experimentId: runMeta.experimentId ?? "feedback-corpus",
-      candidateId: runMeta.candidateId ?? runId,
-      seed: 0,
-      model: runMeta.model ?? "unknown@unknown",
-      promptHash: runMeta.promptHash ?? "sha256:unknown",
-      configHash: runMeta.configHash ?? "sha256:unknown",
-      commitSha: runMeta.commitSha ?? "unknown",
-      wallMs: runMeta.wallMs ?? 0,
-      costUsd,
-      costProvenance: costUsd === null ? { kind: "uncaptured", usd: null } : { kind: "observed", usd: costUsd },
-      tokenUsage: { input: 0, output: 0 },
-      terminalOutcome: "unknown",
-      outcome,
-      splitTag,
-      scenarioId: runMeta.scenarioId ?? runId
-    });
-    if (emitRaterScores) {
-      for (const r of normalised) raterScores.push({ runId, rater: r.rater, score: r.score });
-    }
-  }
-  return { runs, raterScores };
-}
-
-// src/contract/intake/otel-spans.ts
-var TASK_SCORE_ATTR_KEYS = [
-  "gen_ai.evaluation.score.value",
-  "tangle.task.score",
-  "eval.score",
-  "tangle.score"
+	const { ratings, meta = [], scale, emitRaterScores = true } = opts;
+	const metaByRun = new Map(meta.map((m) => [m.runId, m]));
+	const normalise = (rating) => {
+		if (typeof rating === "boolean") return rating ? 1 : 0;
+		if (!Number.isFinite(rating)) return NaN;
+		if (!scale) return rating;
+		const { min, max } = scale;
+		if (max === min) return rating;
+		return (rating - min) / (max - min);
+	};
+	const byRun = /* @__PURE__ */ new Map();
+	for (const row of ratings) {
+		const list = byRun.get(row.runId) ?? [];
+		list.push(row);
+		byRun.set(row.runId, list);
+	}
+	const runs = [];
+	const raterScores = [];
+	for (const [runId, rowsForRun] of byRun) {
+		const normalised = rowsForRun.map((r) => ({
+			rater: r.rater,
+			score: normalise(r.rating)
+		})).filter((r) => Number.isFinite(r.score));
+		if (normalised.length === 0) continue;
+		const meanScore = normalised.reduce((s, r) => s + r.score, 0) / normalised.length;
+		const runMeta = metaByRun.get(runId) ?? { runId };
+		const judgeScores = {
+			perJudge: Object.fromEntries(normalised.map((r) => [r.rater, { rating: r.score }])),
+			perDimMean: { rating: meanScore },
+			composite: meanScore
+		};
+		const splitTag = runMeta.splitTag ?? "holdout";
+		const outcome = {
+			...splitTag === "holdout" ? { holdoutScore: meanScore } : { searchScore: meanScore },
+			raw: Object.fromEntries(normalised.map((r) => [`rater:${r.rater}`, r.score])),
+			judgeScores
+		};
+		const costUsd = runMeta.costUsd ?? null;
+		runs.push({
+			runId,
+			experimentId: runMeta.experimentId ?? "feedback-corpus",
+			candidateId: runMeta.candidateId ?? runId,
+			seed: 0,
+			model: runMeta.model ?? "unknown@unknown",
+			promptHash: runMeta.promptHash ?? "sha256:unknown",
+			configHash: runMeta.configHash ?? "sha256:unknown",
+			commitSha: runMeta.commitSha ?? "unknown",
+			wallMs: runMeta.wallMs ?? 0,
+			costUsd,
+			costProvenance: costUsd === null ? {
+				kind: "uncaptured",
+				usd: null
+			} : {
+				kind: "observed",
+				usd: costUsd
+			},
+			tokenUsage: {
+				input: 0,
+				output: 0
+			},
+			terminalOutcome: "unknown",
+			outcome,
+			splitTag,
+			scenarioId: runMeta.scenarioId ?? runId
+		});
+		if (emitRaterScores) for (const r of normalised) raterScores.push({
+			runId,
+			rater: r.rater,
+			score: r.score
+		});
+	}
+	return {
+		runs,
+		raterScores
+	};
+}
+//#endregion
+//#region src/contract/intake/otel-spans.ts
+/**
+* # `intake/otel-spans` — OTel `TraceSpanEvent[]` → `RunRecord[]`.
+*
+* Turns an existing observability stream into the substrate-canonical
+* `RunRecord` shape so consumers with logs but no eval discipline can
+* call `analyzeRuns()` against their production traffic immediately.
+*
+* Pivot rule: spans are grouped by `tangle.runId` (the same attribute the
+* hosted-tier wire format uses) or, when absent, by `traceId`. One group
+* becomes one `RunRecord`. The root span (no `parentSpanId`) supplies:
+*
+*   - `runId` (the group key)
+*   - `wallMs` from `endTimeUnixNano - startTimeUnixNano`
+*   - `model` from `gen_ai.request.model` / `llm.model` / `tangle.model`
+*   - task failure class and detail from explicit `tangle.task.*` attributes
+*   - cost from `cost.usd` / `gen_ai.usage.cost_usd` / `tangle.cost.usd`
+*   - token usage from model-call input, output, cache-read, and cache-write
+*     attributes without double-counting aggregate parent spans
+*   - task quality from an explicit `scoreForRun` callback or a designated
+*     evaluation attribute on a root / `EVALUATOR` span; `outcome.raw`
+*     collects every numeric attribute without promoting it to task quality.
+*
+* Errored tool, model, and child-agent spans contribute to execution-error
+* counts. Root process, guardrail, evaluator, propagated parent, and unknown
+* errors retain separate counters. Only one failed root can set
+* `RunRecord.terminalOutcome` and `RunRecord.terminalFailureReason`; a child
+* error cannot become a task failure.
+*/
+const TASK_SCORE_ATTR_KEYS = [
+	"gen_ai.evaluation.score.value",
+	"tangle.task.score",
+	"eval.score",
+	"tangle.score"
 ];
-var MODEL_KEYS = ["tangle.model", ...LLM_MODEL_ATTR_KEYS, "model"];
-var PROMPT_HASH_KEYS = ["tangle.prompt_hash", "prompt.hash"];
-var CONFIG_HASH_KEYS = ["tangle.config_hash", "config.hash"];
+const MODEL_KEYS = [
+	"tangle.model",
+	...LLM_MODEL_ATTR_KEYS,
+	"model"
+];
+const PROMPT_HASH_KEYS = ["tangle.prompt_hash", "prompt.hash"];
+const CONFIG_HASH_KEYS = ["tangle.config_hash", "config.hash"];
 function fromOtelSpans(opts) {
-  const { spans, defaultSplit = "holdout", experimentId = "otel-corpus" } = opts;
-  const grouped = groupSpans(spans);
-  const runs = [];
-  for (const [groupKey, groupSpans2] of grouped) {
-    const root = findRoot(groupSpans2);
-    if (!root) continue;
-    const measurements = summarizeExecutionMeasurements(
-      groupSpans2.map((span) => ({
-        id: span.spanId,
-        ...span.parentSpanId ? { parentId: span.parentSpanId } : {},
-        attributes: span.attributes,
-        modelCall: isExplicitModelCall(span),
-        aggregate: isExplicitAggregate(span)
-      }))
-    );
-    const callSpanIds = new Set(measurements.callSpanIds);
-    const callSpans = groupSpans2.filter((span) => callSpanIds.has(span.spanId));
-    const wallMs = unixNanoDurationMs(root.startTimeUnixNano, root.endTimeUnixNano);
-    const model = readAttrString(callSpans, MODEL_KEYS) ?? readAttrString(groupSpans2, MODEL_KEYS) ?? "unknown@unknown";
-    const capturedCost = (measurements.cost.complete ? measurements.cost.value : void 0) ?? measurements.aggregate?.costUsd;
-    const costUsd = capturedCost ?? null;
-    const scenarioId = readConsistentScenarioId(groupKey, groupSpans2) ?? groupKey;
-    const promptHash = readAttrString(groupSpans2, PROMPT_HASH_KEYS) ?? "sha256:unknown";
-    const configHash = readAttrString(groupSpans2, CONFIG_HASH_KEYS) ?? "sha256:unknown";
-    const score = resolveTaskScore(groupKey, groupSpans2, opts.scoreForRun);
-    const taskFailure = readTaskFailureLabels(
-      groupSpans2.filter((span) => !span.parentSpanId && isTerminalRootCandidate(span)),
-      `fromOtelSpans: run '${groupKey}'`
-    );
-    const rawNumeric = collectNumericAttrs(groupSpans2);
-    const errorSummary = summarizeTraceErrors(
-      groupSpans2.map((span) => ({
-        id: spanIdentity(span),
-        ...span.parentSpanId ? { parentId: parentIdentity(span) } : {},
-        role: errorRoleForSpan(span),
-        error: span.status?.code === "ERROR",
-        processRoot: !span.parentSpanId && isTerminalRootCandidate(span)
-      }))
-    );
-    rawNumeric.error_span_count = errorSummary.total;
-    rawNumeric.execution_error_count = errorSummary.execution;
-    rawNumeric.process_error_count = errorSummary.process;
-    rawNumeric.guardrail_error_count = errorSummary.guardrail;
-    rawNumeric.judge_error_count = errorSummary.evaluation;
-    rawNumeric.propagated_error_count = errorSummary.propagated;
-    rawNumeric.unclassified_error_count = errorSummary.unclassified;
-    rawNumeric.llm_span_count = measurements.modelCallCount;
-    if (measurements.cost.value !== void 0 && !measurements.cost.complete) {
-      rawNumeric.partial_observed_cost_usd = measurements.cost.value;
-    }
-    recordAggregateMeasurements(rawNumeric, measurements.aggregate);
-    const judgeScores = score !== void 0 ? {
-      perJudge: { "otel-derived": { score } },
-      perDimMean: { score },
-      composite: score
-    } : void 0;
-    const terminalOutcome = terminalOutcomeFromRoots(groupSpans2);
-    const failedRoot = terminalOutcome === "failed" ? groupSpans2.find(
-      (span) => !span.parentSpanId && isTerminalRootCandidate(span) && span.status?.code === "ERROR"
-    ) : void 0;
-    const outcome = {
-      raw: rawNumeric,
-      ...judgeScores ? { judgeScores } : {}
-    };
-    if (score !== void 0) {
-      if (defaultSplit === "holdout") outcome.holdoutScore = score;
-      else outcome.searchScore = score;
-    }
-    runs.push({
-      runId: groupKey,
-      experimentId,
-      candidateId: root.attributes["tangle.candidateId"] ?? "otel-default",
-      seed: 0,
-      model,
-      promptHash,
-      configHash,
-      commitSha: root.attributes["tangle.commit_sha"] ?? "unknown",
-      wallMs,
-      costUsd,
-      costProvenance: capturedCost === void 0 ? { kind: "uncaptured", usd: null } : { kind: "observed", usd: capturedCost },
-      tokenUsage: measurements.tokenUsage,
-      terminalOutcome,
-      ...failedRoot ? { terminalFailureReason: failedRoot.status?.message ?? failedRoot.name } : {},
-      outcome,
-      ...taskFailure,
-      splitTag: defaultSplit,
-      scenarioId
-    });
-  }
-  return runs;
+	const { spans, defaultSplit = "holdout", experimentId = "otel-corpus" } = opts;
+	const grouped = groupSpans(spans);
+	const runs = [];
+	for (const [groupKey, groupSpans] of grouped) {
+		const root = findRoot(groupSpans);
+		if (!root) continue;
+		const measurements = summarizeExecutionMeasurements(groupSpans.map((span) => ({
+			id: span.spanId,
+			...span.parentSpanId ? { parentId: span.parentSpanId } : {},
+			attributes: span.attributes,
+			modelCall: isExplicitModelCall(span),
+			aggregate: isExplicitAggregate(span)
+		})));
+		const callSpanIds = new Set(measurements.callSpanIds);
+		const callSpans = groupSpans.filter((span) => callSpanIds.has(span.spanId));
+		const wallMs = unixNanoDurationMs(root.startTimeUnixNano, root.endTimeUnixNano);
+		const model = readAttrString(callSpans, MODEL_KEYS) ?? readAttrString(groupSpans, MODEL_KEYS) ?? "unknown@unknown";
+		const capturedCost = (measurements.cost.complete ? measurements.cost.value : void 0) ?? measurements.aggregate?.costUsd;
+		const costUsd = capturedCost ?? null;
+		const scenarioId = readConsistentScenarioId(groupKey, groupSpans) ?? groupKey;
+		const promptHash = readAttrString(groupSpans, PROMPT_HASH_KEYS) ?? "sha256:unknown";
+		const configHash = readAttrString(groupSpans, CONFIG_HASH_KEYS) ?? "sha256:unknown";
+		const score = resolveTaskScore(groupKey, groupSpans, opts.scoreForRun);
+		const taskFailure = readTaskFailureLabels(groupSpans.filter((span) => !span.parentSpanId && isTerminalRootCandidate(span)), `fromOtelSpans: run '${groupKey}'`);
+		const rawNumeric = collectNumericAttrs(groupSpans);
+		const errorSummary = summarizeTraceErrors(groupSpans.map((span) => ({
+			id: spanIdentity(span),
+			...span.parentSpanId ? { parentId: parentIdentity(span) } : {},
+			role: errorRoleForSpan(span),
+			error: span.status?.code === "ERROR",
+			processRoot: !span.parentSpanId && isTerminalRootCandidate(span)
+		})));
+		rawNumeric.error_span_count = errorSummary.total;
+		rawNumeric.execution_error_count = errorSummary.execution;
+		rawNumeric.process_error_count = errorSummary.process;
+		rawNumeric.guardrail_error_count = errorSummary.guardrail;
+		rawNumeric.judge_error_count = errorSummary.evaluation;
+		rawNumeric.propagated_error_count = errorSummary.propagated;
+		rawNumeric.unclassified_error_count = errorSummary.unclassified;
+		rawNumeric.llm_span_count = measurements.modelCallCount;
+		if (measurements.cost.value !== void 0 && !measurements.cost.complete) rawNumeric.partial_observed_cost_usd = measurements.cost.value;
+		recordAggregateMeasurements(rawNumeric, measurements.aggregate);
+		const judgeScores = score !== void 0 ? {
+			perJudge: { "otel-derived": { score } },
+			perDimMean: { score },
+			composite: score
+		} : void 0;
+		const terminalOutcome = terminalOutcomeFromRoots(groupSpans);
+		const failedRoot = terminalOutcome === "failed" ? groupSpans.find((span) => !span.parentSpanId && isTerminalRootCandidate(span) && span.status?.code === "ERROR") : void 0;
+		const outcome = {
+			raw: rawNumeric,
+			...judgeScores ? { judgeScores } : {}
+		};
+		if (score !== void 0) if (defaultSplit === "holdout") outcome.holdoutScore = score;
+		else outcome.searchScore = score;
+		runs.push({
+			runId: groupKey,
+			experimentId,
+			candidateId: root.attributes["tangle.candidateId"] ?? "otel-default",
+			seed: 0,
+			model,
+			promptHash,
+			configHash,
+			commitSha: root.attributes["tangle.commit_sha"] ?? "unknown",
+			wallMs,
+			costUsd,
+			costProvenance: capturedCost === void 0 ? {
+				kind: "uncaptured",
+				usd: null
+			} : {
+				kind: "observed",
+				usd: capturedCost
+			},
+			tokenUsage: measurements.tokenUsage,
+			terminalOutcome,
+			...failedRoot ? { terminalFailureReason: failedRoot.status?.message ?? failedRoot.name } : {},
+			outcome,
+			...taskFailure,
+			splitTag: defaultSplit,
+			scenarioId
+		});
+	}
+	return runs;
 }
 function terminalOutcomeFromRoots(spans) {
-  const roots = spans.filter((span) => !span.parentSpanId && isTerminalRootCandidate(span));
-  if (roots.length !== 1) return "unknown";
-  if (roots[0].status?.code === "OK") return "succeeded";
-  if (roots[0].status?.code === "ERROR") return "failed";
-  return "unknown";
+	const roots = spans.filter((span) => !span.parentSpanId && isTerminalRootCandidate(span));
+	if (roots.length !== 1) return "unknown";
+	if (roots[0].status?.code === "OK") return "succeeded";
+	if (roots[0].status?.code === "ERROR") return "failed";
+	return "unknown";
 }
 function isTerminalRootCandidate(span) {
-  const role = errorRoleForSpan(span);
-  if (role === "LLM" || role === "TOOL" || role === "GUARDRAIL" || role === "EVALUATOR") {
-    return false;
-  }
-  return true;
+	const role = errorRoleForSpan(span);
+	if (role === "LLM" || role === "TOOL" || role === "GUARDRAIL" || role === "EVALUATOR") return false;
+	return true;
 }
 function readSpanKind(span) {
-  return readAttrString([span], [...SPAN_KIND_ATTR_KEYS, "span.kind"])?.toUpperCase();
+	return readAttrString([span], [...SPAN_KIND_ATTR_KEYS, "span.kind"])?.toUpperCase();
 }
 function errorRoleForSpan(span) {
-  return classifyOtlpSpanRole({
-    kind: readSpanKind(span),
-    name: span.name,
-    attributes: span.attributes
-  });
+	return classifyOtlpSpanRole({
+		kind: readSpanKind(span),
+		name: span.name,
+		attributes: span.attributes
+	});
 }
 function spanIdentity(span) {
-  return `${span.traceId}:${span.spanId}`;
+	return `${span.traceId}:${span.spanId}`;
 }
 function parentIdentity(span) {
-  return `${span.traceId}:${span.parentSpanId}`;
+	return `${span.traceId}:${span.parentSpanId}`;
 }
 function isExplicitModelCall(span) {
-  return isOtlpModelCall({
-    kind: readSpanKind(span),
-    name: span.name,
-    attributes: span.attributes
-  });
+	return isOtlpModelCall({
+		kind: readSpanKind(span),
+		name: span.name,
+		attributes: span.attributes
+	});
 }
 function isExplicitAggregate(span) {
-  const kind = readSpanKind(span);
-  return kind !== void 0 && kind !== "LLM";
+	const kind = readSpanKind(span);
+	return kind !== void 0 && kind !== "LLM";
 }
 function groupSpans(spans) {
-  const m = /* @__PURE__ */ new Map();
-  for (const span of spans) {
-    const key = span["tangle.runId"] ?? span.traceId;
-    const list = m.get(key) ?? [];
-    list.push(span);
-    m.set(key, list);
-  }
-  return m;
+	const m = /* @__PURE__ */ new Map();
+	for (const span of spans) {
+		const key = span["tangle.runId"] ?? span.traceId;
+		const list = m.get(key) ?? [];
+		list.push(span);
+		m.set(key, list);
+	}
+	return m;
 }
 function findRoot(group) {
-  const structuralRoots = group.filter((span) => !span.parentSpanId);
-  const terminalRoots = structuralRoots.filter(isTerminalRootCandidate);
-  const pool = terminalRoots.length > 0 ? terminalRoots : structuralRoots.length > 0 ? structuralRoots : group;
-  return orderSpans(pool)[0];
+	const structuralRoots = group.filter((span) => !span.parentSpanId);
+	const terminalRoots = structuralRoots.filter(isTerminalRootCandidate);
+	return orderSpans(terminalRoots.length > 0 ? terminalRoots : structuralRoots.length > 0 ? structuralRoots : group)[0];
 }
 function readAttrString(spans, keys) {
-  for (const span of spans) {
-    for (const key of keys) {
-      const v = span.attributes[key];
-      if (typeof v === "string" && v.length > 0) return v;
-    }
-  }
-  return void 0;
+	for (const span of spans) for (const key of keys) {
+		const v = span.attributes[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
 }
 function readConsistentScenarioId(runId, spans) {
-  const values = /* @__PURE__ */ new Set();
-  for (const span of spans) {
-    const topLevel = span["tangle.scenarioId"];
-    if (typeof topLevel === "string" && topLevel.length > 0) values.add(topLevel);
-    const attribute = span.attributes["tangle.scenarioId"];
-    if (typeof attribute === "string" && attribute.length > 0) values.add(attribute);
-  }
-  if (values.size > 1) {
-    throw new ValidationError(
-      `fromOtelSpans: conflicting scenario ids for run '${runId}': ${[...values].sort().join(", ")}`
-    );
-  }
-  return values.values().next().value;
+	const values = /* @__PURE__ */ new Set();
+	for (const span of spans) {
+		const topLevel = span["tangle.scenarioId"];
+		if (typeof topLevel === "string" && topLevel.length > 0) values.add(topLevel);
+		const attribute = span.attributes["tangle.scenarioId"];
+		if (typeof attribute === "string" && attribute.length > 0) values.add(attribute);
+	}
+	if (values.size > 1) throw new ValidationError(`fromOtelSpans: conflicting scenario ids for run '${runId}': ${[...values].sort().join(", ")}`);
+	return values.values().next().value;
 }
 function resolveTaskScore(runId, spans, scoreForRun) {
-  const orderedSpans = orderSpans(spans);
-  const sources = [];
-  if (scoreForRun) {
-    const supplied = scoreForRun(runId, orderedSpans);
-    if (supplied !== void 0) {
-      if (typeof supplied !== "number" || !Number.isFinite(supplied)) {
-        throw new ValidationError(
-          `fromOtelSpans: scoreForRun returned a non-finite number for run '${runId}'`
-        );
-      }
-      sources.push({ label: "scoreForRun", value: supplied });
-    }
-  }
-  for (const span of orderedSpans) {
-    const role = errorRoleForSpan(span);
-    if (span.parentSpanId && role !== "EVALUATOR") continue;
-    if (role === "EVALUATOR" && span.status?.code === "ERROR") continue;
-    for (const key of TASK_SCORE_ATTR_KEYS) {
-      if (!Object.hasOwn(span.attributes, key)) continue;
-      sources.push({
-        label: `span '${span.spanId}' attribute '${key}'`,
-        value: parseTaskScoreAttribute(runId, span.spanId, key, span.attributes[key])
-      });
-    }
-  }
-  if (sources.length === 0) return void 0;
-  sources.sort((left, right) => left.label.localeCompare(right.label));
-  const score = sources[0].value;
-  if (sources.some((source) => source.value !== score)) {
-    const details = sources.map((source) => `${source.label}=${source.value}`).join(", ");
-    throw new ValidationError(
-      `fromOtelSpans: conflicting task-quality scores for run '${runId}': ${details}`
-    );
-  }
-  return score;
+	const orderedSpans = orderSpans(spans);
+	const sources = [];
+	if (scoreForRun) {
+		const supplied = scoreForRun(runId, orderedSpans);
+		if (supplied !== void 0) {
+			if (typeof supplied !== "number" || !Number.isFinite(supplied)) throw new ValidationError(`fromOtelSpans: scoreForRun returned a non-finite number for run '${runId}'`);
+			sources.push({
+				label: "scoreForRun",
+				value: supplied
+			});
+		}
+	}
+	for (const span of orderedSpans) {
+		const role = errorRoleForSpan(span);
+		if (span.parentSpanId && role !== "EVALUATOR") continue;
+		if (role === "EVALUATOR" && span.status?.code === "ERROR") continue;
+		for (const key of TASK_SCORE_ATTR_KEYS) {
+			if (!Object.hasOwn(span.attributes, key)) continue;
+			sources.push({
+				label: `span '${span.spanId}' attribute '${key}'`,
+				value: parseTaskScoreAttribute(runId, span.spanId, key, span.attributes[key])
+			});
+		}
+	}
+	if (sources.length === 0) return void 0;
+	sources.sort((left, right) => left.label.localeCompare(right.label));
+	const score = sources[0].value;
+	if (sources.some((source) => source.value !== score)) throw new ValidationError(`fromOtelSpans: conflicting task-quality scores for run '${runId}': ${sources.map((source) => `${source.label}=${source.value}`).join(", ")}`);
+	return score;
 }
 function parseTaskScoreAttribute(runId, spanId, key, value) {
-  const source = `span '${spanId}' attribute '${key}'`;
-  if (typeof value === "string") {
-    if (value.trim().length === 0) {
-      throw new ValidationError(
-        `fromOtelSpans: ${source} is blank for run '${runId}'; task quality must be finite`
-      );
-    }
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) return parsed;
-  } else if (typeof value === "number" && Number.isFinite(value)) {
-    return value;
-  }
-  throw new ValidationError(
-    `fromOtelSpans: ${source} is not a finite task-quality score for run '${runId}'`
-  );
+	const source = `span '${spanId}' attribute '${key}'`;
+	if (typeof value === "string") {
+		if (value.trim().length === 0) throw new ValidationError(`fromOtelSpans: ${source} is blank for run '${runId}'; task quality must be finite`);
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	} else if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new ValidationError(`fromOtelSpans: ${source} is not a finite task-quality score for run '${runId}'`);
 }
 function orderSpans(spans) {
-  return [...spans].sort(
-    (left, right) => compareUnixNano(left.startTimeUnixNano, right.startTimeUnixNano) || left.spanId.localeCompare(right.spanId)
-  );
+	return [...spans].sort((left, right) => compareUnixNano(left.startTimeUnixNano, right.startTimeUnixNano) || left.spanId.localeCompare(right.spanId));
 }
 function parseUnixNano(value) {
-  try {
-    return BigInt(value);
-  } catch {
-    throw new ValidationError(`fromOtelSpans: invalid Unix nanosecond timestamp '${value}'`);
-  }
+	try {
+		return BigInt(value);
+	} catch {
+		throw new ValidationError(`fromOtelSpans: invalid Unix nanosecond timestamp '${value}'`);
+	}
 }
 function compareUnixNano(left, right) {
-  const leftValue = parseUnixNano(left);
-  const rightValue = parseUnixNano(right);
-  return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+	const leftValue = parseUnixNano(left);
+	const rightValue = parseUnixNano(right);
+	return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
 }
 function unixNanoDurationMs(start, end) {
-  const delta = parseUnixNano(end) - parseUnixNano(start);
-  if (delta <= 0n) return 0;
-  const wholeMs = delta / 1000000n;
-  const fractionalMs = delta % 1000000n;
-  const value = Number(wholeMs) + Number(fractionalMs) / 1e6;
-  if (!Number.isSafeInteger(Number(wholeMs))) {
-    throw new ValidationError("fromOtelSpans: span duration exceeds the safe millisecond range");
-  }
-  return value;
+	const delta = parseUnixNano(end) - parseUnixNano(start);
+	if (delta <= 0n) return 0;
+	const wholeMs = delta / 1000000n;
+	const fractionalMs = delta % 1000000n;
+	const value = Number(wholeMs) + Number(fractionalMs) / 1e6;
+	if (!Number.isSafeInteger(Number(wholeMs))) throw new ValidationError("fromOtelSpans: span duration exceeds the safe millisecond range");
+	return value;
 }
 function collectNumericAttrs(spans) {
-  const raw = {};
-  for (const span of spans) {
-    for (const [k, v] of Object.entries(span.attributes)) {
-      if (typeof v === "number" && Number.isFinite(v)) raw[k] = v;
-    }
-  }
-  return raw;
-}
-export {
-  FileSystemOutcomeStore,
-  InMemoryOutcomeStore,
-  REFERENCE_EQUIVALENCE_INPUT_LIMITS,
-  REFERENCE_EQUIVALENCE_JUDGE_VERSION,
-  SelfImproveRunError,
-  analyzeRuns,
-  buildDefaultAnalystRegistry,
-  buildEvidenceVector,
-  campaignSplitDigest,
-  compareOptimizationMethods,
-  composeGate,
-  createChatClient,
-  createReferenceEquivalenceJudge,
-  defaultProductionGate,
-  defineAgentEval,
-  diffGenerations,
-  diffRunBaselineToWinner,
-  diffRuns,
-  evalReportingSuite,
-  evaluatePairedMeasurements,
-  externalTextOptimizationMethod,
-  fromClaudeCodeSession,
-  fromCodexSession,
-  fromFeedbackTable,
-  fromKimiCodeSession,
-  fromOpenCodeSession,
-  fromOtelSpans,
-  fromPiSession,
-  fromPigraphSession,
-  fromRunRecordDir,
-  fsCampaignStorage,
-  gepaOptimizationMethod,
-  heldOutGate,
-  inMemoryCampaignStorage,
-  llmJudge,
-  measuredComparisonFromCandidateExperiment,
-  observeCodeAgentSession,
-  paretoPolicy,
-  paretoSignificanceGate,
-  parseAgentTrace,
-  parseCodeAgentJsonl,
-  partitionRunsByAuthoringModel,
-  runCampaign,
-  runCandidateExperiment,
-  runEval,
-  runImprovementLoop,
-  runReferenceEquivalenceJudge,
-  sealCandidateBenchmarkSuite,
-  sealCandidateBenchmarkTask,
-  sealCandidateExperiment,
-  selfImprove,
-  skillOptOptimizationMethod,
-  summarizeExecution,
-  verifyCandidateBenchmarkSuite,
-  verifyCandidateBenchmarkSuiteInputs,
-  verifyCandidateBenchmarkTask,
-  verifyCandidateExperiment,
-  verifyCandidateExperimentComparison
-};
+	const raw = {};
+	for (const span of spans) for (const [k, v] of Object.entries(span.attributes)) if (typeof v === "number" && Number.isFinite(v)) raw[k] = v;
+	return raw;
+}
+//#endregion
+export { FileSystemOutcomeStore, InMemoryOutcomeStore, REFERENCE_EQUIVALENCE_INPUT_LIMITS, REFERENCE_EQUIVALENCE_JUDGE_VERSION, SelfImproveRunError, analyzeRuns, buildDefaultAnalystRegistry, buildEvidenceVector, campaignSplitDigest, compareOptimizationMethods, composeGate, createChatClient, createReferenceEquivalenceJudge, defaultProductionGate, defineAgentEval, diffGenerations, diffRunBaselineToWinner, diffRuns, evalReportingSuite, evaluatePairedMeasurements, externalTextOptimizationMethod, fromClaudeCodeSession, fromCodexSession, fromFeedbackTable, fromKimiCodeSession, fromOpenCodeSession, fromOtelSpans, fromPiSession, fromPigraphSession, fromRunRecordDir, fsCampaignStorage, gepaOptimizationMethod, heldOutGate, inMemoryCampaignStorage, llmJudge, measuredComparisonFromCandidateExperiment, observeCodeAgentSession, paretoPolicy, paretoSignificanceGate, parseAgentTrace, parseCodeAgentJsonl, partitionRunsByAuthoringModel, runCampaign, runCandidateExperiment, runEval, runImprovementLoop, runReferenceEquivalenceJudge, sealCandidateBenchmarkSuite, sealCandidateBenchmarkTask, sealCandidateExperiment, selfImprove, skillOptOptimizationMethod, summarizeExecution, verifyCandidateBenchmarkSuite, verifyCandidateBenchmarkSuiteInputs, verifyCandidateBenchmarkTask, verifyCandidateExperiment, verifyCandidateExperimentComparison };
+
 //# sourceMappingURL=index.js.map