v0.4.2 KV geometry relevance gate

Lossless LLM memory compression for state in motion.

QATQ compresses exported KV caches and tensor migration blocks into portable QATC artefacts, restores them bit-for-bit, and has proven smaller transfer sizes than raw, zstd, and lz4 on documented public and live-migration evidence.

Install with Cargo Read the docs

Restore: bit-for-bit
Geometry profiles: 36
Crate: 0.4.2
Licence: Apache

qatq encode

# exported KV tensor bytes in, lossless QATC out
# encode-chunked is exact; QATQ selects the internal strategy
qatq encode-chunked \
  --dtype bf16 \
  --max-values-per-chunk 65536 \
  kv-cache.bf16le kv-cache.qatc

# shape-aware single-payload path when row width is known
qatq encode --dtype bf16 --stride-elements 128 \
  kv-block.bf16le kv-block.qatq

# restore the same native bytes for runtime import
qatq decode kv-cache.qatc restored.bf16le

QATC v2 checksum validated

Corrupt or truncated payloads are rejected before restore.

Quaternion-chain path

Selected only when it beats simpler lossless transforms.

Measured in v0.4.2

Capacity Oracle met real KV geometry. The result was a useful stop sign.

A bounded research profiler measured 36 deterministic profiles across two model families, three prompt and context regimes, f16 and bf16, keys and values, selected layers, every exported KV head, and three partition layouts.

Post-RoPE key groups were highly correlated, with median maximum cosine similarity 0.954426. No defensible application capacity requirement was established, so QATQ froze further theorem expansion instead of manufacturing a product claim. Capacity Oracle remains narrow and its certificate semantics are unchanged.

Read the decision report

Observation-only profiler

qatq-kv-geometry profile \
  --capture capture.kv \
  --metadata capture.json \
  --max-pairs 1000000 \
  --output results/run

The profiler reports exact, deterministic-sampled, approximate, or refused observations. It never emits an Oracle verdict.

Validated in v0.4.1

Finite capacity evidence, reproduced separately.

A pinned SageMath 10.6 implementation now reproduces all 27 published binary Hamming and spherical Rankin certificate rows without importing QATQ code or expected numeric answers.

Every row is checkable by QATQ and reproduced by separate software. External human coding-theory review is still open and is not claimed. The finite theorem scope and certificate semantics are unchanged.

Read the validation evidence

Proof-carrying outcome

qatq-oracle bound request.json \
  --output evidence

qatq-oracle check \
  evidence/certificate.json

VALID

Evidence bundles bind the normalized request, outcome, certificate, metrics, report, and manifest with SHA-256.

Measured evidence

A simple comparison table, with the claim scoped correctly.

The strongest production-facing compression result today is lossless exported-state compression. In the documented cloud live-migration proof, QATQ transferred fewer bytes than raw blocks, lz4, and zstd while preserving measured task continuation.

Live migration compression comparison between raw, lz4, zstd and QATQ
Codec	Transferred bytes	Ratio vs raw	Reduction	Bit-for-bit restore
Raw streamed blocks	50,331,648	1.0000	baseline	yes
LZ4 baseline	28,739,217	0.5709	43.0% smaller	yes
Zstd baseline	20,405,381	0.4054	59.5% smaller	yes
QATQ	14,004,990	0.2783	72.2% smaller	yes

Source: QATQ external runtime evidence, 2026-06-22 cloud live-migration proof. This proves the measured integration path, not a universal claim across every model, runtime, context length, dtype, or chunk layout.

How it works

Tensor-aware strategy search, wrapped in a portable QATC container.

QATQ is not a transparent GPU memory layer yet. It is a production-shaped codec for exported tensor bytes: f32, f16, and bf16 data that can be chunked, compressed, transferred, checked, and restored bit-for-bit.

Exported tensors

KV caches, migration blocks, and fixture captures leave the runtime as typed little-endian bytes.

Lossless candidates

QATQ chooses among raw, byte-plane, zstd-backed, delta-XOR, native 16-bit adjacent-XOR, shape-aware strided-XOR, and reversible quaternion-chain candidates.

QATC transport

Large tensors are split into bounded chunks with ordered lengths and an aggregate checksum.

Bit-identical restore

Decode returns the same native tensor bytes for runtime import or evidence comparison.

Public fixtures

Small table, reproducible evidence.

Public fixture rows are generated inside the QATQ repository so anyone can reproduce the comparison without private runtime captures.

View source tables

Public fixture compression ratios for QATQ, zstd and lz4
Dataset	Winning QATQ strategy	QATQ	zstd	lz4	Restore
bf16-kv-ramp	byte-plane-zstd	0.3817	0.4665	0.6901	yes
bf16-kv-wave	quaternion-chain-zstd	0.1153	0.2900	0.4693	yes
f32 noisy fixture	byte-plane-zstd	0.6532	0.9061	1.0040	yes
NaN/Inf stress	quaternion-chain-zstd	0.0121	0.0413	0.0673	yes

Lossless first

Lossless claims apply to QATQ and QATC. Lossy research paths remain comparators, not the product claim.

Fast enough to matter

The current target is storage and transfer of exported KV tensors, with throughput gates and fuzzing in CI.

VRAM reduction later

Live GPU VRAM reduction is a roadmap goal that needs runtime KV paging and latency proof before it becomes a claim.

Build against the crate. Read the evidence. Then try your own tensors.

QATQ is open source, Rust-native, and ready for exported KV-cache storage and transfer experiments before larger production integrations broaden the evidence base.

GitHub Whitepaper