@tangle-network/agent-eval 0.93.0 → 0.95.0

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

package/docs/design/loop-taxonomy.md

@@ -1,21 +1,22 @@
-# Loop taxonomy: driver, worker, measurement, and the improvement loop
+# Loop taxonomy: execution driver, worker, measurement, and surface proposer
 
 This is the canonical vocabulary for the Tangle agent stack. It exists because
 the same word ("loop", "shot", "worker") was being used at three different
 layers, and the layers were getting conflated. Every role below has exactly
 one meaning. Use these words and nothing else.
 
-Cross-links: [`three-package-architecture.md`](../three-package-architecture.md)
-(who owns what), [`concepts.md`](../concepts.md) (eval mental model),
-[`multi-shot-optimization.md`](../multi-shot-optimization.md) (GEPA),
+Cross-links: [`concepts.md`](../concepts.md) (eval mental model),
+[`campaign-proposers.md`](../campaign-proposers.md) (proposer catalog),
+[`multi-shot-optimization.md`](../multi-shot-optimization.md) (GEPA), and
 [`auto-research-loop-end-to-end.md`](../auto-research-loop-end-to-end.md)
 (analyst / autoresearch).
 
-## The three roles
+## Core Roles
 
 | Role | Definition | Lives at |
 |---|---|---|
-| **Driver** | The thing that *decides what happens next*. Plans, then decides whether to continue. | Both layers (see below) |
+| **Execution driver** | The thing that decides or routes the next turn/action inside a sandbox or worker conversation. | Inner layer only |
+| **Surface proposer** | The thing that proposes the next prompt/config/code surface for the improvement loop to measure. | Outer layer only |
 | **Worker** | An agent harness instance (Claude Code, Codex, OpenCode, …) running inside a sandbox. Does the actual work; responds in chat. | Inner layer only |
 | **Sandbox** | A multi-harness VM. Hosts **1..N workers**, which can share a workspace. Not an agent — the substrate an agent runs in. | Inner layer only |
 | **Measurement** | Runs the worker over a set of scenarios and judges the outputs into a scorecard with confidence intervals. This is `runCampaign`. | Outer layer |
@@ -28,12 +29,9 @@ Two facts that trip people up:
    `{ sibling, sandboxId }` = co-located workers; `{ fleet, fleetId,
    machineId, sandboxId }` = workers across machines.
 
-2. **"Driver" exists at two layers and means the same *kind* of thing
-   (a decider) at each, but the things it decides differ:**
-   - **Conversation driver** (inner): decides the next *turn* — a persona/user
-     simulating chat, or a planner fanning work to workers.
-   - **Improvement driver** (outer): decides the next *surface* — what system
-     prompt / tool config / code the workers should run.
+2. **"Driver" is reserved for execution.** The outer loop uses a
+   **surface proposer**: it proposes the next prompt / tool config / code
+   surface for the measurement loop.
 
 ## The nesting
 
@@ -42,7 +40,7 @@ There are two loops. The outer one improves the thing the inner one runs.
 ```
 runImprovementLoop                         OUTER loop — improve the agent over time
 │
-├─ DRIVER = ImprovementDriver              proposes a candidate SURFACE
+├─ PROPOSER = SurfaceProposer              proposes a candidate SURFACE
 │           (evolutionary mutator |        (the worker's system prompt / tools / config)
 │            reflective analyst)            — NOT a conversation turn
 │
@@ -84,7 +82,7 @@ opinion about execution topology: the topology lives inside `dispatch`.
 - The worker is the agent in the sandbox. The driver talks to it. ✓
 - `runCampaign` is a **measurement**, not a worker. It *runs the worker* (via
   `dispatch`); the worker does not "run the eval".
-- The outer improvement loop has **no single worker** — its driver proposes a
+- The outer improvement loop has **no single worker** — its proposer proposes a
   *surface*, and each surface is scored by a *measurement* that drives the
   inner workers.
 
@@ -108,7 +106,7 @@ identical in shape:
 
 That captured corpus **is the GEPA training set.** A basic eval run, a
 production conversation, and an autoresearch loop all deposit the same
-`(input, output, reward)` tuples. The optimization driver later samples from
+`(input, output, reward)` tuples. The optimization proposer later samples from
 that corpus to evolve the surface. So:
 
 > Running *any* loop — even one whose purpose is not optimization — builds the
@@ -116,7 +114,7 @@ that corpus to evolve the surface. So:
 > currently optimizing.
 
 This is enforced, not aspirational: `runImprovementLoop` **refuses**
-`tracing: 'off'` whenever a driver is wired, precisely because a loop that
+`tracing: 'off'` whenever a proposer is wired, precisely because a loop that
 doesn't feed the dataset is a loop that breaks the flywheel.
 
 Temporal-split discipline (train vs holdout, `capturedBefore`) and
@@ -124,16 +122,15 @@ default-off-for-training of `production-trace` are enforced at the
 `LabeledScenarioStore.sample()` boundary so the flywheel cannot contaminate
 the holdout it is judged against. See `src/campaign/labeled-store/`.
 
-## One improvement loop, pluggable drivers
+## One improvement loop, pluggable proposers
 
-The improvement loop is **driver-agnostic**. `runOptimization` (the loop body)
+The improvement loop is **proposer-agnostic**. `runOptimization` (the loop body)
 and `runImprovementLoop` (the gated-promotion shell) call
-`driver.propose(...)` → measure → `driver.decide(...)`. They do not know which
-strategy is driving. Two strategies conform to the same `ImprovementDriver`
-interface:
+`proposer.propose(...)` → measure → `proposer.decide(...)`. They do not know
+which strategy proposed the candidate. The API interface is `SurfaceProposer`:
 
 ```ts
-interface ImprovementDriver<TFindings = unknown> {
+interface SurfaceProposer<TFindings = unknown> {
   kind: string
   propose(args: {
     currentSurface: MutableSurface
@@ -149,28 +146,27 @@ interface ImprovementDriver<TFindings = unknown> {
 
 | Implementation | Strategy | How it proposes | Where it lives |
 |---|---|---|---|
-| `evolutionaryDriver` | Evolutionary (GEPA / AxGEPA) | Standalone `ImprovementDriver`. Mutates the current best surface into N candidates, blind to history beyond the current best. Optimizes against the dataset's rewards. | **agent-eval** (pure: dataset → surface, no sandbox) |
-| `improvementDriver` + `reflectiveGenerator` | Reflective | One driver, cheap generator: drafts patches from the report and applies them into a worktree (shots=1, no sandbox). | **agent-runtime** — implements agent-eval's `ImprovementDriver` |
-| `improvementDriver` + `agenticGenerator` | Agentic | Same driver, full generator: runs a coding harness in the worktree (≤ `maxImprovementShots`) to edit in place. | **agent-runtime** |
+| `evolutionaryProposer` | Evolutionary (GEPA / AxGEPA) | Standalone `SurfaceProposer`. Mutates the current best surface into N candidates, blind to history beyond the current best. Optimizes against the dataset's rewards. | **agent-eval** (pure: dataset → surface, no sandbox) |
+| Runtime reflective proposer | Reflective | Cheap generator: drafts patches from the report and applies them into a worktree (shots=1, no sandbox). | **agent-runtime** — implements agent-eval's proposer contract |
+| Runtime agentic proposer | Agentic | Full generator: runs a coding harness in the worktree (≤ `maxImprovementShots`) to edit in place. | **agent-runtime** |
 
 This resolves the prior duplication where `runImprovementLoop` (evolutionary,
 agent-eval) and `runAnalystLoop` (reflective, agent-runtime) were two parallel
 loops doing "propose change → measure → gate → PR". There is **one loop** and
-**one driver** (`improvementDriver`); the reflective and agentic paths are
-pluggable *generators* of it (the same operation at two settings of a cost
-dial), not separate drivers. The dependency direction permits this cleanly:
-agent-eval is the leaf and owns the `ImprovementDriver` contract; agent-runtime
+one proposer contract. The reflective and agentic paths are two settings of the
+same cost dial, not separate outer loops. The dependency direction permits this
+cleanly: agent-eval is the leaf and owns the proposer contract; agent-runtime
 imports agent-eval and implements it.
 
 ## What "the surface" is — improvement tiers
 
-`MutableSurface` is the thing the driver changes. It has tiers, least → most
+`MutableSurface` is the thing the proposer changes. It has tiers, least → most
 invasive. `MutableSurface = string | CodeSurface` spans all of them: `string`
 for tiers 1–2, `CodeSurface{ worktreeRef }` for tier 4.
 
 | Tier | Surface | Generator that changes it | Blast radius |
 |---|---|---|---|
-| 1 | System prompt / prompt-signature addendum | `evolutionaryDriver` (GEPA), `reflectiveGenerator` | prompt only |
+| 1 | System prompt / prompt-signature addendum | `evolutionaryProposer` (GEPA), `reflectiveGenerator` | prompt only |
 | 2 | Tool config / tool signatures | `reflectiveGenerator` | which tools, their schemas |
 | 3 | Knowledge (wiki / knowledge graph) | agent-knowledge's knowledge adapter | what the agent *knows* |
 | 4 | Code / scaffolding | `agenticGenerator` (coding harness reads codebase + report) → worktree / PR | the implementation itself |
@@ -185,38 +181,10 @@ The cost/capability distinction:
   `maxImprovementShots` — measured by re-running the inner loop against the
   changed code.
 
-Both are generators of the one `improvementDriver` (propose → measure → gate →
-PR). They differ only in *what* they edit and *how invasive* it is — and both
+Both are implementations of the one proposer contract (propose → measure → gate
+→ PR). They differ only in *what* they edit and *how invasive* it is — and both
 consume the **same dataset** the flywheel builds.
 
-## Resolved design decisions
-
-1. **`MutableSurface` widens to span all tiers.** `MutableSurface = string |
-   CodeSurface`. The `string` form is tiers 1–2 (prompt / serialized tool
-   config); `CodeSurface = { kind: 'code'; worktreeRef; baseRef?; summary? }`
-   is tier 4 (an implementation change behind a worktree ref). One loop spans
-   prompt *and* code improvement. `surfaceHash` hashes a string by content and
-   a code surface by its `(worktreeRef, baseRef)` identity (the content lives
-   in git). **Shipped in agent-eval 0.40.1.** The consumer's
-   `dispatchWithSurface` is responsible for checking out a code surface's
-   worktree before running the worker.
-
-2. **`runAnalystLoop` (agent-runtime): the analyst is a GENERATOR, knowledge
-   stays separate.** Shipped in agent-runtime 0.25.0 as `improvementDriver` +
-   `reflectiveGenerator` (drafts patches from the report) / `agenticGenerator`
-   (coding harness in the worktree) — one driver, pluggable generators, fed
-   into `runImprovementLoop`'s gate + PR machinery. `runAnalystLoop`'s other
-   responsibilities — the findings ledger and knowledge-graph updates, which
-   are *not* surface optimization — stay where they are.
-
-3. **`runLoop` + `runMultishot` converge into one parameterized
-   `runConversationLoop`** with a pluggable backend (`sandbox | router`). The
-   two are the same shape (driver ↔ workers, iterate) differing only in
-   backend and intent; unify them. **Phase 3+ (cross-repo); needs its own
-   design pass — introduces a backend abstraction and couples the two repos'
-   inner loops, so it lands after the `ImprovementDriver` model is proven in
-   product use.**
-
 ## Vocabulary quick reference
 
 - **shot** — one conversational turn (driver says X, worker responds Y). Used
@@ -227,15 +195,15 @@ consume the **same dataset** the flywheel builds.
   agent-runtime.
 - **runCampaign** — a measurement: a surface scored over N scenarios × M reps.
   agent-eval. (A "campaign" = a coordinated batch of measurements.)
-- **runOptimization** — the improvement loop body: driver proposes surfaces,
+- **runOptimization** — the improvement loop body: proposer suggests surfaces,
   each measured by a campaign, top-K promoted per generation. agent-eval.
 - **runImprovementLoop** — `runOptimization` + holdout re-score + release gate
   + optional PR. agent-eval.
 - **runAnalystLoop** — reflective autoresearch: findings + knowledge updates +
   improvement proposals. agent-runtime.
-- **ImprovementDriver** — the contract a surface-proposer implements.
-  `evolutionaryDriver` (agent-eval) is one; agent-runtime's `improvementDriver`
-  is another, with pluggable `reflectiveGenerator` / `agenticGenerator`.
-- **CandidateGenerator** — the byte-producing seam inside `improvementDriver`;
+- **SurfaceProposer** — the contract a surface proposer implements.
+  `evolutionaryProposer` (agent-eval) is one; agent-runtime can provide
+  reflective or agentic implementations.
+- **CandidateGenerator** — the byte-producing seam inside a runtime proposer;
   `reflectiveGenerator` (cheap, no sandbox) and `agenticGenerator` (coding
   harness in the worktree) are the two cost settings. agent-runtime.

package/docs/distributed-driver.md

@@ -1,7 +1,7 @@
-# Distributed driver — driver-on-A, workers-on-B (and C, D, E…)
+# Distributed campaign execution — coordinator-on-A, workers-on-B
 
-The driver (running `runCampaign` / `runImprovementLoop` / `gepaDriver`)
-and the worker (running your actual agent) **do not have to live in the
+The coordinator process (running `runCampaign` / `runImprovementLoop` /
+`gepaProposer`) and the worker (running your actual agent) **do not have to live in the
 same process, machine, region, or cloud.** `Dispatch` is just a
 function: scenario in, artifact out. Whatever returns the artifact is
 the worker — local, remote, sandboxed, or fanned out across a fleet.
@@ -10,11 +10,11 @@ the worker — local, remote, sandboxed, or fanned out across a fleet.
 
 | Pattern | Reason |
 |---|---|
-| **Driver on your VPC, workers on our sandbox fleet** | Driver holds secrets, training data, prompt corpus; workers stay stateless and scale horizontally |
+| **Coordinator on your VPC, workers on our sandbox fleet** | Coordinator holds secrets, training data, prompt corpus; workers stay stateless and scale horizontally |
 | **Multi-region campaigns** | Each cell runs in the region closest to its target API (latency, compliance, data residency) |
-| **Driver-as-a-service** | Long-running optimization process; reuses across many short-lived worker invocations |
+| **Coordinator-as-a-service** | Long-running optimization process; reuses across many short-lived worker invocations |
 | **Heterogeneous workers** | One cell on a CPU container, another on a GPU box, another against a third-party API — same Dispatch shape, different placement |
-| **Budget-isolated workers** | Worker boxes get scoped, time-bounded credentials; driver never holds production keys |
+| **Budget-isolated workers** | Worker boxes get scoped, time-bounded credentials; coordinator never holds production keys |
 
 ## Two new pieces in 0.45.0
 
@@ -48,9 +48,9 @@ This shipped in 0.40.
 
 ### 2. Single remote worker
 
-Driver-on-A talks to one worker-on-B over HTTP.
+Coordinator-on-A talks to one worker-on-B over HTTP.
 
-**Driver side (machine A):**
+**Coordinator side (machine A):**
 
 ```ts
 import { httpDispatch } from '@tangle-network/agent-eval/adapters/http'
@@ -89,7 +89,7 @@ custom auth headers, optional `fetchImpl` override — all there.
 
 ### 3. Multi-region fan-out
 
-Driver picks a region per cell; the same `httpDispatch` routes to
+The coordinator picks a region per cell; the same `httpDispatch` routes to
 different worker URLs based on placement.
 
 ```ts
@@ -129,13 +129,13 @@ round-robin, region-affinity from a previous run, scheduling table).
 
 | Concern | How |
 |---|---|
-| **Cancellation** | Driver's `AbortSignal` forwards into the HTTP request; server translates `AbortError` → `499` so client doesn't retry. |
+| **Cancellation** | The coordinator's `AbortSignal` forwards into the HTTP request; server translates `AbortError` → `499` so client doesn't retry. |
 | **Timeouts** | Per-call `timeoutMs` on the client; server can layer its own. |
-| **Retries** | Idempotent retries on 5xx / 408 / 429 with exponential backoff + jitter. Driver-aborts never retry. |
+| **Retries** | Idempotent retries on 5xx / 408 / 429 with exponential backoff + jitter. Coordinator aborts never retry. |
 | **Auth** | Bearer token on `Authorization`; pluggable via `auth: string \| () => string \| Promise<string>` for rotation/refresh. |
 | **Payload size** | Server enforces `maxBodyBytes` (default 10 MB). |
 | **Traces** | Both ends emit OTel — if both point at the same OTLP collector, you get a unified trace per cell. See `docs/adapters-observability.md`. |
-| **Cost** | Worker's `ctx.cost.observe(usd, source)` is local to the worker process. Roll up server-side and attach to your worker-side telemetry; we don't (yet) forward cost back to the driver. Tracked as follow-up. |
+| **Cost** | Worker's `ctx.cost.observe(usd, source)` is local to the worker process. Roll up server-side and attach to your worker-side telemetry; we don't (yet) forward cost back to the coordinator. Tracked as follow-up. |
 
 ## Running the reference example
 
@@ -145,7 +145,7 @@ See `examples/distributed-driver/`:
 # Terminal 1 — worker
 pnpm tsx examples/distributed-driver/worker.ts
 
-# Terminal 2 — driver
+# Terminal 2 — coordinator
 WORKER_URL=http://localhost:8080/dispatch \
 WORKER_TOKEN=dev-token \
 pnpm tsx examples/distributed-driver/driver.ts
@@ -160,7 +160,7 @@ and using `cellPlacement` to fan across many of them.
 - **Cost roll-up across the wire** — worker-side `ctx.cost` observations
   stay on the worker. We need to forward them in the response body so
   `defaultProductionGate`'s `budgetUsd` ceiling reflects total spend, not
-  driver-side spend. Tracked as a 0.45.x follow-up.
+  coordinator-side spend. Tracked as a 0.45.x follow-up.
 - **Per-cell artifact streaming** — when the worker writes intermediate
   artifacts via `ctx.artifacts.write`, those land on the worker's
   storage. For multi-worker campaigns you'll want a shared object store

package/docs/feature-guide.md

@@ -149,7 +149,7 @@ Store as `FeedbackTrajectory`, then derive:
 
 | Area | Key exports | Best for | Notes |
 | --- | --- | --- | --- |
-| Judging | `createCustomJudge`, `createAntiSlopJudge`, wire rubrics | Content, voice, semantic quality | Pair with objective checks when possible. |
+| Judging | `createCustomJudge`, semantic judges, anti-slop, wire rubrics | Content, voice, semantic quality | Pair with objective checks when possible. |
 | Verification | `MultiLayerVerifier`, `JudgeRunner`, sandbox harness | Code and multi-step gates | Do not let semantic judges override failed builds. |
 | Control | `runAgentControlLoop`, `objectiveEval`, `subjectiveEval` | Long-running agent tasks | Supports budgets, cost, stop policies, trace spans. |
 | Propose/review | `runProposeReview`, `runProposeReviewAsControlLoop` | Iterative artifact repair | Good for code, docs, plans, briefs. |

package/docs/hosted-ingest-spec.md

@@ -5,9 +5,8 @@ any future open implementation) must accept. Frozen under semver:
 **new minors only add optional fields. Breaking changes mean a major
 bump and a new `HostedWireVersion` literal.**
 
-This is the contract that decouples the LAND-tier substrate
-(`@tangle-network/agent-eval`) from the EXPAND-tier hosted product. A
-foreign builder can:
+This is the contract between `@tangle-network/agent-eval` and any hosted
+or self-hosted orchestrator. A builder can:
 
 - Use our orchestrator at `https://orchestrator.tangle.tools/v1`.
 - Self-host the reference receiver from

package/docs/multi-shot-optimization.md

@@ -1,8 +1,8 @@
 # Multi-Shot Optimization
 
 > **Renamed.** `runMultiShotOptimization` was retired. The live API is
-> `runImprovementLoop` (driver-agnostic, gated promotion) driven by `gepaDriver`,
-> with `compareDrivers` for head-to-head driver lift. This doc was rewritten to the
+> `runImprovementLoop` (proposer-agnostic, gated promotion) driven by `gepaProposer`,
+> with `compareProposers` for head-to-head proposer lift. This doc was rewritten to the
 > live API; see also [feature-guide.md](./feature-guide.md) and [concepts.md](./concepts.md).
 
 `runImprovementLoop` is the public entry for GEPA-style optimization over a whole
@@ -19,8 +19,8 @@ held-out re-score, the promotion gate, provenance):
 - **`dispatchWithSurface(surface, scenario, ctx)`** — run one task to completion
   under a candidate surface; return the artifact the judges score.
 - **`judges`** — score the artifact (`{ composite, dimensions }`).
-- **`driver`** — proposes candidate surfaces each generation: `gepaDriver`
-  (reflective + Pareto frontier) or `evolutionaryDriver` (mutator).
+- **`proposer`** — proposes candidate surfaces each generation: `gepaProposer`
+  (reflective + Pareto frontier) or `evolutionaryProposer` (mutator).
 - **`gate`** — `defaultProductionGate` (held-out significance + red-team +
   reward-hacking + canary). Ships ONLY on a CI-lower-bound held-out lift.
 
@@ -29,7 +29,7 @@ held-out re-score, the promotion gate, provenance):
 ```ts
 import {
   runImprovementLoop,
-  gepaDriver,
+  gepaProposer,
   defaultProductionGate,
 } from '@tangle-network/agent-eval/contract'
 
@@ -40,7 +40,7 @@ const result = await runImprovementLoop({
   dispatchWithSurface: async (surface, scenario) =>
     runYourAgentToCompletion({ scenario, prompt: String(surface) }),
   judges: [myJudge],
-  driver: gepaDriver({
+  proposer: gepaProposer({
     llm: { apiKey, baseUrl },
     model: 'gpt-5',
     target: 'enforce a strict output schema',
@@ -53,7 +53,7 @@ const result = await runImprovementLoop({
 })
 
 if (result.gateResult.decision === 'ship') {
-  deploy(result.winnerSurface) // the driver's proposal, gated on a real held-out lift
+  deploy(result.winnerSurface) // the proposer's candidate, gated on a real held-out lift
 }
 ```
 
@@ -70,6 +70,6 @@ if (result.gateResult.decision === 'ship') {
   auditable candidate→gate→promote chain (rationale, content hashes, a held-out lift
   recomputable from the emitted record).
 
-Reach for `compareDrivers` when the question is "which DRIVER wins" rather than
+Reach for `compareProposers` when the question is "which proposer wins" rather than
 "improve this surface", and see `tests/campaign/presets.test.ts` for the executable
 contract (no-op guard, fail-loud holdout, gate promotion).

package/docs/product-eval-adoption.md

@@ -121,7 +121,7 @@ the record:
 ```ts
 const agentProfile = await buildAgentProfileCell({
   profileId: 'gtm-founder-v1',
-  sourceProfile: { kind: 'sandbox-agent-profile', profile: gtmAgentProfile },
+  sourceProfile: { kind: 'agent-interface-profile', profile: gtmAgentProfile },
   harness: { id: 'gtm-agent-eval', version: '0.3.0' },
   model: 'gpt-4o-2024-11-20',
   promptHash,

package/docs/self-improvement-map.md

@@ -1,6 +1,6 @@
 # The self-improvement map
 
-One loop. Four roles. A driver catalog of pluggable strategies. A bench rig that
+One loop. Four roles. A proposer catalog of pluggable strategies. A bench rig that
 proves the loop produces real lift. Nothing here is duplicated — it is one engine
 pointed at different surfaces. This map exists because the surface count makes it
 *look* like many competing systems when it is one.
@@ -16,7 +16,7 @@ product imports the same function. Each generation it does four things:
 ```
    run AGENT on SCENARIOS ──► JUDGE scores each run
                                       │
-                          DRIVER reads the failures and
+                          PROPOSER reads the failures and
                           proposes better SURFACE versions
                                       │
                   GATE: did a candidate beat the parent on a
@@ -31,28 +31,32 @@ product imports the same function. Each generation it does four things:
 | Role | What it is | Plain meaning |
 |---|---|---|
 | **Surface** | a *string* — an agent directive, a `SKILL.md`, a playbook, a memory, a judge rubric | **what** gets improved |
-| **Driver** | an `ImprovementDriver` (the catalog below) | **how** it is improved |
+| **Proposer** | a `SurfaceProposer` (the catalog below) | **how** candidate surfaces are proposed |
 | **Gate** | held-out split + significance (`paretoSignificanceGate` / `heldOutGate` / `defaultProductionGate`) | **did it actually get better**, vs noise |
 | **Judge** | scores a run | **how good** any version is |
 
-## The driver catalog (one loop, seven strategies)
+## The proposer catalog (one loop, multiple strategies)
 
-Source of truth: `src/campaign/drivers/guide.ts` (`DRIVER_GUIDE` + `selectDriver()`).
-The split that matters: **production drivers** mutate a live surface; **bench-only
-drivers** exist solely to be raced inside `compareDrivers`.
+The package intentionally exposes named proposer factories instead of a hidden
+auto-selector. The split that matters: **production proposers** mutate a live
+surface; **bench-only proposers** exist solely to be raced inside
+`compareProposers`.
 
-| Driver | Surface | Strategy | Role | Notes |
+| Proposer factory | Surface | Strategy | Role | Notes |
 |---|---|---|---|---|
-| `gepaDriver` | prompt | reflective full-surface rewrite + Pareto frontier | **production default** | consumes trace-analysis findings — see below |
-| `skillOptDriver` | skill-doc | anchored add/delete/replace patch | production | preserves earlier rules; edit budget = "textual learning rate" |
-| `aceDriver` | playbook | append-only, provenance-tagged | production | accumulate hard-won lessons, never summarize away |
-| `memoryCurationDriver` | memory | dedup + rank + graft | production | compact alternative to `ace` |
-| `evolutionaryDriver` | any | population mutate → measure → select | production | blind search; no reflection over findings |
-| `traceAnalystDriver` | prompt | analysis → one LLM edit | **bench-only** | our evidence engine, wrapped as a driver |
-| `haloDriver` | prompt | analysis → one LLM edit | **bench-only**, external | wraps `pip install halo-engine` (Inference.net) |
-
-`selectDriver({ goal, surface })` ranks these for you. `GOAL_RANK`: explore →
-`gepa`; refine → `skillOpt`; accumulate → `ace`; benchmark → `traceAnalyst`/`halo`.
+| `gepaProposer` | prompt | reflective full-surface rewrite + Pareto frontier | **production default** | consumes trace-analysis findings — see below |
+| `fapoProposer` | prompt/config/code | reviewed escalation policy over prompt → parameter → structural proposers | production, benchmark | encodes FAPO's scope + reviewer + prompt-first escalation rules; structural generator is injected |
+| `parameterSweepProposer` | config | JSON config patch/sweep | production, benchmark | middle FAPO level for parameter/config edits such as `retrieval.k`, `temperature`, `max_tokens` |
+| `skillOptProposer` | skill-doc | anchored add/delete/replace patch | production | preserves earlier rules; edit budget = "textual learning rate" |
+| `aceProposer` | playbook | append-only, provenance-tagged | production | accumulate hard-won lessons, never summarize away |
+| `memoryCurationProposer` | memory | dedup + rank + graft | production | compact alternative to `ace` |
+| `evolutionaryProposer` | any | population mutate → measure → select | production | blind search; no reflection over findings |
+| `traceAnalystProposer` | prompt | analysis → one LLM edit | **bench-only** | our evidence engine, wrapped as a proposer |
+| `haloProposer` | prompt | analysis → one LLM edit | **bench-only**, external | wraps `pip install halo-engine` (Inference.net) |
+
+Default choice: start with `gepaProposer` for prompt surfaces, add
+`parameterSweepProposer` when config knobs are the likely failure mode, and wrap
+them with `fapoProposer` when evidence should decide when to escalate.
 
 ## Trace analysis — what it is and the three places it is used
 
@@ -63,21 +67,21 @@ three places — this is the answer to "if GEPA does its own thing, what is trac
 analysis *for*?":
 
 1. **Ships to customers** — `analyzeRuns()` → `InsightReport`, the Intelligence product.
-2. **Feeds the optimizer** — `gepaDriver` calls `renderAnalystEvidence(ctx.findings,
-   ctx.report)` (`src/campaign/drivers/gepa.ts`). This is the EYES→HANDS wire: GEPA's
-   rewrites are grounded in the diagnosis instead of guessing blind. Trace analysis
+2. **Feeds the proposer** — `gepaProposer` calls `renderAnalystEvidence(ctx.findings,
+   ctx.report)` (`src/campaign/proposers/gepa.ts`). GEPA's rewrites are grounded
+   in the diagnosis instead of guessing blind. Trace analysis
    **is** on the GEPA side.
-3. **Races HALO** — wrapped as `traceAnalystDriver` so our analysis competes
-   head-to-head with the external SOTA inside `compareDrivers`.
+3. **Races HALO** — wrapped as `traceAnalystProposer` so our analysis competes
+   head-to-head with the external SOTA inside `compareProposers`.
 
 ## Where HALO fits (and why it feels "removed")
 
-`haloDriver` is alive (`src/campaign/drivers/halo.ts`, exported from the campaign
+`haloProposer` is alive (`src/campaign/proposers/halo.ts`, exported from the campaign
 barrel) but it is **never in the product loop**. It shells out to an *external* engine
 (`halo-engine`) — so the analysis genuinely lives outside this repo; we only wrap it.
 
-Its only job is the **bake-off**. HALO's real opponent is **not** `gepaDriver` — it is
-`traceAnalystDriver`. `compareDrivers` holds the apply step identical (same
+Its only job is the **bake-off**. HALO's real opponent is **not** `gepaProposer` — it is
+`traceAnalystProposer`. `compareProposers` holds the apply step identical (same
 `APPLY_SYSTEM`, same `traces.jsonl`, same held-out scoring) so the only variable is
 **analysis quality: HALO vs ours.** A measuring stick, like a benchmark baseline.
 
@@ -100,9 +104,9 @@ Products run the loop to get **better**. `gepa-refine` runs the identical loop t
 
 The code is well-factored; the confusion is narrative:
 
-- **Surface sprawl reads as chaos.** Seven drivers with overlapping shapes *look* like
-  seven competing loops. They are pluggable strategies for one loop — `guide.ts` says
-  so, but it was buried. (This doc surfaces it.)
+- **Surface sprawl reads as chaos.** Several proposers with overlapping shapes *look* like
+  competing loops. They are exported factories for one loop; this map makes that
+  explicit.
 - **The real gap is the missing proof, not the design.** The loop kept being proved on
   benchmarks too easy to show value: when a capable model ceilings an extraction task,
   **0 findings fire** and the whole trace-analysis→optimizer apparatus is inert. It

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-eval",
-  "version": "0.93.0",
+  "version": "0.95.0",
   "description": "Evaluate and improve AI agents from runs, traces, judges, and feedback. Compare candidates, cluster failures, measure lift, and gate releases.",
   "homepage": "https://github.com/tangle-network/agent-eval#readme",
   "repository": {
@@ -134,7 +134,7 @@
       "import": "./dist/authenticity/index.js",
       "default": "./dist/authenticity/index.js"
     },
-    "./experimental/belief-state": {
+    "./belief-state": {
       "types": "./dist/belief-state/index.d.ts",
       "import": "./dist/belief-state/index.js",
       "default": "./dist/belief-state/index.js"
@@ -169,6 +169,11 @@
       "import": "./dist/hosted/index.js",
       "default": "./dist/hosted/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
     "./openapi.json": {
       "default": "./dist/openapi.json"
     }
@@ -185,7 +190,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup && pnpm openapi",
+    "build": "tsup && tsc --emitDeclarationOnly && node scripts/emit-declaration-aliases.mjs && pnpm openapi",
     "dev": "tsup --watch",
     "prepare": "husky",
     "prepublishOnly": "pnpm build",
@@ -201,21 +206,13 @@
     "@asteasolutions/zod-to-openapi": "^8.5.0",
     "@ax-llm/ax": "^19.0.25",
     "@hono/node-server": "^2.0.0",
+    "@tangle-network/agent-interface": "^0.10.0",
     "@tangle-network/tcloud": "^0.4.6",
     "hono": "^4.12.16",
     "zod": "^4.3.6"
   },
-  "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.2.1 <0.5.0"
-  },
-  "peerDependenciesMeta": {
-    "@tangle-network/sandbox": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/sandbox": "0.4.0",
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.5",
@@ -226,9 +223,6 @@
   },
   "pnpm": {
     "minimumReleaseAge": 4320,
-    "minimumReleaseAgeExclude": [
-      "@tangle-network/sandbox"
-    ],
     "overrides": {
       "postcss@<8.5.10": "^8.5.10",
       "ws@>=8.0.0 <8.20.1": "^8.20.1"