@tangle-network/agent-eval 0.115.2 → 0.116.0

package/dist/{chunk-N6MTC3GK.js → chunk-3274WNK7.js}

@@ -2,6 +2,9 @@ import {
   runCampaign,
   summarizeBackendIntegrity
 } from "./chunk-FAOEFFRT.js";
+import {
+  validatePolicyEditCandidateRecord
+} from "./chunk-CIUOICJT.js";
 import {
   detectRewardHacking
 } from "./chunk-ARU2PZFM.js";
@@ -13,7 +16,7 @@ import {
 } from "./chunk-GGE4NNQT.js";
 import {
   callLlm
-} from "./chunk-FUCQVFMU.js";
+} from "./chunk-GY4SYVPJ.js";
 import {
   ValidationError
 } from "./chunk-ONWEPEDO.js";
@@ -922,8 +925,14 @@ function pairHoldout(candidate, baseline, scenarioIds, select) {
     if (!scores) return void 0;
     const vals = [];
     for (const s of Object.values(scores)) {
+      if (s.failed === true) {
+        throw new Error(`pairHoldout: cell '${cellId}' contains a failed judge score`);
+      }
       const v = select(s);
-      if (typeof v === "number" && Number.isFinite(v)) vals.push(v);
+      if (typeof v === "number" && !Number.isFinite(v)) {
+        throw new Error(`pairHoldout: cell '${cellId}' contains a non-finite selected score`);
+      }
+      if (typeof v === "number") vals.push(v);
     }
     if (vals.length === 0) return void 0;
     return vals.reduce((a, b) => a + b, 0) / vals.length;
@@ -942,7 +951,10 @@ function pairHoldout(candidate, baseline, scenarioIds, select) {
   for (const cellId of candCells) {
     const b = cellValue(baseline, cellId);
     const a = cellValue(candidate, cellId);
-    if (b === void 0 || a === void 0) continue;
+    if (b === void 0 && a === void 0) continue;
+    if (b === void 0 || a === void 0) {
+      throw new Error(`pairHoldout: cell '${cellId}' has a selected score on only one arm`);
+    }
     before.push(b);
     after.push(a);
     cellIds.push(cellId);
@@ -1707,6 +1719,65 @@ function parseReflectionResponse(raw, maxProposals) {
   return out;
 }
 
+// src/campaign/surface-identity.ts
+import { createHash } from "crypto";
+var GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+var SHA256 = /^sha256:[a-f0-9]{64}$/;
+function assertCodeSurfaceIdentity(surface) {
+  if (!surface || typeof surface !== "object") {
+    throw new TypeError("CodeSurface must be an object");
+  }
+  const candidate = surface;
+  if (candidate.kind !== "code") throw new TypeError('CodeSurface.kind must be "code"');
+  if (typeof candidate.worktreeRef !== "string" || candidate.worktreeRef.trim().length === 0) {
+    throw new TypeError("CodeSurface.worktreeRef must be a non-empty locator");
+  }
+  if (typeof candidate.baseRef !== "string" || candidate.baseRef.trim().length === 0) {
+    throw new TypeError("CodeSurface.baseRef must be a non-empty ref label");
+  }
+  for (const [field, value] of [
+    ["baseCommit", candidate.baseCommit],
+    ["baseTree", candidate.baseTree],
+    ["candidateCommit", candidate.candidateCommit],
+    ["candidateTree", candidate.candidateTree]
+  ]) {
+    if (typeof value !== "string" || !GIT_OBJECT_ID.test(value)) {
+      throw new TypeError(`CodeSurface.${field} must be a full Git object id`);
+    }
+  }
+  const patch = candidate.patch;
+  if (!patch || typeof patch !== "object" || patch.format !== "git-diff-binary") {
+    throw new TypeError('CodeSurface.patch.format must be "git-diff-binary"');
+  }
+  if (typeof patch.sha256 !== "string" || !SHA256.test(patch.sha256)) {
+    throw new TypeError("CodeSurface.patch.sha256 must be a sha256 digest");
+  }
+  if (!Number.isSafeInteger(patch.byteLength) || patch.byteLength < 0) {
+    throw new TypeError("CodeSurface.patch.byteLength must be a non-negative safe integer");
+  }
+}
+function codeSurfaceIdentityMaterial(surface) {
+  assertCodeSurfaceIdentity(surface);
+  return JSON.stringify({
+    schema: "tangle.code-surface.v1",
+    baseCommit: surface.baseCommit,
+    baseTree: surface.baseTree,
+    candidateTree: surface.candidateTree,
+    patch: {
+      format: surface.patch.format,
+      sha256: surface.patch.sha256,
+      byteLength: surface.patch.byteLength
+    }
+  });
+}
+function surfaceContentHash(surface) {
+  const material = typeof surface === "string" ? surface : codeSurfaceIdentityMaterial(surface);
+  return `sha256:${createHash("sha256").update(material).digest("hex")}`;
+}
+function surfaceHash(surface) {
+  return surfaceContentHash(surface).slice("sha256:".length, "sha256:".length + 16);
+}
+
 // src/campaign/proposers/gepa.ts
 var REFLECTION_SYSTEM = 'You are an expert prompt engineer performing GEPA-style reflective mutation. You are given a prompt surface, its top trials (preserve what works) and its bottom trials (the evidence to fix). For each proposal, reason in this order before writing the payload: (1) LOCALIZE \u2014 point to the exact span of the current surface responsible for a bottom-trial failure; (2) DIAGNOSE the root cause (a missing rule, an ambiguous instruction, an over-broad directive), not just the symptom; (3) propose the MINIMAL, GENERALIZABLE edit that fixes the whole failure class \u2014 state it as a rule the agent should follow, never a patch memorized to the shown trials (that is overfitting and will not transfer to the held-out set); (4) PRESERVE every instruction the top trials depend on \u2014 do not delete or weaken working guidance. Put this localize\u2192diagnose\u2192fix reasoning in each proposal\'s `rationale`. Output ONLY a JSON object of shape {"proposals":[{"label":string,"rationale":string,"payload":string}]} where each `payload` is the FULL improved surface text. No prose outside the JSON.';
 var COMBINE_SYSTEM = 'You are an expert prompt engineer performing a GEPA "combine complementary lessons" merge. You are given several non-dominated versions of one surface; each is uniquely best on different scenarios. Produce ONE new version that keeps what makes each version strong on its winning scenarios and resolves conflicts in favor of the more general rule. Output ONLY a JSON object of shape {"proposals":[{"label":string,"rationale":string,"payload":string}]} with exactly one proposal whose `payload` is the FULL merged surface text. No prose outside the JSON.';
@@ -1854,10 +1925,11 @@ function validatePreservedSections(candidate, required) {
 }
 function buildEvidence(ctx, evidenceK, baseTarget) {
   const last = ctx.history.at(-1);
-  if (!last || last.candidates.length === 0) {
-    return { top: [], bottom: [], target: baseTarget };
-  }
-  const best = [...last.candidates].sort((a, b) => b.composite - a.composite)[0];
+  const currentSurfaceHash = surfaceHash(ctx.currentSurface);
+  const measuredCurrentSurface = ctx.history.flatMap((record) => record.candidates).reverse().find(
+    (candidate) => candidate.surfaceHash === currentSurfaceHash && candidate.eligibleForPromotion !== false
+  );
+  const best = ctx.incumbentOutcome ?? measuredCurrentSurface ?? (last ? [...last.candidates].filter((candidate) => candidate.eligibleForPromotion !== false).sort((a, b) => b.composite - a.composite)[0] : void 0);
   if (!best) return { top: [], bottom: [], target: baseTarget };
   const byScore = [...best.scenarios].sort((a, b) => b.composite - a.composite);
   const toTrace = (s) => ({
@@ -1878,7 +1950,7 @@ function buildEvidence(ctx, evidenceK, baseTarget) {
 function campaignMeanComposite(campaign) {
   const composites = [];
   for (const cell of campaign.cells) {
-    const cellComposites = Object.values(cell.judgeScores).map((s) => s.composite);
+    const cellComposites = Object.values(cell.judgeScores).filter((score) => score.failed !== true && Number.isFinite(score.composite)).map((score) => score.composite);
     if (cellComposites.length > 0) {
       composites.push(cellComposites.reduce((a, b) => a + b, 0) / cellComposites.length);
     }
@@ -1891,7 +1963,9 @@ function campaignBreakdown(campaign) {
   const byScenario = /* @__PURE__ */ new Map();
   const notesByScenario = /* @__PURE__ */ new Map();
   for (const cell of campaign.cells) {
-    const judgeScores = Object.values(cell.judgeScores);
+    const judgeScores = Object.values(cell.judgeScores).filter(
+      (score) => score.failed !== true && Number.isFinite(score.composite)
+    );
     if (judgeScores.length === 0) continue;
     const cellComposite = judgeScores.reduce((a, s) => a + s.composite, 0) / judgeScores.length;
     const arr = byScenario.get(cell.scenarioId) ?? [];
@@ -1906,6 +1980,7 @@ function campaignBreakdown(campaign) {
     }
     for (const score of judgeScores) {
       for (const [key, value] of Object.entries(score.dimensions)) {
+        if (!Number.isFinite(value)) continue;
         dimSums[key] = (dimSums[key] ?? 0) + value;
         dimCounts[key] = (dimCounts[key] ?? 0) + 1;
       }
@@ -1928,84 +2003,120 @@ function campaignBreakdown(campaign) {
   return { dimensions, scenarios };
 }
 
-// src/campaign/surface-identity.ts
-import { createHash } from "crypto";
-var GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
-var SHA256 = /^sha256:[a-f0-9]{64}$/;
-function assertCodeSurfaceIdentity(surface) {
-  if (!surface || typeof surface !== "object") {
-    throw new TypeError("CodeSurface must be an object");
-  }
-  const candidate = surface;
-  if (candidate.kind !== "code") throw new TypeError('CodeSurface.kind must be "code"');
-  if (typeof candidate.worktreeRef !== "string" || candidate.worktreeRef.trim().length === 0) {
-    throw new TypeError("CodeSurface.worktreeRef must be a non-empty locator");
-  }
-  if (typeof candidate.baseRef !== "string" || candidate.baseRef.trim().length === 0) {
-    throw new TypeError("CodeSurface.baseRef must be a non-empty ref label");
-  }
-  for (const [field, value] of [
-    ["baseCommit", candidate.baseCommit],
-    ["baseTree", candidate.baseTree],
-    ["candidateCommit", candidate.candidateCommit],
-    ["candidateTree", candidate.candidateTree]
-  ]) {
-    if (typeof value !== "string" || !GIT_OBJECT_ID.test(value)) {
-      throw new TypeError(`CodeSurface.${field} must be a full Git object id`);
+// src/campaign/coverage.ts
+function campaignCoverage(cells, scenarios, reps, requireJudgeScore) {
+  const expectedCellIds = designedCellIds(scenarios, reps);
+  const cellsById = /* @__PURE__ */ new Map();
+  for (const cell of cells) {
+    const matches = cellsById.get(cell.cellId) ?? [];
+    matches.push(cell);
+    cellsById.set(cell.cellId, matches);
+  }
+  const scorableCellIds = [];
+  const unscorableCells = [];
+  for (const cellId of expectedCellIds) {
+    const matches = cellsById.get(cellId) ?? [];
+    if (matches.length === 0) {
+      unscorableCells.push({ cellId, reason: "missing campaign cell" });
+      continue;
+    }
+    if (matches.length > 1) {
+      unscorableCells.push({ cellId, reason: `duplicate campaign cell (${matches.length})` });
+      continue;
+    }
+    const cell = matches[0];
+    const scoreEntries = Object.entries(cell.judgeScores);
+    const successfulScores = scoreEntries.map(([, score]) => score).filter((score) => score.failed !== true && Number.isFinite(score.composite));
+    const nonFiniteScores = scoreEntries.filter(
+      ([, score]) => score.failed !== true && (!Number.isFinite(score.composite) || Object.values(score.dimensions).some((value) => !Number.isFinite(value)))
+    );
+    const reasons = [];
+    if (cell.error) reasons.push(cell.error);
+    if (cell.artifact === null || cell.artifact === void 0) reasons.push("missing artifact");
+    if (!cell.error && requireJudgeScore && successfulScores.length === 0) {
+      reasons.push("no successful finite judge score");
+    }
+    if (scoreEntries.some(([, score]) => score.failed === true)) {
+      reasons.push("judge score marked failed");
+    }
+    if (nonFiniteScores.length > 0) {
+      reasons.push(
+        `non-finite judge score: ${nonFiniteScores.map(([name]) => name).sort().join(", ")}`
+      );
+    }
+    if (reasons.length > 0) {
+      unscorableCells.push({ cellId, reason: reasons.join("; ") });
+    } else {
+      scorableCellIds.push(cellId);
     }
   }
-  const patch = candidate.patch;
-  if (!patch || typeof patch !== "object" || patch.format !== "git-diff-binary") {
-    throw new TypeError('CodeSurface.patch.format must be "git-diff-binary"');
-  }
-  if (typeof patch.sha256 !== "string" || !SHA256.test(patch.sha256)) {
-    throw new TypeError("CodeSurface.patch.sha256 must be a sha256 digest");
-  }
-  if (!Number.isSafeInteger(patch.byteLength) || patch.byteLength < 0) {
-    throw new TypeError("CodeSurface.patch.byteLength must be a non-negative safe integer");
-  }
-}
-function codeSurfaceIdentityMaterial(surface) {
-  assertCodeSurfaceIdentity(surface);
-  return JSON.stringify({
-    schema: "tangle.code-surface.v1",
-    baseCommit: surface.baseCommit,
-    baseTree: surface.baseTree,
-    candidateTree: surface.candidateTree,
-    patch: {
-      format: surface.patch.format,
-      sha256: surface.patch.sha256,
-      byteLength: surface.patch.byteLength
+  const expected = new Set(expectedCellIds);
+  for (const cell of cells) {
+    if (!expected.has(cell.cellId)) {
+      unscorableCells.push({ cellId: cell.cellId, reason: "unexpected campaign cell" });
     }
-  });
+  }
+  return {
+    complete: unscorableCells.length === 0 && scorableCellIds.length === expectedCellIds.length,
+    expectedCellIds,
+    scorableCellIds,
+    unscorableCells
+  };
 }
-function surfaceContentHash(surface) {
-  const material = typeof surface === "string" ? surface : codeSurfaceIdentityMaterial(surface);
-  return `sha256:${createHash("sha256").update(material).digest("hex")}`;
+function formatCoverageFailures(coverage) {
+  const shown = coverage.unscorableCells.slice(0, 3).map((cell) => `${cell.cellId}: ${cell.reason}`).join("; ");
+  const remainder = coverage.unscorableCells.length - Math.min(3, coverage.unscorableCells.length);
+  return remainder > 0 ? `${shown}; +${remainder} more` : shown || "unknown coverage failure";
 }
-function surfaceHash(surface) {
-  return surfaceContentHash(surface).slice("sha256:".length, "sha256:".length + 16);
+function designedCellIds(scenarios, reps) {
+  const ids = [];
+  for (const scenario of scenarios) {
+    for (let rep = 0; rep < reps; rep++) ids.push(`${scenario.id}:${rep}`);
+  }
+  return ids;
 }
 
 // src/campaign/presets/run-optimization.ts
 async function runOptimization(opts) {
   const { proposer } = opts;
-  const promoteTopK = opts.promoteTopK ?? 2;
   if (typeof opts.runDir !== "string" || opts.runDir.trim().length === 0) {
     throw new Error("runOptimization: runDir is required and must be a non-empty string");
   }
+  if (opts.promoteTopK !== void 0 && opts.promoteTopK !== 1) {
+    throw new Error(
+      "runOptimization: promoteTopK must be 1 because the loop has one global incumbent"
+    );
+  }
   const baselineCampaign = await runCampaign({
     ...opts,
     dispatch: (scenario, ctx) => opts.dispatchWithSurface(opts.baselineSurface, scenario, ctx),
     runDir: `${opts.runDir}/baseline`
   });
+  const requireJudgeScore = (opts.judges?.length ?? 0) > 0;
+  const baselineCoverage = campaignCoverage(
+    baselineCampaign.cells,
+    opts.scenarios,
+    opts.reps ?? 1,
+    requireJudgeScore
+  );
+  if (!baselineCoverage.complete) {
+    throw new Error(
+      `runOptimization: baseline is incomplete (${baselineCoverage.scorableCellIds.length}/${baselineCoverage.expectedCellIds.length} designed cells scorable) \u2014 ${formatCoverageFailures(baselineCoverage)}. Refusing to optimize against an incomplete incumbent.`
+    );
+  }
   const generations = [];
   const history = [];
   let currentFindings = opts.findings ?? [];
-  let currentSurfaces = [opts.baselineSurface];
   let winnerSurface = opts.baselineSurface;
   let winnerSurfaceHash = surfaceHash(opts.baselineSurface);
   let winnerComposite = campaignMeanComposite(baselineCampaign);
+  const baselineOutcome = toScoredSurfaceOutcome(
+    winnerSurfaceHash,
+    baselineCampaign,
+    baselineCoverage,
+    -1
+  );
+  let winnerOutcome = baselineOutcome;
   let winnerLabel;
   let winnerRationale;
   const scored = [
@@ -2025,13 +2136,20 @@ async function runOptimization(opts) {
   for (let gen = 0; gen < opts.maxGenerations; gen++) {
     if (proposer.decide?.({ history }).stop) break;
     const paretoParents = computeParetoFrontier(scored);
+    const parentSurfaceHash = winnerSurfaceHash;
+    const parentComposite = winnerComposite;
     const proposed = await proposer.propose({
-      currentSurface: currentSurfaces[0] ?? opts.baselineSurface,
+      // The mutation anchor is always the best complete surface seen across the
+      // whole run. Exploratory losers remain in history/Pareto evidence, but a
+      // later generation never compounds a candidate already known to regress.
+      currentSurface: winnerSurface,
       history,
       findings: currentFindings,
       populationSize: opts.populationSize,
       generation: gen,
       signal: new AbortController().signal,
+      baselineOutcome,
+      incumbentOutcome: winnerOutcome,
       report: opts.report,
       dataset: opts.labeledStore && opts.labeledStore !== "off" ? opts.labeledStore : void 0,
       maxImprovementShots: opts.maxImprovementShots,
@@ -2042,7 +2160,7 @@ async function runOptimization(opts) {
     );
     const surfaceResults = [];
     for (let i = 0; i < candidates.length; i++) {
-      const { surface, label, rationale } = candidates[i];
+      const { surface, label, rationale, candidateRecord } = candidates[i];
       const hash = surfaceHash(surface);
       const campaign = await runCampaign({
         ...opts,
@@ -2050,21 +2168,43 @@ async function runOptimization(opts) {
         runDir: `${opts.runDir}/gen-${gen}/candidate-${i}`
       });
       const composite = campaignMeanComposite(campaign);
-      surfaceResults.push({ surfaceHash: hash, surface, label, rationale, campaign, composite });
-      scored.push(
-        toParetoParent(surface, hash, campaign, gen, label || void 0, rationale || void 0)
+      const coverage = campaignCoverage(
+        campaign.cells,
+        opts.scenarios,
+        opts.reps ?? 1,
+        requireJudgeScore
       );
+      surfaceResults.push({
+        surfaceHash: hash,
+        surface,
+        label,
+        rationale,
+        ...candidateRecord ? { candidateRecord } : {},
+        campaign,
+        composite,
+        coverage
+      });
+      if (coverage.complete) {
+        scored.push(
+          toParetoParent(surface, hash, campaign, gen, label || void 0, rationale || void 0)
+        );
+      }
     }
-    surfaceResults.sort((a, b) => b.composite - a.composite);
-    const promoted = surfaceResults.slice(0, promoteTopK);
-    currentSurfaces = promoted.map((p) => p.surface);
-    const top = surfaceResults[0];
-    if (top && top.composite > winnerComposite) {
-      winnerSurface = top.surface;
-      winnerSurfaceHash = top.surfaceHash;
-      winnerComposite = top.composite;
-      winnerLabel = top.label || void 0;
-      winnerRationale = top.rationale || void 0;
+    surfaceResults.sort((a, b) => {
+      if (a.coverage.complete !== b.coverage.complete) return a.coverage.complete ? -1 : 1;
+      return b.composite - a.composite;
+    });
+    const eligibleResults = surfaceResults.filter((result) => result.coverage.complete);
+    const top = eligibleResults[0];
+    const promoted = top && top.composite > winnerComposite ? [top] : [];
+    if (promoted[0]) {
+      const top2 = promoted[0];
+      winnerSurface = top2.surface;
+      winnerSurfaceHash = top2.surfaceHash;
+      winnerComposite = top2.composite;
+      winnerOutcome = toScoredSurfaceOutcome(top2.surfaceHash, top2.campaign, top2.coverage, gen);
+      winnerLabel = top2.label || void 0;
+      winnerRationale = top2.rationale || void 0;
     }
     const record = {
       generationIndex: gen,
@@ -2074,11 +2214,21 @@ async function runOptimization(opts) {
           surfaceHash: s.surfaceHash,
           composite: s.composite,
           ci95: [s.composite, s.composite],
+          parentSurfaceHash,
+          parentComposite,
+          ...s.coverage.complete ? { observedDeltaFromParent: s.composite - parentComposite } : {},
+          eligibleForPromotion: s.coverage.complete,
+          coverage: {
+            expectedCells: s.coverage.expectedCellIds.length,
+            scorableCells: s.coverage.scorableCellIds.length,
+            unscorableCells: s.coverage.unscorableCells
+          },
           dimensions: breakdown.dimensions,
           scenarios: breakdown.scenarios
         };
         if (s.label) candidate.label = s.label;
         if (s.rationale) candidate.rationale = s.rationale;
+        if (s.candidateRecord) candidate.candidateRecord = s.candidateRecord;
         return candidate;
       }),
       promoted: promoted.map((p) => p.surfaceHash)
@@ -2156,6 +2306,21 @@ function computeParetoFrontier(scored) {
   }));
   return paretoFrontier(scored, objectives).frontier;
 }
+function toScoredSurfaceOutcome(surfaceHash2, campaign, coverage, generation) {
+  const breakdown = campaignBreakdown(campaign);
+  return {
+    split: "search",
+    generation,
+    surfaceHash: surfaceHash2,
+    composite: campaignMeanComposite(campaign),
+    dimensions: breakdown.dimensions,
+    scenarios: breakdown.scenarios,
+    coverage: {
+      expectedCells: coverage.expectedCellIds.length,
+      scorableCells: coverage.scorableCellIds.length
+    }
+  };
+}
 
 // src/campaign/presets/run-improvement-loop.ts
 var DEFAULT_DISPATCH_TIMEOUT_MS = 6e5;
@@ -2200,15 +2365,23 @@ async function runImprovementLoop(opts) {
     dispatch: (scenario, ctx) => opts.dispatchWithSurface(optimization.winnerSurface, scenario, ctx),
     runDir: `${opts.runDir}/holdout-winner`
   });
-  const scorable = (r) => r.cells.filter((c) => !c.error && c.artifact != null);
-  const baseScorable = scorable(baselineOnHoldout);
-  const winnerScorable = scorable(winnerOnHoldout);
-  if (baseScorable.length === 0 || winnerScorable.length === 0) {
-    const firstErr = (r) => r.cells.find((c) => c.error)?.error ?? "unknown";
-    throw new Error(
-      `runImprovementLoop: holdout produced no scorable cells (baseline ${baseScorable.length}/${baselineOnHoldout.cells.length}, winner ${winnerScorable.length}/${winnerOnHoldout.cells.length}) \u2014 every holdout dispatch or judge failed. Refusing to emit a gate decision over an empty holdout. First baseline error: "${firstErr(baselineOnHoldout)}"; first winner error: "${firstErr(winnerOnHoldout)}".`
+  const requireJudgeScore = (opts.judges?.length ?? 0) > 0;
+  const reps = opts.reps ?? 1;
+  const assertCompleteHoldout = (arm, campaign) => {
+    const coverage = campaignCoverage(
+      campaign.cells,
+      opts.holdoutScenarios,
+      reps,
+      requireJudgeScore
     );
-  }
+    if (!coverage.complete) {
+      throw new Error(
+        `runImprovementLoop: ${arm} holdout is incomplete (${coverage.scorableCellIds.length}/${coverage.expectedCellIds.length} designed cells scorable) \u2014 ${formatCoverageFailures(coverage)}. Refusing to compare unequal holdout results.`
+      );
+    }
+  };
+  assertCompleteHoldout("baseline", baselineOnHoldout);
+  assertCompleteHoldout("winner", winnerOnHoldout);
   const candidateArtifacts = /* @__PURE__ */ new Map();
   const baselineArtifacts = /* @__PURE__ */ new Map();
   const judgeScores = /* @__PURE__ */ new Map();
@@ -2232,6 +2405,7 @@ async function runImprovementLoop(opts) {
       dispatch: (scenario, ctx) => opts.dispatchWithSurface(neutralizedSurface, scenario, ctx),
       runDir: `${opts.runDir}/holdout-neutralized`
     });
+    assertCompleteHoldout("neutralized", neutralizedOnHoldout);
     neutralizedArtifacts = /* @__PURE__ */ new Map();
     neutralizedJudgeScores = /* @__PURE__ */ new Map();
     for (const cell of neutralizedOnHoldout.cells) {
@@ -2335,28 +2509,103 @@ function meanHoldoutComposite(campaign) {
 function buildLoopProvenanceRecord(args) {
   const integrity = summarizeBackendIntegrity(args.workerRecords);
   const models = [...new Set(args.workerRecords.map((r) => r.model))].sort();
+  if (!Number.isFinite(args.baselineSearchComposite)) {
+    throw new Error("buildLoopProvenanceRecord: baselineSearchComposite must be finite");
+  }
   const candidates = [];
+  let incumbentSurfaceHash = surfaceHash(args.baselineSurface);
+  let incumbentComposite = args.baselineSearchComposite;
+  let previousGeneration = -1;
   for (const gen of args.generations) {
+    if (!Number.isSafeInteger(gen.generationIndex) || gen.generationIndex <= previousGeneration) {
+      throw new Error(
+        "buildLoopProvenanceRecord: generation indices must be strictly increasing integers"
+      );
+    }
+    previousGeneration = gen.generationIndex;
+    if (new Set(gen.promoted).size !== gen.promoted.length || gen.promoted.length > 1) {
+      throw new Error(
+        "buildLoopProvenanceRecord: each generation may promote at most one candidate"
+      );
+    }
     const promotedSet = new Set(gen.promoted);
     const surfaceByHash = new Map(gen.surfaces.map((s) => [s.surfaceHash, s.surface]));
+    const candidateByHash = new Map(
+      gen.candidates.map((candidate) => [candidate.surfaceHash, candidate])
+    );
+    if (candidateByHash.size !== gen.candidates.length) {
+      throw new Error("buildLoopProvenanceRecord: duplicate candidate surface hash");
+    }
+    if (surfaceByHash.size !== gen.surfaces.length) {
+      throw new Error("buildLoopProvenanceRecord: duplicate candidate surface entry");
+    }
+    if (surfaceByHash.size !== candidateByHash.size) {
+      throw new Error(
+        "buildLoopProvenanceRecord: every measured candidate requires exactly one surface"
+      );
+    }
+    for (const promotedHash2 of promotedSet) {
+      if (!candidateByHash.has(promotedHash2)) {
+        throw new Error("buildLoopProvenanceRecord: promoted hash has no measured candidate");
+      }
+    }
     for (const c of gen.candidates) {
+      validateCandidateMeasurement(
+        c,
+        incumbentSurfaceHash,
+        incumbentComposite,
+        promotedSet.has(c.surfaceHash)
+      );
       const surface = surfaceByHash.get(c.surfaceHash);
+      if (surface === void 0) {
+        throw new Error("buildLoopProvenanceRecord: measured candidate is missing its surface");
+      }
+      if (surfaceHash(surface) !== c.surfaceHash) {
+        throw new Error(
+          "buildLoopProvenanceRecord: candidate surface hash does not match its surface bytes"
+        );
+      }
       const entry = {
         generation: gen.generationIndex,
         surfaceHash: c.surfaceHash,
-        contentHash: surface !== void 0 ? surfaceContentHash(surface) : `sha256:${c.surfaceHash}`,
+        contentHash: surfaceContentHash(surface),
+        parentSurfaceHash: c.parentSurfaceHash,
+        parentComposite: c.parentComposite,
+        eligibleForPromotion: c.eligibleForPromotion,
+        coverage: {
+          expectedCells: c.coverage.expectedCells,
+          scorableCells: c.coverage.scorableCells,
+          unscorableCells: c.coverage.unscorableCells.map((cell) => ({ ...cell }))
+        },
         composite: c.composite,
         promoted: promotedSet.has(c.surfaceHash)
       };
       if (c.label) entry.label = c.label;
       if (c.rationale) entry.rationale = c.rationale;
+      if (c.candidateRecord) {
+        entry.candidateRecord = validatePolicyEditCandidateRecord(c.candidateRecord);
+      }
+      if (c.observedDeltaFromParent !== void 0) {
+        entry.observedDeltaFromParent = c.observedDeltaFromParent;
+      }
       candidates.push(entry);
     }
+    const promotedHash = gen.promoted[0];
+    if (promotedHash) {
+      const promoted = candidateByHash.get(promotedHash);
+      incumbentSurfaceHash = promoted.surfaceHash;
+      incumbentComposite = promoted.composite;
+    }
+  }
+  if (surfaceHash(args.winnerSurface) !== incumbentSurfaceHash) {
+    throw new Error(
+      "buildLoopProvenanceRecord: winner surface does not match the final promoted incumbent"
+    );
   }
   const baselineHoldoutComposite = meanHoldoutComposite(args.baselineOnHoldout);
   const winnerHoldoutComposite = meanHoldoutComposite(args.winnerOnHoldout);
   const record = {
-    schema: "tangle.loop-provenance.v2",
+    schema: "tangle.loop-provenance.v3",
     runId: args.runId,
     runDir: args.runDir,
     timestamp: args.timestamp,
@@ -2364,6 +2613,7 @@ function buildLoopProvenanceRecord(args) {
     winnerContentHash: surfaceContentHash(args.winnerSurface),
     diff: args.diff,
     candidates,
+    baselineSearchComposite: args.baselineSearchComposite,
     gate: {
       decision: args.gate.decision,
       reasons: args.gate.reasons,
@@ -2391,6 +2641,77 @@ function buildLoopProvenanceRecord(args) {
   if (args.winnerRationale) record.winnerRationale = args.winnerRationale;
   return record;
 }
+function validateCandidateMeasurement(candidate, expectedParentHash, expectedParentComposite, promoted) {
+  if (!Number.isFinite(candidate.composite)) {
+    throw new Error("buildLoopProvenanceRecord: candidate composite must be finite");
+  }
+  if (!candidate.parentSurfaceHash || !/^[a-f0-9]{16}$/.test(candidate.parentSurfaceHash)) {
+    throw new Error(
+      "buildLoopProvenanceRecord: parentSurfaceHash must be 16 lowercase hex characters"
+    );
+  }
+  if (candidate.parentSurfaceHash !== expectedParentHash) {
+    throw new Error("buildLoopProvenanceRecord: candidate parent does not match the incumbent");
+  }
+  if (candidate.parentComposite === void 0 || !Number.isFinite(candidate.parentComposite) || Math.abs(candidate.parentComposite - expectedParentComposite) > 1e-12) {
+    throw new Error(
+      "buildLoopProvenanceRecord: candidate parentComposite does not match the incumbent"
+    );
+  }
+  if (candidate.eligibleForPromotion === void 0 || !candidate.coverage) {
+    throw new Error(
+      "buildLoopProvenanceRecord: candidate measurement requires eligibility and coverage"
+    );
+  }
+  if (candidate.observedDeltaFromParent !== void 0) {
+    if (!Number.isFinite(candidate.observedDeltaFromParent)) {
+      throw new Error("buildLoopProvenanceRecord: observedDeltaFromParent must be finite");
+    }
+    if (candidate.eligibleForPromotion !== true) {
+      throw new Error(
+        "buildLoopProvenanceRecord: observedDeltaFromParent requires a complete eligible candidate and parentSurfaceHash"
+      );
+    }
+  }
+  const coverage = candidate.coverage;
+  if (!Number.isSafeInteger(coverage.expectedCells) || coverage.expectedCells <= 0 || !Number.isSafeInteger(coverage.scorableCells) || coverage.scorableCells < 0 || coverage.scorableCells > coverage.expectedCells) {
+    throw new Error("buildLoopProvenanceRecord: invalid candidate coverage denominator");
+  }
+  const unscorableIds = /* @__PURE__ */ new Set();
+  for (const failure of coverage.unscorableCells) {
+    if (typeof failure.cellId !== "string" || failure.cellId.length === 0 || typeof failure.reason !== "string" || failure.reason.length === 0 || unscorableIds.has(failure.cellId)) {
+      throw new Error("buildLoopProvenanceRecord: invalid candidate coverage failures");
+    }
+    unscorableIds.add(failure.cellId);
+  }
+  if (coverage.expectedCells - coverage.scorableCells !== coverage.unscorableCells.length) {
+    throw new Error(
+      "buildLoopProvenanceRecord: candidate coverage counts do not match its failures"
+    );
+  }
+  const complete = coverage.scorableCells === coverage.expectedCells && coverage.unscorableCells.length === 0;
+  if (candidate.eligibleForPromotion !== void 0 && candidate.eligibleForPromotion !== complete) {
+    throw new Error(
+      "buildLoopProvenanceRecord: candidate eligibility contradicts its coverage receipt"
+    );
+  }
+  if (complete) {
+    if (candidate.observedDeltaFromParent === void 0) {
+      throw new Error(
+        "buildLoopProvenanceRecord: complete candidate is missing observedDeltaFromParent"
+      );
+    }
+    const recomputed = candidate.composite - candidate.parentComposite;
+    if (Math.abs(candidate.observedDeltaFromParent - recomputed) > 1e-12) {
+      throw new Error("buildLoopProvenanceRecord: observed delta does not match measured scores");
+    }
+  } else if (candidate.observedDeltaFromParent !== void 0) {
+    throw new Error("buildLoopProvenanceRecord: incomplete candidate cannot carry observed delta");
+  }
+  if (promoted && (!complete || (candidate.observedDeltaFromParent ?? 0) <= 0)) {
+    throw new Error("buildLoopProvenanceRecord: promoted candidate must improve the incumbent");
+  }
+}
 var DECISION_OK = ["ship"];
 function hashId(parts) {
   return createHash2("sha256").update(parts.join(":")).digest("hex");
@@ -2415,6 +2736,7 @@ function loopProvenanceSpans(record, opts = {}) {
       "tangle.runDir": record.runDir,
       "tangle.baselineContentHash": record.baselineContentHash,
       "tangle.winnerContentHash": record.winnerContentHash,
+      "tangle.baselineSearchComposite": record.baselineSearchComposite,
       "tangle.heldOutLift": record.heldOutLift,
       "tangle.gateDecision": record.gate.decision,
       "tangle.backendVerdict": record.backend.verdict,
@@ -2432,7 +2754,7 @@ function loopProvenanceSpans(record, opts = {}) {
   }
   for (const [generation, cands] of [...byGen.entries()].sort((a, b) => a[0] - b[0])) {
     const genSpanId = hashId(["gen", record.runId, String(generation)]).slice(0, 16);
-    const bestComposite = cands.reduce((m, c) => Math.max(m, c.composite), 0);
+    const bestComposite = Math.max(...cands.map((candidate) => candidate.composite));
     spans.push({
       traceId,
       spanId: genSpanId,
@@ -2460,9 +2782,21 @@ function loopProvenanceSpans(record, opts = {}) {
         "tangle.generation": generation,
         "tangle.surfaceHash": c.surfaceHash,
         "tangle.contentHash": c.contentHash,
+        "tangle.parentSurfaceHash": c.parentSurfaceHash,
+        "tangle.parentComposite": c.parentComposite,
         "tangle.composite": c.composite,
+        "tangle.eligibleForPromotion": c.eligibleForPromotion,
+        "tangle.expectedCells": c.coverage.expectedCells,
+        "tangle.scorableCells": c.coverage.scorableCells,
+        "tangle.unscorableCells": c.coverage.unscorableCells.length,
         "tangle.promoted": c.promoted
       };
+      if (c.observedDeltaFromParent !== void 0) {
+        attributes["tangle.observedDeltaFromParent"] = c.observedDeltaFromParent;
+      }
+      if (c.candidateRecord) {
+        attributes["tangle.policyEditId"] = c.candidateRecord.policyEdit.editId;
+      }
       if (c.label) attributes["tangle.candidateLabel"] = c.label;
       if (c.rationale) attributes["tangle.candidateRationale"] = c.rationale;
       spans.push({
@@ -2613,15 +2947,15 @@ export {
   buildReflectionPrompt,
   renderAnalystEvidence,
   parseReflectionResponse,
+  assertCodeSurfaceIdentity,
+  codeSurfaceIdentityMaterial,
+  surfaceContentHash,
+  surfaceHash,
   gepaProposer,
   extractH2Sections,
   countSentenceEdits,
   campaignMeanComposite,
   campaignBreakdown,
-  assertCodeSurfaceIdentity,
-  codeSurfaceIdentityMaterial,
-  surfaceContentHash,
-  surfaceHash,
   runOptimization,
   runImprovementLoop,
   defaultRenderDiff,
@@ -2633,4 +2967,4 @@ export {
   provenanceSpansPath,
   emitLoopProvenance
 };
-//# sourceMappingURL=chunk-N6MTC3GK.js.map
+//# sourceMappingURL=chunk-3274WNK7.js.map