Initial Commit

openspec/changes/archive/2026-05-15-enterprise-audio-sprite-packer/tasks.md

@@ -0,0 +1,83 @@
+# Tasks: enterprise-audio-sprite-packer
+
+**Change ID**: enterprise-audio-sprite-packer
+**Package**: `@suaveplan/audio-sprite-packer`
+**Target path**: `universal/compression/audio-sprite-packer`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils`
+
+---
+
+## 1. Scaffold
+
+- [ ] Create directory `universal/compression/audio-sprite-packer/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
+- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/mime workspace:^`, `@suaveplan/crypto-utils workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
+- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
+- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
+- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
+
+---
+
+## 2. Types + errors
+
+- [ ] Write `src/types/common.ts` — `AudioFormat`, `AudioClipInput`, `AudioSpriteEntry`, `AudioSpriteManifest`, `AudioSprite`, `PackOptions`, `AudioAdapter`, `AudioSpritePackerOptions`.
+- [ ] Write `src/types/common.md`.
+- [ ] Write `src/error-codes.ts` — `AudioSpriteErrorCode`, `AUDIO_SPRITE_ERROR_METADATA`, `registerAudioSpriteErrorCodes()`.
+- [ ] Write Zod schemas: `AudioSpriteEntrySchema`, `AudioSpriteManifestSchema`, `PackOptionsSchema`, `AudioSpritePackerOptionsSchema`.
+
+---
+
+## 3. NullAudioAdapter
+
+- [ ] Implement `NullAudioAdapter` — `probe` returns configurable fixture metadata (WAV, 44100 Hz, 2ch, 1.0 s), `decode` returns 44100 × 2 float32 zeros, `encode` returns input bytes, `stripSilence` returns input unchanged, `normalise` returns input unchanged.
+- [ ] Write `null-adapter.test.ts` and `null-adapter.md`.
+
+---
+
+## 4. Manifest utilities
+
+- [ ] Implement `buildManifest(entries, packedBuffer): AudioSpriteManifest` — assembles manifest including SHA-256 content hash via `@suaveplan/crypto-utils`.
+- [ ] Implement `validateManifest(manifest): void` — checks version, entries array non-empty, offsets non-overlapping.
+- [ ] Write `manifest.test.ts` and `manifest.md`.
+
+---
+
+## 5. AudioSpritePacker
+
+- [ ] Implement `AudioSpritePacker.pack(clips, options, signal)`:
+  1. Validate clips non-empty.
+  2. For each clip: detect format (`@suaveplan/mime`), probe, decode PCM.
+  3. If `stripSilence`, call `adapter.stripSilence`.
+  4. If `normalise`, call `adapter.normalise`.
+  5. Append silence padding (zero-fill float32 × sampleRate × silencePaddingMs / 1000).
+  6. Encode all clips concatenated as single output buffer.
+  7. Build manifest with byte offsets per clip.
+  8. Return `{ data, manifest }`.
+- [ ] Implement `AudioSpritePacker.unpack(sprite, clipName)` — slice-and-return using manifest offsets.
+- [ ] Wire `AbortSignal` propagation; throw on abort.
+- [ ] Wire OTel: span `audio-sprite.pack`, counter, histogram, compression ratio.
+- [ ] Write `audio-sprite-packer.test.ts` (≤500 lines): pack 3 clips, unpack each, abort, empty clips throws.
+- [ ] Write `audio-sprite-packer.md`.
+
+---
+
+## 6. Benchmarks
+
+- [ ] Write `src/__benchmarks__/audio-sprite-packer.bench.ts` — pack 10 clips, pack 50 clips (null adapter).
+
+---
+
+## 7. Tests
+
+- [ ] Write `tests/integration.test.ts` — full pack/unpack round-trip.
+- [ ] Write `tests/property.test.ts` (fast-check) — manifest entry count = clip count, unpack returns correct slice, silence padding duration.
+
+---
+
+## 8. Docs + verify + publish
+
+- [ ] All co-located `.md` files (≥200 words each).
+- [ ] Write `README.md` at package root.
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/audio-sprite-packer` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-sprite-packer` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/audio-sprite-packer`.
+- [ ] Archive to `openspec/archive/2026-04-24-enterprise-audio-sprite-packer/`.