The bug was NOT residue type 2 — that lead was a reasonable inference from
"stereo-only, transient-heavy", and it was wrong. The cause was overlap-add
placement of early long blocks.
A block's window is centred on `center` and reaches n/2 either side. A file
opening [256, 256, 2048, ...] puts the first long block's centre at 832, so it
starts at -192 — before sample zero. Those leading samples lie outside the
stream and must be DROPPED. The code used center.saturating_sub(n/2), clamping
the start to 0, which slid the whole block 192 samples later. Every sample was
corrupted until the centres grew past n/2, then decoding was perfect again.
That shape is exactly why it read as a residue fault: a wrong head with a
correct body looks like "specific blocks have wrong amplitude", and
correlation averaged it to 0.82. Mono appeared flawless only because no mono
file in this corpus happens to open with an early long block — a corpus
accident, not a decoder property.
mono 47/47 exact, mean 1.00000 -> 186 files, mean 1.00000, min 1.00000
stereo 68/107 exact, mean 0.826 -> 370 files, mean 1.00000, min 1.00000
corpus 115/160 exact -> 556/556, zero decode errors
The 73 "frame-count mismatches" are afconvert trimming further than the
container specifies; afinfo's valid-frame counts match OUR output exactly and
every file still correlates at 1.0000.
The fix is extracted into a shared overlap_add because decode and debug_raw
each had their own copy — a diagnostic that can disagree with the decoder it
diagnoses is worse than no diagnostic.
New test is fixtured on a file that opens [256, 256, 2048, ...] and asserts
PER-SAMPLE agreement, not just correlation: correlation alone hid this at 0.82.
Decode cost 5.16 ms/file; 11.5 MB compressed expands to 143.3 MB of f32 PCM.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
