el/tools/api-reshape/README.md

# Neuron API-surface reshape

Design: artifact **0e828907** + design-brief **2b8078cf §5**. Collapse ~90
functional-CRUD MCP tools into a handful of **geometry ops** over the one
geometry, plus the **live agentic primitives** already in the engram cognition
build. **Type is a parameter, not a tool-per-noun.**

Ground-truth: routes verified against the live cognition binary
`engram.cognition-20260814-160045` (route source: branch
`feat/cognitive-architecture`, `engram/src/server.el`). Built + validated on an
**isolated nsbx clone** (`:8900`); live `:8742` untouched.

**The decoration IS the API.** `surface.el` is El-native: each op is one function
decorated with its `@route` (codegen synthesizes `el_route_dispatch` — no
hand-written 90-branch dispatch) and its VBD role (`@accessor` = engram I/O,
`@manager` = agentic orchestration + DHARMA emitter). Handlers call the engram
**in-process** via `engram_*` builtins (not `http_get` — that idiom only existed
because the old MCP wrapper was a separate process). Decorate→serve is **proven**:
`route_proof.el` serves decorated handlers on :8951; `surface.el` compiles and the
dispatcher is generated for all 8 ops. See `SEAM_STAGED.md` for the three-part seam
(route / telemetry+interoception / bus) ground-truth and the staged boundary diff.

**Clone boot recipe (gate-1):** cold-boot from `neuron.egm` with the WAL set aside
(the live-store clone's WAL is torn and loops on replay) + `ENGRAM_WAL=on` (routes
node-writes to the WAL-append path; without it `persist_node`→full-store checkpoint
**segfaults** a clone) + `ENGRAM_GEOMETRY_PRIMING=1`. **Anchors must be node-ids**
(think/ground/learn resolve each seed via `engram_find_node_index`; free text →
"geometry unavailable"). With this recipe the **full op set is proven live on the
clone** (below).

## Layer 1 — geometry ops

| op | signature | engram route | replaces (~) |
|----|-----------|--------------|--------------|
| `read` (vantage-read) | `read({vantage, type?, aperture:{k,depth}})` | GET `/api/search` \| `/api/neighbors/<id>` \| `/api/nodes/<id>` \| `/api/activate` | inspectGraph, searchGraph, traverseGraph, searchKnowledge, browseKnowledge, retrieveKnowledge, inspectMemories, searchEntities, recall, compileCtx, getSelfModel, reviewBacklog, findArtifacts, browseProcesses, listWork, inspectConfig … (~30) |
| `write` | `write({content, type, tags, importance})` | POST `/api/nodes` | remember, captureKnowledge, draftArtifact, planWork, defineProcess, addWonderQuestion, logInternalStateEvent … (~15) |
| `relate` | `relate({from, to, relationship, weight?})` | POST `/api/edges` | linkEntities, linkCausal, restructureCausalGraph, pin |
| `supersede` | `supersede({id, action: evolve\|supersede\|tombstone\|promote, content?})` | write+relate(`supersedes`) / DELETE `/api/nodes/<id>` (immutable marker) | evolveMemory, evolveKnowledge, forget→tombstone, promoteKnowledge, reviseArtifact, trackWork, progressWork(update) … (~15) |

**Vantage-read = the whole-self-dump fix.** Re-origin at a point + salience +
recency + **aperture** → a *bounded* slice. Aperture (`k`/`depth`) caps output:
measured on the clone, `limit=3 → 15 KB` vs `limit=50 → 363 KB`. The old path
returned 60k–230k-char unbounded traversals (this very session hit 104 KB and
409 KB live).

## Layer 2 — primitive agentic tools (Neuron runs itself)

The base verbs all agentic behavior composes from — grounded in the LIVE
cog-arch (`think` is the one operation; faculties are its steering-space labels;
the correspondence-beat is the reflexive learning loop).

| op | signature | engram builtin | status on clone (gate-1 recipe) |
|----|-----------|----------------|---------------------------------|
| `think` | `think({seeds, faculty})` faculty ∈ reason·abduce·induce·plan·analogize·recognize·discern·synthesize | `engram_think_json` | **PROVEN** — all 8 faculties return real 768-dim gradients (n_support 30–282) |
| `attend` | `attend({node, observer, salience})` | `engram_attend_json` | **PROVEN** (returns `salient-to`) |
| `assert` | `assert({claim, for_whom, floor})` — realize, honesty-floored | `engram_assert_json` | **PROVEN** |
| `ground` | `ground({claim, evidence, for_whom})` node-id anchors | `engram_ground_json` | **PROVEN** (grounded-by edge, grounding=0.912, written) |
| `learn` | `learn({seeds, faculty, keystone})` — the correspondence-beat | `engram_correspondence_beat_json` | **PROVEN** (real Stance: `stance-induce-…`, brier, reliability, written) |

`comprehend`/`realize`/`intend` are **compositions**, not separate live
primitives: comprehend = write+activate (world→geometry), realize = assert
pointed at the world (geometry→act), intend = attend at a goal-region. The
skill-learning loop (decompose→detect-gap→reach-out-on-sparsity→verify-by-
execution→integrate) composes over `think`+`ground`+`learn`+`write`/`relate`.

## Identity is write-protected

`write(type=self|values)`, and `relate`/`supersede` touching the keystones
`kn-efeb4a5b…` / `kn-5b606390…`, are refused — identity routes through
intentional-cultivation, as enforced today.

## How the caller invokes Neuron agentically

Once the ops are registered as MCP tools (aliases in `surface.el`), the caller
(Claude, this loop) calls e.g.:

```
neuron.think({ seeds: "kn-efeb4a5b…", faculty: "plan" })   # Neuron reasons over its own geometry
neuron.attend({ node: <region> })                           # aim its attention
neuron.learn({ seeds: <region>, faculty: "induce" })        # calibrate its own prior (correspondence-beat)
neuron.read({ vantage: "self", aperture:{k:12} })           # bounded self-slice (no dump)
```

and **Neuron does the agentic work over its own geometry** — the beginning of it
running itself.

## Files
- `surface.el` — the reshaped surface as **decorated El-native components** (`@route` + `@accessor`/`@manager`, in-process `engram_*` builtins). Compiles; dispatcher generated for all 8 ops.
- `route_proof.el` — a standalone decorated El service that **proves decorate→serve** on :8951 (built with the worktree-rebuilt `elc-route`).
- `SEAM_STAGED.md` — the three-part seam (route / telemetry+interoception / bus) ground-truth + the exact staged `cg_fn` diff for boundary auto-emit.
- `agentic_loop.el` — the four-call loop (think→attend→learn→read) as compilable El.
- `parity.sh` — API-level parity harness against the clone.

## Honest ledger (built vs staged)
- **Route seam — IMPLEMENTED + PROVEN:** ported the `@route` codegen (from `feat/el-route-decorators`) into the worktree, rebuilt `elc` self-host, proved decorate→serve (`route_proof.el` on :8951); `surface.el` compiles with `el_route_dispatch` generated for all 8 ops.
- **All ops PROVEN live on the clone** (gate-1 boot recipe, node-id anchors): read, write, relate, supersede (immutable), tombstone, think (8 faculties), ground, attend, learn — daemon alive through all mutations (node_count 13173→13176).
- **Aperture-boundedness PROVEN:** vantage-read `limit=3 → 15 KB` vs `limit=50 → 363 KB` (fixes the whole-self dump).
- **Bus:** `@manager` ops emit on the real `dharma_*` bus (explicit today, compiles) — same transport as the swarm (`wt/swarm-ccr`).
- **STAGED (not guessed — needs the cognition-engram rebuild to verify link):** auto-injecting telemetry/interoception + bus emission at the decorated boundary (`cg_fn` diff in `SEAM_STAGED.md`); building the cognition engram with `surface.el` compiled in. No promote to live, no cutover (per rails).