suaveplan/openspec/archive/2026-05-19-add-audio-ir-room-plugin-pool/proposal.md

Add @suaveplan/audio-ir-room-plugin-pool

Package: @suaveplan/audio-ir-room-plugin-pool Status: PROPOSED Type: new-package

Why

Genesis-original IR content package. Ships the outdoor-swimming-pool room IR (from /mnt/c/Users/Administrator/Mountain Duck/74a17879-9780-426d-8bd9-7ed805f53d41/media/_/audio/ir/room/outdoor-swimming-pool.wav) as a bundle-local asset PAIRED with https://swch.b-cdn.net/_/audio/ir/room/roompool.wav as the CDN fallback. Serves as the canonical example of the bundle + fallback content-package pattern — every future audio-ir-{family}-plugin-<name> package that wants a CDN fallback follows this shape.

The URI is a fallback://?u=<bundle>&u=<https> URI built via buildFallbackUri from @suaveplan/storage-uri-plugin-fallback. The shipped fallback:// plugin handles ordered walk + transient classification + per-candidate ALL_CANDIDATES_FAILED cause chain; this package only declares the manifest.

What changes

• ADDED: manifest: IrManifest — { packageSlug: "pool", family: "room", entries: [<pool-outdoor-swimming-pool>] }.
• ADDED: register(registry: IrRegistry, resolver: StorageUriResolver): void — registers the package-scoped bundleUriPlugin on the resolver AND calls registerManifest.
• ADDED: files/outdoor-swimming-pool.wav — bundled binary asset.
• ADDED: entries[0] with id pool-outdoor-swimming-pool AND uri = buildFallbackUri(["bundle://audio-ir-room-plugin-pool/outdoor-swimming-pool.wav", "https://swch.b-cdn.net/_/audio/ir/room/roompool.wav"]).

Out of scope

• Decoding — audio-ir-loader.
• Resolver setup — consumers wire bundleUriPlugin, fallbackUriPlugin, and an HTTP plugin (e.g. @suaveplan/storage-http or any sibling exposing the https scheme) at composition time.
• CDN upload — this change covers only the local manifest declaration; CDN is assumed pre-populated at https://swch.b-cdn.net/_/audio/ir/room/roompool.wav.

Source mapping

• Bundle file: /mnt/c/Users/Administrator/Mountain Duck/74a17879-9780-426d-8bd9-7ed805f53d41/media/_/audio/ir/room/outdoor-swimming-pool.wav (Mountain Duck media library).
• CDN file: https://swch.b-cdn.net/_/audio/ir/room/roompool.wav (existing CDN object — verify reachability at manifest-authoring time).

Cross-cutting model: openspec/changes/add-audio-ir-core/design.md.

Requirements with no source line

Requirement	Justification
every spec requirement	Genesis-original content package

Verification approach

• src/manifest/manifest.test.ts — manifest parses through IrManifestSchema; the entry's uri parses through parseFallbackUri AND yields two candidates in declared order.
• src/register/register.test.ts — register(registry, resolver) adds the bundle plugin AND registers the entry; does NOT add the fallback plugin (that's resolver-owned at composition time).
• tests/integration/bundle-only.test.ts — wire bundleUriPlugin and fallbackUriPlugin and an HTTP plugin; verify the bundle candidate succeeds first and the HTTPS candidate is NOT fetched.
• tests/integration/fallback-walk.test.ts — DELETE the bundle file at fixture-setup time; assert the loader falls through to the HTTPS fixture (served by a node:http server) and decodes successfully; assert fallback_uri.fallback_total{candidate_index:0, outcome:"transient"} is incremented exactly once.

Impact

Affected dependents

No dependents. Verified by bunx turbo ls --filter=...@suaveplan/audio-ir-room-plugin-pool.