@tangle-network/agent-eval 0.106.2 → 0.107.0

package/dist/adapters/http.d.ts

@@ -1,4 +1,4 @@
-import { S as Scenario, D as DispatchFn, b as DispatchContext } from '../types-Ctf7XIAL.js';
+import { S as Scenario, D as DispatchFn, b as DispatchContext } from '../types-CNZ0tHET.js';
 import '../run-record-I-Z3JNvO.js';
 import '@tangle-network/agent-interface';
 import '../errors-oeQrLqXC.js';

package/dist/adapters/langchain.d.ts

@@ -1,4 +1,4 @@
-import { S as Scenario, J as JudgeScore, D as DispatchFn, a as JudgeConfig } from '../types-Ctf7XIAL.js';
+import { S as Scenario, J as JudgeScore, D as DispatchFn, a as JudgeConfig } from '../types-CNZ0tHET.js';
 import '../run-record-I-Z3JNvO.js';
 import '@tangle-network/agent-interface';
 import '../errors-oeQrLqXC.js';

package/dist/adapters/otel.d.ts

@@ -1,5 +1,5 @@
 import { TraceSpanEvent, HostedClient } from '../hosted/index.js';
-import '../types-Ctf7XIAL.js';
+import '../types-CNZ0tHET.js';
 import '../run-record-I-Z3JNvO.js';
 import '@tangle-network/agent-interface';
 import '../errors-oeQrLqXC.js';

package/dist/campaign/index.d.ts

@@ -1,11 +1,11 @@
-import { S as SignedManifest, B as BackendIntegrityReport, C as CompletionRequirement, R as RuntimeEventLike, a as CompletionVerdict, P as ProducedState, b as CorrectnessChecker } from '../pre-registration-BkkTmtQG.js';
-export { L as LlmJudgeDimension, c as LlmJudgeOptions, l as llmJudge } from '../pre-registration-BkkTmtQG.js';
+import { S as SignedManifest, B as BackendIntegrityReport, C as CompletionRequirement, R as RuntimeEventLike, a as CompletionVerdict, P as ProducedState, b as CorrectnessChecker } from '../pre-registration-x3f0VpxT.js';
+export { L as LlmJudgeDimension, c as LlmJudgeOptions, l as llmJudge } from '../pre-registration-x3f0VpxT.js';
 import { A as AnalyzeTracesOptions, a as AnalyzeTracesInput, b as AnalyzeTracesResult } from '../analyst-C8HHvfJp.js';
-import { S as Scenario, M as MutableSurface, b as DispatchContext, a as JudgeConfig, e as GenerationRecord, g as Gate, J as JudgeScore, L as LabeledScenarioStore, s as LabeledScenarioWrite, t as LabeledScenarioSampleArgs, u as LabeledScenarioRecord, v as LabelTrust, f as SurfaceProposer, w as ProposedCandidate, x as ProposeContext, y as LabeledScenarioSource, C as CampaignResult, m as CodeSurface } from '../types-Ctf7XIAL.js';
-export { i as CampaignAggregates, j as CampaignArtifactWriter, k as CampaignCellResult, l as CampaignCostMeter, z as CampaignTokenUsage, d as CampaignTraceWriter, D as DispatchFn, n as GateContext, h as GateDecision, G as GateResult, o as GenerationCandidate, A as JudgeAggregate, c as JudgeDimension, p as Mutator, O as OptimizationProposer, q as OptimizerConfig, P as ParetoParent, R as RedactionStatus, B as ScenarioAggregate, r as SessionScript, T as TraceSpan, E as isProposedCandidate, F as labelTrustRank } from '../types-Ctf7XIAL.js';
-import { e as CampaignRunPlan, P as PlanCampaignRunOptions, C as CampaignStorage, b as RunCampaignOptions, c as RunImprovementLoopOptions } from '../gepa-DQ3ruj18.js';
-export { h as CampaignRunPlanCell, j as GepaProposerConstraints, G as GepaProposerOptions, O as OpenAutoPrOptions, k as OpenAutoPrResult, a as RunImprovementLoopResult, R as RunOptimizationOptions, l as RunOptimizationResult, m as countSentenceEdits, n as defaultRenderDiff, o as extractH2Sections, f as fsCampaignStorage, g as gepaProposer, i as inMemoryCampaignStorage, p as openAutoPr, q as planCampaignRun, r as runCampaign, d as runImprovementLoop, s as runOptimization, t as surfaceHash } from '../gepa-DQ3ruj18.js';
-export { A as AxisEvidence, a as AxisVerdict, B as BuildEvidenceVectorOptions, l as BuildLoopProvenanceArgs, D as DefaultProductionGateOptions, m as EmitLoopProvenanceArgs, n as EmitLoopProvenanceResult, E as EvidenceVector, b as EvolutionaryProposerOptions, H as HeldOutGateOptions, o as LoopProvenanceBackend, q as LoopProvenanceCandidate, L as LoopProvenanceRecord, O as ObjectiveSource, c as ParetoSignificanceGateOptions, P as PowerPreflight, s as PowerPreflightOptions, d as PromotionObjective, e as PromotionPolicy, R as RunEvalOptions, f as buildEvidenceVector, t as buildLoopProvenanceRecord, g as composeGate, h as defaultProductionGate, u as emitLoopProvenance, i as evolutionaryProposer, j as heldOutGate, v as loopProvenanceSpans, p as paretoPolicy, k as paretoSignificanceGate, w as powerPreflight, x as provenanceRecordPath, y as provenanceSpansPath, r as runEval, z as surfaceContentHash } from '../provenance-Bsyjc67Z.js';
+import { S as Scenario, M as MutableSurface, b as DispatchContext, a as JudgeConfig, g as Gate, e as GenerationRecord, J as JudgeScore, L as LabeledScenarioStore, s as LabeledScenarioWrite, t as LabeledScenarioSampleArgs, u as LabeledScenarioRecord, v as LabelTrust, f as SurfaceProposer, w as ProposedCandidate, x as ProposeContext, y as LabeledScenarioSource, C as CampaignResult, m as CodeSurface } from '../types-CNZ0tHET.js';
+export { i as CampaignAggregates, j as CampaignArtifactWriter, k as CampaignCellResult, l as CampaignCostMeter, z as CampaignTokenUsage, d as CampaignTraceWriter, D as DispatchFn, n as GateContext, h as GateDecision, G as GateResult, o as GenerationCandidate, A as JudgeAggregate, c as JudgeDimension, p as Mutator, O as OptimizationProposer, q as OptimizerConfig, P as ParetoParent, R as RedactionStatus, B as ScenarioAggregate, r as SessionScript, T as TraceSpan, E as isProposedCandidate, F as labelTrustRank } from '../types-CNZ0tHET.js';
+import { e as CampaignRunPlan, P as PlanCampaignRunOptions, C as CampaignStorage, b as RunCampaignOptions, c as RunImprovementLoopOptions } from '../gepa-BmqTrdtg.js';
+export { h as CampaignRunPlanCell, j as GepaProposerConstraints, G as GepaProposerOptions, O as OpenAutoPrOptions, k as OpenAutoPrResult, a as RunImprovementLoopResult, R as RunOptimizationOptions, l as RunOptimizationResult, m as countSentenceEdits, n as defaultRenderDiff, o as extractH2Sections, f as fsCampaignStorage, g as gepaProposer, i as inMemoryCampaignStorage, p as openAutoPr, q as planCampaignRun, r as runCampaign, d as runImprovementLoop, s as runOptimization, t as surfaceHash } from '../gepa-BmqTrdtg.js';
+export { A as AxisEvidence, a as AxisVerdict, B as BuildEvidenceVectorOptions, l as BuildLoopProvenanceArgs, D as DefaultProductionGateOptions, m as EmitLoopProvenanceArgs, n as EmitLoopProvenanceResult, E as EvidenceVector, b as EvolutionaryProposerOptions, H as HeldOutGateOptions, o as LoopProvenanceBackend, q as LoopProvenanceCandidate, L as LoopProvenanceRecord, O as ObjectiveSource, c as ParetoSignificanceGateOptions, P as PowerPreflight, s as PowerPreflightOptions, d as PromotionObjective, e as PromotionPolicy, R as RunEvalOptions, f as buildEvidenceVector, t as buildLoopProvenanceRecord, g as composeGate, h as defaultProductionGate, u as emitLoopProvenance, i as evolutionaryProposer, j as heldOutGate, v as loopProvenanceSpans, p as paretoPolicy, k as paretoSignificanceGate, w as powerPreflight, x as provenanceRecordPath, y as provenanceSpansPath, r as runEval, z as surfaceContentHash } from '../provenance-CIjRcI6m.js';
 import { E as EProcessState, a as PairedBootstrapResult } from '../statistics-D88peojY.js';
 import { L as LlmClientOptions } from '../llm-client-DyqEH4jH.js';
 import { AgentProfile } from '@tangle-network/agent-interface';
@@ -32,6 +32,242 @@ import '../judge-calibration-7C-IDmKr.js';
 import '../types-C7DGg5ex.js';
 import 'zod';
 
+/**
+ * Lineage DAG — a git-graph of improvement candidates.
+ *
+ * The improvement loop (`run-optimization.ts`) records a LINEAR `GenerationRecord[]`
+ * with no parent pointers, computes a Pareto frontier within a run, then collapses
+ * to one gated winner and discards the rest. This module adds the missing
+ * first-class structure: a directed acyclic graph of candidate versions where
+ *
+ *   - a node with ONE parent is a mutation,
+ *   - a node with ZERO parents is a root/seed,
+ *   - a node with 2+ parents is a MERGE (a "collapse") — nothing special-cased,
+ *     just a multi-parent node,
+ *   - a `track` groups a lineage into an island, and each track runs a distinct
+ *     `vision` (a proposer strategy — e.g. a "solve" vision, an "outside-the-box"
+ *     vision, and an adversarial "contrarian" vision that attacks the leader).
+ *
+ * An agent-managed {@link Governor} decides the next operation (extend / branch /
+ * merge / prune / stop), so branching AND collapsing are choices a supervisor
+ * makes by reading the graph, not hard-coded control flow.
+ *
+ * DETERMINISM is a hard invariant: no `Date.now`, `Math.random`, or `new Date`.
+ * Ids are content+lineage hashes; order is a monotone insertion counter; every
+ * query returns nodes in `seq` order. Same inputs ⇒ identical graph.
+ */
+interface LineageNode {
+    /** Deterministic content+lineage hash (see {@link lineageNodeId}). */
+    id: string;
+    /** `[]` = root/seed; `[x]` = mutation; `[x, y, ...]` = MERGE (collapse). */
+    parentIds: string[];
+    /** Logical island/track this node belongs to. */
+    track: string;
+    /** Human label for the strategy driving this track (e.g. `solve`, `contrarian`). */
+    vision?: string;
+    /** Candidate content (prompt text, skill document, config JSON, ...). */
+    surface: string;
+    /** Scalar fitness (e.g. mean holdout composite); higher is better. */
+    score: number;
+    /** Optional per-scenario objective vector for Pareto dominance. */
+    scoreVector?: number[];
+    /** Which proposer produced it (`gepa`, `skill-opt`, `merge`, `seed`, ...). */
+    proposer: string;
+    rationale?: string;
+    /** Gate verdict, when this node was gated. */
+    gate?: 'ship' | 'hold';
+    /** Step index within its track (root = 0). */
+    generation: number;
+    /** Monotone global insertion order (assigned by {@link Lineage.addNode}). */
+    seq: number;
+}
+interface LineageEdge {
+    /** Parent node id. */
+    from: string;
+    /** Child node id. */
+    to: string;
+}
+interface LineageGraph {
+    nodes: LineageNode[];
+    edges: LineageEdge[];
+}
+/** Deterministic node id: a hash of the node's lineage + content + proposer.
+ *  Pure — identical inputs always yield the same id (a re-derived node collapses
+ *  onto its original rather than duplicating). */
+declare function lineageNodeId(input: {
+    parentIds: string[];
+    track: string;
+    surface: string;
+    proposer: string;
+}): string;
+/** Input to {@link Lineage.addNode}: everything but the derived `id`/`seq` and the
+ *  optional `generation` (derived from parents when omitted). */
+type LineageNodeInput = Omit<LineageNode, 'id' | 'seq' | 'generation'> & {
+    generation?: number;
+};
+declare class Lineage {
+    private readonly byId;
+    private readonly childIds;
+    private nextSeq;
+    constructor(nodes?: readonly LineageNode[]);
+    /** 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: LineageNodeInput): LineageNode;
+    /** 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: {
+        parentIds: string[];
+        track: string;
+        surface: string;
+        score: number;
+        proposer?: string;
+        vision?: string;
+        scoreVector?: number[];
+        rationale?: string;
+    }): LineageNode;
+    get(id: string): LineageNode | undefined;
+    has(id: string): boolean;
+    /** All nodes, in insertion (`seq`) order. */
+    all(): LineageNode[];
+    roots(): LineageNode[];
+    parents(id: string): LineageNode[];
+    children(id: string): LineageNode[];
+    /** Transitive ancestors (excludes `id`). */
+    ancestors(id: string): Set<string>;
+    /** Transitive descendants (excludes `id`). */
+    descendants(id: string): Set<string>;
+    /** Nodes with no children (leaf/branch tips). */
+    tips(): LineageNode[];
+    /** Distinct track ids, in first-seen (`seq`) order. */
+    tracks(): string[];
+    trackNodes(track: string): LineageNode[];
+    /** The highest-`score` tip of a track (ties broken by lowest `seq`). */
+    trackTip(track: string): LineageNode | undefined;
+    /** The highest-`score` node overall (ties broken by lowest `seq`). */
+    best(): LineageNode | undefined;
+    /** 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(): LineageNode[];
+    toGraph(): LineageGraph;
+    /** One JSON node per line, in `seq` order. */
+    toJSONL(): string;
+    static fromJSONL(text: string): Lineage;
+    private index;
+}
+interface LineageStore {
+    /** Load the persisted lineage (an empty `Lineage` when nothing is stored). */
+    load(): Promise<Lineage>;
+    /** Append one node durably. */
+    append(node: LineageNode): Promise<void>;
+    /** Overwrite with a full snapshot. */
+    save(lineage: Lineage): Promise<void>;
+}
+/** JSONL-file store: append-only durability, snapshot via rewrite, `load` parses
+ *  through {@link Lineage.fromJSONL}. */
+declare function fsLineageStore(path: string): LineageStore;
+/** In-memory store (default; for tests and ephemeral runs). */
+declare function memLineageStore(): LineageStore;
+type GovernorOp = {
+    op: 'extend';
+    track: string;
+} | {
+    op: 'branch';
+    fromNodeId: string;
+    track: string;
+    proposer: string;
+    vision?: string;
+} | {
+    op: 'merge';
+    parentIds: string[];
+    track: string;
+} | {
+    op: 'prune';
+    track: string;
+} | {
+    op: 'stop';
+};
+interface GovernorContext {
+    lineage: Lineage;
+    /** Operations executed so far. */
+    step: number;
+    budgetRemaining: number;
+    /** Tracks already pruned — the governor must not target these for extend/branch. */
+    prunedTracks: string[];
+}
+interface Governor {
+    decide(ctx: GovernorContext): Promise<GovernorOp> | GovernorOp;
+}
+interface HeuristicGovernorOptions {
+    /** Cap on live tracks before branching a new one. Default 3. */
+    maxTracks?: number;
+    /** Non-improving steps a track may take before it is pruned. Default 2. */
+    plateauSteps?: number;
+    /** Frontier-tip count (across distinct tracks) that triggers a merge. Default 2. */
+    mergeFrontierAt?: number;
+}
+/** The reference deterministic policy an agent {@link Governor} can replace.
+ *  Reads only the lineage + context — no LLM, no randomness. */
+declare function heuristicGovernor(opts?: HeuristicGovernorOptions): Governor;
+/** The LLM-supervisor slot: a governor whose `decide` defers to a caller-supplied
+ *  async function (which may read `ctx.lineage.toGraph()`). */
+declare function callbackGovernor(decide: (ctx: GovernorContext) => Promise<GovernorOp>): Governor;
+interface RunLineageSeed {
+    surface: string;
+    track: string;
+    vision?: string;
+    proposer: string;
+    score: number;
+    scoreVector?: number[];
+}
+interface RunLineageStepResult {
+    surface: string;
+    score: number;
+    scoreVector?: number[];
+    rationale?: string;
+    gate?: 'ship' | 'hold';
+}
+interface RunLineageOptions {
+    seeds: RunLineageSeed[];
+    /** Produce one new candidate from a track's tip (propose + measure + gate in
+     *  real use; a pure function in tests). */
+    step: (args: {
+        track: string;
+        proposer: string;
+        tip: LineageNode;
+    }) => Promise<RunLineageStepResult>;
+    /** Collapse 2+ parent surfaces into one (GEPA crossover / LLM merge in real use). */
+    merge: (args: {
+        parents: LineageNode[];
+        track: string;
+    }) => Promise<Omit<RunLineageStepResult, 'gate'>>;
+    governor: Governor;
+    budget: {
+        maxSteps: number;
+    };
+    store?: LineageStore;
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface RunLineageResult {
+    lineage: Lineage;
+    best: LineageNode | undefined;
+    steps: number;
+}
+/** Drive a multi-track improvement DAG under an agent-managed governor. Seeds each
+ *  entry as a root, then repeatedly asks the governor for the next operation
+ *  (extend / branch / merge / prune / stop) up to `budget.maxSteps`, persisting
+ *  every node. Honors `prune`: a pruned track is never extended or branched again. */
+declare function runLineage(opts: RunLineageOptions): Promise<RunLineageResult>;
+
 /**
  * Make the trace-analyst's OWN prompt a GEPA-optimizable surface.
  *
@@ -199,6 +435,43 @@ declare function loadEvalFixtureScenarios(evalsDir: string, options?: LoadEvalFi
  */
 declare function planEvalFixtureRun<TArtifact = unknown>(options: PlanEvalFixtureRunOptions<TArtifact>): EvalFixtureRunPlan;
 
+/**
+ * @module
+ * Composable placebo / neutralization promotion gate.
+ *
+ * A held-out gate proves a candidate beat baseline. It CANNOT prove the lift came
+ * from the candidate's CONTENT rather than from the prompt/mount FOOTPRINT the
+ * content happened to add (more bytes, a longer prompt). This gate closes that
+ * hole: it compares the candidate's held-out lift against the lift of a
+ * FOOTPRINT-MATCHED neutralized variant (same layout + length, zero content, via
+ * `neutralizeText`). If the neutralized variant reproduces more than
+ * `maxDecorativeFraction` of the candidate's lift, the lift is decorative — it
+ * survives blanking the content — and the candidate is HELD regardless of how
+ * large or significant its raw lift is.
+ *
+ * Compose it AFTER the significance gate — significance says the lift is real,
+ * this says the lift is CAUSED BY THE CONTENT:
+ *   composeGate(heldOutGate({ ... }), neutralizationGate({ ... }))
+ *
+ * Requires `ctx.neutralizedJudgeScores`, populated by `runImprovementLoop` when it
+ * is given a `neutralize` function. A gate composed without that wiring fails
+ * loud rather than silently passing an unproven candidate.
+ */
+
+interface NeutralizationGateOptions<TScenario extends Scenario = Scenario> {
+    scenarios: TScenario[];
+    /** Reject when the neutralized (content-blanked, footprint-matched) variant
+     *  reproduces at least this fraction of the candidate's held-out lift. Default
+     *  0.5 — if blanking the content keeps half the lift, the content is decorative.
+     *  Equality rejects: a neutralized lift == threshold·candidateLift is decorative. */
+    maxDecorativeFraction?: number;
+}
+/**
+ * Composable placebo gate: ships only when the candidate's held-out lift is NOT
+ * mostly reproduced by a footprint-matched neutralized variant.
+ */
+declare function neutralizationGate<TArtifact, TScenario extends Scenario>(options: NeutralizationGateOptions<TScenario>): Gate<TArtifact, TScenario>;
+
 /**
  * Anytime-valid sequential promotion gate — an e-process (betting
  * test-martingale, see `eProcess` in `statistics.ts`) over paired
@@ -515,6 +788,34 @@ declare class FsLabeledScenarioStore implements LabeledScenarioStore {
     private pathForSource;
 }
 
+/**
+ * @module
+ * Footprint-matched neutralization — the placebo control for content-vs-footprint
+ * attribution in a promotion gate.
+ *
+ * A promoted surface can raise a held-out score two different ways:
+ *  1. its CONTENT is informative (the thing we want to promote), or
+ *  2. it merely added prompt/mount FOOTPRINT — more bytes, more lines, a longer
+ *     more authoritative-looking prompt — that the model spends attention on
+ *     regardless of what the bytes say.
+ *
+ * A held-out gate proves the candidate beat baseline; it cannot separate (1) from
+ * (2). `neutralizeText` produces a variant that keeps the input's layout and
+ * length while carrying ZERO information, so scoring it isolates the footprint
+ * contribution (2). Feed the neutralized variant's scores to `neutralizationGate`:
+ * any lift it still holds over baseline is decorative, and a candidate whose lift
+ * survives neutralization is rejected however large its raw lift.
+ */
+/**
+ * Blank every non-whitespace character to a 1-byte filler while preserving all
+ * whitespace. Line count, indentation, and word/line lengths are unchanged — so
+ * the neutralized variant has the same layout and (for ASCII) the same byte
+ * footprint as the input, but no readable content. Whitespace is preserved
+ * deliberately: collapsing it would change the token structure and stop the
+ * variant from being a true footprint match.
+ */
+declare function neutralizeText(content: string): string;
+
 /**
  * FAPO (Fully Autonomous Prompt Optimization) is an orchestration policy, not
  * a new prompt mutation primitive. The paper's loop evaluates an inspectable
@@ -1051,6 +1352,129 @@ interface ScoreboardRenderOptions {
  */
 declare function renderScoreboardMarkdown(rows: readonly ScoreboardRow[], opts?: ScoreboardRenderOptions): string;
 
+/**
+ * `runLineageLoop` — the live adapter that wires the {@link runLineage} DAG's
+ * two abstract seams (`step`, `merge`) to the REAL improvement machinery, so the
+ * multi-track, multi-parent improvement DAG can run against a real proposer +
+ * real measurement.
+ *
+ * INTEGRATION CHOICE (smallest correct integration):
+ *   - `step`  = ONE `SurfaceProposer.propose` from the track tip (a single GEPA
+ *               reflective generation, small population) + one scoring campaign
+ *               per candidate. The best-scoring candidate (elitist: the tip is
+ *               kept in the pool so a step never regresses below its parent)
+ *               becomes the new DAG node.
+ *   - `merge` = the SAME proposer driven with `ctx.paretoParents` set to the
+ *               2+ parent surfaces, which fires `gepaProposer`'s GEPA
+ *               combine-complementary-lessons CROSSOVER, then one scoring
+ *               campaign on the merged surface.
+ *
+ * We deliberately do NOT run a full {@link runImprovementLoop} (baseline
+ * campaign + optimization + two holdout campaigns + gate + optional PR) per DAG
+ * step — that is the OUTER gated-promotion shell for a single lineage, far too
+ * heavy to fire once per node. The DAG {@link Governor} controls BREADTH across
+ * steps (extend / branch / merge / prune); the inner step is intentionally one
+ * small generation. This mirrors the task's guidance: "Keep the improvement
+ * budget per step SMALL (1 generation, small population)."
+ *
+ * Both machinery halves are injectable seams so the loop is unit-testable
+ * without a live model or a sandbox:
+ *   - `proposer`     — defaults to {@link gepaProposer} (needs `llm` + `model`).
+ *                      A test injects a pure stub `SurfaceProposer`.
+ *   - `scoreSurface` — defaults to a {@link runCampaign} pass over
+ *                      `holdoutScenarios ?? scenarios` (the "agent" =
+ *                      `dispatchWithSurface`, the judges = `judges`). A test
+ *                      injects a deterministic function of the surface string,
+ *                      or supplies a stub `dispatchWithSurface` + `judges` and
+ *                      exercises the real `runCampaign` path.
+ *
+ * Additive: no changes to `lineage.ts`, `run-optimization.ts`, or `gepa.ts`.
+ */
+
+/** A seed track: the initial surface + track identity. Unlike
+ *  {@link RunLineageSeed} there is NO `score` — `runLineageLoop` scores each
+ *  seed surface in an initial pass so seed fitness is measured, not asserted. */
+interface RunLineageLoopSeed {
+    surface: MutableSurface;
+    track: string;
+    /** Human label for the strategy driving this track (e.g. `solve`,
+     *  `outside-the-box`, `contrarian`). */
+    vision?: string;
+    /** Proposer label recorded on the seed node (e.g. `gepa`, `seed`). */
+    proposer: string;
+}
+/** The measured fitness of one surface — the value recorded on a DAG node. */
+interface SurfaceScore {
+    score: number;
+    /** Per-objective vector (per-scenario composite) for Pareto dominance across
+     *  track tips. Omitted ⇒ the DAG uses the scalar `score`. */
+    scoreVector?: number[];
+}
+interface RunLineageLoopOptions<TScenario extends Scenario, TArtifact> {
+    /** The visioned tracks to seed the DAG with. Each is scored once up front. */
+    seeds: RunLineageLoopSeed[];
+    /** Scenarios the candidate surfaces are proposed against + scored on. */
+    scenarios: TScenario[];
+    /** Held-out scenarios used to SCORE each DAG node's fitness. Defaults to
+     *  `scenarios` when omitted. Scored the same way for seeds, steps, and merges
+     *  so every node's `score` is comparable. */
+    holdoutScenarios?: TScenario[];
+    /** Judges for the scoring campaign. */
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    /** The "agent" seam: run the CURRENT surface on a scenario → artifact. Same
+     *  shape as `runOptimization`'s `dispatchWithSurface`. Required UNLESS a
+     *  custom `scoreSurface` is injected. */
+    dispatchWithSurface?: (surface: MutableSurface, scenario: TScenario, ctx: Parameters<RunCampaignOptions<TScenario, TArtifact>['dispatch']>[1]) => Promise<TArtifact>;
+    /** Where scoring campaigns write. Required UNLESS `scoreSurface` is injected. */
+    runDir?: string;
+    /** Router transport for the default `gepaProposer`. Required UNLESS a custom
+     *  `proposer` is injected. */
+    llm?: LlmClientOptions;
+    /** Model for the default `gepaProposer`. Required UNLESS a custom `proposer`
+     *  is injected. */
+    model?: string;
+    /** What is being optimized — appears in the GEPA reflection/combine prompts.
+     *  Default `'agent surface'`. */
+    target?: string;
+    /** Candidates proposed per extend/branch step (BREADTH within one step).
+     *  Default 4. The merge always proposes a single crossover. */
+    populationSize?: number;
+    /** Agent-managed decision layer. Default {@link heuristicGovernor}. */
+    governor?: Governor;
+    budget: {
+        maxSteps: number;
+    };
+    store?: LineageStore;
+    /** Override the per-step proposer. Default {@link gepaProposer}. Inject a
+     *  pure stub to unit-test without an LLM. */
+    proposer?: SurfaceProposer;
+    /** Override how a surface is scored into a DAG-node fitness. Default is a
+     *  {@link runCampaign} pass over `holdoutScenarios ?? scenarios`. Inject a
+     *  deterministic function to unit-test without a campaign. */
+    scoreSurface?: (surface: MutableSurface) => Promise<SurfaceScore>;
+    seed?: number;
+    reps?: number;
+    storage?: CampaignStorage;
+    tracing?: 'on' | 'off';
+    expectUsage?: 'assert' | 'warn' | 'off';
+    maxConcurrency?: number;
+    dispatchTimeoutMs?: number;
+    /** Test seam — deterministic wall clock forwarded to `runCampaign`. */
+    now?: () => Date;
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface RunLineageLoopResult {
+    lineage: Lineage;
+    best: LineageNode | undefined;
+    steps: number;
+}
+/**
+ * Wire the {@link runLineage} DAG's `step`/`merge` seams to a real
+ * `SurfaceProposer` + a real scoring campaign and run the multi-track improvement
+ * DAG live under a {@link Governor}.
+ */
+declare function runLineageLoop<TScenario extends Scenario, TArtifact>(opts: RunLineageLoopOptions<TScenario, TArtifact>): Promise<RunLineageLoopResult>;
+
 /**
  * SkillOpt patch primitives (Microsoft, arXiv:2605.23904 — "Executive
  * Strategy for Self-Evolving Agent Skills"). Where GEPA regenerates a surface
@@ -1511,6 +1935,60 @@ declare function tangleTracesRoot(): string;
  *  compute so callers pass a *name*, not a path. */
 declare function resolveRunDir(runDir: string, repo?: string): string;
 
+/**
+ * Discriminative scenario selection (research claim E2).
+ *
+ * The OR benchmark is SATURATING: run 7 measured ~75% tied holdout cells — most
+ * problems are solved optimally by the baseline AND every candidate, so those
+ * paired cells carry zero signal. A random/balanced holdout split spends its
+ * budget on scenarios that cannot separate candidates.
+ *
+ * This picks the holdout by DISCRIMINATION power instead: a scenario every
+ * candidate scores identically (variance ~0) carries no signal; one where the
+ * scores spread carries the most. We drop fully saturated ties so each paired
+ * holdout cell is spent on a scenario that can actually move a verdict.
+ */
+/** Per-scenario observation: the composite scores each candidate earned on it. */
+interface ScenarioSignal {
+    scenarioId: string;
+    /** Per-candidate composite scores observed for this scenario (>=1 values). */
+    scores: number[];
+}
+interface DiscriminationScore {
+    scenarioId: string;
+    /** Higher = separates candidates more (spread of their scores). */
+    discrimination: number;
+    /** Higher = easier / more-saturated (mean of candidate scores). */
+    meanScore: number;
+    variance: number;
+    /** variance ~0 AND meanScore at/above the ceiling ⇒ a saturated tie, no signal. */
+    tied: boolean;
+}
+/**
+ * Rank scenarios by how well they DISCRIMINATE candidates.
+ *
+ * `discrimination = variance` (spread of the candidate scores) — kept simple on
+ * purpose; the headroom term (`saturationCeiling - meanScore`) only breaks ties
+ * so that, among equally spread scenarios, the one with more room to improve
+ * ranks first. Returned sorted by the deterministic order above.
+ */
+declare function scoreDiscrimination(signals: ScenarioSignal[], opts?: {
+    saturationCeiling?: number;
+}): DiscriminationScore[];
+/**
+ * Select the top-`k` most discriminative scenario ids for a holdout, EXCLUDING
+ * fully saturated ties when enough non-tied scenarios exist (a tie in the
+ * holdout wastes a paired cell).
+ *
+ * Prefers non-tied scenarios; if fewer than `k` non-tied exist, fills with the
+ * least-saturated tied ones (tied scenarios are already ordered least-saturated
+ * first by `meanScore` asc). Deterministic. Throws if `k < 1`. If
+ * `signals.length <= k`, returns all ids in discrimination order.
+ */
+declare function selectDiscriminative(signals: ScenarioSignal[], k: number, opts?: {
+    saturationCeiling?: number;
+}): string[];
+
 /**
  * Shared campaign-score reductions used by every optimizer preset
  * (`runOptimization`, `runSkillOpt`, `compareProposers`). ONE definition of
@@ -1594,4 +2072,4 @@ declare function gitWorktreeAdapter(opts: GitWorktreeAdapterOptions): WorktreeAd
  *  as a ref under the adapter's worktree dir. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type ApplySkillPatchResult, type BuildAnalystSurfaceDispatchOptions, type CampaignBreakdown, CampaignResult, CampaignRunPlan, CampaignStorage, CodeSurface, type CompareProposersOptions, type DimensionRegression, DispatchContext, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GenerationRecord, type GitWorktreeAdapterOptions, type HaloProposerOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type JsonPrimitive, type JsonValue, JudgeConfig, JudgeScore, LabelTrust, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioSource, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, type LoadEvalFixtureScenariosOptions, type MemoryCurationProposerOptions, MutableSurface, type OptimizerEntryConfig, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditProposerOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, ProposeContext, type ProposePatchesArgs, ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RejectedEdit, RunCampaignOptions, RunImprovementLoopOptions, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, Scenario, type ScenarioRollup, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, SurfaceProposer, type TraceAnalystProposerOptions, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, applySkillPatch, buildAnalystSurfaceDispatch, campaignBreakdown, campaignMeanComposite, compareProposers, detectScale, dimensionRegressions, discoverEvalFixtures, extractFapoAttributionSignals, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, gepaParetoEntry, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldoutSignificance, loadEvalFixture, loadEvalFixtureScenarios, makePlaybackDispatch, memoryCurationProposer, pairHoldout, parameterSweepProposer, parseSkillPatchResponse, patchEditCount, planEvalFixtureRun, policyEditProposer, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, runProfileMatrix, runSkillOpt, scoreUserStory, scoreboardSummary, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard };
+export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type ApplySkillPatchResult, type BuildAnalystSurfaceDispatchOptions, type CampaignBreakdown, CampaignResult, CampaignRunPlan, CampaignStorage, CodeSurface, type CompareProposersOptions, type DimensionRegression, type DiscriminationScore, DispatchContext, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GenerationRecord, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPrimitive, type JsonValue, JudgeConfig, JudgeScore, LabelTrust, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioSource, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LoadEvalFixtureScenariosOptions, type MemoryCurationProposerOptions, MutableSurface, type NeutralizationGateOptions, type OptimizerEntryConfig, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditProposerOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, ProposeContext, type ProposePatchesArgs, ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RejectedEdit, RunCampaignOptions, RunImprovementLoopOptions, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, Scenario, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, applySkillPatch, buildAnalystSurfaceDispatch, callbackGovernor, campaignBreakdown, campaignMeanComposite, compareProposers, detectScale, dimensionRegressions, discoverEvalFixtures, extractFapoAttributionSignals, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsLineageStore, gepaParetoEntry, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldoutSignificance, heuristicGovernor, lineageNodeId, loadEvalFixture, loadEvalFixtureScenarios, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, pairHoldout, parameterSweepProposer, parseSkillPatchResponse, patchEditCount, planEvalFixtureRun, policyEditProposer, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, runLineage, runLineageLoop, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard };