nx_zstd_seqdec.nx

nx_zstd_seqdec.nx -- zstd sequence decoding: repeat offsets + the loop. The last piece of zstd's compressed path, built on RFC 8878 rather than recollection. Two things here are easy to get subtly wrong and impossible to notice without the spec. REPEAT OFFSETS SHIFT WHEN LITERALS_LENGTH IS ZERO. An Offset_Value of 1..3 names one of three remembered offsets -- but ONLY when the sequence carries literals. When Literals_Length is zero the whole mapping slides by one: 1 means Repeated_Offset2, 2 means Repeated_Offset3, and 3 means Repeated_Offset1 MINUS ONE BYTE. That last case is not a typo and not a repeat at all; it is a distinct encoding that exists because Repeated_Offset1 is unreachable in that position. A decoder missing this produces correct output until the first zero-literal sequence and wrong output forever after -- and zero-literal sequences are common in highly-repetitive data, which is exactly what zstd is good at. AN OFFSET_VALUE OF 1 WITH LITERALS DOES NOT REORDER THE HISTORY. Every other repeat case moves the used offset to the front. Reordering on this one too looks harmless and desynchronises the history from the encoder's. THE ORDER IS FIXED AND ASYMMETRIC. Extra bits are read offset, then match length, then literals length. States are updated literals length, then match length, then offset. The two orders are NOT the same, and all three states share one bit reader, so any deviation shifts every subsequent read. genealogy_id: rfc8878_sequence_decoding lineage_id: nx_zstd_seqdec_v1 license_tier: ORIGINAL