@tangle-network/agent-eval 0.123.0 → 0.123.2

package/dist/wire/index.d.ts

@@ -668,6 +668,13 @@ interface LlmClientOptions {
     deadlineMs?: number;
     /** Total provider attempts. Legacy option name; default 3 (1 initial + 2 retries). */
     maxRetries?: number;
+    /**
+     * Transport for requests that declare `jsonSchema`. `native` sends
+     * `response_format: json_schema`; `json-object` sends the broadly supported
+     * JSON mode and relies on the caller to include the schema in model-visible
+     * instructions. Default: `native`.
+     */
+    jsonSchemaTransport?: 'native' | 'json-object';
     /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
     fetch?: typeof fetch;
     /**
@@ -691,6 +698,29 @@ interface LlmClientOptions {
     /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
     redactor?: ProviderRedactor;
 }
+interface LlmRouteRequirements {
+    /**
+     * Throw if `opts.baseUrl` is undefined, i.e. the call would fall back to
+     * `DEFAULT_BASE_URL`. Set this for evaluation runs where silently using
+     * the public/free-tier router is a defect — the launch reviewer needs to
+     * know exactly which provider answered.
+     */
+    requireExplicitBaseUrl?: boolean;
+    /**
+     * Allowlist of acceptable base URLs. Strings match by prefix
+     * (case-insensitive); RegExps test against the full base URL.
+     */
+    allowedBaseUrls?: Array<string | RegExp>;
+    /** Blocklist that takes precedence over `allowedBaseUrls`. */
+    blockedBaseUrls?: Array<string | RegExp>;
+    /** Throw if no auth header / api key is configured. */
+    requireAuth?: boolean;
+    /**
+     * Logical provider id the configured `baseUrl` is expected to match (via
+     * `providerFromBaseUrl`). Mainly useful when paired with `requireExplicitBaseUrl`.
+     */
+    expectedProvider?: string;
+}
 
 declare const RubricDimensionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -1124,6 +1154,8 @@ interface HandleJudgeOptions {
     costLedger?: CostLedgerHandle;
     costPhase?: string;
     llm?: LlmClientOptions;
+    defaultModel?: string;
+    routeRequirements?: LlmRouteRequirements;
     signal?: AbortSignal;
 }
 declare function handleJudge(req: JudgeRequest, options?: HandleJudgeOptions): Promise<JudgeResult>;
@@ -1161,6 +1193,20 @@ declare function handleFeedbackIngest(req: FeedbackTrajectory, stores: Ingestion
 
 declare function buildOpenApi(packageVersion: string): OpenAPIObject;
 
+/**
+ * stdio RPC transport.
+ *
+ * For batch / cron use without a running server. The Python client falls
+ * back to this when no server is reachable.
+ *
+ * Protocol (line-delimited JSON over stdin/stdout):
+ *   IN:  one JSON object on stdin: {"method":"judge","params":{...}}
+ *   OUT: one JSON object on stdout: {"result":{...}} or {"error":{...}}
+ *
+ * One request per process invocation. To pipeline many calls, the client
+ * writes JSONL to stdin and reads JSONL from stdout — see batch mode below.
+ */
+
 interface RpcRequest {
     method: 'judge' | 'listRubrics' | 'version';
     params?: unknown;
@@ -1175,11 +1221,16 @@ interface RpcError {
         details?: unknown;
     };
 }
-declare function dispatchRpc(req: RpcRequest): Promise<RpcSuccess | RpcError>;
+interface RpcOptions {
+    llm?: LlmClientOptions;
+    judgeModel?: string;
+    llmRouteRequirements?: LlmRouteRequirements;
+}
+declare function dispatchRpc(req: RpcRequest, options?: RpcOptions): Promise<RpcSuccess | RpcError>;
 /** Read one JSON request from stdin, write one JSON response to stdout. */
-declare function runRpcOnce(method?: string): Promise<number>;
+declare function runRpcOnce(method?: string, options?: RpcOptions): Promise<number>;
 /** Read JSONL requests from stdin, write JSONL responses to stdout. */
-declare function runRpcBatch(method?: string): Promise<number>;
+declare function runRpcBatch(method?: string, options?: RpcOptions): Promise<number>;
 
 /**
  * Built-in rubrics shipped with agent-eval.
@@ -1218,6 +1269,12 @@ declare function listBuiltinRubrics(): {
 interface CreateAppOptions {
     /** Stores wired to the ingestion endpoints. */
     stores?: IngestionStores;
+    /** Model provider used by `/v1/judge`. */
+    llm?: LlmClientOptions;
+    /** Default judge model when a request does not provide one. */
+    judgeModel?: string;
+    /** Model route checks applied before every judge call. */
+    llmRouteRequirements?: LlmRouteRequirements;
     /**
      * Bearer-token auth. When provided, every endpoint EXCEPT `/healthz`
      * and `/v1/version` requires `Authorization: Bearer <token>`. The
@@ -1257,4 +1314,4 @@ interface StartedServer {
  */
 declare function startServerAsync(opts?: ServeOptions): Promise<StartedServer>;
 
-export { BUILTIN_RUBRICS, type ErrorResponse, ErrorResponseSchema, type FailureMode, FailureModeSchema, FeedbackAttemptSchema, type FeedbackIngestResponse, FeedbackIngestResponseSchema, FeedbackLabelSchema, type FeedbackTrajectory, FeedbackTrajectorySchema, type HandleJudgeOptions, HealthResponseSchema, type IngestionStores, type JudgeRequest, JudgeRequestSchema, type JudgeResult, JudgeResultSchema, type ListRubricsResponse, ListRubricsResponseSchema, type Rubric, type RubricDimension, RubricDimensionSchema, type RubricInfo, RubricInfoSchema, RubricSchema, type ServeOptions, type StartedServer, type TraceEvent, TraceEventSchema, type TracesIngestRequest, TracesIngestRequestSchema, type TracesIngestResponse, TracesIngestResponseSchema, type VersionResponse, VersionResponseSchema, WIRE_VERSION, WireError, buildOpenApi, createApp, dispatchRpc, getBuiltinRubric, handleFeedbackIngest, handleJudge, handleListRubrics, handleTracesIngest, handleVersion, hashRubric, listBuiltinRubrics, runRpcBatch, runRpcOnce, startServer, startServerAsync };
+export { BUILTIN_RUBRICS, type ErrorResponse, ErrorResponseSchema, type FailureMode, FailureModeSchema, FeedbackAttemptSchema, type FeedbackIngestResponse, FeedbackIngestResponseSchema, FeedbackLabelSchema, type FeedbackTrajectory, FeedbackTrajectorySchema, type HandleJudgeOptions, HealthResponseSchema, type IngestionStores, type JudgeRequest, JudgeRequestSchema, type JudgeResult, JudgeResultSchema, type ListRubricsResponse, ListRubricsResponseSchema, type RpcOptions, type Rubric, type RubricDimension, RubricDimensionSchema, type RubricInfo, RubricInfoSchema, RubricSchema, type ServeOptions, type StartedServer, type TraceEvent, TraceEventSchema, type TracesIngestRequest, TracesIngestRequestSchema, type TracesIngestResponse, TracesIngestResponseSchema, type VersionResponse, VersionResponseSchema, WIRE_VERSION, WireError, buildOpenApi, createApp, dispatchRpc, getBuiltinRubric, handleFeedbackIngest, handleJudge, handleListRubrics, handleTracesIngest, handleVersion, hashRubric, listBuiltinRubrics, runRpcBatch, runRpcOnce, startServer, startServerAsync };

package/dist/wire/index.js

@@ -34,8 +34,8 @@ import {
   runRpcOnce,
   startServer,
   startServerAsync
-} from "../chunk-LBAHQOBI.js";
-import "../chunk-NJC7U437.js";
+} from "../chunk-EBDOTTZJ.js";
+import "../chunk-J7S4YM27.js";
 import "../chunk-BGVTIE2C.js";
 import "../chunk-VI2UW6B6.js";
 import "../chunk-PC4UYEBM.js";

package/docs/adapters-observability.md

@@ -3,7 +3,7 @@
 `@tangle-network/agent-eval` ships its own OpenTelemetry pipeline
 (`@tangle-network/agent-eval/telemetry`) that emits spans for every
 cell, judge invocation, mutator proposal, and gate decision. **It's
-just OTel** — same protocol as Langfuse SDK, OpenLLMetry, Arize
+just OTel**: same protocol as Langfuse SDK, OpenLLMetry, Arize
 Phoenix, TraceAI, and the OpenTelemetry GenAI semantic conventions.
 
 That means: if you already instrument your agent with any OTel-native
@@ -11,14 +11,14 @@ observability tool, the two compose **for free at the protocol layer**.
 This doc shows the composition pattern; no agent-eval-specific adapter
 code required.
 
-## TL;DR — one OTel context, two emitters
+## TL;DR: one OTel context, two emitters
 
 1. Set up a shared OTel tracer provider in your process (or service mesh).
 2. Configure your observability tool (TraceAI / Langfuse / OpenLLMetry /
    Phoenix) to register its instrumentations against that provider.
 3. Configure agent-eval's `/telemetry` exporter against the same provider.
 4. Run a campaign. Both sets of spans land at your OTel collector.
-5. Filter / route / fan-out at the collector layer — Jaeger, Tempo,
+5. Filter / route / fan-out at the collector layer: Jaeger, Tempo,
    Phoenix, Langfuse cloud, your private collector, whatever.
 
 The Tangle substrate doesn't compete with the observability tool;
@@ -92,7 +92,7 @@ provider.addSpanProcessor(new SimpleSpanProcessor(
 provider.register()
 
 // 2. Your observability tool registers against the global provider.
-//    Example for TraceAI / OpenLLMetry / Langfuse — call their init.
+//    Example for TraceAI / OpenLLMetry / Langfuse: call their init.
 //    (See each tool's docs.)
 
 // 3. agent-eval is already OTel-native; it picks up the same global
@@ -101,12 +101,12 @@ provider.register()
 import { setOtelExporter } from '@tangle-network/agent-eval/telemetry'
 setOtelExporter({ kind: 'otel-global' })  // use the global provider
 
-// 4. Run your campaign — both sets of spans land at the collector.
+// 4. Run your campaign: both sets of spans land at the collector.
 import { runEval } from '@tangle-network/agent-eval/contract'
 await runEval({ /* ... */ })
 ```
 
-That's it. No new adapter shipping required — the libs are already
+That's it. No new adapter shipping required: the libs are already
 designed to live in the same OTel ecosystem.
 
 ## When you'd want a deeper, code-level adapter

package/docs/building-doctrine.md

@@ -4,7 +4,7 @@ How every fleet agent that consumes `agent-eval` is built. Each rule is mechanic
 
 ## 1. Defaults must be provably reachable
 
-Every hard-coded model id or endpoint default is verifiable against the live router. Membership in `{baseUrl}/models` is the free check; an optional 1-token probe per model confirms the router will actually serve it. A default the router cannot serve is a config bug caught before the run, not a runtime surprise that silently degrades into a stub. Backend ids are namespaced by binding: cli-bridge ids (`claude-code/*`, `kimi-code/*`, `opencode/*`) never appear as defaults in code reachable from production — bridge use is an explicit env opt-in, never an implicit fallback.
+Every hard-coded model id or endpoint default is verifiable against the live router. Membership in `{baseUrl}/models` is the free check; an optional 1-token probe per model confirms the router will actually serve it. A default the router cannot serve is a config bug caught before the run, not a runtime surprise that silently degrades into a stub. Backend ids are namespaced by binding: cli-bridge ids (`claude-code/*`, `kimi-code/*`, `opencode/*`) never appear as defaults in code reachable from production: bridge use is an explicit env opt-in, never an implicit fallback.
 
 Enforced by: `preflightModels` (membership + optional probe) and `assertModelsServed` (gate that names every unreachable id with status + detail).
 
@@ -12,13 +12,13 @@ Enforced by: `preflightModels` (membership + optional probe) and `assertModelsSe
 
 When a request fails, one direct call against the live endpoint bisects platform-versus-client before any code-level debugging begins. A 401 from the router on a `model_not_found` is the platform telling you the default is dead; a connection refused is the platform being unreachable. Establish which side is at fault with a probe first, then debug only the side that is actually broken.
 
-Enforced by: `preflightModels({ probe: true })` — the probe is the platform-side bisection, carrying the router's own `error.message` back to the caller.
+Enforced by: `preflightModels({ probe: true })`: the probe is the platform-side bisection, carrying the router's own `error.message` back to the caller.
 
 ## 3. Agent-produced findings are hypotheses
 
 Enumeration of candidate problems may fan out to agents, but agent output is not evidence. Truth comes from probes against ground truth, not from an agent's assertion. Every classification carries quoted evidence, and nothing unverified is merged or reported as fact. A confident-sounding agent claim with no probe behind it is a hypothesis awaiting falsification.
 
-Enforced by: `assertRealBackend` over the resulting `RunRecord[]` — an agent that claims success while the backend was never called reads as a stub, not a pass.
+Enforced by: `assertRealBackend` over the resulting `RunRecord[]`: an agent that claims success while the backend was never called reads as a stub, not a pass.
 
 ## 4. Experiment integrity checklist
 
@@ -30,7 +30,7 @@ Any lift or benchmark claim satisfies all of the following before it is reported
 - The same scorer and the same items on both sides of any comparison.
 - A leakage check from builder inputs into the evaluation set.
 - Cross-family judge panels, with inter-rater reliability reported and gated.
-- Missing evidence is never scored as zero — fail loud over fabricate.
+- Missing evidence is never scored as zero: fail loud over fabricate.
 - No optional stopping: the stopping rule is fixed before the run.
 
 Enforced by: `pairedBootstrap` (CI), `assertCrossFamily` (panel diversity), `interRaterReliability` (agreement), and `assertRealBackend` (no stub run masquerading as a result).
@@ -39,4 +39,4 @@ Enforced by: `pairedBootstrap` (CI), `assertCrossFamily` (panel diversity), `int
 
 A drifted default is the symptom of a missing convention. The fix ships the convention and its guard alongside the one-line correction, so the same drift cannot recur silently. Patching the single dead id without adding the preflight gate leaves the class open; the next default rots the same way.
 
-Enforced by: `assertModelsServed` wired into the campaign preflight — the guard that turns "this one model was dead" into "no campaign spends tokens against an unreachable default."
+Enforced by: `assertModelsServed` wired into the campaign preflight: the guard that turns "this one model was dead" into "no campaign spends tokens against an unreachable default."

package/docs/concepts.md

@@ -16,17 +16,17 @@ 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 |
+| **`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 report |
+| **`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 |
 | **`loadEvalFixtureScenarios()`** | You want agents to add evals as folders with `PROMPT.md`, checks, and starter files. | `evals/<name>/PROMPT.md + EVAL.ts + package.json` | `Scenario[]` that runs through `runCampaign`; pair with `planEvalFixtureRun()` before spending tokens |
 | **`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()` |
+| **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 customer maturity stages — logs only → ratings → closed loop — map to these
+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).
+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).
 
 ## The layering rule
 
@@ -39,7 +39,7 @@ The test: *does this concept make sense WITHOUT a running agent loop?* If yes, i
 | Thing | What it is | One-line example |
 |---|---|---|
 | **Judge** | A function that scores one piece of output. | "Did this scaffold implement async fetching?" |
-| **Rubric** | The recipe a judge uses — what to score on, with what weights. | "Score on buyer_quality (0.5), voice (0.3), signal (0.2)." |
+| **Rubric** | The recipe a judge uses: what to score on, with what weights. | "Score on buyer_quality (0.5), voice (0.3), signal (0.2)." |
 | **Verifier** | A pipeline of judges run in order, with dependencies. | "install → typecheck → build → semantic" |
 | **Feedback trajectory** | A multi-shot record of attempts, approvals, rejections, edits, metrics, and policy outcomes. | "draft → user rejects → revised draft → approved → measured" |
 
@@ -66,7 +66,7 @@ that can seed memory, replay scenarios, and optimization.
 | **Harness** | A description of *how to run* the artifact: setup command, test command, working dir, timeout. |
 | **Sandbox driver** | The thing that actually executes commands inside the harness. Local subprocess, or remote container. |
 | **Layer** | One stage of a verifier pipeline (install, typecheck, build, semantic, …). |
-| **Finding** | A specific issue a judge found — file, line, severity, message. |
+| **Finding** | A specific issue a judge found: file, line, severity, message. |
 | **Trace store** | The append-only log of every span/event during a run. Replay = read this back. |
 | **Composite score** | A 0..1 number combining all dimensions. The single number you gate on. |
 | **Rubric version** | A stable hash of the rubric. Scores from different rubric versions are not comparable. |
@@ -103,30 +103,30 @@ L1  app-build      Does the artifact build / typecheck / test?
                               │
                               ▼
 L2  app-runtime    Does the artifact actually run end-to-end?
-                   (Dynamic signal — only worth checking if L1 passed.)
+                   (Dynamic signal: only worth checking if L1 passed.)
 ```
 
 `BuilderSession` orchestrates this. It opens at `startChat`, runs the build at `ship`, runs the runtime check at `runAppScenario`. Each layer emits a trace span. Composite score aggregates them with `scoreProject`.
 
 Why three? Because each catches a different failure mode:
-- L0 misses — agent crashed mid-generation, you have a half-written file.
-- L1 misses — files exist but typecheck fails. LLM judges can't reliably catch this.
-- L2 misses — code compiles but does the wrong thing at runtime.
+- L0 misses: agent crashed mid-generation, you have a half-written file.
+- L1 misses: files exist but typecheck fails. LLM judges can't reliably catch this.
+- L2 misses: code compiles but does the wrong thing at runtime.
 
 If you only check one layer, you ship the bugs that the other two layers would have caught.
 
 ## How rubrics work
 
 A rubric describes:
-1. **Dimensions** — the axes you score on (e.g. `buyer_quality`, `voice`, `signal`).
-2. **Weights** — how to combine dimensions into a composite (`0.5 * buyer_quality + 0.3 * voice + 0.2 * signal`).
-3. **Failure modes** — named patterns the judge looks for ("ai-cadence", "vague-claim").
-4. **Wins** — named positive patterns ("specific-component", "earned-detail").
-5. **System prompt** — what to tell the judging LLM about the persona and the task.
+1. **Dimensions**: the axes you score on (e.g. `buyer_quality`, `voice`, `signal`).
+2. **Weights**: how to combine dimensions into a composite (`0.5 * buyer_quality + 0.3 * voice + 0.2 * signal`).
+3. **Failure modes**: named patterns the judge looks for ("ai-cadence", "vague-claim").
+4. **Wins**: named positive patterns ("specific-component", "earned-detail").
+5. **System prompt**: what to tell the judging LLM about the persona and the task.
 
-Built-in rubrics ship in `src/wire/rubrics.ts` (e.g. `anti-slop` for technical-buyer voice). You can also pass a rubric inline — the same shape, just defined at the call site.
+Built-in rubrics ship in `src/wire/rubrics.ts` (e.g. `anti-slop` for technical-buyer voice). You can also pass a rubric inline: the same shape, just defined at the call site.
 
-A rubric is plain data. The hash of that data is the `rubricVersion`. Two scores are only comparable if they used the same `rubricVersion` — change the rubric and you start a new comparison series.
+A rubric is plain data. The hash of that data is the `rubricVersion`. Two scores are only comparable if they used the same `rubricVersion`: change the rubric and you start a new comparison series.
 
 ## How verifiers work
 
@@ -141,14 +141,14 @@ const verifier = new MultiLayerVerifier([
 ])
 
 const report = await verifier.run({ env: { runner, workdir, ... } })
-report.allPass        // boolean — every layer passed
-report.blendedScore   // 0..1 — weighted aggregate
+report.allPass        // boolean: every layer passed
+report.blendedScore   // 0..1: weighted aggregate
 report.layers         // per-layer status, findings, duration
 ```
 
 Two rules that will save you bugs:
 
-1. **Run both gates.** Build gates catch code that doesn't compile; structural assertions catch missing files. Run both unconditionally — they catch orthogonal failures.
+1. **Run both gates.** Build gates catch code that doesn't compile; structural assertions catch missing files. Run both unconditionally: they catch orthogonal failures.
 
 2. **Pair LLM judges with build outcomes.** An LLM judge will rate non-compiling code as "looks right" (0.8). Always short-circuit on `buildOutcome.passed === false` before any LLM judging.
 
@@ -159,7 +159,7 @@ Two questions to answer before trusting any LLM judge:
 1. **Does it agree with humans?** `calibrateJudge(golden, candidate)` reports Pearson, MAE, integer-rounded κ, and worst-N miscalibrations vs a human golden set.
 2. **Does it agree with itself / other judges?** `continuousAgreement(scores)` and `calibrateJudgeContinuous(golden, candidate)` report κ_w + ICC(2,1) + Pearson + Spearman with bootstrap 95% CIs on the raw [0,1] scores.
 
-Why two κ flavours: the original `calibrateJudge` rounds scores to ints before computing κ. For fine-grained judges that loses information — 0.78 vs 0.81 both round to "1" and look perfectly agreed. Use `calibrateJudgeContinuous` (or `continuousAgreement` for N≥2 raters) when scores are continuous. ICC(2,1) catches systematic bias that Pearson misses: if judge B scores 2× judge A, Pearson stays ≈ 1 while ICC drops — that's the signal.
+Why two κ flavours: the original `calibrateJudge` rounds scores to ints before computing κ. For fine-grained judges that loses information: 0.78 vs 0.81 both round to "1" and look perfectly agreed. Use `calibrateJudgeContinuous` (or `continuousAgreement` for N≥2 raters) when scores are continuous. ICC(2,1) catches systematic bias that Pearson misses: if judge B scores 2× judge A, Pearson stays ≈ 1 while ICC drops: that's the signal.
 
 Bias probes (`positionalBias`, `verbosityBias`, `selfPreference`) cover the orthogonal failure modes: position-dependent scoring, length-correlated scoring, and judge-prefers-its-own-family.
 
@@ -178,7 +178,7 @@ builder-session                 [span]
     └── scenario.run            [span]
 ```
 
-Spans are append-only and have stable ids — replay is reading the same store back. OTLP export ships them out for distributed tracing.
+Spans are append-only and have stable ids: replay is reading the same store back. OTLP export ships them out for distributed tracing.
 
 You usually should not build this tree by hand. Product runtimes,
 `runAgentControlLoop`, harnesses, and verifiers should emit it while they run.
@@ -187,12 +187,12 @@ release decision.
 
 ## Where to go next
 
-- **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.
-- **Need a reusable driver/worker/evaluator loop?** → [control-runtime.md](./control-runtime.md) — generic runtime plus coding, browser, computer-use, and research integration patterns.
-- **Want review feedback to become eval/optimization data?** → [feedback-trajectories.md](./feedback-trajectories.md) — turn feedback into datasets, optimizer rows, and preference memory.
+- **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.
+- **Need a reusable driver/worker/evaluator loop?** → [control-runtime.md](./control-runtime.md): generic runtime plus coding, browser, computer-use, and research integration patterns.
+- **Want review feedback to become eval/optimization data?** → [feedback-trajectories.md](./feedback-trajectories.md): turn feedback into datasets, optimizer rows, and preference memory.
 - **Building a code-generator eval?** → Start with `BuilderSession`, `SandboxHarness`, and `MultiLayerVerifier`.
 - **Multi-layer verifier?** → Use [control-runtime.md](./control-runtime.md) and `MultiLayerVerifier` for ordered gates with dependencies.
 - **Adding a new judge or rubric?** → `src/wire/rubrics.ts` for the cross-language path; `src/anti-slop.ts` and `src/judges.ts` for the in-process path.