# Desktop audio callback qualification The desktop callback moves discarded Sample references and command-vector owners into two preallocated return packets. Host service reclaims them outside the data callback. Logical playback completion does not imply immediate physical release. The [audio peripheral contract](../specs/runtime/05-audio-peripheral.md) is normative. ## Capacity and ownership proof One publication can contain 1,024 frame commands and a combined 2,048-command lifecycle batch. Each command introduces at most one Sample reference, and the mixer starts with at most sixteen. Therefore at most 3,088 Sample owners can retire in one callback, even if every command replaces a voice and every resulting voice finishes immediately. Each packet reserves that reference capacity plus two vector slots before starting the stream. Stale command references remain in the returned vectors instead of moving into the retired-reference vector. Exactly two packets circulate through capacity-two SPSC lanes. While the callback owns a packet, no more than one other packet can occupy the return lane. Enqueue therefore needs no waiting, resizing or overflow disposal. Symmetrically, service can always return a reclaimed packet to the free lane. If both packets await service, the callback leaves publications untouched. Up to sixteen naturally completed voices retain owners in their existing slots, becoming silent until reclamation capacity returns. PCM content can be large; this is a bound on references and fixed metadata, not an additional PCM byte quota. Service clears retired references, clears commands and caches at most four empty command vectors for producer reuse. It runs before guest attempts and during pause or backpressure. Stream stop/drop precedes silent-consumer takeover. No additional reclamation worker or playback mirror is introduced. ## Allocation and semantic evidence `tests/audio_callback_allocations.rs` installs a thread-local allocator counter. Only runtime callback execution is counted; fixture construction, I/O, reporting, service reclamation and teardown run outside that region. It counts alloc, alloc_zeroed, realloc and dealloc (realloc contributes to both counters). The original last-owner natural completion made zero allocations and two deallocations; applying a control batch freed one vector. After the change, debug and release counters report zero allocations/deallocations for natural completion, all controls, repeated play/stop/replacement, pause, epoch reset, empty samples, bank unload, 16-voice completion without a packet, ten starved callbacks and recovery. The saturation case combines 3,072 Play commands with sixteen existing voices and completion, exercising the full 3,088-owner bound. Weak-reference assertions prove retention until service and final release. Unit tests additionally check stale-vector identity and deferred release, 1,000 pool recycling cycles, vector-allocation reuse, bounded empty-buffer caching, failed/stalled stream takeover and teardown. Existing exact PCM tests retain one-shot tails, loop seams, fractional interpolation, FIFO/prefix order and pause position. Runtime audio controls and headless tests retain their logical admission behavior; the Rust silent-consumer interface remains unchanged. Reproduce allocation qualification with: ```sh cargo test -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture ``` ## Timing observations Executed on 2026-10-14, macOS/aarch64, rustc 1.98.1, release profile. Both workloads used sixteen voices and 256 stereo frames at 48 kHz (nominal period 5.333 ms). The explicitly named pressure workload reads the checked-in stress-console asset pack and writes a temporary 1 MiB file through HostDirBackend. It does not execute guest asset decoding or the memcard save scheduler; it is not a substitute for a separate full integration workload. | Workload | Callbacks | I/O cycles | p50 | p95 | p99 | Maximum | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | Synthetic callback invocation, interleaved I/O | 1,000 | 1,000 | 13.791 µs | 30.458 µs | 54.292 µs | 72.166 µs | | MacBook Pro Speakers, concurrent main-thread I/O | 375 | 273 | 11.458 µs | 12.875 µs | 15.916 µs | 30.458 µs | Both observed zero runtime allocator calls and sixteen live Sample owners before teardown, zero afterward. Physical buffers were observed at exactly 256 frames. Timing includes the runtime render call and counter overhead, excludes I/O and CPAL/device internals, and does not measure device presentation latency. No timing threshold is asserted. These are local observations, not cross-device certification. Explicit commands (both timing tests are ignored by ordinary CI): ```sh cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations physical_callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture cargo test -p prometeu-host-desktop-winit --lib audio::control_tests::desktop_audio_device_smoke -- --ignored --exact --nocapture ``` The ordinary physical smoke passed on retry. The first sandboxed attempt could not open the device; the first unrestricted attempt received no callbacks and triggered the existing two-second watchdog. Those failures remain part of the qualification evidence and demonstrate why successful local timing is not an availability guarantee. No human listening assessment is claimed. Strict host Clippy passes. Repository-wide strict-gate status remains separate from these behavioral and device observations.