diff --git a/HANDOFF-engram-write-corruption.md b/HANDOFF-engram-write-corruption.md index 32243a4..1ac259f 100644 --- a/HANDOFF-engram-write-corruption.md +++ b/HANDOFF-engram-write-corruption.md @@ -99,3 +99,28 @@ Added `engram_valid_node_type` / `engram_valid_tier` allowlists. Both `engram_no - **No `PUT`/`DELETE`** on knowledge nodes (`method not allowed`) — needed for UI edit/delete. - No **source-conversation** edge on captured nodes — blocks "see source chat" in the UI. - Writes have been **frozen since ~2026-04-29** (newest knowledge node) — nothing is being added in the current running state. + +--- + +## ADDENDUM — Phase 0 live runtime findings (2026-06-08, verified against the running system) + +Validated the write path end-to-end against `neuron-fresh :7770` + `engram :8742`. Confirms the diagnosis and corrects two common assumptions. + +**Ports:** `engram :8742` ✓ listening (healthy: `{"status":"ok","engine":"engram-runtime-native"}`), `neuron-fresh :7770` ✓, **`:7771` NOT listening.** + +**Two distinct write failures (not one):** +1. **`/api/neuron/knowledge/capture` + memory remember** — handled **in-process by the soul** (`neuron-api.el` `handle_api_capture_knowledge` / remember → `engram_node_full(...)`). Live test: `POST …/knowledge/capture` returned `{"id":"2ccfc147…","ok":true}` but that id is **absent from `/api/graph/nodes` and `snapshot.json`** → the node corrupted/vanished. **This is exactly the `engram_node_full` wrapper bug this PR fixes.** It is NOT a `:7771` issue. → fixed by el PR #52 + soul rebuild. +2. **`/api/backlog`, `/api/memories`, `/api/knowledge`, `/api/artifacts`, `/api/projects`, `/api/imprints`** — `routes.el` proxies these to **`axon`** via `axon_get`/`axon_post` (base `SOUL_AXON` or default **`http://localhost:7771`**). `axon` = **`protocols/axon`, an unbuilt Rust crate**, not running → "Failed to connect to localhost port 7771." → needs axon stood up (separate Rust workstream) OR routes repointed. + +**Architecture clarifications (so nobody chases the wrong port again):** +- The soul runs in **file-snapshot mode** (no `ENGRAM_URL` in `/tmp/soul-keepalive.sh`) → it uses `~/.neuron/engram/snapshot.json`, **not `engram :8742` live**. So writing to `:8742` does NOT make data visible to the soul the app talks to. +- `engram :8742` is its own EL service (`engram/src/server.el`) with a **working CRUD API**: `POST/GET/DELETE /api/nodes`, `/api/edges`, `/api/save`, `/api/load`, `/api/activate`, `/api/search`. Verified create+delete (`{"ok":true}`). **But** its `route_create_node` only reads `content/node_type/salience` — **no label/tier/tags/metadata** — so it can't set `metadata.tier_source: canonical`. +- Minor EL bug in `engram/src/server.el route_create_node`: `if str_eq(node_type,""){ let node_type = "Memory" }` **shadows** (new local) instead of reassigning → the default never applies; same for `salience`. Worth fixing while in there. + +**Verification plan (run after the soul rebuild lands):** +1. `POST /api/neuron/knowledge/capture {content,title,tier:canonical}` → capture the returned id. +2. `GET /api/neuron/knowledge/search?q=` → confirm the node comes back with correct `node_type`/`metadata.tier_source`. +3. Confirm it survives a snapshot save (present in `snapshot.json`). Only then is the write "real." +4. Backlog: once `axon :7771` is up, repeat for `POST /api/backlog`. + +**Net:** "make writes persist" needs (a) **this wrapper fix built into the soul** (capture) and (b) **`axon :7771` running** (backlog/artifacts/etc.). Neither was doable on Tim's box (no `elc`; `axon` is unbuilt Rust — out of scope per the no-Rust guardrail). No live writes/restarts were performed; engram probe node was created and deleted to verify the API.