alee/rutster
0
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

slice-4 (dev-a): Task 1 — AdvisoryEvent + ReflexMetrics + barge_in_flush trait #7

Merged
alee merged 2 commits from slice-4-dev-a-reflex into main 2026-07-03 03:37:35 +00:00
Conversation 0 Commits 2 Files Changed 3 +146
alee commented 2026-07-02 21:51:40 +00:00
Owner
Copy Link

What lands

Task 1 of the slice-4 plan — the critical-path foundation. Everything else in slice-4 depends on this merging first.

  • Created crates/rutster-media/src/reflex.rs: AdvisoryEvent enum (SpeechStarted/SpeechStopped), ReflexMetrics (4 AtomicU64 counters + new()/snapshot()), ReflexMetricsSnapshot (Debug+PartialEq+Eq). 3 inline tests.
  • Modified crates/rutster-media/src/pcm.rs: added AudioPipe::barge_in_flush(&mut self) default method (delegates to clear_playout_ring) — the kill-now path. EchoAudioPipe inherits the default unchanged.
  • Modified crates/rutster-media/src/lib.rs: pub mod reflex; + re-exports (Reflex intentionally omitted — Task 2 defines it; flagged inline) + //! module-map catalogue entry.

What this proves

The foundational types + trait hook that every later slice-4 task consumes: Task 2 (Reflex<P> state machine), Task 2b (LocalVadReflex<P> primary trigger), Task 3 (the TapAudioPipe::barge_in_flush override), Task 4 (advisory_tx wiring), Tasks 5–7 (composition + dedicated thread). Without Task 1, none of them compile.

Deviation from the verbatim brief (flagged for review)

The brief's verbatim reflex.rs included use tokio::sync::mpsc; and use crate::pcm::{AudioPipe, AudioSource, AudioSink, PcmFrame};. tokio is not a dependency of rutster-media (Cargo.toml lists only rutster-call-model, opus, str0m, thiserror, tracing), so the verbatim import is a hard compile error + an unused-import warning (promoted to error by -D warnings). Both imports are forward-references — only Reflex<P> (Task 2) consumes them. The implementer stripped both and left an inline comment flagging that Task 2 must reintroduce the imports AND add tokio = { workspace = true } to crates/rutster-media/Cargo.toml. Task 1's actual surface (enum, metrics, trait method, tests) is unaffected and matches the brief's intent verbatim.

Also: the brief's module-doc comment said LocalVadReflex<P> is "deferred per slice-4 §1.2" — stale (Task 2b builds it this slice as the primary trigger). Prose corrected to state it lands via Task 2b (spec §6.4).

Seam gate

crates/rutster-media/src/loop_driver.rs + crates/rutster-media/src/rtc_session.rs are byte-identical to slice-3 (verified via git diff --exit-code origin/main -- <those files>). Not touched.

Verification

  • cargo fmt --all --check — clean
  • cargo clippy --all --all-targets -- -D warnings — clean
  • cargo test --all — all green (rutster-media lib: 14 passed, 11 pre-existing + 3 new; all other crates pass)
  • 2 commits, both DCO-signed (Signed-off-by: opencode controller <controller@local>)

Merge instructions

  • squash-merge
  • This is the critical-path foundation — after merge, dev-a's Task 2 (Reflex<P>) and dev-b's Tasks 3/4 parallelize.
## What lands Task 1 of the slice-4 plan — the **critical-path foundation**. Everything else in slice-4 depends on this merging first. - Created `crates/rutster-media/src/reflex.rs`: `AdvisoryEvent` enum (`SpeechStarted`/`SpeechStopped`), `ReflexMetrics` (4 `AtomicU64` counters + `new()`/`snapshot()`), `ReflexMetricsSnapshot` (Debug+PartialEq+Eq). 3 inline tests. - Modified `crates/rutster-media/src/pcm.rs`: added `AudioPipe::barge_in_flush(&mut self)` default method (delegates to `clear_playout_ring`) — the kill-now path. `EchoAudioPipe` inherits the default unchanged. - Modified `crates/rutster-media/src/lib.rs`: `pub mod reflex;` + re-exports (`Reflex` intentionally omitted — Task 2 defines it; flagged inline) + `//!` module-map catalogue entry. ## What this proves The foundational types + trait hook that every later slice-4 task consumes: Task 2 (`Reflex<P>` state machine), Task 2b (`LocalVadReflex<P>` primary trigger), Task 3 (the `TapAudioPipe::barge_in_flush` override), Task 4 (`advisory_tx` wiring), Tasks 5–7 (composition + dedicated thread). Without Task 1, none of them compile. ## Deviation from the verbatim brief (flagged for review) The brief's verbatim `reflex.rs` included `use tokio::sync::mpsc;` and `use crate::pcm::{AudioPipe, AudioSource, AudioSink, PcmFrame};`. **`tokio` is not a dependency of `rutster-media`** (Cargo.toml lists only `rutster-call-model`, `opus`, `str0m`, `thiserror`, `tracing`), so the verbatim import is a hard compile error + an unused-import warning (promoted to error by `-D warnings`). Both imports are forward-references — only `Reflex<P>` (Task 2) consumes them. The implementer stripped both and left an inline comment flagging that **Task 2 must reintroduce the imports AND add `tokio = { workspace = true }` to `crates/rutster-media/Cargo.toml`**. Task 1's actual surface (enum, metrics, trait method, tests) is unaffected and matches the brief's intent verbatim. Also: the brief's module-doc comment said `LocalVadReflex<P>` is "deferred per slice-4 §1.2" — stale (Task 2b builds it this slice as the primary trigger). Prose corrected to state it lands via Task 2b (spec §6.4). ## Seam gate `crates/rutster-media/src/loop_driver.rs` + `crates/rutster-media/src/rtc_session.rs` are **byte-identical to slice-3** (verified via `git diff --exit-code origin/main -- <those files>`). Not touched. ## Verification - `cargo fmt --all --check` — clean - `cargo clippy --all --all-targets -- -D warnings` — clean - `cargo test --all` — all green (rutster-media lib: 14 passed, 11 pre-existing + 3 new; all other crates pass) - 2 commits, both DCO-signed (`Signed-off-by: opencode controller <controller@local>`) ## Merge instructions - squash-merge - This is the critical-path foundation — after merge, dev-a's Task 2 (`Reflex<P>`) and dev-b's Tasks 3/4 parallelize.
alee added 2 commits 2026-07-03 03:12:55 +00:00
feat(media): AdvisoryEvent + ReflexMetrics + barge_in_flush trait (slice-4 §3.1, §3.3) 0b054e76f4 
The critical-path foundation for the barge-in reflex. AdvisoryEvent is
the enum carried over a tokio mpsc from TapEngine to Reflex (brain →
FOB). ReflexMetrics is the observable surface. barge_in_flush is the
new AudioPipe trait method (default delegates to clear_playout_ring) —
the kill-now path that clears the ring AND drains rx_audio_out.

Task 1 of the slice-4 plan. Everything else depends on this landing.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(media): add reflex module-map entry to lib.rs catalogue (slice-4 §3.1)
All checks were successful
CI / fmt (pull_request) Successful in 1m29s
Details
CI / clippy (pull_request) Successful in 2m31s
Details
CI / test (1.85) (pull_request) Successful in 4m16s
Details
CI / test (stable) (pull_request) Successful in 4m19s
Details
CI / deny (pull_request) Successful in 1m21s
Details
d06e79cc50 
Task 1 review flagged the new reflex module was missing from the
module-map //! catalogue. AGENTS.md learner-facing convention requires
the catalogue entry describing what the module does + why it exists.

Addresses the Minor finding from the Task 1 task review.

Signed-off-by: Aaron D. Lee <himself@adlee.work>
alee force-pushed slice-4-dev-a-reflex from 1a21452e49 to d06e79cc50 2026-07-03 03:12:56 +00:00 Compare
alee merged commit 8cde52b1d3 into main 2026-07-03 03:37:35 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
alee
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alee/rutster#7
Delete Branch "slice-4-dev-a-reflex"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?