Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions .agents/plans/moq-engine-implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ plan, and what Phase 0/5 still owes.
| Plan item | Status | Where |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This temporary implementation plan should not remain in the repository after the implementation lands. Delete .agents/plans/moq-engine-implementation.md before merging, as required by .agents/plans/README.md.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At .agents/plans/moq-engine-implementation.md, line 12:

<comment>This temporary implementation plan should not remain in the repository after the implementation lands. Delete `.agents/plans/moq-engine-implementation.md` before merging, as required by `.agents/plans/README.md`.</comment>

<file context>
@@ -9,7 +9,7 @@ plan, and what Phase 0/5 still owes.
 |---|---|---|
 | §5 type-model change | ✅ | `media/types` — `TrackDeliveryMode` + `LiveOf<T>` (extends `PartiallyResolved<T>`, zero HLS ripple; audit confirmed selection reads only metadata) |
-| Phase 1 wire protocol | ✅ | `network/moqt/` — vi64 varint, control messages, request streams, object streams, session driver; 51 tests incl. spec Table 2 golden vectors |
+| Phase 1 wire protocol | ✅ | Was `network/moqt/` (vi64 varint, control messages, request streams, object streams, session driver; 51 tests incl. spec Table 2 golden vectors). Since 2026-10-27 the player uses `@caprid/moq-core`, the package extracted from it |
 | Phase 2 format layer | ✅ | `media/moq/` — parse-source (msf: fragment), parse-catalog (independent + delta), loc, codec-mapping, timeline; 46 tests |
 | Phase 3 actors/behaviors | ✅ | `playback/actors/{moq-session,track-subscriber}`, `playback/actors/dom/{video,audio}-renderer`, `playback/behaviors/{setup-moq-session,resolve-catalog,subscribe-selected-tracks,sync-latency,track-moq-bandwidth}`, `behaviors/dom/setup-moq-renderers` |
</file context>

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't fix, for the same reason: the MoQ plan files are kept on these integration branches deliberately.

|---|---|---|
| §5 type-model change | ✅ | `media/types` — `TrackDeliveryMode` + `LiveOf<T>` (extends `PartiallyResolved<T>`, zero HLS ripple; audit confirmed selection reads only metadata) |
| Phase 1 wire protocol | ✅ | `network/moqt/` — vi64 varint, control messages, request streams, object streams, session driver; 51 tests incl. spec Table 2 golden vectors |
| Phase 1 wire protocol | ✅ | Was `network/moqt/` (vi64 varint, control messages, request streams, object streams, session driver; 51 tests incl. spec Table 2 golden vectors). Since 2026-10-27 the player uses `@caprid/moq-core`, the package extracted from it |
| Phase 2 format layer | ✅ | `media/moq/` — parse-source (msf: fragment), parse-catalog (independent + delta), loc, codec-mapping, timeline; 46 tests |
| Phase 3 actors/behaviors | ✅ | `playback/actors/{moq-session,track-subscriber}`, `playback/actors/dom/{video,audio}-renderer`, `playback/behaviors/{setup-moq-session,resolve-catalog,subscribe-selected-tracks,sync-latency,track-moq-bandwidth}`, `behaviors/dom/setup-moq-renderers` |
| Phase 4 engine + adapter | ✅ | `playback/engines/moq/` — `createMoqEngine`, `MoqMediaMixin` (canvas facade, §6 prototype 1), `./moq` export, `--moq` size flag |
Expand All @@ -24,9 +24,10 @@ Size baseline (2026-07-17): MoQ entry 18.16 KB min+gzip (90.8% of the
Implemented against the actual spec texts (fetched 2026-07-17):
`draft-ietf-moq-transport-19`, `draft-ietf-moq-msf-01`,
`draft-ietf-moq-loc-02` (LOC moved to loc-04 in PR #9). The spec texts are
now vendored under `internal/specs/moq/` (transport-20, loc-04, msf-01 as of
2026-09-02); the draft-20 migration plan is `moq-transport-20-migration.md`
beside this file. Notable corrections to the plan's assumptions:
now vendored under `internal/specs/moq/` (transport-22, loc-04, msf-01 as of
2026-10-27); the draft-20 migration plan is `moq-transport-20-migration.md`
beside this file, and the transport codec now comes from `@caprid/moq-core`
(moqt-22, falling back to moqt-20). Notable corrections to the plan's assumptions:

- **Varint is NOT the QUIC RFC 9000 varint.** Draft-15+ uses a
leading-ones vi64 (1–9 bytes). Spec Table 2 vectors are test fixtures.
Expand Down Expand Up @@ -151,7 +152,7 @@ promotion). Zero page errors.
draft-19 bytes (vi64, SETUP/SUBSCRIBE_OK/REQUEST_ERROR, subgroup +
LOC framing) over an in-memory `MoqtTransport`, publishing real
WebCodecs-encoded VP8 (two renditions) + Opus. Written from the specs
rather than reusing `network/moqt`'s encoders: it is a second
rather than reusing the transport codec: it is a second
independent implementation, so it checks the decoder rather than
round-tripping against ourselves. `?relay=moqt://…#msf:…` swaps in a
real relay.
Expand Down
7 changes: 7 additions & 0 deletions .agents/plans/moq-transport-20-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,13 @@ the spec text is ambiguous, and calls out each place it does.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This migration plan is explicitly superseded, so retaining its draft-20 checklist leaves stale instructions in the repository. Delete .agents/plans/moq-transport-20-migration.md before merging.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At .agents/plans/moq-transport-20-migration.md, line 21:

<comment>This migration plan is explicitly superseded, so retaining its draft-20 checklist leaves stale instructions in the repository. Delete `.agents/plans/moq-transport-20-migration.md` before merging.</comment>

<file context>
@@ -18,6 +18,13 @@ the spec text is ambiguous, and calls out each place it does.
 
 Temporary implementation notes — delete before merge per `AGENTS.md`.
 
+**Superseded on the player (2026-10-27):** `mmcc/moq` now takes its transport
+from `@caprid/moq-core`, which was extracted from `network/moqt/`. It offers
+`moqt-22` first and falls back to `moqt-20`. The local modules this plan
</file context>

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't fix. The MoQ plan files are kept on these integration branches deliberately. This one is marked superseded on the player instead.

Temporary implementation notes — delete before merge per `AGENTS.md`.

**Superseded on the player (2026-10-27):** `mmcc/moq` now takes its transport
from `@caprid/moq-core`, which was extracted from `network/moqt/`. It offers
`moqt-22` first and falls back to `moqt-20`. The local modules this plan
names, and the vendored draft-20 text, are gone. `internal/specs/moq/` now
carries draft-22. Section numbers below are draft-20's. The publisher still
runs the local codec until its own move.

**Issue #45 verification (2026-09-16, moq-relay 0.14.17):** the shared codec
uses bare Locations in both directions. Fixed-byte tests pin SUBSCRIBE_OK,
REQUEST_OK, multi-byte IDs, following parameters/properties, and truncation.
Expand Down
2 changes: 1 addition & 1 deletion apps/sandbox/templates/moq-relay-interop/main.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// MoQ (draft-ietf-moq-transport-20 / MSF) relay interop smoke test.
// MoQ (draft-ietf-moq-transport-22 / MSF) relay interop smoke test.
// http://localhost:5173/moq-relay-interop/
//
// Query params:
Expand Down
28 changes: 14 additions & 14 deletions apps/sandbox/templates/spf-moq-player/loopback-relay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
* Loopback MoQ relay — a synthetic MSF publisher for the sandbox.
*
* There is no public relay that serves draft-ietf-moq-msf-01 catalogs yet (Phase 0 interop is still owed), so this
* stands in for one: it speaks real draft-20 bytes over an in-memory `MoqtTransport` and publishes real
* stands in for one: it speaks real draft-22 bytes over an in-memory `MoqtTransport` and publishes real

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The sandbox UI still says the default loopback relay speaks draft-20, contradicting this draft-22 update. Update index.html so the user-facing description matches the relay.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At apps/sandbox/templates/spf-moq-player/loopback-relay.ts, line 5:

<comment>The sandbox UI still says the default loopback relay speaks draft-20, contradicting this draft-22 update. Update `index.html` so the user-facing description matches the relay.</comment>

<file context>
@@ -2,12 +2,12 @@
  *
  * There is no public relay that serves draft-ietf-moq-msf-01 catalogs yet (Phase 0 interop is still owed), so this
- * stands in for one: it speaks real draft-20 bytes over an in-memory `MoqtTransport` and publishes real
+ * stands in for one: it speaks real draft-22 bytes over an in-memory `MoqtTransport` and publishes real
  * WebCodecs-encoded media, which is enough to drive the whole engine — catalog → selection → subscribe → decode →
  * canvas + AudioContext.
</file context>

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #77: the sandbox page now says draft-22.

* WebCodecs-encoded media, which is enough to drive the whole engine — catalog → selection → subscribe → decode →
* canvas + AudioContext.
*
* The wire encoding here is written from the specs rather than reusing `network/moqt`'s encoders (they aren't public
* API, and a second independent implementation is worth more as a check on the decoder than a round-trip against
* The wire encoding here is written from the specs rather than reusing `@caprid/moq-core`'s encoders (they aren't
* public API, and a second independent implementation is worth more as a check on the decoder than a round-trip against
* ourselves would be).
*
* Published tracks (subscribe lazily starts a producer per subscription):
Expand All @@ -19,10 +19,10 @@
import type { CreateMoqTransport } from '@videojs/spf/moq';

// ============================================================================
// Wire primitives (draft-ietf-moq-transport-20)
// Wire primitives (draft-ietf-moq-transport-22)
// ============================================================================

/** Control/request message types (§10, Table 5). */
/** Control/request message types (§9, Table 5). */
const MESSAGE_TYPE = {
SETUP: 0x2f00,
SUBSCRIBE: 0x3,
Expand All @@ -31,21 +31,21 @@ const MESSAGE_TYPE = {
FETCH: 0x16,
} as const;

/** REQUEST_ERROR code for "nothing published in that range" (§10.6.1). */
/** REQUEST_ERROR code for "nothing published in that range" (§12.3). */
const ERROR_INVALID_RANGE = 0x11;

/**
* SUBGROUP_HEADER stream type: subgroup-id mode `zero`, default publisher priority, objects carry a Properties field,
* not end-of-group. `0b0011_0001` — see §11.4.2 for the flag layout.
* not end-of-group. `0b0011_0001` — see §11.3.1 for the flag layout.
*/
const SUBGROUP_HEADER_TYPE = 0x31;

/** LOC property IDs (draft-ietf-moq-loc-04 §2.3). */
const LOC_TIMESTAMP = 0x10;

/**
* The vi64 varint of draft-15+ (§1.4.1) — leading ones on the first byte give the encoded length minus one, so an
* L-byte encoding carries 7L value bits. NOT the QUIC RFC 9000 varint.
* The vi64 varint of draft-15+ (§8.1) — leading ones on the first byte give the encoded length minus one, so an L-byte
* encoding carries 7L value bits. NOT the QUIC RFC 9000 varint.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The draft-22 vi64 comment omits the 9-byte, 64-bit form, and varintByteLength still caps encodings at 8 bytes. Add draft-22’s 9-byte encoding support before claiming full draft-22 wire coverage.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At apps/sandbox/templates/spf-moq-player/loopback-relay.ts, line 48:

<comment>The draft-22 vi64 comment omits the 9-byte, 64-bit form, and `varintByteLength` still caps encodings at 8 bytes. Add draft-22’s 9-byte encoding support before claiming full draft-22 wire coverage.</comment>

<file context>
@@ -31,21 +31,21 @@ const MESSAGE_TYPE = {
- * The vi64 varint of draft-15+ (§1.4.1) — leading ones on the first byte give the encoded length minus one, so an
- * L-byte encoding carries 7L value bits. NOT the QUIC RFC 9000 varint.
+ * The vi64 varint of draft-15+ (§8.1) — leading ones on the first byte give the encoded length minus one, so an L-byte
+ * encoding carries 7L value bits. NOT the QUIC RFC 9000 varint.
  */
 function varintByteLength(value: number): number {
</file context>

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected the comment in #77, but no encoder change. The decoder already reads the 9-byte form, and the 8-byte form's 56 bits cover every integer a JS number represents exactly (2^53), so the encoder never needs 9 bytes.

*/
function varintByteLength(value: number): number {
for (let length = 1; length < 8; length++) {
Expand Down Expand Up @@ -144,14 +144,14 @@ class Reader {
}
}

/** Control message framing (§10.1): type varint + 16-bit length + body. */
/** Control message framing (§9): type varint + 16-bit length + body. */
function frame(type: number, body: Uint8Array): Uint8Array {
return new Writer().varint(type).u16(body.length).bytes(body).toBytes();
}

function encodeSetup(): Uint8Array {
// Options-only, and we send none. A Key-Value-Pair block is bounded by its
// enclosing length rather than counted (§10.2), so "no options" is an empty
// enclosing length rather than counted (§9.1), so "no options" is an empty
// body — not a zero count.
return frame(MESSAGE_TYPE.SETUP, new Uint8Array(0));
}
Expand Down Expand Up @@ -574,7 +574,7 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb
const host: ProducerHost = { nowUs, publish: publishObject, log };

/**
* The server's control stream. It stays open for the session's lifetime — closing it ends the session (§3.3) — so
* The server's control stream. It stays open for the session's lifetime — closing it ends the session (§6.3) — so
* the writer is held until this transport closes.
*/
const sendServerSetup = (): void => {
Expand Down Expand Up @@ -672,7 +672,7 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb
if (message.type === MESSAGE_TYPE.SUBSCRIBE) {
onSubscribe(message.body);
} else if (message.type === MESSAGE_TYPE.FETCH) {
// The engine never fetches — a draft-20 join is a subscription
// The engine never fetches — a draft-22 join is a subscription
// filter, and every subscription replays the newest group anyway.
// Anything else asking for history is refused: none is retained.
await writer.write(encodeRequestError(ERROR_INVALID_RANGE, 'nothing published'));
Expand All @@ -684,7 +684,7 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb
}

const { value, done } = await reader.read();
// Cancellation *is* the stream lifecycle (§3.3.3): the subscriber
// Cancellation *is* the stream lifecycle (§6.4.2.3): the subscriber
// aborting its sending direction ends the subscription.
Comment on lines +687 to 688

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Section 6.4.2.3 does not define FIN as cancellation; it explicitly distinguishes FIN from RESET_STREAM/STOP_SENDING cancellation. Describe the done branch as graceful stream completion and leave cancellation to the catch path.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At apps/sandbox/templates/spf-moq-player/loopback-relay.ts, line 687:

<comment>Section 6.4.2.3 does not define FIN as cancellation; it explicitly distinguishes FIN from RESET_STREAM/STOP_SENDING cancellation. Describe the `done` branch as graceful stream completion and leave cancellation to the catch path.</comment>

<file context>
@@ -684,7 +684,7 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb
 
           const { value, done } = await reader.read();
-          // Cancellation *is* the stream lifecycle (§3.3.3): the subscriber
+          // Cancellation *is* the stream lifecycle (§6.4.2.3): the subscriber
           // aborting its sending direction ends the subscription.
           if (done) break;
</file context>
Suggested change
// Cancellation *is* the stream lifecycle (§6.4.2.3): the subscriber
// aborting its sending direction ends the subscription.
// A FIN means the subscriber sent no further messages; cancellation
// uses RESET_STREAM/STOP_SENDING (§6.4.2.3) and reaches the catch path.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #77. The comment now says a FIN isn't a cancellation (§6.4.2.2), that this loopback ends the subscription on either, and why that's harmless with this player (moq-core cancels with a reset and FINs only after the publisher).

if (done) break;

Expand Down
8 changes: 4 additions & 4 deletions internal/specs/moq/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@ Verbatim IETF Internet-Draft texts for the protocols the MoQ stack in `packages/

For a complete catalog example and the current player's media requirements, see [Publish a stream for the MoQ player](../../../packages/spf/docs/moq-publishing.md).

The version the code actually speaks is declared in code: `MOQT_PROTOCOL_ID` in `packages/spf/src/network/moqt/control-messages.ts` for the transport, and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`.
The version the code actually speaks is declared in code: the transport comes from the `@caprid/moq-core` dependency of `packages/spf` (its `MOQT_PROTOCOL_IDS` lists the versions the player offers, most preferred first; `moqt-20` is the fallback), and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`.

| Draft | Revision | Published | Implemented in |
| --- | --- | --- | --- |
| Media over QUIC Transport | `draft-ietf-moq-transport-20` | 2026-08-31 | `packages/spf/src/network/moqt/` |
| Media over QUIC Transport | `draft-ietf-moq-transport-22` | 2026-10-01 | `@caprid/moq-core`, consumed by `packages/spf/src/playback/actors/moq-session.ts` |
| Low Overhead Media Container (LOC) | `draft-ietf-moq-loc-04` | 2026-07-20 | `packages/spf/src/media/moq/loc.ts` |
| MOQT Streaming Format (MSF) | `draft-ietf-moq-msf-01` | 2026-06-02 | `packages/spf/src/media/moq/parse-catalog.ts`, `parse-source.ts` |

## Provenance

Fetched 2026-09-02 from the IETF archive at `https://www.ietf.org/archive/id/<draft-name>.txt`, unmodified.
Fetched from the IETF archive at `https://www.ietf.org/archive/id/<draft-name>.txt`, unmodified: the transport draft on 2026-10-27, LOC and MSF on 2026-09-02.

| File | SHA-256 |
| --- | --- |
| `draft-ietf-moq-transport-20.txt` | `96a3a4467da53cd71bb4d1c334ac7ab13887f02b2e27335e715f75889fa9a1c6` |
| `draft-ietf-moq-transport-22.txt` | `1a725f10db526d94f915b30db9004821d86e57afcdde10789c54fee64b3056b5` |
| `draft-ietf-moq-loc-04.txt` | `fb29e2805be0511a188683b60fc830fb7fd3ecf19931968755d60d83707c3b47` |
| `draft-ietf-moq-msf-01.txt` | `c3e68aac09c36ae1db4afde6fd0600a949e7265348f592520304a31e993c35af` |

Expand Down
Loading
Loading