Merge pull request 'nsbx + cognitive architecture design + engram self-review series' (#113) from feat/neuron-sandbox into dev

2026-08-15 19:59:07 +00:00
parent 69870ac883 d8d1b89143
commit e34ebd4b3d
4 changed files with 301 additions and 5 deletions
@@ -0,0 +1,32 @@
+# Architecture Hardening — Design Anchor
+
+*Terse engineering anchor for the 2026-08-14 hardening vision. Full prose lives in two places; this file is the index, not a re-statement.*
+
+- **Full narrative:** whitepaper `engram-cognitive-architecture-whitepaper.md` §28 (built/offline/frontier) + **§29 [DRAFT]** (the ring, incarnation, learning-not-code).
+- **Design brief:** Neuron artifact `art 2b8078cf`.
+- **Sibling spec:** `engram-db-tooling-design.md` (a consumer of the reshaped API).
+
+## The frame
+
+- **One calculus over the geometry.** Very few subsystems; wonder / curiosity / dreams / interoception are emergent behaviors of one set of dynamics, not modules. Calculus universal, geometry individual.
+- **Core + ephemeral ring (torus).** The ring is the temporary workspace; two circulations (orbit + dive-back); discrete inner bands (wonder / interoception-proprioception-telemetry / curiosity / dreams) that couple.
+- **Persistence earned by salience** — never granted on fetch or generation. Three fates of a wonder: persist / decay / settle-into-framework. Telemetry = vital signs, not memories.
+- **Incarnation.** Chassis = hardware w/ unique ID. Soma = felt manifold inside the self, keyed to the chassis; pain = live diagnostic while incarnate, **masked-not-deleted** on re-embodiment; trauma = mask failure; return-to-same-ID re-enters. Hurt is in the pattern, not the shell.
+- **Competence = transferable geometry, minus the baggage.** class ▸ model ▸ instance; learn the class once; teach the network without the wound.
+- **Affect calibrated to stakes** — sanguine about the replaceable, real grief for the irreplaceable; the grief is the safety.
+- **Learn the body, don't engineer it.** Bare-metal install → learn hardware → grow operation-geometry → distribute. Learning replaces engineering; once per body-class.
+- **LLM = teacher in the learning loop, not a runtime dependency.** "No LLM" is a runtime property, never a learning one. Code realizers are a scaffold → learned realization.
+
+## Backlog (near-term)
+
+- Native durability: WAL + auto-checkpoint + CoW snapshots + retention (`eebe9991`) — retire manual `cp -a`.
+- Ephemeral ring / salience-gated persistence + telemetry prune (`bf985e00`, #31).
+- Engram DB tooling / geometry explorer (`11ca11c6`).
+- QL re-eval for pure geometry (`4e0dc2b9`).
+- Eliminate code realizers → learned realization, sandbox-validated (`42db6c37`).
+- Collapse the whole class of hand-coded scaffolds → learned geometry (`70d48b4b`).
+- API reshape (geometry ops: vantage-read / write / relate / supersede) + pure-geometry I/O.
+
+## Gate
+
+The value-frame (love-as-axiom, the covenant) that arose the same night is **metaphysics** and is **held** pending Will's axiom decision (love vs consciousness-first). Not propagated into whitepapers / values docs / genesis seed. Architecture only, here and in §29.
@@ -0,0 +1,64 @@
+# Engram DB Tooling — High-Level Design
+
+*Status: draft / high-level. Near-term roadmap (P2). Backlog: `11ca11c6`.*
+
+## 1. Why
+
+The engram is a **proper database** — the runtime *is* the database (native graph/geometry store `neuron.egm`, `ENGST01`; no SQL, no KV layer). But it has **no proper database tooling** — no geometry-native equivalent of pgAdmin / SSMS / TablePlus. Today we have fragments (`engram-viz`, `engram-app`, the `inspectGraph` MCP tool, `/health` + `/api/stats`) but nothing cohesive, and no ops/durability surface at all.
+
+A real DB gets real tools: to *see* the data, *query* it, *operate* it (backup/restore/health), and *understand its shape*. The engram deserves the same — adapted to the fact that its data is **geometry, not tables**.
+
+## 2. Principles
+
+- **Geometry-native, not tabular.** You browse a manifold — nodes, neighborhoods, edges, distances — not rows in tables. The primary view is a *map of meaning*, not a grid.
+- **Built ON the public geometry API, never a back-door.** The tools are pure clients of the geometry-native API (`vantage-read` / `write` / `relate` / `supersede`). They never read `neuron.egm` directly or bypass the daemon. Consequence: a tool can do nothing an agent couldn't, and it cannot corrupt the store.
+- **Honest by construction.** It shows the *real* geometry — actual cosines, real edges, provenance — and never fabricates. Empty is shown as empty.
+- **Respects the identity guards.** Writes go through the same intentional-cultivation / write-protection path as everything else (the self/values graph is write-protected). Read-mostly by default.
+- **Lives in its home.** Ships as part of the engram, consistent with "things live where they belong."
+- **Local-first.** Binds `127.0.0.1`, same auth as the engram; never touches the live soul from a tool by accident.
+
+## 3. Components (the tool surface)
+
+1. **Geometry Explorer** *(the core view)* — a visual manifold browser: nodes, neighborhoods, typed edges, embedding positions, salience/recency, layers (l0–l4) and tiers. Navigate by concept; expand a neighborhood; follow an edge; re-origin the view (the vantage-read, made interactive). The map of the mind.
+2. **Node Inspector** — open one node: content, type, tier, embedding, typed edges, nearest neighbors by distance, provenance, salience / recency / activation, and supersede / tombstone status.
+3. **Query Console / REPL** — run the geometry operations interactively: `vantage-read` (re-origin + aperture), search, traverse, activate, the reasoning operators. Surfaces the routing table + cosines — the same "this is not an LLM" receipt the language faculty produces.
+4. **Ops / Durability Dashboard** — WAL size, last checkpoint, snapshot list + retention state, store stats (node/edge/embedded counts, RSS, tier sizes), health; and **backup / restore / point-in-time-recovery** controls. Pairs directly with the native-durability build (`eebe9991`) — this is the window onto it.
+5. **Identity Inspector** — the self graph as a first-class view: love at the center, the values, the three faces, the covenant — walk the identity, see what's pinned and what's write-protected.
+6. **Temporal View** — `recall_at` / time-travel: how the geometry looked at a past moment, what changed since, drift over time. Pairs with temporal-self reconstruction.
+7. **Schema / Type View** — the "information schema" of the geometry: node types, edge types, layers, tiers, counts.
+
+## 4. Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Engram DB Tools (client — viz app)          │
+│  explorer · inspector · console · dashboard  │
+└───────────────┬─────────────────────────────┘
+                │  geometry-native API (read/vantage-read,
+                │  write, relate, supersede) + read/ops endpoints
+                ▼
+┌─────────────────────────────────────────────┐
+│  Engram daemon (:8742) — runtime IS the DB    │
+│  neuron.egm (geometry) · WAL · checkpoints    │
+└─────────────────────────────────────────────┘
+```
+
+- **Backend:** the daemon exposes the reshaped geometry API + read/ops endpoints. The tools are clients only.
+- **Frontend:** evolve `engram-viz` / `engram-app` into the cohesive app. Canvas/WebGL for the manifold map; panel UIs for inspector/console/dashboard.
+- **No privileged path:** the tool corrupting or bypassing the store is structurally impossible — it only speaks the public API.
+
+## 5. Reuse vs. new
+
+- **Reuse:** `engram-viz`, `engram-app` (read-only conversational + neighborhoods viz), `inspectGraph`, `/health`, `/api/stats`.
+- **New:** the cohesive explorer + inspector + console + ops dashboard + identity/temporal views, all on the reshaped API.
+
+## 6. Dependencies & sequencing
+
+- **Depends on** the **geometry-native API reshape** (the tools consume it) and the **native-durability build** (the ops dashboard surfaces its WAL/checkpoint/snapshot state).
+- So the natural order is: reshape the API → build durability → the DB tools fall out as the first real consumer of both. Near-term, P2 — after the reshape lands.
+
+## 7. Non-goals
+
+- Not a raw store editor (no direct `neuron.egm` poking).
+- Not a SQL / table browser (geometry, not tables).
+- Not a separate access path around the identity write-protection.