diff --git a/AGENTS.md b/AGENTS.md index 2ae13a13a85..8c36ca47a79 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. Tests must be worth their weight long-term: cover edge cases, not old bugs or trivial values. - 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. - Every change needs a consumer that uses it now and is worth its cost; name it in the PR. - 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 fdd92a46678..ba72560bc07 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 PR whose diff is only quest files, tests, or CI config goes to the front, since other work builds on it: `gh pr merge` has no flag for this, so use the `enqueuePullRequest` GraphQL mutation with `jump: true`. @@ -64,15 +67,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..39786d01644 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: +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. - `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..1b00fcc5dbc 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. 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 - 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.