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 579
open-standards/wai/README.md
Transaction Science 50667cd2a4 wai: add wai.neural.int_mlicpp, the MLIC++ entropy topology integer end to end 
The float wai.neural.mlicpp decodes correctly only while its encoder evaluates
the entropy network bit-identically to the decoder. Its validation run, with the
encoder at the runtime's default thread count and the decoder single-threaded,
put one scale on the other side of a table edge at symbol 416 of 12,288 and
decoded garbage from there. Matching the execution settings fixes that run, but
it stays a convention between two implementations. int_mlicpp makes the
agreement a property of the arithmetic: the hyper-decoder, the entropy network
re-run before each of the 2*K channel-slice x checkerboard passes, and the
synthesis are all integer networks, so every decoder derives the encoder's scale
bucket for every element, on any platform and at any thread count.

- wai-rs/src/int_mlicpp.rs: the decoder (a WIM1 payload; a one-file WMB1 model
  bundle, so a prior's SHA-256 pins every network and table), built from
  int_hyper_synth's networks, int_entropy's bucketing and the rANS decoder.
- Totality. Before the decode allocates anything, each network's shapes are
  derived from its layer geometry (the new int_hyper_synth::net_shape, which
  shares its geometry with the checked run), and a header whose shapes the
  model does not produce, or on which any network would form a buffer over
  Header::MAX_TENSOR (2^26) elements, is refused. Latents go through
  int_entropy::dequantize (sym * 2^frac + base, None where i64 cannot hold it;
  Kani harness), and every network through int_hyper_synth::run_net_checked
  (run_net layer by layer, only while no value can leave its type). So a decode
  returns an image or an error for any payload, the same one with and without
  overflow checks.
- IntModel::from_bytes, the compact network form every integer neural decoder
  loads, is total on damaged bytes: it no longer reserves for the layer count it
  reads before checking the bytes hold that many (about 480 GB for 2^32 - 1),
  and forms layer sizes and read offsets in checked arithmetic (they overflowed
  a 32-bit usize).
- run_net and decode share a per-layer function and to_rgb8; every committed
  vector still reproduces its hash.
- Registry: NeuralIntegerExact, Lossy, royalty-free (the decoder is this crate's;
  the patent status of the techniques was not examined). A new registry test
  records the basis of every NeuralIntegerExact capability.
- The neural dispatch decodes it and re-checks a pinned prior against the exact
  bytes it decodes with.
- tools/wai_int_mlicpp_export.py writes the committed vector
  tests/vectors/int_mlicpp/. Its weights are synthetic and seeded (no trained
  model is available), so the vector shows decode-equivalence and nothing about
  compression quality.
- Tests: tests/int_mlicpp.rs (the pinned image, bucket and symbol hashes under
  every kernel policy and thread count; one unit in each of four chosen
  parameters, one per value path, changes the image; damaged payloads never
  panic), tests/int_mlicpp_preflight.rs (a counting global allocator: refusing
  a header the model cannot fit, or parsing a damaged network, allocates a few
  KB at most; the decoder without the pre-flight fails it, and aborts on a
  3.4 PB allocation for a synthesis wider than the cap), a byte-exact-conformance
  golden, a neural dispatch test and unit tests. CI runs them on the conformance
  matrix in both profiles, on the byte-equality matrix, and in neural-gates.
- Evidence: all of the above pass, and the pinned hashes reproduce, on macOS
  arm64 and on wasm32-wasip2 under wasmtime 49.0.1, in dev and release. x86_64
  was not measured here (no x86_64 translation layer is installed); the Linux
  legs come from the byte-exact matrix, and the Windows runner is offline.
- SPEC 5 and 7, the README, determinism-tiers 3, 5 and 6, and the CHANGELOG
  record it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-09-30 01:39:56 -04:00

241 lines
12 KiB
Markdown
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.

# WAI — Web AI Media Transport & Execution
A container + capability-dispatch standard for media. **WAI does not
re-implement codecs**; it dispatches to SOTA standard libraries (AVIF,
JPEG-XL, PNG, JPEG, Opus, FLAC, AV1, zstd, XZ) and adds an envelope
that lets the *neural-shared-prior* path coexist with the model-free
floor.
Two paths open every conforming file:
- **Neural condition** — the sink regenerates the media against a
shared ambient prior (a model). The model is a *requirement of
existence*, never shipped (an `.mp3` doesn't ship its decoder
either).
- **Zeroth condition** — a *menu of registered SOTA codecs*. Always
satisfiable on any device that ships ffmpeg or equivalent.
The capability a file requires is *named*, not supplied.
## Building
`wai-rs` builds the codec chain by default (the `codecs` feature), and those
crates link **system** libraries rather than vendoring them — consistent with
"WAI does not re-implement codecs". Without them the build stops in a codec
crate's build script, not in WAI's own code:
```sh
# macOS
brew install jpeg-xl libavif opus dav1d xz
# Debian / Ubuntu
apt-get install libjxl-dev libavif-dev libopus-dev libdav1d-dev liblzma-dev
```
To build without the C codec chain — the envelope, manifest and `world`
engine do not need it, which is also how the wasm32 target is built:
```sh
cargo check -p wai --no-default-features
```
## What's here
| Path | Contents |
|------|----------|
| [`SPEC.md`](SPEC.md) | WAI v1.0 spec — envelope, manifest, capability menu |
| [`wai-rs/`](wai-rs/) | Rust reference implementation (lib + cdylib + staticlib + C FFI) |
| [`glossary/`](glossary/) | Reference catalog of media codecs surveyed for capability registration. [`codecs.json`](glossary/codecs.json) is the canonical survey dataset; [`SCHEMA.md`](glossary/SCHEMA.md) defines the shape and contribution rules. Rendered at [wai.transaction.science/glossary](https://wai.transaction.science/glossary). |
| [`corpus/`](corpus/) | Standard test material (Kodak/CLIC/Tecnick/SIPI images, Xiph Derf + UVG video, SQAM-class audio, enwik8 + Silesia text). Not committed; `CORPUS.md` documents reacquisition. |
## Quickstart
```bash
cd wai-rs
cargo test --lib # every registered capability + envelope round-trip
cargo build --release --bin wai
cargo build --release --lib # produces libwai.dylib/.so/.dll + libwai.a
```
On macOS, libflac lives under the Homebrew "flac" formula prefix that
Cargo doesn't probe automatically. The committed `.cargo/config.toml`
adds the path; if you build outside the repo set
`RUSTFLAGS="-L /opt/homebrew/opt/flac/lib"`.
## SDK consumption
`wai-rs` exposes a stable C ABI in [`src/ffi.rs`](wai-rs/src/ffi.rs) —
the cdylib drops in as `libwai.dylib`/`.so`/`.dll`. Bindings for any
language (Python ctypes, Node N-API, Swift, JNI, Go cgo, etc.) call
into:
- `wai_image_{png,jpeg,avif,jxl}_{encode,decode}`
- `wai_audio_{opus,flac}_{encode,decode}`
- `wai_text_{zstd,xz}_{encode,decode}`
- `wai_envelope_{pack,unpack}` — wrap/unwrap the WAI container
- `wai_buffer_free`, `wai_last_error` — memory + error handling
## Registered capabilities (the zeroth menu)
| Capability | Codec | Lossless? | Mandatory? |
|---|---|---|---|
| `wai.image.png` | PNG | yes | **mandatory floor** |
| `wai.image.jxl` | JPEG-XL | both | recommended |
| `wai.image.avif` | AVIF (AV1-based) | lossy | recommended |
| `wai.image.jpeg` | JPEG | lossy | recommended (legacy compat) |
| `wai.audio.flac` | FLAC | yes | **mandatory floor** |
| `wai.audio.opus` | Opus | lossy | recommended |
| `wai.video.av1` | AV1 | lossy | recommended |
| `wai.video.av1.lossless` | AV1 (`quantizer=0`) | YUV-lossless | recommended |
| `wai.text.zstd` | zstd | yes | **mandatory floor** |
| `wai.text.xz` | XZ/LZMA2 | yes | recommended |
Neural capabilities (`wai.neural.*`) are OPTIONAL and sink-advertised. Most
run float inference, so their decode is exact only on the build that produced
it. A distinguished subset is **integer-exact by construction** — an all-`i64`
decode with no float and no ONNX — so the reconstructed artifact is
byte-identical on every machine and its hash is portable. Conformance is a
hash: a deployer can require `intent=replicate` to dispatch only to these.
| Capability | Integer-exact decode of | Conformance |
|---|---|---|
| `wai.neural.int_hyper` | image — integer hyperprior σ source + integer entropy + integer synthesis | byte-exact (hash-portable) |
| `wai.neural.int_mlicpp` | image — MLIC++ entropy topology (channel slices × checkerboard passes, an entropy network re-run before each pass) on integer networks | byte-exact (hash-portable) |
| `wai.neural.int_synth` | image — integer synthesis only | byte-exact (hash-portable) |
| `wai.video.int_hyper` | video — `int_hyper` I-frame + integer half-pel motion-compensated P-frames | byte-exact (hash-portable) |
| `wai.audio.int_codec` | audio — learned 1-D transform, integer synthesis → int16 PCM | byte-exact (hash-portable) |
| `wai.splat.int_codec` | 3D — learned Gaussian-splat-attribute transform, integer synthesis | byte-exact (hash-portable) |
## Interactive & temporal content (extensions)
Beyond the codec menu, WAI carries content that consumes input or moves
over time — reconstructed from instructions at the sink, over one
`wai.det.fixed64` fixed-point floor, each with its own deterministic
`*-equivalence` conformance criterion:
| Capability | What it carries | Conformance |
|---|---|---|
| `wai.world.{scene,replay,live}` | interactive worlds (signed op log) | replay-equivalence |
| `wai.world.model` | action-conditioned world model (signed action ops → next frame, integer transition + synthesis) | replay-equivalence |
| `wai.mesh.glb` / `wai.splat.spz` | 3D mesh / Gaussian-splat assets | content-addressed |
| `wai.audio.scene` | object-based spatial audio | mixdown-equivalence |
| `wai.audio.score` | music as note events (synthesized at the sink) | mixdown-equivalence |
| `wai.haptic.signal` | keyframed touch envelopes | sample-equivalence |
| `wai.feed.state` | scoreboards / telemetry / market feeds | replay-equivalence |
| `wai.avatar.pose` | digital humans (skeletal pose stream) | pose-equivalence |
| `wai.splat.4d` | volumetric / 4D temporal Gaussian splats | frame-state-equivalence |
| `wai.film.linear` | animation / CGI film (sealed world + camera track) | film-equivalence |
| `wai.film.reel` | a film with cuts (one world, a sequence of shots) | reel-equivalence |
And the verify half — a signed, energy-accounted lineage for opaque
captured content WAI does **not** reconstruct (`wai.asset.provenance`).
See [`SPEC.md`](SPEC.md) §5 and [`extensions/`](extensions/) for each.
## Quantum — deterministic, native and in cloud WASM
WAI carries a full quantum stack in pure Rust: circuit simulation and the whole
operational layer around it, every stage byte-exact and sealable into a signed,
energy-accounted receipt. No QPU, no cloud service, no vendor SDK. Because it is
pure Rust with no host bindings, **one source builds for native and
`wasm32-wasip2` and produces byte-identical results** — the same circuit
reconstructs to the same statevector hash on a laptop or at the edge.
| Capability | What it does | Conformance |
|---|---|---|
| `wai.quantum.circuit` | byte-exact statevector simulation (dyadic Clifford+T+P(k)) | statevector-equivalence |
| `wai.quantum.toolchain` | four backends (statevector / stabilizer / tensor-network MPS / sparse-Pauli), algorithm library, OpenQASM 3.0 in-and-out, **QIR export + ingest**, Bloch + entanglement analysis | statevector-equivalence |
| `wai.quantum.compile` | Clifford routing + stabilizer-tableau equivalence proof | signed equivalence certificate |
| `wai.quantum.cal.*` | calibration, filter-function robust control, DD noise spectroscopy | reproducible + receipt |
| `wai.quantum.cal.noise_learn` | Cycle Benchmarking / CER sparse Pauli–Lindblad learning | signed noise model |
| `wai.quantum.mitigate` | ZNE + readout M3 + classical shadows | byte-exact post-processing |
| `wai.quantum.decode` | CSS codes (rotated surface, toric, bivariate-bicycle) + union-find and Relay-BP decoders | signed decode + joules |
| `wai.quantum.rearrange` | neutral-atom register prep (Hungarian / LSAP) | signed defect-free plan |
| `wai.quantum.phasor` | interference substrate + energy-accounted phasor receipts | reproducible f64 |
| `wai.quantum.kernel` | the quantum kernel deployed as phasor features | reproducible f64 |
| `wai.quantum.qdata` | learning-from-quantum-data sample-complexity separation | reproducible f64 |
| `wai.quantum.qbom` | Quantum Bill of Materials — stage receipts into one provenance manifest | signed manifest |
### Quickstart
```bash
# native
cargo build --release --no-default-features \
--features "quantum_toolchain,quantum_receipt" --bin wai-quantum
./target/release/wai-quantum list # algorithm catalog
./target/release/wai-quantum run ghz -n 5 # simulate + hash + outcomes
./target/release/wai-quantum run grover -n 4 -p 9 # amplitude amplification
./target/release/wai-quantum qasm bell # emit OpenQASM 3.0
./target/release/wai-quantum qir bell # emit QIR (LLVM IR)
./target/release/wai-quantum qir qft -n 4 | \\
./target/release/wai-quantum run --qir # and read it back
./target/release/wai-quantum receipt ghz -n 3 | ./target/release/wai-quantum verify
```
### Same source, at the edge
```bash
cargo build --release --target wasm32-wasip2 --no-default-features \
--features "quantum_toolchain,quantum_receipt" --bin wai-quantum
wasmtime run target/wasm32-wasip2/release/wai-quantum.wasm run ghz -n 5
```
Both print the identical `state-hash`. A receipt sealed in cloud WASM verifies
natively and vice-versa, and the receipt bytes themselves are identical — the
signature travels because the computation is reproducible, not because the two
runtimes agreed to trust each other.
### As a serverless function
[`wai-quantum-serve/`](wai-quantum-serve/) exports the same stack as a
**WASI-HTTP component** (`wasi:http/proxy`), so quantum computation runs as an
ordinary HTTP handler on a component-model host:
```bash
cd wai-quantum-serve
cargo build --release --target wasm32-wasip2
wasmtime serve -S cli=y --addr 127.0.0.1:8231 \
target/wasm32-wasip2/release/wai_quantum_serve.wasm
```
```text
GET /health GET /algorithms
GET /run?algo=ghz&n=5&top=8 POST /run (body = OpenQASM 3.0)
GET /qasm?algo=bell GET /receipt?algo=ghz&n=3[&shots=&seed=]
POST /verify (body = receipt JSON; 200 valid / 409 invalid / 400 unparseable)
```
The endpoint returns the **same** `statevector_hash` as the native CLI for the
same circuit, and a receipt sealed by the HTTP handler verifies with the native
`wai-quantum verify` — the JSON content is byte-identical (the CLI adds a
trailing newline; nothing else differs). Both verify paths accept a receipt in
either form: as sealed, or labelled with its figure's acquisition class, as
`wai_quantum_meter` emits a measured figure (`quantum_energy::MaybeLabelled`,
[energy-measurement](extensions/energy-measurement.md) §2.8). Both restate the
class, or say the figure has none.
That `wasm32-wasip2` build needs `-S cli=y`, because Rust's std imports
`wasi:cli/environment` at startup and the bare `wasi:http/proxy` world does not
provide it. For a component that runs on **any** `wasi:http` host with no host
flags at all, build the pure proxy-world artifact instead:
```bash
./build-proxy.sh
wasmtime serve --addr 127.0.0.1:8080 target/wai_quantum_serve.proxy.wasm
```
That path compiles a `wasm32-wasip1` core module and adapts it with the Bytecode
Alliance proxy adapter, leaving only imports the proxy world defines
(`wasi:http/types`, `wasi:io/*`, `wasi:cli/std{in,out,err}`, `wasi:random`). The
script fails the build if `wasi:cli/environment` ever reappears, and the served
results are byte-identical either way.
Explore the whole stack in the browser (it is the same Rust, compiled to wasm):
the [toolchain IDE](https://wai.transaction.science/quantum-ide), the
[ML layer](https://wai.transaction.science/quantum-ml), and a
[working course](https://wai.transaction.science/quantum-learn).
## License
Apache-2.0 — see [`LICENSE`](LICENSE).
Reference in a new issue View git blame Copy permalink