fix(gf16): reconcile production codec to standard (1+M/512), reclaim wasted mantissa bit

[gHashTag]

Summary

The exported production GF16 codec (golden_float16.GF16, used by every gf16_* C-ABI binding) wasted a mantissa bit and diverged from every other GF16 encoding in the repo. This reconciles it to the standard (1 + M/512)·2^(E−31) form used by the spec-of-record, docs, and the gf_binary ladder — so there is exactly one GF16 codec.

The bug (confirmed with exact-bit tests)

golden_float16.GF16.fromF32 normalized to [0.5, 1.0) and stored (mant_f − 0.5)·512. Across a ~4,000-value sweep the 9-bit mantissa field never exceeded 255 — the top half (256–511) was dead → 8 effective mantissa bits, not 9.

It also produced different raw bits than everything else for the same value:

value	old golden_float16	standard (gf_binary, spec, docs)
1.0	0x4000	0x3E00
1.5	0x4080	0x3F00
3.14159	0x4292	0x4124

The standard form was already used by specs/gf16.tri (from_f32_steps), docs/spec-gf16.md, gf_binary.GF16, and formats_root.f32ToGf16. Only golden_float16 and specs/ops.tri used the wasteful form — an internal spec contradiction. The gf16.tri test_vectors were separately bogus (IEEE-f16 hex, wrong under either convention).

Decision

Owner chose to fix to the standard (1 + M/512) normalization (vs. keeping the old wire format and documenting two encodings).

Changes

• src/formats/golden_float16.zig — GF16.fromF32/toF32 delegate to gf_binary.GF16; one codec, bit-identical by construction. Added an exact-bit test + a golden_float16 ≡ gf_binary reconciliation test.
• testdata/gf_conformance.csv — added gf16 rows (previously excluded); the generic cross-language reader now pins them for Python/Rust/C++.
• src/formats/gf_binary.zig — added gf16 to the exact-bit encoding-regression guard (it skipped gf16 before because the codec diverged).
• specs/ops.tri — 0.5+M/512 → 1+M/512 (and normalize range) to match specs/gf16.tri.
• specs/gf16.tri — fixed the IEEE-f16 copy-paste test_vectors to correct [1:6:9] bits.
• src/c/gf16.h — fixed the documented value formula.
• specs/TRI-HASHES.md — resealed gf16.tri / ops.tri hashes (via shasum).

Reviewer notes

⚠️ Wire-format change: gf16_* now emits standard bits (1.0: 0x4000 → 0x3E00). No FPGA RTL exists in-repo and the FPGA docs already describe [1:6:9] b31, so this aligns the codec with the documented hardware convention rather than departing from it — but any serialized gf16 data matching the old output is incompatible and warrants a format-version bump on release.

ℹ️ Follow-up (not in this PR): tools/gen/check_tri_hashes.zig — the tool CLAUDE.md mandates for resealing — does not compile (JS-style destructuring + stale Zig APIs) and targets the wrong file. Hashes were resealed by hand via shasum (verified the table is plain shasum -a 256). A separate task tracks rewriting it.

Verification

• zig build and zig build test pass (exit 0).
• Freshly built libgoldenfloat.dylib emits every gf16 conformance row exactly (checked via ctypes).
• zig fmt clean; TRI hashes recomputed and matched.

🤖 Generated with Claude Code