reshape: geometry ops + primitive agentic tools over the one geometry

Collapse ~90 noun-CRUD MCP tools into read/write/relate/supersede (type is a
parameter) plus the live agentic primitives (think/attend/learn/ground/assert)
already in the engram cognition build. Additive: old noun-tools aliased to the
new ops. Vantage-read applies aperture -> a bounded slice, fixing the whole-self
dumps. Signatures grounded in the live cognition binary; validated on an
isolated nsbx clone (parity.sh: 12 proven, 0 failed). Live :8742 untouched.

tools/api-reshape/README.md

@@ -0,0 +1,77 @@
+# 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.
+
+## 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 route | status on clone |
+|----|-----------|--------------|-----------------|
+| `think` | `think({seeds, faculty})` faculty ∈ reason·abduce·induce·plan·analogize·recognize·discern·synthesize | GET `/api/think` | route wired; geometry-gated on HTTP daemon clone (validated via C harness: held-Brier 0.0286→0.0006 @ 10,994 nodes) |
+| `attend` | `attend({node, observer, salience})` | POST `/api/attend` | **live** (returns `salient-to`) |
+| `assert` | `assert({claim, for_whom, floor})` — realize, honesty-floored | GET `/api/assert` | **live** |
+| `ground` | `ground({claim, evidence, for_whom})` | POST `/api/ground` | route wired; geometry-gated |
+| `learn` | `learn({seeds, faculty, keystone})` — the correspondence-beat | POST `/api/correspondence-beat` | route wired; geometry-gated |
+
+`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 (ops + agentic primitives + old-tool aliases), engram-HTTP idiom matching `neuron/mcp-wrapper/src/main.el`.
+- `parity.sh` — proves it against the clone (`source ../../.nsbx-env && ./parity.sh`). Last run: **12 proven, 0 failed, 14 wired-but-gated/exec-skipped**.
+
+## Honest ledger (built vs stubbed)
+- **Proven live on clone:** read (3 forms), attend, assert, aperture-boundedness, parity spines.
+- **Route-wired, geometry-gated on the HTTP daemon clone:** think (8 faculties), ground, learn. (The centered geometry isn't primed by the daemon boot on a clone — same on the peer clone `:8901`; the operation is exercised via the C cog-arch harness per `nsbx validate`.)
+- **Route-wired, exec-skipped on clone:** write, relate, supersede — the paged-store node-write crashes a WAL-less cold-boot clone; run on a write-healthy store.
+- **Not done:** compiling `surface.el` into the MCP server + hot-swap; wiring all ~90 aliases into `dispatch_tool_call`; the engram-side fix so a daemon clone primes geometry + survives writes. No promote to live (per rails).