From 0eb20b729ac0cf01238c02f99a78ed4385278b0f Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Sat, 4 Jul 2026 01:44:27 +0000 Subject: [PATCH] =?UTF-8?q?docs(reviews/2026-07-03):=20P4=20fix=20?= =?UTF-8?q?=E2=80=94=20sweep=20status=20staleness=20+=20re-aim=20fuzz/READ?= =?UTF-8?q?ME=20(#11)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Aaron D. Lee Co-committed-by: Aaron D. Lee --- README.md | 14 +++++++----- docs/DEVELOPMENT.md | 10 ++++----- docs/QUICKSTART.md | 11 +++++----- fuzz/README.md | 53 ++++++++++++++++++++++++++++++++------------- 4 files changed, 57 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 82bb084..ad708e8 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,12 @@ pip install -r examples/openai_realtime_brain/requirements.txt OPENAI_API_KEY=sk-... python examples/openai_realtime_brain/openai_realtime_brain.py ``` -> **Status:** Slice 1 (WebRTC media loopback) is the active build target. The workspace is -> landing task-by-task on the `slice-1-webrtc-loopback` branch. Design: -> [`docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md`](docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md). +> **Status:** Slices 1–3 (WebRTC media core, WS tap, OpenAI Realtime brain) are merged to +> `main`. Slice 4 (barge-in / VAD-driven playout kill) is the active build target, in flight +> on the `slice-4-dev-a-reflex` + `slice-4-dev-b-tap` branches. Design: +> [`docs/superpowers/specs/2026-07-01-slice-4-barge-in-design.md`](docs/superpowers/specs/2026-07-01-slice-4-barge-in-design.md). > Implementation plan: -> [`docs/superpowers/plans/2026-06-28-slice-1-webrtc-loopback.md`](docs/superpowers/plans/2026-06-28-slice-1-webrtc-loopback.md). +> [`docs/superpowers/plans/2026-07-01-slice-4-barge-in.md`](docs/superpowers/plans/2026-07-01-slice-4-barge-in.md). ## Documentation @@ -155,10 +156,11 @@ exactly as integrators did on top of Asterisk. ## Status -Slice 1 (WebRTC media loopback) implemented; spearhead steps 2–6 pending. The +Slices 1–3 (WebRTC media core, WS tap, OpenAI Realtime brain) are merged to `main`; +spearhead steps 4–6 remain. The [vision revision](docs/superpowers/specs/2026-06-26-vision-revision-design.md) and ADRs define the architecture; the -[slice-1 design](docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md) +[slice-4 design](docs/superpowers/specs/2026-07-01-slice-4-barge-in-design.md) documents the active build. ## First proof (the spearhead) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index db752e8..a0af383 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -3,11 +3,11 @@ The dev loop: how to iterate on the Rust workspace, run tests, and find your way around the codebase. -> **Status:** Slice 1 is the active build target. The workspace is -> landing task-by-task on the `slice-1-webrtc-loopback` branch. Once it -> merges to `main`, everything below applies directly. Until then, -> `git checkout slice-1-webrtc-loopback` to follow along. -> Implementation plan: [`docs/superpowers/plans/2026-06-28-slice-1-webrtc-loopback.md`](superpowers/plans/2026-06-28-slice-1-webrtc-loopback.md). +> **Status:** Slices 1–3 are merged to `main`. Slice 4 (barge-in / VAD-driven playout +> kill) is the active build target, in flight on the `slice-4-dev-a-reflex` + +> `slice-4-dev-b-tap` branches. Everything below applies to the merged code on +> `main`; to follow slice-4 in flight, check out either dev branch. +> Implementation plan: [`docs/superpowers/plans/2026-07-01-slice-4-barge-in.md`](superpowers/plans/2026-07-01-slice-4-barge-in.md). --- diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 223eee9..f866fd2 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -2,11 +2,12 @@ Get Rutster running and hear your own voice echoed back in under 5 minutes. -> **Status:** Slice 1 (WebRTC media loopback) is the active build target. -> If the workspace isn't on `main` yet, check the `slice-1-webrtc-loopback` -> branch — that's where the implementation is landing task-by-task. -> See [`docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md`](superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md) -> for the full design. +> **Status:** Slices 1–3 are merged to `main`. Slice 4 (barge-in / VAD-driven playout +> kill) is the active build target, in flight on the `slice-4-dev-a-reflex` + +> `slice-4-dev-b-tap` branches. This quickstart exercises the slice-1 WebRTC media +> loopback, which remains the simplest end-to-end demo on `main`. See +> [`docs/superpowers/specs/2026-07-01-slice-4-barge-in-design.md`](superpowers/specs/2026-07-01-slice-4-barge-in-design.md) +> for the active build target's design. --- diff --git a/fuzz/README.md b/fuzz/README.md index ef3a0b2..dbf7717 100644 --- a/fuzz/README.md +++ b/fuzz/README.md @@ -1,21 +1,44 @@ # fuzz/ — cargo-fuzz harness directory (placeholder) **Status:** placeholder. Not yet a cargo-fuzz project — just the directory. -Fuzz harnesses land at spearhead step 5 (PSTN trunk) alongside the -SIP/SDP/RTP wire parsers (PORT_PLAN §10 mandates continuous fuzzing of -every wire parser). Slice 1 has no hostile-bytes surface (the browser is -trusted), so no harnesses here yet — the `fuzz/` dir pre-paves the -layout. Populating this directory with a real `cargo-fuzz` project -(`fuzz/Cargo.toml` + `fuzz/fuzz_targets/*.rs`) happens at step 5. -If you're at step 5, replace this README with that structure: +ADR-0007 abolished the first-party SIP parser (the original reason this +directory was pre-paved), so the original `sip_parser` / `sdp_parser` fuzz +targets are gone from the plan. The hostile-byte surfaces that *do* exist +post-0007, and that the harnesses here will eventually target, are: + +- **Tap protocol frames** (`crates/rutster-tap/src/protocol.rs`) — the WS + framing between the core and an external brain. This is hostility surface + #1 today: a brain is an untrusted process and its frames cross the FOB + boundary. Slice-2 ships this surface without a fuzzer; the harness should + land as soon as third-party brains exist (P6 of the 2026-07-03 adversarial + review — the protocol should also carry an auth field by then). +- **RTP packets at the str0m input** (slice-1's `rtc_session.rs` media + ingress) — every byte str0m hands us is potentially hostile before str0m + validates it; fuzz at the str0m-RtcSession boundary, not str0m internally. +- **Opus decoder inputs** (`crates/rutster-media` codec boundary) — a + malicious or malformed RTP payload hits the Opus decoder. Fuzz the + decoded-PCM contract (finite-length, sane amplitude range), not the + decoder internals. +- **Provider media-fork framing** (spearhead step 5, post-ADR-0007) — the + rented transport's media-fork delivers bytes that the CPaaS framed; that + framing is the post-0007 equivalent of the SIP/SDP parser surface. Lands + with step 5. + +Slice 1 says "the browser is trusted" for the WebRTC ingress, which is +correct for the *signaling* surface (str0m validates SDP). But the media +plane accepts RTP from any peer that completed ICE, which makes the +RTP/Opus surfaces above hostile-by-default regardless of signaling trust. + +If you're populating this directory, replace it with: + - `fuzz/Cargo.toml` — cargo-fuzz manifest. -- `fuzz/fuzz_targets/sip_parser.rs` — fuzz the SIP parser. -- `fuzz/fuzz_targets/sdp_parser.rs` — fuzz the SDP parser. -- `fuzz/fuzz_targets/rtp_packet.rs` — fuzz the RTP packet parser. -- CI job running a short fuzz burst on each PR (the cargo-fuzz integration - lands in `.github/workflows/` at that point). +- `fuzz/fuzz_targets/tap_protocol.rs` — fuzz the tap protocol frame decoder. +- `fuzz/fuzz_targets/rtp_packet.rs` — fuzz the str0m-RtcSession RTP input. +- `fuzz/fuzz_targets/opus_payload.rs` — fuzz the Opus→PCM decoder boundary. +- A CI job running a short fuzz burst on each PR. -The hot-path "drop + observe, don't crash" policy (spec §3.8) is what the -future harnesses assert against: throw arbitrary bytes at the parser, -assert it returns an error or drops silently — never panics. +The hot-path "drop + observe, don't crash" policy (ARCHITECTURE.md Media +plane; slice-4 spec §3.6) is what the harnesses assert against: throw +arbitrary bytes at the surface, assert it returns an error or drops +silently — never panics. A dropped packet must not terminate the peer.