@tangle-network/agent-eval 0.106.2 → 0.107.0

package/dist/campaign/index.js

@@ -7,7 +7,7 @@ import {
   paretoSignificanceGate,
   powerPreflight,
   runEval
-} from "../chunk-J22CKVXN.js";
+} from "../chunk-V75NN2ZR.js";
 import {
   HARNESS_NATIVE_MODEL,
   agentProfileHash,
@@ -17,7 +17,7 @@ import {
   harnessAxisOf,
   llmJudge,
   verifyCompletion
-} from "../chunk-2HLM4SJJ.js";
+} from "../chunk-6PF6LXRY.js";
 import {
   buildLoopProvenanceRecord,
   campaignBreakdown,
@@ -43,7 +43,7 @@ import {
   runOptimization,
   surfaceContentHash,
   surfaceHash
-} from "../chunk-3E5KUXYZ.js";
+} from "../chunk-G4DLZAV5.js";
 import {
   assertRealBackend,
   contentHash,
@@ -103,6 +103,424 @@ import {
 } from "../chunk-ONWEPEDO.js";
 import "../chunk-PZ5AY32C.js";
 
+// src/campaign/lineage.ts
+import { createHash } from "crypto";
+import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+function lineageNodeId(input) {
+  const parents = [...input.parentIds].sort().join(",");
+  const payload = `${parents}|${input.track}|${input.surface}|${input.proposer}`;
+  return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+var Lineage = class _Lineage {
+  byId = /* @__PURE__ */ new Map();
+  childIds = /* @__PURE__ */ new Map();
+  nextSeq = 0;
+  constructor(nodes) {
+    if (!nodes) return;
+    for (const node of [...nodes].sort((a, b) => a.seq - b.seq)) {
+      this.index(node);
+      this.nextSeq = Math.max(this.nextSeq, node.seq + 1);
+    }
+  }
+  /** Append a node. Derives `id` (via {@link lineageNodeId}), assigns the next
+   *  `seq`, and derives `generation` as `max(parent.generation) + 1` (root = 0)
+   *  when omitted. Throws on an unknown parent. Idempotent: re-adding an identical
+   *  node returns the existing one.
+   *
+   *  Acyclicity is guaranteed by construction, not by a runtime check: every
+   *  parent must already exist (a child can never point at a not-yet-added node),
+   *  ids are immutable content hashes (an existing node can never gain new
+   *  parents), and the store is append-only — so no back-edge can form. (Traversal
+   *  is still cycle-safe against hand-corrupted deserialized input via visited
+   *  sets in {@link ancestors}/{@link descendants}.) */
+  addNode(input) {
+    for (const parentId of input.parentIds) {
+      if (!this.byId.has(parentId)) {
+        throw new Error(`Lineage.addNode: unknown parent '${parentId}'`);
+      }
+    }
+    const id = lineageNodeId({
+      parentIds: input.parentIds,
+      track: input.track,
+      surface: input.surface,
+      proposer: input.proposer
+    });
+    const existing = this.byId.get(id);
+    if (existing) return existing;
+    const generation = input.generation ?? (input.parentIds.length === 0 ? 0 : Math.max(...input.parentIds.map((p) => this.byId.get(p).generation)) + 1);
+    const node = {
+      id,
+      parentIds: [...input.parentIds],
+      track: input.track,
+      surface: input.surface,
+      score: input.score,
+      proposer: input.proposer,
+      generation,
+      seq: this.nextSeq++,
+      ...input.vision !== void 0 ? { vision: input.vision } : {},
+      ...input.scoreVector !== void 0 ? { scoreVector: [...input.scoreVector] } : {},
+      ...input.rationale !== void 0 ? { rationale: input.rationale } : {},
+      ...input.gate !== void 0 ? { gate: input.gate } : {}
+    };
+    this.index(node);
+    return node;
+  }
+  /** Collapse 2+ parents into a single node (a merge/"collapse"). A merge is an
+   *  ordinary multi-parent node; this is a guarded convenience. */
+  merge(input) {
+    if (input.parentIds.length < 2) {
+      throw new Error(`Lineage.merge: a merge needs >= 2 parents, got ${input.parentIds.length}`);
+    }
+    return this.addNode({ ...input, proposer: input.proposer ?? "merge" });
+  }
+  get(id) {
+    return this.byId.get(id);
+  }
+  has(id) {
+    return this.byId.has(id);
+  }
+  /** All nodes, in insertion (`seq`) order. */
+  all() {
+    return [...this.byId.values()].sort(bySeq);
+  }
+  roots() {
+    return this.all().filter((n) => n.parentIds.length === 0);
+  }
+  parents(id) {
+    const node = this.byId.get(id);
+    if (!node) return [];
+    return node.parentIds.map((p) => this.byId.get(p)).filter((n) => n !== void 0).sort(bySeq);
+  }
+  children(id) {
+    return (this.childIds.get(id) ?? []).map((c) => this.byId.get(c)).sort(bySeq);
+  }
+  /** Transitive ancestors (excludes `id`). */
+  ancestors(id) {
+    const out = /* @__PURE__ */ new Set();
+    const stack = [...this.byId.get(id)?.parentIds ?? []];
+    while (stack.length > 0) {
+      const cur = stack.pop();
+      if (out.has(cur)) continue;
+      out.add(cur);
+      const node = this.byId.get(cur);
+      if (node) stack.push(...node.parentIds);
+    }
+    return out;
+  }
+  /** Transitive descendants (excludes `id`). */
+  descendants(id) {
+    const out = /* @__PURE__ */ new Set();
+    const stack = [...this.childIds.get(id) ?? []];
+    while (stack.length > 0) {
+      const cur = stack.pop();
+      if (out.has(cur)) continue;
+      out.add(cur);
+      stack.push(...this.childIds.get(cur) ?? []);
+    }
+    return out;
+  }
+  /** Nodes with no children (leaf/branch tips). */
+  tips() {
+    return this.all().filter((n) => (this.childIds.get(n.id) ?? []).length === 0);
+  }
+  /** Distinct track ids, in first-seen (`seq`) order. */
+  tracks() {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const node of this.all()) {
+      if (!seen.has(node.track)) {
+        seen.add(node.track);
+        out.push(node.track);
+      }
+    }
+    return out;
+  }
+  trackNodes(track) {
+    return this.all().filter((n) => n.track === track);
+  }
+  /** The highest-`score` tip of a track (ties broken by lowest `seq`). */
+  trackTip(track) {
+    return pickBest(this.tips().filter((n) => n.track === track));
+  }
+  /** The highest-`score` node overall (ties broken by lowest `seq`). */
+  best() {
+    return pickBest(this.all());
+  }
+  /** The Pareto-non-dominated set among TIPS. Uses `scoreVector` when every
+   *  compared tip carries one, else the scalar `score`. A dominates B iff A is
+   *  >= B on every component and > B on at least one. */
+  frontier() {
+    const tips = this.tips();
+    const useVector = tips.length > 0 && tips.every((n) => n.scoreVector !== void 0);
+    const vecOf = (n) => useVector ? n.scoreVector : [n.score];
+    return tips.filter((a) => !tips.some((b) => b.id !== a.id && dominates(vecOf(b), vecOf(a)))).sort(bySeq);
+  }
+  toGraph() {
+    const nodes = this.all();
+    const edges = [];
+    for (const node of nodes) {
+      for (const parentId of node.parentIds) {
+        edges.push({ from: parentId, to: node.id });
+      }
+    }
+    return { nodes, edges };
+  }
+  /** One JSON node per line, in `seq` order. */
+  toJSONL() {
+    return this.all().map((n) => JSON.stringify(n)).join("\n");
+  }
+  static fromJSONL(text) {
+    const nodes = text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => JSON.parse(line));
+    return new _Lineage(nodes);
+  }
+  index(node) {
+    this.byId.set(node.id, node);
+    for (const parentId of node.parentIds) {
+      const list = this.childIds.get(parentId);
+      if (list) {
+        if (!list.includes(node.id)) list.push(node.id);
+      } else {
+        this.childIds.set(parentId, [node.id]);
+      }
+    }
+  }
+};
+function bySeq(a, b) {
+  return a.seq - b.seq;
+}
+function pickBest(nodes) {
+  let best;
+  for (const node of nodes) {
+    if (!best || node.score > best.score || node.score === best.score && node.seq < best.seq) {
+      best = node;
+    }
+  }
+  return best;
+}
+function dominates(a, b) {
+  if (a.length !== b.length) return false;
+  let strictlyBetter = false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] < b[i]) return false;
+    if (a[i] > b[i]) strictlyBetter = true;
+  }
+  return strictlyBetter;
+}
+function fsLineageStore(path) {
+  const ensureDir = () => mkdir(dirname(path), { recursive: true });
+  return {
+    async load() {
+      try {
+        return Lineage.fromJSONL(await readFile(path, "utf8"));
+      } catch (err) {
+        if (err.code === "ENOENT") return new Lineage();
+        throw err;
+      }
+    },
+    async append(node) {
+      await ensureDir();
+      await appendFile(path, `${JSON.stringify(node)}
+`, "utf8");
+    },
+    async save(lineage) {
+      await ensureDir();
+      const jsonl = lineage.toJSONL();
+      await writeFile(path, jsonl.length > 0 ? `${jsonl}
+` : "", "utf8");
+    }
+  };
+}
+function memLineageStore() {
+  const nodes = [];
+  return {
+    async load() {
+      return new Lineage(nodes);
+    },
+    async append(node) {
+      nodes.push(node);
+    },
+    async save(lineage) {
+      nodes.length = 0;
+      nodes.push(...lineage.all());
+    }
+  };
+}
+function heuristicGovernor(opts = {}) {
+  const maxTracks = opts.maxTracks ?? 3;
+  const plateauSteps = opts.plateauSteps ?? 2;
+  const mergeFrontierAt = opts.mergeFrontierAt ?? 2;
+  return {
+    decide(ctx) {
+      const { lineage } = ctx;
+      if (ctx.budgetRemaining <= 0) return { op: "stop" };
+      const pruned = new Set(ctx.prunedTracks);
+      const liveTracks = lineage.tracks().filter((t) => !pruned.has(t));
+      if (liveTracks.length === 0) return { op: "stop" };
+      const frontierByTrack = /* @__PURE__ */ new Map();
+      for (const tip of lineage.frontier()) {
+        if (pruned.has(tip.track)) continue;
+        if (!frontierByTrack.has(tip.track)) frontierByTrack.set(tip.track, tip);
+      }
+      if (frontierByTrack.size >= mergeFrontierAt) {
+        const tips = [...frontierByTrack.values()].sort(bySeq);
+        const target = pickBest(tips);
+        return { op: "merge", parentIds: tips.map((t) => t.id), track: target.track };
+      }
+      for (const track of liveTracks) {
+        if (isPlateaued(lineage.trackNodes(track), plateauSteps)) {
+          if (liveTracks.length > 1 || liveTracks.length < maxTracks) {
+            return { op: "prune", track };
+          }
+        }
+      }
+      const leader = pickBest(liveTracks.map((t) => lineage.trackTip(t)).filter(Boolean));
+      if (leader && liveTracks.length < maxTracks && isPlateaued(lineage.trackNodes(leader.track), plateauSteps)) {
+        return {
+          op: "branch",
+          fromNodeId: leader.id,
+          track: `${leader.track}+${lineage.tracks().length}`,
+          proposer: "gepa"
+        };
+      }
+      if (leader) return { op: "extend", track: leader.track };
+      return { op: "stop" };
+    }
+  };
+}
+function callbackGovernor(decide) {
+  return { decide };
+}
+function isPlateaued(trackNodes, window) {
+  if (trackNodes.length <= window) return false;
+  const ordered = [...trackNodes].sort(bySeq);
+  const head = ordered.slice(0, ordered.length - window);
+  const tail = ordered.slice(ordered.length - window);
+  const bestBefore = Math.max(...head.map((n) => n.score));
+  const bestRecent = Math.max(...tail.map((n) => n.score));
+  return bestRecent <= bestBefore;
+}
+async function runLineage(opts) {
+  const store = opts.store ?? memLineageStore();
+  const lineage = await store.load();
+  const log = opts.log ?? (() => {
+  });
+  const pruned = /* @__PURE__ */ new Set();
+  const trackProposer = /* @__PURE__ */ new Map();
+  const persist = async (node) => {
+    await store.append(node);
+  };
+  for (const seed of opts.seeds) {
+    const node = lineage.addNode({
+      parentIds: [],
+      track: seed.track,
+      surface: seed.surface,
+      score: seed.score,
+      proposer: seed.proposer,
+      ...seed.vision !== void 0 ? { vision: seed.vision } : {},
+      ...seed.scoreVector !== void 0 ? { scoreVector: seed.scoreVector } : {}
+    });
+    trackProposer.set(seed.track, seed.proposer);
+    await persist(node);
+  }
+  let steps = 0;
+  while (steps < opts.budget.maxSteps) {
+    const op = await opts.governor.decide({
+      lineage,
+      step: steps,
+      budgetRemaining: opts.budget.maxSteps - steps,
+      prunedTracks: [...pruned]
+    });
+    if (op.op === "stop") {
+      log("lineage: governor stop", { steps });
+      break;
+    }
+    if (op.op === "prune") {
+      pruned.add(op.track);
+      log("lineage: prune", { track: op.track });
+      steps += 1;
+      continue;
+    }
+    if (op.op === "merge") {
+      const parents = op.parentIds.map((id) => lineage.get(id)).filter((n) => n !== void 0);
+      if (parents.length < 2) {
+        log("lineage: merge skipped (fewer than 2 known parents)", { op });
+        steps += 1;
+        continue;
+      }
+      const result2 = await opts.merge({ parents, track: op.track });
+      const node2 = lineage.merge({
+        parentIds: parents.map((p) => p.id),
+        track: op.track,
+        surface: result2.surface,
+        score: result2.score,
+        ...parents[0].vision !== void 0 ? { vision: parents[0].vision } : {},
+        ...result2.scoreVector !== void 0 ? { scoreVector: result2.scoreVector } : {},
+        ...result2.rationale !== void 0 ? { rationale: result2.rationale } : {}
+      });
+      await persist(node2);
+      steps += 1;
+      continue;
+    }
+    if (op.op === "branch") {
+      if (pruned.has(op.track)) {
+        log("lineage: branch skipped (target track pruned)", { track: op.track });
+        steps += 1;
+        continue;
+      }
+      const from = lineage.get(op.fromNodeId);
+      if (!from) {
+        log("lineage: branch skipped (unknown fromNodeId)", { op });
+        steps += 1;
+        continue;
+      }
+      trackProposer.set(op.track, op.proposer);
+      const result2 = await opts.step({ track: op.track, proposer: op.proposer, tip: from });
+      const node2 = lineage.addNode({
+        parentIds: [from.id],
+        track: op.track,
+        surface: result2.surface,
+        score: result2.score,
+        proposer: op.proposer,
+        ...op.vision !== void 0 ? { vision: op.vision } : {},
+        ...result2.scoreVector !== void 0 ? { scoreVector: result2.scoreVector } : {},
+        ...result2.rationale !== void 0 ? { rationale: result2.rationale } : {},
+        ...result2.gate !== void 0 ? { gate: result2.gate } : {}
+      });
+      await persist(node2);
+      steps += 1;
+      continue;
+    }
+    if (pruned.has(op.track)) {
+      log("lineage: extend skipped (track pruned)", { track: op.track });
+      steps += 1;
+      continue;
+    }
+    const tip = lineage.trackTip(op.track);
+    if (!tip) {
+      log("lineage: extend skipped (no tip for track)", { track: op.track });
+      steps += 1;
+      continue;
+    }
+    const proposer = trackProposer.get(op.track) ?? tip.proposer;
+    const result = await opts.step({ track: op.track, proposer, tip });
+    const node = lineage.addNode({
+      parentIds: [tip.id],
+      track: op.track,
+      surface: result.surface,
+      score: result.score,
+      proposer,
+      ...tip.vision !== void 0 ? { vision: tip.vision } : {},
+      ...result.scoreVector !== void 0 ? { scoreVector: result.scoreVector } : {},
+      ...result.rationale !== void 0 ? { rationale: result.rationale } : {},
+      ...result.gate !== void 0 ? { gate: result.gate } : {}
+    });
+    await persist(node);
+    steps += 1;
+  }
+  return { lineage, best: lineage.best(), steps };
+}
+
 // src/campaign/analyst-surface.ts
 function surfaceToText(surface) {
   if (typeof surface === "string") return surface;
@@ -166,7 +584,7 @@ function failureModeRecallJudge(opts = {}) {
 }
 
 // src/campaign/fixtures.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { isAbsolute, join, relative, resolve } from "path";
 function discoverEvalFixtures(evalsDir) {
@@ -307,7 +725,7 @@ function collectFixtureFiles(fixturePath, base = "") {
     const bytes = readFileSync(fullPath);
     files.push({
       path: relativePath,
-      sha256: createHash("sha256").update(bytes).digest("hex"),
+      sha256: createHash2("sha256").update(bytes).digest("hex"),
       bytes: bytes.byteLength
     });
   }
@@ -319,8 +737,88 @@ function assertInside(root, target, label) {
   throw new Error(`loadEvalFixture: fixture path escapes evalsDir: ${label}`);
 }
 
+// src/campaign/gates/neutralization-gate.ts
+function mean(xs) {
+  return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+function pairedLift(arm, baseline, scenarioIds) {
+  const paired = pairHoldout(arm, baseline, scenarioIds, (s) => s.composite);
+  const deltas = paired.after.map((a, i) => a - (paired.before[i] ?? 0));
+  return { lift: mean(deltas), n: deltas.length };
+}
+function neutralizationGate(options) {
+  const maxDecorativeFraction = options.maxDecorativeFraction ?? 0.5;
+  return {
+    name: "neutralizationGate",
+    async decide(ctx) {
+      if (!ctx.baselineJudgeScores) {
+        throw new Error(
+          "neutralizationGate: ctx.baselineJudgeScores is required \u2014 the placebo control measures lift OVER baseline."
+        );
+      }
+      if (!ctx.neutralizedJudgeScores) {
+        throw new Error(
+          "neutralizationGate: ctx.neutralizedJudgeScores is required. It is populated by runImprovementLoop only when a `neutralize` function is supplied \u2014 composing this gate without that wiring would pass an unproven candidate."
+        );
+      }
+      const scenarioIds = new Set(options.scenarios.map((s) => s.id));
+      const cand = pairedLift(
+        ctx.judgeScores,
+        ctx.baselineJudgeScores,
+        scenarioIds
+      );
+      const neut = pairedLift(
+        ctx.neutralizedJudgeScores,
+        ctx.baselineJudgeScores,
+        scenarioIds
+      );
+      if (cand.lift <= 0) {
+        return {
+          decision: "hold",
+          reasons: [
+            `neutralization: candidate held-out lift ${cand.lift.toFixed(3)} \u2264 0 \u2014 no positive lift to attribute to content`
+          ],
+          contributingGates: [
+            {
+              name: "neutralizationGate",
+              passed: false,
+              detail: { candidateLift: cand.lift, neutralizedLift: neut.lift, n: cand.n }
+            }
+          ],
+          delta: cand.lift
+        };
+      }
+      const decorativeFraction = neut.lift / cand.lift;
+      const passed = decorativeFraction < maxDecorativeFraction;
+      const pct = (decorativeFraction * 100).toFixed(0);
+      return {
+        decision: passed ? "ship" : "hold",
+        reasons: passed ? [
+          `neutralization: content is causal \u2014 blanked variant reproduces ${pct}% of the lift (< ${(maxDecorativeFraction * 100).toFixed(0)}%); candidate \u0394 ${cand.lift.toFixed(3)}, neutralized \u0394 ${neut.lift.toFixed(3)}`
+        ] : [
+          `neutralization: lift is DECORATIVE \u2014 blanking the content (footprint-matched) reproduces ${pct}% of the lift (\u2265 ${(maxDecorativeFraction * 100).toFixed(0)}%); candidate \u0394 ${cand.lift.toFixed(3)}, neutralized \u0394 ${neut.lift.toFixed(3)}`
+        ],
+        contributingGates: [
+          {
+            name: "neutralizationGate",
+            passed,
+            detail: {
+              candidateLift: cand.lift,
+              neutralizedLift: neut.lift,
+              decorativeFraction,
+              maxDecorativeFraction,
+              n: cand.n
+            }
+          }
+        ],
+        delta: cand.lift
+      };
+    }
+  };
+}
+
 // src/campaign/gates/sequential.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function verifyManifestSync(m) {
   if (m.algo !== void 0 && m.algo !== "sha256-content") {
     throw new Error(`sequentialPairedGate: unrecognized manifest hash algo '${m.algo}'`);
@@ -328,7 +826,7 @@ function verifyManifestSync(m) {
   const { contentHash: contentHash2, algo: _algo, ...rest } = m;
   void _algo;
   const bytes = JSON.stringify(canonicalize(rest));
-  const hash = createHash2("sha256").update(bytes, "utf8").digest("hex");
+  const hash = createHash3("sha256").update(bytes, "utf8").digest("hex");
   return hash === contentHash2;
 }
 function resolveConfig(opts) {
@@ -586,7 +1084,7 @@ function sequentialDecide(options = {}) {
 }
 
 // src/campaign/labeled-store/fs-adapter.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { join as join2 } from "path";
 var LabeledScenarioStoreError = class extends Error {
@@ -785,7 +1283,7 @@ function matchesFilter(record, args, source) {
   return true;
 }
 function sha256(input) {
-  return createHash3("sha256").update(input).digest("hex").slice(0, 16);
+  return createHash4("sha256").update(input).digest("hex").slice(0, 16);
 }
 function appendLine(path, line) {
   if (existsSync2(path)) {
@@ -796,6 +1294,12 @@ function appendLine(path, line) {
   }
 }
 
+// src/campaign/neutralize.ts
+var FILLER = "#";
+function neutralizeText(content) {
+  return content.replace(/\S/g, FILLER);
+}
+
 // src/campaign/proposers/fapo.ts
 var FAPO_LEVELS = ["prompt", "parameter", "structural"];
 var MAX_FINDING_DEPTH = 16;
@@ -1737,8 +2241,8 @@ async function compareProposerEntries(opts) {
     });
     const score = {
       name: w.name,
-      baselineComposite: mean(baselineArr),
-      winnerComposite: mean(w.arr),
+      baselineComposite: mean2(baselineArr),
+      winnerComposite: mean2(w.arr),
       lift: boot.mean,
       liftCi: { low: boot.low, high: boot.high },
       costUsd: w.costUsd,
@@ -1775,7 +2279,7 @@ async function compareProposerEntries(opts) {
   });
   return { scores, best, pairwise, holdoutScenarioIds: scenarioIds };
 }
-function mean(xs) {
+function mean2(xs) {
   return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
 }
 function slug(name) {
@@ -2013,8 +2517,177 @@ function renderScoreboardMarkdown(rows, opts = {}) {
   return out.join("\n");
 }
 
+// src/campaign/presets/run-lineage-loop.ts
+function toCandidate(p) {
+  return isProposedCandidate(p) ? { surface: p.surface, ...p.rationale ? { rationale: p.rationale } : {} } : { surface: p };
+}
+async function runLineageLoop(opts) {
+  const governor = opts.governor ?? heuristicGovernor();
+  const populationSize = opts.populationSize ?? 4;
+  if (populationSize < 1) {
+    throw new Error("runLineageLoop: populationSize must be >= 1");
+  }
+  let proposer = opts.proposer;
+  if (!proposer) {
+    if (!opts.llm || !opts.model) {
+      throw new Error(
+        "runLineageLoop: a proposer is required \u2014 either inject `proposer`, or provide `llm` + `model` for the default gepaProposer."
+      );
+    }
+    proposer = gepaProposer({
+      llm: opts.llm,
+      model: opts.model,
+      target: opts.target ?? "agent surface",
+      // GEPA combine-complementary-lessons is what the `merge` seam relies on.
+      combineParents: true
+    });
+  }
+  const scoringScenarios = opts.holdoutScenarios ?? opts.scenarios;
+  let scoreSurface = opts.scoreSurface;
+  if (!scoreSurface) {
+    const dispatchWithSurface = opts.dispatchWithSurface;
+    const runDir = opts.runDir;
+    if (!dispatchWithSurface || !runDir) {
+      throw new Error(
+        "runLineageLoop: scoring is required \u2014 either inject `scoreSurface`, or provide `dispatchWithSurface` (the agent) + `runDir` for the default runCampaign scorer."
+      );
+    }
+    if (scoringScenarios.length === 0) {
+      throw new Error(
+        "runLineageLoop: the default scorer needs at least one scenario (holdoutScenarios ?? scenarios is empty)."
+      );
+    }
+    scoreSurface = async (surface) => {
+      const campaign = await runCampaign({
+        scenarios: scoringScenarios,
+        dispatch: (scenario, ctx) => dispatchWithSurface(surface, scenario, ctx),
+        dispatchRef: `lineage-loop:${surfaceHash(surface)}`,
+        runDir: `${runDir}/score/${surfaceHash(surface)}`,
+        ...opts.judges ? { judges: opts.judges } : {},
+        ...opts.seed !== void 0 ? { seed: opts.seed } : {},
+        ...opts.reps !== void 0 ? { reps: opts.reps } : {},
+        ...opts.storage ? { storage: opts.storage } : {},
+        ...opts.tracing ? { tracing: opts.tracing } : {},
+        ...opts.expectUsage ? { expectUsage: opts.expectUsage } : {},
+        ...opts.maxConcurrency !== void 0 ? { maxConcurrency: opts.maxConcurrency } : {},
+        ...opts.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: opts.dispatchTimeoutMs } : {},
+        ...opts.now ? { now: opts.now } : {}
+      });
+      const score = campaignMeanComposite(campaign);
+      const byId = new Map(
+        campaignBreakdown(campaign).scenarios.map((s) => [s.scenarioId, s.composite])
+      );
+      const scoreVector = scoringScenarios.map((s) => byId.get(s.id) ?? 0);
+      return { score, scoreVector };
+    };
+  }
+  const objectivesOf = (node) => {
+    const objectives = {};
+    if (node.scoreVector && node.scoreVector.length > 0) {
+      scoringScenarios.forEach((s, i) => {
+        objectives[s.id] = node.scoreVector[i] ?? 0;
+      });
+      if (Object.keys(objectives).length > 0) return objectives;
+    }
+    objectives.composite = node.score;
+    return objectives;
+  };
+  const scoredSeeds = [];
+  for (const seed of opts.seeds) {
+    const measured = await scoreSurface(seed.surface);
+    scoredSeeds.push({
+      surface: seed.surface,
+      track: seed.track,
+      proposer: seed.proposer,
+      score: measured.score,
+      ...seed.vision !== void 0 ? { vision: seed.vision } : {},
+      ...measured.scoreVector !== void 0 ? { scoreVector: measured.scoreVector } : {}
+    });
+  }
+  const step = async (args) => {
+    const proposed = await proposer.propose({
+      currentSurface: args.tip.surface,
+      history: [],
+      findings: [],
+      populationSize,
+      generation: 0,
+      signal: new AbortController().signal,
+      paretoParents: []
+    });
+    const pool = [
+      {
+        surface: args.tip.surface,
+        score: args.tip.score,
+        ...args.tip.scoreVector !== void 0 ? { scoreVector: args.tip.scoreVector } : {},
+        ...args.tip.rationale !== void 0 ? { rationale: args.tip.rationale } : {}
+      }
+    ];
+    for (const p of proposed) {
+      const { surface, rationale } = toCandidate(p);
+      const measured = await scoreSurface(surface);
+      pool.push({
+        surface,
+        score: measured.score,
+        ...measured.scoreVector !== void 0 ? { scoreVector: measured.scoreVector } : {},
+        ...rationale !== void 0 ? { rationale } : {}
+      });
+    }
+    let best = pool[0];
+    for (const entry of pool) {
+      if (entry.score > best.score) best = entry;
+    }
+    return {
+      surface: best.surface,
+      score: best.score,
+      ...best.scoreVector !== void 0 ? { scoreVector: best.scoreVector } : {},
+      ...best.rationale !== void 0 ? { rationale: best.rationale } : {}
+    };
+  };
+  const merge = async (args) => {
+    const ordered = [...args.parents].sort((a, b) => b.score - a.score);
+    const paretoParents = ordered.map((node) => ({
+      surface: node.surface,
+      surfaceHash: surfaceHash(node.surface),
+      objectives: objectivesOf(node),
+      composite: node.score,
+      generation: node.generation
+    }));
+    const proposed = await proposer.propose({
+      currentSurface: ordered[0].surface,
+      history: [],
+      findings: [],
+      // A merge is a single crossover; combineParents fires because
+      // paretoParents has > 1 string member.
+      populationSize: 1,
+      // generation >= 1 keeps the combine slot semantically a "merge" step.
+      generation: 1,
+      signal: new AbortController().signal,
+      paretoParents
+    });
+    const first = proposed[0];
+    const merged = first ? toCandidate(first) : { surface: ordered[0].surface };
+    const measured = await scoreSurface(merged.surface);
+    return {
+      surface: merged.surface,
+      score: measured.score,
+      ...measured.scoreVector !== void 0 ? { scoreVector: measured.scoreVector } : {},
+      ...merged.rationale !== void 0 ? { rationale: merged.rationale } : {}
+    };
+  };
+  const result = await runLineage({
+    seeds: scoredSeeds,
+    step,
+    merge,
+    governor,
+    budget: opts.budget,
+    ...opts.store ? { store: opts.store } : {},
+    ...opts.log ? { log: opts.log } : {}
+  });
+  return { lineage: result.lineage, best: result.best, steps: result.steps };
+}
+
 // src/campaign/presets/run-profile-matrix.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import { join as join3 } from "path";
 var ProfileMatrixError = class extends AgentEvalError {
   constructor(message) {
@@ -2025,14 +2698,14 @@ function sanitize(id) {
   return id.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
 function sha(input) {
-  return createHash4("sha256").update(JSON.stringify(input)).digest("hex");
+  return createHash5("sha256").update(JSON.stringify(input)).digest("hex");
 }
-function mean2(xs) {
+function mean3(xs) {
   return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
 }
 function cellComposite(cell) {
   const composites = Object.values(cell.judgeScores).map((s) => s.composite);
-  return composites.length === 0 ? 0 : mean2(composites);
+  return composites.length === 0 ? 0 : mean3(composites);
 }
 function requireResolvedModel(cell, profileId) {
   const resolved = cell.resolvedModel?.trim();
@@ -2068,7 +2741,7 @@ function buildRunRecord(args) {
     if (js.notes) notes.push(`${judgeName}: ${js.notes}`);
   }
   const perDimMean = {};
-  for (const [dim, values] of Object.entries(dimAccum)) perDimMean[dim] = mean2(values);
+  for (const [dim, values] of Object.entries(dimAccum)) perDimMean[dim] = mean3(values);
   let costUsd = cell.costUsd;
   let costEstimated = false;
   if (costUsd === 0 && cell.tokenUsage.output > 0 && isModelPriced(model)) {
@@ -2232,7 +2905,7 @@ async function runProfileMatrix(opts) {
       // one harness, so the first record's model is representative).
       model: declaredModel === HARNESS_NATIVE_MODEL ? profileRecords[0]?.model ?? declaredModel : declaredModel,
       records: profileRecords.length,
-      meanComposite: mean2(profileRecords.map(compositeOf)),
+      meanComposite: mean3(profileRecords.map(compositeOf)),
       totalCostUsd: pricedTotalCostUsd,
       integrity: summarizeBackendIntegrity(profileRecords)
     };
@@ -2262,7 +2935,7 @@ function rollup(records, keyOf) {
     groups.set(key, arr);
   }
   const out = {};
-  for (const [key, xs] of groups) out[key] = { meanComposite: mean2(xs), n: xs.length };
+  for (const [key, xs] of groups) out[key] = { meanComposite: mean3(xs), n: xs.length };
   return out;
 }
 function rollupByPersona(records, scenarios, personaOf) {
@@ -2665,6 +3338,53 @@ ${report.slice(0, 800)}`,
   });
 }
 
+// src/campaign/scenario-selection.ts
+var DEFAULT_SATURATION_CEILING = 0.999;
+var VARIANCE_EPSILON = 1e-9;
+function moments(scores) {
+  const n = scores.length;
+  if (n === 0) return { meanScore: 0, variance: 0 };
+  let sum = 0;
+  for (const s of scores) sum += s;
+  const meanScore = sum / n;
+  let sqDev = 0;
+  for (const s of scores) {
+    const d = s - meanScore;
+    sqDev += d * d;
+  }
+  return { meanScore, variance: sqDev / n };
+}
+function compareDiscrimination(a, b) {
+  if (b.discrimination !== a.discrimination) return b.discrimination - a.discrimination;
+  if (a.meanScore !== b.meanScore) return a.meanScore - b.meanScore;
+  return a.scenarioId < b.scenarioId ? -1 : a.scenarioId > b.scenarioId ? 1 : 0;
+}
+function scoreDiscrimination(signals, opts) {
+  const saturationCeiling = opts?.saturationCeiling ?? DEFAULT_SATURATION_CEILING;
+  const scored = signals.map((signal) => {
+    const { meanScore, variance } = moments(signal.scores);
+    const tied = variance < VARIANCE_EPSILON && meanScore >= saturationCeiling;
+    return {
+      scenarioId: signal.scenarioId,
+      discrimination: variance,
+      meanScore,
+      variance,
+      tied
+    };
+  });
+  return scored.sort(compareDiscrimination);
+}
+function selectDiscriminative(signals, k, opts) {
+  if (k < 1) throw new Error(`selectDiscriminative: k must be >= 1 (got ${k})`);
+  const ranked = scoreDiscrimination(signals, opts);
+  if (ranked.length <= k) return ranked.map((s) => s.scenarioId);
+  const nonTied = ranked.filter((s) => !s.tied);
+  if (nonTied.length >= k) return nonTied.slice(0, k).map((s) => s.scenarioId);
+  const tied = ranked.filter((s) => s.tied);
+  const fill = tied.slice(0, k - nonTied.length);
+  return [...nonTied, ...fill].map((s) => s.scenarioId);
+}
+
 // src/campaign/worktree/index.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync3 } from "fs";
@@ -2727,6 +3447,7 @@ function resolveWorktreePath(surface, worktreeDir) {
 export {
   FsLabeledScenarioStore,
   LabeledScenarioStoreError,
+  Lineage,
   ProfileMatrixError,
   SkillPatchParseError,
   WorktreeAdapterError,
@@ -2735,6 +3456,7 @@ export {
   buildAnalystSurfaceDispatch,
   buildEvidenceVector,
   buildLoopProvenanceRecord,
+  callbackGovernor,
   campaignBreakdown,
   campaignMeanComposite,
   compareProposers,
@@ -2753,6 +3475,7 @@ export {
   fapoEscalationEntry,
   fapoProposer,
   fsCampaignStorage,
+  fsLineageStore,
   gepaParetoEntry,
   gepaProposer,
   gepaReflectionEntry,
@@ -2760,15 +3483,20 @@ export {
   haloProposer,
   heldOutGate,
   heldoutSignificance,
+  heuristicGovernor,
   inMemoryCampaignStorage,
   isProposedCandidate,
   labelTrustRank,
+  lineageNodeId,
   llmJudge,
   loadEvalFixture,
   loadEvalFixtureScenarios,
   loopProvenanceSpans,
   makePlaybackDispatch,
+  memLineageStore,
   memoryCurationProposer,
+  neutralizationGate,
+  neutralizeText,
   openAutoPr,
   pairHoldout,
   parameterSweepProposer,
@@ -2788,11 +3516,15 @@ export {
   runCampaign,
   runEval,
   runImprovementLoop,
+  runLineage,
+  runLineageLoop,
   runOptimization,
   runProfileMatrix,
   runSkillOpt,
+  scoreDiscrimination,
   scoreUserStory,
   scoreboardSummary,
+  selectDiscriminative,
   sequentialDecide,
   sequentialPairedGate,
   skillOptEntry,