@moqtap/trace 0.2.0 → 0.4.1

package/dist/index.d.ts

@@ -1,28 +1,205 @@
 import { SessionState } from '@moqtap/codec/session';
 
-type DetailLevel = 'control' | 'headers' | 'headers+sizes' | 'headers+data' | 'full';
-type Perspective = 'client' | 'server' | 'observer';
+/**
+ * Any string other than the ones named beside it.
+ *
+ * Unions built with this keep editor completion for the values this version
+ * knows, while still accepting a value it does not. Nothing in the format
+ * rejects an unrecognised string: new perspectives, detail levels and drop
+ * policies may be added without a version bump, and a reader that refused one
+ * would refuse a file it can otherwise read in full.
+ */
+type OtherString = string & Record<never, never>;
+type DetailLevel = 'control' | 'headers' | 'headers+sizes' | 'headers+data' | 'full' | OtherString;
+type Perspective = 'client' | 'server' | 'observer' | 'relay-tap' | OtherString;
+/** Drop strategy a sampled source applied when it could not keep up. */
+type DropPolicy = 'head' | 'tail' | 'sampled' | OtherString;
+/** Length of a trace ID, in bytes. Fixed by the format. */
+declare const TRACE_ID_LENGTH = 16;
+/**
+ * Per-segment metadata.
+ *
+ * Present only in segmented traces. A single-shot file must not carry it —
+ * its absence is what tells a reader that sequence numbers and timestamps are
+ * file-global rather than segment-local.
+ */
+interface SegmentInfo {
+    /** 0-based sequence number of this segment within the stream. */
+    readonly sequence: number;
+    /** Nominal segment duration in milliseconds. A hint; the real one may differ. */
+    readonly durationMs?: number;
+    /** Opaque identifier shared by every segment of the same logical stream. */
+    readonly streamId?: string;
+    /** True if this segment continues a previous one with the same `streamId`. */
+    readonly continues?: boolean;
+    /**
+     * Keys in the `"segment"` map this version does not recognise, kept verbatim
+     * and written back inside that map rather than at the top level.
+     *
+     * See {@link TraceHeader.extra}, which this mirrors — including the part
+     * about a key this version *does* know whose value it cannot use.
+     */
+    readonly extra?: Record<string, unknown>;
+}
+/**
+ * Sampling and filtering metadata. Present only when events were dropped or
+ * filtered at the source; its absence means the trace is complete relative to
+ * its detail level.
+ */
+interface SamplingInfo {
+    /** Fraction of source events retained, in (0, 1]. */
+    readonly effectiveRate?: number;
+    /** Per-segment cap that triggered drops, if rate-limited. */
+    readonly maxEventsPerSec?: number;
+    /** Drop strategy applied when the cap was exceeded. */
+    readonly dropPolicy?: DropPolicy;
+    /** Cumulative events dropped since `startTime`. */
+    readonly droppedTotal?: number;
+    /** Events dropped within this segment only. */
+    readonly droppedSegment?: number;
+    /** Source-side filter rule that selected events. */
+    readonly rule?: string;
+    /** Language the rule is written in ('prefix', 'glob', 'cel'). */
+    readonly ruleLang?: string;
+    /**
+     * Event type IDs the drop policy was applied to.
+     *
+     * All or nothing: an array with one element that is not an event type ID is
+     * unusable *entire* and stays in {@link extra}. Keeping the elements that
+     * read cleanly would not be a partial answer but a wrong one — this key
+     * names the types the policy touched, and every type absent from it may be
+     * treated as complete, so a shortened array reports a sampled type as fully
+     * recorded.
+     */
+    readonly appliesTo?: number[];
+    /**
+     * Keys in the `"sampling"` map this version does not recognise, kept
+     * verbatim and written back inside that map rather than at the top level.
+     *
+     * See {@link TraceHeader.extra}, which this mirrors.
+     */
+    readonly extra?: Record<string, unknown>;
+}
 interface TraceHeader {
     readonly protocol: string;
     readonly perspective: Perspective;
     readonly detail: DetailLevel;
+    /**
+     * Recording start (Unix epoch milliseconds). In a segmented trace this is
+     * the segment's start, not the stream's.
+     */
     readonly startTime: number;
     readonly endTime?: number;
     readonly transport?: string;
     readonly source?: string;
     readonly endpoint?: string;
     readonly sessionId?: string;
+    /** Present only when this header begins one segment of a segmented stream. */
+    readonly segment?: SegmentInfo;
+    /** Present only when events were dropped or filtered at the source. */
+    readonly sampling?: SamplingInfo;
+    /**
+     * User-defined metadata, handed back key for key and value for value.
+     *
+     * A passthrough, and the one map in the header with no store of its own:
+     * every key in it belongs to whoever wrote the trace, so there is no such
+     * thing as an unrecognised key there. A `"custom"` this reader cannot hold
+     * exactly — one that is not a map at all — is therefore unusable as a whole
+     * and goes to {@link extra}, leaving this field absent rather than typed as
+     * a record it is not.
+     */
     readonly custom?: Record<string, unknown>;
+    /**
+     * Keys in the header map that this version of the package does not
+     * recognise, kept verbatim.
+     *
+     * The same guarantee a `TraceEvent`'s `extra` gives one level down, and for
+     * the same reason: "unknown keys MUST be ignored" is a rule about reading
+     * *past* them, not a licence to drop them. A tool that reads a trace and
+     * writes it back — a redaction pass, a filter, a re-segmentation, a download
+     * with annotations applied — would otherwise emit a valid file that looks as
+     * though it never carried them, and one tool's ignorance would become
+     * permanent for every reader downstream of it.
+     *
+     * A key this version *does* know counts as unrecognised when its value is of
+     * a type the field cannot hold. `"transport": 42` is not a transport; it is
+     * also not nothing. Such a value is kept here rather than coerced into the
+     * field or dropped, {@link transport} reads as absent, and the key is
+     * written back unchanged. Knowing more about a key must not mean preserving
+     * it less.
+     *
+     * Three maps in the header carry a store — this one, {@link SegmentInfo} and
+     * {@link SamplingInfo} — and each is written back into the map it came from.
+     * One store for the whole header would not do: a private key on `"segment"`
+     * and a key of the same name at the top level are different keys, and
+     * re-emitting either in the other's map changes what the file says.
+     */
+    readonly extra?: Record<string, unknown>;
 }
 interface BaseEvent {
+    /**
+     * Monotonically increasing sequence number. Segment-local in a segmented
+     * trace, so ordering across segments is `(segment.sequence, seq)`.
+     */
     readonly seq: number;
+    /** Microseconds since the containing segment's `startTime`. */
     readonly timestamp: number;
+    /**
+     * Which peer this event pertains to.
+     *
+     * Required when the perspective is `'relay-tap'`, where one trace covers
+     * many concurrent sessions; omitted otherwise. The identifier is
+     * source-local: the same string in two traces from different sources does
+     * not name the same peer.
+     */
+    readonly peer?: string;
+    /**
+     * Keys on this event that this version of the package does not recognise,
+     * kept verbatim.
+     *
+     * Optional keys may be added to an existing event type without a format
+     * version bump, so "unknown keys MUST be ignored" is a rule about *reading
+     * past* them. It is not a licence to drop them: a tool that reads a trace
+     * and writes it back — a redaction pass, a filter, an annotated download —
+     * would otherwise emit a valid file that looks like it never carried them,
+     * and one tool's ignorance would become permanent for every reader
+     * downstream of it.
+     *
+     * A key this version *does* know counts as unrecognised when its value is of
+     * a type the field cannot hold — a `"ta"` carrying text, say. It is kept
+     * here rather than coerced into the field or dropped, and written back
+     * unchanged, exactly as a key nobody had heard of would be. Knowing more
+     * about a key must not mean preserving it less.
+     *
+     * {@link UnknownEvent} already does this for an event type the package
+     * cannot name. This is the same guarantee one level down, for a key on a
+     * type it can. It is always absent on an `UnknownEvent`, whose `fields`
+     * hold every non-common key already.
+     */
+    readonly extra?: Record<string, unknown>;
 }
 interface ControlMessageEvent extends BaseEvent {
     readonly type: 'control';
     readonly direction: 0 | 1;
     readonly messageType: number;
-    readonly message: Record<string, unknown>;
+    /**
+     * The message's decoded fields — the `"msg"` field of Event 0.
+     *
+     * A writer MUST produce a map here, keyed in snake_case (`request_id`,
+     * `track_alias`), and an empty one when it decoded nothing. A *reader* has
+     * to accept less, because files written before the format said so exist:
+     * every `capture-*` case in the conformance corpus carries a Rust `Debug`
+     * rendering of the message instead — `'Draft16(ClientSetup(ClientSetup {
+     * parameters: [] }))'` — and the format requires such a value to be handed
+     * back unchanged rather than rejected or replaced.
+     *
+     * So the type is `unknown`, not `Record<string, unknown>`. The `Record` was
+     * a lie the compiler could not catch: `event.message.request_id` typechecks
+     * against a string and reads `undefined` at runtime, on exactly the files
+     * this rule exists for. Narrow before reading keys — {@link
+     * controlMessageFields} does it correctly.
+     */
+    readonly message: unknown;
     readonly raw?: Uint8Array;
     /**
      * QUIC stream the message travelled on.
@@ -34,11 +211,80 @@ interface ControlMessageEvent extends BaseEvent {
      */
     readonly streamId?: bigint;
 }
+/**
+ * The decoded fields of a control message, or `undefined` when its `"msg"` is
+ * not a map and there are no fields to address.
+ *
+ * Provided because the narrowing is easy to get wrong once per call site and
+ * silently: `typeof message === 'object'` also admits `null`, a CBOR array,
+ * and a byte string, each of which would then be typed as a field map and
+ * read back `undefined` for every key. A caller that skips the check entirely
+ * gets the bug this function exists to prevent — see
+ * {@link ControlMessageEvent.message}.
+ */
+declare function controlMessageFields(message: unknown): Record<string, unknown> | undefined;
 interface StreamOpenedEvent extends BaseEvent {
     readonly type: 'stream-opened';
     readonly streamId: bigint;
     readonly direction: 0 | 1;
     readonly streamType: 0 | 1 | 2;
+    /**
+     * Track alias the stream carries. Written whenever the recorder knows it.
+     *
+     * The stream header carries the alias and no detail level records that
+     * header's bytes, so before this field a `'headers'` recording could not say
+     * which track a stream belonged to — which is most of what the level exists
+     * to answer, and there was nothing left to re-parse it from.
+     *
+     * `bigint`, and so are the three fields below, unlike this event's
+     * `direction` and `streamType`. Those two are small enumerations that a
+     * narrow type suits; these four are wire identifiers with the same range as
+     * {@link ObjectHeaderEvent}'s `groupId`, `objectId` and `streamId`, and
+     * readers compare the two events. Typed as `number` here, a match would read
+     * as a mismatch: `streamOpened.groupId === objectHeader.groupId` evaluates
+     * `42 === 42n`, which is `false`, with no error, for every pair of values
+     * that are in fact the same.
+     *
+     * Absent when the file's `"ta"` was not an unsigned integer — and the same
+     * for the three fields below. Such a value belongs to no field here, so it
+     * stays verbatim in {@link BaseEvent.extra} and is written back as it came.
+     * It is never coerced on the way in: `true` and the text `"4"` are not track
+     * alias 1 and track alias 4, however willingly `BigInt` converts them.
+     */
+    readonly trackAlias?: bigint;
+    /**
+     * Subgroup ID, on a subgroup stream (`streamType === 0`).
+     *
+     * A writer must not set it on another stream type, where nothing supplies
+     * it. A reader that meets one there keeps it rather than rejecting the
+     * event: an out-of-scope key makes one field meaningless, not the file
+     * unreadable, and discarding the event throws away every other field on it —
+     * all of which were fine. That is about the key being in the wrong place; a
+     * `"sg"` of the wrong *shape* is not held here at all, but in
+     * {@link BaseEvent.extra}.
+     */
+    readonly subgroupId?: bigint;
+    /**
+     * Fetch request ID, on a fetch stream (`streamType === 2`).
+     *
+     * A writer MUST set it there. It is the only correlation between the stream
+     * and the FETCH that asked for it, and without it a fetch stream cannot be
+     * attributed to a request at all. A reader must nevertheless accept a fetch
+     * stream that lacks one — every recording made before the key existed lacks
+     * it — for the same reason as the `'msg'` asymmetry on
+     * {@link ControlMessageEvent.message}: writers conform, readers tolerate.
+     */
+    readonly fetchRequestId?: bigint;
+    /**
+     * Group ID, on a datagram stream (`streamType === 1`).
+     *
+     * Scoped to datagrams because on a subgroup stream every object carries the
+     * same group by construction, so a copy here would be a second field with no
+     * independent source. Where an {@link ObjectHeaderEvent} for the same stream
+     * disagrees, that event wins and this is not corruption: this copy is a
+     * convenience for a reader that has not yet seen an object.
+     */
+    readonly groupId?: bigint;
 }
 interface StreamClosedEvent extends BaseEvent {
     readonly type: 'stream-closed';
@@ -66,17 +312,187 @@ interface StateChangeEvent extends BaseEvent {
     readonly from: string;
     readonly to: string;
 }
+/**
+ * What sort of failure an error event records.
+ *
+ * An open vocabulary: this revision names the three below, others may be added
+ * without a format version bump, and a reader must preserve a value it does not
+ * recognise rather than reject the event — the same contract as {@link
+ * Perspective} and {@link DetailLevel}, which is why all three widen with
+ * `OtherString` instead of being closed unions.
+ */
+type ErrorKind = 
+/** The peer violated the protocol. */
+'protocol'
+/** The QUIC or WebTransport layer failed. */
+ | 'transport'
+/** Bytes that would not parse as any message this recorder knows. */
+ | 'decode' | OtherString;
 interface TraceErrorEvent extends BaseEvent {
     readonly type: 'error';
     readonly errorCode: number;
     readonly reason: string;
+    /**
+     * QUIC stream the error was observed on.
+     *
+     * Optional on the same terms as {@link ControlMessageEvent.streamId}: absent
+     * means there was no stream, or that the recorder knew of none, which a
+     * reader MUST distinguish from stream `0`. `bigint` for the reason given
+     * there — it is the same wire identifier, and `number` stops being exact at
+     * 2^53, which would make this reader disagree with the Rust one silently and
+     * only for large values.
+     *
+     * It may name a *data* stream, which is why {@link rawLength} is gated a
+     * level above this event rather than travelling with it: the length behind an
+     * error on a subgroup stream is the size of a run of media framing.
+     */
+    readonly streamId?: bigint;
+    /**
+     * What sort of failure this was.
+     *
+     * Spelt out rather than `kind` because {@link SubscriptionDerivationEvent}
+     * already owns that name with the unrelated vocabulary `'created'` /
+     * `'shared'`. Two vocabularies under one name survive in a typed reader and
+     * break in every flat projection of a trace — a JSONL export, a warehouse
+     * load, this package's own {@link traceToJSON} — where they become one column
+     * holding both. The wire key is `"ek"` for the same reason.
+     */
+    readonly errorKind?: ErrorKind;
+    /**
+     * How many bytes the recorder held for this error, before any truncation.
+     *
+     * Not the length of {@link raw}: where the two differ the capture is partial,
+     * and this is how a reader learns how much is missing. A `raw` of exactly
+     * `MAX_ERROR_RAW_BYTES` with no `rawLength` beside it must be treated as
+     * possibly truncated, that being the one length the cap makes ambiguous.
+     *
+     * Recorded from `'headers+sizes'` up — one level below {@link raw} and
+     * deliberately not with it. It is a size and carries no content, so it is
+     * available in every trace where the bytes themselves must not appear, and
+     * how large a malformed message was often separates a truncated message from
+     * a mistyped one on its own.
+     */
+    readonly rawLength?: number;
+    /**
+     * The bytes behind the error.
+     *
+     * Payload-bearing, and recorded only at `'full'`: an error naming a data
+     * stream has subgroup framing and object payload behind it, so inheriting
+     * this event's own `control`+ level would have put media into traces whose
+     * declared level excludes payloads entirely.
+     *
+     * The 4096-byte cap on this field binds a *recorder* — see
+     * `MAX_ERROR_RAW_BYTES` in `recorder.ts`, which is where it is applied and
+     * the only place it appears. It does not bind this type, the reader or the
+     * writer: a longer value read out of a file is handed over whole and written
+     * back whole. Re-truncating it would destroy evidence to make someone else's
+     * file conform to a rule that was never addressed to the tool doing the
+     * truncating.
+     */
+    readonly raw?: Uint8Array;
 }
 interface AnnotationEvent extends BaseEvent {
     readonly type: 'annotation';
     readonly label: string;
     readonly data: unknown;
 }
-type TraceEvent = ControlMessageEvent | StreamOpenedEvent | StreamClosedEvent | ObjectHeaderEvent | ObjectPayloadEvent | StateChangeEvent | TraceErrorEvent | AnnotationEvent;
+/** Role a peer is acting in at connection time. */
+type PeerRole = 'publisher' | 'subscriber' | 'both' | OtherString;
+/**
+ * Which end of a relay a peer sits on.
+ *
+ * This is the direction the connection was made in, not the direction
+ * subscriptions flow. For subscription causality see
+ * {@link SubscriptionDerivationEvent}.
+ */
+type Side = 'downstream' | 'upstream' | OtherString;
+/**
+ * A new peer session was established. Emitted only by `'relay-tap'` sources;
+ * the peer it identifies is on the event's `peer` field.
+ */
+interface PeerConnectedEvent extends BaseEvent {
+    readonly type: 'peer-connected';
+    readonly endpoint?: string;
+    readonly transport?: string;
+    readonly role?: PeerRole;
+    readonly side?: Side;
+}
+/** A peer session ended. Emitted only by `'relay-tap'` sources. */
+interface PeerDisconnectedEvent extends BaseEvent {
+    readonly type: 'peer-disconnected';
+    readonly errorCode: number;
+    readonly reason?: string;
+}
+/**
+ * A `(peer, request id)` pair naming one subscription on one peer.
+ *
+ * Request ids are unique only within a peer's session, so neither half
+ * identifies a subscription on its own.
+ */
+interface SubscriptionRef {
+    readonly peer: string;
+    readonly requestId: bigint;
+}
+/** How an upstream subscription came to serve a downstream one. */
+type DerivationKind = 'created' | 'shared' | OtherString;
+/**
+ * An upstream subscription was created or extended in causal response to
+ * downstream ones. Emitted only by `'relay-tap'` sources.
+ *
+ * This is the primitive multi-hop correlation is built from: a collector
+ * reconstructs an end-to-end tree from these links plus the trace ids
+ * propagated along them.
+ *
+ * The four timestamps share the `timestamp` field's timebase — the emitting
+ * source's own clock. Differences between them are meaningful with no
+ * cross-hop clock agreement, which is the point: they measure how long one
+ * hop took. Never subtract one source's timestamp from another's.
+ *
+ * A source emits the event as soon as the downstream SUBSCRIBE arrives,
+ * carrying whichever timestamps it has, and may emit it again for the same
+ * pair as the rest arrive. Treat a later event for the same pair as an update
+ * to the earlier one, not as a second derivation.
+ */
+interface SubscriptionDerivationEvent extends BaseEvent {
+    readonly type: 'subscription-derivation';
+    readonly upstream: SubscriptionRef;
+    /** Every downstream subscription currently served by `upstream`. */
+    readonly downstream: SubscriptionRef[];
+    readonly kind: DerivationKind;
+    /**
+     * Trace id propagated along the subscription chain: exactly
+     * {@link TRACE_ID_LENGTH} raw bytes, never hex- or base64-encoded, so two
+     * implementations produce identical values for the same chain.
+     */
+    readonly traceId?: Uint8Array;
+    /** Track namespace the subscription targets, one entry per field. */
+    readonly namespace?: Uint8Array[];
+    readonly trackName?: Uint8Array;
+    /** When the downstream SUBSCRIBE was received. */
+    readonly tDownstreamReceived?: number;
+    /** When the upstream SUBSCRIBE was sent. Absent for a terminal subscription. */
+    readonly tUpstreamSent?: number;
+    /** When SUBSCRIBE_OK arrived from upstream. */
+    readonly tUpstreamOkReceived?: number;
+    /** When SUBSCRIBE_OK was sent downstream. */
+    readonly tDownstreamOkSent?: number;
+}
+/**
+ * An event whose type this version of the package does not know.
+ *
+ * New event types may be added without a format version bump, so a reader
+ * that dropped or relabelled them would make one tool's ignorance permanent
+ * for everything downstream of it. The fields are kept verbatim, so an
+ * unknown event survives a read-modify-write round trip intact.
+ */
+interface UnknownEvent extends BaseEvent {
+    readonly type: 'unknown';
+    /** The `"e"` discriminant that was read. */
+    readonly eventType: number;
+    /** Every key from the event map other than `n`, `t`, `p` and `e`. */
+    readonly fields: Record<string, unknown>;
+}
+type TraceEvent = ControlMessageEvent | StreamOpenedEvent | StreamClosedEvent | ObjectHeaderEvent | ObjectPayloadEvent | StateChangeEvent | TraceErrorEvent | AnnotationEvent | PeerConnectedEvent | PeerDisconnectedEvent | SubscriptionDerivationEvent | UnknownEvent;
 interface Trace {
     readonly header: TraceHeader;
     readonly events: TraceEvent[];
@@ -89,22 +505,166 @@ interface RecorderOptions {
     readonly source?: string;
     readonly endpoint?: string;
     readonly sessionId?: string;
+    /**
+     * Extra header keys to write, for a recorder that has something to say the
+     * format has no key for.
+     *
+     * Goes to {@link TraceHeader.extra} on the finalized trace and is written
+     * into the header map after the keys above. Use the `"x-"` prefix the format
+     * reserves for private use; a key the format defines is dropped here rather
+     * than written twice, since the field always wins.
+     */
+    readonly extra?: Record<string, unknown>;
     readonly maxEvents?: number;
     readonly clock?: () => number;
     /** Map message type name (e.g. 'subscribe') to wire ID (e.g. 0x03). Required for session-layer recording. */
     readonly messageTypeId?: (name: string) => number;
 }
 
+/** Format version this package writes. */
+declare const FORMAT_VERSION = 2;
+/**
+ * Format versions this package reads.
+ *
+ * Version 1 is a non-segmented version 2 trace carrying none of the keys
+ * version 2 added, so reading it costs nothing and keeps every capture taken
+ * before the bump openable.
+ */
+declare const SUPPORTED_VERSIONS: readonly number[];
+/** The stream ended part-way through an item — the file was truncated. */
+declare class TruncatedTraceError extends Error {
+    /** Byte offset at which the incomplete item begins. */
+    readonly offset: number;
+    /**
+     * Everything that decoded before the cut, one entry per segment. A
+     * truncated trace is still evidence, and the events before the cut are
+     * exactly as valid as they were.
+     */
+    readonly segments: Trace[];
+    constructor(offset: number, segments: Trace[]);
+    /** What decoded, flattened as {@link readMoqtrace} would return it. */
+    get trace(): Trace | undefined;
+}
+/**
+ * A header carried no usable value for a key there is no header without.
+ *
+ * Five keys reach here: the four the format requires — `"protocol"`,
+ * `"perspective"`, `"detail"`, `"startTime"` — and `"segment.sequence"`, the
+ * sole ordering key of a segmented stream. Every other key in the header is
+ * optional, and an optional key's value never fails a file: an unusable one
+ * goes to the store its map keeps and the read continues.
+ *
+ * The alternative is worse than the error. A reader that fills a missing
+ * required key with `undefined`, an empty string or `0` returns a header the
+ * file never carried, and nothing downstream can tell it from a real one — a
+ * fabricated trace reported as evidence. `"segment.sequence"` is the sharpest
+ * case: the default `0` turns a segment whose place in the stream is unknown
+ * into one that claims to be first.
+ *
+ * Malformed here means malformed for *that segment*. {@link ReadOptions.recover}
+ * skips it and carries on at the next one, on the same terms as a malformed
+ * event.
+ *
+ * The writer throws the same error for the same key, before it emits anything.
+ * `"startTime"` and `"segment.sequence"` are `number` fields and TypeScript
+ * admits `-5` and `1.5` into both, so a header built by hand could be written
+ * to a file this package's own reader then refused — a writer emitting files
+ * only some other tool can open, out of a caller mistake nothing reported at
+ * the point it was made. One error type for both directions because it is one
+ * fault about one key, and a read-modify-write catches it once.
+ */
+declare class MalformedHeaderError extends Error {
+    /** The key at fault, dotted for one inside `"segment"`. */
+    readonly key: string;
+    /**
+     * @param key the key at fault
+     * @param fault what was wrong with it, as a predicate on the key
+     */
+    constructor(key: string, fault: string);
+}
+/** Options shared by the readers. */
+interface ReadOptions {
+    /**
+     * On a truncated or corrupt region, skip forward to the next segment and
+     * carry on instead of throwing.
+     *
+     * This is the recovery segmentation exists to offer: one damaged segment
+     * costs that segment rather than the rest of the capture. It can only help
+     * a segmented trace — there is nothing to resynchronize to in a single
+     * segment, so a damaged one still ends the read, just without an error.
+     */
+    readonly recover?: boolean;
+    /**
+     * Called once for each region `recover` skipped.
+     *
+     * Without it a recovered read cannot be told from a clean one: the return
+     * type carries no error channel, so a trace that lost a segment and a trace
+     * that never had one are the same value.
+     */
+    readonly onRecovered?: (region: RecoveredRegion) => void;
+}
+/** A region `recover` could not read. */
+interface RecoveredRegion {
+    /** Byte offset the unreadable region began at. */
+    readonly offset: number;
+    /**
+     * What was lost: `header` drops the whole segment, `event` cuts the segment
+     * in progress short, `truncated` means the item ran past end of file.
+     */
+    readonly kind: 'header' | 'event' | 'truncated';
+    /**
+     * Offset the read resumed at, or `undefined` when no further segment
+     * followed — everything from `offset` on was then discarded.
+     */
+    readonly resumedAt: number | undefined;
+    /** The decode failure, absent when the region was merely truncated. */
+    readonly cause?: unknown;
+}
 /**
  * Write a complete trace to .moqtrace binary format.
  */
 declare function writeMoqtrace(trace: Trace): Uint8Array;
+/**
+ * Write several segments back to back as one segmented `.moqtrace` stream.
+ *
+ * Every segment header must carry {@link SegmentInfo}. That field is what
+ * tells a reader the sequence numbers and timestamps it is about to see
+ * restart at zero; a segmented stream written without it reads as a run of
+ * complete files whose timeline jumps backwards at every boundary, and
+ * nothing downstream can detect that it happened.
+ */
+declare function writeMoqtraceSegments(segments: Trace[]): Uint8Array;
 /**
  * Read a complete .moqtrace file from bytes.
+ *
+ * A segmented file is flattened: the returned header is the first segment's,
+ * and the events of every segment follow in order. Use
+ * {@link readMoqtraceSegments} to see the boundaries — you need them to order
+ * events across segments, since `seq` and `timestamp` restart in each.
+ *
+ * @throws {TruncatedTraceError} if the file stops part-way through an item.
+ *   The error carries everything that decoded before the cut.
+ * @throws {MalformedHeaderError} if a segment header carries no usable value
+ *   for a required key. Pass `recover` to skip that segment instead.
  */
-declare function readMoqtrace(bytes: Uint8Array): Trace;
+declare function readMoqtrace(bytes: Uint8Array, options?: ReadOptions): Trace;
+/**
+ * Read a .moqtrace file as its segments, one entry per segment.
+ *
+ * A non-segmented file yields exactly one entry, whose header carries no
+ * `segment` field.
+ *
+ * @throws {MalformedHeaderError} as {@link readMoqtrace} does.
+ */
+declare function readMoqtraceSegments(bytes: Uint8Array, options?: ReadOptions): Trace[];
 /**
  * Read only the header from a .moqtrace file (fast metadata peek).
+ *
+ * In a segmented file this is the first segment's header.
+ *
+ * @throws {MalformedHeaderError} if that header carries no usable value for a
+ *   required key. There is no partial header to hand back and no later segment
+ *   to fall forward to, so this one always throws.
  */
 declare function readMoqtraceHeader(bytes: Uint8Array): TraceHeader;
 /**
@@ -115,6 +675,16 @@ interface MoqtraceWriter {
     preamble(): Uint8Array;
     /** Encode a single event. Append the returned bytes after the preamble. */
     writeEvent(event: TraceEvent): Uint8Array;
+    /**
+     * Begin a new segment: returns a fresh preamble to append after the
+     * previous segment's last event.
+     *
+     * The header must carry {@link SegmentInfo} — see
+     * {@link writeMoqtraceSegments} for why. It should keep the same
+     * `protocol`, `perspective`, `detail` and `sessionId` as the segments
+     * before it, and increment `segment.sequence`.
+     */
+    startSegment(header: TraceHeader): Uint8Array;
 }
 declare function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter;
 
@@ -125,15 +695,223 @@ declare function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter;
  * This is a one-way export for human inspection and debugging.
  * For lossless round-tripping, use the binary .moqtrace format
  * (`writeMoqtrace` / `readMoqtrace`).
+ *
+ * The unrecognised-key stores are part of the rendering rather than filtered
+ * out of it: `extra` appears on the header, on `segment`, on `sampling` and on
+ * each event, nested values and all. A view that showed only the keys this
+ * version names would reintroduce, for anyone reading a trace through it,
+ * exactly the loss the binary reader stopped making — and it is the view
+ * someone reaches for precisely when they suspect a key went missing.
  */
 declare function traceToJSON(trace: Trace): string;
 
+/**
+ * Incremental reader for the `.moqtrace` binary format.
+ *
+ * The three entry points in `binary.ts` all take the whole file at once, which
+ * a live capture does not have: the bytes arrive in chunks whose boundaries
+ * fall wherever the transport put them, almost never on an item boundary. This
+ * reader takes those chunks and hands back the items that have become whole,
+ * keeping the remainder for the next one.
+ *
+ * It is the read side of {@link createMoqtraceWriter}, which has been
+ * incremental from the start — the asymmetry this closes was one-sided.
+ *
+ * Decoding is not reimplemented here. The header and event decoders are
+ * imported from `binary.ts` so that a trace read in instalments and the same
+ * trace read whole produce the same values. A second decoder would be a second
+ * set of answers, and nothing tests two readers of one format against each
+ * other, so the disagreement would surface as a rendering bug somewhere far
+ * from here.
+ */
+
+/**
+ * The stream ended part-way through an item.
+ *
+ * Deliberately not `TruncatedTraceError`, whose `segments` field promises
+ * "everything that decoded before the cut". An incremental reader has already
+ * handed those events to its caller and does not keep them, so it cannot fill
+ * that field — and filling it with an empty array would report a trace that
+ * decoded nothing, which is a wrong answer rather than a missing one. The
+ * caller holds what decoded; this says only where the bytes stopped.
+ */
+declare class TruncatedStreamError extends Error {
+    /**
+     * Offset into the whole stream at which the incomplete item begins — not
+     * where the bytes ran out. It matches the Rust reader's
+     * `MoqTraceError::Truncated { offset }`, so the same cut is named the same
+     * number in both languages.
+     */
+    readonly offset: number;
+    /**
+     * How many events reached the caller before the cut.
+     *
+     * The events themselves are gone — that is what makes this error different
+     * from {@link TruncatedTraceError} — but their count is not, and it costs one
+     * integer to keep. It is the difference between "the stream was cut" and "the
+     * stream was cut after 4,812 events at byte 190,224", and only the second
+     * tells whoever is holding a damaged capture how much of it they still have.
+     */
+    readonly events: number;
+    constructor(offset: number, events: number);
+}
+/**
+ * One thing the reader has finished reading.
+ *
+ * The two kinds mirror the Rust crate's `ReadItem`, so a consumer that has read
+ * one implementation recognises the other. A `segment` arrives before any event
+ * that belongs to it, including the first one: unlike the Rust reader, which
+ * takes a blocking source and parses the opening header in its constructor,
+ * this one cannot have a header until bytes arrive, so every header reaches the
+ * caller the same way and there is no special case for the first.
+ */
+type ReadItem = {
+    readonly kind: 'segment';
+    readonly header: TraceHeader;
+} | {
+    readonly kind: 'event';
+    readonly event: TraceEvent;
+};
+/** Reads a `.moqtrace` stream in whatever instalments it arrives in. */
+interface MoqtraceReader {
+    /**
+     * Add the next chunk and take everything it completed.
+     *
+     * Returns an empty array when the chunk did not finish an item, which is
+     * ordinary and not a signal of anything. Bytes left over are kept.
+     *
+     * @throws {MalformedHeaderError} if a segment header carries no usable value
+     *   for a key the format requires.
+     * @throws {MalformedCborError} if the bytes at an item boundary are not a
+     *   well-formed CBOR item.
+     */
+    push(chunk: Uint8Array): ReadItem[];
+    /**
+     * Declare the stream complete and take any last item.
+     *
+     * This can return items. An event shorter than the magic cannot be told from
+     * the start of a segment preamble while more bytes might still arrive, so
+     * such an event waits here until `end()` rules the preamble out.
+     *
+     * @throws {TruncatedStreamError} if bytes remain that do not form a whole
+     *   item — the file stops mid-event, mid-preamble or mid-header.
+     */
+    end(): ReadItem[];
+    /**
+     * The header of the segment now being read, or `undefined` before the first
+     * one is whole. In a segmented stream this changes at every boundary.
+     */
+    readonly header: TraceHeader | undefined;
+    /** Bytes held back because they do not yet form a whole item. */
+    readonly pending: number;
+}
+/**
+ * A reader that takes the stream in chunks.
+ *
+ * ```ts
+ * const reader = createMoqtraceReader()
+ * for await (const chunk of stream) {
+ *   for (const item of reader.push(chunk)) {
+ *     if (item.kind === 'event') render(item.event)
+ *   }
+ * }
+ * for (const item of reader.end()) { ... }
+ * ```
+ *
+ * `ReadOptions.recover` has no counterpart here **on purpose.** Its behaviour
+ * in the whole-buffer readers — drop the damaged segment, return the rest, say
+ * nothing — is under revision, because a caller cannot tell three segments from
+ * four with one unreadable. Guessing an answer here would make an incremental
+ * reader the place that shipped it, and a live view is where a silently
+ * dropped segment does the most harm. Until that is settled this reader stops
+ * at damage and says where.
+ */
+declare function createMoqtraceReader(): MoqtraceReader;
+
+/**
+ * The most bytes a recorder may put in an error event's `raw`.
+ *
+ * A MUST in the format, and a fixed number rather than a suggestion, because
+ * an error event is one of the types sampling must not drop: every other
+ * high-volume field is bounded by sampling, so if this one is not bounded here
+ * it is not bounded at all. A peer that opens ten thousand streams and sends
+ * garbage on each is what a fuzzer does to a relay, and the trace of it should
+ * not be larger than the attack.
+ *
+ * It lives here, in the recorder, and appears nowhere in `binary.ts`. The cap
+ * is addressed to the party deciding what to say about traffic it has just
+ * observed — {@link TraceRecorder.recordError}, and nothing else. A serializer
+ * cannot tell a freshly recorded event from one that arrived by being read, so
+ * a cap applied there would either truncate evidence on a rewrite or refuse a
+ * file the reader was required to accept. `writeMoqtrace` therefore writes a
+ * `raw` of any length, and {@link TraceRecorder.record} — which inserts an
+ * event a caller may well have read out of a file — does not apply it either.
+ */
+declare const MAX_ERROR_RAW_BYTES = 4096;
+/**
+ * What a recorder knows about an error beyond its code and reason.
+ *
+ * Every field is optional and each is gated at its own detail level, so one
+ * call site can hand over everything it has and let the recorder keep what its
+ * level allows.
+ */
+interface ErrorDetails {
+    /**
+     * QUIC stream the error was observed on.
+     *
+     * Omit it when there was no stream or none is known — that is what its
+     * absence says, and a reader must not read it as stream `0`.
+     */
+    readonly streamId?: bigint;
+    /** What sort of failure this was. An open vocabulary; any string is legal. */
+    readonly errorKind?: ErrorKind;
+    /**
+     * The offending bytes, in full and untruncated.
+     *
+     * Hand over everything held: the recorder applies {@link
+     * MAX_ERROR_RAW_BYTES} and reports the untruncated length in `rawLength`,
+     * so a caller that pre-truncates loses the one signal saying the capture is
+     * partial. Recorded only at `'full'`, and only once per flow.
+     */
+    readonly raw?: Uint8Array;
+    /**
+     * The length to report, where the caller already holds less than it saw.
+     *
+     * Defaults to `raw.length`, which is right whenever `raw` is everything
+     * there was. Set it to state a length larger than the bytes on hand — a
+     * caller that hit a cap of its own upstream, or one that knows a message's
+     * declared length without having kept it.
+     *
+     * **Set it to `null` when the true length is unknown**, and the key is
+     * omitted. SPEC.md requires that rather than a guess, because the guess is
+     * not neutral: `rawlen` equal to the bytes present is this format's signal
+     * for *not truncated*, so defaulting it would assert a complete capture
+     * exactly where the caller knows least about whether the input was
+     * complete. Absent, a reader treats a `raw` of exactly
+     * {@link MAX_ERROR_RAW_BYTES} as possibly truncated, which is the truth.
+     *
+     * The caller this exists for is real rather than hypothetical: a recorder
+     * that stops *reading* a stream once it will not parse — the sensible thing
+     * to do with such a stream — never holds more than its own cap and cannot
+     * know what it did not read.
+     */
+    readonly rawLength?: number | null;
+}
 interface TraceRecorder {
     /** Wrap a SessionState to auto-record control messages and state changes. */
     wrapSession<M extends {
         type: string;
     }, T extends string>(session: SessionState<M, T>): SessionState<M, T>;
-    /** Record an arbitrary event manually. */
+    /**
+     * Record an arbitrary event manually.
+     *
+     * A passthrough: no detail-level gate, and no cap on an error event's
+     * `raw`, because an event handed here may have been read out of a file
+     * rather than built from observed bytes, and shortening that one would
+     * destroy evidence to enforce a rule addressed to whoever recorded it.
+     * Callers building an event from bytes they just saw want
+     * {@link recordError}.
+     */
     record(event: TraceEvent): void;
     /** Record a stream-opened event. Ignored at 'control' detail level. */
     recordStreamOpened(streamId: bigint, direction: 0 | 1, streamType: 0 | 1 | 2): void;
@@ -143,8 +921,15 @@ interface TraceRecorder {
     recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number): void;
     /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
     recordObjectPayload(streamId: bigint, groupId: bigint, objectId: bigint, size: number, payload?: Uint8Array): void;
-    /** Record a protocol error. */
-    recordError(errorCode: number, reason: string): void;
+    /**
+     * Record a protocol error.
+     *
+     * Recorded at every detail level — an error event is non-droppable — but
+     * `details` is gated key by key: `streamId` and `errorKind` at every
+     * level, `rawLength` from `'headers+sizes'`, and `raw` at `'full'`
+     * alone, capped at {@link MAX_ERROR_RAW_BYTES} and written once per flow.
+     */
+    recordError(errorCode: number, reason: string, details?: ErrorDetails): void;
     /** Record a user-defined annotation. */
     annotate(label: string, data?: unknown): void;
     /** Finalize the trace. Stops recording and returns the trace. */
@@ -154,4 +939,4 @@ interface TraceRecorder {
 }
 declare function createRecorder(options: RecorderOptions): TraceRecorder;
 
-export { type AnnotationEvent, type ControlMessageEvent, type DetailLevel, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type Perspective, type RecorderOptions, type StateChangeEvent, type StreamClosedEvent, type StreamOpenedEvent, type Trace, type TraceErrorEvent, type TraceEvent, type TraceHeader, type TraceRecorder, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, traceToJSON, writeMoqtrace };
+export { type AnnotationEvent, type ControlMessageEvent, type DerivationKind, type DetailLevel, type DropPolicy, type ErrorDetails, type ErrorKind, FORMAT_VERSION, MAX_ERROR_RAW_BYTES, MalformedHeaderError, type MoqtraceReader, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type PeerConnectedEvent, type PeerDisconnectedEvent, type PeerRole, type Perspective, type ReadItem, type ReadOptions, type RecorderOptions, type RecoveredRegion, SUPPORTED_VERSIONS, type SamplingInfo, type SegmentInfo, type Side, type StateChangeEvent, type StreamClosedEvent, type StreamOpenedEvent, type SubscriptionDerivationEvent, type SubscriptionRef, TRACE_ID_LENGTH, type Trace, type TraceErrorEvent, type TraceEvent, type TraceHeader, type TraceRecorder, TruncatedStreamError, TruncatedTraceError, type UnknownEvent, controlMessageFields, createMoqtraceReader, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, readMoqtraceSegments, traceToJSON, writeMoqtrace, writeMoqtraceSegments };