feat(audio): low-latency engine: device-paced rendering, adaptive queues, whole-pipeline tests

.github/pull_request_template.md

@@ -4,8 +4,8 @@
   - Read docs/CONTRIBUTING.md and docs/RULES.md.
   - Keep the diff to the change. No drive-by renames, reformatting, or
     refactors of code the change does not touch.
-  - Run `bun run check`, `cargo check --manifest-path src-tauri/Cargo.toml`,
-    and `bun run format` — all must pass and leave the tree clean.
+  - Run `bun run test`, `bun run check`, and `bun run format` —
+    all must pass and leave the tree clean.
   - If you changed a `#[derive(TS)]` type in Rust, run `bun run generate` and
     commit the regenerated files in src/lib/modules/pipeline/generated/.
 -->
@@ -21,8 +21,8 @@ _Explain the design choice. What alternatives were considered and rejected? If t
 ## Checklist
 
 - [ ] Diff is limited to the change — no unrelated edits
+- [ ] `bun run test` passes
 - [ ] `bun run check` passes
-- [ ] `cargo check --manifest-path src-tauri/Cargo.toml` passes
 - [ ] `bun run format` leaves the tree clean
 - [ ] Generated TS types are committed with the Rust change (if any)
 - [ ] No new dependency without a reason in the PR description

.github/workflows/ci.yml

@@ -55,6 +55,9 @@ jobs:
       - name: Install JS deps
         run: bun install --frozen-lockfile
 
+      - name: Frontend tests
+        run: bun run test:frontend
+
       # Each OS backend needs its native headers to compile. Linux installs
       # PipeWire and the GTK stack explicitly; macOS and Windows runners ship
       # their SDKs (CoreAudio / WASAPI + MSVC) preinstalled.
@@ -93,12 +96,24 @@ jobs:
           fi
           if [ "$RUNNER_OS" = "Windows" ]; then
             cargo test --no-run
-          elif [ "$RUNNER_OS" = "Linux" ]; then
-            cargo test -- --skip audio::playback::tests::playback_pulls_samples
+          elif [ "$RUNNER_OS" = "macOS" ]; then
+            # The real-time scenarios run in their own advisory step below.
+            cargo test --lib --bins --test updater
+            cargo test --doc
           else
             cargo test
           fi
 
+      # The macOS runner is a virtual machine that pauses threads for
+      # milliseconds at a time, longer than a small engine buffer lasts, so the
+      # real-time scenarios report there without failing the build. Linux runs
+      # them as a gate.
+      - name: Real-time scenarios (advisory on macOS)
+        if: runner.os == 'macOS'
+        continue-on-error: true
+        working-directory: src-tauri
+        run: cargo test --test pipelines --test transitions
+
       - name: TS-RS bindings up to date
         run: git diff --exit-code -- src/lib/modules/pipeline/generated
 

AGENTS.md

@@ -33,7 +33,7 @@ Without these, one chunk takes ~16 ms and the worker stalls.
 ## When in doubt
 
 - Read the current code, not earlier explanations.
-- RT path change → `cargo check`.
+- RT path change → `bun run check`.
 - Svelte change → `bun run check`.
 - New node or shared UI component → reuse existing Storybook components first, add its stories under `src/stories/` in the same commit (see [docs/UI.md](docs/UI.md)).
 - Rust `#[derive(TS)]` change → `bun run generate`, commit the generated files with the Rust change.

CONTRIBUTING.md

@@ -57,12 +57,12 @@ If a platform genuinely cannot support what you are adding, return a real error
 ## Before you open the PR
 
 ```bash
-bun run check                                  # svelte-check + tsc
-cargo check --manifest-path src-tauri/Cargo.toml
+bun run test                                   # frontend + Rust tests in parallel
+bun run check                                  # frontend + Rust checks in parallel
 bun run format                                 # Prettier + rustfmt
 ```
 
-Both checks must pass, and `format` must leave the tree clean. A new node or shared component ships with its Storybook stories in the same PR; see [docs/UI.md](docs/UI.md). If you changed a `#[derive(TS)]` type in Rust, run `bun run generate` and commit the regenerated files in `src/lib/modules/pipeline/generated/` together with the Rust change — never by hand, and never on their own.
+All checks must pass, and `format` must leave the tree clean. A new node or shared component ships with its Storybook stories in the same PR; see [docs/UI.md](docs/UI.md). If you changed a `#[derive(TS)]` type in Rust, run `bun run generate` and commit the regenerated files in `src/lib/modules/pipeline/generated/` together with the Rust change — never by hand, and never on their own.
 
 Anything persisted to disk — pipeline JSON, `virtual-devices.json`, the macOS driver plist — has to keep loading for people upgrading. Add a `#[serde(default)]` or a versioned migration; do not silently change the meaning of an existing field.
 

docs/CONCEPT.md

@@ -21,6 +21,8 @@ Inside cpal / SCK callbacks and `DspWorker::run`:
 - Syscalls (I/O, logging, IPC)
 - Non-deterministic latency ops
 
+One exception: waking a sleeping helper thread with `Thread::unpark` (an offload worker after its input was pushed, a network send thread after a block went into its rings; `audio/wake.rs`). It never blocks; when the thread is awake it is a single atomic swap, and otherwise one futex, `dispatch_semaphore_signal` or `WakeByAddressSingle` wake. Polling with `sleep` instead costs the worker up to a poll period of its deadline.
+
 Shared RT↔UI state: `Arc<AtomicU32>` (f32-as-bits, `Ordering::Relaxed`). See `MeterHandle` / `EffectControl` in `audio/effects.rs`.
 
 Ring buffers: `rtrb` SPSC. Use `bulk_pop` / `bulk_push`, never per-sample loops.
@@ -40,8 +42,13 @@ Without these, one chunk takes ~16 ms and the worker stalls.
 
 ## DspWorker pacing
 
-- `Clock` — the single transport cadence for every worker (speaker, monitoring, wire sender, recording). Sleeps to a per-block deadline; a missed deadline produces silence, never a rate error. Recording must follow the wall clock, not the source — a file source decodes faster than real time and would otherwise over-run the encoder.
-- Stall: per-source `last_pop_at`; >150 ms silence → zero-fill and proceed.
+- Speakers render inside the device callback (`pipeline/output/render.rs`): the device is the clock, one engine block per callback, no output ring. The engine block is the user's buffer setting (32-2048 frames); the device IO buffer is requested at the same size. The graph reaches the callback through an SPSC handoff and is handed back on teardown, so it never drops on the audio thread.
+- `Clock` paces the timer workers: monitoring and recording at `TIMER_BLOCK_FRAMES`, a wire sender at the engine block, since its latency is heard at the far end. Sleeps to a per-block deadline; a missed deadline produces silence, never a rate error. Recording must follow the wall clock, not the source: a file source decodes faster than real time and would otherwise over-run the encoder.
+- Live sources hold their queue at a measured headroom (`pipeline/cushion.rs`), sized by `audio/adaptive_depth.rs`, which also sizes the network jitter buffer. A source on another clock reads through an asynchronous resampler (`pipeline/asrc.rs`) whose ratio a slow PI loop steers (`audio/drift_loop.rs`, zita-a2j style, 0.05 Hz, at most 1000 ppm), fed the queue plus what the producer has made but not yet written (`input_bridge::WriteClock`, lowpassed by `ArrivalClock`): drift is absorbed by the ratio, never by splices. The network receiver (`stream_recv.rs`) runs the same loop against its packets' write timing, holding the fill right after a packet at its start level. A source on the speaker's own clock (a process tap on the default output, a mic on the same device or clock domain) reads straight. Either way the queue is spliced only once, when the start depth guessed before measuring is corrected (the loop holds still meanwhile), and after running dry it is realigned only under the silence already played, with fades at every stop and start. Running dry deepens a queue only by audio that later arrives late (`OutageJudge`), and only when that happens again within a minute; a source that goes quiet (paused app, DTX sender) never does. Capture buffers (mic, tap aggregate) are requested at the engine block.
+- An edit rebuilds only what it changed. A node whose build inputs are unchanged (same id, structural spec, width, rate, block) is built as an empty placeholder, and when the new graph swaps in on the running worker it takes over the old node's live state (`OutputGraph::adopt_from`): a source its ring, queue and resamplers, with the bridge feeding that ring kept; an effect its instances, controls and handles; an edge its delay line when the delay is unchanged. Only a graph that is not swapped in place is built from scratch.
+- Nothing steps the output: a speaker fades in over 10 ms when it starts and out over 10 ms before it retires. A swap whose heard part is unchanged (every node reaching the output carried over, fed by the same edges at the same delays; `OutputGraph::plays_like`) goes in at once; any other fades the running graph out over 10 ms, swaps, carrying over what it can, and fades the new one in (`worker.rs`).
+- An effect that cannot answer within the engine block (offloaded plugins, the noise suppressor) runs on an offload thread (`effects/offload.rs`). One that can only step in whole blocks of its own (a model hop) names that block, and the offload gathers exactly those before calling it; the effect never pads or buffers for it itself. The offload's pad is the least that never starves at the worst alignment of those blocks against the engine's, plus a 5 ms turnaround. The effect declares only its own latency (a model's algorithmic delay, a resampler's queues), the offload adds its pad, PDC aligns against the sum, and the node shows it.
+- Stall: per-source `last_pop_at`; >150 ms silence: zero-fill and proceed.
 - RT promotion happens after speaker startup prefill. Every overdue Linux tick performs a real blocking sleep before more DSP work; an unbounded catch-up loop is forbidden even when the ring can absorb it.
 
 ## Effects
@@ -89,6 +96,7 @@ A backend that cannot support the feature returns an error; it does not substitu
 - PipeWire process callbacks and promoted DSP workers are RT code. They may touch only preallocated buffers, SPSC rings and relaxed atomics.
 - `audio_thread_priority` obtains real-time scheduling through RTKit. Its frame argument is the maximum uninterrupted render quantum, not a latency target. Pass the actual known block size; pass `0` when PipeWire owns an unknown callback quantum.
 - Linux `RLIMIT_RTTIME` measures CPU time spent under real-time scheduling without a blocking syscall. Crossing the soft limit sends `SIGXCPU`; crossing the hard limit sends `SIGKILL`. Preemption and `sched_yield` do not reset it. Startup prefill runs before promotion, and deadline catch-up must block between blocks. Never raise or disable the OS limit to hide an overload.
+- An offload worker runs promoted but parks only when its input is empty; one whose effect cannot keep up would never park, so after 20 ms of uninterrupted work it sleeps 1 ms (`effects/offload.rs`).
 - A `SIGXCPU` followed by `SIGKILL` from the audio thread with `si_code=SI_KERNEL` is an RT-budget failure. A Rust panic hook and in-process crash modal cannot observe `SIGKILL`; preserve the previous-run unexpected-exit report.
 
 ### macOS: CoreAudio

docs/DEVELOPMENT.md

@@ -38,10 +38,10 @@ bun run tauri dev
 ## Useful commands
 
 ```bash
-bun run check                          # svelte-check + tsc
+bun run test                           # frontend + Rust tests in parallel
+bun run check                          # frontend + Rust checks in parallel
 bun run generate                       # regenerate TypeScript types from Rust (ts-rs)
 bun run storybook                      # Storybook on :6006, nodes and shared components with mocked engine
-cargo check --manifest-path src-tauri/Cargo.toml
 bun run tauri build --bundles app      # local .app build (macOS)
 bun run tauri build --bundles appimage # local AppImage build (Linux)
 bun run tauri build --bundles nsis     # local installer build (Windows)

docs/RULES.md

@@ -45,7 +45,7 @@ type(scope): subject
 ## When in doubt
 
 - Read the current code, not earlier explanations.
-- RT path change → `cargo check`.
+- RT path change → `bun run check`.
 - Svelte change → `bun run check`.
 - New node or shared component → add its stories in the same commit, see [UI.md](UI.md).
 - Rust `#[derive(TS)]` change → `bun run generate`, commit the generated files with the Rust change.

package.json

@@ -7,7 +7,10 @@
 		"dev": "vite dev",
 		"build": "vite build",
 		"preview": "vite preview",
-		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"test": "bun scripts/test-all.ts",
+		"test:frontend": "bun test tests",
+		"check": "bun scripts/check-all.ts",
+		"check:frontend": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"tauri": "tauri",
 		"format": "prettier --write \"**/*.{ts,tsx,md,svelte,json}\" && cargo fmt --manifest-path src-tauri/Cargo.toml",

scripts/check-all.ts

@@ -0,0 +1,29 @@
+const tasks = [
+	{
+		name: 'frontend',
+		command: ['bun', 'run', 'check:frontend']
+	},
+	{
+		name: 'backend',
+		command: ['cargo', 'check', '--manifest-path', 'src-tauri/Cargo.toml']
+	}
+] as const;
+
+const children = tasks.map((task) => ({
+	...task,
+	process: Bun.spawn(task.command, {
+		stdin: 'inherit',
+		stdout: 'inherit',
+		stderr: 'inherit'
+	})
+}));
+
+const results = await Promise.all(children.map(async ({ name, process }) => ({ name, exitCode: await process.exited })));
+const failed = results.filter(({ exitCode }) => exitCode !== 0);
+
+if (failed.length > 0) {
+	for (const { name, exitCode } of failed) {
+		console.error(`${name} check failed with exit code ${exitCode}`);
+	}
+	process.exit(1);
+}

scripts/test-all.ts

@@ -0,0 +1,29 @@
+const tasks = [
+	{
+		name: 'frontend',
+		command: ['bun', 'run', 'test:frontend']
+	},
+	{
+		name: 'backend',
+		command: ['cargo', 'test', '--manifest-path', 'src-tauri/Cargo.toml']
+	}
+] as const;
+
+const children = tasks.map((task) => ({
+	...task,
+	process: Bun.spawn(task.command, {
+		stdin: 'inherit',
+		stdout: 'inherit',
+		stderr: 'inherit'
+	})
+}));
+
+const results = await Promise.all(children.map(async ({ name, process }) => ({ name, exitCode: await process.exited })));
+const failed = results.filter(({ exitCode }) => exitCode !== 0);
+
+if (failed.length > 0) {
+	for (const { name, exitCode } of failed) {
+		console.error(`${name} tests failed with exit code ${exitCode}`);
+	}
+	process.exit(1);
+}