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

//! Carriage conformance — WAI's universal job, proven for EVERY registered
//! capability: wrap a payload under the capability, write the envelope, read it
//! back, and the payload survives **byte-identically** (§2: payload = the named
//! codec's canonical bytes, carried verbatim), the envelope passes the role check
//! (a candidate fails the candidate check, SPEC §5), and the registry reports a
//! fidelity tier + a license class for it.
//!
//! This is the honest meaning of "WAI handles all of them": WAI *carries* the
//! canonical bytes and *names* the decoder — it does not re-implement the
//! codec. The payload here is opaque test bytes; that it is opaque is the
//! point — the same envelope carries a JPEG 2000 codestream, an IAMF stream, a
//! Draco buffer, or a proprietary AC-4 frame identically. Real end-to-end
//! decode of the open formats (JPEG 2000 via OpenJPEG, IAMF via ffmpeg) is
//! demonstrated in tools/wai_carriage_demo.sh.
//!
//! A companion-only capability (HDR dynamic metadata, an LCEVC enhancement) is
//! carried the only way SPEC §5 allows: as a `WAI2` companion bound to a base
//! rendition. As a `WAI1` capability it still survives the wire (parsing is
//! format-agnostic) but fails the role check. The converse holds for every
//! other registered capability: marked companion, it survives the wire and
//! fails the role check (SPEC §7.1, rule 1).
//!
//! Pure container + registry — no codec feature required, so it runs in the
//! same no-system-deps matrix as the cargo classes.

use wai::codecs::{
    capability_license, capability_media, capability_tier, is_candidate, is_companion_only,
    is_known_capability, is_refinement_only, known_capabilities, Media,
};
use wai::container::{Rendition, RoleError, WaiMulti};
use wai::{Conditioning, Manifest, ModelRequirement, Wai};

fn media_for(cap: &str) -> &'static str {
    capability_media(cap).map_or("binary", Media::label)
}

/// A representative payload for a capability — arbitrary bytes whose exact
/// reproduction through the envelope is the thing under test. Sized and seeded
/// off the capability so each class carries distinct content.
fn payload_for(cap: &str, n: usize) -> Vec<u8> {
    let seed = cap.bytes().fold(0x1234_5678u32, |a, b| a.wrapping_mul(31).wrapping_add(b as u32));
    let mut s = seed | 1;
    (0..n)
        .map(|_| {
            s ^= s << 13;
            s ^= s >> 17;
            s ^= s << 5;
            (s & 0xff) as u8
        })
        .collect()
}

fn wrap(cap: &str, payload: Vec<u8>) -> Wai {
    Wai::new(
        Manifest::new(
            media_for(cap),
            "replicate",
            ModelRequirement::new(cap).with_fallback("wai.image.png"),
            Conditioning::new("bytes"),
        ),
        payload,
    )
}

/// A refinement-only capability in the form SPEC §5 allows: a `WAI1` with `refines`
/// and no fallback (`extensions/staged-delivery.md` §3).
fn wrap_refinement(cap: &str, payload: Vec<u8>) -> Wai {
    let h = "a".repeat(64);
    let mut m = Manifest::new(media_for(cap), "replicate", ModelRequirement::new(cap), Conditioning::new("wir1"));
    m.refines = Some(serde_json::json!({"base": h, "prev": h, "layer": 1}));
    Wai::new(m, payload)
}

/// The base a companion-only capability binds to in these tests (SPEC §7.1, rule 2; SPEC §5,
/// *Base admission*): a video rendition for the descriptors and LCEVC, an image for the gain
/// map, which is a companion of an image, and one Opus packet for the two DRED enhancement
/// layers, whose one base it is.
fn base_of(cap: &str) -> (&'static str, &'static str, &'static str) {
    if wai::codecs::admits(cap, "wai.audio.opus.packet") {
        ("wai.audio.opus.packet", "audio", "opus")
    } else if cap == "wai.meta.gainmap" {
        ("wai.image.png", media_for("wai.image.png"), "png")
    } else {
        ("wai.video.hevc", "video", "hevc")
    }
}

/// A companion-only capability in the form SPEC §5 allows: a `WAI2` companion
/// bound to a base rendition of a capability it applies to (`base_of`). Returns the
/// parsed envelope.
fn wrap_companion(cap: &str, payload: Vec<u8>) -> WaiMulti {
    let (b, media, label) = base_of(cap);
    let base = payload_for(b, 64);
    let env = WaiMulti::new(media, "replicate", serde_json::Value::Null, vec![
        Rendition::media(b, label, base),
        Rendition::companion(cap, payload, b),
    ]);
    WaiMulti::from_bytes(&env.to_bytes().expect("serialize envelope")).expect("parse envelope")
}

#[test]
fn every_registered_capability_carries_bytes_byte_exact() {
    let mut n_checked = 0;
    for &cap in known_capabilities() {
        // a few payload sizes incl. 0 (empty) and a chunky one
        for &len in &[0usize, 1, 31, 4096, 65537] {
            let payload = payload_for(cap, len);
            if is_companion_only(cap) {
                let back = wrap_companion(cap, payload.clone());
                let (base, _, _) = base_of(cap);
                assert_eq!(back.check_component_roles(), Ok(()), "{cap}: companion carriage must conform");
                let bound = back.companions_of(base);
                assert_eq!(bound.len(), 1, "{cap}: companion not bound to its base");
                assert_eq!(bound[0].0.capability, cap, "{cap}: capability not preserved");
                assert_eq!(bound[0].1, payload.as_slice(), "{cap}: payload not carried byte-identically at {len} B");
                assert_eq!(back.primary(wai::container::no_parameter_sets()).unwrap().meta.capability,
                           base, "{cap}: companion was selectable");
                assert!(capability_tier(cap).is_some(), "{cap}: no fidelity tier");
                assert!(capability_license(cap).is_some(), "{cap}: no license class");
                continue;
            }
            if is_refinement_only(cap) {
                let back = Wai::from_bytes(&wrap_refinement(cap, payload.clone()).to_bytes().expect("serialize")).expect("parse");
                assert_eq!(back.check_component_roles(), Ok(()), "{cap}: refinement carriage must conform");
                assert_eq!(back.payload, payload, "{cap}: payload not carried byte-identically at {len} B");
                assert_eq!(back.refines().map(|r| r.map(|r| r.layer)), Some(Ok(1)), "{cap}: refines not preserved");
                assert!(capability_tier(cap).is_some() && capability_license(cap).is_some(), "{cap}: unclassified");
                continue;
            }
            let env = wrap(cap, payload.clone());
            let bytes = env.to_bytes().expect("serialize envelope");
            let back = Wai::from_bytes(&bytes).expect("parse envelope");
            assert_eq!(back.check_component_roles(), Ok(()), "{cap}: standalone WAI1 must conform");
            assert_eq!(back.payload, payload, "{cap}: payload not carried byte-identically at {len} B");
            assert_eq!(back.capability(), cap, "{cap}: capability not preserved");
            assert_eq!(back.fallback(), Some("wai.image.png"), "{cap}: fallback not preserved");
            // A candidate still carries byte-exact, and the candidate check reports it.
            assert_eq!(back.check_candidates().is_ok(), !is_candidate(cap), "{cap}");
            // the registry classifies it (tier + license) — what makes the
            // per-title fidelity/royalty choice auditable.
            assert!(capability_tier(cap).is_some(), "{cap}: no fidelity tier");
            assert!(capability_license(cap).is_some(), "{cap}: no license class");
        }
        n_checked += 1;
    }
    assert!(n_checked >= 50, "expected the full registry, got {n_checked}");
}

#[test]
fn dispatch_distinguishes_known_from_unknown() {
    // the floor + the immersive/cinema/volumetric/haptics classes + the
    // broadcast and streaming codecs are known
    for cap in [
        "wai.image.png", "wai.audio.iamf", "wai.image.jp2", "wai.mesh.draco",
        "wai.pc.gpcc", "wai.haptic.mihs", "wai.meta.hdr10plus", "wai.audio.ac4",
        "wai.video.av2", "wai.video.vvc", "wai.video.hevc", "wai.video.avc", "wai.video.vp9",
        "wai.video.evc", "wai.video.evc.baseline", "wai.video.avs3", "wai.video.lcevc",
        "wai.audio.mpegh", "wai.audio.avs3", "wai.audio.aac",
        "wai.video.vp8", "wai.audio.opus.packet",
    ] {
        assert!(is_known_capability(cap), "{cap} should be registered");
        let env = wrap(cap, payload_for(cap, 128));
        let back = Wai::from_bytes(&env.to_bytes().unwrap()).unwrap();
        assert_eq!(back.capability(), cap);
        // The v1.0 role check separates a standalone payload from a
        // companion-only one, which a WAI1 cannot carry conformantly.
        assert_eq!(back.check_component_roles().is_ok(), !is_companion_only(cap), "{cap}");
    }
    // an unregistered capability is still CARRIED (the envelope is
    // format-agnostic) but is NOT known — a sink returns the loud
    // missing-capability error rather than guessing.
    let env = wrap("wai.image.nope", payload_for("x", 64));
    let back = Wai::from_bytes(&env.to_bytes().unwrap()).unwrap();
    assert_eq!(back.capability(), "wai.image.nope");
    assert!(!is_known_capability(back.capability()));
}

#[test]
fn no_standalone_capability_is_carried_as_a_companion() {
    // SPEC §7.1, rule 1: every registered capability that is not companion-only
    // is standalone media. Bound as a companion to a video base it still
    // survives the wire byte-exact, and the role check reports it.
    let mut n_checked = 0;
    for &cap in known_capabilities() {
        if is_companion_only(cap) {
            continue;
        }
        let payload = payload_for(cap, 257);
        if is_refinement_only(cap) {
            // A refinement is not standalone media either: carried as a companion, the
            // role check reports it as a refinement-only capability in another role.
            let env = WaiMulti::new("video", "replicate", serde_json::Value::Null, vec![
                Rendition::media("wai.video.hevc", "hevc", payload_for("wai.video.hevc", 64)),
                Rendition::companion(cap, payload.clone(), "wai.video.hevc"),
            ]);
            let back = WaiMulti::from_bytes(&env.to_bytes().expect("serialize envelope")).expect("parse envelope");
            assert_eq!(back.check_component_roles(),
                       Err(RoleError::RefinementOnlyAsComponent { index: 1, capability: cap.into() }), "{cap}");
            continue;
        }
        let env = WaiMulti::new("video", "replicate", serde_json::Value::Null, vec![
            Rendition::media("wai.video.hevc", "hevc", payload_for("wai.video.hevc", 64)),
            Rendition::companion(cap, payload.clone(), "wai.video.hevc"),
        ]);
        let back = WaiMulti::from_bytes(&env.to_bytes().expect("serialize envelope")).expect("parse envelope");
        assert_eq!(back.companions()[0].1, payload.as_slice(), "{cap}: payload not carried byte-identically");
        assert_eq!(back.check_component_roles(),
                   Err(RoleError::StandaloneAsCompanion { index: 1, capability: cap.into() }), "{cap}");
        n_checked += 1;
    }
    assert!(n_checked >= 50, "expected the full registry, got {n_checked}");
}