open-standards/wai/wai-rs/tests/neural_native_decode.rs

//! Native-sink E2E: decode every shipped `.wai` neural sample through
//! the Rust `ort`-backed runtime. Asserts the decoder produces sane
//! output (right sample count for audio, right pixel grid for image,
//! right frame count for video, and a non-trivial signal in each).
//!
//! Models are expected at `wai-web/demo/models/<name>/decoder.onnx` —
//! built via the corresponding `tools/wai_<name>_export_onnx.py` once
//! per machine (see wai-web/demo/models/README.md).
//!
//! Skipped (printed, not failed) when a given .onnx isn't present yet,
//! so a fresh clone with only some models built still runs the tests
//! that can run.

#![cfg(feature = "neural")]

use std::path::{Path, PathBuf};

use wai::container::{Conditioning, Manifest, ModelRequirement, Prior, Wai};
use wai::neural::{
    decode_envelope, decode_envelope_strict, model_sha256, DecodeError, Decoded, ModelRegistry,
};

fn repo_root() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR")).join("..").canonicalize().unwrap()
}

fn model_path(name: &str) -> PathBuf {
    repo_root().join(format!("wai-web/demo/models/{name}/decoder.onnx"))
}

fn sample_path(name: &str) -> PathBuf {
    repo_root().join(format!("wai-web/demo/samples/{name}"))
}

fn load_envelope(name: &str) -> Wai {
    let bytes = std::fs::read(sample_path(name))
        .unwrap_or_else(|e| panic!("read {name}: {e}"));
    Wai::from_bytes(&bytes).unwrap_or_else(|e| panic!("parse {name}: {e}"))
}

fn registry() -> ModelRegistry {
    ModelRegistry::new()
        .register("wai.neural.encodec32",         model_path("encodec_32khz"))
        .register("wai.neural.dac",               model_path("dac_44khz"))
        .register("wai.neural.mimi",              model_path("mimi"))
        .register("wai.neural.wavtokenizer",      model_path("wavtokenizer"))
        .register("wai.neural.bmshj2018",         model_path("bmshj2018"))
        .register("wai.neural.video_bmshj2018",   model_path("bmshj2018"))   // shares the image decoder
}

fn assert_audio_sane(cap: &str, sample_file: &str, expected_sr: u32, min_samples: usize) {
    let onnx = model_path(match cap {
        "wai.neural.encodec32"    => "encodec_32khz",
        "wai.neural.dac"          => "dac_44khz",
        "wai.neural.mimi"         => "mimi",
        "wai.neural.wavtokenizer" => "wavtokenizer",
        _ => unreachable!(),
    });
    if !onnx.exists() {
        eprintln!("skipping {cap}: {} not built (see tools/wai_<name>_export_onnx.py)",
                  onnx.display());
        return;
    }
    let env = load_envelope(sample_file);
    assert_eq!(env.manifest.model_requirement.capability, cap,
               "{sample_file} declares wrong capability");
    let dec = decode_envelope(&env, &registry())
        .unwrap_or_else(|e| panic!("decode {sample_file}: {e}"));
    match dec {
        Decoded::Audio(audio) => {
            assert_eq!(audio.sample_rate, expected_sr,
                       "{cap}: wrong sample rate");
            assert!(audio.samples.len() >= min_samples,
                    "{cap}: only {} samples, expected ≥ {}",
                    audio.samples.len(), min_samples);
            // Non-trivial signal: peak amplitude well above 0.
            let peak = audio.samples.iter().fold(0f32, |a, &b| a.max(b.abs()));
            assert!(peak > 0.01, "{cap}: peak={peak:.4} (silent decode?)");
            // No NaNs.
            assert!(audio.samples.iter().all(|s| s.is_finite()),
                    "{cap}: NaN/Inf in output");
            println!("  {cap}: {} samples @ {} Hz, peak {:.3}",
                     audio.samples.len(), audio.sample_rate, peak);
        }
        _ => panic!("{cap}: expected Decoded::Audio"),
    }
}

#[test] fn encodec32_decodes_natively() {
    assert_audio_sane("wai.neural.encodec32",  "glass.encodec.wai",       32_000, 16_000);
}
#[test] fn dac_decodes_natively() {
    assert_audio_sane("wai.neural.dac",        "glass.dac.wai",           44_100, 22_000);
}
#[test] fn mimi_decodes_natively() {
    assert_audio_sane("wai.neural.mimi",       "glass.mimi.wai",          24_000, 12_000);
}
#[test] fn wavtokenizer_decodes_natively() {
    assert_audio_sane("wai.neural.wavtokenizer", "glass.wavtokenizer.wai", 24_000, 12_000);
}

#[test]
fn bmshj2018_decodes_natively() {
    let onnx = model_path("bmshj2018");
    if !onnx.exists() {
        eprintln!("skipping bmshj2018: {} not built", onnx.display());
        return;
    }
    let env = load_envelope("kodim23.bmshj2018.wai");
    let dec = decode_envelope(&env, &registry()).expect("bmshj2018 decode");
    match dec {
        Decoded::Image(img) => {
            assert_eq!(img.width, 256);
            assert_eq!(img.height, 256);
            assert_eq!(img.rgb.len(), 256 * 256 * 3);
            // Variance: a real image has lots of pixel variation. A blank
            // decode would be near-constant.
            let mean = img.rgb.iter().map(|&v| v as f64).sum::<f64>() / img.rgb.len() as f64;
            let var  = img.rgb.iter()
                .map(|&v| (v as f64 - mean).powi(2)).sum::<f64>() / img.rgb.len() as f64;
            assert!(var > 100.0, "bmshj2018: variance {var:.0} suspiciously low");
            println!("  bmshj2018: 256x256 RGB, mean={mean:.1}, var={var:.0}");
        }
        _ => panic!("bmshj2018: expected Decoded::Image"),
    }
}

/// Determinism is half the `Prior.determinism` contract: a "replicate" claim
/// is only meaningful if the same envelope decodes to the same bytes every
/// time. Decode twice through the pinned single-thread runtime and require
/// bit-identical output.
#[test]
fn bmshj2018_decode_is_deterministic() {
    let onnx = model_path("bmshj2018");
    if !onnx.exists() {
        eprintln!("skipping determinism: {} not built", onnx.display());
        return;
    }
    let env = load_envelope("kodim23.bmshj2018.wai");
    let reg = registry();
    let rgb = |w: &Wai| match decode_envelope(w, &reg).expect("decode") {
        Decoded::Image(i) => i.rgb,
        _ => panic!("expected image"),
    };
    let first = rgb(&env);
    let second = rgb(&env);
    assert_eq!(first, second, "bmshj2018 decode is not bit-reproducible across runs");
    println!("  bmshj2018: byte-identical across two decodes ({} bytes)", first.len());
}

/// The pinned prior is enforced: an envelope that names a prior decodes ONLY
/// against the model whose bytes hash to it. The correct hash decodes; a
/// tampered hash is refused with `PriorMismatch` — never a silent wrong image.
#[test]
fn pinned_prior_is_enforced() {
    let onnx = model_path("bmshj2018");
    if !onnx.exists() {
        eprintln!("skipping prior-pin: {} not built", onnx.display());
        return;
    }
    let real = model_sha256(&onnx).expect("hash model");
    let base = load_envelope("kodim23.bmshj2018.wai");

    // Re-wrap the envelope with a pinned prior in its conditioning.
    let pin = |sha: &str| -> Wai {
        let mut m = base.manifest.clone();
        m.conditioning.prior = Some(Prior {
            id: "bmshj2018-factorized/q3".into(),
            sha256: sha.into(),
            determinism: "int-rans/p16+onnx-cpu-f32/1thread".into(),
        });
        Wai::new(m, base.payload.clone())
    };

    // Correct pin → decodes.
    assert!(
        matches!(decode_envelope(&pin(&real), &registry()), Ok(Decoded::Image(_))),
        "envelope pinning the true model hash should decode"
    );

    // Tampered pin → refused, loudly, not a silent reconstruction.
    let mut wrong = real.clone();
    wrong.replace_range(0..1, if real.starts_with('0') { "1" } else { "0" });
    match decode_envelope(&pin(&wrong), &registry()) {
        Err(DecodeError::PriorMismatch(_)) => {}
        other => panic!("tampered prior must be refused with PriorMismatch, got {other:?}"),
    }
    println!("  pinned prior: true hash decodes, tampered hash refused");
}

/// The prior check is pure hashing and runs with no ONNX model present, so
/// this exercises the actual verification logic on every machine. A stand-in
/// file plays the "model"; the registry must accept the true hash, accept an
/// absent prior, and refuse a wrong one.
#[test]
fn resolve_checked_verifies_prior_hash() {
    let path = std::env::temp_dir().join("wai_prior_check_model.bin");
    std::fs::write(&path, b"pretend onnx decoder weights v1").unwrap();
    let real = model_sha256(&path).expect("hash stand-in model");

    let reg = ModelRegistry::new().register("wai.neural.bmshj2018", path.clone());

    // No prior → unverified pass (floor codec / honest perceptual-neural).
    assert!(reg.resolve_checked("wai.neural.bmshj2018", None).is_ok(),
            "absent prior should resolve unverified");

    // Correct pin → pass.
    let good = Prior { id: "m/q3".into(), sha256: real.clone(), determinism: "x".into() };
    assert!(reg.resolve_checked("wai.neural.bmshj2018", Some(&good)).is_ok(),
            "true hash should resolve");

    // Wrong pin → refused, loudly.
    let bad = Prior { id: "m/q3".into(), sha256: "00".repeat(32), determinism: "x".into() };
    assert!(matches!(reg.resolve_checked("wai.neural.bmshj2018", Some(&bad)),
                     Err(DecodeError::PriorMismatch(_))),
            "wrong hash must be a PriorMismatch");

    // Unknown capability → unregistered, regardless of prior.
    assert!(matches!(reg.resolve_checked("wai.neural.nope", None),
                     Err(DecodeError::ModelNotRegistered(_))));

    let _ = std::fs::remove_file(&path);
    println!("  resolve_checked: none=ok, true=ok, wrong=mismatch, unknown=unregistered");
}

#[test]
fn video_bmshj2018_decodes_natively() {
    let onnx = model_path("bmshj2018");
    if !onnx.exists() {
        eprintln!("skipping video_bmshj2018: {} not built", onnx.display());
        return;
    }
    let env = load_envelope("test.video.wai");
    let dec = decode_envelope(&env, &registry()).expect("video decode");
    match dec {
        Decoded::Video(v) => {
            assert!(v.frames_rgb.len() > 0, "no frames decoded");
            assert_eq!(v.width, 256);
            assert_eq!(v.height, 256);
            assert!((v.fps - 12.0).abs() < 0.01, "fps {} != 12", v.fps);
            // First frame should have non-trivial variance.
            let f0 = &v.frames_rgb[0];
            let mean = f0.iter().map(|&v| v as f64).sum::<f64>() / f0.len() as f64;
            let var  = f0.iter().map(|&v| (v as f64 - mean).powi(2)).sum::<f64>() / f0.len() as f64;
            assert!(var > 100.0, "video frame 0 variance {var:.0} suspiciously low");
            println!("  video_bmshj2018: {} frames {}x{} @ {} fps",
                     v.frames_rgb.len(), v.width, v.height, v.fps);
        }
        _ => panic!("video_bmshj2018: expected Decoded::Video"),
    }
}

/// The replicate-soundness gate runs BEFORE any model is touched, so this is
/// model-independent. A `replicate` envelope is decodable strictly only if it
/// pins an integer-exact prior; float-reproducible or absent priors are
/// rejected, and non-`replicate` intents are unconstrained.
#[test]
fn strict_decode_gates_unsound_replicate() {
    fn env(prior: Option<Prior>, intent: &str) -> Wai {
        let manifest = Manifest {
            wai: "1.0".into(),
            media: "image".into(),
            intent: intent.into(),
            model_requirement: ModelRequirement {
                capability: "wai.neural.bmshj2018".into(),
                fallback: None,
                min_sim: None,
                sim_metric: None,
            },
            conditioning: Conditioning { kind: "bmshj2018".into(), prior },
            target: serde_json::json!({"w": 256, "h": 256}),
        };
        Wai::new(manifest, vec![])
    }
    let p = |det: &str| Prior { id: "m".into(), sha256: "ab".repeat(32), determinism: det.into() };
    let integer = p("int-rans/p16+onnx-int8-integerized");
    let floaty = p("int-rans/p16+onnx-cpu-f32/1thread");

    let reg = ModelRegistry::new(); // empty: the gate fires before model resolution

    // replicate + float prior → rejected, before any model touch.
    assert!(matches!(
        decode_envelope_strict(&env(Some(floaty.clone()), "replicate"), &reg),
        Err(DecodeError::UnsoundReplicate(_))
    ));
    // replicate + NO prior → rejected.
    assert!(matches!(
        decode_envelope_strict(&env(None, "replicate"), &reg),
        Err(DecodeError::UnsoundReplicate(_))
    ));
    // replicate + integer-exact prior → gate PASSES, falls through to model
    // resolution (ModelNotRegistered proves the gate let it past).
    assert!(matches!(
        decode_envelope_strict(&env(Some(integer), "replicate"), &reg),
        Err(DecodeError::ModelNotRegistered(_))
    ));
    // A non-replicate intent isn't constrained by the gate.
    assert!(matches!(
        decode_envelope_strict(&env(Some(floaty), "improve"), &reg),
        Err(DecodeError::ModelNotRegistered(_))
    ));
    println!("  strict gate: float/absent rejected, integer-exact + non-replicate pass");
}

/// END-TO-END validation against the real CompressAI mbt2018-mean model:
/// decode the SAME envelope in Rust and compare to CompressAI's own decode.
/// The Gaussian-conditional entropy decode must be EXACT (same rANS bytes →
/// same latents); only `g_s` (ONNX vs torch float) may differ by a hair. A
/// large divergence means the entropy decode is wrong. Artifacts produced by
/// the export/encode tools + a CompressAI reference decode; skipped if absent.
#[test]
fn mbt2018_mean_matches_compressai_reference() {
    let wai = Path::new("/tmp/test.mbt.wai");
    let ref_rgb = Path::new("/tmp/ref.rgb");
    let model_dir = Path::new("/tmp/wai_mbt");
    if !wai.exists() || !ref_rgb.exists() || !model_dir.join("hyper_synthesis.onnx").exists() {
        eprintln!("skipping mbt reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.mbt2018_mean", model_dir.join("model"));
    let img = match decode_envelope(&env, &reg).expect("rust decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    assert_eq!((img.width, img.height), (256, 256));
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let diffs = || img.rgb.iter().zip(&reference).map(|(a, b)| (*a as i32 - *b as i32).abs());
    let maxd = diffs().max().unwrap();
    let meand = diffs().map(|d| d as f64).sum::<f64>() / reference.len() as f64;
    println!("  mbt2018_mean vs CompressAI: max|Δ|={maxd}  mean|Δ|={meand:.3}");
    assert!(maxd <= 4, "Rust decode diverges from CompressAI (max {maxd}) — entropy decode wrong");
}

/// END-TO-END validation of the EXISTING factorized `image.rs` decoder against
/// the real CompressAI bmshj2018-factorized. Factorized = static CDFs (no
/// scale-from-network), so it shouldn't have the hyperprior's bucket-flip
/// hazard. Skipped without /tmp artifacts.
#[test]
fn bmshj2018_matches_compressai_reference() {
    let wai = Path::new("/tmp/test.bmshj.wai");
    let ref_rgb = Path::new("/tmp/ref_bmshj.rgb");
    let model = Path::new("/tmp/wai_bmshj/decoder.onnx");
    if !wai.exists() || !ref_rgb.exists() || !model.exists() {
        eprintln!("skipping bmshj reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.bmshj2018", model);
    let img = match decode_envelope(&env, &reg).expect("rust decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let diffs = || img.rgb.iter().zip(&reference).map(|(a, b)| (*a as i32 - *b as i32).abs());
    let maxd = diffs().max().unwrap();
    let meand = diffs().map(|d| d as f64).sum::<f64>() / reference.len() as f64;
    println!("  bmshj2018 vs CompressAI: max|Δ|={maxd}  mean|Δ|={meand:.3}");
    assert!(maxd <= 4, "bmshj2018 Rust decode diverges from CompressAI (max {maxd})");
}

/// END-TO-END validation of the checkerboard CONTEXT decoder (`context.rs`)
/// against a minimal CompressAI-compatible elic model run through the actual
/// export/encode logic. Validates the 2-pass anchor→context→non-anchor
/// orchestration + single-stream symbol order. Skipped without /tmp artifacts.
#[test]
fn elic_matches_reference() {
    let wai = Path::new("/tmp/test.elic.wai");
    let ref_rgb = Path::new("/tmp/ref_elic.rgb");
    let model = Path::new("/tmp/wai_elic/decoder.onnx");
    let dir = Path::new("/tmp/wai_elic");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("context.onnx").exists() {
        eprintln!("skipping elic reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.elic", model);
    let img = match decode_envelope(&env, &reg).expect("rust elic decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let diffs = || img.rgb.iter().zip(&reference).map(|(a, b)| (*a as i32 - *b as i32).abs());
    let maxd = diffs().max().unwrap();
    let meand = diffs().map(|d| d as f64).sum::<f64>() / reference.len() as f64;
    println!("  elic vs reference: max|Δ|={maxd}  mean|Δ|={meand:.3}");
    assert!(maxd <= 4, "elic Rust decode diverges (max {maxd}) — checkerboard orchestration wrong");
}

/// END-TO-END validation of the MLIC++ channel-autoregressive decoder
/// (`mlicpp.rs`) against a minimal CompressAI-compatible model: K channel
/// slices × checkerboard, the entropy net re-run on concat[y_so_far, hyper] as
/// context grows. Validates the slice-loop ordering. Skipped without artifacts.
#[test]
fn mlicpp_matches_reference() {
    let wai = Path::new("/tmp/test.mlic.wai");
    let ref_rgb = Path::new("/tmp/ref_mlic.rgb");
    let model = Path::new("/tmp/wai_mlic/decoder.onnx");
    let dir = Path::new("/tmp/wai_mlic");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("entropy.onnx").exists() {
        eprintln!("skipping mlicpp reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.mlicpp", model);
    let img = match decode_envelope(&env, &reg).expect("rust mlicpp decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let diffs = || img.rgb.iter().zip(&reference).map(|(a, b)| (*a as i32 - *b as i32).abs());
    let maxd = diffs().max().unwrap();
    let meand = diffs().map(|d| d as f64).sum::<f64>() / reference.len() as f64;
    println!("  mlicpp vs reference: max|Δ|={maxd}  mean|Δ|={meand:.3}");
    assert!(maxd <= 4, "mlicpp Rust decode diverges (max {maxd}) — slice orchestration wrong");
}

/// MLICv2 (current SOTA, −20% vs VTM) shares MLIC++'s multi-reference
/// channel-autoregressive decode — its gains live in the sink nets. Prove the
/// route is LIVE (not just registered): an mlicpp-format envelope relabeled
/// `wai.neural.mlicv2` decodes identically through `mlicpp::decode`.
#[test]
fn mlicv2_routes_through_mlicpp_decoder() {
    let wai = Path::new("/tmp/test.mlic.wai");
    let ref_rgb = Path::new("/tmp/ref_mlic.rgb");
    let model = Path::new("/tmp/wai_mlic/decoder.onnx");
    let dir = Path::new("/tmp/wai_mlic");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("entropy.onnx").exists() {
        eprintln!("skipping mlicv2 route: /tmp artifacts not present");
        return;
    }
    let base = Wai::read(wai).unwrap();
    let mut m = base.manifest.clone();
    m.model_requirement.capability = "wai.neural.mlicv2".into();
    let env = Wai::new(m, base.payload.clone());
    let reg = ModelRegistry::new().register("wai.neural.mlicv2", model);
    let img = match decode_envelope(&env, &reg).expect("mlicv2 decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    let maxd = img.rgb.iter().zip(&reference)
        .map(|(a, b)| (*a as i32 - *b as i32).abs()).max().unwrap();
    println!("  mlicv2 (via mlicpp route) vs reference: max|Δ|={maxd}");
    assert!(maxd <= 4, "mlicv2 route diverges (max {maxd}) — dispatch not wired");
}

/// END-TO-END validation of the SNAC multi-resolution decoder (`snac.rs`):
/// N variable-length code levels → dynamic-input ONNX (codes_0..codes_{N-1}) →
/// waveform. Validates the multi-level wire parse + dynamic dispatch against a
/// clean synthetic decoder of SNAC's interface (the real SNAC model has known
/// ONNX-export issues — noise/attention reshapes — which is a sink-side concern,
/// not this decoder's). Skipped without /tmp artifacts.
#[test]
fn snac_matches_reference() {
    let wai = Path::new("/tmp/test.snac.wai");
    let ref_f = Path::new("/tmp/ref_snac.f32");
    let model = Path::new("/tmp/wai_snac/decoder.onnx");
    if !wai.exists() || !ref_f.exists() || !model.exists() {
        eprintln!("skipping snac reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.snac", model);
    let audio = match decode_envelope(&env, &reg).expect("snac decode") {
        Decoded::Audio(a) => a,
        _ => panic!("expected audio"),
    };
    assert_eq!(audio.sample_rate, 24_000);
    let ref_bytes = std::fs::read(ref_f).unwrap();
    let reference: Vec<f32> = ref_bytes.chunks_exact(4)
        .map(|c| f32::from_le_bytes(c.try_into().unwrap())).collect();
    assert_eq!(audio.samples.len(), reference.len(), "sample count mismatch");
    let maxd = audio.samples.iter().zip(&reference)
        .map(|(a, b)| (a - b).abs()).fold(0f32, f32::max);
    println!("  snac vs reference: max|Δ|={maxd:.2e}  ({} samples, 3 levels)", audio.samples.len());
    assert!(maxd < 1e-4, "snac decode diverges (max {maxd}) — multi-level dispatch wrong");
}

/// CMIC (ICLR 2026, −15.91% vs VTM) uses the SCCTX entropy model (space-channel
/// context = channel slices + checkerboard) — the mlicpp orchestration; its
/// Mamba is in the sink transform. Prove the route is live: an mlicpp-format
/// envelope relabeled `wai.neural.cmic` decodes identically.
#[test]
fn cmic_routes_through_mlicpp_decoder() {
    let wai = Path::new("/tmp/test.mlic.wai");
    let ref_rgb = Path::new("/tmp/ref_mlic.rgb");
    let model = Path::new("/tmp/wai_mlic/decoder.onnx");
    let dir = Path::new("/tmp/wai_mlic");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("entropy.onnx").exists() {
        eprintln!("skipping cmic route: /tmp artifacts not present");
        return;
    }
    let base = Wai::read(wai).unwrap();
    let mut m = base.manifest.clone();
    m.model_requirement.capability = "wai.neural.cmic".into();
    let env = Wai::new(m, base.payload.clone());
    let reg = ModelRegistry::new().register("wai.neural.cmic", model);
    let img = match decode_envelope(&env, &reg).expect("cmic decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    let maxd = img.rgb.iter().zip(&reference)
        .map(|(a, b)| (*a as i32 - *b as i32).abs()).max().unwrap();
    println!("  cmic (via mlicpp route) vs reference: max|Δ|={maxd}");
    assert!(maxd <= 4, "cmic route diverges (max {maxd}) — dispatch not wired");
}

/// END-TO-END validation of the DCVC INTER-frame video decoder
/// (`video_dcvc.rs`): a frame loop that propagates a reference feature, decoded
/// on CPU via ort (refuting "native-sink/CUDA only"). 3 moving frames through a
/// minimal hyperprior + temporal-decoder model; the reference feature threads
/// frame→frame so frames differ even from similar latents. Skipped w/o artifacts.
#[test]
fn dcvc_matches_reference() {
    let wai = Path::new("/tmp/test.dcvc.wai");
    let ref_rgb = Path::new("/tmp/ref_dcvc.rgb");
    let dir = Path::new("/tmp/wai_dcvc");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("temporal_decoder.onnx").exists() {
        eprintln!("skipping dcvc reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.dcvc_rt", dir.join("decoder.onnx"));
    let video = match decode_envelope(&env, &reg).expect("dcvc decode") {
        Decoded::Video(v) => v,
        _ => panic!("expected video"),
    };
    assert_eq!(video.frames_rgb.len(), 3, "frame count");
    let reference = std::fs::read(ref_rgb).unwrap();
    let flat: Vec<u8> = video.frames_rgb.concat();
    assert_eq!(flat.len(), reference.len(), "total byte count");
    let maxd = flat.iter().zip(&reference)
        .map(|(a, b)| (*a as i32 - *b as i32).abs()).max().unwrap();
    // also confirm frames actually differ (temporal propagation did something)
    let f0_eq_f1 = video.frames_rgb[0] == video.frames_rgb[1];
    println!("  dcvc (3 frames, temporal propagation) vs reference: max|Δ|={maxd}  frames-differ={}", !f0_eq_f1);
    assert!(maxd <= 4, "dcvc decode diverges (max {maxd}) — temporal propagation wrong");
}

/// END-TO-END validation of the GLC CATEGORICAL decoder (`glc.rs`): codebook
/// indices via per-position softmax → CompressAI-exact pmf_to_quantized_cdf →
/// bypass-free categorical rANS, over a checkerboard. A minimal VQ model + a
/// matching categorical rANS encoder; reference = synthesis(true indices).
/// Skipped without /tmp artifacts.
#[test]
fn glc_matches_reference() {
    let wai = Path::new("/tmp/test.glc.wai");
    let ref_rgb = Path::new("/tmp/ref_glc.rgb");
    let dir = Path::new("/tmp/wai_glc");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("hyper_entropy.onnx").exists() {
        eprintln!("skipping glc reference match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.glc", dir.join("decoder.onnx"));
    let img = match decode_envelope(&env, &reg).expect("glc decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let maxd = img.rgb.iter().zip(&reference)
        .map(|(a, b)| (*a as i32 - *b as i32).abs()).max().unwrap();
    println!("  glc (categorical/VQ, 256 indices) vs reference: max|Δ|={maxd}");
    assert!(maxd <= 4, "glc decode diverges (max {maxd}) — categorical entropy wrong");
}

/// SNAC against the REAL pretrained snac_24khz model (not synthetic): exported
/// after model surgery — zero-noise (NoiseBlock's torch.randn made decode
/// stochastic; WAI needs determinism) + an export-clean snake. Validates the
/// multi-level decoder on the genuine 3-codebook hierarchy. Skipped w/o files.
#[test]
fn snac_real_model_matches_reference() {
    let wai = Path::new("/tmp/test.snac_real.wai");
    let ref_f = Path::new("/tmp/ref_snac_real.f32");
    let model = Path::new("/tmp/wai_snac_real/decoder.onnx");
    if !wai.exists() || !ref_f.exists() || !model.exists() {
        eprintln!("skipping real-snac match: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.snac", model);
    let audio = match decode_envelope(&env, &reg).expect("snac decode") {
        Decoded::Audio(a) => a,
        _ => panic!("expected audio"),
    };
    assert_eq!(audio.sample_rate, 24_000);
    let reference: Vec<f32> = std::fs::read(ref_f).unwrap()
        .chunks_exact(4).map(|c| f32::from_le_bytes(c.try_into().unwrap())).collect();
    assert_eq!(audio.samples.len(), reference.len());
    let maxd = audio.samples.iter().zip(&reference)
        .map(|(a, b)| (a - b).abs()).fold(0f32, f32::max);
    println!("  REAL snac_24khz vs torch(deterministic): max|Δ|={maxd:.2e}  ({} samples)", audio.samples.len());
    assert!(maxd < 1e-3, "real snac decode diverges (max {maxd})");
}

/// int_synth against a REAL QAT/PTQ-trained model (not the constructed unit
/// test): a float autoencoder trained on synthetic images, then quantized to
/// the integer spec with per-layer activation-calibrated shifts. Confirms the
/// Rust integer decode is BIT-IDENTICAL to the numpy integer-forward reference
/// on a trained model (the determinism guarantee, on real weights). Skipped
/// without /tmp artifacts.
#[test]
fn int_synth_trained_model_matches_integer_forward() {
    let wai = Path::new("/tmp/test.intsynth.wai");
    let ref_rgb = Path::new("/tmp/ref_intsynth.rgb");
    let dir = Path::new("/tmp/wai_intsynth");
    if !wai.exists() || !ref_rgb.exists() || !dir.join("int_synth.json").exists() {
        eprintln!("skipping trained int_synth: /tmp artifacts not present");
        return;
    }
    let env = Wai::read(wai).unwrap();
    let reg = ModelRegistry::new().register("wai.neural.int_synth", dir.join("model"));
    let img = match decode_envelope(&env, &reg).expect("int_synth decode") {
        Decoded::Image(i) => i,
        _ => panic!("expected image"),
    };
    let reference = std::fs::read(ref_rgb).unwrap();
    assert_eq!(img.rgb.len(), reference.len());
    let maxd = img.rgb.iter().zip(&reference)
        .map(|(a, b)| (*a as i32 - *b as i32).abs()).max().unwrap();
    println!("  trained int_synth: Rust vs numpy integer-forward max|Δ|={maxd} (must be 0 — integer-exact)");
    assert_eq!(maxd, 0, "Rust integer decode must be bit-identical to the reference");
}