# 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`