[kixelated]

Problem

Demand was spelled two ways: wanted/wanted_changed on track::Demand and group::Demand, and used/unused/is_used on kio channels, bandwidth::Producer, track::Fill, @moq/net, moq-ffi, moq-c, and the wrappers. This finishes quest/m1/api-audit/wanted.md: every demand signal is a snapshot wanted() plus wanted_changed() and its poll, and a method nobody used is deleted rather than renamed.

Changes

• kio: Producer/ProducerWeak is_used/used/unused/poll_used/poll_unused become wanted() and poll_wanted_changed(waiter, last). Producer::wanted_changed(last) stays async for its two callers, moq-net's server close and moq-scene's source. ProducerWeak's async pair, which only tests used, is gone. write_unused/Unused::{Idle, Used, Closed} become write_unwanted/Unwanted::{Idle, Wanted, Closed}.
• moq-net:
  • bandwidth::Producer loses its five consumer-count methods and gains demand() -> bandwidth::Demand (wanted() -> bool, wanted_changed(), poll_wanted_changed()), shaped like group::Demand.
  • track::Fill merges is_used() and next() into wanted() -> Option<u64>: the next group owed, or None once nothing is owed or no reader is left. wanted_changed()/poll_wanted_changed() replace unused()/poll_unused(). A parked poll wakes on readers leaving, narrowing, or taking a group, on an answer, and on an order change. Fill is now Clone, and each clone watches on its own.
  • track::Producer::abort_unused is abort_unwanted.
  • Crate-internal helpers follow the same names: poll_wanted/poll_unwanted/is_wanted, abort_unwanted, reject_unwanted, and the origin front's Event::{Wanted, Unwanted}.
• @moq/net:
  • Broadcast.Demand, Broadcast.Producer.demand(), and the per-track aggregation behind them are deleted. They were @internal and only tests and a bench read them.
  • The @internal Group.Demand.used is wanted, and unused() is gone. Fetch coalescing waits on wanted through one module-private helper.
  • Lister.used, Listing.used, and Observed.used are wanted.
• moq-ffi: MoqFill::next/is_used/unused become wanted() and wanted_changed(), with a separate watcher the way MoqTrackDemand keeps one.
• moq-c: MOQ_DEMAND_USED/MOQ_DEMAND_UNUSED are MOQ_DEMAND_WANTED/MOQ_DEMAND_UNWANTED, with the same values.
• Wrappers: Python, Swift, and Go Fill expose wanted/wanted_changed in place of next/is_used/unused. Kotlin and Dart alias the generated type, and the Dart bindings are regenerated. The stale Used/Unused advice in go/wrapper/README.md and doc.go is fixed.

Impact

Public API, all breaking. Wire: none.

• kio: replace is_used() with wanted(), and used()/unused() with wanted_changed(false)/wanted_changed(true) (poll_wanted_changed(waiter, last)). These now return the new value (Result<bool, Closed>) instead of (). write_unused is write_unwanted, and Unused::Used is Unwanted::Wanted.
• moq-net bandwidth::Producer: replace is_used() with producer.demand().wanted(), and the used/unused waits with a loop over a held producer.demand()'s wanted_changed().
• moq-net track::Fill: serve with while let Some(sequence) = fill.wanted() where you checked is_used() && next(). Await wanted_changed() until it returns None where you awaited unused(). abort_unused is abort_unwanted.
• moq-ffi and the wrappers: MoqFill.next() is wanted(), is_used() is wanted() != null, and unused() is a loop over wanted_changed() until it returns null.
• moq-c: rename MOQ_DEMAND_USED/MOQ_DEMAND_UNUSED to MOQ_DEMAND_WANTED/MOQ_DEMAND_UNWANTED.
• @moq/net: only @internal items changed, so no published surface moved.

For the release cut, the existing Unreleased notes need these corrections:

• rs/moq-json/MIGRATE.md and rs/moq-flate/MIGRATE.md ("Demand is read through demand()"): the call is producer.demand().wanted().is_some(), not producer.demand().is_used().
• js/net/MIGRATE.md:
  • The line saying broadcast and group demand keep used and unused() is now false. Both are @internal: broadcast demand is gone, and group demand is wanted.
  • The line saying Group.Demand.unused() and Broadcast.Demand.unused() reject on close is moot.
  • "producer.unused() is producer.demand().unused()" should point at demand().wanted.

Decisions settled

The maintainer accepted every recommendation below in a /quest-complete session.

1. kio's wanted_changed takes the last value seen. The quest names wanted_changed() with no argument. A kio Producer is a bare channel handle, so tracking prev per handle would put a field on every channel. Instead it is wanted_changed(last: bool) / poll_wanted_changed(waiter, last), which returns once presence differs from last. moq-net's group::Demand, bandwidth::Demand, and the internal track poll keep the per-handle prev on top of it. Settled: keep it. The alternative, a stateful handle, costs memory on every kio channel.
2. track::Fill is now Clone. moq-ffi needs a second handle to park wanted_changed on without holding a lock across the sync getters, mirroring MoqTrackDemand. A clone shares the fill and keeps it unsettled until the last one drops, as GroupFill already does. Settled: keep it. The alternative is a mutex-wrapped Fill inside moq-ffi.
3. Renames beyond the plan's list. abort_unused → abort_unwanted (public on track::Producer), write_unused/Unused → write_unwanted/Unwanted (kio), plus the crate-internal helpers. None is a demand signal, but each named the vocabulary this PR retires. Settled: keep them. Leaving them would leave unused in kio and moq-net's public API.

Choices made

• Fill::wanted_changed returns Option<u64>, not a Result. A live fill handle keeps its answer channel open, so there is no closed state to report. A track abort shows up as its readers leaving, which ends at None.
• Fill::is_wanted(sequence)/unwanted(sequence) stay as they are. The per-group signal only ever goes one way, so a wanted_changed shape does not fit it.
• Lookups no longer count as demand in @moq/net. Pending info lookups only fed Broadcast.Demand, so with it gone they count toward nothing. Lookups still lets resolveTrackInfo close a request it opened.
• Private helpers outside the listed crates are left alone: moq-audio's private Demand trait (used/unused wrapping wanted_changed) and the carla demo's Python helpers. moq-stats's private is_used became is_wanted because it was one line.
• MIGRATE.md files are untouched; the corrections for the cut are listed under Impact above.

Tests

• New: fill_wanted_changed_follows_the_group_owed (moq-net) checks that a parked poll_wanted_changed wakes on narrowing, on an answer, and on the last reader leaving, and ends at None.
• Existing tests are ported to the new names. kio's loom tests cover wanted_changed in both directions.
• Passed locally:
  • cargo check/clippy -D warnings (all targets) on kio, moq-net, moq-ffi, moq-c, moq-tokio, moq-transcode, moq-archive, moq-scene, and moq-stats.
  • clippy --no-default-features on moq-net and kio.
  • cargo test --lib on moq-net, moq-ffi, moq-c, and moq-tokio.
  • moq-net's fetch_cancel integration tests and moq-transcode's abandoned-fetch test.
  • JS: bun run check and the touched test files in js/net, json, flate, hang, and e2ee.
• Also passed: just go check (vet, build, go test -race) and just py check (ruff, pyright, samples).
• Not run: just rs loom, the Python unit tests, the full js/net suite after the last edits, and the Swift, Kotlin, and Dart builds.
• kio's log::test cases (reader_outlives_writer, a_read_outlasts_eviction, eviction_frees_whatever_readers_do) failed under the parallel run but pass alone. log.rs is untouched here, so this is a pre-existing flake (see Follow-ups).

Follow-ups

• moq-dev/moq#6934 restores Rust's broadcast::Demand and edits this quest file. Whichever lands second converts the other's kio calls (is_used/poll_used/poll_unused → wanted/poll_wanted_changed) and resolves the quest-file conflict. This PR deletes the quest file.
• kio's log::test eviction tests are flaky when run in parallel, likely from a shared global collection. They were not investigated here.

Review

Codex (quest review), gpt-6.1-sol, medium effort, reviewed head 7c378e11ae79f4262d98cc908af9e8e7619fb664 against origin/main (1d8bf24998): no findings. That head merges main conflict-free and adds one fix for a semantic conflict the quest land batch caught: main gated the test helper write_filled behind the async feature, while this PR's sync test fill_wanted_changed_follows_the_group_owed calls it, so --no-default-features test builds failed with E0425. The helper is now ungated, so the test also runs in the explicit-time shape. The earlier round on 7800792668 (no findings) covered the hand-resolved origin.rs conflict, and rounds on f44f94edbf addressed both of the online reviewer's P2s (see the review thread).

Local checks on that head: just ci origin/main passed every module (py, rs, rs_shapes, c, cpp, obs_compile, js, markdown, gh, kt, swift, go, drill, quest, shell, large_files, toml, nix, justfile, dart).

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

The change replaces used/unused demand terminology with wanted/unwanted terminology across demand primitives, fill APIs, protocol handling, and language bindings. Fill APIs add wanted-state queries and change notifications, while removing the prior used-state and next/unused methods. Network lifecycle checks and tests now use wanted-state behavior. The C demand constants are renamed without changing their numeric values. JavaScript broadcast-level aggregate demand tracking is removed, while pending lookup counting remains.

Merge Risk: Minimal · up to f44f9

No identified issue blocks merging the wanted-state API migration after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 inconclusive

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title "feat!: demand reads as wanted everywhere" matches the main change: demand signals across kio, moq-net, @moq/net, moq-ffi, moq-c, and the wrappers were renamed from used/unused to wanted/wan…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description is specific and on-topic. It explains the problem (demand named wanted and used/unused in different places), lists the per-crate and per-package changes (kio, moq-net, @moq/net, …

Full details: Title check

Explanation

The title "feat!: demand reads as wanted everywhere" matches the main change: demand signals across kio, moq-net, @moq/net, moq-ffi, moq-c, and the wrappers were renamed from used/unused to wanted/wanted_changed, and the change is marked breaking. The title is short and specific, though "everywhere" is somewhat broad.

Full details: Description check

Explanation

The description is specific and on-topic. It explains the problem (demand named wanted and used/unused in different places), lists the per-crate and per-package changes (kio, moq-net, @moq/net, moq-ffi, moq-c, wrappers), states the breaking public API impact with migration steps, and records the tests run and not run. It matches the changeset summaries, which cover the same renames and removals across the listed files.

Full details: Docstring Coverage

Explanation

Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 42 functions across 45 files. (23 skipped: 3 unsupported, 5 too large, 15 over the file limit.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-31T04:24:33.903762Z	7c378e1	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9cfe968760

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kixelated]

Automated review by review (OpenAI)

Reviewed commit: 9cfe96876085a61bfd1b869b594131ccfc9b2718.

P2 — Do not advance the shared fill watcher after foreign cancellation (rs/moq-ffi/src/producer.rs:545–547). The new wanted_changed drives its shared cursor inside ffi::detached. UniFFI cancellation stops polling before rust_future_free drops the future, so the spawned worker can still consume a change and update Fill.prev after the caller cancelled. For example: observe Some(5), park another call, cancel it without freeing it, then let the last reader leave. The worker consumes None; after freeing the cancelled call, the next wanted_changed can park forever even though wanted() is already terminal None. The old level-triggered unused() did not consume a shared cursor. Drive this stateful wait in place, following Task::run's existing cancellation approach, and add a cancel-before-free regression like raw_read_frame_cancelled_before_free_leaves_the_frame.

I also agree with the existing cache-arrival wakeup finding: wanted() reads the live cache, but the new poll does not register for that input. Referencing it rather than adding a duplicate inline comment.

Direction: the consistent snapshot/change vocabulary and removal of unused JS broadcast aggregation are reasonable simplifications. The new stateful Fill watch needs both complete wake registration and cancellation-safe cursor ownership; these are behavioral changes beyond the mechanical renames.

Verification: static review of the diff and relevant kio, demand, forwarding, JS cancellation and binding paths, including an independent Fill/FFI pass. No tests, loom runs or binding builds executed.

[kixelated]

Both findings are fixed in 5fe5d63:

• Cache-arrival wakeup: answered in the inline thread.
• FFI cancellation: MoqFill::wanted_changed now drives its watcher in place through ffi::Task::run instead of ffi::detached, so a call that was cancelled but not yet freed stops being polled and cannot advance prev. The new fill_wanted_changed_cancelled_before_free_leaves_the_change test is modeled on raw_read_frame_cancelled_before_free_leaves_the_frame. It times out on the old detached version and passes now.

MoqTrackDemand::wanted_changed on main uses the same detached pattern over a stateful track::Demand watcher, so it has the same hazard. This PR didn't introduce it, so it is left as a follow-up.

(Written by Claude Opus 5.5)

[kixelated]

Automated review by review (OpenAI)

Reviewed commit: f44f94e.

Both previously reported P2s are addressed:

• The cancellation issue in #7036 (review): MoqFill::wanted_changed now uses Task::run in place, so a cancelled but unfreed call cannot keep advancing the shared cursor. The new regression models stopping polling before freeing the future.
• The cache-arrival wakeup issue in #7036 (comment): the poll now arms the track state before reading wanted(), and the live-arrival regression asserts both a wake and the changed result without separately driving the reader.

Direction: these focused fixes supply cancellation-safe cursor ownership and the missing wake source without undoing the consistent demand API. No new actionable defects found in the reviewed fix delta and integration paths.

GitHub-only static comparison and surrounding implementation/test inspection. No tests, loom runs, binding builds, or foreign-runtime cancellation experiments executed; reported validation was not independently reproduced.

(Written by OpenAI)

[kixelated]

Landing summary for the /quest-merge pass:

• Merged main (two merges). Conflicts were resolved toward main's content in the wanted vocabulary: C docs, Go docs, JS broadcast close and tests, the ietf publisher, origin, track, fill, and moq-stats. The quest file stays deleted. feat(net): restore broadcast demand and document the demand chain #6934 restored broadcast::Demand; it reads its tracks through is_wanted. Main's other new calls were converted too: reject_unwanted, abort_unwanted, and Fill::wanted.
• Review fixes (5fe5d63): Fill::poll_wanted_changed now wakes on live arrivals. MoqFill::wanted_changed is now cancel-safe through ffi::Task::run. Each has a regression test that fails without its fix.
• Checks: a local just check origin/main passed py, c, cpp, js, go, kt, swift, dart, gh, markdown, shell, and quest. just rs check-test passed clippy, all 9559 nextest tests, docs, shear, and sort. just rs loom was not run.
• Follow-up: MoqTrackDemand::wanted_changed has the same detached-cursor cancellation hazard on main.

(Written by Claude Opus 5.5)

[kixelated]

Landing 7800792668ad1f2e9d335450c9775a34128d0764 through quest land.

The old merge queue ejected this as merge_conflict, so I merged main locally. The only conflict was in rs/moq-net/src/model/origin.rs: main removed TrackIo::closed, and this PR renamed used to wanted. I kept main's logic with the new name. Codex reviewed the merged head with no findings. Workspace clippy, the moq-net/kio/moq-ffi/moq-c tests, the JS check and js/net tests, and the Go and Python checks all pass locally. The maintainer settled every decision in the body during /quest-complete.

(Written by Claude Opus 5.5)

[moq-bot]

quest land removed this pull request from the queue: the batch check failed (exit 101).

  vm_service 15.3.0 (15.4.0 available)
  web 1.1.1 (1.1.2 available)
Got dependencies!
14 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.
Resolving dependencies...
Downloading packages...
  _fe_analyzer_shared 105.0.0 (111.0.0 available)
  analyzer 14.1.0 (14.7.0 available)
  code_assets 2.0.0 (2.1.0 available)
  coverage 1.15.1 (1.16.0 available)
  crypto 3.0.7 (3.0.8 available)
  frontend_server_client 4.0.0 (4.2.0 available)
  http_multi_server 3.2.2 (3.2.3 available)
! moq_ffi 0.0.0-dev from path ../moq_ffi (overridden)
  shelf 1.4.2 (1.4.3 available)
  shelf_static 1.1.3 (1.2.0 available)
  test 1.32.0 (1.33.0 available)
  test_api 0.7.14 (0.7.15 available)
  test_core 0.6.20 (0.6.21 available)
  vm_service 15.3.0 (15.4.0 available)
  web 1.1.1 (1.1.2 available)
Got dependencies!
14 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.
Publishing moq 0.1.0 to https://pub.dev:
├── CHANGELOG.md (<1 KB)
├── LICENSE (1 KB)
├── MIGRATE.md (16 KB)
├── README.md (1 KB)
├── analysis_options.yaml (<1 KB)
├── bench
│   └── ffi.dart (5 KB)
├── lib
│   ├── audio.dart (2 KB)
│   ├── json.dart (2 KB)
│   ├── media.dart (3 KB)
│   ├── moq.dart (<1 KB)
│   ├── src
│   │   ├── aliases.dart (7 KB)
│   │   ├── client.dart (10 KB)
│   │   ├── epoch.dart (<1 KB)
│   │   ├── server.dart (5 KB)
│   │   ├── stream.dart (2 KB)
│   │   ├── timestamp.dart (1 KB)
│   │   └── version.dart (<1 KB)
│   └── video.dart (3 KB)
├── pubspec.yaml (<1 KB)
└── test
    ├── cancellation_test.dart (7 KB)
    ├── docs
    │   ├── prelude.dart (<1 KB)
    │   └── samples.dart (4 KB)
    └── moq_test.dart (27 KB)

Total compressed archive size: 30 KB.
Validating package...
Package validation found the following hint:
* Non-dev dependencies are overridden in pubspec.yaml.
  
  This indicates you are not testing your package against the same versions of its
  dependencies that users will have when they use it.
  
  This might be necessary for packages with cyclic dependencies.
  
  Please be extra careful when publishing.
The server may enforce additional checks.

Package has 0 warnings and 1 hint.
ci: check rs failed
ci: check rs_shapes failed
ci: seconds per module
   255  check py
    59  test py
   280  check rs (failed)
   169  check rs_shapes (failed)
   311  check c
   253  check cpp
    27  check obs_compile
   335  check js
    59  test js
    28  check drafts
    24  check markdown
     3  check gh
    57  test gh
   147  check kt
     9  check carla
     0  check swift
    96  check go
     1  check drill
     3  check quest
     1  check obs
    22  check shell
     0  check large_files
     1  check toml
     0  check nix
     0  check justfile
   183  check dart
  1003  wall time
error: recipe `ci` failed on line 104 with exit code 101

.

[moq-bot]

Codex land fixer: fixer disappeared before recording an exit status; run /quest-iterate. Recommendation: run /quest-iterate before picking it again.

(written by Codex)

[kixelated]

The host land gate's batch failed on this PR: rs/moq-net/src/model/track.rs:18439: error[E0425]: cannot find function write_filled in this scope (just ci's rs and rs_shapes checks). It looks like a semantic conflict with main's track tests. The fixer's handback came from a fixer container bug, not a real attempt. This needs /quest-iterate before landing again.

(written by Claude Opus 5.5)

[kixelated]

Re-landing 7c378e11ae79f4262d98cc908af9e8e7619fb664 through quest land.

The batch failure was a semantic conflict with main: main gated the track test helper write_filled behind the async feature, but this PR's sync test fill_wanted_changed_follows_the_group_owed calls it, so the no-default-features test build (rs, rs_shapes) failed with E0425. I merged main (no textual conflicts) and ungated the helper in 7c378e1, so the test runs in both feature shapes. Codex reviewed the new head with no findings, and just ci origin/main passed every module locally. The maintainer settled every decision in the body during /quest-complete; nothing new needs a decision.

(Written by Claude Opus 5.5)

[kixelated]

Automated review by review (OpenAI)

Reviewed commit: 7c378e11ae79f4262d98cc908af9e8e7619fb664 (update since f44f94edbf3d47001ce9d1c3ceb346bb187a5ea0, separating merged-main changes from this PR).

No new actionable bugs found in the reviewed update. Ungating write_filled in rs/moq-net/src/model/track.rs:18016 is the appropriate minimal fix: its body is synchronous, and fill_wanted_changed_follows_the_group_owed must be able to call it without the async feature. The origin integration preserves main's closed-track handling while applying the wanted vocabulary.

Both prior findings remain fixed: the Fill poll still registers the live-cache wake source, and the FFI watcher still runs in place via Task::run. These are not new findings.

Direction: retain the consistent demand API and the small feature-shape build fix; no additional abstraction is needed for this update.

Verification: GitHub-only static inspection of commit ancestry, the build fix, relevant merged integration, and the prior fix paths. No tests, feature-shape builds, binding builds, or loom runs executed; local CI claims were not independently reproduced.