open-standards/wai/CONTRIBUTING.md

Contributing to WAI

WAI has two layers — a spec and a reference implementation. The contribution paths are different.

To the spec (SPEC.md)

Open for revision. WAI is a v1.0 draft; until it freezes at v1.0 final, substantive changes are welcome.

A spec change is in scope if it:

• Names a real-world ambiguity in the existing text (point at the section and the case that breaks).
• Adds a missing structural requirement (byte layout, conformance rule, dispatch behavior) needed to make a third implementation falsifiable.
• Tightens the capability-dispatch or container semantics.
• Adds a new codec or capability — with a byte-precise wire definition and cross-implementation fixtures, not a placeholder.

A spec change is out of scope if it:

• Adds optional fields with no testable conformance impact. WAI leans toward fewer well-defined fields.
• Re-litigates the capability-as-requirement model (§1 is intentional: the model is named, never transported, never hash-pinned).
• Substitutes an existing primitive for a different one (e.g. another entropy coder for rANS) without a concrete failure mode in the existing one.

How to propose a change: open a draft in a parallel SPEC-vX-draft.md, quote the section it modifies, and regenerate + run the cross-implementation conformance suite (below) to show the change does not regress the two reference implementations.

To the reference implementations

Code is Apache-2.0. There are two interoperable references:

• wai/ — Python, readability-first. Container, static rANS, entropy_zeroth, and the image/audio/video zeroth codecs; python -m wai encode|play. Neural paths (EnCodec, TAESD) live here and are out of scope for byte-level conformance (the model is a requirement, not part of the standard).
• wai-rs/ — Rust, performance + embeddability. Same wire format; wai binary with encode/play.

The two MUST stay byte-interoperable on every lossless path. Before submitting:

# Rust: 10 library + 9 cross-Python conformance tests
cd wai-rs
cargo test
cargo build --release --bin wai

# Regenerate the canonical Python reference fixtures and re-check the
# Rust port still agrees byte-for-byte (run from the wai-rs root; the
# sibling `wai/` Python package must be importable)
python tests/gen_cross_fixtures.py
cargo test --test cross_python

Both must pass. The cross-Python suite is what catches wire drift between the two implementations — it is the executable definition of conformance for v1.0 (SPEC.md §9).

A third implementation

Conformance is cross-implementation byte-equivalence, not "passes its own tests." A new-language implementation is conformant when, given the fixtures emitted by wai-rs/tests/gen_cross_fixtures.py, it produces byte-identical output for the bit-exact paths (rANS, entropy_zeroth, container) and reconstruction-equivalent output (identical quantized arrays) for the lossy codecs (image 4:4:4 + 4:2:0, audio MDCT, video I+P). Validate against the same fixtures the Rust reference is held to.

A third implementation is in scope when it brings up a language ecosystem that doesn't have one yet and is validated against those fixtures. It is not in scope when it duplicates an existing reference for ergonomic reasons; consolidate instead.

License

By contributing, you agree your contribution is licensed under the same terms as the corresponding layer:

• Contributions to the spec: published under the same open terms (royalty-free; contributors grant patent rights for compliant implementations).
• Contributions to either reference implementation: Apache-2.0.

No CLA. The license is the agreement.