@tangle-network/agent-eval 0.190.1 → 0.192.0

package/docs/hosted-ingest-spec.md

@@ -1,133 +1,121 @@
 # Hosted-ingest wire spec: `2026-07-24.v1`
 
-This is the only hosted-ingest wire format implemented by the current package.
+This is the only hosted-ingest wire format the current package implements.
 Clients and servers reject every other wire version.
 
-This is the contract between `@tangle-network/agent-eval` and any hosted
-or self-hosted orchestrator. A builder can:
+This is the contract between `@tangle-network/agent-eval` and any hosted or self-hosted store.
+A builder can use our store, self-host the reference receiver from `examples/hosted-ingest-server/`, or implement this spec.
 
-- Use our orchestrator at `https://orchestrator.tangle.tools/v1`.
-- Self-host the reference receiver from
-  `examples/hosted-ingest-server/`.
-- Implement their own orchestrator against this spec.
+The wire carries two streams:
 
-All three are wire-compatible by definition.
+- **Search ledgers.** A producer ships a search's hash-chained ledger and the blobs its entries name.
+  The ledger is the search's record: nodes, edges, cells, decisions and the claim ([search ledger](./search-ledger.md)).
+- **Trace spans.** OTLP-shaped spans with `tangle.*` pivots, so a store can join a cell to its execution.
+
+The shapes are exported from `@tangle-network/agent-eval/hosted` as zod schemas.
+A store imports them instead of copying them.
 
 ---
 
 ## Transport
 
-Two endpoints, both `POST`, both JSON. Headers on every request:
+Headers on every request:
 
 | Header | Value |
 |---|---|
-| `Authorization` | `Bearer <tenant-key>` (the orchestrator issues this) |
-| `Content-Type` | `application/json` |
-| `X-Tangle-Tenant-Id` | The tenant's stable id (the orchestrator's primary key for the tenant) |
-| `X-Tangle-Wire-Version` | `2026-07-24.v1` (this spec) |
-| `Idempotency-Key` | Non-empty request key, at most 256 characters; clients generate one per call and reuse it across retries |
+| `Authorization` | `Bearer <tenant-key>` |
+| `X-Tangle-Tenant-Id` | The tenant's stable id |
+| `X-Tangle-Wire-Version` | `2026-07-24.v1` |
+| `Idempotency-Key` | On `POST` and `PUT`: at most 256 characters, reused across retries |
 
-Responses are JSON of shape `{ accepted: number, rejected: Array<{ index, reason }> }`.
-Clients validate the complete response before returning it.
-The server can return 202 for asynchronous acceptance or 200 for synchronous acceptance.
+A client retries network errors, 408, 429 and 5xx.
+When the response carries `Retry-After` (delay-seconds or an HTTP date), the client waits exactly that long before the next attempt; otherwise it backs off exponentially.
 
-### `POST /v1/ingest/eval-runs`
+---
 
-Body: `IngestEvalRunsRequest = { wireVersion, events: EvalRunEvent[] }`.
+## Search ledgers
 
-One ingest call per logical eval-run; generations stream in
-incrementally via repeated calls with the same `runId`. The
-orchestrator deduplicates by `(tenantId, runId, generation.index)`.
+A producer ships in this order, so a store has an entry's content before the entry.
 
-### `POST /v1/ingest/traces`
+### `PUT /v1/search-blobs/<sha256 hex>`
 
-Body: `IngestTracesRequest = { wireVersion, spans: TraceSpanEvent[] }`.
+Body: the exact bytes an artifact ref names.
+`Content-Type` is `application/json` for the JSON blobs the recorder writes, otherwise `application/octet-stream`.
 
-Standard OTLP-shaped spans with a few additional attributes
-(`tangle.runId`, `tangle.generation`, `tangle.cellId`,
-`tangle.scenarioId`) so the orchestrator can pivot between the
-eval-run stream and the underlying execution trace.
+The store re-hashes the bytes and refuses a mismatch with 422.
+The call is idempotent by content.
+Response (`SearchBlobPutResponseSchema`): `{ sha256, byteLength, state }`, where `state` is `stored`, `masked` or `withheld`.
+A store masks or withholds bytes its redaction scan or the tenant's content posture refuses; it never rejects the entry that names them.
 
----
+### `GET /v1/ingest/search-ledger/<searchId>/head`
 
-## `EvalRunEvent`
+Response (`SearchLedgerHeadSchema`): `{ searchId, nextSequence, headHash }`.
+`nextSequence` is the number of entries the store holds, and `headHash` is the hash of the last one, or null when it holds none.
+A restarted producer starts here.
 
-```ts
-interface EvalRunEvent {
-  runId: string                      // stable; same id across all generations of one run
-  runDir: string                     // logical run directory (mem://... or filesystem path)
-  timestamp: string                  // ISO-8601
-  status:                            // lifecycle stage this event represents
-    | 'started'
-    | 'baseline-complete'
-    | 'generation-complete'
-    | 'gate-decided'
-    | 'finished'
-    | 'errored'
-  labels: Record<string, string>     // free-form (env, branch, model id, etc.)
-  baseline?: EvalRunGenerationSnapshot   // present when status >= baseline-complete
-  generations: EvalRunGenerationSnapshot[]
-  gateDecision?:                     // present when status >= gate-decided
-    | 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling'
-  holdoutLift?: number               // winner-on-holdout - baseline-on-holdout
-  totalCostUsd: number
-  totalDurationMs: number
-  errorMessage?: string              // present when status === 'errored'
-  insightReport?: InsightReport      // current report contract
-}
-```
+### `POST /v1/ingest/search-ledger`
 
-## `EvalRunGenerationSnapshot`
+Body (`IngestSearchLedgerRequestSchema`):
 
 ```ts
-interface EvalRunGenerationSnapshot {
-  index: number                      // 0 is baseline; 1..N are improvement generations
-  surfaceHash: string                // stable hash of the candidate surface (pivot key)
-  surface?: MutableSurface           // OMITTED to avoid PII when consumer prefers
-  cells: EvalRunCellScore[]
-  compositeMean: number | null       // null when no cell has a task-quality label
-  costUsd: number
-  durationMs: number
+{
+  wireVersion: '2026-07-24.v1'
+  searchId: string
+  runKind: 'optimization' | 'eval'   // an eval is a one-node search
+  fromSequence: number               // the sequence of lines[0]
+  lines: string[]                    // canonical ledger lines, without newlines
 }
 ```
 
-## `EvalRunCellScore`
+At most 1,000 lines and 1 MiB of line bytes per request.
+Each line is the producer's own ledger bytes, so producer and store hash identical input.
 
-```ts
-interface EvalRunCellScore {
-  scenarioId: string
-  rep: number                        // 0 for the default; > 0 when reps > 1
-  compositeMean: number | null       // null when the cell is unscored
-  dimensions: Record<                // successful scores; failed or missing judges are absent
-    string,
-    Record<string, number>
-  >
-  terminalOutcome: 'succeeded' | 'failed' | 'cancelled' | 'incomplete' | 'unknown'
-  executionErrorCount: number | null // null when the producer cannot classify errors
-  errorMessage?: string              // present for a dispatch or judge error
-}
-```
+The store applies `admitSearchLedgerBatch` to the batch, in one transaction:
+
+1. `fromSequence` past the store's head: `409 sequence_gap`.
+2. Each line must verify alone with `parseSearchLedgerLine`: the schema tag, the entry and event schemas, canonical bytes, its `entryHash`, and its `searchId`. A line that does not: 422.
+3. A line below the head with the stored hash is a no-op; a different hash is `409 chain_conflict`.
+4. The first new line must extend the stored head; if it does not, `409 chain_conflict`.
+5. The new entries pass the `SearchState` state machine, or the batch returns 422 and stores nothing.
+
+Response (`SearchLedgerHeadSchema`): the head after the batch.
+A 409 body (`SearchLedgerConflictSchema`) is `{ error: 'sequence_gap' | 'chain_conflict', message, head }`.
+
+A producer resends from `head.nextSequence` after a gap.
+It stops on a fork: the store holds a different chain for the same search, and nothing is overwritten.
+
+`runKind` is fixed by the first batch; a later batch with another kind is a 422.
+
+### The shipper
 
-## `TraceSpanEvent`
+`shipSearchLedger({ tenant, ledger: { path, searchId }, runKind })` ships every complete line of a ledger file and returns the store's head and blob counts.
+`startSearchShipper(...)` tails the file while the search runs: the search never waits on the network, and `stop()` ships the rest.
+`agent-eval search ship <ledger> --run-kind optimization|eval` does the same from a terminal, reading the store from `TANGLE_INGEST_URL`, `TANGLE_INGEST_API_KEY` and `TANGLE_TENANT_ID`.
+`selfImprove({ hostedTenant, searchLedger })` runs the tailing shipper for its own ledger.
+
+`content: 'digests'` ships entries without blobs, so the store holds refs and digests but no text.
+A blob whose local bytes are missing or do not match their ref is not uploaded and is reported under `blobs.missing`; the entries still ship.
+
+---
+
+## Trace spans
+
+### `POST /v1/ingest/traces`
+
+Body (`IngestTracesRequestSchema`): `{ wireVersion, spans: TraceSpanEvent[] }`.
+Response (`IngestResponseSchema`): `{ accepted, rejected: Array<{ index, reason }> }`.
 
 ```ts
 interface TraceSpanEvent {
-  // Standard OTel
   traceId: string
   spanId: string
   parentSpanId?: string
   name: string
-  startTimeUnixNano: string // canonical unsigned 64-bit integer encoded in base 10
-  endTimeUnixNano: string   // canonical unsigned 64-bit integer encoded in base 10
+  startTimeUnixNano: string // canonical unsigned 64-bit integer in base 10
+  endTimeUnixNano: string
   attributes: Record<string, string | number | boolean>
-  events?: Array<{
-    timeUnixNano: string    // canonical unsigned 64-bit integer encoded in base 10
-    name: string
-    attributes?: Record<string, string | number | boolean>
-  }>
-  status?: { code: 'OK' | 'ERROR' | 'UNSET', message? }
-
-  // Tangle additions (all optional) for pivoting
+  events?: Array<{ timeUnixNano: string; name: string; attributes?: Record<string, string | number | boolean> }>
+  status?: { code: 'OK' | 'ERROR' | 'UNSET'; message?: string }
   'tangle.runId'?: string
   'tangle.generation'?: number
   'tangle.cellId'?: string
@@ -135,59 +123,30 @@ interface TraceSpanEvent {
 }
 ```
 
+A store keeps at most one span per `(tenantId, traceId, spanId)`.
+It accepts an exact duplicate as stored and rejects a conflicting payload with the same identity.
+When an `Idempotency-Key` matches a request from the same tenant in the last 24 hours, it returns the recorded response.
+
 ---
 
 ## Server requirements
 
-Any orchestrator implementing this spec MUST:
-
-1. **Validate auth**: reject without `Authorization` header (401), with a
-   mismatched bearer token (401), or without a recognized `X-Tangle-Tenant-Id`
-   (404).
-2. **Validate wire version**: reject incompatible wire versions (400 with
-   a clear error message). The major component is the breaking-change axis.
-3. **Validate tenant isolation**: queries with `tenantId` X never return
-   data tagged with `tenantId` Y. Test this adversarially.
-4. **Honor idempotency**: require an `Idempotency-Key`; when it matches a prior request to the same endpoint from the same tenant in the last 24 hours, return the same response without processing the body again.
-5. **Deduplicate spans**: store at most one span for each `(tenantId, traceId, spanId)` identity.
-   Accept an exact duplicate as already stored and reject a conflicting payload with the same identity.
-6. **Keep run state monotonic**: accept forward lifecycle transitions, but never replace `finished` or `errored` with a late event.
-   Delayed events can add a missing generation without replacing terminal totals, labels, or status.
-7. **Persist eval-runs durably**: at least the event + cell scores must
-   survive an orchestrator restart. Trace spans MAY be best-effort.
-8. **Provide read access**: GET endpoints for the tenant to list + fetch
-   their own runs. Wire format for reads is NOT part of this spec: each
-   orchestrator can pick its own (REST + JSON, gRPC, GraphQL).
-
-Servers SHOULD also:
-
-- Provide a webhook callback per tenant for `gate-decided` events.
-- Provide a billable-events emitter (Stripe meter / equivalent) per ingest
-  call so consumption can be metered.
-- Provide a dashboard or API to view + diff per-scenario lifts over time.
+A store that implements this spec must:
+
+1. Reject a request without a valid bearer token (401) or with an unknown tenant (404).
+2. Reject every wire version other than `2026-07-24.v1` (400) and name the accepted one.
+3. Isolate tenants: a read for tenant X never returns tenant Y's data, and a blob, search or span of another tenant reads as absent.
+4. Apply the search-ledger batch rule above, and store a batch whole or not at all.
+5. Keep search entries, blobs and their metadata durably; trace spans may be best-effort.
 
 ---
 
 ## Reference implementation
 
-`examples/hosted-ingest-server/` is a Hono receiver for local development and contract tests.
-It validates auth, request and response shapes, versions, exact nanosecond strings, request keys, span identity, and monotonic run state.
-It is not production storage because process restart clears its in-memory data.
+`examples/hosted-ingest-server/` is an in-memory Hono receiver for local development.
+It applies `admitSearchLedgerBatch` and `SearchState` to every batch, re-hashes blobs, and serves `GET /v1/searches/<searchId>` with the replayed audit.
+A process restart clears it.
 
 ```sh
 TENANT_KEY=dev-token TENANT_ID=acme pnpm tsx examples/hosted-ingest-server/server.ts
 ```
-
-Send events with [`createHostedClient`](../src/hosted/client.ts) from `@tangle-network/agent-eval/hosted`.
-Call `client.ingestEvalRun(event)` with a valid `EvalRunEvent` after configuring the client's endpoint, tenant ID, and API key.
-For `selfImprove`, configure `hostedTenant` as shown in the [receiver example](../examples/hosted-ingest-server/).
-The receiver's authenticated `GET /v1/runs` endpoint lists ingested runs.
-
----
-
-## Version
-
-`HostedWireVersion` is `"2026-07-24.v1"`.
-The current clients emit only this value.
-Servers return 400 for every other value and list the accepted version.
-There are no compatibility readers or migration branches.

package/docs/public-api.md

@@ -7,11 +7,11 @@ Generated by `pnpm api:census` on demand — this is a dated reading, not a gate
 | measure | count |
 | --- | --- |
 | export subpaths | 32 |
-| published value exports (subpath x symbol) | 1500 |
-| distinct symbols | 1313 |
-| production | 978 |
+| published value exports (subpath x symbol) | 1511 |
+| distinct symbols | 1324 |
+| production | 992 |
 | planned | 268 |
-| none | 254 |
+| none | 251 |
 
 Type-only exports are not listed: a type binds no runtime surface, and removing one cannot break a caller at run time.
 
@@ -152,7 +152,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `checkTraceContracts` | production | creative-agent:eval/lib/trace-contracts.ts |
 | `clamp01` | production | agent-dev-container:products/intelligence/api/src/lib/consultant/executor.ts |
 | `classifyFailure` | production | phony:products/builder/api/src/eval/autoresearch/trace-analyst.ts |
-| `classifyFailureReason` | production | this package: src/diagnosis/first-failure.ts:28 |
+| `classifyFailureReason` | production | this package: src/diagnosis/first-failure.ts:39 |
 | `cliffsDelta` | production | agent-builder:src/lib/.server/eval/loops/differential-eval.ts |
 | `CODING_HARNESSES` | production | agent-runtime:src/runtime/define-leaderboard.ts |
 | `cohensD` | production | starter-foundry:examples/recruiter-eval-workspace/eval/src/eval/regression/gate.ts |
@@ -402,7 +402,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `scorePolicyEditReadiness` | none | — |
 | `scoreRedTeamOutput` | production | agent-dev-container:products/intelligence/api/src/lib/optimization-gate.ts |
 | `scoreTraceInsightReadiness` | production | blueprint-agent:scripts/experiments/lib/analyze-vb-run/report-html-sections.ts |
-| `searchCellRunId` | production | this package: src/campaign/search-ledger-recording.ts:24 |
+| `searchCellRunId` | production | this package: src/campaign/search-ledger-recording.ts:25 |
 | `seatPresets` | production | supervisor-lab:bench/comms/judges.ts |
 | `selfImprove` | production | agent-app:src/eval-campaign/index.ts |
 | `SEMANTIC_CONCEPT_JUDGE_VERSION` | production | blueprint-agent:scripts/experiments/lib/semantic-audit.ts |
@@ -584,7 +584,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `rlmEngineLimits` | none | only this package's tests: src/analyst/definition-parity.test.ts:26 |
 | `roundAgentRxStep` | production | this package: src/analyst/benchmark-agentrx-calibration.ts:2 |
 | `runAnalystBenchmark` | production | this package: benchmarks/trace-analysis/codetracebench-glm52-20260730/summarize-codetracer.mjs:6 |
-| `runAnalystBenchmarkCommand` | production | this package: src/cli.ts:17 |
+| `runAnalystBenchmarkCommand` | production | this package: src/cli.ts:18 |
 | `runPrimeExchange` | production | this package: src/analyst/benchmark-runner-prime.ts:19 |
 | `runTraceAnalyst` | production | this package: scripts/gepa-analyst-campaign.ts:71 |
 | `scoreAnalystFindings` | production | this package: scripts/gepa-analyst-campaign.ts:57 |
@@ -644,7 +644,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./campaign`
 
-143 value exports — 91 production, 26 planned, 26 none.
+144 value exports — 92 production, 26 planned, 26 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
@@ -662,7 +662,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `buildTraceAnalystSurfaceDispatch` | none | only this package's tests: src/campaign/analyst-surface.test.ts:4 |
 | `campaignBreakdown` | production | this package: src/campaign/external-text-evaluation.ts:11 |
 | `campaignMeanComposite` | production | agent-dev-container:products/intelligence/api/src/lib/optimization-engine.ts |
-| `campaignMeasurementDigest` | production | this package: src/contract/self-improve-method.ts:13 |
+| `campaignMeasurementDigest` | production | this package: src/contract/self-improve-method.ts:14 |
 | `campaignScenarioIdentity` | production | agent-runtime:src/improvement/method-identity.ts |
 | `campaignSplitDigest` | production | discovery-lab:tools/profile-population.mjs |
 | `campaignSplitDigestFromIdentities` | production | agent-runtime:src/improvement/method-identity.ts |
@@ -679,7 +679,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `createProfileMatrixPlan` | production | discovery-lab:tools/run-profile-confirmation.mjs |
 | `createReferenceEquivalenceJudge` | none | only this package's tests: src/reference-equivalence-judge.test.ts:13 |
 | `createRunCostLedger` | production | agent-dev-container:products/intelligence/api/src/lib/eval-engine.ts |
-| `createSearchHistoryReceipt` | production | this package: src/campaign/search-ledger-recording.ts:26 |
+| `createSearchHistoryReceipt` | production | this package: src/campaign/search-ledger-recording.ts:27 |
 | `crowdedFrontierParent` | planned | doc: docs/campaign-proposers.md |
 | `decodeExternalTextCandidate` | production | agent-runtime:src/improvement/method-execution.ts |
 | `DEFAULT_EXTERNAL_OPTIMIZER_CALLBACK_LIMITS` | none | — |
@@ -724,6 +724,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `pairHoldout` | production | agent-dev-container:products/intelligence/api/src/lib/run-provenance.ts |
 | `paretoPolicy` | none | only this package's tests: src/campaign/gates/promotion-policy.test.ts:3 |
 | `paretoSignificanceGate` | production | agent-app:src/eval-campaign/index.ts |
+| `parseSearchLedgerLine` | production | this package: src/hosted/search-ledger-wire.ts:24 |
 | `phoenixEvaluatorJudge` | none | only this package's tests: src/campaign/upstream-evaluators.test.ts:6 |
 | `planCampaignRun` | production | this package: src/campaign/fixtures.ts:5 |
 | `planEvalFixtureRun` | planned | example: examples/eval-fixtures-quickstart/index.ts:11 |
@@ -755,21 +756,21 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `scoreDiscrimination` | production | supervisor-lab:bench/comms/seat-discrimination.ts |
 | `scoreUserStory` | production | blueprint-agent:scripts/experiments/eval/launch-scoreboard/scoreboard-core.ts |
 | `SEARCH_ESTIMATOR` | planned | doc: docs/search-ledger.md |
-| `SEARCH_LEDGER_SCHEMA` | production | this package: src/campaign/search-ledger.ts:40 |
-| `searchCellId` | production | this package: src/campaign/search-ledger-recording.ts:56 |
+| `SEARCH_LEDGER_SCHEMA` | production | this package: src/campaign/search-ledger.ts:41 |
+| `searchCellId` | production | this package: src/campaign/search-ledger-recording.ts:57 |
 | `searchCellSetDigest` | planned | doc: docs/search-ledger.md |
 | `searchEdgeId` | planned | doc: docs/search-ledger.md |
 | `searchHistoryCoverageRow` | production | this package: src/campaign/optimization-method.ts:14 |
 | `SearchHistoryRequiredError` | none | — |
-| `SearchLedgerConflictError` | production | this package: src/campaign/search-ledger.ts:33 |
+| `SearchLedgerConflictError` | production | this package: src/campaign/search-ledger.ts:34 |
 | `SearchLedgerError` | production | this package: src/campaign/estimate-node.ts:20 |
 | `SearchLedgerIntegrityError` | production | this package: src/campaign/search-ledger-file.ts:10 |
-| `searchNodeId` | production | this package: src/campaign/search-ledger-recording.ts:56 |
+| `searchNodeId` | production | this package: src/campaign/search-ledger-recording.ts:57 |
 | `searchPosterior` | planned | doc: docs/search-ledger.md |
 | `SearchRecorder` | production | this package: src/campaign/gepa-search-import.ts:23 |
-| `SearchState` | production | this package: src/campaign/search-ledger.ts:47 |
+| `SearchState` | production | this package: src/campaign/search-ledger.ts:48 |
 | `SearchStateView` | production | this package: src/campaign/estimate-node.ts:28 |
-| `searchTaskSetDigest` | production | this package: src/campaign/search-ledger-recording.ts:56 |
+| `searchTaskSetDigest` | production | this package: src/campaign/search-ledger-recording.ts:57 |
 | `searchUnitScores` | production | this package: src/campaign/estimate-node.ts:28 |
 | `selectDiscriminative` | none | only this package's tests: src/campaign/scenario-selection.test.ts:2 |
 | `sequentialDecide` | planned | doc: docs/experiment.md |
@@ -785,7 +786,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `traceAnalystQualityJudge` | production | this package: scripts/gepa-analyst-campaign.ts:74 |
 | `transientDispatchFailure` | planned | doc: docs/eval-surface-map.md |
 | `userStoryScoreboard` | production | blueprint-agent:scripts/experiments/eval/launch-scoreboard/run.ts |
-| `validateSearchLedgerEvent` | production | this package: src/campaign/search-ledger-recording.ts:27 |
+| `validateSearchLedgerEvent` | production | this package: src/campaign/search-ledger-recording.ts:28 |
 | `verifyCodeSurface` | production | agent-runtime:src/candidate-execution/builder.ts |
 | `verifyLoopProvenanceRecord` | none | only this package's tests: src/campaign/provenance-integrity.test.ts:5 |
 | `verifySearchHistoryArtifact` | production | this package: src/campaign/optimization-method.ts:14 |
@@ -794,7 +795,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./contract`
 
-65 value exports — 41 production, 14 planned, 10 none.
+62 value exports — 41 production, 14 planned, 7 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
@@ -808,9 +809,6 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `createReferenceEquivalenceJudge` | none | only this package's tests: src/reference-equivalence-judge.test.ts:13 |
 | `defaultProductionGate` | production | agent-app:src/eval-campaign/index.ts |
 | `defineAgentEval` | planned | example: examples/evaluate-a-change/index.ts:10 |
-| `diffGenerations` | none | only this package's tests: tests/contract-diff.test.ts:2 |
-| `diffRunBaselineToWinner` | none | only this package's tests: tests/contract-diff.test.ts:2 |
-| `diffRuns` | none | only this package's tests: tests/contract-diff.test.ts:2 |
 | `evalReportingSuite` | none | only this package's tests: tests/contract-eval-reporting-suite.test.ts:19 |
 | `evaluatePairedMeasurements` | production | this package: src/contract/profile-measured-comparison.ts:26 |
 | `externalTextOptimizationMethod` | production | agent-app:src/eval-campaign/index.ts |
@@ -1012,20 +1010,33 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./hosted`
 
-11 value exports — 7 production, 2 planned, 2 none.
+24 value exports — 20 production, 2 planned, 2 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
+| `admitSearchLedgerBatch` | planned | example: examples/hosted-ingest-server/server.ts:30 |
 | `createHostedClient` | production | traces:src/index.ts |
-| `EvalRunEventSchema` | planned | example: examples/hosted-ingest-server/server.ts:33 |
 | `HOSTED_WIRE_VERSION` | production | agent-dev-container:packages/sdk-data/src/sink/intelligence-sink.ts |
 | `hostedClientFromEnv` | production | traces:src/index.ts |
+| `HostedRequestError` | none | — |
 | `hostedTenantFromEnv` | production | creative-agent:eval/self-improve.ts |
-| `IngestEvalRunsRequestSchema` | production | this package: src/hosted/client.ts:19 |
-| `IngestResponseSchema` | production | this package: src/hosted/client.ts:19 |
-| `IngestTracesRequestSchema` | production | this package: src/hosted/client.ts:19 |
-| `InsightReportSchema` | none | only this package's tests: tests/contract-analyze-runs.test.ts:29 |
-| `TraceSpanEventSchema` | planned | example: examples/hosted-ingest-server/server.ts:33 |
+| `IngestResponseSchema` | production | this package: src/hosted/client.ts:22 |
+| `IngestSearchLedgerRequestSchema` | production | this package: src/hosted/client.ts:23 |
+| `IngestTracesRequestSchema` | production | this package: src/hosted/client.ts:22 |
+| `SEARCH_LEDGER_BATCH_MAX_BYTES` | production | this package: src/hosted/search-shipper.ts:18 |
+| `SEARCH_LEDGER_BATCH_MAX_LINES` | production | this package: src/hosted/search-shipper.ts:18 |
+| `SEARCH_LEDGER_INGEST_PATH` | production | this package: src/hosted/client.ts:23 |
+| `searchBlobPath` | production | this package: src/hosted/client.ts:23 |
+| `SearchBlobPutResponseSchema` | production | this package: src/hosted/client.ts:23 |
+| `searchLedgerArtifactRefs` | production | this package: src/hosted/search-shipper.ts:18 |
+| `SearchLedgerConflictSchema` | production | this package: src/hosted/client.ts:23 |
+| `searchLedgerHeadPath` | production | this package: src/hosted/client.ts:23 |
+| `SearchLedgerHeadSchema` | production | this package: src/hosted/client.ts:23 |
+| `SearchRunKindSchema` | production | this package: src/search-command.ts:13 |
+| `SearchShipConflictError` | production | this package: src/search-command.ts:14 |
+| `shipSearchLedger` | production | this package: src/contract/self-improve-method.ts:24 |
+| `startSearchShipper` | production | this package: src/contract/self-improve.ts:66 |
+| `TraceSpanEventSchema` | planned | example: examples/hosted-ingest-server/server.ts:29 |
 | `UnixNanoTimestampSchema` | none | — |
 
 ### `./jev`
@@ -1368,7 +1379,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `ROLLOUT_ROLES` | production | this package: src/rollout/interchange/harbor.ts:60 |
 | `ROLLOUT_SCHEMA` | production | this package: src/rollout/interchange/harbor.ts:60 |
 | `ROLLOUT_SPLITS` | production | this package: src/rollout/interchange/harbor.ts:60 |
-| `runRolloutReleaseCli` | production | this package: src/cli.ts:19 |
+| `runRolloutReleaseCli` | production | this package: src/cli.ts:20 |
 | `scoreOrigin` | production | this package: src/rollout/mint.ts:39 |
 | `scrubLines` | production | supervisor-lab:bench/vertical-rollout-package.ts |
 | `scrubRolloutLine` | none | only this package's tests: src/rollout/release/scrub.test.ts:4 |
@@ -1429,7 +1440,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `renderSupervisorRunMarkdown` | production | discovery-lab:experiments/0005-run-visibility/render-run.mjs |
 | `reportSupervisorRound` | planned | named in agent-runtime (bind not in the import graph) |
 | `rollupSupervisorRuns` | production | discovery-lab:tools/disco.mjs |
-| `runSupervisorRunCommand` | production | this package: src/cli.ts:20 |
+| `runSupervisorRunCommand` | production | this package: src/cli.ts:22 |
 | `RUNTIME_FAILED_STATUS` | none | — |
 | `runtimeSupervisorRunReader` | none | only this package's tests: src/supervisor-run/index.test.ts:2 |
 | `showMeasured` | production | this package: src/supervisor-run/render.ts:8 |
@@ -1774,7 +1785,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
-| `buildOpenApi` | production | this package: src/cli.ts:22 |
+| `buildOpenApi` | production | this package: src/cli.ts:24 |
 | `createApp` | planned | doc: docs/wire-protocol.md |
 | `dispatchRpc` | planned | doc: docs/wire-protocol.md |
 | `ErrorResponseSchema` | production | this package: src/wire/openapi.ts:15 |
@@ -1785,7 +1796,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `handleJudge` | production | this package: src/wire/rpc.ts:15 |
 | `handleListRubrics` | production | this package: src/wire/rpc.ts:15 |
 | `handleTracesIngest` | production | this package: src/wire/server.ts:20 |
-| `handleVersion` | production | this package: src/cli.ts:21 |
+| `handleVersion` | production | this package: src/cli.ts:23 |
 | `hashRubric` | production | this package: src/wire/handlers.ts:22 |
 | `HealthResponseSchema` | production | this package: src/wire/openapi.ts:15 |
 | `JudgeRequestSchema` | production | this package: src/wire/openapi.ts:15 |
@@ -1795,10 +1806,10 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `RUBRIC_VERSION_SCHEME` | none | — |
 | `RubricDimensionSchema` | none | only this package's tests: tests/wire/schemas.test.ts:12 |
 | `RubricSchema` | none | only this package's tests: tests/wire/schemas.test.ts:12 |
-| `runRpcBatch` | production | this package: src/cli.ts:23 |
-| `runRpcOnce` | production | this package: src/cli.ts:23 |
+| `runRpcBatch` | production | this package: src/cli.ts:25 |
+| `runRpcOnce` | production | this package: src/cli.ts:25 |
 | `startServer` | production | creative-agent:eval/ingestion-server.ts |
-| `startServerAsync` | production | this package: src/cli.ts:24 |
+| `startServerAsync` | production | this package: src/cli.ts:26 |
 | `TraceEventSchema` | planned | named in insurance-agent (bind not in the import graph) |
 | `TracesIngestRequestSchema` | production | this package: src/wire/openapi.ts:15 |
 | `TracesIngestResponseSchema` | production | this package: src/wire/openapi.ts:15 |

package/docs/search-ledger.md

@@ -134,13 +134,87 @@ const cellId = await recorder.allocateCell({ nodeId: root.nodeId, taskId, split:
 await recorder.settleCell({ cellId, outcome, accounting, identity, runRecord })
 ```
 
-`runOptimization({ searchLedger: { ledger, identity } })` and `selfImprove` record through the recorder and return the receipt on `searchHistory`.
+`runOptimization` and `selfImprove` run on the kernel below and return the receipt on `searchHistory`.
 The loop's scenarios are its proposer's feedback, so they are the train split; its promotions are budget decisions and it makes no claim.
 
 `gepaOptimizationMethod({ searchLedger: { identity } })` records GEPA's search when it finishes.
 `importGepaPopulation` turns the population into nodes and `correlated` edges and reports collapsed duplicates.
 `importExternalEvaluations` turns every callback evaluation into an `external` cell; a candidate GEPA evaluated but kept out of its population gets an `unknown` edge and is decided `pruned`.
 
+## Run a search: the kernel
+
+`runSearch` is the one loop every optimizer runs on.
+It separates three decisions: where to expand (a `SearchPolicy`), where to spend rollouts (a `SearchAllocator`), and what to claim (the claim step on the sealed test split).
+There is no generation barrier.
+A lane that frees up takes the next allocated cell: claim cells first, then rung and root cells, then screens, then train cells.
+The policy proposes when no cell waits, fewer than twice the lanes' capacity run, and the cap admits one proposal and its expected screens.
+
+```ts
+import { incumbent, runSearch, SearchRecorder, uniform } from '@tangle-network/agent-eval/campaign'
+
+const policy = incumbent({ patience: 3 })
+const allocation = uniform({ reps: 1 })
+const recorder = await SearchRecorder.open({ ledger }, {
+  ...opening,
+  policy: { expansion: policy.name, allocation: allocation.name, seed },
+})
+const { state, leader, reason } = await runSearch({
+  recorder, root, codec, policy, allocation, proposer, executor, maxExpansions: 10,
+})
+```
+
+The ports:
+
+- **Executor:** `lanes()` declares pools of slots, each `hard` (it enforces `cellUsd` per cell) or `estimate` (it cannot); `place(cell)` picks a cell's lane; `run(work)` runs one attempt and returns its outcome, accounting and identity; `adopt(work)` returns an attempt an earlier process finished, or null.
+  An environment fault is an `errored` outcome; a rejection stops the search.
+- **Proposer:** `propose({ parents, operator, leader })` returns children with a label, a rationale and optional typed `attribution`, plus the operation's accounting.
+  Its output is stored as a `proposal` blob on `operation-recorded` before any child is registered.
+- **Codec:** `node(recorder, artifact)` content-addresses an artifact, `diff` stores the parent-to-child diff, and `load` reads a node's artifact back.
+- **Policy:** `expand(view)` returns parents and an operator, or null to wait; `leader(view)` names the node the search keeps.
+  The view holds the policy split (selection, or train when a search has none) and no test cell.
+  `incumbent({ patience })` is the hill climb: it expands the leader once every earlier child is screened, and a node that scored every unit of its screen leads when it beats the leader on the units they share.
+  `crowdedFrontierParent({ seed })` draws the parent from the Pareto frontier by a seeded crowded tournament and keeps the incumbent's leader rule.
+- **Allocator:** `plan(state, nodeId)` lists the cells a node needs now; the kernel allocates the ones the ledger lacks.
+  `uniform({ reps })` gives the root every train and selection task as `root` cells, and every other node every train task (`train`) and selection task (`screen`).
+
+**Budget.**
+Every reservation passes the ledger's admission rule: committed spend plus open reservations plus the unspent claim reserve plus the new hold stays within `maxUsd`.
+The kernel checks `state.budget.headroomUsd` first and prices an expansion as one proposal plus `childrenPerProposal` screens.
+A hard lane holds its maximum; an estimate lane holds 1.5 times the p99 of its settled cells once 20 settled, else its prior.
+Spend above a hold is recorded as overspend, never refused.
+Expansion stops at `maxNodes`, `maxExpansions`, the deadline, after `patience` expansions without a new leader, when the cap cannot admit one more expansion, or when the proposer stops.
+Allocated cells still run; at the deadline the ones not yet started are cancelled.
+At close the leader is decided `selected` when it has a scored cell, every other undecided node `rejected` with its estimate against the leader, and the search closes with no claim.
+
+**Resume.**
+The ledger is the only checkpoint.
+Running the kernel again on an open ledger replays it and continues.
+An operation that started without a result is recorded `failed` with an unknown cost and a floor of 0, and the next proposal runs under a new operation id.
+A recorded proposal whose children were not all registered is finished from its stored output.
+A cell the ledger shows unsettled is offered to `executor.adopt` before its first dispatch, so an attempt that finished before the restart is recorded once and not run again.
+Aborting the `signal` pauses the search: in-flight cells are aborted, a scored result that still arrives is recorded, an attempt that ends in an error while the search stops stays unsettled (the error may be the interruption), and the ledger stays open.
+One kernel runs a ledger file at a time on a host: a second one is refused by a pid lock beside the ledger, and a killed holder's lock is reclaimed.
+A closed ledger returns its result; more work on a closed search is a new search.
+
+`scripts/search-sim.ts` runs the real kernel, ledger and policies over a seeded synthetic objective, proposer and executor, and `kill-resume` SIGKILLs it at random ledger positions and compares the resumed search with an uninterrupted one.
+
+## Ship a search
+
+A hosted store (Intelligence, or the reference receiver in `examples/hosted-ingest-server/`) receives a search through the [hosted ingest wire](./hosted-ingest-spec.md).
+The shipper reads the ledger file, uploads the blobs each entry names, and posts the entries from the store's head.
+A restarted shipper, a lost response, or a store that lost data continues from the store's head; a store that holds a different chain for the same search stops it with `SearchShipConflictError`.
+
+```ts
+import { shipSearchLedger, startSearchShipper } from '@tangle-network/agent-eval/hosted'
+
+const shipper = startSearchShipper({ tenant, ledger: { path: ledger.path, searchId }, runKind: 'optimization' })
+// ...the search appends to its ledger; the shipper tails it...
+const shipped = await shipper.stop() // { head, localLines, batches, blobs: { uploaded, missing, ... } }
+```
+
+`selfImprove({ hostedTenant, searchLedger })` does this for its own ledger.
+`agent-eval search ship <ledger> --run-kind optimization|eval` finishes or resumes a ship from a terminal.
+
 ## Receipts and `require-complete`
 
 `createSearchHistoryReceipt({ producerId, runId, ledger })` reads the ledger's bytes, replays them, and binds the byte digest, the audit digest, and a bounded summary.
@@ -169,6 +243,10 @@ Those claims need the sealed test split, the claim's power check, and held-out e
 - `src/campaign/search-state.ts`: `SearchState`, the invariants and read model, and the id functions.
 - `src/campaign/estimate-node.ts`: `estimateNode`, `estimateNodeFromCells` and `searchPosterior`.
 - `src/campaign/search-ledger-recording.ts`: `SearchRecorder` and the surface helpers.
+- `src/campaign/search-kernel.ts`: `runSearch`, the executor, proposer and codec ports, and `searchPolicyView`.
+- `src/campaign/search-policy.ts`: `SearchPolicy`, `incumbent` and `crowdedFrontierParent`.
+- `src/campaign/allocation.ts`: `SearchAllocator` and `uniform`.
+- `src/campaign/presets/run-optimization.ts`: `runOptimization` as a search on the kernel.
 - `src/campaign/gepa-search-import.ts`: the GEPA population and evaluation importers.
 - `src/campaign/search-history-receipt.ts`: receipts and admission.
 - `src/ledger-core/`: hashing, locking, durable appends, chain verification, and the trusted-head pin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-eval",
-  "version": "0.190.1",
+  "version": "0.192.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": {
@@ -221,7 +221,7 @@
     "@hono/node-server": "^2.1.1",
     "@tangle-network/agent-core": "^0.9.6",
     "@tangle-network/agent-interface": "^2.0.0",
-    "@tangle-network/agent-trace-contract": "^1.0.2",
+    "@tangle-network/agent-trace-contract": "^1.2.0",
     "hono": "^4.13.5",
     "linear-sum-assignment": "1.0.9",
     "re2js": "2.8.6",