docs/README_UPGRADE.md

# DRIFT Upgrade — Pre-Test Execution Guide
## Complete, Ordered Steps. No improvising.

---

## Files in This Package

| File | Purpose |
|------|---------|
| `run_logger.py` | Thread-safe SQLite logger (deadlock-free) |
| `experiment_control.py` | Freeze-mode infrastructure + ablation discipline |
| `dmu_scoring.py` | Corrected additive MPS with score_components |
| `hook_wiring.py` | Reference patterns for memory.py, homeostasis.py, cognition.py |
| `continuity_vector.py` | Five-axis continuity scoring + baseline normalization |
| `collect_baseline.py` | Baseline session runner |
| `ablation_runner.py` | Ablation test suite |
| `inspect_logs.py` | Database inspector for log verification |
| `FALSIFIABILITY.md` | Committed falsifiability statement — do not modify after baseline |

---

## Execution Order (do not skip steps)

### PHASE 1 — Infrastructure

**Step 1: Copy files into DRIFT codebase**
```
run_logger.py          → your project root or utils/
experiment_control.py  → your project root or utils/
dmu_scoring.py         → wire into your existing DMU/memory module
```

**Step 2: Move MPS_WEIGHTS to your config**

In `dmu_scoring.py`, MPS_WEIGHTS is marked for relocation.
Move it to `config.py` or your existing config module.
Import from there in dmu_scoring.py.
Do this before wiring MPS — weight location must be stable.

**Step 3: Wire the three core hooks**

Open `hook_wiring.py` and apply the patterns to:
- `memory.py` — memory store call site
- `homeostasis.py` — state update call site
- `cognition.py` — novelty computation (BEFORE memory.novelty_score is set)

Rules:
- `if control.is_active("memory"):` wraps memory storage
- `if control.is_active("state"):` wraps homeostasis updates
- novelty: freeze check must happen BEFORE propagation to memory object
- DO NOT wire self_modify.py yet — frozen in all initial test configs

**Step 4: Wire stub functions in dmu_scoring.py**

The following must be implemented against your actual codebase:
- `_normalized_contextual_sim()` → your embedding/keyword similarity
- `_state_alignment_score()` → your homeostasis deficit alignment
- `_chromadb_results_to_memories()` → your Memory class factory

**Step 5: Wire stub functions in collect_baseline.py and ablation_runner.py**

Both files have a `_extract_continuity_axes()` stub.
Wire it to your NLP layer (spaCy entities, embedding cosine for tone, etc.)
See continuity_vector.py for operationalization notes per axis.

---

### PHASE 2 — Verification

**Step 6: Run one unfrozen session manually**

Run DRIFT normally (not via ablation_runner) for 20-30 turns.
After the session, run:
```
python inspect_logs.py
```

Verify ALL of the following are present:
- [ ] run_id in runs table
- [ ] git_hash (not "unknown" if in git repo)
- [ ] config logged
- [ ] state_snapshot events present
- [ ] memory_selection events present
- [ ] score_components present in selected memories
- [ ] rejected candidates logged
- [ ] continuity_metrics events present (all 5 axes)
- [ ] run_end event present

**If anything is missing: stop. Fix the wiring. Re-run. Do not proceed.**

---

### PHASE 3 — Baseline Collection

**Step 7: Run three baseline sessions**
```
python collect_baseline.py
```

This runs companion, task, and exploration mode sessions automatically.
Pools data and saves `drift_baseline_stats.json`.
Output will show variance check results per axis.

**If any axis fails variance check: stop. Fix the metric. Re-run.**

**Step 8: Check axis correlations**
After baseline, run correlation check using data from the baseline sessions.
See `continuity_vector.check_axis_correlation()`.
If any pair shows r > 0.6, investigate before proceeding.

---

### PHASE 4 — Ablation Runs

**Step 9: Read FALSIFIABILITY.md**
Read it. It defines what results mean before you see them.
Do not run ablations without having read it.

**Step 10: Identity Collapse run**
```
python ablation_runner.py --test identity_collapse
```

After run: inspect logs. Do not interpret yet.

**Step 11: Scrambled Memory run**
```
python ablation_runner.py --test scrambled_memory
```

**Step 12: Reintroduction Curve**
```
python ablation_runner.py --test reintroduction_curve
```

**Step 13: Compute effect sizes**
Use `ablation_runner.compute_effect_sizes()` with baseline and ablation results.
Report Cohen's d per axis. Thresholds defined in FALSIFIABILITY.md.

---

## Absolute Rules (enforced by code or by discipline)

1. Never run mutation + self_modify + DMU changes simultaneously during testing.
2. Never start a new run without calling end_run() first.
3. Never skip the log inspection step (Step 6).
4. Never run ablations before baseline variance is validated (Step 7).
5. Never move the effect size goalposts after seeing results.
6. Never modify FALSIFIABILITY.md after baseline runs begin.
7. Keep codebase on a stable git commit during each ablation run.
   Branch → freeze → run → merge.

---

## Hardware Notes (OmniSlim CPU-only)

- Sparse counterfactual PEDI: run only on high-variance turns or every N turns.
  Not every turn. Your CPU will not survive it.
- Two-stage retrieval (ChromaDB wide pull → DMU rerank) is the correct pattern.
  Do not try to make ChromaDB do the full scoring.
- Score caching: use `state_hash + node_id + session_id` as cache key.
  Invalidate only when state_delta > threshold or reinforcement updated.
- Metabolism thread: idle-only (30-60 min intervals). Not in the hot path.
- Ollama qwen3:4b fallback: budget for 500%+ CPU under load.
  Do not run ablations during heavy system load.

---

## After the Ablation Suite

Once effect sizes are computed and results are in:
- Document findings against FALSIFIABILITY.md interpretation framework.
- Only then: implement mutation (with dual-anchor + founding_summary).
- Only then: implement dream compression.
- Only then: wire self_modify hooks.

Each of these adds a new drift vector. Add them one at a time with freeze-mode
ablations between additions.

---

## The Question You're Actually Answering

> "Which components of continuity emerge under controlled memory conditions,
>  and what do state and memory each independently contribute?"

Everything in this package is instrumentation for that question.
The answer is whatever the data shows.