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 157
open-standards/wai/REGISTRY.md
Transaction Science 7fb55e8c17 wai: the refinement-only role, base admission as one table, and refines 
SPEC registers the residual refinement capabilities wai.image.int_refine,
wai.video.int_refine, wai.audio.int_refine and wai.splat.int_refine, each
refinement-only: applied in a declared order to the output of the stage
below it, bound to that output's producer by content hash, and never decoded
on its own. Section 4 never takes step 3 or 5 with one; section 8 adds the
role and lists the envelopes its registration makes non-conforming.

SPEC section 5's Base admission table holds the bases of every capability
applied to a base's output, the refinements and the LCEVC enhancement layer.
codecs::BASE_ADMISSION is that table; enhancement_bases, companion_applies_to
and admits read it, and no other admission logic remains.

The registry gains the refinement kind and role. A refinement is not
dispatchable, never selected, never a companion or a companion's base, and
not in the video media class; its class is StandardDefined and, like the
audio scene, it composes another envelope's decoded output, so it is as
exact as the base it refines. The registry export is regenerated.

A WAI1 manifest gains the optional member refines, kept as JSON so a
malformed value still parses; container::Refines reads it and reports
refines-malformed. Wai::check_component_roles reports a refinement without
refines, with a fallback, as a fallback, and refines on any other capability.
The emit paths parse a refinement's WIR1 payload.

extensions/staged-delivery.md defines stage sets, the refines member, the
per-unit application algorithm with its closed list of reasons, holds and
batches, tiers and stage hashes, the residual form, deferral, live deadlines,
attestation, byte counting, and the WIR1 payload with its check order, caps,
declared cost and refusal codes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-02 00:02:12 -04:00

253 lines
24 KiB
Markdown
Raw Permalink Blame History

# WAI registry
The registry is the set of strings [SPEC §5](SPEC.md) registers, with the classes
the specification gives each one. Its source of truth is one table in the
reference implementation, [`wai-rs/src/codecs/registry.rs`](wai-rs/src/codecs/registry.rs)
together with the class functions of [`wai-rs/src/codecs/mod.rs`](wai-rs/src/codecs/mod.rs).
`wai registry export` writes it out in machine-readable form:
| file | what |
|---|---|
| [`registry/capabilities.json`](registry/capabilities.json) | every registered string with its kind, status, media class, role, fidelity tier, licence class, replicate class, set membership, registering section, edition and registration date; the named identifiers that are not capabilities; the unregistered labels |
| [`registry/capabilities.schema.json`](registry/capabilities.schema.json) | JSON Schema (2020-12) for that file; its enums are the label sets below |
| [`vocab/v2.ttl`](vocab/v2.ttl), [`vocab/v2.jsonld`](vocab/v2.jsonld), [`vocab/v2.shapes.ttl`](vocab/v2.shapes.ttl) | the same registry as RDF, a JSON-LD context for manifests, and a SHACL shape that checks a manifest's capability and fallback against it, only the form of its media, and its parameter-set pins (`vocab/README.md`); a violation for a string the registry does not hold means the string is not registered in this revision, not that the envelope fails to conform or cannot be dispatched (SPEC §4, §8) |
| the table at the end of this file | the same registry, for reading |
A library test (`codecs::registry::tests::registry_export_matches_committed`) and
a CI step (`wai registry export --check` in `.github/workflows/wai-conformance.yml`)
fail when a committed file differs from what the table renders. Edit the table,
never the exported files.
## Kinds
Every registered string has one kind.
- **payload** — a capability whose payload a sink decodes: it may be a `WAI1`
`capability` or `fallback`, or a `WAI2` rendition.
- **companion** — a companion-only capability (SPEC §5, §7.1): its payload is
applied with a base rendition and never on its own, so it is only ever a `WAI2`
companion.
- **refinement** — a refinement-only capability (SPEC §5, *Refinement
capabilities*): its payload is applied to the output of the stage below it,
bound to that output's producer by content hash, and never decoded on its own.
It is a `WAI1` `capability` with `refines`, or a `WAI2` component with
`role: "refinement"` ([staged-delivery](extensions/staged-delivery.md)). The
bases each one applies over are SPEC §5's *Base admission* table, which also
holds the bases of the enhancement layer `wai.video.lcevc`.
- **derivation** — an operation of ISO/IEC 23001-16 (`wai.derive.*`,
[derived-tracks](extensions/derived-tracks.md)). It acts on samples another
capability decoded and names no payload format.
- **record** — a signed record a WAI tool emits and verifies (a receipt kind:
`wai.asset.provenance`, the quantum-operations receipts, the delivery records
`wai.video.manifest` and its siblings). It names no payload format.
A derivation or record string is not a payload capability, so it is not
dispatchable (SPEC §4): dispatch never takes an envelope's capability that names
one, and step 5 may still take a usable fallback. A refinement is not dispatchable
either; staged-delivery §4 processes it.
Two further tables hold strings that look like capabilities and are not:
- **identifiers** name a part of a capability's definition (`wai.det.fixed64`, the
fixed-point floor; `wai.world.sim.*`, the simulation steps of the feed and avatar
capabilities);
- **unregistered labels** are strings the reference implementation uses as labels
that no revision registers, each with the reason.
## Status
- **registered** — the payload format (for a record or derivation, the
definition) is pinned. The WAI-native integer codecs `wai.video.int_motion`,
`wai.video.int_hyper`, `wai.neural.int_hyper`, `wai.audio.int_codec` and
`wai.splat.int_codec` were registered with a decoder and no byte layout (the first,
the fourth and the fifth also with the tool that wrote their bitstreams); v0.4.0
completes their registrations by pinning their formats (SPEC §8, *Completing a
registration*; SPEC §5, *Payloads of the WAI-native integer codecs*).
- **candidate** — the string is registered but no revision has pinned its payload
format. An encoder MUST NOT emit a candidate, and a sink MUST treat it as
unsupported (SPEC §5, *Candidate capabilities*). The reference implementation
lists candidates in `codecs::is_candidate`, reports an envelope that names one
from `Wai::check_candidates` and `WaiMulti::check_candidates`, and never
dispatches or selects one.
Every dispatch and selection function uses one predicate,
`codecs::is_dispatchable(cap)`, SPEC §4's *dispatchable*: false for a
companion-only capability, a refinement-only capability, a candidate, a record and
a derivation; true for a
registered payload capability that is not a candidate, and for a string this
revision does not register, which a later MINOR revision may register (SPEC §8)
and which a sink decodes only if it advertises it. A new dispatch or selection
function MUST use it too.
## Editions
A registration that names an edition of its standard carries that edition. A
registration that names none carries the edition of its named standard current on
the date it was registered, and no later edition or amendment: a later edition or
amendment that changes the bitstream gets a capability string of its own
(SPEC §8, *Editions*). The export records both: `edition` (a designation, or
`null` for the edition current on the registration date) and `registered` (the
date of the first commit of this repository that registers the string; the
specification entered the repository on 2026-06-12, so a string registered before
then carries that date).
## Licence classes
Every payload, companion and refinement capability carries a licence class:
`royalty-free`, `patent-pool`, `proprietary` or `non-commercial`
(`codecs::capability_license`). It is a property of the capability, not a
per-file claim. The classification has no default: a capability registered
without a class is a registry defect the tests reject. The sources and residual
caveats for each class are in
[`research/media-codec-registry.md`](research/media-codec-registry.md). A
capability whose royalty status is not established is classified conservatively
(`patent-pool`), never `royalty-free`; a candidate's class is provisional until a
revision pins its payload format, since the licensing of a format not yet chosen
cannot be established. Every
derivation operation carries the class `codecs::derivation::derivation_license`
gives it; a record carries none.
## How to register a string
1. Add the capability constant to `wai-rs/src/codecs/mod.rs` and, for a payload,
companion or refinement capability, list it in `known_capabilities()` and give it an arm in
`capability_tier`, `capability_license` and `capability_replicate_class` (each
function has no default, and the tests reject a registered capability without
one). A record goes in `RECORDS`, a derivation in `codecs::derivation`.
2. Give it a row in `ROWS` of `wai-rs/src/codecs/registry.rs`: the SPEC §5 heading
it is registered under, the edition it carries, and the registration date. A
string whose payload format is not yet pinned also goes in `CANDIDATES`.
3. Register it in SPEC §5, under that heading, with its payload format and role.
The test `spec_and_registry_name_the_same_strings` holds SPEC and the table to
the same set of strings, in both directions.
4. Run `cargo run --no-default-features --bin wai -- registry export` from
`wai/wai-rs`, and commit the files it writes.
5. Link it from the codec glossary entry that describes its bitstream, or list it
in the glossary's `GLOSSARY_NO_ENTRY` table with the reason
([`glossary/SCHEMA.md`](glossary/SCHEMA.md)).
6. Add a CHANGELOG entry.
Changing what a registered string carries is governed by SPEC §8: a payload format
and a role are fixed once registered.
## The registry
<!-- generated: wai registry export; do not edit by hand -->
| string | kind | status | media | role | licence | replicate | sets | registered in |
|---|---|---|---|---|---|---|---|---|
| `wai.asset.provenance` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.audio.aac` | payload | registered | audio | standalone | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.audio.ac4` | payload | registered | audio | standalone | proprietary | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.audio.avs3` | payload | registered | audio | standalone | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.audio.flac` | payload | registered | audio | standalone | royalty-free | standard-defined | floor | §5 Mandatory floor |
| `wai.audio.iamf` | payload | registered | audio | standalone | royalty-free | standard-tolerance | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.audio.int_codec` | payload | registered | audio | standalone | royalty-free | neural-int-exact | — | §5 Interactive, temporal & computed content |
| `wai.audio.int_refine` | refinement | registered | audio | refinement | royalty-free | standard-defined | — | §5 Refinement capabilities (staged delivery) |
| `wai.audio.ivas` | payload | registered | audio | standalone | patent-pool | standard-tolerance | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.audio.mpegh` | payload | registered | audio | standalone | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.audio.opus` | payload | registered | audio | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.audio.scene` | payload | registered | audio | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.audio.score` | payload | registered | audio | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.avatar.pose` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.derive.crop` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.dissolve` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.grid_composition` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.identity` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.mirror` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.overlay_composition` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.roi_selection` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.rotation` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.scaling` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.derive.srgb_fill` | derivation | registered | — | — | patent-pool | — | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.feed.state` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.film.linear` | payload | registered | video | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.film.reel` | payload | registered | video | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.generate.spectral` | payload | registered | image | standalone | royalty-free | generative-exact | — | §5 Neural capabilities |
| `wai.haptic.mihs` | payload | registered | haptic | standalone | patent-pool | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.haptic.signal` | payload | registered | haptic | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.image.avif` | payload | registered | image | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.image.int_refine` | refinement | registered | image | refinement | royalty-free | standard-defined | — | §5 Refinement capabilities (staged delivery) |
| `wai.image.jp2` | payload | registered | image | standalone | royalty-free | standard-tolerance | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.image.jpeg` | payload | registered | image | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.image.jpegai` | payload | registered | image | standalone | royalty-free | neural-entropy-exact | — | §5 Neural capabilities |
| `wai.image.jxl` | payload | registered | image | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.image.png` | payload | registered | image | standalone | royalty-free | standard-defined | floor | §5 Mandatory floor |
| `wai.mesh.draco` | payload | registered | volumetric | standalone | royalty-free | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.mesh.glb` | payload | registered | volumetric | standalone | royalty-free | standard-unclassified | — | §5 Interactive, temporal & computed content |
| `wai.meta.dovi` | companion | registered | metadata | companion | proprietary | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.meta.hdr10plus` | companion | registered | metadata | companion | royalty-free | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.neural.bmshj2018` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.cmic` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.dac` | payload | registered | audio | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.dcvc_fm` | payload | registered | video | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.dcvc_rt` | payload | registered | video | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.elic` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.encodec32` | payload | registered | audio | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.glc` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.int_hyper` | payload | registered | image | standalone | royalty-free | neural-int-exact | — | §5 Neural capabilities |
| `wai.neural.int_mlicpp` | payload | registered | image | standalone | royalty-free | neural-int-exact | — | §5 Neural capabilities |
| `wai.neural.int_synth` | payload | registered | image | standalone | royalty-free | neural-int-exact | — | §5 Neural capabilities |
| `wai.neural.mbt2018_mean` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.mimi` | payload | registered | audio | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.mlicpp` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.mlicv2` | payload | registered | image | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.snac` | payload | registered | audio | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.video_bmshj2018` | payload | registered | video | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.neural.wavtokenizer` | payload | registered | audio | standalone | royalty-free | neural-float | — | §5 Neural capabilities |
| `wai.pc.gpcc` | payload | registered | volumetric | standalone | patent-pool | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.pc.vpcc` | payload | registered | volumetric | standalone | patent-pool | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.prior.nnc` | payload | registered | binary | standalone | patent-pool | standard-unclassified | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.prior.set` | payload | registered | binary | standalone | royalty-free | standard-defined | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.quantum.calibration` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.quantum.circuit` | payload | registered | binary | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.quantum.job` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.semantic.clip` | payload | registered | image | standalone | royalty-free | behavioral | — | §5 Neural capabilities |
| `wai.semantic.perco2` | payload | registered | image | standalone | non-commercial | behavioral | — | §5 Neural capabilities |
| `wai.splat.4d` | payload | registered | volumetric | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.splat.int_codec` | payload | registered | volumetric | standalone | royalty-free | neural-int-exact | — | §5 Interactive, temporal & computed content |
| `wai.splat.int_refine` | refinement | registered | volumetric | refinement | royalty-free | standard-defined | — | §5 Refinement capabilities (staged delivery) |
| `wai.splat.sog` | payload | candidate | volumetric | standalone | patent-pool | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.splat.spz` | payload | registered | volumetric | standalone | royalty-free | standard-unclassified | — | §5 Interactive, temporal & computed content |
| `wai.tensor.nnc` | payload | candidate | binary | standalone | patent-pool | standard-unclassified | — | §5 Prior artifacts, general tensors and derivation operations |
| `wai.ternary.tt` | payload | registered | binary | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.text.xz` | payload | registered | text | standalone | royalty-free | standard-defined | recommended | §5 Recommended modern set |
| `wai.text.zstd` | payload | registered | text | standalone | royalty-free | standard-defined | floor | §5 Mandatory floor |
| `wai.video.av1` | payload | registered | video | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.video.av1.lossless` | payload | registered | video | standalone | royalty-free | standard-tolerance | recommended | §5 Recommended modern set |
| `wai.video.av2` | payload | registered | video | standalone | royalty-free | standard-tolerance | — | §5 Broadcast and streaming codecs |
| `wai.video.avc` | payload | registered | video | standalone | patent-pool | standard-defined | — | §5 Broadcast and streaming codecs |
| `wai.video.avs3` | payload | registered | video | standalone | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.video.channel` | record | registered | — | — | — | — | — | §5 Neural capabilities |
| `wai.video.evc` | payload | registered | video | standalone | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.video.evc.baseline` | payload | registered | video | standalone | royalty-free | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.video.hevc` | payload | registered | video | standalone | patent-pool | standard-defined | — | §5 Broadcast and streaming codecs |
| `wai.video.int_hyper` | payload | registered | video | standalone | royalty-free | neural-int-exact | — | §5 Neural capabilities |
| `wai.video.int_motion` | payload | registered | video | standalone | royalty-free | standard-defined | — | §5 Neural capabilities |
| `wai.video.int_refine` | refinement | registered | video | refinement | royalty-free | standard-defined | — | §5 Refinement capabilities (staged delivery) |
| `wai.video.j2k` | payload | registered | video | standalone | royalty-free | standard-tolerance | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.video.keys` | record | registered | — | — | — | — | — | §5 Neural capabilities |
| `wai.video.lcevc` | companion | registered | video | enhancement | patent-pool | standard-unclassified | — | §5 Broadcast and streaming codecs |
| `wai.video.manifest` | record | registered | — | — | — | — | — | §5 Neural capabilities |
| `wai.video.package` | record | registered | — | — | — | — | — | §5 Neural capabilities |
| `wai.video.ssai` | record | registered | — | — | — | — | — | §5 Neural capabilities |
| `wai.video.vp9` | payload | registered | video | standalone | royalty-free | standard-defined | — | §5 Broadcast and streaming codecs |
| `wai.video.vvc` | payload | registered | video | standalone | patent-pool | standard-defined | — | §5 Broadcast and streaming codecs |
| `wai.world.live` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.world.model` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.world.replay` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| `wai.world.scene` | payload | registered | interactive | standalone | royalty-free | standard-defined | — | §5 Interactive, temporal & computed content |
| identifier (not a capability) | meaning | in |
|---|---|---|
| `wai.det.fixed64` | the fixed-point arithmetic floor the deterministic *-equivalence criteria are computed in | §5 Interactive, temporal & computed content |
| `wai.world.sim.feed0` | the identity simulation step of wai.feed.state | §5 Interactive, temporal & computed content |
| `wai.world.sim.skeletal0` | the skeletal-pose simulation step of wai.avatar.pose | §5 Interactive, temporal & computed content |
| unregistered label | reason |
|---|---|
| `wai.quantum.mitigate` | a receipt-kind label the wai-quantum crate seals; no revision of SPEC or of an extension registers it, so it is not a registered record |
| `wai.quantum.decode` | a receipt-kind label the wai-quantum crate seals; no revision of SPEC or of an extension registers it, so it is not a registered record |
| `wai.quantum.compile` | a receipt-kind label the wai-quantum crate seals; no revision of SPEC or of an extension registers it, so it is not a registered record |
| `wai.quantum.rearrange` | a receipt-kind label the wai-quantum crate seals; no revision of SPEC or of an extension registers it, so it is not a registered record |
| `wai.quantum.qbom` | a receipt-kind label the wai-quantum crate seals; no revision of SPEC or of an extension registers it, so it is not a registered record |
<!-- end generated -->
Reference in a new issue View git blame Copy permalink