open-standards/wai/neural-conformance/README.md

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, which checks the integer-exact contract on x86-64 and arm64 (Linux x86_64, Linux arm64 and macOS arm64) on every push that touches it.

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).
• sha256.json — per vector, the SHA-256 of its decoded output as RGB8 (SPEC §7, Digests): the conformance digest.
• expected_hashes.json — per vector: s_log2, in_channels, layers, width, height, and rgb_hash, a domain-prefixed BLAKE3 of the decoded RGB, kept unchanged as a divergence diagnostic.

The vectors keep their unpinned <dir>/model convention. A sink that pins an int_synth parameter set pins int_synth.json, the one file that holds it (SPEC §5).

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.