Stop refusing measured facts as spec gaps: five entry points corrected
The bitstream module's surveying entry points spent a release refusing, as gaps in
the published specification, facts this project had measured, implemented and
shipped. The shipped decoder was never affected -- a full decode is byte-identical
to 3.5.1 on all 11 decodable corpus files, with all 11 refusals unchanged -- but the
error these functions raised asserted something false about the format.
WHAT WAS WRONG. Four throws in src/bitstream.js carried `{ gap: 8 }`, and gap 8 is
the k-adaptation rule, closed by 7.5.42. None of the four topics was that. The
mis-keying was the smaller half.
The class was the real defect. All four raised PgfUndeterminedError, which
src/errors.js defines as "the published specification does not determine the
behaviour required here" and explicitly NOT "we chose not to implement it". But
section 9.1 records every paper-era gap row 0..11 as closed, including row 7 (`d`
field width -- the position field is split around the sign bit, LSB-first) and row
10 (macroblock serialization, all of it). The scan order is measured for every band,
channel and pyramid level -- 8x8 blocks with clipped edges, LL/HL/LH/HH within an
entry, channel-major, entries topmost-first (7.5.51, 7.5.53, 7.5.58) -- and shipped
as resolveSlot/buildPlan in src/geometry.js, exercised by every conformance harness.
Two of the messages stated the falsehood outright: "that order is established only
for the levels = 1 LL sub-band".
A fifth site, mapStreamIndexToPosition, and decodeSignificanceStream's doc comment
carried the same framing.
WHY THEY STILL REFUSE, WHICH IS THE POINT. Each entry point lacks the GEOMETRY, not
the rule. mapStreamIndexToPosition(streamIndex) is handed one integer;
decodeSignificanceRecord(record, context) is handed 8 bytes; bitsFor holds a fixed
12-byte slice. A slot index means nothing without a plan -- width, height, nLevels,
channels, quality -- so the mapping is a property of the geometry rather than of the
record, and no further measurement can make those signatures sufficient. That is
why the fix is neither to implement them nor to delete them.
They now raise PgfUnsupportedError / PGF_UNSUPPORTED, state that the rule IS
determined with the sections that closed it, explain why this entry point cannot
apply it, and name the function that can -- decodeMacroblock for payloads,
resolveSlot/buildPlan for slot-to-position, decodeToPixels for whole files. The
`gap` key is gone from all of them; no paper-derived row applies. The "do not
improve this function by decoding the record" warning is kept in substance, with its
reason corrected from "the spec does not say" to "the geometry lives elsewhere and
the shipped path already does this correctly".
TWO REFUSALS STAY SPEC GAPS, and the distinction is now load-bearing in the module
header: a bit-plane count of 0, and a byte 0 breaking the bit5 invariant. Those are
genuinely unspecified values.
ALSO CORRECTED. 7.5.57 had already measured multi-coefficient refinement packing
(increasing slot order, LSB-first, 5/5), so bitsFor's "never been observed" was
false on its own terms and not merely mis-classed. src/rlr.js carried the same stale
framing in two places -- its header called the reordering "only partly recovered",
and its kMax note omitted 7.5.106's result that the ceiling is UNREACHABLE rather
than unknown. src/geometry.js back-referenced the bitstream notice as if current.
Several remaining descriptions of the bit-plane count as a "low nibble" are now
"bits 0..4", the field being five bits (7.5.86) -- except in tools/analysis/search.js,
where `planeSource: 'nibble'` NAMES A CANDIDATE READING the tool enumerates on
purpose, and the narrower hypothesis is the point rather than a stale claim.
VERSION. A minor rather than a patch, because the error class and code change on
five public exports: code catching PgfUndeterminedError from decodeSignificanceRecord
would stop catching it. Those are bitstream-surveying entry points that have always
thrown, and no decoding path is affected.
619 tests, up from 618, the addition being a regression test that enumerates all
five refusals and asserts none is a PgfUndeterminedError and none carries a `gap`,
so the old framing cannot come back quietly. Full decode byte-identical to 3.5.1
across the corpus; roi-check, progressive-check, formats-check (210/210 each
direction), encode-check, and the bitmap, indexed, gray, lab and untransformed
harnesses all pass. Recorded as SPEC-DIGEST 7.5.122, explicitly an API-hygiene
defect rather than a decoding one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>