media/type: declare the magic-byte signatures once - #1533

Approving. Two things worth recording below — one is a real (deliberate, documented) behaviour change at a boundary, the other is a testing suggestion. Neither blocks.

Baseline: origin/main at 16142109; branch merge-base 373c3325, i.e. one commit behind, nothing overlapping.

Gates

• npx tsc --noEmit — exit 0. npm run prepack from a clean tree — exit 0.
• npm test — 2540 / 0, same as main.
• Public surface: bin/extract.mjs and bin/consts.mjs identical to main; file-aware export type listing across the emitted .d.mts identical (589 lines both sides). signatures stays module-private, detect's signature is unchanged.
• node bin/linkcheck.mjs — broken-link sets identical to main, so deleting todo/single-signature-table.md stranded nothing (the one inbound reference, in detect-json.md's Related list, is removed in the same commit). Its two updated line references check out: finish is at :221-229 and the UTF-8 factor at :140-161.
• §8.3 CHANGELOG — code change, entry present, links only /pull/1533.

Faithfulness of the extraction, at the boundaries

I did not take "same signatures, one copy" on trust. I enumerated the nine signatures that existed before, compared them byte-for-byte against the new signatures list (they match, including the three PK variants and both GIF version headers, and WebP's four-byte gap becomes exactly four null wildcards), then ran main's detect and this head's detect side by side over 1115 constructed inputs: each signature exact, exact-plus-trailing-bytes, truncated by every whole number of bytes, truncated by 1–7 bits, one byte off at every position (±1 and ^0x80), shifted by a leading byte, the GIF8-prefix trap, WebP with RIFF only / size only / a wrong second marker / 11 bytes, plus 800 pseudo-random and signature-biased vectors at random bit lengths.

inputs=1115 divergent=1 nonNullMain=30 nonNullPr=31
  png/trunc-1bit  bytes=[89 50 4e 47 0d 0a 1a 0a] drop=1bit  main=null  pr=image/png
divergent with dropBits=0: 0

Negative control: flipping one byte of the JPEG pattern (0xff → 0xfe) on the PR side made the comparison report the expected extra divergences and then 0 again after reverting, so it is not a comparison that cannot fail.

So: on any byte-aligned Vec — the only shape a CAS blob or a file ever has — the new detect is byte-for-byte the old one. The single divergence is exactly the case the new JSDoc calls out: a Vec whose length is not a whole number of bytes now has its trailing partial byte zero-padded by u8List, so 71 bits of the PNG header complete the signature (PNG's last byte 0x0a has a zero low bit) where startsWith on a 72-bit pattern used to reject it.

That is the right direction, and it is a fix rather than a regression — I checked what main did with the same input:

main: detectVec(71bit).mime_type = image/png | detect(71bit) = null
pr:   detectVec(71bit).mime_type = image/png | detect(71bit) = image/png

main's two detectors disagreed on ragged input; this head makes them agree, which is the whole point of the extraction. Worth knowing that the old single-signature-table.md justified the change with "detectVec already proves the streaming machine reproduces detect's verdict on whole buffers" — true for whole buffers, and this is the one place where it was not. The CHANGELOG entry might be worth a clause saying sub-byte-length Vecs now read the same way detectStream reads them, since that is the only observable difference.

Proof coverage — a suggestion, not a regression

The proof (34 assertions) passes, but three mutations survive it:

• deleting the PK 07 08 (spanned-archive) signature entirely;
• magicStep's terminal-position test s.pattern.length === pos + 1 → pos + 2;
• dropping the if (magic.tag !== 'scan') { break } in the new detect — this one is fine, since matched and dead are absorbing, so the mutant is semantically equivalent and surviving is correct.

The second is the one I would pin. The mutant makes every signature match one byte early, so it defeats precisely the guarantee the code comment claims: detect([47 49 46 38 37]) returns image/gif (the "GIF8"-prefix trap the comment says must not fire) and detect([ff d8]) returns image/jpeg.

I checked whether this is a regression before saying anything, and it is not: on main, deleting PK 07 08 from either copy, and the same pos + 2 mutation, all leave the proof green too. The gaps are pre-existing in the eliminator, and my 1115-input differential says the arithmetic is in fact correct today. What changes here is only that one untested line is now load-bearing for both detectors instead of one — which, on balance, is the extraction working as intended (a missing zip3 test used to have to be right in two places, now one). A truncated-signature case per pattern and a PK 07 08 case would close it cheaply. fromSentinel keeps its own coverage in bit_vec's proof, so dropping its last consumer here does not orphan it.

The README and module header now describe one list rather than two, the "table above is documentation" note is accurate, and the deleted todo's proposal matches what landed (table, the sig literals, riff, webp, isWebp all gone).