# 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.

**Provenance.** `gradient`, `bloom` and `facade` are generated here by `wai_int_synth_vectors` from a fixed SplitMix64 sequence. `photo` is not: it codes a third-party picture that was not made for this repository and has no recorded licence for redistribution, and its decoder was trained on images that are not recorded. It is to be replaced by generated content.

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 third-party picture (see *Provenance*, above):
- `photo` — a 128×128 third-party picture, encoded to a 6,156-byte int8
  latent (96×8×8) + a four-layer integer decoder trained on images the corpus does not record
  (`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, 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.