feat(audio): the audio module — credit-based PCM spec, web/sim hosts, a music demo that really plays

[doodlewind]

What

Audio lands as PocketJS's third module (after the ui surface and OpenStrike's strike), and the first one built module-first: spec before any host code, every host implementing the same pinned boundary. The concrete payoff: apps/music now actually plays WAV music in the web dev host — while every one of its 17 committed pixel goldens (web + psp×3 + vita) stays byte-identical, un-rebaked.

The module (docs/AUDIO.md is the map)

platform audio device (AudioWorklet · sceAudio · …)      Host / substrate
audio core: per-stream PCM ring + credit accounting
audio spec: ops · events · data contract · frame contract (contracts/spec/audio.ts)
SDK: @pocketjs/framework/audio (decodeWav, createWavPlayer)
apps/music                                               Guest

• Own namespace, own op space. Mounted as globalThis.audio; AUDIO_OP codes append-only; capability id audio.pcm = spec namespace = pak prefix (audio:wav.*). gen-rust emits pub mod audio into engine/core/src/spec.rs, drift-guarded by tests/contract.ts as always.
• Credit-based flow control. Core grants ring space as credit events (drained via poll(), one JSON line per call — the svcPoll convention); guest writes s16 PCM as borrowed-for-the-call buffers against a guest-side free-frame mirror. Hot path: one poll drain + at most one writePcm per tick, never a query.
• Multi-clock, honestly. The frame contract declares a native-side audio clock (worklet/thread) that never calls the guest and batches its facts to tick boundaries — law 3 holds unchanged. Virtual-clock hosts consume exactly floor((n+1)·rate/60) − floor(n·rate/60) frames per playing tick, so consumed PCM is a pure function of (tick, ops): the audio equivalent of byte-exact goldens.
• Rates pinned to 44100/22050/11025 — integer divisors of the PSP's native output, the hardware lesson from hosts/psp/src/audio.rs promoted to the portable contract.

Hosts

host	embodiment	status
web	hosts/web/audio.js + audio-worklet.js (device-clock ring, gesture-deferred AudioContext)	audible
sim	hosts/sim/audio.ts (formula consumption, PCM FNV-1a + op/event log)	deterministic tests
psp / vita / others	not mounted; contract constants shipped, ring/thread discipline already exists in their video-plane audio	documented seam, capability not advertised

Consoles adopt by implementing the namespace in their FFI table and appending audio.pcm to their target profile — no spec/framework/app change. That's the no-heavy-fork property this PR exists to establish.

The demo

All three framework variants of apps/music wire the same createWavPlayer: load on select/skip, play/pause slaved to UI state, one pump() per frame. Three original 5-second tracks are deterministically synthesized (apps/music/gen-assets.ts, SHA-pinned in tests) and spliced via the pak.json raw-blob route. The tick clock stays authoritative — the player follows the frame counters, never drives them — which is the invariant tests/audio-sim.test.ts pins by running the same journey with the module mounted and absent and asserting identical pixel hashes.

Verification

• bun run test (full chain, includes new tests/audio.test.ts + tests/audio-sim.test.ts) — green
• bun tests/golden.ts — 54/54, music frames untouched
• bun run gen + bun run contract — drift guard green; cargo check -p pocketjs-core green
• bun run tape:check — hero tape holds
• Live headless-Chrome probe of the web host: namespace mounted, worklet consuming (credit free-values oscillating at steady state), zero console errors, demo at 60 FPS

Deliberately deferred (with triggers)

Host-level mixing across runtimes, codec registration, raw-PCM pak entries, native console mounts — all per the delayed-items table in the module discipline.

🤖 Generated with Claude Code