From e5ad3d79d1e0e85e304d0571865a5c9b7764f899 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 13:54:51 -0700 Subject: [PATCH 1/4] quest: claim m1/ffi-crate-spike Co-Authored-By: Claude Opus 5.5 From 1158e083c2129422bba3a7394381848c62129acd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 14:37:40 -0700 Subject: [PATCH 2/4] quest(m1): binding namespace spike is a no-go UniFFI 0.32 keys a crate's types by bare name, so a layer crate cannot reuse the net noun it wraps (media.GroupConsumer over GroupConsumer). Every generator refuses it except Python, which drops the type silently. Keep the wrapper namespaces and delete the crate-split migration. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 - quest/m1/c/README.md | 2 - quest/m1/cpp-generated-shape.md | 4 -- quest/m1/ffi-crate-spike.md | 37 ---------------- quest/m1/ffi-crate-split.md | 78 --------------------------------- quest/m1/ffi-shape/README.md | 14 ++++-- 6 files changed, 11 insertions(+), 126 deletions(-) delete mode 100644 quest/m1/ffi-crate-spike.md delete mode 100644 quest/m1/ffi-crate-split.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 01a985a77c7..346d0cbb864 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -72,7 +72,6 @@ above them. - [FETCH max-delay](/quest/m1/fetch-max-delay.md) - historical readers obey publisher max-age and an optional tighter reader budget, including while holding a group - [Claim answer epochs](/quest/m1/claim-answer-epochs.md) - a claim answers each output by publishing it at its exact path under its own epoch, so a restarted output never reaches a returning reader as the old one's cache - [Untimed decisions](/quest/m1/untimed-decisions.md) - the maintainer decides whether moq-archive keeps refusing untimed tracks, and whether a malformed FETCH object ends its track -- [Binding namespace feasibility](/quest/m1/ffi-crate-spike.md) - a measured generator go/no-go before the binding API freezes - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed - [moq-net's async feature](/quest/m1/net-async-feature.md) - async helpers and both sessions sit behind a default `async` feature, and CI builds moq-net without it; Controlled time's net migration requires it @@ -174,7 +173,6 @@ above them. - [Plan: HLS export failure signal](/quest/m1/hls-failure-signal.md) - decide what players see when the exporter's timeline fails, live or history, so a truncated recording never looks complete - [Publisher linger](/quest/m1/publisher-linger.md) - every finishing publisher keeps its broadcast up for the media max-age so subscribers can drain it - [Shared timebase in the bindings](/quest/m1/ffi-timebase.md) - binding apps publish several containers from one source on one shared offset -- [One UniFFI crate per binding layer](/quest/m1/ffi-crate-split.md) - conditional on the separate spike, per-layer UniFFI crates in one library so generated names drop the `Moq` and layer prefixes; reopens the one-crate decision - [Vulkan Video encode on AMD](/quest/m1/vulkan-encode.md) - H.264 and H.265 from an external Vulkan image on RADV, hand-rolled on ash, proven on an RX 9070 - [VA-API encodes an external Vulkan image](/quest/m1/vaapi-vulkan-import.md) - an explicit-sync DMA-BUF reaches Intel's encoder, proven on Arrow Lake - [Malformed moq-transport input](/quest/m1/ietf-malformed-close.md) - malformed draft-18 and draft-21 control input closes the session with the draft's code, or PROTOCOL_VIOLATION where a code is a real burden and the fallback is recorded in `doc/concept/standard.md`, in moq-net and js/net diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index 065309ea6b2..2e16a2efd97 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -52,8 +52,6 @@ That change owns its C tests and upgrade notes; other API reshaping stays here. ## Required -- [Binding namespaces](/quest/m1/ffi-crate-split.md) - settle the generated package shape before its C/C++ release proof - - [moq-c package](/quest/m1/c/package.md) - the generated header ships as `moq-c` 0.8.0 with `moq::c`, pkg-config, and a release workflow - [C consumers](/quest/m1/c/consumers.md) - the C interop client and `doc/lib/c` samples move onto the generated API diff --git a/quest/m1/cpp-generated-shape.md b/quest/m1/cpp-generated-shape.md index 4e8976a5a1b..454ac74df48 100644 --- a/quest/m1/cpp-generated-shape.md +++ b/quest/m1/cpp-generated-shape.md @@ -34,7 +34,3 @@ place that names the pin. makes `value()` on an error `__builtin_unreachable`; patch it to abort with a message, like a misused future, and drop the "undefined" warning from the Errors section of `doc/lib/cpp/index.md`. - -## Required - -- [Binding namespaces](/quest/m1/ffi-crate-split.md) - settle the generated package shape before its C/C++ release proof diff --git a/quest/m1/ffi-crate-spike.md b/quest/m1/ffi-crate-spike.md deleted file mode 100644 index 05df3c09ea8..00000000000 --- a/quest/m1/ffi-crate-spike.md +++ /dev/null @@ -1,37 +0,0 @@ -# [L] Prove generated binding namespaces - -## Goal - -Decide whether every supported binding generator can expose per-layer -namespaces from one native library before this release freezes the API. - -## Plan - -Spike, splitting `media` from `net` alone: - -1. Make the dependency one-way, `media` on `net`. Today `net`'s consumers - return `MoqFrame` and `MoqDatagram` from `media.rs`, which Cargo would - reject as a cycle; those raw records likely belong in `net`. -2. Generate bindings from the built library, in this order: uniffi-bindgen-go, - uniffi-bindgen-dart, uniffi-bindgen-cpp (both C++ and generated C), then Kotlin, Swift, and Python. - For each, check: - - It emits one module per crate. - - `net` types used from `media` resolve as external types, covering each - category the real split crosses: an object (`GroupConsumer`), the - thrown `MoqError`, and a record or enum. - - The Go, Dart, and C++ generators are kixelated forks pinned in - `flake.nix`, so patch a gap in the fork before calling it a no-go. - For generated C, compile and link an installed consumer using cross-crate - objects, errors and records from the same native library. -3. Check that each platform still ships one native library: the `go/ffi` - module layout, the Swift XCFramework and its module maps, the Kotlin and - Android artifacts, the `moq_ffi` Dart package, the Python wheel, and the - C++ CMake package. -4. Record the verdict for each generator here, along with the library size - before and after the split. - -A go enables [the migration](/quest/m1/ffi-crate-split.md). A measured -no-go records the unsupported generator and retains wrapper namespaces, -removing the migration prerequisite from the tree. This quest ships proof -and a decision, not the full wrapper migration. diff --git a/quest/m1/ffi-crate-split.md b/quest/m1/ffi-crate-split.md deleted file mode 100644 index 442b7a748d9..00000000000 --- a/quest/m1/ffi-crate-split.md +++ /dev/null @@ -1,78 +0,0 @@ -# [L] One UniFFI crate per binding layer - -## Goal - -The generated bindings carry the layers themselves. moq-ffi becomes one -UniFFI crate per layer (`net`, `media`, `json`, `flate`, `audio`, `video`), -all linked into the one moq-ffi library, so a generated type is -`media.GroupConsumer` instead of `MoqMediaGroupConsumer`. -The separate feasibility spike decides whether all generators can carry -this shape. A no-go removes this migration from the release and retains -wrapper namespaces; do not hold the release for an infeasible generator. - -Out of scope: the hand-written moq-c, the wire, and Rust type names. - -## Plan - -Raised on #5356, where the maintainer found `MoqMediaContainerGroupConsumer` -too long and asked how to namespace the modules better. #5356 renamed the -media consumers to `MoqMediaTrackConsumer` and `MoqMediaGroupConsumer`, but -every generated name still carries `Moq` and its layer, as in -`MoqMediaContainerStreamProducer`. They show up in moq-ffi's source, the raw -generated packages (`go/ffi`, `dart/moq_ffi`), and C++ -(`moq::MediaGroupConsumer`). The Python, Go, Swift, Kotlin, and Dart -wrappers already shorten them to `media.GroupConsumer`. - -✅ The maintainer reopened (2026-10-13) the 2026-10-09 decision in -[The bindings mirror Rust's layers](/quest/m1/ffi-shape/README.md) that -moq-ffi stays one crate and the wrappers supply the namespaces, calling the -5-word generated name from #5356 terrible. UniFFI 0.32 gives each crate one -flat namespace, so only a split shortens it. The migration waits for the -spike to pass. - -Options weighed on #5356: - -- ✅ One UniFFI crate per layer, all in one library. This is the only option - that puts real namespaces below the wrappers. Mozilla's - application-services ships many UniFFI component crates in one "megazord" - library this way. -- Drop `Moq` with `#[uniffi(name = "...")]`. The layer prefix stays, - because the namespace is still flat. Bare names collide with host types - (Swift `Error`, Kotlin `Result`), and UniFFI renames behave inconsistently - in Python and for custom types. -- Keep the generated names and treat them as plumbing behind the wrappers. - -If the spike passes, migrate: - -- Split moq-ffi into one crate per ffi-shape layer. Every layer keeps the - one runtime in `ffi.rs`, so `moq_ffi_shutdown` (Python's `atexit` hook) - still stops tasks from every layer; add an exit regression with a live - non-`net` task. -- Point each wrapper at the generated modules, and delete any wrapper code - that only existed to rename types. This includes every `rs/moq-ffi` - consumer in AGENTS.md's Cross-Package Sync table; `cpp/moq`'s alias list - backs the flat `moq::Media*` names that `cpp/obs/src` uses. -- Update `doc/lib`, the Unreleased section of `doc/setup/upgrade.md`, and the - ffi-shape Plan. -- Review the import-side media names under the same rule (decided - 2026-10-13 instead of a separate quest). `MoqMediaContainerStreamProducer` - (`media.ContainerStreamProducer`) is still five words, and "Container" there - means an importer that recovers framing from a raw byte stream and may publish - several tracks, unlike the per-track consumers #5356 renamed to - `media.TrackConsumer` and `media.GroupConsumer`. -- Run `just test interop --all`. - -The migration lands after [Codecs](/quest/m1/ffi-shape/codec.md), so it does -not fight that reshape of `audio` and `video`. - -## Related - -- [The bindings mirror Rust's layers](/quest/m1/ffi-shape/README.md) - the one-crate decision this reopens -- [Unprefixed generated C++](/quest/m1/cpp-generated-shape.md) - its `Moq` prefix rename shrinks if the C++ generator gives each crate its own namespace -- [Generated C bindings](/quest/m1/c/README.md) - the C backend in the same generator fork would also see one module per crate -- [Bindings size profile](/quest/m2/ffi-size-profile.md) - measures the same library whose size the split may change - -## Required - -- [Namespace feasibility](/quest/m1/ffi-crate-spike.md) - a measured go/no-go before changing generated package names -- [Codecs](/quest/m1/ffi-shape/codec.md) - the layer shape being migrated diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 60b9d37793b..6cd0331bc85 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -56,9 +56,17 @@ Settled shape: the wrappers supply real namespaces in each language's idiom: Python submodules, Go subpackages (`moq.dev/moq/json`, aliased on import next to `encoding/json`), Kotlin packages, Dart libraries, Swift caseless-enum - namespaces. Reopened 2026-10-13: - [Binding namespace feasibility](/quest/m1/ffi-crate-spike.md) spikes - a per-layer split that would move the namespaces below the wrappers. + namespaces. A per-layer crate split, reopened 2026-10-13 to move the + namespaces below the wrappers, was spiked and rejected (PR_PLACEHOLDER): UniFFI + 0.32 keys a crate's types by bare name, so `media.GroupConsumer` cannot + take the net `GroupConsumer` it wraps. Python drops the media type + silently; every other generator refuses. Revisit only if UniFFI + namespaces external types. +- Still open from #5356: whether the import-side + `MoqMediaContainerStreamProducer` (`media.ContainerStreamProducer`) is + named by role. "Container" there means an importer that recovers framing + from a raw byte stream and may publish several tracks, unlike the + per-track `media.TrackConsumer` and `media.GroupConsumer`. - `demand()` is the one way to watch subscribers; producers drop their `name`/`is_used`/`used`/`unused` duplicates. - moq-ffi and its generated consumers, including `cpp/obs` (above). The From 89e54702a164b710bf619895b6c905001905f2bb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 14:38:43 -0700 Subject: [PATCH 3/4] quest(m1): link the spike PR from ffi-shape Co-Authored-By: Claude Opus 5.5 --- quest/m1/ffi-shape/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 6cd0331bc85..6b9509bf57c 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -57,7 +57,7 @@ Settled shape: submodules, Go subpackages (`moq.dev/moq/json`, aliased on import next to `encoding/json`), Kotlin packages, Dart libraries, Swift caseless-enum namespaces. A per-layer crate split, reopened 2026-10-13 to move the - namespaces below the wrappers, was spiked and rejected (PR_PLACEHOLDER): UniFFI + namespaces below the wrappers, was spiked and rejected (#5460): UniFFI 0.32 keys a crate's types by bare name, so `media.GroupConsumer` cannot take the net `GroupConsumer` it wraps. Python drops the media type silently; every other generator refuses. Revisit only if UniFFI From d32c9c61729f8aa3886f7e2bd55c68f79a2f7949 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 13 Oct 2026 15:53:51 -0700 Subject: [PATCH 4/4] quest(m1): track the stream importer name as its own decision quest The deleted crate split owned this naming review; an unlinked note in the epic's settled shape could be skipped when the epic retires. Co-Authored-By: Claude Opus 5.5 --- quest/m1/ffi-shape/README.md | 6 +----- quest/m1/ffi-shape/stream-producer-name.md | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 5 deletions(-) create mode 100644 quest/m1/ffi-shape/stream-producer-name.md diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 6b9509bf57c..a613abe59e7 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -62,11 +62,6 @@ Settled shape: take the net `GroupConsumer` it wraps. Python drops the media type silently; every other generator refuses. Revisit only if UniFFI namespaces external types. -- Still open from #5356: whether the import-side - `MoqMediaContainerStreamProducer` (`media.ContainerStreamProducer`) is - named by role. "Container" there means an importer that recovers framing - from a raw byte stream and may publish several tracks, unlike the - per-track `media.TrackConsumer` and `media.GroupConsumer`. - `demand()` is the one way to watch subscribers; producers drop their `name`/`is_used`/`used`/`unused` duplicates. - moq-ffi and its generated consumers, including `cpp/obs` (above). The @@ -87,4 +82,5 @@ runs `just test interop --all`. ## Required - [Codecs](/quest/m1/ffi-shape/codec.md) - audio and video producers, codec-only encoders, and decoders move under their own namespaces, named as in Rust; binding releases wait for it +- [Stream importer name](/quest/m1/ffi-shape/stream-producer-name.md) - the maintainer settles `media.ContainerStreamProducer`'s name before the binding release - [Layers guide](/quest/m1/ffi-shape/layers-guide.md) - a `doc/lib` page maps each Rust layer to every binding's module, once Codecs adds `audio` and `video` diff --git a/quest/m1/ffi-shape/stream-producer-name.md b/quest/m1/ffi-shape/stream-producer-name.md new file mode 100644 index 00000000000..88d43078cf6 --- /dev/null +++ b/quest/m1/ffi-shape/stream-producer-name.md @@ -0,0 +1,21 @@ +# [S] Name the container stream importer by role + +## Goal + +The maintainer decides whether the import-side +`MoqMediaContainerStreamProducer` (`media.ContainerStreamProducer` in the +wrappers) is named by role, and any rename lands before the binding release +that [Codecs](/quest/m1/ffi-shape/codec.md) gates, so the bindings break once. + +## Plan + +Still open from #5356, which renamed the per-track consumers to +`media.TrackConsumer` and `media.GroupConsumer`. "Container" here means an +importer that recovers framing from a raw byte stream and may publish several +tracks, unlike those per-track consumers. The rejected crate split (#5460) +had owned this review. + +Ask with 2-3 candidate names and a recommendation. A rename touches moq-ffi, +every wrapper, `cpp/moq`'s alias list, the `doc/lib` samples, and the +Unreleased section of `doc/setup/upgrade.md`; keeping the name deletes this +quest.