suaveplan/openspec/archive/2026-05-19-add-audio-ir-loader/tasks.md

Tasks — Add @suaveplan/audio-ir-loader

Every checkbox MUST reflect work actually done in this change. No retroactive ticking. Prereq: add-audio-ir-core and add-audio-ir-loader may proceed in parallel, but the integration test in §4.9 requires both audio-ir-core and audio-decode-wav SHIPPED.

1. Spec authoring

• 1.1 Read openspec/AGENTS.md §§ 13, 14, 14a, 2c, 6a
• 1.2 Read openspec/changes/add-audio-ir-core/design.md for the cross-cutting model
• 1.3 proposal.md (incl. ## Impact per §14a)
• 1.4 design.md — loader-specific pipeline + dispatch + cache decisions
• 1.5 specs/audio-ir-loader/spec.md — every requirement carries **Verified by:**
• 1.6 Working-notes checklist of every ### Requirement and #### Scenario

2. Package scaffold

• 2.1 mkdir -p packages/audio-ir/audio-ir-loader/src/{loader,cache,otel,error-codes}
• 2.2 package.json — version: 0.0.0, sideEffects: false, deps @suaveplan/{audio-ir-core,storage-uri,error,types,opentelemetry}, dev-dep @suaveplan/{audio-decode-wav,storage-uri-plugin-bundle,storage-uri-plugin-fallback} for integration tests, zod, tslib
• 2.3 tsconfig.lib.json, vite.config.ts, biome.json
• 2.4 Subpath exports: ., ./error-codes
• 2.5 README.md

3. Implementation

• 3.1 src/error-codes/error-codes.ts + .md — defineCodes("AUDIO_IR_LOADER", [...])
• 3.2 src/loader/extension.ts + .md — extension extraction (handles bundle://, https://, fallback://)
• 3.3 src/loader/manifest-validation.ts + .md — channels / sampleRate / gainDb application
• 3.4 src/loader/loader.ts + .md — createIrLoader, pipeline orchestration
• 3.5 src/loader/preload.ts + .md — bounded-concurrency preload
• 3.6 src/cache/cache.ts + .md — LRU keyed by id, byte-bounded, overflow throw
• 3.7 src/otel/otel.ts + .md — tracer, counters, histogram
• 3.8 src/index.ts — explicit named re-exports

4. Tests

• 4.1 src/loader/loader.test.ts — construction + happy path + pass-through errors
• 4.2 src/loader/loader.spec-conformance.test.ts — strict-mode + signal threading invariants
• 4.3 src/loader/manifest-validation.test.ts — channels/sampleRate/gainDb
• 4.4 src/loader/extension.test.ts — every URI scheme + edge cases
• 4.5 src/loader/preload.test.ts — concurrency, order, aggregate failure
• 4.6 src/cache/cache.test.ts — hit / miss / eviction / overflow / evict()
• 4.7 src/otel/otel.test.ts — real in-memory MeterProvider
• 4.8 src/error-codes/error-codes.test.ts — exhaustion
• 4.9 tests/integration/with-bundle-fallback.test.ts — real node:http fixture, real bundleUriPlugin, real fallbackUriPlugin, real decodeWav
• 4.10 Every it(...) carries { timeout: 5000 } (or 30000 for async)

5. Documentation

• 5.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples)
• 5.2 README ## Modules
• 5.3 Update root CLAUDE.md Audio IR subsection

6. Pre-archive verification (5-gate triple)

• 6.1 bun run check — 0/0/0/0
• 6.2 bunx turbo lint typecheck test --filter=@suaveplan/audio-ir-loader — green
• 6.3 bunx turbo test:coverage --filter=@suaveplan/audio-ir-loader — 100/100/100/100
• 6.4 bun scripts/openspec-conformance.ts @suaveplan/audio-ir-loader — exit 0
• 6.5 bunx turbo build --filter=@suaveplan/audio-ir-loader — green

7. Pre-archive 7-row checklist (AGENTS §13)

• 7.1 Generics threaded; expectTypeOf assertions
• 7.2 Zod schemas wired at every boundary (loader options)
• 7.3 Every AUDIO_IR_LOADER_CODES code thrown by a production path
• 7.4 Strict-mode behaviors tested both on and off
• 7.5 OTel instruments asserted with real in-memory MeterProvider
• 7.6 Lifecycle dedup tested (cache idempotency, evict idempotency)
• 7.7 No retroactive tick

8. Archive

• 8.1 Fold delta into new openspec/specs/audio-ir-loader/spec.md
• 8.2 Move folder to openspec/archive/<yyyy-mm-dd>-add-audio-ir-loader/
• 8.3 Refresh MANIFEST.md