suaveplan/openspec/archive/2026-05-23-refresh-audio-queue-2026-05-23/proposal.md

Refresh audio queue for 3-level layout and upstream deps (2026-05-23)

Why

Thirteen audio-queue OpenSpec changes — enterprise-audio-codecs, enterprise-audio-codec-ffmpeg-{native,wasm}, enterprise-audio-engine-server, enterprise-audio-analysis-{spectrum,beat,loudness,pitch}, enterprise-audio-cli, enterprise-audio-sprite-player, and enterprise-react-audio-{player,stream,fingerprint} — were authored before the 2026-05-20 super-category restructure. They still encode the old 2-level packages/audio/<pkg>/ path and reference upstream contracts that do not exist on genesis. Four parallel implementation agents (one per package) refused to ship on 2026-05-23 because the proposals contradict CLAUDE.md and openspec/AGENTS.md §2c forbids silently rewriting spec elements during implementation.

This change ships the prerequisites those thirteen proposals depend on so they can be implemented as authored (post-refresh) with no further blockers.

What changes

1. Path migration — every audio-queue OpenSpec change's proposal.md, tasks.md, design.md, and specs/**/spec.md is rewritten from packages/audio/<pkg>/ to packages/media/audio/<pkg>/ (or packages/ui/react/<pkg>/ for the three react-audio changes). The closed super-category vocabulary in CLAUDE.md is authoritative; no category is added.

2. Workspace catalog: ffmpeg deps — fluent-ffmpeg, @ffmpeg-installer/ffmpeg, @types/fluent-ffmpeg added to catalog.audio and catalog.types; @ffmpeg/ffmpeg and @ffmpeg/core added to catalog.audio for the WASM variant.

3. @suaveplan/audio-core MODIFIED — add the AnalysisOp operator contract and the AnalysisResult base shape required by every audio-analysis-* package. These are types-only additions plus a small runtime helper (createAnalysisOp) for the four analysis packages to consume.

4. enterprise-audio-engine-server MODIFIED in place — replace the spec's hard import dependency on @suaveplan/audio-plugins-fx (which does not exist on genesis) with a locally-owned PluginChain + BusRegistry shape defined inside the engine-server package itself. The original spec intent — per-track plugin chains with PDC recompute and a cycle-safe bus registry — is preserved verbatim; only the import location changes. When @suaveplan/audio-plugins-fx lands in a later wave, an additive OpenSpec amendment can re-route the contract to the upstream package.

5. Date alignment — every refreshed proposal stamps its target archive folder as openspec/archive/2026-05-23-<change-id>/ and the proposal Date: line as 2026-05-23.

6. No scope changes — no Requirements are added, removed, or weakened in the refreshed change folders. Path corrections + dep additions + upstream-contract relocation only.

Impact

• Spec: 13 change folders rewritten in place (paths + dates only) plus one MODIFIED to relocate upstream contracts.
• Code: @suaveplan/audio-core gains AnalysisOp / AnalysisResult types + createAnalysisOp helper. Root package.json gains 5 catalog entries.
• Downstream: the 13 implementation agents can now read their refreshed change folders and ship without further spec amendments. Each becomes an independent implementation PR.
• Risk: nil. Paths are mechanical, catalog additions are additive, the @suaveplan/audio-core addition is types-only + one builder helper at 100% coverage in this change.