08b1568291
SPEC §5 and determinism-tiers §5 said `wai.neural.int_synth` decodes "QAT weights". No committed model was trained that way. The trained corpus vector was made by `tools/wai_int_synth_real.py`: float training, then post-training quantisation with each layer's shift derived from its measured activation range, the recipe `tools/wai_int_synth_train.py` documents. The synthetic vectors' weights are generated from a seed. Both texts, the capability constant's comment, the module doc and a test comment now say that. `tools/wai_int_synth_qat.py` said it "closes the one open gap" and tunes "the weights AND the shifts"; it trains the weights against one fixed shift and made no committed model, and it now says so. `tools/wai_int_synth_export.py` told users to train with QAT upstream; it now names the working path. Stale paths: the int_synth decoder is `int_synth.rs` at the crate root, not `neural/int_synth.rs` (SPEC §5, the export tool, the capability comment); the quantum-ops engine is `wai-quantum/src/quantum_ops.rs`, and the quantum-sim receipt's feature is `quantum_receipt` of `wai-quantum`, which `wai-rs` forwards, not `["quantum", "world"]`. Co-Authored-By: Claude Opus 5.5 <[email protected]>
140 lines
7 KiB
Markdown
140 lines
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; 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 `wai.neural.int_hyper`, whose float model is quantised once, after
|
||
training, and never runs in float at decode.
|
||
|
||
## 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.
|