@tangle-network/agent-eval 0.94.0 → 0.95.1

package/dist/{types-BU-7W85F.d.ts → types-DQRY8ZT-.d.ts}

@@ -1,8 +1,6 @@
-import { b as RunTokenUsage } from './run-record-e7vj1uZQ.js';
+import { b as RunTokenUsage } from './run-record-CP2ObebC.js';
 
 /**
- * @experimental
- *
  * Pass A substrate types — `runCampaign` is the one primitive every
  * eval flow composes from. Three contracts in this file:
  *
@@ -20,14 +18,14 @@ import { b as RunTokenUsage } from './run-record-e7vj1uZQ.js';
  * can build dashboards / CI gates / regression diffs against a stable schema.
  */
 
-/** @experimental Stable identifier + kind tag for any scenario. Consumers
+/** Stable identifier + kind tag for any scenario. Consumers
  *  extend with their per-domain payload (persona, task, requirement, ...). */
 interface Scenario {
     id: string;
     kind: string;
     tags?: string[];
 }
-/** @experimental Context handed to every dispatch invocation. Scoped — every
+/** Context handed to every dispatch invocation. Scoped — every
  *  trace/span carries the cellId, every artifact write lands under the cell's
  *  artifact root, the cost meter accumulates per cell. */
 interface DispatchContext {
@@ -52,10 +50,10 @@ interface DispatchContext {
      */
     placement?: string;
 }
-/** @experimental One function: scenario + ctx → artifact. Dispatcher chooses
+/** One function: scenario + ctx → artifact. Dispatcher chooses
  *  whether to call `runMultishot`, `runLoop`, raw `streamPrompt`, anything. */
 type DispatchFn<TScenario extends Scenario, TArtifact> = (scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
-/** @experimental One session within a multi-session journey. Dispatch is
+/** One session within a multi-session journey. Dispatch is
  *  invoked once per session in order; state from prior session's artifact
  *  is exposed via `ctx.priorSessionArtifact`. */
 interface SessionScript<TScenario, TArtifact> {
@@ -74,7 +72,7 @@ interface JudgeDimension {
     /** Description shown in the judge's user prompt. */
     description: string;
 }
-/** @experimental Pluggable dimensional scorer. `score` is the contract:
+/** Pluggable dimensional scorer. `score` is the contract:
  *  given an artifact + scenario, return a `JudgeScore`. This is deliberately a
  *  function, not a fixed LLM-prompt shape — real consumers judge with
  *  ensembles, deterministic checks, or a single LLM call, and the substrate
@@ -118,7 +116,7 @@ interface JudgeScore {
     /** Ensemble extras: each surviving judge's per-dimension scores. */
     perJudge?: Record<string, Record<string, number>>;
 }
-/** @experimental A tier-4 code surface — a candidate change to the agent's
+/** A tier-4 code surface — a candidate change to the agent's
  *  IMPLEMENTATION, not its prompt. Produced by autoresearch (reads codebase +
  *  trace findings → opens a worktree). Measured by checking out `worktreeRef`
  *  and running the worker against the changed code. See the improvement-tier
@@ -133,7 +131,7 @@ interface CodeSurface {
     /** Human summary of what changed — rendered into the auto-PR body. */
     summary?: string;
 }
-/** @experimental The mutable surface a driver proposes. Tiers (see
+/** The mutable surface a proposer changes. Tiers (see
  *  `docs/design/loop-taxonomy.md`):
  *   - `string`      — tiers 1-2: system-prompt addendum / serialized tool
  *                     config. Cheap, reversible, text-diffable.
@@ -141,12 +139,12 @@ interface CodeSurface {
  *  Tier 3 (knowledge) is owned by agent-knowledge and rides its own adapter,
  *  not this type. */
 type MutableSurface = string | CodeSurface;
-/** @experimental A driver proposal carrying the surface AND the WHY behind
- *  it. Reflective drivers (`gepaDriver`) parse a `{label, rationale, payload}`
+/** A proposer output carrying the surface AND the WHY behind
+ *  it. Reflective proposers (`gepaProposer`) parse a `{label, rationale, payload}`
  *  from the model; without this wrapper the loop keeps only `payload` and the
  *  rationale that motivated the change is lost — the candidate becomes
  *  unattributable. `propose()` may return either bare `MutableSurface`s (cheap
- *  blind mutators) or these (reflective drivers); the loop normalizes both. */
+ *  blind mutators) or these (reflective proposers); the loop normalizes both. */
 interface ProposedCandidate {
     surface: MutableSurface;
     /** Short human label for the change (≤ 40 chars typical). */
@@ -156,16 +154,16 @@ interface ProposedCandidate {
      *  emitted provenance record. */
     rationale: string;
 }
-/** @experimental Type guard: a proposal carrying its rationale vs a bare
+/** Type guard: a proposal carrying its rationale vs a bare
  *  surface. The loop branches on this to populate `GenerationCandidate`. */
 declare function isProposedCandidate(value: MutableSurface | ProposedCandidate): value is ProposedCandidate;
-/** @experimental A non-dominated parent on the GEPA Pareto frontier — a
+/** A non-dominated parent on the GEPA Pareto frontier — a
  *  surface that, across the per-scenario objective vectors, no other tried
  *  surface beats on every scenario. A candidate worse on the mean composite
  *  but uniquely best on one hard scenario is non-dominated and survives here;
  *  the composite-best ranking would discard the lesson it carries. The loop
- *  computes the frontier across ALL generations and hands it to the driver so
- *  a reflective driver can combine complementary lessons (GEPA, Agrawal et
+ *  computes the frontier across ALL generations and hands it to the proposer so
+ *  a reflective proposer can combine complementary lessons (GEPA, Agrawal et
  *  al., arXiv:2507.19457). See `pareto.ts` (`paretoFrontier`). */
 interface ParetoParent {
     surface: MutableSurface;
@@ -181,10 +179,10 @@ interface ParetoParent {
     label?: string;
     rationale?: string;
 }
-/** @experimental Stateless surface mutation — given findings + current
+/** Stateless surface mutation — given findings + current
  *  surface, return N candidate surfaces. Pure transform, no generation
  *  awareness. Reflective-mutation and `AxGEPA` mutators conform. Wrapped by
- *  `evolutionaryDriver` to become an `ImprovementDriver`. */
+ *  `evolutionaryProposer` to become a `SurfaceProposer`. */
 interface Mutator<TFindings = unknown> {
     kind: string;
     mutate(args: {
@@ -194,12 +192,12 @@ interface Mutator<TFindings = unknown> {
         signal: AbortSignal;
     }): Promise<Array<MutableSurface | ProposedCandidate>>;
 }
-/** @experimental Everything a driver's `propose()` may read to plan the next
+/** Everything a proposer may read to plan the next
  *  batch of candidates. The first six fields are always present; the rest are
- *  optional context the loop supplies when available, so cheap drivers
- *  (`evolutionaryDriver`) can ignore them while a code-tier agentic generator
- *  consumes the research report + dataset to drive a coding harness.
- *  See `docs/design/self-improvement-engine.md`. */
+ *  optional context the loop supplies when available, so cheap proposers
+ *  (`evolutionaryProposer`) can ignore them while a code-tier agentic generator
+ *  consumes the report + dataset to drive a coding harness.
+ *  See `docs/campaign-proposers.md`. */
 interface ProposeContext<TFindings = unknown> {
     currentSurface: MutableSurface;
     history: GenerationRecord[];
@@ -208,11 +206,10 @@ interface ProposeContext<TFindings = unknown> {
     populationSize: number;
     generation: number;
     signal: AbortSignal;
-    /** The Phase-2 research report (analyst findings + diff), produced AFTER the
-     *  trace analysts run. Opaque to the substrate — the driver that consumes it
-     *  types it. See the phase diagram in self-improvement-engine.md. */
+    /** Optional analysis report produced before proposal. Opaque to the substrate:
+     *  the proposer that consumes it owns the shape. */
     report?: unknown;
-    /** Handle to all captured data — the driver samples traces / artifacts /
+    /** Handle to all captured data — the proposer samples traces / artifacts /
      *  rewards here to ground its proposals. */
     dataset?: LabeledScenarioStore;
     /** DEPTH: max iterations the agentic generator may take per candidate.
@@ -221,38 +218,38 @@ interface ProposeContext<TFindings = unknown> {
     maxImprovementShots?: number;
     /** GEPA Pareto frontier across ALL generations so far — the non-dominated
      *  surfaces by per-scenario objective vector. Empty/absent on generation 0
-     *  (only the baseline is scored). A reflective driver combines the
+     *  (only the baseline is scored). A reflective proposer combines the
      *  complementary lessons of these parents (each excels on different
-     *  scenarios) into a merged candidate. Drivers doing pure single-parent
+     *  scenarios) into a merged candidate. Proposers doing pure single-parent
      *  reflection may ignore it. See {@link ParetoParent}. */
     paretoParents?: ParetoParent[];
     /** FIREWALL (non-negotiable): the held-out judge is write-only — its verdicts
      *  score the chosen output and gate promotion, and are NEVER an input to
      *  proposal/steering (else the optimizer games the acceptance axis = an
      *  oracle). This `never`-typed field makes that a compile-time tripwire: a
-     *  driver that tries to thread judge verdicts into the proposal will not type.
+     *  proposer that tries to thread judge verdicts into the proposal will not type.
      *  Steering may consume TRACE-OBSERVABLE signals (what the agent did) via
      *  `findings`/`report`; it may NOT consume the judge's held-out verdict. */
     judgeScores?: never;
 }
-/** @experimental A surface-improvement strategy — the DRIVER of the
- *  improvement loop. Given the current best surface, the history of what's
- *  been tried + scored, and any external findings, propose the next batch of
- *  candidate surfaces to measure. Optionally decide to stop early.
+/** A surface-improvement strategy. Given the current best
+ *  surface, the history of what's been tried + scored, and any external
+ *  findings, propose the next batch of candidate surfaces to measure.
+ *  Optionally decide to stop early.
  *
- *  The evolutionary mutator (`evolutionaryDriver`, here) and agent-runtime's
- *  `improvementDriver` (with reflective / agentic generators) both conform —
- *  drivers of the SAME loop, not separate loops. The loop body
- *  (`runOptimization`) and the gated promotion shell (`runImprovementLoop`)
- *  are driver-agnostic. */
-interface ImprovementDriver<TFindings = unknown> {
+ *  The evolutionary mutator (`evolutionaryProposer`, here) and agent-runtime's
+ *  reflective / agentic generators both conform. They are proposers for the
+ *  SAME loop, not separate loops. The loop body (`runOptimization`) and the
+ *  gated promotion shell (`runImprovementLoop`) are proposer-agnostic.
+ */
+interface SurfaceProposer<TFindings = unknown> {
     kind: string;
-    /** Plan: propose N candidate surfaces for the next generation. A driver
+    /** Plan: propose N candidate surfaces for the next generation. A proposer
      *  may return bare `MutableSurface`s or `ProposedCandidate`s that carry the
      *  `{label, rationale}` motivating the change — the loop threads the
      *  rationale into `GenerationCandidate` and the emitted provenance. */
     propose(ctx: ProposeContext<TFindings>): Promise<Array<MutableSurface | ProposedCandidate>>;
-    /** Decide: stop early when the driver judges the search converged or
+    /** Decide: stop early when the proposer judges the search converged or
      *  exhausted. Default (omitted) runs all `maxGenerations`. */
     decide?(args: {
         history: GenerationRecord[];
@@ -261,13 +258,18 @@ interface ImprovementDriver<TFindings = unknown> {
         reason?: string;
     };
 }
-interface OptimizerConfig {
-    driver: ImprovementDriver;
+/** Optional vocabulary alias. The loop is the optimizer; this object is the
+ * proposer inside that loop. */
+type OptimizationProposer<TFindings = unknown> = SurfaceProposer<TFindings>;
+interface OptimizerConfigBase {
     populationSize: number;
     maxGenerations: number;
     surfaceExtractor: (profile: unknown) => MutableSurface;
 }
-/** @experimental Five-valued verdict taxonomy (MOSS-paper alignment). */
+interface OptimizerConfig extends OptimizerConfigBase {
+    proposer: SurfaceProposer;
+}
+/** Five-valued verdict taxonomy (MOSS-paper alignment). */
 type GateDecision = 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
 interface GateContext<TArtifact, TScenario extends Scenario> {
     candidateArtifacts: Map<string, TArtifact>;
@@ -296,12 +298,12 @@ interface GateResult {
     }>;
     delta?: number;
 }
-/** @experimental Composable promotion gate. */
+/** Composable promotion gate. */
 interface Gate<TArtifact = unknown, TScenario extends Scenario = Scenario> {
     name: string;
     decide(ctx: GateContext<TArtifact, TScenario>): Promise<GateResult>;
 }
-/** @experimental Scoped trace writer handed to each dispatch — every span
+/** Scoped trace writer handed to each dispatch — every span
  *  auto-tagged with the cellId so traces filter cleanly. */
 interface CampaignTraceWriter {
     span(name: string, attributes?: Record<string, unknown>): TraceSpan;
@@ -311,7 +313,7 @@ interface TraceSpan {
     end(attributes?: Record<string, unknown>): void;
     setAttribute(key: string, value: unknown): void;
 }
-/** @experimental Scoped artifact writer — `write(path, content)` lands under
+/** Scoped artifact writer — `write(path, content)` lands under
  *  `<runDir>/<cellId>/<path>`. */
 interface CampaignArtifactWriter {
     write(path: string, content: string | Uint8Array): Promise<string>;
@@ -322,7 +324,7 @@ interface CampaignArtifactWriter {
  *  backend-integrity guard with ONE source of truth — a field added to
  *  `RunTokenUsage` is a compile error here, not a silent drift. */
 type CampaignTokenUsage = RunTokenUsage;
-/** @experimental Cell-scoped cost meter. NOTHING is captured automatically —
+/** Cell-scoped cost meter. NOTHING is captured automatically —
  *  the substrate does not intercept the LLM call, so it cannot see cost or
  *  tokens unless the dispatch reports them. Every LLM cost MUST be reported via
  *  `observe` and every token count via `observeTokens`; a dispatch that reports
@@ -341,7 +343,7 @@ interface CampaignCostMeter {
     /** Accumulated token usage for this cell (zeros if never observed). */
     tokens(): CampaignTokenUsage;
 }
-/** @experimental Source tag — required on every store write. Used by the
+/** Source tag — required on every store write. Used by the
  *  default training-source filter (production-trace samples NOT used as
  *  training scenarios unless explicitly opted in). */
 type LabeledScenarioSource = 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
@@ -363,7 +365,7 @@ type RedactionStatus = 'raw' | 'redacted-pii' | 'redacted-secrets' | 'fully-reda
 type LabelTrust = 'unverified' | 'verified-signal' | 'human-rated';
 /** Ordinal rank for a label-trust tier; absent ⇒ `unverified` (rank 0). */
 declare function labelTrustRank(trust: LabelTrust | undefined): number;
-/** @experimental Required-provenance write. The store rejects writes that
+/** Required-provenance write. The store rejects writes that
  *  lack provenance — a default-on flywheel without provenance is the
  *  data-poisoning vector flagged in the alignment review. */
 interface LabeledScenarioWrite<TScenario extends Scenario = Scenario, TArtifact = unknown> {
@@ -455,7 +457,7 @@ interface GenerationRecord {
     promoted: string[];
 }
 /** One scored candidate surface in a generation. `dimensions` + `scenarios`
- *  let a reflective `ImprovementDriver` ground its next proposal on WHICH
+ *  let a reflective proposer ground its next proposal on WHICH
  *  dimensions the candidate is weakest on and WHICH scenarios it best/worst
  *  handled — the evidence a blind `Mutator` cannot see. */
 interface GenerationCandidate {
@@ -467,7 +469,7 @@ interface GenerationCandidate {
     dimensions: Record<string, number>;
     /** Per-scenario composite (mean over reps + judges), plus the judge's
      *  free-form `notes` for that scenario — the "why it scored low" evidence a
-     *  reflective driver grounds its next edit on. Keep `notes` GENERALIZABLE
+     *  reflective proposer grounds its next edit on. Keep `notes` GENERALIZABLE
      *  (which checks/lines/dimensions failed and how), NOT case-specific ground
      *  truth: leaking expected answers into the prompt is memorization, and the
      *  held-out gate would reject it anyway. */
@@ -476,12 +478,12 @@ interface GenerationCandidate {
         composite: number;
         notes?: string;
     }>;
-    /** Driver-supplied short label for the change. Present when the driver
+    /** Proposer-supplied short label for the change. Present when the proposer
      *  returned a `ProposedCandidate`; absent for bare-surface mutators. */
     label?: string;
-    /** Driver-supplied rationale — WHY this candidate was proposed. The
+    /** Proposer-supplied rationale — WHY this candidate was proposed. The
      *  "because rationale Z" the audit requires to survive to the result.
-     *  Present when the driver returned a `ProposedCandidate`. */
+     *  Present when the proposer returned a `ProposedCandidate`. */
     rationale?: string;
 }
 interface CampaignAggregates {
@@ -517,4 +519,4 @@ interface CampaignResult<TArtifact = unknown, TScenario extends Scenario = Scena
     scenarios: Array<Pick<TScenario, 'id' | 'kind'>>;
 }
 
-export { isProposedCandidate as A, labelTrustRank as B, type CampaignAggregates as C, type DispatchFn as D, type Gate as G, type ImprovementDriver as I, type JudgeScore as J, type LabeledScenarioStore as L, type MutableSurface as M, type OptimizerConfig as O, type ParetoParent as P, type RedactionStatus as R, type Scenario as S, type TraceSpan as T, type JudgeConfig as a, type DispatchContext as b, type GateDecision as c, type CampaignArtifactWriter as d, type CampaignCellResult as e, type CampaignCostMeter as f, type CampaignResult as g, type CampaignTraceWriter as h, type CodeSurface as i, type GateContext as j, type GateResult as k, type GenerationCandidate as l, type GenerationRecord as m, type JudgeDimension as n, type Mutator as o, type SessionScript as p, type ProposeContext as q, type LabeledScenarioWrite as r, type LabeledScenarioSampleArgs as s, type LabeledScenarioRecord as t, type LabelTrust as u, type LabeledScenarioSource as v, type CampaignTokenUsage as w, type JudgeAggregate as x, type ProposedCandidate as y, type ScenarioAggregate as z };
+export { type JudgeAggregate as A, type ScenarioAggregate as B, type CampaignResult as C, type DispatchFn as D, isProposedCandidate as E, labelTrustRank as F, type Gate as G, type JudgeScore as J, type LabeledScenarioStore as L, type MutableSurface as M, type OptimizationProposer as O, type ParetoParent as P, type RedactionStatus as R, type Scenario as S, type TraceSpan as T, type JudgeConfig as a, type DispatchContext as b, type SurfaceProposer as c, type GateDecision as d, type CampaignAggregates as e, type CampaignArtifactWriter as f, type CampaignCellResult as g, type CampaignCostMeter as h, type CampaignTraceWriter as i, type CodeSurface as j, type GateContext as k, type GateResult as l, type GenerationCandidate as m, type GenerationRecord as n, type JudgeDimension as o, type Mutator as p, type OptimizerConfig as q, type SessionScript as r, type LabeledScenarioWrite as s, type LabeledScenarioSampleArgs as t, type LabeledScenarioRecord as u, type LabelTrust as v, type ProposedCandidate as w, type ProposeContext as x, type LabeledScenarioSource as y, type CampaignTokenUsage as z };

package/dist/workflow/index.d.ts

@@ -1,7 +1,7 @@
 import { W as WorkflowTopology } from '../harness-optimizer-mOl9XX_O.js';
-import { a as RunSplitTag, b as RunTokenUsage, R as RunRecord } from '../run-record-e7vj1uZQ.js';
-import { c as AnalystFinding, h as AnalystSeverity, E as EvidenceRef } from '../types-Ce17tDlG.js';
-import { F as FailureClusterInsight } from '../insight-report-DWl3z9tl.js';
+import { a as RunSplitTag, b as RunTokenUsage, R as RunRecord } from '../run-record-CP2ObebC.js';
+import { c as AnalystFinding, h as AnalystSeverity, E as EvidenceRef } from '../types-B5x54y6n.js';
+import { F as FailureClusterInsight } from '../insight-report-BnRjTibG.js';
 import { a as VerificationReport, L as LayerResult } from '../multi-layer-verifier-DUZXrPDA.js';
 import { F as FailureClusterReport } from '../failure-cluster-DH9Flgcf.js';
 import { R as RedactionRule, a as RedactionReport } from '../redact-B40YG2M_.js';
@@ -12,13 +12,14 @@ import '../pareto-E-pembql.js';
 import '../run-critic-CmMf05uV.js';
 import '../schema-m0gsnbt3.js';
 import '../store-BcFXE6LG.js';
+import '@tangle-network/agent-interface';
 import '../errors-CzMUYo7b.js';
 import '../store-C1YxJDEK.js';
 import '../types-C7DGg5ex.js';
 import '@tangle-network/tcloud';
 import '../llm-client-Bj7g0rqu.js';
 import '../raw-provider-sink-C46HDghv.js';
-import '../summary-report-BDOFevaT.js';
+import '../summary-report-CInXwsza.js';
 import '../judge-calibration-0p2QcWNE.js';
 import '../verdict-C9MlYujm.js';
 import '../control-runtime-Acf9CGhw.js';

package/dist/workflow/index.js

@@ -7,7 +7,7 @@ import {
 } from "../chunk-GGE4NNQT.js";
 import {
   validateRunRecord
-} from "../chunk-KWRRMR3J.js";
+} from "../chunk-LO6IOIJ2.js";
 import "../chunk-VSMTAMNK.js";
 import {
   ValidationError

package/docs/campaign-proposers.md

@@ -0,0 +1,170 @@
+# Campaign Proposers, ELI5
+
+A campaign proposer is the part of an improvement loop that says: "try this
+candidate next."
+
+It does not run your agent. It does not score anything. It only proposes a new
+surface to measure. A surface is the thing you are changing: a prompt string, a
+serialized config string, or a code/worktree surface.
+
+Use **proposer** for this role. Older optimizer APIs used "driver"; that word is
+now reserved for execution, sandbox, and router agents that actually drive
+workers.
+
+## The Loop
+
+```text
+current surface
+  -> proposer suggests candidate surfaces
+  -> runCampaign runs each candidate on scenarios
+  -> judges score the artifacts
+  -> runOptimization picks the best candidate
+  -> runImprovementLoop re-scores on holdout and gates release
+```
+
+## Proposer Input
+
+Every `SurfaceProposer.propose(ctx)` receives:
+
+| Field | Plain meaning |
+|---|---|
+| `currentSurface` | The prompt/config/code surface currently being improved. |
+| `history` | What candidates were tried before and how they scored. |
+| `findings` | Failure analysis or analyst findings from traces/eval runs. |
+| `populationSize` | How many candidates the loop asks for this generation. |
+| `generation` | Which generation number this is. |
+| `signal` | Abort signal for cancellation. |
+| `report` | Optional larger analysis report. |
+| `dataset` | Optional labeled scenario store. |
+| `paretoParents` | Optional non-dominated surfaces from prior generations. |
+
+## Proposer Output
+
+A proposer returns candidates:
+
+```ts
+{
+  surface: 'the full new prompt or config',
+  label: 'short name',
+  rationale: 'why this change should help'
+}
+```
+
+Bare surfaces are still accepted, but `label` and `rationale` make results
+auditable, so new proposers should return `ProposedCandidate`.
+
+## Which Proposer To Use
+
+| Proposer factory | Best when | Output surface |
+|---|---|---|
+| `gepaProposer` | You want a strong prompt rewrite driven by prior scores and findings. | prompt string |
+| `skillOptProposer` | You are editing a structured skill/runbook and want anchored small patches. | prompt/skill string |
+| `aceProposer` | You want append-only lessons from findings, preserving every distinct lesson. | prompt/playbook string |
+| `memoryCurationProposer` | You want compact deduped lessons from findings. | prompt/playbook string |
+| `parameterSweepProposer` | You want FAPO-style config/parameter edits from a JSON config surface. | JSON string |
+| `fapoProposer` | You want the FAPO policy: prompt first, then parameter, then structural only when evidence supports escalation. | whatever its level proposer returns |
+
+## FAPO Proposer
+
+FAPO is not "another prompt mutator." The paper describes a reviewed escalation
+policy:
+
+1. evaluate the current workflow,
+2. attribute failures to prompt, parameter/config, or structure,
+3. propose one scoped change,
+4. review the change for scope/leakage/compatibility,
+5. measure it,
+6. keep moving or escalate only when the cheaper level is exhausted.
+
+The simplest useful setup is prompt plus JSON config. Structural/code edits are
+optional and should be injected by the app or runtime layer.
+
+```ts
+import {
+  fapoProposer,
+  gepaProposer,
+  parameterSweepProposer,
+  runImprovementLoop,
+} from '@tangle-network/agent-eval/campaign'
+
+const proposer = fapoProposer({
+  scope: { allowedLevels: ['prompt', 'parameter'] },
+  promptProposer: gepaProposer({ llm, model, target: 'agent prompt' }),
+  parameterProposer: parameterSweepProposer({
+    candidates: [
+      {
+        label: 'raise-retrieval-k',
+        rationale: 'retrieval misses indicate the search budget may be too low',
+        changes: [{ path: 'retrieval.k', value: 10 }],
+      },
+    ],
+  }),
+})
+
+await runImprovementLoop({
+  scenarios: trainScenarios,
+  holdoutScenarios,
+  baselineSurface: JSON.stringify(currentConfig),
+  dispatchWithSurface,
+  judges,
+  proposer,
+  gate,
+  autoOnPromote: 'none',
+  runDir,
+  populationSize: 1,
+  maxGenerations: 10,
+})
+```
+
+If you do have a real code/worktree proposer, pass it as `structuralProposer`.
+`agent-eval` intentionally does not provide that proposer because this package
+measures candidates; the runtime or app owns code generation.
+
+For side-by-side experiments with existing proposers, use the compare entry:
+
+```ts
+import {
+  compareProposers,
+  fapoEscalationEntry,
+  gepaParetoEntry,
+} from '@tangle-network/agent-eval/campaign'
+
+await compareProposers({
+  proposers: [
+    gepaParetoEntry(config),
+    fapoEscalationEntry({
+      ...config,
+      parameterCandidates: [
+        {
+          label: 'raise-retrieval-k',
+          rationale: 'retrieval misses indicate the search budget may be too low',
+          changes: [{ path: 'retrieval.k', value: 10 }],
+        },
+      ],
+    }),
+  ],
+  baselineSurface,
+  holdoutScenarios,
+  dispatchWithSurface,
+  judges,
+  runDir,
+})
+```
+
+## Common Mistakes
+
+- Do not put eval logic inside a proposer. Put it in `dispatch` and `judges`.
+- Do not let a proposer read held-out judge scores. `ProposeContext` makes this
+  a type-level firewall.
+- Do not call FAPO a prompt-only optimizer. Its main value is evidence-based
+  escalation beyond prompt edits.
+- Do not put Claude Code or sandbox-specific code in `agent-eval`. Structural
+  code generation should be supplied as an injected `SurfaceProposer` from the
+  runtime/app layer.
+
+## Simpler Mental Model
+
+Use this sentence when wiring a loop:
+
+> The proposer chooses candidates; the campaign measures them; the gate decides
+> whether the measured winner is safe to promote.

package/docs/concepts.md

@@ -9,17 +9,21 @@ connected, or the answer lacks required sources. The package gives products a
 shared way to record runs, check outcomes, classify failures, compare variants,
 and make release decisions.
 
-## The three top-level functions
+## The top-level functions
 
-Everything funnels through `/contract`. Three entries, one shape coming back:
+Everything funnels through `/contract`. Start with `defineAgentEval()` when you
+can; drop to the raw functions when you need lower-level control.
 
 | Function | When to call it | What you give it | What you get back |
 |---|---|---|---|
+| **`defineAgentEval()`** | You have scenarios, an agent, a judge, and a baseline surface, and you want one object you can score or improve. | scenarios, agent, judge, baseline surface | `{ evaluate(), improve() }` where `evaluate()` returns a campaign result and `improve()` returns a decision packet |
 | **`selfImprove()`** | You have a closed loop — scenarios, judge, agent in hand, and you want the substrate to propose better candidates + gate them. | scenarios, agent, judge, baseline surface | `SelfImproveResult.insight: InsightReport` + ship/hold verdict + winner surface |
 | **`analyzeRuns()`** | You have observed runs (production traces, an approve/reject corpus, a CSV gold set) and want the same rigor packet without invoking an agent. | `RunRecord[]` + optional flags | `InsightReport` |
 | **Intake adapters** (`fromFeedbackTable`, `fromOtelSpans`) | Your data isn't already in `RunRecord` shape — it's in Obsidian, Sheets, an OTel collector, etc. | source-specific input | `RunRecord[]` ready to pipe into `analyzeRuns()` |
 
-The three customer maturity stages — logs only → ratings → closed loop — map exactly to the three functions. See [`customer-journeys.md`](./customer-journeys.md) for the runnable walkthroughs.
+The customer maturity stages — logs only → ratings → closed loop — map to these
+entry points. See [`customer-journeys.md`](./customer-journeys.md) for the
+runnable walkthroughs.
 
 The shape of the answer — `InsightReport` — is identical across all three paths. Distributional summary, paired-bootstrap lift CI, judge stats, inter-rater agreement, cost-quality Pareto, failure clusters, contamination check, outcome correlation, release axes, and a ranked recommendations array. Walked through section-by-section in [`insight-report.md`](./insight-report.md).
 
@@ -182,7 +186,7 @@ release decision.
 
 ## Where to go next
 
-- **Confused by "GEPA / HALO / trace analysis / drivers everywhere"?** → [self-improvement-map.md](./self-improvement-map.md) — one loop, four roles, the seven-driver catalog (production vs bench-only), and why `gepa-refine` is the same loop on a test bench.
+- **Confused by "GEPA / HALO / trace analysis / proposers everywhere"?** → [self-improvement-map.md](./self-improvement-map.md) — one loop, four roles, the proposer catalog (production vs bench-only), and why `gepa-refine` is the same loop on a test bench.
 - **Which `run*` primitive do I use, and how do I grade produced state?** → [eval-surface-map.md](./eval-surface-map.md) — the campaign/matrix/optimization/gate primitives as a pick-by-"use-when" table, plus the produced-state grading composition (verifyCompletion-as-judge — there is no persona-dispatch wrapper) and the in-band body contract.
 - **Need the layman feature map?** → [feature-guide.md](./feature-guide.md) — what each primitive does, when to use it, integration patterns, and guardrails.
 - **Just want to score a string against a rubric?** → [wire-protocol.md](./wire-protocol.md) — HTTP/RPC interface, pluggable from any language.

package/docs/customer-journeys.md

@@ -58,7 +58,7 @@ Cost mean:         $0.103 (p95: $0.131)
 
 1. Wire an `AnalystRegistry` to cluster the 6 failures by root cause via LLM analysis.
 2. Add `outcomeSignal` once they have downstream conversion / engagement / post-engagement data, and the report fits a reward model showing whether their score predicts the customer outcome.
-3. Once they identify a step worth optimizing (translation, say), graduate to journey #3 — wrap that step in a `Dispatch` and call `selfImprove()`.
+3. Once they identify a step worth optimizing (translation, say), graduate to journey #3 — wrap that step as an `agent(surface, scenario)` and call `defineAgentEval()`.
 
 **Runnable:** [`examples/customer-otel-traces/`](../examples/customer-otel-traces/)
 
@@ -130,7 +130,7 @@ Mean κ:               0.43
 1. **Triage meeting on the disagreement cases.** Mean κ=0.43 means the rubric is ambiguous; clarify it on the cases that split.
 2. **Calibrate one LLM judge per reviewer.** Each reviewer's history is the gold signal — substrate primitive `calibrateJudge` against `raterScores` filtered to that reviewer.
 3. **Add engagement as `outcomeSignal`** once the content downstream is instrumented. The `outcomeCorrelation` section tells the team whether their taste predicts the founder's token-max goal — and if not, the linear reward model says how to retarget.
-4. **Graduate to journey #3** — wrap the research-generation Claude-P call as a `Dispatch`, use the calibrated judges, run `selfImprove()` nightly. Open a PR against the GitHub Action when the holdout approval rate beats baseline.
+4. **Graduate to journey #3** — wrap the research-generation Claude-P call as an `agent(surface, scenario)`, use the calibrated judges, run `evalKit.improve()` nightly. Open a PR against the GitHub Action when the holdout approval rate beats baseline.
 
 **Runnable:** [`examples/customer-feedback-loop/`](../examples/customer-feedback-loop/)
 
@@ -142,14 +142,14 @@ Mean κ:               0.43
 
 **The frustration:** "We can run an A/B by hand but we don't know if the improvement is real. We don't have time to run paired bootstrap by hand. We want a function that decides."
 
-**What they need from agent-eval:** the closed loop in one function — propose, score, gate, ship — with the full rigor packet on the way out.
+**What they need from agent-eval:** one reusable eval definition — propose, score, gate, ship — with the full rigor packet on the way out.
 
 ### The code
 
 ```ts
-import { selfImprove } from '@tangle-network/agent-eval/contract'
+import { defineAgentEval } from '@tangle-network/agent-eval/contract'
 
-const result = await selfImprove({
+const evalKit = defineAgentEval({
   scenarios,
   agent: async (surface, scenario) =>
     await myAgent.run({ systemPrompt: (surface as { systemPrompt: string }).systemPrompt, scenario }),
@@ -162,6 +162,8 @@ const result = await selfImprove({
   budget: { generations: 3, populationSize: 2 },
 })
 
+const result = await evalKit.improve()
+
 result.gateDecision   // 'ship' | 'hold' | ...
 result.insight        // full decision packet
 ```
@@ -172,18 +174,18 @@ result.insight        // full decision packet
 ═══ selfImprove() decision packet ═══
 
 Gate decision:        ship
-Raw lift:             +0.194
+Raw lift:             +0.361
 
 ── Statistical lift (paired bootstrap) ──
-delta:    +0.254
-CI95:     [0.254, 0.254]
-pValue:   1.0000
-Cohen's d: 0.00
-MDE @ 80% power: 2.802
-required n at observed effect: 244
+delta:    +0.359
+CI95:     [0.311, 0.408]
+pValue:   0.0013
+Cohen's d: 8.58
+MDE @ 80% power: 1.401
+required n at observed effect: 122
 
 ── Recommendations ──
-[critical] ship — Ship — lift 0.254 (95% CI 0.254..0.254)
+[critical] ship — Ship — lift 0.359 (95% CI 0.311..0.408)
 ```
 
 ### Next steps for this customer