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.

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