headroom

public

Star0

Fork 0

Watch0

4 commits 1 branch 0 tags 0 releases521.6 KiB

Commit `65250d1c123c`

tarball

atagen <boss@atagen.co>2026-06-04 03:27 UTC

24 files changed+7909-0

core: pipewire daemon with bus filter, routing, dsp, meters, ipc server

Added file: crates/headroom-core/Cargo.toml+55 additions@@ -0,0 +1,55 @@
+[package]
+name = "headroom-core"
+description = "automatic loudness and per-app volume control (pipewire)"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[dependencies]
+headroom-dsp = { workspace = true }
+headroom-ipc = { workspace = true }
+
+serde = { workspace = true }
+serde_json = { workspace = true }
+toml = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+crossbeam-channel = { workspace = true }
+parking_lot = { workspace = true }
+signal-hook = { workspace = true }
+nix = { workspace = true }
+
+pipewire = { workspace = true }
+libspa     = { workspace = true }
+libspa-sys = { workspace = true }
+# own crate: headroom-core forbids unsafe, pipewire-rs 0.8 has no `Filter` API
+pipewire-filter = { workspace = true }
+
+rtrb     = { workspace = true }
+bytemuck = { workspace = true }
+# basedrop = { workspace = true }
+
+notify = { workspace = true }
+notify-debouncer-mini = { workspace = true }
+
+ebur128 = { workspace = true }
+
+# debug: panics on alloc inside `assert_no_alloc!`; release: no-op. wraps each `process` callback
+assert_no_alloc = { workspace = true }
+
+# tracing-journald = { workspace = true }
+
+[dev-dependencies]
+criterion = { workspace = true }
+headroom-client = { workspace = true }
+
+[features]
+default = []
+
+[[bench]]
+name = "app_level"
+harness = false

Added file: crates/headroom-core/src/agc.rs+543 additions@@ -0,0 +1,543 @@
+//! control-thread piece of the slow agc; not spike-reactive (time constants are seconds)
+
+use std::time::Duration;
+
+use ebur128::{EbuR128, Mode};
+use headroom_ipc::{Event, MeterTick, Topic};
+
+use crate::meters::SharedBusMetrics;
+use crate::pw::filter::FilterControl;
+use crate::state::SharedState;
+
+/// hardcoded for v0; not a profile knob
+pub const AGC_TICK: Duration = Duration::from_millis(50);
+
+/// ~50 ms of stereo at 48k (4800 samples) plus slack; bounds `ebur128.add_frames_f32` work
+const TICK_BUF_SAMPLES: usize = 8192;
+
+/// "no usable measurement yet" — `ebur128` before its window fills, or during silence. published
+/// verbatim in `MeterTick.*_lufs` so clients can recognise it without hardcoding the number.
+pub const LOUDNESS_FLOOR_LUFS: f32 = -200.0;
+
+pub struct AgcController {
+    sample_rate: u32,
+    channels: u32,
+    ebu: EbuR128,
+    measurement_consumer: rtrb::Consumer<f32>,
+    filter_control: FilterControl,
+    daemon: SharedState,
+    smoothed_target_db: f32,
+    /// cached so we push the audio-thread enable flag exactly on transition
+    last_enabled: bool,
+    last_short_term_lufs: f32,
+    /// last successfully queued limiter program loudness
+    last_program_lufs: Option<f32>,
+    bus_metrics: SharedBusMetrics,
+    /// wraps freely
+    meter_tick_counter: u32,
+    timing: crate::meters::SharedPlaybackTiming,
+    /// previous values, for computing per-log deltas (only warn on new events)
+    last_logged_spike_count: u64,
+    last_logged_starved: u64,
+    last_logged_dropped: u64,
+    last_logged_format_errors: u64,
+    timing_log_counter: u32,
+}
+
+impl AgcController {
+    pub fn new(
+        sample_rate: u32,
+        channels: u32,
+        measurement_consumer: rtrb::Consumer<f32>,
+        filter_control: FilterControl,
+        daemon: SharedState,
+        bus_metrics: SharedBusMetrics,
+        timing: crate::meters::SharedPlaybackTiming,
+    ) -> Result<Self, AgcInitError> {
+        // Mode::I costs a histogram walk per `loudness_global()` — bounded, fine at 20 Hz.
+        // lets the `meters` topic surface integrated lufs without a second ebur128 instance.
+        let ebu = EbuR128::new(
+            channels,
+            sample_rate,
+            Mode::S | Mode::M | Mode::I | Mode::TRUE_PEAK,
+        )
+        .map_err(AgcInitError::from)?;
+        Ok(Self {
+            sample_rate,
+            channels,
+            ebu,
+            measurement_consumer,
+            filter_control,
+            daemon,
+            smoothed_target_db: 0.0,
+            last_enabled: true,
+            last_short_term_lufs: LOUDNESS_FLOOR_LUFS,
+            last_program_lufs: None,
+            bus_metrics,
+            meter_tick_counter: 0,
+            timing,
+            last_logged_spike_count: 0,
+            last_logged_starved: 0,
+            last_logged_dropped: 0,
+            last_logged_format_errors: 0,
+            timing_log_counter: 0,
+        })
+    }
+
+    /// `LOUDNESS_FLOOR_LUFS` before the short-term window fills.
+    #[must_use]
+    pub fn last_short_term_lufs(&self) -> f32 {
+        self.last_short_term_lufs
+    }
+
+    #[must_use]
+    pub fn current_target_db(&self) -> f32 {
+        self.smoothed_target_db
+    }
+
+    /// one control-loop iteration; invoked at [`AGC_TICK`] cadence by a main-loop timer.
+    pub fn tick(&mut self) {
+        // snapshot config out from under the lock
+        let (cfg, compressor_enabled, publish_hz) = {
+            let s = self.daemon.lock();
+            let p = s.profiles.effective();
+            (p.agc.clone(), p.compressor.enabled, p.meters.publish_hz)
+        };
+
+        if cfg.enabled != self.last_enabled {
+            self.filter_control.set_agc_enabled(cfg.enabled);
+            self.last_enabled = cfg.enabled;
+        }
+
+        // unconditional so `meters` keeps surfacing lufs even with only compressor/limiter on
+        self.consume_measurements();
+        let short_term = finite_or_floor(
+            self.ebu.loudness_shortterm().map(|v| v as f32).ok(),
+        );
+        self.last_short_term_lufs = short_term;
+
+        if cfg.enabled
+            && short_term > cfg.silence_threshold_lufs
+            && short_term.is_finite()
+        {
+            let raw_target = cfg.target_lufs - short_term;
+            let clamped = raw_target.clamp(-cfg.max_cut_db, cfg.max_boost_db);
+
+            // leaky integrator: attack when target drops, release when it rises
+            let dt_ms = AGC_TICK.as_secs_f32() * 1000.0;
+            let alpha = if clamped < self.smoothed_target_db {
+                alpha_for_dt(cfg.attack_ms, dt_ms)
+            } else {
+                alpha_for_dt(cfg.release_ms, dt_ms)
+            };
+            self.smoothed_target_db += alpha * (clamped - self.smoothed_target_db);
+            self.filter_control
+                .set_agc_target_db(self.smoothed_target_db);
+        }
+
+        // limiter sees post-agc loudness; ebur128 measures pre-agc
+        let program_lufs = if short_term.is_finite() && short_term > cfg.silence_threshold_lufs {
+            let makeup_db = if cfg.enabled { self.smoothed_target_db } else { 0.0 };
+            Some(short_term + makeup_db)
+        } else {
+            None
+        };
+        self.push_program_loudness(program_lufs);
+
+        self.publish_meters(publish_hz, cfg.enabled, compressor_enabled);
+        self.log_playback_timing();
+    }
+
+    fn push_program_loudness(&mut self, program_lufs: Option<f32>) {
+        const EPSILON_DB: f32 = 0.1;
+        let changed = match (self.last_program_lufs, program_lufs) {
+            (Some(prev), Some(next)) => (prev - next).abs() >= EPSILON_DB,
+            (None, None) => false,
+            _ => true,
+        };
+        if changed && self.filter_control.set_program_loudness_lufs(program_lufs) {
+            self.last_program_lufs = program_lufs;
+        }
+    }
+
+    /// throttled (~1 Hz) log of playback callback timing; lock-free atomic loads.
+    fn log_playback_timing(&mut self) {
+        // 20 Hz tick → every 20 ticks ≈ 1 Hz
+        self.timing_log_counter = self.timing_log_counter.wrapping_add(1);
+        if self.timing_log_counter % 20 != 0 {
+            return;
+        }
+        let snap = self.timing.snapshot();
+        if snap.call_count == 0 {
+            return;
+        }
+        let avg_us = snap.sum_us / snap.call_count.max(1);
+        let new_spikes = snap.spike_count.saturating_sub(self.last_logged_spike_count);
+        self.last_logged_spike_count = snap.spike_count;
+        let new_starved = snap.samples_starved.saturating_sub(self.last_logged_starved);
+        self.last_logged_starved = snap.samples_starved;
+        let new_dropped = snap.samples_dropped.saturating_sub(self.last_logged_dropped);
+        self.last_logged_dropped = snap.samples_dropped;
+        if new_spikes > 0 {
+            tracing::warn!(
+                avg_us,
+                max_us = snap.max_us,
+                new_spikes,
+                total_spikes = snap.spike_count,
+                last_spike_us = snap.last_spike_us,
+                last_spike_at_call = snap.last_spike_at_call,
+                call_count = snap.call_count,
+                "playback callback BUSY spike(s) since last log"
+            );
+        } else {
+            tracing::debug!(
+                avg_us,
+                max_us = snap.max_us,
+                call_count = snap.call_count,
+                "playback callback timing"
+            );
+        }
+        // ring-imbalance diagnostic: steady-state is all zeros. non-zero delta = capture→playback
+        // ring drained/stuffed within a quantum (the "tremolo every quantum" mechanism). warn so
+        // it shows at default tracing level.
+        if new_starved > 0 || new_dropped > 0 {
+            tracing::warn!(
+                new_starved,
+                total_starved = snap.samples_starved,
+                new_dropped,
+                total_dropped = snap.samples_dropped,
+                call_count = snap.call_count,
+                "filter ring imbalance — playback zero-filled and/or capture dropped samples"
+            );
+        }
+        // rt format errors are logged here to keep the callback allocation-free
+        let new_format_errors = snap.format_errors.saturating_sub(self.last_logged_format_errors);
+        self.last_logged_format_errors = snap.format_errors;
+        if new_format_errors > 0 {
+            tracing::warn!(
+                new_format_errors,
+                total_format_errors = snap.format_errors,
+                "filter skipped short/misaligned audio buffer(s)"
+            );
+        }
+    }
+
+    fn consume_measurements(&mut self) {
+        let mut buf = [0.0_f32; TICK_BUF_SAMPLES];
+        let mut n = 0;
+        while n < buf.len() {
+            match self.measurement_consumer.pop() {
+                Ok(s) => {
+                    buf[n] = s;
+                    n += 1;
+                }
+                Err(_) => break,
+            }
+        }
+        if n == 0 {
+            return;
+        }
+        // ebur128 wants whole frames; drop any odd trailing sample.
+        let usable = (n / self.channels as usize) * self.channels as usize;
+        if usable == 0 {
+            return;
+        }
+        if let Err(e) = self.ebu.add_frames_f32(&buf[..usable]) {
+            tracing::warn!(error = %e, "ebur128 add_frames_f32 failed");
+        }
+    }
+
+    fn publish_meters(&mut self, publish_hz: f32, agc_enabled: bool, compressor_enabled: bool) {
+        if !self.should_publish(publish_hz) {
+            return;
+        }
+        let bus = *self.bus_metrics.lock();
+        // ebur128 returns -inf (not Err) for "no measurement yet"; serde_json renders non-finite
+        // f32 as null, so floor here.
+        let momentary = finite_or_floor(
+            self.ebu.loudness_momentary().map(|v| v as f32).ok(),
+        );
+        let integrated = finite_or_floor(
+            self.ebu.loudness_global().map(|v| v as f32).ok(),
+        );
+
+        let tick = MeterTick {
+            momentary_lufs: momentary,
+            shortterm_lufs: self.last_short_term_lufs,
+            integrated_lufs: integrated,
+            true_peak_dbtp: bus.true_peak_dbtp,
+            // path GR is additive in log domain; both ≤ 0 dB when reducing
+            gain_reduction_db: bus.compressor_gr_db + bus.limiter_total_gr_db,
+            compressor_gr_db: bus.compressor_gr_db,
+            limiter_gr_db: bus.limiter_total_gr_db,
+            agc_gain_db: self.smoothed_target_db,
+            agc_enabled,
+            compressor_enabled,
+        };
+
+        if let Ok(event) = Event::new(Topic::Meters, "tick", &tick) {
+            self.daemon.lock().broadcaster.publish(Topic::Meters, event);
+        }
+    }
+
+    /// tick-rate gate for `meters`; caps at [`AGC_TICK`]'s 20 Hz, higher `publish_hz` clamped.
+    fn should_publish(&mut self, publish_hz: f32) -> bool {
+        if publish_hz <= 0.0 {
+            return false;
+        }
+        let agc_hz = 1000.0 / AGC_TICK.as_millis() as f32;
+        if publish_hz >= agc_hz {
+            self.meter_tick_counter = self.meter_tick_counter.wrapping_add(1);
+            return true;
+        }
+        let skip = (agc_hz / publish_hz).round().max(1.0) as u32;
+        let now = self.meter_tick_counter;
+        self.meter_tick_counter = self.meter_tick_counter.wrapping_add(1);
+        now % skip == 0
+    }
+
+    pub fn reset(&mut self) {
+        self.smoothed_target_db = 0.0;
+        self.last_short_term_lufs = LOUDNESS_FLOOR_LUFS;
+        self.last_program_lufs = None;
+        // ebur128 has no public reset; rebuild with the same mode set as new()
+        if let Ok(fresh) = EbuR128::new(
+            self.channels,
+            self.sample_rate,
+            Mode::S | Mode::M | Mode::I | Mode::TRUE_PEAK,
+        ) {
+            self.ebu = fresh;
+        }
+        self.filter_control.set_agc_target_db(0.0);
+        self.filter_control.set_program_loudness_lufs(None);
+    }
+
+    /// rebind to a freshly-built filter after rate-change. old consumer/control point at rtrbs
+    /// whose producers were just dropped (sends would fail), so swap handles + rebuild ebur128 at
+    /// the new rate.
+    pub fn rebind(
+        &mut self,
+        measurement_consumer: rtrb::Consumer<f32>,
+        filter_control: FilterControl,
+        sample_rate: u32,
+    ) {
+        self.measurement_consumer = measurement_consumer;
+        self.filter_control = filter_control;
+        self.sample_rate = sample_rate;
+        self.reset();
+    }
+}
+
+/// -inf (ebur128 "no reading" sentinel) and NaN collapse to [`LOUDNESS_FLOOR_LUFS`].
+fn finite_or_floor(v: Option<f32>) -> f32 {
+    match v {
+        Some(x) if x.is_finite() => x,
+        _ => LOUDNESS_FLOOR_LUFS,
+    }
+}
+
+/// leaky-integrator alpha: `1 - exp(-dt / tau)`, clamped to `[0, 1]`.
+fn alpha_for_dt(tau_ms: f32, dt_ms: f32) -> f32 {
+    if tau_ms <= 0.0 || dt_ms <= 0.0 {
+        return 1.0;
+    }
+    (1.0 - (-dt_ms / tau_ms).exp()).clamp(0.0, 1.0)
+}
+
+/// construction-time failures only; tick-time errors are logged and the tick skipped.
+#[derive(Debug, thiserror::Error)]
+pub enum AgcInitError {
+    #[error("ebur128: {0}")]
+    Ebu(#[from] ebur128::Error),
+}
+
+impl From<AgcInitError> for crate::error::DaemonError {
+    fn from(e: AgcInitError) -> Self {
+        crate::error::DaemonError::other(format!("agc init: {e}"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::meters;
+    use crate::profile_store::ProfileStore;
+    use crate::pw::filter::{AudioCmd, FilterControl};
+    use crate::state::{self, DaemonState};
+    use rtrb::RingBuffer;
+
+    const SR: u32 = 48_000;
+    const CH: u32 = 2;
+
+    fn fixture() -> (
+        AgcController,
+        rtrb::Producer<f32>,
+        rtrb::Consumer<AudioCmd>,
+        SharedState,
+        SharedBusMetrics,
+    ) {
+        let (m_prod, m_cons) = RingBuffer::<f32>::new(8192);
+        let (control, cmd_cons) = FilterControl::for_testing(32);
+        let state = state::shared(DaemonState::new(ProfileStore::builtin()));
+        let bus = meters::shared();
+        let timing = meters::shared_timing();
+        let agc = AgcController::new(
+            SR,
+            CH,
+            m_cons,
+            control,
+            state.clone(),
+            bus.clone(),
+            timing,
+        )
+        .unwrap();
+        (agc, m_prod, cmd_cons, state, bus)
+    }
+
+    fn push_silence(prod: &mut rtrb::Producer<f32>, frames: usize) {
+        for _ in 0..frames {
+            let _ = prod.push(0.0);
+            let _ = prod.push(0.0);
+        }
+    }
+
+    fn push_sine(prod: &mut rtrb::Producer<f32>, frames: usize, amp: f32) {
+        // Constant amplitude impulse-like — not a real sine but it
+        // produces a measurable loudness in ebur128 well above silence.
+        for _ in 0..frames {
+            let _ = prod.push(amp);
+            let _ = prod.push(-amp);
+        }
+    }
+
+    #[test]
+    fn tick_with_no_samples_does_nothing() {
+        let (mut agc, _prod, mut cmd_cons, _state, _bus) = fixture();
+        agc.tick();
+        assert!(cmd_cons.pop().is_err(), "no samples → no target push");
+        assert_eq!(agc.current_target_db(), 0.0);
+    }
+
+    #[test]
+    fn tick_under_silence_threshold_holds_target() {
+        let (mut agc, mut prod, mut cmd_cons, _state, _bus) = fixture();
+        push_silence(&mut prod, 4800); // 100ms of silence
+        agc.tick();
+        // ebur128 may report -inf or values below the silence
+        // threshold; either way we should not push.
+        assert!(
+            cmd_cons.pop().is_err(),
+            "below silence threshold — no target push expected"
+        );
+    }
+
+    #[test]
+    fn tick_with_audible_signal_pushes_target() {
+        let (mut agc, mut prod, mut cmd_cons, _state, _bus) = fixture();
+        // Pump multiple ticks worth so ebur128's short-term window
+        // (~3 s) starts producing values.
+        for _ in 0..40 {
+            push_sine(&mut prod, 4800, 0.3);
+            agc.tick();
+        }
+        // We expect at least one SetAgcTargetDb to have been pushed
+        // once short-term loudness became finite.
+        let mut saw = false;
+        while let Ok(cmd) = cmd_cons.pop() {
+            if matches!(cmd, AudioCmd::SetAgcTargetDb(_)) {
+                saw = true;
+            }
+        }
+        assert!(saw, "expected at least one AGC target push after pumping");
+    }
+
+    #[test]
+    fn tick_with_audible_signal_pushes_program_loudness() {
+        let (mut agc, mut prod, mut cmd_cons, _state, _bus) = fixture();
+        for _ in 0..40 {
+            push_sine(&mut prod, 4800, 0.3);
+            agc.tick();
+        }
+        let mut program: Option<f32> = None;
+        while let Ok(cmd) = cmd_cons.pop() {
+            if let AudioCmd::SetProgramLoudnessLufs(v) = cmd {
+                program = v;
+            }
+        }
+        let lufs = program.expect("expected a SetProgramLoudnessLufs(Some) push");
+        assert!(
+            lufs.is_finite() && lufs > -200.0,
+            "program loudness should be a real reading, got {lufs}"
+        );
+    }
+
+    #[test]
+    fn silence_then_audio_clears_then_sets_program_loudness() {
+        let (mut agc, mut prod, mut cmd_cons, _state, _bus) = fixture();
+        for _ in 0..5 {
+            push_silence(&mut prod, 4800);
+            agc.tick();
+        }
+        while let Ok(cmd) = cmd_cons.pop() {
+            if let AudioCmd::SetProgramLoudnessLufs(Some(v)) = cmd {
+                panic!("silence should not set a program loudness, got {v}");
+            }
+        }
+    }
+
+    #[test]
+    fn reset_clears_program_loudness() {
+        let (mut agc, mut prod, mut cmd_cons, _state, _bus) = fixture();
+        for _ in 0..40 {
+            push_sine(&mut prod, 4800, 0.3);
+            agc.tick();
+        }
+        while cmd_cons.pop().is_ok() {}
+        agc.reset();
+        let mut saw_clear = false;
+        while let Ok(cmd) = cmd_cons.pop() {
+            if matches!(cmd, AudioCmd::SetProgramLoudnessLufs(None)) {
+                saw_clear = true;
+            }
+        }
+        assert!(saw_clear, "reset should clear the limiter's program loudness");
+    }
+
+    #[test]
+    fn agc_disable_in_profile_flips_audio_thread() {
+        let (mut agc, _prod, mut cmd_cons, state, _bus) = fixture();
+        // First tick with the default-enabled profile.
+        agc.tick();
+        // Drain any commands.
+        while cmd_cons.pop().is_ok() {}
+
+        // Disable AGC in the profile.
+        state
+            .lock()
+            .profiles
+            .set_setting("agc.enabled", serde_json::json!(false))
+            .unwrap();
+        agc.tick();
+
+        // Expect a SetAgcEnabled(false) command.
+        let mut saw_disable = false;
+        while let Ok(cmd) = cmd_cons.pop() {
+            if matches!(cmd, AudioCmd::SetAgcEnabled(false)) {
+                saw_disable = true;
+            }
+        }
+        assert!(saw_disable, "expected SetAgcEnabled(false) on profile flip");
+    }
+
+    #[test]
+    fn alpha_endpoints() {
+        // tau == 0 → instantaneous.
+        assert_eq!(alpha_for_dt(0.0, 50.0), 1.0);
+        // dt == 0 → no progress.
+        assert_eq!(alpha_for_dt(1000.0, 0.0), 1.0); // we clamp dt<=0 to 1.0 too
+        // Sanity: shorter tau → larger alpha for same dt.
+        let a_fast = alpha_for_dt(100.0, 50.0);
+        let a_slow = alpha_for_dt(2000.0, 50.0);
+        assert!(a_fast > a_slow);
+    }
+}

Added file: crates/headroom-core/src/error.rs+39 additions@@ -0,0 +1,39 @@
+//! daemon error types.
+
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum DaemonError {
+    #[error("io: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("json: {0}")]
+    Json(#[from] serde_json::Error),
+
+    #[error("toml: {0}")]
+    Toml(#[from] toml::de::Error),
+
+    #[error("pipewire: {0}")]
+    PipeWire(String),
+
+    #[error("pipewire object not found: {0}")]
+    PipeWireNotFound(String),
+
+    #[error("profile: {0}")]
+    Profile(String),
+
+    #[error("daemon shutting down")]
+    Shutdown,
+
+    #[error("{0}")]
+    Other(String),
+}
+
+impl DaemonError {
+    pub fn pipewire(msg: impl std::fmt::Display) -> Self {
+        DaemonError::PipeWire(msg.to_string())
+    }
+
+    pub fn other(msg: impl std::fmt::Display) -> Self {
+        DaemonError::Other(msg.to_string())
+    }
+}

Added file: crates/headroom-core/src/ipc/broadcast.rs+288 additions@@ -0,0 +1,288 @@
+//! per-subscriber event fan-out. full queue → event dropped + per-(sub,
+//! topic) counter, flushed as a `daemon::overflow` event on next success.
+//! see `IPC.md` §4 Backpressure.
+
+use std::collections::{HashMap, HashSet};
+
+use crossbeam_channel::{Sender, TrySendError};
+use serde_json::json;
+
+use headroom_ipc::{Event, ServerFrame, Topic};
+
+pub const SUBSCRIBER_CAPACITY: usize = 64;
+
+/// stable for the life of the connection.
+pub type SubscriberId = u64;
+
+struct Subscriber {
+    tx: Sender<ServerFrame>,
+    topics: HashSet<Topic>,
+    /// per-topic drops since the last successful overflow flush.
+    dropped: HashMap<Topic, u64>,
+    /// lifetime total, reset only on subscriber removal.
+    dropped_total: u64,
+}
+
+#[derive(Default)]
+pub struct Broadcaster {
+    subscribers: HashMap<SubscriberId, Subscriber>,
+    next_id: SubscriberId,
+}
+
+impl std::fmt::Debug for Broadcaster {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Broadcaster")
+            .field("subscribers", &self.subscribers.len())
+            .field("next_id", &self.next_id)
+            .finish()
+    }
+}
+
+impl Broadcaster {
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// register a connection's outbound channel.
+    pub fn register(&mut self, tx: Sender<ServerFrame>) -> SubscriberId {
+        let id = self.next_id;
+        self.next_id = self.next_id.wrapping_add(1);
+        self.subscribers.insert(
+            id,
+            Subscriber {
+                tx,
+                topics: HashSet::new(),
+                dropped: HashMap::new(),
+                dropped_total: 0,
+            },
+        );
+        id
+    }
+
+    /// idempotent.
+    pub fn unregister(&mut self, id: SubscriberId) {
+        self.subscribers.remove(&id);
+    }
+
+    /// add `topics` to subscriber `id`'s interest set; returns the
+    /// accepted set.
+    pub fn subscribe(&mut self, id: SubscriberId, topics: &[Topic]) -> Vec<Topic> {
+        let Some(sub) = self.subscribers.get_mut(&id) else {
+            return Vec::new();
+        };
+        for t in topics {
+            // `control` is reserved for the connect-time hello.
+            if matches!(t, Topic::Control) {
+                continue;
+            }
+            sub.topics.insert(*t);
+        }
+        sub.topics.iter().copied().collect()
+    }
+
+    pub fn unsubscribe(&mut self, id: SubscriberId, topics: &[Topic]) -> Vec<Topic> {
+        let Some(sub) = self.subscribers.get_mut(&id) else {
+            return Vec::new();
+        };
+        for t in topics {
+            sub.topics.remove(t);
+        }
+        topics.to_vec()
+    }
+
+    #[must_use]
+    pub fn subscriber_count(&self) -> usize {
+        self.subscribers.len()
+    }
+
+    /// publish on `topic`: non-blocking try-send to each interested
+    /// subscriber; full-queue failures accrue to the drop counter.
+    pub fn publish(&mut self, topic: Topic, event: Event) {
+        for sub in self.subscribers.values_mut() {
+            if !sub.topics.contains(&topic) {
+                continue;
+            }
+            match sub.tx.try_send(ServerFrame::Event(event.clone())) {
+                Ok(()) => {
+                    if sub.topics.contains(&Topic::Daemon) {
+                        flush_overflow(sub);
+                    }
+                }
+                Err(TrySendError::Full(_)) => {
+                    *sub.dropped.entry(topic).or_insert(0) += 1;
+                    sub.dropped_total = sub.dropped_total.wrapping_add(1);
+                }
+                Err(TrySendError::Disconnected(_)) => {
+                    // reaped on unregister.
+                }
+            }
+        }
+    }
+}
+
+/// flush pending per-topic overflow counts as `daemon::overflow`
+/// events; failed entries stay in `dropped` for next time.
+fn flush_overflow(sub: &mut Subscriber) {
+    if sub.dropped.is_empty() {
+        return;
+    }
+    // drain first so a failed try_send doesn't double-emit.
+    let entries: Vec<(Topic, u64)> = sub.dropped.drain().collect();
+    for (lost_topic, lost) in entries {
+        let lost_u32: u32 = u32::try_from(lost).unwrap_or(u32::MAX);
+        let data = json!({
+            "lost_topic": lost_topic.as_str(),
+            "lost": lost_u32,
+            "total_lost": sub.dropped_total,
+        });
+        let event = match Event::new(Topic::Daemon, "overflow", &data) {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+        match sub.tx.try_send(ServerFrame::Event(event)) {
+            Ok(()) => {}
+            Err(_) => {
+                // reinstate the count for the next flush.
+                *sub.dropped.entry(lost_topic).or_insert(0) += lost;
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crossbeam_channel::bounded;
+    use serde_json::Value;
+
+    fn make_subscriber(b: &mut Broadcaster, capacity: usize) -> (SubscriberId, crossbeam_channel::Receiver<ServerFrame>) {
+        let (tx, rx) = bounded(capacity);
+        let id = b.register(tx);
+        (id, rx)
+    }
+
+    fn ev(topic: Topic, name: &str) -> Event {
+        Event::new(topic, name, &json!({})).unwrap()
+    }
+
+    #[test]
+    fn register_and_unregister() {
+        let mut b = Broadcaster::new();
+        assert_eq!(b.subscriber_count(), 0);
+        let (id, _rx) = make_subscriber(&mut b, 4);
+        assert_eq!(b.subscriber_count(), 1);
+        b.unregister(id);
+        assert_eq!(b.subscriber_count(), 0);
+    }
+
+    #[test]
+    fn publish_reaches_only_subscribed_topic_subscribers() {
+        let mut b = Broadcaster::new();
+        let (id_a, rx_a) = make_subscriber(&mut b, 4);
+        let (id_b, rx_b) = make_subscriber(&mut b, 4);
+        b.subscribe(id_a, &[Topic::Routing]);
+        b.subscribe(id_b, &[Topic::Profile]);
+
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        // A receives, B does not.
+        assert!(rx_a.try_recv().is_ok());
+        assert!(rx_b.try_recv().is_err());
+    }
+
+    #[test]
+    fn control_topic_is_not_user_subscribable() {
+        let mut b = Broadcaster::new();
+        let (id, rx) = make_subscriber(&mut b, 4);
+        let acked = b.subscribe(id, &[Topic::Control]);
+        // Control was filtered out, so the ack list is empty for
+        // this single-topic subscribe.
+        assert!(acked.is_empty());
+        // Publishing on Control doesn't reach the client.
+        b.publish(Topic::Control, ev(Topic::Control, "hello"));
+        assert!(rx.try_recv().is_err());
+    }
+
+    #[test]
+    fn overflow_accrues_and_flushes_on_next_success() {
+        let mut b = Broadcaster::new();
+        // Capacity 2 so the flush has room for one routing + one
+        // overflow event after we've drained. Subscriber needs the
+        // Daemon topic on its interest list to receive overflow
+        // notices.
+        let (id, rx) = make_subscriber(&mut b, 2);
+        b.subscribe(id, &[Topic::Routing, Topic::Daemon]);
+
+        // First two publishes fill the queue.
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        // Subsequent publishes overflow — counted, not delivered.
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+
+        // Drain both messages so the queue is empty again.
+        let _ = rx.recv().unwrap();
+        let _ = rx.recv().unwrap();
+
+        // Now publish again; this should succeed AND piggyback the
+        // overflow notice on the daemon topic.
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+
+        // Collect remaining messages.
+        let mut got: Vec<ServerFrame> = Vec::new();
+        while let Ok(m) = rx.try_recv() {
+            got.push(m);
+        }
+        // Expect one routing event + one daemon::overflow.
+        let topics: Vec<Topic> = got
+            .iter()
+            .map(|f| match f {
+                ServerFrame::Event(e) => e.topic,
+                ServerFrame::Response(_) => panic!("no response expected"),
+            })
+            .collect();
+        assert!(topics.contains(&Topic::Routing));
+        assert!(topics.contains(&Topic::Daemon));
+
+        // The daemon event has the overflow payload.
+        let overflow = got
+            .into_iter()
+            .find_map(|f| match f {
+                ServerFrame::Event(e) if e.topic == Topic::Daemon => Some(e),
+                _ => None,
+            })
+            .unwrap();
+        assert_eq!(overflow.event, "overflow");
+        let data = overflow.data;
+        assert_eq!(data["lost_topic"], Value::String("routing".into()));
+        assert!(data["lost"].as_u64().unwrap() >= 1);
+    }
+
+    #[test]
+    fn unsubscribe_stops_delivery() {
+        let mut b = Broadcaster::new();
+        let (id, rx) = make_subscriber(&mut b, 4);
+        b.subscribe(id, &[Topic::Routing]);
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        rx.try_recv().unwrap();
+
+        b.unsubscribe(id, &[Topic::Routing]);
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        assert!(rx.try_recv().is_err());
+    }
+
+    #[test]
+    fn disconnected_subscriber_is_a_silent_no_op_until_unregistered() {
+        let mut b = Broadcaster::new();
+        let (id, rx) = make_subscriber(&mut b, 4);
+        b.subscribe(id, &[Topic::Routing]);
+        drop(rx); // simulate the reader thread dying
+
+        // Publish doesn't panic and doesn't error.
+        b.publish(Topic::Routing, ev(Topic::Routing, "stream_routed"));
+        // Subscriber still listed until explicit unregister.
+        assert_eq!(b.subscriber_count(), 1);
+        b.unregister(id);
+        assert_eq!(b.subscriber_count(), 0);
+    }
+}

Added file: crates/headroom-core/src/ipc/connection.rs+146 additions@@ -0,0 +1,146 @@
+//! per-connection handler. each client spawns a writer thread (owns
+//! the write half, drains a bounded channel the broadcaster also feeds)
+//! and runs the reader on the current thread (dispatches requests,
+//! sends responses through the channel). split so events don't
+//! interleave with request/response writes.
+
+use std::io::{BufReader, BufWriter, Write};
+use std::os::unix::net::UnixStream;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::thread;
+use std::time::Duration;
+
+use crossbeam_channel::{bounded, Receiver, RecvTimeoutError, Sender};
+
+use headroom_ipc::{
+    Codec, Event, HelloData, Op, Request, Response, ServerFrame, Topic, PROTOCOL_VERSION,
+};
+
+use crate::ipc::broadcast::{SubscriberId, SUBSCRIBER_CAPACITY};
+use crate::ipc::ops;
+use crate::state::SharedState;
+
+const DAEMON_VERSION: &str = env!("CARGO_PKG_VERSION");
+const DAEMON_NAME: &str = "headroom";
+
+/// how often the writer wakes to check the shutdown flag.
+const WRITER_POLL_INTERVAL: Duration = Duration::from_millis(100);
+
+pub fn handle_connection(
+    stream: UnixStream,
+    state: SharedState,
+    shutdown: Arc<AtomicBool>,
+) {
+    let codec = Codec::new();
+    let reader_stream = match stream.try_clone() {
+        Ok(s) => s,
+        Err(e) => {
+            tracing::warn!(error = %e, "ipc conn: failed to clone stream");
+            return;
+        }
+    };
+    let mut reader = BufReader::new(reader_stream);
+
+    let (outbound_tx, outbound_rx) = bounded::<ServerFrame>(SUBSCRIBER_CAPACITY);
+
+    // hello before anything else lands on the wire.
+    if outbound_tx.try_send(ServerFrame::Event(hello())).is_err() {
+        tracing::warn!("ipc conn: outbound queue full at hello (capacity misconfigured?)");
+        return;
+    }
+
+    let sub_id = state.lock().broadcaster.register(outbound_tx.clone());
+
+    let writer_stream = stream;
+    let writer_shutdown = shutdown.clone();
+    let writer_handle = thread::Builder::new()
+        .name("headroom-ipc-conn-writer".into())
+        .spawn(move || writer_loop(writer_stream, outbound_rx, writer_shutdown))
+        .expect("spawn writer thread");
+
+    serve(&codec, &mut reader, &outbound_tx, &state, sub_id, &shutdown);
+
+    // drop outbound_tx so the writer sees disconnection and exits.
+    state.lock().broadcaster.unregister(sub_id);
+    drop(outbound_tx);
+    let _ = writer_handle.join();
+}
+
+fn hello() -> Event {
+    let data = HelloData {
+        daemon: DAEMON_NAME.into(),
+        version: DAEMON_VERSION.into(),
+        protocol: PROTOCOL_VERSION,
+    };
+    // unwrap: HelloData always serialises.
+    Event::new(Topic::Control, "hello", &data).expect("hello serialises")
+}
+
+fn writer_loop(stream: UnixStream, rx: Receiver<ServerFrame>, shutdown: Arc<AtomicBool>) {
+    let codec = Codec::new();
+    let mut writer = BufWriter::new(stream);
+    while !shutdown.load(Ordering::Relaxed) {
+        match rx.recv_timeout(WRITER_POLL_INTERVAL) {
+            Ok(frame) => {
+                if let Err(e) = codec.write(&mut writer, &frame) {
+                    tracing::warn!(error = %e, "ipc writer: codec write failed; closing");
+                    return;
+                }
+                // flush after each frame so events land promptly.
+                if let Err(e) = writer.flush() {
+                    tracing::warn!(error = %e, "ipc writer: flush failed; closing");
+                    return;
+                }
+            }
+            Err(RecvTimeoutError::Timeout) => continue,
+            Err(RecvTimeoutError::Disconnected) => return,
+        }
+    }
+}
+
+fn serve<R: std::io::Read>(
+    codec: &Codec,
+    reader: &mut R,
+    outbound: &Sender<ServerFrame>,
+    state: &SharedState,
+    sub_id: SubscriberId,
+    shutdown: &AtomicBool,
+) {
+    while !shutdown.load(Ordering::Relaxed) {
+        let req: Request = match codec.read(&mut *reader) {
+            Ok(r) => r,
+            Err(headroom_ipc::Error::Closed) => return,
+            Err(headroom_ipc::Error::Io(e))
+                if matches!(
+                    e.kind(),
+                    std::io::ErrorKind::UnexpectedEof | std::io::ErrorKind::BrokenPipe
+                ) =>
+            {
+                return
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "ipc reader: read failed; closing");
+                return;
+            }
+        };
+
+        // subscribe/unsubscribe mutate the broadcaster directly so
+        // sub_id needn't thread through every op handler.
+        let response: Response = match &req.op {
+            Op::Subscribe { topics } => {
+                let acked = state.lock().broadcaster.subscribe(sub_id, topics);
+                ops::ok_value(req.id, &serde_json::json!({ "subscribed": acked }))
+            }
+            Op::Unsubscribe { topics } => {
+                let acked = state.lock().broadcaster.unsubscribe(sub_id, topics);
+                ops::ok_value(req.id, &serde_json::json!({ "unsubscribed": acked }))
+            }
+            _ => ops::dispatch(&req, state),
+        };
+
+        if outbound.send(ServerFrame::Response(response)).is_err() {
+            return; // writer gone
+        }
+    }
+}

Added file: crates/headroom-core/src/ipc/mod.rs+13 additions@@ -0,0 +1,13 @@
+//! daemon IPC server (server side of `IPC.md`). one blocking thread per
+//! connection. no async runtime.
+
+pub mod broadcast;
+mod connection;
+mod ops;
+mod server;
+
+pub use server::{IpcServer, IpcServerHandle};
+
+/// re-exported so the profile file-watcher reuses the same path as the
+/// `profile.reload` op.
+pub(crate) use ops::execute_reload;

Added file: crates/headroom-core/src/ipc/ops.rs+1166 additions@@ -0,0 +1,1166 @@
+//! op dispatch + handlers. each locks state briefly and returns a
+//! [`Response`]; mutations route through [`ProfileStore`].
+
+use serde::Serialize;
+use serde_json::{json, Value};
+
+use headroom_ipc::{
+    ErrorCode, Event, HelloData, Op, ProfileInfo, ProtoError, Request, Response, Route, RouteList,
+    SinkInfo, Sinks, Status, StreamRoute, Topic, PROTOCOL_VERSION,
+};
+
+use crate::profile_store::StoreError;
+use crate::pw::command::PwCommand;
+use crate::state::SharedState;
+
+const DAEMON_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+mod profile_effects;
+use profile_effects::ProfileEffects;
+
+pub fn dispatch(req: &Request, state: &SharedState) -> Response {
+    match &req.op {
+        Op::Status => status(req.id, state),
+        Op::ProfileList => profile_list(req.id, state),
+        Op::ProfileShow { name } => profile_show(req.id, name.as_deref(), state),
+        Op::ProfileUse { name } => profile_use(req.id, name, state),
+        Op::ProfileReload => profile_reload(req.id, state),
+        Op::RouteList => route_list(req.id, state),
+        Op::RouteSet { app, to } => route_set(req.id, app, *to, state),
+        Op::RouteUnset { app } => route_unset(req.id, app, state),
+        Op::RouteStream { node_id, to } => route_stream(req.id, *node_id, *to, state),
+        Op::SettingGet { key } => setting_get(req.id, key, state),
+        Op::SettingSet { key, value } => setting_set(req.id, key, value.clone(), state),
+        Op::SettingList => setting_list(req.id, state),
+        Op::SettingClear { key } => setting_clear(req.id, key, state),
+        Op::SettingReset => setting_reset(req.id, state),
+        Op::BypassSet { enabled } => bypass_set(req.id, *enabled, state),
+        Op::LayerAList => layer_a_list(req.id, state),
+        Op::PerAppSet { app, enabled } => per_app_set(req.id, app, *enabled, state),
+        Op::PerAppMaster { enabled } => per_app_master(req.id, *enabled, state),
+        Op::LayerAReset { node_id } => layer_a_reset(req.id, *node_id, state),
+        Op::Hello { protocol } => hello(req.id, *protocol),
+        Op::Subscribe { .. } | Op::Unsubscribe { .. } => not_yet(req, "Phase 4d"),
+        // Op is #[non_exhaustive]; future ops look unknown here.
+        _ => err(
+            req.id,
+            ErrorCode::UnknownOp,
+            format!("op '{}' is not recognised by this daemon", req.op.name()),
+        ),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Read-only ops
+// ---------------------------------------------------------------------------
+
+fn status(id: u64, state: &SharedState) -> Response {
+    let s = state.lock();
+    let effective = s.profiles.effective();
+    let snapshot = Status {
+        version: DAEMON_VERSION.into(),
+        protocol: PROTOCOL_VERSION,
+        uptime_s: s.started_at.elapsed().as_secs(),
+        profile: effective.name.clone(),
+        bypass: s.profiles.bypass_global(),
+        per_app: effective.per_app.enabled,
+        sinks: Sinks {
+            processed: SinkInfo {
+                node_id: s.processed_sink_id,
+                name: Some(crate::pw::sink::NODE_NAME.to_owned()),
+                ready: s.processed_sink_id.is_some(),
+                // filter's current rate; `None` only pre-`Filter::create`.
+                sample_rate: s.filter_sample_rate,
+            },
+            real: s.real_sink.clone(),
+        },
+        streams: s
+            .streams
+            .values()
+            .map(|r| StreamRoute {
+                node_id: r.node_id,
+                app: r.app.clone(),
+                route: r.route,
+            })
+            .collect(),
+        layer_a: s.layer_a.values().cloned().collect(),
+        warnings: s.profiles.warnings(),
+        setting_overrides: s.profiles.setting_overrides(),
+    };
+    ok(id, &snapshot)
+}
+
+fn hello(id: u64, client_protocol: u32) -> Response {
+    if client_protocol != PROTOCOL_VERSION {
+        tracing::warn!(
+            client_protocol,
+            daemon_protocol = PROTOCOL_VERSION,
+            "IPC client protocol version differs from daemon; \
+             continuing best-effort — some ops or fields may not line up"
+        );
+    }
+    ok(
+        id,
+        &HelloData {
+            daemon: "headroom".into(),
+            version: DAEMON_VERSION.into(),
+            protocol: PROTOCOL_VERSION,
+        },
+    )
+}
+
+fn profile_list(id: u64, state: &SharedState) -> Response {
+    let s = state.lock();
+    let active = s.profiles.effective().name.clone();
+    let profiles: Vec<ProfileInfo> = s
+        .profiles
+        .list()
+        .map(|sp| ProfileInfo {
+            name: sp.name.clone(),
+            active: sp.name == active,
+            description: sp.profile.description.clone(),
+        })
+        .collect();
+    ok(id, &json!({ "profiles": profiles }))
+}
+
+fn profile_show(id: u64, name: Option<&str>, state: &SharedState) -> Response {
+    let s = state.lock();
+    let effective = s.profiles.effective();
+    match name {
+        None => ok(id, effective),
+        Some(requested) if requested == effective.name => ok(id, effective),
+        Some(requested) => match s.profiles.list().find(|sp| sp.name == requested) {
+            Some(found) => ok(id, &found.profile),
+            None => err(
+                id,
+                ErrorCode::NotFound,
+                format!("profile '{requested}' not loaded"),
+            ),
+        },
+    }
+}
+
+fn route_list(id: u64, state: &SharedState) -> Response {
+    let s = state.lock();
+    let effective = s.profiles.effective();
+    let body = RouteList {
+        rules: effective.rules.clone(),
+        current: s
+            .streams
+            .values()
+            .map(|r| StreamRoute {
+                node_id: r.node_id,
+                app: r.app.clone(),
+                route: r.route,
+            })
+            .collect(),
+        default_route: effective.default_route.route,
+    };
+    ok(id, &body)
+}
+
+fn setting_get(id: u64, key: &str, state: &SharedState) -> Response {
+    let s = state.lock();
+    let json_value = match serde_json::to_value(s.profiles.effective()) {
+        Ok(v) => v,
+        Err(e) => {
+            return err(id, ErrorCode::Internal, format!("serialise profile: {e}"));
+        }
+    };
+    drop(s);
+
+    let Some(found) = lookup_dotted(&json_value, key) else {
+        return err(
+            id,
+            ErrorCode::NotFound,
+            format!("setting '{key}' not found in active profile"),
+        );
+    };
+    ok(id, &json!({ "key": key, "value": found }))
+}
+
+fn setting_list(id: u64, state: &SharedState) -> Response {
+    let s = state.lock();
+    let json_value = match serde_json::to_value(s.profiles.effective()) {
+        Ok(v) => v,
+        Err(e) => {
+            return err(id, ErrorCode::Internal, format!("serialise profile: {e}"));
+        }
+    };
+    drop(s);
+
+    let mut flat = serde_json::Map::new();
+    flatten(&json_value, "", &mut flat);
+    ok(id, &json!({ "settings": flat }))
+}
+
+// ---------------------------------------------------------------------------
+// Mutating ops
+// ---------------------------------------------------------------------------
+
+fn profile_use(id: u64, name: &str, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    if name == s.profiles.effective().name {
+        let body = json!({ "name": name });
+        return ok(id, &body);
+    }
+    match s.profiles.use_profile(name) {
+        Ok(()) => {
+            tracing::info!(name, "profile.use applied");
+            let post = ProfileEffects::profile_used(name).apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &json!({ "name": name }))
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn profile_reload(id: u64, state: &SharedState) -> Response {
+    match execute_reload(state) {
+        Ok(report) => ok(
+            id,
+            &json!({ "reloaded": report.loaded, "warnings": report.warnings }),
+        ),
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+/// scan disk, publish events, push fresh DSP configs to the filter.
+/// used by [`Op::ProfileReload`] and the file-watcher.
+///
+/// # Errors
+/// fatal disk I/O from [`ProfileStore::reload`].
+pub(crate) fn execute_reload(
+    state: &SharedState,
+) -> Result<crate::profile_store::ReloadReport, StoreError> {
+    let mut s = state.lock();
+    let report = s.profiles.reload()?;
+    tracing::info!(
+        loaded = report.loaded.len(),
+        warnings = report.warnings.len(),
+        "profile reload applied"
+    );
+    for w in &report.warnings {
+        tracing::warn!(warning = %w, "profile reload warning");
+    }
+    let post = ProfileEffects::profile_reloaded(report.loaded.clone()).apply(&mut s);
+    drop(s);
+    post.finish();
+    Ok(report)
+}
+
+fn route_set(id: u64, app: &str, to: Route, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.set_route(app, to) {
+        Ok(()) => {
+            tracing::info!(app, ?to, "route.set applied");
+            let post = ProfileEffects::route_rule_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn route_unset(id: u64, app: &str, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.unset_route(app) {
+        Ok(()) => {
+            tracing::info!(app, "route.unset applied");
+            let post = ProfileEffects::route_rule_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn setting_set(id: u64, key: &str, value: Value, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.set_setting(key, value) {
+        Ok(()) => {
+            tracing::info!(key, "setting.set applied");
+            let post = ProfileEffects::settings_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn setting_clear(id: u64, key: &str, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.clear_setting(key) {
+        Ok(existed) => {
+            tracing::info!(key, existed, "setting.clear applied");
+            let post = ProfileEffects::settings_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &json!({ "key": key, "cleared": existed }))
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn setting_reset(id: u64, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.clear_all_settings() {
+        Ok(cleared) => {
+            tracing::info!(cleared, "setting.reset applied");
+            let post = ProfileEffects::settings_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &json!({ "cleared": cleared }))
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn route_stream(id: u64, node_id: u32, to: Route, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    let Some(stream) = s.streams.get_mut(&node_id) else {
+        return err(
+            id,
+            ErrorCode::NotFound,
+            format!("no stream with node_id {node_id} is currently routed by the daemon"),
+        );
+    };
+    let app_label = stream.app.clone();
+    let prior = stream.route;
+    stream.route = to;
+    // record synchronously so `status`/`route.list` reflect it now;
+    // the metadata write is async on the main loop (≤ ~50 ms).
+    let event = Event::new(
+        Topic::Routing,
+        "stream_routed",
+        &json!({ "node_id": node_id, "app": app_label, "to": to.as_str() }),
+    );
+    if let Ok(event) = event {
+        s.broadcaster.publish(Topic::Routing, event);
+    }
+    let tx = s.pw_command_tx.clone();
+    drop(s);
+    if let Some(tx) = tx {
+        if tx
+            .send(PwCommand::RouteStream {
+                node_id,
+                to,
+                app_label: app_label.clone(),
+            })
+            .is_err()
+        {
+            tracing::warn!(
+                node_id,
+                "PipeWire command channel closed; metadata write skipped"
+            );
+        }
+    } else {
+        tracing::debug!(
+            node_id,
+            "no PipeWire command channel; state updated but no metadata write (test mode)"
+        );
+    }
+    tracing::info!(
+        node_id,
+        app = app_label.as_str(),
+        ?prior,
+        new = ?to,
+        "route.stream applied"
+    );
+    ok(id, &Value::Null)
+}
+
+fn bypass_set(id: u64, enabled: bool, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.set_bypass(enabled) {
+        Ok(()) => {
+            tracing::info!(enabled, "bypass.set applied");
+            let post = ProfileEffects::bypass_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Per-app (Layer A) ops
+// ---------------------------------------------------------------------------
+
+fn layer_a_list(id: u64, state: &SharedState) -> Response {
+    let s = state.lock();
+    let mut list: Vec<headroom_ipc::LayerASnapshot> = s.layer_a.values().cloned().collect();
+    drop(s);
+    list.sort_by_key(|snap| snap.node_id);
+    ok(id, &json!({ "layer_a": list }))
+}
+
+fn per_app_set(id: u64, app: &str, enabled: bool, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.set_per_app_enabled(app, enabled) {
+        Ok(()) => {
+            tracing::info!(app, enabled, "per-app.set applied");
+            let post = ProfileEffects::per_app_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn per_app_master(id: u64, enabled: bool, state: &SharedState) -> Response {
+    let mut s = state.lock();
+    match s.profiles.set_per_app_master(enabled) {
+        Ok(()) => {
+            tracing::info!(enabled, "per-app.master applied");
+            let post = ProfileEffects::per_app_changed().apply(&mut s);
+            drop(s);
+            post.finish();
+            ok(id, &Value::Null)
+        }
+        Err(e) => store_err_to_response(id, e),
+    }
+}
+
+fn layer_a_reset(id: u64, node_id: u32, state: &SharedState) -> Response {
+    let s = state.lock();
+    let tx = s.pw_command_tx.clone();
+    drop(s);
+    if let Some(tx) = tx {
+        if tx
+            .send(PwCommand::LayerAResetDeference { node_id })
+            .is_err()
+        {
+            tracing::warn!(
+                node_id,
+                "PipeWire command channel closed; layer-a reset lost"
+            );
+        }
+    } else {
+        tracing::debug!(
+            node_id,
+            "no PipeWire command channel; layer-a reset skipped (test mode)"
+        );
+    }
+    tracing::info!(node_id, "per-app.reset applied");
+    ok(id, &Value::Null)
+}
+
+fn store_err_to_response(id: u64, e: StoreError) -> Response {
+    let code = match &e {
+        StoreError::ProfileNotFound(_)
+        | StoreError::SettingNotFound(_)
+        | StoreError::NoUserRoute(_) => ErrorCode::NotFound,
+        StoreError::SettingInvalid { .. } => ErrorCode::InvalidArgs,
+        StoreError::Io(_) | StoreError::OverlayParse(_) | StoreError::OverlaySerialize(_) => {
+            ErrorCode::Internal
+        }
+    };
+    err(id, code, e.to_string())
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+fn lookup_dotted<'v>(value: &'v Value, key: &str) -> Option<&'v Value> {
+    let mut cur = value;
+    for part in key.split('.') {
+        cur = cur.get(part)?;
+    }
+    Some(cur)
+}
+
+fn flatten(value: &Value, prefix: &str, out: &mut serde_json::Map<String, Value>) {
+    match value {
+        Value::Object(map) => {
+            for (k, v) in map {
+                let next = if prefix.is_empty() {
+                    k.clone()
+                } else {
+                    format!("{prefix}.{k}")
+                };
+                flatten(v, &next, out);
+            }
+        }
+        // arrays + primitives surfaced wholesale at their key prefix;
+        // rule arrays etc. are better read via route.list/profile.show.
+        _ => {
+            out.insert(prefix.to_string(), value.clone());
+        }
+    }
+}
+
+fn ok<T: Serialize>(id: u64, body: &T) -> Response {
+    Response::ok(id, body).unwrap_or_else(|e| {
+        Response::err(
+            id,
+            ProtoError::new(ErrorCode::Internal, format!("serialise reply: {e}")),
+        )
+    })
+}
+
+/// used by the connection handler for subscribe/unsubscribe ops.
+pub(crate) fn ok_value<T: Serialize>(id: u64, body: &T) -> Response {
+    ok(id, body)
+}
+
+fn err(id: u64, code: ErrorCode, msg: impl Into<String>) -> Response {
+    Response::err(id, ProtoError::new(code, msg))
+}
+
+fn not_yet(req: &Request, phase: &str) -> Response {
+    err(
+        req.id,
+        ErrorCode::UnknownOp,
+        format!("op '{}' not implemented yet ({})", req.op.name(), phase),
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod effect_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::profile_store::ProfileStore;
+    use crate::state::{self, RoutedStream};
+    use headroom_ipc::{Op, Request, ResponsePayload, Route};
+
+    fn shared_with_default_profile() -> SharedState {
+        state::shared(crate::state::DaemonState::new(ProfileStore::builtin()))
+    }
+
+    fn extract_ok(resp: Response) -> Value {
+        match resp.payload {
+            ResponsePayload::Ok { result } => result,
+            ResponsePayload::Err { error } => panic!("expected ok, got {error}"),
+        }
+    }
+
+    #[test]
+    fn hello_echoes_daemon_handshake_and_serves_on_mismatch() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::Hello {
+                    protocol: PROTOCOL_VERSION,
+                },
+            ),
+            &state,
+        );
+        let body = extract_ok(resp);
+        assert_eq!(body["daemon"], "headroom");
+        assert_eq!(body["protocol"], PROTOCOL_VERSION);
+        let resp = dispatch(
+            &Request::new(
+                2,
+                Op::Hello {
+                    protocol: PROTOCOL_VERSION + 1,
+                },
+            ),
+            &state,
+        );
+        let body = extract_ok(resp);
+        assert_eq!(body["protocol"], PROTOCOL_VERSION);
+    }
+
+    #[test]
+    fn status_reports_active_profile_and_zero_streams() {
+        let state = shared_with_default_profile();
+        let req = Request::new(1, Op::Status);
+        let resp = dispatch(&req, &state);
+        let body = extract_ok(resp);
+        assert_eq!(body["profile"], "default");
+        assert_eq!(body["bypass"], false);
+        assert_eq!(body["protocol"], PROTOCOL_VERSION);
+        assert!(body["streams"].as_array().unwrap().is_empty());
+        // Builtin store with no overlay → no warnings.
+        assert!(
+            body.get("warnings")
+                .and_then(|w| w.as_array())
+                .is_none_or(|a| a.is_empty()),
+            "expected empty/absent warnings on healthy startup"
+        );
+    }
+
+    #[test]
+    fn status_surfaces_store_warnings() {
+        use crate::profile_store::ProfileStore;
+        use std::fs;
+        use std::time::{SystemTime, UNIX_EPOCH};
+
+        // Build a load-from-disk store with a broken TOML so a warning
+        // is recorded, then point Status at it.
+        let base = std::env::temp_dir().join(format!(
+            "headroom-warntest-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        fs::create_dir_all(base.join("config/profiles")).unwrap();
+        fs::create_dir_all(base.join("state")).unwrap();
+        fs::write(
+            base.join("config/profiles/broken.toml"),
+            "this is not = valid",
+        )
+        .unwrap();
+        let paths = crate::profile_store::StorePaths {
+            config_dir: base.join("config"),
+            state_dir: base.join("state"),
+            share_dirs: vec![],
+            extra_profile_dirs: vec![],
+        };
+        let store = ProfileStore::load(&paths).unwrap();
+        let state = state::shared(crate::state::DaemonState::new(store));
+
+        let resp = dispatch(&Request::new(1, Op::Status), &state);
+        let body = extract_ok(resp);
+        let warnings = body["warnings"].as_array().expect("warnings field");
+        assert!(
+            warnings
+                .iter()
+                .any(|w| w.as_str().unwrap_or("").contains("broken.toml")),
+            "expected warning mentioning broken.toml, got {warnings:?}"
+        );
+
+        let _ = fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn status_surfaces_routed_streams() {
+        let state = shared_with_default_profile();
+        state.lock().streams.insert(
+            42,
+            RoutedStream {
+                node_id: 42,
+                app: "firefox".into(),
+                route: Route::Processed,
+            },
+        );
+        let resp = dispatch(&Request::new(1, Op::Status), &state);
+        let body = extract_ok(resp);
+        let streams = body["streams"].as_array().unwrap();
+        assert_eq!(streams.len(), 1);
+        assert_eq!(streams[0]["app"], "firefox");
+        assert_eq!(streams[0]["route"], "processed");
+    }
+
+    #[test]
+    fn profile_list_returns_active() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(&Request::new(1, Op::ProfileList), &state);
+        let body = extract_ok(resp);
+        let list = body["profiles"].as_array().unwrap();
+        assert_eq!(list.len(), 1);
+        assert_eq!(list[0]["name"], "default");
+        assert_eq!(list[0]["active"], true);
+    }
+
+    #[test]
+    fn profile_show_default_returns_active_profile() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(&Request::new(1, Op::ProfileShow { name: None }), &state);
+        let body = extract_ok(resp);
+        assert_eq!(body["name"], "default");
+    }
+
+    #[test]
+    fn profile_show_unknown_returns_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::ProfileShow {
+                    name: Some("nightclub-mix".into()),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn route_list_returns_profile_rules_and_default_route() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(&Request::new(1, Op::RouteList), &state);
+        let body = extract_ok(resp);
+        // default profile carries the bypass + processed rule sets.
+        let rules = body["rules"].as_array().unwrap();
+        assert_eq!(rules.len(), 2);
+        assert_eq!(body["default_route"], "processed");
+    }
+
+    #[test]
+    fn setting_get_dotted_path() {
+        let state = shared_with_default_profile();
+        let req = Request::new(
+            1,
+            Op::SettingGet {
+                key: "limiter.ceiling_dbtp".into(),
+            },
+        );
+        let resp = dispatch(&req, &state);
+        let body = extract_ok(resp);
+        assert_eq!(body["key"], "limiter.ceiling_dbtp");
+        let v = body["value"].as_f64().unwrap();
+        assert!((v - -0.1).abs() < 1e-6);
+    }
+
+    #[test]
+    fn setting_get_unknown_key_is_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::SettingGet {
+                    key: "completely.not.a.key".into(),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn setting_list_flattens_to_dotted_keys() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(&Request::new(1, Op::SettingList), &state);
+        let body = extract_ok(resp);
+        let settings = body["settings"].as_object().unwrap();
+        assert!(settings.contains_key("agc.target_lufs"));
+        assert!(settings.contains_key("limiter.ceiling_dbtp"));
+        assert!(settings.contains_key("compressor.ratio"));
+    }
+
+    // -----------------------------------------------------------------
+    // 4c mutating ops
+    // -----------------------------------------------------------------
+
+    #[test]
+    fn bypass_set_toggles_flag() {
+        let state = shared_with_default_profile();
+        assert!(!state.lock().profiles.bypass_global());
+
+        dispatch(&Request::new(1, Op::BypassSet { enabled: true }), &state);
+        assert!(state.lock().profiles.bypass_global());
+
+        dispatch(&Request::new(2, Op::BypassSet { enabled: false }), &state);
+        assert!(!state.lock().profiles.bypass_global());
+    }
+
+    #[test]
+    fn route_set_inserts_user_rule_at_top() {
+        let state = shared_with_default_profile();
+        dispatch(
+            &Request::new(
+                1,
+                Op::RouteSet {
+                    app: "obs".into(),
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        let s = state.lock();
+        let rules = &s.profiles.effective().rules;
+        // First rule is now the user-set one.
+        assert_eq!(rules[0].match_.process_binary, vec!["obs".to_string()]);
+        assert_eq!(rules[0].route, Route::Bypass);
+    }
+
+    #[test]
+    fn route_set_replaces_existing_user_rule() {
+        let state = shared_with_default_profile();
+        // First set: bypass.
+        dispatch(
+            &Request::new(
+                1,
+                Op::RouteSet {
+                    app: "obs".into(),
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        // Second set on the same app: processed. Should replace, not stack.
+        dispatch(
+            &Request::new(
+                2,
+                Op::RouteSet {
+                    app: "obs".into(),
+                    to: Route::Processed,
+                },
+            ),
+            &state,
+        );
+        let s = state.lock();
+        let rules = &s.profiles.effective().rules;
+        let user_rules: Vec<_> = rules
+            .iter()
+            .filter(|r| r.match_.process_binary.len() == 1 && r.match_.process_binary[0] == "obs")
+            .collect();
+        assert_eq!(user_rules.len(), 1);
+        assert_eq!(user_rules[0].route, Route::Processed);
+    }
+
+    #[test]
+    fn route_unset_removes_user_rule() {
+        let state = shared_with_default_profile();
+        dispatch(
+            &Request::new(
+                1,
+                Op::RouteSet {
+                    app: "obs".into(),
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        dispatch(
+            &Request::new(2, Op::RouteUnset { app: "obs".into() }),
+            &state,
+        );
+        let s = state.lock();
+        let still_there = s
+            .profiles
+            .effective()
+            .rules
+            .iter()
+            .any(|r| r.match_.process_binary.len() == 1 && r.match_.process_binary[0] == "obs");
+        assert!(!still_there);
+    }
+
+    #[test]
+    fn route_unset_unknown_app_is_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::RouteUnset {
+                    app: "no-such-app".into(),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn route_unset_does_not_remove_shipped_rules() {
+        let state = shared_with_default_profile();
+        // "firefox" is in a shipped multi-app rule; route.unset must
+        // refuse to touch it.
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::RouteUnset {
+                    app: "firefox".into(),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+        // And firefox is still in the rules (via the shipped rule).
+        let s = state.lock();
+        let still_firefox = s
+            .profiles
+            .effective()
+            .rules
+            .iter()
+            .any(|r| r.match_.process_binary.iter().any(|p| p == "firefox"));
+        assert!(still_firefox);
+    }
+
+    #[test]
+    fn setting_set_mutates_value() {
+        let state = shared_with_default_profile();
+        dispatch(
+            &Request::new(
+                1,
+                Op::SettingSet {
+                    key: "limiter.ceiling_dbtp".into(),
+                    value: json!(-1.0),
+                },
+            ),
+            &state,
+        );
+        let v = state.lock().profiles.effective().limiter.ceiling_dbtp;
+        assert!((v - -1.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn setting_set_rejects_wrong_type() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::SettingSet {
+                    key: "limiter.ceiling_dbtp".into(),
+                    value: json!("not a number"),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::InvalidArgs),
+            ResponsePayload::Ok { .. } => panic!("expected InvalidArgs"),
+        }
+        // Profile unchanged.
+        assert!((state.lock().profiles.effective().limiter.ceiling_dbtp - -0.1).abs() < 1e-6);
+    }
+
+    #[test]
+    fn setting_set_unknown_key_is_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::SettingSet {
+                    key: "limiter.does_not_exist".into(),
+                    value: json!(1),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn profile_use_active_is_noop_success() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::ProfileUse {
+                    name: "default".into(),
+                },
+            ),
+            &state,
+        );
+        let body = extract_ok(resp);
+        assert_eq!(body["name"], "default");
+    }
+
+    #[test]
+    fn profile_use_unknown_returns_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::ProfileUse {
+                    name: "night".into(),
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn profile_reload_built_in_only_returns_default() {
+        // Built-in stores have no disk paths; reload returns just the
+        // built-in default and a warning saying there's nothing to scan.
+        let state = shared_with_default_profile();
+        let resp = dispatch(&Request::new(1, Op::ProfileReload), &state);
+        let body = extract_ok(resp);
+        let reloaded = body["reloaded"].as_array().unwrap();
+        assert_eq!(reloaded.len(), 1);
+        assert_eq!(reloaded[0], "default");
+    }
+
+    #[test]
+    fn setting_set_pushes_dsp_update() {
+        use crate::pw::filter::{AudioCmd, FilterControl};
+        let state = shared_with_default_profile();
+        let (control, mut consumer) = FilterControl::for_testing(8);
+        state.lock().filter_control = Some(control);
+
+        dispatch(
+            &Request::new(
+                1,
+                Op::SettingSet {
+                    key: "limiter.ceiling_dbtp".into(),
+                    value: json!(-1.5),
+                },
+            ),
+            &state,
+        );
+
+        // Expect a compressor cmd and a limiter cmd (we push both for
+        // simplicity even when only one field changed).
+        let mut saw_limiter = false;
+        while let Ok(cmd) = consumer.pop() {
+            if let AudioCmd::SetLimiter(cfg) = cmd {
+                assert!((cfg.ceiling_dbtp - -1.5).abs() < 1e-6);
+                saw_limiter = true;
+            }
+        }
+        assert!(saw_limiter, "setting.set should push a SetLimiter cmd");
+    }
+
+    #[test]
+    fn route_set_does_not_push_dsp_update() {
+        // Routing changes don't touch DSP. Filter must be left alone.
+        use crate::pw::filter::FilterControl;
+        let state = shared_with_default_profile();
+        let (control, mut consumer) = FilterControl::for_testing(8);
+        state.lock().filter_control = Some(control);
+
+        dispatch(
+            &Request::new(
+                1,
+                Op::RouteSet {
+                    app: "obs".into(),
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        assert!(consumer.pop().is_err(), "route.set must not push DSP cmds");
+    }
+
+    #[test]
+    fn route_stream_unknown_node_id_returns_not_found() {
+        let state = shared_with_default_profile();
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::RouteStream {
+                    node_id: 9999,
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        match resp.payload {
+            ResponsePayload::Err { error } => assert_eq!(error.code, ErrorCode::NotFound),
+            ResponsePayload::Ok { .. } => panic!("expected NotFound"),
+        }
+    }
+
+    #[test]
+    fn route_stream_updates_state_synchronously() {
+        let state = shared_with_default_profile();
+        // Seed: a known stream currently routed Processed.
+        state.lock().streams.insert(
+            42,
+            RoutedStream {
+                node_id: 42,
+                app: "firefox".into(),
+                route: Route::Processed,
+            },
+        );
+
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::RouteStream {
+                    node_id: 42,
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        assert!(matches!(resp.payload, ResponsePayload::Ok { .. }));
+        assert_eq!(state.lock().streams[&42].route, Route::Bypass);
+    }
+
+    #[test]
+    fn route_stream_pushes_command_when_channel_present() {
+        use crate::pw::command::PwCommand;
+        let state = shared_with_default_profile();
+        let (tx, rx) = crossbeam_channel::unbounded::<PwCommand>();
+        state.lock().pw_command_tx = Some(tx);
+        state.lock().streams.insert(
+            42,
+            RoutedStream {
+                node_id: 42,
+                app: "firefox".into(),
+                route: Route::Processed,
+            },
+        );
+
+        dispatch(
+            &Request::new(
+                1,
+                Op::RouteStream {
+                    node_id: 42,
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        let cmd = rx.try_recv().expect("command should arrive");
+        let PwCommand::RouteStream {
+            node_id,
+            to,
+            app_label,
+        } = cmd
+        else {
+            panic!("expected RouteStream, got {cmd:?}");
+        };
+        assert_eq!(node_id, 42);
+        assert_eq!(to, Route::Bypass);
+        assert_eq!(app_label, "firefox");
+    }
+
+    #[test]
+    fn route_stream_no_channel_is_still_success() {
+        // Tests / pre-PipeWire startup: no tx is fine, state still
+        // updates and the op returns Ok.
+        let state = shared_with_default_profile();
+        state.lock().streams.insert(
+            42,
+            RoutedStream {
+                node_id: 42,
+                app: "mpv".into(),
+                route: Route::Processed,
+            },
+        );
+        let resp = dispatch(
+            &Request::new(
+                1,
+                Op::RouteStream {
+                    node_id: 42,
+                    to: Route::Bypass,
+                },
+            ),
+            &state,
+        );
+        assert!(matches!(resp.payload, ResponsePayload::Ok { .. }));
+        assert_eq!(state.lock().streams[&42].route, Route::Bypass);
+    }
+}

Added file: crates/headroom-core/src/ipc/ops/effect_tests.rs+433 additions@@ -0,0 +1,433 @@
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crossbeam_channel::Receiver;
+use rtrb::Consumer;
+use serde_json::{json, Value};
+
+use super::*;
+use crate::profile_store::{ProfileStore, StorePaths};
+use crate::pw::command::PwCommand;
+use crate::pw::filter::{AudioCmd, FilterControl};
+use crate::state::{self, SharedState};
+use headroom_ipc::{Op, Request, ResponsePayload, Route, ServerFrame, Topic};
+
+struct TempDir(PathBuf);
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+fn temp_paths() -> (StorePaths, TempDir) {
+    let base = std::env::temp_dir().join(format!(
+        "headroom-ipc-effects-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    ));
+    fs::create_dir_all(base.join("config/profiles")).unwrap();
+    fs::create_dir_all(base.join("state")).unwrap();
+    (
+        StorePaths {
+            config_dir: base.join("config"),
+            state_dir: base.join("state"),
+            share_dirs: vec![],
+            extra_profile_dirs: vec![],
+        },
+        TempDir(base),
+    )
+}
+
+fn shared_with_default_profile() -> SharedState {
+    state::shared(crate::state::DaemonState::new(ProfileStore::builtin()))
+}
+
+fn shared_with_night_profile() -> (SharedState, TempDir) {
+    let (paths, guard) = temp_paths();
+    fs::write(
+        paths.config_dir.join("profiles/night.toml"),
+        r#"
+name = "night"
+description = "night profile"
+[limiter]
+ceiling_dbtp = -2.0
+"#,
+    )
+    .unwrap();
+    let store = ProfileStore::load(&paths).unwrap();
+    (state::shared(crate::state::DaemonState::new(store)), guard)
+}
+
+fn ok(resp: Response) -> Value {
+    match resp.payload {
+        ResponsePayload::Ok { result } => result,
+        ResponsePayload::Err { error } => panic!("expected ok, got {error}"),
+    }
+}
+
+fn attach_filter(state: &SharedState) -> Consumer<AudioCmd> {
+    let (control, consumer) = FilterControl::for_testing(16);
+    state.lock().filter_control = Some(control);
+    consumer
+}
+
+fn attach_pw_commands(state: &SharedState) -> Receiver<PwCommand> {
+    let (tx, rx) = crossbeam_channel::unbounded();
+    state.lock().pw_command_tx = Some(tx);
+    rx
+}
+
+fn attach_events(state: &SharedState, topics: &[Topic]) -> Receiver<ServerFrame> {
+    let (tx, rx) = crossbeam_channel::unbounded();
+    let mut state = state.lock();
+    let id = state.broadcaster.register(tx);
+    state.broadcaster.subscribe(id, topics);
+    rx
+}
+
+fn drain_audio(consumer: &mut Consumer<AudioCmd>) -> Vec<AudioCmd> {
+    let mut out = Vec::new();
+    while let Ok(cmd) = consumer.pop() {
+        out.push(cmd);
+    }
+    out
+}
+
+fn drain_pw(rx: &Receiver<PwCommand>) -> Vec<PwCommand> {
+    rx.try_iter().collect()
+}
+
+fn drain_events(rx: &Receiver<ServerFrame>) -> Vec<headroom_ipc::Event> {
+    rx.try_iter()
+        .filter_map(|frame| match frame {
+            ServerFrame::Event(event) => Some(event),
+            ServerFrame::Response(_) => None,
+        })
+        .collect()
+}
+
+fn setting_set(key: &str, value: Value, state: &SharedState) {
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::SettingSet {
+                key: key.into(),
+                value,
+            },
+        ),
+        state,
+    ));
+}
+
+fn count_reevaluate_all(cmds: &[PwCommand]) -> usize {
+    cmds.iter()
+        .filter(|cmd| matches!(cmd, PwCommand::ReevaluateAll))
+        .count()
+}
+
+fn count_reevaluate_layer_a(cmds: &[PwCommand]) -> usize {
+    cmds.iter()
+        .filter(|cmd| matches!(cmd, PwCommand::ReevaluateLayerA))
+        .count()
+}
+
+fn assert_reevaluate_counts(cmds: &[PwCommand], route: usize, layer_a: usize) {
+    assert_eq!(
+        count_reevaluate_all(cmds),
+        route,
+        "expected {route} route reapply command(s), got {cmds:?}"
+    );
+    assert_eq!(
+        count_reevaluate_layer_a(cmds),
+        layer_a,
+        "expected {layer_a} layer a reapply command(s), got {cmds:?}"
+    );
+}
+
+#[test]
+fn setting_set_agc_enabled_pushes_filter_enable() {
+    let state = shared_with_default_profile();
+    let mut audio = attach_filter(&state);
+
+    setting_set("agc.enabled", json!(false), &state);
+
+    let cmds = drain_audio(&mut audio);
+    assert!(
+        cmds.iter()
+            .any(|cmd| matches!(cmd, AudioCmd::SetAgcEnabled(false))),
+        "expected agc enable update, got {cmds:?}"
+    );
+}
+
+#[test]
+fn setting_set_compressor_enabled_pushes_compressor_config() {
+    let state = shared_with_default_profile();
+    let mut audio = attach_filter(&state);
+
+    setting_set("compressor.enabled", json!(false), &state);
+
+    let cmds = drain_audio(&mut audio);
+    assert!(
+        cmds.iter()
+            .any(|cmd| { matches!(cmd, AudioCmd::SetCompressor(cfg) if !cfg.enabled) }),
+        "expected compressor update, got {cmds:?}"
+    );
+}
+
+#[test]
+fn setting_set_limiter_ceiling_pushes_limiter_config() {
+    let state = shared_with_default_profile();
+    let mut audio = attach_filter(&state);
+
+    setting_set("limiter.ceiling_dbtp", json!(-1.5), &state);
+
+    let cmds = drain_audio(&mut audio);
+    assert!(
+        cmds.iter().any(|cmd| {
+            matches!(cmd, AudioCmd::SetLimiter(cfg) if (cfg.ceiling_dbtp - -1.5).abs() < 1e-6)
+        }),
+        "expected limiter update, got {cmds:?}"
+    );
+}
+
+#[test]
+fn setting_set_default_route_posts_route_reapply() {
+    let state = shared_with_default_profile();
+    let rx = attach_pw_commands(&state);
+
+    setting_set("default_route.route", json!("bypass"), &state);
+
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 1);
+}
+
+#[test]
+fn setting_set_per_app_enabled_posts_layer_a_reapply() {
+    let state = shared_with_default_profile();
+    let rx = attach_pw_commands(&state);
+
+    setting_set("per_app.enabled", json!(false), &state);
+
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 1);
+}
+
+#[test]
+fn setting_clear_posts_route_and_layer_a_reapply() {
+    let state = shared_with_default_profile();
+    setting_set("limiter.ceiling_dbtp", json!(-2.0), &state);
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            2,
+            Op::SettingClear {
+                key: "limiter.ceiling_dbtp".into(),
+            },
+        ),
+        &state,
+    ));
+
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 1);
+}
+
+#[test]
+fn setting_reset_posts_route_and_layer_a_reapply() {
+    let state = shared_with_default_profile();
+    setting_set("limiter.ceiling_dbtp", json!(-2.0), &state);
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(&Request::new(2, Op::SettingReset), &state));
+
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 1);
+}
+
+#[test]
+fn profile_use_posts_dsp_and_reapply() {
+    let (state, _guard) = shared_with_night_profile();
+    let mut audio = attach_filter(&state);
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::ProfileUse {
+                name: "night".into(),
+            },
+        ),
+        &state,
+    ));
+
+    let audio_cmds = drain_audio(&mut audio);
+    let pw_cmds = drain_pw(&rx);
+    assert!(
+        audio_cmds
+            .iter()
+            .any(|cmd| matches!(cmd, AudioCmd::SetLimiter(_))),
+        "expected dsp update, got {audio_cmds:?}"
+    );
+    assert_reevaluate_counts(&pw_cmds, 1, 1);
+}
+
+#[test]
+fn profile_reload_posts_dsp_and_reapply() {
+    let (state, _guard) = shared_with_night_profile();
+    let mut audio = attach_filter(&state);
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(&Request::new(1, Op::ProfileReload), &state));
+
+    let audio_cmds = drain_audio(&mut audio);
+    let pw_cmds = drain_pw(&rx);
+    assert!(
+        audio_cmds
+            .iter()
+            .any(|cmd| matches!(cmd, AudioCmd::SetLimiter(_))),
+        "expected dsp update, got {audio_cmds:?}"
+    );
+    assert_reevaluate_counts(&pw_cmds, 1, 1);
+}
+
+#[test]
+fn bypass_set_posts_route_reapply() {
+    let state = shared_with_default_profile();
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(
+        &Request::new(1, Op::BypassSet { enabled: true }),
+        &state,
+    ));
+
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 0);
+}
+
+#[test]
+fn route_set_and_unset_post_route_reapply() {
+    let state = shared_with_default_profile();
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::RouteSet {
+                app: "obs".into(),
+                to: Route::Bypass,
+            },
+        ),
+        &state,
+    ));
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 0);
+
+    let _ = ok(dispatch(
+        &Request::new(2, Op::RouteUnset { app: "obs".into() }),
+        &state,
+    ));
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 1, 0);
+}
+
+#[test]
+fn per_app_set_and_master_post_layer_a_reapply() {
+    let state = shared_with_default_profile();
+    let rx = attach_pw_commands(&state);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::PerAppSet {
+                app: "discord".into(),
+                enabled: true,
+            },
+        ),
+        &state,
+    ));
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 0, 1);
+
+    let _ = ok(dispatch(
+        &Request::new(2, Op::PerAppMaster { enabled: true }),
+        &state,
+    ));
+    let cmds = drain_pw(&rx);
+    assert_reevaluate_counts(&cmds, 0, 1);
+}
+
+#[test]
+fn profile_use_publishes_used_event() {
+    let (state, _guard) = shared_with_night_profile();
+    let rx = attach_events(&state, &[Topic::Profile]);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::ProfileUse {
+                name: "night".into(),
+            },
+        ),
+        &state,
+    ));
+
+    let events = drain_events(&rx);
+    assert!(
+        events.iter().any(|event| {
+            event.topic == Topic::Profile
+                && event.event == "used"
+                && event.data["name"] == json!("night")
+        }),
+        "expected profile used event, got {events:?}"
+    );
+}
+
+#[test]
+fn profile_reload_publishes_reloaded_event() {
+    let (state, _guard) = shared_with_night_profile();
+    let rx = attach_events(&state, &[Topic::Profile]);
+
+    let _ = ok(dispatch(&Request::new(1, Op::ProfileReload), &state));
+
+    let events = drain_events(&rx);
+    assert!(
+        events.iter().any(|event| {
+            event.topic == Topic::Profile
+                && event.event == "reloaded"
+                && event.data["loaded"]
+                    .as_array()
+                    .is_some_and(|loaded| loaded.iter().any(|name| name == "night"))
+        }),
+        "expected profile reloaded event, got {events:?}"
+    );
+}
+
+#[test]
+fn route_rule_mutations_publish_rule_changed() {
+    let state = shared_with_default_profile();
+    let rx = attach_events(&state, &[Topic::Routing]);
+
+    let _ = ok(dispatch(
+        &Request::new(
+            1,
+            Op::RouteSet {
+                app: "obs".into(),
+                to: Route::Bypass,
+            },
+        ),
+        &state,
+    ));
+
+    let events = drain_events(&rx);
+    assert!(
+        events
+            .iter()
+            .any(|event| event.topic == Topic::Routing && event.event == "rule_changed"),
+        "expected route rule change event, got {events:?}"
+    );
+}

Added file: crates/headroom-core/src/ipc/ops/profile_effects.rs+151 additions@@ -0,0 +1,151 @@
+use serde_json::json;
+
+use headroom_ipc::{Event, Topic};
+
+use crate::pw::command::PwCommand;
+use crate::pw::filter::FilterControl;
+use crate::state::DaemonState;
+
+pub(super) struct ProfileEffects {
+    event: Option<EffectEvent>,
+    dsp: DspEffect,
+    commands: &'static [PwCommand],
+}
+
+enum EffectEvent {
+    ProfileUsed(String),
+    ProfileReloaded(Vec<String>),
+    RouteRuleChanged,
+}
+
+enum DspEffect {
+    None,
+    PushEffective,
+}
+
+pub(super) struct PostProfileEffects {
+    dsp: Option<(FilterControl, DspSnapshot)>,
+}
+
+const ROUTE_REAPPLY: &[PwCommand] = &[PwCommand::ReevaluateAll];
+const LAYER_A_REAPPLY: &[PwCommand] = &[PwCommand::ReevaluateLayerA];
+const ROUTE_AND_LAYER_A_REAPPLY: &[PwCommand] =
+    &[PwCommand::ReevaluateAll, PwCommand::ReevaluateLayerA];
+
+impl ProfileEffects {
+    pub(super) fn profile_used(name: &str) -> Self {
+        Self {
+            event: Some(EffectEvent::ProfileUsed(name.to_owned())),
+            dsp: DspEffect::PushEffective,
+            commands: ROUTE_AND_LAYER_A_REAPPLY,
+        }
+    }
+
+    pub(super) fn profile_reloaded(loaded: Vec<String>) -> Self {
+        Self {
+            event: Some(EffectEvent::ProfileReloaded(loaded)),
+            dsp: DspEffect::PushEffective,
+            commands: ROUTE_AND_LAYER_A_REAPPLY,
+        }
+    }
+
+    pub(super) fn route_rule_changed() -> Self {
+        Self {
+            event: Some(EffectEvent::RouteRuleChanged),
+            dsp: DspEffect::None,
+            commands: ROUTE_REAPPLY,
+        }
+    }
+
+    pub(super) fn settings_changed() -> Self {
+        Self {
+            event: None,
+            dsp: DspEffect::PushEffective,
+            commands: ROUTE_AND_LAYER_A_REAPPLY,
+        }
+    }
+
+    pub(super) fn bypass_changed() -> Self {
+        Self {
+            event: None,
+            dsp: DspEffect::None,
+            commands: ROUTE_REAPPLY,
+        }
+    }
+
+    pub(super) fn per_app_changed() -> Self {
+        Self {
+            event: Some(EffectEvent::RouteRuleChanged),
+            dsp: DspEffect::None,
+            commands: LAYER_A_REAPPLY,
+        }
+    }
+
+    pub(super) fn apply(self, state: &mut DaemonState) -> PostProfileEffects {
+        publish(state, self.event);
+        let dsp = match self.dsp {
+            DspEffect::None => None,
+            DspEffect::PushEffective => state
+                .filter_control
+                .clone()
+                .map(|control| (control, DspSnapshot::from(state))),
+        };
+        for cmd in self.commands {
+            post_command(state, cmd);
+        }
+        PostProfileEffects { dsp }
+    }
+}
+
+impl PostProfileEffects {
+    pub(super) fn finish(self) {
+        if let Some((control, snap)) = self.dsp {
+            control.set_compressor(snap.compressor);
+            control.set_limiter(snap.limiter);
+            control.set_agc_enabled(snap.agc_enabled);
+        }
+    }
+}
+
+fn publish(state: &mut DaemonState, event: Option<EffectEvent>) {
+    let Some(event) = event else { return };
+    let event = match event {
+        EffectEvent::ProfileUsed(name) => {
+            Event::new(Topic::Profile, "used", &json!({ "name": name }))
+        }
+        EffectEvent::ProfileReloaded(loaded) => {
+            Event::new(Topic::Profile, "reloaded", &json!({ "loaded": loaded }))
+        }
+        EffectEvent::RouteRuleChanged => Event::new(Topic::Routing, "rule_changed", &json!({})),
+    };
+    if let Ok(event) = event {
+        state.broadcaster.publish(event.topic, event);
+    }
+}
+
+fn post_command(state: &DaemonState, cmd: &PwCommand) {
+    let Some(tx) = state.pw_command_tx.as_ref() else {
+        tracing::debug!(?cmd, "no PipeWire command channel; profile effect skipped");
+        return;
+    };
+    if tx.send((*cmd).clone()).is_err() {
+        tracing::warn!(?cmd, "PipeWire command channel closed; profile effect lost");
+    }
+}
+
+struct DspSnapshot {
+    compressor: headroom_dsp::CompressorConfig,
+    limiter: headroom_dsp::LimiterConfig,
+    agc_enabled: bool,
+}
+
+impl DspSnapshot {
+    fn from(state: &DaemonState) -> Self {
+        let effective = state.profiles.effective();
+        Self {
+            compressor: effective.build_compressor_config(),
+            limiter: effective.build_limiter_config(),
+            agc_enabled: effective.agc.enabled,
+        }
+    }
+}

Added file: crates/headroom-core/src/ipc/server.rs+306 additions@@ -0,0 +1,306 @@
+//! unix-domain socket listener + accept loop.
+
+use std::os::unix::fs::PermissionsExt;
+use std::os::unix::net::{UnixListener, UnixStream};
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::thread::{self, JoinHandle};
+use std::time::Duration;
+
+use crate::error::DaemonError;
+use crate::ipc::connection::handle_connection;
+use crate::state::SharedState;
+
+/// accept-thread shutdown poll interval.
+const ACCEPT_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// owner-only ($XDG_RUNTIME_DIR/headroom/).
+const SOCKET_DIR_MODE: u32 = 0o700;
+
+/// owner-only — IPC auth is filesystem perms, as PipeWire/Wayland do.
+const SOCKET_MODE: u32 = 0o600;
+
+pub struct IpcServer;
+
+/// drop or [`IpcServerHandle::shutdown`] to stop the server.
+pub struct IpcServerHandle {
+    shutdown: Arc<AtomicBool>,
+    accept_thread: Option<JoinHandle<()>>,
+    socket_path: PathBuf,
+}
+
+impl IpcServer {
+    /// bind a [`UnixListener`] at `socket_path` and spawn the accept
+    /// thread. stale sockets are unlinked; a reachable path means
+    /// another daemon is running → [`DaemonError::Other`].
+    ///
+    /// # Errors
+    /// - [`DaemonError::Io`] for filesystem failures.
+    /// - [`DaemonError::Other`] if another daemon owns the path.
+    pub fn start(
+        socket_path: PathBuf,
+        state: SharedState,
+    ) -> Result<IpcServerHandle, DaemonError> {
+        if let Some(parent) = socket_path.parent() {
+            std::fs::create_dir_all(parent)?;
+            // best-effort: $XDG_RUNTIME_DIR is already user-owned.
+            let _ = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(SOCKET_DIR_MODE));
+        }
+
+        if socket_path.exists() {
+            if UnixStream::connect(&socket_path).is_ok() {
+                return Err(DaemonError::other(format!(
+                    "another headroom daemon is already listening at {}",
+                    socket_path.display()
+                )));
+            }
+            std::fs::remove_file(&socket_path)?;
+            tracing::debug!(path = %socket_path.display(), "removed stale socket");
+        }
+
+        let listener = UnixListener::bind(&socket_path)?;
+        std::fs::set_permissions(&socket_path, std::fs::Permissions::from_mode(SOCKET_MODE))?;
+        listener.set_nonblocking(true)?;
+
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let shutdown_for_thread = shutdown.clone();
+        let state_for_thread = state;
+        let accept_thread = thread::Builder::new()
+            .name("headroom-ipc-accept".into())
+            .spawn(move || accept_loop(listener, state_for_thread, shutdown_for_thread))?;
+
+        tracing::info!(path = %socket_path.display(), "ipc server listening");
+
+        Ok(IpcServerHandle {
+            shutdown,
+            accept_thread: Some(accept_thread),
+            socket_path,
+        })
+    }
+}
+
+impl IpcServerHandle {
+    /// stop + join the accept thread and unlink the socket. idempotent.
+    /// connection threads outlive this; they exit when peers close.
+    pub fn shutdown(&mut self) {
+        self.shutdown.store(true, Ordering::Relaxed);
+        if let Some(t) = self.accept_thread.take() {
+            if let Err(e) = t.join() {
+                tracing::warn!(?e, "ipc accept thread join failed");
+            }
+        }
+        // remove the socket file so the next daemon sees no stale entry.
+        let _ = std::fs::remove_file(&self.socket_path);
+        tracing::info!(path = %self.socket_path.display(), "ipc server stopped");
+    }
+}
+
+impl Drop for IpcServerHandle {
+    fn drop(&mut self) {
+        self.shutdown();
+    }
+}
+
+fn accept_loop(
+    listener: UnixListener,
+    state: SharedState,
+    shutdown: Arc<AtomicBool>,
+) {
+    while !shutdown.load(Ordering::Relaxed) {
+        match listener.accept() {
+            Ok((stream, _addr)) => {
+                // connection threads use blocking I/O.
+                if let Err(e) = stream.set_nonblocking(false) {
+                    tracing::warn!(error = %e, "set_nonblocking(false) failed; dropping conn");
+                    continue;
+                }
+                let shutdown_for_conn = shutdown.clone();
+                let state_for_conn = state.clone();
+                if let Err(e) = thread::Builder::new()
+                    .name("headroom-ipc-conn".into())
+                    .spawn(move || handle_connection(stream, state_for_conn, shutdown_for_conn))
+                {
+                    tracing::warn!(error = %e, "ipc conn spawn failed");
+                }
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+                thread::sleep(ACCEPT_POLL_INTERVAL);
+            }
+            Err(e) => {
+                tracing::error!(error = %e, "ipc accept failed; stopping accept loop");
+                break;
+            }
+        }
+    }
+    tracing::debug!("ipc accept loop exited");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::profile_store::ProfileStore;
+    use crate::state::{self, DaemonState};
+    use headroom_client::Client;
+    use headroom_ipc::Route;
+    use std::process;
+    use std::sync::atomic::AtomicU64;
+
+    static NEXT_TEST_SOCKET: AtomicU64 = AtomicU64::new(0);
+
+    fn temp_socket_path() -> PathBuf {
+        let n = NEXT_TEST_SOCKET.fetch_add(1, Ordering::Relaxed);
+        std::env::temp_dir().join(format!("headroom-test-{}-{}.sock", process::id(), n))
+    }
+
+    fn test_state() -> SharedState {
+        state::shared(DaemonState::new(ProfileStore::builtin()))
+    }
+
+    #[test]
+    fn start_and_shutdown_cleanly() {
+        let path = temp_socket_path();
+        let _ = std::fs::remove_file(&path);
+
+        let mut handle = IpcServer::start(path.clone(), test_state()).expect("server should start");
+        assert!(path.exists(), "socket file should exist while server runs");
+        handle.shutdown();
+        assert!(!path.exists(), "shutdown should unlink the socket");
+    }
+
+    #[test]
+    fn rejects_double_start() {
+        let path = temp_socket_path();
+        let _ = std::fs::remove_file(&path);
+
+        let _first = IpcServer::start(path.clone(), test_state()).expect("first server should start");
+        let second = IpcServer::start(path.clone(), test_state());
+        assert!(
+            second.is_err(),
+            "second server should refuse to take over a live socket"
+        );
+    }
+
+    #[test]
+    fn stale_socket_is_reclaimed() {
+        let path = temp_socket_path();
+        let _ = std::fs::remove_file(&path);
+
+        // Create a "stale" socket file with no listener behind it.
+        {
+            let _l = UnixListener::bind(&path).expect("bind for stale fixture");
+        }
+        // Listener dropped; the file remains but is unreachable.
+
+        let handle = IpcServer::start(path.clone(), test_state());
+        assert!(
+            handle.is_ok(),
+            "should reclaim a stale socket (file present, no listener)"
+        );
+    }
+
+    #[test]
+    fn client_can_status_and_setting_get() {
+        let path = temp_socket_path();
+        let _ = std::fs::remove_file(&path);
+        let _server = IpcServer::start(path.clone(), test_state()).expect("server should start");
+
+        let mut client = Client::connect_at(&path).expect("client connect");
+        let hello = client.hello();
+        assert_eq!(hello.daemon, "headroom");
+        assert_eq!(hello.protocol, headroom_ipc::PROTOCOL_VERSION);
+
+        // Read-only ops land in 4b.
+        let status = client.status().expect("status should succeed");
+        assert_eq!(status.profile, "default");
+        assert_eq!(status.protocol, headroom_ipc::PROTOCOL_VERSION);
+
+        let value = client
+            .setting_get("limiter.ceiling_dbtp")
+            .expect("setting.get should succeed");
+        let n = value.as_f64().unwrap();
+        assert!((n - -0.1).abs() < 1e-6);
+    }
+
+    /// End-to-end through the IPC: load a store with a second profile
+    /// on disk, switch to it via `profile.use`, and confirm that an
+    /// overlay tweak made on the original profile carries across.
+    #[test]
+    fn client_profile_use_preserves_overlay() {
+        use crate::profile_store::{ProfileStore, StorePaths};
+        use std::fs;
+        use std::time::{SystemTime, UNIX_EPOCH};
+
+        let base = std::env::temp_dir().join(format!(
+            "headroom-e2e-{}-{}",
+            process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        let _guard = scopeguard_remove(base.clone());
+        fs::create_dir_all(base.join("config/profiles")).unwrap();
+        fs::create_dir_all(base.join("state")).unwrap();
+        fs::write(
+            base.join("config/profiles/night.toml"),
+            "name = \"night\"\ndescription = \"loud night\"\n[limiter]\nceiling_dbtp = -2.0\n",
+        )
+        .unwrap();
+        let paths = StorePaths {
+            config_dir: base.join("config"),
+            state_dir: base.join("state"),
+            share_dirs: vec![],
+            extra_profile_dirs: vec![],
+        };
+        let store = ProfileStore::load(&paths).expect("store load");
+        let state = state::shared(DaemonState::new(store));
+
+        let sock = temp_socket_path();
+        let _ = std::fs::remove_file(&sock);
+        let _server = IpcServer::start(sock.clone(), state).expect("server should start");
+
+        let mut client = Client::connect_at(&sock).expect("client connect");
+
+        // Apply an overlay tweak while on `default`.
+        client
+            .route_set("obs", Route::Bypass)
+            .expect("route.set obs");
+        client
+            .setting_set("agc.target_lufs", serde_json::json!(-22.0))
+            .expect("setting.set agc.target_lufs");
+
+        // Switch to `night`.
+        let switched_to = client.profile_use("night").expect("profile.use night");
+        assert_eq!(switched_to, "night");
+        let status = client.status().unwrap();
+        assert_eq!(status.profile, "night");
+
+        // Overlay survived: route override is still visible in route.list,
+        // and the setting override still wins over night.toml's value.
+        let routes = client.route_list().unwrap();
+        let user_rule = routes
+            .rules
+            .iter()
+            .find(|r| r.match_.process_binary == vec!["obs".to_string()])
+            .expect("obs override carried across profile switch");
+        assert_eq!(user_rule.route, Route::Bypass);
+
+        let lufs = client.setting_get("agc.target_lufs").unwrap();
+        assert!((lufs.as_f64().unwrap() - -22.0).abs() < 1e-6);
+
+        // night.toml's limiter ceiling shows through where there's no override.
+        let ceiling = client.setting_get("limiter.ceiling_dbtp").unwrap();
+        assert!((ceiling.as_f64().unwrap() - -2.0).abs() < 1e-6);
+    }
+
+    fn scopeguard_remove(path: PathBuf) -> impl Drop {
+        struct Cleanup(PathBuf);
+        impl Drop for Cleanup {
+            fn drop(&mut self) {
+                let _ = std::fs::remove_dir_all(&self.0);
+            }
+        }
+        Cleanup(path)
+    }
+}

Added file: crates/headroom-core/src/lib.rs+36 additions@@ -0,0 +1,36 @@
+//! daemon core: pipewire main loop, filter pipeline, registry, routing, agc, ipc
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+pub mod agc;
+pub mod app_level;
+pub mod error;
+pub mod ipc;
+pub mod meters;
+pub mod profile;
+pub mod profile_store;
+pub mod profile_watcher;
+pub mod pw;
+pub mod routing;
+pub mod runtime;
+pub mod state;
+
+pub use error::DaemonError;
+pub use profile::Profile;
+pub use profile_store::{ProfileStore, StorePaths, StoreError, UserOverlay};
+
+/// blocks until shutdown (SIGTERM/SIGINT) or fatal failure. profiles + overlay from xdg paths.
+pub fn run() -> Result<(), DaemonError> {
+    run_with_profile_dirs(Vec::new())
+}
+
+/// like [`run`] but also scans `extra_profile_dirs` directly for `*.toml` and watches
+/// the first for live edits. backs the daemon's `--profile-dir` flag.
+pub fn run_with_profile_dirs(extra_profile_dirs: Vec<std::path::PathBuf>) -> Result<(), DaemonError> {
+    let mut paths = StorePaths::from_env();
+    paths.extra_profile_dirs = extra_profile_dirs;
+    let store = ProfileStore::load(&paths)
+        .map_err(|e| DaemonError::Profile(format!("loading profiles: {e}")))?;
+    runtime::run(store)
+}

Added file: crates/headroom-core/src/meters.rs+169 additions@@ -0,0 +1,169 @@
+//! bus meter snapshot shared audio-thread → agc; audio side writes via try_lock, never blocks
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use parking_lot::Mutex;
+
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+pub struct BusMetrics {
+    /// negative when reducing
+    pub compressor_gr_db: f32,
+    /// min of soft and hard gain, in dB
+    pub limiter_total_gr_db: f32,
+    pub limiter_soft_gr_db: f32,
+    /// non-zero only when the soft tier wasn't enough — alarm condition
+    pub limiter_hard_gr_db: f32,
+    /// peak the limiter saw on its input (not the bounded output); for tuning soft-tier headroom
+    pub true_peak_dbtp: f32,
+}
+
+pub type SharedBusMetrics = Arc<Mutex<BusMetrics>>;
+
+#[must_use]
+pub fn shared() -> SharedBusMetrics {
+    Arc::new(Mutex::new(BusMetrics::default()))
+}
+
+/// rolling timing stats for the bus filter's `playback_process`; lock-free atomics from the
+/// audio thread, read on the agc tick. detects BUSY spikes + ring imbalance.
+#[derive(Debug, Default)]
+pub struct PlaybackTiming {
+    pub call_count: AtomicU64,
+    pub sum_us: AtomicU64,
+    pub max_us: AtomicU64,
+    pub spike_count: AtomicU64,
+    pub last_spike_us: AtomicU64,
+    /// `call_count` when the last spike fired; reader compares against its prior snapshot
+    pub last_spike_at_call: AtomicU64,
+    /// samples zero-filled because the capture→playback ring was empty. non-zero delta = bug
+    /// (producer/consumer not lined up within a quantum → audible drop-outs).
+    pub samples_starved: AtomicU64,
+    /// samples dropped because the ring was full; mirror of `samples_starved` (ring imbalance)
+    pub samples_dropped: AtomicU64,
+    /// short/misaligned rt buffers; logged off-thread
+    pub format_errors: AtomicU64,
+}
+
+impl PlaybackTiming {
+    /// steady-state cost scales with quantum (~240 μs @ 1024 frames, ~2.2 ms @ 8192 release);
+    /// 5 ms sits above both, fires only on real outliers.
+    pub const SPIKE_THRESHOLD_US: u64 = 5_000;
+
+    #[inline]
+    pub fn record(&self, dur_us: u64) {
+        self.call_count.fetch_add(1, Ordering::Relaxed);
+        self.sum_us.fetch_add(dur_us, Ordering::Relaxed);
+        let mut cur_max = self.max_us.load(Ordering::Relaxed);
+        while dur_us > cur_max {
+            match self.max_us.compare_exchange_weak(
+                cur_max,
+                dur_us,
+                Ordering::Relaxed,
+                Ordering::Relaxed,
+            ) {
+                Ok(_) => break,
+                Err(v) => cur_max = v,
+            }
+        }
+        if dur_us > Self::SPIKE_THRESHOLD_US {
+            let count = self.call_count.load(Ordering::Relaxed);
+            self.spike_count.fetch_add(1, Ordering::Relaxed);
+            self.last_spike_us.store(dur_us, Ordering::Relaxed);
+            self.last_spike_at_call.store(count, Ordering::Relaxed);
+        }
+    }
+
+    #[inline]
+    pub fn record_starved(&self, n: u64) {
+        if n > 0 {
+            self.samples_starved.fetch_add(n, Ordering::Relaxed);
+        }
+    }
+
+    #[inline]
+    pub fn record_dropped(&self, n: u64) {
+        if n > 0 {
+            self.samples_dropped.fetch_add(n, Ordering::Relaxed);
+        }
+    }
+
+    #[inline]
+    pub fn record_format_error(&self) {
+        self.format_errors.fetch_add(1, Ordering::Relaxed);
+    }
+
+    pub fn snapshot(&self) -> PlaybackTimingSnapshot {
+        PlaybackTimingSnapshot {
+            call_count: self.call_count.load(Ordering::Relaxed),
+            sum_us: self.sum_us.load(Ordering::Relaxed),
+            max_us: self.max_us.load(Ordering::Relaxed),
+            spike_count: self.spike_count.load(Ordering::Relaxed),
+            last_spike_us: self.last_spike_us.load(Ordering::Relaxed),
+            last_spike_at_call: self.last_spike_at_call.load(Ordering::Relaxed),
+            samples_starved: self.samples_starved.load(Ordering::Relaxed),
+            samples_dropped: self.samples_dropped.load(Ordering::Relaxed),
+            format_errors: self.format_errors.load(Ordering::Relaxed),
+        }
+    }
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+pub struct PlaybackTimingSnapshot {
+    pub call_count: u64,
+    pub sum_us: u64,
+    pub max_us: u64,
+    pub spike_count: u64,
+    pub last_spike_us: u64,
+    pub last_spike_at_call: u64,
+    pub samples_starved: u64,
+    pub samples_dropped: u64,
+    pub format_errors: u64,
+}
+
+pub type SharedPlaybackTiming = Arc<PlaybackTiming>;
+
+#[must_use]
+pub fn shared_timing() -> SharedPlaybackTiming {
+    Arc::new(PlaybackTiming::default())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_is_all_zero() {
+        let m = BusMetrics::default();
+        assert_eq!(m.compressor_gr_db, 0.0);
+        assert_eq!(m.limiter_total_gr_db, 0.0);
+        assert_eq!(m.limiter_soft_gr_db, 0.0);
+        assert_eq!(m.limiter_hard_gr_db, 0.0);
+        assert_eq!(m.true_peak_dbtp, 0.0);
+    }
+
+    #[test]
+    fn record_format_error_accumulates_in_snapshot() {
+        let t = PlaybackTiming::default();
+        assert_eq!(t.snapshot().format_errors, 0);
+        t.record_format_error();
+        t.record_format_error();
+        assert_eq!(t.snapshot().format_errors, 2);
+    }
+
+    #[test]
+    fn shared_is_cheap_to_clone() {
+        let a = shared();
+        let b = a.clone();
+        *a.lock() = BusMetrics {
+            compressor_gr_db: -3.0,
+            limiter_total_gr_db: -1.0,
+            limiter_soft_gr_db: -1.0,
+            limiter_hard_gr_db: 0.0,
+            true_peak_dbtp: -0.5,
+        };
+        let snap = *b.lock();
+        assert!((snap.compressor_gr_db - -3.0).abs() < 1e-6);
+        assert!((snap.true_peak_dbtp - -0.5).abs() < 1e-6);
+    }
+}

Added file: crates/headroom-core/src/pw/command.rs+36 additions@@ -0,0 +1,36 @@
+//! cross-thread command channel from IPC handlers to the pipewire main loop.
+//!
+//! pipewire proxies are tied to the loop's thread; IPC handlers post a
+//! [`PwCommand`] drained by a 50 ms timer source instead. ~50 ms
+//! worst-case dispatch — do NOT route anything spike-reactive here
+//! (Layer A `channelVolumes`, rt gain reduction); that breaks the §4.5
+//! reaction-time contract. filter DSP updates bypass this via
+//! [`crate::pw::filter::FilterControl`]'s wait-free rtrb.
+
+use headroom_ipc::Route;
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub enum PwCommand {
+    /// set `target.object` for one stream, overriding the routing rule.
+    RouteStream {
+        node_id: u32,
+        to: Route,
+        app_label: String,
+    },
+    /// re-run `routing::evaluate` against every known stream. stale post harmless.
+    ReevaluateAll,
+    /// rebuild the bus filter at a new rate. posted when the real sink's
+    /// Format listener sees a rate the filter isn't running at (ALSA
+    /// sinks publish rate only via Format, not the props dict → initial
+    /// filter is at fallback rate; also sink hot-swap). ~50–100 ms gap.
+    RebuildFilter {
+        sample_rate: u32,
+    },
+    /// reconcile Layer A taps against `[per_app]`. stale post harmless.
+    ReevaluateLayerA,
+    /// clear a managed stream's deference (user-ceiling / strict lock).
+    LayerAResetDeference {
+        node_id: u32,
+    },
+}

Added file: crates/headroom-core/src/pw/filter.rs+728 additions@@ -0,0 +1,728 @@
+//! the bus filter: a single `pw_filter` node sandwiching the DSP chain.
+
+use std::sync::Arc;
+
+use parking_lot::Mutex;
+use pipewire::{
+    core::Core,
+    keys,
+    properties::properties,
+    spa::{pod::Pod, utils::Direction},
+};
+use pipewire_filter::{Filter as PwFilter, FilterFlags, FilterListener, PortData, PortFlags};
+use rtrb::{Consumer, Producer, RingBuffer};
+
+use headroom_dsp::{
+    AgcGain, AgcGainConfig, Compressor, CompressorConfig, Limiter, LimiterConfig, SetConfigOutcome,
+};
+
+use crate::error::DaemonError;
+use crate::meters::{BusMetrics, SharedBusMetrics, SharedPlaybackTiming};
+
+/// `node.name` the routing engine looks for to wire the explicit
+/// monitor → input and output → real-sink links — wireplumber does
+/// not auto-link `pw_filter` nodes.
+pub const NODE_NAME: &str = "headroom-filter";
+
+/// rate used until a real sink is known; [`Filter::create`] overrides
+/// it from the captured real-sink rate.
+pub const DEFAULT_SAMPLE_RATE: u32 = 48_000;
+
+/// back-compat alias for out-of-tree code.
+pub const FILTER_SAMPLE_RATE: u32 = DEFAULT_SAMPLE_RATE;
+
+/// stereo only in v0.
+pub const CHANNELS: u32 = 2;
+
+const CMD_RING_CAPACITY: usize = 32;
+
+/// audio→AGC measurement ring, interleaved f32. several controller
+/// ticks of slack so a stalled controller doesn't drop coverage.
+const MEASUREMENT_RING_CAPACITY: usize = 32_768;
+
+/// control-plane param updates to the rt audio thread. structural
+/// limiter changes (oversample, lookahead) can't apply live — see
+/// [`headroom_dsp::SetConfigOutcome::StructuralChange`].
+#[derive(Debug, Clone, Copy)]
+pub enum AudioCmd {
+    SetCompressor(CompressorConfig),
+    SetLimiter(LimiterConfig),
+    /// AGC target dB, pushed by the slow controller each tick.
+    SetAgcTargetDb(f32),
+    /// toggle AGC; when disabled the smoother unwinds to 0 dB.
+    SetAgcEnabled(bool),
+    SetAgcConfig(AgcGainConfig),
+    /// limiter soft-ceiling program loudness; `None` resets
+    SetProgramLoudnessLufs(Option<f32>),
+}
+
+/// cheap-to-clone handle for pushing [`AudioCmd`]s into the running
+/// filter. held in `DaemonState` so any IPC thread can update params.
+#[derive(Clone)]
+pub struct FilterControl {
+    cmd_producer: Arc<Mutex<Producer<AudioCmd>>>,
+}
+
+impl FilterControl {
+    /// `false` (and a warn) if the ring is full; the command is dropped.
+    pub fn try_send(&self, cmd: AudioCmd) -> bool {
+        match self.cmd_producer.lock().push(cmd) {
+            Ok(()) => true,
+            Err(_) => {
+                tracing::warn!(
+                    "filter command ring full; dropping parameter update — \
+                     audio thread may be stalled or commands arriving faster than the quantum"
+                );
+                false
+            }
+        }
+    }
+
+    pub fn set_compressor(&self, cfg: CompressorConfig) -> bool {
+        self.try_send(AudioCmd::SetCompressor(cfg))
+    }
+
+    pub fn set_limiter(&self, cfg: LimiterConfig) -> bool {
+        self.try_send(AudioCmd::SetLimiter(cfg))
+    }
+
+    pub fn set_agc_target_db(&self, db: f32) -> bool {
+        self.try_send(AudioCmd::SetAgcTargetDb(db))
+    }
+
+    pub fn set_agc_enabled(&self, enabled: bool) -> bool {
+        self.try_send(AudioCmd::SetAgcEnabled(enabled))
+    }
+
+    pub fn set_agc_config(&self, cfg: AgcGainConfig) -> bool {
+        self.try_send(AudioCmd::SetAgcConfig(cfg))
+    }
+
+    pub fn set_program_loudness_lufs(&self, lufs: Option<f32>) -> bool {
+        self.try_send(AudioCmd::SetProgramLoudnessLufs(lufs))
+    }
+}
+
+impl std::fmt::Debug for FilterControl {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("FilterControl").finish_non_exhaustive()
+    }
+}
+
+#[cfg(test)]
+impl FilterControl {
+    pub(crate) fn for_testing(capacity: usize) -> (Self, Consumer<AudioCmd>) {
+        let (producer, consumer) = RingBuffer::<AudioCmd>::new(capacity);
+        (
+            Self {
+                cmd_producer: Arc::new(Mutex::new(producer)),
+            },
+            consumer,
+        )
+    }
+}
+
+/// user-data carried into the rt process callback. ports are mono
+/// (`format.dsp = "32 bit float mono audio"`), one per channel per
+/// direction — canonical `pw_filter` shape; explicit links pair
+/// FL/FR port-by-port.
+struct FilterState {
+    in_l: PortData,
+    in_r: PortData,
+    out_l: PortData,
+    out_r: PortData,
+    cmd_consumer: Consumer<AudioCmd>,
+    /// pre-AGC input samples for the slow AGC. over-capacity dropped
+    /// silently (controller tolerates gaps).
+    measurement_producer: Producer<f32>,
+    agc: AgcGain,
+    compressor: Compressor,
+    limiter: Limiter,
+    measurement_dropped: u64,
+    bus_metrics: SharedBusMetrics,
+    timing: SharedPlaybackTiming,
+}
+
+/// owns the `pw_filter` node + listener; drop tears down the audio
+/// path. drop order is listener-first, filter-second (field order),
+/// required by the `pipewire-filter` wrapper.
+pub struct Filter {
+    _listener: FilterListener<FilterState>,
+    _filter: PwFilter,
+}
+
+/// initial DSP config for [`Filter::create`].
+#[derive(Debug, Clone, Copy)]
+pub struct FilterInit {
+    pub compressor: CompressorConfig,
+    pub limiter: LimiterConfig,
+    pub agc: AgcGainConfig,
+    pub agc_enabled: bool,
+}
+
+pub struct FilterBundle {
+    pub filter: Filter,
+    pub control: FilterControl,
+    pub measurement_consumer: Consumer<f32>,
+    pub bus_metrics: SharedBusMetrics,
+    pub timing: SharedPlaybackTiming,
+    /// rate the filter runs at — captured from the real sink, or
+    /// [`DEFAULT_SAMPLE_RATE`] if none known yet.
+    pub sample_rate: u32,
+}
+
+impl Filter {
+    /// create the node, add four mono ports, register the rt callback,
+    /// and connect.
+    ///
+    /// wireplumber does *not* auto-link `pw_filter` nodes; the routing
+    /// layer builds the `processed.monitor → filter.in.*` and
+    /// `filter.out.* → real_sink` links explicitly. filter sits in
+    /// `Paused` until both land.
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] on filter/port/connect failure.
+    pub fn create(
+        core: &Core,
+        init: FilterInit,
+        sample_rate: u32,
+    ) -> Result<FilterBundle, DaemonError> {
+        let (cmd_producer, cmd_consumer) = RingBuffer::<AudioCmd>::new(CMD_RING_CAPACITY);
+        let (measurement_producer, measurement_consumer) =
+            RingBuffer::<f32>::new(MEASUREMENT_RING_CAPACITY);
+        let control = FilterControl {
+            cmd_producer: Arc::new(Mutex::new(cmd_producer)),
+        };
+        let bus_metrics = crate::meters::shared();
+        let timing = crate::meters::shared_timing();
+
+        // caps the internal (post-oversample) rate: 96 kHz base + 4×
+        // auto-drops to 2× → 192 kHz internal, not 384 kHz. bounds FIR
+        // cost at higher real-sink rates.
+        let limiter_cfg = init.limiter.sanitize_for_rate(sample_rate as f32);
+        let compressor = Compressor::new(init.compressor, sample_rate as f32);
+        let limiter = Limiter::new(limiter_cfg, sample_rate as f32);
+        let mut agc = AgcGain::new(init.agc, sample_rate as f32);
+        agc.set_enabled(init.agc_enabled);
+
+        let filter = build_filter(core)?;
+
+        let in_l = add_mono_port(&filter, Direction::Input, "input_FL", "FL")?;
+        let in_r = add_mono_port(&filter, Direction::Input, "input_FR", "FR")?;
+        let out_l = add_mono_port(&filter, Direction::Output, "output_FL", "FL")?;
+        let out_r = add_mono_port(&filter, Direction::Output, "output_FR", "FR")?;
+
+        let listener = filter
+            .add_local_listener_with_user_data(FilterState {
+                in_l,
+                in_r,
+                out_l,
+                out_r,
+                cmd_consumer,
+                measurement_producer,
+                agc,
+                compressor,
+                limiter,
+                measurement_dropped: 0,
+                bus_metrics: bus_metrics.clone(),
+                timing: timing.clone(),
+            })
+            .process(|state, _position| process(state))
+            .register()
+            .map_err(|e| DaemonError::pipewire(format!("filter listener register: {e}")))?;
+
+        // no top-level params; per-port `format.dsp` declares mono F32.
+        let mut connect_params: [&Pod; 0] = [];
+        filter
+            .connect(FilterFlags::RT_PROCESS, &mut connect_params)
+            .map_err(|e| DaemonError::pipewire(format!("filter connect: {e}")))?;
+
+        tracing::info!(
+            sample_rate,
+            channels = CHANNELS,
+            "bus filter (pw_filter) created and connected"
+        );
+
+        Ok(FilterBundle {
+            filter: Self {
+                _listener: listener,
+                _filter: filter,
+            },
+            control,
+            measurement_consumer,
+            bus_metrics,
+            timing,
+            sample_rate,
+        })
+    }
+}
+
+/// add a mono DSP port. `channel` is `audio.channel` ("FL"/"FR"),
+/// which the routing engine pairs on. `format.dsp` declares the
+/// format up-front so no SPA POD.
+fn add_mono_port(
+    filter: &PwFilter,
+    direction: Direction,
+    port_name: &str,
+    channel: &str,
+) -> Result<PortData, DaemonError> {
+    let props = properties! {
+        *keys::FORMAT_DSP => "32 bit float mono audio",
+        *keys::PORT_NAME => port_name,
+        *keys::AUDIO_CHANNEL => channel,
+    };
+    let mut params: [&Pod; 0] = [];
+    filter
+        .add_port(direction, PortFlags::MAP_BUFFERS, props, &mut params)
+        .map_err(|e| DaemonError::pipewire(format!("filter add_port ({port_name}): {e}")))
+}
+
+/// kept from the dual-stream era so external policy that special-cased
+/// it still applies.
+const FILTER_LINK_GROUP: &str = "headroom.filter";
+
+/// latency target; pipewire rounds up to `max(this, driver_quantum)`.
+/// small value avoids the ~250 ms pipewire picks when unset.
+const NODE_LATENCY_HINT: &str = "256/48000";
+
+fn build_filter(core: &Core) -> Result<PwFilter, DaemonError> {
+    let props = properties! {
+        *keys::MEDIA_TYPE => "Audio",
+        *keys::MEDIA_ROLE => "DSP",
+        *keys::NODE_NAME => NODE_NAME,
+        *keys::NODE_DESCRIPTION => "Headroom bus filter",
+        // we own our linking; routing must not move us, wireplumber
+        // must not re-target us on default-sink changes.
+        *keys::NODE_DONT_RECONNECT => "true",
+        "node.dont-move" => "true",
+        "node.link-group" => FILTER_LINK_GROUP,
+        // the real sink drives, not us.
+        "node.passive" => "false",
+        *keys::NODE_LATENCY => NODE_LATENCY_HINT,
+    };
+    PwFilter::new(core, NODE_NAME, props)
+        .map_err(|e| DaemonError::pipewire(format!("pw_filter new: {e}")))
+}
+
+/// apply one [`AudioCmd`] to the DSP kernels. allocation-free.
+fn apply_audio_cmd(
+    cmd: AudioCmd,
+    compressor: &mut Compressor,
+    limiter: &mut Limiter,
+    agc: &mut AgcGain,
+) {
+    match cmd {
+        AudioCmd::SetCompressor(cfg) => {
+            compressor.set_config(cfg);
+        }
+        AudioCmd::SetLimiter(cfg) => match limiter.try_set_config(cfg) {
+            SetConfigOutcome::Applied => {}
+            SetConfigOutcome::StructuralChange => {
+                tracing::warn!(
+                    "limiter structural change (oversample / lookahead / fir_taps) cannot be \
+                     applied live; daemon restart required to pick up the new value"
+                );
+            }
+        },
+        AudioCmd::SetAgcTargetDb(db) => {
+            agc.set_target_db(db);
+        }
+        AudioCmd::SetAgcEnabled(enabled) => {
+            agc.set_enabled(enabled);
+        }
+        AudioCmd::SetAgcConfig(cfg) => {
+            agc.set_config(cfg);
+        }
+        AudioCmd::SetProgramLoudnessLufs(Some(lufs)) => {
+            limiter.set_program_loudness_lufs(lufs);
+        }
+        AudioCmd::SetProgramLoudnessLufs(None) => {
+            limiter.clear_program_loudness();
+        }
+    }
+}
+
+/// drain control-plane param updates into the DSP kernels. allocation-free.
+fn drain_audio_commands(state: &mut FilterState) {
+    while let Ok(cmd) = state.cmd_consumer.pop() {
+        apply_audio_cmd(
+            cmd,
+            &mut state.compressor,
+            &mut state.limiter,
+            &mut state.agc,
+        );
+    }
+}
+
+/// rt process callback. allocation-free, guarded by `assert_no_alloc`
+/// in debug builds. timed into [`PlaybackTiming`].
+fn process(state: &mut FilterState) {
+    let start = std::time::Instant::now();
+    assert_no_alloc::assert_no_alloc(|| process_inner(state));
+    let dur_us = start.elapsed().as_micros() as u64;
+    state.timing.record(dur_us);
+}
+
+fn process_inner(state: &mut FilterState) {
+    drain_audio_commands(state);
+
+    // any missing buffer this quantum: bail, pipewire re-fires us.
+    let Some(mut in_l_buf) = state.in_l.dequeue_buffer() else {
+        return;
+    };
+    let Some(mut in_r_buf) = state.in_r.dequeue_buffer() else {
+        return;
+    };
+    let Some(mut out_l_buf) = state.out_l.dequeue_buffer() else {
+        return;
+    };
+    let Some(mut out_r_buf) = state.out_r.dequeue_buffer() else {
+        return;
+    };
+
+    let sample_bytes = std::mem::size_of::<f32>();
+
+    let in_l_samples = match read_mono_input(in_l_buf.datas_mut(), &state.timing) {
+        Some(s) => s,
+        None => return,
+    };
+    let in_r_samples = match read_mono_input(in_r_buf.datas_mut(), &state.timing) {
+        Some(s) => s,
+        None => return,
+    };
+    let in_frames = in_l_samples.len().min(in_r_samples.len());
+    if in_frames == 0 {
+        return;
+    }
+
+    let out_l_datas = out_l_buf.datas_mut();
+    let Some(out_l_data) = out_l_datas.first_mut() else {
+        return;
+    };
+    let Some(out_l_bytes) = out_l_data.data() else {
+        return;
+    };
+    let out_l_max = out_l_bytes.len() / sample_bytes;
+
+    let out_r_datas = out_r_buf.datas_mut();
+    let Some(out_r_data) = out_r_datas.first_mut() else {
+        return;
+    };
+    let Some(out_r_bytes) = out_r_data.data() else {
+        return;
+    };
+    let out_r_max = out_r_bytes.len() / sample_bytes;
+
+    let frames = in_frames.min(out_l_max).min(out_r_max);
+    if frames == 0 {
+        return;
+    }
+
+    // rt cast failures are logged off-thread
+    let out_l_samples: &mut [f32] =
+        match bytemuck::try_cast_slice_mut::<u8, f32>(&mut out_l_bytes[..frames * sample_bytes]) {
+            Ok(s) => s,
+            Err(_) => {
+                state.timing.record_format_error();
+                return;
+            }
+        };
+    let out_r_samples: &mut [f32] =
+        match bytemuck::try_cast_slice_mut::<u8, f32>(&mut out_r_bytes[..frames * sample_bytes]) {
+            Ok(s) => s,
+            Err(_) => {
+                state.timing.record_format_error();
+                return;
+            }
+        };
+
+    let measurement_dropped = push_measurements(
+        &mut state.measurement_producer,
+        in_l_samples,
+        in_r_samples,
+        frames,
+    );
+    for frame_idx in 0..frames {
+        let left_in = in_l_samples[frame_idx];
+        let right_in = in_r_samples[frame_idx];
+        let (la, ra) = state.agc.process_frame(left_in, right_in);
+        let (lc, rc) = state.compressor.process_frame(la, ra);
+        let (lo, ro) = state.limiter.process_frame(lc, rc);
+        out_l_samples[frame_idx] = lo;
+        out_r_samples[frame_idx] = ro;
+    }
+    if measurement_dropped > 0 {
+        state.measurement_dropped = state
+            .measurement_dropped
+            .saturating_add(measurement_dropped);
+    }
+
+    // `frames < in_frames` shouldn't happen (output maxsize is sized
+    // by `clock.quantum-limit` ≫ typical quanta); recorded as a
+    // regression signal.
+    if frames < in_frames {
+        let dropped_frames = in_frames - frames;
+        state
+            .timing
+            .record_dropped((dropped_frames * CHANNELS as usize) as u64);
+    }
+
+    // `try_lock` so we never block on a daemon-thread reader; a
+    // contended quantum drops this update, next one lands.
+    if frames > 0 {
+        if let Some(mut metrics) = state.bus_metrics.try_lock() {
+            *metrics = BusMetrics {
+                compressor_gr_db: state.compressor.gain_reduction_db(),
+                limiter_total_gr_db: state.limiter.gain_reduction_db(),
+                limiter_soft_gr_db: state.limiter.soft_gain_reduction_db(),
+                limiter_hard_gr_db: state.limiter.hard_gain_reduction_db(),
+                true_peak_dbtp: state.limiter.true_peak_dbtp(),
+            };
+        }
+    }
+
+    for chunk_data in [out_l_data, out_r_data] {
+        let chunk = chunk_data.chunk_mut();
+        *chunk.size_mut() = (frames * sample_bytes) as u32;
+        *chunk.stride_mut() = sample_bytes as i32;
+        *chunk.offset_mut() = 0;
+    }
+}
+
+/// Feed the slow AGC in one ring reservation per callback. If the
+/// controller is behind, keep the prefix that fits and drop the tail;
+/// gaps are acceptable for loudness tracking and this never blocks.
+fn push_measurements(
+    producer: &mut Producer<f32>,
+    left: &[f32],
+    right: &[f32],
+    frames: usize,
+) -> u64 {
+    let requested = frames.saturating_mul(CHANNELS as usize);
+    if requested == 0 {
+        return 0;
+    }
+    let writable = match producer.write_chunk(requested) {
+        Ok(chunk) => {
+            fill_measurement_chunk(chunk, left, right);
+            return 0;
+        }
+        Err(rtrb::chunks::ChunkError::TooFewSlots(slots)) => slots & !(CHANNELS as usize - 1),
+    };
+    if writable == 0 {
+        return requested as u64;
+    }
+    match producer.write_chunk(writable) {
+        Ok(chunk) => {
+            fill_measurement_chunk(chunk, left, right);
+            (requested - writable) as u64
+        }
+        Err(_) => requested as u64,
+    }
+}
+
+fn fill_measurement_chunk(
+    mut chunk: rtrb::chunks::WriteChunk<'_, f32>,
+    left: &[f32],
+    right: &[f32],
+) {
+    let mut sample_idx = 0;
+    let (first, second) = chunk.as_mut_slices();
+    sample_idx = fill_measurement_slice(first, sample_idx, left, right);
+    let _ = fill_measurement_slice(second, sample_idx, left, right);
+    chunk.commit_all();
+}
+
+fn fill_measurement_slice(
+    dst: &mut [f32],
+    mut sample_idx: usize,
+    left: &[f32],
+    right: &[f32],
+) -> usize {
+    for slot in dst {
+        let frame_idx = sample_idx / CHANNELS as usize;
+        let sample = if sample_idx % CHANNELS as usize == 0 {
+            left[frame_idx]
+        } else {
+            right[frame_idx]
+        };
+        *slot = sample;
+        sample_idx += 1;
+    }
+    sample_idx
+}
+
+/// mono input data as f32 samples; misalignment is counted off-thread
+fn read_mono_input<'a>(
+    datas: &'a mut [libspa::buffer::Data],
+    timing: &SharedPlaybackTiming,
+) -> Option<&'a [f32]> {
+    let data = datas.first_mut()?;
+    let n_bytes = data.chunk().size() as usize;
+    if n_bytes == 0 {
+        return None;
+    }
+    let bytes = data.data()?;
+    let n = n_bytes.min(bytes.len());
+    match bytemuck::try_cast_slice::<u8, f32>(&bytes[..n]) {
+        Ok(s) => Some(s),
+        Err(_) => {
+            timing.record_format_error();
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    //! audio-thread leg (apply_audio_cmd) + control-side send leg
+    //! (FilterControl); pw_filter halves need a running PipeWire.
+
+    use super::*;
+    use headroom_dsp::{
+        AgcGain, AgcGainConfig, Compressor, CompressorConfig, Limiter, LimiterConfig,
+        SoftTierConfig,
+    };
+
+    const SR: f32 = 48_000.0;
+
+    #[test]
+    fn apply_audio_cmd_updates_compressor_scalars() {
+        let mut compressor = Compressor::new(CompressorConfig::default(), SR);
+        let mut limiter = Limiter::new(LimiterConfig::default(), SR);
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        let new_cfg = CompressorConfig {
+            threshold_db: -12.0,
+            ratio: 4.0,
+            ..CompressorConfig::default()
+        };
+        apply_audio_cmd(
+            AudioCmd::SetCompressor(new_cfg),
+            &mut compressor,
+            &mut limiter,
+            &mut agc,
+        );
+        let active = compressor.config();
+        assert!((active.threshold_db - -12.0).abs() < 1e-6);
+        assert!((active.ratio - 4.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn apply_audio_cmd_updates_limiter_scalars() {
+        let mut compressor = Compressor::new(CompressorConfig::default(), SR);
+        let mut limiter = Limiter::new(LimiterConfig::default(), SR);
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        let new_cfg = LimiterConfig {
+            ceiling_dbtp: -1.5,
+            release_ms: 250.0,
+            soft: Some(SoftTierConfig {
+                max_psr_db: 10.0,
+                ..SoftTierConfig::default()
+            }),
+            ..LimiterConfig::default()
+        };
+        apply_audio_cmd(
+            AudioCmd::SetLimiter(new_cfg),
+            &mut compressor,
+            &mut limiter,
+            &mut agc,
+        );
+        assert!((limiter.ceiling_dbtp() - -1.5).abs() < 1e-6);
+        assert!((limiter.config().release_ms - 250.0).abs() < 1e-6);
+        let soft = limiter.config().soft.expect("soft preserved");
+        assert!((soft.max_psr_db - 10.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn apply_audio_cmd_skips_structural_limiter_change_silently() {
+        let mut compressor = Compressor::new(CompressorConfig::default(), SR);
+        let mut limiter = Limiter::new(LimiterConfig::default(), SR);
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        let bad = LimiterConfig {
+            // structural; can't apply in place
+            oversample: 8,
+            ..LimiterConfig::default()
+        };
+        // Should not panic, should not change the limiter.
+        apply_audio_cmd(
+            AudioCmd::SetLimiter(bad),
+            &mut compressor,
+            &mut limiter,
+            &mut agc,
+        );
+        assert_eq!(
+            limiter.config().oversample,
+            LimiterConfig::default().oversample
+        );
+    }
+
+    #[test]
+    fn filter_control_send_reaches_consumer() {
+        let (control, mut consumer) = FilterControl::for_testing(8);
+        assert!(control.set_compressor(CompressorConfig::default()));
+        assert!(control.set_limiter(LimiterConfig::default()));
+        // Two commands queued.
+        let c1 = consumer.pop().expect("first cmd");
+        let c2 = consumer.pop().expect("second cmd");
+        assert!(matches!(c1, AudioCmd::SetCompressor(_)));
+        assert!(matches!(c2, AudioCmd::SetLimiter(_)));
+        assert!(consumer.pop().is_err(), "ring drained");
+    }
+
+    #[test]
+    fn filter_control_returns_false_on_full_ring() {
+        // Capacity 2: third push should fail.
+        let (control, _consumer) = FilterControl::for_testing(2);
+        assert!(control.set_compressor(CompressorConfig::default()));
+        assert!(control.set_limiter(LimiterConfig::default()));
+        assert!(!control.set_compressor(CompressorConfig::default()));
+    }
+
+    #[test]
+    fn filter_control_send_then_drain_applies_to_dsp_kernels() {
+        // End-to-end on the cmd plane: push via FilterControl, drain
+        // via apply_audio_cmd, observe DSP state.
+        let (control, mut consumer) = FilterControl::for_testing(8);
+        let mut compressor = Compressor::new(CompressorConfig::default(), SR);
+        let mut limiter = Limiter::new(LimiterConfig::default(), SR);
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+
+        control.set_compressor(CompressorConfig {
+            threshold_db: -8.0,
+            ..CompressorConfig::default()
+        });
+        control.set_limiter(LimiterConfig {
+            ceiling_dbtp: -2.0,
+            ..LimiterConfig::default()
+        });
+
+        while let Ok(cmd) = consumer.pop() {
+            apply_audio_cmd(cmd, &mut compressor, &mut limiter, &mut agc);
+        }
+        assert!((compressor.config().threshold_db - -8.0).abs() < 1e-6);
+        assert!((limiter.ceiling_dbtp() - -2.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn apply_audio_cmd_updates_agc_target_and_enable() {
+        let mut compressor = Compressor::new(CompressorConfig::default(), SR);
+        let mut limiter = Limiter::new(LimiterConfig::default(), SR);
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        apply_audio_cmd(
+            AudioCmd::SetAgcTargetDb(4.5),
+            &mut compressor,
+            &mut limiter,
+            &mut agc,
+        );
+        assert!((agc.target_db() - 4.5).abs() < 1e-6);
+        apply_audio_cmd(
+            AudioCmd::SetAgcEnabled(false),
+            &mut compressor,
+            &mut limiter,
+            &mut agc,
+        );
+        assert!(!agc.enabled());
+        // Disable resets target to 0 (smoother unwinds gracefully).
+        assert!((agc.target_db()).abs() < 1e-6);
+    }
+}

Added file: crates/headroom-core/src/pw/metadata.rs+68 additions@@ -0,0 +1,68 @@
+//! parse/format the PipeWire `default` metadata object. binding,
+//! listening, and writing live in [`crate::pw::registry`].
+
+use serde_json::Value;
+
+pub const DEFAULT_AUDIO_SINK_KEY: &str = "default.audio.sink";
+
+pub const TARGET_OBJECT_KEY: &str = "target.object";
+
+pub const SPA_JSON_TYPE: &str = "Spa:String:JSON";
+
+/// parse a `default.audio.sink` value (`{"name":"alsa_output.…"}`) into
+/// a sink name. `None` on anything unrecognised — ignore rather than
+/// crash the metadata listener.
+#[must_use]
+pub fn parse_default_sink_name(value: &str) -> Option<String> {
+    let parsed: Value = serde_json::from_str(value.trim()).ok()?;
+    parsed.get("name")?.as_str().map(str::to_owned)
+}
+
+/// format a `target.object` value pointing at `sink_name`.
+#[must_use]
+pub fn format_sink_target_value(sink_name: &str) -> String {
+    // formatter is also called with observed (user-influenced) sink
+    // names, so escape embedded quotes even though pipewire's never
+    // contain them.
+    let escaped = sink_name.replace('"', "\\\"");
+    format!("{{\"name\":\"{escaped}\"}}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_default_sink_name_from_canonical_json() {
+        let v = parse_default_sink_name("{\"name\":\"alsa_output.usb-foo\"}");
+        assert_eq!(v.as_deref(), Some("alsa_output.usb-foo"));
+    }
+
+    #[test]
+    fn parses_default_sink_name_with_whitespace() {
+        let v = parse_default_sink_name("  {\"name\":\"x\"}\n");
+        assert_eq!(v.as_deref(), Some("x"));
+    }
+
+    #[test]
+    fn rejects_garbage() {
+        assert_eq!(parse_default_sink_name("not json"), None);
+        assert_eq!(parse_default_sink_name("{}"), None);
+        assert_eq!(parse_default_sink_name("{\"name\":42}"), None);
+    }
+
+    #[test]
+    fn formats_sink_target_round_trips() {
+        let formatted = format_sink_target_value("alsa_output.usb-foo");
+        let back = parse_default_sink_name(&formatted).unwrap();
+        assert_eq!(back, "alsa_output.usb-foo");
+    }
+
+    #[test]
+    fn formats_sink_target_escapes_embedded_quote() {
+        let formatted = format_sink_target_value("we\"ird");
+        // Should still be valid JSON.
+        let back = parse_default_sink_name(&formatted).unwrap();
+        assert_eq!(back, "we\"ird");
+    }
+}

Added file: crates/headroom-core/src/pw/mod.rs+272 additions@@ -0,0 +1,272 @@
+//! PipeWire integration layer. [`PwContext`] owns the main loop,
+//! `Context`, and `Core`.
+
+pub mod command;
+pub mod filter;
+pub mod metadata;
+pub mod registry;
+pub mod sink;
+pub mod tap;
+
+use std::cell::{Cell, RefCell};
+use std::rc::Rc;
+use std::time::Duration;
+
+use pipewire::{context::Context, core::Core, loop_::Signal, main_loop::MainLoop};
+
+use crate::error::DaemonError;
+use crate::pw::registry::RegistryWatcher;
+use crate::pw::sink::VirtualSink;
+use crate::state::SharedState;
+
+const CONNECT_RETRY_TIMEOUT: Duration = Duration::from_secs(20);
+const CONNECT_RETRY_INTERVAL: Duration = Duration::from_millis(250);
+
+/// block `SIGTERM`/`SIGINT` so PipeWire's signalfd source can receive
+/// them instead of the kernel's default (terminate).
+///
+/// **must be called before any thread is spawned** — threads spawned
+/// beforehand keep the unblocked mask and die on signal before the
+/// signalfd reads.
+///
+/// # Errors
+/// [`DaemonError::PipeWire`] if `sigprocmask` fails.
+pub fn block_termination_signals() -> Result<(), DaemonError> {
+    use nix::sys::signal::{SigSet, SigmaskHow};
+
+    let mut set = SigSet::empty();
+    set.add(Signal::SIGTERM);
+    set.add(Signal::SIGINT);
+    nix::sys::signal::sigprocmask(SigmaskHow::SIG_BLOCK, Some(&set), None)
+        .map_err(|e| DaemonError::pipewire(format!("sigprocmask: {e}")))?;
+    Ok(())
+}
+
+/// owns the PipeWire main loop, context, and core for the daemon's run.
+/// single-threaded by design.
+pub struct PwContext {
+    main_loop: MainLoop,
+    _context: Context,
+    core: Core,
+    /// `RefCell` because creation happens after construction (must be
+    /// inside the main loop for the roundtrip).
+    sink: RefCell<VirtualSink>,
+    /// registry watcher + routing engine; `None` until
+    /// [`Self::start_routing`].
+    routing: RefCell<Option<RegistryWatcher>>,
+}
+
+impl PwContext {
+    /// init PipeWire, create the main loop/context, connect, and block
+    /// termination signals (see [`block_termination_signals`]).
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] on failure; usually `Context::connect`
+    /// when no server is reachable on `$PIPEWIRE_RUNTIME_DIR`.
+    pub fn new() -> Result<Self, DaemonError> {
+        // idempotent if `runtime::run` already called it.
+        block_termination_signals()?;
+        pipewire::init();
+        let main_loop = MainLoop::new(None)
+            .map_err(|e| DaemonError::pipewire(format!("MainLoop::new: {e}")))?;
+        let context = Context::new(&main_loop)
+            .map_err(|e| DaemonError::pipewire(format!("Context::new: {e}")))?;
+        let core = connect_with_retry(&context)?;
+        tracing::info!("connected to pipewire");
+        Ok(Self {
+            main_loop,
+            _context: context,
+            core,
+            sink: RefCell::new(VirtualSink::new()),
+            routing: RefCell::new(None),
+        })
+    }
+
+    /// watch the registry and route new playback streams. idempotent;
+    /// calling twice replaces the previous watcher.
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] if obtaining the registry fails.
+    pub fn start_routing(&self, daemon: SharedState) -> Result<(), DaemonError> {
+        let registry = self
+            .core
+            .get_registry()
+            .map_err(|e| DaemonError::pipewire(format!("get_registry: {e}")))?;
+        let watcher = RegistryWatcher::new(Rc::new(registry), self.core.clone(), daemon);
+        *self.routing.borrow_mut() = Some(watcher);
+        tracing::info!("registry watcher + routing engine installed");
+        Ok(())
+    }
+
+    #[must_use]
+    pub fn main_loop(&self) -> &MainLoop {
+        &self.main_loop
+    }
+
+    #[must_use]
+    pub fn core(&self) -> &Core {
+        &self.core
+    }
+
+    /// routing state, if [`Self::start_routing`] ran. lets `runtime`
+    /// install the filter-rebuild handles afterwards.
+    #[must_use]
+    pub fn routing_state(&self) -> Option<Rc<RefCell<crate::pw::registry::RoutingState>>> {
+        self.routing.borrow().as_ref().map(|w| w.state().clone())
+    }
+
+    /// create `headroom-processed` and roundtrip to confirm. must be
+    /// called before [`Self::run_until_signal`].
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] if `create_object` fails, the
+    /// `support.null-audio-sink` factory isn't available, or the
+    /// roundtrip times out.
+    pub fn create_processed_sink(&self, sample_rate: u32) -> Result<(), DaemonError> {
+        self.sink.borrow_mut().create(&self.core, sample_rate)?;
+        self.roundtrip()?;
+        tracing::info!(sample_rate, "headroom-processed virtual sink created");
+        Ok(())
+    }
+
+    /// block until all queued requests are acked by the server.
+    fn roundtrip(&self) -> Result<(), DaemonError> {
+        let done = Rc::new(Cell::new(false));
+        let done_cb = done.clone();
+        let loop_for_cb = self.main_loop.clone();
+
+        let pending = self
+            .core
+            .sync(0)
+            .map_err(|e| DaemonError::pipewire(format!("core.sync: {e}")))?;
+
+        let _listener = self
+            .core
+            .add_listener_local()
+            .done(move |id, seq| {
+                if id == pipewire::core::PW_ID_CORE && seq == pending {
+                    done_cb.set(true);
+                    loop_for_cb.quit();
+                }
+            })
+            .register();
+
+        while !done.get() {
+            self.main_loop.run();
+        }
+        Ok(())
+    }
+
+    /// run the main loop until SIGTERM/SIGINT.
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] if installing the signal sources fails.
+    pub fn run_until_signal(&self) -> Result<(), DaemonError> {
+        // SIGTERM: graceful service stop (systemd).
+        let ml = self.main_loop.clone();
+        let _sig_term = self
+            .main_loop
+            .loop_()
+            .add_signal_local(Signal::SIGTERM, move || {
+                tracing::info!("SIGTERM received, shutting down");
+                ml.quit();
+            });
+
+        // SIGINT: Ctrl-C in foreground.
+        let ml = self.main_loop.clone();
+        let _sig_int = self
+            .main_loop
+            .loop_()
+            .add_signal_local(Signal::SIGINT, move || {
+                tracing::info!("SIGINT received, shutting down");
+                ml.quit();
+            });
+
+        // drain IPC → PipeWire commands at 50 ms. operator-grade only;
+        // NOT for spike-reactive gain reduction (Layer A) — see
+        // `pw::command` module docs.
+        let _cmd_timer = {
+            let routing = self.routing.borrow();
+            routing.as_ref().map(|watcher| {
+                let state = watcher.state().clone();
+                let back = state.clone();
+                let timer = self.main_loop.loop_().add_timer(move |_expirations| {
+                    state.borrow_mut().drain_pw_commands(&back);
+                });
+                let _ = timer.update_timer(
+                    Some(Duration::from_millis(50)),
+                    Some(Duration::from_millis(50)),
+                );
+                timer
+            })
+        };
+
+        // drain Layer A measurement rings + issue `Props.channelVolumes`
+        // writes. 5 ms keeps detection-to-write inside one quantum at
+        // typical 21 ms quanta
+        let _layer_a_timer = {
+            let routing = self.routing.borrow();
+            routing.as_ref().map(|watcher| {
+                let state = watcher.state().clone();
+                let back = state.clone();
+                let timer = self.main_loop.loop_().add_timer(move |_expirations| {
+                    state.borrow_mut().drain_layer_a(&back);
+                });
+                let _ = timer.update_timer(
+                    Some(Duration::from_millis(5)),
+                    Some(Duration::from_millis(5)),
+                );
+                timer
+            })
+        };
+
+        tracing::info!("entering pipewire main loop");
+        self.main_loop.run();
+        tracing::info!("main loop exited");
+
+        // graceful shutdown: restore every attenuated app's volume,
+        // then pump the loop a few times so the writes flush before
+        // the connection tears down. best-effort (no SIGKILL).
+        if let Some(watcher) = self.routing.borrow().as_ref() {
+            watcher.state().borrow().restore_all_managed_volumes();
+        }
+        for _ in 0..10 {
+            self.main_loop.loop_().iterate(Duration::from_millis(5));
+        }
+        Ok(())
+    }
+}
+
+fn connect_with_retry(context: &Context) -> Result<Core, DaemonError> {
+    let started = std::time::Instant::now();
+    let mut attempts = 0_u32;
+    loop {
+        attempts = attempts.saturating_add(1);
+        match context.connect(None) {
+            Ok(core) => {
+                if attempts > 1 {
+                    tracing::info!(
+                        attempts,
+                        elapsed_ms = started.elapsed().as_millis(),
+                        "pipewire connect succeeded after retry"
+                    );
+                }
+                return Ok(core);
+            }
+            Err(e) if started.elapsed() < CONNECT_RETRY_TIMEOUT => {
+                tracing::warn!(
+                    attempts,
+                    error = %e,
+                    "pipewire connect failed; retrying"
+                );
+                std::thread::sleep(CONNECT_RETRY_INTERVAL);
+            }
+            Err(e) => {
+                return Err(DaemonError::pipewire(format!(
+                    "Context::connect after {attempts} attempts over {:?}: {e}",
+                    started.elapsed()
+                )));
+            }
+        }
+    }
+}

Added file: crates/headroom-core/src/pw/registry.rs+2086 additions@@ -0,0 +1,2086 @@
+//! PipeWire registry subscription + routing decisions. watches new
+//! globals (metadata, nodes, ports, links), routes `Stream/Output/Audio`
+//! per the active profile, tracks `preferred_real_sink`, and owns the
+//! explicit link layer (WP only honours `target.object` at connect time).
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::rc::Rc;
+
+use crossbeam_channel::Receiver;
+use pipewire::{
+    core::Core,
+    link::Link,
+    metadata::{Metadata, MetadataListener},
+    node::{Node, NodeListener},
+    properties::{properties, Properties},
+    registry::{GlobalObject, Listener, Registry},
+    spa::{
+        param::ParamType,
+        pod::{
+            deserialize::PodDeserializer, serialize::PodSerializer, Object as PodObject, Pod,
+            Property, PropertyFlags, Value, ValueArray,
+        },
+        utils::{dict::DictRef, SpaTypes},
+    },
+    types::ObjectType,
+};
+use rtrb::Consumer;
+
+use headroom_ipc::{Event, LayerASnapshot, Route, Topic};
+use serde_json::json;
+
+use crate::app_level::{self, AppLevelController, LayerAEval};
+use crate::pw::command::PwCommand;
+use crate::pw::metadata::{
+    format_sink_target_value, parse_default_sink_name, DEFAULT_AUDIO_SINK_KEY, SPA_JSON_TYPE,
+    TARGET_OBJECT_KEY,
+};
+use crate::pw::sink::NODE_NAME as PROCESSED_SINK_NAME;
+use crate::pw::tap::{MeasurementSample, StreamTap};
+use crate::routing::{self, PwNodeInfo, RoutingDecision};
+use crate::state::{RoutedStream, SharedState};
+
+/// assumed audio-thread quantum for Layer A controllers. nodes may
+/// negotiate other values; the smoothing constants tolerate 512–2048.
+const LAYER_A_QUANTUM_FRAMES: f32 = 1024.0;
+
+/// Layer A block period (seconds); falls back to 48 kHz when no real
+/// sink rate is known.
+fn layer_a_block_dt_s(sample_rate: Option<u32>) -> f32 {
+    let sr = sample_rate.unwrap_or(crate::pw::filter::DEFAULT_SAMPLE_RATE);
+    LAYER_A_QUANTUM_FRAMES / (sr as f32)
+}
+
+/// view of a `Port` global. tracked because WP won't wire
+/// `Stream/Output → Stream/Input` — we build links from these port ids.
+#[derive(Debug, Clone)]
+struct PortInfo {
+    /// the port's global id (used as `link.{input,output}.port`).
+    port_id: u32,
+    direction: PortDirection,
+    /// per-node ordinal (port.id), pairs FL↔FL / FR↔FR when channel
+    /// hints are absent.
+    ordinal: Option<u32>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PortDirection {
+    In,
+    Out,
+}
+
+/// view of a `Link` global. tracked so routing can find + destroy a
+/// WP-created link that conflicts with the declared route — WP only
+/// honours `target.object` at connect time, so the daemon owns the
+/// link layer for any stream it routes.
+#[derive(Debug, Clone, Copy)]
+struct LinkInfo {
+    output_port: u32,
+    input_port: u32,
+    /// owner of `output_port`; cached to avoid walking `ports_by_node`.
+    output_node: u32,
+    /// owner of `input_port`.
+    input_node: u32,
+}
+
+/// per-stream routing intent recorded by `try_route_stream`, resolved
+/// by `apply_pending_routes` once both port sets are on the registry.
+#[derive(Debug, Clone)]
+struct PendingRoute {
+    /// target sink `node.name` (`headroom-processed` or real-sink name).
+    target_sink_name: String,
+    app_label: String,
+    route: Route,
+}
+
+/// daemon-owned routing links for one stream + the target they were
+/// built for. keeping them alive lets `enqueue_route` skip a
+/// destroy+rebuild (and its audio gap) when the target is unchanged.
+struct ManagedRoute {
+    target_sink_name: String,
+    links: Vec<Link>,
+}
+
+/// subject for system-wide metadata keys (e.g. `default.audio.sink`).
+const METADATA_SUBJECT_GLOBAL: u32 = 0;
+
+/// bus filter `node.name`; WP does not auto-link `pw_filter` nodes.
+const FILTER_NODE_NAME: &str = crate::pw::filter::NODE_NAME;
+
+/// per-PipeWire-thread state. proxies aren't `Send`, so they live here
+/// behind `Rc<RefCell<_>>` rather than in [`SharedState`].
+pub struct RoutingState {
+    daemon: SharedState,
+    /// `None` until the registry surfaces the `default` metadata.
+    default_metadata: Option<Metadata>,
+    _default_metadata_listener: Option<MetadataListener>,
+    registry: Rc<Registry>,
+    core: Core,
+    /// global id of `headroom-filter`. routing treats it as both the
+    /// sink-side target for the processed monitor and the source-side
+    /// target into the real sink; retargeted on default-sink change.
+    filter_playback_id: Option<u32>,
+    /// `Audio/Sink` node.name → global id.
+    sinks_by_name: HashMap<String, u32>,
+    /// IPC-originated commands, drained by [`Self::drain_pw_commands`].
+    pw_command_rx: Receiver<PwCommand>,
+    /// Layer A managed streams, keyed by source node id.
+    managed_streams: HashMap<u32, ManagedStream>,
+    /// `Port` globals keyed by owning node id; used to build links.
+    ports_by_node: HashMap<u32, Vec<PortInfo>>,
+    /// port id → owning node id, so `on_global_remove` distinguishes a
+    /// port removal from a node removal under PipeWire's id reuse —
+    /// the old "retain by port_id across all nodes" pass could wipe a
+    /// live node's ports.
+    port_owner: HashMap<u32, u32>,
+    /// `Link` globals keyed by link global id. see [`LinkInfo`].
+    links_by_id: HashMap<u32, LinkInfo>,
+    /// outbound link ids per source node.
+    outbound_links_by_node: HashMap<u32, Vec<u32>>,
+    /// routes declared but not yet linked (ports still arriving).
+    /// drained by [`Self::apply_pending_routes`].
+    pending_routes: HashMap<u32, PendingRoute>,
+    /// daemon-owned `Link` proxies keyed by source node; see
+    /// [`ManagedRoute`].
+    managed_route_links: HashMap<u32, ManagedRoute>,
+    /// `default.audio.sink` re-assertion budget so a hostile WP can't
+    /// hot-loop us. `(window_start, attempts)`.
+    default_reassertion: Option<(std::time::Instant, u32)>,
+    /// `PwNodeInfo` per routable stream, so bypass/profile reapply can
+    /// re-run `routing::evaluate` without re-reading PipeWire props.
+    known_streams: HashMap<u32, PwNodeInfo>,
+    /// owned global per known stream — the Layer A reconciliation path
+    /// runs on the drain timer (no live `global`) but `bind` only reads
+    /// id + type, which an owned global carries.
+    stream_globals: HashMap<u32, GlobalObject<Properties>>,
+    /// persisted per-app `user_ceiling`, keyed as `info_app_label`.
+    /// without this, an app that respawns a node per track (Strawberry)
+    /// reads its inherited daemon-written volume, misreads it as a user
+    /// change, and locks the controller at the prior track's cut.
+    persisted_ceilings: HashMap<String, f32>,
+    /// node proxy + Format listener for the real sink, capturing its
+    /// negotiated `audio.rate` (ALSA sinks expose it only via Format).
+    real_sink_format_listener: Option<(u32, Node, NodeListener)>,
+    /// the bus filter, held here so `PwCommand::RebuildFilter` can swap
+    /// it atomically on a rate change.
+    bus_filter: Option<crate::pw::filter::Filter>,
+    /// whether the processed-sink monitor -> filter -> real-sink graph
+    /// should currently be linked.
+    bus_graph_active: bool,
+    /// slow AGC controller, so a rebuild can rebind it. shared with the
+    /// AGC timer in `runtime`; the main loop serialises borrow_mut.
+    agc_controller: Option<Rc<RefCell<crate::agc::AgcController>>>,
+}
+
+/// per-stream Layer A bundle: tap + controller + measurement consumer.
+struct ManagedStream {
+    /// drop severs the passive link + destroys the tap stream.
+    #[allow(dead_code)]
+    tap: StreamTap,
+    controller: AppLevelController,
+    measurement_consumer: Consumer<MeasurementSample>,
+    /// bound source `Node` for `Props.channelVolumes` writes; `None` if
+    /// the bind failed (controller still runs, writes skipped).
+    node: Option<Node>,
+    /// param listener: external `channelVolumes` changes (pavucontrol,
+    /// hotkey, the app) route through `controller.on_external_change`
+    /// (the rule's `DeferPolicy`).
+    #[allow(dead_code)]
+    node_listener: Option<NodeListener>,
+    /// explicit per-channel passive links source → tap; empty until the
+    /// drain-timer retry finds both port sets.
+    #[allow(dead_code)]
+    links: Vec<Link>,
+    app_label: String,
+}
+
+impl RoutingState {
+    #[must_use]
+    pub fn new(
+        daemon: SharedState,
+        registry: Rc<Registry>,
+        core: Core,
+        pw_command_rx: Receiver<PwCommand>,
+    ) -> Self {
+        Self {
+            daemon,
+            default_metadata: None,
+            _default_metadata_listener: None,
+            registry,
+            core,
+            filter_playback_id: None,
+            sinks_by_name: HashMap::new(),
+            pw_command_rx,
+            managed_streams: HashMap::new(),
+            ports_by_node: HashMap::new(),
+            port_owner: HashMap::new(),
+            links_by_id: HashMap::new(),
+            outbound_links_by_node: HashMap::new(),
+            pending_routes: HashMap::new(),
+            managed_route_links: HashMap::new(),
+            default_reassertion: None,
+            known_streams: HashMap::new(),
+            stream_globals: HashMap::new(),
+            persisted_ceilings: HashMap::new(),
+            real_sink_format_listener: None,
+            bus_filter: None,
+            bus_graph_active: false,
+            agc_controller: None,
+        }
+    }
+
+    /// hand over the bus filter + AGC controller so a rate change can
+    /// rebuild + rebind both atomically. called once from `runtime`.
+    pub fn install_filter_rebuild_handles(
+        &mut self,
+        filter: crate::pw::filter::Filter,
+        agc: Rc<RefCell<crate::agc::AgcController>>,
+    ) {
+        self.bus_filter = Some(filter);
+        self.agc_controller = Some(agc);
+    }
+
+    /// drain queued [`PwCommand`]s then run a routing-link enforcement
+    /// pass. called by the 50 ms timer in
+    /// [`crate::pw::PwContext::run_until_signal`].
+    pub fn drain_pw_commands(&mut self, back: &Rc<RefCell<Self>>) {
+        while let Ok(cmd) = self.pw_command_rx.try_recv() {
+            self.apply_pw_command(cmd, back);
+        }
+        self.apply_pending_routes();
+    }
+
+    fn apply_pw_command(&mut self, cmd: PwCommand, back: &Rc<RefCell<Self>>) {
+        match cmd {
+            PwCommand::RouteStream {
+                node_id,
+                to,
+                app_label,
+            } => {
+                let target_name = match to {
+                    Route::Processed => PROCESSED_SINK_NAME.to_owned(),
+                    Route::Bypass => {
+                        let Some(name) = self.daemon.lock().real_sink.name.clone() else {
+                            tracing::warn!(
+                                node_id,
+                                "route.stream bypass requested but no real sink known yet — skipping metadata write"
+                            );
+                            return;
+                        };
+                        name
+                    }
+                };
+                self.write_stream_target(node_id, &target_name, &app_label);
+                self.enqueue_route(node_id, target_name, app_label, to);
+                self.sync_bus_graph_links();
+            }
+            PwCommand::ReevaluateAll => {
+                self.reevaluate_all();
+            }
+            PwCommand::RebuildFilter { sample_rate } => {
+                self.rebuild_filter(sample_rate);
+            }
+            PwCommand::ReevaluateLayerA => {
+                self.reevaluate_layer_a(back);
+            }
+            PwCommand::LayerAResetDeference { node_id } => {
+                if let Some(managed) = self.managed_streams.get_mut(&node_id) {
+                    managed.controller.reset_deference();
+                    tracing::info!(node_id, "Layer A deference reset");
+                } else {
+                    tracing::debug!(
+                        node_id,
+                        "Layer A reset requested for an unmanaged stream — ignoring"
+                    );
+                }
+            }
+        }
+    }
+
+    /// tear down + recreate the bus filter at `new_sample_rate` and
+    /// rebind AGC. posted by the Format listener on a rate mismatch.
+    /// ~50–100 ms audio gap during the swap.
+    fn rebuild_filter(&mut self, new_sample_rate: u32) {
+        let Some(agc) = self.agc_controller.clone() else {
+            tracing::warn!(
+                new_sample_rate,
+                "filter rebuild requested but agc handle not installed yet"
+            );
+            return;
+        };
+        let current_rate = self.daemon.lock().filter_sample_rate;
+        if current_rate == Some(new_sample_rate) {
+            tracing::debug!(
+                new_sample_rate,
+                "filter rebuild requested but rate is already current — no-op"
+            );
+            return;
+        }
+        // snapshot DSP config under the lock; rebuild runs without it.
+        let filter_init = {
+            let s = self.daemon.lock();
+            let effective = s.profiles.effective();
+            crate::pw::filter::FilterInit {
+                compressor: effective.build_compressor_config(),
+                limiter: effective.build_limiter_config(),
+                agc: headroom_dsp::AgcGainConfig::default(),
+                agc_enabled: effective.agc.enabled,
+            }
+        };
+        tracing::info!(
+            old_rate = ?current_rate,
+            new_rate = new_sample_rate,
+            "rebuilding bus filter at new sample rate"
+        );
+        // clear the cached filter id BEFORE dropping the old filter:
+        // if the new filter's `global_add` ever beats the old one's
+        // remove, `try_capture_filter_playback`'s early-exit would skip
+        // the new id and never re-link. stale pending entries are
+        // harmless (apply_pending_routes no-ops on a missing id).
+        let old_filter_id = self.filter_playback_id.take();
+        if let Some(id) = old_filter_id {
+            self.pending_routes.remove(&id);
+            self.managed_route_links.remove(&id);
+        }
+        // drop the old filter before creating the new one (short silence).
+        self.bus_filter = None;
+        let bundle = match crate::pw::filter::Filter::create(
+            &self.core,
+            filter_init,
+            new_sample_rate,
+        ) {
+            Ok(b) => b,
+            Err(e) => {
+                tracing::error!(
+                    error = %e,
+                    new_sample_rate,
+                    "filter rebuild failed; daemon will run without a filter until the next rate change"
+                );
+                return;
+            }
+        };
+        {
+            let mut s = self.daemon.lock();
+            s.filter_control = Some(bundle.control.clone());
+            s.filter_sample_rate = Some(bundle.sample_rate);
+        }
+        agc.borrow_mut().rebind(
+            bundle.measurement_consumer,
+            bundle.control,
+            bundle.sample_rate,
+        );
+        self.bus_filter = Some(bundle.filter);
+        // re-run routing to re-anchor links on the new filter's ports.
+        self.reevaluate_all();
+    }
+
+    /// true iff the default metadata has been bound.
+    #[must_use]
+    pub fn has_default_metadata(&self) -> bool {
+        self.default_metadata.is_some()
+    }
+
+    fn on_global(&mut self, global: &GlobalObject<&DictRef>, back: &Rc<RefCell<Self>>) {
+        match &global.type_ {
+            ObjectType::Metadata => self.try_bind_default_metadata(global, back),
+            ObjectType::Node => {
+                self.try_capture_processed_sink_id(global);
+                self.try_capture_real_sink(global);
+                self.try_capture_filter_playback(global);
+                self.try_route_stream(global, back);
+            }
+            ObjectType::Port => self.try_capture_port(global),
+            ObjectType::Link => self.try_capture_link(global),
+            _ => {}
+        }
+    }
+
+    /// track a Link global + vigilance check: if it originates from a
+    /// stream we route and lands off its declared target, destroy it
+    /// now. WP links streams faster than our node callback fires, so
+    /// this fast path backs up the slower `apply_pending_routes` retry.
+    fn try_capture_link(&mut self, global: &GlobalObject<&DictRef>) {
+        let Some(props) = &global.props else {
+            tracing::debug!(link_id = global.id, "link global without props");
+            return;
+        };
+        let dict: &DictRef = props;
+        let parse = |k: &str| dict.get(k).and_then(|s| s.parse::<u32>().ok());
+        let (Some(output_port), Some(input_port), Some(output_node), Some(input_node)) = (
+            parse("link.output.port"),
+            parse("link.input.port"),
+            parse("link.output.node"),
+            parse("link.input.node"),
+        ) else {
+            tracing::debug!(
+                link_id = global.id,
+                out_port = ?parse("link.output.port"),
+                in_port = ?parse("link.input.port"),
+                out_node = ?parse("link.output.node"),
+                in_node = ?parse("link.input.node"),
+                "link global with incomplete props"
+            );
+            return;
+        };
+
+        let info = LinkInfo {
+            output_port,
+            input_port,
+            output_node,
+            input_node,
+        };
+        tracing::debug!(
+            link_id = global.id,
+            output_port,
+            input_port,
+            output_node,
+            input_node,
+            "captured link global"
+        );
+        self.links_by_id.insert(global.id, info);
+        self.outbound_links_by_node
+            .entry(output_node)
+            .or_default()
+            .push(global.id);
+
+        self.enforce_link_for_managed_stream(global.id, &info);
+    }
+
+    /// destroy `link` if it leaves a routed stream for a *different*
+    /// Audio/Sink than the declared target. links to non-sinks (Layer A
+    /// taps) are left alone — Layer A owns those.
+    fn enforce_link_for_managed_stream(&mut self, link_id: u32, info: &LinkInfo) {
+        let intent = self.intent_for_node(info.output_node);
+        let Some((target_sink_node_id, target_input_ports)) = intent else {
+            return;
+        };
+        if info.input_node == target_sink_node_id
+            && target_input_ports.iter().any(|p| *p == info.input_port)
+        {
+            return; // link lands on the intended target — keep
+        }
+        // If the destination isn't one of our routing targets,
+        // leave it alone — it's likely a Layer A tap or some
+        // other downstream consumer the daemon doesn't own.
+        if !self.is_routing_target(info.input_node) {
+            return;
+        }
+        match self.registry.destroy_global(link_id).into_result() {
+            Ok(_) => tracing::debug!(
+                link_id,
+                output_node = info.output_node,
+                input_node = info.input_node,
+                "destroyed conflicting link for managed stream"
+            ),
+            Err(e) => tracing::warn!(
+                link_id,
+                output_node = info.output_node,
+                error = ?e,
+                "failed to destroy conflicting link"
+            ),
+        }
+    }
+
+    /// resolve a routing-target name to its node id. targets are
+    /// `Audio/Sink`s + the bus filter; the filter is special-cased so
+    /// `sinks_by_name` stays sink-only.
+    fn resolve_routing_target(&self, name: &str) -> Option<u32> {
+        if name == FILTER_NODE_NAME {
+            return self.filter_playback_id;
+        }
+        self.sinks_by_name.get(name).copied()
+    }
+
+    /// does `node_id` belong to a routing target the daemon links into?
+    /// (link-teardown vigilance: leave non-targets like Layer A taps.)
+    fn is_routing_target(&self, node_id: u32) -> bool {
+        if self.filter_playback_id == Some(node_id) {
+            return true;
+        }
+        self.sinks_by_name.values().any(|&id| id == node_id)
+    }
+
+    /// `(target_sink_node_id, target_input_port_ids)` if the daemon
+    /// intends to route `source_node`. for the link-vigilance fast path.
+    fn intent_for_node(&self, source_node: u32) -> Option<(u32, Vec<u32>)> {
+        let target_name = if let Some(p) = self.pending_routes.get(&source_node) {
+            p.target_sink_name.clone()
+        } else if self.managed_route_links.contains_key(&source_node) {
+            let s = self.daemon.lock();
+            let entry = s.streams.get(&source_node)?;
+            match entry.route {
+                Route::Processed => PROCESSED_SINK_NAME.to_owned(),
+                Route::Bypass => s.real_sink.name.clone()?,
+            }
+        } else {
+            return None;
+        };
+        let target_node = self.resolve_routing_target(&target_name)?;
+        let target_inputs: Vec<u32> = self
+            .ports_by_node
+            .get(&target_node)?
+            .iter()
+            .filter(|p| p.direction == PortDirection::In)
+            .map(|p| p.port_id)
+            .collect();
+        if target_inputs.is_empty() {
+            None
+        } else {
+            Some((target_node, target_inputs))
+        }
+    }
+
+    fn try_capture_port(&mut self, global: &GlobalObject<&DictRef>) {
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        let Some(node_id) = dict.get("node.id").and_then(|s| s.parse::<u32>().ok()) else {
+            return;
+        };
+        let direction = match dict.get("port.direction") {
+            Some("in") => PortDirection::In,
+            Some("out") => PortDirection::Out,
+            _ => return,
+        };
+        let ordinal = dict.get("port.id").and_then(|s| s.parse::<u32>().ok());
+        let info = PortInfo {
+            port_id: global.id,
+            direction,
+            ordinal,
+        };
+        let entry = self.ports_by_node.entry(node_id).or_default();
+        entry.retain(|p| p.port_id != info.port_id);
+        entry.push(info);
+        // owning node so `on_global_remove` distinguishes port vs node
+        // removal under id reuse.
+        self.port_owner.insert(global.id, node_id);
+    }
+
+    /// record non-processed `Audio/Sink` nodes in `sinks_by_name` and,
+    /// if the name matches the real sink, populate its node_id.
+    ///
+    /// **cold-boot fallback (F4):** with no real sink known yet, adopt
+    /// the first non-processed sink, else `real_sink.name` stays `None`
+    /// forever and bypass routes log "no real sink known". a later
+    /// `default.audio.sink` event refines it via `adopt_new_real_sink`.
+    fn try_capture_real_sink(&mut self, global: &GlobalObject<&DictRef>) {
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        if dict.get("media.class") != Some("Audio/Sink") {
+            return;
+        }
+        let Some(name) = dict.get("node.name") else {
+            return;
+        };
+        if name == PROCESSED_SINK_NAME {
+            return; // tracked elsewhere
+        }
+        let rate = dict.get("audio.rate").and_then(|s| s.parse::<u32>().ok());
+        self.sinks_by_name.insert(name.to_owned(), global.id);
+        let mut became_real_sink = false;
+        {
+            let mut s = self.daemon.lock();
+            if s.real_sink.name.is_none() {
+                tracing::info!(
+                    node_id = global.id,
+                    name,
+                    ?rate,
+                    "no preferred_real_sink yet; adopting first available Audio/Sink as fallback"
+                );
+                s.real_sink.name = Some(name.to_owned());
+                s.real_sink.node_id = Some(global.id);
+                s.real_sink.sample_rate = rate;
+                // adopted sink is "ready" (matches the metadata path);
+                // else status/GUI report it not-ready while linked.
+                s.real_sink.ready = true;
+                became_real_sink = true;
+            } else if s.real_sink.name.as_deref() == Some(name) {
+                // re-sighting the current real sink.
+                s.real_sink.ready = true;
+                if s.real_sink.node_id != Some(global.id) {
+                    tracing::info!(
+                        node_id = global.id,
+                        name,
+                        "resolved preferred_real_sink node id"
+                    );
+                    s.real_sink.node_id = Some(global.id);
+                    became_real_sink = true;
+                }
+                // refresh rate on re-sight; ALSA sinks first register
+                // without `audio.rate` (filled by the Format listener).
+                if rate.is_some() && s.real_sink.sample_rate != rate {
+                    tracing::info!(
+                        node_id = global.id,
+                        name,
+                        old_rate = ?s.real_sink.sample_rate,
+                        new_rate = ?rate,
+                        "real sink rate updated"
+                    );
+                    s.real_sink.sample_rate = rate;
+                }
+            }
+        }
+        // ALSA sinks carry `audio.rate` only in the Format param, not
+        // the props dict; subscribe to pull it. only for the current
+        // real sink so we don't accumulate proxies.
+        if became_real_sink {
+            self.install_real_sink_format_listener(global);
+            self.write_policy_default_audio_sink();
+            // F4 can surface the sink after filter capture (which then
+            // skipped the output leg); pin now — order-independent with
+            // `try_capture_filter_playback`.
+            self.sync_bus_graph_links();
+        }
+    }
+
+    /// bind `sink_global` and subscribe to its `Format` param (the
+    /// initial value is replayed on subscribe) to track
+    /// `real_sink.sample_rate`. replaces a listener on a different node.
+    fn install_real_sink_format_listener(&mut self, sink_global: &GlobalObject<&DictRef>) {
+        let node_id = sink_global.id;
+        if let Some((prev_id, _, _)) = &self.real_sink_format_listener {
+            if *prev_id == node_id {
+                return; // already bound, nothing to do
+            }
+        }
+        let node = match self.registry.bind::<Node, _>(sink_global) {
+            Ok(n) => n,
+            Err(e) => {
+                tracing::warn!(
+                    node_id,
+                    error = %e,
+                    "failed to bind real sink Node proxy; sample rate will fall back to default"
+                );
+                self.real_sink_format_listener = None;
+                return;
+            }
+        };
+        let daemon = self.daemon.clone();
+        let listener = node
+            .add_listener_local()
+            .param(move |_seq, id, _index, _next, param_opt| {
+                if id != ParamType::Format {
+                    return;
+                }
+                let Some(param) = param_opt else { return };
+                let Some(rate) = extract_audio_rate(param) else {
+                    return;
+                };
+                let (need_rebuild, tx) = {
+                    let mut s = daemon.lock();
+                    if s.real_sink.sample_rate == Some(rate) {
+                        return;
+                    }
+                    tracing::info!(
+                        node_id,
+                        old_rate = ?s.real_sink.sample_rate,
+                        new_rate = rate,
+                        "real sink Format negotiated; updating sample_rate"
+                    );
+                    s.real_sink.sample_rate = Some(rate);
+                    // filter on a different rate → ask for a rebuild.
+                    let need = s.filter_sample_rate != Some(rate);
+                    (need, s.pw_command_tx.clone())
+                };
+                if !need_rebuild {
+                    return;
+                }
+                let Some(tx) = tx else {
+                    tracing::debug!(
+                        "no PipeWire command channel; filter rebuild deferred (test mode?)"
+                    );
+                    return;
+                };
+                if tx
+                    .send(PwCommand::RebuildFilter { sample_rate: rate })
+                    .is_err()
+                {
+                    tracing::warn!(
+                        "PipeWire command channel closed; filter rate-match lost"
+                    );
+                }
+            })
+            .register();
+        node.subscribe_params(&[ParamType::Format]);
+        self.real_sink_format_listener = Some((node_id, node, listener));
+    }
+
+    /// capture `headroom-filter`'s global id. match on `node.name`
+    /// alone — `pw_filter` publishes no `Stream/*` media class.
+    fn try_capture_filter_playback(&mut self, global: &GlobalObject<&DictRef>) {
+        if self.filter_playback_id.is_some() {
+            return;
+        }
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        if dict.get("node.name") != Some(FILTER_NODE_NAME) {
+            return;
+        }
+        tracing::info!(node_id = global.id, "captured bus filter node id");
+        self.filter_playback_id = Some(global.id);
+        // not registered in `sinks_by_name` (that map is sink-only);
+        // resolved via `resolve_routing_target`/`is_routing_target`.
+
+        // both link legs are enqueued idempotently; whichever of the
+        // filter / processed-sink / real-sink surfaces last wins the
+        // race. (the output leg via `pin_filter_to_real_sink` is also
+        // called from the real-sink adoption paths.)
+        self.sync_bus_graph_links();
+    }
+
+    fn sync_bus_graph_links(&mut self) {
+        let should_be_active = self.should_activate_bus_graph();
+        if should_be_active {
+            if !self.bus_graph_active {
+                tracing::info!("processed bus graph activated");
+            }
+            self.bus_graph_active = true;
+            self.enqueue_filter_input_link();
+            self.pin_filter_to_real_sink();
+        } else {
+            self.drop_bus_graph_links();
+            if self.bus_graph_active {
+                tracing::info!("processed bus graph deactivated");
+            }
+            self.bus_graph_active = false;
+        }
+    }
+
+    fn should_activate_bus_graph(&self) -> bool {
+        let s = self.daemon.lock();
+        if s.profiles.bypass_global() {
+            return false;
+        }
+        if s.profiles.effective().default_route.route == Route::Processed {
+            return true;
+        }
+        s.streams.values().any(|r| r.route == Route::Processed)
+    }
+
+    fn drop_bus_graph_links(&mut self) {
+        let processed_id = { self.daemon.lock().processed_sink_id };
+        if let Some(processed_id) = processed_id {
+            self.pending_routes.remove(&processed_id);
+            self.managed_route_links.remove(&processed_id);
+        }
+        if let Some(filter_id) = self.filter_playback_id {
+            self.pending_routes.remove(&filter_id);
+            self.managed_route_links.remove(&filter_id);
+        }
+    }
+
+    /// enqueue the `filter → real_sink` output link once both the
+    /// filter and a real sink are known. idempotent — callable from any
+    /// site that learns one half, regardless of arrival order; the
+    /// intent survives until the (maybe-suspended) sink's ports surface.
+    fn pin_filter_to_real_sink(&mut self) {
+        let Some(filter_id) = self.filter_playback_id else {
+            return;
+        };
+        let Some(name) = self.daemon.lock().real_sink.name.clone() else {
+            return;
+        };
+        self.enqueue_route(filter_id, name, FILTER_NODE_NAME.to_owned(), Route::Bypass);
+    }
+
+    /// enqueue the `processed.monitor → filter.in.*` link pair. source
+    /// = processed sink (its `Out` ports = the monitor); target = the
+    /// filter's `In` ports. paired by ordinal in `apply_pending_routes`.
+    fn enqueue_filter_input_link(&mut self) {
+        let processed_id = match self.daemon.lock().processed_sink_id {
+            Some(id) => id,
+            None => {
+                tracing::debug!(
+                    "filter input link deferred: processed sink id not yet captured"
+                );
+                return;
+            }
+        };
+        self.enqueue_route(
+            processed_id,
+            FILTER_NODE_NAME.to_owned(),
+            "headroom-processed.monitor".to_owned(),
+            Route::Processed,
+        );
+    }
+
+    fn try_bind_default_metadata(
+        &mut self,
+        global: &GlobalObject<&DictRef>,
+        back: &Rc<RefCell<Self>>,
+    ) {
+        if self.default_metadata.is_some() {
+            return;
+        }
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        if dict.get("metadata.name") != Some("default") {
+            return;
+        }
+        let md = match self.registry.bind::<Metadata, _>(global) {
+            Ok(m) => m,
+            Err(e) => {
+                tracing::warn!(error = %e, "failed to bind default metadata");
+                return;
+            }
+        };
+        tracing::info!(global_id = global.id, "bound default metadata");
+        // install the listener BEFORE our promotion write so it sees the
+        // prior server state then our write, in order.
+        let listener_back = back.clone();
+        let listener = md
+            .add_listener_local()
+            .property(move |subject, key, _type, value| {
+                // re-entrancy invariant: callbacks are serial on this loop
+                // no sync pipewire round-trips while this `RefCell` borrow lives
+                listener_back.borrow_mut().on_metadata_property(subject, key, value);
+                0
+            })
+            .register();
+        self.default_metadata = Some(md);
+        self._default_metadata_listener = Some(listener);
+        self.write_policy_default_audio_sink();
+    }
+
+    fn try_capture_processed_sink_id(&mut self, global: &GlobalObject<&DictRef>) {
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        if dict.get("node.name") != Some(PROCESSED_SINK_NAME) {
+            return;
+        }
+        let mut s = self.daemon.lock();
+        if s.processed_sink_id != Some(global.id) {
+            tracing::info!(node_id = global.id, "captured headroom-processed node id");
+            s.processed_sink_id = Some(global.id);
+        }
+        drop(s);
+        // expose in `sinks_by_name` so routing resolves it to a node id.
+        self.sinks_by_name
+            .insert(PROCESSED_SINK_NAME.to_owned(), global.id);
+        // registry replay order isn't guaranteed; if the filter came
+        // first, retry the monitor → filter.in.* enqueue now.
+        if self.filter_playback_id.is_some() {
+            self.sync_bus_graph_links();
+        }
+    }
+
+    fn try_route_stream(
+        &mut self,
+        global: &GlobalObject<&DictRef>,
+        back: &Rc<RefCell<Self>>,
+    ) {
+        let Some(props) = &global.props else { return };
+        let dict: &DictRef = props;
+        if dict.get("media.class") != Some("Stream/Output/Audio") {
+            return;
+        }
+        // don't route the daemon's own streams (filter + taps) back in
+        // — feedback loop. `node.dont-move` isn't always in the registry
+        // view, so match on name prefix too.
+        if dict
+            .get("node.name")
+            .is_some_and(|n| n.starts_with("headroom-filter") || n.starts_with("headroom-tap"))
+        {
+            tracing::trace!(node_id = global.id, "skipping headroom-internal stream");
+            return;
+        }
+
+        let info = build_node_info(global.id, dict);
+
+        // cache before routing so reapply paths can re-`evaluate`
+        // without re-reading props; owned global lets the Layer A
+        // reconcile path bind without a live callback. cleared in
+        // `on_global_remove`.
+        self.known_streams.insert(info.node_id, info.clone());
+        self.stream_globals.insert(info.node_id, global.to_owned());
+
+        let app_label = info_app_label(&info);
+        self.apply_bus_route(&info, &app_label);
+
+        // Layer A is orthogonal to the bus route — taps the source
+        // wherever it routes.
+        self.maybe_spawn_layer_a(&info, &app_label, back);
+    }
+
+    /// apply the bus-routing decision for `info`. reads bypass +
+    /// profile + real-sink name at call time, then enqueues a route or
+    /// unmanages. no proxies touched while the lock is held.
+    fn apply_bus_route(&mut self, info: &PwNodeInfo, app_label: &str) {
+        let (decision, real_sink_name) = {
+            let s = self.daemon.lock();
+            let bypass = s.profiles.bypass_global();
+            let d = routing::evaluate(info, s.profiles.effective(), bypass);
+            (d, s.real_sink.name.clone())
+        };
+
+        match decision {
+            RoutingDecision::Route(Route::Processed) => {
+                self.write_stream_target(info.node_id, PROCESSED_SINK_NAME, app_label);
+                self.enqueue_route(
+                    info.node_id,
+                    PROCESSED_SINK_NAME.to_owned(),
+                    app_label.to_owned(),
+                    Route::Processed,
+                );
+                self.record_route(info.node_id, app_label.to_owned(), Route::Processed);
+                self.sync_bus_graph_links();
+            }
+            RoutingDecision::Route(Route::Bypass) => {
+                if let Some(name) = real_sink_name.as_deref() {
+                    self.write_stream_target(info.node_id, name, app_label);
+                    self.enqueue_route(
+                        info.node_id,
+                        name.to_owned(),
+                        app_label.to_owned(),
+                        Route::Bypass,
+                    );
+                } else {
+                    // no real sink known yet (early boot); record the
+                    // route, leave the stream at PipeWire's default.
+                    tracing::warn!(
+                        node_id = info.node_id,
+                        app = app_label,
+                        "bypass route with no known real sink — leaving stream at PipeWire default"
+                    );
+                }
+                self.record_route(info.node_id, app_label.to_owned(), Route::Bypass);
+                self.sync_bus_graph_links();
+            }
+            RoutingDecision::Skip => {
+                // not a managed bus stream; drop its links + intent,
+                // leave Layer A alone.
+                tracing::trace!(node_id = info.node_id, "skip (not routable)");
+                self.unmanage(info.node_id);
+                self.sync_bus_graph_links();
+            }
+        }
+    }
+
+    /// tear down bus-routing state for `node_id` (links via
+    /// `object.linger = "false"`, pending intent, `state.streams`).
+    /// Layer A entries untouched — keyed on source node, own lifecycle.
+    fn unmanage(&mut self, node_id: u32) {
+        self.pending_routes.remove(&node_id);
+        self.managed_route_links.remove(&node_id);
+        let mut s = self.daemon.lock();
+        if s.streams.remove(&node_id).is_some() {
+            tracing::debug!(node_id, "bus route unmanaged");
+        }
+    }
+
+    /// re-apply routing policy to every known stream (one
+    /// `routing::evaluate` each). also re-asserts `default.audio.sink`
+    /// for the current bypass state — what makes "bypass on" a real
+    /// kill switch for apps that follow `default` rather than
+    /// `target.object`.
+    fn reevaluate_all(&mut self) {
+        self.write_policy_default_audio_sink();
+
+        let snapshot: Vec<PwNodeInfo> = self.known_streams.values().cloned().collect();
+        tracing::info!(streams = snapshot.len(), "reevaluating all known streams");
+        for info in snapshot {
+            let app_label = info_app_label(&info);
+            self.apply_bus_route(&info, &app_label);
+        }
+        self.sync_bus_graph_links();
+    }
+
+    /// spawn a Layer A tap + controller if the stream matches an
+    /// enabled `[[per_app.rules]]` entry. no-op if already managed or
+    /// unmatched; every no-op path logs *why* at debug. wiring is in
+    /// [`Self::spawn_layer_a`].
+    fn maybe_spawn_layer_a(
+        &mut self,
+        info: &PwNodeInfo,
+        app_label: &str,
+        back: &Rc<RefCell<Self>>,
+    ) {
+        if self.managed_streams.contains_key(&info.node_id) {
+            tracing::debug!(
+                node_id = info.node_id,
+                app = app_label,
+                "Layer A spawn skipped: already managed"
+            );
+            return;
+        }
+        let eval = {
+            let s = self.daemon.lock();
+            app_level::evaluate(info, &s.profiles.effective().per_app)
+        };
+        let rule = match eval {
+            LayerAEval::Spawn(rule) => rule,
+            other => {
+                tracing::debug!(
+                    node_id = info.node_id,
+                    app = app_label,
+                    reason = other.skip_reason(),
+                    "Layer A spawn skipped"
+                );
+                return;
+            }
+        };
+        self.spawn_layer_a(info.node_id, rule, app_label, back);
+    }
+
+    /// create the tap, bind the source node (from the cached owned
+    /// global, so both the callback + reconcile paths can call this),
+    /// restore any persisted ceiling, register the managed stream.
+    fn spawn_layer_a(
+        &mut self,
+        node_id: u32,
+        rule: crate::profile::PerAppRule,
+        app_label: &str,
+        back: &Rc<RefCell<Self>>,
+    ) {
+        let block_dt_s = layer_a_block_dt_s(self.daemon.lock().real_sink.sample_rate);
+        let (tap, consumer) = match StreamTap::start(&self.core, node_id) {
+            Ok(pair) => pair,
+            Err(e) => {
+                tracing::warn!(
+                    node_id,
+                    app = app_label,
+                    error = %e,
+                    "Layer A tap start failed; stream will be left unmanaged (retry next drain)"
+                );
+                return;
+            }
+        };
+        let mut controller = AppLevelController::new(rule, block_dt_s);
+
+        // restore any persisted user_ceiling for this app; lookup
+        // before bind keeps the ordering below clean.
+        let persisted_ceiling = if app_label.is_empty() {
+            None
+        } else {
+            self.persisted_ceilings.get(app_label).copied()
+        };
+        if let Some(ceiling) = persisted_ceiling {
+            controller.restore_state(ceiling, std::time::Instant::now());
+            tracing::debug!(
+                node_id,
+                app = app_label,
+                ceiling,
+                "Layer A: restored persisted user_ceiling for new instance"
+            );
+        }
+
+        // bind → install_listener → write baseline → subscribe(Props),
+        // in that order. writing a known baseline (persisted ceiling or
+        // unity) BEFORE subscribing means the Props echo equals the
+        // controller's `last_written_lin`, so the echo check ignores it
+        // instead of misreading a stale/inherited value as a user
+        // gesture and locking the ceiling (the "hangs until I tweak it
+        // again" bug on re-enable). bind failure still registers the tap.
+        let baseline = persisted_ceiling.unwrap_or(1.0);
+        let (node, node_listener) = match self.stream_globals.get(&node_id) {
+            Some(global) => match self.registry.bind::<Node, _>(global) {
+                Ok(n) => {
+                    let listener = install_param_listener(&n, node_id, back);
+                    write_channel_volumes(&n, baseline);
+                    n.subscribe_params(&[ParamType::Props]);
+                    (Some(n), Some(listener))
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        node_id,
+                        error = %e,
+                        "Layer A: failed to bind Node proxy; volume writes + deference will be skipped"
+                    );
+                    (None, None)
+                }
+            },
+            None => {
+                tracing::warn!(
+                    node_id,
+                    "Layer A: no cached global for source node; volume writes + deference skipped"
+                );
+                (None, None)
+            }
+        };
+        self.managed_streams.insert(
+            node_id,
+            ManagedStream {
+                tap,
+                controller,
+                measurement_consumer: consumer,
+                node,
+                node_listener,
+                links: Vec::new(),
+                app_label: app_label.to_owned(),
+            },
+        );
+        tracing::info!(node_id, app = app_label, "Layer A tap spawned");
+        if let Ok(event) = Event::new(
+            Topic::Routing,
+            "layer_a_attached",
+            &json!({ "node_id": node_id, "app": app_label }),
+        ) {
+            self.daemon.lock().broadcaster.publish(Topic::Routing, event);
+        }
+    }
+
+    /// self-healing: spawn a tap for any known stream that should be
+    /// managed but isn't, regardless of why it missed its one
+    /// `try_route_stream` spawn. runs every drain so a miss recovers in
+    /// one tick.
+    fn reconcile_layer_a(&mut self, back: &Rc<RefCell<Self>>) {
+        let per_app = self.daemon.lock().profiles.effective().per_app.clone();
+        if !per_app.enabled {
+            return; // master off
+        }
+        let candidates: Vec<PwNodeInfo> = self
+            .known_streams
+            .values()
+            .filter(|info| !self.managed_streams.contains_key(&info.node_id))
+            .cloned()
+            .collect();
+        for info in candidates {
+            if let LayerAEval::Spawn(rule) = app_level::evaluate(&info, &per_app) {
+                let app_label = info_app_label(&info);
+                tracing::debug!(
+                    node_id = info.node_id,
+                    app = app_label.as_str(),
+                    "Layer A reconcile: re-attaching a stream that missed its spawn"
+                );
+                self.spawn_layer_a(info.node_id, rule, &app_label, back);
+            }
+        }
+    }
+
+    /// re-evaluate managed + known streams against `[per_app]`: tear
+    /// down taps that no longer match, spawn ones that now do. posted as
+    /// `PwCommand::ReevaluateLayerA` by the per-app / master setters.
+    fn reevaluate_layer_a(&mut self, back: &Rc<RefCell<Self>>) {
+        let per_app = self.daemon.lock().profiles.effective().per_app.clone();
+        let managed_ids: Vec<u32> = self.managed_streams.keys().copied().collect();
+        for node_id in managed_ids {
+            let Some(info) = self.known_streams.get(&node_id).cloned() else {
+                continue;
+            };
+            match app_level::evaluate(&info, &per_app) {
+                // still managed: push the (maybe new) rule into the live
+                // controller — thresholds change in place, no tap churn,
+                // ceiling + deference + envelope preserved.
+                LayerAEval::Spawn(rule) => {
+                    if let Some(managed) = self.managed_streams.get_mut(&node_id) {
+                        managed.controller.set_rule(rule);
+                    }
+                }
+                // no longer managed: release the tap + gain.
+                other => {
+                    tracing::info!(
+                        node_id,
+                        reason = other.skip_reason(),
+                        "Layer A: stopping per-app management for this stream (per-app disabled \
+                         for the app or globally)"
+                    );
+                    self.teardown_managed_stream(node_id, true);
+                }
+            }
+        }
+        self.reconcile_layer_a(back);
+    }
+
+    /// restore every managed stream's pre-management volume (ceiling or
+    /// unity) on graceful shutdown so attenuated apps aren't left
+    /// reduced. best-effort; caller pumps the loop to flush the writes.
+    pub fn restore_all_managed_volumes(&self) {
+        for (&node_id, managed) in &self.managed_streams {
+            let Some(node) = managed.node.as_ref() else {
+                continue;
+            };
+            let restore_to = managed.controller.user_ceiling_lin().unwrap_or(1.0);
+            write_channel_volumes(node, restore_to);
+            tracing::info!(
+                node_id,
+                restore_to,
+                app = managed.app_label.as_str(),
+                "restoring managed stream volume on shutdown"
+            );
+        }
+    }
+
+    /// tear down a managed Layer A stream: optionally restore volume
+    /// (so a policy-disable releases the gain), persist the ceiling for
+    /// the app's next instance, drop the tap, emit `layer_a_detached`.
+    /// `restore_volume = false` from `on_global_remove` (stream gone),
+    /// `true` from `reevaluate_layer_a` (policy disable).
+    fn teardown_managed_stream(&mut self, node_id: u32, restore_volume: bool) {
+        let Some(managed) = self.managed_streams.remove(&node_id) else {
+            return;
+        };
+        if restore_volume {
+            if let Some(node) = managed.node.as_ref() {
+                let restore_to = managed.controller.user_ceiling_lin().unwrap_or(1.0);
+                write_channel_volumes(node, restore_to);
+                tracing::debug!(
+                    node_id,
+                    restore_to,
+                    "Layer A: restored stream volume on teardown"
+                );
+            }
+        }
+        if let Some(ceiling) = managed.controller.user_ceiling_lin() {
+            if !managed.app_label.is_empty() {
+                self.persisted_ceilings
+                    .insert(managed.app_label.clone(), ceiling);
+                tracing::debug!(
+                    node_id,
+                    app = managed.app_label.as_str(),
+                    ceiling,
+                    "Layer A: persisted user_ceiling for next instance"
+                );
+            }
+        }
+        {
+            let mut s = self.daemon.lock();
+            s.layer_a.remove(&node_id);
+            if let Ok(event) = Event::new(
+                Topic::Routing,
+                "layer_a_detached",
+                &json!({ "node_id": node_id }),
+            ) {
+                s.broadcaster.publish(Topic::Routing, event);
+            }
+        }
+        tracing::info!(node_id, "Layer A tap torn down");
+        drop(managed);
+    }
+
+    /// drain each managed stream's measurement ring, advance its
+    /// controller, write `Props.channelVolumes` on change. also retries
+    /// explicit-link creation. called by the 5 ms timer in
+    /// [`crate::pw::PwContext::run_until_signal`].
+    pub fn drain_layer_a(&mut self, back: &Rc<RefCell<Self>>) {
+        self.attempt_pending_links();
+
+        // collect meter events to emit after the iter_mut borrow drops
+        // (broadcaster is behind the daemon mutex; avoid nested borrows).
+        let mut meters: Vec<(u32, String, f32, f32)> = Vec::new();
+        let mut snapshots: Vec<LayerASnapshot> = Vec::with_capacity(self.managed_streams.len());
+
+        let now = std::time::Instant::now();
+        for (&source_node_id, managed) in self.managed_streams.iter_mut() {
+            while let Ok(sample) = managed.measurement_consumer.pop() {
+                let Some(volume_lin) =
+                    managed.controller.process_block(sample.peak, sample.mean_sq, now)
+                else {
+                    continue;
+                };
+                let Some(node) = managed.node.as_ref() else {
+                    tracing::trace!(
+                        target_volume = volume_lin,
+                        "Layer A wanted to write volume but no Node proxy was bound"
+                    );
+                    continue;
+                };
+                write_channel_volumes(node, volume_lin);
+                meters.push((
+                    source_node_id,
+                    managed.app_label.clone(),
+                    volume_lin,
+                    managed.controller.smoothed_reduction_db(),
+                ));
+            }
+            // advance envelopes through a silent gap (source suspension,
+            // e.g. Strawberry between tracks, stops the audio thread);
+            // else the gain freezes at the last value. no-op when
+            // measurements flow.
+            if let Some(volume_lin) = managed.controller.tick_silent(now) {
+                if let Some(node) = managed.node.as_ref() {
+                    write_channel_volumes(node, volume_lin);
+                    meters.push((
+                        source_node_id,
+                        managed.app_label.clone(),
+                        volume_lin,
+                        managed.controller.smoothed_reduction_db(),
+                    ));
+                }
+            }
+
+            snapshots.push(LayerASnapshot {
+                node_id: source_node_id,
+                app: managed.app_label.clone(),
+                managed: true,
+                volume_lin: managed.controller.last_written_lin(),
+                reduction_db: managed.controller.smoothed_reduction_db(),
+                user_ceiling_lin: managed.controller.user_ceiling_lin(),
+                deferred: managed.controller.deferred(),
+            });
+        }
+
+        {
+            let mut s = self.daemon.lock();
+            for snap in snapshots {
+                s.layer_a.insert(snap.node_id, snap);
+            }
+            for (node_id, app, volume, reduction_db) in meters {
+                if let Ok(event) = Event::new(
+                    Topic::Meters,
+                    "layer_a_level",
+                    &json!({
+                        "node_id": node_id,
+                        "app": app,
+                        "volume_lin": volume,
+                        "reduction_db": reduction_db,
+                    }),
+                ) {
+                    s.broadcaster.publish(Topic::Meters, event);
+                }
+            }
+        }
+
+        self.reconcile_layer_a(back);
+    }
+
+    /// for each managed stream lacking links, if both port sets are in
+    /// the cache, pair by ordinal and create one passive `Link` per
+    /// channel. idempotent.
+    fn attempt_pending_links(&mut self) {
+        // snapshot first so we don't hold &mut self across the
+        // link-factory calls (which need &self.core).
+        let pending: Vec<(u32, u32)> = self
+            .managed_streams
+            .iter()
+            .filter(|(_, m)| m.links.is_empty())
+            .map(|(&src_id, m)| (src_id, m.tap.tap_node_id()))
+            .collect();
+
+        for (source_node_id, tap_node_id) in pending {
+            if tap_node_id == 0 {
+                // Stream isn't bound yet; retry next tick.
+                continue;
+            }
+            let Some(src_outs) = collect_ports(
+                &self.ports_by_node,
+                source_node_id,
+                PortDirection::Out,
+            ) else {
+                continue;
+            };
+            let Some(tap_ins) =
+                collect_ports(&self.ports_by_node, tap_node_id, PortDirection::In)
+            else {
+                continue;
+            };
+
+            // Stereo only in v0 — pair by per-node ordinal. If counts
+            // mismatch, skip and retry (ports may still be arriving).
+            if src_outs.len() < 2 || tap_ins.len() < 2 {
+                continue;
+            }
+
+            let mut created = Vec::with_capacity(2);
+            let mut all_ok = true;
+            for (out, inp) in src_outs.iter().take(2).zip(tap_ins.iter().take(2)) {
+                match create_explicit_link(&self.core, out.port_id, inp.port_id) {
+                    Ok(link) => created.push(link),
+                    Err(e) => {
+                        tracing::warn!(
+                            source = source_node_id,
+                            tap = tap_node_id,
+                            out_port = out.port_id,
+                            in_port = inp.port_id,
+                            error = %e,
+                            "Layer A explicit link creation failed; will retry next tick"
+                        );
+                        all_ok = false;
+                        break;
+                    }
+                }
+            }
+            if all_ok && !created.is_empty() {
+                if let Some(m) = self.managed_streams.get_mut(&source_node_id) {
+                    tracing::info!(
+                        source = source_node_id,
+                        tap = tap_node_id,
+                        links = created.len(),
+                        "Layer A explicit passive links created"
+                    );
+                    m.links = created;
+                }
+            }
+        }
+    }
+
+    /// record routing intent for `node_id`; `apply_pending_routes`
+    /// later builds the explicit links. last intent wins.
+    fn enqueue_route(
+        &mut self,
+        node_id: u32,
+        target_sink_name: String,
+        app_label: String,
+        route: Route,
+    ) {
+        // already-correct links to the same sink are left alone (the
+        // apply pass no-ops), avoiding the 21-42 ms gap an
+        // unconditional rebuild would cost. only drop the proxies when
+        // the target actually changed.
+        let already_at_target = self
+            .managed_route_links
+            .get(&node_id)
+            .is_some_and(|m| m.target_sink_name == target_sink_name);
+        if !already_at_target {
+            self.managed_route_links.remove(&node_id);
+        }
+        self.pending_routes.insert(
+            node_id,
+            PendingRoute {
+                target_sink_name,
+                app_label,
+                route,
+            },
+        );
+    }
+
+    /// drain `pending_routes`: for each stream whose source + target
+    /// ports are both on the registry, tear down conflicting outbound
+    /// links and create the explicit ones. not-ready intents stay queued.
+    fn apply_pending_routes(&mut self) {
+        // snapshot keys: we mutate `managed_route_links` while iterating.
+        let candidates: Vec<u32> = self.pending_routes.keys().copied().collect();
+        if !candidates.is_empty() {
+            tracing::debug!(
+                pending = candidates.len(),
+                "apply_pending_routes pass"
+            );
+        }
+        for node_id in candidates {
+            let Some(intent) = self.pending_routes.get(&node_id).cloned() else {
+                continue;
+            };
+
+            let Some(target_node) = self.resolve_routing_target(&intent.target_sink_name) else {
+                tracing::debug!(
+                    node_id,
+                    target = intent.target_sink_name.as_str(),
+                    "pending route: target not yet on registry"
+                );
+                continue; // target not yet on registry
+            };
+            let Some(src_outs) =
+                collect_ports(&self.ports_by_node, node_id, PortDirection::Out)
+            else {
+                tracing::debug!(node_id, "pending route: source has no output ports yet");
+                continue;
+            };
+            let Some(target_ins) =
+                collect_ports(&self.ports_by_node, target_node, PortDirection::In)
+            else {
+                tracing::debug!(node_id, target_node, "pending route: target has no input ports yet");
+                continue;
+            };
+            // pair by ordinal up to the narrower side (all N channels,
+            // so surround isn't truncated to stereo). mono (N=1) is
+            // intentionally left to WP's upmix adapter — 1→N fanout +
+            // stereo-link limiter semantics don't generalise, so
+            // `route.set` on a mono app is a hint, not enforcement
+            // (v0; fixed in the v1 multichannel pipeline).
+            let pair_count = src_outs.len().min(target_ins.len());
+            if pair_count < 2 {
+                tracing::debug!(
+                    node_id,
+                    src_outs = src_outs.len(),
+                    target_ins = target_ins.len(),
+                    "pending route: not enough ports for stereo+ pairing (mono left to WP)"
+                );
+                continue;
+            }
+            let want: Vec<(u32, u32)> = src_outs
+                .iter()
+                .take(pair_count)
+                .zip(target_ins.iter().take(pair_count))
+                .map(|(o, i)| (o.port_id, i.port_id))
+                .collect();
+            let want_set: std::collections::HashSet<(u32, u32)> = want.iter().copied().collect();
+
+            // 1) destroy outbound links to a *different* sink; leave
+            // non-sink links (Layer A taps) alone.
+            let existing: Vec<u32> = self
+                .outbound_links_by_node
+                .get(&node_id)
+                .cloned()
+                .unwrap_or_default();
+            for link_id in existing {
+                let Some(info) = self.links_by_id.get(&link_id).copied() else {
+                    continue;
+                };
+                if want_set.contains(&(info.output_port, info.input_port)) {
+                    continue; // already correct — keep
+                }
+                if !self.is_routing_target(info.input_node) {
+                    continue; // probably a Layer A tap or similar
+                }
+                if let Err(e) = self.registry.destroy_global(link_id).into_result() {
+                    tracing::warn!(
+                        link_id,
+                        node_id,
+                        target = intent.target_sink_name.as_str(),
+                        error = ?e,
+                        "apply_pending_routes: destroy_global failed"
+                    );
+                }
+            }
+
+            // 2) Create any missing wanted links.
+            let already_wanted: std::collections::HashSet<(u32, u32)> = self
+                .outbound_links_by_node
+                .get(&node_id)
+                .into_iter()
+                .flatten()
+                .filter_map(|id| self.links_by_id.get(id))
+                .map(|info| (info.output_port, info.input_port))
+                .collect();
+            let mut created: Vec<Link> = self
+                .managed_route_links
+                .remove(&node_id)
+                .map(|m| m.links)
+                .unwrap_or_default();
+            let mut all_ok = true;
+            for (out_port, in_port) in &want {
+                if already_wanted.contains(&(*out_port, *in_port)) {
+                    continue;
+                }
+                match create_routing_link(&self.core, *out_port, *in_port) {
+                    Ok(link) => created.push(link),
+                    Err(e) => {
+                        tracing::warn!(
+                            node_id,
+                            out_port,
+                            in_port,
+                            target = intent.target_sink_name.as_str(),
+                            error = %e,
+                            "apply_pending_routes: create_object failed; retry next tick"
+                        );
+                        all_ok = false;
+                        break;
+                    }
+                }
+            }
+            if !created.is_empty() {
+                self.managed_route_links.insert(
+                    node_id,
+                    ManagedRoute {
+                        target_sink_name: intent.target_sink_name.clone(),
+                        links: created,
+                    },
+                );
+            }
+            if all_ok {
+                tracing::info!(
+                    node_id,
+                    app = intent.app_label.as_str(),
+                    target = intent.target_sink_name.as_str(),
+                    route = intent.route.as_str(),
+                    "explicit routing link established"
+                );
+                self.pending_routes.remove(&node_id);
+            }
+        }
+    }
+
+    /// write `target.object = {"name":"<sink_name>"}` for `node_id`.
+    fn write_stream_target(&self, node_id: u32, sink_name: &str, app_label: &str) {
+        let Some(md) = &self.default_metadata else {
+            tracing::warn!(node_id, "no default metadata bound; cannot apply target.object");
+            return;
+        };
+        let value = format_sink_target_value(sink_name);
+        md.set_property(node_id, TARGET_OBJECT_KEY, Some(SPA_JSON_TYPE), Some(&value));
+        tracing::info!(node_id, app = app_label, target = sink_name, "routed");
+    }
+
+    /// write `default.audio.sink` (subject 0, system-wide).
+    fn write_default_audio_sink(&self, sink_name: &str) {
+        let Some(md) = &self.default_metadata else {
+            tracing::warn!("no default metadata bound; cannot write default.audio.sink");
+            return;
+        };
+        let value = format_sink_target_value(sink_name);
+        md.set_property(
+            METADATA_SUBJECT_GLOBAL,
+            DEFAULT_AUDIO_SINK_KEY,
+            Some(SPA_JSON_TYPE),
+            Some(&value),
+        );
+        tracing::info!(sink_name, "wrote default.audio.sink");
+    }
+
+    /// handle a `default` metadata property change; only
+    /// `default.audio.sink` matters.
+    fn on_metadata_property(&mut self, subject: u32, key: Option<&str>, value: Option<&str>) {
+        if subject != METADATA_SUBJECT_GLOBAL {
+            return;
+        }
+        if key != Some(DEFAULT_AUDIO_SINK_KEY) {
+            return;
+        }
+        let Some(raw) = value else {
+            // key removed; keep the last-known real sink for retargets.
+            tracing::warn!("default.audio.sink cleared on server side");
+            return;
+        };
+        let Some(name) = parse_default_sink_name(raw) else {
+            tracing::warn!(raw, "failed to parse default.audio.sink value");
+            return;
+        };
+        if name == PROCESSED_SINK_NAME {
+            // our own promotion echo.
+            tracing::debug!("default.audio.sink is headroom-processed (expected)");
+            return;
+        }
+        self.adopt_new_real_sink(name);
+    }
+
+    /// re-assert `default.audio.sink = headroom-processed`, capped at
+    /// `MAX_PER_WINDOW` per `WINDOW` so a WP that keeps rewriting our
+    /// value back can't hot-loop us. explicit links still enforce
+    /// routing whichever side wins the default.
+    fn reassert_default_processed(&mut self) {
+        // under default-bypass policy, stop fighting WP for the default so
+        // `default`-following apps land at the real sink — else
+        // "bypass on" wouldn't bypass for them.
+        if self.default_should_bypass() {
+            return;
+        }
+        const WINDOW: std::time::Duration = std::time::Duration::from_secs(1);
+        const MAX_PER_WINDOW: u32 = 10;
+        let now = std::time::Instant::now();
+        match &mut self.default_reassertion {
+            Some((started, n)) if now.duration_since(*started) < WINDOW => {
+                if *n >= MAX_PER_WINDOW {
+                    tracing::debug!(
+                        attempts = *n,
+                        "default.audio.sink re-assertion budget exhausted for this window"
+                    );
+                    return;
+                }
+                *n += 1;
+            }
+            _ => {
+                self.default_reassertion = Some((now, 1));
+            }
+        }
+        self.write_default_audio_sink(PROCESSED_SINK_NAME);
+    }
+
+    fn write_policy_default_audio_sink(&self) {
+        if self.default_should_bypass() {
+            let real_sink_name = { self.daemon.lock().real_sink.name.clone() };
+            if let Some(name) = real_sink_name {
+                tracing::info!(
+                    sink = name.as_str(),
+                    "bypass default: setting default.audio.sink to real sink"
+                );
+                self.write_default_audio_sink(&name);
+            } else {
+                tracing::warn!(
+                    "bypass default requested but no real sink known yet — leaving default.audio.sink alone"
+                );
+            }
+        } else {
+            self.write_default_audio_sink(PROCESSED_SINK_NAME);
+        }
+    }
+
+    fn default_should_bypass(&self) -> bool {
+        let s = self.daemon.lock();
+        s.profiles.bypass_global() || s.profiles.effective().default_route.route == Route::Bypass
+    }
+
+    /// update `preferred_real_sink`, retarget every bypass-routed
+    /// stream + the filter, re-assert headroom-processed as default.
+    fn adopt_new_real_sink(&mut self, new_sink_name: String) {
+        let (bypass_targets, resolved_node_id) = {
+            let mut s = self.daemon.lock();
+            let Some(targets) = s.apply_real_sink_change(&new_sink_name) else {
+                // sink unchanged, WP just moved default away; re-assert.
+                drop(s);
+                self.reassert_default_processed();
+                return;
+            };
+            // resolve node_id now if known; else try_capture_real_sink
+            // fills it on the next global.
+            let resolved = self.sinks_by_name.get(&new_sink_name).copied();
+            if let Some(id) = resolved {
+                s.real_sink.node_id = Some(id);
+            }
+            (targets, resolved)
+        };
+        tracing::info!(
+            sink = new_sink_name.as_str(),
+            node_id = ?resolved_node_id,
+            "preferred_real_sink updated"
+        );
+
+        for (node_id, app_label) in &bypass_targets {
+            self.write_stream_target(*node_id, &new_sink_name, app_label);
+            self.enqueue_route(
+                *node_id,
+                new_sink_name.clone(),
+                app_label.clone(),
+                Route::Bypass,
+            );
+        }
+        if !bypass_targets.is_empty() {
+            tracing::info!(
+                retargeted = bypass_targets.len(),
+                sink = new_sink_name.as_str(),
+                "retargeted bypass streams"
+            );
+        }
+
+        // retarget the filter (no `target.object` — we own its
+        // linking; WP wouldn't honour it for a pw_filter anyway).
+        self.sync_bus_graph_links();
+
+        // re-assert headroom-processed as default for new streams.
+        self.reassert_default_processed();
+
+        let event = Event::new(
+            Topic::Routing,
+            "real_sink_changed",
+            &json!({ "name": new_sink_name, "node_id": resolved_node_id }),
+        );
+        if let Ok(event) = event {
+            self.daemon.lock().broadcaster.publish(Topic::Routing, event);
+        }
+    }
+
+    fn record_route(&self, node_id: u32, app: String, route: Route) {
+        let mut s = self.daemon.lock();
+        s.streams.insert(
+            node_id,
+            RoutedStream {
+                node_id,
+                app: app.clone(),
+                route,
+            },
+        );
+        if let Ok(event) = Event::new(
+            Topic::Routing,
+            "stream_routed",
+            &json!({
+                "node_id": node_id,
+                "app": app,
+                "to": route.as_str(),
+            }),
+        ) {
+            s.broadcaster.publish(Topic::Routing, event);
+        }
+    }
+
+    fn on_global_remove(&mut self, node_id: u32) {
+        // best-effort cleanup over a mixed id namespace; missing-key
+        // removes are harmless. port cleanup is scoped via `port_owner`
+        // so a node removal isn't conflated with a port removal under
+        // id reuse (the old "retain by port_id across all nodes" could
+        // wipe a live node's ports).
+        if let Some(owner) = self.port_owner.remove(&node_id) {
+            if let Some(ports) = self.ports_by_node.get_mut(&owner) {
+                ports.retain(|p| p.port_id != node_id);
+                if ports.is_empty() {
+                    self.ports_by_node.remove(&owner);
+                }
+            }
+        } else if let Some(ports) = self.ports_by_node.remove(&node_id) {
+            for p in ports {
+                self.port_owner.remove(&p.port_id);
+            }
+        }
+
+        // node_id may be a link global, or a node whose links we forget.
+        if let Some(info) = self.links_by_id.remove(&node_id) {
+            if let Some(v) = self.outbound_links_by_node.get_mut(&info.output_node) {
+                v.retain(|&id| id != node_id);
+                if v.is_empty() {
+                    self.outbound_links_by_node.remove(&info.output_node);
+                }
+            }
+        }
+        self.outbound_links_by_node.remove(&node_id);
+        self.links_by_id
+            .retain(|_, info| info.output_node != node_id && info.input_node != node_id);
+
+        // stream gone — drop intent + cache so reapply doesn't route a
+        // dead node.
+        self.pending_routes.remove(&node_id);
+        self.managed_route_links.remove(&node_id);
+        self.known_streams.remove(&node_id);
+        self.stream_globals.remove(&node_id);
+
+        if self.filter_playback_id == Some(node_id) {
+            tracing::debug!(node_id, "filter playback removed from registry");
+            self.filter_playback_id = None;
+        }
+        self.sinks_by_name.retain(|name, &mut id| {
+            if id == node_id {
+                tracing::debug!(node_id, name, "real sink removed from registry");
+                let mut s = self.daemon.lock();
+                // clear BOTH name and node_id: nulling only node_id
+                // leaves the name pinned to a dead sink, so every
+                // bypass route queues forever against a stale target.
+                if s.real_sink.name.as_deref() == Some(name.as_str()) {
+                    s.real_sink.name = None;
+                    s.real_sink.node_id = None;
+                    s.real_sink.sample_rate = None;
+                    drop(s);
+                    // the Format listener points at a dead node.
+                    if let Some((prev_id, _, _)) = &self.real_sink_format_listener {
+                        if *prev_id == node_id {
+                            self.real_sink_format_listener = None;
+                        }
+                    }
+                } else if s.real_sink.node_id == Some(node_id) {
+                    // defensive: id matched but name didn't.
+                    s.real_sink.node_id = None;
+                }
+                false
+            } else {
+                true
+            }
+        });
+        // node gone, so don't restore volume — just persist the ceiling
+        // and tear down the tap.
+        self.teardown_managed_stream(node_id, false);
+        let mut s = self.daemon.lock();
+        let removed = s.streams.remove(&node_id);
+        if removed.is_some() {
+            tracing::debug!(node_id, "stream removed");
+            if let Ok(event) = Event::new(
+                Topic::Routing,
+                "stream_removed",
+                &json!({ "node_id": node_id }),
+            ) {
+                s.broadcaster.publish(Topic::Routing, event);
+            }
+        }
+    }
+}
+
+/// `param` listener forwarding external `channelVolumes` changes to
+/// the controller's `on_external_change` — the user-volume-deference
+/// loop.
+fn install_param_listener(
+    node: &Node,
+    source_node_id: u32,
+    back: &Rc<RefCell<RoutingState>>,
+) -> NodeListener {
+    let back = back.clone();
+    node.add_listener_local()
+        .param(move |_seq, id, _index, _next, param_opt| {
+            if id != ParamType::Props {
+                return;
+            }
+            let Some(param) = param_opt else { return };
+            let Some(new_volume) = extract_channel_volume(param) else {
+                return;
+            };
+            let mut state = back.borrow_mut();
+            let Some(managed) = state.managed_streams.get_mut(&source_node_id) else {
+                return;
+            };
+            managed.controller.on_external_change(new_volume);
+            tracing::debug!(
+                source = source_node_id,
+                new_volume,
+                user_ceiling = ?managed.controller.user_ceiling_lin(),
+                deferred = managed.controller.deferred(),
+                "Layer A observed external Props.channelVolumes change"
+            );
+        })
+        .register()
+}
+
+/// pull `SPA_FORMAT_AUDIO_rate` from a `Format` POD (ALSA sinks expose
+/// rate only here, not in the props dict). `None` if absent.
+fn extract_audio_rate(pod: &Pod) -> Option<u32> {
+    let bytes = pod.as_bytes();
+    let (_, value) = PodDeserializer::deserialize_any_from(bytes).ok()?;
+    let Value::Object(obj) = value else { return None };
+    if obj.id != ParamType::Format.as_raw() {
+        return None;
+    }
+    for prop in obj.properties {
+        if prop.key == libspa_sys::SPA_FORMAT_AUDIO_rate {
+            if let Value::Int(rate) = prop.value {
+                if rate > 0 {
+                    return Some(rate as u32);
+                }
+            }
+        }
+    }
+    None
+}
+
+/// pull the first channel of `SPA_PROP_channelVolumes` from a `Props`
+/// POD. `None` if absent or the wrong shape.
+fn extract_channel_volume(pod: &Pod) -> Option<f32> {
+    let bytes = pod.as_bytes();
+    let (_, value) = PodDeserializer::deserialize_any_from(bytes).ok()?;
+    let Value::Object(obj) = value else { return None };
+    if obj.id != ParamType::Props.as_raw() {
+        return None;
+    }
+    for prop in obj.properties {
+        if prop.key == libspa_sys::SPA_PROP_channelVolumes {
+            if let Value::ValueArray(ValueArray::Float(values)) = prop.value {
+                return values.first().copied();
+            }
+        }
+    }
+    None
+}
+
+/// ports of a given direction owned by `node_id`, sorted by ordinal so
+/// pairs line up across source/tap calls.
+fn collect_ports(
+    cache: &HashMap<u32, Vec<PortInfo>>,
+    node_id: u32,
+    direction: PortDirection,
+) -> Option<Vec<PortInfo>> {
+    let ports = cache.get(&node_id)?;
+    let mut filtered: Vec<PortInfo> = ports
+        .iter()
+        .filter(|p| p.direction == direction)
+        .cloned()
+        .collect();
+    if filtered.is_empty() {
+        return None;
+    }
+    // ordinal 0 ↔ FL, 1 ↔ FR (PipeWire convention); port_id breaks
+    // ties for ports lacking `port.id`.
+    filtered.sort_by_key(|p| (p.ordinal.unwrap_or(u32::MAX), p.port_id));
+    Some(filtered)
+}
+
+/// passive `link-factory` link with explicit port ids. `passive` so the
+/// tap rides alongside without driving the source.
+fn create_explicit_link(core: &Core, output_port: u32, input_port: u32) -> Result<Link, pipewire::Error> {
+    let out_str = output_port.to_string();
+    let in_str = input_port.to_string();
+    let props = properties! {
+        "link.output.port" => out_str.as_str(),
+        "link.input.port" => in_str.as_str(),
+        "link.passive" => "true",
+        "object.linger" => "false",
+    };
+    core.create_object::<Link>("link-factory", &props)
+}
+
+/// active `link-factory` link that drives the sink — forces routing
+/// where WP's `target.object` is unreliable for already-linked streams.
+fn create_routing_link(core: &Core, output_port: u32, input_port: u32) -> Result<Link, pipewire::Error> {
+    let out_str = output_port.to_string();
+    let in_str = input_port.to_string();
+    let props = properties! {
+        "link.output.port" => out_str.as_str(),
+        "link.input.port" => in_str.as_str(),
+        "object.linger" => "false",
+    };
+    core.create_object::<Link>("link-factory", &props)
+}
+
+/// write `Props.channelVolumes = [vol, vol]` (stereo) to the node for
+/// Layer A attenuation. allocates a POD on the heap; not on the rt
+/// thread.
+fn write_channel_volumes(node: &Node, volume_lin: f32) {
+    let obj = PodObject {
+        type_: SpaTypes::ObjectParamProps.as_raw(),
+        id: ParamType::Props.as_raw(),
+        properties: vec![Property {
+            key: libspa_sys::SPA_PROP_channelVolumes,
+            flags: PropertyFlags::empty(),
+            value: Value::ValueArray(ValueArray::Float(vec![volume_lin, volume_lin])),
+        }],
+    };
+    let serialised = match PodSerializer::serialize(
+        std::io::Cursor::new(Vec::new()),
+        &Value::Object(obj),
+    ) {
+        Ok((cursor, _)) => cursor.into_inner(),
+        Err(e) => {
+            tracing::warn!(error = %e, "channelVolumes POD serialize failed");
+            return;
+        }
+    };
+    let Some(pod) = Pod::from_bytes(&serialised) else {
+        tracing::warn!("channelVolumes Pod::from_bytes returned None");
+        return;
+    };
+    node.set_param(ParamType::Props, 0, pod);
+    tracing::debug!(volume = volume_lin, "Layer A wrote channelVolumes");
+}
+
+fn info_app_label(info: &PwNodeInfo) -> String {
+    info.application_process_binary
+        .clone()
+        .or_else(|| info.application_name.clone())
+        .unwrap_or_default()
+}
+
+fn build_node_info(node_id: u32, dict: &DictRef) -> PwNodeInfo {
+    PwNodeInfo {
+        node_id,
+        media_class: dict.get("media.class").map(str::to_owned),
+        application_process_binary: dict.get("application.process.binary").map(str::to_owned),
+        application_name: dict.get("application.name").map(str::to_owned),
+        portal_app_id: dict
+            .get("pipewire.access.portal.app_id")
+            .map(str::to_owned),
+        media_role: dict.get("media.role").map(str::to_owned),
+        dont_move: dict.get("node.dont-move") == Some("true"),
+        audio_channels: dict.get("audio.channels").and_then(|s| s.parse::<u32>().ok()),
+    }
+}
+
+fn install_listener(registry: &Registry, state: Rc<RefCell<RoutingState>>) -> Listener {
+    let state_for_global = state.clone();
+    let state_for_remove = state;
+    registry
+        .add_listener_local()
+        .global(move |global| {
+            let back = state_for_global.clone();
+            state_for_global.borrow_mut().on_global(global, &back);
+        })
+        .global_remove(move |id| {
+            state_for_remove.borrow_mut().on_global_remove(id);
+        })
+        .register()
+}
+
+/// owns the registry, routing state, and listener. drop order matters:
+/// listener before registry (field order ensures it).
+pub struct RegistryWatcher {
+    _listener: Listener,
+    state: Rc<RefCell<RoutingState>>,
+    _registry: Rc<Registry>,
+}
+
+impl RegistryWatcher {
+    /// builds the IPC → PipeWire command channel and writes its sender
+    /// into `daemon.pw_command_tx` so IPC handlers can post from any
+    /// thread.
+    pub fn new(registry: Rc<Registry>, core: Core, daemon: SharedState) -> Self {
+        let (tx, rx) = crossbeam_channel::unbounded::<PwCommand>();
+        daemon.lock().pw_command_tx = Some(tx);
+        let state = Rc::new(RefCell::new(RoutingState::new(
+            daemon,
+            registry.clone(),
+            core,
+            rx,
+        )));
+        let listener = install_listener(&registry, state.clone());
+        Self {
+            _listener: listener,
+            state,
+            _registry: registry,
+        }
+    }
+
+    /// per-thread routing state; mostly for tests + instrumentation.
+    #[must_use]
+    pub fn state(&self) -> &Rc<RefCell<RoutingState>> {
+        &self.state
+    }
+}

Added file: crates/headroom-core/src/pw/sink.rs+77 additions@@ -0,0 +1,77 @@
+//! `headroom-processed` virtual sink (the bus filter captures from its
+//! monitor; bypassed streams skip it).
+
+use pipewire::{core::Core, node::Node, properties::properties};
+
+use crate::error::DaemonError;
+
+/// stable, user-visible in `pavucontrol`, `pw-cli list-objects`, etc.
+pub const NODE_NAME: &str = "headroom-processed";
+
+pub const NODE_DESCRIPTION: &str = "Headroom (processed)";
+
+pub struct VirtualSink {
+    /// holds the sink alive on the server; drop destroys it. `None`
+    /// until [`Self::create`].
+    proxy: Option<Node>,
+}
+
+impl VirtualSink {
+    #[must_use]
+    pub fn new() -> Self {
+        Self { proxy: None }
+    }
+
+    /// create the virtual sink. uses the generic `adapter` factory
+    /// (always present) wrapping `support.null-audio-sink` (the SPA
+    /// factory that yields a null sink with a monitor port).
+    ///
+    /// `sample_rate` → `audio.rate` so the sink clocks at the real
+    /// sink's rate; otherwise it defaults to 48 kHz and the capture
+    /// adapter resamples — that buffering across two drivers caused
+    /// the per-quantum tremolo seen in soak.
+    ///
+    /// # Errors
+    /// [`DaemonError::PipeWire`] if the server rejects create-object.
+    pub fn create(&mut self, core: &Core, sample_rate: u32) -> Result<(), DaemonError> {
+        let rate_str = sample_rate.to_string();
+        let props = properties! {
+            // SPA factory the adapter wraps → null sink with monitor.
+            "factory.name" => "support.null-audio-sink",
+            "node.name" => NODE_NAME,
+            "node.description" => NODE_DESCRIPTION,
+            // monitor we can capture from.
+            "media.class" => "Audio/Sink",
+            // stereo; >2ch bypasses entirely.
+            "audio.position" => "FL,FR",
+            // lock to real-sink rate — no resampling at monitor → filter.
+            "audio.rate" => rate_str.as_str(),
+            // follower, not driver: land both filter halves on the
+            // real sink's driver.
+            "node.passive" => "true",
+            "node.suspend-on-idle" => "true",
+        };
+
+        let proxy: Node = core
+            .create_object("adapter", &props)
+            .map_err(|e| DaemonError::pipewire(format!("create_object: {e}")))?;
+
+        self.proxy = Some(proxy);
+        tracing::debug!(
+            node.name = NODE_NAME,
+            "create_object(adapter, factory.name=support.null-audio-sink) queued"
+        );
+        Ok(())
+    }
+
+    #[must_use]
+    pub fn is_created(&self) -> bool {
+        self.proxy.is_some()
+    }
+}
+
+impl Default for VirtualSink {
+    fn default() -> Self {
+        Self::new()
+    }
+}

Added file: crates/headroom-core/src/routing.rs+308 additions@@ -0,0 +1,308 @@
+//! pure routing policy; pipewire-free so it unit-tests without the daemon
+
+use headroom_ipc::{Route, RouteRuleMatch};
+
+use crate::profile::Profile;
+
+/// subset of a pw node's props the routing engine needs.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct PwNodeInfo {
+    pub node_id: u32,
+    /// e.g. `"Stream/Output/Audio"`, `"Audio/Sink"`
+    pub media_class: Option<String>,
+    /// kernel-sourced, highest reliability
+    pub application_process_binary: Option<String>,
+    /// client-set
+    pub application_name: Option<String>,
+    /// flatpak-set, trustworthy when present
+    pub portal_app_id: Option<String>,
+    /// rarely set
+    pub media_role: Option<String>,
+    /// `node.dont-move`; honoured by skipping routing entirely
+    pub dont_move: bool,
+    /// `None` if absent. `>2ch` forced to bypass: bus filter is stereo-only, so processing surround
+    /// would drop channels or downmix unrequested.
+    pub audio_channels: Option<u32>,
+}
+
+impl PwNodeInfo {
+    #[must_use]
+    pub fn is_routable_playback(&self) -> bool {
+        !self.dont_move && self.media_class.as_deref() == Some("Stream/Output/Audio")
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RoutingDecision {
+    Route(Route),
+    Skip,
+}
+
+/// `Skip` if not routable playback. `bypass_global` overrides every rule. else first-match route,
+/// falling back to the profile's `default_route`.
+#[must_use]
+pub fn evaluate(info: &PwNodeInfo, profile: &Profile, bypass_global: bool) -> RoutingDecision {
+    if !info.is_routable_playback() {
+        return RoutingDecision::Skip;
+    }
+    // real graph operation (4k explicit links to the real sink), not just a metadata write —
+    // see PwCommand::ReevaluateAll + `set_global_bypass`
+    if bypass_global {
+        return RoutingDecision::Route(Route::Bypass);
+    }
+    // stereo-only bus filter: processing >2ch would drop channels or downmix unrequested. straight
+    // to the real sink preserves the layout; pw's source-side adapter handles any downmix.
+    if matches!(info.audio_channels, Some(ch) if ch > 2) {
+        return RoutingDecision::Route(Route::Bypass);
+    }
+    for rule in &profile.rules {
+        if matches(info, &rule.match_) {
+            return RoutingDecision::Route(rule.route);
+        }
+    }
+    RoutingDecision::Route(profile.default_route.route)
+}
+
+/// true iff every present matcher field has a value equal to the node's. empty fields = don't care.
+pub(crate) fn matches(info: &PwNodeInfo, m: &RouteRuleMatch) -> bool {
+    let any_match = |needle: &Option<String>, hay: &[String]| -> bool {
+        if hay.is_empty() {
+            return true;
+        }
+        match needle {
+            Some(s) => hay.iter().any(|h| h == s),
+            None => false,
+        }
+    };
+
+    any_match(&info.application_process_binary, &m.process_binary)
+        && any_match(&info.application_name, &m.application_name)
+        && any_match(&info.portal_app_id, &m.portal_app_id)
+        && any_match(&info.media_role, &m.media_role)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn playback(binary: &str) -> PwNodeInfo {
+        PwNodeInfo {
+            node_id: 1,
+            media_class: Some("Stream/Output/Audio".into()),
+            application_process_binary: Some(binary.into()),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn non_playback_streams_are_skipped() {
+        let mut info = playback("firefox");
+        info.media_class = Some("Stream/Input/Audio".into());
+        let profile = Profile::default_v0();
+        assert_eq!(evaluate(&info, &profile, false), RoutingDecision::Skip);
+    }
+
+    #[test]
+    fn dont_move_opts_out() {
+        let mut info = playback("firefox");
+        info.dont_move = true;
+        let profile = Profile::default_v0();
+        assert_eq!(evaluate(&info, &profile, false), RoutingDecision::Skip);
+    }
+
+    #[test]
+    fn surround_streams_force_bypass_regardless_of_rule_match() {
+        // The default profile routes `firefox` to processed. A 5.1
+        // firefox stream (rare but valid — some browser content
+        // declares surround) must still bypass: the bus filter is
+        // stereo-only and the explicit-link path would otherwise
+        // drop FC/LFE/SL/SR (surround contract).
+        let mut info = playback("firefox");
+        info.audio_channels = Some(6);
+        let profile = Profile::default_v0();
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn stereo_and_mono_streams_follow_normal_rules() {
+        // Sanity: the surround forcer only kicks in for >2ch.
+        let profile = Profile::default_v0();
+        for ch in [None, Some(1), Some(2)] {
+            let mut info = playback("firefox");
+            info.audio_channels = ch;
+            assert_eq!(
+                evaluate(&info, &profile, false),
+                RoutingDecision::Route(Route::Processed),
+                "channels={ch:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn global_bypass_overrides_processed_rules() {
+        let info = playback("firefox");
+        let profile = Profile::default_v0();
+        assert_eq!(
+            evaluate(&info, &profile, true),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn application_name_only_rule_matches_stream_with_no_process_binary() {
+        // The shape `route set` emits when expanded into an
+        // `application_name`-keyed override. Verifies that a
+        // stream missing `application.process.binary` (typical
+        // of pw-cat, many CLI tools, some Flatpak wrappers) is
+        // still matched by the user's intent.
+        use headroom_ipc::{RouteRule, RouteRuleMatch};
+        let mut profile = Profile::default_v0();
+        // Override at the top of the rule list.
+        profile.rules.insert(
+            0,
+            RouteRule {
+                match_: RouteRuleMatch {
+                    application_name: vec!["pw-cat".into()],
+                    ..Default::default()
+                },
+                route: Route::Bypass,
+            },
+        );
+        // Stream advertises only application.name = "pw-cat".
+        let info = PwNodeInfo {
+            node_id: 9,
+            media_class: Some("Stream/Output/Audio".into()),
+            application_process_binary: None,
+            application_name: Some("pw-cat".into()),
+            ..Default::default()
+        };
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn matches_bypass_rule_for_known_music_player() {
+        let info = playback("mpv");
+        let profile = Profile::default_v0();
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn matches_processed_rule_for_browser() {
+        let info = playback("firefox");
+        let profile = Profile::default_v0();
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Processed)
+        );
+    }
+
+    #[test]
+    fn falls_back_to_default_route_when_no_rule_matches() {
+        let info = playback("some-obscure-binary");
+        let profile = Profile::default_v0();
+        // default_v0 has `default_route = Processed`.
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Processed)
+        );
+    }
+
+    #[test]
+    fn first_matching_rule_wins() {
+        // Build a profile whose first rule says everything matches
+        // → bypass, and second rule contradicts. First should win.
+        let mut profile = Profile::default_v0();
+        profile.rules.clear();
+        profile.rules.push(headroom_ipc::RouteRule {
+            match_: RouteRuleMatch {
+                process_binary: vec!["firefox".into()],
+                ..Default::default()
+            },
+            route: Route::Bypass,
+        });
+        profile.rules.push(headroom_ipc::RouteRule {
+            match_: RouteRuleMatch {
+                process_binary: vec!["firefox".into()],
+                ..Default::default()
+            },
+            route: Route::Processed,
+        });
+        let info = playback("firefox");
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn empty_matcher_acts_as_wildcard() {
+        let mut profile = Profile::default_v0();
+        profile.rules.clear();
+        profile.rules.push(headroom_ipc::RouteRule {
+            match_: RouteRuleMatch::default(), // all fields empty
+            route: Route::Bypass,
+        });
+        let info = playback("firefox");
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn multiple_match_fields_are_anded() {
+        let mut profile = Profile::default_v0();
+        profile.rules.clear();
+        profile.rules.push(headroom_ipc::RouteRule {
+            match_: RouteRuleMatch {
+                process_binary: vec!["firefox".into()],
+                media_role: vec!["Communication".into()],
+                ..Default::default()
+            },
+            route: Route::Bypass,
+        });
+
+        // process_binary matches but media_role doesn't (None on info).
+        let info = playback("firefox");
+        assert_ne!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+
+        // Both match.
+        let mut info2 = playback("firefox");
+        info2.media_role = Some("Communication".into());
+        assert_eq!(
+            evaluate(&info2, &profile, false),
+            RoutingDecision::Route(Route::Bypass)
+        );
+    }
+
+    #[test]
+    fn portal_app_id_can_match_when_present() {
+        let mut profile = Profile::default_v0();
+        profile.rules.clear();
+        profile.rules.push(headroom_ipc::RouteRule {
+            match_: RouteRuleMatch {
+                portal_app_id: vec!["com.discordapp.Discord".into()],
+                ..Default::default()
+            },
+            route: Route::Processed,
+        });
+        let mut info = playback("DiscordWrapper");
+        info.portal_app_id = Some("com.discordapp.Discord".into());
+        assert_eq!(
+            evaluate(&info, &profile, false),
+            RoutingDecision::Route(Route::Processed)
+        );
+    }
+}

Added file: crates/headroom-core/src/runtime.rs+173 additions@@ -0,0 +1,173 @@
+//! top-level orchestrator: wires pw layer, ipc, agc, routing; runs the main loop
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use headroom_ipc::{Event, Topic};
+use serde_json::json;
+
+use crate::agc::{AgcController, AGC_TICK};
+use crate::error::DaemonError;
+use crate::ipc::IpcServer;
+use crate::profile_store::ProfileStore;
+use crate::profile_watcher::ProfileWatcher;
+use crate::pw::filter::{Filter, FilterBundle, FilterInit};
+use crate::pw::{block_termination_signals, PwContext};
+use crate::state::{self, DaemonState, SharedState};
+
+/// blocks until shutdown (SIGTERM/SIGINT).
+pub fn run(profiles: ProfileStore) -> Result<(), DaemonError> {
+    // snapshot without draining: status/ipc keeps surfacing until next reload clears them
+    let pending_warnings = profiles.warnings();
+    let active_missing = profiles.is_active_missing().map(|s| s.to_owned());
+    tracing::info!(
+        profile = profiles.effective().name.as_str(),
+        rules = profiles.effective().rules.len(),
+        "starting headroom daemon"
+    );
+    for w in &pending_warnings {
+        tracing::warn!(warning = %w, "profile store warning");
+    }
+    if let Some(name) = active_missing.as_deref() {
+        tracing::warn!(missing = name, "selected profile missing; using built-in default");
+    }
+
+    // block SIGTERM/SIGINT process-wide BEFORE spawning any threads, so every thread inherits
+    // the blocked mask and pipewire's signalfd is the sole receiver. threads spawned before would
+    // keep default disposition and dying on SIGTERM would skip our shutdown path. (the ipc accept
+    // thread, added later in startup, tripped this once.)
+    block_termination_signals()?;
+
+    // captured before `profiles` moves into shared state
+    let watch_dir = profiles.primary_profile_watch_dir();
+
+    let daemon_state = state::shared(DaemonState::new(profiles));
+
+    // ipc first so its accept thread is ready before any pipewire work logs through it.
+    // handle's Drop cleans the socket.
+    let socket_path = headroom_ipc::default_socket_path()
+        .ok_or_else(|| DaemonError::other("no default IPC socket path"))?;
+    let _ipc = IpcServer::start(socket_path, daemon_state.clone())?;
+
+    // failure to install is non-fatal: manual `profile.reload` over ipc still works
+    let _profile_watcher = match watch_dir {
+        Some(dir) => match ProfileWatcher::start(dir, daemon_state.clone()) {
+            Ok(watcher) => watcher,
+            Err(e) => {
+                tracing::warn!(error = %e, "profile file-watcher disabled");
+                None
+            }
+        },
+        None => None,
+    };
+
+    let pw = PwContext::new()?;
+    // processed sink and bus filter must run at the real sink's rate to avoid a rate-conversion
+    // stage at the monitor → filter boundary. falls back to 48k if the real sink hasn't surfaced;
+    // the Format-param listener rebuilds on the first observed rate change.
+    let initial_rate = daemon_state
+        .lock()
+        .real_sink
+        .sample_rate
+        .unwrap_or(crate::pw::filter::DEFAULT_SAMPLE_RATE);
+    tracing::info!(initial_rate, "creating processed sink + filter at real-sink-matched rate");
+    pw.create_processed_sink(initial_rate)?;
+
+    // seed the dsp from the effective profile. FilterControl → DaemonState for live updates;
+    // measurement consumer → agc controller.
+    let filter_init = {
+        let s = daemon_state.lock();
+        let effective = s.profiles.effective();
+        FilterInit {
+            compressor: effective.build_compressor_config(),
+            limiter: effective.build_limiter_config(),
+            agc: headroom_dsp::AgcGainConfig::default(),
+            agc_enabled: effective.agc.enabled,
+        }
+    };
+
+    let FilterBundle {
+        filter,
+        control: filter_control,
+        measurement_consumer,
+        bus_metrics,
+        timing,
+        sample_rate: filter_rate,
+    } = Filter::create(pw.core(), filter_init, initial_rate)?;
+    {
+        let mut s = daemon_state.lock();
+        s.filter_control = Some(filter_control.clone());
+        s.filter_sample_rate = Some(filter_rate);
+    }
+
+    // reads [agc] config each tick so profile.use takes effect next tick
+    let agc_controller = AgcController::new(
+        filter_rate,
+        crate::pw::filter::CHANNELS,
+        measurement_consumer,
+        filter_control,
+        daemon_state.clone(),
+        bus_metrics,
+        timing,
+    )
+    .map_err(DaemonError::from)?;
+    let agc_controller = Rc::new(RefCell::new(agc_controller));
+    let agc_timer = {
+        let agc = agc_controller.clone();
+        let timer = pw
+            .main_loop()
+            .loop_()
+            .add_timer(move |_| agc.borrow_mut().tick());
+        let _ = timer.update_timer(Some(AGC_TICK), Some(AGC_TICK));
+        timer
+    };
+
+    // matching Stream/Output/Audio nodes get `target.object` via the `default` metadata;
+    // wireplumber moves them. bypassed streams point straight at preferred_real_sink the same way.
+    pw.start_routing(daemon_state.clone())?;
+
+    // hand the filter + agc handle to routing state so the Format-param listener can ask the
+    // registry thread to rebuild at a new rate via PwCommand::RebuildFilter. filter ownership
+    // moves here; RoutingState drops it on shutdown via PwContext's drop order.
+    if let Some(routing_state) = pw.routing_state() {
+        routing_state
+            .borrow_mut()
+            .install_filter_rebuild_handles(filter, agc_controller.clone());
+    } else {
+        // start_routing succeeded so this shouldn't fire; keep the filter alive defensively
+        tracing::warn!("routing_state unavailable post-start_routing; keeping filter local");
+    }
+
+    publish_daemon_started(&daemon_state, &pending_warnings, active_missing.as_deref());
+
+    pw.run_until_signal()?;
+
+    // drop before exiting so they tear down deterministically alongside the pipewire context
+    drop(agc_timer);
+    drop(agc_controller);
+
+    publish_daemon_shutdown(&daemon_state);
+
+    tracing::info!("headroom daemon stopped");
+    Ok(())
+}
+
+fn publish_daemon_started(state: &SharedState, warnings: &[String], active_missing: Option<&str>) {
+    if let Ok(event) = Event::new(
+        Topic::Daemon,
+        "started",
+        &json!({
+            "version": env!("CARGO_PKG_VERSION"),
+            "warnings": warnings,
+            "active_missing": active_missing,
+        }),
+    ) {
+        state.lock().broadcaster.publish(Topic::Daemon, event);
+    }
+}
+
+fn publish_daemon_shutdown(state: &SharedState) {
+    if let Ok(event) = Event::new(Topic::Daemon, "shutdown", &json!({})) {
+        state.lock().broadcaster.publish(Topic::Daemon, event);
+    }
+}

Added file: crates/headroom-core/src/state.rs+166 additions@@ -0,0 +1,166 @@
+//! cross-thread daemon state; non-Send pw state stays on the pw thread in `pw::registry`
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Instant;
+
+use crossbeam_channel::Sender;
+use parking_lot::Mutex;
+
+use headroom_ipc::{LayerASnapshot, Route, SinkInfo};
+
+use crate::ipc::broadcast::Broadcaster;
+use crate::profile_store::ProfileStore;
+use crate::pw::command::PwCommand;
+use crate::pw::filter::FilterControl;
+
+/// per-stream routing decision the daemon has applied (or attempted).
+#[derive(Debug, Clone)]
+pub struct RoutedStream {
+    pub node_id: u32,
+    /// `application.process.binary`, else `application.name`, else empty
+    pub app: String,
+    pub route: Route,
+}
+
+/// shared state behind a single mutex. lock held briefly; no nested locks, no awaits.
+#[derive(Debug)]
+pub struct DaemonState {
+    pub started_at: Instant,
+    pub profiles: ProfileStore,
+    /// global id of `headroom-processed`; `None` until the registry surfaces it
+    pub processed_sink_id: Option<u32>,
+    /// rate the filter runs at. matches the real sink's native rate at last (re)build; drives
+    /// status reporting + layer a's block-period. `None` only at very early boot.
+    pub filter_sample_rate: Option<u32>,
+    /// user's preferred hardware sink, kept fresh from `default.audio.sink`
+    pub real_sink: SinkInfo,
+    pub streams: HashMap<u32, RoutedStream>,
+    /// layer a controller state mirrored from the pipewire thread's `managed_streams` each drain
+    /// pass, so ipc threads can read it without reaching into the `Rc<RefCell>` pw-thread state.
+    /// keyed by source node id; removed on teardown.
+    pub layer_a: HashMap<u32, LayerASnapshot>,
+    pub broadcaster: Broadcaster,
+    /// `None` between startup and `Filter::create`, and in tests with no audio path. cloned under
+    /// the daemon lock then dropped before pushing, so the lock is never held during an
+    /// audio-thread hand-off.
+    pub filter_control: Option<FilterControl>,
+    /// commands that must run on the pipewire main-loop thread (e.g. `route.stream` metadata
+    /// writes). `None` until `start_routing`. cloned + dropped before send so the lock is never
+    /// held while crossbeam pushes.
+    pub pw_command_tx: Option<Sender<PwCommand>>,
+}
+
+impl DaemonState {
+    #[must_use]
+    pub fn new(profiles: ProfileStore) -> Self {
+        Self {
+            started_at: Instant::now(),
+            profiles,
+            processed_sink_id: None,
+            filter_sample_rate: None,
+            real_sink: SinkInfo::default(),
+            streams: HashMap::new(),
+            layer_a: HashMap::new(),
+            broadcaster: Broadcaster::new(),
+            filter_control: None,
+            pw_command_tx: None,
+        }
+    }
+
+    /// apply a `default.audio.sink` change to `real_sink`, returning bypass-routed streams that
+    /// need their `target.object` rewritten to follow the new sink. `None` on idempotent no-op.
+    /// touches only in-memory state, so it's safe under the lock (pw writes happen after unlock).
+    pub fn apply_real_sink_change(&mut self, new_name: &str) -> Option<Vec<(u32, String)>> {
+        if self.real_sink.name.as_deref() == Some(new_name) {
+            return None;
+        }
+        self.real_sink = SinkInfo {
+            // node_id + sample_rate stay unknown; `try_capture_real_sink` resolves both when it
+            // sees the matching `Audio/Sink` global. the routing path operates on name alone.
+            node_id: None,
+            name: Some(new_name.to_owned()),
+            ready: true,
+            sample_rate: None,
+        };
+        Some(
+            self.streams
+                .values()
+                .filter(|r| r.route == Route::Bypass)
+                .map(|r| (r.node_id, r.app.clone()))
+                .collect(),
+        )
+    }
+}
+
+pub type SharedState = Arc<Mutex<DaemonState>>;
+
+#[must_use]
+pub fn shared(state: DaemonState) -> SharedState {
+    Arc::new(Mutex::new(state))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::profile_store::ProfileStore;
+
+    fn state() -> DaemonState {
+        DaemonState::new(ProfileStore::builtin())
+    }
+
+    fn add_stream(s: &mut DaemonState, node_id: u32, app: &str, route: Route) {
+        s.streams.insert(
+            node_id,
+            RoutedStream {
+                node_id,
+                app: app.into(),
+                route,
+            },
+        );
+    }
+
+    #[test]
+    fn apply_real_sink_change_first_time_returns_empty_retarget_list() {
+        let mut s = state();
+        let to_retarget = s.apply_real_sink_change("alsa_output.usb-foo").unwrap();
+        assert!(to_retarget.is_empty(), "no streams yet — nothing to retarget");
+        assert_eq!(s.real_sink.name.as_deref(), Some("alsa_output.usb-foo"));
+        assert!(s.real_sink.ready);
+    }
+
+    #[test]
+    fn apply_real_sink_change_returns_bypass_streams_only() {
+        let mut s = state();
+        // Seed: two streams routed, one bypass, one processed.
+        add_stream(&mut s, 100, "mpv", Route::Bypass);
+        add_stream(&mut s, 101, "firefox", Route::Processed);
+        let mut retarget = s.apply_real_sink_change("alsa_output.usb-foo").unwrap();
+        retarget.sort_by_key(|(id, _)| *id);
+        assert_eq!(retarget.len(), 1);
+        assert_eq!(retarget[0].0, 100);
+        assert_eq!(retarget[0].1, "mpv");
+    }
+
+    #[test]
+    fn apply_real_sink_change_idempotent_on_same_name() {
+        let mut s = state();
+        add_stream(&mut s, 100, "mpv", Route::Bypass);
+        assert!(s.apply_real_sink_change("alsa_output.usb-foo").is_some());
+        assert!(s.apply_real_sink_change("alsa_output.usb-foo").is_none());
+    }
+
+    #[test]
+    fn apply_real_sink_change_returns_targets_on_subsequent_switches() {
+        let mut s = state();
+        add_stream(&mut s, 100, "mpv", Route::Bypass);
+        add_stream(&mut s, 101, "ardour", Route::Bypass);
+        s.apply_real_sink_change("speakers").unwrap();
+        let mut t = s.apply_real_sink_change("headphones").unwrap();
+        t.sort_by_key(|(id, _)| *id);
+        assert_eq!(t.len(), 2);
+        assert_eq!(t[0].0, 100);
+        assert_eq!(t[1].0, 101);
+        assert_eq!(s.real_sink.name.as_deref(), Some("headphones"));
+    }
+}

Added file: crates/pipewire-filter/Cargo.toml+19 additions@@ -0,0 +1,19 @@
+[package]
+name = "pipewire-filter"
+description = "automatic loudness and per-app volume control (pipewire)"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+# pipewire-rs 0.8 has no safe `pw_filter` wrapper + headroom-core
+# forbids unsafe; the unsafe FFI lives here.
+
+[dependencies]
+pipewire     = { workspace = true }
+pipewire-sys = { workspace = true }
+libspa       = { workspace = true }
+libspa-sys   = { workspace = true }
+thiserror    = { workspace = true }

Added file: crates/pipewire-filter/src/error.rs+18 additions@@ -0,0 +1,18 @@
+//! error type for the [`pipewire-filter`](crate) crate.
+
+#[derive(Debug, thiserror::Error)]
+pub enum FilterError {
+    /// `pw_filter_new` returned NULL — alloc failure or, since we own
+    /// every arg, an internal bug.
+    #[error("pw_filter_new returned NULL")]
+    CreationFailed,
+
+    /// `pw_filter_add_port` returned NULL — malformed props or format POD.
+    #[error("pw_filter_add_port returned NULL")]
+    AddPortFailed,
+
+    /// `pw_filter_connect` returned a negative error code.
+    #[error("pw_filter_connect failed: {0}")]
+    ConnectFailed(std::io::Error),
+
+}

Added file: crates/pipewire-filter/src/lib.rs+613 additions@@ -0,0 +1,613 @@
+//! minimal safe wrapper around `pw_filter` (pipewire-rs 0.8 has no
+//! `Filter`). mirrors `pipewire::stream`; lives in its own crate so
+//! the unsafe FFI stays out of `headroom-core`'s `forbid(unsafe_code)`.
+//! every `unsafe` block carries a `// SAFETY:` comment.
+//!
+//! drop order invariant: [`Filter`] must outlive its [`FilterListener`]
+//! — otherwise a trampoline could recover a freed `Box`. not encoded in
+//! the types (same as pipewire-rs `Stream`); callers drop the listener
+//! first.
+
+#![warn(missing_docs)]
+#![warn(clippy::missing_safety_doc)]
+
+pub mod error;
+
+use std::ffi::CString;
+use std::marker::PhantomData;
+use std::mem;
+use std::os::raw::c_void;
+use std::pin::Pin;
+use std::ptr::NonNull;
+
+use pipewire::{
+    core::Core,
+    properties::Properties,
+};
+
+pub use error::FilterError;
+pub use libspa::utils::Direction;
+
+/// state of a [`Filter`], from the C `pw_filter_state` enum.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FilterState {
+    /// `PW_FILTER_STATE_ERROR`. carries the optional error string.
+    Error(String),
+    /// `PW_FILTER_STATE_UNCONNECTED`.
+    Unconnected,
+    /// `PW_FILTER_STATE_CONNECTING`.
+    Connecting,
+    /// `PW_FILTER_STATE_PAUSED`.
+    Paused,
+    /// `PW_FILTER_STATE_STREAMING`.
+    Streaming,
+}
+
+impl FilterState {
+    /// decode the C enum + optional error string into [`FilterState`].
+    ///
+    /// # Safety
+    /// `error` must be NULL or a NUL-terminated C string valid until
+    /// return (PipeWire guarantees both for the callback's duration).
+    unsafe fn from_raw(state: pipewire_sys::pw_filter_state, error: *const std::os::raw::c_char) -> Self {
+        match state {
+            pipewire_sys::pw_filter_state_PW_FILTER_STATE_UNCONNECTED => Self::Unconnected,
+            pipewire_sys::pw_filter_state_PW_FILTER_STATE_CONNECTING => Self::Connecting,
+            pipewire_sys::pw_filter_state_PW_FILTER_STATE_PAUSED => Self::Paused,
+            pipewire_sys::pw_filter_state_PW_FILTER_STATE_STREAMING => Self::Streaming,
+            _ => {
+                let msg = if error.is_null() {
+                    String::new()
+                } else {
+                    // SAFETY: documented above; PipeWire guarantees a
+                    // valid NUL-terminated string for the call's
+                    // duration.
+                    std::ffi::CStr::from_ptr(error)
+                        .to_string_lossy()
+                        .into_owned()
+                };
+                Self::Error(msg)
+            }
+        }
+    }
+}
+
+/// flags accepted by [`Filter::connect`]. mirrors `enum pw_filter_flags`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct FilterFlags(pipewire_sys::pw_filter_flags);
+
+impl FilterFlags {
+    /// `PW_FILTER_FLAG_NONE`.
+    pub const NONE: Self = Self(pipewire_sys::pw_filter_flags_PW_FILTER_FLAG_NONE);
+    /// `PW_FILTER_FLAG_INACTIVE`.
+    pub const INACTIVE: Self = Self(pipewire_sys::pw_filter_flags_PW_FILTER_FLAG_INACTIVE);
+    /// `PW_FILTER_FLAG_DRIVER`.
+    pub const DRIVER: Self = Self(pipewire_sys::pw_filter_flags_PW_FILTER_FLAG_DRIVER);
+    /// `PW_FILTER_FLAG_RT_PROCESS` — process on the rt data thread.
+    pub const RT_PROCESS: Self = Self(pipewire_sys::pw_filter_flags_PW_FILTER_FLAG_RT_PROCESS);
+    /// `PW_FILTER_FLAG_CUSTOM_LATENCY`.
+    pub const CUSTOM_LATENCY: Self =
+        Self(pipewire_sys::pw_filter_flags_PW_FILTER_FLAG_CUSTOM_LATENCY);
+
+    /// OR two flag sets.
+    #[must_use]
+    pub const fn union(self, other: Self) -> Self {
+        Self(self.0 | other.0)
+    }
+
+    /// raw bits for `pw_filter_connect`.
+    #[must_use]
+    pub const fn bits(self) -> pipewire_sys::pw_filter_flags {
+        self.0
+    }
+}
+
+impl std::ops::BitOr for FilterFlags {
+    type Output = Self;
+    fn bitor(self, rhs: Self) -> Self {
+        self.union(rhs)
+    }
+}
+
+/// flags accepted by [`Filter::add_port`]. mirrors
+/// `enum pw_filter_port_flags`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct PortFlags(pipewire_sys::pw_filter_port_flags);
+
+impl PortFlags {
+    /// `PW_FILTER_PORT_FLAG_NONE`.
+    pub const NONE: Self = Self(pipewire_sys::pw_filter_port_flags_PW_FILTER_PORT_FLAG_NONE);
+    /// `PW_FILTER_PORT_FLAG_MAP_BUFFERS` — mmap so `data.data` is
+    /// directly readable/writable.
+    pub const MAP_BUFFERS: Self =
+        Self(pipewire_sys::pw_filter_port_flags_PW_FILTER_PORT_FLAG_MAP_BUFFERS);
+
+    /// OR two flag sets.
+    #[must_use]
+    pub const fn union(self, other: Self) -> Self {
+        Self(self.0 | other.0)
+    }
+
+    /// raw bits for `pw_filter_add_port`.
+    #[must_use]
+    pub const fn bits(self) -> pipewire_sys::pw_filter_port_flags {
+        self.0
+    }
+}
+
+impl std::ops::BitOr for PortFlags {
+    type Output = Self;
+    fn bitor(self, rhs: Self) -> Self {
+        self.union(rhs)
+    }
+}
+
+/// owns a `*mut pw_filter`. drop calls `pw_filter_destroy`.
+///
+/// not `Send`/`Sync`: `pw_filter` is bound to its owning main loop,
+/// like `pw_stream`.
+pub struct Filter {
+    ptr: NonNull<pipewire_sys::pw_filter>,
+    /// keeps the Core alive while this filter exists.
+    _core: Core,
+    /// `!Send`/`!Sync` even where `NonNull<_>` is `Send`.
+    _not_send: PhantomData<*mut ()>,
+}
+
+impl Filter {
+    /// create an unconnected filter. `properties` is consumed (PipeWire
+    /// takes ownership of the `pw_properties`).
+    ///
+    /// # Errors
+    /// [`FilterError::CreationFailed`] if `pw_filter_new` returns NULL.
+    pub fn new(core: &Core, name: &str, properties: Properties) -> Result<Self, FilterError> {
+        let c_name = CString::new(name).expect("filter name contains a NUL byte");
+        // SAFETY:
+        //  - `core.as_raw_ptr()` returns the live `*mut pw_core` that
+        //    `Core` keeps alive for the lifetime of the reference.
+        //  - `c_name.as_ptr()` is valid through this expression.
+        //  - `properties.into_raw()` consumes ownership; PipeWire
+        //    must free the `pw_properties` (it does: per filter.h
+        //    "ownership is taken"). We must NOT free it ourselves;
+        //    `into_raw` is exactly the API for that handoff.
+        let ptr = unsafe {
+            pipewire_sys::pw_filter_new(core.as_raw_ptr(), c_name.as_ptr(), properties.into_raw())
+        };
+        let ptr = NonNull::new(ptr).ok_or(FilterError::CreationFailed)?;
+        Ok(Self {
+            ptr,
+            _core: core.clone(),
+            _not_send: PhantomData,
+        })
+    }
+
+    fn as_raw_ptr(&self) -> *mut pipewire_sys::pw_filter {
+        self.ptr.as_ptr()
+    }
+
+    /// add a port. `params` are borrowed PODs (initial format hint);
+    /// `properties` is consumed (as [`Self::new`]). `port_data_size`
+    /// is 0 — the rt callback recovers state from the listener box.
+    ///
+    /// # Errors
+    /// [`FilterError::AddPortFailed`] if `pw_filter_add_port` returns
+    /// NULL.
+    pub fn add_port(
+        &self,
+        direction: Direction,
+        flags: PortFlags,
+        properties: Properties,
+        params: &mut [&libspa::pod::Pod],
+    ) -> Result<PortData, FilterError> {
+        // SAFETY:
+        //  - `self.as_raw_ptr()` is valid for the lifetime of `self`.
+        //  - `direction.as_raw()` is one of SPA_DIRECTION_INPUT /
+        //    SPA_DIRECTION_OUTPUT.
+        //  - `properties.into_raw()` hands ownership over; PipeWire
+        //    frees on filter destruction.
+        //  - `params` is `&mut [&Pod]`. `Pod` is `#[repr(transparent)]`
+        //    over `spa_pod`, so `&Pod` and `*const spa_pod` have the
+        //    same layout. The cast pattern is the one pipewire-rs
+        //    uses for `pw_stream_connect` (stream.rs:170).
+        //  - `params` is not stored; PipeWire copies whatever it needs
+        //    from the PODs before returning.
+        let port_data = unsafe {
+            pipewire_sys::pw_filter_add_port(
+                self.as_raw_ptr(),
+                direction.as_raw(),
+                flags.bits(),
+                0,
+                properties.into_raw(),
+                params.as_mut_ptr().cast(),
+                params.len() as u32,
+            )
+        };
+        let port_data = NonNull::new(port_data).ok_or(FilterError::AddPortFailed)?;
+        Ok(PortData { ptr: port_data })
+    }
+
+    /// connect the filter for processing. `params` are optional
+    /// filter-level format hints (headroom passes none; negotiation is
+    /// per-port).
+    ///
+    /// # Errors
+    /// [`FilterError::ConnectFailed`] if `pw_filter_connect` returns a
+    /// negative result code.
+    pub fn connect(
+        &self,
+        flags: FilterFlags,
+        params: &mut [&libspa::pod::Pod],
+    ) -> Result<(), FilterError> {
+        // SAFETY: same argument-validity rationale as `add_port`. The
+        // params slice can be empty — pipewire-rs's `Stream::connect`
+        // accepts the same.
+        let rc = unsafe {
+            pipewire_sys::pw_filter_connect(
+                self.as_raw_ptr(),
+                flags.bits(),
+                params.as_mut_ptr().cast(),
+                params.len() as u32,
+            )
+        };
+        if rc < 0 {
+            let errno = -rc;
+            return Err(FilterError::ConnectFailed(std::io::Error::from_raw_os_error(
+                errno,
+            )));
+        }
+        Ok(())
+    }
+
+    /// node id assigned by the server; non-zero once connected + acked.
+    #[must_use]
+    pub fn node_id(&self) -> u32 {
+        // SAFETY: `self.as_raw_ptr()` is valid for the lifetime of
+        // `self`. `pw_filter_get_node_id` is documented as a simple
+        // getter, no side effects.
+        unsafe { pipewire_sys::pw_filter_get_node_id(self.as_raw_ptr()) }
+    }
+
+    /// begin registering a listener. `user_data` is moved into the
+    /// listener box, reachable from every callback as `&mut D`.
+    /// finalise with [`ListenerBuilder::register`].
+    pub fn add_local_listener_with_user_data<D>(
+        &self,
+        user_data: D,
+    ) -> ListenerBuilder<'_, D> {
+        ListenerBuilder {
+            filter: self,
+            callbacks: ListenerCallbacks::with_user_data(user_data),
+        }
+    }
+}
+
+impl std::fmt::Debug for Filter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Filter")
+            .field("node_id", &self.node_id())
+            .finish()
+    }
+}
+
+impl Drop for Filter {
+    fn drop(&mut self) {
+        // SAFETY: `self.ptr` was returned by `pw_filter_new` and has
+        // not been freed since. `pw_filter_destroy` is the documented
+        // cleanup function. Note: callers are expected to drop any
+        // associated `FilterListener` first; otherwise the listener's
+        // `spa_hook::remove` runs against a freed list. We can't
+        // express that constraint in the borrow checker without
+        // making the listener literally borrow the filter, which
+        // pipewire-rs `Stream` also chooses not to do.
+        unsafe { pipewire_sys::pw_filter_destroy(self.as_raw_ptr()) }
+    }
+}
+
+/// opaque port handle from [`Filter::add_port`]; rt callbacks move
+/// audio via [`Self::dequeue_buffer`] + the [`Buffer`] RAII.
+///
+/// `Send` so the listener user-data struct can own port handles, but
+/// not `Sync`: `pw_filter_dequeue_buffer` writes a per-port lockless
+/// ring, so concurrent same-port calls aren't documented-safe. all
+/// real use is single-threaded in the rt callback.
+pub struct PortData {
+    ptr: NonNull<c_void>,
+}
+
+// SAFETY: the underlying `*mut c_void` points into the `pw_filter`
+// allocation, which lives until `pw_filter_destroy`. The Filter
+// owns the lifetime; the documented drop order (listener before
+// filter) ensures that PortData inside the listener's user-data
+// box never outlives the filter. Move-only ownership is the right
+// model — there must be exactly one logical owner of a port
+// handle, and the RT-callback closure is where that owner lives.
+unsafe impl Send for PortData {}
+
+impl PortData {
+    fn as_raw_ptr(&self) -> *mut c_void {
+        self.ptr.as_ptr()
+    }
+
+    /// dequeue the next buffer (fresh data on input ports, blank on
+    /// output ports). `None` if the queue is empty. the returned
+    /// [`Buffer`] queues itself back on drop.
+    pub fn dequeue_buffer(&self) -> Option<Buffer<'_>> {
+        // SAFETY: `as_raw_ptr` returns the live port handle; PipeWire
+        // returns either a valid `*mut pw_buffer` or NULL. The
+        // returned pointer is owned by PipeWire — we only borrow it
+        // for the realtime callback's duration. The `Buffer` RAII
+        // hands it back via `pw_filter_queue_buffer` on drop.
+        let raw = unsafe { pipewire_sys::pw_filter_dequeue_buffer(self.as_raw_ptr()) };
+        let raw = NonNull::new(raw)?;
+        Some(Buffer {
+            buf: raw,
+            port: self,
+        })
+    }
+}
+
+/// RAII handle for a dequeued buffer. drop calls `pw_filter_queue_buffer`.
+pub struct Buffer<'p> {
+    buf: NonNull<pipewire_sys::pw_buffer>,
+    port: &'p PortData,
+}
+
+impl Buffer<'_> {
+    /// borrow the buffer's `spa_data` slice (mirrors pipewire-rs
+    /// `Buffer::datas_mut`).
+    pub fn datas_mut(&mut self) -> &mut [libspa::buffer::Data] {
+        // SAFETY: `pw_buffer.buffer` points at a `spa_buffer` that
+        // PipeWire owns for the duration of this callback. The same
+        // invariant pipewire-rs relies on in `Buffer::datas_mut`. If
+        // `n_datas == 0` or `datas == NULL` we return an empty slice
+        // rather than dereferencing.
+        unsafe {
+            let pw_buf = self.buf.as_ptr();
+            let spa_buf = (*pw_buf).buffer;
+            if spa_buf.is_null() {
+                return &mut [];
+            }
+            let n_datas = (*spa_buf).n_datas;
+            let datas_ptr = (*spa_buf).datas;
+            if n_datas == 0 || datas_ptr.is_null() {
+                return &mut [];
+            }
+            // `libspa::buffer::Data` is `#[repr(transparent)]` over
+            // `spa_sys::spa_data`, so a `*mut spa_data` is layout-
+            // compatible with `*mut Data`.
+            let datas = datas_ptr.cast::<libspa::buffer::Data>();
+            std::slice::from_raw_parts_mut(datas, n_datas as usize)
+        }
+    }
+}
+
+impl Drop for Buffer<'_> {
+    fn drop(&mut self) {
+        // SAFETY: `self.buf` was obtained from
+        // `pw_filter_dequeue_buffer` on `self.port` and has not been
+        // queued elsewhere (this is the only path that consumes it).
+        // The `&PortData` borrow keeps the port alive at least until
+        // this call returns.
+        unsafe {
+            pipewire_sys::pw_filter_queue_buffer(self.port.as_raw_ptr(), self.buf.as_ptr());
+        }
+    }
+}
+
+// -- Listener machinery ------------------------------------------------------
+
+type ProcessCb<D> = dyn FnMut(&mut D, *mut libspa_sys::spa_io_position);
+type StateChangedCb<D> = dyn FnMut(&mut D, FilterState, FilterState);
+type ParamChangedCb<D> = dyn FnMut(&mut D, *mut c_void, u32, Option<&libspa::pod::Pod>);
+
+/// user data + per-event closures, behind a `Box` whose raw pointer is
+/// the trampoline's `data` argument.
+struct ListenerCallbacks<D> {
+    user_data: D,
+    process: Option<Box<ProcessCb<D>>>,
+    state_changed: Option<Box<StateChangedCb<D>>>,
+    param_changed: Option<Box<ParamChangedCb<D>>>,
+}
+
+impl<D> ListenerCallbacks<D> {
+    fn with_user_data(user_data: D) -> Self {
+        Self {
+            user_data,
+            process: None,
+            state_changed: None,
+            param_changed: None,
+        }
+    }
+
+    /// build the C `pw_filter_events` vtable + heap-boxed callbacks.
+    /// only wires events whose closure is set.
+    fn into_raw(self) -> (Pin<Box<pipewire_sys::pw_filter_events>>, Box<Self>) {
+        let callbacks = Box::new(self);
+
+        // SAFETY notes for the trampolines below:
+        //  - `data` is the `*mut c_void` we hand to
+        //    `pw_filter_add_listener`. It is the raw pointer to the
+        //    `Box<ListenerCallbacks<D>>`. The box is reclaimed by the
+        //    `FilterListener` on drop, so during the listener's
+        //    lifetime the pointer remains valid.
+        //  - We rebuild a `&mut ListenerCallbacks<D>` from `data`,
+        //    NOT a `Box<_>`. We must not double-free.
+        //  - PipeWire serialises callbacks for a single filter on a
+        //    single thread (data thread for RT events, main loop
+        //    otherwise) so the unique borrow is sound.
+
+        unsafe extern "C" fn on_process<D>(
+            data: *mut c_void,
+            position: *mut libspa_sys::spa_io_position,
+        ) {
+            // SAFETY: per the block comment above.
+            let state = unsafe { &mut *(data as *mut ListenerCallbacks<D>) };
+            if let Some(cb) = &mut state.process {
+                cb(&mut state.user_data, position);
+            }
+        }
+
+        unsafe extern "C" fn on_state_changed<D>(
+            data: *mut c_void,
+            old: pipewire_sys::pw_filter_state,
+            new: pipewire_sys::pw_filter_state,
+            error: *const std::os::raw::c_char,
+        ) {
+            // SAFETY: per the block comment above.
+            let state = unsafe { &mut *(data as *mut ListenerCallbacks<D>) };
+            if let Some(cb) = &mut state.state_changed {
+                // SAFETY for `new`: error is documented to either be
+                // NULL or a valid NUL-terminated C string owned by
+                // the filter.
+                let new = unsafe { FilterState::from_raw(new, error) };
+                // `error` only describes the *new* state; passing it
+                // to the `old` decode would misattribute the message
+                // if a future PipeWire enum value falls through to
+                // the `_` arm.
+                let old = unsafe { FilterState::from_raw(old, std::ptr::null()) };
+                cb(&mut state.user_data, old, new);
+            }
+        }
+
+        unsafe extern "C" fn on_param_changed<D>(
+            data: *mut c_void,
+            port_data: *mut c_void,
+            id: u32,
+            param: *const libspa_sys::spa_pod,
+        ) {
+            // SAFETY: per the block comment above.
+            let state = unsafe { &mut *(data as *mut ListenerCallbacks<D>) };
+            if let Some(cb) = &mut state.param_changed {
+                let param_ref = if param.is_null() {
+                    None
+                } else {
+                    // SAFETY: PipeWire owns the POD for the call's
+                    // duration. `Pod::from_raw` only borrows.
+                    Some(unsafe { libspa::pod::Pod::from_raw(param) })
+                };
+                cb(&mut state.user_data, port_data, id, param_ref);
+            }
+        }
+
+        // SAFETY: `mem::zeroed` produces an all-NULL `pw_filter_events`
+        // — every callback field is `Option<unsafe extern "C" fn ...>`
+        // which is layout-equivalent to a nullable function pointer.
+        // We then fill in the fields we want and leave the rest NULL,
+        // which is exactly what PipeWire expects (it skips NULL slots).
+        let events = unsafe {
+            let mut events: Pin<Box<pipewire_sys::pw_filter_events>> = Box::pin(mem::zeroed());
+            events.version = pipewire_sys::PW_VERSION_FILTER_EVENTS;
+            if callbacks.process.is_some() {
+                events.process = Some(on_process::<D>);
+            }
+            if callbacks.state_changed.is_some() {
+                events.state_changed = Some(on_state_changed::<D>);
+            }
+            if callbacks.param_changed.is_some() {
+                events.param_changed = Some(on_param_changed::<D>);
+            }
+            events
+        };
+
+        (events, callbacks)
+    }
+}
+
+/// builder from [`Filter::add_local_listener_with_user_data`]. install
+/// closures, then [`Self::register`].
+#[must_use = "Listener builders do nothing until .register() is called"]
+pub struct ListenerBuilder<'f, D> {
+    filter: &'f Filter,
+    callbacks: ListenerCallbacks<D>,
+}
+
+impl<D> ListenerBuilder<'_, D> {
+    /// set the rt process callback.
+    pub fn process<F>(mut self, callback: F) -> Self
+    where
+        F: FnMut(&mut D, *mut libspa_sys::spa_io_position) + 'static,
+    {
+        self.callbacks.process = Some(Box::new(callback));
+        self
+    }
+
+    /// set the state-changed callback.
+    pub fn state_changed<F>(mut self, callback: F) -> Self
+    where
+        F: FnMut(&mut D, FilterState, FilterState) + 'static,
+    {
+        self.callbacks.state_changed = Some(Box::new(callback));
+        self
+    }
+
+    /// set the param-changed callback. `port_data` is NULL for
+    /// filter-level changes, else the per-port handle; the `Pod` is
+    /// borrowed for the call.
+    pub fn param_changed<F>(mut self, callback: F) -> Self
+    where
+        F: FnMut(&mut D, *mut c_void, u32, Option<&libspa::pod::Pod>) + 'static,
+    {
+        self.callbacks.param_changed = Some(Box::new(callback));
+        self
+    }
+
+    /// register the listener; drop the returned [`FilterListener`] to
+    /// unregister.
+    ///
+    /// # Errors
+    /// never (`pw_filter_add_listener` is `void`); `Result` kept for
+    /// parity with pipewire-rs `Stream::register`.
+    pub fn register(self) -> Result<FilterListener<D>, FilterError> {
+        let (events, data) = self.callbacks.into_raw();
+        // SAFETY:
+        //  - `Box::into_raw` consumes the box, leaving the heap
+        //    allocation alive. We reclaim it inside the
+        //    `FilterListener` on drop.
+        //  - The events table is `Box::pin`ned; the raw `&` returned
+        //    by `events.as_ref().get_ref()` is stable for as long as
+        //    the listener holds the pinned box (the listener owns it).
+        //  - The spa_hook is zero-initialised and handed to PipeWire
+        //    to populate.
+        let (listener, data) = unsafe {
+            let listener: Box<libspa_sys::spa_hook> = Box::new(mem::zeroed());
+            let raw_listener = Box::into_raw(listener);
+            let raw_data = Box::into_raw(data);
+            pipewire_sys::pw_filter_add_listener(
+                self.filter.as_raw_ptr(),
+                raw_listener,
+                events.as_ref().get_ref(),
+                raw_data.cast(),
+            );
+            (Box::from_raw(raw_listener), Box::from_raw(raw_data))
+        };
+        Ok(FilterListener {
+            listener,
+            _events: events,
+            _data: data,
+        })
+    }
+}
+
+/// owns the spa_hook + heap-boxed callbacks; drop unhooks the listener.
+/// must outlive any callback — drop this *before* the [`Filter`], else
+/// `pw_filter_destroy` could fire a trampoline against a freed hook.
+pub struct FilterListener<D> {
+    listener: Box<libspa_sys::spa_hook>,
+    /// pinned: PipeWire keeps a pointer into this allocation.
+    _events: Pin<Box<pipewire_sys::pw_filter_events>>,
+    /// the trampoline's `data` box; kept alive for the listener's life.
+    _data: Box<ListenerCallbacks<D>>,
+}
+
+impl<D> Drop for FilterListener<D> {
+    fn drop(&mut self) {
+        // SAFETY: `self.listener` is the spa_hook PipeWire wrote into
+        // during `pw_filter_add_listener`. `hook::remove` consumes the
+        // hook by value; we hand it a copy from the box, then the box
+        // itself is freed by the auto-generated Drop. The original
+        // hook in `self.listener` is now invalid but no further code
+        // reads it.
+        let hook = *self.listener;
+        libspa::utils::hook::remove(hook);
+    }
+}

show truncated diff

headroom

Commit 65250d1c123c

Commit `65250d1c123c`