Resonance Knot (.rknot)

Spectral-residual replacement for the dense .knot weight format.

Getting Started

• What: implementation notes for the rknot source subtree.
• Why: it helps you find the owner module before editing code or importing a public surface.
• How: read this file as the local module map, then open the named source file and its matching tests.
• Next: return to the parent README when you need commands or package-level context.

A Resonance Knot drops the embedding dimensions that don't carry signal, signed-quantizes the rest at amplitude-graded bit widths, and ships the result as a single file with a header pointer table for mmap-style block access. Lean-first design — every claim in this document is either a measurement or points at a lake build-green theorem.

Format

magic        :  6 bytes  "RKNOT\x02"
header_len   :  4 bytes  u32 LE
header_json  :  N bytes  RknotHeader: arch_meta + per-layer offsets
body         :  rest     concatenated quantized blocks

Per-block payload is [4 bytes f32 LE scale] || [packed signed codes]. Decode: ((code - 2^(bits-1)) * scale) ≈ original_weight.

The Lean SSOT for the contract lives at open-source/gnosis-math/Gnosis/ResonanceKnot{Format,Encoder,Decoder,RoundTrip,CompressionBound,Correctness}.lean. The Rust struct names mirror the Lean structures verbatim.

Two formats under one extension: .rknot vs KNOT-format SK32 sketches

There are two distinct compressed-weight files in distributed-inference/rknots/, and they do not share a body layout:

RknotBackend::open only understands the RKNOT\x02 magic — pointed at a sketch file it fails with BadMagic { found: [75,78,79,84,1,0] } ("KNOT" + v1). That is the format gap.

Resolution (no conversion needed): SketchBackend is a parallel WeightBackend that reads the KNOT-format SK32 sketches directly. fat-station's --rknot … --dense … boot sniffs the first four bytes (sketch_backend::is_knot_magic): a KNOT-magic source routes to SketchBackend, an RKNOT-magic source keeps RknotBackend. Both attach the dense .knot as fallback for tensors they don't carry.

SK32 on-disk layout

magic        : 4 bytes  "KNOT"
version      : 2 bytes  u16 LE
meta_len     : 4 bytes  u32 LE
meta_json    : meta_len bytes  (sketches map: per-tensor offset/length/d_out/d_in/rank/maxes)
pad          : (10 + meta_len) up to a 4-byte boundary
codec_marker : 1 byte
payload      : per-sketch  (u_q8 [d_out×rank] || sigma_q8 [rank] || v_q8 [rank×d_in])

payload_base = ((10 + meta_len + 3) & !3) + 1; each sketch offset is relative to it. Dequant: U = ((u_q8-128)/127)·u_max, σ = (sigma_q8/255)·sigma_max, Vᵀ = ((v_q8-128)/127)·v_max. Served row-major fp32 [d_out, d_in] — the exact byte layout model.rs::mat_vec_dispatch_batch expects (M=d_out, K=d_in), no transpose.

Wiring gotchas SketchBackend handles

1. Name aliasing. The sketch file keys tensors GGUF-dot (blk.0.attn_q.weight); model.rs::resolve_tensor fetches by the dense knot's bitwise underscore name (blk_0_attn_q_weight). SketchBackend registers both. The output projection is named attn_o by the sketch generator but attn_output by the dense knot / model.rs, so that pair is mapped too.
2. fp32 metadata override. The dense knot marks these tensors Q4_K / Q6_K, but SketchBackend serves fp32. Without fp32_tensor_overrides() merged into the metadata before KnotWeights::from_parts, the Q4_K kernel parses fp32 bytes as 144-byte super-blocks → instant NaN. (Mirrors RknotBackend::fp32_tensor_overrides / KnotWeights::from_rknot.)
3. Embeddings / lm_head excluded. token_embd.weight and output.weight are present in the sketch file but a rank-32 sketch of a 152064×3584 vocab table is a catastrophic approximation that poisons /embed with NaN-grade error. SketchBackend skips them, leaving the embedding table + output projection to the dense fallback (matches RknotBackend's spectral-only policy).

Verified status + fidelity caveat

fat-station --rknot rknots/qwen-coder-7b-sketches.knot --dense ~/.edgework/models/qwen-coder-7b.knot boots (196 SK32 sketches served), /embed is NaN-free, and a full 28-layer /forward over the Paris prompt [785,6722,315,9625,374] completes (~40 s, no NaN) producing valid logits. It does not reproduce the dense answer: the dense model returns 12095 (" Paris"), the rank-32 sketch model returns garbage (top-1 = 73665 "aeper"). This is expected — these are topology: "rank-k-exclusion-sketch" probe artifacts at rank 32, far below the fidelity needed to replace every attention+FFN matrix. The format gap is closed (the file loads and forwards mechanically); rank-32 SK32 is simply too lossy for coherent generation. A higher-rank sketch (or the standing-wave .rknot path) is required for answer-faithful inference.

Module map

Binaries

Cloud Build pipelines

End-to-end is parameterized by _MODEL_NAME, _HF_REPO, _HF_FILE, _MIN_BYTES so the same yaml fans out across the HF library:

gcloud builds submit --config=cloudbuild-llama-70b-end-to-end.yaml . --async \
  --substitutions=_MODEL_NAME=qwen2.5-7b,_HF_REPO=bartowski/Qwen2.5-7B-Instruct-GGUF,\
_HF_FILE=Qwen2.5-7B-Instruct-Q4_K_M.gguf,_GCS_STAGING_PREFIX=models/qwen2.5-7b,\
_R2_KEY=models/qwen2.5-7b.knot,_RKNOT_R2_KEY=models/qwen2.5-7b.rknot

Measured cascade ratios

Wave dispatch on 2026-05-03, encoding from Q4_K_M dense .knot with production defaults (k=0.30 coverage, 4-bit Q/K, 8-bit V, 4-bit FFN):

These are ratios over Q4_K_M. The same artifacts vs fp16 baseline are roughly 4× larger again — TinyLlama's .rknot is ~16× smaller than fp16 dense.

Why some knots compress better than others

Five orthogonal levers. We can measure each one:

1. McNally Cliff density

The strongest predictor. A layer is "compressible" iff its centered activation singular spectrum has σ_1 ≥ 8 × σ_2 — the McNallyCliff predicate, formalized in Lean and discharged by decide on real spectral-atlas measurements.

The empirical handoff measured Qwen2.5-0.5B and found:

• Layer 13: σ_1/σ_2 = 40× ✓ sharp cliff
• Layer 14: σ_1/σ_2 = 38× ✓ sharp cliff
• Layer 22: σ_1/σ_2 = 1.3× ✗ smooth decay

Layers with sharp cliffs have effective rank ≈ 1 in their residual stream — a single dominant direction with a long flat tail. That flat tail is what we compress away.

This explains why Qwen wins the wave at 7.3×: more cliff layers per total depth than Mistral / Llama. Qwen's k8 PCA-tolerant set was 8 out of 24 layers (33%) on the 0.5B variant — the 7B model likely inherits the same cliff topology.

Falsified alternative: the smooth power-law noise-color thesis (brown vs pink vs white α exponents). Every Qwen layer measured as white or pink — no brown — but the cliff signature was sharp. Recorded as a falsification in GnosticValley.lean.

2. GQA grouping width

Models with grouped-query attention (GQA) have kv_dim < hidden_dim. When kv_dim ≤ k = 0.30 × hidden_dim, all KV columns fit inside the standing manifest and K/V get energy ratio = 1.0 at encode time.

Verified on Llama-1B: K=1.000, V=1.000 in the encoder summary output. Mistral-7B-v3 (4096 hidden, 1024 kv_dim, 4× group ratio) and Llama-3-8B (4096 hidden, 1024 kv_dim) both clear the threshold trivially — that's some of where the 4× ratio comes from "for free."

Multi-head attention (no GQA, kv_dim = hidden_dim) loses this win.

3. Quantization headroom

The signed quantizer captures 100% of signal at 8 bits and ~95% at 4 bits, given the standing manifest covered the load-bearing columns. Models with weights closer to a clean zero-mean Gaussian quantize cleanly; models with heavy-tailed weights lose precision in the tails and the per-block scale gets stretched.

We do not yet have a measurement that isolates this from #1 + #2, but the cliff thesis predicts it: models with sharp cliffs have concentrated weight spectra, which means the per-block scale doesn't have to span a wide dynamic range, which means the signed quant bins efficiently.

4. Source quant format

Going from Q4_K_M to .rknot is "lossy on lossy." The Q4_K_M baseline already discarded ~½ a bit of precision per weight. Every ratio in the table above is a Q4_K_M ratio; vs fp16 they're roughly 4× higher. Encoding from fp16 source GGUF would land closer to the Lean-proven (d/k)² floor of 9× over fp16 at k=0.30.

5. Architecture compatibility

Phi3 fuses Q+K+V into one tensor. Mamba is state-space (no Q/K/V at all). Mixtral has 8 expert FFNs per layer with ffn_gate_exps naming. FLUX is rectified-flow diffusion with no transformer config block. Our dense_reader.rs::load_layer_blocks fails cleanly on all four with helpful error messages — the diagnostic signal is what each architecture would need to support.

The Lean cascade theorem is architecture-agnostic; the Rust encoder is currently transformer-specific. Closing that gap is Phase 5+.

Honest boundaries

• Storage compression is verified. verify-rknot round-trips the structural format; signed_round_trip_recovers_negative_values is a real test, not a spec-level True.
• Energy preservation at the standing subspace is verified. On Llama-1B Q4_K_M with the signed-quant fix, layer-0 energy lifted from 0.5 → 1.0 across all 12 measured blocks at the production bit profile.
• Multi-token inference correctness is NOT yet verified. No Resonance Knot has been used for the Paris probe (load → decode → forward pass → assert "Paris" token). The RknotBackend implementing WeightBackend is in place; what's left is wiring it into a NativeLlamaPipeline::from_parts call (currently wasm32-only). That's Phase 4.
• The PCA-cliff-aware manifest is wired but not measured at scale. --input-pca <sidecar> reads PCAB files emitted by standing-wave-pca and uses cliff-aware coordinate selection. No production .rknot has been built with this path yet — every ratio in the table above used the magnitude heuristic.

What we know is left to measure

1. Spectral-atlas every wave model — get cliff density per model and check the predicted correlation with cascade ratio.
2. Re-encode with --input-pca for each model that has a PCAB sidecar. Conjecture: cliff-aware encoding lifts the magnitude-baseline cascade by ~1.5–2× per model.
3. Phase 4 inference round-trip. RknotBackend → KnotWeights → NativeLlamaPipeline → generate one token. The Compression Uncertainty Principle (verify_preserves_identity ∧ total_compute > baseline) says we either compress or verify; this measurement chooses the verify side and tells us how much fidelity we lost.
4. Endurance probe. The standing-wave handoff measured 128-token PCA endurance at 0.94 cosine. Worth running the same probe on the storage-side .rknot to see if the format itself survives long generations or whether it needs paired draft-and-verify.

Cross-references

• Lean SSOT: open-source/gnosis-math/Gnosis/ResonanceKnot*.lean
• Compression Uncertainty Principle: open-source/gnosis-math/Gnosis/CompressionUncertainty.lean
• Synergistic Stabilization (endurance falsification): open-source/gnosis-math/Gnosis/SynergisticStabilization.lean
• McNally Cliff predicate: open-source/gnosis-math/Gnosis/GnosticValley.lean#L286
• PCAB sidecar format (standing-wave routing): open-source/gnosis/distributed-inference/src/standing_wave_pinning.rs
• Phase contracts: RKNOT_RUST_CONTRACTS.md, RKNOT_PHASE2_CONTRACTS.md, RKNOT_PHASE3_CONTRACTS.md (this directory)

License

MPL-2.0, same as the parent crate.