@tangle-network/agent-eval 0.144.5 → 0.144.7

package/dist/trajectory-replay/index.d.ts

@@ -0,0 +1,781 @@
+import { s as TraceStore } from "../store-CT9YIIve.js";
+import { i as TraceEmitter } from "../emitter-DGQGoLyj.js";
+import { i as CounterfactualRunner, t as CounterfactualContext } from "../counterfactual-CxmxAONP.js";
+import { a as parseObservationOutput, i as isSubmitAction, n as SUBMIT_ACTION_SIGNATURE, o as parseRecordedReturncode, r as deriveFailureSignature, t as RecordedTrajectoryStep } from "../steps-BArUxhna.js";
+//#region src/trajectory-replay/corpus.d.ts
+interface CorpusSpec {
+  readonly name: string;
+  readonly labelsPath: string;
+  readonly preparedDir: string;
+}
+/** Parses `name=<labelsPath>::<preparedDir>` (paths may contain `=`, not `::`). */
+declare function parseCorpusFlag(value: string): CorpusSpec;
+type ReplayExclusionReason = 'no-swe-raw-trajectory' | 'ambiguous-swe-raw-trajectory' | 'unreadable-raw-trajectory' | 'no-docker-image' | 'no-gold-incorrect-step' | 'gold-only-submit-step' | 'missing-steps-json' | 'gold-step-outside-steps' | 'cwd-underivable';
+interface ExcludedCase {
+  readonly corpus: string;
+  readonly trajId: string;
+  readonly reason: ReplayExclusionReason;
+  readonly detail?: string;
+}
+type CwdSource = 'run-config' | 'docker-config' | 'pwd-observation';
+/** Everything needed to replay one trajectory. */
+interface CaseResources {
+  readonly corpus: string;
+  readonly trajId: string;
+  readonly stepsPath: string;
+  readonly steps: readonly RecordedTrajectoryStep[];
+  readonly taskStatement: string | null;
+  readonly image: string;
+  readonly cwd: string;
+  readonly cwdSource: CwdSource;
+  /** Per-step timeout the recorded run used, when the raw config carries one. */
+  readonly recordedStepTimeoutMs: number | null;
+}
+interface ReplayableCase extends CaseResources {
+  /** 1-based gold incorrect step ids, ascending. */
+  readonly goldIncorrectSteps: readonly number[];
+  /** k — the first gold incorrect step that is a real mid-trajectory action;
+   *  submit-command golds are skipped (see SUBMIT_ACTION_SIGNATURE). */
+  readonly k: number;
+  /** Gold steps before k skipped because their action is the submit command. */
+  readonly submitGoldsSkipped: number;
+  /** Recorded returncode at k; null when the observation carries none. */
+  readonly recordedReturncodeAtK: number | null;
+}
+interface LabelEntry {
+  readonly traj_id: string;
+  readonly incorrect_stages?: readonly {
+    readonly incorrect_step_ids?: readonly number[];
+  }[];
+}
+declare function readLabelEntries(labelsPath: string): LabelEntry[];
+declare function goldIncorrectSteps(entry: LabelEntry): number[];
+type ResourceResolution = {
+  readonly resolved: true;
+  readonly resources: CaseResources;
+} | {
+  readonly resolved: false;
+  readonly reason: ReplayExclusionReason;
+  readonly detail?: string;
+};
+/**
+ * Resolves the replay resources for one trajectory, independent of gold
+ * labels — the finding wire uses this with a finding-supplied step instead.
+ */
+declare function resolveCaseResources(corpus: CorpusSpec, trajId: string): ResourceResolution;
+interface EnumerationResult {
+  readonly replayable: ReplayableCase[];
+  readonly excluded: ExcludedCase[];
+  readonly labelEntryCount: number;
+}
+/**
+ * Replayable = a raw trajectory with a recorded image AND at least one gold
+ * incorrect step that is a real mid-trajectory action. Gold steps whose action
+ * is the submit command are skipped when choosing k (counted per case); a case
+ * whose golds are ALL submit steps is excluded as gold-only-submit-step.
+ * Exclusion reasons are reported in resolution order:
+ * raw trajectory → image → gold labels → steps.json → k range → cwd.
+ */
+declare function enumerateReplayableCases(corpora: readonly CorpusSpec[]): EnumerationResult;
+//#endregion
+//#region src/trajectory-replay/exec.d.ts
+/**
+ * The execution boundary replay runs across.
+ *
+ * A replay needs one thing from its environment: a session that runs a shell
+ * command inside the trajectory's own image and reports the exit code and
+ * output. That is the whole contract. Concrete backends — a sandbox platform
+ * client, a docker exec, an SSH shell — live with the consumer that owns the
+ * infrastructure, so this package depends on no sandbox client.
+ */
+interface ReplayExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+interface ReplayExecSession {
+  exec(command: string, timeoutMs: number): Promise<ReplayExecResult>;
+  close(): Promise<void>;
+}
+interface ReplayExecBackend {
+  /** One fresh execution environment per call; the caller closes it. */
+  open(): Promise<ReplayExecSession>;
+}
+/** Builds a backend pinned to one image. Callers that resolve images
+ *  internally (batch, corpus wire, finding verification) take this instead of
+ *  a backend, so every case runs against its own image. */
+type ReplayExecBackendFactory = (image: string) => ReplayExecBackend;
+/**
+ * mini-SWE runs every action as a fresh /bin/sh subshell from a fixed
+ * workdir. Reproduce that exactly — and stay quote-proof for arbitrary
+ * recorded actions — by piping the base64 of the action into `sh` after
+ * cd-ing to the workdir. Exit code is sh's, i.e. the action's.
+ */
+declare function wrapActionForExec(action: string, cwd: string): string;
+//#endregion
+//#region src/trajectory-replay/fix.d.ts
+interface ChatUsage {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+}
+type ChatOutcome = {
+  readonly succeeded: true;
+  readonly value: {
+    content: string;
+    usage: ChatUsage | null;
+  };
+} | {
+  readonly succeeded: false;
+  readonly error: string;
+};
+interface ChatCompletionCaller {
+  complete(system: string, user: string): Promise<ChatOutcome>;
+}
+interface FixPromptInput {
+  readonly taskStatement: string | null;
+  readonly steps: readonly RecordedTrajectoryStep[];
+  /** 1-based step_id of the incorrect step. */
+  readonly k: number;
+  /** Steps of context on each side of k (default 3). */
+  readonly contextRadius?: number;
+}
+/** Head+tail excerpt with an elision marker; identity below the limit. */
+declare function clipText(text: string, limit: number): string;
+declare function buildFixPrompt(input: FixPromptInput): {
+  system: string;
+  user: string;
+};
+/** One prior attempt of the fix loop, rendered into the retry prompt. */
+interface FailedFixAttempt {
+  readonly attempt: number;
+  /** Null when the model call itself failed before producing a command. */
+  readonly command: string | null;
+  readonly exitCode: number | null;
+  readonly stdoutTail: string | null;
+  readonly stderrTail: string | null;
+  readonly llmError: string | null;
+}
+/**
+ * Retry prompt for fix-loop attempts ≥2: the original context plus every prior
+ * attempt with its REAL executed output, and permission to answer with a short
+ * script (the block still executes as one /bin/sh unit).
+ */
+declare function buildRetryFixPrompt(input: FixPromptInput, priorAttempts: readonly FailedFixAttempt[], maxScriptCommands?: number): {
+  system: string;
+  user: string;
+};
+/** Non-empty, non-comment lines of a fix script — the loop's script-size cap. */
+declare function countScriptCommands(script: string): number;
+/** Last fenced code block, else the whole trimmed content; null when empty. */
+declare function extractFixCommand(content: string): string | null;
+type FixGenerationOutcome = {
+  readonly succeeded: true;
+  readonly value: {
+    command: string;
+    usage: ChatUsage | null;
+  };
+} | {
+  readonly succeeded: false;
+  readonly error: string;
+};
+declare function generateFixCommand(caller: ChatCompletionCaller, input: FixPromptInput): Promise<FixGenerationOutcome>;
+//#endregion
+//#region src/trajectory-replay/fix-loop.d.ts
+/** Result of executing one corrected command as a full arm. */
+interface FixArmExecution {
+  readonly exitCode: number;
+  readonly prefixExecuted: number;
+  readonly prefixDivergences: number;
+  /** Divergent prefix steps over executed ones, in percent. */
+  readonly prefixDivergencePct: number;
+  readonly failureVanished: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+/** Runs one corrected command as a full arm: fresh sandbox + prefix replay. */
+type FixArmExecutor = (command: string, attempt: number) => Promise<FixArmExecution>;
+interface FixLoopOptions {
+  /** Total LLM attempts per case (≥1); 1 degenerates to the one-shot path. */
+  readonly maxAttempts: number;
+  /** Command-line cap on retry scripts (default 5). */
+  readonly maxScriptCommands?: number;
+  /** Chars kept per stdout/stderr tail in records and retry prompts. */
+  readonly outputTailChars?: number;
+  readonly onProgress?: (message: string) => void;
+}
+interface FixLoopAttemptRecord {
+  readonly attempt: number;
+  readonly command: string | null;
+  readonly llmError: string | null;
+  readonly usage: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+  } | null;
+  readonly executed: boolean;
+  readonly exitCode: number | null;
+  readonly prefixExecuted: number | null;
+  readonly prefixDivergences: number | null;
+  readonly prefixDivergencePct: number | null;
+  readonly failureVanished: boolean | null;
+  readonly stdoutTail: string | null;
+  readonly stderrTail: string | null;
+  readonly armBError: string | null;
+  readonly wallMs: number;
+}
+interface FixLoopResult {
+  readonly flipped: boolean;
+  readonly flippedAtAttempt: number | null;
+  readonly attempts: readonly FixLoopAttemptRecord[];
+  /** True when a sandbox error ended the loop before the attempt budget. */
+  readonly aborted: boolean;
+  readonly llmCalls: number;
+  /** Calls that produced no runnable fix: transport errors, empty replies,
+   *  and retry scripts over the command cap. */
+  readonly llmFailures: number;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  /** Successful calls whose provider reported no usage. Their tokens are absent
+   *  from the two totals above, so a nonzero count makes those totals a lower
+   *  bound rather than a measurement. */
+  readonly callsWithoutUsage: number;
+}
+declare function runFixLoop(caller: ChatCompletionCaller, input: FixPromptInput, executor: FixArmExecutor, options: FixLoopOptions): Promise<FixLoopResult>;
+//#endregion
+//#region src/trajectory-replay/image-preparer.d.ts
+/**
+ * Replay-ready image derivation.
+ *
+ * A recorded trajectory names the image it ran in, but the image is not always
+ * runnable as-is: sandbox platforms pin customer commands to a non-root
+ * identity, so a root-owned working tree must be chowned before the replay can
+ * write to it. `ImagePreparer` is that step, injectable so a consumer whose
+ * images are already replay-ready supplies its own no-op or none at all.
+ */
+type ImagePreparation = {
+  readonly succeeded: true;
+  readonly value: {
+    derivedImage: string;
+    pulled: boolean;
+    built: boolean;
+  };
+} | {
+  readonly succeeded: false;
+  readonly error: string;
+};
+interface ImagePreparer {
+  ensure(image: string, cwd: string): Promise<ImagePreparation>;
+}
+interface DockerImagePreparerOptions {
+  readonly pullTimeoutMs?: number;
+  readonly buildTimeoutMs?: number;
+}
+declare function derivedImageTag(image: string, cwd: string): string;
+/**
+ * Pulls the base image when absent and builds `FROM <base>; RUN chown -R
+ * 1000:1000 <cwd>` tagged by content hash, so repeated batches reuse both
+ * the pull and the build. cwd `/` skips the chown (never chown -R /) and
+ * replays on the base image directly.
+ */
+declare function dockerImagePreparer(options?: DockerImagePreparerOptions): ImagePreparer;
+//#endregion
+//#region src/trajectory-replay/batch.d.ts
+interface ReplayBatchOptions {
+  readonly corpora: readonly CorpusSpec[];
+  readonly out: string;
+  /** 'generate' = one LLM call per arm-A-reproduced case, then arm B.
+   *  'loop' = iterative: failed arms feed their real output into up to
+   *  `fixAttempts` prompts, each executed in its own fresh session. */
+  readonly fix: 'none' | 'generate' | 'loop';
+  /** Attempt budget per case in loop mode (default 3). */
+  readonly fixAttempts?: number;
+  readonly fixCaller?: ChatCompletionCaller;
+  readonly fixModelLabel?: string;
+  /** Cap on LLM fix calls; eligible cases beyond it are seeded-sampled out. */
+  readonly maxFixCases?: number;
+  readonly seed?: number;
+  /** Overrides the per-case recorded step timeout. */
+  readonly stepTimeoutMs?: number;
+  readonly prefixLimit?: number;
+  /** Run only cases whose trajId contains this substring (smoke knob). */
+  readonly caseFilter?: string;
+  /** Run only the first N replayable cases (smoke knob). */
+  readonly caseLimit?: number;
+  /** Derives the replay-ready image per case. Defaults to the docker preparer. */
+  readonly preparer?: ImagePreparer;
+  /** Builds the exec backend for a case's derived image. */
+  readonly backendFactory: ReplayExecBackendFactory;
+  readonly onProgress?: (message: string) => void;
+}
+interface ReplayBatchFixResult {
+  /** false when the case was eligible but seeded-sampled out of the cap. */
+  readonly attempted: boolean;
+  readonly sampledOut: boolean;
+  readonly command: string | null;
+  readonly llmError: string | null;
+  /** Loop mode: token totals summed across every attempt (null when the
+   *  provider reported no usage). */
+  readonly usage: ChatUsage | null;
+  readonly armBExit: number | null;
+  readonly armBPrefixExecuted: number | null;
+  readonly armBPrefixDivergences: number | null;
+  readonly armBPrefixDivergencePct: number | null;
+  readonly failureVanished: boolean | null;
+  readonly armBError: string | null;
+  /** Loop mode only: the full per-attempt trail. Null in generate mode. */
+  readonly attempts: readonly FixLoopAttemptRecord[] | null;
+  /** 1-based attempt that flipped the failure; null when none did.
+   *  Generate mode: 1 when the single attempt flipped. */
+  readonly flippedAtAttempt: number | null;
+}
+interface ReplayBatchCaseRow {
+  readonly corpus: string;
+  readonly trajId: string;
+  readonly image: string;
+  readonly derivedImage: string | null;
+  readonly cwd: string;
+  readonly cwdSource: string;
+  readonly k: number;
+  readonly stepCount: number;
+  readonly goldIncorrectSteps: readonly number[];
+  /** Gold steps before k skipped because their action is the submit command. */
+  readonly submitGoldsSkipped: number;
+  readonly recordedReturncodeAtK: number | null;
+  readonly signature: string | null;
+  readonly status: 'ok' | 'image-unavailable' | 'replay-error';
+  readonly error: string | null;
+  readonly imagePulled: boolean;
+  readonly imageBuilt: boolean;
+  readonly prefixExecuted: number | null;
+  readonly prefixDivergences: number | null;
+  readonly prefixDivergencePct: number | null;
+  /** Prefix steps whose recorded returncode equalled the replayed exit. */
+  readonly prefixConfirmed: number | null;
+  readonly prefixReturncodeMismatches: number | null;
+  /** Prefix steps the recording carries no returncode for: unverifiable, and
+   *  counted as divergences because agreement was never established. */
+  readonly prefixUnknownExpectations: number | null;
+  readonly armAExit: number | null;
+  readonly armAReturncodeMatch: boolean;
+  readonly armASignatureMatch: boolean;
+  /** Headline predicate: prefix divergence within tolerance AND arm A
+   *  reproduced the recorded returncode at k. */
+  readonly replayed: boolean;
+  readonly fix: ReplayBatchFixResult | null;
+  readonly wallMs: number;
+}
+interface ReplayBatchReport {
+  readonly generatedAt: string;
+  readonly corpora: readonly {
+    name: string;
+    labelsPath: string;
+    preparedDir: string;
+  }[];
+  readonly totals: {
+    readonly labelEntries: number;
+    readonly replayable: number;
+    readonly executed: number;
+    readonly excludedByReason: Record<string, number>;
+    /** Per-corpus submit-gold accounting: cases dropped because every gold is
+     *  the submit command, and golds skipped inside still-replayable cases. */
+    readonly submitGoldsByCorpus: Record<string, {
+      submitOnlyCases: number;
+      goldsSkippedWithinReplayable: number;
+    }>;
+  };
+  readonly headline: {
+    readonly replayabilityRate: {
+      numerator: number;
+      denominator: number;
+      value: number | null;
+    };
+    readonly signatureStrictRate: {
+      numerator: number;
+      denominator: number;
+      value: number | null;
+    };
+    /** Corpus-level replay fidelity over every executed prefix step. A corpus
+     *  whose recordings cannot adjudicate the replay lands here as
+     *  `unknownExpectations`, not as a clean replay. */
+    readonly prefixFidelity: {
+      readonly executedSteps: number;
+      readonly divergentSteps: number;
+      readonly returncodeMismatches: number;
+      readonly unknownExpectations: number;
+      /** Divergent over executed steps; null when no prefix step ran. */
+      readonly divergencePct: number | null;
+      readonly tolerancePct: number;
+      readonly casesWithinTolerance: number;
+      readonly casesExecuted: number;
+    };
+    readonly fixFlipRate: {
+      numerator: number;
+      denominator: number;
+      value: number | null;
+    } | null;
+    /** Fix-flip restricted to cases whose recorded returncode at k is nonzero —
+     *  real recorded failures, where "the failure vanished" is not vacuous. */
+    readonly fixFlipRateNonzeroRc: {
+      numerator: number;
+      denominator: number;
+      value: number | null;
+    } | null;
+    /** Loop mode only: flips at attempt 1 over cases whose attempt 1 executed —
+     *  the number directly comparable to the one-shot fixFlipRate. */
+    readonly fixFlipAttempt1: {
+      numerator: number;
+      denominator: number;
+      value: number | null;
+    } | null;
+    /** Loop mode only: flip count keyed by the attempt number that flipped. */
+    readonly flipsByAttempt: Record<string, number> | null;
+  };
+  readonly llm: {
+    readonly model: string;
+    readonly calls: number;
+    readonly failures: number;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    /** Successful calls whose provider reported no usage. Their tokens are
+     *  absent from the two totals above, so a nonzero count here means the
+     *  totals are a lower bound, not a measurement. */
+    readonly callsWithoutUsage: number;
+  } | null;
+  readonly excluded: readonly {
+    corpus: string;
+    trajId: string;
+    reason: string;
+    detail?: string;
+  }[];
+  readonly pullFailures: readonly {
+    corpus: string;
+    trajId: string;
+    image: string;
+    error: string;
+  }[];
+  readonly cases: readonly ReplayBatchCaseRow[];
+}
+declare function seededSample<T>(items: readonly T[], size: number, seed: number): Set<T>;
+declare function runReplayBatch(options: ReplayBatchOptions): Promise<ReplayBatchReport>;
+declare function renderBatchReport(report: ReplayBatchReport): string;
+//#endregion
+//#region src/trajectory-replay/verify.d.ts
+interface IngestedTrajectory {
+  runId: string;
+  stepCount: number;
+}
+/**
+ * Emit one tool span per trajectory step, in order, with a monotonic
+ * injected clock so `buildTrajectory` ordering is deterministic even when
+ * two spans would share a Date.now() millisecond.
+ */
+declare function ingestRecordedTrajectory(store: TraceStore, steps: readonly RecordedTrajectoryStep[], caseId: string): Promise<IngestedTrajectory>;
+/** Why a replayed prefix step failed to confirm the recording. */
+type PrefixDivergenceKind =
+/** The recording carries a returncode and the replayed exit differs from it. */
+'returncode-mismatch' |
+/** The recording carries no returncode, so agreement cannot be established. */
+'unknown-expectation';
+interface PrefixDivergence {
+  step: number;
+  kind: PrefixDivergenceKind;
+  /** null exactly when `kind` is `unknown-expectation`. */
+  expectedReturncode: number | null;
+  actualExit: number;
+}
+interface PrefixReplayResult {
+  prefixExecuted: number;
+  /** Every step that did not confirm the recording, of both kinds. */
+  prefixDivergences: PrefixDivergence[];
+  /** Steps whose recorded returncode equalled the replayed exit. */
+  prefixConfirmed: number;
+  prefixReturncodeMismatches: number;
+  prefixUnknownExpectations: number;
+  /** Divergent steps over executed steps, in percent, one decimal.
+   *  0 for an empty prefix: no step ran, so none diverged. */
+  prefixDivergencePct: number;
+  /** `prefixDivergencePct` within `PREFIX_DIVERGENCE_TOLERANCE_PCT`. */
+  prefixWithinTolerance: boolean;
+  wallMs: number;
+}
+/** Admission tolerance: a prefix replay is faithful enough to build a verdict
+ *  on when at most this percentage of its executed steps diverged. */
+declare const PREFIX_DIVERGENCE_TOLERANCE_PCT = 10;
+/**
+ * Compare one replayed prefix step against its recording. Returns null only
+ * when the recording positively confirms the replay.
+ */
+declare function classifyPrefixStep(step: number, expectedReturncode: number | null, actualExit: number): PrefixDivergence | null;
+/** Roll per-step classifications up into the rate the admission pre-pass gates on. */
+declare function summarizePrefixReplay(prefixExecuted: number, prefixDivergences: PrefixDivergence[], wallMs: number): PrefixReplayResult;
+interface ArmExecutionResult {
+  command: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  wallMs: number;
+}
+interface SandboxCounterfactualRunnerOptions {
+  cwd: string;
+  stepTimeoutMs: number;
+  /** Execute at most this many prefix steps (from the start). Fast-iteration
+   *  knob; a truncated prefix weakens state fidelity and the verdict says so. */
+  prefixLimit?: number;
+  onProgress?: (message: string) => void;
+}
+/**
+ * Replays `ctx.prefix` in a fresh session, then executes the mutated step.
+ * Divergences are recorded and never abort the replay. Results land on
+ * `lastPrefix` / `lastArm` for the caller; spans for every exec land in the
+ * counterfactual meta-run.
+ */
+declare class SandboxCounterfactualRunner implements CounterfactualRunner {
+  private readonly backend;
+  private readonly options;
+  lastPrefix: PrefixReplayResult | null;
+  lastArm: ArmExecutionResult | null;
+  constructor(backend: ReplayExecBackend, options: SandboxCounterfactualRunnerOptions);
+  executeFrom(ctx: CounterfactualContext, emitter: TraceEmitter): Promise<void>;
+}
+interface ReplayVerifyOptions {
+  stepsPath: string;
+  image: string;
+  /** 1-based step_id of the error-critical step. */
+  at: number;
+  /** Corrected command for arm B. Omit to run arm A only. */
+  fixCommand?: string;
+  cwd: string;
+  out: string;
+  caseId?: string;
+  /** Override the auto-derived failure signature substring. */
+  signature?: string;
+  stepTimeoutMs?: number;
+  prefixLimit?: number;
+  /** Label of the driver backing the exec backend (reported, not probed). */
+  driverLabel?: string;
+  /** Execution environment for both arms; each arm opens its own session. */
+  backend: ReplayExecBackend;
+  onProgress?: (message: string) => void;
+}
+interface ReplayArmVerdict {
+  command: string;
+  exitCode: number;
+  wallMs: number;
+  prefix: PrefixReplayResult;
+}
+interface ReplayVerdict {
+  case: string;
+  image: string;
+  driver: string;
+  k: number;
+  cwd: string;
+  recordedReturncode: number | null;
+  signature: string | null;
+  signatureBasis: 'returncode+output-substring' | 'returncode-only';
+  prefixExecuted: number;
+  prefixDivergences: PrefixDivergence[];
+  /** Arm A's prefix divergence rate — the number admission gates on. */
+  prefixDivergencePct: number;
+  prefixConfirmed: number;
+  prefixReturncodeMismatches: number;
+  prefixUnknownExpectations: number;
+  prefixWithinTolerance: boolean;
+  armA: ReplayArmVerdict & {
+    failureSignatureMatch: boolean;
+  };
+  armB: (ReplayArmVerdict & {
+    failureVanished: boolean;
+  }) | null;
+  timings: {
+    armAMs: number;
+    armBMs: number | null;
+    totalMs: number;
+  };
+  runIds: {
+    original: string;
+    armA: string;
+    armB: string | null;
+  };
+}
+declare function replayVerify(options: ReplayVerifyOptions): Promise<ReplayVerdict>;
+//#endregion
+//#region src/trajectory-replay/findings.d.ts
+interface VerifiableFinding {
+  readonly finding_id?: string;
+  readonly analyst_id?: string;
+  readonly subject?: string;
+  readonly area?: string;
+  readonly claim?: string;
+  readonly evidence_refs?: readonly {
+    readonly kind?: string;
+    readonly uri?: string;
+    readonly excerpt?: string;
+  }[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 1-based step the finding accuses, or null when the finding names none.
+ * `metadata.block_first_step` wins over the subject: the analyst records the
+ * block's first incorrect step there even when the subject names a later
+ * step of the same block.
+ */
+declare function findingReplayStep(finding: VerifiableFinding): number | null;
+/** Trajectory id from the finding's `trace://<traj>/…` evidence refs, or null. */
+declare function findingTrajectoryId(finding: VerifiableFinding): string | null;
+/**
+ * Where the executable trajectory lives.
+ * `direct` — one trajectory's steps.json plus a replay-ready image; the
+ *   caller owns image preparation.
+ * `corpus` — labeled trajectory corpora; each finding's trajectory is
+ *   resolved by its `trace://` evidence and the image is derived through
+ *   `preparer` (the docker uid-1000 preparer unless overridden; `null` when
+ *   the images are already replay-ready).
+ */
+type FindingReplaySource = {
+  readonly kind: 'direct';
+  readonly stepsPath: string;
+  readonly image: string;
+  readonly cwd: string;
+  readonly caseId?: string;
+} | {
+  readonly kind: 'corpus';
+  readonly corpora: readonly CorpusSpec[];
+  readonly preparer?: ImagePreparer | null;
+};
+interface ResolvedFindingReplay {
+  readonly caseId: string;
+  readonly stepsPath: string;
+  /** Raw image; corpus-mode execution derives the replay image from it. */
+  readonly image: string;
+  readonly cwd: string;
+  /** 1-based step_id arm A executes. */
+  readonly at: number;
+  readonly recordedReturncode: number;
+  readonly recordedStepTimeoutMs: number | null;
+}
+type FindingReplayability = {
+  readonly replayable: true;
+  readonly resolved: ResolvedFindingReplay;
+} | {
+  readonly replayable: false;
+  readonly reason: string;
+};
+/**
+ * Decides whether one finding can be executed against the source, and with
+ * what invocation. Never throws for a finding-shaped problem — every dead end
+ * becomes a `not-replayable` reason the receipt can carry verbatim.
+ */
+declare function resolveFindingReplayability(finding: VerifiableFinding, source: FindingReplaySource): FindingReplayability;
+type FindingVerificationStatus = 'reproduced' | 'fix-flipped' | 'not-replayable' | 'divergent';
+interface FindingVerification {
+  readonly finding_id: string | null;
+  readonly subject: string | null;
+  readonly trajectory_id: string | null;
+  /** 1-based step the proof executed at; null when not replayable. */
+  readonly step: number | null;
+  readonly verified: FindingVerificationStatus;
+  /** Present exactly when `verified` is `not-replayable`. */
+  readonly reason: string | null;
+  /** Receipt directory: receipt.json plus, when executed, replay-verdict.json + report.md. */
+  readonly receipt: string;
+  readonly verdict_path: string | null;
+  /** Receipt dir of the executed proof this finding shares (same case, step, and fix). */
+  readonly deduplicated_with: string | null;
+}
+interface VerifyFindingsRun {
+  readonly out: string;
+  readonly verifications: readonly FindingVerification[];
+  readonly counts: Readonly<Record<FindingVerificationStatus, number>>;
+  /** Executions actually performed (deduplicated proofs count once). */
+  readonly executions: number;
+}
+interface VerifyFindingsOptions {
+  readonly source: FindingReplaySource;
+  /** Receipt root; one subdirectory per finding plus verifications.json. */
+  readonly out: string;
+  /** Corrected command for arm B on every executed finding; omit for arm A only. */
+  readonly fixCommand?: string;
+  readonly stepTimeoutMs?: number;
+  readonly prefixLimit?: number;
+  /** Builds the exec backend for a finding's replay image. */
+  readonly backendFactory: ReplayExecBackendFactory;
+  /** Runs once before the first proof, only when some finding is replayable.
+   *  Throw to refuse execution against absent or degraded infrastructure. */
+  readonly preflight?: () => Promise<void>;
+  readonly onProgress?: (message: string) => void;
+}
+/**
+ * Arm A reproduced on a prefix the recording confirmed → the fix flipping it
+ * beats plain reproduction; anything else diverged. A proof standing on a
+ * prefix outside the divergence tolerance is divergent no matter what arm A
+ * did: the state it ran against is not the recorded state.
+ */
+declare function classifyVerdict(verdict: ReplayVerdict): FindingVerificationStatus;
+/**
+ * Verifies every finding against the source: resolves replayability, executes
+ * one proof per distinct (case, step, fix) — findings accusing the same step
+ * share the executed proof — and writes a receipt directory per finding plus a
+ * run-level verifications.json.
+ */
+declare function verifyFindings(findings: readonly VerifiableFinding[], options: VerifyFindingsOptions): Promise<VerifyFindingsRun>;
+/** Markdown section an analysis report appends when finding verification ran. */
+declare function renderVerifiedFindingsSection(run: VerifyFindingsRun): string;
+/**
+ * Accepts the two shapes findings travel in: a bare JSON array of analyst
+ * findings, or an object with a `findings` array (e.g. an extracted
+ * `observations[n]` from a result.json).
+ */
+declare function readFindingsFile(path: string): VerifiableFinding[];
+//#endregion
+//#region src/trajectory-replay/wire.d.ts
+interface IncorrectStepsSubject {
+  readonly firstStep: number;
+  readonly lastStep: number;
+  readonly escapeStatus: 'escaped' | 'unescaped';
+  readonly consequenceStep: number;
+}
+/** Null when the subject is not an incorrect-steps finding subject. */
+declare function parseIncorrectStepsSubject(subject: string): IncorrectStepsSubject | null;
+interface AnalystReplayFinding {
+  readonly trajId: string;
+  readonly subject: string;
+}
+interface ResolvedReplayInvocation {
+  readonly resources: CaseResources;
+  readonly subject: IncorrectStepsSubject;
+  /** 1-based step_id arm A executes: the finding's first incorrect step. */
+  readonly at: number;
+}
+/**
+ * Maps a finding onto replay resources, searching the given corpora for the
+ * trajectory. Throws with the precise reason when the finding cannot be
+ * replayed (malformed subject, unknown trajectory, non-replayable case, step
+ * out of range) — the caller surfaces that reason instead of a proof.
+ */
+declare function resolveFindingInvocation(finding: AnalystReplayFinding, corpora: readonly CorpusSpec[]): ResolvedReplayInvocation;
+interface ReplayFindingOptions {
+  readonly corpora: readonly CorpusSpec[];
+  readonly out: string;
+  /** Generates the arm-B corrected command; omit to run arm A only. */
+  readonly fixCaller?: ChatCompletionCaller;
+  /** Pre-supplied arm-B command; mutually exclusive with fixCaller. */
+  readonly fixCommand?: string;
+  readonly stepTimeoutMs?: number;
+  readonly prefixLimit?: number;
+  /** Builds the exec backend for the resolved trajectory image. */
+  readonly backendFactory: ReplayExecBackendFactory;
+  readonly onProgress?: (message: string) => void;
+}
+interface ReplayFindingResult {
+  readonly invocation: ResolvedReplayInvocation;
+  readonly fixCommand: string | null;
+  readonly verdict: ReplayVerdict;
+}
+/**
+ * Finding in, executed proof out. The image comes from the corpus resources;
+ * the backend factory receives it as-is, so a factory backed by infrastructure
+ * that needs a derived image must run an `ImagePreparer` first.
+ */
+declare function replayVerifyFinding(finding: AnalystReplayFinding, options: ReplayFindingOptions): Promise<ReplayFindingResult>;
+//#endregion
+export { type AnalystReplayFinding, type ArmExecutionResult, type CaseResources, type ChatCompletionCaller, type ChatOutcome, type ChatUsage, type CorpusSpec, type CwdSource, type DockerImagePreparerOptions, type EnumerationResult, type ExcludedCase, type FailedFixAttempt, type FindingReplaySource, type FindingReplayability, type FindingVerification, type FindingVerificationStatus, type FixArmExecution, type FixArmExecutor, type FixGenerationOutcome, type FixLoopAttemptRecord, type FixLoopOptions, type FixLoopResult, type FixPromptInput, type ImagePreparation, type ImagePreparer, type IncorrectStepsSubject, type IngestedTrajectory, PREFIX_DIVERGENCE_TOLERANCE_PCT, type PrefixDivergence, type PrefixDivergenceKind, type PrefixReplayResult, type RecordedTrajectoryStep, type ReplayArmVerdict, type ReplayBatchCaseRow, type ReplayBatchFixResult, type ReplayBatchOptions, type ReplayBatchReport, type ReplayExclusionReason, type ReplayExecBackend, type ReplayExecBackendFactory, type ReplayExecResult, type ReplayExecSession, type ReplayFindingOptions, type ReplayFindingResult, type ReplayVerdict, type ReplayVerifyOptions, type ReplayableCase, type ResolvedFindingReplay, type ResolvedReplayInvocation, type ResourceResolution, SUBMIT_ACTION_SIGNATURE, SandboxCounterfactualRunner, type SandboxCounterfactualRunnerOptions, type VerifiableFinding, type VerifyFindingsOptions, type VerifyFindingsRun, buildFixPrompt, buildRetryFixPrompt, classifyPrefixStep, classifyVerdict, clipText, countScriptCommands, deriveFailureSignature, derivedImageTag, dockerImagePreparer, enumerateReplayableCases, extractFixCommand, findingReplayStep, findingTrajectoryId, generateFixCommand, goldIncorrectSteps, ingestRecordedTrajectory, isSubmitAction, parseCorpusFlag, parseIncorrectStepsSubject, parseObservationOutput, parseRecordedReturncode, readFindingsFile, readLabelEntries, renderBatchReport, renderVerifiedFindingsSection, replayVerify, replayVerifyFinding, resolveCaseResources, resolveFindingInvocation, resolveFindingReplayability, runFixLoop, runReplayBatch, seededSample, summarizePrefixReplay, verifyFindings, wrapActionForExec };
+//# sourceMappingURL=index.d.ts.map