Aeon-Flow Wire Integration — Scoping Document

Status: scoping only. Not a commitment to ship, not a design spec, not a change-spec. A 300-foot view to inform the conversation about whether to take this on as the next major sprint.

Date: 2026-05-03 (after wave 6).

Read alongside:

STANDING_WAVE_STATUS.md (empirical baseline)
STANDING_WAVE_STATUS_2026_05_03.md (wave-4 snapshot)
STANDING_WAVE_STATUS_2026_05_03_AFTER_FALSIFICATION.md (wave-5/6 refinement)
gnosis-math/THEORY_OF_MODEL_PHYSICS.md (the constitutional index)

1. Current state

Where aeon-flow lives

The aeon-flow protocol has two implementations on opposite sides of the mesh, both tracking the same 10-byte ConsciousTick header.

TS (canonical, browser + edge + worker):

open-source/aeon/src/flow/AeonFlowProtocol.ts (936 LOC) — fork/race/fold stream multiplexing.
open-source/aeon/src/flow/FlowCodec.ts (494 LOC) — 10-byte header + payload encode/decode, optional WASM acceleration.
open-source/aeon/src/flow/types.ts (246 LOC) — flag constants (FORK 0x01 / RACE 0x02 / FOLD 0x04 / VENT 0x08 / FIN 0x10 / POISON 0x20 / HELIX 0x40), ConsciousTick, FlowFrame, transport interface.
open-source/aeon/src/flow/UDPFlowTransport.ts, WebSocketFlowTransport.ts, FlowSendBatcher.ts, frame-reassembler.ts, StreamEncoder.ts, ProgressiveMeshOrchestrator.ts — transport + framing helpers.
Edge surface: apps/edge-workers/src/workers/aeon-web-gateway.ts carries the application/x-aeon-flow content-type and x-aeon-flow: supported capability advertisement.

Rust (mesh side, distributed-inference):

open-source/gnosis/distributed-inference/src/bin/fat-station-flow.rs (1042 LOC) — UDS variant. Hand-rolled mirror of FlowCodec.ts (constants FLOW_HEADER_SIZE=10, FLOW_MAX_PAYLOAD=0xff_ffff, FLAG_FIN=0x10, FLAG_VENT=0x08, FLAG_RESPONSE=0x20).
open-source/gnosis/distributed-inference/src/bin/fat-station-flow-udp.rs — UDP variant, one datagram == one frame, no UDS length prefix. Also dispatches 0xF001 / 0xF002 liquid-memory shard JSON (shared implementation via gnosis-rtl-bridge liquid_memory_shard, same as rtl-bridge’s gnosis-liquid-shard-mock).

There is no shared library between the two sides — both copies re-derive the wire format from comments in their own file plus a back-reference to the other ("mirror of FlowCodec.ts" in the Rust; no reverse pointer in the TS). Drift risk is structural.

What gets put on the wire today

Per fat-station-flow.rs:

payload = u16BE meta_len || UTF-8 JSON meta || raw body
body    = packed little-endian f32 (residuals) | packed u32 (token IDs) | empty

The route opcodes that actually move residuals are ROUTE_FORWARD (0x0003) and ROUTE_LM_HEAD (0x0004). Both call body_to_f32(body) to deserialize a full-precision residual of size hidden_dim × seq_len × 4 bytes. There is no compression of any kind on the wire — the residual is a flat f32 blob.

Confirmed by grep over both flow binaries: zero hits for compress, pca, PCA, LRFD, LRKV, truncate in the wire path. The compression primitives (compress_to_standing, decompress_from_standing, fit_pca, read_pca_bases, write_pca_bases, PcaBasis::open, the .pca .lrfd .lrkv sidecar formats) all live in src/standing_wave_pinning.rs and src/rknot/manifest_from_pca.rs and are exercised only by the local fat-station-uds path and the parity / atlas binaries.

Net statement

The local fat-station compresses at every per-layer hook (PCA basis loaded at boot, hook fires on forward_one). The multi-host aeon-flow wire still ships full residuals. The two surfaces are disconnected.

2. Why it matters now

Wave 6 confirmed that operational compression policy depends on hidden_dim. The k=8 PCA policy that worked on Qwen-0.5B (hidden=896) failed on Qwen-Coder-7B (hidden=3584) at K=5 draft-and-verify (F_eff = 0/30). The refinement is RankFloorScalesWithDim: k_components = 8 perthou × hidden_dim, NOT a fixed k. The cliff structure is necessary; the rank density is the invariant.

Combine that with wave-4's wire-residual measurement: at Qwen-Coder-7B hidden=3584, full residual = 14336 bytes per layer per token. For an 80-layer 70B-class deployment, that is ~1.1 MB per token of inter-host residual traffic. Multi-host inference at any non-trivial scale MUST compress on the wire, or the network is the bottleneck — even before considering Llama-1B's brown-layer morphology or Gemma4-31B (5376 hidden × 60 layers = ~1.3 MB per token uncompressed).

The local-only PCA compression demonstrated this session is necessary but not sufficient for distributed deployment. The wire is the next load-bearing surface.

3. The cross-codebase change scope

Rust side (`open-source/gnosis/distributed-inference`)

Mostly already done. The PCA cache format (PCAB magic, see standing_wave_pinning::write_pca_bases) exists and is exercised by the parity binaries. PcaBasis::open and PcaBasis::layer are the load + lookup APIs.

What is not there yet:

A wire-codec entry point: compress_residual(r: &[f32], layer: usize, policy: &CompressionPolicy) -> CompressedResidual that mean-centers and projects a residual through a fitted basis.
The matching decompress_residual(c: &CompressedResidual, layer: usize, basis: &PcaBasis) -> Vec<f32> that lifts back to full hidden_dim using mean + basis^T · components.
CompressionPolicy struct that pins (k_components, layer_set, methodology_id, basis_fingerprint) so the receiver can verify it has the same basis loaded.
A small extension to fat-station-flow.rs (and its UDP cousin) to branch on a new BODY_KIND byte at the start of body and dispatch compress/decompress around body_to_f32 / f32_to_body. Today there is no body_kind discriminator at all — the body type is implied by the route opcode.

TS side (`open-source/aeon` and `apps/edge-workers`)

This is the cross-codebase change. The aeon-flow wire format needs a new payload variant for compressed residuals. Today AeonFlowProtocol.ts is fully payload-agnostic (the codec only parses the 10-byte header), so the change lives in the application layer that consumes the payload, not in the codec. Concretely:

A new payload-variant tag (see §4) understood by whichever TS surface owns inter-host residual transport for the mesh. As of this scope, that surface does not exist — the worker side of the mesh speaks aeon-flow but currently does not move residuals (the edge-workers paths are gateway-shaped, not inference-shaped). This is part of the gap: the TS wire receiver for inference residuals has to be designed AND built.
A reference encoder + decoder in TS. The decoder needs the same PCA basis the Rust sender used; that means either (a) pushing the PCAB sidecar to the worker as a static asset, or (b) defining a basis-fetch step in the inference handshake. Option (a) is simpler; option (b) is the path to per-conversation calibration.
Version negotiation: see Protocol section.

Protocol (somewhere shared)

Today there is no version field in the 10-byte header — the format itself is implicitly v0. Recommend bumping to a versioned aeon-flow protocol that advertises compression support during the connection handshake. Nodes negotiate the lowest common version. Pre-v1 nodes never see compressed payloads; v1+ nodes can opt in per-layer.

The version negotiation does not require a header change — it can ride on the existing application/x-aeon-flow content-type machinery in aeon-web-gateway.ts (extend with a ; v=1 parameter). This avoids breaking the wire shape.

4. Proposed wire format

A compressed residual is a single contiguous body block:

[0..3]   tag           u8[4]  ASCII 'P','C','A','R'  (PCA Residual)
[4..7]   layer_index   u32 LE
[8..11]  k_components  u32 LE  (the actual rank used at this layer)
[12..15] hidden_dim    u32 LE  (sender's d, for receiver sanity check)
[16..19] methodology   u32 LE  (FNV-1a or similar of the policy spec)
[20..23] basis_fp      u32 LE  (FNV-1a of the PCAB file the sender used)
[24..]   components    f32 LE × k_components

Total fixed overhead: 24 bytes.

For Qwen-Coder-7B at k=29 (≈8 perthou of hidden=3584), the body shrinks from 14336 B → 24 + 116 B = 140 B per residual per layer. That is a ~100× compression at the wire if the basis-load and methodology agree.

The receiver's algorithm:

Verify basis_fp matches the locally loaded PCAB. If not, vent the frame with FLAG_VENT and a status JSON like {"status": 412, "error": "basis fingerprint mismatch"} so the sender can fall back to full-residual.
Verify methodology is one the receiver supports. If not, same 412 vent.
Verify hidden_dim matches the locally loaded model. Mismatch is a hard 400.
Apply lift = mean[layer] + components · basis[layer]^T.
Hand the lifted residual to forward_range_chunk exactly as today.

The tag is in the body, NOT in the 10-byte header — it preserves backward compatibility because today's receivers blindly call body_to_f32, so a tagged body simply fails to decode as a multiple-of-4 f32 array (24 bytes header + 4*k bytes always satisfies that... so we need a stronger discriminator). Honest gap: see §7, the tag-as-prefix scheme conflicts with today's "implicit f32 body" contract; either we add a BODY_KIND byte to the route opcode space or we negotiate at handshake. Don't ship the tag-only design without deciding.

5. Risks

Recursive falsification (wave 6)

The compression policy's (k, layer_set) must be measured per-model under a fixed methodology. The wave-4 → wave-5 falsification showed that PROJECTED-CERTIFIED is not admissible without measured K and measured surface stack. Cannot ship a single static policy across all models. The wire format must therefore carry the methodology fingerprint so the receiver can refuse mixed-policy frames; a methodology_id mismatch is operationally identical to basis mismatch.

Methodology pinning

If the wire receiver doesn't know which methodology the sender used, the reconstructed cosine is undefined. The 4-byte methodology field is the minimum; in practice the receiver needs a small registry of known methodology specs (one per (model, hidden_dim, k_rule, calibration_corpus_hash)). This registry is shared state — another cross-codebase artifact.

Cross-version compat

Nodes at different aeon-flow versions need fallback paths to full-residual. The PCAR body must be an opt-in advertised at handshake; v0 nodes never see one. A v1 node receiving a HTTP/200 application/x-aeon-flow (no version param) MUST send uncompressed. This is straightforward but easy to forget — bake into the negotiation library, not into per-route code.

Drift between Rust and TS implementations

Today the two sides drift independently (no shared schema, no generated bindings). Adding a body-tag discriminator widens the surface. Mitigation: pin both implementations against a single JSON-schema / Lean RuntimeCertificate-style spec, and add a parity test binary that sends every body kind from each language to the other and round-trips.

The basis sidecar is now a wire-time dependency

Today the PCAB lives on disk next to the .knot. With this scope, a multi-host deployment must guarantee every worker has the same PCAB file (matching basis_fp). Any rolling deploy that mixes basis versions silently loses fidelity unless the handshake catches the mismatch.

6. Phasing

Phase A (1-2 weeks) — single-version wire codec

Rust: add compress_residual / decompress_residual against the existing PcaBasis.
Rust: add a BODY_KIND discriminator to fat-station-flow.rs and fat-station-flow-udp.rs. Branch on the discriminator before calling body_to_f32.
TS: build the inference-residual receiver in the worker layer (does not exist yet). Implement PCAR decode against a worker-loaded PCAB.
No version negotiation. Both sides hardcode v1, both sides ship with an identical PCAB.
Test: Qwen2.5-0.5B (the only fully CERTIFIED model in the atlas) end-to-end across a Rust sender → TS receiver loop. Pass bar: cosine ≥ 0.94 over 128 tokens (same as the local triple-surface pass bar in STANDING_WAVE_STATUS.md).

Phase B (1-2 weeks) — version negotiation + per-model methodology

Add ; v=1 content-type negotiation in aeon-web-gateway.ts.
Add the methodology registry. Define methodology IDs for qwen-0.5b/k8, qwen-coder-7b/derive_policy_3584, etc.
Add the basis_fp mismatch / methodology mismatch fallback path (vent + 412 → sender retransmits as raw f32).
Test: rescued K-widening Qwen-Coder-7B (assuming wave-6 / wave-7 finds the rescue with k = 28 per recommended_k_qwen_coder_7b). Pass bar: F_eff ≥ 0.30 at the rescue K, AND wire savings ≥ 50% net of fallback.

Phase C (later) — adaptive policy

Drift-triggered re-fit at the receiver based on cosine measurement of the reconstructed signal. Requires the receiver to occasionally request an uncompressed frame (sample-rate verification, see §7).
Per-conversation PCA calibration if cross-prompt generalization fails (open question from STANDING_WAVE_STATUS.md §"What's left to be useful").
Block-sharing of bases across layer groups (one basis per 4-layer group) for Gemma4-31B-class memory budgets.

7. Honest gaps

The gaps below are the most important section of this doc. None of them are blockers in the engineering sense; all of them are load-bearing in the "do we know what we're shipping" sense.

Wire-side drift detection is unspecified

The Theory of Model Physics (THEORY_OF_MODEL_PHYSICS.md) does not yet specify how to detect when a wire-side reconstruction has drifted from baseline. The consciousness-monitor binary is local-only — it watches inner_consciousness (rollback rate) on a single host. The wire equivalent would need a sample-rate test where a fraction of frames are sent uncompressed for verification. Design this before Phase C. Without it, Phase C is unsafe (we'd be adapting the basis based on signal we can't validate).

Methodology metadata has to be in the wire format, not just the policy parameters

Wave 6's derive_policy_3584 showed that two policies with the same (k, layer_set) can produce different reconstructions if their calibration corpora differ. The 4-byte methodology field in §4 encodes the ID of the policy spec, not the spec itself. The receiver MUST have the spec already. There is no inline negotiation of an unknown methodology. This is a hard constraint, not a soft recommendation.

The body-tag discriminator conflicts with today's implicit-f32 contract

§4 hand-waves "tag at byte 0 of body" but today's receivers blindly treat the body as packed f32. A 24-byte tag header is length-divisible-by-4, so it would silently decode as 6 corrupted floats. Either: (a) reserve a new ROUTE opcode for compressed residuals (ROUTE_FORWARD_PCA = 0x0103, ROUTE_LM_HEAD_PCA = 0x0104), OR (b) bump the protocol version so v1 receivers know to look for the tag, OR (c) carry a body_kind byte in the JSON meta ({"body_kind": "pca"}).

No shared library between Rust and TS

The two flow implementations re-derive the wire format from comments. Adding a compression body kind doubles the drift surface. Long-term fix is a generated codec from a single schema (Lean? capnp? flatbuf?). Out of scope for this sprint but flag it as the structural debt that this sprint will increase.

The TS inference-residual receiver does not exist

The aeon-flow protocol is live on edge gateways and worker-to-worker streaming, but no worker today is the receiving end of an inference-residual chain. Phase A includes BUILDING that receiver, not just adding a codec to it. Estimate 50% of Phase A's wall time goes here, not to the codec itself. This is the biggest unknown in the time estimate.

Rust vs TS f32 bit-exactness

PCA reconstruction is f32 matmul. The Rust path (fit_pca in standing_wave_pinning.rs) and the TS path (would be a hand-rolled matmul or WASM) need to round identically or the cosine measurement on the receiver will drift in a model-specific way. Recommend shipping the same WASM kernel (the standalone WASM SIMD already in open-source/aether/src/wasm-simd/) on both sides.

Recursive-falsification risk for the protocol itself

Wave 6 falsified the k=8 universal claim. It is plausible that wave 7+ falsifies k = 8 perthou × hidden_dim at the multi-family scale (see THEORY_OF_MODEL_PHYSICS.md "What's NOT in the stack" § "Rank density scaling at multi-family"). If that happens after Phase A ships, the wire format must carry enough policy information to migrate without a full protocol bump. The methodology field is intended to absorb this, but the registry must be designed extensibly.

8. What this scope doc is NOT

Not a commitment to ship. A different sprint (e.g. K-widening validation on Qwen-Coder-7B, or Gemma4-31B atlas) may be the better next move. This doc enables that conversation; it does not preempt it.
Not a design spec. The wire format in §4 is a strawman. The discriminator question in §7 must be resolved before any code lands.
Not a change-spec. No file paths to edit, no PR plan, no test list beyond the phasing pass bars.

It is a 300-foot view. The honest gaps in §7 are the load-bearing content; the rest is context.

forkjoin-ai/gnosis