# 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; rate reduction is not its purpose.
It exists to demonstrate, and make usable, one property: 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)

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 limits, both recorded so the scope is stated plainly:

- **Low rate–distortion.** 13.3 dB at 3.8× with six layers (the table above); 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 (as SPEC §7 *Signatures*
requires); `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.
The figure's acquisition class rides beside it as an optional signed label
([energy-measurement](energy-measurement.md) §2.8): absent, the receipt keeps
its legacy bytes and the figure is unlabelled; present, it is inside the
signature. `with_energy_class` labels and re-signs a sealed receipt.

## 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.