Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 17 Packages Wiki Activity Actions 255
open-standards/wai/wai-rs/src/codecs/mod.rs
Transaction Science f3927f755d D2c M1 gate 3: refusal parity, int_synth's registry ops member and SPEC citations 
Refusal parity (tests/int_synth_ops.rs): one fixture for each refusal the
direct decode makes (a payload short or long, a side of 2^64 or 2^255, C*S*S
past the word, an output that is not [3, H, W], an H of 0, a first in_ch that
is not C, a set that is not JSON or has no layers, a malformed layer, a
negative, fractional or non-boolean field, a weight or bias count off by one,
a value past i32, layers that do not chain, an output side of 0). Each is
refused by both decodes, and a sink's int_payload dispatch reports it as
payload_malformed, the one code integer-payloads §13 gives. The lowered graph's
input check [-128, 127] decodes at both ends and refuses one past each with
field_range at input 0.

The registry's ops member (integer-operators §11): codecs::OpsMember and
capability_ops, Registration::ops, the export's ops member and its schema
(built in its own function: the schema literal had reached json!'s recursion
limit). wai.neural.int_synth gets {set wai-ops/1, profile acc64, subset full,
lowering int_synth/1}; a unit test pins it as the only member, on a
NeuralIntegerExact capability. registry/ regenerated by `wai registry export`.

SPEC §5's row cites integer-payloads §13 and integer-operators §13.1; SPEC §7
says a NeuralIntegerExact capability that decodes through the operator set
names it in its ops member. REGISTRY.md lists the member; CHANGELOG entry.

int_ops::PROFILE is private: as a public constant, cbindgen wrote an opaque
Profile typedef into include/wai.h.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-13 03:06:21 -04:00

2599 lines
160 KiB
Rust
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! The capability registry: every capability string SPEC §5 registers, and the
//! classes the registry gives each one (fidelity tier, licence class, replicate
//! class, role, kind, status, media).
//!
//! WAI dispatches registered standard codecs, which a sink supplies from the
//! libraries it already has, and also defines WAI-native capability classes (the
//! integer codecs, worlds, scores, films and the other extensions of SPEC §5).
//! The zeroth condition is the menu of standard capabilities: a sink with the
//! corresponding library opens the file. The standard codecs this crate decodes
//! natively are thin wrappers around their reference libraries (the `codecs`
//! feature); the registry itself needs no feature.
#[cfg(feature = "codecs")]
pub mod audio;
#[cfg(feature = "codecs")]
pub mod image;
#[cfg(feature = "codecs")]
pub mod text;
#[cfg(feature = "codecs")]
pub mod video;
// Registry-only modules, no codec dependency: the derivation operations of
// ISO/IEC 23001-16 with a determinism tier each (extensions/derived-tracks), and
// the wire forms a `Prior` may declare (extensions/prior-carriage).
pub mod derivation;
pub mod prior_form;
// The registry as one table, and its export (`wai registry export`).
pub mod registry;
// The codec glossary (wai/glossary) held to its schema and the registry. Test-only.
#[cfg(test)]
mod glossary_check;
pub use registry::{
capability_kind, capability_media, capability_role, capability_status, is_candidate,
is_dispatchable, Kind, Media, Registration, RegistrationStatus, registrations,
};
// ---- Capability strings (the values that go in manifest.model_requirement.capability)
// Image
pub const CAP_IMAGE_PNG: &str = "wai.image.png"; // universal floor
pub const CAP_IMAGE_JPEG: &str = "wai.image.jpeg"; // most-supported lossy
pub const CAP_IMAGE_AVIF: &str = "wai.image.avif"; // modern lossy (AV1-based)
pub const CAP_IMAGE_JXL: &str = "wai.image.jxl"; // JPEG-XL (lossless + lossy)
pub const CAP_IMAGE_JPEGAI: &str = "wai.image.jpegai"; // JPEG AI (ITU-T T.840.1 / ISO/IEC 6048-1:2025) standardized neural image codec. Deterministic decoder in-crate for one configuration (256×256 4:4:4, model_id 0 / tools_0, β = 0, high-operation-point synthesis; jpegai_decode::check_codestream lists the rest): codestream→RGB via jpegai_decode::decode (integer entropy and PTQ networks; dequant, post-filters and colour conversion in fixed-order IEEE-754 float; max|Δ| ≤ 2 vs the reference in its test). Without the integer weight bundle, or in a non-default floating-point environment, the float ORT decode runs; codestreams outside the configuration are refused. Model weights sink-supplied.
// Audio
pub const CAP_AUDIO_OPUS: &str = "wai.audio.opus"; // modern lossy
pub const CAP_AUDIO_FLAC: &str = "wai.audio.flac"; // lossless
// Video
pub const CAP_VIDEO_AV1: &str = "wai.video.av1"; // lossy AV1
pub const CAP_VIDEO_AV1_LOSSLESS: &str = "wai.video.av1.lossless"; // lossless AV1
pub const CAP_VIDEO_INT_MOTION: &str = "wai.video.int_motion"; // DETERMINISTIC INTEGER inter-frame codec (int_video.rs): I-frame + integer block motion-compensated P-frames + integer-quantized residual over rANS. Decoder IMPLEMENTED, pure i64, no float/ONNX — every frame is byte-identical on every machine (frame-state-equivalence; per-frame portable hash). The temporal extension of the integer contract. Payload WIV1, keyframe 0 (extensions/integer-payloads.md); the encode tools write a JSON form a converter reads
pub const CAP_VIDEO_INT_HYPER: &str = "wai.video.int_hyper"; // NEURAL-KEYFRAME inter-frame codec: the I-frame is the LEARNED integer codec int_hyper (wai.neural.int_hyper) decoded byte-exact, the P-frames are integer block-MC residuals on top (int_video::decode_pframes_typed). A learned keyframe you can put in a receipt + integer inter-frames — the whole decode integer, byte-identical everywhere. Composes int_hyper_synth + int_video; pure i64. Payload WIV1, keyframe 1, a nested WIH1 (extensions/integer-payloads.md)
// Text
pub const CAP_TEXT_ZSTD: &str = "wai.text.zstd"; // general-purpose
pub const CAP_TEXT_XZ: &str = "wai.text.xz"; // maximum classical ratio
// Neural (declared here so the dispatcher sees them; impls live at the sink).
// See SPEC.md §5 "Neural capabilities" for each model and its published operating point.
pub const CAP_NEURAL_ENCODEC32: &str = "wai.neural.encodec32"; // EnCodec, 32 kHz
pub const CAP_NEURAL_DAC: &str = "wai.neural.dac"; // DAC (improved RVQGAN, arXiv 2306.06546), 44.1 kHz
pub const CAP_NEURAL_MIMI: &str = "wai.neural.mimi"; // Mimi, real-time speech
pub const CAP_NEURAL_WAVTOKENIZER: &str = "wai.neural.wavtokenizer"; // ultra-low bitrate audio
pub const CAP_NEURAL_BMSHJ2018: &str = "wai.neural.bmshj2018"; // bmshj2018-factorized image codec (2018 baseline)
pub const CAP_NEURAL_MBT2018_MEAN: &str = "wai.neural.mbt2018_mean"; // mean-scale HYPERPRIOR image codec (Gaussian-conditional entropy) — decoder IMPLEMENTED in this crate (neural/hyperprior.rs); the conditional-entropy family: a mean-scale hyperprior conditions each latent's Gaussian; sink-supplied ONNX (hyper_synthesis + synthesis)
pub const CAP_NEURAL_INT_SYNTH: &str = "wai.neural.int_synth"; // INTEGER fixed-point synthesis (int_synth.rs): all-i64 transposed-conv decode, no float/ONNX — bit-identical on every machine BY CONSTRUCTION. The first capability that can soundly back intent=replicate cross-hardware (determinism IS integer-exact). Weights are sink-supplied (int_synth.json; the reference tools train in float, then quantise after training with calibrated per-layer shifts, tools/wai_int_synth_train.py)
pub const CAP_NEURAL_INT_HYPER: &str = "wai.neural.int_hyper"; // INTEGER fixed-point CONDITIONAL codec (int_hyper_synth.rs): the full Gaussian-conditional decode integer end-to-end — factorized rANS-decode z (z_q = s·2^afrac + median_q) → integer hyper-decoder h_s → σ,μ → integer-σ bucket (int_entropy) → integer rANS-decode residual → y_hat = r·2^afrac + μ → integer synthesis g_s. Both bitstreams entropy-coded, no raw latents; payload WIH1 (extensions/integer-payloads.md). No float/ONNX anywhere, so the WHOLE bitstream→image decode is bit-identical on every machine BY CONSTRUCTION — int_synth's sibling that adds the conditional entropy. Quality: PTQ of the pretrained mbt2018_mean (quality 6); CI (wai-sota-vectors.yml) requires the integer decode within 1 dB of the same model's float decode on a pinned test photograph — measured cost there 0.19 dB (35.985 vs 36.175 dB, arm64 macOS); image-dependent, see int_hyper_synth.rs. Tables sink-supplied
pub const CAP_NEURAL_INT_MLICPP: &str = "wai.neural.int_mlicpp"; // INTEGER MLIC++-topology codec (int_mlicpp.rs): the channel-autoregressive × checkerboard entropy model — K channel slices, each decoded as an anchor pass then a non-anchor pass, with an entropy network over concat[y decoded so far, hyper] giving σ‖μ before every pass — with every decode-side network integer (int_hyper_synth networks, int_entropy bucketing, integer rANS). The encoder and every decoder compute the same σ, so the same bucket, at any thread count: no float/ONNX anywhere, byte-identical on every machine BY CONSTRUCTION. Refuses any stream value outside the exact integer range. Payload (WIM1) and one-file model bundle (WMB1, so a prior pins every network and table) specified in int_mlicpp.rs. Conformance vector tests/vectors/int_mlicpp/ has SYNTHETIC weights (seeded, quantised like a trained model): it shows decode-equivalence, not compression quality. Model sink-supplied
pub const CAP_NEURAL_ELIC: &str = "wai.neural.elic"; // checkerboard CONTEXT-MODEL image codec (neural/context.rs) — the JPEG-AI/MLIC++ entropy class: hyperprior + 2-pass spatial context (anchor → context net → non-anchor). Decoder IMPLEMENTED; sink-supplied ONNX (hyper_synthesis + context + synthesis). WAI-native, NOT the ISO JPEG AI bitstream
pub const CAP_NEURAL_MLICPP: &str = "wai.neural.mlicpp"; // MLIC++: the multi-reference entropy model — channel-autoregressive slices + checkerboard + global attention. Decoder IMPLEMENTED (neural/mlicpp.rs): the slice/checkerboard decode orchestration; the attention nets are sink-supplied ONNX (hyper_synthesis + entropy + synthesis)
pub const CAP_NEURAL_MLICV2: &str = "wai.neural.mlicv2"; // MLICv2 / MLICv2+ (2025): a learned image codec with the SAME multi-reference channel-autoregressive decode orchestration as mlicpp — the gains are in the MetaFormer transform + enhanced entropy/global-context nets, all sink-supplied ONNX. Decoder route IMPLEMENTED (shares neural/mlicpp.rs)
pub const CAP_NEURAL_CMIC: &str = "wai.neural.cmic"; // Content-Adaptive Mamba (CMIC, ICLR 2026, arXiv 2508.02192): a state-space-model transform for learned image coding. Its entropy model is SCCTX (space-channel context = channel slices + checkerboard) = the mlicpp orchestration; the Mamba lives in the sink-supplied transform. Decoder route IMPLEMENTED (shares neural/mlicpp.rs)
pub const CAP_NEURAL_VIDEO_BMSHJ2018: &str = "wai.neural.video_bmshj2018"; // per-frame bmshj2018 video
pub const CAP_NEURAL_GLC: &str = "wai.neural.glc"; // GLC ultra-low-bpp images: CATEGORICAL/VQ entropy (codebook indices), not Gaussian. Decoder IMPLEMENTED (neural/glc.rs): per-position softmax → CompressAI-exact pmf_to_quantized_cdf → bypass-free categorical rANS over a checkerboard → VQ synthesis. Sink-supplied ONNX
pub const CAP_NEURAL_DCVC_RT: &str = "wai.neural.dcvc_rt"; // DCVC-RT (2025): real-time neural video (the paper reports 1080p and 4K real-time decode on a GPU). INTER-frame decoder IMPLEMENTED (neural/video_dcvc.rs): frame loop + reference-feature propagation, CPU-capable via ort (a GPU is needed for its real-time figures, not for the decode). Sink-supplied temporal net
pub const CAP_NEURAL_DCVC_FM: &str = "wai.neural.dcvc_fm"; // DCVC-FM (feature modulation): neural video with a wide single-model quality range, RGB+YUV. Shares the inter-frame decode orchestration (neural/video_dcvc.rs); sink-supplied temporal net
pub const CAP_NEURAL_SNAC: &str = "wai.neural.snac"; // SNAC: multi-resolution RVQ audio (hierarchical code streams, e.g. lengths [12,24,48,96]), ubiquitous in low-bitrate TTS. Decoder IMPLEMENTED (neural/snac.rs): N variable-length code levels → dynamic-input ONNX (codes_0..codes_{N-1}) → waveform; carries its own sample rate. Sink-supplied ONNX
// Perceptual / generative-semantic (the `wai.semantic.*` path): the wire
// carries an "understanding" (e.g. a CLIP embedding) and ANY conforming sink
// generator regenerates; conformance is similarity-by-threshold, never bytes.
// See `crate::semantic`. Generators are always sink-supplied.
pub const CAP_SEMANTIC_CLIP: &str = "wai.semantic.clip"; // reference perceptual profile: CLIP-embedding package, any conforming generator
pub const CAP_SEMANTIC_PERCO2: &str = "wai.semantic.perco2"; // PerCoV2 (SD3, ultra-low bpp). ⚠ paper is CC-BY-NC-SA — NON-COMMERCIAL; register only as a license-flagged optional profile, never a default
// Deterministic generative synthesis (the `wai.generate.*` path): GENERATION
// (intent=create) that is byte-exact — integer/fixed-point all the way down,
// pinned to (model, prompt, seed, steps), so the generated image is identical on
// every machine and its hash is portable (receiptable). The create-side of "conformance
// is a hash" — generation-equivalence, distinct from the similarity-only semantic path.
// Decoder IMPLEMENTED in this crate (`crate::generate`), no float/ONNX; the model is a
// small pinned bundle (integer sine LUT + draw config), NOT a sink-supplied float model.
pub const CAP_GENERATE_SPECTRAL: &str = "wai.generate.spectral"; // integer fixed-point spectral synthesis: prompt+seed → byte-exact image
// Interactive worlds (extensions/interactive-worlds). Engine behind the
// `world` feature; the capability strings are registered unconditionally —
// registration is not the same as a bundled decoder.
pub const CAP_WORLD_SCENE: &str = "wai.world.scene"; // a world at tick 0 (WWLD container, op log empty)
pub const CAP_WORLD_REPLAY: &str = "wai.world.replay"; // sealed session — re-derives every state from kilobytes
pub const CAP_WORLD_LIVE: &str = "wai.world.live"; // joinable world; ops arrive by out-of-scope transport
// GENERATIVE-world transport (world_model.rs): an interactive world-MODEL session
// carried as a signed action trace (the world CausalOp log), replaying — canonical
// total order, any arrival — to one portable session hash (replay-equivalence); the
// renderer is a declared model_id (sink-supplied, or the int_* family for byte-exact
// frames), the generated frames vouched for by a signed, joules-accounted provenance
// receipt. The neural sibling of wai.world.replay: the session is reproducible and
// metered as an action trace, whatever renderer draws it. world_model.rs
pub const CAP_WORLD_MODEL: &str = "wai.world.model";
// Asset media for worlds (and any other consumer): same zeroth-condition
// approach as the rest of §5 — dispatch to a published royalty-free standard.
// Payload is canonical glTF 2.0 Binary (.glb,
// Khronos, royalty-free): meshes, materials, textures, skeletal armatures
// in one self-contained object. Decoder is sink/library-supplied (every
// engine and DCC tool ships one); this crate treats the bytes as opaque.
pub const CAP_MESH_GLB: &str = "wai.mesh.glb";
// Volumetric / 4D temporal Gaussian splats (extensions/volumetric,
// Phase 5): a "video" of a moving Gaussian cloud. Each Gaussian carries
// keyframed tracks (position/scale/rotation/color/opacity); the sink
// interpolates the cloud at frame N in the wai.det.fixed64 floor and the
// frame's Gaussian set hashes identically on every sink
// (frame-state-equivalence). Engine behind the `splat4d` feature; the
// EWA render is the sink's. Heavy (the cloud is MB-scale) — the win is
// content-addressing + dedup + a verifiable per-frame state, NOT payload
// reduction. Distinct from wai.splat.spz (a single static cloud asset).
pub const CAP_SPLAT_4D: &str = "wai.splat.4d";
// Gaussian-splat scene asset: the same asset-path role as wai.mesh.glb,
// a different presentation representation. Payload is SPZ, an open-source
// splat interchange format that stores quantised attributes. PRESENTATION
// ONLY: a splat is bound to a node the
// sim moves; it never enters the state hash. Heavy (MB-scale) — the win
// is content-addressing + dedup + one envelope, NOT payload size.
// Decoder/renderer is sink-supplied. WAI dispatches; it does not
// rasterize Gaussians.
pub const CAP_SPLAT_SPZ: &str = "wai.splat.spz";
// LEARNED integer-exact Gaussian-splat ATTRIBUTE codec (int_splat.rs): a learned
// transform over the [14,S,S] attribute image (pos/scale/rot/color/opacity), integer
// synthesis (int_hyper machinery, 14 channels) over a factorized-rANS latent →
// byte-exact attribute tensor on every machine (splat-equivalence; a portable cloud
// hash). The int_hyper of 3D — the decoded attributes you can put in a receipt.
// Decoder IMPLEMENTED, pure i64, no float/ONNX. Payload WIS1, with each attribute's
// presentation range (extensions/integer-payloads.md); its parameter set is one file,
// the WHM1 synthesis. tools/wai_int_splat_export.py writes the model and a JSON form a
// converter reads. The float rasterizer stays sink-supplied.
pub const CAP_SPLAT_INT_CODEC: &str = "wai.splat.int_codec";
// Object-based spatial audio (extensions/spatial-audio, Phase 1). Ship
// sound OBJECTS + a scene; the sink renders to its own speaker layout.
// The audio analog of interactive-worlds — conformance is
// mixdown-equivalence (bit-exact PCM for a declared layout), the floor
// layout is stereo. Sources are content-addressed wai.audio.* objects.
// Reference mixer behind a wai-rs feature; format frozen by
// research/spatial-audio-draft.md.
pub const CAP_AUDIO_SCENE: &str = "wai.audio.scene";
// Music as instructions (extensions/score): a score of note events — the
// deepest audio lever, carrying the composition not the recording. A
// deterministic trig-free synth in the Fx floor reconstructs a canonical
// PCM mixdown (mixdown-equivalence); a soundfont/neural instrument is the
// sink's presentation. Engine behind the `score` feature.
pub const CAP_AUDIO_SCORE: &str = "wai.audio.score";
// LEARNED integer-exact audio codec (int_audio.rs): a learned 1-D transform codec
// whose SYNTHESIS is a stack of integer transposed convolutions + integer IGDN,
// decoding the per-channel factorized-rANS latent to int16 PCM byte-identically on
// every machine (sample-equivalence; a portable PCM hash). The audio analog of
// int_hyper — a neural audio codec whose reconstruction you can put in a receipt.
// Decoder IMPLEMENTED, pure i64, no float/ONNX. Payload WIA1, with its sample rate
// (extensions/integer-payloads.md); its parameter set is one file, the WAM1 synthesis.
// tools/wai_int_audio_export.py writes the model and a JSON form a converter reads.
pub const CAP_AUDIO_INT_CODEC: &str = "wai.audio.int_codec";
/// SPEC §5, *Payloads of the WAI-native integer codecs*: each capability whose payload
/// this revision pins to a format of `extensions/integer-payloads.md`, with the
/// format's magic. The one table `int_payload`, `container::check_int_payload_framing`
/// (and so `wai wrap` and `wai inspect`) and the SPEC test read. `WIV1` is pinned twice:
/// keyframe 0 for `wai.video.int_motion`, keyframe 1 for `wai.video.int_hyper`.
pub const PINNED_INT_PAYLOADS: &[(&str, [u8; 4])] = &[
(CAP_VIDEO_INT_MOTION, *b"WIV1"),
(CAP_VIDEO_INT_HYPER, *b"WIV1"),
(CAP_NEURAL_INT_HYPER, *b"WIH1"),
(CAP_AUDIO_INT_CODEC, *b"WIA1"),
(CAP_SPLAT_INT_CODEC, *b"WIS1"),
];
/// The magic of the format SPEC §5 pins `cap`'s payload to, or `None`.
pub fn pinned_int_payload(cap: &str) -> Option<[u8; 4]> {
PINNED_INT_PAYLOADS.iter().find(|(c, _)| *c == cap).map(|&(_, m)| m)
}
// Refinement capabilities (SPEC §5, *Refinement capabilities*;
// extensions/staged-delivery.md): each is **refinement-only**, a payload applied to the
// output of the stage below it, bound to that output's producer by content hash, and
// never decoded on its own. The residual form, payload WIR1 (staged-delivery §6.1).
pub const CAP_IMAGE_INT_REFINE: &str = "wai.image.int_refine";
pub const CAP_VIDEO_INT_REFINE: &str = "wai.video.int_refine";
pub const CAP_AUDIO_INT_REFINE: &str = "wai.audio.int_refine";
pub const CAP_SPLAT_INT_REFINE: &str = "wai.splat.int_refine";
/// How a capability applied to a base's output computes what it gives (SPEC §5, *Base
/// admission*).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AppliedForm {
/// A refinement-only capability of the residual form (staged-delivery §6.1): the
/// next stage is the stage below, predicted and corrected by a decoded residual.
Residual,
/// An enhancement layer (SPEC §5, *Enhancement layers*): its standard's own
/// decode over one base encode's output. Carried as a companion (SPEC §7.1).
Enhancement,
}
/// SPEC §5, *Base admission*: the one table of every capability applied to a base's
/// output, with its form and the base capabilities it applies over. A refinement-only
/// capability is admitted over a base when `refines.base` names an envelope decoded
/// through one of these (staged-delivery §4.1 step 4); an enhancement layer binds to a
/// rendition of one of them (SPEC §7.1, rule 2). Admitting another base widens a
/// capability (SPEC §8). Every admission check of the reference implementation reads
/// this table ([`admits`], [`enhancement_bases`], [`companion_applies_to`]).
///
/// cbindgen:ignore
pub static BASE_ADMISSION: &[(&str, AppliedForm, &[&str])] = &[
(CAP_IMAGE_INT_REFINE, AppliedForm::Residual,
&[CAP_NEURAL_INT_HYPER, CAP_NEURAL_INT_MLICPP, CAP_NEURAL_INT_SYNTH, CAP_IMAGE_PNG]),
(CAP_VIDEO_INT_REFINE, AppliedForm::Residual, &[CAP_VIDEO_INT_MOTION, CAP_VIDEO_INT_HYPER]),
(CAP_AUDIO_INT_REFINE, AppliedForm::Residual, &[CAP_AUDIO_INT_CODEC, CAP_AUDIO_FLAC]),
(CAP_SPLAT_INT_REFINE, AppliedForm::Residual, &[CAP_SPLAT_INT_CODEC]),
(CAP_VIDEO_LCEVC, AppliedForm::Enhancement, LCEVC_BASES),
];
/// The form of a capability applied to a base's output ([`BASE_ADMISSION`]), or `None`
/// for any other string.
pub fn applied_form(cap: &str) -> Option<AppliedForm> {
BASE_ADMISSION.iter().find(|(c, ..)| *c == cap).map(|&(_, f, _)| f)
}
/// The base capabilities `cap` applies over ([`BASE_ADMISSION`]); empty for a
/// capability not applied to a base.
pub fn admitted_bases(cap: &str) -> &'static [&'static str] {
BASE_ADMISSION.iter().find(|(c, ..)| *c == cap).map(|&(.., b)| b).unwrap_or(&[])
}
/// Whether the capability `applied` applies over a base decoded through `base`
/// (SPEC §5, *Base admission*).
pub fn admits(applied: &str, base: &str) -> bool {
admitted_bases(applied).contains(&base)
}
/// Whether a registered capability is **refinement-only** (SPEC §5, §8): a payload
/// applied, in a declared order, to the output of the stage below it, bound to that
/// output's producer by content hash (`extensions/staged-delivery.md`), and never
/// decoded on its own. Such a capability is never a `WAI1` `capability` dispatched by
/// SPEC §4 or a `fallback`, never a selectable rendition and never a companion; it is
/// carried as a `WAI1` with `refines`, or as a `WAI2` component with
/// `role: "refinement"`.
pub fn is_refinement_only(cap: &str) -> bool {
applied_form(cap) == Some(AppliedForm::Residual)
}
// Haptics (extensions/haptics): per-channel intensity/sharpness envelope,
// reconstructed to an actuator signal (sample-equivalence). Engine
// behind the `haptic` feature.
pub const CAP_HAPTIC_SIGNAL: &str = "wai.haptic.signal";
// Live state-feeds (extensions/state-feeds, Phase 3): a non-physics
// world — scoreboard, telemetry, market tape. A signed op log over the
// worlds machinery whose sim is the identity step (wai.world.sim.feed0):
// state converges to the identical hash on every sink (replay-
// equivalence), no solver. Engine behind the `world` feature. The
// broadcast profile (one authoritative publisher, many read-only sinks)
// is a deployment shape of this capability, not a separate format.
pub const CAP_FEED_STATE: &str = "wai.feed.state";
// Digital humans / avatars (extensions/avatars, Phase 4): a skeletal
// pose stream. A WWLD whose sim is wai.world.sim.skeletal0 — bones are
// nodes, an op stream sets joint transforms in wai.det.fixed64, and the
// per-bone local transforms hash identically on every sink
// (pose-equivalence). The sink skins a wai.mesh.glb by the deterministic
// pose; the skinning is presentation, never in the state hash. A
// telepresence stream is a live world of one avatar.
pub const CAP_AVATAR_POSE: &str = "wai.avatar.pose";
// Deterministic quantum-circuit SIMULATION (extensions/quantum-sim): the wire
// carries a compact gate op-log (WQC container), the sink CLASSICALLY simulates it
// in a fixed-point complex floor (Amp = i64 re/im at 2^FRAC), and the reconstructed
// statevector is byte-identical on every machine (statevector-equivalence) — a
// portable statevector hash; measurement is sampled by the pinned splitmix64
// (shot-histogram-equivalence). Clifford+T + dyadic phase P(k), so the QFT's
// controlled-phase ladder ("quantum FFT") reconstructs byte-exact. Pure i64, no
// float/ONNX — WAI's deterministic floor applied to amplitudes, the simulation
// analog of lossless (like world/score/film). Quantum HARDWARE is deliberately
// absent: NISQ noise + stochastic measurement break the determinism the standard
// rests on. Engine behind the `quantum` feature (crate::quantum). NOT a media
// codec — a way to make a quantum computation a transportable, receiptable object.
// Frozen (magic WQC1), so that existing content reproduces bit for bit: its phase
// table deviates from e^{2πi/2^k} for k ≥ 8 and applies no phase for k ≥ 19. New
// content uses wai.quantum.circuit2.
pub const CAP_QUANTUM_CIRCUIT: &str = "wai.quantum.circuit";
// The successor of wai.quantum.circuit (extensions/quantum-sim): the same WQC
// layout under magic WQC2, with a correctly rounded phase table (each component
// of every P(k) within half a unit of 2^30·e^{2πi/2^k}, so the controlled-phase
// ladder gives the QFT), a byte-canonical contract and a strict op-log. A new
// capability rather than a change to the old one, because a registered
// capability's payload format is fixed (SPEC §8): a reader that predates it
// rejects a WQC2 payload at the magic, and an envelope under this string is inert
// to it. Same equivalence, tier and replicate class as wai.quantum.circuit. Engine
// behind the `quantum` feature.
pub const CAP_QUANTUM_CIRCUIT2: &str = "wai.quantum.circuit2";
// Balanced-ternary matrix-product-state transform (extensions/ternary-tt): a
// quantum-INSPIRED (tensor-network) LOSSY compressor whose whole decode is
// integer (per-column integer scale, i64/i128), so the reconstruction is
// byte-identical on every machine (reconstruction-equivalence) — receiptable.
// Engine behind the `ternary` feature (crate::ternary). Scope: a PROVENANCE
// transform (auditable, deterministic); rate reduction is not its purpose
// (measured rate-distortion: the extension's §5). Tier = Lossy;
// determinism = WAI's deterministic floor (StandardDefined replicate class).
pub const CAP_TERNARY_TT: &str = "wai.ternary.tt";
// Neural-network coding, ISO/IEC 15938-17 ("NNC"; extensions/prior-carriage).
// wai.prior.nnc: a trained network's parameters as an NNC bitstream conforming to
// the published second edition (ISO/IEC 15938-17:2024) — the registered wire form
// a `Prior` MAY declare for the artifact its digest covers, and the capability the
// artifact travels under when it is carried at all. Decoder sink-supplied; this
// crate reads no NNC. The standard's reference software and decoder-conformance
// tests are specified by ISO/IEC 15938-18.
pub const CAP_PRIOR_NNC: &str = "wai.prior.nnc";
// wai.prior.set: the listing of a parameter set of one or more files (SPEC §3.1) —
// each file's SHA-256 and path below the set's root, one line per file, sorted by
// path. The registered prior form in which a set of several files is pinned: the
// pin covers the listing, and each line covers one file. WAI-native; reading a set
// through its listing compares digests and hands the decoder each file's bytes
// unchanged, so it is the one form the registry lists as established exact. Read
// and written by `crate::pin`.
pub const CAP_PRIOR_SET: &str = "wai.prior.set";
// wai.tensor.nnc: general tensorial data (split-inference feature maps, 3D/4D
// scene parameters) coded with NNC. A CANDIDATE (is_candidate; SPEC §5, Candidate
// capabilities): general-tensor coding is in an NNC amendment at committee-draft
// stage, so the payload format is not fixed and an encoder MUST NOT emit it until
// it is pinned to a published edition. For splat attributes, wai.splat.int_codec is the byte-exact path; this
// is an interchange form with no determinism guarantee.
pub const CAP_TENSOR_NNC: &str = "wai.tensor.nnc";
// Linear film (extensions/linear-film): a film is a sealed camera-on-rails
// world. A WFLM embeds a sealed wai.world.replay + a keyframed camera track
// (Fx floor) + a frame schedule; every sink samples the world at each frame
// tick and the interpolated camera pose, so the per-frame identity
// BLAKE3(world_state_hash(tick) || camera_pose) is bit-identical everywhere
// (film-equivalence). Composes the world's replay-equivalence; the pixels are
// the sink's. Engine behind the `film` feature.
pub const CAP_FILM_LINEAR: &str = "wai.film.linear";
// Linear-film reel (extensions/linear-film §reel): a film with cuts. A WREL
// embeds one sealed world + a sequence of shots (each its own camera track +
// frame schedule) played back to back; the editor's layer over wai.film.linear.
// Per-frame identity BLAKE3(world_state_hash(tick) || shot camera pose) is
// bit-identical everywhere (reel-equivalence). Engine behind the `film` feature.
pub const CAP_FILM_REEL: &str = "wai.film.reel";
// ---------------------------------------------------------------------------
// Immersive / object-based audio. The floor (Opus/FLAC) + audio.scene cover
// stereo and the deterministic object mix; these name the field's standard
// immersive carriers. Payload is the named standard's canonical bytes;
// decoder/renderer is sink-supplied, exactly as for jxl/av1.
// ---------------------------------------------------------------------------
// IAMF (AOMedia Immersive Audio Model and Formats) — ROYALTY-FREE, from the
// Alliance for Open Media, which also publishes AV1. NOT a codec
// but a codec-agnostic 3D-audio description that carries open codecs (Opus,
// FLAC, LPCM): channel-based (5.1.2 / 7.1.4 per ITU-R BS.2051), scene-based
// ambisonics, and binaural rendering, up to 28 input channels. Reference:
// libiamf (Apache-2.0). Payload = the canonical IAMF bitstream (opaque to WAI).
pub const CAP_AUDIO_IAMF: &str = "wai.audio.iamf";
// AC-4 (ETSI TS 103 190) — PROPRIETARY, licensed per device and per title.
// Registered as a licence-flagged optional slot (like wai.semantic.perco2) so
// content already encoded in it can ride inside a WAI envelope; never a
// default, never a floor.
pub const CAP_AUDIO_AC4: &str = "wai.audio.ac4";
// 3GPP IVAS (Immersive Voice and Audio Services, 2024; EVS-based) — the
// real-time immersive *conversational* codec (telepresence/5G). ROYALTY
// CAVEAT: EVS sits in a cellular SEP pool, so this is NOT royalty-free —
// flagged accordingly, registered for the telepresence media class.
pub const CAP_AUDIO_IVAS: &str = "wai.audio.ivas";
// ---------------------------------------------------------------------------
// Cinema mastering / intra-frame mezzanine. The theatrical interchange path.
// ---------------------------------------------------------------------------
// JPEG 2000 still (ISO/IEC 15444-1) — the Digital Cinema codestream (carried
// in SMPTE ST 429 / MXF for a DCP). Core baseline is royalty-free; reference
// is OpenJPEG (BSD-2). Lossless or visually-lossless mezzanine. NB: confirm
// the precise royalty terms before asserting them publicly.
pub const CAP_IMAGE_JP2: &str = "wai.image.jp2";
// Intra-frame JPEG 2000 video (each frame an independent J2K codestream) —
// the DCP / archival-mezzanine video path. Same OpenJPEG reference.
pub const CAP_VIDEO_J2K: &str = "wai.video.j2k";
// ---------------------------------------------------------------------------
// Volumetric / 3D geometry compression. Complements the asset capabilities
// (wai.mesh.glb, wai.splat.spz, wai.splat.4d) with the standard *compression*
// codecs the field uses; decoder is sink-supplied.
// ---------------------------------------------------------------------------
// Draco — ROYALTY-FREE (Apache-2.0) mesh + point-cloud geometry compression,
// an open-source library; glTF carries it through an extension.
pub const CAP_MESH_DRACO: &str = "wai.mesh.draco";
// MPEG G-PCC (ISO/IEC 23090-9) — geometry-based point-cloud coding for
// sparse / LiDAR-style clouds. Reference mpeg-pcc-tmc13. Patent
// considerations apply (MPEG pool) — flagged, not asserted royalty-free.
pub const CAP_PC_GPCC: &str = "wai.pc.gpcc";
// MPEG V-PCC (ISO/IEC 23090-5) — video-based point-cloud coding for dense /
// dynamic volumetric video (the offline distribution path). MPEG pool.
pub const CAP_PC_VPCC: &str = "wai.pc.vpcc";
// Gaussian-splat compression, registered (June 2026) as a CANDIDATE for the
// Self-Organizing Gaussians (SOG / SOGS) family of splat formats. No payload
// format is pinned and no specification of the format is cited, so an encoder
// MUST NOT emit it and a sink treats it as unsupported until a revision pins
// one (is_candidate; SPEC §5, Candidate capabilities). It names no MPEG work
// item: the MPEG Gaussian-splat work read for research/media-codec-registry.md
// names no such format. Would compress the wai.splat.spz / wai.splat.4d
// clouds the heavy asset path ships.
pub const CAP_SPLAT_SOG: &str = "wai.splat.sog";
// ---------------------------------------------------------------------------
// Standardized haptics codec (complements the native wai.haptic.signal).
// ---------------------------------------------------------------------------
// MPEG-I Haptics (ISO/IEC 23090-31, published Jan 2025) — unified
// vibrotactile + kinesthetic encoding for XR / gaming / teleoperation.
// Human-readable HJIF (JSON) + a binary MIHS stream (~8–16 kbps). ISO/IEC
// 23090-33 defines bit-exact decoder verification + valid/invalid conformance
// datasets — the conformance-vector philosophy already in the standard.
pub const CAP_HAPTIC_MIHS: &str = "wai.haptic.mihs";
// ---------------------------------------------------------------------------
// HDR dynamic-metadata DESCRIPTORS. These are NOT standalone media payloads —
// they are color/dynamic-range metadata that accompanies a video payload (in
// SEI / SMPTE ST 2094). Registered as companion descriptors a manifest can
// declare alongside a video capability so a sink routes/tone-maps correctly;
// the video bytes stay the video capability's. The companion-payload binding
// is the multi-component envelope's job (see the registry roadmap).
// ---------------------------------------------------------------------------
// HDR10+ dynamic metadata (SMPTE ST 2094-40) — ROYALTY-FREE for content and
// devices (only a logo is licensed).
pub const CAP_META_HDR10PLUS: &str = "wai.meta.hdr10plus";
// SMPTE ST 2094-10 dynamic metadata (the RPU form) — PROPRIETARY, a
// licence-flagged slot. The capability string is a functional identifier.
pub const CAP_META_DOVI: &str = "wai.meta.dovi";
// ---------------------------------------------------------------------------
// Broadcast and streaming video / audio codecs: the elementary bitstreams that
// terrestrial and satellite broadcast, streaming and device playback carry, so
// a WAI envelope can name them. Every one is SINK-SUPPLIED — this crate bundles
// no decoder for any of them — and none is in the mandatory floor, the
// recommended set or sink_capabilities(). Payload = the named standard's
// canonical elementary bitstream in the framing stated per entry (SPEC §5,
// "Broadcast and streaming codecs"). Licence classes live in
// capability_license(); sources in research/media-codec-registry.md.
// ---------------------------------------------------------------------------
// AV2 (AOMedia; AV2 Bitstream & Decoding Process Specification v1.0.0, 28 May
// 2026) — ROYALTY-FREE (AOMedia Patent License 1.0, shipped with the AVM
// v1.0.0 reference software). Payload: the length-delimited bitstream of the
// AV2 specification's Annex B (every OBU preceded by its leb128 byte length) —
// AV2 OBUs carry no size of their own, and Annex B is the one framing the
// specification itself defines. Registered, not recommended: a reference
// decoder exists, deployable decode (a production decoder, shipping hardware)
// is not yet confirmed. See SPEC §5 for the placement rule.
pub const CAP_VIDEO_AV2: &str = "wai.video.av2";
// VVC / H.266 (ITU-T H.266 | ISO/IEC 23090-3) — PATENT POOL. Payload: the
// Annex B byte stream (start-code-delimited NAL units, parameter sets in-band).
pub const CAP_VIDEO_VVC: &str = "wai.video.vvc";
// HEVC / H.265 (ITU-T H.265 | ISO/IEC 23008-2) — PATENT POOL. Payload: the
// Annex B byte stream.
pub const CAP_VIDEO_HEVC: &str = "wai.video.hevc";
// AVC / H.264 (ITU-T H.264 | ISO/IEC 14496-10) — PATENT POOL. Payload: the
// Annex B byte stream.
pub const CAP_VIDEO_AVC: &str = "wai.video.avc";
// VP9 (VP9 Bitstream & Decoding Process Specification) — ROYALTY-FREE (BSD
// source + the WebM project's patent grant). VP9 frames are not
// self-delimiting, so the payload is the IVF frame container (FourCC "VP90"):
// a 32-byte file header, then a 12-byte header before each frame.
pub const CAP_VIDEO_VP9: &str = "wai.video.vp9";
// EVC (MPEG-5 Part 1, ISO/IEC 23094-1), ANY profile — PATENT POOL: the Main
// profile's coding tools are licensed by their holders on FRAND terms, so a
// decoder for this capability needs that licence. Payload: the raw bitstream
// file storage format of ISO/IEC 23094-1 Annex B.
pub const CAP_VIDEO_EVC: &str = "wai.video.evc";
// EVC constrained to the BASELINE profile — ROYALTY-FREE by design (its tools
// are more than 20 years old or were offered royalty-free). No formal
// guarantee; the residual caveat is recorded in the research doc, as for JPEG
// 2000 Part 1. Same payload framing as wai.video.evc, Baseline-conformant only
// (the relation wai.video.av1.lossless has to wai.video.av1).
pub const CAP_VIDEO_EVC_BASELINE: &str = "wai.video.evc.baseline";
// AVS3 video (AVS3-P2: T/AI 109.2-2021; IEEE 1857.10) — PATENT POOL (the AVS
// patent pool; RAND, fees on devices). Payload: the AVS3-P2 video elementary
// bitstream as T/AI 109.2 defines it.
pub const CAP_VIDEO_AVS3: &str = "wai.video.avs3";
// LCEVC (MPEG-5 Part 2, ISO/IEC 23094-2) — PATENT POOL (SEP licence, royalty
// on devices and on distribution services). NOT a standalone codec: an
// ENHANCEMENT LAYER whose residuals are added to the upscaled output of one
// specific base encode (AVC, HEVC, VVC, EVC, VP9, AV1). Two carriages:
// - embedded: the enhancement rides inside the base bitstream (SEI /
// registered user data); the payload is the base codec's bytes, under the
// base capability, and no separate component exists;
// - separate: payload = the LCEVC enhancement in the byte-stream form of
// ISO/IEC 23094-2 Annex B (a 0x000001 start code prefix before every NAL
// unit), carried ONLY as a WAI2 companion (SPEC §7.1) whose companion_of
// resolves to EXACTLY ONE selectable video rendition — the base it was
// encoded against. See is_companion_only / is_enhancement_layer.
// 23094-2 admits two bitstream forms, a NAL unit stream or a byte stream
// (definition 3.2); only the byte stream delimits itself, so it is the pin.
// A bare or length-prefixed NAL unit stream is NOT this capability.
pub const CAP_VIDEO_LCEVC: &str = "wai.video.lcevc";
// MPEG-H 3D Audio (ISO/IEC 23008-3) — PATENT POOL. Channel, object and
// scene-based (HOA) next-generation audio. Payload: the MHAS packet stream
// (MPEG-H 3D Audio Stream, ISO/IEC 23008-3), the self-synchronising form
// broadcast carriage uses.
pub const CAP_AUDIO_MPEGH: &str = "wai.audio.mpegh";
// AVS3 audio / Audio Vivid (AVS3-P3: T/AI 109.3-2023; GY/T 363-2023; the
// 3D-audio national standard GB/T 46271-2025) — PATENT POOL (the AVS patent
// pool). Immersive audio with lossy and lossless modes. Payload: the AVS3-P3
// audio elementary bitstream as T/AI 109.3 defines it.
pub const CAP_AUDIO_AVS3: &str = "wai.audio.avs3";
// AAC family (ISO/IEC 14496-3: AAC-LC, HE-AAC, HE-AAC v2) — PATENT POOL.
// Payload: an ADTS stream (ISO/IEC 13818-7 / 14496-3), the self-synchronising
// elementary form. Extended HE-AAC (USAC) is NOT this capability — ADTS
// cannot carry it.
pub const CAP_AUDIO_AAC: &str = "wai.audio.aac";
/// Returns the set of capabilities this sink (the WAI Rust crate)
/// supports natively. A wrapping application is free to advertise
/// additional neural capabilities backed by its own ML runtime.
pub fn sink_capabilities() -> &'static [&'static str] {
&[
CAP_IMAGE_PNG,
CAP_IMAGE_JPEG,
CAP_IMAGE_AVIF,
CAP_IMAGE_JXL,
CAP_AUDIO_OPUS,
CAP_AUDIO_FLAC,
CAP_VIDEO_AV1,
CAP_VIDEO_AV1_LOSSLESS,
CAP_TEXT_ZSTD,
CAP_TEXT_XZ,
]
}
/// Every capability string WAI recognizes — floor, modern, and neural —
/// including ones whose decoder is **sink-supplied** rather than bundled here
/// (`wai.image.jpegai`, `wai.neural.{mlicpp,glc,dcvc_rt}`). Registration is not
/// the same as a bundled decoder: this names what a conformant WAI file may
/// declare. Use [`sink_capabilities`] for the subset this crate decodes
/// natively with no external model.
pub fn known_capabilities() -> &'static [&'static str] {
&[
// floor + modern (zeroth condition)
CAP_IMAGE_PNG, CAP_IMAGE_JPEG, CAP_IMAGE_AVIF, CAP_IMAGE_JXL, CAP_IMAGE_JPEGAI,
CAP_AUDIO_OPUS, CAP_AUDIO_FLAC,
CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS, CAP_VIDEO_INT_MOTION, CAP_VIDEO_INT_HYPER,
CAP_TEXT_ZSTD, CAP_TEXT_XZ,
// neural (sink-supplied models)
CAP_NEURAL_ENCODEC32, CAP_NEURAL_DAC, CAP_NEURAL_MIMI, CAP_NEURAL_WAVTOKENIZER,
CAP_NEURAL_SNAC,
CAP_NEURAL_BMSHJ2018, CAP_NEURAL_MBT2018_MEAN, CAP_NEURAL_INT_SYNTH, CAP_NEURAL_INT_HYPER,
CAP_NEURAL_INT_MLICPP,
CAP_NEURAL_ELIC, CAP_NEURAL_MLICPP, CAP_NEURAL_MLICV2, CAP_NEURAL_CMIC,
CAP_NEURAL_VIDEO_BMSHJ2018,
CAP_NEURAL_GLC, CAP_NEURAL_DCVC_RT, CAP_NEURAL_DCVC_FM,
// perceptual / generative-semantic
CAP_SEMANTIC_CLIP, CAP_SEMANTIC_PERCO2,
// learned integer-exact audio codec (byte-exact PCM) + splat codec (byte-exact attrs)
CAP_AUDIO_INT_CODEC, CAP_SPLAT_INT_CODEC,
// deterministic generative (byte-exact, intent=create)
CAP_GENERATE_SPECTRAL,
// interactive worlds + asset media (engine behind the `world` feature)
CAP_WORLD_SCENE, CAP_WORLD_REPLAY, CAP_WORLD_LIVE, CAP_WORLD_MODEL,
CAP_MESH_GLB, CAP_SPLAT_SPZ, CAP_AUDIO_SCENE, CAP_AUDIO_SCORE, CAP_HAPTIC_SIGNAL, CAP_FEED_STATE,
CAP_AVATAR_POSE, CAP_SPLAT_4D, CAP_FILM_LINEAR, CAP_FILM_REEL,
// deterministic quantum-circuit simulation (byte-exact statevector)
CAP_QUANTUM_CIRCUIT, CAP_QUANTUM_CIRCUIT2,
// quantum-inspired ternary-MPS transform (byte-exact recon, lossy)
CAP_TERNARY_TT,
// neural-network coding: the prior artifact form + the general-tensor candidate
CAP_PRIOR_NNC, CAP_TENSOR_NNC,
// the listing of a parameter set: the form a pin over several files takes
CAP_PRIOR_SET,
// immersive audio (IAMF royalty-free; AC-4 / IVAS license-flagged)
CAP_AUDIO_IAMF, CAP_AUDIO_AC4, CAP_AUDIO_IVAS,
// cinema mastering (JPEG 2000 / DCP)
CAP_IMAGE_JP2, CAP_VIDEO_J2K,
// volumetric / 3D geometry compression
CAP_MESH_DRACO, CAP_PC_GPCC, CAP_PC_VPCC, CAP_SPLAT_SOG,
// standardized haptics
CAP_HAPTIC_MIHS,
// HDR dynamic-metadata descriptors (companion to a video payload)
CAP_META_HDR10PLUS, CAP_META_DOVI,
// broadcast and streaming video (sink-supplied; none is a default)
CAP_VIDEO_AV2, CAP_VIDEO_VVC, CAP_VIDEO_HEVC, CAP_VIDEO_AVC, CAP_VIDEO_VP9,
CAP_VIDEO_EVC, CAP_VIDEO_EVC_BASELINE, CAP_VIDEO_AVS3,
// enhancement layer (companion-only, bound to one base video rendition)
CAP_VIDEO_LCEVC,
// broadcast and streaming audio (sink-supplied; none is a default)
CAP_AUDIO_MPEGH, CAP_AUDIO_AVS3, CAP_AUDIO_AAC,
// refinement-only: residual refinements of an integer or lossless base
CAP_IMAGE_INT_REFINE, CAP_VIDEO_INT_REFINE, CAP_AUDIO_INT_REFINE, CAP_SPLAT_INT_REFINE,
]
}
/// SPEC §5 "Mandatory floor": every conforming sink MUST implement these.
pub fn mandatory_floor() -> &'static [&'static str] {
&[CAP_IMAGE_PNG, CAP_AUDIO_FLAC, CAP_TEXT_ZSTD]
}
/// SPEC §5 "Recommended modern set": every conforming sink SHOULD implement
/// these. Together with [`mandatory_floor`] these are the capabilities WAI
/// makes defaults; every one is royalty-free (a test enforces it).
pub fn recommended_set() -> &'static [&'static str] {
&[
CAP_IMAGE_JXL, CAP_IMAGE_AVIF, CAP_IMAGE_JPEG,
CAP_AUDIO_OPUS,
CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS,
CAP_TEXT_XZ,
]
}
/// Whether `cap` is a capability WAI recognizes (see [`known_capabilities`]).
pub fn is_known_capability(cap: &str) -> bool {
known_capabilities().contains(&cap)
}
/// Whether a registered capability is **companion-only**: its payload has no
/// meaning on its own and is only ever applied *with* a base payload, never
/// selected instead of one (SPEC §7.1). HDR dynamic metadata describes a video
/// payload; an LCEVC enhancement adds residuals to one. Such a capability is
/// never dispatched standalone — not as a v1.0 `capability` or `fallback`, not
/// as a v1.1 selectable rendition — only as a v1.1 companion. The converse
/// holds too: no other registered capability is ever a companion (SPEC §7.1, rule
/// 1). Every other payload capability is standalone media; a refinement-only
/// capability is a layer; and a record or a derivation names no payload format, so
/// it is no `WAI2` component in any role.
pub fn is_companion_only(cap: &str) -> bool {
matches!(cap, CAP_META_HDR10PLUS | CAP_META_DOVI | CAP_VIDEO_LCEVC)
}
/// Whether a registered capability is an **enhancement layer**: a companion
/// whose payload was encoded against one specific base encode, so it binds to
/// exactly one selectable rendition of one of its [`enhancement_bases`], never
/// to "every rendition of that codec" (SPEC §5, §7.1). Every enhancement layer
/// is also companion-only. Read from [`BASE_ADMISSION`]: the capabilities applied
/// to a base as an enhancement.
pub fn is_enhancement_layer(cap: &str) -> bool {
applied_form(cap) == Some(AppliedForm::Enhancement)
}
/// The base codecs WAI registers `wai.video.lcevc` over (SPEC §5): AVC, HEVC,
/// VVC, EVC, VP9 and AV1, each under every capability that names its bitstream
/// — the EVC Baseline entry is an EVC bitstream and the lossless AV1 entry an
/// AV1 bitstream. Not AV2, AVS3, JPEG 2000 or the WAI-native integer codecs.
///
/// The list is this registration's, not a limit of the LCEVC standard:
/// ISO/IEC 23094-2:2021 takes its decoded base picture from "a base decoder"
/// (definition 3.17) and names no base codec among its normative references
/// (clause 2). Adding a base widens what the enhancement layer applies to, which
/// a MINOR revision may do; removing one narrows it, which needs a new MAJOR
/// (SPEC §8).
const LCEVC_BASES: &[&str] = &[
CAP_VIDEO_AVC, CAP_VIDEO_HEVC, CAP_VIDEO_VVC, CAP_VIDEO_EVC, CAP_VIDEO_EVC_BASELINE,
CAP_VIDEO_VP9, CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS,
];
/// The capabilities an enhancement layer may be bound to: the base codecs its
/// registration names (SPEC §5), which for LCEVC are WAI's choice rather than a
/// restriction of its standard, read from [`BASE_ADMISSION`]. Empty for a
/// capability that is not an enhancement layer.
pub fn enhancement_bases(cap: &str) -> &'static [&'static str] {
if applied_form(cap) == Some(AppliedForm::Enhancement) { admitted_bases(cap) } else { &[] }
}
/// The registered capabilities outside the `wai.video.*` namespace whose payload
/// is video: the neural video codecs SPEC §5 lists under *Video:* (the `video`
/// media class, in its sink-architecture note), and the films of the
/// linear-film extension, which gives a linear film's `media` the value
/// `"video"` (a reel is a film with cuts).
const VIDEO_CLASS_OUTSIDE_NAMESPACE: &[&str] = &[
CAP_NEURAL_VIDEO_BMSHJ2018, CAP_NEURAL_DCVC_RT, CAP_NEURAL_DCVC_FM,
CAP_FILM_LINEAR, CAP_FILM_REEL,
];
/// Whether a registered capability's payload is video — the `video` media
/// class of SPEC §3, as the capability's registration places it (the
/// manifest's `media` field is informational; the capability is
/// authoritative):
///
/// - every registered `wai.video.*` capability that is neither companion-only nor
/// refinement-only;
/// - the neural video codecs `wai.neural.video_bmshj2018`, `wai.neural.dcvc_rt`
/// and `wai.neural.dcvc_fm`;
/// - the films `wai.film.linear` and `wai.film.reel`.
///
/// False for a capability this revision does not register: its class is not
/// known here. A video capability a later revision registers joins the class
/// in that revision.
pub fn is_video_class(cap: &str) -> bool {
is_known_capability(cap)
&& ((cap.starts_with("wai.video.") && !is_companion_only(cap) && !is_refinement_only(cap))
|| VIDEO_CLASS_OUTSIDE_NAMESPACE.contains(&cap))
}
/// Whether a companion of capability `companion` may be applied to a rendition
/// of capability `base` — SPEC §7.1, rule 2:
///
/// - an HDR dynamic-metadata descriptor (`wai.meta.hdr10plus`,
/// `wai.meta.dovi`) was registered as a companion to a video payload, so a
/// registered `base` is one in the `video` media class ([`is_video_class`]):
/// a `wai.video.*` capability that is not itself companion-only, a neural
/// video codec, or a film. A `base` this revision does not register is not
/// constrained — its class is not known here, and a sink that does not
/// recognise it cannot present it — so a video capability a later revision
/// registers, in any namespace, is already a base older checkers accept. A
/// later revision that registers such a base outside the video class makes
/// that binding non-conforming, as SPEC §8 allows a new registration to;
/// - an enhancement layer applies to one of its [`enhancement_bases`] only.
///
/// False for every other `companion`: a standalone capability is never a
/// companion (rule 1), and for a capability this revision does not register the
/// registry knows no bases — [`crate::container::WaiMulti::check_component_roles`]
/// checks such a companion only for a present base (rule 3). No companion
/// applies to a companion-only or a refinement-only `base`.
pub fn companion_applies_to(companion: &str, base: &str) -> bool {
if is_companion_only(base) || is_refinement_only(base) {
return false;
}
match companion {
CAP_META_HDR10PLUS | CAP_META_DOVI => !is_known_capability(base) || is_video_class(base),
c if is_enhancement_layer(c) => enhancement_bases(c).contains(&base),
_ => false,
}
}
/// The fidelity a capability delivers — the honest answer to "what do I get
/// back?". This is *independent* of the determinism contract
/// ([`crate::container::DeterminismClass`], about cross-hardware
/// reproducibility) and of `intent`: a capability can be perfectly
/// reproducible yet still lossy. The tier reflects the codec's **primary role**
/// in the WAI menu; for dual-mode codecs (JXL, AVIF) the actual fidelity is
/// carried in the bitstream, so this is the ceiling, not a per-file guarantee.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FidelityTier {
/// Reproduces the exact original bytes/samples/pixels: the reconstruction is
/// the source. What `intent=replicate` promises across sinks is a separate
/// axis, the capability's [`ReplicateClass`].
Lossless,
/// Deterministic approximation — fixed given the bitstream, but not the
/// original. Conventional lossy + lossy neural codecs (incl. WavTokenizer,
/// which is acoustic-token lossy, NOT bit-exact).
Lossy,
/// Regenerated by a sink generator; conforms by similarity, not bytes; the
/// output legitimately varies by generator. The `wai.semantic.*` path.
Perceptual,
}
/// The [`FidelityTier`] of a registered capability, or `None` if unknown.
pub fn capability_tier(cap: &str) -> Option<FidelityTier> {
use FidelityTier::*;
let tier = match cap {
// NNC: lossy by primary role (compression by parameter reduction and
// quantisation), as AVIF is. The published standard also has integer and
// raw-float payload types that carry values unquantised, so an NNC
// artifact can reproduce its source; whether every conforming decoder
// reconstructs the same values is open (extensions/prior-carriage.md §5).
CAP_PRIOR_NNC | CAP_TENSOR_NNC => Lossy,
// Guaranteed / ceiling-lossless.
CAP_IMAGE_PNG | CAP_IMAGE_JXL | CAP_AUDIO_FLAC | CAP_VIDEO_AV1_LOSSLESS
| CAP_TEXT_ZSTD | CAP_TEXT_XZ
// JPEG 2000 cinema mezzanine (lossless/visually-lossless ceiling);
// Draco mesh geometry (exact-geometry ceiling, like wai.mesh.glb);
// IAMF (carries lossless codecs — FLAC/LPCM — so lossless ceiling);
// HDR dynamic metadata reproduces exactly (it IS the descriptor bytes).
| CAP_IMAGE_JP2 | CAP_VIDEO_J2K | CAP_MESH_DRACO | CAP_AUDIO_IAMF
| CAP_META_HDR10PLUS | CAP_META_DOVI
// A parameter-set listing is its own output, byte for byte.
| CAP_PRIOR_SET => Lossless,
// Interactive worlds: replay-equivalence is EXACT state
// reproduction (identical BLAKE3 state hash at every checkpoint,
// no tolerance parameter) — the simulation analog of lossless.
// wai.mesh.glb is canonical-byte pass-through of the .glb.
// wai.film.linear is film-equivalence: the per-frame (world state,
// camera pose) identity reproduces exactly on every sink — the
// simulation analog of lossless, like the world it is built on.
// wai.generate.spectral is generation-equivalence: a deterministic integer
// generator reproduces the GENERATED image byte-for-byte from its pin — the
// generative analog of lossless (byte-exact, just of created not captured content).
// wai.quantum.circuit and wai.quantum.circuit2 are statevector-equivalence:
// the reconstructed fixed-point statevector is byte-identical on every
// machine — the simulation analog of lossless, like world replay (it IS a
// fixed-point approximation of the ideal unitary evolution, but its
// reconstruction is exact and portable; the honest note lives in the
// extension's §Fidelity).
CAP_WORLD_SCENE | CAP_WORLD_REPLAY | CAP_WORLD_LIVE | CAP_WORLD_MODEL | CAP_MESH_GLB | CAP_AUDIO_SCENE | CAP_AUDIO_SCORE | CAP_HAPTIC_SIGNAL | CAP_FEED_STATE | CAP_AVATAR_POSE | CAP_FILM_LINEAR | CAP_FILM_REEL | CAP_GENERATE_SPECTRAL | CAP_QUANTUM_CIRCUIT | CAP_QUANTUM_CIRCUIT2 => Lossless,
// Splat delivery is byte-exact and the temporal reconstruction is
// frame-state-exact; the splat representation itself approximates a
// scene, so the honest tier matches the captured medium, not the
// (exact) reconstruction — the same call as the static splat.
CAP_SPLAT_SPZ | CAP_SPLAT_4D => Lossy,
// Lossy: conventional + every lossy neural codec.
CAP_IMAGE_JPEG | CAP_IMAGE_AVIF | CAP_IMAGE_JPEGAI | CAP_AUDIO_OPUS | CAP_VIDEO_AV1
| CAP_NEURAL_ENCODEC32 | CAP_NEURAL_DAC | CAP_NEURAL_MIMI | CAP_NEURAL_WAVTOKENIZER
| CAP_NEURAL_SNAC | CAP_NEURAL_BMSHJ2018 | CAP_NEURAL_MBT2018_MEAN | CAP_NEURAL_INT_SYNTH
| CAP_NEURAL_INT_HYPER | CAP_NEURAL_INT_MLICPP
| CAP_NEURAL_ELIC | CAP_NEURAL_MLICPP | CAP_NEURAL_MLICV2 | CAP_NEURAL_CMIC
| CAP_NEURAL_VIDEO_BMSHJ2018 | CAP_NEURAL_GLC | CAP_NEURAL_DCVC_RT
| CAP_NEURAL_DCVC_FM
// immersive audio (AC-4 / IVAS are perceptual lossy); point-cloud
// compression (G-PCC / V-PCC) and Gaussian-splat compression (SOG)
// approximate the captured geometry; MIHS is a lossy haptic codec.
| CAP_AUDIO_AC4 | CAP_AUDIO_IVAS | CAP_PC_GPCC | CAP_PC_VPCC
// int_motion quantizes the residual (lossy vs source), but its decode is
// byte-exact (frame-state-equivalence) — the StandardDefined replicate class.
// int_codec quantizes the latent (lossy vs source) but decodes byte-exact.
| CAP_SPLAT_SOG | CAP_HAPTIC_MIHS | CAP_VIDEO_INT_MOTION | CAP_VIDEO_INT_HYPER
| CAP_AUDIO_INT_CODEC | CAP_SPLAT_INT_CODEC
// ternary-MPS quantizes the transform to trits (lossy vs source) but its
// decode is integer/byte-exact (reconstruction-equivalence) — the
// StandardDefined replicate class, the deterministic floor, like quantum.
| CAP_TERNARY_TT
// Broadcast and streaming codecs, tiered by their primary role in the
// menu (lossy distribution). Several have lossless modes (HEVC/VVC
// lossless coding, AVS3-P3 lossless audio) — as for AVIF, the bitstream
// carries the actual fidelity; the tier is the role, not a per-file
// guarantee. LCEVC is lossy residual enhancement of a lossy base.
| CAP_VIDEO_AV2 | CAP_VIDEO_VVC | CAP_VIDEO_HEVC | CAP_VIDEO_AVC | CAP_VIDEO_VP9
| CAP_VIDEO_EVC | CAP_VIDEO_EVC_BASELINE | CAP_VIDEO_AVS3 | CAP_VIDEO_LCEVC
| CAP_AUDIO_MPEGH | CAP_AUDIO_AVS3 | CAP_AUDIO_AAC
// A residual refinement quantises its residual by its step q: lossy against
// its target, whatever its base; its decode is exact given the stage below.
| CAP_IMAGE_INT_REFINE | CAP_VIDEO_INT_REFINE | CAP_AUDIO_INT_REFINE | CAP_SPLAT_INT_REFINE => Lossy,
// Generative / similarity-conformant.
CAP_SEMANTIC_CLIP | CAP_SEMANTIC_PERCO2 => Perceptual,
_ => return None,
};
Some(tier)
}
/// IP / royalty status of *implementing* a registered capability. A property of
/// the **capability**, looked up in the registry — NOT a per-file manifest
/// claim (a codec's license can't be honestly asserted in an envelope's
/// header). Tooling uses it to audit a title or a whole library: "use only
/// royalty-free capabilities", or "flag every pool/proprietary capability in
/// this catalog", in code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LicenseClass {
/// No royalty or patent fee to implement: an open standard or an open
/// reference under a permissive licence (the AOMedia / JPEG / IETF /
/// Khronos lineage, the WAI-native classes, the open neural references).
RoyaltyFree,
/// Implementing requires a patent-pool / SEP licence (royalties apply).
PatentPool,
/// Single-vendor proprietary licence.
Proprietary,
/// Licence forbids commercial use.
NonCommercial,
}
/// The [`LicenseClass`] of a registered capability, or `None` if unknown.
/// Verified against primary sources (June 2026 for the immersive / cinema /
/// volumetric / haptics / HDR rows, September 2026 for the broadcast and
/// streaming codecs); the residual caveats (JPEG 2000 extensions / submarine
/// patents, MPEG-I Haptics pool status unconfirmed, EVC Baseline's
/// by-design royalty-free status, third-party pool assertions against the
/// AOMedia and VP9 formats) are documented in `research/media-codec-registry.md`.
///
/// The classification is **exhaustive, with no default class**: every
/// registered capability is listed under exactly one arm, and a capability
/// that is registered but listed nowhere returns `None` — which the registry
/// tests reject. A newly registered codec therefore cannot become
/// "royalty-free" by omission.
pub fn capability_license(cap: &str) -> Option<LicenseClass> {
use LicenseClass::*;
if !is_known_capability(cap) {
return None;
}
Some(match cap {
// NNC: royalty status not established — ISO/IEC 15938-17:2022 records a
// patent claimed essential under a RAND assurance, an open implementation
// is licensed with no patent rights granted, and no royalty-free
// commitment was found. Classified conservatively, as MPEG-I Haptics is.
CAP_PRIOR_NNC | CAP_TENSOR_NNC => PatentPool,
// wai.splat.sog: a candidate with no pinned payload format, so the
// licensing of whatever format is pinned is not established.
// Classified conservatively and provisionally (SPEC §5, Licence classes).
CAP_SPLAT_SOG => PatentPool,
// Single-licensor proprietary: AC-4 and ST 2094-10 dynamic metadata.
CAP_AUDIO_AC4 | CAP_META_DOVI => Proprietary,
// Patent-pool / SEP royalties: IVAS (a voice-codec pool, with EVS); MPEG
// point clouds (G-PCC/V-PCC: classified conservatively, as MIHS is, see
// research/media-codec-registry.md); MPEG-I Haptics (ISO patent
// declarations apply — pool status unconfirmed, classified
// conservatively).
CAP_AUDIO_IVAS | CAP_PC_GPCC | CAP_PC_VPCC | CAP_HAPTIC_MIHS => PatentPool,
// Broadcast and streaming codecs whose essential patents are licensed
// for royalties — through pools, a single SEP licensor, or FRAND
// holders (September 2026): VVC, HEVC and AVC (several pools plus
// bilateral licensors); EVC Main-profile tools (FRAND holders); LCEVC
// (SEP licence with device and distribution royalties); AVS3 video and
// audio (the AVS patent pool, RAND, fees on devices); MPEG-H 3D Audio
// and AAC (pool programmes).
CAP_VIDEO_VVC | CAP_VIDEO_HEVC | CAP_VIDEO_AVC | CAP_VIDEO_EVC | CAP_VIDEO_LCEVC
| CAP_VIDEO_AVS3 | CAP_AUDIO_MPEGH | CAP_AUDIO_AVS3 | CAP_AUDIO_AAC => PatentPool,
// Non-commercial model licence (PerCoV2 is CC-BY-NC-SA).
CAP_SEMANTIC_PERCO2 => NonCommercial,
// Royalty-free — listed explicitly, never a fall-through.
// Floor + modern menu: open standards and open references.
CAP_IMAGE_PNG | CAP_IMAGE_JPEG | CAP_IMAGE_AVIF | CAP_IMAGE_JXL
| CAP_AUDIO_OPUS | CAP_AUDIO_FLAC
| CAP_VIDEO_AV1 | CAP_VIDEO_AV1_LOSSLESS
| CAP_TEXT_ZSTD | CAP_TEXT_XZ
// JPEG AI and the neural / semantic / generative capabilities. This is
// the classification the registry already gave them (by fall-through);
// it was made explicit here, not re-verified — model-weight licences
// are an open item in research/media-codec-registry.md.
| CAP_IMAGE_JPEGAI
| CAP_NEURAL_ENCODEC32 | CAP_NEURAL_DAC | CAP_NEURAL_MIMI | CAP_NEURAL_WAVTOKENIZER
| CAP_NEURAL_SNAC
| CAP_NEURAL_BMSHJ2018 | CAP_NEURAL_MBT2018_MEAN | CAP_NEURAL_INT_SYNTH | CAP_NEURAL_INT_HYPER
| CAP_NEURAL_ELIC | CAP_NEURAL_MLICPP | CAP_NEURAL_MLICV2 | CAP_NEURAL_CMIC
| CAP_NEURAL_VIDEO_BMSHJ2018 | CAP_NEURAL_GLC | CAP_NEURAL_DCVC_RT | CAP_NEURAL_DCVC_FM
| CAP_SEMANTIC_CLIP | CAP_GENERATE_SPECTRAL
// wai.neural.int_mlicpp, classified when it was registered: its decoder is this
// crate's (Apache-2.0) and no model is registered with it (the conformance
// vector's weights are WAI's own synthetic ones). The patent status of the
// entropy-model techniques it implements was not examined.
| CAP_NEURAL_INT_MLICPP
// WAI-native classes: the reference implementation is Apache-2.0.
| CAP_VIDEO_INT_MOTION | CAP_VIDEO_INT_HYPER | CAP_AUDIO_INT_CODEC | CAP_SPLAT_INT_CODEC
| CAP_WORLD_SCENE | CAP_WORLD_REPLAY | CAP_WORLD_LIVE | CAP_WORLD_MODEL
| CAP_AUDIO_SCENE | CAP_AUDIO_SCORE | CAP_HAPTIC_SIGNAL | CAP_FEED_STATE
| CAP_AVATAR_POSE | CAP_SPLAT_4D | CAP_FILM_LINEAR | CAP_FILM_REEL
| CAP_QUANTUM_CIRCUIT | CAP_QUANTUM_CIRCUIT2 | CAP_TERNARY_TT | CAP_PRIOR_SET
| CAP_IMAGE_INT_REFINE | CAP_VIDEO_INT_REFINE | CAP_AUDIO_INT_REFINE | CAP_SPLAT_INT_REFINE
// Open asset formats: glTF (Khronos), SPZ (open source).
| CAP_MESH_GLB | CAP_SPLAT_SPZ
// JPEG 2000 Part 1 is fee-free under ITU-T policy 2.1 (extensions /
// submarine-patent caveats noted); IAMF under the AOMedia Patent
// License 1.0; Draco Apache-2.0; HDR10+ royalty-free for content +
// devices (only the logo is licensed).
| CAP_IMAGE_JP2 | CAP_VIDEO_J2K | CAP_AUDIO_IAMF | CAP_MESH_DRACO
| CAP_META_HDR10PLUS
// AV2 under the AOMedia Patent License 1.0; VP9 under its BSD source +
// patent grant; EVC Baseline royalty-free by design (caveat recorded).
| CAP_VIDEO_AV2 | CAP_VIDEO_VP9 | CAP_VIDEO_EVC_BASELINE => RoyaltyFree,
// Registered but unclassified: a registry defect, surfaced as `None`.
_ => return None,
})
}
/// Whether a capability is royalty-free to implement — the predicate a
/// royalty-conscious deployer filters on.
pub fn is_royalty_free(cap: &str) -> bool {
capability_license(cap) == Some(LicenseClass::RoyaltyFree)
}
/// How a capability's reconstruction relates to cross-hardware reproducibility —
/// the **integer-entropy contract** for neural decodes, and the named standard's
/// decoder conformance for standard codecs — a property of the capability looked
/// up in the registry (like [`capability_license`], not a per-file claim). It
/// answers the question `intent=replicate` turns on: *what does every conforming
/// sink running this capability reconstruct?* [`ReplicateClass::replicate_promise`]
/// states it per class — the same bytes on every conforming sink
/// (*decode-equivalence*) for the integer-exact neural decodes and the capabilities
/// whose reconstruction is specified exactly; what the named standard's decoder
/// conformance admits for the other standard codecs; and nothing, so `replicate` is
/// refused, for the rest (SPEC §3, §7; `extensions/determinism-tiers.md`).
/// [`replicate_refusal`] applies the rule.
///
/// The hazard this isolates for **neural** regenerate paths: a learned codec's
/// entropy decode desyncs the instant the decoder's scale-bucket / σ computation
/// drifts from the encoder's by one float ULP — the bucket assignment flips and the
/// whole stream corrupts. So a float neural decode is reproducible only on the
/// *same build*. An integer entropy stage fixes the decoded symbols on every
/// machine but leaves the reconstruction to whatever arithmetic the later stages
/// run in; only a decode that is integer/fixed-point end to end is byte-identical
/// on *every* machine. Standard codecs are classified on a separate axis: by what
/// their named standard's decoder conformance fixes — the output exactly
/// ([`StandardDefined`](Self::StandardDefined)), a criterion around a reference
/// ([`StandardTolerance`](Self::StandardTolerance)), or not yet classified
/// ([`StandardUnclassified`](Self::StandardUnclassified)).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReplicateClass {
/// The reconstruction is specified exactly, so `replicate` promises the same
/// bytes on every conforming sink. Either the named standard requires it — the
/// lossless formats whose decoded output it determines (PNG, FLAC, the zstd and
/// XZ byte formats), and the video codecs whose decoder-conformance clause
/// requires every output sample to equal the specified decoding process's:
/// `wai.video.avc` (ITU-T H.264 (V16, 06/2026) §C.4), `wai.video.hevc` (H.265
/// (V11, 01/2026) §C.5.1), `wai.video.vvc` (H.266 (V4, 01/2026) §C.5.1),
/// `wai.video.vp9` (VP9 Bitstream & Decoding Process Specification v0.6 §8.1,
/// "identical in all respects") — or the WAI extension that defines the
/// capability's `*-equivalence` over integer / fixed-point state (`world`,
/// `score`, `film`, `quantum`, `ternary`, the haptic signal, the integer
/// inter-frame codec, …). The promise covers the output the standard or
/// extension specifies, at its own sample depth and layout: for the video codecs
/// the cropped decoded pictures, before any processing a message only signals
/// (film grain characteristics, post-filter hints) and before colour
/// conversion; a conversion a sink applies afterwards (PNG sample-depth
/// rescaling, for which RFC 2083 §10.4 gives two methods) is not part of it. An
/// extension's equivalence holds given its inputs: where it composes other
/// capabilities' decoded output (a `wai.audio.scene` source decoded through
/// `wai.audio.opus`, say), it is only as exact as their classes
/// ([`composes_decoded_sources`]; [`is_cross_decoder_exact`] is false for such
/// a capability until its sources are known); for
/// `wai.world.model` it covers the signed action trace and session hash, not
/// the frames its declared renderer generates. No neural decode is in this
/// class. Every member's basis is recorded, one row per capability, in the
/// registry tests (`STANDARD_DEFINED_EVIDENCE`); a capability without a
/// recorded basis belongs in [`StandardUnclassified`](Self::StandardUnclassified).
StandardDefined,
/// A standard codec whose named standard holds decoders to a criterion around
/// a reference instead of to identical output, for at least some conforming
/// payloads, so two conforming sinks may reconstruct different bytes. For Opus
/// and JPEG XL the clauses read state the criterion as numeric thresholds. For
/// JPEG and JPEG 2000 the text read points to a criterion without stating its
/// bound — T.81 leaves the accuracy of dequantisation and IDCT to its Part 2,
/// which was not read, and only the table of contents and terms of ISO/IEC
/// 15444-4 were read — so no bound is given here. For IVAS the clauses read
/// hold a non-bit-exact implementation to a stated procedure (below). For AV1,
/// AVIF and AV2 with film grain it is the absence of "perceptually significant
/// differences", whose definition AV1 §7.2 places outside the specification and
/// AV2 §7.1 leaves to others. `replicate` over it promises what that
/// conformance promises — every conforming sink within the standard's
/// criterion — and not byte identity across sinks.
/// `wai.audio.opus` (RFC 6716 §6: within `opus_compare`'s thresholds of the
/// reference decoder, with the same final range-decoder state);
/// `wai.image.jpeg` (ITU-T T.81 §7 and A.3.3: decoding "with appropriate
/// accuracy", the accuracy of dequantisation and IDCT specified in Part 2);
/// `wai.image.jxl` (ISO/IEC 18181-3 §4.2–§4.3, read in its public preview:
/// peak-error and RMSE thresholds per test); `wai.image.jp2` / `wai.video.j2k`
/// (ISO/IEC 15444-4, per the table of contents and terms of its public preview:
/// decoded components compared with reference components by error metrics, and
/// a reversible path its definitions describe as lossless);
/// `wai.video.av1`, `wai.video.av1.lossless` and
/// `wai.image.avif` (AV1 §7.2: identical output unless the payload signals film
/// grain, and then identical frames before grain synthesis, and output frames
/// that "do not have perceptually significant differences" from the reference
/// grain synthesis); `wai.video.av2` (AV2 v1.0.0 §7.1, the same two options);
/// `wai.audio.ivas` (3GPP TS 26.252 V19.2.0 §7.2.1: an implementation based on
/// the floating-point reference whose output is not bit-exact to the test
/// sequences is tested by a non-bit-exact procedure — TS 26.444's for mono, a
/// per-frame loudness-difference corridor for stereo and immersive operation);
/// `wai.audio.iamf` (its substreams include Opus, and its renderers are out of
/// its scope).
StandardTolerance,
/// A standard codec this registry has not yet classified between
/// [`StandardDefined`](Self::StandardDefined) and
/// [`StandardTolerance`](Self::StandardTolerance): its named standard's
/// decoder-conformance clauses have not been checked. `replicate` over it
/// promises what that conformance promises, and the registry does not say
/// whether that is byte identity. The sink-supplied broadcast codecs whose
/// conformance documents were not read — `wai.video.evc` and
/// `wai.video.evc.baseline` (ISO/IEC 23094-1), `wai.video.avs3` (T/AI 109.2),
/// `wai.video.lcevc` (ISO/IEC 23094-2, whose decoding process includes a
/// signalled dither step), `wai.audio.mpegh` (ISO/IEC 23008-3),
/// `wai.audio.avs3` (T/AI 109.3), `wai.audio.aac` (three decoders measured on
/// one host give three different PCM streams from one ADTS stream; whether its
/// conformance admits that, or makes some of them non-conforming, was not
/// established), `wai.audio.ac4`; `wai.mesh.draco`, `wai.pc.gpcc`,
/// `wai.pc.vpcc`, `wai.splat.sog` (a candidate: no payload format is pinned), `wai.haptic.mihs`,
/// and the HDR metadata descriptors `wai.meta.hdr10plus` / `wai.meta.dovi`
/// (what they reconstruct is a display-mapped picture); and the asset
/// capabilities `wai.mesh.glb` and `wai.splat.spz`, whose payload bytes pass
/// through intact but whose decode is unclassified (a glTF binary may carry JPEG
/// images in its buffers and compressed geometry through extensions, and glTF
/// specifies an asset format, not a decoder conformance over what is rendered;
/// SPZ stores quantised attributes). All are sink-supplied.
StandardUnclassified,
/// A neural regenerate path that is integer/fixed-point **by construction**
/// — no float inference anywhere on the decode, entropy and synthesis — so it
/// is byte-identical on every machine: registered at *decode-equivalence*. The
/// only neural class that soundly backs cross-hardware `intent=replicate`.
NeuralIntegerExact,
/// A neural regenerate path whose **entropy decode** is integer by
/// construction — the decoded symbols, and the entropy parameters they are
/// decoded with, are byte-identical on every machine — but whose later stages
/// run float, so the reconstruction is not guaranteed across conforming sinks:
/// registered at *entropy-consistency*, the lower tier. **Not** sound for
/// `replicate`, which promises the reconstruction, not the symbols. A
/// particular implementation may still pin one reconstruction (WAI's exact
/// JPEG AI decoder does, under the conditions in `determinism-tiers` §5); that
/// is a property of the implementation, not of the capability.
/// `wai.image.jpegai`. It is here by the neural rule (SPEC §7), not because
/// its standard was found to leave the reconstruction unbounded: an overview of
/// the standard says its conformance part (ISO/IEC 6048-4) specifies the
/// requirements for a compliant reconstruction and "considers the possibility
/// that a decoder is conformant to the standard without having bit-exact
/// reconstruction", and that part has not been read. Refusing `replicate` over
/// it is a conservative choice pending that reading (SPEC §7,
/// *`wai.image.jpegai` and the standard classes*).
NeuralEntropyExact,
/// A **generative** path (`intent=create`) that is integer/fixed-point by
/// construction and pinned to `(model, prompt, seed, steps)` — so the
/// *generated* content is byte-identical on every machine. There is no
/// original to reconstruct, yet the output hash is portable and receiptable:
/// the create-side of byte-exact conformance (*generation-equivalence*).
/// Distinct from [`Behavioral`](Self::Behavioral), which conforms by
/// similarity and never reproduces bytes. The `wai.generate.*` path.
GenerativeDeterministic,
/// A neural regenerate path that runs float inference (ONNX synthesis, and
/// for the conditional-entropy family a float σ/scale computation). Exact
/// only on the same build; **not** sound for cross-hardware `replicate`. The
/// registry claims no determinism tier for these.
NeuralFloat,
/// Regenerated by a sink generator; conforms by similarity, not bytes — no
/// byte reproduction at all (the `wai.semantic.*` path).
Behavioral,
}
/// The two reproducibility tiers a neural capability can be registered at
/// (`extensions/determinism-tiers.md` §2). Each is a property of the capability as
/// registered — it holds on every conforming sink — not of one implementation.
/// Ordered weakest first. One type serves the registry and
/// [`derivation::derived_sample_tier`], so a tier read from one can be passed to
/// the other.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum DeterminismTier {
/// The entropy decode reproduces byte-for-byte on every conforming sink; the
/// reconstruction may differ. Does not back `replicate`.
EntropyConsistency,
/// The whole decode to the final medium reproduces byte-for-byte on every
/// conforming sink. What `replicate` over a neural capability promises.
DecodeEquivalence,
}
/// What `intent = replicate` promises over a capability, by its registry class
/// (SPEC §3, §7). See [`ReplicateClass::replicate_promise`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReplicatePromise {
/// Every conforming sink reconstructs the same bytes: *decode-equivalence*, or
/// the `*-equivalence` the capability's extension defines. For a
/// [`ReplicateClass::NeuralIntegerExact`] capability the envelope must also pin
/// an integer-exact prior ([`replicate_refusal`]).
ByteExact,
/// Every conforming sink reconstructs what the named standard's decoder
/// conformance admits — within its criterion around a reference
/// ([`ReplicateClass::StandardTolerance`]; for film-grain AV1 that criterion
/// is perceptual and not quantified by the standard), or a criterion this
/// registry has not classified ([`ReplicateClass::StandardUnclassified`]).
/// Byte identity across sinks is not promised.
NamedStandardConformance,
}
impl ReplicateClass {
/// The determinism tier a neural capability of this class is registered at.
/// `None` for [`NeuralFloat`](Self::NeuralFloat), which claims no tier, and for
/// the classes the neural tiers do not describe (the standard classes,
/// generative, behavioral).
pub fn neural_tier(self) -> Option<DeterminismTier> {
match self {
Self::NeuralIntegerExact => Some(DeterminismTier::DecodeEquivalence),
Self::NeuralEntropyExact => Some(DeterminismTier::EntropyConsistency),
Self::StandardDefined | Self::StandardTolerance | Self::StandardUnclassified
| Self::GenerativeDeterministic | Self::NeuralFloat | Self::Behavioral => None,
}
}
/// What `intent = replicate` promises over a capability of this class, or
/// `None` when the class cannot back `replicate` at all (SPEC §7): entropy-only
/// and float neural decodes, whose reconstruction nothing the registry states
/// bounds, and the generative and behavioral paths, which do not reconstruct a
/// source.
pub fn replicate_promise(self) -> Option<ReplicatePromise> {
match self {
Self::NeuralIntegerExact | Self::StandardDefined => Some(ReplicatePromise::ByteExact),
Self::StandardTolerance | Self::StandardUnclassified => {
Some(ReplicatePromise::NamedStandardConformance)
}
Self::NeuralEntropyExact | Self::NeuralFloat
| Self::GenerativeDeterministic | Self::Behavioral => None,
}
}
/// The short label `wai capabilities` prints in its `replicate` column.
pub fn label(self) -> &'static str {
match self {
Self::StandardDefined => "standard-defined",
Self::StandardTolerance => "standard-tolerance",
Self::StandardUnclassified => "standard-unclassified",
Self::NeuralIntegerExact => "neural-int-exact",
Self::NeuralEntropyExact => "neural-entropy-exact",
Self::GenerativeDeterministic => "generative-exact",
Self::NeuralFloat => "neural-float",
Self::Behavioral => "behavioral",
}
}
}
/// The [`ReplicateClass`] of a registered capability, or `None` if unknown.
///
/// The classification is **exhaustive, with no default class**, as
/// [`capability_license`] is: every registered capability is listed under
/// exactly one arm, and one registered but listed nowhere returns `None`, which
/// the registry tests reject. A newly registered codec therefore cannot become
/// "reproducible on every machine" by omission. The basis for each standard
/// codec's class — the conformance clause read, and where a second decoder was
/// available a cross-decoder measurement — is recorded in
/// `research/media-codec-registry.md`; the basis of every
/// [`StandardDefined`](ReplicateClass::StandardDefined) member is also pinned in
/// the registry tests.
pub fn capability_replicate_class(cap: &str) -> Option<ReplicateClass> {
use ReplicateClass::*;
if !is_known_capability(cap) {
return None;
}
Some(match cap {
// Every registered capability is listed under exactly one arm below; there
// is no default. A new registration takes the conservative class of its
// kind — StandardUnclassified for a standard codec, NeuralFloat for a neural
// decode — until evidence supports a stronger one.
// The neural decodes that are integer/fixed-point by construction (all-i64,
// no float/ONNX) — byte-identical everywhere. int_synth is synthesis only;
// int_hyper is the FULL conditional codec (integer hyper-decoder σ source +
// integer entropy + integer synthesis), so its whole bitstream→image path is
// exact cross-hardware — the integer-entropy contract fully assembled.
// wai.video.int_hyper composes the learned int_hyper I-frame with integer
// P-frames — its decode embeds the integer-exact neural codec, byte-exact.
// wai.audio.int_codec is the audio analog of int_hyper: a learned 1-D
// transform codec, integer synthesis → byte-exact int16 PCM.
// wai.splat.int_codec is the int_hyper of 3D: a learned splat-attribute
// transform, integer synthesis → byte-exact attribute tensor.
// wai.neural.int_mlicpp is the MLIC++ entropy topology over the same integer
// networks: every σ the entropy network gives is integer, so the bucket is the
// encoder's on every decoder. Every member's basis is one row of
// NEURAL_INTEGER_EXACT_EVIDENCE in the tests.
CAP_NEURAL_INT_SYNTH | CAP_NEURAL_INT_HYPER | CAP_VIDEO_INT_HYPER
| CAP_AUDIO_INT_CODEC | CAP_SPLAT_INT_CODEC | CAP_NEURAL_INT_MLICPP => NeuralIntegerExact,
// JPEG AI: the entropy decode, including the scale-index derivation (an
// integer hyper-scale network), is integer on both reference decode paths,
// so the decoded symbols reproduce everywhere. Dequantisation, latent
// refinement, the post-filters and colour conversion are float (fixed-order
// in the exact decoder, ONNX Runtime in the fallback), so the reconstruction
// is not guaranteed across conforming sinks. Earlier in v0.4.0 this capability
// fell through to StandardDefined, which let a `replicate` envelope over it
// pass the strict check; it no longer backs `replicate` (SPEC §7). Its
// standard's conformance part (ISO/IEC 6048-4) may hold the reconstruction
// to a criterion around a reference; it has not been read, so this class is
// a conservative choice pending it, not a reading of the standard.
CAP_IMAGE_JPEGAI => NeuralEntropyExact,
// Every other neural regenerate path runs float inference, so the decode
// is exact only on the same build, never guaranteed cross-hardware.
CAP_NEURAL_ENCODEC32 | CAP_NEURAL_DAC | CAP_NEURAL_MIMI | CAP_NEURAL_WAVTOKENIZER
| CAP_NEURAL_SNAC | CAP_NEURAL_BMSHJ2018 | CAP_NEURAL_MBT2018_MEAN
| CAP_NEURAL_ELIC | CAP_NEURAL_MLICPP | CAP_NEURAL_MLICV2 | CAP_NEURAL_CMIC
| CAP_NEURAL_VIDEO_BMSHJ2018 | CAP_NEURAL_GLC | CAP_NEURAL_DCVC_RT
| CAP_NEURAL_DCVC_FM => NeuralFloat,
// Deterministic integer generator: generated content, byte-identical on
// every machine, pinned to (model, prompt, seed, steps) — receiptable.
CAP_GENERATE_SPECTRAL => GenerativeDeterministic,
// Sink-generator regeneration; conforms by similarity, not bytes.
CAP_SEMANTIC_CLIP | CAP_SEMANTIC_PERCO2 => Behavioral,
// ---- Standard classes: what the named standard's decoder conformance fixes.
// Specified exactly. Each member's basis is one row of
// STANDARD_DEFINED_EVIDENCE in the tests; an exact class without one fails
// `standard_defined_rests_on_recorded_evidence`.
// Lossless formats: the decode reproduces the encoded samples / bytes.
CAP_IMAGE_PNG | CAP_AUDIO_FLAC | CAP_TEXT_ZSTD | CAP_TEXT_XZ
// Video codecs whose decoder conformance requires every output sample to
// equal the specified decoding process's: H.264 §C.4, H.265 §C.5.1, H.266
// §C.5.1, the VP9 specification §8.1. It covers the cropped decoded
// pictures, not processing an SEI message only signals (film grain).
| CAP_VIDEO_AVC | CAP_VIDEO_HEVC | CAP_VIDEO_VVC | CAP_VIDEO_VP9
// WAI-native capabilities, by the extension that defines each one's
// `*-equivalence` over integer / fixed-point state. The wai.audio.scene
// mixdown is exact given its sources' decoded PCM; wai.world.model's
// equivalence covers its action trace, not its renderer's frames.
| CAP_VIDEO_INT_MOTION
| CAP_WORLD_SCENE | CAP_WORLD_REPLAY | CAP_WORLD_LIVE | CAP_WORLD_MODEL
| CAP_AUDIO_SCENE | CAP_AUDIO_SCORE | CAP_HAPTIC_SIGNAL | CAP_FEED_STATE
| CAP_AVATAR_POSE | CAP_SPLAT_4D | CAP_FILM_LINEAR | CAP_FILM_REEL
| CAP_QUANTUM_CIRCUIT | CAP_QUANTUM_CIRCUIT2 | CAP_TERNARY_TT
// A parameter-set listing: SPEC §3.1 fixes its bytes exactly, and they are
// its own output.
| CAP_PRIOR_SET
// A residual refinement: integer prediction, residual and clamp
// (staged-delivery §6.1), exact given the stage below; it composes its base's
// decoded output (`composes_decoded_sources`), so it is as exact as its base.
| CAP_IMAGE_INT_REFINE | CAP_VIDEO_INT_REFINE | CAP_AUDIO_INT_REFINE | CAP_SPLAT_INT_REFINE => StandardDefined,
// A criterion around a reference, not identical output (clauses in the
// variant's doc and in research/media-codec-registry.md): Opus (RFC 6716
// §6), JPEG (T.81 §7, A.3.3), JPEG XL (18181-3 §4.2), JPEG 2000 (15444-4),
// AV1 and AVIF (AV1 §7.2, when film grain is signalled), AV2 (AV2 v1.0.0
// §7.1, likewise), IVAS (TS 26.252 V19.2.0 §7.2.1, floating-point
// implementations), IAMF (Opus substreams; renderers out of scope).
CAP_AUDIO_OPUS | CAP_IMAGE_JPEG | CAP_IMAGE_JXL | CAP_IMAGE_JP2 | CAP_VIDEO_J2K
| CAP_VIDEO_AV1 | CAP_VIDEO_AV1_LOSSLESS | CAP_IMAGE_AVIF | CAP_VIDEO_AV2
| CAP_AUDIO_IVAS | CAP_AUDIO_IAMF => StandardTolerance,
// Sink-supplied standards whose decoder-conformance clauses the registry
// has not checked, and the two pass-through asset formats whose decode it
// has not classified. The conservative class: it promises no byte identity.
// Moving one to StandardDefined needs a recorded basis (see above).
CAP_VIDEO_EVC | CAP_VIDEO_EVC_BASELINE | CAP_VIDEO_AVS3 | CAP_VIDEO_LCEVC
| CAP_AUDIO_MPEGH | CAP_AUDIO_AVS3 | CAP_AUDIO_AAC | CAP_AUDIO_AC4
| CAP_MESH_DRACO | CAP_PC_GPCC | CAP_PC_VPCC | CAP_SPLAT_SOG | CAP_HAPTIC_MIHS
| CAP_META_HDR10PLUS | CAP_META_DOVI
| CAP_MESH_GLB | CAP_SPLAT_SPZ => StandardUnclassified,
// Neural-network coding (ISO/IEC 15938-17). Whether every conforming NNC
// decoder reconstructs the same parameter values is not established
// (extensions/prior-carriage.md §5), so NNC is held to the conservative
// class like the other unchecked standards. A prior's declared NNC form
// is refused for replicate by Prior::is_cross_hardware_exact regardless.
CAP_PRIOR_NNC | CAP_TENSOR_NNC => StandardUnclassified,
// Registered but unclassified: a registry defect, surfaced as `None`.
_ => return None,
})
}
/// The integer operator set a capability's decode runs through
/// (`extensions/integer-operators.md` §11): the registry's `ops` member. `profile` is the
/// profile every conforming parameter set of the capability meets, and a set whose
/// certificate does not meet it is refused; `subset` is `full` or `npu`; `lowering`
/// names the §13 lowering the capability's sets are lowered by; `rans64` and `bucket`
/// fix the modes of the stage operators its driver uses (§5E). Strengthening a profile
/// or a subset narrows the sets a capability accepts, a breaking change (SPEC §8).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpsMember {
pub profile: &'static str,
pub subset: &'static str,
pub lowering: &'static str,
/// `rans64_decode`'s `(table, escape, end)` (E1), where the driver decodes one.
pub rans64: Option<(&'static str, &'static str, &'static str)>,
/// `bucket`'s rule (E3), where the driver buckets a scale.
pub bucket: Option<&'static str>,
}
/// The `ops` member of `cap`, for a capability decoded through the integer operator
/// set; `None` for any other. A capability gains one when its decoder runs its
/// networks through their lowering (`extensions/integer-operators.md` §15.1).
pub fn capability_ops(cap: &str) -> Option<OpsMember> {
let ops = |lowering, rans64, bucket| Some(OpsMember { profile: "acc64", subset: "full", lowering, rans64, bucket });
match cap {
CAP_NEURAL_INT_SYNTH => ops("int_synth/1", None, None),
_ => None,
}
}
/// Whether a capability's **neural** decode is integer-exact by construction —
/// the integer-entropy contract. Isolates exactly the neural codecs WAI itself
/// guarantees byte-identical on every machine, so a deployer can require
/// `intent=replicate` to dispatch only to a cross-hardware-sound neural decode.
/// Standard codecs are not neural; what `replicate` promises over them is their
/// class's [`ReplicateClass::replicate_promise`]. For the whole-registry question
/// ("does every conforming sink reconstruct the same bytes?", neural or not) use
/// [`is_cross_decoder_exact`].
pub fn is_neural_integer_exact(cap: &str) -> bool {
capability_replicate_class(cap) == Some(ReplicateClass::NeuralIntegerExact)
}
// ---- Parameter sets, the tier vocabulary and dispatchability (SPEC §3.1, §4, §7.1) ----
/// Whether a registered capability **decodes against a parameter set** (SPEC §3.1):
/// its registry class is `NeuralIntegerExact`, `NeuralEntropyExact`, `NeuralFloat`
/// or `GenerativeDeterministic`. Its parameter set is every byte other than the
/// payload that its decode reads and that its output depends on; the sink supplies
/// it, and a manifest MAY pin it. `false` for an unregistered capability: this
/// revision does not know what it decodes against (a sink that advertises one and
/// finds a pin on it verifies the pin as several files, SPEC §3.1).
pub fn decodes_against_parameter_set(cap: &str) -> bool {
use ReplicateClass::*;
matches!(
capability_replicate_class(cap),
Some(NeuralIntegerExact | NeuralEntropyExact | NeuralFloat | GenerativeDeterministic)
)
}
/// The registered shape of a capability's parameter set (SPEC §5): one file, or
/// several. A form-less pin is admissible only over a one-file set (SPEC §3.1,
/// `form_required`); a set of several files is pinned through its listing
/// ([`CAP_PRIOR_SET`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParameterSetShape {
/// One file holds the whole set.
OneFile,
/// Several files make up the set, or the registration names no one-file format.
SeveralFiles,
}
/// The parameter-set shape SPEC §5 registers for `cap`: `Some` exactly when
/// [`decodes_against_parameter_set`]. A capability is one file when the reference
/// decoder reads one file and that file holds every parameter its output depends
/// on; every other capability that decodes against a parameter set is several
/// files. A later revision MAY register a several-file capability as one file when
/// it defines a one-file format that holds the whole set (a widening, SPEC §8).
pub fn parameter_set_shape(cap: &str) -> Option<ParameterSetShape> {
if !decodes_against_parameter_set(cap) {
return None;
}
Some(match cap {
// int_synth: its model specification, int_synth.json. int_mlicpp: its WMB1
// bundle. audio.int_codec: its WAM1 synthesis (model.wam). splat.int_codec: its
// WHM1 synthesis (g_s.whm). The audio codecs and the per-frame video codec: one
// self-contained ONNX decoder (a model that keeps tensors in external files is
// several files).
CAP_NEURAL_INT_SYNTH | CAP_NEURAL_INT_MLICPP | CAP_AUDIO_INT_CODEC | CAP_SPLAT_INT_CODEC
| CAP_NEURAL_ENCODEC32 | CAP_NEURAL_DAC | CAP_NEURAL_MIMI | CAP_NEURAL_WAVTOKENIZER
| CAP_NEURAL_SNAC | CAP_NEURAL_VIDEO_BMSHJ2018 => ParameterSetShape::OneFile,
_ => ParameterSetShape::SeveralFiles,
})
}
/// The tier a pin's `tier` member declares (SPEC §3.1): the closed, registered
/// vocabulary of `extensions/determinism-tiers.md` §2 plus `none`. Ordered weakest
/// first. An encoder writes only these tokens ([`DeclaredTier::token`]); a sink
/// reads any other token as [`DeclaredTier::None`], and a verifier reports it
/// (`tier_unregistered`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum DeclaredTier {
/// Neither tier is claimed.
None,
/// `entropy-consistency` ([`DeterminismTier::EntropyConsistency`]).
EntropyConsistency,
/// `decode-equivalence` ([`DeterminismTier::DecodeEquivalence`]).
DecodeEquivalence,
}
/// The registered tier tokens, in the one table every reader and writer of the
/// vocabulary uses (SPEC §3.1; the vocabulary's shape; the registry export).
/// Tier tokens and class labels are kebab-case; refusal reasons are snake_case.
pub const TIER_TOKENS: &[(&str, DeclaredTier)] = &[
("decode-equivalence", DeclaredTier::DecodeEquivalence),
("entropy-consistency", DeclaredTier::EntropyConsistency),
("none", DeclaredTier::None),
];
impl DeclaredTier {
/// The registered token this tier is written as.
pub fn token(self) -> &'static str {
TIER_TOKENS.iter().find(|&&(_, t)| t == self).map(|&(tok, _)| tok).unwrap_or("none")
}
/// The tier a registered token names, or `None` for a token this revision
/// does not register (which a sink reads as [`DeclaredTier::None`]).
pub fn from_token(token: &str) -> Option<Self> {
TIER_TOKENS.iter().find(|&&(tok, _)| tok == token).map(|&(_, t)| t)
}
/// The determinism tier this declares, `None` for [`DeclaredTier::None`].
pub fn determinism_tier(self) -> Option<DeterminismTier> {
match self {
Self::None => None,
Self::EntropyConsistency => Some(DeterminismTier::EntropyConsistency),
Self::DecodeEquivalence => Some(DeterminismTier::DecodeEquivalence),
}
}
}
impl From<Option<DeterminismTier>> for DeclaredTier {
fn from(t: Option<DeterminismTier>) -> Self {
match t {
None => Self::None,
Some(DeterminismTier::EntropyConsistency) => Self::EntropyConsistency,
Some(DeterminismTier::DecodeEquivalence) => Self::DecodeEquivalence,
}
}
}
impl DeterminismTier {
/// The registered token (`decode-equivalence`, `entropy-consistency`).
pub fn token(self) -> &'static str {
DeclaredTier::from(Some(self)).token()
}
/// The tier a registered token names; `None` for `none` or an unregistered token.
pub fn from_token(token: &str) -> Option<Self> {
DeclaredTier::from_token(token).and_then(DeclaredTier::determinism_tier)
}
}
/// The capabilities that decode a classical codec: those the codec glossary
/// (`wai/glossary/codecs.json`) links from an entry whose era is `classical`, the
/// registered standards' own formats. WAI's own formats, the neural codecs, records,
/// derivations and parameter sets are not among them. A test holds this list to the
/// glossary. A `reconstruct-session` claim's classical rendition is one of these
/// (`extensions/jwp-receipts.md` §2.4.12).
const CLASSICAL: &[&str] = &[
CAP_IMAGE_JPEG, CAP_IMAGE_JP2, CAP_IMAGE_AVIF, CAP_IMAGE_JXL, CAP_IMAGE_PNG,
CAP_VIDEO_AVC, CAP_VIDEO_HEVC, CAP_VIDEO_VVC, CAP_VIDEO_LCEVC, CAP_VIDEO_EVC, CAP_VIDEO_EVC_BASELINE,
CAP_VIDEO_AVS3, CAP_VIDEO_VP9, CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS, CAP_VIDEO_AV2, CAP_VIDEO_J2K,
CAP_AUDIO_AAC, CAP_AUDIO_MPEGH, CAP_AUDIO_AVS3, CAP_AUDIO_IAMF, CAP_AUDIO_FLAC, CAP_AUDIO_OPUS,
CAP_AUDIO_AC4, CAP_AUDIO_IVAS,
CAP_TEXT_ZSTD, CAP_TEXT_XZ,
CAP_MESH_GLB, CAP_MESH_DRACO, CAP_PC_GPCC, CAP_PC_VPCC, CAP_SPLAT_SPZ,
CAP_HAPTIC_MIHS,
CAP_META_HDR10PLUS, CAP_META_DOVI,
];
/// Whether `cap` decodes a classical codec ([`CLASSICAL`]).
pub fn is_classical(cap: &str) -> bool {
CLASSICAL.contains(&cap)
}
/// The tier `cap`'s registry class gives (SPEC §3.1, *Tier*): `decode-equivalence`
/// for `NeuralIntegerExact`, `entropy-consistency` for `NeuralEntropyExact`, `none`
/// for every other class. `None` for an unregistered capability.
pub fn class_tier(cap: &str) -> Option<DeclaredTier> {
capability_replicate_class(cap).map(|c| DeclaredTier::from(c.neural_tier()))
}
/// Whether a pin's stated `tier` claims more than `cap`'s registry class gives
/// (SPEC §3.1, `tier_exceeds_class`). Only a registered `tier` member is read: a
/// pin without one, or with an unregistered token (read as `none`), claims nothing
/// above any class. `false` for an unregistered capability, whose class is unknown.
pub fn tier_exceeds_class(cap: &str, prior: &crate::container::Prior) -> bool {
let Some(class) = class_tier(cap) else { return false };
match prior.tier().and_then(DeclaredTier::from_token) {
Some(claim) => claim > class,
None => false,
}
}
/// Why SPEC §7 refuses an `intent = replicate` envelope. See [`replicate_refusal`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ReplicateRefusal {
/// The capability is not registered, so nothing states what it reproduces.
Unregistered,
/// The capability's registry class cannot back `replicate`
/// ([`ReplicateClass::replicate_promise`] is `None`), whatever the envelope's
/// prior declares.
Class(ReplicateClass),
/// The class is [`ReplicateClass::NeuralIntegerExact`], but the envelope's prior
/// does not make the decode exact across hardware: none is pinned, its declared
/// contract is not integer-exact, or it declares a form whose reconstruction is
/// not established exact at every reader
/// ([`crate::container::replicate_prior_refusal`] gives the reason).
Prior(crate::container::PriorRefusal),
}
impl std::fmt::Display for ReplicateRefusal {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
use ReplicateClass::*;
match self {
Self::Unregistered => write!(f, "the capability is not registered"),
Self::Class(NeuralEntropyExact) => write!(f,
"registry class NeuralEntropyExact: only the entropy decode is integer \
(entropy-consistency); later stages run float, so the reconstruction is not \
byte-identical on every conforming sink"),
Self::Class(NeuralFloat) => write!(f,
"registry class NeuralFloat: float inference is not byte-identical across hardware"),
Self::Class(Behavioral) => write!(f,
"registry class Behavioral: conforms by similarity, not bytes"),
Self::Class(GenerativeDeterministic) => write!(f,
"registry class GenerativeDeterministic: a generator (intent = create) has no \
source to replicate"),
Self::Class(c) => write!(f, "registry class {c:?} does not back replicate"),
Self::Prior(crate::container::PriorRefusal::Absent) => write!(f, "no pinned prior"),
Self::Prior(r) => write!(f, "{r}"),
}
}
}
impl ReplicateRefusal {
/// The reason SPEC §7 names: `replicate_unregistered`, `replicate_class`, or the
/// pin's reason ([`crate::container::PriorRefusal::code`]).
pub fn code(&self) -> &'static str {
match self {
Self::Unregistered => "replicate_unregistered",
Self::Class(_) => "replicate_class",
Self::Prior(r) => r.code(),
}
}
}
/// SPEC §7 *replicate-soundness* for one envelope: `None` when `(cap, intent, prior)`
/// may be honoured as `replicate`, otherwise why not.
///
/// The registry class decides first, and does not depend on anything the sender
/// declares: a class whose [`ReplicateClass::replicate_promise`] is `None` is refused.
/// For a neural capability `replicate` promises decode-equivalence — the same
/// reconstruction bytes on every conforming sink — which only
/// [`ReplicateClass::NeuralIntegerExact`] can keep, and then only against a pinned
/// prior that declares an integer-exact contract
/// ([`crate::container::Prior::is_cross_hardware_exact`]); a prior that *declares* an
/// integer contract does not rescue a capability whose decode is float or only
/// entropy-consistent. The three standard classes pass with no prior: over them
/// `replicate` promises what their class states — the same bytes for
/// [`ReplicateClass::StandardDefined`], the named standard's decoder conformance for
/// [`ReplicateClass::StandardTolerance`] and [`ReplicateClass::StandardUnclassified`].
/// Nothing here checks a sink's decoder against its standard. Intents other than
/// `replicate` are unconstrained. For a capability whose output is computed from
/// other envelopes' decoded output ([`composes_decoded_sources`]: a
/// `wai.audio.scene` mixes the PCM of the `wai.audio.*` envelopes it references),
/// this checks the one envelope it is given: its class's promise holds given its
/// sources, each of which is its own envelope with its own class, so the composite
/// is byte-exact only when every source is too
/// ([`is_cross_decoder_exact_with_sources`]).
pub fn replicate_refusal(
cap: &str,
intent: &str,
prior: Option<&crate::container::Prior>,
) -> Option<ReplicateRefusal> {
if intent != "replicate" {
return None;
}
match capability_replicate_class(cap) {
None => Some(ReplicateRefusal::Unregistered),
// The prior's reason, including a declared form that is not established
// exact, comes from the one place that defines it.
Some(ReplicateClass::NeuralIntegerExact) => {
crate::container::replicate_prior_refusal(intent, prior).map(ReplicateRefusal::Prior)
}
Some(c) if c.replicate_promise().is_some() => None,
Some(c) => Some(ReplicateRefusal::Class(c)),
}
}
/// Whether a capability's output is computed from **other envelopes' decoded
/// output** — sources it references rather than carries — so it is only as exact
/// as they are. `wai.audio.scene`'s payload names each object's source by the
/// content hash of a `wai.audio.*` envelope, and its mixdown is exact given the PCM
/// those sources decode to (`extensions/spatial-audio.md` §4), whatever their codec.
/// A refinement-only capability names, by content hash, the base whose output it
/// refines (`extensions/staged-delivery.md` §3), and its next stage is exact given
/// that output. The other WAI-native capabilities hash only state they carry: a
/// world's, a film's or an avatar's assets are presentation and never enter its
/// state hash.
pub fn composes_decoded_sources(cap: &str) -> bool {
cap == CAP_AUDIO_SCENE || is_refinement_only(cap)
}
/// Whether the class promises byte identity for the capability's own output.
fn promises_byte_exact(cap: &str) -> bool {
capability_replicate_class(cap).and_then(ReplicateClass::replicate_promise)
== Some(ReplicatePromise::ByteExact)
}
/// Whether every conforming sink decoding an envelope of this capability
/// reconstructs the same bytes, **from the capability alone**: its class's
/// [`ReplicateClass::replicate_promise`] is [`ReplicatePromise::ByteExact`]
/// ([`StandardDefined`](ReplicateClass::StandardDefined) or
/// [`NeuralIntegerExact`](ReplicateClass::NeuralIntegerExact)), and its output
/// does not depend on sources carried in other envelopes. A deployer that needs a
/// hash or receipt over a reconstruction to verify at another conforming sink
/// dispatches only to capabilities for which this is true.
///
/// A capability that [`composes_decoded_sources`] is **false** here, although its
/// class is `StandardDefined`: `wai.audio.scene`'s mixdown is exact given its
/// sources' PCM, and a source decoded through `wai.audio.opus` may decode
/// differently on two conforming sinks. Once its sources' capabilities are known,
/// [`is_cross_decoder_exact_with_sources`] answers for the scene.
///
/// It covers the output the named standard or WAI extension specifies, at that
/// output's own sample depth and layout — the cropped decoded pictures of a video
/// codec, the samples of an audio codec, the state an extension's equivalence
/// hashes. A conversion a sink applies afterwards (to RGB, to another bit depth, a
/// display mapping) is not covered; a hash over converted output is portable only
/// between sinks that also agree on the conversion. `StandardTolerance`,
/// `StandardUnclassified`, `NeuralEntropyExact`, `NeuralFloat` and `Behavioral`
/// capabilities are false; so is a generator (`GenerativeDeterministic` reproduces
/// generated content, it does not reconstruct a source). For a neural capability
/// this is the portability of the reconstruction only; whether an envelope may
/// claim `intent = replicate` over it is [`replicate_refusal`]'s rule (SPEC §7).
pub fn is_cross_decoder_exact(cap: &str) -> bool {
promises_byte_exact(cap) && !composes_decoded_sources(cap)
}
/// Whether `source` is a capability a composing capability's payload may
/// reference: for `wai.audio.scene`, a `wai.audio.*` envelope — the asset table
/// names each object's source as one (`extensions/spatial-audio.md` §2.2); for a
/// refinement-only capability, a base it admits (SPEC §5, *Base admission*).
fn is_source_of(cap: &str, source: &str) -> bool {
match cap {
CAP_AUDIO_SCENE => source.starts_with("wai.audio."),
c if is_refinement_only(c) => admits(c, source),
_ => false,
}
}
/// [`is_cross_decoder_exact`] for an envelope whose sources are known: `sources`
/// is the capability of every envelope its payload references — for a
/// `wai.audio.scene`, the envelope behind each object's `source_hash`, one entry
/// per object. True when the capability's class promises byte identity and every
/// source is a source it may reference and is itself cross-decoder exact.
///
/// It answers **false when it cannot tell**, never true:
///
/// - `sources` is empty. This cannot tell a scene that references no source
/// from a caller that resolved none, so a scene with no objects, whose mix is
/// silence, is also false here;
/// - a source is not one the capability may reference — for a scene, a
/// capability outside `wai.audio.*`;
/// - a source is unregistered, composes sources of its own, or is not
/// cross-decoder exact.
///
/// The answer is still only as complete as `sources`: a source left out is not
/// checked. It covers the output spatial-audio §4 holds to mixdown-equivalence,
/// the declared output layout's canonical PCM; a binaural render is perceptual
/// there, and nothing here makes it exact. For a capability that composes
/// nothing, `sources` is ignored and this equals [`is_cross_decoder_exact`].
pub fn is_cross_decoder_exact_with_sources(cap: &str, sources: &[&str]) -> bool {
if !composes_decoded_sources(cap) {
return is_cross_decoder_exact(cap);
}
promises_byte_exact(cap)
&& !sources.is_empty()
&& sources.iter().all(|s| is_source_of(cap, s) && is_cross_decoder_exact(s))
}
/// The intent an encoder that pins **no prior** may write over `cap`: `requested`,
/// or `replicate` when nothing is requested — unless [`replicate_refusal`] refuses
/// that intent over `cap` with no prior, in which case the refusal comes back and
/// the encoder writes nothing.
///
/// This is the encoder side of SPEC §7. An encoder MUST NOT emit `intent =
/// replicate` over a `NeuralEntropyExact` or `NeuralFloat` capability, and a sink
/// refuses `replicate` over any class whose [`ReplicateClass::replicate_promise`] is
/// `None`, and over a `NeuralIntegerExact` capability whose envelope pins no
/// integer-exact prior — which an unpinned envelope cannot. So an unpinned
/// `replicate` is accepted exactly over the three standard classes. `wai wrap` uses
/// this, so the reference tool does not write an envelope the reference strict
/// decode refuses. An intent other than `replicate` is returned unchanged.
pub fn unpinned_envelope_intent<'a>(
cap: &str,
requested: Option<&'a str>,
) -> Result<&'a str, ReplicateRefusal> {
let intent = requested.unwrap_or("replicate");
match replicate_refusal(cap, intent, None) {
None => Ok(intent),
Some(why) => Err(why),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn capability_registry_is_coherent() {
// Sink-supplied learned capabilities are registered.
assert!(is_known_capability(CAP_NEURAL_MLICPP));
assert!(is_known_capability(CAP_IMAGE_JPEGAI));
// Everything this crate decodes natively is also a known capability.
for &c in sink_capabilities() {
assert!(is_known_capability(c), "{c} advertised native but not registered");
}
// Sink-supplied / future capabilities are KNOWN but NOT advertised as
// natively decodable — registration is not a bundled decoder.
for &c in &[CAP_NEURAL_MLICPP, CAP_NEURAL_MLICV2, CAP_NEURAL_CMIC, CAP_NEURAL_SNAC,
CAP_NEURAL_GLC, CAP_NEURAL_DCVC_RT, CAP_NEURAL_DCVC_FM, CAP_IMAGE_JPEGAI,
CAP_SEMANTIC_CLIP, CAP_SEMANTIC_PERCO2,
CAP_VIDEO_AV2, CAP_VIDEO_VVC, CAP_VIDEO_LCEVC, CAP_AUDIO_MPEGH] {
assert!(is_known_capability(c));
assert!(!sink_capabilities().contains(&c),
"{c} is sink-supplied and must not claim native decode");
}
// Unregistered strings are not known; the catalog has no duplicates.
assert!(!is_known_capability("wai.image.nope"));
let mut seen = std::collections::HashSet::new();
for &c in known_capabilities() {
assert!(seen.insert(c), "duplicate capability {c}");
}
}
#[test]
fn every_capability_has_an_honest_tier() {
// No registered capability is untiered.
for &c in known_capabilities() {
assert!(capability_tier(c).is_some(), "{c} has no fidelity tier");
}
// The honesty cases that motivated tiers:
assert_eq!(capability_tier(CAP_IMAGE_PNG), Some(FidelityTier::Lossless));
assert_eq!(capability_tier(CAP_AUDIO_FLAC), Some(FidelityTier::Lossless));
// WavTokenizer is acoustic-token LOSSY, never bit-exact (the research point).
assert_eq!(capability_tier(CAP_NEURAL_WAVTOKENIZER), Some(FidelityTier::Lossy));
assert_eq!(capability_tier(CAP_NEURAL_MLICPP), Some(FidelityTier::Lossy));
// Quantum-circuit simulation is statevector-equivalence — the simulation
// analog of lossless (byte-exact reconstruction of the fixed-point state).
assert_eq!(capability_tier(CAP_QUANTUM_CIRCUIT), Some(FidelityTier::Lossless));
assert_eq!(capability_tier(CAP_QUANTUM_CIRCUIT2), Some(FidelityTier::Lossless));
// The semantic path is perceptual, not byte-exact.
assert_eq!(capability_tier(CAP_SEMANTIC_CLIP), Some(FidelityTier::Perceptual));
assert_eq!(capability_tier(CAP_SEMANTIC_PERCO2), Some(FidelityTier::Perceptual));
// Unknown → no tier.
assert_eq!(capability_tier("wai.image.nope"), None);
}
#[test]
fn every_capability_has_a_license_class() {
use LicenseClass::*;
// No registered capability is unclassified.
for &c in known_capabilities() {
assert!(capability_license(c).is_some(), "{c} has no license class");
}
// The floor + modern menu + WAI-native classes are royalty-free.
assert!(is_royalty_free(CAP_IMAGE_PNG));
assert!(is_royalty_free(CAP_VIDEO_AV1));
assert!(is_royalty_free(CAP_FILM_REEL));
assert!(is_royalty_free(CAP_QUANTUM_CIRCUIT)); // WAI-native, integer floor
assert!(is_royalty_free(CAP_QUANTUM_CIRCUIT2));
// Verified June 2026 against primary sources:
assert_eq!(capability_license(CAP_AUDIO_IAMF), Some(RoyaltyFree)); // AOMedia PL 1.0
assert_eq!(capability_license(CAP_IMAGE_JP2), Some(RoyaltyFree)); // ITU-T 2.1 Part 1
assert_eq!(capability_license(CAP_MESH_DRACO), Some(RoyaltyFree)); // Apache-2.0
assert_eq!(capability_license(CAP_META_HDR10PLUS), Some(RoyaltyFree));
assert_eq!(capability_license(CAP_AUDIO_IVAS), Some(PatentPool)); // voice-codec pool
assert_eq!(capability_license(CAP_PC_GPCC), Some(PatentPool));
assert_eq!(capability_license(CAP_PC_VPCC), Some(PatentPool));
assert_eq!(capability_license(CAP_HAPTIC_MIHS), Some(PatentPool)); // conservative (MPEG)
assert_eq!(capability_license(CAP_AUDIO_AC4), Some(Proprietary)); // single licensor
assert_eq!(capability_license(CAP_META_DOVI), Some(Proprietary)); // single licensor
assert_eq!(capability_license(CAP_SEMANTIC_PERCO2), Some(NonCommercial)); // CC-BY-NC-SA
// Unknown → no class.
assert_eq!(capability_license("wai.image.nope"), None);
assert!(!is_royalty_free("wai.image.nope"));
}
/// The broadcast and streaming codecs, each with the licence class recorded
/// September 2026 (sources and residual caveats: research/media-codec-registry.md)
/// and its replicate class. One row per capability so a reclassification is a
/// visible, reviewed diff.
const BROADCAST: &[(&str, LicenseClass, ReplicateClass)] = &[
// Video whose decoder conformance requires identical decoded samples
// (H.266/H.265 §C.5.1, H.264 §C.4, VP9 §8.1).
(CAP_VIDEO_VVC, LicenseClass::PatentPool, ReplicateClass::StandardDefined), // H.266 pools + bilateral
(CAP_VIDEO_HEVC, LicenseClass::PatentPool, ReplicateClass::StandardDefined), // H.265 pools + bilateral
(CAP_VIDEO_AVC, LicenseClass::PatentPool, ReplicateClass::StandardDefined), // H.264 pool
(CAP_VIDEO_VP9, LicenseClass::RoyaltyFree, ReplicateClass::StandardDefined), // BSD + patent grant
// AV2 v1.0.0 §7.1: identical output unless film grain is signalled, then a
// perceptual criterion — as AV1.
(CAP_VIDEO_AV2, LicenseClass::RoyaltyFree, ReplicateClass::StandardTolerance), // AOMedia Patent License 1.0
// Conformance documents not read: the conservative class.
(CAP_VIDEO_EVC, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // Main-profile FRAND holders
(CAP_VIDEO_EVC_BASELINE, LicenseClass::RoyaltyFree, ReplicateClass::StandardUnclassified), // RF by design (caveat)
(CAP_VIDEO_AVS3, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // AVS patent pool
(CAP_VIDEO_LCEVC, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // SEP licence, royalties
(CAP_AUDIO_MPEGH, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // MPEG-H 3D Audio pool
(CAP_AUDIO_AVS3, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // AVS patent pool
// Measured: three decoders give three different PCM streams.
(CAP_AUDIO_AAC, LicenseClass::PatentPool, ReplicateClass::StandardUnclassified), // AAC pool
];
#[test]
fn broadcast_codecs_are_registered_classified_and_sink_supplied() {
for &(c, class, replicate) in BROADCAST {
assert!(is_known_capability(c), "{c} not registered");
assert_eq!(capability_license(c), Some(class), "{c} licence class");
assert_eq!(is_royalty_free(c), class == LicenseClass::RoyaltyFree, "{c}");
// Lossy distribution role.
assert_eq!(capability_tier(c), Some(FidelityTier::Lossy), "{c} tier");
// Replication: pinned per row. No model is involved; the split is what
// the named standard's decoder conformance fixes, as far as it was read.
assert_eq!(capability_replicate_class(c), Some(replicate), "{c} replicate class");
assert_eq!(is_cross_decoder_exact(c), replicate == ReplicateClass::StandardDefined, "{c}");
// Registration is not a bundled decoder: every one is sink-supplied.
assert!(!sink_capabilities().contains(&c), "{c} must not claim native decode");
}
// Every broadcast capability string is in the video or audio class, and
// no broadcast audio codec claims a cross-decoder-exact reconstruction.
for &(c, _, replicate) in BROADCAST {
assert!(c.starts_with("wai.video.") || c.starts_with("wai.audio."), "{c}");
if c.starts_with("wai.audio.") {
assert_ne!(replicate, ReplicateClass::StandardDefined, "{c}");
}
}
}
#[test]
fn licence_classification_is_exhaustive_with_no_default() {
// Every registered capability is classified by an explicit arm...
for &c in known_capabilities() {
assert!(capability_license(c).is_some(), "{c} is registered but unclassified");
}
// ...and the non-royalty-free set is exactly what the registry says it
// is — adding a pool / proprietary / non-commercial capability, or
// reclassifying one, has to change this list in review.
let mut non_rf: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| !is_royalty_free(c)).collect();
non_rf.sort_unstable();
let mut want = vec![
CAP_AUDIO_AC4, CAP_META_DOVI,
CAP_AUDIO_IVAS, CAP_PC_GPCC, CAP_PC_VPCC, CAP_HAPTIC_MIHS,
CAP_SEMANTIC_PERCO2,
CAP_VIDEO_VVC, CAP_VIDEO_HEVC, CAP_VIDEO_AVC, CAP_VIDEO_EVC, CAP_VIDEO_LCEVC,
CAP_VIDEO_AVS3, CAP_AUDIO_MPEGH, CAP_AUDIO_AVS3, CAP_AUDIO_AAC,
// NNC (ISO/IEC 15938-17): royalty status not established, so pooled.
CAP_PRIOR_NNC, CAP_TENSOR_NNC,
// A candidate whose format is not pinned: provisional, conservative.
CAP_SPLAT_SOG,
];
want.sort_unstable();
assert_eq!(non_rf, want);
// No candidate is royalty-free: the licensing of a format no revision has
// pinned is not established (SPEC §5, Licence classes).
for &c in known_capabilities() {
if registry::is_candidate(c) {
assert!(!is_royalty_free(c), "{c} is a candidate, so its class cannot be royalty-free");
}
}
}
#[test]
fn defaults_are_royalty_free_and_never_pool_or_proprietary() {
// The floor and the recommended set are the defaults; the native sink
// decodes exactly those. SPEC §5 and the code agree on the list.
let mut defaults: Vec<&str> = mandatory_floor().iter().chain(recommended_set()).copied().collect();
defaults.sort_unstable();
let mut native: Vec<&str> = sink_capabilities().to_vec();
native.sort_unstable();
assert_eq!(defaults, native, "floor ∪ recommended must equal the native sink set");
// Every default is royalty-free.
for &c in &defaults {
assert_eq!(capability_license(c), Some(LicenseClass::RoyaltyFree), "default {c}");
assert!(!is_companion_only(c), "default {c} must be a standalone payload");
}
// Stated the other way round: no pool, proprietary or non-commercial
// capability — including every new broadcast codec — is a default.
for &c in known_capabilities() {
if !is_royalty_free(c) {
assert!(!defaults.contains(&c), "{c} is not royalty-free and must never be a default");
}
}
// Royalty-free is necessary, not sufficient: AV2 is royalty-free but
// deliberately NOT a default until deployable decode exists (SPEC §5).
assert!(is_royalty_free(CAP_VIDEO_AV2));
assert!(!defaults.contains(&CAP_VIDEO_AV2));
}
#[test]
fn companion_only_and_enhancement_layers() {
// Companion-only: HDR dynamic metadata and the LCEVC enhancement layer.
for &c in &[CAP_META_HDR10PLUS, CAP_META_DOVI, CAP_VIDEO_LCEVC] {
assert!(is_known_capability(c));
assert!(is_companion_only(c), "{c} is companion-only");
}
// Enhancement layers are exactly LCEVC, and every one is companion-only.
let enh: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| is_enhancement_layer(c)).collect();
assert_eq!(enh, vec![CAP_VIDEO_LCEVC]);
for &c in &enh {
assert!(is_companion_only(c));
}
// LCEVC's registered base codecs are standalone payloads.
for &c in &[CAP_VIDEO_AVC, CAP_VIDEO_HEVC, CAP_VIDEO_VVC, CAP_VIDEO_EVC, CAP_VIDEO_VP9, CAP_VIDEO_AV1] {
assert!(!is_companion_only(c), "{c} is a base, not a companion");
}
// IAMF carries its own audio substreams: standalone, never companion-only.
assert!(!is_companion_only(CAP_AUDIO_IAMF));
assert!(!is_companion_only("wai.image.nope"));
}
/// Test 16: every refinement-only capability is complete in the registry, and
/// *Base admission* is one table. Each refinement has the residual form, its
/// admitted bases (pinned here in both directions), the royalty-free licence, the
/// StandardDefined class, the Lossy tier, the refinement kind and role; none is a
/// candidate, a companion, dispatchable or in the video media class; and it is as
/// exact as the base it refines. LCEVC's bases are its row of the same table:
/// `enhancement_bases` and `companion_applies_to` read it, and no other string has
/// an applied form.
#[test]
fn refinement_registry_is_complete() {
use registry::{capability_kind, capability_role, Kind};
let pinned: &[(&str, &[&str])] = &[
(CAP_IMAGE_INT_REFINE, &[CAP_NEURAL_INT_HYPER, CAP_NEURAL_INT_MLICPP, CAP_NEURAL_INT_SYNTH, CAP_IMAGE_PNG]),
(CAP_VIDEO_INT_REFINE, &[CAP_VIDEO_INT_MOTION, CAP_VIDEO_INT_HYPER]),
(CAP_AUDIO_INT_REFINE, &[CAP_AUDIO_INT_CODEC, CAP_AUDIO_FLAC]),
(CAP_SPLAT_INT_REFINE, &[CAP_SPLAT_INT_CODEC]),
];
let refinements: Vec<&str> = known_capabilities().iter().copied().filter(|c| is_refinement_only(c)).collect();
assert_eq!(refinements, pinned.iter().map(|(c, _)| *c).collect::<Vec<_>>());
for &(cap, bases) in pinned {
assert_eq!(applied_form(cap), Some(AppliedForm::Residual), "{cap}");
assert_eq!(admitted_bases(cap), bases, "{cap}");
assert_eq!(capability_license(cap), Some(LicenseClass::RoyaltyFree), "{cap}");
assert_eq!(capability_replicate_class(cap), Some(ReplicateClass::StandardDefined), "{cap}");
assert_eq!(capability_tier(cap), Some(FidelityTier::Lossy), "{cap}");
assert_eq!(capability_kind(cap), Some(Kind::Refinement), "{cap}");
assert_eq!(capability_role(cap), Some("refinement"), "{cap}");
assert!(!is_candidate(cap) && !is_companion_only(cap) && !is_dispatchable(cap), "{cap}");
assert!(!is_video_class(cap) && pinned_int_payload(cap).is_none(), "{cap}");
assert!(!decodes_against_parameter_set(cap), "{cap}: a refinement reads no parameter set");
assert!(!is_cross_decoder_exact(cap), "{cap}: exact only given its base");
for &other in known_capabilities() {
assert_eq!(admits(cap, other), bases.contains(&other), "{cap} over {other}");
assert_eq!(is_cross_decoder_exact_with_sources(cap, &[other]),
bases.contains(&other) && is_cross_decoder_exact(other), "{cap} over {other}");
assert!(!companion_applies_to(other, cap), "no companion applies to {cap}");
}
}
// LCEVC: one row of the same table, with the bases SPEC §5 lists.
assert_eq!(applied_form(CAP_VIDEO_LCEVC), Some(AppliedForm::Enhancement));
assert_eq!(enhancement_bases(CAP_VIDEO_LCEVC), admitted_bases(CAP_VIDEO_LCEVC));
assert_eq!(admitted_bases(CAP_VIDEO_LCEVC), LCEVC_BASES);
for &b in known_capabilities() {
assert_eq!(companion_applies_to(CAP_VIDEO_LCEVC, b), admits(CAP_VIDEO_LCEVC, b), "{b}");
}
// No other string has an applied form, and the table names each once.
let applied: Vec<&str> = known_capabilities().iter().copied().filter(|c| applied_form(c).is_some()).collect();
assert_eq!(applied.len(), pinned.len() + 1);
assert_eq!(BASE_ADMISSION.len(), applied.len());
assert!(applied_form("wai.image.nope").is_none() && admitted_bases("wai.image.nope").is_empty());
}
/// SPEC §5 and §7.1, rule 2: what each companion-only capability applies to.
/// Pinned in both directions, so widening or narrowing a base set is a
/// reviewed change to this test.
#[test]
fn companions_apply_only_to_the_bases_their_registration_names() {
// The video media class, pinned: every standalone wai.video.* capability,
// the neural video codecs SPEC §5 lists under *Video:*, and the films.
let mut video: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| c.starts_with("wai.video.") && !is_companion_only(c) && !is_refinement_only(c)).collect();
assert!(video.contains(&CAP_VIDEO_J2K) && video.contains(&CAP_VIDEO_AV2));
video.extend([CAP_NEURAL_VIDEO_BMSHJ2018, CAP_NEURAL_DCVC_RT, CAP_NEURAL_DCVC_FM,
CAP_FILM_LINEAR, CAP_FILM_REEL]);
video.sort_unstable();
let mut class: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| is_video_class(c)).collect();
class.sort_unstable();
assert_eq!(class, video, "the video media class");
// HDR dynamic metadata was registered as a companion to a video payload:
// it applies to every video-class capability and to nothing else.
for &hdr in &[CAP_META_HDR10PLUS, CAP_META_DOVI] {
for &base in known_capabilities() {
let want = video.contains(&base);
assert_eq!(companion_applies_to(hdr, base), want, "{hdr} on {base}");
}
// A base this revision does not register is not constrained: its class
// is unknown here, so a later revision's video codec, in any namespace,
// is already accepted.
for base in ["wai.video.future", "wai.neural.video_future"] {
assert!(!is_video_class(base));
assert!(companion_applies_to(hdr, base), "{hdr} on unregistered {base}");
}
// Never an audio, image, volumetric or world payload, nor a companion.
for base in [CAP_AUDIO_OPUS, CAP_AUDIO_AAC, CAP_AUDIO_IAMF, CAP_IMAGE_AVIF,
CAP_IMAGE_JP2, CAP_NEURAL_GLC, CAP_SPLAT_4D, CAP_WORLD_REPLAY,
CAP_PC_VPCC, CAP_VIDEO_LCEVC, CAP_META_DOVI] {
assert!(!companion_applies_to(hdr, base), "{hdr} must not apply to {base}");
}
}
// LCEVC: exactly the base codecs SPEC §5 names, among registered capabilities.
let mut lcevc: Vec<&str> = known_capabilities().iter().copied()
.filter(|b| companion_applies_to(CAP_VIDEO_LCEVC, b)).collect();
lcevc.sort_unstable();
let mut want = vec![
CAP_VIDEO_AVC, CAP_VIDEO_HEVC, CAP_VIDEO_VVC, CAP_VIDEO_EVC, CAP_VIDEO_EVC_BASELINE,
CAP_VIDEO_VP9, CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS,
];
want.sort_unstable();
assert_eq!(lcevc, want);
assert_eq!(enhancement_bases(CAP_VIDEO_LCEVC).len(), want.len());
// Registered video codecs outside LCEVC's registered bases, and an unregistered one.
for base in [CAP_VIDEO_J2K, CAP_VIDEO_AV2, CAP_VIDEO_AVS3, CAP_VIDEO_INT_MOTION,
CAP_VIDEO_INT_HYPER, CAP_VIDEO_LCEVC, "wai.video.future"] {
assert!(!companion_applies_to(CAP_VIDEO_LCEVC, base), "LCEVC must not apply to {base}");
}
// Every base is a registered, standalone video capability.
for &b in enhancement_bases(CAP_VIDEO_LCEVC) {
assert!(is_known_capability(b) && !is_companion_only(b) && b.starts_with("wai.video."), "{b}");
}
assert!(enhancement_bases(CAP_META_HDR10PLUS).is_empty());
assert!(enhancement_bases(CAP_VIDEO_HEVC).is_empty());
// Rule 1: a standalone capability applies to nothing — it is never a
// companion. Neither does a capability this revision does not register.
for &c in known_capabilities() {
if is_companion_only(c) {
assert!(known_capabilities().iter().any(|b| companion_applies_to(c, b)),
"companion-only {c} applies to no registered capability");
} else {
assert!(!known_capabilities().iter().any(|b| companion_applies_to(c, b)),
"standalone {c} must apply to nothing");
}
}
assert!(!companion_applies_to("wai.meta.future", CAP_VIDEO_AV1));
}
#[test]
fn replicate_class_isolates_the_integer_entropy_contract() {
use ReplicateClass::*;
// No registered capability is unclassified.
for &c in known_capabilities() {
assert!(capability_replicate_class(c).is_some(), "{c} has no replicate class");
}
// The integer-exact neural decodes — sound for cross-hardware replicate by
// construction: int_synth (synthesis only) and int_hyper (the FULL
// conditional codec: integer hyper-decoder σ + integer entropy + synthesis).
// int_synth (synthesis), int_hyper (the full conditional codec),
// video.int_hyper (a learned int_hyper keyframe + integer inter-frames),
// and audio.int_codec (the learned 1-D audio transform codec).
for &c in &[CAP_NEURAL_INT_SYNTH, CAP_NEURAL_INT_HYPER, CAP_VIDEO_INT_HYPER, CAP_AUDIO_INT_CODEC, CAP_SPLAT_INT_CODEC,
CAP_NEURAL_INT_MLICPP] {
assert_eq!(capability_replicate_class(c), Some(NeuralIntegerExact), "{c}");
assert!(is_neural_integer_exact(c), "{c}");
}
// They are exactly the integer-exact subset (image, conditional, and video).
let mut nie: Vec<_> = known_capabilities().iter()
.filter(|c| is_neural_integer_exact(c)).copied().collect();
nie.sort_unstable();
let mut want = vec![CAP_NEURAL_INT_SYNTH, CAP_NEURAL_INT_HYPER, CAP_VIDEO_INT_HYPER, CAP_AUDIO_INT_CODEC, CAP_SPLAT_INT_CODEC,
CAP_NEURAL_INT_MLICPP];
want.sort_unstable();
assert_eq!(nie, want);
// The learned codecs that run float inference are not cross-hardware sound.
for &c in &[CAP_NEURAL_MLICPP, CAP_NEURAL_MLICV2, CAP_NEURAL_CMIC, CAP_NEURAL_ELIC, CAP_NEURAL_GLC,
CAP_NEURAL_MBT2018_MEAN, CAP_NEURAL_DCVC_FM, CAP_NEURAL_SNAC] {
assert_eq!(capability_replicate_class(c), Some(NeuralFloat), "{c}");
assert!(!is_neural_integer_exact(c), "{c} must not claim integer-exact");
}
// JPEG AI: integer entropy decode, float later stages → entropy-consistency
// only. It is the only capability in that class, and it is NOT
// standard-defined: its reconstruction runs float stages WAI introduces.
assert_eq!(capability_replicate_class(CAP_IMAGE_JPEGAI), Some(NeuralEntropyExact));
assert!(!is_neural_integer_exact(CAP_IMAGE_JPEGAI));
let entropy_only: Vec<_> = known_capabilities().iter().copied()
.filter(|c| capability_replicate_class(c) == Some(NeuralEntropyExact)).collect();
assert_eq!(entropy_only, vec![CAP_IMAGE_JPEGAI]);
// The lossless floor formats and the deterministic-floor WAI-native classes
// are standard-defined (reconstruction specified exactly, not by a model
// WAI runs).
for &c in &[CAP_IMAGE_PNG, CAP_AUDIO_FLAC, CAP_TEXT_ZSTD,
CAP_WORLD_REPLAY, CAP_AUDIO_SCORE, CAP_FILM_REEL, CAP_QUANTUM_CIRCUIT,
CAP_QUANTUM_CIRCUIT2] {
assert_eq!(capability_replicate_class(c), Some(StandardDefined), "{c}");
assert!(!is_neural_integer_exact(c), "{c} is not a neural decode");
}
// No `wai.neural.*` capability is in a standard class.
for &c in known_capabilities().iter().filter(|c| c.starts_with("wai.neural.")) {
let class = capability_replicate_class(c);
for std_class in [StandardDefined, StandardTolerance, StandardUnclassified] {
assert_ne!(class, Some(std_class), "{c}");
}
}
// The semantic path reproduces nothing byte-wise (similarity only).
assert_eq!(capability_replicate_class(CAP_SEMANTIC_CLIP), Some(Behavioral));
// The create-side quadrant: a DETERMINISTIC generator is byte-exact
// (generation-equivalence), distinct from both Behavioral (similarity) and
// the neural-decode classes — it generates, it does not reconstruct.
assert_eq!(capability_replicate_class(CAP_GENERATE_SPECTRAL), Some(GenerativeDeterministic));
assert!(!is_neural_integer_exact(CAP_GENERATE_SPECTRAL), "generation is not a neural decode");
assert_ne!(capability_replicate_class(CAP_GENERATE_SPECTRAL), Some(Behavioral), "deterministic, not similarity");
// Unknown → no class.
assert_eq!(capability_replicate_class("wai.image.nope"), None);
assert!(!is_neural_integer_exact("wai.image.nope"));
}
#[test]
fn neural_classes_map_onto_the_determinism_tiers() {
use DeterminismTier::*;
use ReplicateClass::*;
assert_eq!(NeuralIntegerExact.neural_tier(), Some(DecodeEquivalence));
assert_eq!(NeuralEntropyExact.neural_tier(), Some(EntropyConsistency));
for c in [NeuralFloat, StandardDefined, StandardTolerance, StandardUnclassified,
GenerativeDeterministic, Behavioral] {
assert_eq!(c.neural_tier(), None, "{c:?}");
}
assert_eq!(capability_replicate_class(CAP_IMAGE_JPEGAI).and_then(ReplicateClass::neural_tier),
Some(EntropyConsistency));
assert_eq!(capability_replicate_class(CAP_NEURAL_INT_HYPER).and_then(ReplicateClass::neural_tier),
Some(DecodeEquivalence));
// Labels are distinct (the CLI column must tell the classes apart).
let labels: std::collections::HashSet<_> = [StandardDefined, StandardTolerance,
StandardUnclassified, NeuralIntegerExact, NeuralEntropyExact,
GenerativeDeterministic, NeuralFloat, Behavioral]
.iter().map(|c| c.label()).collect();
assert_eq!(labels.len(), 8);
}
/// SPEC §7: a standard codec is classed by what its named standard's decoder
/// conformance fixes, and `replicate` over it promises that and no more. A codec
/// whose standard conforms decoders to anything but identical output must not
/// sit in the class that promises the same bytes on every sink.
#[test]
fn tier_claims_and_parameter_set_shapes() {
use crate::container::Prior;
let pin = |tier: &str| {
let mut p = Prior::new("m", "ab".repeat(32), "int");
p.tier = Some(tier.into());
p
};
assert!(tier_exceeds_class(CAP_IMAGE_JPEGAI, &pin("decode-equivalence")));
assert!(tier_exceeds_class(CAP_NEURAL_BMSHJ2018, &pin("entropy-consistency")));
assert!(!tier_exceeds_class(CAP_IMAGE_JPEGAI, &pin("entropy-consistency")));
assert!(!tier_exceeds_class(CAP_NEURAL_INT_SYNTH, &pin("none")));
assert!(!tier_exceeds_class(CAP_IMAGE_JPEGAI, &pin("decode_equivalence")), "unregistered reads as none");
assert!(!tier_exceeds_class(CAP_IMAGE_JPEGAI, &Prior::new("m", "ab", "int")), "no tier, no claim");
assert!(!tier_exceeds_class("wai.neural.future", &pin("decode-equivalence")));
// The closed vocabulary: one table, round-tripping, ordered.
for &(tok, t) in TIER_TOKENS {
assert_eq!(DeclaredTier::from_token(tok), Some(t));
assert_eq!(t.token(), tok);
assert!(tok.chars().all(|c| c.is_ascii_lowercase() || c == '-'), "{tok} is kebab-case");
}
assert!(DeclaredTier::None < DeclaredTier::EntropyConsistency
&& DeclaredTier::EntropyConsistency < DeclaredTier::DecodeEquivalence);
assert_eq!(DeterminismTier::DecodeEquivalence.token(), "decode-equivalence");
assert_eq!(DeterminismTier::from_token("none"), None);
// Shapes: Some exactly for the capabilities that decode against a parameter
// set, OneFile exactly for the capabilities SPEC §5 registers as one file.
let mut one_file = Vec::new();
for &c in known_capabilities() {
assert_eq!(parameter_set_shape(c).is_some(), decodes_against_parameter_set(c), "{c}");
if parameter_set_shape(c) == Some(ParameterSetShape::OneFile) {
one_file.push(c);
}
}
one_file.sort_unstable();
let mut want = vec![CAP_NEURAL_INT_SYNTH, CAP_NEURAL_INT_MLICPP, CAP_AUDIO_INT_CODEC, CAP_SPLAT_INT_CODEC,
CAP_NEURAL_ENCODEC32, CAP_NEURAL_DAC, CAP_NEURAL_MIMI, CAP_NEURAL_WAVTOKENIZER,
CAP_NEURAL_SNAC, CAP_NEURAL_VIDEO_BMSHJ2018];
want.sort_unstable();
assert_eq!(one_file, want);
for c in [CAP_IMAGE_PNG, CAP_SEMANTIC_CLIP, CAP_PRIOR_SET, CAP_WORLD_MODEL] {
assert!(!decodes_against_parameter_set(c), "{c}");
}
for c in [CAP_IMAGE_JPEGAI, CAP_NEURAL_GLC, CAP_GENERATE_SPECTRAL, CAP_NEURAL_INT_HYPER, CAP_VIDEO_INT_HYPER] {
assert_eq!(parameter_set_shape(c), Some(ParameterSetShape::SeveralFiles), "{c}");
}
// The listing form: lossless, royalty-free, StandardDefined.
assert_eq!(capability_tier(CAP_PRIOR_SET), Some(FidelityTier::Lossless));
assert!(is_royalty_free(CAP_PRIOR_SET));
assert_eq!(capability_replicate_class(CAP_PRIOR_SET), Some(ReplicateClass::StandardDefined));
assert!(is_dispatchable(CAP_PRIOR_SET) && !is_dispatchable(CAP_VIDEO_LCEVC));
}
#[test]
fn standard_classes_follow_the_named_standards_decoder_conformance() {
use ReplicateClass::*;
let of = |class: ReplicateClass| {
let mut v: Vec<_> = known_capabilities().iter().copied()
.filter(|c| capability_replicate_class(c) == Some(class)).collect();
v.sort_unstable();
v
};
let sorted = |mut v: Vec<&'static str>| { v.sort_unstable(); v };
// Opus (RFC 6716 §6), JPEG (T.81 §7, A.3.3), JPEG XL (18181-3 §4.2),
// JPEG 2000 (15444-4), AV1/AVIF (AV1 §7.2 with film grain), AV2 (AV2
// v1.0.0 §7.1, likewise), IVAS (TS 26.252 V19.2.0 §7.2.1), IAMF.
assert_eq!(of(StandardTolerance), sorted(vec![
CAP_AUDIO_OPUS, CAP_IMAGE_JPEG, CAP_IMAGE_JXL, CAP_IMAGE_JP2, CAP_VIDEO_J2K,
CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS, CAP_IMAGE_AVIF, CAP_VIDEO_AV2,
CAP_AUDIO_IVAS, CAP_AUDIO_IAMF]));
// The sink-supplied standards and asset formats not yet classified —
// including every broadcast codec whose conformance document was not read.
assert_eq!(of(StandardUnclassified), sorted(vec![
CAP_VIDEO_EVC, CAP_VIDEO_EVC_BASELINE, CAP_VIDEO_AVS3, CAP_VIDEO_LCEVC,
CAP_AUDIO_MPEGH, CAP_AUDIO_AVS3, CAP_AUDIO_AAC, CAP_AUDIO_AC4,
CAP_MESH_DRACO, CAP_PC_GPCC, CAP_PC_VPCC,
CAP_SPLAT_SOG, CAP_HAPTIC_MIHS, CAP_META_HDR10PLUS, CAP_META_DOVI,
CAP_MESH_GLB, CAP_SPLAT_SPZ,
// NNC: reconstruction equality across decoders not established.
CAP_PRIOR_NNC, CAP_TENSOR_NNC]));
// Every natively decoded standard codec is classified: none is unclassified.
for &c in sink_capabilities() {
assert_ne!(capability_replicate_class(c), Some(StandardUnclassified), "{c}");
}
// The promise per class: byte-exact only where the reconstruction is
// specified exactly; the named standard's conformance for the other two.
assert_eq!(StandardDefined.replicate_promise(), Some(ReplicatePromise::ByteExact));
assert_eq!(NeuralIntegerExact.replicate_promise(), Some(ReplicatePromise::ByteExact));
for c in [StandardTolerance, StandardUnclassified] {
assert_eq!(c.replicate_promise(), Some(ReplicatePromise::NamedStandardConformance), "{c:?}");
}
for c in [NeuralEntropyExact, NeuralFloat, GenerativeDeterministic, Behavioral] {
assert_eq!(c.replicate_promise(), None, "{c:?}");
}
// A tolerance codec is not refused by the replicate rule: it carries no prior,
// and what it promises is its standard's conformance, not the same bytes.
for &c in &[CAP_AUDIO_OPUS, CAP_IMAGE_JPEG, CAP_VIDEO_AV1, CAP_AUDIO_AC4] {
assert_eq!(replicate_refusal(c, "replicate", None), None, "{c}");
}
}
/// SPEC §7: `replicate` promises decode-equivalence, so the registry class
/// decides, and a prior that merely *declares* an integer contract cannot
/// rescue a float or entropy-only capability.
#[test]
fn replicate_follows_the_registry_class_not_the_declared_prior() {
use crate::container::{DeterminismClass, Prior};
let p = |det: &str| Prior::new("m", "ab".repeat(32), det);
let integer = p("int-rans/p16+int-synth/i64");
let floaty = p("int-rans/p16+onnx-cpu-f32/1thread");
// Every registered capability, replicate with an integer-declared prior:
// allowed exactly for the classes that promise something — the integer-exact
// neural decodes and the three standard classes.
for &c in known_capabilities() {
let class = capability_replicate_class(c).unwrap();
let allowed = class.replicate_promise().is_some();
assert_eq!(allowed, matches!(class,
ReplicateClass::NeuralIntegerExact | ReplicateClass::StandardDefined
| ReplicateClass::StandardTolerance | ReplicateClass::StandardUnclassified),
"{c} ({class:?})");
assert_eq!(replicate_refusal(c, "replicate", Some(&integer)).is_none(), allowed, "{c} ({class:?})");
// Intents other than replicate are never constrained.
for intent in ["improve", "create"] {
assert_eq!(replicate_refusal(c, intent, Some(&floaty)), None, "{c} {intent}");
assert_eq!(replicate_refusal(c, intent, None), None, "{c} {intent}");
}
}
// The mis-declared prior: an integer contract over JPEG AI or a float codec
// is refused on the class, before the prior is read.
assert_eq!(replicate_refusal(CAP_IMAGE_JPEGAI, "replicate", Some(&integer)),
Some(ReplicateRefusal::Class(ReplicateClass::NeuralEntropyExact)));
assert_eq!(replicate_refusal(CAP_NEURAL_BMSHJ2018, "replicate", Some(&integer)),
Some(ReplicateRefusal::Class(ReplicateClass::NeuralFloat)));
assert_eq!(replicate_refusal(CAP_SEMANTIC_CLIP, "replicate", Some(&integer)),
Some(ReplicateRefusal::Class(ReplicateClass::Behavioral)));
assert_eq!(replicate_refusal(CAP_GENERATE_SPECTRAL, "replicate", Some(&integer)),
Some(ReplicateRefusal::Class(ReplicateClass::GenerativeDeterministic)));
// An integer-exact capability still needs its integer-exact prior.
assert_eq!(replicate_refusal(CAP_NEURAL_INT_SYNTH, "replicate", Some(&integer)), None);
assert_eq!(replicate_refusal(CAP_NEURAL_INT_SYNTH, "replicate", Some(&floaty)),
Some(ReplicateRefusal::Prior(crate::container::PriorRefusal::NotIntegerExact(DeterminismClass::FloatReproducible))));
assert_eq!(replicate_refusal(CAP_NEURAL_INT_SYNTH, "replicate", None),
Some(ReplicateRefusal::Prior(crate::container::PriorRefusal::Absent)));
// A standard-defined floor codec carries no prior and is not refused here.
assert_eq!(replicate_refusal(CAP_IMAGE_PNG, "replicate", None), None);
// An unregistered capability cannot back replicate.
assert_eq!(replicate_refusal("wai.image.nope", "replicate", Some(&integer)),
Some(ReplicateRefusal::Unregistered));
// The refusal says why, naming the tier.
let why = replicate_refusal(CAP_IMAGE_JPEGAI, "replicate", Some(&integer)).unwrap().to_string();
assert!(why.contains("entropy-consistency"), "{why}");
}
/// Every capability classed StandardDefined, with the evidence its class rests
/// on. The class promises the same bytes on every conforming sink (SPEC §7), so
/// a capability enters it only with a recorded basis: a conformance clause
/// that requires identical output, or the WAI extension whose equivalence pins
/// the reconstruction. Adding a row is a reviewed change. A capability classed
/// StandardDefined without a row here fails
/// `standard_defined_rests_on_recorded_evidence`; one that has no such basis
/// belongs in StandardUnclassified.
const STANDARD_DEFINED_EVIDENCE: &[(&str, &str)] = &[
(CAP_IMAGE_PNG, "lossless: decoding restores the encoded samples"),
(CAP_AUDIO_FLAC, "lossless: decoding restores the encoded samples"),
(CAP_TEXT_ZSTD, "lossless byte format: decoding restores the encoded bytes"),
(CAP_TEXT_XZ, "lossless byte format: decoding restores the encoded bytes"),
(CAP_VIDEO_AVC, "ITU-T H.264 (V16, 06/2026) §C.4: every output sample equals the HRD's"),
(CAP_VIDEO_HEVC, "ITU-T H.265 (V11, 01/2026) §C.5.1: every output sample equals the specified decoding process's"),
(CAP_VIDEO_VVC, "ITU-T H.266 (V4, 01/2026) §C.5.1: every output sample equals the specified decoding process's"),
(CAP_VIDEO_VP9, "VP9 Bitstream & Decoding Process Specification v0.6 §8.1: output frames identical in all respects"),
(CAP_VIDEO_INT_MOTION, "int_video.rs: pure-integer decode, frame-state-equivalence"),
(CAP_WORLD_SCENE, "extensions/interactive-worlds.md: replay-equivalence"),
(CAP_WORLD_REPLAY, "extensions/interactive-worlds.md: replay-equivalence"),
(CAP_WORLD_LIVE, "extensions/interactive-worlds.md: replay-equivalence"),
(CAP_WORLD_MODEL, "world_model.rs: replay-equivalence of the action trace (not the rendered frames)"),
(CAP_AUDIO_SCENE, "extensions/spatial-audio.md: mixdown-equivalence, given its sources' decoded PCM"),
(CAP_AUDIO_SCORE, "extensions/score.md: mixdown-equivalence"),
(CAP_HAPTIC_SIGNAL, "extensions/haptics.md: sample-equivalence"),
(CAP_FEED_STATE, "extensions/state-feeds.md: replay-equivalence"),
(CAP_AVATAR_POSE, "extensions/avatars.md: pose-equivalence"),
(CAP_SPLAT_4D, "extensions/volumetric.md: frame-state-equivalence"),
(CAP_FILM_LINEAR, "extensions/linear-film.md: film-equivalence"),
(CAP_FILM_REEL, "extensions/linear-film.md: reel-equivalence"),
(CAP_QUANTUM_CIRCUIT, "extensions/quantum-sim.md: statevector-equivalence"),
(CAP_QUANTUM_CIRCUIT2, "extensions/quantum-sim.md: statevector-equivalence"),
(CAP_TERNARY_TT, "extensions/ternary-tt.md: reconstruction-equivalence"),
(CAP_PRIOR_SET, "SPEC.md §3.1: a listing's bytes are fixed exactly and are their own output"),
(CAP_IMAGE_INT_REFINE, "extensions/staged-delivery.md §6.1: integer predictor, residual and clamp; staged-conformance"),
(CAP_VIDEO_INT_REFINE, "extensions/staged-delivery.md §6.1: integer predictor, residual and clamp; staged-conformance"),
(CAP_AUDIO_INT_REFINE, "extensions/staged-delivery.md §6.1: integer predictor, residual and clamp; staged-conformance"),
(CAP_SPLAT_INT_REFINE, "extensions/staged-delivery.md §6.1: integer predictor, residual and clamp; staged-conformance"),
];
/// Every capability classed NeuralIntegerExact, with the basis its class rests
/// on: the integer decode path that makes it byte-identical by construction, and
/// what pins that decode (a committed vector matched against an independent
/// integer reference, a cross-architecture golden). Where each was run is recorded
/// in `extensions/determinism-tiers.md` §6. A capability classed NeuralIntegerExact
/// without a row here fails `neural_integer_exact_rests_on_recorded_evidence`.
const NEURAL_INTEGER_EXACT_EVIDENCE: &[(&str, &str)] = &[
(CAP_NEURAL_INT_SYNTH, "int_synth.rs: integer synthesis; pinned by the byte-exact-conformance golden"),
(CAP_NEURAL_INT_HYPER, "int_hyper_synth.rs: integer hyper-decoder, bucketing, rANS and synthesis; pinned by the committed tiny vector and its keyframe golden in byte-exact-conformance"),
(CAP_VIDEO_INT_HYPER, "int_hyper_synth.rs + int_video.rs: an int_hyper keyframe, then integer P-frames; pinned by the neural-keyframe clip golden in byte-exact-conformance"),
(CAP_AUDIO_INT_CODEC, "int_audio.rs: integer synthesis over a factorized rANS latent; pinned by a committed vector against an independent Python integer reference"),
(CAP_SPLAT_INT_CODEC, "int_splat.rs: integer synthesis over a factorized rANS latent; pinned by a committed vector against an independent Python integer reference"),
(CAP_NEURAL_INT_MLICPP, "int_mlicpp.rs: integer hyper-decoder, entropy network, bucketing, rANS and synthesis; pinned by a committed vector against an independent Python integer reference and by its byte-exact-conformance golden; decode measured identical on macOS arm64 and wasm32-wasip2"),
];
#[test]
fn neural_integer_exact_rests_on_recorded_evidence() {
for &c in known_capabilities() {
if capability_replicate_class(c) == Some(ReplicateClass::NeuralIntegerExact) {
assert!(NEURAL_INTEGER_EXACT_EVIDENCE.iter().any(|&(e, _)| e == c),
"{c} is classed NeuralIntegerExact with no recorded basis");
}
}
for &(c, basis) in NEURAL_INTEGER_EXACT_EVIDENCE {
assert_eq!(capability_replicate_class(c), Some(ReplicateClass::NeuralIntegerExact), "{c}: {basis}");
assert!(basis.contains(".rs:"), "{c}: the basis names the decode path");
}
let mut rows: Vec<&str> = NEURAL_INTEGER_EXACT_EVIDENCE.iter().map(|&(c, _)| c).collect();
rows.sort_unstable();
rows.dedup();
assert_eq!(rows.len(), NEURAL_INTEGER_EXACT_EVIDENCE.len(), "duplicate evidence row");
}
#[test]
fn standard_defined_rests_on_recorded_evidence() {
use ReplicateClass::*;
// Every registered capability is classified by an explicit arm (the
// function has no default class; an unlisted one returns None).
for &c in known_capabilities() {
assert!(capability_replicate_class(c).is_some(), "{c} is registered but has no replicate class");
}
// The exact class is exactly the capabilities with a recorded basis.
for &c in known_capabilities() {
if capability_replicate_class(c) == Some(StandardDefined) {
assert!(STANDARD_DEFINED_EVIDENCE.iter().any(|&(e, _)| e == c),
"{c} is classed StandardDefined with no recorded evidence: record the \
conformance clause or extension that fixes its output, or class it \
StandardUnclassified");
}
}
for &(c, basis) in STANDARD_DEFINED_EVIDENCE {
assert_eq!(capability_replicate_class(c), Some(StandardDefined), "{c}: {basis}");
assert!(!basis.is_empty(), "{c}");
}
let mut rows: Vec<&str> = STANDARD_DEFINED_EVIDENCE.iter().map(|&(c, _)| c).collect();
rows.sort_unstable();
rows.dedup();
assert_eq!(rows.len(), STANDARD_DEFINED_EVIDENCE.len(), "duplicate evidence row");
// is_cross_decoder_exact is exactly StandardDefined ∪ NeuralIntegerExact,
// less the capabilities whose output depends on other envelopes' decode.
for &c in known_capabilities() {
let class = capability_replicate_class(c).unwrap();
assert_eq!(is_cross_decoder_exact(c),
matches!(class, StandardDefined | NeuralIntegerExact) && !composes_decoded_sources(c),
"{c}");
}
assert!(!is_cross_decoder_exact("wai.image.nope"));
// The mandatory floor reconstructs identically at every conforming sink.
for &c in mandatory_floor() {
assert!(is_cross_decoder_exact(c), "floor {c}");
}
// The same family can land on either side: the decoded pictures of the
// ITU-T video codecs are fixed by their conformance clauses, the AAC PCM
// is not established, and film-grain AV1 is held to a perceptual criterion.
assert!(is_cross_decoder_exact(CAP_VIDEO_AVC) && !is_cross_decoder_exact(CAP_AUDIO_AAC));
assert!(is_cross_decoder_exact(CAP_VIDEO_VP9) && !is_cross_decoder_exact(CAP_VIDEO_AV1));
assert!(is_cross_decoder_exact(CAP_AUDIO_FLAC) && !is_cross_decoder_exact(CAP_AUDIO_IAMF));
// The two classifications round one got wrong are not exact: a glTF binary
// may embed JPEG images and compressed geometry, and JPEG AI's reconstruction
// runs float stages that its standard does not fix.
assert!(!is_cross_decoder_exact(CAP_MESH_GLB));
assert!(!is_cross_decoder_exact(CAP_IMAGE_JPEGAI));
// Neither neural float nor a generator nor similarity is exact.
assert!(!is_cross_decoder_exact(CAP_NEURAL_DCVC_FM));
assert!(!is_cross_decoder_exact(CAP_GENERATE_SPECTRAL));
assert!(!is_cross_decoder_exact(CAP_SEMANTIC_CLIP));
}
/// A `wai.audio.scene` mixes the decoded PCM of sources carried in other
/// envelopes, so its class (StandardDefined: the mix is exact given that PCM)
/// does not make it portable by itself.
#[test]
fn a_scene_is_only_as_exact_as_its_sources() {
// The capabilities that compose other envelopes' decoded output: the scene,
// and the refinements, each exact given the base it refines.
let composing: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| composes_decoded_sources(c)).collect();
assert_eq!(composing, vec![CAP_AUDIO_SCENE, CAP_IMAGE_INT_REFINE, CAP_VIDEO_INT_REFINE,
CAP_AUDIO_INT_REFINE, CAP_SPLAT_INT_REFINE]);
assert_eq!(capability_replicate_class(CAP_AUDIO_SCENE), Some(ReplicateClass::StandardDefined));
// Not portable from the capability alone...
assert!(!is_cross_decoder_exact(CAP_AUDIO_SCENE));
// ...portable when every source is: lossless FLAC, the integer audio codec.
assert!(is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_FLAC]));
assert!(is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_FLAC, CAP_AUDIO_INT_CODEC]));
// One source whose standard admits a tolerance, or is unclassified, or is
// unregistered, and the mix is not.
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_FLAC, CAP_AUDIO_OPUS]));
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_AAC]));
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_NEURAL_ENCODEC32]));
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &["wai.audio.nope"]));
// A scene used as a source is not portable by itself either.
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_SCENE]));
// It answers false when it cannot tell. No sources: a scene with no
// objects cannot be told from a caller that resolved none.
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[]));
// A source outside wai.audio.* is not a scene source (spatial-audio §2.2),
// even when its own class is exact: a PNG image, AVC video, a WAI world.
for bad in [CAP_IMAGE_PNG, CAP_VIDEO_AVC, CAP_WORLD_REPLAY] {
assert!(is_cross_decoder_exact(bad), "{bad} is exact on its own");
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[bad]), "{bad}");
assert!(!is_cross_decoder_exact_with_sources(CAP_AUDIO_SCENE, &[CAP_AUDIO_FLAC, bad]), "{bad}");
}
// A capability that composes nothing ignores `sources`.
for &c in known_capabilities() {
if !composes_decoded_sources(c) {
assert_eq!(is_cross_decoder_exact_with_sources(c, &[CAP_AUDIO_OPUS]), is_cross_decoder_exact(c), "{c}");
assert_eq!(is_cross_decoder_exact_with_sources(c, &[]), is_cross_decoder_exact(c), "{c}");
}
}
// The replicate gate checks the one envelope it is given; the sources are
// envelopes of their own, each gated by its own class.
assert_eq!(replicate_refusal(CAP_AUDIO_SCENE, "replicate", None), None);
assert_eq!(replicate_refusal(CAP_AUDIO_FLAC, "replicate", None), None);
assert_eq!(replicate_refusal(CAP_AUDIO_OPUS, "replicate", None), None,
"opus backs replicate at its standard's tolerance, not byte identity");
}
/// `wai wrap` pins no prior, and used to write `intent = replicate` over every
/// capability, `wai.image.jpegai` included, against SPEC §7's MUST NOT. The
/// intent it writes now comes from `unpinned_envelope_intent`, which must agree
/// with the sink's check on the envelope it produces.
#[test]
fn an_unpinned_envelope_claims_replicate_only_where_a_sink_accepts_it() {
use crate::container::{Conditioning, Manifest, ModelRequirement, Wai};
let envelope = |cap: &str, intent: &str| Wai::new(
Manifest::new("binary", intent, ModelRequirement::new(cap), Conditioning::new("bytes")),
vec![],
);
for &c in known_capabilities() {
let class = capability_replicate_class(c).unwrap();
let default = unpinned_envelope_intent(c, None);
// Unpinned, `replicate` is written exactly over the standard classes.
assert_eq!(default.is_ok(), matches!(class,
ReplicateClass::StandardDefined | ReplicateClass::StandardTolerance
| ReplicateClass::StandardUnclassified), "{c} ({class:?})");
match &default {
// What the encoder writes, the sink's check accepts …
Ok(intent) => {
assert_eq!(*intent, "replicate", "{c}");
assert_eq!(envelope(c, intent).replicate_refusal(), None, "{c}");
}
// … and what it refuses is what the sink would refuse, for the same reason.
Err(why) => assert_eq!(envelope(c, "replicate").replicate_refusal(), Some(why.clone()), "{c}"),
}
// An explicit `replicate` is held to the same rule; any other intent passes.
assert_eq!(unpinned_envelope_intent(c, Some("replicate")), default, "{c}");
assert_eq!(unpinned_envelope_intent(c, Some("improve")), Ok("improve"), "{c}");
}
// The case that was wrong: JPEG AI is refused, and the refusal names its tier.
let why = unpinned_envelope_intent(CAP_IMAGE_JPEGAI, None).unwrap_err();
assert_eq!(why, ReplicateRefusal::Class(ReplicateClass::NeuralEntropyExact));
assert!(why.to_string().contains("entropy-consistency"), "{why}");
// A float neural codec and a generator are refused on their class.
assert_eq!(unpinned_envelope_intent(CAP_NEURAL_BMSHJ2018, None),
Err(ReplicateRefusal::Class(ReplicateClass::NeuralFloat)));
assert_eq!(unpinned_envelope_intent(CAP_GENERATE_SPECTRAL, None),
Err(ReplicateRefusal::Class(ReplicateClass::GenerativeDeterministic)));
assert_eq!(unpinned_envelope_intent(CAP_GENERATE_SPECTRAL, Some("create")), Ok("create"));
// An integer-exact neural codec backs replicate only with a pinned prior,
// which an unpinned envelope does not carry.
assert_eq!(unpinned_envelope_intent(CAP_NEURAL_INT_HYPER, None),
Err(ReplicateRefusal::Prior(crate::container::PriorRefusal::Absent)));
// Every capability `wai encode` writes (all with `replicate`, no prior) is
// one of the standard classes, so its envelopes stay acceptable.
for c in [CAP_IMAGE_PNG, CAP_IMAGE_JPEG, CAP_IMAGE_AVIF, CAP_IMAGE_JXL,
CAP_AUDIO_OPUS, CAP_AUDIO_FLAC, CAP_VIDEO_AV1, CAP_VIDEO_AV1_LOSSLESS,
CAP_TEXT_ZSTD, CAP_TEXT_XZ] {
assert_eq!(unpinned_envelope_intent(c, None), Ok("replicate"), "{c}");
}
// `wai wrap --companion` holds the intent over the base payload's
// capability and each companion's. Every companion-only capability
// registered today is in a standard class, so the companion check refuses
// nothing yet; this fails when one is registered in another class, which
// is when that check needs a test of its own.
let companions: Vec<&str> = known_capabilities().iter().copied()
.filter(|c| is_companion_only(c)).collect();
assert!(!companions.is_empty());
for c in companions {
assert_eq!(unpinned_envelope_intent(c, None), Ok("replicate"), "{c}");
}
}
}
Reference in a new issue View git blame Copy permalink