# KAI v9.2.0 — Implementation Plan for Antigravity

> **Codex v9.10.64** · Track 4 archive · Codex §Comprehensive Plans  
> **AI / low-credit:** Historical spec — verify shipped before re-implementing; on stop log `Last worked` / `Next`.

**Author:** spec written by a separate model (Claude) for Antigravity to implement in-project.
**Goal:** Two features, both touching critical data. Implement **exactly** as specified, behind version gates, with backups and round-trip verification. **Do not "improve" or restructure beyond this spec.** If anything is ambiguous, stop and ask — do not guess on the connectome path.

**Two deliverables:**
1. Connectome storage fix — kill the 9.4 GB `data/kai-meta.json` bloat (label interning + zstd + streaming load). *Zero data semantics change.*
2. Memory-decay "Last Judgment" — score expiring backups before annihilation.

---

## 0. NON-NEGOTIABLE SAFETY PROTOCOL (do this first, every time)

1. `git add -A && git commit -m "pre-v9.2.0 checkpoint"` so everything is reversible.
2. Copy the whole `data/` dir: `Copy-Item C:\KAI\data C:\KAI\data_BACKUP_v910 -Recurse`.
3. Implement each feature **behind a format-version bump**, never by overwriting the old reader.
4. After build, run the **round-trip verification** in each section. Do **not** delete the backup or the old file until verification passes.
5. The connectome (`SynapticLayer`, ~20.7M LTP events) is irreplaceable. Treat every change to its save/load as if one wrong byte loses real memory — because it can.

Build command (production, GPU on): `cargo build --release --bin kai` (default features already include `gpu`).

---

## 1. CONNECTOME STORAGE FIX (the 9.4 GB problem)

### Diagnosis (confirmed by sampling, do not re-litigate)
`data/kai-meta.json` (currently `version:3`) stores `synaptic_layer.synapses` as an array where **every synapse carries its full `pre_label` and `post_label` text** (long sentences), massively duplicated, plus a parallel text-keyed index. The data is valid; only the encoding is wasteful. JSON parse balloons 2–3× → 22–30 GB transient RAM at boot.

### Files in scope
- `src/persistence.rs` — where the meta sidecar is written/read (`save_compact*`, `load_compact`/`load`, the meta JSON).
- `src/core/synapse.rs` — `SynapticLayer` / `Synapse` structs.
- Any struct deriving `Serialize`/`Deserialize` for the meta JSON.

### Design — label interning + zstd + streaming (format `version:4`)
1. **Interning (in the serialized form only; in-memory `Synapse` may stay as-is):**
   - On save, build a `Vec<String> label_table` of unique labels and a `HashMap<&str,u32>` for dedup.
   - Serialize each synapse as `{ "p": <u32 pre_idx>, "q": <u32 post_idx>, "w": f32, "t": u32 last_fire_tick, "c": u32 fire_count }`.
   - Write `label_table` once at the top of the synaptic section.
   - Apply the same interning to the text-keyed index (store labels by index).
   - Set meta `"version": 4`.
2. **Compression:** write the meta as `data/kai-meta.json.zst` (zstd level 3–6). Keep writing the `.bin.zst` cells exactly as today.
3. **Streaming load (no giant String):**
   - Loader resolution order: if `kai-meta.json.zst` exists → open file → `zstd::Decoder` → `BufReader` → `serde_json::from_reader`. Else if `kai-meta.json` exists → `BufReader` → `from_reader`.
   - **Backward compatibility (critical):** branch on the `version` field.
     - `version <= 3`: parse the **old** schema (full-text `pre_label`/`post_label`) exactly as today. This is how the existing 9.4 GB file still loads.
     - `version >= 4`: parse interned schema, rebuild full `Synapse` labels from `label_table`.
   - **Migration:** after a successful old-format load, the next `save_compact` writes `version:4` + `.zst`. Leave the old `kai-meta.json` in place until verification passes; do not delete it in code.

### Round-trip verification (MUST pass before trusting)
Add a one-shot check (a `--verify-meta` bin subcommand or a test):
1. Load current `data/` (old v3). Record: `synapse_count`, `sum(weight)` (to 6 dp), `sum(fire_count)`, `total_ltp`, `total_ltd`, `total_pruned`.
2. Save as v4 (`.json.zst`), then load v4 into a fresh `Universe`.
3. Assert **every** recorded metric is identical, and `label_table` round-trips (no label dropped/empty).
4. Assert new file size is dramatically smaller (expect a few hundred MB) and boot RSS peak is far below the prior 22–30 GB.
Only after all asserts pass: keep v4, archive the old json.

### Acceptance
- Synapse count + weight sums + LTP/LTD/pruned identical before/after. ✅
- `data/kai-meta.json.zst` ≪ 9.4 GB. ✅
- Launch RAM peak materially reduced. ✅
- Old-format files still load (don't break existing/backup snapshots). ✅

---

## 2. MEMORY-DECAY "LAST JUDGMENT"

### Behavior
Before annihilating Tribunal snapshots at 3 days, score each for usefulness; reprieve the worthy, annihilate the rest. Count floats with how many pass.

### 2a. Engine endpoint — `src/bridge/oracle_server.rs`
Add a route arm (match the existing routing style, e.g. alongside `"/api/lattice/rebuild-index"`):
- `POST /api/judge-snapshot` body `{ "path": "<absolute path to snapshot dir>" }` → `200 { "score": f32, "verdict": "reprieve"|"annihilate", "factors": { "used": f32, "novelty": f32, "resonance": f32 }, "sampled": u32 }`.
- Handler:
  1. `persistence::load_compact(path)` into a temp `Universe` (read-only; never mutate the live one). If load fails → `200 { score: 0.0, verdict: "annihilate", error: "unreadable" }` (a dead snapshot earns no reprieve).
  2. Sample up to `N = 256` cells (deterministic stride).
  3. **used** = mean over sampled of `min(confidence/5.0, 1.0)` blended with access/fire signals if present.
  4. **novelty** = fraction of sampled cells whose top-1 cosine vs the **live** universe is `< 0.92` (i.e. the live brain does NOT already have it). Use the existing live-lattice query path (cosine/`predictive_query`); read-only.
  5. **resonance** = mean `phasor_coherence(cell, live drive.goal_vector)` clamped to `[0,1]` (if `goal_vector` is null, resonance = 0.5 neutral).
  6. `score = 0.4*novelty + 0.35*used + 0.25*resonance`. `verdict = "reprieve" if score >= THRESHOLD else "annihilate"` (THRESHOLD const = `0.5`).
- Must be **read-only** w.r.t. the live universe and must not block the main loop (spawn/scoped lock, drop lock before heavy work).

### 2b. Prune script — `tools/backup-kai.ps1`
Replace the blind annihilation block (the `AddDays(-3)` delete of `Archive_Trash`) with:
```powershell
$THRESHOLD = 0.5
$engine = "http://127.0.0.1:3334/api/judge-snapshot"
foreach ($trash in (Get-ChildItem $archiveTrash -Directory | Where-Object { $_.CreationTime -lt (Get-Date).AddDays(-3) })) {
    $verdict = "annihilate"; $score = $null
    try {
        $resp = Invoke-RestMethod -Uri $engine -Method POST -TimeoutSec 30 `
            -ContentType "application/json" -Body (@{ path = $trash.FullName } | ConvertTo-Json)
        $score = $resp.score; $verdict = $resp.verdict
    } catch {
        # Engine unreachable -> SAFE FALLBACK: keep current behavior (annihilate >3d), log it.
        Write-Host "[KAI Judgment] Engine unavailable; default annihilation for $($trash.Name)."
        $verdict = "annihilate"
    }
    if ($verdict -eq "reprieve") {
        New-Item -ItemType File -Path (Join-Path $trash.FullName "REPRIEVED.flag") -Force | Out-Null
        Write-Host "[KAI Judgment] REPRIEVED ($([math]::Round($score,3))): $($trash.Name)"
    } else {
        Remove-Item $trash.FullName -Recurse -Force
        Write-Host "[KAI Judgment] Annihilated ($(if($null -ne $score){[math]::Round($score,3)}else{'no-score'})): $($trash.Name)"
    }
}
```
- A reprieved snapshot gets a `REPRIEVED.flag`; it survives this pass. (Optional next cycle: re-judge; reprieve is not permanent immortality — define a max reprieve count later if desired.)
- **Do not** change the 7-day decay step (move >7d into Tribunal) — that logic is already correct.

### Acceptance
- With engine up: snapshots scoring `>= 0.5` keep a `REPRIEVED.flag` and survive; the rest delete. ✅
- With engine down: behaves exactly like today (annihilate >3d), no errors. ✅
- Endpoint never mutates or blocks the live universe. ✅

---

## 3. ALSO INCLUDED IN THIS REBUILD (already coded by Claude this session — just verify they compile)
These are already edited in the tree; the same `cargo build --release --bin kai` activates them:
- `oracle_server.rs`: brain auto-save loop `from_secs(60)` → `from_secs(600)` (10-min autosave).
- `idle_ingest.rs`: background pool `0.85` → `0.34` of cores.
- GPU: build with **default features** (do NOT pass `--no-default-features`; that flag is Codespaces-only).
- `.env`: `GEMINI_LIVE_MODEL=models/gemini-3.1-flash-live-preview` (+ stable `gemini-2.5-flash-native-audio` fallbacks in leo.mjs/native-bot.mjs/gemini-live-bridge.mjs).
Confirm these compile cleanly; if `cargo build` errors on any, fix the smallest thing and report — don't refactor around them.

---

## 4. ORDER OF OPERATIONS
1. Safety protocol (§0).
2. Implement §1 (connectome) → build → run §1 verification. **Stop if it fails.**
3. Implement §2 (Last Judgment) → build → run §2 acceptance.
4. Full boot: confirm vitals timeouts gone, RAM peak down, GPU engaged, fleet order Oracle→KAI→industrial→social.
5. Bump version to **v9.2.0** in `The KAI Codex.md` header and add a SYSTEM STATE SUMMARY entry describing exactly what landed and the verification results.
6. `git commit` the verified result.

## 5. ROLLBACK
If any verification fails or boot misbehaves: `git checkout -- .` (or reset to the §0 checkpoint) and restore `data_BACKUP_v910`. Report which assert failed with numbers; do not attempt blind fixes on the connectome path.