From 39861fd7c8434365ff2bc2b2070c7932a716b6d6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 10:26:25 -0700 Subject: [PATCH 1/3] docs(agents): steer by the corrections agents keep needing A month of session transcripts showed the same steering again and again. Promote the recurring design principles into the instruction files, fix the lines that pulled agents the wrong way, and trim stale, duplicated, or tooling-enforced text. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 24 ++++++++++-------------- CONTRIBUTING.md | 20 +++++++++----------- drafts/AGENTS.md | 3 +-- js/AGENTS.md | 2 +- py/AGENTS.md | 1 - rs/AGENTS.md | 14 +++++++------- rs/moq-ffi/AGENTS.md | 9 --------- rs/moq-mux/AGENTS.md | 6 +----- rs/moq-net/AGENTS.md | 7 +++---- rs/moq-relay/AGENTS.md | 9 +++------ test/smoke/AGENTS.md | 3 +-- 11 files changed, 36 insertions(+), 62 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 78e94587d80..b32515721f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,26 +13,25 @@ This file is split into nested `AGENTS.md` files based on the language/situation # Required - Pull the latest origin changes before working. -- Dig into the root cause and fix it at the source. Never work around a fixable bug with a retry, sleep, or timeout. +- Dig into the root cause and fix it at the source. Never work around a fixable bug with a retry, sleep, or timeout, nor pass a flaky test by loosening its assertion or disabling production behavior. - Fail loud and early. Error on unsupported or malformed input rather than warn and continue: supported or refused. -- Treat anything received over the network as untrusted. Ask how a hostile peer could abuse it, such as memory, CPU, or state it makes the other side hold, and bound that cost by design. +- Treat anything received over the network as untrusted. Ask how a hostile peer could abuse it, such as memory, CPU, or state it makes the other side hold, and bound that cost by design (backpressure, flow control, ownership), never with a constant whose only effect is a runtime refusal. A peer must never crash the process, reach another tenant's data, or receive a credential it was not issued. - Reproduce bugs before fixing them. Land each fix with a regression test that fails without it, when one is easy. - Unit tests mock time instead of depending on wall-clock timing or sleeps. - Impair a network with bufferbloat (a rate limit below the media bitrate, behind a deep but finite queue), whose overflow drops packets too. Random loss may prove correctness, such as retransmits happening, but never gates acceptance or performance. -- Keep the PR focused. No unrelated refactors, formatting churn, or drive-by changes; split when in doubt. +- Keep the PR to one problem: no unrelated refactors, formatting churn, or drive-by changes. Fix every instance of that problem and the gaps it exposes in the same PR. - Refactor aggressively for long-term maintainability, but re-evaluate the direction as you learn. - Land the ideal implementation now rather than a partial one plus follow-ups; split off only work that is independently landable. If the ideal is out of reach, propose a course change, even abandoning the PR. - Be adversarial: attack your own approach, reports, reviews, and other PRs as hard as anyone else's, and argue for the best approach over the first one that works. -- When a decision is the maintainer's (API shape, naming, scope), ask with 2-3 options and a recommendation. -- All tests need to be wired into CI, at least a nightly. -- Never edit an `AGENTS.md`, `CONTRIBUTING.md`, or skill without being prompted, and read `PROMPTING.md` first. +- When a decision is the maintainer's (API shape, naming, scope) or you are unsure, ask with an interactive prompt of 2-3 options and a recommendation. +- Every test runs in CI, at least nightly. The merge gate holds only fast, high-signal tests: make a slow test fast at its source, or move it to nightly. +- Never add or change a rule in an `AGENTS.md`, `CONTRIBUTING.md`, or skill without being prompted, and read `PROMPTING.md` first. A fact your own change made stale is fixed inline like any other doc. - No em dashes. - Match the existing conventions, patterns, and naming when possible. - Fix any outdated docs and comments inline; don't add a separate PR for it. - Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. -- Any AI comments may be challenged, and not confused with human maintainers. +- AI comments carry no maintainer authority and may be challenged. - This repo is public: never mention customers, partners, or prospects (names, volumes, terms) or link to private repos. Justify work on its merits. -- Prompt the user to decide when unsure, but always provide recommendations. # Guidelines @@ -44,11 +43,9 @@ This file is split into nested `AGENTS.md` files based on the language/situation - Inline simple helpers. - Question whether functionality is needed at all before adding it. - Deleting code is better than adding code. -- Suggest follow up sessions and quests when finished, interactively prompting the user. +- Record out-of-scope follow-ups as quests, never GitHub issues, and prompt the user about starting them when finished. - Prefer the net simpler result: reuse what exists, or narrow the scope, when that makes the implementation or API simpler overall. Say what was dropped. - Say it once, in the fewest words that hold up. -- Prefer a quest over a GitHub issue for work needing durable scope. -- Use interactive prompts when possible. - Try to do stuff asynchronously. ex. ask about follow-ups while tests run. - Try to recognize when you're stuck, or making minimal progress, and stop early. - If the core problem is addressed, ship it instead of spinning your wheels on meaningless revisions. @@ -74,7 +71,7 @@ A bad shape costs a breaking change in every language, and the surface is huge. - Short names under a module namespace (`encode::Config`, not `EncoderConfig`). Mirror names across Rust, JS, and the bindings. - Document every exported symbol in one plain line, the way you'd say it out loud. - Prefer refactoring and simplification; many APIs have not been published yet. -- The `moq-net` API and moq-lite take priority over moq-transport. Map moq-transport onto them, not the reverse, and skip any of its features or MUSTs that add cost without a real behavioral benefit. +- The `moq-net` API and moq-lite take priority over moq-transport, in design and in work order. Map moq-transport onto them, not the reverse, and skip any of its features or MUSTs that add cost without a real behavioral benefit. A spec rule or a "spec violation" finding never decides a design on its own; argue on behavior. MoQ is split into many layers as part of the public API. The boundary between packages is extremely important to keep things modular and reusable. @@ -84,8 +81,8 @@ The boundary between packages is extremely important to keep things modular and PRs target `main`, the trunk, where breaking API changes are allowed. `release` is what ships; touch it only to cut a release or backport a fix (see `CONTRIBUTING.md`). Wire changes should be backwards compatible for any *published* drafts/versions. +An unpublished `-wip` version changes freely, so never defer a better wire design to keep it compatible. -Before starting, `git fetch origin` and set the upstream to the base branch. Pass PR bodies to `gh` on stdin (`--body-file -`); never write to a directory other agents share. Keep scratch files in your worktree's `.scratch/`, not `target/`: build output may live outside the checkout and gets wiped. @@ -116,7 +113,6 @@ The `quest` binary comes from the kixelated/quest flake input and serves the que | `rs/moq-gst` | `doc/bin/gstreamer.md` | | `rs/moq-c` C ABI (`moq.h`) | `doc/lib/c` | | `js/{watch,publish}` UI/API | `demo/web` if it consumes the API | -| a kramdown-rfc construct new to `drafts/` | `doc/.vitepress/drafts.ts`, which translates the drafts into `/draft/` site pages | Any wire-format change updates its matching IETF draft in the same PR, including framing, message fields, enum values, and version negotiation. Use the feature-specific draft for extensions and validate with `just drafts check`. See `drafts/AGENTS.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85f2c7b6514..a575cdbb798 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,17 +20,20 @@ Have at least these sections: - **Follow-ups**: any issues encountered or quests created. When pushing additional commits to an existing PR, update the title and description if needed. -When taking over someone else's PR, push commits on top of theirs so they keep credit. +When taking over someone else's PR, push commits on top of theirs so they keep credit; if their fork blocks maintainer edits, open a new PR carrying their commits. +Never rebase or force-push a pushed branch; merge the base branch in instead. +Check that the PR is still open before pushing to its branch, since a push after merge recreates the deleted branch. -Create a draft PR. -Run `just ci` before switching it to "Ready for review" and before every push. +Open a draft PR while working, without asking once the scope is settled. +Run `just ci` before every push, and mark the PR ready yourself when the work is done. +Keep it a draft only while its description lists a decision the maintainer still owns. Fix any merge conflicts and failing CI checks. # Merge queue PRs into `main` get no cloud CI: they report **Check** as skipped, and `just ci` runs the same gate locally. The merge queue runs Check on the PR combined with the latest `main` and the PRs queued ahead of it. -Enqueue with `gh pr merge ` once the review is clean. +Enqueue with `gh pr merge ` once the review is clean and the maintainer has approved merging that PR, by number or through a standing go-ahead that covers it. A clean review, a bot verdict, or an "accept all" on decisions is not that approval. Both select only what the diff touches, so a break can reach `main`; `just gate` runs the full suite, and it, the feature matrix, optimized binding builds, macOS, Windows, and the other optional workflows run nightly on `main` and on PRs into `release`. A dequeued PR means the combination failed checks, timed out, or no longer meets the ruleset. @@ -63,15 +66,10 @@ Skipped or rate-limited reviews do not count. For a fork with no automatic non-Grok review, ask the maintainer to arrange one. Merge only when that review has no findings, or every finding is fixed or replied to. -# CI - -Workflow steps run `just` recipes, never a script path; `just gh check` enforces it. - # Follow-ups -If you encounter issues, or findings that are out of scope, create follow-up quests. -Focus on the core problem, offering a potential solution only if its obvious. -For non-trivial tasks, file an issue or offer to run `/quest-plan`. +Record out-of-scope findings as follow-up quests with `/quest-plan`, not GitHub issues, which are for outside contributors. +Focus on the core problem, offering a potential solution only if it's obvious. # Forks diff --git a/drafts/AGENTS.md b/drafts/AGENTS.md index d1c582e50c3..df77a46b97c 100644 --- a/drafts/AGENTS.md +++ b/drafts/AGENTS.md @@ -9,7 +9,7 @@ just drafts check # every draft still parses just drafts publish # submit to the datatracker ``` -`publish` POSTs to the datatracker; the version is final only after clicking the emailed confirmation link. For a new draft, set "Replaces" on the confirmation page. The first build needs network access to fetch bibxml into `.refcache/`. +`README.md` covers publishing. The first build needs network access to fetch bibxml into `.refcache/`. # Conventions @@ -17,7 +17,6 @@ just drafts publish # submit to the datatracker - `docname` ends in `-latest`; `publish` rewrites it. Never hardcode a version in the source. - A wire-format or semantic change adds a bullet to the draft's changelog appendix under the in-progress version. List what changed, not why. - Don't add a section for an unpublished next version; edit the in-progress one. -- `remark` skips these files; a successful `kramdown-rfc` run is the syntax check. - Follow IETF contribution rules (BCP 78/79), see `CONTRIBUTING.md` here. # Documentation site diff --git a/js/AGENTS.md b/js/AGENTS.md index f038f0c52d7..7e4c60a154c 100644 --- a/js/AGENTS.md +++ b/js/AGENTS.md @@ -2,7 +2,7 @@ The `/js` TypeScript workspace. Extends the root `AGENTS.md`. # Packages -Bun workspaces listed in the repo-root `package.json`, published as `@moq/` after the root list. Run recipes via `just js `. Beyond that list: `@moq/signals` is the reactive core every package uses, `@moq/wasm` wraps `rs/moq-wasm`, and `@moq/boy` is the only Solid/`.tsx` package. +Bun workspaces listed in the repo-root `package.json`, published as `@moq/`. Run recipes via `just js `. `@moq/signals` is the reactive core every package uses, `@moq/wasm` wraps `rs/moq-wasm`, and `@moq/boy` is the only Solid/`.tsx` package. Entrypoints re-export deps under namespaces (`Net`, `Signals`, `Hang`). Only re-export what is part of the public API. diff --git a/py/AGENTS.md b/py/AGENTS.md index fabb85cc18a..76699761f4d 100644 --- a/py/AGENTS.md +++ b/py/AGENTS.md @@ -15,4 +15,3 @@ The `/py` uv workspace. Extends the root `AGENTS.md` and `rs/moq-ffi/AGENTS.md`. - Keyword-only args with defaults (`*, ...`) instead of an options object; that is how Python extends additively. - The package ships `py.typed`: types and docstrings are the API, so document public symbols. - `just py ` for everything. Tests live under each package's `tests/`. -- Releases: `moq-ffi` tracks `rs/moq-ffi` and publishes on `moq-ffi-v*` tags; `moq-rs` is versioned by hand and publishes on merge to `release` when the version isn't on PyPI yet. diff --git a/rs/AGENTS.md b/rs/AGENTS.md index f93c7f8aa10..3be48de9bde 100644 --- a/rs/AGENTS.md +++ b/rs/AGENTS.md @@ -2,17 +2,17 @@ The `/rs` Cargo workspace. Extends the root `AGENTS.md`. # Crates -One crate per component from the root list, named `moq-` (`hang` is the exception). Keep them modular; a crate does one thing. Beyond that list: +Crates are named `moq-` (`hang` is the exception). Keep them modular; a crate does one thing. The ones whose role isn't obvious from the name: - `kio`: "easy async" primitives everything else polls through. - `moq-tokio`: configures the QUIC backends (`moq-quic`, our quinn fork, and Iroh) and the fallback transports for native binaries, on tokio. `moq-sock` holds the socket plumbing it shares with `moq-uring`, the experimental thread-per-core io\_uring runtime. - `moq-cli` builds the `moq` binary and owns the CLI surface for the gateway crates. Binaries never carry a `-cli` suffix. -`moq-net`, `moq-mux`, `moq-relay` (including the config conventions every binary shares), and `moq-ffi` have their own `AGENTS.md`. +`moq-net`, `moq-mux`, `moq-relay` (including its layered config), and `moq-ffi` have their own `AGENTS.md`. # Producer / Consumer -Most crates use a split-handle pattern: a `Producer` writes, any number of `Consumer`s read, state is shared via `kio`. Handles are refcounted: clones share state, the last drop closes cleanly, `abort(err)` closes with an error. A parked clone that keeps something alive is a bug in the holder. A track, group, or frame consumer seeing `Error::Dropped` is a bug too: its producer went away unfinished without calling `abort` with a specific error, so find that path and abort with the real cause. Lifecycle watchers like `broadcast::Demand` return `Dropped` after `close()` by design. +Most crates use a split-handle pattern: a `Producer` writes, any number of `Consumer`s read, state is shared via `kio`. Handles are refcounted: clones share state, the last drop closes cleanly, `abort(err)` closes with an error. A parked clone that keeps something alive is a bug in the holder, and a consumer never keeps its producer or parent alive. A track, group, or frame consumer seeing `Error::Dropped` is a bug too: its producer went away unfinished without calling `abort` with a specific error, so find that path and abort with the real cause. Lifecycle watchers like `broadcast::Demand` return `Dropped` after `close()` by design. # Async / poll @@ -31,22 +31,22 @@ Prefer poll. New logic is a `poll_*` with an `async` helper, not the other way a # Conventions - `thiserror` with `#[from]` for libraries; `anyhow` with `.context("...")` for binaries. -- Public error enums are always `#[non_exhaustive]`. Don't re-export a third-party error type unless the crate is a thin wrapper that re-exports the dependency. +- Don't re-export a third-party error type unless the crate is a thin wrapper that re-exports the dependency. - Make terminal operations consume `self` (`fn close(self)`). Rely on `Drop` instead of a `close` the user can forget. - Take `&[T]` / `&str` for data the callee only reads; return owned values. Take `Vec` only when storing it. - Typed units only: `std::time::Duration`, `moq_net::Timestamp`, never `f64` seconds or bare `u64` millis. `serde_as` converts at the edge. +- Flushing, cutting, and expiry advance on max(wall clock, pts) through a timer: peer timestamps are untrusted, and a sparse track may never send another frame. - `if let` / `let else` over a `match` whose only job is to bind. Keep `match` when both arms do work. - Derive `Serialize`/`Deserialize`; a hand-written impl is a second copy of the wire shape. Reach for `serde_with` for what the derive can't express. - Public modules with short names: `broadcast::Consumer`, not `BroadcastConsumer`. Keep `mod encoder` private and re-export flat as `encode::Encoder`. -- Workspace members and shared dependency versions live in the root `Cargo.toml`; crates reference deps via `{ workspace = true }`, except internal dev-dependencies, which are path-only so releases publish (`_publish-test` enforces it). +- Workspace members and shared dependency versions live in the root `Cargo.toml`; crates reference deps via `{ workspace = true }`, except internal dev-dependencies, which are path-only so releases publish. - Use newtypes and enums instead of untyped strings. -- Have the language make misuse impossible: terminal operations consume `self`, cleanup in `Drop`, etc. # Semver - Don't add `#[non_exhaustive]` by default. It earns its keep on error enums, enums that will gain variants, and `Config`-style structs with `pub` fields plus a `Default`/constructor. Builders with private fields don't need it. - Append new variants to the end of a public fieldless enum with implicit discriminants; inserting reorders `as` values. -- A deprecated item gets `#[doc(hidden)]` and `#[deprecated(note)]`. A renamed flag or env var stays as a hidden arg with its original `env`, reported by the section's `deprecated()` into `moq_tokio::cli::Deprecated`; callers must reject startup when the collection is non-empty and name the replacement rather than honor the old spelling. Never advertise the dead name in docs or `--help`. +- A renamed flag or env var stays as a hidden arg with its original `env`, reported by the section's `deprecated()` into `moq_tokio::cli::Deprecated`; callers must reject startup when the collection is non-empty and name the replacement rather than honor the old spelling. Never advertise the dead name in docs or `--help`. # Testing diff --git a/rs/moq-ffi/AGENTS.md b/rs/moq-ffi/AGENTS.md index 647be91bc56..037f97df014 100644 --- a/rs/moq-ffi/AGENTS.md +++ b/rs/moq-ffi/AGENTS.md @@ -4,15 +4,6 @@ The UniFFI core every non-Rust binding is generated from. Proc-macro based (`#[u Rust owns capture, codecs, and rendering. Bridge native surfaces as opaque handles (`CVPixelBuffer` on iOS, Android `HardwareBuffer` or `Surface`). Do not add a Swift or Kotlin codec, capture, or render stack beside the Rust one. The default `audio` and `video` features are how the bindings carry those codecs. -# Changing the surface - -Mirror every change in the same PR: - -- `rs/moq-c`: the C staticlib (`cbindgen` emits `moq.h`). If the C ABI moved, also `cpp/obs`. -- Hand-written wrappers: `py/moq-rs`, `go/wrapper`, `dart/moq`, `swift/Sources`, `kt/moq`. The `go/ffi` and `dart/moq_ffi` layers regenerate, but a new method still needs its ergonomic wrapper. -- Docs under `doc/lib/{py,go,dart,swift,kt,c}`. -- Then `just test interop --all` for the interop matrix. - # Layers UniFFI allows one namespace per crate, so moq-ffi names by type (`MoqJsonSnapshotProducer`) and gives each layer above moq-net a constructor over the handle it wraps, not a verb on `MoqBroadcastProducer`. A constructor that takes over a handle closes it. diff --git a/rs/moq-mux/AGENTS.md b/rs/moq-mux/AGENTS.md index 604b8bff6cc..89d601d28c3 100644 --- a/rs/moq-mux/AGENTS.md +++ b/rs/moq-mux/AGENTS.md @@ -4,11 +4,7 @@ The transmuxer: file/stream containers (`container/`) and codec parsers (`codec/ - The keyframe bit drives grouping. Only the first frame of a group is a keyframe; for audio, mark one frame per intended group, not every frame, or each frame opens its own QUIC stream. `cut` closes a group early and the next write must be a keyframe. - Frame durations are backfilled from the next frame in decode order, never across a discontinuity; a backwards gap (B-frame reordering) stays unset. Frames that arrive with a duration keep it. -- hang frames carry a timestamp normalized to microseconds (`hang::container::TIMESCALE`). `moq_net::track::Info::default()` is milliseconds, so pin the track with `with_timescale` when creating it. +- hang frames carry a timestamp normalized to microseconds (`hang::container::TIMESCALE`). Create media tracks with `hang::container::track_info`; a default `moq_net::track::Info` is untimed and refuses timestamped frames. - Reject an unsupported codec or container with a typed `Error` rather than warn and drop. - An fMP4 fragment's `tfdt` must advance past the previous fragment on that track. ffmpeg's `frag_every_frame` repeats one when it interleaves audio and video, so the demo recipes use `-frag_duration`. - Catalog fields that decide decoder configuration (codec, dimensions, description) are effectively immutable for a rendition; bitrate and similar hints are maximums. - -# Cross-language - -`js/hang` mirrors the catalog and container; `js/watch` and `js/publish` are the browser equivalents of the codec paths. A catalog or container change lands in both languages and in `drafts/draft-lcurley-moq-hang.md` in the same PR. diff --git a/rs/moq-net/AGENTS.md b/rs/moq-net/AGENTS.md index a353bc28683..5bc7bfc202d 100644 --- a/rs/moq-net/AGENTS.md +++ b/rs/moq-net/AGENTS.md @@ -2,18 +2,17 @@ The wire layer. Generic over the transport and media-agnostic: the relay never i # Rules -- Any wire change updates the matching draft in `drafts/` and `js/net` in the same PR: `draft-lcurley-moq-lite.md` for session/SETUP/framing, the per-feature draft otherwise. New capabilities are additive SETUP extensions; receivers ignore unknown parameters. +- New capabilities are additive SETUP extensions; receivers ignore unknown parameters. - Closes never cascade. Aborting a group must not tear down its track, broadcast, or siblings. -- A route change is never fatal on its own. A subscription stays on the instance it started on while that instance still has a route, even after a newer route wins the path. Once none is left (e.g. the publisher's session closed), it ends with an error, never a clean end, and the app requests the path again. Never stitch it onto another instance. A clean end means only a deliberate publisher finish or the local session closing. See "Publisher epochs" in `doc/concept/moq-lite.md`. +- A route change is never fatal on its own. A subscription stays on the instance it started on while that instance still has a route, even after a newer route wins the path. Once none is left (e.g. the publisher's session closed), it ends with an error, never a clean end, and the app requests the path again. Never stitch it onto another instance. A clean end means only a deliberate publisher finish or the local session closing. Players start, stop, and restart on announcements, never on request errors. See "Publisher epochs" in `doc/concept/moq-lite.md`. - The cache is a performance optimization. A relay behaves the same warm or cold: report upstream state (e.g. the largest group), not what the cache happens to hold. - Sessions are caller-driven: `connect`/`accept` return `(Session, Driver)`. The `Driver` holds no `Session` clone, so spawning it never keeps the session alive. - Version matching: outside the crate branch on `is_lite()` / `is_ietf()` and `alpn()`; inside it match the draft enums. List old drafts explicitly and let the newest behavior be the fallthrough so future drafts fall forward. - Interop rule of thumb: respond to every feature a peer may use, but don't request new ones. Never emit or accept partial groups; a group starts at frame 0. Exception: moq-transport passthrough forwards a mid-group start as the publisher sent it. -- `Timestamp` is an instant with a scale, not a scalar. `checked_add`/`checked_sub` error on mismatched scales; `.convert()` first. `ZERO` is second-scale, so seed a max with `Option`, not `ZERO`. +- `Timestamp` is an instant with a scale, not a scalar. `checked_add`/`checked_sub` error on mismatched scales; `.convert()` first. `ZERO` is second-scale, so seed a max with `Option`, not `ZERO`. A track's timestamps never rewind; spend nothing on staying correct after one. # Testing - Tests never use tokio or the wall clock. Prefer a plain `#[test]` that polls with explicit instants; async bodies use `#[moq_clock::test]`, whose simulated time jumps only when every task is stalled. tokio is for the benches. - `just rs fuzz ` (one per file in `fuzz/fuzz_targets/`) needs nightly. The target bodies live in `src/fuzz.rs`; `fuzz/regressions//` replays under `just check`, so commit every crash input there. - `just rs loom` model-checks the concurrent handoffs. A hang is a lost wakeup, not a flake. -- `just test interop --all` runs the cross-language interop matrix after a wire change. diff --git a/rs/moq-relay/AGENTS.md b/rs/moq-relay/AGENTS.md index 9a3d5b41b19..d3342ccc665 100644 --- a/rs/moq-relay/AGENTS.md +++ b/rs/moq-relay/AGENTS.md @@ -1,16 +1,13 @@ The clusterable, media-agnostic relay. It routes by broadcast path and never inspects payloads; anything media-aware belongs in a gateway or `moq-mux`. +A relay never blocks an answer on another node finishing something (a replay, a catch-up, a complete announce set); it reports what it knows now and accepts the rare race. + # Config Config structs are Usage `Args` that also load from TOML, with the `moq-tokio` configs flattened in. -- Merge is CLI > env > file > defaults, declared in `moq_tokio::cli::merge`. Presence comes from the source (`CliLayer` / `EnvLayer` / the TOML document), never from whether a standing value looks empty. A new merged flag needs `setting = "dotted.key"` on the `Args` field and a matching `usage_rs::Config` field in `settings.rs`; `Registry::drift` is the test they stay in step. -- Relay behavior and config changes update `doc/bin/relay/`. Stats track names and frame shapes are documented in `doc/bin/relay/config.md`. +- Merge is CLI > env > file > defaults, declared in `moq_tokio::cli::Merge`. Presence comes from the source (`CliLayer` / `EnvLayer` / the TOML document), never from whether a standing value looks empty. A new merged flag needs `setting = "dotted.key"` on the `Args` field and a matching `usage_rs::Config` field in `settings.rs`; `Registry::drift` is the test they stay in step. # Testing `tests/drills.rs` disrupts a live session through a real relay over real QUIC. Each drill records that its fault activated and requires a terminal result rather than a clean finish or a hang. `test/drill/README.md` covers the recipe and the sensitivity proof; add a mutation there for any recovery behavior a new drill grades. - -# Semver - -Relay patch bumps only cover breaking config changes; release-plz owns every version field. diff --git a/test/smoke/AGENTS.md b/test/smoke/AGENTS.md index c1149ddf78b..6ac0d0b3203 100644 --- a/test/smoke/AGENTS.md +++ b/test/smoke/AGENTS.md @@ -4,8 +4,7 @@ Cross-language interop smoke for the published MoQ packages. # Required - Install the published artifact each cell claims to test. -- MoQ package versions stay at latest: `@moq/*` on the `latest` tag, PyPI `moq-rs`, `moq.dev/moq`, `moqdev/*` images, and GitHub release tarballs. `cloudflare.sh` and `moxygen.sh` build from unpinned Git HEAD. -- No package lock files under `test/smoke/` (`go.sum`, `bun.lock`, `Cargo.lock`, `uv.lock`, and the rest of the list in `.gitignore`). `flake.lock` pins the dev toolchain. The moq flake is not a flake input; `just nix-channel` builds `github:moq-dev/moq#moq-relay` and `#moq` with `--refresh`. +- MoQ packages are tested at latest, with no package lock files here; `freshness.sh` enforces both. `cloudflare.sh` and `moxygen.sh` build from unpinned Git HEAD, and `just nix-channel` builds the moq flake with `--refresh` rather than locking it as an input. - npm `playwright` is the one version pin, and it matches the flake's `PLAYWRIGHT_VERSION`. Bump the toolchain with `nix flake update` and the pin together. - `moq-relay` and `moq` come from a channel (PATH, `RELAY_BIN`/`MOQ_BIN`, `just nix-channel`, or `clients/docker`). The harness leaves installing them to that channel. - A red cell is the result. `mark_broken` drops that package's cells and lets the rest of the matrix run. Retries belong on transient registry and release downloads. A client that failed to exchange media gets no retry, no longer timeout, and no skip. From 652b63392be476a3774a56b6e286048d127c6a43 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 16:03:40 -0700 Subject: [PATCH 2/3] docs(agents): scope the no-rewind rule to what a peer can send A local write refuses a rewind, but some received tracks skip the check, so a peer's rewind must stay bounded even though results may be wrong. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-net/AGENTS.md b/rs/moq-net/AGENTS.md index 5bc7bfc202d..1b00fcc5dbc 100644 --- a/rs/moq-net/AGENTS.md +++ b/rs/moq-net/AGENTS.md @@ -9,7 +9,7 @@ The wire layer. Generic over the transport and media-agnostic: the relay never i - Sessions are caller-driven: `connect`/`accept` return `(Session, Driver)`. The `Driver` holds no `Session` clone, so spawning it never keeps the session alive. - Version matching: outside the crate branch on `is_lite()` / `is_ietf()` and `alpn()`; inside it match the draft enums. List old drafts explicitly and let the newest behavior be the fallthrough so future drafts fall forward. - Interop rule of thumb: respond to every feature a peer may use, but don't request new ones. Never emit or accept partial groups; a group starts at frame 0. Exception: moq-transport passthrough forwards a mid-group start as the publisher sent it. -- `Timestamp` is an instant with a scale, not a scalar. `checked_add`/`checked_sub` error on mismatched scales; `.convert()` first. `ZERO` is second-scale, so seed a max with `Option`, not `ZERO`. A track's timestamps never rewind; spend nothing on staying correct after one. +- `Timestamp` is an instant with a scale, not a scalar. `checked_add`/`checked_sub` error on mismatched scales; `.convert()` first. `ZERO` is second-scale, so seed a max with `Option`, not `ZERO`. A track's timestamps never rewind. A local write refuses one, but some received tracks skip that check: a peer's rewind must never panic or cost unbounded work, yet results on that track may be wrong, so spend nothing on staying correct after one. # Testing From c801bbf82e5bfb76d800801399e8995513040396 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 16:14:47 -0700 Subject: [PATCH 3/3] docs(agents): limit the moq- prefix rule to component crates Co-Authored-By: Claude Opus 5.5 --- rs/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/AGENTS.md b/rs/AGENTS.md index 3be48de9bde..39786d01644 100644 --- a/rs/AGENTS.md +++ b/rs/AGENTS.md @@ -2,7 +2,7 @@ The `/rs` Cargo workspace. Extends the root `AGENTS.md`. # Crates -Crates are named `moq-` (`hang` is the exception). Keep them modular; a crate does one thing. The ones whose role isn't obvious from the name: +Component crates are named `moq-` (`hang` is the exception); infrastructure like `kio` is not. Keep them modular; a crate does one thing. The ones whose role isn't obvious from the name: - `kio`: "easy async" primitives everything else polls through. - `moq-tokio`: configures the QUIC backends (`moq-quic`, our quinn fork, and Iroh) and the fallback transports for native binaries, on tokio. `moq-sock` holds the socket plumbing it shares with `moq-uring`, the experimental thread-per-core io\_uring runtime.