@tangle-network/agent-eval 0.190.0 → 0.191.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) | 1496 |
-| distinct symbols | 1309 |
-| production | 975 |
-| planned | 269 |
-| none | 252 |
+| published value exports (subpath x symbol) | 1511 |
+| distinct symbols | 1324 |
+| production | 992 |
+| planned | 268 |
+| 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 |
@@ -223,7 +223,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `evaluateInterimReleaseConfidence` | production | agent-builder:scripts/eval.ts |
 | `evaluateOracles` | planned | doc: docs/verdicts.md |
 | `evaluateReleaseConfidence` | production | agent-knowledge:src/release.ts |
-| `evaluateTraceContract` | planned | doc: docs/verdicts.md |
+| `evaluateTraceContract` | planned | doc: docs/trace-contracts.md |
 | `expandProfileAxes` | production | agent-runtime:src/runtime/define-leaderboard.ts |
 | `explainTraceContract` | planned | doc: docs/trace-contracts.md |
 | `exportProductBenchmark` | production | creative-agent:eval/research-package.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 |
@@ -460,7 +460,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./analyst`
 
-129 value exports — 78 production, 20 planned, 31 none.
+131 value exports — 79 production, 19 planned, 33 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
@@ -489,6 +489,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `AnalystRegistry` | production | blueprint-agent:scripts/experiments/vb-multi-analyst.ts |
 | `analystUsageReceiptFromPrimeUsage` | production | this package: src/analyst/benchmark-runner-prime.ts:19 |
 | `appendVerificationArtifactsToOtlp` | production | this package: src/analyst/benchmark-public-data.ts:32 |
+| `askTraceQuestions` | none | only this package's tests: src/analyst/trace-questions.test.ts:7 |
 | `assertProposalFindings` | production | agent-runtime:src/improvement/code-execution.ts |
 | `behavioralAnalyst` | production | agent-dev-container:products/intelligence/api/src/lib/deep-trace-analyst.ts |
 | `bindAnalyst` | planned | doc: docs/trace-analysis.md |
@@ -497,6 +498,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `buildPrimeRepairPrompt` | planned | doc: docs/prime-analyst.md |
 | `buildSkillUsageReport` | none | only this package's tests: src/analyst/kinds/skill-usage.test.ts:2 |
 | `buildTraceToolsForGroup` | production | this package: src/analyst/kind-factory.ts:15 |
+| `citedSpansOnly` | none | only this package's tests: src/analyst/trace-questions.test.ts:7 |
 | `CODE_TRACE_BENCH_ANALYST_PROMPT` | production | this package: scripts/gepa-analyst-campaign.ts:60 |
 | `codeTraceBenchCase` | production | this package: scripts/gepa-analyst-campaign.ts:58 |
 | `codeTracerPredictionsToFindings` | production | this package: benchmarks/trace-analysis/codetracebench-glm52-20260730/summarize-codetracer.mjs:6 |
@@ -519,7 +521,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `DEFAULT_TRACE_ANALYST_OUTPUT_TOKENS` | production | this package: src/analyst/chat-trace-engine.ts:46 |
 | `defaultIsMaterial` | none | only this package's tests: src/analyst/analyst.test.ts:8 |
 | `defineCustomAnalyst` | planned | doc: docs/trace-analysis.md |
-| `defineTraceAnalyst` | planned | doc: docs/feature-guide.md |
+| `defineTraceAnalyst` | production | this package: src/analyst/trace-questions.ts:24 |
 | `deriveEfficiencyFindings` | none | only this package's tests: src/trace-analyst/behavioral-metrics.test.ts:2 |
 | `diffFindings` | production | agent-runtime:src/analyst-loop/run-analyst-loop.ts |
 | `effectiveAnalystProtocolSha256` | production | this package: src/analyst/benchmark-command-persistence.ts:31 |
@@ -582,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 |
@@ -642,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 |
 | --- | --- | --- |
@@ -660,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 |
@@ -677,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 | — |
@@ -722,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 |
@@ -753,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 |
@@ -783,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 |
@@ -792,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 |
 | --- | --- | --- |
@@ -806,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 |
@@ -1010,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`
@@ -1060,7 +1073,7 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 
 ### `./ledger-core`
 
-17 value exports — 16 production, 0 planned, 1 none.
+19 value exports — 18 production, 0 planned, 1 none.
 
 | symbol | consumer | evidence |
 | --- | --- | --- |
@@ -1073,12 +1086,14 @@ The `none` set was reviewed symbol by symbol on 2026-08-21. Four rules decided m
 | `LEDGER_HASH_PATTERN` | production | this package: src/campaign/final-evidence.ts:13 |
 | `LedgerCanonicalizationError` | none | only this package's tests: src/ledger-core/canonical.test.ts:5 |
 | `probeAtomicFileLock` | production | this package: src/campaign/single-run-lock.ts:17 |
-| `readTrustedHeadFile` | production | this package: src/ledger-core/journal.ts:40 |
+| `projectorSnapshotPathFor` | production | this package: src/ledger-core/journal.ts:48 |
+| `readProjectorSnapshotFile` | production | this package: src/ledger-core/journal.ts:48 |
+| `readTrustedHeadFile` | production | this package: src/ledger-core/journal.ts:55 |
 | `replayLedgerText` | production | this package: src/campaign/search-ledger.ts:23 |
-| `trustedHeadPathFor` | production | this package: src/ledger-core/journal.ts:40 |
+| `trustedHeadPathFor` | production | this package: src/ledger-core/journal.ts:55 |
 | `tryAcquireAtomicFileLock` | production | this package: src/campaign/single-run-lock.ts:17 |
 | `tryWithLedgerFileLock` | production | this package: src/campaign/search-ledger-file.ts:3 |
-| `verifyEntriesAgainstTrustedHead` | production | this package: src/ledger-core/journal.ts:40 |
+| `verifyEntriesAgainstTrustedHead` | production | this package: src/ledger-core/journal.ts:55 |
 | `withLedgerFileLock` | production | this package: src/analyst/benchmark-response-cache.ts:6 |
 | `writeLedgerFileAtomically` | production | this package: src/analyst/benchmark-response-cache.ts:6 |
 
@@ -1364,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 |
@@ -1425,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 |
@@ -1770,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 |
@@ -1781,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 |
@@ -1791,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

@@ -141,6 +141,23 @@ The loop's scenarios are its proposer's feedback, so they are the train split; i
 `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`.
 
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-eval",
-  "version": "0.190.0",
+  "version": "0.191.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",