Initial Commit

openspec/archive/2026-05-19-add-audio-decode-wav/tasks.md

@@ -0,0 +1,74 @@
+# Tasks — Add `@suaveplan/audio-decode-wav`
+
+> Every checkbox MUST reflect work actually done in this change. No retroactive ticking.
+
+## 1. Spec authoring
+
+- [ ] 1.1 Read `openspec/AGENTS.md` Sections 13, 14, 2c (code reachability), 6a (barrel rule)
+- [ ] 1.2 Inspect `../audio-decode/packages/decode-wav/decode-wav.js` and `../audio-decode/audio-decode.d.ts` to nail the upstream surface
+- [ ] 1.3 `proposal.md` from `openspec/templates/proposal.md`
+- [ ] 1.4 `specs/audio-decode-wav/spec.md` — every requirement carries `**Verified by:**`
+- [ ] 1.5 Working-notes checklist enumerates every `### Requirement` and `#### Scenario` (§206)
+
+## 2. Package scaffold
+
+- [ ] 2.1 `mkdir -p packages/audio/audio-decode-wav/src/{decode-wav,stream,otel,error-codes,types,utils}`
+- [ ] 2.2 `package.json` — `version: 0.0.0`, `sideEffects: false`, deps `@suaveplan/{error,types,opentelemetry}`, `@audio/decode-wav` from `../audio-decode/packages/decode-wav` via catalog, `zod`, `tslib`
+- [ ] 2.3 `tsconfig.lib.json`, `vite.config.ts` (mirror `audio-plugins-fx` pattern), `biome.json` (extends root)
+- [ ] 2.4 Subpath exports: `.` (barrel), `./stream`, `./error-codes`
+- [ ] 2.5 `README.md` at package root only — links every co-located `.md` under `## Modules`
+
+## 3. Implementation
+
+- [ ] 3.1 `src/types/decoded-audio.ts` — `DecodedAudio` interface + Zod schema + freeze invariant
+- [ ] 3.2 `src/types/decoded-audio.md`
+- [ ] 3.3 `src/types/options.ts` — `AudioDecodeOptions` Zod schema
+- [ ] 3.4 `src/types/options.md`
+- [ ] 3.5 `src/error-codes/error-codes.ts` — `defineCodes("AUDIO_DECODE.WAV", [...])` registry
+- [ ] 3.6 `src/error-codes/error-codes.md`
+- [ ] 3.7 `src/decode-wav/decode-wav.ts` — `decodeWav` orchestrator over upstream `@audio/decode-wav`
+- [ ] 3.8 `src/decode-wav/decode-wav.md`
+- [ ] 3.9 `src/stream/stream.ts` — `createWavStreamDecoder` wrapping upstream `decode.stream`
+- [ ] 3.10 `src/stream/stream.md`
+- [ ] 3.11 `src/otel/otel.ts` — tracer/meter setup, counter + histogram registration
+- [ ] 3.12 `src/otel/otel.md`
+- [ ] 3.13 `src/index.ts` — explicit named re-exports (rule 10); NO `export *`
+
+## 4. Tests
+
+- [ ] 4.1 `src/decode-wav/decode-wav.test.ts` — every scenario in spec delta requirements 1–4
+- [ ] 4.2 `src/stream/stream.test.ts` — every scenario in spec delta requirement 5
+- [ ] 4.3 `src/otel/otel.test.ts` — every scenario in spec delta requirement 6 with a real in-memory `MeterProvider`
+- [ ] 4.4 `src/error-codes/error-codes.test.ts` — exhaustion check per spec delta requirement 7
+- [ ] 4.5 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for genuinely async)
+- [ ] 4.6 Fixtures under `tests/fixtures/` — generated WAV bytes (mono/stereo, 16/24-bit PCM, 32-bit float, A-law); checked in only if `< 50 KiB` total, else generated programmatically
+
+## 5. Documentation
+
+- [ ] 5.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
+- [ ] 5.2 README `## Modules` section linking every `.md`
+- [ ] 5.3 Update root `CLAUDE.md` package listing — add `audio-decode-wav` under a new "Audio codecs" subsection (§13b root-doc refresh)
+
+## 6. Pre-archive verification (5-gate triple)
+
+- [ ] 6.1 `bun run check` — Biome 0/0/0/0 across the whole monorepo
+- [ ] 6.2 `bunx turbo lint typecheck test --filter=@suaveplan/audio-decode-wav` — green
+- [ ] 6.3 `bunx turbo test:coverage --filter=@suaveplan/audio-decode-wav` — 100/100/100/100
+- [ ] 6.4 `bun scripts/openspec-conformance.ts @suaveplan/audio-decode-wav` — exit 0, no `error` findings
+- [ ] 6.5 `bunx turbo build --filter=@suaveplan/audio-decode-wav` — green
+
+## 7. Pre-archive 7-row checklist (AGENTS §13)
+
+- [ ] 7.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
+- [ ] 7.2 Zod schemas wired at every declared boundary (`AudioDecodeOptions`, `DecodedAudio`)
+- [ ] 7.3 Every code in `AUDIO_DECODE_WAV_CODES` thrown by at least one production path
+- [ ] 7.4 Strict-mode behaviors tested both on and off
+- [ ] 7.5 OTel instruments asserted with a real in-memory `MeterProvider`
+- [ ] 7.6 Lifecycle dedup tested where claimed (stream decoder free → feed throws)
+- [ ] 7.7 No retroactive tick
+
+## 8. Archive
+
+- [ ] 8.1 Fold delta into new `openspec/specs/audio-decode-wav/spec.md`
+- [ ] 8.2 Move folder to `openspec/archive/<yyyy-mm-dd>-add-audio-decode-wav/`
+- [ ] 8.3 Refresh `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`