@moqtap/trace 0.1.3 → 0.3.0

package/dist/index.d.cts

@@ -1,22 +1,98 @@
 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;
+}
+/**
+ * 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. */
+    readonly appliesTo?: number[];
+}
 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;
     readonly custom?: 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;
 }
 interface ControlMessageEvent extends BaseEvent {
     readonly type: 'control';
@@ -24,6 +100,15 @@ interface ControlMessageEvent extends BaseEvent {
     readonly messageType: number;
     readonly message: Record<string, unknown>;
     readonly raw?: Uint8Array;
+    /**
+     * QUIC stream the message travelled on.
+     *
+     * Optional, and only meaningful for a recorder that knows it. It matters
+     * from draft-17, where the control plane is no longer one stream: each
+     * request gets its own bidirectional stream and responses carry no request
+     * id, so the stream is the only thing tying a response to its request.
+     */
+    readonly streamId?: bigint;
 }
 interface StreamOpenedEvent extends BaseEvent {
     readonly type: 'stream-opened';
@@ -67,7 +152,103 @@ interface AnnotationEvent extends BaseEvent {
     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[];
@@ -86,16 +267,80 @@ interface RecorderOptions {
     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;
+}
+/** 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;
+}
 /**
  * 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.
+ */
+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.
  */
-declare function readMoqtrace(bytes: Uint8Array): Trace;
+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.
  */
 declare function readMoqtraceHeader(bytes: Uint8Array): TraceHeader;
 /**
@@ -106,6 +351,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;
 
@@ -145,4 +400,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, FORMAT_VERSION, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type PeerConnectedEvent, type PeerDisconnectedEvent, type PeerRole, type Perspective, type ReadOptions, type RecorderOptions, 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, TruncatedTraceError, type UnknownEvent, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, readMoqtraceSegments, traceToJSON, writeMoqtrace, writeMoqtraceSegments };

package/dist/index.d.ts

@@ -1,22 +1,98 @@
 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;
+}
+/**
+ * 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. */
+    readonly appliesTo?: number[];
+}
 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;
     readonly custom?: 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;
 }
 interface ControlMessageEvent extends BaseEvent {
     readonly type: 'control';
@@ -24,6 +100,15 @@ interface ControlMessageEvent extends BaseEvent {
     readonly messageType: number;
     readonly message: Record<string, unknown>;
     readonly raw?: Uint8Array;
+    /**
+     * QUIC stream the message travelled on.
+     *
+     * Optional, and only meaningful for a recorder that knows it. It matters
+     * from draft-17, where the control plane is no longer one stream: each
+     * request gets its own bidirectional stream and responses carry no request
+     * id, so the stream is the only thing tying a response to its request.
+     */
+    readonly streamId?: bigint;
 }
 interface StreamOpenedEvent extends BaseEvent {
     readonly type: 'stream-opened';
@@ -67,7 +152,103 @@ interface AnnotationEvent extends BaseEvent {
     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[];
@@ -86,16 +267,80 @@ interface RecorderOptions {
     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;
+}
+/** 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;
+}
 /**
  * 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.
+ */
+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.
  */
-declare function readMoqtrace(bytes: Uint8Array): Trace;
+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.
  */
 declare function readMoqtraceHeader(bytes: Uint8Array): TraceHeader;
 /**
@@ -106,6 +351,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;
 
@@ -145,4 +400,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, FORMAT_VERSION, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type PeerConnectedEvent, type PeerDisconnectedEvent, type PeerRole, type Perspective, type ReadOptions, type RecorderOptions, 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, TruncatedTraceError, type UnknownEvent, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, readMoqtraceSegments, traceToJSON, writeMoqtrace, writeMoqtraceSegments };