Amplituhedron Bitwise Wire

Binary wire format for the /amplituhedron/replay and /amplituhedron/capture admin endpoints introduced in AMPLITUHEDRON_PLAN.md §4. Replaces the JSON-with-Array.from(Float32Array) envelope today's plan implies with a bitwise-encoded f32 blob. The streaming hot path (/flow, Death #3 aeon-flow) is untouched.

Companion documents:

• AMPLITUHEDRON_PLAN.md — host/worker handler shapes and Lean coverage.
• BOWL_MESH_FALSIFIABILITY.md — prediction-ledger tone copied verbatim.
• open-source/bitwise/src/bw-codec.ts — TS encoder/decoder used here.
• open-source/bitwise/src/lib.rs — Rust primitives the worker side needs (with the gap called out in §3 below).

1. Why binary

The current AMPLITUHEDRON_PLAN.md §4 reads as if the tail residual is shipped as the octet body, but the surrounding handlers and the host-side fetch call sites in distributed-inference-host use JSON for headers and metadata, and the path of least resistance today is JSON.stringify of Array.from(Float32Array). Each float renders as ~7 ASCII bytes ("0.12345,"), so a 3584-wide qwen-coder-7b tail residual lands around ~14 KiB plus the header. The raw f32 surface is 3584 * 4 = 14336 bytes (~14 KiB) — JSON expansion is the cost we pay for the convenience.

Bitwise's .bw codec (open-source/bitwise/src/bw-codec.ts, encodeBw / decodeBw) ships a fp48 word-pack on raw bytes that hits the proved fp48_concrete_4x (48 * 4 = 64 * 3) shrink for the 8-byte-aligned body and emits the 1/4 high-16 parity as a manifest sidecar. Composed with the Array→bytes step, the net wire reduction predicted on a qwen-coder-7b tail residual is roughly:

• JSON encode of 3584 floats: ~25 KiB on the wire (ASCII float tokens, commas, brackets).
• Raw f32 bytes: 14336 B = 14 KiB.
• After encodeBw 3/4 fp48 shrink + tiny header: ~10.7 KiB on the wire (14336 * 3/4 ≈ 10752 + header). Driven toward ~3.5 KiB when the dictionary-mode flag is set and the parity sidecar lives in a runtime ParityDictionary.

So the practical envelope wins are ~2× (raw-byte mode) to ~7× (dictionary mode), not the "21×" speculative figure floated earlier. Predictions in §9 are sized to the codec, not to wishful arithmetic.

2. Wire format

2.1 Header (shared)

byte 0-3   magic       "BWAH"  (0x42 0x57 0x41 0x48)
byte 4     version     0x01
byte 5     flags       u8 bitset (see §2.4)
byte 6-9   tail_len    u32 LE   (length of the encoded tail-residual payload in bytes)
byte 10-13 kv_slab_len u32 LE   (replay: 0; capture: encoded KV slab length)

tail_len and kv_slab_len are sizes of the encoded payloads, not the raw f32 counts. The raw count is recoverable from the encoded header inside bw-codec itself (encodeBw writes the original byte length into the manifest), so no separate raw-length field is needed.

2.2 Capture-only suffix

byte 14-21 prefix_hash u64 LE
byte 22-25 prefix_len  u32 LE
byte 26-27 layer_lo    u16 LE
byte 28-29 layer_hi    u16 LE

These are the keys for AmplituhedronCache.entries as defined in AMPLITUHEDRON_PLAN.md §2. The replay endpoint passes the same keys but in the request URL/JSON body (handler convenience — see §6); the capture endpoint carries them inline so the worker can dispatch on the binary body alone.

2.3 Payloads

After the header (replay: 14 bytes; capture: 30 bytes) the wire carries two concatenated .bw blobs (each one encoded by encodeBw):

[ header ] [ tail_residual_bw : tail_len bytes ] [ kv_slab_bw : kv_slab_len bytes ]

kv_slab_bw.length == 0 on the replay reply (the host does not need the KV slab; the worker already spliced it locally) and on the replay miss (no body at all; HTTP 204).

2.4 Flags byte (byte 5)

Bit 2 (formerly GZIPPED, 2026-05-10 swap) was reclaimed as reserved-zero when the canonical bitwise::bw_codec wire replaced the gzip-interim layer. The gzip codepath landed 1.07-1.08× shrink on realistic residual workloads — not worth the asymmetric capability probe across runtimes. bw_codec is uniform across host/worker/Rust, carries an fp48 integrity fingerprint for free, and unlocks the .bw ecosystem (future dict-mode, lift-mode, parity-dictionary tooling) without another wire revision.

The earlier speculative DICT_MODE (bit 3) slot is likewise reserved until a real dictionary path lands; if/when it does, it will live inside the .bw envelope's own version byte rather than the BWAH flags byte.

2.5 Byte-level diagram

Replay-hit reply (worker → host):

0          4    5    6        10       14
+----------+----+----+--------+--------+----------------------+
| "BWAH"   |0x01|flag|tail_len|kv_slab |     tail_residual_bw |
|          |    |    | (LE)   |  =0    |  (encodeBw output)   |
+----------+----+----+--------+--------+----------------------+

Replay-miss reply: HTTP 204, zero-length body.

Capture request (host → worker):

0          4    5    6        10       14            22       26   28   30
+----------+----+----+--------+--------+-------------+--------+----+----+--------+--------+
| "BWAH"   |0x01|flag|tail_len|kv_slab | prefix_hash |prefix_ |L_lo|L_hi| tail_  |kv_slab |
|          |    |    | (LE)   |  (LE)  |  u64 LE     |len LE  |    |    | res_bw |  _bw   |
+----------+----+----+--------+--------+-------------+--------+----+----+--------+--------+

3. Bitwise primitives used

The 2026-05-10 swap landed the Rust port of bw_codec. The TS source and Rust port produce byte-identical output on the wire by design, so both sides ride a single codec API.

3.1 TS side (host + Cloudflare Worker)

The host runs in TS. Encode the f32 array as the standard LE byte view of a Float32Array, then pass through encodeBw:

• open-source/bitwise/src/bw-codec.ts:350 — encodeBw(bytes, mimeType, options?). We feed mimeType = "application/octet-stream" for the inner blob's MIME field; the outer Content-Type stays application/x-bitwise-residual as before.
• open-source/bitwise/src/bw-codec.ts:482 — decodeBw(blob).
• Exported via the workspace package's @a0n/bitwise/bw-codec subpath (see open-source/bitwise/package.json:167-171). Both the host and the Cloudflare Worker import from this path.

3.2 Rust side (Cloudflare Worker / station encode+decode)

The Rust counterpart lives at open-source/bitwise/src/bw_codec/:

• bitwise::bw_codec::encode_bw(bytes, mime_type, options) -> Result<Vec<u8>, BwError>
• bitwise::bw_codec::decode_bw(buf) -> Result<DecodedBw, BwError>

The module is wired through bitwise/src/lib.rs:39 (pub mod bw_codec) and is a path dep of distributed-inference/Cargo.toml. The fp48 fingerprint is computed via xxhash_rust::xxh64; the manifest layout, HEADER_FIXED_LEN, and mime dictionary all mirror the TS source byte for byte.

3.3 fp48 word pack — Rust port already landed

bw-codec.ts's fp48PackWords lives in Rust at open-source/bitwise/src/bw_codec/encode.rs::fp48_pack_words (and its inverse in decode.rs). Both sides of the wire run the same 3/4 shrink on the inner bytes; the f32 round-trip is byte-exact by construction.

3.4 Asymmetry between BWAH framing and the inner .bw blob

The BWAH envelope (magic + version + flags + tail_len + kv_slab_len, plus the capture extension) is amplituhedron-specific framing. The inner payload section is a generic .bw blob. They are independent: upgrading the BWAH envelope (e.g., adding a new HTTP-protocol field) does not break the .bw payload, and vice versa. Both wires carry their own version byte for forward compatibility.

3.4 Does residual-codec.ts cover our need?

No. open-source/bitwise/src/residual-codec.ts:87 (encodeResidual) and :125 (decodeResidual) implement an Int16Array Huffman codec against the bundled VoiceResidual prior (bw-prior-registry.ts::VOICE_RESIDUAL_HISTOGRAM). The header is [tag=0x06 | u32 samples BE | u32 bitLength BE] and the payload assumes Laplacian-ish int16 PCM-residual statistics. f32 hidden-state residuals are not int16 and not Laplacian: post-RMSNorm Luminary residuals are near unit-norm Gaussian-ish floats. Forcing them through the int16 prior would clip silently and destroy the round-trip. The residualBitsPerSample diagnostic at residual-codec.ts:181 confirms the codec is sized for ~30-80 kbps voice, not hidden-state floats. Use the generic bw-codec.ts path, not residual-codec.ts.

4. TS codec surface contract (verbatim from parent message)

encodeAmplituhedronReply({ hit, tailResidual?, kvSlab? }) -> Uint8Array — produces the BWAH-magicked envelope. On miss returns a zero-length Uint8Array (caller emits HTTP 204).

decodeAmplituhedronReply(blob: Uint8Array) -> { hit, tailResidual?, kvSlab? } — fails fast on magic/version mismatch (throws BWAHDecodeError), never panics. Returns { hit: false } on a zero-length blob.

encodeAmplituhedronCapture({ prefixHash, prefixLen, layerLo, layerHi, tailResidual, kvSlab }) -> Uint8Array — request body. prefixHash is a bigint; all other ints are JS numbers in the safe-integer range.

decodeAmplituhedronCapture(blob: Uint8Array) -> { prefixHash, prefixLen, layerLo, layerHi, tailResidual, kvSlab } — worker-side. Same failure shape as decodeAmplituhedronReply.

5. Rust codec surface contract (verbatim from parent message)

pub fn encode_amplituhedron_reply(hit: bool, tail: Option<&[f32]>, kv: Option<&[f32]>) -> Vec<u8> — on miss returns vec![].

pub fn decode_amplituhedron_reply(buf: &[u8]) -> Result<AmplituhedronReply, BwahError> — AmplituhedronReply { hit: bool, tail: Option<Vec<f32>>, kv: Option<Vec<f32>> }. BwahError enumerates BadMagic, BadVersion, Truncated, InnerBlobError.

pub fn encode_amplituhedron_capture(prefix_hash: u64, prefix_len: u32, layer_lo: u16, layer_hi: u16, tail: &[f32], kv: &[f32]) -> Vec<u8>

pub fn decode_amplituhedron_capture(buf: &[u8]) -> Result<AmplituhedronCapture, BwahError> — AmplituhedronCapture { prefix_hash: u64, prefix_len: u32, layer_lo: u16, layer_hi: u16, tail: Vec<f32>, kv: Vec<f32> }.

All four Rust entry points are #[wasm_bindgen] so the worker shim in distributed-inference-worker can call them from JS land if/when the worker bridges through a JS shell instead of pure wasm.

6. HTTP wire

• Request and response Content-Type: application/x-bitwise-residual on both /amplituhedron/replay and /amplituhedron/capture.
• /amplituhedron/replay:
  • 200 = hit, body = BWAH envelope with tail_residual_bw payload.
  • 204 = miss, no body, no Content-Type header.
  • 400 = malformed request (host bug, log loudly).
• /amplituhedron/capture:
  • 200 = { captured: true } as plain JSON. The capture response is one bit of information; binary framing for it would be theater. Note that the capture request is binary but the response is JSON. This is asymmetric on purpose: the worker has no float payload to return on capture.
  • 4xx / 5xx = plain JSON { error: string } (same shape as the rest of the worker admin API).

CDN / proxy posture: application/x-bitwise-residual is custom enough that no compressing proxy will mangle it (gzip on top of fp48-packed bytes is a strict loss in size; gzip on the BWAH header adds overhead). F5 in §10 falsifies if a real CDN path does mangle.

7. Round-trip invariants

• Magic & version checked first: decode_amplituhedron_* returns BadMagic / BadVersion before touching the payload. No panics.
• Truncation safe: a buffer shorter than the fixed header returns Truncated. Past the header, the codec consults tail_len / kv_slab_len and refuses to read past buf.len().
• Inner-blob errors propagate: the inner .bw blob's own decodeBw (TS) / Rust equivalent surfaces an InnerBlobError with the original cause. We do not lose error provenance.
• Round-trip precision: the inner .bw codec is byte-exact per BizarroCompiler.load_time_reconstruction_exact. The f32 → bytes step is also exact (no normalization, no quantization), so the end-to-end round trip is byte-exact f32. There is no precision loss to budget for, unlike the fp48 hash family.
• No silent truncation of f32 NaNs: if the f32 array contains NaNs (Pisot drift overflow, KV slab corruption), the bytes round-trip the exact bit-pattern. The downstream amplituhedron_replay is responsible for refusing NaN-bearing tails (matches the topological_erasure invariant in AMPLITUHEDRON_PLAN.md §1).

8. Composition with Death #3 (aeon-flow)

The amplituhedron wire and the aeon-flow wire are disjoint by URL space and by payload semantics:

A coordinator that runs both has two independent codecs in its host process. Neither imports the other. The shared bitwise dependency (open-source/bitwise/src/lib.rs) is the only file both reach into, and they touch disjoint exports (this doc: encodeBw/decodeBw, fp48 family; Death #3: FlowFrame encode/decode).

9. Predictions

P1. Wire size for a single qwen-coder-7b tail residual (3584 f32) is raw LE + ~14-20 bytes of .bw framing overhead for every realistic residual shape. The 2026-05-10 swap to bw_codec removed the gzip-interim illusion: random residuals never compressed (1.07-1.08× at best on the gzip path), so the new ceiling is tight and uniform. Concretely, a 3584-element f32 vector lands at:

• Raw LE payload: 3584 * 4 = 14336 bytes.
• bw_codec wrapped: 15 (header) + 4 + 1 + 0 (tail) + 1792*2 (parity) + 1792*6 (packed) = 14356 bytes.
• BWAH envelope (magic + version + flags + tail_len + kv_slab_len): 4 + 1 + 1 + 4 + 4 = 14 bytes.
• Total wire: 14370 bytes for a 3584-element tail residual.

The 14-byte BWAH framing + 20-byte .bw framing overhead is constant regardless of residual statistics. There is no longer a near-zero fixture "shrink" path because we never claimed to compress; the inner codec is a 3/4 word-pack + integrity fingerprint, not a compressor.

P2. Encode latency on the host (TS, V8 in Cloudflare Worker) ≤ 200 μs for a 3584-wide tail residual at p50. Comparison floor (no measurement) is JSON.stringify of Array.from(Float32Array) — that is allocation

• ASCII float formatting per element, which is the worst case the codec needs to beat.

P3. Decode latency on the worker (Rust → wasm) ≤ 200 μs at p50 for the same residual. The Rust path is decodeBw (TS-equivalent port if it lands) or direct f32::from_le_bytes reinterpretation (raw-bytes mode).

P4. Round-trip cosine over N=1000 random f32 vectors of length 3584 is exactly 1.0, not "≥ 0.999". The codec is byte-exact; any deviation is a bug, not a precision budget. If we observe < 1.0 we have an F-class failure, not a softness.

P5. End-to-end /amplituhedron/replay p99 wall-clock with this wire ≤ 6 ms for a single-station replay against a warm worker, on the qwen-coder-7b 28-station mesh. The JSON baseline is not measured; P5 is the value to beat in the bench, not a delta claim.

10. Falsification triggers

F1. Wire size > 14 KiB for the qwen-coder-7b tail residual after encodeBw (i.e., the codec made the blob bigger than the raw f32 bytes). Indicates the fp48 word-pack is being applied to a payload shape it cannot compress (e.g., uniform noise) and the manifest overhead dominates. Falsification action: drop the wire to raw-f32-bytes mode (DICT_MODE=0, version byte plain 0x01).

F2. Encode or decode latency p50 > 1 ms on the host or worker, i.e. the codec dominates the savings. Falsification action: bypass encodeBw and ship raw f32 bytes inside the BWAH envelope; we keep the framing but skip the bitwise compression.

F3. Round-trip cosine < 1.0 (any deviation) over the N=1000 random vector harness. The codec is supposed to be byte-exact; any drift is a real bug in fp48PackWords or the Rust port. Falsification action: file against bitwise/ and pin the wire to BWAH over raw bytes until the bitwise round-trip is restored.

F4. The host TS encode and the worker Rust decode disagree on what version byte / flags byte they emit. Specifically: host emits DICT_MODE=1 but worker has no dictionary registered, or worker emits a flag bit the host has not allocated yet. Falsification action: pin both sides to flags byte = 0x03 (HIT | TAIL_PRESENT) exactly until the dictionary path is wired end-to-end.

F5. A real CDN / WSS proxy path (Cloudflare default, Cloud Run default) mangles application/x-bitwise-residual — either by trying to gzip it, by rejecting it as a binary type that "should be JSON," or by stripping the Content-Type header. Falsification action: fall back to application/octet-stream and embed the content-type inside the BWAH header (steal one of the reserved flag bits).

11. Pointers — the six implementation waves this doc anchors

1. This doc — open-source/gnosis/distributed-inference/AMPLITUHEDRON_BITWISE_WIRE.md.
2. TS codec — open-source/gnosis/distributed-inference-host/src/amplituhedron-bwah-codec.ts (new file). Exports encodeAmplituhedronReply, decodeAmplituhedronReply, encodeAmplituhedronCapture, decodeAmplituhedronCapture per §4.
3. Rust codec — open-source/gnosis/distributed-inference/src/amplituhedron_bwah.rs (new file). Exports the four entry points in §5 as #[wasm_bindgen] symbols. Pulls pack_f64 shape from bitwise/src/lib.rs:1375 for the f32 analog and reuses BWAHError shape from this doc.
4. Worker wire-up edit — open-source/gnosis/distributed-inference-worker/src/admin-handlers.ts (modify): /amplituhedron/replay and /amplituhedron/capture switch from JSON to application/x-bitwise-residual (call sites of Response.json(...) for these two routes only).
5. Host wire-up edit — open-source/gnosis/distributed-inference-host/src/pipeline.ts (modify): the replay fan-out and capture fan-out call sites swap JSON.stringify for encodeAmplituhedron*. No control-flow change; only the body bytes change.
6. Lean contract — open-source/gnosis-math/Gnosis/AmplituhedronWireContract.lean (new): one theorem bwah_round_trip_byte_exact stating that decode_amplituhedron_reply (encode_amplituhedron_reply hit tail kv) = (hit, tail, kv). The Lean does not prove fp48_concrete_4x; that proof already lives in BizarroCompiler.lean and we cite it.
7. Bench extension — open-source/gnosis/distributed-inference/src/bin/amplituhedron-wire-bench.rs (new): the harness that emits the P1-P3 numbers and the F1-F3 triggers, on a fixed corpus of 1000 random f32 vectors plus 10 real qwen-coder-7b tail residuals captured from the existing bench.

(Six implementation files plus this doc — the title says "six waves" because the bench is the verification wave, not a new code surface.)