# 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.

> **⚠ The "PROVEN" verdicts in this table were measured against a build dated
> 2026-08-14 and four of the five are now known to have been proving the wrong
> thing (2026-08-16).** A verdict of PROVEN meant *the route returned a
> well-formed response*, not *the response was derivable from what produced it*.
> Corrections below, each with the measurement. Authority:
> `lang/spec/correspondence-and-censorship.md`.

| 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~~ **RETRACTED, then re-proven differently.** The gradients were real in *shape* only: the call passed `NULL` as the anchor, `engram_think` re-origins at `anchor ? anchor : region->centroid`, and **the centroid is the one point where the gradient is zero by construction**. Measured: every faculty returned `{"direction":[0,0,…],"spread":0,"magnitude":1,"confidence":0.5}` — identical, differing only in its label. Fixed in **#141/#142**; gradients now vary by seed |
| `attend` | `attend({node, observer, salience})` | `engram_attend_json` | **PROVEN** (returns `salient-to`) |
| `assert` | `assert({claim, for_whom, floor})` — realize, honesty-floored | `engram_assert_json` | **PARTIAL.** `may_assert` is real. `"still_held"` is a **hardcoded literal `true`** — `el_runtime.c:14538` emits it unconditionally, so it reports nothing it measured. Violates the invariant *a returned value must be derivable from what produced it* |
| `ground` | `ground({claim, evidence, for_whom})` node-id anchors | `engram_ground_json` | ~~PROVEN (grounded-by edge, grounding=0.912, written)~~ **RETRACTED.** That 0.912 was structural, not evidential: the call wrote the edge between the two *region hubs* and echoed them back as though they were the caller's input, so when both seeds resolved into one region it **grounded a node against itself and returned a confident score**. Measured: grounding `3b9ced5d` against `6edf8c79` scored **0.98883** purely because `6edf8c79` is the hub of `3b9ced5d`'s region; two independent agents reported 0.885 / 0.909 self-groundings as confident. **#147** grounds the node asked about, reports `claim_region`/`evidence_region` separately, and refuses three circular shapes. **The operation itself is still the wrong shape** — see below |
| `learn` | `learn({seeds, faculty, keystone})` — the correspondence-beat | `engram_correspondence_beat_json` | **PROVEN, and it was writing into a void.** The Stance, brier and reliability were real and really persisted — but `think` built a *neutral* stance every call and never loaded them, so every beat's calibration was written and thrown away on the next read. Fixed in **#146**: `think` resumes `stance-<faculty>-<hub>`, the same id the beat writes. Confidence **0.5 → 0.930726** on a calibrated region |

### What this table gets structurally wrong

- **`faculty` is not a parameter.** `reason` changes the *estimate* (a read),
  `induce` changes the *parameters* (this is exactly what `learn` does), and
  `abduce` changes the *structure* — a **write**, which `GeoGradient` cannot
  express. A write cannot be a parameter of a read. That the eight were listed as
  interchangeable values of one argument is why all eight returning the same thing
  looked like a pass. Underneath, `engram/src/server.el:1870–1886` routes six of
  them into one call with a string argument, and the name only reaches
  `engram_think` through the stance — `cog_stance_init` stores it and nothing
  reads it.
- **`ground` should not mint an edge at all.** Grounding is not a subsystem and
  not a score: **it is the edge weight.** `grounded-by` as a relation type models
  grounding as a relation *between* nodes when it is a property *of* a relation.
  #147 corrected a scalar rather than deleting the operation; deletion is
  sequenced.
- **`addWonderQuestion`** (Layer 1, `write`) treats wonder as an enumerable
  instance you push. **Wonder is the boundary** — where activation spreads and
  finds thin or absent geometry. There are about six, the same for everyone, and
  they never close. A manifest materializes a property as a stored artifact.

`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.

> **⚠ SUPERSEDED (2026-08-16).** This describes what the surface enforces, which
> is accurate — but the enforcement is the wrong kind of thing:
>
> > **In an immutable substrate, any mechanism that refuses a write is either
> > redundant with immutability, or an epistemic constraint misfiled as a
> > protective one.**
>
> "Keystone" means **load-bearing**, not precious. The real requirement is
> **non-circularity of the reference frame** — a reference fitted to its own
> readings reports perfect correspondence forever while drift becomes undetectable
> from inside — and that is satisfied *temporally*, not by a gate: the frame
> updates while activation is internally seeded, not while it is being used to act.
> **Independence is *when*, not *what*.** Corruption requires mutation, and the
> engram does not mutate: recoverability (the predecessor is always present),
> governance (supersession *is* the audit trail), evidence quality, and rate all
> fall out of the substrate. **Authorization** is the only residue and it is
> bounded — an unauthorized writer can *propose*, never erase. Note also that the
> live check is a substring match against two hard-coded ids
> (`el_runtime.c:14337`).

## 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).
  > **⚠ Retracted in part (2026-08-16).** "The daemon stayed alive and every route
  > returned a well-formed response" is what was actually proven, and that is a
  > weaker claim than it reads as. See the Layer-2 table: `think` was reading at the
  > zero-gradient point, `ground` was scoring nodes against themselves, `assert`
  > emits a hardcoded field, and `learn` was persisting into a void. **A build that
  > passes because nothing checks whether a returned value is derivable from what
  > produced it has not been tested — it has been observed not to crash.** The
  > related discipline gap, also 2026-08-16: **no test without a negative control**
  > (#148's first attempt passed on the unpatched build too), and **no deploy
  > without verifying the artifact carries the fix** (nine instances in one session).
- **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).
