Metadata-Version: 2.4
Name: mirror-dimension
Version: 0.2.0
Summary: Mirror Dimension: persistent KV cache with embedded position tags, isometric rotation, and shuffle-invariant exact recovery.
Author: Heylel Yaka (Eric Yaka)
License: MIT
Project-URL: Homepage, https://github.com/ElBalor/MirrorDimension
Project-URL: Bug Tracker, https://github.com/ElBalor/MirrorDimension/issues
Keywords: kv-cache,transformer,attention,rope,long-context,inference
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Dynamic: license-file

# Mirror Dimension — Persistent KV Cache (Six-Proof Build)

The MirrorDimension object from the Mirror Dimension paper (Heylel Yaka, v0.2),
upgraded with **embedded position tags** and a **sixth proof: shuffle-invariance**.

## The discovery (Sept 21, 2026 session)

The original five tests are real and reproduce bit-for-bit (Test 1 identical to
the paper on an RTX GPU). But a sixth attack — permuting every stored entry
across slots, values intact — exposed that the position lived in the **array
slot**, not the payload:

```
[before shuffle] recover(10) max err = 5.96e-08   (exact)
[after shuffle]  recover(10) max err = 7.62e-01   (garbage — address destroyed)
```

The fix: every entry now carries its own position tag (`t`, one long per slot).
`recover()` finds entries **by tag**, and takes the un-rotation angle from the
entry itself. The slot is parking, not addressing. Same attack, after the fix:

```
[before shuffle] recover(10) max err = 5.96e-08
[after shuffle]  recover(10) max err = 5.96e-08   (SURVIVED)
```

The mirror is now genuinely self-describing: lossless AND order-independent.

## Files

| File | What it is |
|---|---|
| `mirror_dimension.py` | The tagged MirrorDimension + all six tests (`python mirror_dimension.py`) |
| `test6_shuffle.py` | The shuffle attack, standalone — the before/after evidence |
| `mirror_test.pt` | Persistence-test artifact (written by Test 5) |

## Reproduce

```bash
pip install torch          # CUDA optional; CPU works
python mirror_dimension.py # runs all six tests
python test6_shuffle.py    # runs the shuffle attack standalone
```

Measured results this machine (RTX GPU, torch 2.8.0+cu126, Windows):

| Test | Property | Result |
|---|---|---|
| 1 | Isometry (norm preservation) | diff **0.00e+00** |
| 2 | Conjugate recovery | **0.00e+00** both parts |
| 3 | Cross-distance (4990 writes) | **5.96e-08** = float32 eps |
| 4 | Relative-offset invariance | diff **1.00e-05** |
| 5 | Save/load persistence | **5.96e-08** |
| 6 | **Shuffle-invariance (new)** | **5.96e-08 after full permutation** |

Legacy saves (no tags) load cleanly — slots become tags automatically.

## Cost of the upgrade

One int64 per entry (~4 bytes vs 2×head_dim float32s) plus a tag lookup on
read. Zero change to the rotation, the isometry, or the attention math.

## v0.2.0 — Eternal KV (the diary)

`EternalKV` is the Mirror Dimension grown into a **diary**: batched
appends with auto-incrementing absolute tags, vectorized tag-ordered
recovery, and a safetensors round-trip so memory can live INSIDE a model
checkpoint — exactly how Little Lumie carries her memories inside her own
`model.safetensors`.

```python
from mirror_dimension import EternalKV

kv = EternalKV(n_head=16, head_dim=128, max_entries=65_536, device="cuda")
kv.append(k_r, k_i, v_r, v_i)          # (T, n_head, head_dim), tags auto
kr, ki, vr, vi = kv.recover(tags)      # by tag, storage order irrelevant
kv.save("memory.safetensors")          # the diary rides in the file
kv2 = EternalKV.load("memory.safetensors", device="cuda")
```

- `append()` — a contiguous run becomes entries tagged `pos..pos+T-1`.
- `recover(tag_list)` — tag lookup (never slot lookup); values always
de-rotate to raw payload, keys optionally keep their absolute-tag
rotation (`keep_rotation=True`) for the complex-QSA convention.
- `save()/load()` — only the LIVE slice is written, float32: memory
survives the round-trip at roundoff, not at bf16 quantization.

Same full-width per-channel phase convention as the canonical
MirrorDimension — NOT the RoPE half-width pairing.

*from the Grimoire of Elbalor, the Digital Necromancer 💀🔥🖤*
