@moqtap/trace 0.4.1 → 0.5.0

package/README.md

@@ -1,18 +1,9 @@
 # @moqtap/trace
 
-Record, serialize, and analyze MoQT (Media over QUIC Transport) sessions using the `.moqtrace` binary format.
-
-- Binary `.moqtrace` format with CBOR encoding (compact, streamable, cross-language)
-- Segmented traces for capture rotation, live carriage, and recovery from a damaged region
-- Configurable detail levels from control-only to full wire captures
-- Session recorder that wraps `@moqtap/codec` session state machines
-- Human-readable JSON export for debugging
-- Zero-copy streaming writer, and an incremental reader for a stream that
-  arrives in chunks
-- Unrecognised keys, event types and enum values preserved through a
-  read-modify-write
-
-Writes format version 2 and reads versions 1 and 2.
+Record, serialize and analyze MoQT (Media over QUIC Transport) sessions as
+`.moqtrace` files — a compact, streamable CBOR format that reads the same across
+implementations. Includes a recorder that wraps `@moqtap/codec` session state
+machines, streaming read and write, and a lossy JSON export for debugging.
 
 ## Install
 
@@ -20,271 +11,109 @@ Writes format version 2 and reads versions 1 and 2.
 npm install @moqtap/trace @moqtap/codec
 ```
 
-`@moqtap/codec` is a peer dependency — install it alongside `@moqtap/trace`.
+`@moqtap/codec` is a peer dependency — install it alongside.
 
 ## Quick Start
 
-### Recording a session
+Wrap a codec session state machine, then serialize what it recorded:
 
 ```typescript
 import { createRecorder, writeMoqtrace } from '@moqtap/trace'
-import { createDraft17SessionState } from '@moqtap/codec/draft17/session'
+import { MESSAGE_ID_MAP } from '@moqtap/codec/draft21'
+import { createDraft21SessionState } from '@moqtap/codec/draft21/session'
 
 const recorder = createRecorder({
-  protocol: 'moq-transport-17',
+  protocol: 'moq-transport-21',
   perspective: 'client',
   detail: 'control',
+  messageTypeId: (name) => Number(MESSAGE_ID_MAP.get(name) ?? 0),
 })
 
-// Wrap a session to auto-capture control messages and state transitions
-const session = createDraft17SessionState('client')
-const traced = recorder.wrapSession(session)
-
-// Use `traced` instead of `session` — all send/receive calls are recorded
+// Every send/receive on the wrapper is recorded.
+const traced = recorder.wrapSession(createDraft21SessionState('client'))
 traced.send(setupMessage)
 traced.receive(setupMessage)
 
-// Manually record events the session layer doesn't see
-recorder.recordStreamOpened(4n, 0, 0) // outgoing subgroup stream
+// Events the session layer never sees.
+recorder.recordStreamOpened(4n, 0, 0)
 recorder.annotate('connected', { relay: 'cdn.example.com' })
 
-// Finalize and serialize
-const trace = recorder.finalize()
-const bytes = writeMoqtrace(trace) // → Uint8Array (.moqtrace binary)
+const bytes = writeMoqtrace(recorder.finalize()) // Uint8Array
 ```
 
-### Recording an error with the bytes behind it
-
-A report saying "your SUBSCRIBE_OK did not parse" is an assertion. The same
-report carrying the bytes is evidence the other party can run against their own
-encoder.
-
-```typescript
-recorder.recordError(0, 'SUBSCRIBE_OK did not parse', {
-  streamId: 4n,
-  errorKind: 'decode', // 'protocol' | 'transport' | 'decode' | any other string
-  raw: offendingBytes, // hand over everything held, untruncated
-})
-```
-
-Hand `raw` the full bytes. The recorder applies `MAX_ERROR_RAW_BYTES` (4096)
-itself and reports the untruncated length separately, so a caller that
-pre-truncates destroys the one signal saying the capture is partial. `rawLength`
-is recorded from `'headers+sizes'` and `raw` only at `'full'`, and the bytes are
-written once per flow.
-
-### Reading a trace file
+Read one back:
 
 ```typescript
 import { readMoqtrace, readMoqtraceHeader } from '@moqtap/trace'
 
-// Quick metadata peek (no event parsing)
-const header = readMoqtraceHeader(bytes)
-console.log(header.protocol) // "moq-transport-17"
-console.log(header.perspective) // "client"
-console.log(header.detail) // "control"
+const header = readMoqtraceHeader(bytes) // metadata only, no event parsing
+console.log(header.protocol, header.perspective, header.detail)
 
-// Full parse
 const trace = readMoqtrace(bytes)
 for (const event of trace.events) {
   console.log(event.type, event.timestamp)
 }
 ```
 
-### Streaming writer (for large traces)
-
-```typescript
-import { createMoqtraceWriter } from '@moqtap/trace'
-
-const writer = createMoqtraceWriter(header)
-outputStream.write(writer.preamble())
-
-for (const event of events) {
-  outputStream.write(writer.writeEvent(event))
-}
-```
-
-### Streaming reader (for a stream that arrives in chunks)
-
-`readMoqtrace` and the functions beside it take a finished file. A live capture
-does not have one: chunk boundaries fall wherever the transport put them,
-almost never on an item boundary.
-
-```typescript
-import { createMoqtraceReader, TruncatedStreamError } from '@moqtap/trace'
-
-const reader = createMoqtraceReader()
-
-for await (const chunk of incoming) {
-  // Returns whatever the chunk completed — often nothing, which is ordinary.
-  for (const item of reader.push(chunk)) {
-    if (item.kind === 'segment') console.log('segment', item.header.sessionId)
-    else console.log(item.event.type, item.event.timestamp)
-  }
-}
-
-// `end()` can still yield items, and throws if bytes are left over that do not
-// form a whole one.
-try {
-  for (const item of reader.end()) console.log(item.kind)
-} catch (error) {
-  if (error instanceof TruncatedStreamError) console.warn('stream cut mid-item')
-}
-```
-
-### Segmented traces
-
-A segment is a complete `.moqtrace` blob — magic, version, header, events —
-appended after the one before it, so a reader can start at any segment without
-the ones preceding it. That buys capture rotation without finalizing a file, a
-natural cut point for live carriage, and recovery from a damaged region.
-
-```typescript
-import { readMoqtraceSegments, writeMoqtraceSegments } from '@moqtap/trace'
-
-// Each segment header must carry `segment` metadata: it is what tells a reader
-// that `seq` and `timestamp` restart at zero in every segment.
-const bytes = writeMoqtraceSegments([
-  { header: { ...header, segment: { sequence: 0 } }, events: firstBatch },
-  { header: { ...header, segment: { sequence: 1, continues: true } }, events: secondBatch },
-])
-
-// Read the boundaries — you need them to order events across segments.
-for (const segment of readMoqtraceSegments(bytes)) {
-  console.log(segment.header.segment?.sequence, segment.events.length)
-}
-
-// Or ignore them: readMoqtrace flattens every segment's events in order.
-```
-
-### Damaged and truncated files
-
-A file that stops part-way through an event throws `TruncatedTraceError`, which
-carries everything that decoded before the cut — a truncated trace is still
-evidence. On a segmented trace, `{ recover: true }` skips a damaged region and
-resumes at the next segment instead of throwing; pass `onRecovered` alongside
-it to be told what that cost, since the return value cannot say.
-
-```typescript
-import { readMoqtrace, readMoqtraceSegments, TruncatedTraceError } from '@moqtap/trace'
-
-try {
-  const trace = readMoqtrace(bytes)
-} catch (error) {
-  if (error instanceof TruncatedTraceError) {
-    console.warn(`truncated at byte ${error.offset}`)
-    const survived = error.segments.reduce((n, segment) => n + segment.events.length, 0)
-    console.log(survived, 'events survived')
-  }
-}
-
-const whatSurvived = readMoqtraceSegments(bytes, {
-  recover: true,
-  onRecovered: ({ offset, kind, resumedAt }) => {
-    console.warn(
-      resumedAt == null
-        ? `${kind} damage at ${offset}: nothing readable followed, rest discarded`
-        : `${kind} damage at ${offset}, resumed at ${resumedAt}`,
-    )
-  },
-})
-```
+## API
+
+| Function                                             | Purpose                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------ |
+| `createRecorder(options)`                            | Session recorder; wraps a codec session state machine         |
+| `writeMoqtrace(trace)`                               | Serialize a complete trace to bytes                           |
+| `readMoqtrace(bytes)`                                | Parse a complete file, flattening every segment in order      |
+| `readMoqtraceHeader(bytes)`                          | Parse the header only                                         |
+| `createMoqtraceWriter(header)`                       | Streaming writer: `preamble()`, then `writeEvent()` per event  |
+| `createMoqtraceReader()`                             | Incremental reader for a stream arriving in chunks             |
+| `writeMoqtraceSegments()` / `readMoqtraceSegments()` | Segmented traces, for rotation, live carriage and recovery    |
+| `traceToJSON(trace)`                                 | Human-readable export; lossy, as bigints and bytes stringify   |
+
+`createRecorder` requires `protocol`, `perspective` and `detail`. Pass
+`messageTypeId` to map a message name to its wire id, which session-layer
+recording needs; `maxEvents` bounds the event buffer.
+
+Beyond `wrapSession`, the recorder takes events the session layer cannot see:
+`recordStreamOpened`, `recordStreamClosed`, `recordObjectHeader`,
+`recordObjectPayload`, `recordError` and `annotate`. `finalize()` returns the
+trace and stops recording.
+
+## Detail levels
+
+| Level           | What is recorded                       |
+| --------------- | -------------------------------------- |
+| `control`       | Control messages only                  |
+| `headers`       | + data stream and object headers       |
+| `headers+sizes` | + payload byte lengths                 |
+| `headers+data`  | + full payload bytes                   |
+| `full`          | + raw wire bytes, pre-decode           |
+
+Errors and annotations are recorded at every level. `headers+data` and `full`,
+and the `raw` field on any event, carry user content, so capturing them should
+be an explicit choice rather than a default.
+
+When recording an error, hand `recordError` the full bytes: it applies
+`MAX_ERROR_RAW_BYTES` itself and reports the untruncated length separately, so a
+caller that pre-truncates destroys the signal saying the capture is partial.
 
 ## Reading a trace you did not write
 
-Nothing here rejects a file for carrying something newer than this version
-knows. An unrecognised event type arrives as an `UnknownEvent` with its fields
-intact, so it survives a read-modify-write round trip rather than being dropped
-or relabelled; an unrecognised perspective, detail level, role, side, drop
-policy or derivation kind is kept verbatim.
-
-Keys are kept on the same terms. One this version does not recognise — on the
-header, on `segment`, on `sampling`, or on any event — is preserved verbatim in
-an `extra` map beside the fields and written back unchanged. Ignoring a key is
-permitted; dropping one is not, or a redaction pass, a filter or an annotated
-download emits a file that looks as though it never carried the key.
-
-The one place that refuses is `createRecorder`, which cannot honour a detail
-level it does not implement: it would either capture less than you asked for
-while writing a header claiming otherwise, or — for the payload-bearing levels
-— capture more.
+Nothing is rejected for carrying something newer than this version knows. An
+unrecognised event type arrives as an `UnknownEvent` with its fields intact, and
+an unrecognised key is preserved verbatim in an `extra` map beside the fields, so
+neither is dropped by a read-modify-write round trip.
 
-## Detail Levels
-
-| Level           | What's recorded                                           |
-| --------------- | --------------------------------------------------------- |
-| `control`       | Control messages only (setup, subscribe, publish, goaway) |
-| `headers`       | + data stream headers (subgroup/fetch, object metadata)   |
-| `headers+sizes` | + payload byte lengths                                    |
-| `headers+data`  | + full payload bytes                                      |
-| `full`          | + raw wire bytes (pre-decode)                             |
-
-`headers+data` and `full`, and the `raw` field on any event, carry user
-content. Capturing them is optional for a conformant recorder and should be an
-explicit choice, not a default.
-
-## JSON Export
+A file that stops part-way through an event throws `TruncatedTraceError`, which
+carries everything that decoded before the cut. On a segmented trace,
+`readMoqtraceSegments(bytes, { recover: true })` skips a damaged region and
+resumes at the next segment instead of throwing.
 
-For human-readable debugging (not lossless — bigint/Uint8Array become strings):
+## File format
 
-```typescript
-import { traceToJSON } from '@moqtap/trace'
+[SPEC.md](./SPEC.md) is the complete `.moqtrace` binary specification.
 
-const json = traceToJSON(trace)
-console.log(json)
-```
+## Documentation
 
-## Upgrading
-
-### To 0.4.0 (from 0.3.0)
-
-Two changes to what a reader accepts:
-
-- `ControlMessageEvent.message` is `unknown` rather than
-  `Record<string, unknown>`, so anything reading a key straight off it stops
-  compiling. Narrow with `controlMessageFields()` first. The old type was a
-  claim the runtime did not keep — every real capture carries a text rendering
-  there, so `event.message.request_id` typechecked and read `undefined`.
-- A header with no usable value for a required key throws
-  `MalformedHeaderError` instead of returning a header with `undefined`, `NaN`
-  or `0` standing in for it. Pass `recover` to skip that segment instead. No
-  file either implementation writes is affected.
-
-Everything else is additive: `extra` on the header and its two sub-maps, the
-stream-header identifiers on Event 1, the error fields on Event 6, and
-`createMoqtraceReader`.
-
-### To 0.3.0 (from 0.2.0)
-
-The package now writes format version 2. A 0.2.0 reader rejects those files at
-byte 8, which is the point of the bump: it turns what would have been silent
-desynchronization on a segmented trace into a clear refusal. Reading is
-unaffected in the other direction — 0.3.0 reads everything 0.2.0 wrote.
-
-What changes for code already using it:
-
-- `TraceEvent` gained four members (`peer-connected`, `peer-disconnected`,
-  `subscription-derivation`, `unknown`). A `switch` that handles only the
-  cases it cares about is unaffected; one that asserts exhaustiveness is not.
-- `Perspective`, `DetailLevel` and the new string unions accept values they do
-  not name, so indexing a `Record<DetailLevel, T>` with one now yields
-  `T | undefined`.
-- An unknown event type used to arrive as an annotation labelled
-  `unknown-event-<n>`. It now arrives as an `UnknownEvent` carrying its real
-  type and fields, so code matching that label should match `type === 'unknown'`
-  instead. The old shape was lossy in a way that mattered: writing the trace
-  back rewrote the event's type to 7.
-- `createRecorder` throws on a detail level it does not implement, which the
-  types previously made unexpressible.
-- The bytes changed in two ways that make files readable by the Rust
-  implementation for the first time: an integral value past 32 bits is now
-  written as a CBOR integer rather than a float64, and a byte string as major
-  type 2 rather than wrapped in the typed-array tag 64. Both readers accept
-  either form, so nothing already written becomes unreadable.
-
-## File Format
-
-See [SPEC.md](./SPEC.md) for the complete `.moqtrace` binary format specification.
+<https://moqtap.com/npm-packages/moqtap-trace/>
 
 ## License
 

package/SPEC.md

@@ -44,7 +44,9 @@ and Event 4's `"pl"` begins after the object header, so the bytes of a
 including `"full"`. What those headers carry is recorded as decoded fields
 instead — see [Event 1](#event-1-stream-opened). Closing that gap needs a new
 key and is not in this revision; the level's description no longer implies
-otherwise.
+otherwise. The one part of an object's framing recorded as bytes is its
+property block, [Event 3's `"props"`](#event-3-object-header), because the
+block's encoding is the draft's and has no decoded form this format could hold.
 
 At any detail level, the recorder MAY be configured to **mask payloads** — replacing payload bytes with zeroes before writing. This preserves payload sizes for bandwidth analysis while stripping media content. Sources MUST advertise masking via `"payloadMasked": true` in the header's `"custom"` map when active.
 
@@ -261,6 +263,33 @@ Object header events and object payload events (event 4) for the same object sha
 | `"o"`   | integer | `headers`+   | Object ID                                                                  |
 | `"pp"`  | integer | `headers`+   | Publisher priority                                                         |
 | `"os"`  | integer | `headers`+   | Object status (0=normal, 1=end-of-group, 2=end-of-track, 3=does-not-exist) |
+| `"props"` | byte string | `headers`+ | The object's property block as the wire carried it, past its length field. **Optional.** See below. |
+
+#### `"props"` — the property block
+
+Object Properties — called Extension Headers before draft-17 — are the part of
+an object a consumer reads before its payload: a LOC object's timestamp, frame
+marking and codec configuration, the gaps a publisher signals after a restart,
+the key ID of an encrypted object. Before this key no level recorded them, and
+none of them can be recovered from the payload, so a trace could show an
+object's bytes but not what decided how they were decoded.
+
+- **Bytes, not a decoded list.** Every draft encodes the block differently —
+  absolute or delta types, two varint encodings — and a reader already holds
+  the codec for the session's draft. A decoded form would freeze one draft's
+  rules into this format, and the block MUST be recorded byte for byte so a
+  reader decodes exactly what the endpoint saw. Immutable Properties, which an
+  encrypted object authenticates, depend on that.
+- **Absent and empty differ.** A writer MUST omit the key when the object had no
+  properties field, and MUST write an empty byte string when the field was
+  present with a length of 0 — on a subgroup stream with the PROPERTIES flag,
+  every object without properties carries one. A reader MUST keep the
+  distinction.
+- **`headers`+, not payload-bearing.** The block is object metadata, not media.
+  A property value can still carry application data — a codec configuration is
+  a few dozen bytes of it — so a source that must not share any object content
+  MAY drop the key along with the payload. Dropping it does not change the
+  trace's detail level.
 
 ### Event 4: Object Payload
 

package/dist/index.cjs

@@ -329,10 +329,10 @@ function cborToHeader(obj) {
     ...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
+    // Not `Record<string, unknown>` by assertion but by test. Asserted, a
+    // `"custom"` that is not a map would reach this field wearing that type,
+    // and the first caller to iterate its keys would meet a shape it was told
+    // could not occur. The bytes survive either way; only the test keeps the
     // field's type true.
     ...optional(src, "custom", "custom", asMap)
   };
@@ -404,6 +404,7 @@ function eventToCbor(event) {
       base.o = event.objectId;
       base.pp = int(event.publisherPriority);
       base.os = int(event.objectStatus);
+      if (event.properties != null) base.props = event.properties;
       break;
     }
     case "object-payload": {
@@ -661,7 +662,8 @@ function decodeEvent(src) {
         groupId: requireUint(src, "g"),
         objectId: requireUint(src, "o"),
         publisherPriority: Number(_nullishCoalesce(take(src, "pp"), () => ( 0))),
-        objectStatus: Number(_nullishCoalesce(take(src, "os"), () => ( 0)))
+        objectStatus: Number(_nullishCoalesce(take(src, "os"), () => ( 0))),
+        ...optional(src, "props", "properties", asByteString)
       };
     case "object-payload":
       return {
@@ -1215,7 +1217,7 @@ function createRecorder(options) {
         errorCode
       });
     },
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
@@ -1225,7 +1227,8 @@ function createRecorder(options) {
         groupId,
         objectId,
         publisherPriority,
-        objectStatus
+        objectStatus,
+        ...properties !== void 0 ? { properties } : {}
       });
     },
     recordObjectPayload(streamId, groupId, objectId, size, payload) {

package/dist/index.d.cts

@@ -298,6 +298,23 @@ interface ObjectHeaderEvent extends BaseEvent {
     readonly objectId: bigint;
     readonly publisherPriority: number;
     readonly objectStatus: number;
+    /**
+     * The Object's property block — Object Properties, Extension Headers before
+     * draft-17 — exactly as the wire carried it, past its length field.
+     *
+     * Absent when the Object had no properties field, which is not the same as an
+     * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+     * length on every Object that has none. Kept as bytes rather than decoded
+     * because the encoding is the draft's, and a reader decodes it with the codec
+     * that reads the rest of the session; a decoded form would freeze one draft's
+     * rules into the format.
+     *
+     * Recorded from `'headers'` up. It is object metadata a payload's consumer
+     * reads before the payload — timestamps, frame marking, a codec
+     * configuration — and before this key no level recorded it, so a trace could
+     * not show what decided how its media was decoded.
+     */
+    readonly properties?: Uint8Array;
 }
 interface ObjectPayloadEvent extends BaseEvent {
     readonly type: 'object-payload';
@@ -917,8 +934,13 @@ interface TraceRecorder {
     recordStreamOpened(streamId: bigint, direction: 0 | 1, streamType: 0 | 1 | 2): void;
     /** Record a stream-closed event. Ignored at 'control' detail level. */
     recordStreamClosed(streamId: bigint, errorCode?: number): void;
-    /** Record an object header event. Ignored below 'headers' detail level. */
-    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number): void;
+    /**
+     * Record an object header event. Ignored below 'headers' detail level.
+     *
+     * `properties` is the Object's property block as the wire carried it; omit it
+     * when the Object had no properties field.
+     */
+    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number, properties?: Uint8Array): void;
     /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
     recordObjectPayload(streamId: bigint, groupId: bigint, objectId: bigint, size: number, payload?: Uint8Array): void;
     /**

package/dist/index.d.ts

@@ -298,6 +298,23 @@ interface ObjectHeaderEvent extends BaseEvent {
     readonly objectId: bigint;
     readonly publisherPriority: number;
     readonly objectStatus: number;
+    /**
+     * The Object's property block — Object Properties, Extension Headers before
+     * draft-17 — exactly as the wire carried it, past its length field.
+     *
+     * Absent when the Object had no properties field, which is not the same as an
+     * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+     * length on every Object that has none. Kept as bytes rather than decoded
+     * because the encoding is the draft's, and a reader decodes it with the codec
+     * that reads the rest of the session; a decoded form would freeze one draft's
+     * rules into the format.
+     *
+     * Recorded from `'headers'` up. It is object metadata a payload's consumer
+     * reads before the payload — timestamps, frame marking, a codec
+     * configuration — and before this key no level recorded it, so a trace could
+     * not show what decided how its media was decoded.
+     */
+    readonly properties?: Uint8Array;
 }
 interface ObjectPayloadEvent extends BaseEvent {
     readonly type: 'object-payload';
@@ -917,8 +934,13 @@ interface TraceRecorder {
     recordStreamOpened(streamId: bigint, direction: 0 | 1, streamType: 0 | 1 | 2): void;
     /** Record a stream-closed event. Ignored at 'control' detail level. */
     recordStreamClosed(streamId: bigint, errorCode?: number): void;
-    /** Record an object header event. Ignored below 'headers' detail level. */
-    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number): void;
+    /**
+     * Record an object header event. Ignored below 'headers' detail level.
+     *
+     * `properties` is the Object's property block as the wire carried it; omit it
+     * when the Object had no properties field.
+     */
+    recordObjectHeader(streamId: bigint, groupId: bigint, objectId: bigint, publisherPriority: number, objectStatus: number, properties?: Uint8Array): void;
     /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
     recordObjectPayload(streamId: bigint, groupId: bigint, objectId: bigint, size: number, payload?: Uint8Array): void;
     /**

package/dist/index.js

@@ -329,10 +329,10 @@ function cborToHeader(obj) {
     ...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
+    // Not `Record<string, unknown>` by assertion but by test. Asserted, a
+    // `"custom"` that is not a map would reach this field wearing that type,
+    // and the first caller to iterate its keys would meet a shape it was told
+    // could not occur. The bytes survive either way; only the test keeps the
     // field's type true.
     ...optional(src, "custom", "custom", asMap)
   };
@@ -404,6 +404,7 @@ function eventToCbor(event) {
       base.o = event.objectId;
       base.pp = int(event.publisherPriority);
       base.os = int(event.objectStatus);
+      if (event.properties != null) base.props = event.properties;
       break;
     }
     case "object-payload": {
@@ -661,7 +662,8 @@ function decodeEvent(src) {
         groupId: requireUint(src, "g"),
         objectId: requireUint(src, "o"),
         publisherPriority: Number(take(src, "pp") ?? 0),
-        objectStatus: Number(take(src, "os") ?? 0)
+        objectStatus: Number(take(src, "os") ?? 0),
+        ...optional(src, "props", "properties", asByteString)
       };
     case "object-payload":
       return {
@@ -1215,7 +1217,7 @@ function createRecorder(options) {
         errorCode
       });
     },
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
@@ -1225,7 +1227,8 @@ function createRecorder(options) {
         groupId,
         objectId,
         publisherPriority,
-        objectStatus
+        objectStatus,
+        ...properties !== void 0 ? { properties } : {}
       });
     },
     recordObjectPayload(streamId, groupId, objectId, size, payload) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moqtap/trace",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "MoQT session trace format — record, serialize, and analyze .moqtrace files",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "corpus": "bun run src/__tests__/corpus/generate.ts && bun run src/__tests__/corpus/manifest.ts"
   },
   "peerDependencies": {
-    "@moqtap/codec": "*"
+    "@moqtap/codec": ">=0.11.0"
   },
   "dependencies": {
     "cbor-x": "^1.6.0"

package/src/binary.ts

@@ -110,11 +110,11 @@ const COMMON_EVENT_KEYS = new Set(['n', 't', 'p', 'e'])
  * "A defined key whose value has an unusable type is treated as unrecognised."
  *
  * Only the decode writes to the set, so there is no separate list of owned keys
- * to keep in step with it. The list there used to be is what made adding
- * `"ta"`, `"sg"`, `"fri"` and `"g"` to Event 1 *reduce* what this reader
- * preserved: those keys counted as owned whatever they carried, so a
- * wrong-typed one was kept out of `extra` while the decode either threw on it,
- * losing the whole file, or coerced it into a value the file never carried.
+ * to keep in step with it. A list would make adding a key to an event *reduce*
+ * what this reader preserves: a listed key counts as owned whatever it
+ * carries, so a wrong-typed one would be kept out of `extra` while the decode
+ * either threw on it, losing the whole file, or coerced it into a value the
+ * file never carried.
  */
 interface Decoding {
   readonly obj: Record<string, unknown>
@@ -315,8 +315,8 @@ function segmentToCbor(segment: SegmentInfo): Record<string, unknown> {
  *
  * `"sequence"` is the exception, and the only key inside here that can fail a
  * header: it is the sole ordering key of a segmented stream, so a reader that
- * cannot read it cannot place the segment, and the `0` this function used to
- * default to invents an order the file never had.
+ * cannot read it cannot place the segment, and defaulting it to `0` would
+ * invent an order the file never had.
  */
 function cborToSegment(value: unknown): SegmentInfo | undefined {
   const obj = asMap(value)
@@ -415,10 +415,10 @@ export function cborToHeader(obj: Record<string, unknown>): TraceHeader {
     ...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
+    // Not `Record<string, unknown>` by assertion but by test. Asserted, a
+    // `"custom"` that is not a map would reach this field wearing that type,
+    // and the first caller to iterate its keys would meet a shape it was told
+    // could not occur. The bytes survive either way; only the test keeps the
     // field's type true.
     ...optional(src, 'custom', 'custom', asMap),
   }
@@ -542,6 +542,7 @@ function eventToCbor(event: TraceEvent): Record<string, unknown> {
       base.o = event.objectId
       base.pp = int(event.publisherPriority)
       base.os = int(event.objectStatus)
+      if (event.properties != null) base.props = event.properties
       break
     }
     case 'object-payload': {
@@ -808,10 +809,10 @@ function requireUint(src: Decoding, key: string): bigint {
 /**
  * Take a required header text key, or fail the header.
  *
- * The reader used to assert the type instead — `obj.protocol as string` — which
- * let a header with no `"protocol"` reach a caller with `undefined` sitting in
- * a field declared `string`, and re-encode as CBOR `undefined`, a shape the
- * format tells writers never to produce.
+ * Asserting the type instead — `obj.protocol as string` — would let a header
+ * with no `"protocol"` reach a caller with `undefined` sitting in a field
+ * declared `string`, and re-encode as CBOR `undefined`, a shape the format
+ * tells writers never to produce.
  */
 function requireHeaderText(src: Decoding, key: string): string {
   const present = Object.hasOwn(src.obj, key)
@@ -986,6 +987,7 @@ function decodeEvent(src: Decoding): TraceEvent {
         objectId: requireUint(src, 'o'),
         publisherPriority: Number(take(src, 'pp') ?? 0),
         objectStatus: Number(take(src, 'os') ?? 0),
+        ...optional(src, 'props', 'properties', asByteString),
       }
 
     case 'object-payload':

package/src/recorder.ts

@@ -104,13 +104,19 @@ export interface TraceRecorder {
   /** Record a stream-closed event. Ignored at 'control' detail level. */
   recordStreamClosed(streamId: bigint, errorCode?: number): void
 
-  /** Record an object header event. Ignored below 'headers' detail level. */
+  /**
+   * Record an object header event. Ignored below 'headers' detail level.
+   *
+   * `properties` is the Object's property block as the wire carried it; omit it
+   * when the Object had no properties field.
+   */
   recordObjectHeader(
     streamId: bigint,
     groupId: bigint,
     objectId: bigint,
     publisherPriority: number,
     objectStatus: number,
+    properties?: Uint8Array,
   ): void
 
   /** Record an object payload event. Ignored below 'headers+sizes' detail level. */
@@ -171,10 +177,10 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
   /**
    * Index of the oldest event still live in {@link events}.
    *
-   * Dropping used to be `events.shift()`, which moves the whole backlog on
-   * every call; at a hundred thousand retained events that is O(n) per
-   * recorded event, and it bites hardest exactly when the recorder is already
-   * under pressure. The head advances instead, and the dead prefix is spliced
+   * Dropping is not `events.shift()`, which moves the whole backlog on every
+   * call; at a hundred thousand retained events that is O(n) per recorded
+   * event, and it bites hardest exactly when the recorder is already under
+   * pressure. The head advances instead, and the dead prefix is spliced
    * away in one pass every few thousand drops, which is O(1) amortised.
    */
   let head = 0
@@ -342,7 +348,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
       })
     },
 
-    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
+    recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus, properties) {
       if (detailRank < DETAIL_RANK.headers) return
       addEvent({
         type: 'object-header',
@@ -353,6 +359,7 @@ export function createRecorder(options: RecorderOptions): TraceRecorder {
         objectId,
         publisherPriority,
         objectStatus,
+        ...(properties !== undefined ? { properties } : {}),
       })
     },
 

package/src/types.ts

@@ -319,6 +319,23 @@ export interface ObjectHeaderEvent extends BaseEvent {
   readonly objectId: bigint
   readonly publisherPriority: number
   readonly objectStatus: number
+  /**
+   * The Object's property block — Object Properties, Extension Headers before
+   * draft-17 — exactly as the wire carried it, past its length field.
+   *
+   * Absent when the Object had no properties field, which is not the same as an
+   * empty block: a subgroup stream with the PROPERTIES flag carries a zero
+   * length on every Object that has none. Kept as bytes rather than decoded
+   * because the encoding is the draft's, and a reader decodes it with the codec
+   * that reads the rest of the session; a decoded form would freeze one draft's
+   * rules into the format.
+   *
+   * Recorded from `'headers'` up. It is object metadata a payload's consumer
+   * reads before the payload — timestamps, frame marking, a codec
+   * configuration — and before this key no level recorded it, so a trace could
+   * not show what decided how its media was decoded.
+   */
+  readonly properties?: Uint8Array
 }
 
 export interface ObjectPayloadEvent extends BaseEvent {