docs(plan): ship dlopen-audio-backend-and-audio-blocks — fold into §Media I/O and archive

[tato123]

Ships dlopen-audio-backend-and-audio-blocks — rung one of the [audio-subsystem]
ladder. Audio exists: a microphone reaches a processor as timestamped samples over a
backend the wheel never links, and a processor's samples reach a speaker.

Plan changes merge only with the owner's review.

Precondition — every ticket merged

Ticket	What	PR	Merged
#1988	AudioBlock — samples ride the bag as msgpack bin	#1995	2026-08-27
#1989	the device seam and the null backend	#1997	2026-08-27
#1998	headless known-signal loopback fixture	#2001	2026-08-27
#2002	verify audio per processor by tapping its channel	#2003	2026-08-27
#2004	an unconnected audio output logged ~94 errors a second	#2005	2026-08-27
#1990	the PipeWire arm — dlopen'd libpipewire, vendored SPA shim	#2008	2026-08-28
#1991	the ALSA arm — dlopen'd libasound, chain demotes in order	#2010	2026-08-28
#1992	SpeakerSink — playback on every arm	#2013	2026-08-28
#1993	the rung's removals — the FIXME closes, dead sync machinery goes	#2016	2026-08-28
#1999	/verify-audio as a callable skill	#2017	2026-08-28
#2012	a stream that dies tells its owner, not just the log	#2018	2026-08-28

#2018 merged 2026-08-28T22:10:12Z — the archive date, not today's guess.

#2015 is the one ticket that did not ship. It was closed NOT_PLANNED, not
implemented: the drop counter it would fix turns on whether lossless and
every_sample are distinct concepts, and that vocabulary needs an /align before the
windower rung. Recorded here as a fact; no plan entry claims the fix.

Gate — clean at the archived path

$ bash .claude/scripts/ship-change-removed-gate.sh \
    docs/plan/changes/archive/2026-08-28-dlopen-audio-backend-and-audio-blocks.md
clean: 7 REMOVED bullets, none referenced and none on disk.
EXIT=0

All 11 source-walking gates pass, including check-no-in-process-placement (7408 files,
19 exempt prohibition lines matched) — this change file pinned no gate key, so archiving
it moved nothing the placement gate depends on.

The fold — eleven DECIDED entries into §Media I/O

Six new entries. The device seam as one engine primitive (AudioDeviceBackend
opening capture and playback streams beside the audio clock, no second audio device
path); every audio symbol binding at runtime through libloading against the versioned
soname; SPA's header-only layer as a cc-compiled shim that references no external
symbol; the headers vendored rather than taken from the build machine; the portability
gate unchanged and unweakened. Then the AudioBlock half — the wire contract and its
six keys, samples as msgpack bin rather than a typed vector, the pure-Python cast
that composes nothing surface-shaped, "zero-copy" stated as a claim about the cast
alone, and the harness bin-decode defect fixed at the engine layer.

Five existing [audio-subsystem] entries sharpened in place, each gaining its
SHIPPED citation: the backend chain gains an arm is chosen by opening, not by
loading and the named-device_id raise at setup(); the pacing entry gains the clock
starting only when something needs it, which is what makes "exactly one cadence source"
true in the tree rather than merely stated; A/V sync, the data model, and the two
built-ins gain theirs. The built-ins entry cites partially — #1989, #1992 for the
built-ins, their execution mode and the drop-at-the-edge clause, with conditioning and
immediate cancel named as a later rung.

The section stays IN-FLIGHT. Its audio-plugins entry is still OPEN, and the
convention here is that a section ships only when it holds no OPEN. Only the
(→ dlopen-audio-backend-and-audio-blocks) pointer goes.

#2012 folds rather than adding an entry. It was filed during implementation, not
part of the approved delta, so its contract lands as a clause on the device-seam entry
instead of becoming architecture this session made.

Every verify marker was run before it was written

The wheel's .so predated HEAD, so maturin develop ran first — otherwise the PASS
would describe the old code.

• 20 Rust tests across streamlib-engine --lib, streamlib-media-builtins --lib,
  and the audio_clock_paces_only_what_needs_it / silent_null_arm_* integration
  binaries.
• 13 hardware-tier tests that skip on a bare machine actually ran here — this rig
  has /dev/snd and a live PipeWire session, so pipewire_arm_* and alsa_arm_* were
  executed under --features streamlib/hardware-tests, not merely listed. The device
  stamping the block is proven against a real daemon and a real driver.
• 29 wheel tests: test_audio_block_cast.py, test_microphone_source.py,
  test_speaker_sink.py (22), plus test_wheel_portability.py and
  test_third_party_notices.py (7).

The design's own pass/fail, run directly rather than asserted:

$ readelf -d python/streamlib/_engine.abi3.so | grep NEEDED
 [libstdc++.so.6]  [libc.so.6]  [ld-linux-x86-64.so.2]  [libgcc_s.so.1]  [libm.so.6]

Five libraries after audio, the same five as before. No audio library entered
DT_NEEDED.

Diagram

system.mmd gains the vendored-shim and DT_NEEDED clause on the media node, and the
previously unlabelled media → engine edge now carries the seam, the liveness report,
and the device-stamps-the-block rule.

Note, not a ticket

packages/audio, packages/opus and packages/clap remain read-only reference for
rungs two and three (the rubato wiring, the rechunker, the Opus framing). They are
deleted as REMOVED: facts when the last of that logic is re-homed, not before.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 20 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e9106418-3d00-4892-bbca-9d8fe26eb380

📥 Commits

Reviewing files that changed from the base of the PR and between 357963d and 44c3d03.

📒 Files selected for processing (3)

• docs/plan/ARCHITECTURE.md
• docs/plan/changes/archive/2026-08-28-dlopen-audio-backend-and-audio-blocks.md
• docs/plan/diagrams/system.mmd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}