import { type ParseError } from "../statelog/parse.js";
import type { EventEnvelope } from "../statelog/wireTypes.js";
/** One trace: every event sharing a `trace_id`, in file order, with the raw
 *  lines it came from and a digest of its content. */
export type Trace = {
    traceId: string;
    events: EventEnvelope[];
    lines: string[];
    digest: string;
};
export type ReadTracesResult = {
    traces: Trace[];
    errors: ParseError[];
};
/** sha256 over the sha256 of each canonicalized event, in order, so two
 *  serializations of the same events (different key order, different
 *  whitespace) share a digest. Each event is hashed on its own, so no string
 *  ever holds a whole trace. The digest is only compared in memory (the merge
 *  planner, the run directory's snapshot check), never stored. */
export declare function traceDigest(events: readonly EventEnvelope[]): string;
/**
 * Read a statelog file into traces, grouped by `trace_id` in first-seen order.
 *
 * This is the many-trace, byte-preserving reader; `StatelogParser`
 * (lib/eval/statelogParser.ts) is the one-trace, one-file view for graders.
 * Both parse lines with `parseStatelogLine`, and a trace's eval record is
 * still `extractEvalRecord` (see `evalRecord.ts`). What is new here is only
 * grouping by id, keeping raw lines for merging, and the digest.
 *
 * The file is read one chunk of lines at a time, so its text is never one
 * string, and its partial last line follows the line reader's rule for a
 * finished file (`LineReader.finish`). A line
 * byte-identical to one already seen for its trace is dropped: that is the
 * harmless result of `cat`-ing two copies of one trace. Nothing more is
 * checked here — two different streams sharing an id cannot be told apart once
 * concatenated; `mergeStatelog` refuses that while they are still separate.
 */
export declare function readTraces(statelogPath: string): ReadTracesResult;
/** For writers: a statelog with any unparseable line is refused whole, since a
 *  trace stored without its bad lines would look complete and be judged as
 *  such. Readers stay tolerant (`readTraces`). */
export declare function readTracesOrThrow(statelogPath: string): Trace[];
export type TraceMatch = {
    kind: "one";
    trace: Trace;
} | {
    kind: "none";
} | {
    kind: "ambiguous";
    ids: string[];
};
/** Resolve a full id or a unique prefix (the viewer shows shortened ids). */
export declare function matchTrace(traces: readonly Trace[], idOrPrefix: string): TraceMatch;
export type TraceIdMatch = {
    kind: "one";
    id: string;
} | {
    kind: "none";
} | {
    kind: "ambiguous";
    ids: string[];
};
/** The one rule for what a trace id argument means, over ids alone, so the
 *  viewer and the CLI agree on which trace `7f3a` is. */
export declare function matchTraceId(ids: readonly string[], idOrPrefix: string): TraceIdMatch;
export type TraceIdArgument = {
    kind: "one";
    id: string;
} | {
    kind: "problem";
    message: string;
};
/** The trace a `--trace-id` value names, or the message to show when it
 *  names none or several. The CLI prints the message; the viewer shows it. */
export declare function resolveTraceIdArgument(ids: readonly string[], idOrPrefix: string): TraceIdArgument;