@tangle-network/agent-eval 0.114.0 → 0.115.0

package/dist/campaign/index.d.ts

@@ -1,17 +1,17 @@
-import { S as SignedManifest, B as BackendIntegrityReport, C as CompletionRequirement, R as RuntimeEventLike, a as CompletionVerdict, P as ProducedState, b as CorrectnessChecker } from '../pre-registration-CTQbZbpX.js';
-export { L as LlmJudgeDimension, c as LlmJudgeOptions, l as llmJudge } from '../pre-registration-CTQbZbpX.js';
+import { P as PairedArmsComparison, S as SignedManifest, B as BackendIntegrityReport, C as CompletionRequirement, R as RuntimeEventLike, a as CompletionVerdict, b as ProducedState, c as CorrectnessChecker } from '../pre-registration-oNItiRBb.js';
+export { L as LlmJudgeDimension, d as LlmJudgeOptions, l as llmJudge } from '../pre-registration-oNItiRBb.js';
 import { A as AnalyzeTracesOptions, a as AnalyzeTracesInput, b as AnalyzeTracesResult } from '../analyst-C8HHvfJp.js';
 import { S as Scenario, M as MutableSurface, D as DispatchContext, b as JudgeConfig, g as Gate, e as GenerationRecord, J as JudgeScore, L as LabeledScenarioStore, s as LabeledScenarioWrite, t as LabeledScenarioSampleArgs, u as LabeledScenarioRecord, v as LabelTrust, f as SurfaceProposer, w as ProposedCandidate, x as ProposeContext, m as CodeSurface, y as LabeledScenarioSource, C as CampaignResult } from '../types-CgSlO6wT.js';
 export { i as CampaignAggregates, j as CampaignArtifactWriter, k as CampaignCellResult, l as CampaignCostMeter, z as CampaignTokenUsage, d as CampaignTraceWriter, c as DispatchFn, n as GateContext, h as GateDecision, G as GateResult, o as GenerationCandidate, A as JudgeAggregate, a as JudgeDimension, p as Mutator, O as OptimizationProposer, q as OptimizerConfig, P as ParetoParent, R as RedactionStatus, B as ScenarioAggregate, r as SessionScript, T as TraceSpan, E as isProposedCandidate, F as labelTrustRank } from '../types-CgSlO6wT.js';
 import { C as CampaignRunPlan, P as PlanCampaignRunOptions, b as RunCampaignOptions, c as RunImprovementLoopOptions } from '../gepa-DolL_Fko.js';
 export { f as CampaignRunPlanCell, h as GepaProposerConstraints, G as GepaProposerOptions, O as OpenAutoPrOptions, i as OpenAutoPrResult, a as RunImprovementLoopResult, R as RunOptimizationOptions, j as RunOptimizationResult, k as countSentenceEdits, l as defaultRenderDiff, m as extractH2Sections, g as gepaProposer, o as openAutoPr, p as planCampaignRun, r as runCampaign, d as runImprovementLoop, n as runOptimization } from '../gepa-DolL_Fko.js';
+import { a as PairedBootstrapResult, E as EProcessState } from '../statistics-oUbOJe-S.js';
 import { C as CampaignStorage } from '../storage-Dw_f7WMt.js';
 export { f as fsCampaignStorage, i as inMemoryCampaignStorage } from '../storage-Dw_f7WMt.js';
 export { A as AxisEvidence, a as AxisVerdict, B as BuildEvidenceVectorOptions, l as BuildLoopProvenanceArgs, D as DefaultProductionGateOptions, m as EmitLoopProvenanceArgs, n as EmitLoopProvenanceResult, E as EvidenceVector, b as EvolutionaryProposerOptions, H as HeldOutGateOptions, o as LoopProvenanceBackend, q as LoopProvenanceCandidate, L as LoopProvenanceRecord, O as ObjectiveSource, c as ParetoSignificanceGateOptions, P as PowerPreflight, s as PowerPreflightOptions, d as PromotionObjective, e as PromotionPolicy, R as RunEvalOptions, f as buildEvidenceVector, t as buildLoopProvenanceRecord, g as composeGate, h as defaultProductionGate, u as emitLoopProvenance, i as evolutionaryProposer, j as heldOutGate, v as loopProvenanceSpans, p as paretoPolicy, k as paretoSignificanceGate, w as powerPreflight, x as provenanceRecordPath, y as provenanceSpansPath, r as runEval } from '../provenance-BZmpWmn4.js';
-import { E as EProcessState, a as PairedBootstrapResult } from '../statistics-oUbOJe-S.js';
 import { L as LlmClientOptions } from '../llm-client-DyqEH4jH.js';
 import { AgentProfile } from '@tangle-network/agent-interface';
-import { A as AgentEvalError } from '../errors-oeQrLqXC.js';
+import { A as AgentEvalError, V as ValidationError } from '../errors-oeQrLqXC.js';
 import { b as RunSplitTag, R as RunRecord } from '../run-record-DksGsfgv.js';
 import { b as PolicyEdit, F as FindingToPolicyEditOptions, d as PolicyEditAdmissionOptions, c as PolicyEditAdmission } from '../policy-edit-az2qRmvN.js';
 import { T as TraceAnalystKindSpec, A as AnalystFinding } from '../kind-factory-20hcaYpf.js';
@@ -23,12 +23,12 @@ import '../store-C1YxJDEK.js';
 import '../dataset-NENEzRgk.js';
 import '../store-BsVi7ncX.js';
 import '../schema-SGWcK9wa.js';
+import '../judge-calibration-7C-IDmKr.js';
+import '../types-C7DGg5ex.js';
 import '../hosted/index.js';
 import '../insight-report-D4cXFsLt.js';
 import '../summary-report-Bz-0-t8v.js';
 import '../failure-cluster-C48PiReX.js';
-import '../judge-calibration-7C-IDmKr.js';
-import '../types-C7DGg5ex.js';
 import 'zod';
 
 /**
@@ -375,6 +375,278 @@ interface FailureModeRecallJudgeOptions {
  */
 declare function failureModeRecallJudge(opts?: FailureModeRecallJudgeOptions): JudgeConfig<AnalystArtifact, AnalystScenario>;
 
+/** Whether one candidate attempt produced a usable executable outcome. */
+type CrossSurfaceAttemptCompleteness = 'complete' | 'missing' | 'invalid';
+/** One independently proposed change on one caller-defined surface. */
+interface CrossSurfaceComponent {
+    componentId: string;
+    surfaceId: string;
+    /** Explicitly controls whether this component may anchor the best-single arm. */
+    bestSingleEligible: boolean;
+}
+/** Immutable identity for a single candidate or a materialized composition. */
+interface CrossSurfaceCandidate {
+    candidateId: string;
+    componentIds: string[];
+    contentHash: string;
+    artifactBytes: number;
+}
+/** Per-component trace evidence captured during one task attempt. */
+interface CrossSurfaceComponentEvidence {
+    componentId: string;
+    /** null means the trace could not establish whether the component fired. */
+    fired: boolean | null;
+    /** null means the trace could not establish whether the component changed behavior. */
+    effectObserved: boolean | null;
+}
+/**
+ * Canonical per-task input row. Consumers may extend this interface with
+ * receipt, trace, retry, or failure details; the report preserves the original
+ * row object rather than projecting those details away.
+ */
+interface CrossSurfaceTaskRow {
+    taskId: string;
+    candidateId: string;
+    /** Repeated here so every persisted row remains self-describing. */
+    componentIds: string[];
+    completeness: CrossSurfaceAttemptCompleteness;
+    pass: boolean | null;
+    score: number | null;
+    /**
+     * Per-attempt deployment measurements. Every declared metric must have a
+     * known, non-negative value. Proposal, analysis, and selection spend belongs
+     * in the search ledger rather than being spread across task cells.
+     */
+    cost: Record<string, number | null>;
+    componentEvidence: CrossSurfaceComponentEvidence[];
+    /** Required for missing or invalid attempts; forbidden for complete attempts. */
+    rejectReason: string | null;
+}
+interface CrossSurfaceBootstrapPolicy {
+    seed: number;
+    resamples: number;
+    confidence: number;
+}
+/** Predeclared candidate eligibility and composition policy. */
+interface CrossSurfaceSelectionPolicy {
+    minimumFiringTasks: number;
+    minimumEffectTasks: number;
+    requireObservedFiring: boolean;
+    requireObservedEffect: boolean;
+    /** Only named metrics are constrained; all declared metrics are still reported. */
+    maximumMedianCostRatioToBaseline: Record<string, number>;
+    /** A smaller terminal bundle is reported but cannot become the selected arm. */
+    minimumBundleComponents: number;
+}
+interface AnalyzeCrossSurfaceInteractionsInput<TRow extends CrossSurfaceTaskRow = CrossSurfaceTaskRow> {
+    components: readonly CrossSurfaceComponent[];
+    candidates: readonly CrossSurfaceCandidate[];
+    rows: readonly TRow[];
+    baselineCandidateId: string;
+    /** Exact shared task axis and its canonical output order. */
+    taskOrder: readonly string[];
+    /** Canonical materialization order for component sets and the naive stack. */
+    componentOrder: readonly string[];
+    /** Final deterministic tie-break; lower index wins. */
+    candidateOrder: readonly string[];
+    /** Declares every cost key and the order used for cost tie-breaks. */
+    costMetricOrder: readonly string[];
+    bootstrap: CrossSurfaceBootstrapPolicy;
+    selection: CrossSurfaceSelectionPolicy;
+}
+interface CrossSurfaceDistribution {
+    n: number;
+    min: number;
+    median: number;
+    mean: number;
+    max: number;
+    total: number;
+}
+interface CrossSurfaceEvidenceBreakdown {
+    componentId: string;
+    observedTaskIds: string[];
+    notObservedTaskIds: string[];
+    unobservedTaskIds: string[];
+}
+interface CrossSurfaceCandidateEvidence {
+    byComponent: CrossSurfaceEvidenceBreakdown[];
+    allObservedTaskIds: string[];
+    someObservedTaskIds: string[];
+    noneObservedTaskIds: string[];
+    unobservedTaskIds: string[];
+}
+type CrossSurfaceIneligibilityReason = 'missing_attempt' | 'invalid_attempt' | 'baseline_outcome_missing' | 'benefit_not_greater_than_regression' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfaceEligibility {
+    eligible: boolean;
+    reasons: CrossSurfaceIneligibilityReason[];
+}
+interface CrossSurfaceCandidateOutcome {
+    resolvedTaskIds: string[];
+    failedTaskIds: string[];
+    missingTaskIds: string[];
+    invalidTaskIds: string[];
+    benefitTaskIds: string[];
+    regressionTaskIds: string[];
+    comparisonMissingTaskIds: string[];
+    netBenefit: number;
+}
+interface CrossSurfaceCandidateSummary {
+    candidate: CrossSurfaceCandidate;
+    outcome: CrossSurfaceCandidateOutcome;
+    score: CrossSurfaceDistribution | null;
+    costs: Record<string, CrossSurfaceDistribution>;
+    firing: CrossSurfaceCandidateEvidence;
+    effect: CrossSurfaceCandidateEvidence;
+    /** Reuses the package's paired McNemar/risk-difference/bootstrap statistics. */
+    comparisonToBaseline: PairedArmsComparison | null;
+    /** null only for the fixed baseline. */
+    eligibility: CrossSurfaceEligibility | null;
+}
+interface CrossSurfaceRelativeCost {
+    treatmentMedian: number;
+    comparatorMedian: number;
+    medianDelta: number;
+    /** null when the comparator median is zero but the treatment median is not. */
+    medianRatio: number | null;
+}
+interface CrossSurfaceCandidateComparison {
+    comparatorCandidateId: string;
+    treatmentCandidateId: string;
+    winsTaskIds: string[];
+    regressionTaskIds: string[];
+    missingTaskIds: string[];
+    paired: PairedArmsComparison;
+    relativeCost: Record<string, CrossSurfaceRelativeCost>;
+}
+interface CrossSurfacePairEvidence {
+    bothTaskIds: string[];
+    leftOnlyTaskIds: string[];
+    rightOnlyTaskIds: string[];
+    neitherTaskIds: string[];
+    unobservedTaskIds: string[];
+}
+interface CrossSurfaceInteractionTask {
+    taskId: string;
+    /** Composition minus the additive expectation from the baseline and singles. */
+    passInteraction: number | null;
+    scoreInteraction: number | null;
+}
+interface CrossSurfaceInteractionEffect {
+    perTask: CrossSurfaceInteractionTask[];
+    n: number;
+    nMissing: number;
+    meanPassInteraction: number | null;
+    meanScoreInteraction: number | null;
+    passBootstrap: PairedBootstrapResult | null;
+    scoreBootstrap: PairedBootstrapResult | null;
+}
+type CrossSurfacePairIncompatibilityReason = 'constituent_not_ready' | 'pair_incomplete' | 'baseline_regression' | 'interference' | 'no_incremental_resolution' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfacePairCompatibility {
+    compatible: boolean;
+    reasons: CrossSurfacePairIncompatibilityReason[];
+    betterSingleCandidateId: string;
+}
+interface CrossSurfacePairwiseEntry {
+    componentIds: [string, string];
+    singleCandidateIds: [string, string];
+    compositionCandidateId: string;
+    benefitTaskIds: string[];
+    regressionTaskIds: string[];
+    synergyTaskIds: string[];
+    interferenceTaskIds: string[];
+    incrementalVsConstituents: [CrossSurfaceCandidateComparison, CrossSurfaceCandidateComparison];
+    relativeCostToBaseline: Record<string, CrossSurfaceRelativeCost>;
+    firing: CrossSurfacePairEvidence;
+    effect: CrossSurfacePairEvidence;
+    interaction: CrossSurfaceInteractionEffect;
+    compatibility: CrossSurfacePairCompatibility;
+}
+interface CrossSurfaceRankedSingle {
+    rank: number;
+    candidateId: string;
+    componentId: string;
+}
+interface CrossSurfaceBestSingleSelection {
+    candidateId: string;
+    componentId: string;
+    ranking: CrossSurfaceRankedSingle[];
+}
+interface CrossSurfaceNaiveStackSelection {
+    candidateId: string;
+    componentIds: string[];
+}
+type CrossSurfaceAdditionRejectionReason = 'pair_incompatible' | 'full_bundle_not_evaluated' | 'bundle_incomplete' | 'baseline_regression' | 'no_incremental_resolution' | 'incremental_regression' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfaceAdditionDecision {
+    additionCandidateId: string;
+    additionComponentId: string;
+    bundleCandidateId: string | null;
+    incrementalResolutionTaskIds: string[];
+    incrementalRegressionTaskIds: string[];
+    incrementalMedianCost: Record<string, number> | null;
+    eligible: boolean;
+    selected: boolean;
+    reasons: CrossSurfaceAdditionRejectionReason[];
+}
+interface CrossSurfaceCompositionStep {
+    fromCandidateId: string;
+    retainedComponentIds: string[];
+    considered: CrossSurfaceAdditionDecision[];
+    selectedCandidateId: string | null;
+}
+/** One deterministic growth path starting from a compatible two-surface seed. */
+interface CrossSurfaceInteractionPath {
+    seedCandidateId: string;
+    terminalCandidateId: string;
+    terminalComponentIds: string[];
+    qualified: boolean;
+    steps: CrossSurfaceCompositionStep[];
+}
+interface CrossSurfaceInteractionAwareSelection {
+    /** Compatible pair that seeded the selected deterministic growth path. */
+    seedCandidateId: string;
+    /** Candidate reached by the winning path, even if the minimum size is not met. */
+    terminalCandidateId: string;
+    terminalComponentIds: string[];
+    /** null when no path produced a qualifying multi-component bundle. */
+    selectedCandidateId: string | null;
+    qualified: boolean;
+    /** Every compatible pair seed is retained so seed choice cannot hide an interaction. */
+    evaluatedPaths: CrossSurfaceInteractionPath[];
+    /** Convenience alias for the winning path's steps. */
+    steps: CrossSurfaceCompositionStep[];
+}
+interface CrossSurfaceSelections {
+    bestSingle: CrossSurfaceBestSingleSelection | null;
+    naiveStack: CrossSurfaceNaiveStackSelection | null;
+    interactionAware: CrossSurfaceInteractionAwareSelection | null;
+}
+interface CrossSurfaceInteractionReport<TRow extends CrossSurfaceTaskRow = CrossSurfaceTaskRow> {
+    taskIds: string[];
+    componentIds: string[];
+    candidateIds: string[];
+    costMetrics: string[];
+    /** Canonical candidate × task order; no input row is dropped. */
+    rows: TRow[];
+    missingAttempts: TRow[];
+    invalidAttempts: TRow[];
+    candidates: CrossSurfaceCandidateSummary[];
+    pairwise: CrossSurfacePairwiseEntry[];
+    selections: CrossSurfaceSelections;
+}
+
+/**
+ * Task-paired comparison and deterministic selection for independently
+ * proposed agent surfaces. Unlike factorial cell-mean attribution, every
+ * benefit, regression, and interaction remains attached to its task row.
+ */
+
+/**
+ * Build the complete cross-surface evidence matrix and derive all three frozen
+ * candidates. The task/candidate/component orders are part of the input so
+ * neither insertion order nor an after-the-fact tie-break can change a result.
+ */
+declare function analyzeCrossSurfaceInteractions<TRow extends CrossSurfaceTaskRow>(input: AnalyzeCrossSurfaceInteractionsInput<TRow>): CrossSurfaceInteractionReport<TRow>;
+
 type EvalFixtureValidationMode = 'vitest' | 'none';
 interface EvalFixtureFile {
     path: string;
@@ -2145,6 +2417,338 @@ interface CampaignBreakdown {
  *  on: mean score per judge dimension + per-scenario composite. */
 declare function campaignBreakdown<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): CampaignBreakdown;
 
+declare class SearchLedgerError extends ValidationError {
+}
+declare class SearchLedgerIntegrityError extends SearchLedgerError {
+}
+declare class SearchLedgerConflictError extends SearchLedgerError {
+}
+
+/**
+ * Durable append-only audit log for improvement searches.
+ *
+ * Existing campaign artifacts keep their own rich records: `RunRecord` owns a
+ * measured run, `Lineage` owns the candidate graph, and `CostLedger` owns
+ * per-call accounting. This ledger does not copy those structures. It binds
+ * their immutable ids and receipts into one replayable event stream so a
+ * search can answer, after a crash, exactly which candidates and task attempts
+ * existed, which surfaces actually fired, what they cost, and why they were
+ * selected or rejected.
+ *
+ * The file format is canonical JSONL with a SHA-256 hash chain. Every append is
+ * serialized across processes, fsynced before acknowledgement, and idempotent
+ * by `eventId`. A malformed, non-canonical, truncated, reordered, or conflicting
+ * log fails loudly; the implementation never skips a bad row.
+ */
+
+declare const SEARCH_LEDGER_SCHEMA: "tangle.search-ledger.v1";
+type SearchLedgerHash = `sha256:${string}`;
+type SearchSurfaceKind = 'prompt' | 'tool-contract' | 'runtime-config' | 'memory' | 'knowledge' | 'agent-profile' | 'code' | 'deployment';
+/** Content-addressed artifact or receipt. Mutable paths are locators only; the
+ * digest and byte length bind the exact bytes used by the search. */
+interface SearchArtifactRef {
+    role: string;
+    uri: string;
+    sha256: SearchLedgerHash;
+    byteLength: number;
+}
+/** Repository, dataset, or package source pinned to an immutable commit or
+ * content digest. Branches, tags, and bare package versions are rejected. */
+interface SearchSourceRef {
+    uri: string;
+    revision: string;
+}
+interface SearchModelIdentity {
+    provider: string;
+    snapshot: string;
+}
+interface SearchCandidateSurface {
+    surfaceId: string;
+    kind: SearchSurfaceKind;
+    artifact: SearchArtifactRef;
+}
+interface SearchCandidateLineage {
+    /** Existing `LineageNode.id`; this ledger references rather than embeds it. */
+    lineageNodeId: string;
+    parentCandidateIds: string[];
+    generation: number;
+    proposer: string;
+    proposerSource: SearchSourceRef;
+}
+type SearchOperationKind = 'candidate-generation' | 'analysis' | 'selection' | 'judge' | 'other';
+interface SearchPlannedTask {
+    taskId: string;
+    source: SearchSourceRef;
+    benchmark: SearchSourceRef;
+    /** Maximum transport attempts for this task and candidate. Only an explicit
+     * passed/failed outcome satisfies the planned denominator. */
+    maxAttempts: number;
+}
+interface SearchPlannedOperation {
+    operationId: string;
+    kind: SearchOperationKind;
+}
+interface SearchCandidateSlot {
+    slotId: string;
+    /** Planned candidate-generation call that must either produce this slot or
+     * fail before the slot can be closed. Several slots may share one batched call. */
+    generationOperationId: string;
+}
+interface SearchPlan {
+    /** Stable slots and their proposer calls are frozen before search begins. */
+    candidateSlots: SearchCandidateSlot[];
+    /** Every task applies to every successfully registered candidate. */
+    tasks: SearchPlannedTask[];
+    /** Non-task spend slots: proposal, analysis, selection, extra judges, etc. */
+    operations: SearchPlannedOperation[];
+}
+type SearchTokenAccounting = {
+    status: 'known';
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+type SearchCostAccounting = {
+    status: 'known';
+    usd: number;
+    source: 'provider' | 'pricing-table' | 'free';
+} | {
+    status: 'unknown';
+    /** Known spend may still be a lower bound when one call was unpriced. */
+    knownLowerBoundUsd: number;
+    reason: string;
+};
+interface SearchAttemptAccounting {
+    tokens: SearchTokenAccounting;
+    cost: SearchCostAccounting;
+}
+interface SearchFailureReason {
+    code: string;
+    message: string;
+}
+type SearchTaskOutcome = {
+    status: 'passed';
+    score: number;
+    metrics: Record<string, number>;
+} | {
+    status: 'failed';
+    score: number;
+    metrics: Record<string, number>;
+    failure: SearchFailureReason;
+} | {
+    status: 'errored';
+    metrics: Record<string, number>;
+    error: SearchFailureReason & {
+        retryable: boolean;
+    };
+};
+type SearchSurfaceEffect = {
+    status: 'measured';
+    metric: string;
+    baselineValue: number;
+    candidateValue: number;
+    delta: number;
+} | {
+    status: 'not-measured';
+    reason: string;
+};
+/** Per-attempt proof that a declared candidate surface was or was not active,
+ * plus measured effect when the experiment supports attribution. */
+interface SearchSurfaceEvidence {
+    surfaceId: string;
+    fired: boolean;
+    firingCount: number;
+    effect: SearchSurfaceEffect;
+    evidence: SearchArtifactRef[];
+}
+interface SearchLedgerEventBase {
+    eventId: string;
+    occurredAt: string;
+    artifacts: SearchArtifactRef[];
+}
+interface SearchPlannedEvent extends SearchLedgerEventBase {
+    kind: 'search-planned';
+    plan: SearchPlan;
+}
+interface SearchCandidateRegisteredEvent extends SearchLedgerEventBase {
+    kind: 'candidate-registered';
+    slotId: string;
+    generationOperationId: string;
+    candidateId: string;
+    lineage: SearchCandidateLineage;
+    surfaces: SearchCandidateSurface[];
+}
+interface SearchCandidateSlotClosedEvent extends SearchLedgerEventBase {
+    kind: 'candidate-slot-closed';
+    slotId: string;
+    generationOperationId: string;
+    reason: SearchFailureReason;
+}
+interface SearchTaskAttemptedEvent extends SearchLedgerEventBase {
+    kind: 'task-attempted';
+    candidateId: string;
+    runId: string;
+    attemptIndex: number;
+    task: {
+        taskId: string;
+        source: SearchSourceRef;
+    };
+    identity: {
+        model: SearchModelIdentity;
+        agent: SearchSourceRef;
+        benchmark: SearchSourceRef;
+    };
+    outcome: SearchTaskOutcome;
+    accounting: SearchAttemptAccounting;
+    surfaceEvidence: SearchSurfaceEvidence[];
+}
+interface SearchOperationRecordedEvent extends SearchLedgerEventBase {
+    kind: 'search-operation-recorded';
+    operationId: string;
+    operationKind: SearchOperationKind;
+    execution: {
+        kind: 'model';
+        model: SearchModelIdentity;
+        source: SearchSourceRef;
+    } | {
+        kind: 'deterministic';
+        source: SearchSourceRef;
+    };
+    outcome: {
+        status: 'completed';
+    } | {
+        status: 'partial';
+        failure: SearchFailureReason;
+    } | {
+        status: 'failed';
+        failure: SearchFailureReason;
+    };
+    accounting: SearchAttemptAccounting;
+}
+interface SearchCandidateDecidedEvent extends SearchLedgerEventBase {
+    kind: 'candidate-decided';
+    candidateId: string;
+    decision: {
+        status: 'selected';
+    } | {
+        status: 'rejected';
+        reason: SearchFailureReason;
+    };
+}
+interface SearchCompletedEvent extends SearchLedgerEventBase {
+    kind: 'search-completed';
+    result: {
+        status: 'selected';
+        candidateId: string;
+    } | {
+        status: 'all-rejected';
+        reason: SearchFailureReason;
+    };
+}
+type SearchLedgerEvent = SearchPlannedEvent | SearchCandidateRegisteredEvent | SearchCandidateSlotClosedEvent | SearchTaskAttemptedEvent | SearchOperationRecordedEvent | SearchCandidateDecidedEvent | SearchCompletedEvent;
+interface SearchLedgerEntry {
+    schema: typeof SEARCH_LEDGER_SCHEMA;
+    campaignId: string;
+    sequence: number;
+    previousHash: SearchLedgerHash | null;
+    event: SearchLedgerEvent;
+    entryHash: SearchLedgerHash;
+}
+type SearchAccountingAudit = {
+    status: 'known';
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    costUsd: number;
+} | {
+    status: 'partial';
+    knownInputTokens: number;
+    knownOutputTokens: number;
+    knownCachedTokens: number;
+    knownCostUsd: number;
+    unknownTokenEventIds: string[];
+    unknownCostEventIds: string[];
+};
+interface SearchLedgerAudit {
+    campaignId: string;
+    eventCount: number;
+    candidateCount: number;
+    closedCandidateSlotCount: number;
+    attemptCount: number;
+    operationCount: number;
+    outcomes: {
+        passed: number;
+        failed: number;
+        errored: number;
+    };
+    operationOutcomes: {
+        completed: number;
+        partial: number;
+        failed: number;
+    };
+    decisions: {
+        selected: number;
+        rejected: number;
+        pending: number;
+    };
+    expected: {
+        candidateSlots: number;
+        taskOutcomes: number;
+        operations: number;
+        missingCandidateSlots: string[];
+        missingTaskOutcomes: string[];
+        missingOperations: string[];
+    };
+    status: 'in-progress' | 'selected' | 'all-rejected';
+    selectedCandidateId: string | null;
+    accounting: SearchAccountingAudit;
+    headHash: SearchLedgerHash | null;
+}
+interface SearchLedgerReplay {
+    entries: SearchLedgerEntry[];
+    plan: SearchPlannedEvent | null;
+    candidates: SearchCandidateRegisteredEvent[];
+    closedCandidateSlots: SearchCandidateSlotClosedEvent[];
+    attempts: SearchTaskAttemptedEvent[];
+    operations: SearchOperationRecordedEvent[];
+    decisions: SearchCandidateDecidedEvent[];
+    completion: SearchCompletedEvent | null;
+    audit: SearchLedgerAudit;
+}
+interface SearchLedgerAppendResult {
+    entry: SearchLedgerEntry;
+    /** False when the exact event was already durably present. */
+    appended: boolean;
+    replay: SearchLedgerReplay;
+}
+/** Validate and return a canonical copy. Arrays whose order is not semantic are
+ * sorted so retries from different processes produce byte-identical events. */
+declare function validateSearchLedgerEvent(input: unknown): SearchLedgerEvent;
+interface OpenSearchLedgerOptions {
+    path: string;
+    campaignId: string;
+}
+interface SearchLedger {
+    readonly path: string;
+    readonly campaignId: string;
+    append(event: SearchLedgerEvent): Promise<SearchLedgerAppendResult>;
+    replay(): Promise<SearchLedgerReplay>;
+}
+/** Open a durable filesystem search ledger. Construction performs no I/O; the
+ * first `append` or `replay` validates the complete existing file. */
+declare function openSearchLedger(options: OpenSearchLedgerOptions): SearchLedger;
+declare class FileSearchLedger implements SearchLedger {
+    readonly path: string;
+    readonly campaignId: string;
+    private readonly mutex;
+    constructor(path: string, campaignId: string);
+    replay(): Promise<SearchLedgerReplay>;
+    append(input: SearchLedgerEvent): Promise<SearchLedgerAppendResult>;
+}
+
 /**
  * Single-run lock for evaluations that share one mutable environment.
  *
@@ -2294,4 +2898,4 @@ declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string):
  *  identity against the checkout at `worktreeRef`. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type ApplySkillPatchResult, type BuildAnalystSurfaceDispatchOptions, type CampaignBreakdown, CampaignResult, CampaignRunPlan, CampaignStorage, CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type DimensionRegression, type DiscriminationScore, DispatchContext, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GenerationRecord, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPrimitive, type JsonValue, JudgeConfig, JudgeScore, LabelTrust, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioSource, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LoadEvalFixtureScenariosOptions, type MemoryCurationProposerOptions, MutableSurface, type NeutralizationGateOptions, type OptimizerEntryConfig, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditProposerOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, ProposeContext, type ProposePatchesArgs, ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, RunCampaignOptions, RunImprovementLoopOptions, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, Scenario, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, applySkillPatch, assertCodeSurfaceIdentity, buildAnalystSurfaceDispatch, callbackGovernor, campaignBreakdown, campaignMeanComposite, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, compositeProposer, detectScale, dimensionRegressions, discoverEvalFixtures, extractFapoAttributionSignals, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsLineageStore, gepaParetoEntry, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldoutSignificance, heuristicGovernor, isTransientTransportFailure, lineageNodeId, loadEvalFixture, loadEvalFixtureScenarios, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, pairHoldout, parameterSweepProposer, parseSkillPatchResponse, patchEditCount, planEvalFixtureRun, policyEditProposer, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runLineage, runLineageLoop, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, verifyCodeSurface };
+export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type ApplySkillPatchResult, type BuildAnalystSurfaceDispatchOptions, type CampaignBreakdown, CampaignResult, CampaignRunPlan, CampaignStorage, CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, type DimensionRegression, type DiscriminationScore, DispatchContext, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GenerationRecord, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPrimitive, type JsonValue, JudgeConfig, JudgeScore, LabelTrust, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioSource, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LoadEvalFixtureScenariosOptions, type MemoryCurationProposerOptions, MutableSurface, type NeutralizationGateOptions, type OpenSearchLedgerOptions, type OptimizerEntryConfig, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditProposerOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, ProposeContext, type ProposePatchesArgs, ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, RunCampaignOptions, RunImprovementLoopOptions, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, SEARCH_LEDGER_SCHEMA, Scenario, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, analyzeCrossSurfaceInteractions, applySkillPatch, assertCodeSurfaceIdentity, buildAnalystSurfaceDispatch, callbackGovernor, campaignBreakdown, campaignMeanComposite, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, compositeProposer, detectScale, dimensionRegressions, discoverEvalFixtures, extractFapoAttributionSignals, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsLineageStore, gepaParetoEntry, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldoutSignificance, heuristicGovernor, isTransientTransportFailure, lineageNodeId, loadEvalFixture, loadEvalFixtureScenarios, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, openSearchLedger, pairHoldout, parameterSweepProposer, parseSkillPatchResponse, patchEditCount, planEvalFixtureRun, policyEditProposer, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runLineage, runLineageLoop, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface };