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