# KVX: Key-Value eXtension / Neural Shard Container Specification

**Specification Version:** 1.0.0-DRAFT  
**MIME Type:** `application/x-governor-kvx`  
**File Extension:** `.kvx`  
**Authors:** Jay (Architect), Antigravity (Google DeepMind Coding Assistant), The Governor  
**Date:** August 20, 2026  

---

## 1. Executive Overview

The `.kvx` format is a machine-native binary container designed to replace disk-based text shard logs with **pre-computed, hardware-aligned GPU memory structures**. 

A `.kvx` container fuses two complementary cognitive representations:
1. **Lossless Memory (Radix KV Pages):** Pre-computed, frozen Key-Value cache tensors across 32 transformer layers in FP8 format, mapped directly into GPU HBM3e page tables ($0.0\,\text{ms}$ prefill latency).
2. **Lossy Cognitive Lens (Spectral Steering Tensor):** Multi-layer subspace projection matrices ($\Psi \in \mathbb{R}^{L \times 128 \times 128}$) that phase-lock the residual stream to damp hallucination and enforce epistemic discipline.

---

## 2. 4-Byte Coordinate Topology (`uint32`)

Every knowledge block in the Governor estate is uniquely addressable via a single **32-bit unsigned integer**:

```
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   SHARD ID    |         RADIX BLOCK ID        | SPECTRAL FLAG |
|    (8 bits)   |            (16 bits)          |    (8 bits)   |
|   0..255      |           0..65,535           |   0..255      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

* **Bits 0–7 (`Shard ID`):** Index of the estate shard ($0\dots 255$).
* **Bits 8–23 (`Radix Block ID`):** Page sequence index in the GPU Radix tree ($0\dots 65,535$).
* **Bits 24–31 (`Spectral Flag`):** Active steering cartridge ID ($0 = \text{Neutral}$, $1\dots 32 = \text{SPEC-01..32}$).

---

## 3. Binary File Layout

A `.kvx` file consists of four contiguous sections aligned to 64-byte boundaries:

```
+-------------------------------------------------------+  Offset 0x0000
| Header (64 Bytes, Aligned)                           |
+-------------------------------------------------------+  Offset 0x0040
| Coordinate Descriptor Table                           |
+-------------------------------------------------------+  Offset 0x0040 + TableSize
| Spectral Steering Tensor Bundle                       |
+-------------------------------------------------------+  Offset KV_Start (64-byte aligned)
| Frozen Radix KV-Page Tensors (FP8)                    |
+-------------------------------------------------------+  EOF
```

### 3.1 Header (64 Bytes)
```c
struct KVXHeader {
    char     magic[8];          // "RADX-KVX" (0x52 0x41 0x44 0x58 0x2D 0x4B 0x56 0x58)
    uint16_t format_version;    // 0x0100 (v1.0)
    uint16_t num_layers;        // 32 (Gemma-4 layers)
    uint16_t kv_heads;          // 16
    uint16_t head_dim;          // 128
    uint32_t num_blocks;        // Total Radix blocks contained
    uint64_t model_signature;   // First 8 bytes of base model SHA-256
    uint32_t quant_format;      // 0 = FP16, 1 = FP8_E4M3, 2 = FP8_E5M2
    uint32_t spectral_dim;      // 128 (subspace rank)
    uint64_t spectral_offset;   // Byte offset to Spectral Tensor Bundle
    uint64_t kv_data_offset;    // Byte offset to KV Page Data
    uint8_t  reserved[16];      // Padding to 64 bytes
};
```

### 3.2 Coordinate Descriptor Entry (24 Bytes)
```c
struct KVXCoordinateEntry {
    uint32_t coordinate_id;     // e.g. 0x01000A1A
    uint32_t token_count;       // Number of tokens in this block
    uint64_t kv_page_offset;    // Offset within KV Page Data section
    uint32_t kv_page_bytes;     // Byte length of this block's KV tensor
    uint32_t checksum_crc32;    // CRC-32 of raw KV tensor
};
```

---

## 4. Spectral Steering Tensor Bundle

The spectral steering section stores the multi-layer rank-$r$ projection matrices:

$$\Psi \in \mathbb{R}^{L_{\text{steer}} \times d_{\text{model}} \times r}$$

* **Target Layers:** Layers 12 through 24 (13 active layers).
* **Storage Size:** $13 \text{ layers} \times 128 \text{ subspace floats} \times 4 \text{ bytes} = 6.656\text{ KiB}$ (Rank-1) to $26.6\text{ KiB}$ (Rank-4).
* **Application Kernel:** Injected directly into the GPU forward pass:
  $$h_{l}' = h_{l} + \gamma \cdot \left(\Psi_{l} \Psi_{l}^T\right) h_{l}$$
  where $\gamma \in [0.0, 1.0]$ is the active steering intensity.

---

## 5. Frozen Radix KV-Page Tensors

For each block of $N$ tokens:
* **Key Cache Tensor:** $\mathbf{K} \in \mathbb{R}^{32 \times 16 \times N \times 128}$ (FP8 format).
* **Value Cache Tensor:** $\mathbf{V} \in \mathbb{R}^{32 \times 16 \times N \times 128}$ (FP8 format).
* **Memory Size per Token:** $32 \times 16 \times 128 \times 1 \text{ byte (K)} + 32 \times 16 \times 128 \times 1 \text{ byte (V)} = 131,072 \text{ bytes (128 KiB/token)}$.
* **1,000-Token Shard Block:** Exactly **`128 MiB`** of frozen GPU-ready KV tensors.

---

## 6. Radix Page Splicing Flow

```
[1] Model/Prompt emits Coordinate: ⟦0x01000A1A⟧
                        │
                        ▼
[2] Go Runtime reads KVX Coordinate Table (O(1) Memory Map)
    Locates: Offset = 0x00104000, Pages = 8, Tokens = 512
                        │
                        ▼
[3] vLLM / SGLang PagedAttention Driver (HBM3e Zero-Copy)
    Directly assigns Physical GPU Page IDs to the active RadixNode:
    RadixNode->block_table = [1042, 1043, 1044, 1045, 1046, 1047, 1048, 1049]
                        │
                        ▼
[4] Attention Kernel executes in 0.0 ms prefill latency at 4.8 TB/s HBM bandwidth.
```