@tangle-network/agent-eval 0.125.0 → 0.126.1

package/dist/{chunk-QFQZ3U3X.js → chunk-OCFJACJU.js}

@@ -23,7 +23,7 @@ import {
 } from "./chunk-PC4UYEBM.js";
 import {
   validateRunRecord
-} from "./chunk-LOW3U7JZ.js";
+} from "./chunk-IILEIWGW.js";
 import {
   canonicalize,
   hashJson
@@ -1934,4 +1934,4 @@ export {
   createReplayFetch,
   iterateRawCalls
 };
-//# sourceMappingURL=chunk-QFQZ3U3X.js.map
+//# sourceMappingURL=chunk-OCFJACJU.js.map

package/dist/{chunk-GID26AN4.js → chunk-P22LJ3Y2.js}

@@ -1,6 +1,6 @@
 import {
   assertLlmRoute
-} from "./chunk-EQUK3RFS.js";
+} from "./chunk-J5SQWP6Y.js";
 import {
   researchReport
 } from "./chunk-DPZAEKA6.js";
@@ -14,13 +14,11 @@ import {
 import {
   TraceEmitter
 } from "./chunk-VQMK5FMP.js";
-import {
-  validateRunRecord
-} from "./chunk-LOW3U7JZ.js";
 import {
   buildAgentProfileCell,
+  validateRunRecord,
   verifyAgentProfileCell
-} from "./chunk-GC4ATIKK.js";
+} from "./chunk-IILEIWGW.js";
 import {
   canonicalize,
   hashJson
@@ -354,4 +352,4 @@ function defaultRunId(params) {
 export {
   runEvalCampaign
 };
-//# sourceMappingURL=chunk-GID26AN4.js.map
+//# sourceMappingURL=chunk-P22LJ3Y2.js.map

package/dist/{chunk-GID26AN4.js.map → chunk-P22LJ3Y2.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/eval-campaign.ts"],"sourcesContent":["/**\n * EvalCampaign — opinionated matrix runner that wires the four\n * capture-integrity directives by construction.\n *\n * The canonical benchmark shape — matrix runner → for each\n * (variant, scenario, seed) → start a TraceEmitter → call LLMs → end the\n * run → analyze — has a bug class at the integration boundary: raw\n * events not captured, route silently wrong, integrity not asserted,\n * analyst never run. The directives in `SKILL.md § Capture integrity`\n * are the mitigations.\n *\n * `EvalCampaign` is the structural fix — consumers don't wire the\n * integrity surface themselves; the campaign owns it. Specifically:\n *\n *   - calls `assertLlmRoute` once at preflight before any work runs\n *   - constructs a per-run `TraceStore` and `RawProviderSink` via factories\n *   - constructs the `TraceEmitter` with `onRunComplete: [analyst hook]`\n *   - hands the runner an `LlmClientOptions` pre-wired with the sink and\n *     trace context — the runner can't accidentally call an LLM without\n *     capturing the raw HTTP envelope\n *   - calls `assertRunCaptured` after every `endRun` and routes failures\n *     through a configurable policy (`throw` / `mark_failed` / `log`)\n *   - assembles per-run `RunRecord`s and runs `researchReport` at the end\n *     so the campaign artifact is launch-decision-grade by default\n *   - embeds the campaign fingerprint (a SHA-256 over the canonicalised\n *     run set) and optional `preregistrationHash` in the report\n *\n * The runner contract is intentionally narrow: produce a `CampaignRunOutcome`\n * given a fully-wired `CampaignRunContext`. Everything orchestration-shaped\n * lives in the campaign. This is the inversion-of-control point — consumers\n * stop writing matrix runners and start writing scenario-runners.\n *\n * Out of scope for v1 (tracked in `docs/research-report-methodology.md`):\n *\n *   - Distributed/cluster execution (concurrency is local async)\n *   - Adaptive sampling / sequential interim looks\n *   - Resume from partial state across crashes\n *   - LLM-call retry beyond what `LlmClient` already does\n */\n\nimport {\n  type AgentProfileCell,\n  type AgentProfileCellInput,\n  buildAgentProfileCell,\n  verifyAgentProfileCell,\n} from './agent-profile-cell'\nimport { assertLlmRoute, type LlmClientOptions, type LlmRouteRequirements } from './llm-client'\nimport { canonicalize, hashJson } from './pre-registration'\nimport type {\n  JudgeScoresRecord,\n  RunJudgeMetadata,\n  RunOutcome,\n  RunRecord,\n  RunSplitTag,\n  RunTokenUsage,\n} from './run-record'\nimport { validateRunRecord } from './run-record'\nimport { type ResearchReport, type ResearchReportOptions, researchReport } from './summary-report'\nimport type { RunCompleteHook } from './trace/emitter'\nimport { TraceEmitter } from './trace/emitter'\nimport {\n  assertRunCaptured,\n  RunIntegrityError,\n  type RunIntegrityExpectations,\n  type RunIntegrityReport,\n} from './trace/integrity'\nimport { FileSystemRawProviderSink, type RawProviderSink } from './trace/raw-provider-sink'\nimport type { FailureClass } from './trace/schema'\nimport type { TraceStore } from './trace/store'\n\n// ── Public types ─────────────────────────────────────────────────────────\n\nexport interface CampaignVariant<V> {\n  id: string\n  payload: V\n}\n\nexport interface CampaignScenario {\n  scenarioId: string\n  /** Free-form metadata propagated to runs and reports. */\n  tags?: Record<string, string>\n}\n\nexport interface CampaignRunContext<V> {\n  /** Stable run id. The campaign generates this; the runner does not. */\n  runId: string\n  /** Logical experiment id (campaignId by default; overridable per-run via opts). */\n  experimentId: string\n  variant: V\n  variantId: string\n  scenarioId: string\n  scenarioTags: Record<string, string>\n  seed: number\n  splitTag: RunSplitTag\n  /**\n   * The TraceEmitter for this run, with `onRunComplete` hooks pre-wired\n   * (analyst auto-execution if configured, plus integrity check). The\n   * runner MUST call `emitter.startRun` before doing any work and either\n   * `emitter.endRun` or `emitter.abortRun` before returning.\n   */\n  emitter: TraceEmitter\n  store: TraceStore\n  rawSink: RawProviderSink\n  /**\n   * Pre-wired LLM client options — `rawSink` and `traceContext` are populated\n   * so any `callLlm(req, ctx.llmOpts)` automatically captures raw HTTP. The\n   * runner can spread additional fields if needed.\n   */\n  llmOpts: LlmClientOptions\n}\n\nexport interface CampaignRunOutcome {\n  /** Did the run pass? Mirrors `RunOutcome.pass` semantics. */\n  pass: boolean\n  /** Score for the run on its split. Maps to `searchScore` or `holdoutScore`. */\n  score: number\n  /** Mandatory cost in USD. Use 0 + raw.cost_unknown=1 only if truly unknown. */\n  costUsd: number\n  tokenUsage: RunTokenUsage\n  /** Snapshot model id (e.g. `claude-sonnet-4-6@2025-04-15`). */\n  model: string\n  /** sha256 of the effective prompt sent to the model. */\n  promptHash: string\n  /** sha256 of the effective config (model, temperature, tools, judges, splits). */\n  configHash: string\n  /** Optional extra numeric metrics to land in `outcome.raw`. */\n  raw?: Record<string, number>\n  /** Canonical cross-agent failure class from the shared `FAILURE_CLASSES`\n   *  taxonomy. Propagated to `RunRecord.failureClass` so campaign runs\n   *  aggregate failures in the same vocabulary as every other producer. */\n  failureClass?: FailureClass\n  /** Optional free-form failure detail, scoped under `failureClass`. */\n  failureMode?: string\n  /** Optional judge metadata when a judge was used. */\n  judgeMetadata?: RunJudgeMetadata\n  /**\n   * Optional per-judge / per-dim breakdown for ensemble-judged runs.\n   * Propagated to `outcome.judgeScores` on the resulting `RunRecord`.\n   * Single-judge or scalar-only runs leave this unset.\n   */\n  judgeScores?: JudgeScoresRecord\n  /**\n   * Agent profile cell observed by the runner. When supplied, it overrides\n   * `EvalCampaignOptions.agentProfile` for this run and must match the\n   * outcome's `model` and `promptHash`.\n   */\n  agentProfile?: AgentProfileCell | AgentProfileCellInput\n}\n\nexport type CampaignRunner<V> = (ctx: CampaignRunContext<V>) => Promise<CampaignRunOutcome>\n\nexport type CampaignIntegrityPolicy = 'throw' | 'mark_failed' | 'log'\n\nexport interface EvalCampaignOptions<V> {\n  /**\n   * Stable id for the campaign. Used as the default `experimentId` on\n   * every run, and folded into the campaign fingerprint.\n   */\n  campaignId: string\n  variants: CampaignVariant<V>[]\n  scenarios: CampaignScenario[]\n  /** Default `[0, 1, 2]`. */\n  seeds?: number[]\n  /** Default `'holdout'` — the split that anchors a launch decision. */\n  splitTag?: RunSplitTag\n  /** Git SHA the campaign is run against. Mandatory; `RunRecord` rejects unset. */\n  commitSha: string\n  /**\n   * LLM client config. Augmented per-run with `rawSink` and `traceContext`\n   * before being passed to the runner. The campaign asserts this config\n   * matches `routeRequirements` once at preflight.\n   */\n  llmOpts: LlmClientOptions\n  /**\n   * Default `{ requireExplicitBaseUrl: true, requireAuth: true }` — fail\n   * loud if the campaign would silently fall back to the public router or\n   * run unauthenticated. Override with an empty object to disable.\n   */\n  routeRequirements?: LlmRouteRequirements\n  /**\n   * Per-run TraceStore factory. Common shape: a fresh store per run keyed\n   * on `runId`. Implementations that share a store across the campaign\n   * are valid — the campaign only writes through `emitter`.\n   */\n  storeFactory: (params: CampaignFactoryParams) => TraceStore\n  /**\n   * Per-run RawProviderSink factory. Defaults to `FileSystemRawProviderSink`\n   * rooted at `${workDir}/raw-events/${runId}` if `workDir` is supplied;\n   * otherwise required. Forensic capture is non-negotiable in a campaign\n   * run — pass `NoopRawProviderSink` explicitly if you want to opt out.\n   */\n  rawSinkFactory?: (params: CampaignFactoryParams) => RawProviderSink\n  /**\n   * Filesystem root for default `rawSinkFactory`. Ignored if\n   * `rawSinkFactory` is supplied.\n   */\n  workDir?: string\n  /**\n   * Extra `onRunComplete` hooks the campaign appends (after its own\n   * integrity-check hook). Pass `traceAnalystOnRunComplete(...)` here.\n   */\n  onRunComplete?: RunCompleteHook[]\n  /**\n   * Per-run integrity expectations. Defaults to:\n   *   `{ llmSpansMin: 1, requireRawCoverageOfLlmSpans: true, requireOutcome: true }`.\n   * Override (e.g. `{ llmSpansMin: 0 }`) for runs that don't call LLMs.\n   */\n  integrity?: RunIntegrityExpectations\n  /** Behaviour when integrity fails. Default `'mark_failed'`. */\n  onIntegrityFailure?: CampaignIntegrityPolicy\n  /**\n   * Per-run runner. Receives a fully-wired context; produces an outcome\n   * the campaign converts into a `RunRecord`.\n   */\n  runner: CampaignRunner<V>\n  /**\n   * If set, the campaign computes `researchReport` at the end. `comparator`\n   * is a `variantId`. Other fields are forwarded verbatim.\n   */\n  report?: { comparator?: string } & Omit<\n    ResearchReportOptions,\n    'comparator' | 'preregistrationHash' | 'generatedAt'\n  >\n  /**\n   * Hash of a signed `HypothesisManifest` (see `pre-registration.ts`).\n   * Embedded in the campaign fingerprint and the research report.\n   */\n  preregistrationHash?: string\n  /** Local concurrency. Default `1` (sequential). */\n  concurrency?: number\n  /**\n   * Override the time source. Tests pass a mock to make wallMs deterministic.\n   */\n  now?: () => number\n  /** Override the runId generator. Tests pin this. */\n  runId?: (params: CampaignFactoryParams) => string\n  /**\n   * Agent profile cell for campaign runs. Static profiles can pass an object;\n   * routers or variant-specific harnesses can pass a factory. The campaign\n   * stamps the built cell onto every `RunRecord` and rejects profile/model or\n   * profile/prompt contradictions.\n   */\n  agentProfile?:\n    | AgentProfileCell\n    | AgentProfileCellInput\n    | ((\n        params: CampaignFactoryParams & {\n          variant: V\n          scenarioTags: Record<string, string>\n        },\n      ) =>\n        | AgentProfileCell\n        | AgentProfileCellInput\n        | Promise<AgentProfileCell | AgentProfileCellInput>)\n}\n\nexport interface CampaignFactoryParams {\n  campaignId: string\n  runId: string\n  variantId: string\n  scenarioId: string\n  seed: number\n}\n\nexport interface FailedRun {\n  runId: string\n  variantId: string\n  scenarioId: string\n  seed: number\n  reason: string\n  error?: string\n}\n\nexport interface EvalCampaignResult {\n  campaignId: string\n  /** SHA-256 over canonicalised `(variantIds, scenarioIds, seeds, comparator, splitTag, baseUrl, provider, preregistrationHash)`. */\n  campaignFingerprint: string\n  preregistrationHash: string | null\n  /** Successful runs only. Failed runs land in `failedRuns`. */\n  runs: RunRecord[]\n  /** Integrity reports for every successful run. */\n  integrityReports: RunIntegrityReport[]\n  failedRuns: FailedRun[]\n  /** Computed when `report` is set on options. */\n  report?: ResearchReport\n  startedAt: string\n  endedAt: string\n}\n\n// ── Implementation ───────────────────────────────────────────────────────\n\nconst DEFAULT_INTEGRITY: RunIntegrityExpectations = {\n  llmSpansMin: 1,\n  requireRawCoverageOfLlmSpans: true,\n  requireOutcome: true,\n}\n\nconst DEFAULT_ROUTE: LlmRouteRequirements = {\n  requireExplicitBaseUrl: true,\n  requireAuth: true,\n}\n\nexport async function runEvalCampaign<V>(\n  opts: EvalCampaignOptions<V>,\n): Promise<EvalCampaignResult> {\n  // ── Preflight ──────────────────────────────────────────────────────\n  assertLlmRoute(opts.llmOpts, opts.routeRequirements ?? DEFAULT_ROUTE)\n\n  if (opts.variants.length === 0) {\n    throw new Error('runEvalCampaign: variants must be non-empty.')\n  }\n  if (opts.scenarios.length === 0) {\n    throw new Error('runEvalCampaign: scenarios must be non-empty.')\n  }\n  const variantIds = new Set<string>()\n  for (const v of opts.variants) {\n    if (variantIds.has(v.id)) {\n      throw new Error(`runEvalCampaign: duplicate variant id \"${v.id}\".`)\n    }\n    variantIds.add(v.id)\n  }\n  const scenarioIds = new Set<string>()\n  for (const s of opts.scenarios) {\n    if (scenarioIds.has(s.scenarioId)) {\n      throw new Error(`runEvalCampaign: duplicate scenarioId \"${s.scenarioId}\".`)\n    }\n    scenarioIds.add(s.scenarioId)\n  }\n  if (opts.report?.comparator && !variantIds.has(opts.report.comparator)) {\n    throw new Error(\n      `runEvalCampaign: report.comparator \"${opts.report.comparator}\" is not a configured variantId.`,\n    )\n  }\n  if (!opts.commitSha) {\n    throw new Error('runEvalCampaign: commitSha is required (every RunRecord needs it).')\n  }\n\n  const seeds = opts.seeds ?? [0, 1, 2]\n  const splitTag: RunSplitTag = opts.splitTag ?? 'holdout'\n  const concurrency = Math.max(1, opts.concurrency ?? 1)\n  const integrity = { ...DEFAULT_INTEGRITY, ...(opts.integrity ?? {}) }\n  const onIntegrityFailure: CampaignIntegrityPolicy = opts.onIntegrityFailure ?? 'mark_failed'\n  const now = opts.now ?? (() => Date.now())\n  const baseUrl = (opts.llmOpts.baseUrl ?? '').replace(/\\/+$/, '')\n  const provider = opts.llmOpts.provider ?? null\n  const preregistrationHash = opts.preregistrationHash ?? null\n\n  const rawSinkFactory = opts.rawSinkFactory ?? defaultRawSinkFactory(opts.workDir)\n\n  // ── Fingerprint ────────────────────────────────────────────────────\n  const campaignFingerprint = await hashJson(\n    canonicalize({\n      campaignId: opts.campaignId,\n      variants: opts.variants.map((v) => v.id).sort(),\n      scenarios: opts.scenarios.map((s) => s.scenarioId).sort(),\n      seeds: [...seeds].sort((a, b) => a - b),\n      splitTag,\n      comparator: opts.report?.comparator ?? null,\n      baseUrl,\n      provider,\n      preregistrationHash,\n    }),\n  )\n\n  // ── Plan the matrix ────────────────────────────────────────────────\n  type Cell = { variant: CampaignVariant<V>; scenario: CampaignScenario; seed: number }\n  const cells: Cell[] = []\n  for (const variant of opts.variants) {\n    for (const scenario of opts.scenarios) {\n      for (const seed of seeds) {\n        cells.push({ variant, scenario, seed })\n      }\n    }\n  }\n\n  const startedAt = new Date(now()).toISOString()\n  const runs: RunRecord[] = []\n  const integrityReports: RunIntegrityReport[] = []\n  const failedRuns: FailedRun[] = []\n\n  // ── Execute (bounded-concurrency worker pool) ──────────────────────\n  // A genuine (non-CellExecutionError) error from any worker is a bug, not a\n  // run-level failure. We must NOT let `Promise.all` reject mid-flight and\n  // orphan the other workers' in-progress runs (emitters never finalized,\n  // sinks/handles leak, partial work silently discarded). Instead: capture the\n  // first genuine error, stop dispatching new cells so in-flight workers wind\n  // down, finalize every still-open run, then re-throw the aggregated error.\n  let cursor = 0\n  let aborting = false\n  const genuineErrors: unknown[] = []\n  // Emitters for runs that are currently mid-flight, keyed by runId. A worker\n  // registers its emitter before invoking the runner and removes it once the\n  // run is finalized (via endRun/abortRun, success or failure). Anything left\n  // here after the pool settles is an orphan we must abort.\n  const openRuns = new Map<string, TraceEmitter>()\n\n  async function worker(): Promise<void> {\n    while (!aborting) {\n      const i = cursor++\n      if (i >= cells.length) return\n      const cell = cells[i]!\n      try {\n        const result = await runOneCell(cell)\n        runs.push(result.record)\n        integrityReports.push(result.integrity)\n      } catch (err) {\n        if (err instanceof CellExecutionError) {\n          failedRuns.push(err.failed)\n          if (err.integrity) integrityReports.push(err.integrity)\n        } else {\n          // Genuine bug — not a runner failure, not an integrity failure.\n          // Capture it and stop dispatching so peers wind down gracefully;\n          // re-thrown after the pool settles. Do not surface here — that would\n          // reject Promise.all and orphan the other workers' runs.\n          genuineErrors.push(err)\n          aborting = true\n          return\n        }\n      }\n    }\n  }\n\n  async function runOneCell(\n    cell: Cell,\n  ): Promise<{ record: RunRecord; integrity: RunIntegrityReport }> {\n    const runId = (opts.runId ?? defaultRunId)({\n      campaignId: opts.campaignId,\n      runId: '', // unused by default generator\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      seed: cell.seed,\n    })\n    const factoryParams: CampaignFactoryParams = {\n      campaignId: opts.campaignId,\n      runId,\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      seed: cell.seed,\n    }\n    const store = opts.storeFactory(factoryParams)\n    const rawSink = rawSinkFactory(factoryParams)\n\n    const emitter = new TraceEmitter(store, {\n      runId,\n      now: opts.now,\n      onRunComplete: opts.onRunComplete,\n    })\n    // Track this run as open so a genuine error elsewhere in the pool can\n    // finalize it instead of orphaning it. Removed in the finally below.\n    openRuns.set(runId, emitter)\n\n    const llmOpts: LlmClientOptions = {\n      ...opts.llmOpts,\n      rawSink,\n      traceContext: { runId },\n    }\n\n    const ctx: CampaignRunContext<V> = {\n      runId,\n      experimentId: opts.campaignId,\n      variant: cell.variant.payload,\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      scenarioTags: cell.scenario.tags ?? {},\n      seed: cell.seed,\n      splitTag,\n      emitter,\n      store,\n      rawSink,\n      llmOpts,\n    }\n\n    try {\n      const wallStart = now()\n      let outcome: CampaignRunOutcome\n      try {\n        outcome = await opts.runner(ctx)\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        // The runner threw mid-execution. Abort the run so the emitter\n        // finalizes. The only benign abortRun failure is \"the runner never\n        // started the run\" (nothing to finalize). A store-write failure (disk\n        // full, FS error) is a genuine diagnostic — surface it rather than\n        // masking it as a plain runner failure.\n        await finalizeAbort(emitter, runId, message)\n        throw new CellExecutionError({\n          runId,\n          variantId: cell.variant.id,\n          scenarioId: cell.scenario.scenarioId,\n          seed: cell.seed,\n          reason: 'runner_threw',\n          error: message,\n        })\n      }\n      const wallMs = now() - wallStart\n\n      const integrityReport = await assertRunCaptured(store, runId, { ...integrity, rawSink })\n      if (!integrityReport.ok) {\n        switch (onIntegrityFailure) {\n          case 'throw':\n            throw new RunIntegrityError(integrityReport)\n          case 'mark_failed':\n            throw new CellExecutionError(\n              {\n                runId,\n                variantId: cell.variant.id,\n                scenarioId: cell.scenario.scenarioId,\n                seed: cell.seed,\n                reason: 'integrity_failed',\n                error: integrityReport.issues.map((i) => i.code).join(', '),\n              },\n              integrityReport,\n            )\n          case 'log':\n            // Caller wants the run admitted with a flagged report; fall through.\n            break\n        }\n      }\n\n      const recordOutcome: RunOutcome = {\n        raw: outcome.raw ?? {},\n      }\n      if (splitTag === 'holdout') recordOutcome.holdoutScore = outcome.score\n      else recordOutcome.searchScore = outcome.score\n      if (outcome.judgeScores !== undefined) recordOutcome.judgeScores = outcome.judgeScores\n\n      const record: RunRecord = {\n        runId,\n        experimentId: opts.campaignId,\n        candidateId: cell.variant.id,\n        seed: cell.seed,\n        model: outcome.model,\n        promptHash: outcome.promptHash,\n        configHash: outcome.configHash,\n        commitSha: opts.commitSha,\n        wallMs,\n        costUsd: outcome.costUsd,\n        tokenUsage: outcome.tokenUsage,\n        judgeMetadata: outcome.judgeMetadata,\n        outcome: recordOutcome,\n        ...(outcome.failureClass ? { failureClass: outcome.failureClass } : {}),\n        failureMode: outcome.failureMode,\n        splitTag,\n        scenarioId: cell.scenario.scenarioId,\n      }\n      const profileSource =\n        outcome.agentProfile ??\n        (typeof opts.agentProfile === 'function'\n          ? await opts.agentProfile({\n              campaignId: opts.campaignId,\n              runId,\n              variantId: cell.variant.id,\n              scenarioId: cell.scenario.scenarioId,\n              seed: cell.seed,\n              variant: cell.variant.payload,\n              scenarioTags: cell.scenario.tags ?? {},\n            })\n          : opts.agentProfile)\n      if (profileSource !== undefined) {\n        const agentProfile = await resolveAgentProfileCell(profileSource)\n        assertAgentProfileMatchesRun(agentProfile, outcome.model, outcome.promptHash)\n        record.agentProfile = agentProfile\n      }\n      return { record: validateRunRecord(record), integrity: integrityReport }\n    } finally {\n      // This run's worker has finished with it (success, run-level failure, or\n      // genuine error). It is no longer the pool's job to finalize — drop it so\n      // the post-settle sweep doesn't double-abort a finalized run.\n      openRuns.delete(runId)\n    }\n  }\n\n  const workers = Array.from({ length: Math.min(concurrency, cells.length) }, () => worker())\n  // allSettled (not all): a genuine error in one worker must not reject the\n  // pool mid-flight and orphan the others. Each worker captures its own\n  // genuine error into `genuineErrors` and returns; we re-throw below.\n  await Promise.allSettled(workers)\n\n  // Finalize any run still open after the pool wound down. With the\n  // stop-dispatch flag these are the runs that were mid-flight in peer workers\n  // when the first genuine error fired — abort them so their emitters finalize\n  // (hooks fire, store records a terminal status) instead of leaking.\n  for (const [runId, emitter] of openRuns) {\n    await finalizeAbort(emitter, runId, 'campaign aborted: genuine error in a sibling run')\n  }\n  openRuns.clear()\n\n  if (genuineErrors.length > 0) {\n    throw genuineErrors.length === 1\n      ? genuineErrors[0]\n      : new AggregateError(\n          genuineErrors,\n          `runEvalCampaign: ${genuineErrors.length} runs failed with genuine (non-run-level) errors`,\n        )\n  }\n\n  // ── Optional research report ───────────────────────────────────────\n  let report: ResearchReport | undefined\n  if (opts.report) {\n    const reportOpts: ResearchReportOptions = {\n      ...opts.report,\n      comparator: opts.report.comparator,\n      split: splitTag === 'dev' ? 'search' : splitTag,\n      generatedAt: new Date(now()).toISOString(),\n      preregistrationHash: preregistrationHash ?? undefined,\n    }\n    report = await researchReport(runs, reportOpts)\n  }\n\n  const endedAt = new Date(now()).toISOString()\n\n  return {\n    campaignId: opts.campaignId,\n    campaignFingerprint,\n    preregistrationHash,\n    runs,\n    integrityReports,\n    failedRuns,\n    report,\n    startedAt,\n    endedAt,\n  }\n}\n\n// ── Internal ─────────────────────────────────────────────────────────────\n\nclass CellExecutionError extends Error {\n  readonly failed: FailedRun\n  readonly integrity?: RunIntegrityReport\n  constructor(failed: FailedRun, integrity?: RunIntegrityReport) {\n    super(`cell ${failed.variantId}/${failed.scenarioId}@${failed.seed} failed: ${failed.reason}`)\n    this.failed = failed\n    this.integrity = integrity\n  }\n}\n\n/**\n * Abort a run whose owning work threw or was orphaned by a sibling's genuine\n * error, finalizing the emitter so hooks fire and the store records a terminal\n * status. Safe to call unconditionally: it only aborts runs that are still\n * `running`. Two no-op cases are intentional and benign:\n *\n *   - the run was never started (absent from the store) — nothing to finalize\n *   - the run is already terminal (`completed` / `failed` / `aborted`) —\n *     finalizing again would overwrite the real outcome (e.g. flip a passed run\n *     to `aborted` with `{ pass: false, notes: reason }`), so we leave it alone\n *\n * Any OTHER failure of the store read or the abort write (disk full, FS fault,\n * backend down) is a genuine diagnostic and propagates rather than being\n * swallowed.\n */\nexport async function finalizeAbort(\n  emitter: TraceEmitter,\n  runId: string,\n  reason: string,\n): Promise<void> {\n  const existing = await emitter.traceStore.getRun(runId)\n  if (existing === undefined) return // run never started; nothing to abort\n  if (existing.status !== 'running') return // already finalized; never overwrite a real outcome\n  await emitter.abortRun(reason)\n}\n\nfunction defaultRawSinkFactory(workDir: string | undefined) {\n  return (params: CampaignFactoryParams): RawProviderSink => {\n    if (!workDir) {\n      throw new Error(\n        'runEvalCampaign: rawSinkFactory not supplied and workDir not set. Pass either to enable raw provider capture, or pass `new NoopRawProviderSink()` via rawSinkFactory to opt out explicitly.',\n      )\n    }\n    return new FileSystemRawProviderSink({\n      dir: `${workDir}/raw-events/${params.runId}`,\n    })\n  }\n}\n\nasync function resolveAgentProfileCell(\n  input: AgentProfileCell | AgentProfileCellInput,\n): Promise<AgentProfileCell> {\n  if (isAgentProfileCell(input)) {\n    if (!(await verifyAgentProfileCell(input))) {\n      throw new Error(`runEvalCampaign: agentProfile.cellId does not match its content`)\n    }\n    return input\n  }\n  return buildAgentProfileCell(input)\n}\n\nfunction isAgentProfileCell(\n  input: AgentProfileCell | AgentProfileCellInput,\n): input is AgentProfileCell {\n  return 'schemaVersion' in input && 'cellId' in input\n}\n\nfunction assertAgentProfileMatchesRun(\n  profile: AgentProfileCell,\n  model: string,\n  promptHash: string,\n): void {\n  if (profile.model !== undefined && profile.model !== model) {\n    throw new Error(\n      `runEvalCampaign: agentProfile.model \"${profile.model}\" does not match outcome.model \"${model}\"`,\n    )\n  }\n  if (profile.promptHash !== undefined && profile.promptHash !== promptHash) {\n    throw new Error(\n      `runEvalCampaign: agentProfile.promptHash \"${profile.promptHash}\" does not match outcome.promptHash \"${promptHash}\"`,\n    )\n  }\n}\n\nfunction defaultRunId(params: CampaignFactoryParams): string {\n  // Stable across re-runs: fingerprint of (campaignId, variantId, scenarioId, seed).\n  // Caller can override via opts.runId for non-deterministic IDs.\n  const base = `${params.campaignId}::${params.variantId}::${params.scenarioId}::${params.seed}`\n  // Lightweight hex: we don't need crypto-grade here, just stability + uniqueness.\n  let h1 = 0x811c9dc5\n  let h2 = 0x12345678\n  for (let i = 0; i < base.length; i++) {\n    const c = base.charCodeAt(i)\n    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0\n    h2 = Math.imul(h2 ^ c, 0x9e3779b1) >>> 0\n  }\n  return `run-${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}`\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/eval-campaign.ts"],"sourcesContent":["/**\n * EvalCampaign — opinionated matrix runner that wires the four\n * capture-integrity directives by construction.\n *\n * The canonical benchmark shape — matrix runner → for each\n * (variant, scenario, seed) → start a TraceEmitter → call LLMs → end the\n * run → analyze — has a bug class at the integration boundary: raw\n * events not captured, route silently wrong, integrity not asserted,\n * analyst never run. The directives in `SKILL.md § Capture integrity`\n * are the mitigations.\n *\n * `EvalCampaign` is the structural fix — consumers don't wire the\n * integrity surface themselves; the campaign owns it. Specifically:\n *\n *   - calls `assertLlmRoute` once at preflight before any work runs\n *   - constructs a per-run `TraceStore` and `RawProviderSink` via factories\n *   - constructs the `TraceEmitter` with `onRunComplete: [analyst hook]`\n *   - hands the runner an `LlmClientOptions` pre-wired with the sink and\n *     trace context — the runner can't accidentally call an LLM without\n *     capturing the raw HTTP envelope\n *   - calls `assertRunCaptured` after every `endRun` and routes failures\n *     through a configurable policy (`throw` / `mark_failed` / `log`)\n *   - assembles per-run `RunRecord`s and runs `researchReport` at the end\n *     so the campaign artifact is launch-decision-grade by default\n *   - embeds the campaign fingerprint (a SHA-256 over the canonicalised\n *     run set) and optional `preregistrationHash` in the report\n *\n * The runner contract is intentionally narrow: produce a `CampaignRunOutcome`\n * given a fully-wired `CampaignRunContext`. Everything orchestration-shaped\n * lives in the campaign. This is the inversion-of-control point — consumers\n * stop writing matrix runners and start writing scenario-runners.\n *\n * Out of scope for v1 (tracked in `docs/research-report-methodology.md`):\n *\n *   - Distributed/cluster execution (concurrency is local async)\n *   - Adaptive sampling / sequential interim looks\n *   - Resume from partial state across crashes\n *   - LLM-call retry beyond what `LlmClient` already does\n */\n\nimport {\n  type AgentProfileCell,\n  type AgentProfileCellInput,\n  buildAgentProfileCell,\n  verifyAgentProfileCell,\n} from './agent-profile-cell'\nimport { assertLlmRoute, type LlmClientOptions, type LlmRouteRequirements } from './llm-client'\nimport { canonicalize, hashJson } from './pre-registration'\nimport type {\n  JudgeScoresRecord,\n  RunJudgeMetadata,\n  RunOutcome,\n  RunRecord,\n  RunSplitTag,\n  RunTokenUsage,\n} from './run-record'\nimport { validateRunRecord } from './run-record'\nimport { type ResearchReport, type ResearchReportOptions, researchReport } from './summary-report'\nimport type { RunCompleteHook } from './trace/emitter'\nimport { TraceEmitter } from './trace/emitter'\nimport {\n  assertRunCaptured,\n  RunIntegrityError,\n  type RunIntegrityExpectations,\n  type RunIntegrityReport,\n} from './trace/integrity'\nimport { FileSystemRawProviderSink, type RawProviderSink } from './trace/raw-provider-sink'\nimport type { FailureClass } from './trace/schema'\nimport type { TraceStore } from './trace/store'\n\n// ── Public types ─────────────────────────────────────────────────────────\n\nexport interface CampaignVariant<V> {\n  id: string\n  payload: V\n}\n\nexport interface CampaignScenario {\n  scenarioId: string\n  /** Free-form metadata propagated to runs and reports. */\n  tags?: Record<string, string>\n}\n\nexport interface CampaignRunContext<V> {\n  /** Stable run id. The campaign generates this; the runner does not. */\n  runId: string\n  /** Logical experiment id (campaignId by default; overridable per-run via opts). */\n  experimentId: string\n  variant: V\n  variantId: string\n  scenarioId: string\n  scenarioTags: Record<string, string>\n  seed: number\n  splitTag: RunSplitTag\n  /**\n   * The TraceEmitter for this run, with `onRunComplete` hooks pre-wired\n   * (analyst auto-execution if configured, plus integrity check). The\n   * runner MUST call `emitter.startRun` before doing any work and either\n   * `emitter.endRun` or `emitter.abortRun` before returning.\n   */\n  emitter: TraceEmitter\n  store: TraceStore\n  rawSink: RawProviderSink\n  /**\n   * Pre-wired LLM client options — `rawSink` and `traceContext` are populated\n   * so any `callLlm(req, ctx.llmOpts)` automatically captures raw HTTP. The\n   * runner can spread additional fields if needed.\n   */\n  llmOpts: LlmClientOptions\n}\n\nexport interface CampaignRunOutcome {\n  /** Did the run pass? Mirrors `RunOutcome.pass` semantics. */\n  pass: boolean\n  /** Score for the run on its split. Maps to `searchScore` or `holdoutScore`. */\n  score: number\n  /** Mandatory cost in USD. Use 0 + raw.cost_unknown=1 only if truly unknown. */\n  costUsd: number\n  tokenUsage: RunTokenUsage\n  /** Snapshot model id (e.g. `claude-sonnet-4-6@2025-04-15`). */\n  model: string\n  /** sha256 of the effective prompt sent to the model. */\n  promptHash: string\n  /** sha256 of the effective config (model, temperature, tools, judges, splits). */\n  configHash: string\n  /** Optional extra numeric metrics to land in `outcome.raw`. */\n  raw?: Record<string, number>\n  /** Canonical cross-agent failure class from the shared `FAILURE_CLASSES`\n   *  taxonomy. Propagated to `RunRecord.failureClass` so campaign runs\n   *  aggregate failures in the same vocabulary as every other producer. */\n  failureClass?: FailureClass\n  /** Optional free-form failure detail, scoped under `failureClass`. */\n  failureMode?: string\n  /** Optional judge metadata when a judge was used. */\n  judgeMetadata?: RunJudgeMetadata\n  /**\n   * Optional per-judge / per-dim breakdown for ensemble-judged runs.\n   * Propagated to `outcome.judgeScores` on the resulting `RunRecord`.\n   * Single-judge or scalar-only runs leave this unset.\n   */\n  judgeScores?: JudgeScoresRecord\n  /**\n   * Agent profile cell observed by the runner. When supplied, it overrides\n   * `EvalCampaignOptions.agentProfile` for this run and must match the\n   * outcome's `model` and `promptHash`.\n   */\n  agentProfile?: AgentProfileCell | AgentProfileCellInput\n}\n\nexport type CampaignRunner<V> = (ctx: CampaignRunContext<V>) => Promise<CampaignRunOutcome>\n\nexport type CampaignIntegrityPolicy = 'throw' | 'mark_failed' | 'log'\n\nexport interface EvalCampaignOptions<V> {\n  /**\n   * Stable id for the campaign. Used as the default `experimentId` on\n   * every run, and folded into the campaign fingerprint.\n   */\n  campaignId: string\n  variants: CampaignVariant<V>[]\n  scenarios: CampaignScenario[]\n  /** Default `[0, 1, 2]`. */\n  seeds?: number[]\n  /** Default `'holdout'` — the split that anchors a launch decision. */\n  splitTag?: RunSplitTag\n  /** Git SHA the campaign is run against. Mandatory; `RunRecord` rejects unset. */\n  commitSha: string\n  /**\n   * LLM client config. Augmented per-run with `rawSink` and `traceContext`\n   * before being passed to the runner. The campaign asserts this config\n   * matches `routeRequirements` once at preflight.\n   */\n  llmOpts: LlmClientOptions\n  /**\n   * Default `{ requireExplicitBaseUrl: true, requireAuth: true }` — fail\n   * loud if the campaign would silently fall back to the public router or\n   * run unauthenticated. Override with an empty object to disable.\n   */\n  routeRequirements?: LlmRouteRequirements\n  /**\n   * Per-run TraceStore factory. Common shape: a fresh store per run keyed\n   * on `runId`. Implementations that share a store across the campaign\n   * are valid — the campaign only writes through `emitter`.\n   */\n  storeFactory: (params: CampaignFactoryParams) => TraceStore\n  /**\n   * Per-run RawProviderSink factory. Defaults to `FileSystemRawProviderSink`\n   * rooted at `${workDir}/raw-events/${runId}` if `workDir` is supplied;\n   * otherwise required. Forensic capture is non-negotiable in a campaign\n   * run — pass `NoopRawProviderSink` explicitly if you want to opt out.\n   */\n  rawSinkFactory?: (params: CampaignFactoryParams) => RawProviderSink\n  /**\n   * Filesystem root for default `rawSinkFactory`. Ignored if\n   * `rawSinkFactory` is supplied.\n   */\n  workDir?: string\n  /**\n   * Extra `onRunComplete` hooks the campaign appends (after its own\n   * integrity-check hook). Pass `traceAnalystOnRunComplete(...)` here.\n   */\n  onRunComplete?: RunCompleteHook[]\n  /**\n   * Per-run integrity expectations. Defaults to:\n   *   `{ llmSpansMin: 1, requireRawCoverageOfLlmSpans: true, requireOutcome: true }`.\n   * Override (e.g. `{ llmSpansMin: 0 }`) for runs that don't call LLMs.\n   */\n  integrity?: RunIntegrityExpectations\n  /** Behaviour when integrity fails. Default `'mark_failed'`. */\n  onIntegrityFailure?: CampaignIntegrityPolicy\n  /**\n   * Per-run runner. Receives a fully-wired context; produces an outcome\n   * the campaign converts into a `RunRecord`.\n   */\n  runner: CampaignRunner<V>\n  /**\n   * If set, the campaign computes `researchReport` at the end. `comparator`\n   * is a `variantId`. Other fields are forwarded verbatim.\n   */\n  report?: { comparator?: string } & Omit<\n    ResearchReportOptions,\n    'comparator' | 'preregistrationHash' | 'generatedAt'\n  >\n  /**\n   * Hash of a signed `HypothesisManifest` (see `pre-registration.ts`).\n   * Embedded in the campaign fingerprint and the research report.\n   */\n  preregistrationHash?: string\n  /** Local concurrency. Default `1` (sequential). */\n  concurrency?: number\n  /**\n   * Override the time source. Tests pass a mock to make wallMs deterministic.\n   */\n  now?: () => number\n  /** Override the runId generator. Tests pin this. */\n  runId?: (params: CampaignFactoryParams) => string\n  /**\n   * Agent profile cell for campaign runs. Static profiles can pass an object;\n   * routers or variant-specific harnesses can pass a factory. The campaign\n   * stamps the built cell onto every `RunRecord` and rejects profile/model or\n   * profile/prompt contradictions.\n   */\n  agentProfile?:\n    | AgentProfileCell\n    | AgentProfileCellInput\n    | ((\n        params: CampaignFactoryParams & {\n          variant: V\n          scenarioTags: Record<string, string>\n        },\n      ) =>\n        | AgentProfileCell\n        | AgentProfileCellInput\n        | Promise<AgentProfileCell | AgentProfileCellInput>)\n}\n\nexport interface CampaignFactoryParams {\n  campaignId: string\n  runId: string\n  variantId: string\n  scenarioId: string\n  seed: number\n}\n\nexport interface FailedRun {\n  runId: string\n  variantId: string\n  scenarioId: string\n  seed: number\n  reason: string\n  error?: string\n}\n\nexport interface EvalCampaignResult {\n  campaignId: string\n  /** SHA-256 over canonicalised `(variantIds, scenarioIds, seeds, comparator, splitTag, baseUrl, provider, preregistrationHash)`. */\n  campaignFingerprint: string\n  preregistrationHash: string | null\n  /** Successful runs only. Failed runs land in `failedRuns`. */\n  runs: RunRecord[]\n  /** Integrity reports for every successful run. */\n  integrityReports: RunIntegrityReport[]\n  failedRuns: FailedRun[]\n  /** Computed when `report` is set on options. */\n  report?: ResearchReport\n  startedAt: string\n  endedAt: string\n}\n\n// ── Implementation ───────────────────────────────────────────────────────\n\nconst DEFAULT_INTEGRITY: RunIntegrityExpectations = {\n  llmSpansMin: 1,\n  requireRawCoverageOfLlmSpans: true,\n  requireOutcome: true,\n}\n\nconst DEFAULT_ROUTE: LlmRouteRequirements = {\n  requireExplicitBaseUrl: true,\n  requireAuth: true,\n}\n\nexport async function runEvalCampaign<V>(\n  opts: EvalCampaignOptions<V>,\n): Promise<EvalCampaignResult> {\n  // ── Preflight ──────────────────────────────────────────────────────\n  assertLlmRoute(opts.llmOpts, opts.routeRequirements ?? DEFAULT_ROUTE)\n\n  if (opts.variants.length === 0) {\n    throw new Error('runEvalCampaign: variants must be non-empty.')\n  }\n  if (opts.scenarios.length === 0) {\n    throw new Error('runEvalCampaign: scenarios must be non-empty.')\n  }\n  const variantIds = new Set<string>()\n  for (const v of opts.variants) {\n    if (variantIds.has(v.id)) {\n      throw new Error(`runEvalCampaign: duplicate variant id \"${v.id}\".`)\n    }\n    variantIds.add(v.id)\n  }\n  const scenarioIds = new Set<string>()\n  for (const s of opts.scenarios) {\n    if (scenarioIds.has(s.scenarioId)) {\n      throw new Error(`runEvalCampaign: duplicate scenarioId \"${s.scenarioId}\".`)\n    }\n    scenarioIds.add(s.scenarioId)\n  }\n  if (opts.report?.comparator && !variantIds.has(opts.report.comparator)) {\n    throw new Error(\n      `runEvalCampaign: report.comparator \"${opts.report.comparator}\" is not a configured variantId.`,\n    )\n  }\n  if (!opts.commitSha) {\n    throw new Error('runEvalCampaign: commitSha is required (every RunRecord needs it).')\n  }\n\n  const seeds = opts.seeds ?? [0, 1, 2]\n  const splitTag: RunSplitTag = opts.splitTag ?? 'holdout'\n  const concurrency = Math.max(1, opts.concurrency ?? 1)\n  const integrity = { ...DEFAULT_INTEGRITY, ...(opts.integrity ?? {}) }\n  const onIntegrityFailure: CampaignIntegrityPolicy = opts.onIntegrityFailure ?? 'mark_failed'\n  const now = opts.now ?? (() => Date.now())\n  const baseUrl = (opts.llmOpts.baseUrl ?? '').replace(/\\/+$/, '')\n  const provider = opts.llmOpts.provider ?? null\n  const preregistrationHash = opts.preregistrationHash ?? null\n\n  const rawSinkFactory = opts.rawSinkFactory ?? defaultRawSinkFactory(opts.workDir)\n\n  // ── Fingerprint ────────────────────────────────────────────────────\n  const campaignFingerprint = await hashJson(\n    canonicalize({\n      campaignId: opts.campaignId,\n      variants: opts.variants.map((v) => v.id).sort(),\n      scenarios: opts.scenarios.map((s) => s.scenarioId).sort(),\n      seeds: [...seeds].sort((a, b) => a - b),\n      splitTag,\n      comparator: opts.report?.comparator ?? null,\n      baseUrl,\n      provider,\n      preregistrationHash,\n    }),\n  )\n\n  // ── Plan the matrix ────────────────────────────────────────────────\n  type Cell = { variant: CampaignVariant<V>; scenario: CampaignScenario; seed: number }\n  const cells: Cell[] = []\n  for (const variant of opts.variants) {\n    for (const scenario of opts.scenarios) {\n      for (const seed of seeds) {\n        cells.push({ variant, scenario, seed })\n      }\n    }\n  }\n\n  const startedAt = new Date(now()).toISOString()\n  const runs: RunRecord[] = []\n  const integrityReports: RunIntegrityReport[] = []\n  const failedRuns: FailedRun[] = []\n\n  // ── Execute (bounded-concurrency worker pool) ──────────────────────\n  // A genuine (non-CellExecutionError) error from any worker is a bug, not a\n  // run-level failure. We must NOT let `Promise.all` reject mid-flight and\n  // orphan the other workers' in-progress runs (emitters never finalized,\n  // sinks/handles leak, partial work silently discarded). Instead: capture the\n  // first genuine error, stop dispatching new cells so in-flight workers wind\n  // down, finalize every still-open run, then re-throw the aggregated error.\n  let cursor = 0\n  let aborting = false\n  const genuineErrors: unknown[] = []\n  // Emitters for runs that are currently mid-flight, keyed by runId. A worker\n  // registers its emitter before invoking the runner and removes it once the\n  // run is finalized (via endRun/abortRun, success or failure). Anything left\n  // here after the pool settles is an orphan we must abort.\n  const openRuns = new Map<string, TraceEmitter>()\n\n  async function worker(): Promise<void> {\n    while (!aborting) {\n      const i = cursor++\n      if (i >= cells.length) return\n      const cell = cells[i]!\n      try {\n        const result = await runOneCell(cell)\n        runs.push(result.record)\n        integrityReports.push(result.integrity)\n      } catch (err) {\n        if (err instanceof CellExecutionError) {\n          failedRuns.push(err.failed)\n          if (err.integrity) integrityReports.push(err.integrity)\n        } else {\n          // Genuine bug — not a runner failure, not an integrity failure.\n          // Capture it and stop dispatching so peers wind down gracefully;\n          // re-thrown after the pool settles. Do not surface here — that would\n          // reject Promise.all and orphan the other workers' runs.\n          genuineErrors.push(err)\n          aborting = true\n          return\n        }\n      }\n    }\n  }\n\n  async function runOneCell(\n    cell: Cell,\n  ): Promise<{ record: RunRecord; integrity: RunIntegrityReport }> {\n    const runId = (opts.runId ?? defaultRunId)({\n      campaignId: opts.campaignId,\n      runId: '', // unused by default generator\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      seed: cell.seed,\n    })\n    const factoryParams: CampaignFactoryParams = {\n      campaignId: opts.campaignId,\n      runId,\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      seed: cell.seed,\n    }\n    const store = opts.storeFactory(factoryParams)\n    const rawSink = rawSinkFactory(factoryParams)\n\n    const emitter = new TraceEmitter(store, {\n      runId,\n      now: opts.now,\n      onRunComplete: opts.onRunComplete,\n    })\n    // Track this run as open so a genuine error elsewhere in the pool can\n    // finalize it instead of orphaning it. Removed in the finally below.\n    openRuns.set(runId, emitter)\n\n    const llmOpts: LlmClientOptions = {\n      ...opts.llmOpts,\n      rawSink,\n      traceContext: { runId },\n    }\n\n    const ctx: CampaignRunContext<V> = {\n      runId,\n      experimentId: opts.campaignId,\n      variant: cell.variant.payload,\n      variantId: cell.variant.id,\n      scenarioId: cell.scenario.scenarioId,\n      scenarioTags: cell.scenario.tags ?? {},\n      seed: cell.seed,\n      splitTag,\n      emitter,\n      store,\n      rawSink,\n      llmOpts,\n    }\n\n    try {\n      const wallStart = now()\n      let outcome: CampaignRunOutcome\n      try {\n        outcome = await opts.runner(ctx)\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        // The runner threw mid-execution. Abort the run so the emitter\n        // finalizes. The only benign abortRun failure is \"the runner never\n        // started the run\" (nothing to finalize). A store-write failure (disk\n        // full, FS error) is a genuine diagnostic — surface it rather than\n        // masking it as a plain runner failure.\n        await finalizeAbort(emitter, runId, message)\n        throw new CellExecutionError({\n          runId,\n          variantId: cell.variant.id,\n          scenarioId: cell.scenario.scenarioId,\n          seed: cell.seed,\n          reason: 'runner_threw',\n          error: message,\n        })\n      }\n      const wallMs = now() - wallStart\n\n      const integrityReport = await assertRunCaptured(store, runId, { ...integrity, rawSink })\n      if (!integrityReport.ok) {\n        switch (onIntegrityFailure) {\n          case 'throw':\n            throw new RunIntegrityError(integrityReport)\n          case 'mark_failed':\n            throw new CellExecutionError(\n              {\n                runId,\n                variantId: cell.variant.id,\n                scenarioId: cell.scenario.scenarioId,\n                seed: cell.seed,\n                reason: 'integrity_failed',\n                error: integrityReport.issues.map((i) => i.code).join(', '),\n              },\n              integrityReport,\n            )\n          case 'log':\n            // Caller wants the run admitted with a flagged report; fall through.\n            break\n        }\n      }\n\n      const recordOutcome: RunOutcome = {\n        raw: outcome.raw ?? {},\n      }\n      if (splitTag === 'holdout') recordOutcome.holdoutScore = outcome.score\n      else recordOutcome.searchScore = outcome.score\n      if (outcome.judgeScores !== undefined) recordOutcome.judgeScores = outcome.judgeScores\n\n      const record: RunRecord = {\n        runId,\n        experimentId: opts.campaignId,\n        candidateId: cell.variant.id,\n        seed: cell.seed,\n        model: outcome.model,\n        promptHash: outcome.promptHash,\n        configHash: outcome.configHash,\n        commitSha: opts.commitSha,\n        wallMs,\n        costUsd: outcome.costUsd,\n        tokenUsage: outcome.tokenUsage,\n        judgeMetadata: outcome.judgeMetadata,\n        outcome: recordOutcome,\n        ...(outcome.failureClass ? { failureClass: outcome.failureClass } : {}),\n        failureMode: outcome.failureMode,\n        splitTag,\n        scenarioId: cell.scenario.scenarioId,\n      }\n      const profileSource =\n        outcome.agentProfile ??\n        (typeof opts.agentProfile === 'function'\n          ? await opts.agentProfile({\n              campaignId: opts.campaignId,\n              runId,\n              variantId: cell.variant.id,\n              scenarioId: cell.scenario.scenarioId,\n              seed: cell.seed,\n              variant: cell.variant.payload,\n              scenarioTags: cell.scenario.tags ?? {},\n            })\n          : opts.agentProfile)\n      if (profileSource !== undefined) {\n        const agentProfile = await resolveAgentProfileCell(profileSource)\n        assertAgentProfileMatchesRun(agentProfile, outcome.model, outcome.promptHash)\n        record.agentProfile = agentProfile\n      }\n      return { record: validateRunRecord(record), integrity: integrityReport }\n    } finally {\n      // This run's worker has finished with it (success, run-level failure, or\n      // genuine error). It is no longer the pool's job to finalize — drop it so\n      // the post-settle sweep doesn't double-abort a finalized run.\n      openRuns.delete(runId)\n    }\n  }\n\n  const workers = Array.from({ length: Math.min(concurrency, cells.length) }, () => worker())\n  // allSettled (not all): a genuine error in one worker must not reject the\n  // pool mid-flight and orphan the others. Each worker captures its own\n  // genuine error into `genuineErrors` and returns; we re-throw below.\n  await Promise.allSettled(workers)\n\n  // Finalize any run still open after the pool wound down. With the\n  // stop-dispatch flag these are the runs that were mid-flight in peer workers\n  // when the first genuine error fired — abort them so their emitters finalize\n  // (hooks fire, store records a terminal status) instead of leaking.\n  for (const [runId, emitter] of openRuns) {\n    await finalizeAbort(emitter, runId, 'campaign aborted: genuine error in a sibling run')\n  }\n  openRuns.clear()\n\n  if (genuineErrors.length > 0) {\n    throw genuineErrors.length === 1\n      ? genuineErrors[0]\n      : new AggregateError(\n          genuineErrors,\n          `runEvalCampaign: ${genuineErrors.length} runs failed with genuine (non-run-level) errors`,\n        )\n  }\n\n  // ── Optional research report ───────────────────────────────────────\n  let report: ResearchReport | undefined\n  if (opts.report) {\n    const reportOpts: ResearchReportOptions = {\n      ...opts.report,\n      comparator: opts.report.comparator,\n      split: splitTag === 'dev' ? 'search' : splitTag,\n      generatedAt: new Date(now()).toISOString(),\n      preregistrationHash: preregistrationHash ?? undefined,\n    }\n    report = await researchReport(runs, reportOpts)\n  }\n\n  const endedAt = new Date(now()).toISOString()\n\n  return {\n    campaignId: opts.campaignId,\n    campaignFingerprint,\n    preregistrationHash,\n    runs,\n    integrityReports,\n    failedRuns,\n    report,\n    startedAt,\n    endedAt,\n  }\n}\n\n// ── Internal ─────────────────────────────────────────────────────────────\n\nclass CellExecutionError extends Error {\n  readonly failed: FailedRun\n  readonly integrity?: RunIntegrityReport\n  constructor(failed: FailedRun, integrity?: RunIntegrityReport) {\n    super(`cell ${failed.variantId}/${failed.scenarioId}@${failed.seed} failed: ${failed.reason}`)\n    this.failed = failed\n    this.integrity = integrity\n  }\n}\n\n/**\n * Abort a run whose owning work threw or was orphaned by a sibling's genuine\n * error, finalizing the emitter so hooks fire and the store records a terminal\n * status. Safe to call unconditionally: it only aborts runs that are still\n * `running`. Two no-op cases are intentional and benign:\n *\n *   - the run was never started (absent from the store) — nothing to finalize\n *   - the run is already terminal (`completed` / `failed` / `aborted`) —\n *     finalizing again would overwrite the real outcome (e.g. flip a passed run\n *     to `aborted` with `{ pass: false, notes: reason }`), so we leave it alone\n *\n * Any OTHER failure of the store read or the abort write (disk full, FS fault,\n * backend down) is a genuine diagnostic and propagates rather than being\n * swallowed.\n */\nexport async function finalizeAbort(\n  emitter: TraceEmitter,\n  runId: string,\n  reason: string,\n): Promise<void> {\n  const existing = await emitter.traceStore.getRun(runId)\n  if (existing === undefined) return // run never started; nothing to abort\n  if (existing.status !== 'running') return // already finalized; never overwrite a real outcome\n  await emitter.abortRun(reason)\n}\n\nfunction defaultRawSinkFactory(workDir: string | undefined) {\n  return (params: CampaignFactoryParams): RawProviderSink => {\n    if (!workDir) {\n      throw new Error(\n        'runEvalCampaign: rawSinkFactory not supplied and workDir not set. Pass either to enable raw provider capture, or pass `new NoopRawProviderSink()` via rawSinkFactory to opt out explicitly.',\n      )\n    }\n    return new FileSystemRawProviderSink({\n      dir: `${workDir}/raw-events/${params.runId}`,\n    })\n  }\n}\n\nasync function resolveAgentProfileCell(\n  input: AgentProfileCell | AgentProfileCellInput,\n): Promise<AgentProfileCell> {\n  if (isAgentProfileCell(input)) {\n    if (!(await verifyAgentProfileCell(input))) {\n      throw new Error(`runEvalCampaign: agentProfile.cellId does not match its content`)\n    }\n    return input\n  }\n  return buildAgentProfileCell(input)\n}\n\nfunction isAgentProfileCell(\n  input: AgentProfileCell | AgentProfileCellInput,\n): input is AgentProfileCell {\n  return 'schemaVersion' in input && 'cellId' in input\n}\n\nfunction assertAgentProfileMatchesRun(\n  profile: AgentProfileCell,\n  model: string,\n  promptHash: string,\n): void {\n  if (profile.model !== undefined && profile.model !== model) {\n    throw new Error(\n      `runEvalCampaign: agentProfile.model \"${profile.model}\" does not match outcome.model \"${model}\"`,\n    )\n  }\n  if (profile.promptHash !== undefined && profile.promptHash !== promptHash) {\n    throw new Error(\n      `runEvalCampaign: agentProfile.promptHash \"${profile.promptHash}\" does not match outcome.promptHash \"${promptHash}\"`,\n    )\n  }\n}\n\nfunction defaultRunId(params: CampaignFactoryParams): string {\n  // Stable across re-runs: fingerprint of (campaignId, variantId, scenarioId, seed).\n  // Caller can override via opts.runId for non-deterministic IDs.\n  const base = `${params.campaignId}::${params.variantId}::${params.scenarioId}::${params.seed}`\n  // Lightweight hex: we don't need crypto-grade here, just stability + uniqueness.\n  let h1 = 0x811c9dc5\n  let h2 = 0x12345678\n  for (let i = 0; i < base.length; i++) {\n    const c = base.charCodeAt(i)\n    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0\n    h2 = Math.imul(h2 ^ c, 0x9e3779b1) >>> 0\n  }\n  return `run-${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}`\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-SJT4OBVL.js → chunk-SDPM6554.js}

@@ -1,6 +1,6 @@
 import {
   summarizeBackendIntegrity
-} from "./chunk-D5JZ7UDZ.js";
+} from "./chunk-UCLVDLCH.js";
 import {
   paretoChart
 } from "./chunk-DPZAEKA6.js";
@@ -19,7 +19,7 @@ import {
 } from "./chunk-ZET2UAYW.js";
 import {
   resolveRunCostProvenance
-} from "./chunk-LOW3U7JZ.js";
+} from "./chunk-IILEIWGW.js";
 
 // src/contamination-guard.ts
 function checkCanaries(output, scenarios) {
@@ -1006,4 +1006,4 @@ export {
   summarizeExecution,
   analyzeRuns
 };
-//# sourceMappingURL=chunk-SJT4OBVL.js.map
+//# sourceMappingURL=chunk-SDPM6554.js.map

package/dist/{chunk-D5JZ7UDZ.js → chunk-UCLVDLCH.js}

@@ -4,7 +4,7 @@ import {
 import {
   CostAccountingIncompleteError,
   CostLedger
-} from "./chunk-GRCDRKII.js";
+} from "./chunk-WS3NZZQQ.js";
 import {
   AgentEvalError,
   ValidationError
@@ -774,7 +774,11 @@ async function runCampaign(opts) {
   const judges = opts.judges ?? [];
   const storage = opts.storage ?? fsCampaignStorage();
   const costPhase = opts.costPhase ?? "campaign";
+  const dispatchShutdownTimeoutMs = opts.dispatchShutdownTimeoutMs ?? 5e3;
   assertCampaignDesign(opts.scenarios, reps);
+  if (!Number.isSafeInteger(dispatchShutdownTimeoutMs) || dispatchShutdownTimeoutMs <= 0) {
+    throw new Error("runCampaign: dispatchShutdownTimeoutMs must be a positive safe integer");
+  }
   if (typeof opts.runDir !== "string" || opts.runDir.trim().length === 0) {
     throw new Error("runCampaign: runDir is required and must be a non-empty string");
   }
@@ -802,51 +806,71 @@ async function runCampaign(opts) {
   const cells = [];
   const artifactsByPath = {};
   const schedule = buildCellSchedule(opts.scenarios, seed, reps);
-  const abortController = new AbortController();
+  const campaignAbort = new AbortController();
+  const onOwnerAbort = () => campaignAbort.abort(opts.signal?.reason);
+  if (opts.signal?.aborted) campaignAbort.abort(opts.signal.reason);
+  else opts.signal?.addEventListener("abort", onOwnerAbort, { once: true });
+  const campaignSignal = campaignAbort.signal;
   const lanes = [];
   let nextIdx = 0;
   const cellsRef = cells;
+  let firstLaneError;
   for (let i = 0; i < maxConcurrency; i++) {
     lanes.push(
       (async () => {
-        while (true) {
-          const myIdx = nextIdx++;
-          if (myIdx >= schedule.length) return;
-          const slot = schedule[myIdx];
-          const result = await executeCell({
-            slot,
-            opts,
-            manifestHash,
-            resumable,
-            now,
-            storage,
-            buildTraceWriter: opts.buildTraceWriter ?? defaultBuildTraceWriter(storage),
-            signal: abortController.signal,
-            dispatchTimeoutMs: opts.dispatchTimeoutMs,
-            costLedger,
-            costPhase,
-            runAttemptId
-          });
-          cellsRef.push(result.cell);
-          Object.assign(artifactsByPath, result.artifactsByPath);
-          if (opts.labeledStore && opts.labeledStore !== "off" && !result.cell.error) {
-            await captureToStore({
-              store: opts.labeledStore,
-              cell: result.cell,
-              scenario: slot.scenario,
+        try {
+          while (true) {
+            if (campaignSignal.aborted) return;
+            const myIdx = nextIdx++;
+            if (myIdx >= schedule.length) return;
+            const slot = schedule[myIdx];
+            const result = await executeCell({
+              slot,
               opts,
-              now
-            }).catch((err) => {
-              console.warn(
-                `[runCampaign] capture failed for ${result.cell.cellId}: ${err instanceof Error ? err.message : String(err)}`
-              );
+              manifestHash,
+              resumable,
+              now,
+              storage,
+              buildTraceWriter: opts.buildTraceWriter ?? defaultBuildTraceWriter(storage),
+              signal: campaignSignal,
+              dispatchTimeoutMs: opts.dispatchTimeoutMs,
+              dispatchShutdownTimeoutMs,
+              costLedger,
+              costPhase,
+              runAttemptId
             });
+            cellsRef.push(result.cell);
+            Object.assign(artifactsByPath, result.artifactsByPath);
+            if (opts.labeledStore && opts.labeledStore !== "off" && !result.cell.error) {
+              await captureToStore({
+                store: opts.labeledStore,
+                cell: result.cell,
+                scenario: slot.scenario,
+                opts,
+                now
+              }).catch((err) => {
+                console.warn(
+                  `[runCampaign] capture failed for ${result.cell.cellId}: ${err instanceof Error ? err.message : String(err)}`
+                );
+              });
+            }
           }
+        } catch (error) {
+          if (firstLaneError === void 0) {
+            firstLaneError = error;
+            campaignAbort.abort(error);
+          }
+          throw error;
         }
       })()
     );
   }
-  await Promise.all(lanes);
+  const laneResults = await Promise.allSettled(lanes);
+  opts.signal?.removeEventListener("abort", onOwnerAbort);
+  const failedLane = laneResults.find(
+    (result) => result.status === "rejected"
+  );
+  if (failedLane) throw firstLaneError ?? failedLane.reason;
   const endedAt = now();
   cellsRef.sort((a, b) => a.cellId.localeCompare(b.cellId));
   const campaignCost = costLedger.summary({ tags: { runDir: opts.runDir } });
@@ -876,6 +900,7 @@ async function executeCell(args) {
   const cellDir = join3(args.opts.runDir, args.slot.cellId.replace(/[^a-zA-Z0-9_-]/g, "_"));
   storage.ensureDir(cellDir);
   const stableCostTags = {
+    ...args.opts.costTags ?? {},
     runDir: args.opts.runDir,
     cellId: args.slot.cellId,
     scenarioId: args.slot.scenario.id,
@@ -924,6 +949,7 @@ async function executeCell(args) {
   const startMs = Date.now();
   const trace = args.buildTraceWriter(args.slot.cellId, cellDir);
   const artifactsByPath = {};
+  let paidCallStarted = false;
   const artifacts = {
     async write(path, content) {
       const fullPath = join3(cellDir, path);
@@ -938,6 +964,7 @@ async function executeCell(args) {
   };
   const cost = {
     async runPaidCall(input) {
+      paidCallStarted = true;
       const result = await args.costLedger.runPaidCall({
         ...input,
         channel: input.channel ?? "agent",
@@ -972,35 +999,77 @@ async function executeCell(args) {
   };
   let artifact;
   let errorMessage;
+  let dispatched;
   const timeoutMs = args.dispatchTimeoutMs;
   let timeoutTimer;
+  let removeAbortListener = () => void 0;
   try {
-    const dispatched = args.opts.dispatch(args.slot.scenario, ctx);
+    dispatched = Promise.resolve(args.opts.dispatch(args.slot.scenario, ctx));
+    const aborted = new Promise((_resolve, reject) => {
+      const rejectAbort = () => {
+        const reason = cellAbort.signal.reason;
+        reject(reason instanceof Error ? reason : new Error(String(reason ?? "dispatch aborted")));
+      };
+      if (cellAbort.signal.aborted) {
+        rejectAbort();
+        return;
+      }
+      cellAbort.signal.addEventListener("abort", rejectAbort, { once: true });
+      removeAbortListener = () => cellAbort.signal.removeEventListener("abort", rejectAbort);
+    });
     if (timeoutMs !== void 0 && timeoutMs > 0) {
       artifact = await Promise.race([
         dispatched,
+        aborted,
         new Promise((_, reject) => {
           timeoutTimer = setTimeout(() => {
-            cellAbort.abort(new Error("dispatch timeout"));
-            reject(
-              new Error(
-                `dispatch exceeded ${timeoutMs}ms for cell '${args.slot.cellId}' \u2014 aborted and failed loud (no silent hang)`
-              )
+            const timeoutError = new Error(
+              `dispatch exceeded ${timeoutMs}ms for cell '${args.slot.cellId}' \u2014 aborted and failed loud (no silent hang)`
             );
+            reject(timeoutError);
+            cellAbort.abort(timeoutError);
           }, timeoutMs);
           if (typeof timeoutTimer.unref === "function")
             timeoutTimer.unref();
         })
       ]);
     } else {
-      artifact = await dispatched;
+      artifact = await Promise.race([dispatched, aborted]);
     }
   } catch (err) {
     errorMessage = err instanceof Error ? err.message : String(err);
   } finally {
     if (timeoutTimer) clearTimeout(timeoutTimer);
+    removeAbortListener();
     args.signal.removeEventListener("abort", onCampaignAbort);
   }
+  if (dispatched) {
+    const dispatchSettled = await settlesWithin(dispatched, args.dispatchShutdownTimeoutMs);
+    if (!dispatchSettled) {
+      await trace.flush();
+      throw new CostAccountingIncompleteError(
+        `dispatch for cell '${args.slot.cellId}' ignored cancellation and did not stop within ${args.dispatchShutdownTimeoutMs}ms; no campaign result was produced`
+      );
+    }
+  }
+  if (paidCallStarted) {
+    if (typeof args.costLedger.waitForIdle !== "function") {
+      await trace.flush();
+      throw new CostAccountingIncompleteError(
+        `cost ledger for cell '${args.slot.cellId}' cannot prove that paid calls stopped`
+      );
+    }
+    const paidCallsSettled = await args.costLedger.waitForIdle({
+      timeoutMs: args.dispatchShutdownTimeoutMs,
+      filter: { channel: "agent", phase: args.costPhase, tags: costTags }
+    });
+    if (!paidCallsSettled) {
+      await trace.flush();
+      throw new CostAccountingIncompleteError(
+        `paid calls for cell '${args.slot.cellId}' did not settle within ${args.dispatchShutdownTimeoutMs}ms; no campaign result was produced`
+      );
+    }
+  }
   const agentReceipts = args.costLedger.list({ channel: "agent", tags: costTags });
   const agentCost = args.costLedger.summary({ channel: "agent", tags: costTags });
   const tokenUsage = {
@@ -1072,6 +1141,23 @@ async function executeCell(args) {
   }
   return { cell, artifactsByPath };
 }
+function settlesWithin(promise, timeoutMs) {
+  return new Promise((resolve) => {
+    let completed = false;
+    let timer;
+    const finish = (value) => {
+      if (completed) return;
+      completed = true;
+      if (timer) clearTimeout(timer);
+      resolve(value);
+    };
+    timer = setTimeout(() => finish(false), timeoutMs);
+    promise.then(
+      () => finish(true),
+      () => finish(true)
+    );
+  });
+}
 function planCampaignRun(opts) {
   const seed = opts.seed ?? 42;
   const reps = opts.reps ?? 1;
@@ -1356,6 +1442,15 @@ export {
   inMemoryVerdictCache,
   fileVerdictCache,
   cachedJudge,
+  assertCampaignDesign,
+  campaignScenarioIdentity,
+  campaignSplitDigestFromIdentities,
+  campaignSplitDigest,
+  assertCampaignSplitIdentity,
+  campaignCoverage,
+  formatCoverageFailures,
+  tangleTracesRoot,
+  resolveRunDir,
   probeAtomicFileLock,
   tryAcquireAtomicFileLock,
   SearchLedgerError,
@@ -1366,16 +1461,7 @@ export {
   fsCampaignStorage,
   inMemoryCampaignStorage,
   createRunCostLedger,
-  assertCampaignDesign,
-  campaignScenarioIdentity,
-  campaignSplitDigestFromIdentities,
-  campaignSplitDigest,
-  assertCampaignSplitIdentity,
-  campaignCoverage,
-  formatCoverageFailures,
-  tangleTracesRoot,
-  resolveRunDir,
   runCampaign,
   planCampaignRun
 };
-//# sourceMappingURL=chunk-D5JZ7UDZ.js.map
+//# sourceMappingURL=chunk-UCLVDLCH.js.map