a4f0cd2d0f
Some checks failed
no-vanity-metrics / Scan committed Markdown for vanity metrics (push) Successful in 3s
WAI conformance / cargo-class corpora · linux (push) Successful in 42s
WAI conformance / cargo-class corpora · linux-arm64 (push) Successful in 1m7s
WAI conformance / cross-arch byte-equality · linux (push) Successful in 23s
WAI conformance / cross-arch byte-equality · linux-arm64 (push) Successful in 38s
WAI conformance / cargo-class corpora · macos (push) Successful in 5m17s
WAI conformance / cross-arch byte-equality · macos (push) Successful in 1m16s
WAI conformance / cargo-class corpora · windows (push) Has been cancelled
WAI conformance / cross-arch byte-equality · windows (push) Has been cancelled
Promotes the ternary-MPS prototype to a real, honestly-scoped WAI capability. - REGISTRY (codecs/mod.rs): CAP_TERNARY_TT registered — tier=Lossy, replicate_class=StandardDefined (WAI deterministic floor, like quantum — NOT the neural-integer-exact bucket), license=RoyaltyFree. All 4 registry-coherence tests pass. - WQTT CONTAINER (ternary.rs): to_wqtt/from_wqtt — self-describing, bounds-checked wire bytes (magic, n_signal, per-core left/phys/right + shared exp + u16 mantissas + base-3-packed trits). Round-trips exactly; truncation/bad-magic are errors, not panics. - RECEIPT (ternary_receipt.rs, feature ternary_receipt = [ternary, world]): a TernaryReceipt mirroring QuantumReceipt — separates portable-exact WORK (trit_macs, verified by recomputation) from measured-attested ENERGY (joules_micro), bound to payload_hash (WQTT bytes) + reconstruction_hash (re-decodable). seal/verify/verify_reconstruction/receipt_hash/JSON + chaining. JWP Merkle + Ed25519 reused. 5 receipt tests. - SPEC.md row + extensions/ternary-tt.md — the doc leads with the HONEST scope: a PROVENANCE transform, not a rate-competitive codec. The measured RD verdict (§5) and the "productionize only with a use case" caveat (§7) are in the spec itself, not buried. The capability's value is exactly what the whole exploration proved: byte-exact, receiptable, energy-accounted quantum-inspired compression — the property neither the float ternary/MPS fabric it ports from nor the field's lossy learned codecs have. NOT a claim to competitive compression ratio. 107 tests green under `ternary_receipt`; new files clippy-clean. Co-Authored-By: Claude Opus 4.8 <[email protected]>
134 lines
6.7 KiB
Markdown
134 lines
6.7 KiB
Markdown
# WAI Extension: Balanced-Ternary MPS Transform (`wai.ternary.tt`)
|
||
|
||
Status: **Draft / reference prototype.** Engine: `wai-rs/src/ternary.rs`
|
||
(feature `ternary`), receipt `wai-rs/src/ternary_receipt.rs` (feature
|
||
`ternary_receipt`). A **quantum-inspired** (tensor-network), classical,
|
||
deterministic transform.
|
||
|
||
## 0. What this is — and what it is not (read first)
|
||
|
||
`wai.ternary.tt` is a **provenance** capability, not a rate-competitive codec.
|
||
It exists to demonstrate — and make usable — one property nothing else in the
|
||
learned-compression field offers: a quantum-inspired ternary/tensor-network
|
||
transform whose reconstruction is **byte-exact, portable, and receiptable**.
|
||
|
||
It is **not** a good general media codec, and this document says so up front with
|
||
numbers (§5). If you need compression ratio, use the zeroth menu (JPEG-XL, AVIF,
|
||
Opus). Reach for `wai.ternary.tt` only when *determinism and provenance of the
|
||
reconstruction outrank the ratio* — an auditable, energy-accounted transform for
|
||
high-throughput edge streams where "what exactly did the sink reconstruct, and
|
||
what did it cost?" must be answerable and signable.
|
||
|
||
## 1. Lineage (ported, not invented)
|
||
|
||
The two ingredients are established, working techniques — this extension does not
|
||
reinvent them:
|
||
|
||
- **Balanced-ternary weights** ({−1,0,+1}, BitNet-b1.58 style; five trits per
|
||
byte, `3^5 = 243 < 256`, the 1.58-bit regime).
|
||
- **Matrix-product-state (MPS / tensor-train) compression** — a signal reshaped
|
||
into a chain of small cores with bounded bond dimension.
|
||
|
||
Both already live as real code in the wider portfolio (ternary fabrics, MPS/MPO
|
||
indices). Every such implementation shares one property that makes it **not**
|
||
WAI-conformant: a **float scale** (`α·(trit·x)`, `α : f32`). A float scale
|
||
desyncs across machines exactly as a float σ desyncs a learned entropy coder.
|
||
|
||
**The one change that is the whole contribution:** the scale is an **integer**
|
||
(per output column: a shared exponent + a `u16` mantissa, dequantized by a pure
|
||
integer shift). So the entire *decode* path is `i64`/`i128` with no float, and a
|
||
reconstruction is byte-identical on every machine. Encoder-side float (the SVD,
|
||
the optimal per-column scale) runs once at encode and never at decode — the same
|
||
posture as QAT and as `wai.neural.int_hyper`.
|
||
|
||
## 2. Container (`WQTT`)
|
||
|
||
```
|
||
"WQTT" | u8 version | u32 n_signal | u8 n_layers | layer*
|
||
layer := u8 n_sites | u8 n_cores | core*
|
||
core := u16 left | u16 phys | u16 right | u8 scale_exp
|
||
| scale_mant[right] (u16 each) | packed_trits(left*phys*right)
|
||
```
|
||
|
||
Little-endian; trits base-3-packed (five per byte). The container is
|
||
self-describing and bounds-checked on parse (`from_wqtt`). This byte string is
|
||
the canonical payload a receipt's identity hashes.
|
||
|
||
## 3. Transform
|
||
|
||
A left-canonical MPS per layer: sites `0..n-1` are orthonormal isometries (the
|
||
`U` of a thin SVD), the **last** core absorbs the magnitude (the remaining
|
||
`S·Vᵀ`). Per-column integer scales keep the isometries unit-scaled so magnitude
|
||
never drifts multiplicatively; the last core carries the amplitude.
|
||
|
||
**Fidelity knob — residual layers (`TernaryStack`).** RVQ over ternary-MPS: each
|
||
layer ternary-MPS-encodes the residual of the sum so far. Decode **sums** the
|
||
layers. A sum of byte-exact deterministic integer decodes is itself byte-exact
|
||
deterministic, so fidelity climbs with depth while the reconstruction stays
|
||
portable. `phys = 2` is the binary reshape; **`phys = 3` is the qutrit/base-3
|
||
site reshape** (a ternary *site* dimension, distinct from the ternary *weights*).
|
||
|
||
## 4. Conformance — reconstruction-equivalence
|
||
|
||
A sink conforms iff, given a `WQTT` payload, it produces a decoded signal whose
|
||
BLAKE3 (`reconstruction_hash`) matches — byte for byte, on every machine. This is
|
||
the deterministic-floor `*-equivalence` criterion the other WAI extensions use,
|
||
here over the integer decode. The registry classes it accordingly:
|
||
`capability_tier = Lossy` (fidelity to *source* is lossy), `replicate_class =
|
||
StandardDefined` (the reconstruction is fixed by WAI's deterministic floor, not a
|
||
float neural decode), `license = RoyaltyFree`.
|
||
|
||
## 5. Rate–distortion verdict (measured, honest)
|
||
|
||
Measured on a realistic 256-sample multi-tone + noise stream (raw 2048 B, bond
|
||
≤ 4), reconstruction SNR vs on-wire bytes as residual layers accumulate:
|
||
|
||
| layers | SNR | payload (entropy-coded) |
|
||
|---|---|---|
|
||
| K=1 | 3.6 dB | 104 B (19.7×) |
|
||
| K=2 | 5.7 dB | 194 B (10.6×) |
|
||
| K=3 | 7.6 dB | 280 B (7.3×) |
|
||
| K=4 | 10.1 dB | 370 B (5.5×) |
|
||
| K=6 | 13.3 dB | 546 B (3.8×) |
|
||
|
||
Two honest negatives, both recorded so the scope is not oversold:
|
||
|
||
- **Not rate-competitive.** ~13 dB at 3.6× is far below the zeroth menu; the
|
||
noise floor is incompressible and multi-tone content out-ranks bond-4. On a toy
|
||
sinusoid it reaches ~20 dB @ 2×, but that is a flattering input.
|
||
- **Entropy coding of the trits is break-even.** The trit stream is ~54% zeros
|
||
(≈1.45 bits vs the base-3 packing's 1.6, ~9% headroom), most of which the rANS
|
||
header/state overhead eats; it is even a small loss at low layer counts. The
|
||
five-trits-per-byte packing is already near-optimal.
|
||
|
||
Consistent with WAI's own charter (SPEC Appendix B: *don't reinvent codecs*). The
|
||
value is **not** the ratio — it is that the reconstruction and its cost are
|
||
byte-exact and auditable.
|
||
|
||
## 6. Receipt (JWP profile)
|
||
|
||
The provenance payoff (`ternary_receipt.rs`). A [`TernaryReceipt`] separates the
|
||
two costs so each is trusted honestly:
|
||
|
||
| field | what | trust |
|
||
|---|---|---|
|
||
| `payload_hash` | BLAKE3 of the `WQTT` bytes | re-checkable (tamper-evidence) |
|
||
| `reconstruction_hash` | BLAKE3 of the decoded signal | **re-checkable** (re-decode) |
|
||
| `trit_macs` | Σ trit-tensor sizes — the decode work | **verified** by recomputation |
|
||
| `joules_micro` | measured marginal energy | **attested** by signature |
|
||
|
||
`seal` decodes the stack (so `reconstruction_hash` is always the true
|
||
reconstruction); `verify` checks the Merkle root + Ed25519; `verify_reconstruction`
|
||
recovers the stack from the `WQTT` payload and confirms hash, shape, work, and
|
||
reconstruction independently. Chains via `parent_receipt_hash`. The JWP Merkle +
|
||
Ed25519 are reused verbatim — the same shape as `QuantumReceipt`
|
||
([quantum-sim](quantum-sim.md)) and the world/provenance receipts. Measured
|
||
energy comes from the same IOReport path as `wai_quantum_meter`; never fabricated.
|
||
|
||
## 7. Productionize only with a use case
|
||
|
||
This capability is registered and receipt-backed, but its RD verdict means it
|
||
earns a place in a deployment **only** where a concrete auditable-edge-stream
|
||
requirement makes provenance outrank ratio. Absent that, it is a proven reference
|
||
prototype — do not tune the RD further; that ceiling is not the interesting
|
||
question, and it has been measured.
|