@moqtap/trace 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -32,6 +32,14 @@ interface SegmentInfo {
     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
@@ -53,8 +61,24 @@ interface SamplingInfo {
     readonly rule?: string;
     /** Language the rule is written in ('prefix', 'glob', 'cel'). */
     readonly ruleLang?: string;
-    /** Event type IDs the drop policy was applied to. */
+    /**
+     * 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;
@@ -74,7 +98,43 @@ interface TraceHeader {
     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 {
     /**
@@ -93,12 +153,53 @@ interface BaseEvent {
      * 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.
@@ -110,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';
@@ -142,10 +312,84 @@ 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';
@@ -261,6 +505,16 @@ 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. */
@@ -291,6 +545,43 @@ declare class TruncatedTraceError extends Error {
     /** 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 {
     /**
@@ -303,6 +594,31 @@ interface ReadOptions {
      * 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.
@@ -328,6 +644,8 @@ declare function writeMoqtraceSegments(segments: Trace[]): Uint8Array;
  *
  * @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, options?: ReadOptions): Trace;
 /**
@@ -335,12 +653,18 @@ declare function readMoqtrace(bytes: Uint8Array, options?: ReadOptions): Trace;
  *
  * 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;
 /**
@@ -371,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;
@@ -389,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. */
@@ -400,4 +939,4 @@ interface TraceRecorder {
 }
 declare function createRecorder(options: RecorderOptions): TraceRecorder;
 
-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 };
+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 };