@moqtap/trace 0.3.0 → 0.4.1

package/dist/index.js

@@ -137,6 +137,11 @@ function cborItemLength(bytes, start) {
 
 // src/types.ts
 var TRACE_ID_LENGTH = 16;
+function controlMessageFields(message) {
+  if (message === null || typeof message !== "object") return void 0;
+  if (Array.isArray(message) || ArrayBuffer.isView(message)) return void 0;
+  return message;
+}
 
 // src/binary.ts
 var codec = new Encoder({ useRecords: false, mapsAsObjects: true, tagUint8Array: false });
@@ -173,6 +178,31 @@ var INT_TO_EVENT_TYPE = {
   10: "subscription-derivation"
 };
 var COMMON_EVENT_KEYS = /* @__PURE__ */ new Set(["n", "t", "p", "e"]);
+function setKey(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+}
+function unrecognisedKeys(src) {
+  let extra;
+  for (const [key, value] of Object.entries(src.obj)) {
+    if (src.used.has(key)) continue;
+    extra ??= {};
+    setKey(extra, key, value);
+  }
+  return extra;
+}
+function withStore(map, store) {
+  if (store == null) return map;
+  for (const [key, value] of Object.entries(store)) {
+    if (Object.hasOwn(map, key)) continue;
+    setKey(map, key, value);
+  }
+  return map;
+}
 var TruncatedTraceError = class extends Error {
   /** Byte offset at which the incomplete item begins. */
   offset;
@@ -193,20 +223,46 @@ var TruncatedTraceError = class extends Error {
     return flatten(this.segments);
   }
 };
+var MalformedHeaderError = class extends Error {
+  /** The key at fault, dotted for one inside `"segment"`. */
+  key;
+  /**
+   * @param key the key at fault
+   * @param fault what was wrong with it, as a predicate on the key
+   */
+  constructor(key, fault) {
+    super(`Malformed header: ${JSON.stringify(key)} ${fault}`);
+    this.name = "MalformedHeaderError";
+    this.key = key;
+  }
+};
+function requiredUint(value, reportedAs) {
+  if (!Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+    throw new MalformedHeaderError(reportedAs, "must be an unsigned integer");
+  }
+  return int(value);
+}
 function segmentToCbor(segment) {
-  const map = { sequence: int(segment.sequence) };
+  const map = {
+    sequence: requiredUint(segment.sequence, "segment.sequence")
+  };
   if (segment.durationMs != null) map.durationMs = int(segment.durationMs);
   if (segment.streamId != null) map.streamId = segment.streamId;
   if (segment.continues != null) map.continues = segment.continues;
-  return map;
+  return withStore(map, segment.extra);
 }
-function cborToSegment(obj) {
-  return {
-    sequence: Number(obj.sequence ?? 0),
-    ...obj.durationMs != null ? { durationMs: Number(obj.durationMs) } : {},
-    ...obj.streamId != null ? { streamId: obj.streamId } : {},
-    ...obj.continues != null ? { continues: obj.continues } : {}
+function cborToSegment(value) {
+  const obj = asMap(value);
+  if (obj == null) return void 0;
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const segment = {
+    sequence: requireHeaderUint(src, "sequence", "segment.sequence"),
+    ...optional(src, "durationMs", "durationMs", asUintNumber),
+    ...optional(src, "streamId", "streamId", asText),
+    ...optional(src, "continues", "continues", asBoolean)
   };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? segment : { ...segment, extra };
 }
 function samplingToCbor(sampling) {
   const map = {};
@@ -218,26 +274,36 @@ function samplingToCbor(sampling) {
   if (sampling.rule != null) map.rule = sampling.rule;
   if (sampling.ruleLang != null) map.ruleLang = sampling.ruleLang;
   if (sampling.appliesTo != null) map.appliesTo = sampling.appliesTo.map(int);
-  return map;
+  return withStore(map, sampling.extra);
 }
-function cborToSampling(obj) {
-  return {
-    ...obj.effectiveRate != null ? { effectiveRate: Number(obj.effectiveRate) } : {},
-    ...obj.maxEventsPerSec != null ? { maxEventsPerSec: Number(obj.maxEventsPerSec) } : {},
-    ...obj.dropPolicy != null ? { dropPolicy: obj.dropPolicy } : {},
-    ...obj.droppedTotal != null ? { droppedTotal: Number(obj.droppedTotal) } : {},
-    ...obj.droppedSegment != null ? { droppedSegment: Number(obj.droppedSegment) } : {},
-    ...obj.rule != null ? { rule: obj.rule } : {},
-    ...obj.ruleLang != null ? { ruleLang: obj.ruleLang } : {},
-    ...obj.appliesTo != null ? { appliesTo: obj.appliesTo.map(Number) } : {}
+function cborToSampling(value) {
+  const obj = asMap(value);
+  if (obj == null) return void 0;
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const sampling = {
+    // A rate is a fraction, so this is the one header number that is not an
+    // integer — and the one whose range the format states, so it is the one
+    // key here checked for more than its type. It is tested rather than
+    // converted: `Number('half')` is `NaN`, a rate no file carried and none
+    // can be written back from.
+    ...optional(src, "effectiveRate", "effectiveRate", asRate),
+    ...optional(src, "maxEventsPerSec", "maxEventsPerSec", asUintNumber),
+    ...optional(src, "dropPolicy", "dropPolicy", asText),
+    ...optional(src, "droppedTotal", "droppedTotal", asUintNumber),
+    ...optional(src, "droppedSegment", "droppedSegment", asUintNumber),
+    ...optional(src, "rule", "rule", asText),
+    ...optional(src, "ruleLang", "ruleLang", asText),
+    ...optional(src, "appliesTo", "appliesTo", asUintNumbers)
   };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? sampling : { ...sampling, extra };
 }
 function headerToCbor(header) {
   const map = {
     protocol: header.protocol,
     perspective: header.perspective,
     detail: header.detail,
-    startTime: int(header.startTime)
+    startTime: requiredUint(header.startTime, "startTime")
   };
   if (header.endTime != null) map.endTime = int(header.endTime);
   if (header.transport != null) map.transport = header.transport;
@@ -247,23 +313,31 @@ function headerToCbor(header) {
   if (header.segment != null) map.segment = segmentToCbor(header.segment);
   if (header.sampling != null) map.sampling = samplingToCbor(header.sampling);
   if (header.custom != null) map.custom = header.custom;
-  return map;
+  return withStore(map, header.extra);
 }
 function cborToHeader(obj) {
-  return {
-    protocol: obj.protocol,
-    perspective: obj.perspective,
-    detail: obj.detail,
-    startTime: Number(obj.startTime),
-    ...obj.endTime != null ? { endTime: Number(obj.endTime) } : {},
-    ...obj.transport != null ? { transport: obj.transport } : {},
-    ...obj.source != null ? { source: obj.source } : {},
-    ...obj.endpoint != null ? { endpoint: obj.endpoint } : {},
-    ...obj.sessionId != null ? { sessionId: obj.sessionId } : {},
-    ...obj.segment != null ? { segment: cborToSegment(obj.segment) } : {},
-    ...obj.sampling != null ? { sampling: cborToSampling(obj.sampling) } : {},
-    ...obj.custom != null ? { custom: obj.custom } : {}
+  const src = { obj, used: /* @__PURE__ */ new Set() };
+  const header = {
+    protocol: requireHeaderText(src, "protocol"),
+    perspective: requireHeaderText(src, "perspective"),
+    detail: requireHeaderText(src, "detail"),
+    startTime: requireHeaderUint(src, "startTime"),
+    ...optional(src, "endTime", "endTime", asUintNumber),
+    ...optional(src, "transport", "transport", asText),
+    ...optional(src, "source", "source", asText),
+    ...optional(src, "endpoint", "endpoint", asText),
+    ...optional(src, "sessionId", "sessionId", asText),
+    ...optional(src, "segment", "segment", cborToSegment),
+    ...optional(src, "sampling", "sampling", cborToSampling),
+    // Not `Record<string, unknown>` by assertion but by test. A `"custom"`
+    // that is not a map used to reach this field wearing that type, so the
+    // first caller to iterate its keys met a shape it was told could not
+    // occur. The bytes survive either way; only one of the two keeps the
+    // field's type true.
+    ...optional(src, "custom", "custom", asMap)
   };
+  const extra = unrecognisedKeys(src);
+  return extra == null ? header : { ...header, extra };
 }
 function subscriptionRefToCbor(ref) {
   return [ref.peer, ref.requestId];
@@ -272,7 +346,12 @@ function cborToSubscriptionRef(value) {
   if (!Array.isArray(value) || value.length !== 2) {
     throw new Error("Subscription reference must be [peer, requestId]");
   }
-  return { peer: value[0], requestId: BigInt(value[1]) };
+  const peer = asText(value[0]);
+  const requestId = asUint(value[1]);
+  if (peer == null || requestId == null) {
+    throw new Error("Subscription reference must be a [text, unsigned integer] pair");
+  }
+  return { peer, requestId };
 }
 function toBytes(value) {
   return value instanceof Uint8Array ? new Uint8Array(value) : new Uint8Array(value);
@@ -299,7 +378,7 @@ function eventToCbor(event) {
     case "control": {
       base.d = event.direction;
       base.mt = int(event.messageType);
-      base.msg = event.message;
+      base.msg = event.message === void 0 ? {} : event.message;
       if (event.streamId != null) base.sid = event.streamId;
       if (event.raw != null) base.raw = event.raw;
       break;
@@ -308,6 +387,10 @@ function eventToCbor(event) {
       base.sid = event.streamId;
       base.d = event.direction;
       base.st = event.streamType;
+      if (event.trackAlias != null) base.ta = event.trackAlias;
+      if (event.subgroupId != null) base.sg = event.subgroupId;
+      if (event.fetchRequestId != null) base.fri = event.fetchRequestId;
+      if (event.groupId != null) base.g = event.groupId;
       break;
     }
     case "stream-closed": {
@@ -339,6 +422,10 @@ function eventToCbor(event) {
     case "error": {
       base.ec = int(event.errorCode);
       base.reason = event.reason;
+      if (event.streamId != null) base.sid = event.streamId;
+      if (event.errorKind != null) base.ek = event.errorKind;
+      if (event.rawLength != null) base.rawlen = int(event.rawLength);
+      if (event.raw != null) base.raw = event.raw;
       break;
     }
     case "annotation": {
@@ -374,14 +461,119 @@ function eventToCbor(event) {
     case "unknown": {
       base.e = event.eventType;
       for (const [key, value] of Object.entries(event.fields)) {
-        base[key] = value;
+        setKey(base, key, value);
       }
       break;
     }
   }
+  if (event.type !== "unknown" && event.extra != null) {
+    for (const [key, value] of Object.entries(event.extra)) {
+      if (COMMON_EVENT_KEYS.has(key) || Object.hasOwn(base, key)) continue;
+      setKey(base, key, value);
+    }
+  }
   return base;
 }
+function asUint(value) {
+  if (typeof value === "bigint") return value >= 0n ? value : void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return void 0;
+  return BigInt(value);
+}
+function asUintNumber(value) {
+  const int2 = asUint(value);
+  return int2 == null || int2 > BigInt(Number.MAX_SAFE_INTEGER) ? void 0 : Number(int2);
+}
+function asText(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function asRate(value) {
+  const rate = asNumber(value);
+  return rate != null && rate > 0 && rate <= 1 ? rate : void 0;
+}
+function asUintNumbers(value) {
+  if (!Array.isArray(value)) return void 0;
+  const ids = [];
+  for (const item of value) {
+    const id = asUintNumber(item);
+    if (id == null) return void 0;
+    ids.push(id);
+  }
+  return ids;
+}
+function asMap(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return void 0;
+  return value;
+}
+function asByteString(value) {
+  return value instanceof Uint8Array ? toBytes(value) : void 0;
+}
+function asByteStrings(value) {
+  if (!Array.isArray(value)) return void 0;
+  const parts = [];
+  for (const item of value) {
+    const bytes = asByteString(item);
+    if (bytes == null) return void 0;
+    parts.push(bytes);
+  }
+  return parts;
+}
+function asTraceId(value) {
+  const bytes = asByteString(value);
+  return bytes?.length === TRACE_ID_LENGTH ? bytes : void 0;
+}
+function take(src, key) {
+  src.used.add(key);
+  return src.obj[key];
+}
+function requireUint(src, key) {
+  const value = asUint(take(src, key));
+  if (value == null) {
+    throw new Error(`Event key ${JSON.stringify(key)} must be an unsigned integer`);
+  }
+  return value;
+}
+function requireHeaderText(src, key) {
+  const present = Object.hasOwn(src.obj, key);
+  const value = asText(take(src, key));
+  if (value == null) {
+    throw new MalformedHeaderError(key, present ? "must be a text string" : "is missing");
+  }
+  return value;
+}
+function requireHeaderUint(src, key, reportedAs = key) {
+  const present = Object.hasOwn(src.obj, key);
+  const value = asUintNumber(take(src, key));
+  if (value == null) {
+    throw new MalformedHeaderError(
+      reportedAs,
+      present ? "must be an unsigned integer" : "is missing"
+    );
+  }
+  return value;
+}
+function optional(src, key, name, read) {
+  const usable = read(src.obj[key]);
+  if (usable === void 0) return {};
+  src.used.add(key);
+  return { [name]: usable };
+}
 function cborToEvent(obj) {
+  const src = { obj, used: new Set(COMMON_EVENT_KEYS) };
+  const event = decodeEvent(src);
+  if (event.type === "unknown") return event;
+  const extra = unrecognisedKeys(src);
+  return extra == null ? event : { ...event, extra };
+}
+function decodeEvent(src) {
+  const obj = src.obj;
   const seq = Number(obj.n ?? 0);
   const timestamp = Number(obj.t ?? 0);
   const peerFields = obj.p != null ? { peer: obj.p } : {};
@@ -389,7 +581,7 @@ function cborToEvent(obj) {
   if (eventType == null) {
     const fields = {};
     for (const [key, value] of Object.entries(obj)) {
-      if (!COMMON_EVENT_KEYS.has(key)) fields[key] = value;
+      if (!COMMON_EVENT_KEYS.has(key)) setKey(fields, key, value);
     }
     return {
       type: "unknown",
@@ -407,11 +599,20 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        direction: obj.d,
-        messageType: Number(obj.mt ?? 0),
-        message: obj.msg ?? {},
-        ...obj.sid != null ? { streamId: BigInt(obj.sid) } : {},
-        ...obj.raw != null ? { raw: toBytes(obj.raw) } : {}
+        direction: take(src, "d"),
+        messageType: Number(take(src, "mt") ?? 0),
+        // Handed over exactly as it decoded. A `"msg"` that is not a map is
+        // still the only decode the recording has — the corpus captures carry
+        // a Rust `Debug` string here — and the format requires a reader to
+        // preserve it rather than reject the event or substitute a map. That
+        // includes `null`, which is a value a writer chose to put on the wire,
+        // not an absence; absence is the single case normalised, to `{}`, so
+        // that a caller reading keys off a conforming file never meets
+        // `undefined`. It is the one key with no unusable shape: the field's
+        // type is `unknown`, so every value is one it can hold.
+        message: Object.hasOwn(obj, "msg") ? take(src, "msg") : {},
+        ...optional(src, "sid", "streamId", asUint),
+        ...optional(src, "raw", "raw", asByteString)
       };
     case "stream-opened":
       return {
@@ -419,9 +620,27 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        streamId: BigInt(obj.sid),
-        direction: obj.d,
-        streamType: obj.st
+        streamId: requireUint(src, "sid"),
+        direction: take(src, "d"),
+        streamType: take(src, "st"),
+        // `bigint`, not `number`, even though a writer that used a narrow CBOR
+        // integer hands these back as JS numbers. They are the same
+        // identifiers an object-header event carries, and that event converts;
+        // leaving one a number here makes `opened.groupId === header.groupId`
+        // read `42 === 42n` and answer `false` for values that match.
+        //
+        // Tested rather than converted, and optional rather than required.
+        // `BigInt(obj.ta)` threw on a text or fractional value and took the
+        // whole file down with it, since nothing catches one event's decode; it
+        // answered `1n` for `true` and `4n` for `"4"`, inventing an identifier
+        // the file never carried; and the owned-key list then kept the
+        // survivors out of `extra`, so adding these four keys *lost* values
+        // this reader had preserved before it knew them. A value of any other
+        // shape now stays where it was, on the event as an unrecognised key.
+        ...optional(src, "ta", "trackAlias", asUint),
+        ...optional(src, "sg", "subgroupId", asUint),
+        ...optional(src, "fri", "fetchRequestId", asUint),
+        ...optional(src, "g", "groupId", asUint)
       };
     case "stream-closed":
       return {
@@ -429,8 +648,8 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        streamId: BigInt(obj.sid),
-        errorCode: Number(obj.ec ?? 0)
+        streamId: requireUint(src, "sid"),
+        errorCode: Number(take(src, "ec") ?? 0)
       };
     case "object-header":
       return {
@@ -438,11 +657,11 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        streamId: BigInt(obj.sid),
-        groupId: BigInt(obj.g),
-        objectId: BigInt(obj.o),
-        publisherPriority: Number(obj.pp ?? 0),
-        objectStatus: Number(obj.os ?? 0)
+        streamId: requireUint(src, "sid"),
+        groupId: requireUint(src, "g"),
+        objectId: requireUint(src, "o"),
+        publisherPriority: Number(take(src, "pp") ?? 0),
+        objectStatus: Number(take(src, "os") ?? 0)
       };
     case "object-payload":
       return {
@@ -450,11 +669,11 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        streamId: BigInt(obj.sid),
-        groupId: BigInt(obj.g),
-        objectId: BigInt(obj.o),
-        size: Number(obj.sz ?? 0),
-        ...obj.pl != null ? { payload: toBytes(obj.pl) } : {}
+        streamId: requireUint(src, "sid"),
+        groupId: requireUint(src, "g"),
+        objectId: requireUint(src, "o"),
+        size: Number(take(src, "sz") ?? 0),
+        ...optional(src, "pl", "payload", asByteString)
       };
     case "state-change":
       return {
@@ -462,8 +681,8 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        from: obj.from,
-        to: obj.to
+        from: take(src, "from"),
+        to: take(src, "to")
       };
     case "error":
       return {
@@ -471,8 +690,24 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        errorCode: Number(obj.ec ?? 0),
-        reason: obj.reason ?? ""
+        errorCode: Number(take(src, "ec") ?? 0),
+        reason: take(src, "reason") ?? "",
+        // Optional, so an unusable value costs the key and not the event: the
+        // error code and reason are the point of the event and are fine.
+        // `asUint` rather than a conversion, for the reason Event 1 gives —
+        // `BigInt(true)` is `1n`, a stream this file never named.
+        ...optional(src, "sid", "streamId", asUint),
+        // An error kind this version has never heard of is still text, and
+        // still kept: the vocabulary is open and `ErrorKind` widens to any
+        // string for exactly that. What `asText` refuses is a value that is
+        // not text at all.
+        ...optional(src, "ek", "errorKind", asText),
+        ...optional(src, "rawlen", "rawLength", asUintNumber),
+        // No length check. The 4096-byte cap binds a recorder; a reader that
+        // refused a longer value — or shortened it — would reject a file it was
+        // required to accept, or destroy the evidence the field exists to
+        // carry.
+        ...optional(src, "raw", "raw", asByteString)
       };
     case "annotation":
       return {
@@ -480,8 +715,8 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        label: obj.label ?? "",
-        data: obj.data
+        label: take(src, "label") ?? "",
+        data: take(src, "data")
       };
     case "peer-connected":
       return {
@@ -489,10 +724,13 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        ...obj.endpoint != null ? { endpoint: obj.endpoint } : {},
-        ...obj.transport != null ? { transport: obj.transport } : {},
-        ...obj.role != null ? { role: obj.role } : {},
-        ...obj.side != null ? { side: obj.side } : {}
+        ...optional(src, "endpoint", "endpoint", asText),
+        ...optional(src, "transport", "transport", asText),
+        // A role or side this version has never heard of is still text, and
+        // still kept: the unions they widen to exist for exactly that. What
+        // `asText` refuses is a value that is not text at all.
+        ...optional(src, "role", "role", asText),
+        ...optional(src, "side", "side", asText)
       };
     case "peer-disconnected":
       return {
@@ -500,8 +738,8 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        errorCode: Number(obj.ec ?? 0),
-        ...obj.reason != null ? { reason: obj.reason } : {}
+        errorCode: Number(take(src, "ec") ?? 0),
+        ...optional(src, "reason", "reason", asText)
       };
     case "subscription-derivation":
       return {
@@ -509,16 +747,16 @@ function cborToEvent(obj) {
         seq,
         timestamp,
         ...peerFields,
-        upstream: cborToSubscriptionRef(obj.u),
-        downstream: (obj.d ?? []).map(cborToSubscriptionRef),
-        kind: obj.kind ?? "",
-        ...obj.traceId != null ? { traceId: checkTraceId(obj.traceId) } : {},
-        ...obj.ns != null ? { namespace: obj.ns.map(toBytes) } : {},
-        ...obj.tn != null ? { trackName: toBytes(obj.tn) } : {},
-        ...obj.tdr != null ? { tDownstreamReceived: Number(obj.tdr) } : {},
-        ...obj.tus != null ? { tUpstreamSent: Number(obj.tus) } : {},
-        ...obj.tuo != null ? { tUpstreamOkReceived: Number(obj.tuo) } : {},
-        ...obj.tdo != null ? { tDownstreamOkSent: Number(obj.tdo) } : {}
+        upstream: cborToSubscriptionRef(take(src, "u")),
+        downstream: (take(src, "d") ?? []).map(cborToSubscriptionRef),
+        kind: take(src, "kind") ?? "",
+        ...optional(src, "traceId", "traceId", asTraceId),
+        ...optional(src, "ns", "namespace", asByteStrings),
+        ...optional(src, "tn", "trackName", asByteString),
+        ...optional(src, "tdr", "tDownstreamReceived", asUintNumber),
+        ...optional(src, "tus", "tUpstreamSent", asUintNumber),
+        ...optional(src, "tuo", "tUpstreamOkReceived", asUintNumber),
+        ...optional(src, "tdo", "tDownstreamOkSent", asUintNumber)
       };
   }
 }
@@ -575,26 +813,40 @@ function readSegments(bytes, options) {
   const segments = [];
   let events = [];
   let offset = 0;
+  const skip = (from, kind, cause) => {
+    const next = findNextSegment(bytes, from + 1);
+    options?.onRecovered?.({ offset: from, kind, resumedAt: next < 0 ? void 0 : next, cause });
+    return next;
+  };
   validatePreamble(bytes, 0);
   while (offset < bytes.length) {
     if (startsWithMagic(bytes, offset)) {
       const { headerLength } = validatePreamble(bytes, offset);
       const start = offset + PREAMBLE_SIZE;
       const headerBytes = bytes.subarray(start, start + headerLength);
+      let header;
+      try {
+        header = cborToHeader(decode(headerBytes));
+      } catch (error) {
+        if (!recover) throw error;
+        const next2 = skip(offset, "header", error);
+        if (next2 < 0) return segments;
+        offset = next2;
+        continue;
+      }
       events = [];
-      segments.push({
-        header: cborToHeader(decode(headerBytes)),
-        events
-      });
+      segments.push({ header, events });
       offset = start + headerLength;
       continue;
     }
     let length;
+    let failure;
     try {
       length = cborItemLength(bytes, offset);
     } catch (error) {
       if (!recover || !(error instanceof MalformedCborError)) throw error;
       length = null;
+      failure = error;
     }
     if (length != null) {
       try {
@@ -604,11 +856,12 @@ function readSegments(bytes, options) {
         continue;
       } catch (error) {
         if (!recover) throw error;
+        failure = error;
       }
     } else if (!recover) {
       throw new TruncatedTraceError(offset, segments);
     }
-    const next = findNextSegment(bytes, offset + 1);
+    const next = skip(offset, failure === void 0 ? "truncated" : "event", failure);
     if (next < 0) return segments;
     offset = next;
   }
@@ -700,7 +953,122 @@ function traceToJSON(trace) {
   );
 }
 
+// src/reader.ts
+var TruncatedStreamError = class 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.
+   */
+  offset;
+  /**
+   * 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.
+   */
+  events;
+  constructor(offset, events) {
+    super(
+      `Trace stream truncated: the item starting at byte ${offset} is incomplete, after ${events} event${events === 1 ? "" : "s"}`
+    );
+    this.name = "TruncatedStreamError";
+    this.offset = offset;
+    this.events = events;
+  }
+};
+function createMoqtraceReader() {
+  let buffer = new Uint8Array(0);
+  let consumed = 0;
+  let delivered = 0;
+  let current;
+  let ended = false;
+  function take2(count) {
+    const slice = buffer.subarray(0, count);
+    buffer = buffer.subarray(count);
+    consumed += count;
+    return slice;
+  }
+  function tryReadSegment() {
+    if (buffer.length < PREAMBLE_SIZE) return void 0;
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const version = view.getUint32(8, true);
+    if (!SUPPORTED_VERSIONS.includes(version)) {
+      throw new Error(
+        `Unsupported format version: ${version} (supported: ${SUPPORTED_VERSIONS.join(", ")})`
+      );
+    }
+    const headerLength = view.getUint32(12, true);
+    if (buffer.length < PREAMBLE_SIZE + headerLength) return void 0;
+    take2(PREAMBLE_SIZE);
+    const headerBytes = take2(headerLength);
+    return cborToHeader(decode(headerBytes));
+  }
+  function drain(atEnd) {
+    const items = [];
+    for (; ; ) {
+      if (current === void 0) {
+        if (buffer.length >= MAGIC.length && !startsWithMagic(buffer, 0)) {
+          throw new Error("Invalid magic bytes: not a .moqtrace file");
+        }
+        const header = tryReadSegment();
+        if (header === void 0) break;
+        current = header;
+        items.push({ kind: "segment", header });
+        continue;
+      }
+      if (buffer.length === 0) break;
+      if (buffer.length < MAGIC.length && !atEnd) break;
+      if (startsWithMagic(buffer, 0)) {
+        const header = tryReadSegment();
+        if (header === void 0) break;
+        current = header;
+        items.push({ kind: "segment", header });
+        continue;
+      }
+      const length = cborItemLength(buffer, 0);
+      if (length === null) break;
+      const item = decode(take2(length));
+      items.push({ kind: "event", event: cborToEvent(item) });
+      delivered += 1;
+    }
+    return items;
+  }
+  return {
+    push(chunk) {
+      if (ended) throw new Error("Cannot push to a reader that has ended");
+      if (chunk.length > 0) {
+        const grown = new Uint8Array(buffer.length + chunk.length);
+        grown.set(buffer, 0);
+        grown.set(chunk, buffer.length);
+        buffer = grown;
+      }
+      return drain(false);
+    },
+    end() {
+      if (ended) return [];
+      ended = true;
+      const items = drain(true);
+      if (buffer.length > 0 || current === void 0) {
+        throw new TruncatedStreamError(consumed, delivered);
+      }
+      return items;
+    },
+    get header() {
+      return current;
+    },
+    get pending() {
+      return buffer.length;
+    }
+  };
+}
+
 // src/recorder.ts
+var MAX_ERROR_RAW_BYTES = 4096;
 var DETAIL_RANK = {
   control: 0,
   headers: 1,
@@ -720,19 +1088,35 @@ function createRecorder(options) {
   const clock = options.clock ?? (() => Math.round(performance.now() * 1e3));
   const messageTypeId = options.messageTypeId ?? (() => 0);
   const events = [];
+  let head = 0;
+  let dropped = 0;
+  const rawRecorded = /* @__PURE__ */ new Set();
   let _recording = true;
   let _seq = 0;
   const startTime = Date.now();
   function addEvent(event) {
     if (!_recording) return;
-    if (events.length >= maxEvents) {
-      events.shift();
+    if (events.length - head >= maxEvents) {
+      head++;
+      dropped++;
+      if (head >= 4096 || head >= maxEvents) {
+        events.splice(0, head);
+        head = 0;
+      }
     }
     events.push(event);
   }
   function nextSeq() {
     return _seq++;
   }
+  function rawFlow(streamId) {
+    return streamId == null ? "no-stream" : `stream:${streamId}`;
+  }
+  function claimRawSlot(flow) {
+    if (rawRecorded.has(flow)) return false;
+    rawRecorded.add(flow);
+    return true;
+  }
   function wrapSession(session) {
     return {
       get phase() {
@@ -858,14 +1242,27 @@ function createRecorder(options) {
       };
       addEvent(event);
     },
-    recordError(errorCode, reason) {
-      addEvent({
+    recordError(errorCode, reason, details) {
+      const streamId = details?.streamId;
+      const raw = details?.raw;
+      const rawLength = details?.rawLength === null ? void 0 : details?.rawLength ?? raw?.length;
+      const writeRaw = raw != null && detailRank >= DETAIL_RANK.full && claimRawSlot(rawFlow(streamId));
+      const event = {
         type: "error",
         seq: nextSeq(),
         timestamp: clock(),
         errorCode,
-        reason
-      });
+        reason,
+        ...streamId != null ? { streamId } : {},
+        ...details?.errorKind != null ? { errorKind: details.errorKind } : {},
+        // A size, gated with the other sizes and one level below the bytes: an
+        // error may name a data stream, so at 'control' this length would be a
+        // fact about media volume in a trace whose declared level excludes it.
+        // Written whether or not the bytes are, which is most of its value.
+        ...rawLength != null && detailRank >= DETAIL_RANK["headers+sizes"] ? { rawLength } : {},
+        ...writeRaw && raw != null ? { raw: raw.length > MAX_ERROR_RAW_BYTES ? raw.slice(0, MAX_ERROR_RAW_BYTES) : raw } : {}
+      };
+      addEvent(event);
     },
     annotate(label, data) {
       addEvent({
@@ -887,9 +1284,18 @@ function createRecorder(options) {
         ...options.transport != null ? { transport: options.transport } : {},
         ...options.source != null ? { source: options.source } : {},
         ...options.endpoint != null ? { endpoint: options.endpoint } : {},
-        ...options.sessionId != null ? { sessionId: options.sessionId } : {}
+        ...options.sessionId != null ? { sessionId: options.sessionId } : {},
+        // Carried through so a recorder with something to say the format has
+        // no key for can say it, and so a header this package builds has the
+        // same shape as one it reads. `writeMoqtrace` writes the store after
+        // the keys above and drops any entry naming one of them.
+        ...options.extra != null ? { extra: options.extra } : {},
+        // Only when something was actually dropped: the key's presence is
+        // what tells a reader this trace is incomplete, so writing it with a
+        // zero would make every complete trace look sampled.
+        ...dropped > 0 ? { sampling: { dropPolicy: "head", droppedTotal: dropped } } : {}
       };
-      return { header, events: [...events] };
+      return { header, events: events.slice(head) };
     },
     get recording() {
       return _recording;
@@ -898,9 +1304,14 @@ function createRecorder(options) {
 }
 export {
   FORMAT_VERSION,
+  MAX_ERROR_RAW_BYTES,
+  MalformedHeaderError,
   SUPPORTED_VERSIONS,
   TRACE_ID_LENGTH,
+  TruncatedStreamError,
   TruncatedTraceError,
+  controlMessageFields,
+  createMoqtraceReader,
   createMoqtraceWriter,
   createRecorder,
   readMoqtrace,