@tangle-network/agent-eval 0.22.0 → 0.23.0

package/dist/chunk-AXHNWLIX.js

@@ -0,0 +1,246 @@
+// src/meta-eval/rubric-predictive-validity.ts
+async function rubricPredictiveValidity(input) {
+  const minSamples = input.minSamples ?? 8;
+  const reduction = input.reduction ?? "latest";
+  const resamples = input.bootstrapResamples ?? 500;
+  const rng = makeRng(input.seed);
+  const outcomes = await input.outcomes.list();
+  const outcomesByRun = /* @__PURE__ */ new Map();
+  for (const o of outcomes) {
+    const arr = outcomesByRun.get(o.runId) ?? [];
+    arr.push(o);
+    outcomesByRun.set(o.runId, arr);
+  }
+  const observedRubrics = /* @__PURE__ */ new Set();
+  for (const r of input.runs) {
+    for (const k of Object.keys(r.outcome.raw)) observedRubrics.add(k);
+  }
+  const rubrics = input.rubrics ?? [...observedRubrics];
+  const buckets = [];
+  for (const r of rubrics) {
+    for (const o of input.outcomeMetrics) {
+      buckets.push({ rubric: r, outcome: o, xs: [], ys: [] });
+    }
+  }
+  let joined = 0;
+  let skipped = 0;
+  for (const run of input.runs) {
+    const os = outcomesByRun.get(run.runId);
+    if (!os || os.length === 0) {
+      skipped++;
+      continue;
+    }
+    let joinedThisRun = false;
+    for (const r of rubrics) {
+      const x = run.outcome.raw[r];
+      if (typeof x !== "number" || !Number.isFinite(x)) continue;
+      for (const o of input.outcomeMetrics) {
+        const values = os.map((row) => row.metrics[o]).filter((v) => typeof v === "number" && Number.isFinite(v));
+        if (values.length === 0) continue;
+        const y = reduce(values, os, o, reduction);
+        if (y === null) continue;
+        const bucket = buckets.find((b) => b.rubric === r && b.outcome === o);
+        bucket.xs.push(x);
+        bucket.ys.push(y);
+        joinedThisRun = true;
+      }
+    }
+    if (joinedThisRun) joined++;
+  }
+  const pairs = [];
+  for (const b of buckets) {
+    if (b.xs.length < minSamples) continue;
+    const pearson = pearsonR(b.xs, b.ys);
+    const spearman = pearsonR(rankWithTies(b.xs), rankWithTies(b.ys));
+    const ci = bootstrapCi(b.xs, b.ys, resamples, rng);
+    const verdict = Math.abs(spearman) >= 0.7 ? "load_bearing" : Math.abs(spearman) >= 0.4 ? "informative" : "decorative";
+    pairs.push({
+      rubric: b.rubric,
+      outcome: b.outcome,
+      n: b.xs.length,
+      pearson,
+      spearman,
+      ci95: ci,
+      verdict
+    });
+  }
+  const byRubric = /* @__PURE__ */ new Map();
+  for (const p of pairs) {
+    const arr = byRubric.get(p.rubric) ?? [];
+    arr.push(p);
+    byRubric.set(p.rubric, arr);
+  }
+  const ranked = [...byRubric.entries()].map(([rubric, ps]) => {
+    const best = ps.reduce((a, b) => Math.abs(b.spearman) > Math.abs(a.spearman) ? b : a);
+    return {
+      rubric,
+      bestOutcome: best.outcome,
+      spearman: best.spearman,
+      pearson: best.pearson,
+      n: best.n,
+      verdict: best.verdict
+    };
+  }).sort((a, b) => Math.abs(b.spearman) - Math.abs(a.spearman));
+  const rubricsWithoutData = rubrics.filter((r) => !byRubric.has(r));
+  return { pairs, ranked, joinedSamples: joined, skippedRuns: skipped, rubricsWithoutData };
+}
+function reduce(values, outcomes, metric, kind) {
+  if (values.length === 0) return null;
+  if (kind === "mean") return values.reduce((s, v) => s + v, 0) / values.length;
+  if (kind === "max") return Math.max(...values);
+  const sorted = [...outcomes].filter((o) => typeof o.metrics[metric] === "number").sort((a, b) => b.capturedAt - a.capturedAt);
+  return sorted[0]?.metrics[metric] ?? null;
+}
+function pearsonR(a, b) {
+  if (a.length !== b.length || a.length < 2) return Number.NaN;
+  const ma = a.reduce((s, v) => s + v, 0) / a.length;
+  const mb = b.reduce((s, v) => s + v, 0) / b.length;
+  let num = 0, da = 0, db = 0;
+  for (let i = 0; i < a.length; i++) {
+    const xa = a[i] - ma;
+    const xb = b[i] - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  if (da === 0 || db === 0) return da === 0 && db === 0 ? 1 : 0;
+  return num / Math.sqrt(da * db);
+}
+function rankWithTies(xs) {
+  const indexed = xs.map((v, i) => ({ v, i })).sort((a, b) => a.v - b.v);
+  const r = new Array(xs.length);
+  for (let i = 0; i < indexed.length; ) {
+    let j = i;
+    while (j + 1 < indexed.length && indexed[j + 1].v === indexed[i].v) j++;
+    const avg = (i + j + 2) / 2;
+    for (let k = i; k <= j; k++) r[indexed[k].i] = avg;
+    i = j + 1;
+  }
+  return r;
+}
+function bootstrapCi(xs, ys, iterations, rng) {
+  const n = xs.length;
+  if (n < 3) return { low: Number.NaN, high: Number.NaN };
+  const samples = [];
+  for (let b = 0; b < iterations; b++) {
+    const rx = new Array(n);
+    const ry = new Array(n);
+    for (let i = 0; i < n; i++) {
+      const idx = Math.floor(rng() * n);
+      rx[i] = xs[idx];
+      ry[i] = ys[idx];
+    }
+    const r = pearsonR(rx, ry);
+    if (Number.isFinite(r)) samples.push(r);
+  }
+  samples.sort((a, b) => a - b);
+  if (samples.length === 0) return { low: Number.NaN, high: Number.NaN };
+  return {
+    low: samples[Math.floor(0.025 * samples.length)],
+    high: samples[Math.min(samples.length - 1, Math.floor(0.975 * samples.length))]
+  };
+}
+function makeRng(seed) {
+  if (seed === void 0) return Math.random;
+  let s = seed >>> 0;
+  return () => {
+    s = s + 1831565813 >>> 0;
+    let t = s;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/sequential.ts
+function pairedEvalueSequence(deltas, opts = {}) {
+  const c = opts.bound ?? 1;
+  const alpha = opts.alpha ?? 0.05;
+  const initialShrink = opts.initialBetShrinkage ?? 0.5;
+  const rope = opts.rope ?? null;
+  if (c <= 0) throw new Error("pairedEvalueSequence: bound must be > 0");
+  if (alpha <= 0 || alpha >= 1) throw new Error("pairedEvalueSequence: alpha must be in (0,1)");
+  if (rope && !(Number.isFinite(rope.low) && Number.isFinite(rope.high) && rope.low <= rope.high)) {
+    throw new Error("pairedEvalueSequence: rope must satisfy low \u2264 high");
+  }
+  const steps = [];
+  let clipped = false;
+  let evalue = 1;
+  let decisionFiredAt = null;
+  let sum = 0;
+  let sumSq = 0;
+  let count = 0;
+  for (let i = 0; i < deltas.length; i++) {
+    let d = deltas[i];
+    if (d < -c || d > c) {
+      d = Math.max(-c, Math.min(c, d));
+      clipped = true;
+    }
+    const muHat = count === 0 ? 0 : sum / count;
+    const varHat = count === 0 ? c * c : Math.max(1e-12, sumSq / count - muHat * muHat);
+    const t = i + 1;
+    const shrink = initialShrink * Math.min(1, count / 32);
+    let lambda = muHat / (varHat + c * c) * shrink;
+    const lambdaMax = 0.99 / c;
+    if (lambda > lambdaMax) lambda = lambdaMax;
+    if (lambda < -lambdaMax) lambda = -lambdaMax;
+    evalue = evalue * (1 + lambda * d);
+    if (!Number.isFinite(evalue) || evalue < 0) evalue = 0;
+    sum += d;
+    sumSq += d * d;
+    count += 1;
+    const pValue = Math.min(1, 1 / Math.max(evalue, 1e-300));
+    const cs = empiricalBernsteinCs(sum, sumSq, count, c, alpha);
+    let decision = "continue";
+    if (rope && cs.low >= rope.low && cs.high <= rope.high) decision = "equivalent";
+    else if (evalue >= 2 / alpha && muHat > 0) decision = "promote_now";
+    else if (evalue >= 2 / alpha && muHat < 0) decision = "reject_now";
+    else if (rope && cs.high < rope.low) decision = "reject_now";
+    if (decision !== "continue" && decisionFiredAt === null) decisionFiredAt = t;
+    steps.push({ t, delta: d, evalue, pValue, csLow: cs.low, csHigh: cs.high, decision });
+  }
+  const finalDecision = steps.length === 0 ? "continue" : steps[steps.length - 1].decision;
+  return { steps, finalDecision, decisionFiredAt, clipped };
+}
+function evaluateInterimReleaseConfidence(input) {
+  const candidates = input.deltaSeries.map((s) => {
+    const seq = pairedEvalueSequence(s.deltas, {
+      alpha: input.alpha,
+      bound: input.bound,
+      rope: input.rope
+    });
+    const last = seq.steps[seq.steps.length - 1];
+    return {
+      candidateId: s.candidateId,
+      decision: seq.finalDecision,
+      decisionFiredAt: seq.decisionFiredAt,
+      finalEvalue: last?.evalue ?? 1,
+      finalPValue: last?.pValue ?? 1,
+      pairs: seq.steps.length,
+      csLow: last?.csLow ?? Number.NEGATIVE_INFINITY,
+      csHigh: last?.csHigh ?? Number.POSITIVE_INFINITY
+    };
+  });
+  const promote = candidates.find((c) => c.decision === "promote_now");
+  if (promote) return { candidates, recommendation: { decision: "promote_now", candidateId: promote.candidateId } };
+  const live = candidates.find((c) => c.decision === "continue");
+  if (live) return { candidates, recommendation: { decision: "continue", candidateId: null } };
+  const equiv = candidates.find((c) => c.decision === "equivalent");
+  if (equiv) return { candidates, recommendation: { decision: "equivalent", candidateId: equiv.candidateId } };
+  return { candidates, recommendation: { decision: "reject_now", candidateId: null } };
+}
+function empiricalBernsteinCs(sum, sumSq, n, bound, alpha) {
+  if (n === 0) return { low: -bound, high: bound };
+  const mean = sum / n;
+  const variance = Math.max(0, sumSq / n - mean * mean);
+  const psi = Math.log(2 / alpha) + 1.7 * Math.log(Math.log(Math.max(Math.E, n)) + 1);
+  const radius = Math.sqrt(2 * variance * psi / n) + 3 * bound * psi / n;
+  return { low: mean - radius, high: mean + radius };
+}
+
+export {
+  rubricPredictiveValidity,
+  pairedEvalueSequence,
+  evaluateInterimReleaseConfidence
+};
+//# sourceMappingURL=chunk-AXHNWLIX.js.map

package/dist/chunk-AXHNWLIX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/meta-eval/rubric-predictive-validity.ts","../src/sequential.ts"],"sourcesContent":["/**\n * Rubric predictive validity — does our eval rubric predict deployment\n * outcomes?\n *\n * `correlationStudy` (already in this package) joins a `TraceStore` to an\n * `OutcomeStore` and computes Pearson + Spearman + bootstrap CI for each\n * (eval-metric, outcome-metric) pair. That answers \"does X correlate with\n * Y at all.\" `rubricPredictiveValidity` is the campaign-shaped wrapper\n * around it: take a sequence of `RunRecord`s (the canonical campaign\n * artifact) and a `DeploymentOutcomeStore`, join on `runId`, return a\n * ranked verdict on every rubric whose dimension scores were captured in\n * `outcome.raw`.\n *\n * The point — quoting the methodology doc — is that **without this loop\n * every rubric is faith-based**. Once it's wired, you know which rubrics\n * have earned their promotion power and which ones are decoration.\n *\n *   const validity = await rubricPredictiveValidity({\n *     runs: lastQuarter,\n *     outcomes: shipFlagOutcomeStore,\n *     outcomeMetrics: ['revenue_lift', 'retention_30d', 'csat'],\n *     rubrics: ['anti_slop', 'semantic_concept', 'tool_recovery'],\n *   })\n *   for (const r of validity.ranked) {\n *     console.log(`${r.rubric} → ${r.bestOutcome}: ρ=${r.spearman.toFixed(2)}`)\n *   }\n *\n * The function is intentionally read-only. Use the verdict to deprecate\n * decorative rubrics, re-weight composite scores, or trigger a\n * recalibration sweep when predictive validity drops below a threshold.\n */\n\nimport type { RunRecord } from '../run-record'\nimport type { DeploymentOutcome, OutcomeStore } from './outcome-store'\n\nexport interface RubricPredictiveValidityInput {\n  /**\n   * Canonical campaign output. Each record's `outcome.raw[<rubricId>]`\n   * provides the eval score; missing keys are silently skipped per pair.\n   */\n  runs: RunRecord[]\n  outcomes: OutcomeStore\n  /**\n   * Outcome metric names to evaluate against. Each must appear in at\n   * least one `DeploymentOutcome.metrics` keyspace; pairs with too few\n   * joined samples are excluded from the result.\n   */\n  outcomeMetrics: string[]\n  /**\n   * Rubric ids to evaluate. Must appear as keys in `RunRecord.outcome.raw`.\n   * If omitted, every numeric key in `outcome.raw` across the run set is\n   * treated as a rubric.\n   */\n  rubrics?: string[]\n  /** Minimum joined-sample count before a pair is reported. Default 8. */\n  minSamples?: number\n  /** Bootstrap resamples for CI. Default 500. */\n  bootstrapResamples?: number\n  /** Random seed for the bootstrap (mulberry32). Default unset (Math.random). */\n  seed?: number\n  /**\n   * Reduction when multiple outcomes attach to one runId. Default `'latest'`\n   * (most recently captured).\n   */\n  reduction?: 'latest' | 'mean' | 'max'\n}\n\nexport interface RubricOutcomePair {\n  rubric: string\n  outcome: string\n  n: number\n  pearson: number\n  spearman: number\n  ci95: { low: number; high: number }\n  /**\n   * Verdict bucket. `load_bearing` ≥ 0.7, `informative` ≥ 0.4,\n   * `decorative` < 0.4 in absolute correlation. A negative correlation\n   * with a desired outcome is also `decorative` — actively misleading\n   * is worse than uninformative.\n   */\n  verdict: 'load_bearing' | 'informative' | 'decorative'\n}\n\nexport interface RubricRanking {\n  rubric: string\n  /** Outcome metric this rubric correlated best with. */\n  bestOutcome: string\n  spearman: number\n  pearson: number\n  n: number\n  verdict: RubricOutcomePair['verdict']\n}\n\nexport interface RubricPredictiveValidityReport {\n  pairs: RubricOutcomePair[]\n  /** Per-rubric best pair, sorted descending by |spearman|. */\n  ranked: RubricRanking[]\n  joinedSamples: number\n  skippedRuns: number\n  /** Rubrics that were declared but never produced a usable score. */\n  rubricsWithoutData: string[]\n}\n\nexport async function rubricPredictiveValidity(\n  input: RubricPredictiveValidityInput,\n): Promise<RubricPredictiveValidityReport> {\n  const minSamples = input.minSamples ?? 8\n  const reduction = input.reduction ?? 'latest'\n  const resamples = input.bootstrapResamples ?? 500\n  const rng = makeRng(input.seed)\n\n  const outcomes = await input.outcomes.list()\n  const outcomesByRun = new Map<string, DeploymentOutcome[]>()\n  for (const o of outcomes) {\n    const arr = outcomesByRun.get(o.runId) ?? []\n    arr.push(o)\n    outcomesByRun.set(o.runId, arr)\n  }\n\n  // Discover rubrics: caller-declared OR every numeric key in outcome.raw\n  // observed across runs.\n  const observedRubrics = new Set<string>()\n  for (const r of input.runs) {\n    for (const k of Object.keys(r.outcome.raw)) observedRubrics.add(k)\n  }\n  const rubrics = input.rubrics ?? [...observedRubrics]\n\n  // Collect aligned (x, y) pairs per (rubric, outcome).\n  type Bucket = { rubric: string; outcome: string; xs: number[]; ys: number[] }\n  const buckets: Bucket[] = []\n  for (const r of rubrics) {\n    for (const o of input.outcomeMetrics) {\n      buckets.push({ rubric: r, outcome: o, xs: [], ys: [] })\n    }\n  }\n\n  let joined = 0\n  let skipped = 0\n  for (const run of input.runs) {\n    const os = outcomesByRun.get(run.runId)\n    if (!os || os.length === 0) { skipped++; continue }\n    let joinedThisRun = false\n    for (const r of rubrics) {\n      const x = run.outcome.raw[r]\n      if (typeof x !== 'number' || !Number.isFinite(x)) continue\n      for (const o of input.outcomeMetrics) {\n        const values = os\n          .map((row) => row.metrics[o])\n          .filter((v): v is number => typeof v === 'number' && Number.isFinite(v))\n        if (values.length === 0) continue\n        const y = reduce(values, os, o, reduction)\n        if (y === null) continue\n        const bucket = buckets.find((b) => b.rubric === r && b.outcome === o)!\n        bucket.xs.push(x)\n        bucket.ys.push(y)\n        joinedThisRun = true\n      }\n    }\n    if (joinedThisRun) joined++\n  }\n\n  const pairs: RubricOutcomePair[] = []\n  for (const b of buckets) {\n    if (b.xs.length < minSamples) continue\n    const pearson = pearsonR(b.xs, b.ys)\n    const spearman = pearsonR(rankWithTies(b.xs), rankWithTies(b.ys))\n    const ci = bootstrapCi(b.xs, b.ys, resamples, rng)\n    const verdict: RubricOutcomePair['verdict'] =\n      Math.abs(spearman) >= 0.7 ? 'load_bearing'\n      : Math.abs(spearman) >= 0.4 ? 'informative'\n      : 'decorative'\n    pairs.push({\n      rubric: b.rubric, outcome: b.outcome, n: b.xs.length,\n      pearson, spearman, ci95: ci, verdict,\n    })\n  }\n\n  const byRubric = new Map<string, RubricOutcomePair[]>()\n  for (const p of pairs) {\n    const arr = byRubric.get(p.rubric) ?? []\n    arr.push(p)\n    byRubric.set(p.rubric, arr)\n  }\n  const ranked: RubricRanking[] = [...byRubric.entries()]\n    .map(([rubric, ps]) => {\n      const best = ps.reduce((a, b) => (Math.abs(b.spearman) > Math.abs(a.spearman) ? b : a))\n      return {\n        rubric,\n        bestOutcome: best.outcome,\n        spearman: best.spearman,\n        pearson: best.pearson,\n        n: best.n,\n        verdict: best.verdict,\n      }\n    })\n    .sort((a, b) => Math.abs(b.spearman) - Math.abs(a.spearman))\n\n  const rubricsWithoutData = rubrics.filter((r) => !byRubric.has(r))\n\n  return { pairs, ranked, joinedSamples: joined, skippedRuns: skipped, rubricsWithoutData }\n}\n\n// ── Helpers ──────────────────────────────────────────────────────────────\n\nfunction reduce(\n  values: number[],\n  outcomes: DeploymentOutcome[],\n  metric: string,\n  kind: 'latest' | 'mean' | 'max',\n): number | null {\n  if (values.length === 0) return null\n  if (kind === 'mean') return values.reduce((s, v) => s + v, 0) / values.length\n  if (kind === 'max') return Math.max(...values)\n  // 'latest'\n  const sorted = [...outcomes]\n    .filter((o) => typeof o.metrics[metric] === 'number')\n    .sort((a, b) => b.capturedAt - a.capturedAt)\n  return sorted[0]?.metrics[metric] ?? null\n}\n\nfunction pearsonR(a: number[], b: number[]): number {\n  if (a.length !== b.length || a.length < 2) return Number.NaN\n  const ma = a.reduce((s, v) => s + v, 0) / a.length\n  const mb = b.reduce((s, v) => s + v, 0) / b.length\n  let num = 0, da = 0, db = 0\n  for (let i = 0; i < a.length; i++) {\n    const xa = a[i]! - ma\n    const xb = b[i]! - mb\n    num += xa * xb; da += xa * xa; db += xb * xb\n  }\n  if (da === 0 || db === 0) return da === 0 && db === 0 ? 1 : 0\n  return num / Math.sqrt(da * db)\n}\n\nfunction rankWithTies(xs: number[]): number[] {\n  const indexed = xs.map((v, i) => ({ v, i })).sort((a, b) => a.v - b.v)\n  const r = new Array<number>(xs.length)\n  for (let i = 0; i < indexed.length; ) {\n    let j = i\n    while (j + 1 < indexed.length && indexed[j + 1]!.v === indexed[i]!.v) j++\n    const avg = (i + j + 2) / 2\n    for (let k = i; k <= j; k++) r[indexed[k]!.i] = avg\n    i = j + 1\n  }\n  return r\n}\n\nfunction bootstrapCi(\n  xs: number[],\n  ys: number[],\n  iterations: number,\n  rng: () => number,\n): { low: number; high: number } {\n  const n = xs.length\n  if (n < 3) return { low: Number.NaN, high: Number.NaN }\n  const samples: number[] = []\n  for (let b = 0; b < iterations; b++) {\n    const rx = new Array<number>(n)\n    const ry = new Array<number>(n)\n    for (let i = 0; i < n; i++) {\n      const idx = Math.floor(rng() * n)\n      rx[i] = xs[idx]!\n      ry[i] = ys[idx]!\n    }\n    const r = pearsonR(rx, ry)\n    if (Number.isFinite(r)) samples.push(r)\n  }\n  samples.sort((a, b) => a - b)\n  if (samples.length === 0) return { low: Number.NaN, high: Number.NaN }\n  return {\n    low: samples[Math.floor(0.025 * samples.length)]!,\n    high: samples[Math.min(samples.length - 1, Math.floor(0.975 * samples.length))]!,\n  }\n}\n\nfunction makeRng(seed?: number): () => number {\n  if (seed === undefined) return Math.random\n  let s = seed >>> 0\n  return () => {\n    s = (s + 0x6D2B79F5) >>> 0\n    let t = s\n    t = Math.imul(t ^ (t >>> 15), t | 1)\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296\n  }\n}\n","/**\n * Always-valid sequential evaluation.\n *\n * `researchReport` (0.21+) assumes a single pre-specified analysis. Real\n * consumers run campaigns weekly / nightly / per-PR; each new run silently\n * inflates the false-discovery rate, because the BH-FDR guarantee was for\n * the *first* look, not the 47th. Without time-uniform inference,\n * launch-decision teams either (a) don't peek, which forfeits the cost\n * advantage of stop-when-decisive, or (b) peek and pretend they didn't,\n * which forfeits scientific validity.\n *\n * This module ships **e-value-based confidence sequences** for paired\n * bounded outcomes. The methodology is the predictable plug-in betting\n * martingale of Waudby-Smith & Ramdas (2024) — provably valid at *any*\n * stopping time. Concretely:\n *\n *   For paired deltas D_1, D_2, … ∈ [-c, c] with the null H_0: E[D] ≤ 0,\n *   a betting fraction λ_i is chosen using only D_{1..i-1} (predictable\n *   plug-in), and the running e-value is\n *\n *     E_t = ∏_{i=1}^{t} (1 + λ_i · D_i)\n *\n *   E_t is a non-negative martingale under H_0 with E[E_t] ≤ 1, so by\n *   Ville's inequality, P(∃ t : E_t ≥ 1/α) ≤ α — we can reject the null\n *   at any time without inflating the type-I error.\n *\n * Combined with `runEvalCampaign`, every consumer running rolling\n * campaigns gains the ability to ship the moment evidence is decisive,\n * stop-early on dead-on-arrival variants, and accumulate evidence across\n * partial runs without spending the FDR budget. No new sweep is wasted.\n *\n * References:\n *   - Howard, S. R., Ramdas, A., McAuliffe, J., Sekhon, J. (2021).\n *     Time-uniform, nonparametric, nonasymptotic confidence sequences.\n *     Annals of Statistics, 49(2), 1055–1080.\n *   - Waudby-Smith, I., Ramdas, A. (2024). Estimating means of bounded\n *     random variables by betting. JRSS B, 86(1), 1–27.\n */\n\nexport type SequentialDecision = 'promote_now' | 'continue' | 'reject_now' | 'equivalent'\n\nexport interface PairedEvalueOptions {\n  /**\n   * Bound on |delta|. Default 1 (matching most score scales). Must satisfy\n   * c > 0; deltas outside [-c, c] are clipped with a warning attached to\n   * the return value.\n   */\n  bound?: number\n  /** Target Type-I error. Default 0.05. */\n  alpha?: number\n  /**\n   * Region of Practical Equivalence on the *mean* paired delta. When\n   * supplied, the verdict can return `'equivalent'` once the running\n   * confidence sequence on the mean is fully contained in [low, high].\n   */\n  rope?: { low: number; high: number }\n  /** Initial bet shrinkage (0 < scale ≤ 1). Default 0.5 — empirically robust. */\n  initialBetShrinkage?: number\n}\n\nexport interface PairedEvalueStep {\n  /** 1-indexed observation count. */\n  t: number\n  delta: number\n  /** Running e-value E_t = ∏ (1 + λ_i · D_i). */\n  evalue: number\n  /** Time-uniform p-value at stopping time t. */\n  pValue: number\n  /** Lower bound of the empirical Bernstein confidence sequence at level 1-α. */\n  csLow: number\n  csHigh: number\n  /** Verdict at this stopping time. */\n  decision: SequentialDecision\n}\n\nexport interface PairedEvalueSequence {\n  steps: PairedEvalueStep[]\n  /** The decision at the final step. */\n  finalDecision: SequentialDecision\n  /** Index (1-based) at which a non-`continue` decision first fired, or null. */\n  decisionFiredAt: number | null\n  /** True if any deltas were clipped to [-bound, bound]. */\n  clipped: boolean\n}\n\n/**\n * Run the paired e-value sequence over an in-order delta stream.\n *\n * Use for *streaming* / interim analyses: pass the deltas you have so\n * far, get the verdict at every prefix length. The decision is\n * monotone-stable in the sense that once `'reject_now'` or `'promote_now'`\n * fires, the verdict at later steps remains decisive (the e-value is a\n * non-negative martingale; once it crosses the threshold, it's crossed).\n */\nexport function pairedEvalueSequence(\n  deltas: number[],\n  opts: PairedEvalueOptions = {},\n): PairedEvalueSequence {\n  const c = opts.bound ?? 1\n  const alpha = opts.alpha ?? 0.05\n  const initialShrink = opts.initialBetShrinkage ?? 0.5\n  const rope = opts.rope ?? null\n  if (c <= 0) throw new Error('pairedEvalueSequence: bound must be > 0')\n  if (alpha <= 0 || alpha >= 1) throw new Error('pairedEvalueSequence: alpha must be in (0,1)')\n  if (rope && !(Number.isFinite(rope.low) && Number.isFinite(rope.high) && rope.low <= rope.high)) {\n    throw new Error('pairedEvalueSequence: rope must satisfy low ≤ high')\n  }\n\n  const steps: PairedEvalueStep[] = []\n  let clipped = false\n  let evalue = 1\n  let decisionFiredAt: number | null = null\n\n  // Running statistics (using only D_{1..i-1} for the bet → predictable plug-in).\n  let sum = 0\n  let sumSq = 0\n  let count = 0\n\n  for (let i = 0; i < deltas.length; i++) {\n    let d = deltas[i]!\n    if (d < -c || d > c) {\n      d = Math.max(-c, Math.min(c, d))\n      clipped = true\n    }\n\n    // Predictable plug-in bet (positive λ tests for E[D] > 0; we run a two-sided\n    // test by tracking the symmetric e-value via |bet|).\n    // λ_i ∝ mean / (variance + bound^2). Shrink early to avoid overbetting.\n    const muHat = count === 0 ? 0 : sum / count\n    const varHat = count === 0 ? c * c : Math.max(1e-12, sumSq / count - muHat * muHat)\n    const t = i + 1\n    const shrink = initialShrink * Math.min(1, count / 32) // anneal toward 1\n    let lambda = (muHat / (varHat + c * c)) * shrink\n    // Clip to ensure 1 + λ·D > 0 for all |D| ≤ c (so the e-value stays non-negative).\n    const lambdaMax = 0.99 / c\n    if (lambda > lambdaMax) lambda = lambdaMax\n    if (lambda < -lambdaMax) lambda = -lambdaMax\n\n    evalue = evalue * (1 + lambda * d)\n    if (!Number.isFinite(evalue) || evalue < 0) evalue = 0\n\n    sum += d\n    sumSq += d * d\n    count += 1\n\n    const pValue = Math.min(1, 1 / Math.max(evalue, 1e-300))\n\n    // Empirical Bernstein confidence sequence on the mean. Howard et al.\n    // (2021), Theorem 4.4 with σ̂² the running sample variance and a\n    // calibration constant tuned for two-sided coverage at level 1 - α.\n    const cs = empiricalBernsteinCs(sum, sumSq, count, c, alpha)\n\n    let decision: SequentialDecision = 'continue'\n    if (rope && cs.low >= rope.low && cs.high <= rope.high) decision = 'equivalent'\n    else if (evalue >= 2 / alpha && muHat > 0) decision = 'promote_now'\n    else if (evalue >= 2 / alpha && muHat < 0) decision = 'reject_now'\n    else if (rope && cs.high < rope.low) decision = 'reject_now'\n\n    if (decision !== 'continue' && decisionFiredAt === null) decisionFiredAt = t\n\n    steps.push({ t, delta: d, evalue, pValue, csLow: cs.low, csHigh: cs.high, decision })\n  }\n\n  const finalDecision = steps.length === 0 ? 'continue' : steps[steps.length - 1]!.decision\n  return { steps, finalDecision, decisionFiredAt, clipped }\n}\n\nexport interface InterimReleaseConfidenceInput {\n  /**\n   * One delta series per candidate (paired deltas vs comparator). Order\n   * within a series is the order the campaigns were run.\n   */\n  deltaSeries: Array<{ candidateId: string; deltas: number[] }>\n  alpha?: number\n  bound?: number\n  rope?: { low: number; high: number }\n}\n\nexport interface InterimReleaseConfidence {\n  candidates: Array<{\n    candidateId: string\n    decision: SequentialDecision\n    decisionFiredAt: number | null\n    finalEvalue: number\n    finalPValue: number\n    pairs: number\n    csLow: number\n    csHigh: number\n  }>\n  /**\n   * Campaign-level recommendation: pick the strongest 'promote_now', else\n   * 'continue' if any candidate is still live, else 'reject_now' if every\n   * candidate is dead, else 'equivalent'.\n   */\n  recommendation: { decision: SequentialDecision; candidateId: string | null }\n}\n\n/**\n * Run interim sequential analyses across many candidates at once,\n * preserving the time-uniform α guarantee for each candidate's series and\n * synthesising a campaign-level recommendation. Designed to be called on\n * every campaign tick — the recommendation is anytime-valid.\n */\nexport function evaluateInterimReleaseConfidence(\n  input: InterimReleaseConfidenceInput,\n): InterimReleaseConfidence {\n  const candidates = input.deltaSeries.map((s) => {\n    const seq = pairedEvalueSequence(s.deltas, {\n      alpha: input.alpha,\n      bound: input.bound,\n      rope: input.rope,\n    })\n    const last = seq.steps[seq.steps.length - 1]\n    return {\n      candidateId: s.candidateId,\n      decision: seq.finalDecision,\n      decisionFiredAt: seq.decisionFiredAt,\n      finalEvalue: last?.evalue ?? 1,\n      finalPValue: last?.pValue ?? 1,\n      pairs: seq.steps.length,\n      csLow: last?.csLow ?? Number.NEGATIVE_INFINITY,\n      csHigh: last?.csHigh ?? Number.POSITIVE_INFINITY,\n    }\n  })\n\n  const promote = candidates.find((c) => c.decision === 'promote_now')\n  if (promote) return { candidates, recommendation: { decision: 'promote_now', candidateId: promote.candidateId } }\n  const live = candidates.find((c) => c.decision === 'continue')\n  if (live) return { candidates, recommendation: { decision: 'continue', candidateId: null } }\n  const equiv = candidates.find((c) => c.decision === 'equivalent')\n  if (equiv) return { candidates, recommendation: { decision: 'equivalent', candidateId: equiv.candidateId } }\n  return { candidates, recommendation: { decision: 'reject_now', candidateId: null } }\n}\n\n// ── Internals ────────────────────────────────────────────────────────────\n\n/**\n * Empirical Bernstein confidence sequence on the mean of bounded variables.\n * Adapted from Howard et al. (2021) §4.4. Provides a time-uniform CI on\n * the running mean; valid at every stopping time.\n */\nfunction empiricalBernsteinCs(\n  sum: number,\n  sumSq: number,\n  n: number,\n  bound: number,\n  alpha: number,\n): { low: number; high: number } {\n  if (n === 0) return { low: -bound, high: bound }\n  const mean = sum / n\n  const variance = Math.max(0, sumSq / n - mean * mean)\n  // Iterated-log calibration constant. The 1.7 exponent matches the\n  // recommended choice in Howard et al. for two-sided coverage at level\n  // 1 - α with mild log-corrections; tightening further requires a\n  // tuned mixture and is out of scope.\n  const psi = Math.log(2 / alpha) + 1.7 * Math.log(Math.log(Math.max(Math.E, n)) + 1)\n  const radius = Math.sqrt((2 * variance * psi) / n) + (3 * bound * psi) / n\n  return { low: mean - radius, high: mean + radius }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-EXGR4XEM.js

@@ -0,0 +1,283 @@
+import {
+  assertLlmRoute
+} from "./chunk-KAO3Q65R.js";
+import {
+  researchReport
+} from "./chunk-IOXMGMHQ.js";
+import {
+  RunIntegrityError,
+  assertRunCaptured
+} from "./chunk-QUKKGHTZ.js";
+import {
+  FileSystemRawProviderSink
+} from "./chunk-SQQLHODJ.js";
+import {
+  TraceEmitter
+} from "./chunk-5IIQKMD5.js";
+import {
+  canonicalize,
+  hashJson
+} from "./chunk-6M774GY6.js";
+
+// src/eval-campaign.ts
+var DEFAULT_INTEGRITY = {
+  llmSpansMin: 1,
+  requireRawCoverageOfLlmSpans: true,
+  requireOutcome: true
+};
+var DEFAULT_ROUTE = {
+  requireExplicitBaseUrl: true,
+  requireAuth: true
+};
+async function runEvalCampaign(opts) {
+  assertLlmRoute(opts.llmOpts, opts.routeRequirements ?? DEFAULT_ROUTE);
+  if (opts.variants.length === 0) {
+    throw new Error("runEvalCampaign: variants must be non-empty.");
+  }
+  if (opts.scenarios.length === 0) {
+    throw new Error("runEvalCampaign: scenarios must be non-empty.");
+  }
+  const variantIds = /* @__PURE__ */ new Set();
+  for (const v of opts.variants) {
+    if (variantIds.has(v.id)) {
+      throw new Error(`runEvalCampaign: duplicate variant id "${v.id}".`);
+    }
+    variantIds.add(v.id);
+  }
+  const scenarioIds = /* @__PURE__ */ new Set();
+  for (const s of opts.scenarios) {
+    if (scenarioIds.has(s.scenarioId)) {
+      throw new Error(`runEvalCampaign: duplicate scenarioId "${s.scenarioId}".`);
+    }
+    scenarioIds.add(s.scenarioId);
+  }
+  if (opts.report?.comparator && !variantIds.has(opts.report.comparator)) {
+    throw new Error(`runEvalCampaign: report.comparator "${opts.report.comparator}" is not a configured variantId.`);
+  }
+  if (!opts.commitSha) {
+    throw new Error("runEvalCampaign: commitSha is required (every RunRecord needs it).");
+  }
+  const seeds = opts.seeds ?? [0, 1, 2];
+  const splitTag = opts.splitTag ?? "holdout";
+  const concurrency = Math.max(1, opts.concurrency ?? 1);
+  const integrity = { ...DEFAULT_INTEGRITY, ...opts.integrity ?? {} };
+  const onIntegrityFailure = opts.onIntegrityFailure ?? "mark_failed";
+  const now = opts.now ?? (() => Date.now());
+  const baseUrl = (opts.llmOpts.baseUrl ?? "").replace(/\/+$/, "");
+  const provider = opts.llmOpts.provider ?? null;
+  const preregistrationHash = opts.preregistrationHash ?? null;
+  const rawSinkFactory = opts.rawSinkFactory ?? defaultRawSinkFactory(opts.workDir);
+  const campaignFingerprint = await hashJson(canonicalize({
+    campaignId: opts.campaignId,
+    variants: opts.variants.map((v) => v.id).sort(),
+    scenarios: opts.scenarios.map((s) => s.scenarioId).sort(),
+    seeds: [...seeds].sort((a, b) => a - b),
+    splitTag,
+    comparator: opts.report?.comparator ?? null,
+    baseUrl,
+    provider,
+    preregistrationHash
+  }));
+  const cells = [];
+  for (const variant of opts.variants) {
+    for (const scenario of opts.scenarios) {
+      for (const seed of seeds) {
+        cells.push({ variant, scenario, seed });
+      }
+    }
+  }
+  const startedAt = new Date(now()).toISOString();
+  const runs = [];
+  const integrityReports = [];
+  const failedRuns = [];
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const i = cursor++;
+      if (i >= cells.length) return;
+      const cell = cells[i];
+      try {
+        const result = await runOneCell(cell);
+        runs.push(result.record);
+        integrityReports.push(result.integrity);
+      } catch (err) {
+        if (err instanceof CellExecutionError) {
+          failedRuns.push(err.failed);
+          if (err.integrity) integrityReports.push(err.integrity);
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+  async function runOneCell(cell) {
+    const runId = (opts.runId ?? defaultRunId)({
+      campaignId: opts.campaignId,
+      runId: "",
+      // unused by default generator
+      variantId: cell.variant.id,
+      scenarioId: cell.scenario.scenarioId,
+      seed: cell.seed
+    });
+    const factoryParams = {
+      campaignId: opts.campaignId,
+      runId,
+      variantId: cell.variant.id,
+      scenarioId: cell.scenario.scenarioId,
+      seed: cell.seed
+    };
+    const store = opts.storeFactory(factoryParams);
+    const rawSink = rawSinkFactory(factoryParams);
+    const emitter = new TraceEmitter(store, {
+      runId,
+      now: opts.now,
+      onRunComplete: opts.onRunComplete
+    });
+    const llmOpts = {
+      ...opts.llmOpts,
+      rawSink,
+      traceContext: { runId }
+    };
+    const ctx = {
+      runId,
+      experimentId: opts.campaignId,
+      variant: cell.variant.payload,
+      variantId: cell.variant.id,
+      scenarioId: cell.scenario.scenarioId,
+      scenarioTags: cell.scenario.tags ?? {},
+      seed: cell.seed,
+      splitTag,
+      emitter,
+      store,
+      rawSink,
+      llmOpts
+    };
+    const wallStart = now();
+    let outcome;
+    try {
+      outcome = await opts.runner(ctx);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      try {
+        await emitter.abortRun(message);
+      } catch {
+      }
+      throw new CellExecutionError({
+        runId,
+        variantId: cell.variant.id,
+        scenarioId: cell.scenario.scenarioId,
+        seed: cell.seed,
+        reason: "runner_threw",
+        error: message
+      });
+    }
+    const wallMs = now() - wallStart;
+    const integrityReport = await assertRunCaptured(store, runId, { ...integrity, rawSink });
+    if (!integrityReport.ok) {
+      switch (onIntegrityFailure) {
+        case "throw":
+          throw new RunIntegrityError(integrityReport);
+        case "mark_failed":
+          throw new CellExecutionError(
+            {
+              runId,
+              variantId: cell.variant.id,
+              scenarioId: cell.scenario.scenarioId,
+              seed: cell.seed,
+              reason: "integrity_failed",
+              error: integrityReport.issues.map((i) => i.code).join(", ")
+            },
+            integrityReport
+          );
+        case "log":
+          break;
+      }
+    }
+    const recordOutcome = {
+      raw: outcome.raw ?? {}
+    };
+    if (splitTag === "holdout") recordOutcome.holdoutScore = outcome.score;
+    else recordOutcome.searchScore = outcome.score;
+    const record = {
+      runId,
+      experimentId: opts.campaignId,
+      candidateId: cell.variant.id,
+      seed: cell.seed,
+      model: outcome.model,
+      promptHash: outcome.promptHash,
+      configHash: outcome.configHash,
+      commitSha: opts.commitSha,
+      wallMs,
+      costUsd: outcome.costUsd,
+      tokenUsage: outcome.tokenUsage,
+      judgeMetadata: outcome.judgeMetadata,
+      outcome: recordOutcome,
+      failureMode: outcome.failureMode,
+      splitTag,
+      scenarioId: cell.scenario.scenarioId
+    };
+    return { record, integrity: integrityReport };
+  }
+  const workers = Array.from({ length: Math.min(concurrency, cells.length) }, () => worker());
+  await Promise.all(workers);
+  let report;
+  if (opts.report) {
+    const reportOpts = {
+      ...opts.report,
+      comparator: opts.report.comparator,
+      split: splitTag === "dev" ? "search" : splitTag,
+      generatedAt: new Date(now()).toISOString(),
+      preregistrationHash: preregistrationHash ?? void 0
+    };
+    report = await researchReport(runs, reportOpts);
+  }
+  const endedAt = new Date(now()).toISOString();
+  return {
+    campaignId: opts.campaignId,
+    campaignFingerprint,
+    preregistrationHash,
+    runs,
+    integrityReports,
+    failedRuns,
+    report,
+    startedAt,
+    endedAt
+  };
+}
+var CellExecutionError = class extends Error {
+  failed;
+  integrity;
+  constructor(failed, integrity) {
+    super(`cell ${failed.variantId}/${failed.scenarioId}@${failed.seed} failed: ${failed.reason}`);
+    this.failed = failed;
+    this.integrity = integrity;
+  }
+};
+function defaultRawSinkFactory(workDir) {
+  return (params) => {
+    if (!workDir) {
+      throw new Error(
+        "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."
+      );
+    }
+    return new FileSystemRawProviderSink({
+      dir: `${workDir}/raw-events/${params.runId}`
+    });
+  };
+}
+function defaultRunId(params) {
+  const base = `${params.campaignId}::${params.variantId}::${params.scenarioId}::${params.seed}`;
+  let h1 = 2166136261;
+  let h2 = 305419896;
+  for (let i = 0; i < base.length; i++) {
+    const c = base.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 16777619) >>> 0;
+    h2 = Math.imul(h2 ^ c, 2654435761) >>> 0;
+  }
+  return `run-${h1.toString(16).padStart(8, "0")}${h2.toString(16).padStart(8, "0")}`;
+}
+
+export {
+  runEvalCampaign
+};
+//# sourceMappingURL=chunk-EXGR4XEM.js.map

package/dist/chunk-EXGR4XEM.js.map

@@ -0,0 +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 * Every consumer that ran a launch-grade benchmark before 0.22 reinvented\n * the same shape: matrix runner → for each (variant, scenario, seed) →\n * start a TraceEmitter → call LLMs → end the run → maybe analyze.\n * The bug class blueprint-agent reported (raw events not captured, route\n * silently wrong, integrity not asserted, analyst never ran) lives at the\n * integration boundary — not the agent-eval API surface. The four\n * directives in `SKILL.md § Capture integrity` are mitigations.\n *\n * `EvalCampaign` is the structural fix. Consumers don't wire the integrity\n * surface anymore; the campaign owns it. Specifically, the campaign:\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 { canonicalize, hashJson } from './pre-registration'\nimport { assertLlmRoute, type LlmClientOptions, type LlmRouteRequirements } from './llm-client'\nimport { TraceEmitter } from './trace/emitter'\nimport {\n  FileSystemRawProviderSink,\n  type RawProviderSink,\n} from './trace/raw-provider-sink'\nimport {\n  RunIntegrityError,\n  assertRunCaptured,\n  type RunIntegrityExpectations,\n  type RunIntegrityReport,\n} from './trace/integrity'\nimport type { RunCompleteHook } from './trace/emitter'\nimport type { TraceStore } from './trace/store'\nimport type {\n  RunJudgeMetadata,\n  RunOutcome,\n  RunRecord,\n  RunSplitTag,\n  RunTokenUsage,\n} from './run-record'\nimport {\n  researchReport,\n  type ResearchReport,\n  type ResearchReportOptions,\n} from './summary-report'\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  /** Optional failure-taxonomy tag if the run failed. */\n  failureMode?: string\n  /** Optional judge metadata when a judge was used. */\n  judgeMetadata?: RunJudgeMetadata\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<ResearchReportOptions, 'comparator' | 'preregistrationHash' | 'generatedAt'>\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\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>(opts: EvalCampaignOptions<V>): 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(`runEvalCampaign: report.comparator \"${opts.report.comparator}\" is not a configured variantId.`)\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(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  // ── 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  let cursor = 0\n  async function worker(): Promise<void> {\n    while (true) {\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          // Surface it; don't silently mask.\n          throw err\n        }\n      }\n    }\n  }\n\n  async function runOneCell(cell: Cell): 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\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    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; give it a chance to have aborted.\n      try {\n        await emitter.abortRun(message)\n      } catch {\n        // Already aborted/ended; ignore.\n      }\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\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      failureMode: outcome.failureMode,\n      splitTag,\n      scenarioId: cell.scenario.scenarioId,\n    }\n    return { record, integrity: integrityReport }\n  }\n\n  const workers = Array.from({ length: Math.min(concurrency, cells.length) }, () => worker())\n  await Promise.all(workers)\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\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\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":[]}