//! # rutster-media
//!
//! The media core: str0m WebRTC termination + the Opus⇄PCM boundary
//! (spec §3). One per WebRTC peer; a `RtcSession` owns a `str0m::Rtc`
//! instance + an Opus encoder/decoder pair + an `EchoAudioPipe`
//! wiring the inbound decode path to the outbound encode path.
//!
//! ## Architecture references
//!
//! - [slice-1 spec §3](../../../docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md)
//!   — full media-core design.
//! - [ARCHITECTURE.md](../../../docs/ARCHITECTURE.md) — fused per-call
//!   vertical; the tap is the central interface; PCM tap format.
//! - [ADR-0002](../../../docs/adr/0002-north-star-and-fused-core.md) —
//!   fused vertical + the in-boundary spend gate.
//!
//! ## Error handling posture (spec §3.8)
//!
//! Cold path (RTc construction, codec init): `thiserror`-derived errors + `?`.
//! Hot path (the 20 ms loop): **never** `?`. Match-and-continue. A
//! dropped packet MUST NOT terminate the peer. Policy: "drop + observe
//! (log + counter), don't crash." This is the posture the eventual fuzz
//! harness (step 5) will test against.
//!
//! ## Module map
//!
//! - [`pcm`] — `PcmFrame` + `AudioSource`/`AudioSink` traits (the tap
//!   seam) + `EchoAudioPipe` (slice-1 wiring).
//! - [`opus_codec`] — `OpusDecoder`/`OpusEncoder` wrappers.
//! - [`reflex`] (slice-4) — `AdvisoryEvent` + `ReflexMetrics`; the FOB
//!   barge-in reflex state machine will decorate `AudioPipe` here (Task 2).
//! - [`loop_driver`] (Task 4) — the str0m poll loop on tokio.
//! - [`rtc_session`] (Task 4) — `RtcSession`, the per-peer owner.

pub mod loop_driver;
pub mod opus_codec;
pub mod pcm;
pub mod reflex;
pub mod rtc_session;

pub use opus_codec::{OpusDecoder, OpusEncoder};
pub use pcm::{AudioPipe, AudioSink, AudioSource, EchoAudioPipe, PcmFrame, SAMPLES_PER_FRAME};
pub use reflex::{
    AdvisoryEvent, LocalVadReflex, Reflex, ReflexMetrics, ReflexMetricsSnapshot,
    VAD_DEBOUNCE_FRAMES, VAD_RMS_THRESHOLD,
};
pub use rtc_session::{MediaAddressConfig, RtcSession, RtcSessionError};

use thiserror::Error;

/// Cold-path errors for media-core construction. Hot-path failures go
/// through the "match-and-continue" `Option<_>` returns on
/// `OpusDecoder::decode` / `OpusEncoder::encode`, NOT through this enum.
#[derive(Debug, Error)]
pub enum MediaError {
    #[error("opus codec initialization failed: {0}")]
    CodecInit(#[from] opus::Error),
}
