81c1813822
int_synth's determinism was proven on synthetic/constructed models; this adds a model TRAINED ON REAL IMAGES decoding a REAL PHOTOGRAPH, and proves the same bit-exactness on it. tools/wai_int_synth_real.py trains an autoencoder on real photos, post-training-quantizes the decoder with per-layer activation-scale calibration (the working recipe — pure QAT through the >> shift can't learn), encodes a held-out image to an int8 latent, and decodes it through the EXPORTED integer model in numpy (the same i64 scatter-accumulate / +bias / arithmetic >> shift / clamp that int_synth.rs runs) as the reference. New corpus vector `photo`: a 128×128 macOS Sonoma landscape → a 6,156-byte int8 latent (96×8×8) + a four-layer trained integer decoder, ~21.6 dB at ~3 bpp. Honest scope: a pure integer transposed-conv decoder with no entropy model — quality is modest BY DESIGN; the point is that the decode is bit-identical on every machine. wai_int_synth_vectors `gen` cross-checks the Rust decode against the python integer-forward (ref_rgb.bin) to max|Δ|=0 and freezes the rgb_hash; the four-platform conformance CI then enforces the same bytes everywhere. A real trained model, a real photo, decoded identically on every machine — the int_synth thesis, demonstrated end to end. Co-Authored-By: Claude Opus 4.8 <[email protected]>
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# Neural Conformance Corpus — integer synthesis
|
||
|
||
Vectors for the **integer-synthesis** neural decoder (`wai.neural.int_synth`).
|
||
This is the one neural decoder that can make the promise the reconstruct
|
||
cargo classes make: **bit-identical output on every machine, no tolerance** —
|
||
because its synthesis is pure `i64` arithmetic (integer transposed
|
||
convolutions + arithmetic-shift requantize + integer ReLU), not float ONNX.
|
||
Two sinks honoring the spec produce the same bytes on every architecture.
|
||
|
||
The float decoders (`bmshj2018`, `mbt2018_mean`, `elic`, `mlicpp`, …) are
|
||
deliberately **not** here: their ONNX synthesis is float, so two conforming
|
||
sinks on different hardware may differ in the low bits — a byte-equality
|
||
corpus would be a false promise for them. The integer decoder is the member
|
||
where `intent = replicate` is sound, so it is the member with a cross-arch
|
||
byte-equality corpus.
|
||
|
||
Because the decoder pulls in no float runtime, it lives at the crate root
|
||
behind the light `neural_int` feature (no `ort`), so this corpus is verified
|
||
in the same no-system-deps CI matrix as the reconstruct classes — proving
|
||
the integer-exact contract on x86-64 and arm64 across Linux, macOS, and
|
||
Windows, every push.
|
||
|
||
## Layout
|
||
|
||
- `vectors/<name>/int_synth.json` — the integer decoder model (per-layer
|
||
weights/bias as `i32`, stride, requantize shift, integer ReLU flag).
|
||
- `vectors/<name>/latent.bin` — the wire payload (12-byte header +
|
||
channel-major `int8` latents).
|
||
- `expected_hashes.json` — per vector: `s_log2`, `in_channels`, `layers`,
|
||
`width`, `height`, and `rgb_hash` (domain-prefixed BLAKE3 of the decoded
|
||
RGB — the conformance quantity).
|
||
|
||
Synthetic vectors (realistic multi-layer decoders, distinct shapes) — model
|
||
weights/latents authored from a fixed integer SplitMix64 sequence, so `gen`
|
||
is reproducible without a float RNG:
|
||
- `gradient` — 8×8 latent, 4 ch → ×2 → ×2 = 38×38 RGB, two layers, one ReLU.
|
||
- `bloom` — 4×4 latent, 8 ch → ×4 (single deep upsample) = 18×18 RGB.
|
||
- `facade` — 16×16 latent, 3 ch → ×2 → ×2 → refine = 72×72 RGB, three
|
||
layers, two ReLUs (a deeper integer stack).
|
||
|
||
And one **real trained model on a real photograph**:
|
||
- `photo` — a 128×128 macOS *Sonoma* landscape, encoded to a 6,156-byte int8
|
||
latent (96×8×8) + a four-layer integer decoder **trained on real images**
|
||
(`tools/wai_int_synth_real.py`: float-train + post-training quantization with
|
||
per-layer activation-scale calibration). Reconstruction ≈ 21.6 dB at ~3 bpp.
|
||
This is the honest scope of int_synth: a pure integer transposed-conv decoder
|
||
with no entropy model — its **quality is modest by design**; its **point is
|
||
that the decode is bit-identical on every machine**. At `gen` time the Rust
|
||
decoder is cross-checked against the tool's python integer-forward
|
||
(`ref_rgb.bin`) to max|Δ|=0, and the frozen `rgb_hash` then enforces the same
|
||
bytes on every platform in CI — a real trained model, a real photo, decoded
|
||
identically everywhere.
|
||
|
||
## Running
|
||
|
||
```
|
||
cd ../wai-rs
|
||
cargo run --features neural_int --bin wai_int_synth_vectors -- verify ../neural-conformance
|
||
cargo run --features neural_int --bin wai_int_synth_vectors -- gen ../neural-conformance # regenerate
|
||
```
|
||
|
||
Pass = decoded-RGB BLAKE3 + dimensions equality, on every machine.
|