neuron/docs/runbooks/2026-08-12-geometry-priming-cutover-reversal.md

Runbook — M9 Geometry Priming: Cutover & Reversal

Date: 2026-08-12 Component: engram activation (lang/runtime/el_runtime.c → engram_activate) Branch: engram-tiered-storage Flag: ENGRAM_GEOMETRY_PRIMING (env, default OFF = current M8 behavior, byte-identical) Blast radius if wrong: the core recall path of Will's live memory. Treat with according care.

---

1. What changes

This is the first behavior-changing step that touches the core recall/priming path. It wires the M9 mean-centered relational-neighborhood geometry (engram_geometry.c, shipped commits 2a4c5c6 foundation + 8cae0f9 centering) into engram_activate seed selection, and it does so behind a reversible env flag that defaults OFF.

• Flag OFF (default): engram_activate runs the exact M8 code path. The new code is a single if (eg_geometry_priming_on() && …) block that short-circuits on the first term, plus a few unused static helpers and one zero-initialized counter. No behavioral change.
• Flag ON (ENGRAM_GEOMETRY_PRIMING=1): after M8 produces its ANN seed set, the centered geometry of that neighborhood is computed and used to, composing with (never replacing) M8's ANN candidate generation:
  1. Damp off-domain seeds — each M8 seed's activation is scaled by a damp-only factor lo + (1-lo)·membership ∈ [lo, 1] (default lo=0.5). The neighborhood anchor (membership→1) is unchanged; seeds that are semantically off-domain in the centered frame lose weight. This is the disambiguation win. It can only sharpen, never amplify.
  2. Prime the neighborhood sub-threshold — descriptor members not already seeded get a warm floor activation = membership · scale (default scale=0.08, strictly below the WM promotion gate 0.15), capped at ENGRAM_GEO_PRIME_MAX (default 32), ISE nodes skipped. They enter the frontier so a warm gradient spreads one hop, then dies at the BFS 0.02 cutoff. Safe because the BFS keeps the max (el_runtime.c if (!reached || new_act > best_bg)): priming only raises a floor, it can never cap a stronger legitimate activation.

Why default-OFF makes deploying the binary behavior-neutral

Because every line of the new logic is gated behind ENGRAM_GEOMETRY_PRIMING, deploying the new binary with the flag unset is behavior-neutral — it is the M8 activation path, verified byte-identical in the A/B (flag-OFF promoted-node sets equal the pre-M9 M8 binary's, per-query). Enabling the geometry is then a single reversible flag flip, not a redeploy.

---

2. The flag

Env var	Default	Effect
ENGRAM_GEOMETRY_PRIMING	unset / 0	OFF — exact M8 behavior.
ENGRAM_GEOMETRY_PRIMING=1	—	ON — centered-geometry seed damping + sub-threshold priming.
ENGRAM_GEO_SEED_LO	0.5	Seed damp floor (factor ∈ [LO,1]). 1.0 disables damping.
ENGRAM_GEO_PRIME_SCALE	0.08	Warm-floor scale; clamped (0, WM_gate=0.15).
ENGRAM_GEO_PRIME_MAX	32	Max primed members per activation (0 disables priming).

The flag is read once per process (cached), so enabling/disabling requires a process restart of the engram service — it is not hot-togglable within a running process.

---

3. How to enable live (deliberate, reversible)

Precondition: the default-OFF binary has already been deployed and is running the M8 path healthily (behavior-neutral deploy). Do this only with Will present, per the standing rails.

1. Snapshot first (always, before any activation-behavior change): ~/.neuron/backups/pre-geometry-priming-<ts>/ ← copy neuron.egm, neuron.wal, the current engram binary, and ai.neuron.engram.plist.
2. Add ENGRAM_GEOMETRY_PRIMING=1 to the engram service environment (ai.neuron.engram.plist EnvironmentVariables).
3. launchctl bootout gui/$(id -u)/ai.neuron.engram → launchctl bootstrap … (restart so the flag is re-read).
4. Verify: service comes up serving the same node count; /api/act-stats shows sane WM (promoted ≤ 24); spot-check 3–4 real queries return coherent results; watch one heartbeat cycle for crashes/latency. The geo_primed counter (if surfaced) should be > 0.

---

4. Rollback (exact steps)

Rollback is a flag flip, not a data operation — the store is untouched by enabling the flag, and priming is a read-mostly, bounded, sub-threshold addition.

Fast path (preferred) — disable the flag:

1. Remove ENGRAM_GEOMETRY_PRIMING (or set =0) from ai.neuron.engram.plist.
2. launchctl bootout … && launchctl bootstrap ….
3. Verify: service healthy, activation is the M8 path again. Done — no data change to undo.

Full path (only if the binary itself is suspect) — redeploy prior binary:

1. launchctl bootout gui/$(id -u)/ai.neuron.engram.
2. Restore the prior engram binary from ~/.neuron/backups/pre-geometry-priming-<ts>/.
3. Restore ai.neuron.engram.plist from the same backup (flag absent).
4. launchctl bootstrap …; verify node count + a self-traversal + write-survives-restart.
5. If (and only if) the store was somehow mutated: restore neuron.egm + neuron.wal from the backup. Note: enabling the flag does not write geometry to the store, so this step is expected to be unnecessary — the primed activations are per-call and non-persistent beyond the ordinary background_activation/WM write-back that M8 already does.

Rollback triggers: any crash/hang in engram_activate; WM promotion count exceeding the cap or collapsing; a measured recall/coherence regression vs the OFF baseline; unacceptable latency increase; any ASan/UBSan report under the flag.

---

5. Reversibility guarantees (why this is low-risk to deploy, higher-care to enable)

• Deploy (flag OFF): byte-identical to M8. Verified in A/B. Zero-risk redeploy.
• Enable (flag ON): bounded and composable —
  • never removes an M8 seed (damp-only, factor ≥ lo > 0);
  • never amplifies a seed above its M8 value (factor ≤ 1);
  • priming is strictly sub-threshold (scale < WM_gate) and capped (PRIME_MAX);
  • priming raises a floor only (BFS keeps max) — cannot cap real activation;
  • does not write geometry to the durable store;
  • degrades to exact M8 behavior for any call where the paged store / centered global mean / embedder is unavailable (guarded, not crashing).
• Disable: one env removal + restart; no data to reconcile.

---

6. Known caveats / uncertainties (flagged — this is the memory core)

• Perf cost of ON: the descriptor (covariance eigensolve + store_get_node paged reads per member) runs on every activation when the flag is ON. See docs/architecture/design/perf/engram-geometry-priming-profile.md for the measured OFF-vs-ON latency. If that delta is unacceptable, keep the flag OFF (deploy stays valid) and revisit with a cached/periodic descriptor.
• Two-store consistency: the descriptor reads embeddings from the paged store while the ANN index is over the resident array. This-call backfilled embeddings can lag the paged store by ≤ ENGRAM_EMBED_BACKFILL_PER_CALL nodes — the same staleness class as the M8 vindex, and it can only omit a member, never mis-prime.
• Damp tuning: lo=0.5 can at most halve an off-domain seed. If a coherence regression is observed, raise ENGRAM_GEO_SEED_LO toward 1.0 (→ priming-only, no damping) before disabling entirely.