bigmerge
4abeed6bee
The docs described a mind made of subsystems — a grounding subsystem, a wonder manifest, a dreamer on a beat, faculties as arguments to one call. Each of those is a supervisor invented for something that should be a property of the substrate, and two of the documents carrying them are load-bearing for a build agent: cognitive-architecture.design.md says "a build agent executes from this doc", and tools/api-reshape/README.md marks the refuted shapes PROVEN on a live clone. Corrections carried, per lang/spec/correspondence-and-censorship.md (PR #149) and lang/spec/runtime-ownership.md: - Grounding is not a subsystem — it IS the edge weight. grounded-by as a relation type should not exist; grounding is a property of a relation, not a relation between nodes. Never computed on demand. - Faculties are operations, not parameters. reason changes the estimate, induce changes the parameters, abduce changes the structure — a write, which GeoGradient cannot express. A write is not a parameter of a read. - Wonder is the boundary, not a manifest. Curiosity is wonder crystallized at a nucleation site: one thing at two phases. Removed wonder from the operator table in AGENTS.md. - Consolidation is ambient, not scheduled. A brain has no cron job. The presence of a ticker is the diagnostic. - co_registration is deprecated — it averaged a per-edge property into a region scalar, so opposing sites cancelled. GeoEdge.discord replaces it. Nothing new may read it. - In an immutable substrate, any mechanism that refuses a write is either redundant with immutability or an epistemic constraint misfiled as a protective one. The two design docs are marked superseded-in-part with the refutation at the point each claim is made, not rewritten. Preserving what was argued down is the point of an immutable record. Also measured and corrected while verifying the above: engram/README.md documented a Rust engram-core crate on sled with "flat cosine scan until scale demands HNSW" — there is no Rust in engram/ and HNSW is the index; lang/releases/ no longer exists, so both README.md and AGENTS.md pointed at a deleted path for the authored runtime; language.md listed the engram_* and http_* runtimes as stubs. Added language.md §20 for geometry-as-a-value, realizers and transduce (#144), which had landed with no spec coverage. Documentation only. No .c, .h, or .el file is touched.
156 lines
13 KiB
Markdown
156 lines
13 KiB
Markdown
# 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).
|