@tangle-network/agent-eval 0.188.0 → 0.190.0

package/dist/types-C8VBbiw6.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-C8VBbiw6.js","names":[],"sources":["../src/ledger-core/deep-freeze.ts","../src/analyst/types.ts"],"sourcesContent":["/** Freeze a detached canonical-JSON graph. Canonicalization has already ruled out cycles.\n *\n * Lives outside canonical.ts so the analyst-benchmark implementation digest,\n * which covers canonical.ts, stays bound to the published benchmark evidence. */\nexport function deepFreezeCanonicalJson<T>(value: T): T {\n  if (value && typeof value === 'object' && !Object.isFrozen(value)) {\n    Object.freeze(value)\n    for (const nested of Object.values(value)) deepFreezeCanonicalJson(nested)\n  }\n  return value\n}\n","/**\n * Analyst contract — the missing orchestration layer over agent-eval's\n * existing analyzers (analyzeTraces, MultiLayerVerifier,\n * SemanticConceptJudge, JudgeFn, ...).\n *\n * Each existing primitive returns its own output shape. The Analyst\n * contract is the single envelope every primitive lifts into, so a\n * registry can run N analysts against a run and a single renderer can\n * compose findings without knowing which analyzer produced them.\n *\n * The contract is intentionally domain-agnostic: nothing here knows\n * about code, voice, RAG, or any particular agent stack. Analysts\n * declare what INPUT KIND they need (a trace store, an artifact dir,\n * a RunRecord, a JudgeInput, or `custom`), and the registry routes\n * the matching input from `AnalystRunInputs`.\n */\n\nimport { createHash } from 'node:crypto'\nimport type { CostLedgerHandle } from '../cost-ledger'\nimport type { RunCostProvenance, RunRecord, RunTokenUsage } from '../run-record'\nimport type { TraceAnalysisStore } from '../trace-analyst/store'\nimport type { JudgeInput } from '../types'\nimport type { ChatClient } from './chat-client'\n\n/**\n * Unified envelope every analyst emits. Schema-versioned so renderers\n * and time-series diffs survive future field additions.\n */\nexport interface AnalystFinding {\n  schema_version: '1.0.0'\n  /**\n   * Stable hash over identity-defining fields (analyst_id + canonical\n   * claim + area + optional subject). Two findings from two runs that\n   * \"are the same finding\" share this id — that's what `diffFindings`\n   * uses to compute appeared/disappeared sets across runs.\n   */\n  finding_id: string\n  analyst_id: string\n  produced_at: string\n  severity: AnalystSeverity\n  /**\n   * Coarse classification. Renderers group by this. Free-form so\n   * domain-specific analysts can introduce categories without a\n   * schema change ('agent-reasoning', 'verification', 'cost',\n   * 'tool-use', 'safety', 'latency', 'data-quality', ...).\n   */\n  area: string\n  claim: string\n  rationale?: string\n  evidence_refs: EvidenceRef[]\n  recommended_action?: string\n  validation_plan?: string\n  /** 0..1 — the analyst's own confidence. Not calibrated across analysts. */\n  confidence: number\n  /**\n   * Optional subject the finding is about — leaf id, agent id, request\n   * id. Included in finding_id when present so per-subject findings\n   * diff cleanly across runs.\n   */\n  subject?: string\n  /** True when this finding was lifted from a judge result rather than observed\n   *  directly in a trace or artifact. Descriptive only: proposal access is\n   *  controlled by `ProposalFinding.proposal_origin`. */\n  derived_from_judge?: boolean\n  /** Analyst-private extras; renderers ignore unless they know the analyst. */\n  metadata?: Record<string, unknown>\n}\n\n/** Finding severity. `AnalystSeverity` derives from this array, so the type\n *  and the schema that validates a finding cannot name different levels. */\nexport const ANALYST_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'] as const\n\nexport type AnalystSeverity = (typeof ANALYST_SEVERITIES)[number]\n\n/** Data sources that candidate generation may intentionally learn from. */\nexport type ProposalFindingOrigin = 'search' | 'production'\n\n/** A finding explicitly admitted as candidate-generation input. */\nexport type ProposalFinding = AnalystFinding & {\n  readonly proposal_origin: ProposalFindingOrigin\n}\n\nexport interface EvidenceRef {\n  /**\n   * Where the evidence lives. `span` and `event` refer to OTLP trace\n   * elements; `artifact` to a file inside the run's artifact tree;\n   * `finding` to another AnalystFinding (cross-analyst chaining);\n   * `metric` to a named scalar reading the renderer knows how to read.\n   */\n  kind: 'span' | 'event' | 'artifact' | 'finding' | 'metric'\n  uri: string\n  excerpt?: string\n}\n\n// ── Analyst contract ─────────────────────────────────────────────────\n\n/**\n * The discriminator the registry uses to pass the right input.\n * `custom` is the escape hatch — analysts that need something else\n * (e.g. an embedding cache, a partner SDK handle) read it from\n * `AnalystRunInputs.custom[<analyst id>]`.\n */\nexport type AnalystInputKind =\n  | 'trace-store'\n  | 'artifact-dir'\n  | 'run-record'\n  | 'judge-input'\n  | 'custom'\n\nexport interface AnalystCost {\n  /** `deterministic` analysts MUST NOT call the LLM. */\n  kind: 'deterministic' | 'llm'\n  /** Optional declared upper bound; the registry can enforce a budget. */\n  est_usd_per_run?: number\n  /** Models the analyst expects to use (informational). */\n  models?: string[]\n  /** Maximum post-cancellation wait for provider usage. Model analysts default to 5 seconds. */\n  settlement_timeout_ms?: number\n}\n\nexport interface AnalystRequirements {\n  /** Min number of shots / samples the analyst needs to produce signal. */\n  min_shots?: number\n  /** Capabilities the runtime must supply (e.g. ['network', 'gpu']). */\n  capabilities?: string[]\n}\n\n/**\n * What's passed to every analyst call. The registry resolves which\n * field the analyst's `inputKind` selects and asserts it's present.\n */\nexport interface AnalystRunInputs {\n  traceStore?: TraceAnalysisStore\n  artifactDir?: string\n  runRecord?: RunRecord\n  judgeInput?: JudgeInput\n  /** Keyed by analyst id; populated by callers that registered custom analysts. */\n  custom?: Record<string, unknown>\n}\n\nexport interface AnalystContext {\n  runId: string\n  /** Stable correlation id so logs from a single registry.run() share a tag. */\n  correlationId: string\n  /** Enforced wall-clock deadline (epoch ms). */\n  deadlineMs?: number\n  /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */\n  budgetUsd?: number\n  /** Shared paid-call account when the analyst runs inside a larger campaign. */\n  costLedger?: CostLedgerHandle\n  /** Attribution phase used when writing to the shared paid-call account. */\n  costPhase?: string\n  /**\n   * Shared chat client. Analysts that call an LLM go through this so\n   * the operator picks transport (sandbox-sdk | router | cli-bridge |\n   * direct-provider | mock) at the registry boundary without touching\n   * analyst code.\n   */\n  chat?: ChatClient\n  /**\n   * Findings from a prior run the operator wants the analyst to see as\n   * retrieval context. Kinds that take advantage of cross-run memory\n   * (failure-mode \"I saw this cluster last run\", knowledge-gap \"the wiki\n   * page I asked for is still missing\") render these into the actor's\n   * working set. Filtering is the operator's job: pass the slice that\n   * matches the analyst's id, or pass everything and let the kind\n   * filter. Empty / absent means no cross-run context.\n   */\n  priorFindings?: ReadonlyArray<AnalystFinding>\n  /**\n   * Findings emitted by analysts that completed earlier in this registry run.\n   * This is separate from `priorFindings`: upstream findings are dependency\n   * context for the current pass, while prior findings are cross-run memory.\n   * The registry populates this only when `RegistryRunOpts.chainFindings` is on.\n   */\n  upstreamFindings?: ReadonlyArray<AnalystFinding>\n  /**\n   * Report metered work independently of findings. This keeps an empty finding\n   * set from erasing token/cost telemetry. Multiple receipts are accumulated.\n   */\n  recordUsage?: (receipt: AnalystUsageReceipt) => void\n  /** Free-form runtime tags (env, host, op). Findings can echo these into metadata. */\n  tags?: Record<string, string>\n  /** Logger callback — analysts SHOULD prefer this over console.* for testability. */\n  log?: (msg: string, fields?: Record<string, unknown>) => void\n  /** Optional abort signal. Analysts SHOULD pass it through to LLM calls. */\n  signal?: AbortSignal\n  /**\n   * Optional live-execution port. A runtime that owns a sandbox or checkout\n   * fills it so an analyst can execute a bounded probe against the run's\n   * produced state instead of reasoning about it from the trace alone. This\n   * package defines only the port: no field here reaches for an agent loop,\n   * and an absent probe means the analyst works from recorded evidence.\n   */\n  probe?: ExecutionProbe\n}\n\n// ── Live-execution port ─────────────────────────────────────────────\n\n/** One bounded command an analyst asks the probe to run. */\nexport interface ExecutionProbeRequest {\n  command: string\n  /** Working directory inside the probed environment. */\n  cwd?: string\n  /** Hard wall-clock deadline for this one execution. */\n  timeoutMs: number\n  /** Bytes of combined output retained; the prober truncates beyond it. */\n  maxOutputBytes?: number\n  signal?: AbortSignal\n}\n\n/**\n * Typed outcome of one probe execution. `succeeded: false` is a PROBE failure\n * (the environment could not run the command); a command that ran and exited\n * non-zero is a successful observation with a non-zero `exitCode`.\n */\nexport type ExecutionProbeOutcome =\n  | {\n      succeeded: true\n      exitCode: number\n      stdout: string\n      stderr: string\n      durationMs: number\n      /** True when output was cut at `maxOutputBytes`. */\n      truncated: boolean\n    }\n  | { succeeded: false; error: { class: string; message: string } }\n\n/**\n * The seam a runtime fills to let analysts observe produced state live.\n * Implementations own sandboxing, credentials, and cleanup; analysts only\n * submit bounded requests and read typed outcomes.\n */\nexport interface ExecutionProbe {\n  /** One plain sentence naming what is being probed (e.g. a sandbox id). */\n  readonly description: string\n  execute(request: ExecutionProbeRequest): Promise<ExecutionProbeOutcome>\n}\n\n/**\n * The minimal contract. Concrete analysts can refine `TInput` so\n * implementations stay type-safe (e.g. a trace analyst's `TInput` is\n * `TraceAnalysisStore`); the registry passes the right field from\n * `AnalystRunInputs` based on `inputKind`.\n */\nexport interface Analyst<TInput = unknown> {\n  /** Stable identifier — appears in finding_id, telemetry, and registry exclusion lists. */\n  readonly id: string\n  /** Human-readable. One sentence. */\n  readonly description: string\n  readonly inputKind: AnalystInputKind\n  readonly cost: AnalystCost\n  readonly requires?: AnalystRequirements\n  /** Bump on breaking changes to claim wording or area so old finding_ids don't collide. */\n  readonly version: string\n  analyze(input: TInput, ctx: AnalystContext): Promise<AnalystFinding[]>\n}\n\n/** Metered work performed by one analyst call. */\nexport interface AnalystUsageReceipt {\n  /** Number of model-usage records observed at the provider boundary. */\n  calls: number | null\n  /** Null when the provider did not return token accounting. */\n  tokens: RunTokenUsage | null\n  /** Observed, estimated, or explicitly uncaptured dollar cost. */\n  cost: RunCostProvenance\n  /** Known lower bound when one or more calls have uncaptured cost. */\n  knownCostUsd?: number\n  /**\n   * Token counts the provider reported on only one side. Present exactly when\n   * `tokens` is null and at least one side WAS reported: `RunTokenUsage` has no\n   * nullable side, so a one-sided count cannot live in `tokens` without writing\n   * a zero nobody measured. Read it as a lower bound, never as a total — the\n   * field exists so a null `tokens` cannot hide a real count.\n   */\n  partialTokens?: { input: number | null; output: number | null }\n  /**\n   * True when the token counts were DERIVED by the transport (from character\n   * lengths, say) rather than measured by the model provider. `cost.kind` is\n   * `estimated` both for a rate estimate over exact tokens and for one over\n   * derived tokens; this is the field that separates them.\n   */\n  tokensEstimated?: boolean\n}\n\n// ── finding_id stability ─────────────────────────────────────────────\n\n/**\n * Compute the stable finding_id from the identity-defining fields.\n * Default implementation hashes {analyst_id, area, subject, normalized claim}.\n * Analysts that emit findings whose claim text varies per run (timestamps,\n * counts) SHOULD either: (a) pass an explicit `id_basis` to fix the hash,\n * or (b) move the variable part into `rationale`/`metadata` and keep the\n * `claim` static.\n */\nexport function computeFindingId(input: {\n  analyst_id: string\n  area: string\n  subject?: string\n  claim: string\n  /** Override the claim for hashing — use when the displayed claim has run-specific bits. */\n  id_basis?: string\n}): string {\n  const basis = JSON.stringify({\n    a: input.analyst_id,\n    r: input.area,\n    s: input.subject ?? '',\n    c: normalizeClaim(input.id_basis ?? input.claim),\n  })\n  return `f_${createHash('sha256').update(basis).digest('hex').slice(0, 20)}`\n}\n\nfunction normalizeClaim(c: string): string {\n  // Lowercase, collapse whitespace, strip trailing punctuation. Goal:\n  // \"Leaf X failed install\" and \"Leaf X failed install.\" hash the same.\n  return c\n    .toLowerCase()\n    .replace(/\\s+/g, ' ')\n    .replace(/[.!?;:,]+$/g, '')\n    .trim()\n}\n\n/**\n * Convenience factory: produce a fully-formed AnalystFinding with the\n * id computed automatically. Analyst code stays terse.\n */\nexport function makeFinding(\n  init: Omit<AnalystFinding, 'schema_version' | 'finding_id' | 'produced_at'> & {\n    id_basis?: string\n    produced_at?: string\n  },\n): AnalystFinding {\n  const { id_basis, produced_at, ...rest } = init\n  return {\n    schema_version: '1.0.0',\n    finding_id: computeFindingId({\n      analyst_id: rest.analyst_id,\n      area: rest.area,\n      subject: rest.subject,\n      claim: rest.claim,\n      id_basis,\n    }),\n    produced_at: produced_at ?? new Date().toISOString(),\n    ...rest,\n  }\n}\n\n/** Build a finding whose source is explicitly allowed during candidate generation. */\nexport function makeProposalFinding(\n  init: Omit<ProposalFinding, 'schema_version' | 'finding_id' | 'produced_at'> & {\n    id_basis?: string\n    produced_at?: string\n  },\n): ProposalFinding {\n  const { proposal_origin, ...finding } = init\n  return { ...makeFinding(finding), proposal_origin }\n}\n\n// ── Registry result envelope ────────────────────────────────────────\n\nexport interface AnalystRunSummary {\n  analyst_id: string\n  status: 'ok' | 'skipped' | 'failed'\n  /** Why skipped — missing input, budget exceeded, capability unmet. */\n  reason?: string\n  findings_count: number\n  latency_ms: number\n  /** Additive model usage and cost provenance for this analyst. */\n  usage: AnalystUsageReceipt\n  /** When `status='failed'`: the error class + message, never the full stack. */\n  error?: { class: string; message: string }\n}\n\nexport interface AnalystRunResult {\n  run_id: string\n  correlation_id: string\n  started_at: string\n  ended_at: string\n  findings: AnalystFinding[]\n  per_analyst: AnalystRunSummary[]\n  /** Total LLM cost in USD across all analysts in this registry.run(). */\n  total_cost_usd: number\n  /**\n   * Provenance for `total_cost_usd`. When uncaptured, the numeric field is only\n   * the known subtotal and must not be treated as the run's total spend.\n   */\n  total_cost_provenance?: RunCostProvenance\n}\n\n// ── Streaming event envelope ────────────────────────────────────────\n\n/**\n * Events emitted by `AnalystRegistry.runStream(...)` in real time as\n * the registry executes. UIs subscribe via `for await (const ev of\n * registry.runStream(...))`; `registry.run(...)` is a thin collector\n * over the same stream, so the two surfaces share their invariants.\n *\n * Per-finding events are intentionally omitted — analyzers are batch\n * operations (a recursive engine returns the full `findings:json[]` at the\n * end of the responder), so streaming inside one analyst would only\n * emit partial JSON consumers can't render. The kind-completion event\n * is the right granularity; subscribers wanting per-finding rendering\n * iterate `event.findings` themselves.\n */\nexport type AnalystRunEvent =\n  | {\n      type: 'run-started'\n      run_id: string\n      correlation_id: string\n      started_at: string\n      /** The ordered list of analyst ids the registry will run. */\n      analyst_ids: ReadonlyArray<string>\n    }\n  | {\n      type: 'analyst-skipped'\n      summary: AnalystRunSummary\n    }\n  | {\n      type: 'analyst-started'\n      analyst_id: string\n      started_at: string\n    }\n  | {\n      type: 'analyst-completed'\n      /** `summary.status` is `'ok'` for clean completion or `'failed'` for thrown analysts. */\n      summary: AnalystRunSummary\n      findings: ReadonlyArray<AnalystFinding>\n    }\n  | {\n      type: 'run-completed'\n      result: AnalystRunResult\n    }\n"],"mappings":";;;;;;AAIA,SAAgB,wBAA2B,OAAa;CACtD,IAAI,SAAS,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GAAG;EACjE,OAAO,OAAO,KAAK;EACnB,KAAK,MAAM,UAAU,OAAO,OAAO,KAAK,GAAG,wBAAwB,MAAM;CAC3E;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;AC4DA,MAAa,qBAAqB;CAAC;CAAY;CAAQ;CAAU;CAAO;AAAM;;;;;;;;;AAiO9E,SAAgB,iBAAiB,OAOtB;CACT,MAAM,QAAQ,KAAK,UAAU;EAC3B,GAAG,MAAM;EACT,GAAG,MAAM;EACT,GAAG,MAAM,WAAW;EACpB,GAAG,eAAe,MAAM,YAAY,MAAM,KAAK;CACjD,CAAC;CACD,OAAO,KAAK,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE;AAC1E;AAEA,SAAS,eAAe,GAAmB;CAGzC,OAAO,EACJ,YAAY,CAAC,CACb,QAAQ,QAAQ,GAAG,CAAC,CACpB,QAAQ,eAAe,EAAE,CAAC,CAC1B,KAAK;AACV;;;;;AAMA,SAAgB,YACd,MAIgB;CAChB,MAAM,EAAE,UAAU,aAAa,GAAG,SAAS;CAC3C,OAAO;EACL,gBAAgB;EAChB,YAAY,iBAAiB;GAC3B,YAAY,KAAK;GACjB,MAAM,KAAK;GACX,SAAS,KAAK;GACd,OAAO,KAAK;GACZ;EACF,CAAC;EACD,aAAa,gCAAe,IAAI,KAAK,EAAA,CAAE,YAAY;EACnD,GAAG;CACL;AACF;;AAGA,SAAgB,oBACd,MAIiB;CACjB,MAAM,EAAE,iBAAiB,GAAG,YAAY;CACxC,OAAO;EAAE,GAAG,YAAY,OAAO;EAAG;CAAgB;AACpD"}

package/docs/search-history-receipts.md

@@ -1,232 +0,0 @@
-# Complete optimization search history
-
-A selected prompt, profile, or patch is not a record of the search that produced it. A trustworthy optimizer must account for what it planned, tried, failed to run, rejected, and left unresolved before its winner is evaluated on untouched final cases.
-
-Eval already has one rich source of truth for that process: `SearchLedger`. This feature does not add another event log.
-
-```text
-SearchLedger JSONL                 canonical facts and rich evidence
-        │
-        ├── hash chain             mutation and truncation detection
-        ├── replay audit           planned denominator and unresolved work
-        └── SearchHistoryReceipt   bounded proof envelope
-                    │
-                    └── compareOptimizationMethods({
-                          searchHistoryPolicy: 'require-complete'
-                        })
-```
-
-## ELI5
-
-`SearchLedger` is the sealed laboratory notebook. `SearchHistoryReceipt` is the small signed cover sheet saying which notebook, which run, and whether the notebook accounts for the whole planned experiment.
-
-The cover sheet does not copy every page. To inspect a candidate, failed attempt, missing task id, decision, or accounting gap, open the notebook.
-
-## What the receipt contains
-
-The receipt is bounded by the contract rather than by search length. It carries:
-
-- the producer and concrete run identity;
-- a content-addressed reference to the canonical ledger bytes;
-- the digest of the exact replay audit;
-- counts and terminal state needed to classify completeness;
-- short, count-based incompleteness reasons;
-- its own RFC 8785 SHA-256 digest.
-
-It does not carry event arrays, candidate inventories, attempt records, decisions, or lists of every missing id. Those remain in `SearchLedgerReplay`.
-
-## Create a receipt
-
-Create receipts only from the result returned by `SearchLedger.replay()`:
-
-```ts
-import {
-  createSearchHistoryReceipt,
-  openSearchLedger,
-} from '@tangle-network/agent-eval/campaign'
-
-const searchLedger = openSearchLedger({
-  path: '/runs/gepa/search-ledger.jsonl',
-  campaignId: 'gepa-run-42',
-})
-
-const replay = await searchLedger.replay()
-const receipt = createSearchHistoryReceipt({
-  producerId: 'gepa',
-  runId: 'gepa-run-42',
-  ledger: {
-    role: 'search-ledger',
-    uri: 'artifact://gepa-run-42/search-ledger.jsonl',
-    sha256: ledgerArtifactDigest,
-    byteLength: ledgerArtifactBytes,
-  },
-  replay,
-})
-```
-
-First-party optimizers do this for you. Application code should not hand-author receipt JSON.
-
-## Record a search from the loop
-
-`runOptimization()` and `selfImprove()` accept `searchLedger` and return the receipt on `searchHistory`:
-
-```ts
-import { openSearchLedger, runOptimization } from '@tangle-network/agent-eval/campaign'
-
-const result = await runOptimization({
-  // ...scenarios, dispatchWithSurface, judges, proposer, populationSize, maxGenerations, runDir
-  searchLedger: {
-    ledger: openSearchLedger({ path: `${runDir}/search-ledger.jsonl`, campaignId: runId }),
-    identity: {
-      agent: { uri: 'git+https://github.com/acme/agent.git', revision: agentCommit },
-      proposer: { kind: 'deterministic', source: { uri: proposerUri, revision: proposerCommit } },
-      search: { uri: searchUri, revision: searchCommit },
-      model: { provider: 'openai', snapshot: 'gpt-5.4@2026-06-01' },
-    },
-  },
-})
-```
-
-The loop emits the plan, one candidate-generation operation per generation, one registration per candidate with the exact parent it mutated, one task attempt per designed cell, one decision per candidate, and the terminal event.
-
-`identity` carries what the ledger requires and a campaign cannot infer: immutable revisions for the agent, proposer, and search implementations, plus the model the agent runs. A measured value wins wherever execution reported one; a cell that ran a moving model alias is refused rather than recorded as an immutable identity.
-
-`gepaOptimizationMethod({ searchLedger: { identity } })` records GEPA's own candidate population into the same ledger, so a comparison under `require-complete` accepts it.
-
-## Extend a plan for a rolling search
-
-A search whose length is not known when it starts appends `search-plan-extended` with the extra candidate slots and operations.
-The first plan event stays first, the effective plan is the merge, and the generation invariant continues across rounds: a candidate whose parent is a round-one candidate is generation 2, not a restarted 0.
-
-The planned task denominator does not extend. Extending it would reopen candidates that already closed their tasks.
-
-A search still uses one ledger. A parent from an earlier ledger enters as a generation-0 `candidate-registered` whose surface artifact references the prior ledger, because a cross-file parent cannot be replayed and verified from these bytes.
-
-## Complete means the planned denominator is closed
-
-A receipt is complete only when canonical replay reports:
-
-- a search plan;
-- a terminal `search-completed` event;
-- no unresolved candidate slots;
-- no missing planned task outcomes;
-- no missing planned operations;
-- no pending candidate decisions;
-- a terminal status of `selected` or `all-rejected`.
-
-A first-party recorder appends the terminal event only when replay already accounts for the whole planned denominator. An interrupted run, or a candidate that left a designed cell unscored, stays `in-progress` and reports the exact gap.
-
-Cost completeness remains a separate contract. Unknown spend stays unknown; it is never converted into zero merely because search history is complete.
-
-## Compare methods without exposing final cases
-
-Existing callers remain compatible. Missing history is reported:
-
-```ts
-const comparison = await compareOptimizationMethods({
-  methods,
-  trainScenarios,
-  selectionScenarios,
-  testScenarios,
-  // existing options
-})
-
-console.log(comparison.searchHistory)
-```
-
-Autonomous or publication-grade callers fail closed:
-
-```ts
-const comparison = await compareOptimizationMethods({
-  methods,
-  trainScenarios,
-  selectionScenarios,
-  testScenarios,
-  searchHistoryPolicy: 'require-complete',
-  // existing options
-})
-```
-
-`selfImprove({ method })` accepts the same `searchHistoryPolicy` and `searchHistoryVerification` options.
-Both workflows use the same method preparation, result validation, cost reconciliation, and history admission.
-`selfImprove` returns `searchHistoryCoverage`; comparison returns coverage for every method.
-The default remains `allow-missing` with receipt verification.
-
-### Verify referenced history before final assessment
-
-Set `searchHistoryVerification: 'ledger'` to require the referenced bytes, even with `allow-missing`.
-Combine it with `require-complete` to require both verified bytes and complete history.
-
-```ts
-const comparison = await compareOptimizationMethods({
-  // ...methods, partitions, dispatch, judges, runDir
-  searchHistoryPolicy: 'require-complete',
-  searchHistoryVerification: 'ledger',
-  storage,
-})
-```
-
-Eval reads the receipt URI through `storage.read`.
-A `file:` URI becomes a local path; other URIs remain opaque storage keys.
-A custom `CampaignStorage` can resolve retained artifacts without another ledger implementation.
-Missing bytes, length or digest mismatches, invalid chains, and replay discrepancies refuse final dispatch.
-A verified coverage row carries `ledgerVerified: true`.
-Receipt-only coverage does not make that claim.
-
-Existing search recorders compute `ledger.sha256` with `hashCanonical` over the complete JSONL string.
-It hashes that string's canonical JSON encoding, rather than the raw UTF-8 file.
-Verification preserves this existing identity scheme.
-`byteLength` measures the UTF-8 JSONL bytes.
-
-Every method finishes optimization before the first untouched-final-test dispatch. Under `require-complete`, missing, malformed, producer-mismatched, interrupted, or denominator-incomplete evidence aborts at that boundary.
-
-## Verification boundary
-
-`verifySearchHistoryReceipt()` verifies the bounded envelope and its canonical digest.
-
-`assertSearchHistoryMatchesReplay()` additionally proves that the envelope was derived from the supplied canonical replay.
-
-`verifySearchHistoryArtifact(receipt, storage)` resolves bytes and runs both checks through the canonical journal codec.
-The two receipt-only functions do not fetch or retain the ledger artifact. A skeptical consumer must resolve `receipt.ledger`, verify its digest and byte length, replay it with `SearchLedger`, and then call `assertSearchHistoryMatchesReplay()`.
-
-The receipt does not prove that:
-
-- the optimizer searched intelligently;
-- a candidate is correct, safe, or novel;
-- the winner generalizes;
-- an external source identity is honest;
-- knowledge caused an improvement;
-- the artifact URI will remain available.
-
-Those claims require held-out evaluation, artifact retention, provenance verification, knowledge-use evidence, and causal experiments.
-
-## Ownership
-
-- **Eval** owns search evidence, completeness, held-out comparison, statistics, and release decisions.
-- **Runtime** owns execution, checkpoints, cancellation, and resume orchestration while referencing Eval evidence.
-- **Knowledge** owns what information was visible, retrieved, and selected for use.
-- **Interface** owns portable profiles, diffs, identities, and digest primitives.
-- **SDKs** should automate these owner contracts, not copy their types or introduce another optimizer loop.
-
-## Bind final measurements to execution evidence
-
-Both complete-method workflows accept optional `evidence: CampaignEvidenceContext`.
-It requires the caller's pursuit, evaluator, environment, authority, and attestation provenance.
-Eval does not infer independent authority or certify those external declarations.
-
-Each measured baseline and winner receives the existing `EvidenceReceipt` format.
-Eval derives candidate, input-set, output, and result digests from the executed surface and complete campaign.
-A missing or deferred final measurement cannot produce a receipt.
-Receipts describe measurements; they do not override the release gate or replace the method's selected winner.
-
-`createCampaignEvidenceReceipt` on `/experiment` provides the same binding for other complete campaign consumers.
-Changing an output changes its output digest; changing a judge result changes its measurement digest.
-The final receipt retains caller authority, including `candidate-self-report`, without upgrading it.
-
-## Implementation ownership
-
-`src/campaign/search-ledger.ts` owns validation, canonical event normalization, and composition with the shared ledger journal.
-`search-ledger-projector.ts` owns campaign replay invariants and audit projection.
-`search-ledger-types.ts` defines the shared data contracts, reexported through the existing facade.
-`search-ledger-ordering.ts` shares artifact identity and deterministic string ordering between normalization and replay.
-The journal in `src/ledger-core` owns hashing, locking, durable appends, and chain verification.