yellowjacket/.planning/plans/completed/004-v1.2.1-format-parity.md

004 — v1.2.1 Format Parity (OGG + WAV)

Closes the tag-writing format gap: every file YellowJacket plays can also be edited. OGG Vorbis and WAV writers, plus a wsl_v5 lint cleanup. (This was tracked as M001 in the GSD system; S01–S18 in that milestone were just retroactive imports of v1.0–v1.2.)

Shipped: 2026-03-21 · Phases: 19-21

What landed

• Phase 19 — WAV tag writer. Custom RIFF parser with lenient-read / strict-write behavior. ID3v2 chunk placed at end of file after preserved chunks. Case-insensitive id3/ID3 chunk detection. Existing ID3v2 tags merged so unknown frames written by other tools survive. Read-back uses bogem/id3v2.ParseReader (handles cleared tags correctly; dhowden/tag does not).
• Phase 20 — OGG Vorbis tag writer. Custom OGG page parser/writer with MSB-first CRC32 (Go's hash/crc32 uses incompatible reflected bit ordering, so a precomputed 256-entry lookup table lives in-package). Vorbis Comment serializer with METADATA_BLOCK_PICTURE cover art. Raw byte preservation for non-edited entries — avoids corrupting non-UTF-8 tags. Tests use a programmatic fixture builder (no embedded binaries). CRC32 validated against independently computed known vectors (OggS → 0x5fb0a94f, {1..8} → 0x7d0f3681).
• Phase 21 — Cleanup. wsl → wsl_v5 upgrade, all 19 pre-existing warnings fixed.

Test coverage

• 7 FLAC round-trip tests (pre-existing).
• WAV round-trip tests covering all 8 text fields + cover art.
• OGG round-trip tests with CRC32 validation against known vectors.
• All pass with -race.