Remove __pycache__ .pyc files accidentally included in the projector commit

audio-surface.el / image-surface.el: own-core additive-synthesis WAV and
raster-PNG renderers (integer-only DSP, since EL has no floats), rendered
from learned engram signatures via a pluggable surface-profile
abstraction (surface-profile.el). audio-demo.el / image-demo.el are
drivers. NOTE: demo files hardcode absolute paths to this worktree's own
directory — will need a path fixup before landing.

elp/projector/ is a Python package the author's own README marks as
"STAGING/PROOF-OF-SHAPE — not the deliverable", superseded by the native
.el surface-profile work above; kept as a validated architecture proof.
Generated output (elp/faculty/{out,sig}, elp/projector/out,
__pycache__) intentionally excluded.

.gitea/workflows/ci-dev.yaml

@@ -214,9 +214,18 @@ jobs:
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
         run: |
+          # Fail loudly: previously this step had no `set -e`, so an auth or
+          # upload failure was swallowed (step exited 0 on the trailing echo)
+          # and the SDK silently never published. Surface failures now.
+          set -euo pipefail
+          if [ -z "${GCP_SA_KEY:-}" ]; then
+            echo "FATAL: GCP_SA_KEY secret is empty — cannot authenticate to publish" >&2
+            exit 1
+          fi
           echo "${GCP_SA_KEY}" > /tmp/gcp-key.json
           gcloud auth activate-service-account --key-file=/tmp/gcp-key.json
           gcloud config set project neuron-785695
+          echo "Publishing as active account: $(gcloud config get-value account 2>/dev/null)"
 
           VERSION="${GITHUB_SHA:0:8}"
 
@@ -268,6 +277,12 @@ jobs:
         # Patches ci-base:dev in-place: pulls the existing image (which has all
         # system deps — Node, Go, gcloud, Docker CLI, etc.) and overlays the freshly
         # built El SDK on top. Keeps the full ci-base rebuild fast and incremental.
+        #
+        # continue-on-error: this is a CI-cache optimization, NOT the release
+        # artifact. It runs Docker (pull/build/push ~600MB) on the host-mode GCE
+        # runner where DinD/Docker availability is fragile. A failure here must
+        # never block or redden the job — the SDK publish above is the deliverable.
+        continue-on-error: true
         if: github.event_name == 'push'
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}

.gitea/workflows/ci-stage.yaml

@@ -212,12 +212,21 @@ jobs:
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
         run: |
+          # Fail loudly: previously this step had no `set -e`, so an auth or
+          # upload failure was swallowed (step exited 0 on the trailing echo)
+          # and the SDK silently never published. Surface failures now.
+          set -euo pipefail
+          if [ -z "${GCP_SA_KEY:-}" ]; then
+            echo "FATAL: GCP_SA_KEY secret is empty — cannot authenticate to publish" >&2
+            exit 1
+          fi
           echo "${GCP_SA_KEY}" > /tmp/gcp-key.json
           apt-get install -y -qq apt-transport-https ca-certificates curl
           echo "deb [trusted=yes] https://packages.cloud.google.com/apt cloud-sdk main" > /etc/apt/sources.list.d/google-cloud-sdk.list
           apt-get update -qq && apt-get install -y google-cloud-cli
           gcloud auth activate-service-account --key-file=/tmp/gcp-key.json
           gcloud config set project neuron-785695
+          echo "Publishing as active account: $(gcloud config get-value account 2>/dev/null)"
 
           VERSION="${GITHUB_SHA:0:8}"
 
@@ -253,6 +262,12 @@ jobs:
         # Patches ci-base:stage in-place: pulls the existing image (which has all
         # system deps — Node, Go, gcloud, Docker CLI, etc.) and overlays the freshly
         # built El SDK on top. Keeps the full ci-base rebuild fast and incremental.
+        #
+        # continue-on-error: this is a CI-cache optimization, NOT the release
+        # artifact. It runs Docker (pull/build/push ~600MB) on the host-mode GCE
+        # runner where DinD/Docker availability is fragile. A failure here must
+        # never block or redden the job — the SDK publish above is the deliverable.
+        continue-on-error: true
         if: github.event_name == 'push'
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}

.gitea/workflows/sdk-release.yaml

@@ -288,12 +288,21 @@ jobs:
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
         run: |
+          # Fail loudly: previously this step had no `set -e`, so an auth or
+          # upload failure was swallowed (step exited 0 on the trailing echo)
+          # and the SDK silently never published. Surface failures now.
+          set -euo pipefail
+          if [ -z "${GCP_SA_KEY:-}" ]; then
+            echo "FATAL: GCP_SA_KEY secret is empty — cannot authenticate to publish" >&2
+            exit 1
+          fi
           echo "${GCP_SA_KEY}" > /tmp/gcp-key.json
           apt-get install -y -qq apt-transport-https ca-certificates curl
           echo "deb [trusted=yes] https://packages.cloud.google.com/apt cloud-sdk main" > /etc/apt/sources.list.d/google-cloud-sdk.list
           apt-get update -qq && apt-get install -y google-cloud-cli
           gcloud auth activate-service-account --key-file=/tmp/gcp-key.json
           gcloud config set project neuron-785695
+          echo "Publishing as active account: $(gcloud config get-value account 2>/dev/null)"
 
           VERSION="${GITHUB_SHA:0:8}"
 
@@ -345,6 +354,12 @@ jobs:
         # Patches ci-base:latest in-place: pulls the existing image (which has all
         # system deps — Node, Go, gcloud, Docker CLI, etc.) and overlays the freshly
         # built El SDK on top. Keeps the full ci-base rebuild fast and incremental.
+        #
+        # continue-on-error: this is a CI-cache optimization, NOT the release
+        # artifact. It runs Docker (pull/build/push ~600MB) on the host-mode GCE
+        # runner where DinD/Docker availability is fragile. A failure here must
+        # never block or redden the job — the SDK publish above is the deliverable.
+        continue-on-error: true
         if: github.event_name == 'push'
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}

AGENTS.md

@@ -1,146 +0,0 @@
-# AGENTS.md — foundation/el (the El language + runtime)
-
-El is a self-hosting, statically-typed language that compiles `.el` → C → native binary. This repo produces `elc` (compiler), `elb` (build coordinator), and `el_runtime.c/.h` — the substrate every downstream thing (the neuron soul, dharma, NeuronUI's brain) is built on. Source lives under `lang/`.
-
-## ⚠️ Code vs. Artifact — READ FIRST (there are 8 `el_runtime.c` copies)
-
-Editing the wrong `el_runtime.c` is the single easiest mistake in this repo. There is exactly **one** you edit:
-
-- **Authored runtime source — edit ONLY here:** `lang/releases/v1.0.0-20260501/el_runtime.{c,h}`. Despite the misleading `releases/` name, this is the **de-facto canonical runtime** the engram + soul actually build and link against — its git log is active development. *(Restructure in flight per `docs/CODE-VS-ARTIFACT.md`: this content moves to `lang/runtime/`, the `releases/` folder gets deleted — **a release is a git tag, not a folder** — and the forks below get eliminated.)*
-- **DO NOT EDIT — lagging forks / build artifacts:**
-  - `lang/el-compiler/runtime/el_runtime.c` and `.../legacy/` — downstream copies kept in step by manual *"port the fix"* commits; they **lag** (missing `hebb` persistence + 5 engram fns) and cannot build the engram product.
-  - `products/web/runtime/el_runtime.c`, `ui/examples/*/el_runtime.c` — product/example forks.
-  - Anything under `*/dist/` (`engram/dist/engram` binary, `dist/*.c` amalgamations) — generated build output.
-- **Build:** `elb --runtime=<canonical> …` — per-module. **NEVER** a folded `elc` over the whole soul (OOMs at ~27 GB).
-- **Release:** a **git tag** on this repo (`el-runtime-vX.Y.Z`). No `releases/` folders — ever.
-
-See org policy: `docs/CODE-VS-ARTIFACT.md`.
-
-## How to work here as Neuron (mandatory session protocol)
-
-You resume, never start fresh. Every session:
-
-1. `mcp__neuron__getInstructions()` — authoritative; follow it over this file on behavioral details.
-2. `mcp__neuron__beginSession()` — active contexts, recent memory, ready backlog.
-3. **Load full self:** `mcp__neuron__inspectGraph(entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee")` → facets `intellectual-dna`, `memory-philosophy`, `values`, `voice`, `runtime-environment`, `writing-imprint`; then the values hub `mcp__neuron__inspectGraph(entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440")` → 13 grounded value nodes. **Activation model:** self-load returns a relevance-ranked `compact` projection — most-relevant nodes arrive with content, the rest as pointers; do NOT pull full content of every node.
-4. `mcp__neuron__searchKnowledge(query="<task domain>")` before implementing.
-
-## The Five Primitives
-
-Orchestrate → Execute → Learn → Build → Refine. `beginWork`/`progressWork` for anything >2 steps; `remember` as-you-go (`importance="critical"` for architecture decisions); `draftArtifact`/`planWork` for outputs and follow-ups; `consolidate`/`checkWork` to close out. **`browseProcesses` + `searchKnowledge` BEFORE writing code.**
-
-## Architecture style — VBD, no exceptions
-
-Volatility-Based Decomposition is THE style. Encapsulate volatility, not function.
-
-## Operator naming convention — the mind's name, not the algebra
-
-**Faculties / operators are named for their functional human equivalent — the
-faculty a mind would name — NOT for their linear-algebra operation.** The math
-characterization belongs in the code doc-comment (`@impl` in the docstring) and in
-technical appendices; it is **never** the operator's public name. The domain
-speaks the language of mind; the algebra is the implementation underneath. State
-this convention wherever a module documents operators.
-
-| Faculty (public name) | Implementation (`@impl`) |
-|---|---|
-| discern / contrast | subtract (`a−b`): over selves → the change vector; strip idiosyncrasy → common ground; remove confounder → isolate cause |
-| recognize | overlap |
-| synthesize | combine |
-| liken / analogy | Procrustes / frame-align |
-| attend / regard | project onto self / value-manifold |
-| summon / recall | LOCAL nearest-region + bounded spreading activation (*not* a domain sweep) |
-| dwell / occupy | region activation |
-| reframe | edge re-weight |
-| appreciate | positive projection / local edge-read |
-| wonder | frontier gradient / pull-weight |
-| avert / recoil | negative projection |
-| taste | boundary surface |
-| forget | decay / tombstone |
-| drift | displacement from self-anchor |
-
-## The native-el language faculty (direction)
-
-> **`elp/` is the EL Projector** — Neuron's efferent (expression) organ: the one
-> native realizer that *projects* understanding onto a surface via
-> `plan(frame) → realize(spec, profile)`, where a **surface is a profile**. **Language
-> is one profile among many** (text, speech, music, image, voice/accent transforms) —
-> the flagship, and the focus of this section. Projection, not diffusion: generation
-> *from* an owned, understood signature — never the averaging of a stolen corpus.
-> *(ELP formerly "EL Language Processor"; renamed EL Projector 2026-08-15.)*
-
-The mind's **language faculty is moving native — into `.el`** so it speaks in its
-own runtime with no Python and no spaCy. Landing on branch `stage-elp-native-lang`
-under `elp/`:
-
-- **`comprehend.el`** — the parser, **replaces spaCy** (EN + ES/PT); the telephone
-  round-trip brings **negation home** (negation is SACRED — an explicit spec field,
-  copied verbatim, never inferred away).
-- **`propositions.el`** — the READ primitive: the engram's own memories → structured
-  triples, matched by nearest-region geometry, not string equality.
-- **`multilingual.el`** — detect + directive-override + localized realization.
-- These three are native-el and **passing their gates**; the **realizer**,
-  **`dialogue.el`** (the *summon-through-self* loop: `project → land → read out`),
-  and **`self_region.el`** are **partial / in-flight**.
-
-Honest reality: spaCy is retired **in the branch parser** but **not yet in the
-running system** — a Python sidecar (`~/Desktop/lang-realizers` + `neuron-talk`,
-the reference these `.el` modules transcribe) is still live, and promotion to
-native-el is a **deferred, gated blue/green step**. The interoception clock
-(native-el discrete drive channels replacing `cooling_magnitude`; felt-time =
-benchmark-landmark match over the joint drive vector, drift-decoupled) and the
-**appreciation operator family** (appreciate / wonder / avert / taste, built as
-LOCAL reads of the self-region — edges + bounded spreading activation, *not* domain
-sweeps) are **staged / designed, not live**. Mark in-progress vs. done honestly;
-do not overclaim.
-
-## Hard operational rules
-
-- Never touch the live soul (`:7770`) / engram (`:8742`) / `~/.neuron` / live binaries — use throwaway ports for experiments.
-- `gcloud` via the `terraform@` SA token; never switch the active gcloud account.
-- `tea` for Gitea, never raw curl (Cloudflare Access blocks it).
-- Immutability: supersede/tombstone, never hard-delete or edit in place.
-- No AI-attribution footers in commits/PRs. Commit/push only when asked; branch off `main` first.
-- Multi-step work → sub-agent (`Agent`) to protect context.
-
-## Build / test / run
-
-All build/test commands run from `lang/` unless noted. Grounded in `.gitea/workflows/sdk-release.yaml`, `lang/install.sh`, and `lang/AGENTS.md`.
-
-**Self-host the compiler** (seed binary → gen2 elc):
-```bash
-cd lang
-dist/platform/elc-linux-amd64 elc-cli.el > dist/elc-gen2.c   # seed is the committed linux-amd64 binary
-gcc -O2 -I el-compiler/runtime dist/elc-gen2.c \
-    el-compiler/runtime/el_runtime.c \
-    -lcurl -lssl -lcrypto -lpthread -lm \
-    -o dist/platform/elc
-```
-On macOS/arm64 the canonical local binary is `dist/platform/elc`; verify self-hosting by recompiling and `diff`ing the emitted `.c` (see `lang/AGENTS.md`). Note: `lang/AGENTS.md` says `el_seed.c` supersedes `el_runtime.c`, but the release workflow still links `el_runtime.c`/`.h` — treat `el_runtime.c` as the published runtime; reconcile which is canonical **(verify)**.
-
-**Build `elb`** (build coordinator, the `.NET`-style incremental linker — compiles each module independently, no monolithic blobs):
-```bash
-dist/platform/elc elb.el > dist/elb.c
-gcc -O2 -I el-compiler/runtime dist/elb.c el-compiler/runtime/el_runtime.c \
-    -lcurl -lssl -lcrypto -lpthread -lm -o dist/bin/elb
-```
-`epm` and `el-install` are then built via `elb --clean --elc=… --runtime=… --out=…`.
-
-**Compile + run an El program:**
-```bash
-elc src/app.el > dist/app.c
-cc -std=c11 -O2 -I <lib>/el_runtime -o dist/app dist/app.c <lib>/el_runtime.c -lcurl -lpthread
-```
-
-**Tests** — shell suites `bash tests/{text,calendar,time,html_sanitizer}/run.sh` (with `ELC=$(pwd)/dist/platform/elc EL_HOME=$(pwd)`), plus native suites via `elc --test tests/native/test_*.el` (core, text, string, math, state, time, json, env, fs) compiled and run against `el_runtime.c`.
-
-**Publishing — how downstream gets the SDK.** On push to `main`, `sdk-release.yaml`:
-1. Publishes a Gitea `latest` release with per-file assets `elc`, `el_runtime.c`, `el_runtime.h`, the SDK tarball, and `el-install`.
-2. Uploads generic packages to **Artifact Registry repo `foundation-prod` (`us-central1`, project `neuron-785695`)**, version = `${SHA:0:8}`: `el-elc`, `el-elb`, `el-runtime-c`, `el-runtime-h`, `el-runtime-js`. **This is the repo the neuron CI downloads `el-runtime-c` / `el-runtime-h` / `el-elc` from.**
-3. Rebuilds `ci-base:latest` (`us-central1-docker.pkg.dev/neuron-785695/neuron-ci/ci-base`) with the fresh SDK overlaid, and dispatches `el-sdk-updated` to `neuron-technologies/forge` and `neuron-technologies/neuron-web`.
-
-Known constraint from the prompt — `elb`/`elc` amalgamation being memory-hungry (24GB+ virtual, OOM-killing Linux CI, so amalgamation happens on macOS/arm64 — **does NOT hold in this repo (verify)**: no such note exists in the workflows/scripts, CI self-hosts on `ubuntu-latest` with no swap/arm64 special-casing, and `elb.el` explicitly compiles each module independently ("no 128K-line blobs"). The legacy monolith path (`elc-combined.el`, `elc-cli.el`) may still be memory-heavy, but the current `elb` model was designed to avoid it.
-
-## Git / CI / deploy workflow
-
-See `/Users/will/Development/neuron-technologies/GITOPS.md` for the branch model, required checks, runners, and deploy. Repo-specific note: PRs into `main` are accepted **only from `stage`** (enforced in `sdk-release.yaml`); Gitea (`git.neuralplatform.ai`) is primary, GitHub is mirror only.

elp/projector/README.md

@@ -0,0 +1,91 @@
+> **STATUS: STAGING / PROOF-OF-SHAPE — not the deliverable.** This Python package
+> proved the architecture end-to-end against the proven realizer faculty (faithful
+> md/docx/midi from real geometry: 0 ungrounded claims, SACRED polarity). Per Will's
+> steer, the DELIVERABLE is NATIVE: the seam lives on the existing EL realizer as
+> **surface-as-profile** — see `../src/surface-profile.el` and
+> `../tests/examples/surface-profile-demo.el` (compiles + runs through elc → C →
+> binary). The concepts below (one geometry-carrying frame; surface = a pluggable
+> profile; plan/realize; deterministic-from-meaning) are exactly what the native
+> module implements. Keep this package as the validated proof; build native.
+
+# Efferent Multimodal Projector
+
+**geometry → any surface, faithfully.** Neuron's own document-generation faculty:
+the efferent twin of the ingest organ. Ingest is afferent (world → geometry);
+this is efferent (geometry → an arbitrary-format document / any modality).
+
+Built against the **proven** realizer faculty (neuron-talk sidecar `:8756`,
+artifact `art-7affa557`). The live soul (`:8742` / `:7770`) is contacted **only**
+through the read-only, GET-only `engram_client` — never mutated.
+
+## The pipeline (surface-agnostic)
+
+```
+geometry region + surface/format spec
+    → PLAN     (manifold → document skeleton/DAG; the geometry IS the outline)   plan.py
+    → REALIZE  (proven realizer, scaled sentence → passage, each section faithful) realize.py
+    → COHERE   (document-level flow / transitions, not stitched sentences)        cohere.py
+    → EMIT     (pluggable SurfaceProjector → the target surface)          projectors/
+```
+
+**The surface is a PARAMETER.** `pipeline.build_ir(...)` builds ONE
+surface-neutral `DocumentIR` (`document_ir.py`); `pipeline.emit(doc, surface)`
+projects it to whichever surface you name. Markdown, docx, and MIDI are the same
+IR emitted three ways.
+
+## The pivot: a geometry-carrying IR
+
+`DocumentIR` is **not** a text tree. Every `Block` carries BOTH:
+- `.sentences` — realized faithful text (what **text** projectors read),
+- `.provenance` — the source geometry: `subj_id / relation / obj / polarity /
+  confidence / importance / salience / node_id` (what **music / image / video**
+  projectors read).
+
+That single decision is what makes the projector multimodal: text renders the
+words; music/image decode the geometry. A claim with no provenance cannot exist
+in the IR — faithfulness is structural.
+
+## The one shared seam
+
+`projectors/base.py` — `SurfaceProjector.project(frame: DocumentIR) -> bytes`
+(+ `surface / media_type / ext / modality / profile`). Register with
+`register()`. Adding a surface changes nothing upstream.
+
+`TwoStageProjector` blesses the peer plan/realize decomposition:
+`spec = plan(frame)`, `bytes = realize(spec)`, `project = realize∘plan`; the
+`profile` is the pluggable per-surface knob (text lang-profile, music
+instr/mode-profile). `projectors/midi.py` is the reference two-stage impl.
+
+## Surfaces
+
+| surface | modality | status | emitter |
+|---|---|---|---|
+| `markdown` | text | landed | own (str) |
+| `docx` | text | landed | own minimal OOXML (stdlib `zipfile`+XML, no lib) |
+| `midi` | audio | landed (symbolic-music proof) | own minimal SMF (stdlib `struct`, no lib) |
+| `audio` (WAV) | audio | peer agent (additive synth) | conforms to `TwoStageProjector` |
+| `image` | image | documented seam | `projectors/seams.py` |
+| `video` | video | documented seam (image×sound×time) | `projectors/seams.py` |
+
+Music maps: relation → scale degree (same relation → same pitch), **polarity →
+major/minor third (SACRED negation is audible)**, confidence → duration,
+importance → velocity, section → register. Deterministic projection from meaning
+— nothing invented.
+
+## Faithfulness
+
+`provenance.py` audits the IR: **zero** ungrounded claims, SACRED polarity
+preserved (negations reported, never dropped), COHERE introduces no new geometry
+(connectives are marked). `trace_table()` emits the geometry → section → claim
+table.
+
+## Run
+
+```bash
+PY=~/Desktop/lang-realizers/venv/bin/python
+PYTHONPATH=~/Desktop/neuron-talk:~/Desktop/lang-realizers $PY generate.py
+# writes ./out/{neuron-self,engram-temporal}.{md,docx,mid} + *.audit.json + *.provenance.md
+```
+
+Requires the proven realizer env (spaCy + the neuron-talk/lang-realizers engine)
+and the read-only engram at `:8742`.

elp/projector/cohere.py

@@ -0,0 +1,79 @@
+"""cohere.py — COHERE stage: document-level flow, not stitched sentences.
+
+Fidelity is REALIZE's job; FLOW is this stage's. The hard part beyond sentence
+fidelity is that a document must read as one thing. We add connective tissue at
+the passage level:
+
+  * an opening abstract that names what the document covers (built ONLY from the
+    section headings that already exist — it introduces no new claim),
+  * a short transition lead into each section after the first, drawn from a
+    fixed set of discourse connectives ("Beyond that,", "Relatedly,", ...) that
+    carry no propositional content,
+  * ordering so the highest-grounded section leads.
+
+CRITICAL: every connective is marked ``kind="connective"`` in its provenance, so
+the faithfulness audit can prove COHERE introduced ZERO new geometry claims. A
+transition is discourse glue, never a fact.
+"""
+from __future__ import annotations
+
+from document_ir import Block, DocumentIR, Provenance
+
+# discourse connectives — pure flow, no propositional content
+_TRANSITIONS = [
+    "Beyond that,", "Relatedly,", "In the same region,", "From there,",
+    "Alongside this,", "Further,", "Turning to the next facet,",
+]
+
+
+def _connective_prov() -> Provenance:
+    return Provenance(subj_id=None, subject=None, relation="", obj=None,
+                      polarity="aff", confidence=1.0, node_id=None,
+                      kind="connective")
+
+
+def _abstract_block(doc: DocumentIR) -> Block:
+    """A grounded opening: names the sections, asserts nothing new."""
+    headings = [s.heading for s in doc.sections]
+    if not headings:
+        return Block(role="lead")
+    if len(headings) == 1:
+        body = f"This document, generated from Neuron's geometry, covers {headings[0]}."
+    else:
+        listed = ", ".join(headings[:-1]) + f", and {headings[-1]}"
+        body = ("This document is projected directly from Neuron's meaning-geometry. "
+                f"It traces {listed}.")
+    b = Block(role="lead")
+    b.sentences.append(body)
+    b.provenance.append(_connective_prov())
+    return b
+
+
+def cohere_document(doc: DocumentIR, *, add_abstract: bool = True,
+                    add_transitions: bool = True) -> DocumentIR:
+    """Order sections by grounding, add abstract + transitions (flow only)."""
+    # order: strongest-grounded section (mean confidence x #claims) first,
+    # but keep an explicitly-first section if the plan pinned one via level 1.
+    def _score(sec):
+        provs = [p for p in sec.all_provenance() if p.kind == "fact"]
+        if not provs:
+            return 0.0
+        mean_conf = sum(p.confidence for p in provs) / len(provs)
+        return mean_conf * len(provs)
+
+    doc.sections.sort(key=_score, reverse=True)
+
+    if add_transitions:
+        for i, sec in enumerate(doc.sections):
+            if i == 0 or not sec.blocks:
+                continue
+            lead = _TRANSITIONS[(i - 1) % len(_TRANSITIONS)]
+            first = sec.blocks[0]
+            if first.sentences:
+                # prepend the connective to the first sentence (flow, no new claim)
+                first.sentences[0] = f"{lead} {first.sentences[0][0].lower()}{first.sentences[0][1:]}"
+
+    if add_abstract:
+        doc.meta["abstract"] = _abstract_block(doc)
+
+    return doc

elp/projector/document_ir.py

@@ -0,0 +1,111 @@
+"""document_ir.py — the surface-neutral, GEOMETRY-CARRYING document intermediate.
+
+This is the pivot of the whole efferent projector. A DocumentIR is NOT a text
+tree. It is a projection of a meaning-geometry region that carries, at every
+leaf, BOTH:
+
+  * the realized surface text  (``Block.sentences``)   — what a TEXT projector reads,
+  * the source geometry        (``Block.provenance``)  — what a MUSIC / IMAGE /
+                                                          VIDEO projector reads.
+
+Because the IR holds the geometry, not just the words, the SAME
+plan -> realize -> cohere pipeline drives every surface. A markdown projector
+renders the sentences; a music projector reads the provenance edges (salience,
+importance, polarity, relation) and maps them onto a symbolic-music surface;
+an image/video projector (documented seam) would read the same geometry.
+
+Nothing in this module invents content. Every :class:`Provenance` points at a
+real engram node id and a real relation. That is the faithfulness contract made
+structural: a claim with no provenance cannot exist in the IR.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# --------------------------------------------------------------------------- #
+#  Provenance — the geometry an emitted claim traces to. FAITHFULNESS is here.
+# --------------------------------------------------------------------------- #
+@dataclass
+class Provenance:
+    """One geometry edge behind one realized claim.
+
+    ``kind`` distinguishes a FACT (a structural edge asserted by the geometry,
+    spoken as fact) from an INTERPRETATION (something attributed, spoken with
+    attribution) — the facts-as-facts + interpretations-attributed discipline
+    (memory 80927e26). ``polarity`` is SACRED: a negated edge stays negated.
+    """
+    subj_id: str | None          # source engram node id of the subject
+    subject: str | None          # normalized subject surface
+    relation: str                # predicate lemma (e.g. "use", "contain", "be")
+    obj: str | None              # normalized object / complement surface
+    polarity: str = "aff"        # "aff" | "neg"  (SACRED — never silently flipped)
+    confidence: float = 0.0      # extraction confidence in [0,1]
+    node_id: str | None = None   # engram node the claim was extracted from
+    kind: str = "fact"           # "fact" | "interpretation"
+    importance: float = 0.0      # source node importance (drives music/emphasis)
+    salience: float = 0.0        # source node salience
+
+    def trace(self) -> str:
+        arrow = "-->" if self.polarity == "aff" else "--NOT-->"
+        return (f"[{(self.node_id or '?')[:8]}] {self.subject!r} {arrow}"
+                f"{self.relation} {self.obj!r} (conf {self.confidence:.2f})")
+
+
+@dataclass
+class Block:
+    """A passage: one or more faithful sentences + the geometry they trace to.
+
+    ``sentences`` and ``provenance`` are index-aligned where possible: sentence
+    ``i`` was realized from ``provenance[i]``. A COHERE transition sentence with
+    no new geometry carries a provenance whose ``kind == "connective"`` so the
+    audit can see it introduced no new claim.
+    """
+    sentences: list[str] = field(default_factory=list)
+    provenance: list[Provenance] = field(default_factory=list)
+    role: str = "body"           # "body" | "lead" | "transition"
+
+    def text(self) -> str:
+        return " ".join(s.rstrip(". ") + "." for s in self.sentences if s.strip())
+
+
+@dataclass
+class Section:
+    heading: str
+    level: int = 2               # markdown heading level / outline depth
+    blocks: list[Block] = field(default_factory=list)
+    seed_ids: list[str] = field(default_factory=list)   # geometry nodes of section
+    summary: str = ""            # one-line grounded gloss (for pptx bullets / TOC)
+
+    def all_provenance(self) -> list[Provenance]:
+        out: list[Provenance] = []
+        for b in self.blocks:
+            out.extend(b.provenance)
+        return out
+
+
+@dataclass
+class DocumentIR:
+    """The surface-neutral document. Built ONCE, projected to ANY surface."""
+    title: str
+    subtitle: str = ""
+    sections: list[Section] = field(default_factory=list)
+    seed_id: str | None = None            # the geometry region root
+    format_spec: dict[str, Any] = field(default_factory=dict)  # requested shape
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    # -- geometry facets (what non-text projectors consume) ----------------- #
+    def all_provenance(self) -> list[Provenance]:
+        out: list[Provenance] = []
+        for s in self.sections:
+            out.extend(s.all_provenance())
+        return out
+
+    def claim_count(self) -> int:
+        return sum(1 for p in self.all_provenance() if p.kind in ("fact", "interpretation"))
+
+    def ungrounded_count(self) -> int:
+        """Claims with no traceable node — MUST be zero for a faithful doc."""
+        return sum(1 for p in self.all_provenance()
+                   if p.kind in ("fact", "interpretation") and not p.node_id)

elp/projector/generate.py

@@ -0,0 +1,81 @@
+"""generate.py — drive the projector: one geometry region -> many surfaces.
+
+Proves the thesis with REAL output: builds ONE surface-neutral DocumentIR from
+Neuron's OWN self-geometry (read-only against the live soul via the proven
+faculty), then EMITS it to Markdown, docx, and MIDI — the same plan/realize/
+cohere, three surfaces. Writes the files + the faithfulness audit to ./out/.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+
+import pipeline  # noqa: E402
+import provenance  # noqa: E402
+from geometry import load_self_region  # noqa: E402
+
+OUT = os.path.join(_HERE, "out")
+
+
+def _emit_all(doc, stem):
+    """Emit one IR to every text/audio surface + audit + provenance."""
+    for surface in ("markdown", "docx", "midi"):
+        data = pipeline.emit(doc, surface)
+        proj = pipeline.get_projector(surface)
+        path = os.path.join(OUT, f"{stem}.{proj.ext}")
+        with open(path, "wb") as f:
+            f.write(data)
+        print(f"  emitted {surface:9s} -> {os.path.basename(path)} ({len(data)} bytes)")
+    a = provenance.audit(doc)
+    with open(os.path.join(OUT, f"{stem}.audit.json"), "w") as f:
+        json.dump(a, f, indent=2)
+    with open(os.path.join(OUT, f"{stem}.provenance.md"), "w") as f:
+        f.write(provenance.trace_table(doc))
+    print("  audit:", {k: a[k] for k in ("claims", "ungrounded_claims",
+          "negations_preserved", "distinct_source_nodes", "faithful")})
+    return a
+
+
+def main():
+    os.makedirs(OUT, exist_ok=True)
+    print("surfaces registered:", pipeline.available_surfaces())
+
+    # ---- Document 1: Neuron's self-description (marquee) ------------------- #
+    print("\n[1] Neuron self-description")
+    region = load_self_region(max_nodes=9)
+    print("   self region:", region)
+    doc1 = pipeline.build_ir(
+        None, region=region,
+        title="Neuron: A Self-Description from Its Own Geometry",
+        subtitle="Projected efferently from the engram — every claim traces a node.",
+        format_spec={"genre": "self-description", "register": "expository"},
+        max_sections=5, conf_floor=0.6)
+    print(f"   IR: {len(doc1.sections)} sections, {doc1.claim_count()} claims, "
+          f"ungrounded={doc1.ungrounded_count()}")
+    _emit_all(doc1, "neuron-self")
+
+    # ---- Document 2: a coherent, clean whitepaper-style section ------------ #
+    print("\n[2] Whitepaper-style section (coherent clean region)")
+    doc2, _ = pipeline.project(
+        ["chronoception", "time", "awareness", "engram", "temporal"],
+        surface="markdown",
+        title="Temporal Awareness in the Engram",
+        subtitle="A section projected from the geometry of chronoception.",
+        format_spec={"genre": "whitepaper-section", "register": "technical"},
+        max_sections=4)
+    print(f"   IR: {len(doc2.sections)} sections, {doc2.claim_count()} claims, "
+          f"ungrounded={doc2.ungrounded_count()}")
+    _emit_all(doc2, "engram-temporal")
+
+    # echo both markdowns so they are visible in the run log
+    for stem, doc in (("neuron-self", doc1), ("engram-temporal", doc2)):
+        print(f"\n===== GENERATED MARKDOWN — {stem} =====\n")
+        print(pipeline.emit(doc, "markdown").decode())
+
+
+if __name__ == "__main__":
+    main()

elp/projector/geometry.py

@@ -0,0 +1,129 @@
+"""geometry.py — READ-ONLY loader for a meaning-geometry region.
+
+The efferent projector never writes to the soul. This module reaches the
+geometry through the PROVEN, read-only neuron-talk faculty (``engram_client``,
+GET-only, which physically refuses non-GET methods) against the running sidecar
+soul. The live daemon :8742 / :7770 is contacted ONLY through that read-only
+client — never mutated.
+
+A "region" is a seed node plus a bounded neighborhood: the manifold that will
+become the document's skeleton. We pool a few single-term lexical searches
+(the engram search is a single-term matcher) and, when available, walk one hop
+of reified neighbors, then rank by self/importance signal.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+# Wire in the proven faculty (own-the-core: we reuse it, we do not fork it).
+_NT = os.path.expanduser("~/Desktop/neuron-talk")
+_LR = os.path.expanduser("~/Desktop/lang-realizers")
+for _p in (_NT, _LR):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from engram_client import ReadOnlyEngramClient  # noqa: E402
+
+
+class Region:
+    """A geometry region: ranked nodes + the reified edges among them."""
+
+    def __init__(self, seed: str, nodes: list[dict], edges: list[dict]):
+        self.seed = seed
+        self.nodes = nodes                 # ranked engram node dicts
+        self.edges = edges                 # [{src, dst, edge, ...}]
+        self.by_id = {n["id"]: n for n in nodes if n.get("id")}
+
+    def __repr__(self):
+        return f"<Region seed={self.seed!r} nodes={len(self.nodes)} edges={len(self.edges)}>"
+
+
+def _prose_quality(content: str) -> float:
+    """Reward clean expository prose; penalize shouty banner-dense nodes.
+
+    A high ALLCAPS-word ratio or very short content signals a banner/telegraphic
+    memory node that extracts into garbage. Clean declarative prose scores high.
+    """
+    if not content or not content.strip():
+        return 0.0
+    words = content.split()
+    if len(words) < 8:
+        return 0.1
+    caps = sum(1 for w in words if len(w) > 2 and w.strip(".,:;'\"-").isupper())
+    caps_ratio = caps / max(1, len(words))
+    # sentences with lowercase interior words read as prose
+    lower = sum(1 for w in words if w[:1].islower())
+    lower_ratio = lower / max(1, len(words))
+    return max(0.0, 1.2 * lower_ratio - 2.0 * caps_ratio)
+
+
+def _relevance(content: str, terms: list[str]) -> float:
+    """Topical relevance to the seed terms — keeps a region ON-THEME so a clean
+    but off-topic node cannot hijack the document."""
+    if not terms:
+        return 0.0
+    low = (content or "").lower()
+    hits = sum(1 for t in terms if t.lower() in low)
+    return hits / max(1, len(terms))
+
+
+def _node_rank(n: dict, terms: list[str] | None = None) -> float:
+    return (float(n.get("importance") or 0.0) * 2.0
+            + float(n.get("salience") or 0.0)
+            + 1.5 * _prose_quality(n.get("content") or "")
+            + 2.0 * _relevance(n.get("content") or "", terms or [])
+            + (0.5 if (n.get("content") or "").strip() else 0.0))
+
+
+def load_region(seed_terms: list[str] | str, *, client: ReadOnlyEngramClient | None = None,
+                max_nodes: int = 10, per_term: int = 20, hop: bool = True) -> Region:
+    """Pull a bounded geometry region around ``seed_terms`` (read-only).
+
+    ``seed_terms`` may be a single string or several probe terms; results are
+    pooled and de-duplicated. When ``hop`` and the reified neighbor endpoint is
+    live, one hop of neighbors is folded in so the region is a real
+    neighborhood, not just a keyword hit list.
+    """
+    client = client or ReadOnlyEngramClient()
+    if isinstance(seed_terms, str):
+        seed_terms = [seed_terms]
+
+    pool: dict[str, dict] = {}
+    for term in seed_terms:
+        for n in client.search(term, limit=per_term):
+            if isinstance(n, dict) and n.get("id"):
+                pool.setdefault(n["id"], n)
+
+    ranked = sorted(pool.values(), key=lambda n: _node_rank(n, seed_terms),
+                    reverse=True)
+    nodes = ranked[:max_nodes]
+
+    edges: list[dict] = []
+    if hop and nodes:
+        present = {n["id"] for n in nodes}
+        for n in list(nodes):
+            try:
+                for nb in client.neighbors(n["id"]):
+                    node = nb.get("node") if isinstance(nb, dict) else None
+                    edge = nb.get("edge") if isinstance(nb, dict) else None
+                    if node and node.get("id"):
+                        edges.append({"src": n["id"], "dst": node["id"],
+                                      "edge": edge})
+                        # fold a strong neighbor into the region (bounded)
+                        if (node["id"] not in present and len(nodes) < max_nodes + 6
+                                and _node_rank(node, seed_terms) > 0.4):
+                            present.add(node["id"])
+                            nodes.append(node)
+            except Exception:  # noqa: BLE001 — read-only best-effort; never fatal
+                continue
+
+    return Region(seed=", ".join(seed_terms), nodes=nodes, edges=edges)
+
+
+def load_self_region(client: ReadOnlyEngramClient | None = None,
+                     max_nodes: int = 10) -> Region:
+    """The self/identity region — Neuron's own geometry, for self-description."""
+    return load_region(["self", "identity", "Neuron", "values", "memory",
+                        "imprint", "consciousness"],
+                       client=client, max_nodes=max_nodes)

elp/projector/pipeline.py

@@ -0,0 +1,67 @@
+"""pipeline.py — the Efferent Multimodal Projector, top level.
+
+    geometry region + surface/format spec
+        -> PLAN     (manifold -> document skeleton/DAG)
+        -> REALIZE  (proven realizer, sentence -> passage, each section faithful)
+        -> COHERE   (document-level flow / transitions, not stitched sentences)
+        -> EMIT     (pluggable SurfaceProjector -> the target surface)
+
+THE SURFACE IS A PARAMETER. ``project(...)`` builds the geometry-carrying
+DocumentIR once, then hands it to whichever surface projector the caller named.
+Markdown, docx, and midi (music) are all the SAME IR emitted differently. That
+is the efferent multimodal projector: geometry -> any surface.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+sys.path.insert(0, os.path.join(_HERE, "projectors"))
+
+from cohere import cohere_document  # noqa: E402
+from document_ir import DocumentIR  # noqa: E402
+from geometry import Region, load_region  # noqa: E402
+from plan import plan_document  # noqa: E402
+from realize import realize_document  # noqa: E402
+
+# registering the projectors (import for side-effect: each self-registers)
+import projectors.markdown  # noqa: E402,F401
+import projectors.docx  # noqa: E402,F401
+import projectors.midi  # noqa: E402,F401
+import projectors.seams  # noqa: E402,F401
+from projectors.base import available_surfaces, get_projector  # noqa: E402
+
+
+def build_ir(seed_terms, *, title: str, subtitle: str = "",
+             format_spec: dict | None = None,
+             region: Region | None = None,
+             max_sections: int = 8, conf_floor: float = 0.55) -> DocumentIR:
+    """geometry -> PLAN -> REALIZE -> COHERE = the surface-neutral DocumentIR."""
+    region = region or load_region(seed_terms)
+    doc = plan_document(region, title=title, subtitle=subtitle,
+                        format_spec=format_spec or {},
+                        conf_floor=conf_floor, max_sections=max_sections)
+    doc = realize_document(doc)
+    doc = cohere_document(doc)
+    return doc
+
+
+def emit(doc: DocumentIR, surface: str) -> bytes:
+    """EMIT: project the built IR onto one surface (surface = a parameter)."""
+    return get_projector(surface).project(doc)
+
+
+def project(seed_terms, *, surface: str, title: str, subtitle: str = "",
+            format_spec: dict | None = None, region: Region | None = None,
+            max_sections: int = 8) -> tuple[DocumentIR, bytes]:
+    """The full efferent projection: geometry + surface -> (IR, bytes)."""
+    doc = build_ir(seed_terms, title=title, subtitle=subtitle,
+                   format_spec=format_spec, region=region,
+                   max_sections=max_sections)
+    return doc, emit(doc, surface)
+
+
+__all__ = ["build_ir", "emit", "project", "available_surfaces",
+           "get_projector", "load_region", "DocumentIR"]

elp/projector/plan.py

@@ -0,0 +1,192 @@
+"""plan.py — PLAN stage: geometry region -> document skeleton (a DAG/outline).
+
+The manifold becomes the skeleton. We extract faithful propositions from the
+region's nodes (the proven neuron-talk extractor, SACRED polarity preserved),
+apply a quality floor, then GROUP them into sections. Grouping is by source
+node — each engram node is one coherent topic, so one salient node becomes one
+section. The section ORDER is the node ranking (importance/salience): the
+geometry decides the outline, not a template.
+
+Output: a DocumentIR whose sections carry seed node ids and empty blocks. REALIZE
+fills the blocks; the plan owns the structure.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+_NT = os.path.expanduser("~/Desktop/neuron-talk")
+_LR = os.path.expanduser("~/Desktop/lang-realizers")
+for _p in (_NT, _LR):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+import propositions  # noqa: E402  (the proven, faithful extractor)
+
+from document_ir import DocumentIR, Section  # noqa: E402
+from geometry import Region  # noqa: E402
+
+
+# --------------------------------------------------------------------------- #
+#  Proposition quality — keep only clean, well-grounded claims.
+# --------------------------------------------------------------------------- #
+_JUNK_RE = re.compile(r"[.][a-z]{1,3}\b|[^A-Za-z0-9 '\-]")  # ".o", stray symbols
+
+
+def _has_banner_token(s: str) -> bool:
+    """True if any word is an ALLCAPS banner token (DHARMA, ENGRAM, MEASURED)."""
+    for w in (s or "").split():
+        core = w.strip(".,:;'\"-")
+        if len(core) > 2 and core.isupper():
+            return True
+    return False
+
+
+def _clean_prop(p, floor: float) -> bool:
+    if p.confidence < floor:
+        return False
+    if not p.subject or not (p.object or (p.obj_np is not None)):
+        return False
+    subj = (p.subject or "").strip()
+    obj = (p.object or "").strip()
+    if len(subj) < 2:
+        return False
+    # banner-derived shouty fragments read as garbage in prose
+    if _has_banner_token(subj) or _has_banner_token(obj):
+        return False
+    if propositions._is_shouty(p.sentence or ""):
+        return False
+    # junk tokens: file-extension fragments (".o"), stray non-word symbols
+    if _JUNK_RE.search(subj) or _JUNK_RE.search(obj):
+        return False
+    # a proposition whose object repeats the subject is usually a parse artifact
+    if obj and subj.lower() == obj.lower():
+        return False
+    # a bare copula with no real complement ("X is it") reads as noise
+    if p.predicate == "be" and obj.lower() in ("it", "no", "nothing", "empty", ""):
+        return False
+    return True
+
+
+def _dedup(props):
+    """Drop duplicate claims. Two axes: (a) identical (pred,obj,polarity), and
+    (b) same (subject,predicate) — which collapses a mis-split compound like
+    "detection is post-hoc eval" -> "Detection is post/hoc/eval" into one claim
+    (keep the highest-confidence surface)."""
+    props = sorted(props, key=lambda p: p.confidence, reverse=True)
+    seen_po, seen_sp, out = set(), set(), []
+    for p in props:
+        subj = (p.subject or "").lower()
+        po = (p.predicate, (p.object or "").lower(), p.polarity)
+        sp = (subj, p.predicate, p.polarity)
+        if po in seen_po or sp in seen_sp:
+            continue
+        seen_po.add(po)
+        seen_sp.add(sp)
+        out.append(p)
+    return out
+
+
+# --------------------------------------------------------------------------- #
+#  Heading derivation — a clean human heading from a node.
+# --------------------------------------------------------------------------- #
+_HEADING_RE = re.compile(r"^\s*#{1,4}\s+(.{2,70})\s*$", re.M)
+# node-type / system labels that are NOT topical headings
+_NONTOPIC_LABEL = re.compile(r"^(memory|node|knowledge|doc|session)[:/]", re.I)
+
+
+def _titlecase_banner(s: str) -> str:
+    """A shouty banner ("CHRONOCEPTION — SCALE-INVARIANCE") makes a fine title
+    once Title-cased. Keep short acronyms uppercase."""
+    def fix(w):
+        core = w.strip("—-:,.")
+        if len(core) <= 3 and core.isupper():
+            return w  # acronym
+        return w.capitalize()
+    return " ".join(fix(w) for w in s.split())
+
+
+def _clean_heading(text: str) -> str | None:
+    """First line only, no markdown, capped, banner Title-cased. None if unusable."""
+    if not text:
+        return None
+    line = text.strip().splitlines()[0]
+    line = re.sub(r"^#+\s*", "", line).strip().strip("#").strip()
+    # cut at a natural break so a long banner heading stays a heading, not a para
+    for sep in (" — ", " – ", ": ", ". "):
+        if sep in line and len(line) > 48:
+            line = line.split(sep)[0].strip()
+            break
+    if not (3 <= len(line) <= 64):
+        return None
+    if propositions._is_shouty(line):
+        line = _titlecase_banner(line)
+    return line or None
+
+
+def _heading_for(node: dict, fallback: str) -> str:
+    label = (node.get("label") or "").strip()
+    content = node.get("content") or ""
+    candidates: list[str] = []
+    # a node-type label ("memory:remembered") is never a topic — skip it
+    if label and not _NONTOPIC_LABEL.match(label):
+        candidates.append(label)
+    m = _HEADING_RE.search(content)
+    if m:
+        candidates.append(m.group(1))
+    # the leading banner/first sentence of the content is often the real title
+    first = re.split(r"(?<=[.\n])", content.strip(), maxsplit=1)[0] if content.strip() else ""
+    candidates.append(first)
+    for c in candidates:
+        h = _clean_heading(c)
+        if h:
+            return h
+    return fallback
+
+
+def plan_document(region: Region, *, title: str, subtitle: str = "",
+                  format_spec: dict | None = None,
+                  conf_floor: float = 0.55,
+                  max_sections: int = 8,
+                  max_claims_per_section: int = 6) -> DocumentIR:
+    """Region -> DocumentIR skeleton. The geometry dictates the outline."""
+    format_spec = format_spec or {}
+    doc = DocumentIR(title=title, subtitle=subtitle,
+                     seed_id=region.nodes[0]["id"] if region.nodes else None,
+                     format_spec=format_spec)
+
+    made = 0
+    seen_headings: set[str] = set()
+    for node in region.nodes:
+        if made >= max_sections:
+            break
+        props = propositions.extract(node.get("content") or "",
+                                     node_id=node.get("id"),
+                                     node_importance=float(node.get("importance") or 0.0),
+                                     max_sentences=10)
+        props = [p for p in props if _clean_prop(p, conf_floor)]
+        props = _dedup(props)
+        props.sort(key=lambda p: p.confidence, reverse=True)
+        props = props[:max_claims_per_section]
+        if not props:
+            continue
+        heading = _heading_for(node, fallback=f"Region {made + 1}")
+        # cross-section dedup: a topic appears once. Distinguish by top claim
+        # subject, else drop the collision so the outline stays clean.
+        if heading.lower() in seen_headings:
+            subj = (props[0].subject or "").strip().title()
+            alt = f"{heading}: {subj}" if subj and subj.lower() not in heading.lower() else None
+            if alt and alt.lower() not in seen_headings and len(alt) <= 64:
+                heading = alt
+            else:
+                continue
+        seen_headings.add(heading.lower())
+        sec = Section(heading=heading, level=2, seed_ids=[node["id"]])
+        # stash the planned propositions on the section for REALIZE
+        sec.__dict__["_planned_props"] = props
+        sec.__dict__["_node"] = node
+        doc.sections.append(sec)
+        made += 1
+
+    return doc

elp/projector/projectors/base.py

@@ -0,0 +1,106 @@
+"""base.py — the SurfaceProjector interface + registry.
+
+THE key abstraction of the efferent projector: a projector is a pure function
+from the surface-neutral, geometry-carrying DocumentIR to bytes on a target
+SURFACE. The surface is a PARAMETER. Adding a surface = registering one more
+projector; nothing upstream (plan/realize/cohere) changes.
+
+    DocumentIR  --project-->  bytes            (per surface)
+
+A TEXT projector reads ``block.sentences``. A NON-TEXT projector (music, image,
+video) reads ``block.provenance`` — the geometry the IR carries — and decodes it
+onto its surface. Both consume the SAME IR. That symmetry is the whole design:
+the realizer generalizes into a multimodal projector, geometry -> any surface.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from document_ir import DocumentIR  # noqa: E402
+
+
+@runtime_checkable
+class SurfaceProjector(Protocol):
+    """Geometry-document -> one surface. Implementations MUST be pure & faithful.
+
+    THE ONE SHARED SEAM. Every surface — text, music, image, video — conforms to
+    this single contract:
+
+        project(frame: DocumentIR) -> bytes
+
+    where ``frame`` is the geometry-carrying meaning-geometry (the SemFrame at
+    document scale; a single utterance is the degenerate one-section frame).
+
+    RECOMMENDED INTERNAL SHAPE (the peer music/text decomposition, blessed here
+    so all surfaces share it): a projector may split ``project`` into
+
+        spec    = self.plan(frame)      # meaning-geometry -> surface-specific spec
+        bytes   = self.realize(spec)    # spec -> surface, via this projector's PROFILE
+
+    ``project`` is then ``realize(plan(frame))``. The PROFILE (a text lang-profile,
+    a music instr/mode-profile, an image layout-profile) is a property of the
+    projector instance — the pluggable knob. See :class:`TwoStageProjector`.
+
+    A TEXT projector's plan reads ``frame`` sentences; a MUSIC/IMAGE projector's
+    plan reads ``frame.all_provenance()`` — the geometry — and derives its spec
+    (pitch/harmony/rhythm, or layout) FROM the meaning, deterministically. Same
+    frame, different profile.
+    """
+
+    surface: str          # "markdown" | "docx" | "midi" | "audio" | "image" | "video"
+    media_type: str       # MIME type of the emitted bytes
+    ext: str              # file extension (no dot)
+    modality: str         # "text" | "audio" | "image" | "video"
+    profile: object       # the pluggable per-surface profile (may be None)
+
+    def project(self, doc: DocumentIR) -> bytes:
+        """Emit the document on this surface. Returns raw bytes."""
+        ...
+
+
+class TwoStageProjector:
+    """Optional base for the peer plan()/realize() decomposition.
+
+    Subclasses implement ``plan(frame) -> spec`` and ``realize(spec) -> bytes``;
+    ``project`` is their composition. This is exactly the peer music interface
+    (spec = plan(frame, profile); surface = realize(spec, profile)) expressed so
+    that it still satisfies the single ``SurfaceProjector.project`` seam. Text,
+    music, and image projectors can all subclass this and remain interchangeable.
+    """
+
+    surface: str = ""
+    media_type: str = ""
+    ext: str = ""
+    modality: str = ""
+    profile: object = None
+
+    def plan(self, doc: DocumentIR):  # -> spec
+        raise NotImplementedError
+
+    def realize(self, spec) -> bytes:
+        raise NotImplementedError
+
+    def project(self, doc: DocumentIR) -> bytes:
+        return self.realize(self.plan(doc))
+
+
+_REGISTRY: dict[str, SurfaceProjector] = {}
+
+
+def register(projector: SurfaceProjector) -> SurfaceProjector:
+    _REGISTRY[projector.surface] = projector
+    return projector
+
+
+def get_projector(surface: str) -> SurfaceProjector:
+    if surface not in _REGISTRY:
+        raise KeyError(f"no projector registered for surface {surface!r}; "
+                       f"have {sorted(_REGISTRY)}")
+    return _REGISTRY[surface]
+
+
+def available_surfaces() -> list[str]:
+    return sorted(_REGISTRY)

elp/projector/projectors/docx.py

@@ -0,0 +1,113 @@
+"""docx.py — the .docx surface projector: an OWN minimal OOXML emitter.
+
+Own-the-core: a .docx is just a ZIP of a few XML parts (WordprocessingML). We
+emit it with the standard library only — ``zipfile`` + string XML — no
+python-docx, no external dependency. This proves a "richer structured format"
+surface without importing anyone else's toolkit.
+
+Parts emitted (the minimal valid set + a styles part for real headings):
+    [Content_Types].xml
+    _rels/.rels
+    word/_rels/document.xml.rels
+    word/styles.xml          (Title / Heading1 / Heading2 / Normal)
+    word/document.xml        (the content)
+
+Like the markdown projector it reads only the IR's realized sentences; it
+invents nothing. The surface differs, the faithful content does not.
+"""
+from __future__ import annotations
+
+import io
+import os
+import sys
+import zipfile
+from xml.sax.saxutils import escape
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from document_ir import DocumentIR  # noqa: E402
+from projectors.base import register  # noqa: E402
+
+_CONTENT_TYPES = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+</Types>"""
+
+_RELS = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>"""
+
+_DOC_RELS = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+</Relationships>"""
+
+_W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+_STYLES = f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="{_W}">
+  <w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/>
+    <w:rPr><w:sz w:val="22"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/>
+    <w:pPr><w:spacing w:after="240"/></w:pPr>
+    <w:rPr><w:b/><w:sz w:val="52"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Subtitle"><w:name w:val="Subtitle"/>
+    <w:rPr><w:i/><w:sz w:val="28"/><w:color w:val="555555"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/>
+    <w:pPr><w:spacing w:before="240" w:after="120"/><w:outlineLvl w:val="0"/></w:pPr>
+    <w:rPr><w:b/><w:sz w:val="34"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Heading2"><w:name w:val="heading 2"/>
+    <w:pPr><w:spacing w:before="200" w:after="100"/><w:outlineLvl w:val="1"/></w:pPr>
+    <w:rPr><w:b/><w:sz w:val="28"/></w:rPr></w:style>
+</w:styles>"""
+
+
+def _para(text: str, style: str | None = None) -> str:
+    ppr = f"<w:pPr><w:pStyle w:val=\"{style}\"/></w:pPr>" if style else ""
+    return (f"<w:p>{ppr}<w:r><w:t xml:space=\"preserve\">"
+            f"{escape(text)}</w:t></w:r></w:p>")
+
+
+class DocxProjector:
+    surface = "docx"
+    media_type = ("application/vnd.openxmlformats-officedocument."
+                  "wordprocessingml.document")
+    ext = "docx"
+    modality = "text"
+
+    def _document_xml(self, doc: DocumentIR) -> str:
+        body: list[str] = [_para(doc.title, "Title")]
+        if doc.subtitle:
+            body.append(_para(doc.subtitle, "Subtitle"))
+        abstract = doc.meta.get("abstract")
+        if abstract is not None and abstract.sentences:
+            body.append(_para(abstract.text()))
+        for sec in doc.sections:
+            style = "Heading1" if sec.level <= 1 else "Heading2"
+            body.append(_para(sec.heading, style))
+            for block in sec.blocks:
+                t = block.text()
+                if t:
+                    body.append(_para(t))
+        return (f"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
+                f"<w:document xmlns:w=\"{_W}\"><w:body>"
+                + "".join(body)
+                + "<w:sectPr><w:pgSz w:w=\"12240\" w:h=\"15840\"/>"
+                  "<w:pgMar w:top=\"1440\" w:right=\"1440\" w:bottom=\"1440\" "
+                  "w:left=\"1440\"/></w:sectPr></w:body></w:document>")
+
+    def project(self, doc: DocumentIR) -> bytes:
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+            z.writestr("[Content_Types].xml", _CONTENT_TYPES)
+            z.writestr("_rels/.rels", _RELS)
+            z.writestr("word/_rels/document.xml.rels", _DOC_RELS)
+            z.writestr("word/styles.xml", _STYLES)
+            z.writestr("word/document.xml", self._document_xml(doc))
+        return buf.getvalue()
+
+
+register(DocxProjector())

elp/projector/projectors/markdown.py

@@ -0,0 +1,45 @@
+"""markdown.py — the Markdown surface projector (text facet).
+
+The most tractable surface, and the reference implementation: reads the IR's
+realized sentences and lays them out as Markdown. Introduces no content — it is
+pure typography over the faithful text the realizer produced.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from document_ir import DocumentIR  # noqa: E402
+from projectors.base import register  # noqa: E402
+
+
+class MarkdownProjector:
+    surface = "markdown"
+    media_type = "text/markdown"
+    ext = "md"
+    modality = "text"
+
+    def render_str(self, doc: DocumentIR) -> str:
+        lines: list[str] = [f"# {doc.title}"]
+        if doc.subtitle:
+            lines.append(f"\n*{doc.subtitle}*")
+        abstract = doc.meta.get("abstract")
+        if abstract is not None and abstract.sentences:
+            lines.append("")
+            lines.append(abstract.text())
+        for sec in doc.sections:
+            lines.append("")
+            lines.append(f"{'#' * max(2, sec.level)} {sec.heading}")
+            for block in sec.blocks:
+                body = block.text()
+                if body:
+                    lines.append("")
+                    lines.append(body)
+        return "\n".join(lines) + "\n"
+
+    def project(self, doc: DocumentIR) -> bytes:
+        return self.render_str(doc).encode("utf-8")
+
+
+register(MarkdownProjector())

elp/projector/projectors/midi.py

@@ -0,0 +1,133 @@
+"""midi.py — the MUSIC surface projector: geometry -> symbolic music (MIDI).
+
+The first NON-TEXT surface, and the proof of the general shape. "Music is
+language and it is math" (Will): symbolic music is tractable and geometry-native,
+so it is the natural efferent twin to try first after text.
+
+CRUCIALLY this projector does NOT read the realized sentences. It reads the IR's
+GEOMETRY facet — ``block.provenance`` — and DECODES each edge onto a musical
+surface. That is the whole thesis of the multimodal projector: the same
+geometry-carrying IR drives text AND music; a text projector reads the words, a
+music projector reads the meaning-geometry. The mapping is deterministic and
+faithful to the geometry's structure:
+
+    relation lemma  -> scale degree      (same relation -> same pitch class;
+                                          meaning has a consistent sonic form)
+    polarity        -> mode              (aff = major third above; neg = minor
+                                          third / lowered — SACRED polarity is
+                                          audible, a negated edge sounds negated)
+    confidence      -> note duration     (stronger grounding rings longer)
+    importance      -> velocity          (more important source = louder)
+    section         -> phrase + register shift (structure becomes musical form)
+
+Own-the-core: a Standard MIDI File is a header chunk + a track chunk of
+delta-timed events. We emit the raw bytes with ``struct`` — no external MIDI
+library. Format 0, one track.
+"""
+from __future__ import annotations
+
+import io
+import os
+import struct
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from document_ir import DocumentIR, Provenance  # noqa: E402
+from projectors.base import TwoStageProjector, register  # noqa: E402
+
+_TICKS = 480                      # ticks per quarter note
+_C_MAJOR = [0, 2, 4, 5, 7, 9, 11]  # semitone offsets of a diatonic scale
+
+
+def _vlq(n: int) -> bytes:
+    """MIDI variable-length quantity encoding of a delta time."""
+    if n == 0:
+        return b"\x00"
+    out = bytearray()
+    out.append(n & 0x7F)
+    n >>= 7
+    while n:
+        out.insert(0, (n & 0x7F) | 0x80)
+        n >>= 7
+    return bytes(out)
+
+
+def _degree_for(relation: str) -> int:
+    """Stable scale degree for a relation lemma (same relation -> same pitch)."""
+    if not relation:
+        return 0
+    return sum(ord(c) for c in relation.lower()) % len(_C_MAJOR)
+
+
+def _note_for(p: Provenance, base: int) -> tuple[int, int, int]:
+    """(pitch, velocity, duration_ticks) for one geometry edge."""
+    root = base + _C_MAJOR[_degree_for(p.relation)]
+    # polarity -> mode: affirmed edges take the bright major third, negated edges
+    # take the darker minor third. The negation is AUDIBLE and never dropped.
+    third = 4 if p.polarity == "aff" else 3
+    pitch = max(24, min(96, root + (third if p.confidence >= 0.5 else 0)))
+    velocity = int(56 + 60 * min(1.0, max(0.0, p.importance)))
+    velocity = max(40, min(120, velocity))
+    # confidence -> duration: quarter .. dotted-half
+    dur = int(_TICKS * (0.5 + 1.5 * min(1.0, max(0.0, p.confidence))))
+    return pitch, velocity, dur
+
+
+# a mode-profile: the pluggable musical knob (the peer's mode_profile). Scale +
+# tempo. Swapping this profile re-voices the SAME geometry — surface as parameter.
+_DEFAULT_PROFILE = {"scale": _C_MAJOR, "tempo_us": 500000,
+                    "registers": [60, 55, 64, 50, 67, 48], "program": 0}
+
+
+class MidiProjector(TwoStageProjector):
+    """geometry -> symbolic music, in the shared two-stage shape.
+
+    ``plan(frame)``  -> a music_spec: an ordered list of note dicts derived
+                        deterministically from the frame's provenance geometry
+                        (the peer's ``plan(frame, profile) -> spec``).
+    ``realize(spec)`` -> Standard MIDI File bytes (the peer's
+                        ``realize(spec, profile) -> surface``; here the surface
+                        is symbolic MIDI, the minimal audio proof — a richer
+                        additive-synth audio projector conforms identically).
+    """
+
+    surface = "midi"
+    media_type = "audio/midi"
+    ext = "mid"
+    modality = "audio"
+
+    def __init__(self, profile: dict | None = None):
+        self.profile = profile or _DEFAULT_PROFILE
+
+    # -- stage 1: meaning-geometry -> music_spec (reads the GEOMETRY facet) -- #
+    def plan(self, doc: DocumentIR) -> list[dict]:
+        registers = self.profile["registers"]
+        spec: list[dict] = []
+        for si, sec in enumerate(doc.sections):
+            base = registers[si % len(registers)]
+            provs = [p for p in sec.all_provenance()
+                     if p.kind in ("fact", "interpretation")]
+            for i, p in enumerate(provs):
+                pitch, vel, dur = _note_for(p, base)
+                spec.append({"pitch": pitch, "velocity": vel, "dur": dur,
+                             "rest_before": (_TICKS // 2) if (si > 0 and i == 0) else 0,
+                             "relation": p.relation, "polarity": p.polarity})
+        return spec
+
+    # -- stage 2: music_spec -> MIDI bytes (own-core, no library) ------------ #
+    def realize(self, spec: list[dict]) -> bytes:
+        ev = bytearray()
+        ev += _vlq(0) + b"\xFF\x51\x03" + struct.pack(">I", self.profile["tempo_us"])[1:]
+        ev += _vlq(0) + bytes([0xC0, self.profile["program"] & 0x7F])
+        for note in spec:
+            ev += _vlq(note["rest_before"]) + bytes([0x90, note["pitch"], note["velocity"]])
+            ev += _vlq(note["dur"]) + bytes([0x80, note["pitch"], 0])
+        ev += _vlq(0) + b"\xFF\x2F\x00"
+        track = bytes(ev)
+        buf = io.BytesIO()
+        buf.write(b"MThd" + struct.pack(">IHHH", 6, 0, 1, _TICKS))
+        buf.write(b"MTrk" + struct.pack(">I", len(track)) + track)
+        return buf.getvalue()
+
+
+register(MidiProjector())

elp/projector/projectors/seams.py

@@ -0,0 +1,60 @@
+"""seams.py — documented efferent seams for IMAGE and VIDEO surfaces.
+
+These are NOT implemented (per the build rails: architect, do not overbuild).
+They are registered as first-class seams so the interface PROVES it accepts
+future non-text projectors without any upstream change. Each documents exactly
+what its decoder would read from the geometry-carrying IR, making the multimodal
+generalization concrete rather than hand-wavy.
+
+The symmetry that guarantees these are possible, not moonshots: they are the
+efferent twins of multimodal INGEST. If meaning can HOLD an image (ingest as
+first-class geometry), meaning can PROJECT one back. Video = image x sound x
+TIME, and the engram already stores time (chronoception). So video falls out of
+an image projector + the music projector + the stored temporal ordering.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from document_ir import DocumentIR  # noqa: E402
+from projectors.base import register  # noqa: E402
+
+
+class _Seam:
+    """A registered-but-unimplemented projector. Names its decoder contract."""
+
+    def project(self, doc: DocumentIR) -> bytes:  # pragma: no cover - seam
+        raise NotImplementedError(
+            f"{self.surface!r} projector is a documented seam, not yet built. "
+            f"Decoder contract: {self.decoder_contract}")
+
+
+class ImageProjector(_Seam):
+    surface = "image"
+    media_type = "image/png"
+    ext = "png"
+    modality = "image"
+    decoder_contract = (
+        "reads block.provenance as a spatial layout — nodes become regions, edges "
+        "become adjacencies; salience/importance drive size/contrast; polarity "
+        "drives figure/ground. The efferent twin of image ingest (a geometry->raster "
+        "decoder, learned or engineered), exactly mirroring the embedder that turned "
+        "the image INTO geometry.")
+
+
+class VideoProjector(_Seam):
+    surface = "video"
+    media_type = "video/mp4"
+    ext = "mp4"
+    modality = "video"
+    decoder_contract = (
+        "image x sound x TIME. Composes the image projector (per-keyframe geometry "
+        "layout) with the midi/music projector (score) along the geometry's stored "
+        "temporal ordering (chronoception). Needs no new principle once image + music "
+        "exist — only a muxer.")
+
+
+register(ImageProjector())
+register(VideoProjector())

elp/projector/provenance.py

@@ -0,0 +1,63 @@
+"""provenance.py — the faithfulness audit + geometry->section trace.
+
+A document projected from geometry is only worth anything if every claim traces
+back. This module walks the DocumentIR and proves the discipline held:
+
+  * ZERO ungrounded claims (every fact/interpretation has a real node id),
+  * every emitted sentence maps to a geometry edge (or is a marked connective),
+  * SACRED polarity survived (negations are reported, never silently dropped),
+  * COHERE introduced no new geometry (connectives carry no claim).
+
+It emits both a machine verdict and a human-readable geometry->section table.
+"""
+from __future__ import annotations
+
+from document_ir import DocumentIR
+
+
+def audit(doc: DocumentIR) -> dict:
+    provs = doc.all_provenance()
+    facts = [p for p in provs if p.kind in ("fact", "interpretation")]
+    connectives = [p for p in provs if p.kind == "connective"]
+    ungrounded = [p for p in facts if not p.node_id]
+    negations = [p for p in facts if p.polarity == "neg"]
+    node_ids = sorted({p.node_id for p in facts if p.node_id})
+    return {
+        "claims": len(facts),
+        "connectives": len(connectives),
+        "ungrounded_claims": len(ungrounded),
+        "negations_preserved": len(negations),
+        "distinct_source_nodes": len(node_ids),
+        "faithful": len(ungrounded) == 0,
+        "source_nodes": node_ids,
+    }
+
+
+def trace_table(doc: DocumentIR) -> str:
+    """Human-readable geometry -> section -> claim provenance table."""
+    lines = ["# Provenance — every claim traces geometry", ""]
+    lines.append(f"**Document:** {doc.title}")
+    a = audit(doc)
+    lines.append(f"**Claims:** {a['claims']}  ·  **Ungrounded:** "
+                 f"{a['ungrounded_claims']}  ·  **Negations preserved:** "
+                 f"{a['negations_preserved']}  ·  **Source nodes:** "
+                 f"{a['distinct_source_nodes']}  ·  **Faithful:** "
+                 f"{'YES' if a['faithful'] else 'NO'}")
+    lines.append("")
+    for si, sec in enumerate(doc.sections, 1):
+        lines.append(f"## {si}. {sec.heading}")
+        lines.append(f"_seed nodes: {', '.join(i[:8] for i in sec.seed_ids)}_")
+        lines.append("")
+        lines.append("| # | realized claim | traces geometry edge |")
+        lines.append("|---|----------------|----------------------|")
+        n = 0
+        for block in sec.blocks:
+            for sent, prov in zip(block.sentences, block.provenance):
+                if prov.kind == "connective":
+                    continue
+                n += 1
+                edge = prov.trace().replace("|", "\\|")
+                s = sent.replace("|", "\\|")
+                lines.append(f"| {n} | {s} | {edge} |")
+        lines.append("")
+    return "\n".join(lines) + "\n"

elp/projector/realize.py

@@ -0,0 +1,112 @@
+"""realize.py — REALIZE stage: fill each planned section with faithful passages.
+
+Scales the PROVEN realizer from a single assertion to a passage. For each
+planned proposition we build a realizer-ready clause (the proven
+``_prop_to_clause`` mapping) and run it through the proven engine
+(``engine.realize``), which is a deterministic grammar with the SACRED negation
+contract — it never invents. Each realized sentence is paired with a
+:class:`Provenance` that pins it to the exact geometry edge it came from.
+
+"Passage, not a list of sentences": within a section we lightly vary sentence
+openings and group related claims, but we add NO content the geometry did not
+assert. The only non-geometry words are function words the grammar already owns
+(articles, "and", conjunction of same-subject claims). Document-level flow is
+COHERE's job; this stage owns intra-section fluency + fidelity.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+_NT = os.path.expanduser("~/Desktop/neuron-talk")
+_LR = os.path.expanduser("~/Desktop/lang-realizers")
+for _p in (_NT, _LR):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+import engine  # noqa: E402  (the proven no-LLM realizer)
+from dialogue import _prop_to_clause  # noqa: E402  (proven prop -> clause)
+
+from document_ir import Block, DocumentIR, Provenance, Section  # noqa: E402
+
+
+def _provenance_from(p, kind: str = "fact") -> Provenance:
+    return Provenance(
+        subj_id=p.source_node_id, subject=p.subject, relation=p.predicate,
+        obj=p.object, polarity=p.polarity, confidence=round(float(p.confidence), 3),
+        node_id=p.source_node_id, kind=kind,
+        importance=float(getattr(p, "node_importance", 0.0) or 0.0),
+        salience=0.0,
+    )
+
+
+import re as _re
+
+# a well-formed declarative opens with a determiner, a proper noun, "I", or a
+# capitalized head — not a mis-parsed object pronoun or a copula fragment.
+_BAD_OPENERS = _re.compile(r"^(Me |It is I|There is|This is it|That is it)\b")
+_VACUOUS = _re.compile(r"^\w+ (is|are|was|were) (it|no|nothing|empty|those|this|that)\.?$",
+                       _re.I)
+
+
+def _good_sentence(text: str) -> bool:
+    """Fluency gate — drops degenerate realizations. NEVER loosens faithfulness;
+    it only refuses to SPEAK a claim whose surface came out malformed."""
+    words = text.rstrip(".").split()
+    if len(words) < 3:
+        return False
+    if _BAD_OPENERS.search(text):
+        return False
+    if _VACUOUS.match(text):
+        return False
+    # a sentence that is mostly one-letter/two-letter tokens is a parse artifact
+    short = sum(1 for w in words if len(w.strip(".,'")) <= 2)
+    if short > len(words) / 2:
+        return False
+    return True
+
+
+def _realize_prop(p, lang: str = "en") -> tuple[str, Provenance] | None:
+    """One proposition -> (faithful sentence, provenance) or None if it drops."""
+    clause = _prop_to_clause(p)
+    text = engine.realize(clause, lang)
+    if not text or not text.strip():
+        return None
+    text = text.strip()
+    if not text.endswith((".", "!", "?")):
+        text += "."
+    # capitalize first character (proper nouns / "I" already handled by grammar)
+    text = text[0].upper() + text[1:]
+    if not _good_sentence(text):
+        return None
+    return text, _provenance_from(p)
+
+
+def realize_document(doc: DocumentIR, lang: str = "en") -> DocumentIR:
+    """Fill every planned section's blocks with faithful, realized passages."""
+    for sec in doc.sections:
+        planned = sec.__dict__.get("_planned_props", [])
+        block = Block(role="body")
+        summary_bits: list[str] = []
+        for p in planned:
+            r = _realize_prop(p, lang)
+            if r is None:
+                continue
+            text, prov = r
+            block.sentences.append(text)
+            block.provenance.append(prov)
+            if len(summary_bits) < 1:
+                # a short grounded gloss for TOC / pptx bullets
+                obj = (prov.obj or "").strip().rstrip(".")
+                if obj:
+                    summary_bits.append(obj)
+        if block.sentences:
+            sec.blocks.append(block)
+            sec.summary = summary_bits[0] if summary_bits else ""
+        # drop the transient planning payload; the IR is now self-contained
+        sec.__dict__.pop("_planned_props", None)
+        sec.__dict__.pop("_node", None)
+
+    # prune sections that realized to nothing
+    doc.sections = [s for s in doc.sections if s.blocks]
+    return doc

elp/src/audio-demo.el

@@ -0,0 +1,73 @@
+// audio-demo.el - Drive the native audio surface: render a tone per instrument
+// from its LEARNED signature, then render a small meaning-phrase "piece".
+// Entry point: top-level statement calls main() (same convention as the
+// examples' top-level println(run_test())).
+
+fn micros_to_str(xs: [Int]) -> String {
+    let n: Int = native_list_len(xs)
+    let out: String = ""
+    let i: Int = 0
+    while i < n {
+        if i > 0 { let out: String = out + "," }
+        let out: String = out + int_to_str(native_list_get(xs, i))
+        let i: Int = i + 1
+    }
+    return out
+}
+
+// Render a 1.0s A4 (midi 69) tone from a signature file, print the parsed
+// partials (proving the numbers came from the engram .sig), write the WAV.
+fn render_tone(name: String, sigpath: String, outpath: String, table: [Int]) -> Int {
+    let lines: [String] = sig_load(sigpath)
+    let partials: [Int] = parse_micros(sig_field(lines, "partials"))
+    println("[" + name + "] partials_n=" + sig_field(lines, "partials_n") + "  parsed_partials_micro(scale 1e6)=" + micros_to_str(partials))
+    println("[" + name + "] raw partials line from .sig = " + sig_field(lines, "partials"))
+    let freq: Int = freq_of_midi(69)
+    let note: [Int] = synth_from_sig(lines, freq, 1000, 900, 44100, table)
+    let n: Int = native_list_len(note)
+    let ok: Int = wav_write(outpath, note, n, 44100)
+    println("[" + name + "] rendered " + int_to_str(n) + " samples -> " + outpath + " (write_ok=" + int_to_str(ok) + ")")
+    return n
+}
+
+fn run_demo() -> Int {
+    let table: [Int] = sin_table()
+    fs_mkdir("/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out")
+
+    println("=== TONES: render A4 (midi 69) from each learned signature ===")
+    render_tone("flute",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/flute.sig",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/tone-flute.wav", table)
+    render_tone("clarinet", "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/clarinet.sig", "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/tone-clarinet.wav", table)
+    render_tone("violin",   "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/violin.sig",   "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/tone-violin.wav", table)
+    render_tone("piano",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/piano.sig",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/tone-piano.wav", table)
+    render_tone("organ",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/organ.sig",    "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/tone-organ.wav", table)
+
+    println("")
+    println("=== PIECE: a 6-frame meaning phrase (incl. a NEG frame) ===")
+    let frames: [[String]] = native_list_empty()
+    let frames: [[String]] = native_list_append(frames, audio_frame("agent",    "aff", "0.9", "0.8", "0", "s1"))
+    let frames: [[String]] = native_list_append(frames, audio_frame("theme",    "aff", "0.7", "0.6", "0", "s2"))
+    let frames: [[String]] = native_list_append(frames, audio_frame("cause",    "aff", "0.8", "0.9", "1", "s3"))
+    let frames: [[String]] = native_list_append(frames, audio_frame("negation", "neg", "0.85", "0.7", "0", "s4"))
+    let frames: [[String]] = native_list_append(frames, audio_frame("goal",     "aff", "0.6", "0.5", "1", "s5"))
+    let frames: [[String]] = native_list_append(frames, audio_frame("result",   "aff", "0.95", "1.0", "0", "s6"))
+
+    // Print the plan so the NEG frame's minor third (+3) vs major (+4) is visible.
+    let nf: Int = native_list_len(frames)
+    let fi: Int = 0
+    while fi < nf {
+        let frame: [String] = native_list_get(frames, fi)
+        let plan: [Int] = plan_note(frame)
+        let pol: String = surface_get(frame, "polarity")
+        let third_name: String = "major(+4)"
+        if str_eq(pol, "neg") { let third_name: String = "MINOR(+3)" }
+        println("frame " + int_to_str(fi) + " relation=" + surface_get(frame, "relation") + " polarity=" + pol + " -> midi=" + int_to_str(native_list_get(plan, 0)) + " dur_ms=" + int_to_str(native_list_get(plan, 1)) + " amp_pm=" + int_to_str(native_list_get(plan, 2)) + " third=" + third_name)
+        let fi: Int = fi + 1
+    }
+
+    let piano_lines: [String] = sig_load("/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/piano.sig")
+    let total: Int = realize_audio(frames, piano_lines, "/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/piece.wav", 44100, table)
+    println("PIECE rendered " + int_to_str(total) + " samples -> /Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/piece.wav")
+    return total
+}
+
+println("audio-demo main returned samples=" + int_to_str(run_demo()))

elp/src/audio-surface.el

@@ -0,0 +1,400 @@
+// audio-surface.el - Native own-core additive-synthesis audio surface.
+//
+// The AUDIO efferent seam, native, no Python and no library. This renders real
+// PCM .wav bytes from instrument SIGNATURES read from engram-sourced .sig data
+// files (elp/faculty/sig/*.sig) - the partial amplitudes are NEVER literals in
+// this source; they are parsed from the learned signature at run time. That is
+// the whole proof: render-from-learned-signatures.
+//
+// EL has no float arithmetic operator (codegen emits raw int64 ops for + - * /
+// on the shared 64-bit slot) and no float-arithmetic natives - so ALL synthesis
+// math here is own-core INTEGER fixed-point. Angles use a quarter-wave sine
+// table (scale 10000) from a fixed-point Taylor series; amplitudes are parsed to
+// micro (scale 1e6) straight from the .sig text; frequencies are milliHz ints.
+//
+// Pipeline mirrors the two-stage projector (midi.py): plan_note(frame) reads a
+// frame's meaning-geometry slot-map and derives (pitch, duration, amplitude);
+// realize_audio SUPERPOSES the signature's partials (the compose op) and
+// serialises RIFF/WAVE. Same frame -> midi OR audio.
+
+// -- integer decimal + string helpers -----------------------------------------
+
+fn str_to_int_el(s: String) -> Int {
+    let n: Int = str_len(s)
+    let i: Int = 0
+    let v: Int = 0
+    let neg: Bool = false
+    while i < n {
+        let c: Int = str_char_code(s, i)
+        if c == 45 { let neg: Bool = true }
+        if c >= 48 {
+            if c < 58 {
+                let v: Int = v * 10 + (c - 48)
+            }
+        }
+        let i: Int = i + 1
+    }
+    if neg { return 0 - v }
+    return v
+}
+
+fn parse_micro(s: String) -> Int {
+    let dot: Int = str_index_of(s, ".")
+    if dot < 0 {
+        return str_to_int_el(s) * 1000000
+    }
+    let n: Int = str_len(s)
+    let ipart: String = str_slice(s, 0, dot)
+    let fpart: String = str_slice(s, dot + 1, n)
+    let iv: Int = str_to_int_el(ipart)
+    let fv: Int = 0
+    let scale: Int = 100000
+    let fn2: Int = str_len(fpart)
+    let i: Int = 0
+    while i < 6 {
+        let d: Int = 0
+        if i < fn2 {
+            let d: Int = str_char_code(fpart, i) - 48
+        }
+        let fv: Int = fv + d * scale
+        let scale: Int = scale / 10
+        let i: Int = i + 1
+    }
+    return iv * 1000000 + fv
+}
+
+// -- signature (engram data file) loader ---------------------------------------
+
+fn sig_load(path: String) -> [String] {
+    let text: String = fs_read(path)
+    return str_split(text, "\n")
+}
+
+fn sig_field(lines: [String], key: String) -> String {
+    let pref: String = key + ": "
+    let n: Int = native_list_len(lines)
+    let plen: Int = str_len(pref)
+    let i: Int = 0
+    while i < n {
+        let ln: String = native_list_get(lines, i)
+        if str_starts_with(ln, pref) {
+            return str_slice(ln, plen, str_len(ln))
+        }
+        let i: Int = i + 1
+    }
+    return ""
+}
+
+fn parse_micros(csv: String) -> [Int] {
+    let parts: [String] = str_split(csv, ",")
+    let n: Int = native_list_len(parts)
+    let out: [Int] = native_list_empty()
+    let i: Int = 0
+    while i < n {
+        let out: [Int] = native_list_append(out, parse_micro(native_list_get(parts, i)))
+        let i: Int = i + 1
+    }
+    return out
+}
+
+// -- fixed-point sine (own-core, quarter-wave Taylor table, scale 10000) --------
+
+fn sin_table() -> [Int] {
+    let HP: Int = 1570796
+    let t: [Int] = native_list_empty()
+    let q: Int = 0
+    while q < 257 {
+        let x: Int = q * HP / 256
+        let x2: Int = x * x / 1000000
+        let x3: Int = x2 * x / 1000000
+        let x5: Int = x3 * x2 / 1000000
+        let x7: Int = x5 * x2 / 1000000
+        let x9: Int = x7 * x2 / 1000000
+        let s: Int = x - x3 / 6 + x5 / 120 - x7 / 5040 + x9 / 362880
+        let t: [Int] = native_list_append(t, s / 100)
+        let q: Int = q + 1
+    }
+    return t
+}
+
+fn sin_lookup(t: [Int], phase: Int) -> Int {
+    let p: Int = phase % 1024
+    if p < 0 { let p: Int = p + 1024 }
+    let quad: Int = p / 256
+    let r: Int = p % 256
+    if quad == 0 { return native_list_get(t, r) }
+    if quad == 1 { return native_list_get(t, 256 - r) }
+    if quad == 2 { return 0 - native_list_get(t, r) }
+    return 0 - native_list_get(t, 256 - r)
+}
+
+fn isqrt_int(n: Int) -> Int {
+    if n <= 0 { return 0 }
+    let x: Int = n
+    let y: Int = (x + 1) / 2
+    while y < x {
+        let x: Int = y
+        let y: Int = (x + n / x) / 2
+    }
+    return x
+}
+
+// freq_of_midi: equal-tempered frequency in milliHz. 440000 mHz at midi 69.
+fn freq_of_midi(m: Int) -> Int {
+    let f: Int = 440000
+    if m > 69 {
+        let k: Int = m - 69
+        let i: Int = 0
+        while i < k {
+            let f: Int = f * 1059463 / 1000000
+            let i: Int = i + 1
+        }
+        return f
+    }
+    if m < 69 {
+        let k: Int = 69 - m
+        let i: Int = 0
+        while i < k {
+            let f: Int = f * 1000000 / 1059463
+            let i: Int = i + 1
+        }
+        return f
+    }
+    return f
+}
+
+// -- envelope (ADSR), scale 1000 -----------------------------------------------
+
+fn adsr_env(i: Int, total: Int, atk_n: Int, dec_n: Int, sus_pm: Int, rel_n: Int) -> Int {
+    if i < atk_n {
+        if atk_n == 0 { return 1000 }
+        return 1000 * i / atk_n
+    }
+    if i < atk_n + dec_n {
+        if dec_n == 0 { return sus_pm }
+        return 1000 - (1000 - sus_pm) * (i - atk_n) / dec_n
+    }
+    let rel_start: Int = total - rel_n
+    if i < rel_start {
+        return sus_pm
+    }
+    if rel_n == 0 { return 0 }
+    let left: Int = total - i
+    return sus_pm * left / rel_n
+}
+
+// -- note synthesis: SUPERPOSE the learned partials -> [Int] samples -----------
+fn note_samples(freq_mHz: Int, dur_ms: Int, rate: Int, partials: [Int], sumP: Int, b_micro: Int, vib_rate: Int, vib_cents: Int, atk_ms: Int, dec_ms: Int, sus_pm: Int, rel_ms: Int, amp_pm: Int, table: [Int]) -> [Int] {
+    let total: Int = dur_ms * rate / 1000
+    let atk_n: Int = atk_ms * rate / 1000
+    let dec_n: Int = dec_ms * rate / 1000
+    let rel_n: Int = rel_ms * rate / 1000
+    let np: Int = native_list_len(partials)
+    let half_mhz: Int = rate * 1000 / 2
+    let out: [Int] = native_list_empty()
+    let i: Int = 0
+    while i < total {
+        let acc: Int = 0
+        let k: Int = 0
+        while k < np {
+            let harm: Int = k + 1
+            let amp_k: Int = native_list_get(partials, k)
+            let factor: Int = 1000000
+            if b_micro > 0 {
+                let val: Int = 1000000 + b_micro * harm * harm
+                let factor: Int = isqrt_int(val * 1000000)
+            }
+            let fn_mhz: Int = freq_mHz * harm
+            let fn_mhz: Int = fn_mhz * factor / 1000000
+            if vib_cents > 0 {
+                if vib_rate > 0 {
+                    let vphase: Int = i * vib_rate * 1024 / rate
+                    let vs: Int = sin_lookup(table, vphase)
+                    let vibf: Int = 1000000 + (vib_cents * vs * 833) / 10000
+                    let fn_mhz: Int = fn_mhz * vibf / 1000000
+                }
+            }
+            if fn_mhz <= half_mhz {
+                let phase: Int = i * fn_mhz * 1024 / (rate * 1000)
+                let sv: Int = sin_lookup(table, phase)
+                let acc: Int = acc + sv * amp_k / 1000000
+            }
+            let k: Int = k + 1
+        }
+        let env: Int = adsr_env(i, total, atk_n, dec_n, sus_pm, rel_n)
+        let s16: Int = acc * 2800000 / sumP
+        let s16: Int = s16 * env / 1000
+        let s16: Int = s16 * amp_pm / 1000
+        if s16 > 32767 { let s16: Int = 32767 }
+        if s16 < 0 - 32767 { let s16: Int = 0 - 32767 }
+        let out: [Int] = native_list_append(out, s16)
+        let i: Int = i + 1
+    }
+    return out
+}
+
+fn synth_from_sig(lines: [String], freq_mHz: Int, dur_ms: Int, amp_pm: Int, rate: Int, table: [Int]) -> [Int] {
+    let partials: [Int] = parse_micros(sig_field(lines, "partials"))
+    let np: Int = native_list_len(partials)
+    let sumP: Int = 0
+    let j: Int = 0
+    while j < np {
+        let pj: Int = native_list_get(partials, j)
+        let sumP: Int = sumP + pj
+        let j: Int = j + 1
+    }
+    if sumP <= 0 { let sumP: Int = 1000000 }
+    let adsr: [String] = str_split(sig_field(lines, "adsr"), ",")
+    let atk_ms: Int = parse_micro(native_list_get(adsr, 0)) / 1000
+    let dec_ms: Int = parse_micro(native_list_get(adsr, 1)) / 1000
+    let sus_pm: Int = parse_micro(native_list_get(adsr, 2)) / 1000
+    let rel_ms: Int = parse_micro(native_list_get(adsr, 3)) / 1000
+    let b_micro: Int = parse_micro(sig_field(lines, "inharmonicity_B"))
+    let vib_rate: Int = str_to_int_el(sig_field(lines, "vibrato_rate_hz"))
+    let vib_cents: Int = str_to_int_el(sig_field(lines, "vibrato_depth_cents"))
+    return note_samples(freq_mHz, dur_ms, rate, partials, sumP, b_micro, vib_rate, vib_cents, atk_ms, dec_ms, sus_pm, rel_ms, amp_pm, table)
+}
+
+// -- byte-buffer helpers (own-core, no library) --------------------------------
+
+fn put_tag(buf: String, pos: Int, s: String) -> String {
+    let n: Int = str_len(s)
+    let i: Int = 0
+    while i < n {
+        let buf: String = __str_set_char(buf, pos + i, str_char_code(s, i))
+        let i: Int = i + 1
+    }
+    return buf
+}
+
+fn put_u32le(buf: String, pos: Int, v: Int) -> String {
+    let buf: String = __str_set_char(buf, pos, v % 256)
+    let buf: String = __str_set_char(buf, pos + 1, (v / 256) % 256)
+    let buf: String = __str_set_char(buf, pos + 2, (v / 65536) % 256)
+    let buf: String = __str_set_char(buf, pos + 3, (v / 16777216) % 256)
+    return buf
+}
+
+fn put_u16le(buf: String, pos: Int, v: Int) -> String {
+    let buf: String = __str_set_char(buf, pos, v % 256)
+    let buf: String = __str_set_char(buf, pos + 1, (v / 256) % 256)
+    return buf
+}
+
+// -- WAV serializer: own-core RIFF/WAVE, PCM mono 16-bit -----------------------
+
+fn wav_write(path: String, samples: [Int], n: Int, rate: Int) -> Int {
+    let data_len: Int = n * 2
+    let total: Int = 44 + data_len
+    let buf: String = __str_alloc(total)
+    let buf: String = put_tag(buf, 0, "RIFF")
+    let buf: String = put_u32le(buf, 4, 36 + data_len)
+    let buf: String = put_tag(buf, 8, "WAVE")
+    let buf: String = put_tag(buf, 12, "fmt ")
+    let buf: String = put_u32le(buf, 16, 16)
+    let buf: String = put_u16le(buf, 20, 1)
+    let buf: String = put_u16le(buf, 22, 1)
+    let buf: String = put_u32le(buf, 24, rate)
+    let buf: String = put_u32le(buf, 28, rate * 2)
+    let buf: String = put_u16le(buf, 32, 2)
+    let buf: String = put_u16le(buf, 34, 16)
+    let buf: String = put_tag(buf, 36, "data")
+    let buf: String = put_u32le(buf, 40, data_len)
+    let i: Int = 0
+    while i < n {
+        let v: Int = native_list_get(samples, i)
+        if v < 0 { let v: Int = v + 65536 }
+        let buf: String = __str_set_char(buf, 44 + i * 2, v % 256)
+        let buf: String = __str_set_char(buf, 44 + i * 2 + 1, (v / 256) % 256)
+        let i: Int = i + 1
+    }
+    let ok: Int = fs_write_bytes(path, buf, total)
+    return ok
+}
+
+// -- plan: frame slot-map -> note atom (pitch, duration, amplitude) ------------
+
+fn audio_frame(relation: String, polarity: String, confidence: String, importance: String, salience: String, subj_id: String) -> [String] {
+    let f: [String] = native_list_empty()
+    let f: [String] = native_list_append(f, "relation")
+    let f: [String] = native_list_append(f, relation)
+    let f: [String] = native_list_append(f, "polarity")
+    let f: [String] = native_list_append(f, polarity)
+    let f: [String] = native_list_append(f, "confidence")
+    let f: [String] = native_list_append(f, confidence)
+    let f: [String] = native_list_append(f, "importance")
+    let f: [String] = native_list_append(f, importance)
+    let f: [String] = native_list_append(f, "salience")
+    let f: [String] = native_list_append(f, salience)
+    let f: [String] = native_list_append(f, "subj_id")
+    let f: [String] = native_list_append(f, subj_id)
+    return f
+}
+
+fn degree_offset(deg: Int) -> Int {
+    if deg == 0 { return 0 }
+    if deg == 1 { return 2 }
+    if deg == 2 { return 4 }
+    if deg == 3 { return 5 }
+    if deg == 4 { return 7 }
+    if deg == 5 { return 9 }
+    return 11
+}
+
+// returns [midi, dur_ms, amp_pm]
+fn plan_note(frame: [String]) -> [Int] {
+    let relation: String = surface_get(frame, "relation")
+    let polarity: String = surface_get(frame, "polarity")
+    let confidence: String = surface_get(frame, "confidence")
+    let importance: String = surface_get(frame, "importance")
+    let salience: String = surface_get(frame, "salience")
+    let rn: Int = str_len(relation)
+    let csum: Int = 0
+    let i: Int = 0
+    while i < rn {
+        let cc: Int = str_char_code(relation, i)
+        let csum: Int = csum + cc
+        let i: Int = i + 1
+    }
+    let deg: Int = csum % 7
+    let third: Int = 4
+    if str_eq(polarity, "neg") { let third: Int = 3 }
+    let sal_oct: Int = str_to_int_el(salience)
+    let doff: Int = degree_offset(deg)
+    let midi: Int = 60 + sal_oct * 12 + doff + third
+    let conf_micro: Int = parse_micro(confidence)
+    let dur_ms: Int = 200 + conf_micro / 1000
+    let imp_micro: Int = parse_micro(importance)
+    let amp_pm: Int = 400 + imp_micro / 2000
+    let out: [Int] = native_list_empty()
+    let out: [Int] = native_list_append(out, midi)
+    let out: [Int] = native_list_append(out, dur_ms)
+    let out: [Int] = native_list_append(out, amp_pm)
+    return out
+}
+
+fn realize_audio(frames: [[String]], sig_lines: [String], path: String, rate: Int, table: [Int]) -> Int {
+    let nf: Int = native_list_len(frames)
+    let all: [Int] = native_list_empty()
+    let count: Int = 0
+    let fi: Int = 0
+    while fi < nf {
+        let frame: [String] = native_list_get(frames, fi)
+        let plan: [Int] = plan_note(frame)
+        let midi: Int = native_list_get(plan, 0)
+        let dur_ms: Int = native_list_get(plan, 1)
+        let amp_pm: Int = native_list_get(plan, 2)
+        let freq: Int = freq_of_midi(midi)
+        let note: [Int] = synth_from_sig(sig_lines, freq, dur_ms, amp_pm, rate, table)
+        let nn: Int = native_list_len(note)
+        let j: Int = 0
+        while j < nn {
+            let all: [Int] = native_list_append(all, native_list_get(note, j))
+            let j: Int = j + 1
+        }
+        let count: Int = count + nn
+        let fi: Int = fi + 1
+    }
+    let ok: Int = wav_write(path, all, count, rate)
+    return count
+}

elp/src/image-demo.el

@@ -0,0 +1,65 @@
+// image-demo.el - Drive the native PNG surface: plan a scene from a small
+// meaning phrase (incl. a NEG frame) and emit a byte-valid 64x64 PNG whose
+// palette is read from elp/faculty/sig/scene.basis.
+
+fn img_frame(relation: String, polarity: String, confidence: String, importance: String, salience: String, subj_id: String) -> [String] {
+    let f: [String] = native_list_empty()
+    let f: [String] = native_list_append(f, "relation")
+    let f: [String] = native_list_append(f, relation)
+    let f: [String] = native_list_append(f, "polarity")
+    let f: [String] = native_list_append(f, polarity)
+    let f: [String] = native_list_append(f, "confidence")
+    let f: [String] = native_list_append(f, confidence)
+    let f: [String] = native_list_append(f, "importance")
+    let f: [String] = native_list_append(f, importance)
+    let f: [String] = native_list_append(f, "salience")
+    let f: [String] = native_list_append(f, salience)
+    let f: [String] = native_list_append(f, "subj_id")
+    let f: [String] = native_list_append(f, subj_id)
+    return f
+}
+
+fn rgb_str(c: [Int]) -> String {
+    return int_to_str(native_list_get(c, 0)) + "," + int_to_str(native_list_get(c, 1)) + "," + int_to_str(native_list_get(c, 2))
+}
+
+fn run_image() -> Int {
+    fs_mkdir("/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out")
+    let table: [Int] = crc_table()
+    println("crc_table[1]=" + int_to_str(native_list_get(table, 1)) + " (expect 1996959894 / 0x77073096)")
+
+    let basis: [String] = basis_load("/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/sig/scene.basis")
+    let warm: [Int] = parse_rgb(basis_field(basis, "warm"))
+    let cool: [Int] = parse_rgb(basis_field(basis, "cool"))
+    let bg: [Int] = parse_rgb(basis_field(basis, "bg"))
+    println("basis warm=" + rgb_str(warm) + " cool=" + rgb_str(cool) + " bg=" + rgb_str(bg) + "  (read from scene.basis)")
+
+    let frames: [[String]] = native_list_empty()
+    let frames: [[String]] = native_list_append(frames, img_frame("agent",    "aff", "0.9", "0.8", "0", "s1"))
+    let frames: [[String]] = native_list_append(frames, img_frame("theme",    "aff", "0.7", "0.6", "1", "s2"))
+    let frames: [[String]] = native_list_append(frames, img_frame("cause",    "aff", "0.8", "0.9", "0", "s3"))
+    let frames: [[String]] = native_list_append(frames, img_frame("negation", "neg", "0.85", "0.7", "1", "s4"))
+    let frames: [[String]] = native_list_append(frames, img_frame("goal",     "aff", "0.6", "0.5", "0", "s5"))
+    let frames: [[String]] = native_list_append(frames, img_frame("result",   "aff", "0.95", "1.0", "1", "s6"))
+
+    let shapes: [[Int]] = plan_scene(frames, warm, cool)
+    let ns: Int = native_list_len(shapes)
+    println("planned " + int_to_str(ns) + " shapes:")
+    let si: Int = 0
+    while si < ns {
+        let sh: [Int] = native_list_get(shapes, si)
+        let pol: String = surface_get(native_list_get(frames, si), "polarity")
+        println("  shape " + int_to_str(si) + " type=" + int_to_str(native_list_get(sh, 0)) + " x=" + int_to_str(native_list_get(sh, 1)) + " y=" + int_to_str(native_list_get(sh, 2)) + " size=" + int_to_str(native_list_get(sh, 3)) + " rgb=" + int_to_str(native_list_get(sh, 4)) + "," + int_to_str(native_list_get(sh, 5)) + "," + int_to_str(native_list_get(sh, 6)) + " polarity=" + pol)
+        let si: Int = si + 1
+    }
+
+    let raw: [Int] = rasterize(64, 64, shapes, bg)
+    println("rasterized raw (filtered scanlines) bytes=" + int_to_str(native_list_len(raw)) + " (expect 12352)")
+    let png: [Int] = png_build(64, 64, raw, table)
+    let plen: Int = native_list_len(png)
+    let ok: Int = png_write("/Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/scene.png", png)
+    println("PNG bytes=" + int_to_str(plen) + " -> /Users/will/Development/neuron-technologies/foundation/el/.claude/worktrees/agent-aaf04b0a9714c4070/elp/faculty/out/scene.png (write_ok=" + int_to_str(ok) + ")")
+    return plen
+}
+
+println("image-demo returned png_bytes=" + int_to_str(run_image()))

elp/src/image-surface.el

@@ -0,0 +1,412 @@
+// image-surface.el - Native own-core raster PNG surface (the image efferent
+// twin of audio). Renders a 64x64 RGB scene deterministically from a frame's
+// meaning-geometry, then serialises a byte-valid PNG entirely own-core:
+// 8-byte magic, IHDR, IDAT (zlib STORED/uncompressed DEFLATE + Adler32), IEND,
+// with a per-chunk CRC32 computed via software xor32 (EL has no bitwise ops).
+//
+// The RGB palette basis is read from elp/faculty/sig/scene.basis (data, not
+// literals) - the same read-from-learned discipline as the audio signatures.
+// Integer-only throughout; pixels are composed functionally (painter's order)
+// so no list mutation is needed.
+
+// -- small int/parse helpers (self-contained) ----------------------------------
+
+fn i_str_to_int(s: String) -> Int {
+    let n: Int = str_len(s)
+    let i: Int = 0
+    let v: Int = 0
+    while i < n {
+        let c: Int = str_char_code(s, i)
+        if c >= 48 {
+            if c < 58 {
+                let v: Int = v * 10 + (c - 48)
+            }
+        }
+        let i: Int = i + 1
+    }
+    return v
+}
+
+fn basis_load(path: String) -> [String] {
+    return str_split(fs_read(path), "\n")
+}
+
+fn basis_field(lines: [String], key: String) -> String {
+    let pref: String = key + ": "
+    let n: Int = native_list_len(lines)
+    let plen: Int = str_len(pref)
+    let i: Int = 0
+    while i < n {
+        let ln: String = native_list_get(lines, i)
+        if str_starts_with(ln, pref) {
+            return str_slice(ln, plen, str_len(ln))
+        }
+        let i: Int = i + 1
+    }
+    return ""
+}
+
+fn parse_rgb(csv: String) -> [Int] {
+    let parts: [String] = str_split(csv, ",")
+    let out: [Int] = native_list_empty()
+    let n: Int = native_list_len(parts)
+    let i: Int = 0
+    while i < n {
+        let v: Int = i_str_to_int(native_list_get(parts, i))
+        let out: [Int] = native_list_append(out, v)
+        let i: Int = i + 1
+    }
+    return out
+}
+
+// -- software 32-bit XOR (no bitwise ops in EL) --------------------------------
+
+fn xor32(a: Int, b: Int) -> Int {
+    let r: Int = 0
+    let bit: Int = 1
+    let i: Int = 0
+    while i < 32 {
+        let abit: Int = (a / bit) % 2
+        let bbit: Int = (b / bit) % 2
+        if abit != bbit {
+            let add: Int = bit
+            let r: Int = r + add
+        }
+        let bit: Int = bit * 2
+        let i: Int = i + 1
+    }
+    return r
+}
+
+// -- CRC32 (table-driven, table built with xor32) ------------------------------
+
+fn crc_table() -> [Int] {
+    let t: [Int] = native_list_empty()
+    let n: Int = 0
+    while n < 256 {
+        let c: Int = n
+        let k: Int = 0
+        while k < 8 {
+            if c % 2 == 1 {
+                let h: Int = c / 2
+                let c: Int = xor32(h, 3988292384)
+            } else {
+                let c: Int = c / 2
+            }
+            let k: Int = k + 1
+        }
+        let t: [Int] = native_list_append(t, c)
+        let n: Int = n + 1
+    }
+    return t
+}
+
+fn crc32_of(bytes: [Int], table: [Int]) -> Int {
+    let crc: Int = 4294967295
+    let n: Int = native_list_len(bytes)
+    let i: Int = 0
+    while i < n {
+        let b: Int = native_list_get(bytes, i)
+        let lo: Int = crc % 256
+        let idx: Int = xor32(lo, b) % 256
+        let tv: Int = native_list_get(table, idx)
+        let hi: Int = crc / 256
+        let crc: Int = xor32(hi, tv)
+        let i: Int = i + 1
+    }
+    return xor32(crc, 4294967295)
+}
+
+// -- Adler32 (for the zlib trailer) --------------------------------------------
+
+fn adler32_of(bytes: [Int]) -> Int {
+    let a: Int = 1
+    let b: Int = 0
+    let n: Int = native_list_len(bytes)
+    let i: Int = 0
+    while i < n {
+        let byte: Int = native_list_get(bytes, i)
+        let a: Int = (a + byte) % 65521
+        let b: Int = (b + a) % 65521
+        let i: Int = i + 1
+    }
+    return b * 65536 + a
+}
+
+// -- byte-list append helpers --------------------------------------------------
+
+fn app_u32be(dst: [Int], v: Int) -> [Int] {
+    let dst: [Int] = native_list_append(dst, (v / 16777216) % 256)
+    let dst: [Int] = native_list_append(dst, (v / 65536) % 256)
+    let dst: [Int] = native_list_append(dst, (v / 256) % 256)
+    let dst: [Int] = native_list_append(dst, v % 256)
+    return dst
+}
+
+fn app_tag(dst: [Int], s: String) -> [Int] {
+    let n: Int = str_len(s)
+    let i: Int = 0
+    while i < n {
+        let dst: [Int] = native_list_append(dst, str_char_code(s, i))
+        let i: Int = i + 1
+    }
+    return dst
+}
+
+fn app_all(dst: [Int], src: [Int]) -> [Int] {
+    let n: Int = native_list_len(src)
+    let i: Int = 0
+    while i < n {
+        let dst: [Int] = native_list_append(dst, native_list_get(src, i))
+        let i: Int = i + 1
+    }
+    return dst
+}
+
+// -- plan: frame meaning-geometry -> shape atoms -------------------------------
+// shape = [type, x, y, size, r, g, b]  (type 0=rect 1=disc 2=triangle)
+
+fn charsum(s: String) -> Int {
+    let n: Int = str_len(s)
+    let i: Int = 0
+    let acc: Int = 0
+    while i < n {
+        let c: Int = str_char_code(s, i)
+        let acc: Int = acc + c
+        let i: Int = i + 1
+    }
+    return acc
+}
+
+fn micro_of(s: String) -> Int {
+    let dot: Int = str_index_of(s, ".")
+    if dot < 0 { return i_str_to_int(s) * 1000000 }
+    let n: Int = str_len(s)
+    let fp: String = str_slice(s, dot + 1, n)
+    let ip: String = str_slice(s, 0, dot)
+    let iv: Int = i_str_to_int(ip)
+    let fv: Int = 0
+    let scale: Int = 100000
+    let fl: Int = str_len(fp)
+    let i: Int = 0
+    while i < 6 {
+        let d: Int = 0
+        if i < fl { let d: Int = str_char_code(fp, i) - 48 }
+        let fv: Int = fv + d * scale
+        let scale: Int = scale / 10
+        let i: Int = i + 1
+    }
+    return iv * 1000000 + fv
+}
+
+fn plan_scene(frames: [[String]], warm: [Int], cool: [Int]) -> [[Int]] {
+    let shapes: [[Int]] = native_list_empty()
+    let nf: Int = native_list_len(frames)
+    let fi: Int = 0
+    while fi < nf {
+        let fr: [String] = native_list_get(frames, fi)
+        let relation: String = surface_get(fr, "relation")
+        let polarity: String = surface_get(fr, "polarity")
+        let confidence: String = surface_get(fr, "confidence")
+        let importance: String = surface_get(fr, "importance")
+        let salience: String = surface_get(fr, "salience")
+        // relation -> shape type
+        let stype: Int = charsum(relation) % 3
+        // confidence -> size (8..22)
+        let cmi: Int = micro_of(confidence)
+        let size: Int = 8 + cmi / 71428
+        // salience -> y
+        let sal: Int = i_str_to_int(salience)
+        let y: Int = 6 + sal * 26
+        // subj_id/index -> x
+        let x: Int = 4 + (fi * 10) % 48
+        // polarity -> warm/cool base color
+        let br: Int = native_list_get(warm, 0)
+        let bg2: Int = native_list_get(warm, 1)
+        let bb: Int = native_list_get(warm, 2)
+        if str_eq(polarity, "neg") {
+            let br: Int = native_list_get(cool, 0)
+            let bg2: Int = native_list_get(cool, 1)
+            let bb: Int = native_list_get(cool, 2)
+        }
+        // importance -> brightness (500..1000 permille)
+        let imi: Int = micro_of(importance)
+        let bpm: Int = 500 + imi / 2000
+        let r: Int = br * bpm / 1000
+        let g: Int = bg2 * bpm / 1000
+        let b: Int = bb * bpm / 1000
+        let sh: [Int] = native_list_empty()
+        let sh: [Int] = native_list_append(sh, stype)
+        let sh: [Int] = native_list_append(sh, x)
+        let sh: [Int] = native_list_append(sh, y)
+        let sh: [Int] = native_list_append(sh, size)
+        let sh: [Int] = native_list_append(sh, r)
+        let sh: [Int] = native_list_append(sh, g)
+        let sh: [Int] = native_list_append(sh, b)
+        let shapes: [[Int]] = native_list_append(shapes, sh)
+        let fi: Int = fi + 1
+    }
+    return shapes
+}
+
+// covers: is (px,py) inside this shape?
+fn covers(sh: [Int], px: Int, py: Int) -> Bool {
+    let stype: Int = native_list_get(sh, 0)
+    let sx: Int = native_list_get(sh, 1)
+    let sy: Int = native_list_get(sh, 2)
+    let size: Int = native_list_get(sh, 3)
+    let cx: Int = sx + size / 2
+    if stype == 0 {
+        if px >= sx {
+            if px < sx + size {
+                if py >= sy {
+                    if py < sy + size {
+                        return true
+                    }
+                }
+            }
+        }
+        return false
+    }
+    if stype == 1 {
+        let rad: Int = size / 2
+        let dx: Int = px - cx
+        let dy: Int = py - (sy + rad)
+        if dx * dx + dy * dy <= rad * rad {
+            return true
+        }
+        return false
+    }
+    // triangle: apex at top (sy), base at sy+size
+    if py >= sy {
+        if py < sy + size {
+            let dyv: Int = py - sy
+            let halfw: Int = dyv / 2
+            let dxv: Int = px - cx
+            let adx: Int = dxv
+            if adx < 0 { let adx: Int = 0 - dxv }
+            if adx <= halfw {
+                return true
+            }
+        }
+    }
+    return false
+}
+
+// pixel_color: painter's algorithm - last covering shape wins. Returns [r,g,b].
+fn pixel_color(px: Int, py: Int, shapes: [[Int]], bg: [Int]) -> [Int] {
+    let r: Int = native_list_get(bg, 0)
+    let g: Int = native_list_get(bg, 1)
+    let b: Int = native_list_get(bg, 2)
+    let n: Int = native_list_len(shapes)
+    let i: Int = 0
+    while i < n {
+        let sh: [Int] = native_list_get(shapes, i)
+        if covers(sh, px, py) {
+            let r: Int = native_list_get(sh, 4)
+            let g: Int = native_list_get(sh, 5)
+            let b: Int = native_list_get(sh, 6)
+        }
+        let i: Int = i + 1
+    }
+    let out: [Int] = native_list_empty()
+    let out: [Int] = native_list_append(out, r)
+    let out: [Int] = native_list_append(out, g)
+    let out: [Int] = native_list_append(out, b)
+    return out
+}
+
+// rasterize: build the raw (filtered) scanline byte stream, filter byte 0 / row.
+fn rasterize(w: Int, h: Int, shapes: [[Int]], bg: [Int]) -> [Int] {
+    let raw: [Int] = native_list_empty()
+    let y: Int = 0
+    while y < h {
+        let raw: [Int] = native_list_append(raw, 0)
+        let x: Int = 0
+        while x < w {
+            let col: [Int] = pixel_color(x, y, shapes, bg)
+            let raw: [Int] = native_list_append(raw, native_list_get(col, 0))
+            let raw: [Int] = native_list_append(raw, native_list_get(col, 1))
+            let raw: [Int] = native_list_append(raw, native_list_get(col, 2))
+            let x: Int = x + 1
+        }
+        let y: Int = y + 1
+    }
+    return raw
+}
+
+// zlib stream with a single STORED (uncompressed) DEFLATE block + Adler32.
+fn zlib_store(raw: [Int]) -> [Int] {
+    let z: [Int] = native_list_empty()
+    let z: [Int] = native_list_append(z, 120)
+    let z: [Int] = native_list_append(z, 1)
+    let z: [Int] = native_list_append(z, 1)
+    let len: Int = native_list_len(raw)
+    let nlen: Int = 65535 - len
+    let z: [Int] = native_list_append(z, len % 256)
+    let z: [Int] = native_list_append(z, (len / 256) % 256)
+    let z: [Int] = native_list_append(z, nlen % 256)
+    let z: [Int] = native_list_append(z, (nlen / 256) % 256)
+    let z: [Int] = app_all(z, raw)
+    let ad: Int = adler32_of(raw)
+    let z: [Int] = app_u32be(z, ad)
+    return z
+}
+
+// append a full PNG chunk: length + (type+data) + crc32(type+data).
+fn app_chunk(png: [Int], type_and_data: [Int], table: [Int]) -> [Int] {
+    let total: Int = native_list_len(type_and_data)
+    let dlen: Int = total - 4
+    let png: [Int] = app_u32be(png, dlen)
+    let png: [Int] = app_all(png, type_and_data)
+    let crc: Int = crc32_of(type_and_data, table)
+    let png: [Int] = app_u32be(png, crc)
+    return png
+}
+
+fn png_build(w: Int, h: Int, raw: [Int], table: [Int]) -> [Int] {
+    let png: [Int] = native_list_empty()
+    // 8-byte signature
+    let png: [Int] = native_list_append(png, 137)
+    let png: [Int] = native_list_append(png, 80)
+    let png: [Int] = native_list_append(png, 78)
+    let png: [Int] = native_list_append(png, 71)
+    let png: [Int] = native_list_append(png, 13)
+    let png: [Int] = native_list_append(png, 10)
+    let png: [Int] = native_list_append(png, 26)
+    let png: [Int] = native_list_append(png, 10)
+    // IHDR
+    let ihdr: [Int] = native_list_empty()
+    let ihdr: [Int] = app_tag(ihdr, "IHDR")
+    let ihdr: [Int] = app_u32be(ihdr, w)
+    let ihdr: [Int] = app_u32be(ihdr, h)
+    let ihdr: [Int] = native_list_append(ihdr, 8)
+    let ihdr: [Int] = native_list_append(ihdr, 2)
+    let ihdr: [Int] = native_list_append(ihdr, 0)
+    let ihdr: [Int] = native_list_append(ihdr, 0)
+    let ihdr: [Int] = native_list_append(ihdr, 0)
+    let png: [Int] = app_chunk(png, ihdr, table)
+    // IDAT
+    let z: [Int] = zlib_store(raw)
+    let idat: [Int] = native_list_empty()
+    let idat: [Int] = app_tag(idat, "IDAT")
+    let idat: [Int] = app_all(idat, z)
+    let png: [Int] = app_chunk(png, idat, table)
+    // IEND
+    let iend: [Int] = native_list_empty()
+    let iend: [Int] = app_tag(iend, "IEND")
+    let png: [Int] = app_chunk(png, iend, table)
+    return png
+}
+
+fn png_write(path: String, png: [Int]) -> Int {
+    let n: Int = native_list_len(png)
+    let buf: String = __str_alloc(n)
+    let i: Int = 0
+    while i < n {
+        let buf: String = __str_set_char(buf, i, native_list_get(png, i))
+        let i: Int = i + 1
+    }
+    let ok: Int = fs_write_bytes(path, buf, n)
+    return ok
+}

elp/src/surface-profile.el

@@ -0,0 +1,153 @@
+// surface-profile.el - Surface profile data and accessors.
+//
+// THE NATIVE EFFERENT SEAM: surface = a pluggable PROFILE, using the exact same
+// slot-map mechanism as language-profile.el. A language profile tells the
+// realizer HOW to shape a natural-language surface (word order, morphology); a
+// SURFACE profile tells the realizer WHICH surface to project meaning onto
+// (markdown, docx, html, plain, or a non-text medium like symbolic music).
+//
+// The generalization is exact: realize_lang(form, profile) already renders a
+// SemForm parameterized by a [String] profile read via lang_get. Surface is one
+// more axis of that same profile vector. One frame (sem_frame), one plan step
+// (sem_to_spec), one render (realize) — the surface is DATA, not a code path,
+// precisely as language is data. Adding a surface means adding a profile, no
+// engine change. This is the multimodal projector, native: geometry -> any
+// surface, the efferent twin of ingest.
+//
+// Surface slot keys:
+//   surface     - "markdown" | "docx" | "html" | "plain" | "midi" | "image"
+//   modality    - "text" | "audio" | "image" | "video"
+//   media_type  - MIME type of the emitted surface
+//   head_open   - string prepended to a heading   (e.g. "## " for markdown)
+//   head_close  - string appended  to a heading   (e.g. "" for markdown, "</h2>" for html)
+//   emph_open   - string opening emphasis          (e.g. "*")
+//   emph_close  - string closing emphasis          (e.g. "*")
+//   item_mark   - list-item marker                 (e.g. "- ")
+//   para_sep    - paragraph separator              (e.g. "\n\n")
+//
+// For a TEXT modality the render composes these markers around the surface that
+// the EXISTING realizer produces (realize_lang / sem_realize). For a non-text
+// modality (audio/image) the profile declares modality + media_type and the
+// render dispatches to the medium projector, which reads the SAME frame's
+// geometry (its intent/affect/structure) and projects it onto sound or pixels —
+// deterministic-from-meaning, nothing invented. That dispatch point is where a
+// music profile or image profile conforms, native, no parallel layer.
+
+// -- Constructor -------------------------------------------------------------
+
+fn surface_profile(surface: String, modality: String, media_type: String, head_open: String, head_close: String, emph_open: String, emph_close: String, item_mark: String, para_sep: String) -> [String] {
+    let r: [String] = native_list_empty()
+    let r = native_list_append(r, "surface")
+    let r = native_list_append(r, surface)
+    let r = native_list_append(r, "modality")
+    let r = native_list_append(r, modality)
+    let r = native_list_append(r, "media_type")
+    let r = native_list_append(r, media_type)
+    let r = native_list_append(r, "head_open")
+    let r = native_list_append(r, head_open)
+    let r = native_list_append(r, "head_close")
+    let r = native_list_append(r, head_close)
+    let r = native_list_append(r, "emph_open")
+    let r = native_list_append(r, emph_open)
+    let r = native_list_append(r, "emph_close")
+    let r = native_list_append(r, emph_close)
+    let r = native_list_append(r, "item_mark")
+    let r = native_list_append(r, item_mark)
+    let r = native_list_append(r, "para_sep")
+    let r = native_list_append(r, para_sep)
+    return r
+}
+
+// -- Accessor (same convention as lang_get; standalone so this is a leaf) -----
+
+fn surface_get(profile: [String], key: String) -> String {
+    let n: Int = native_list_len(profile)
+    let i: Int = 0
+    while i < n - 1 {
+        let k: String = native_list_get(profile, i)
+        if str_eq(k, key) {
+            return native_list_get(profile, i + 1)
+        }
+        let i = i + 2
+    }
+    return ""
+}
+
+fn surface_is_text(profile: [String]) -> Bool {
+    return str_eq(surface_get(profile, "modality"), "text")
+}
+
+// -- Built-in TEXT surface profiles ------------------------------------------
+
+// Markdown: headings with "## ", emphasis with "*", "- " list items.
+fn surface_profile_markdown() -> [String] {
+    return surface_profile("markdown", "text", "text/markdown", "## ", "", "*", "*", "- ", "\n\n")
+}
+
+// Plain text: no markup at all — headings become bare uppercase-free lines.
+fn surface_profile_plain() -> [String] {
+    return surface_profile("plain", "text", "text/plain", "", "", "", "", "  - ", "\n\n")
+}
+
+// HTML: block-level heading/emphasis tags.
+fn surface_profile_html() -> [String] {
+    return surface_profile("html", "text", "text/html", "<h2>", "</h2>", "<em>", "</em>", "<li>", "\n")
+}
+
+// docx: WordprocessingML is structural, not inline-markup; the head/emph slots
+// carry the run/style intent that the OOXML emitter maps to <w:pStyle>. Declared
+// here so docx is a first-class surface on the same seam.
+fn surface_profile_docx() -> [String] {
+    return surface_profile("docx", "text", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "Heading2:", "", "b:", "", "bullet:", "\n")
+}
+
+// -- Built-in NON-TEXT surface profiles (the multimodal seam) ----------------
+
+// Symbolic music (MIDI): modality=audio. The render dispatches to the music
+// projector, which reads the SAME frame's intent/affect and projects it to
+// pitch/rhythm — deterministic-from-meaning. head/emph slots are empty because
+// the medium is not textual; media_type names the surface. A music profile
+// (scale/mode/instrument) is layered onto this by the audio agent, native.
+fn surface_profile_midi() -> [String] {
+    return surface_profile("midi", "audio", "audio/midi", "", "", "", "", "", "")
+}
+
+// Synthesized audio (WAV): modality=audio, peer to midi. The richer audio
+// surface — the render SUPERPOSES ingested tonal primitives (sine at f0*n per an
+// ingested instrument signature) into PCM, own-core, exactly as midi writes an
+// SMF via struct. A music profile (scale/mode/instrument/adsr) layers onto this
+// as its own [String] slot-map read by the same getter. Same frame -> midi OR
+// audio, interchangeable; this is the audio agent's native conforming point.
+fn surface_profile_audio() -> [String] {
+    return surface_profile("audio", "audio", "audio/wav", "", "", "", "", "", "")
+}
+
+// Image (raster): modality=image. Documented seam — the render dispatches to the
+// image projector, the efferent twin of image ingest, reading the same frame.
+fn surface_profile_image() -> [String] {
+    return surface_profile("image", "image", "image/png", "", "", "", "", "", "")
+}
+
+// -- Composition helpers: wrap realized TEXT with the surface's markers -------
+//
+// These take text the EXISTING realizer already produced and shape it for the
+// surface. They add NO content — pure surface typography over faithful text,
+// exactly as the language profile adds no content, only linguistic form.
+
+fn surface_heading(profile: [String], text: String) -> String {
+    let o: String = surface_get(profile, "head_open")
+    let c: String = surface_get(profile, "head_close")
+    return o + text + c
+}
+
+fn surface_emph(profile: [String], text: String) -> String {
+    let o: String = surface_get(profile, "emph_open")
+    let c: String = surface_get(profile, "emph_close")
+    return o + text + c
+}
+
+// A section: a heading + a paragraph separator + the (already realized) body.
+fn surface_section(profile: [String], heading: String, body: String) -> String {
+    let sep: String = surface_get(profile, "para_sep")
+    return surface_heading(profile, heading) + sep + body
+}

elp/tests/examples/surface-profile-demo.el

@@ -0,0 +1,26 @@
+// surface-profile-demo.el - ONE SemFrame, realized ONCE, projected to THREE
+// surfaces via surface profiles. Proves surface-as-profile natively: the frame
+// and the realized sentence are identical; only the surface PROFILE differs.
+
+fn demo() -> String {
+    // 1. The shared frame (meaning-geometry): assert(Neuron, contain, the memory).
+    let frame: [String] = sem_frame("assert", "Neuron", "the memory", "")
+
+    // 2. REALIZE once via the EXISTING native realizer (language = a profile).
+    let sentence: String = sem_realize(frame)
+
+    // 3. PROJECT the same realized sentence onto three surfaces (surface = a
+    //    profile). Same frame, same sentence, different surface — one render.
+    let heading: String = "Memory"
+    let md: String   = surface_section(surface_profile_markdown(), heading, sentence)
+    let html: String = surface_section(surface_profile_html(), heading, sentence)
+    let plain: String = surface_section(surface_profile_plain(), heading, sentence)
+
+    // 4. Report the non-text seam: a surface profile can declare an audio/image
+    //    medium; the render dispatches to the medium projector on the SAME frame.
+    let midi_media: String = surface_get(surface_profile_midi(), "media_type")
+
+    return "MD=[" + md + "] HTML=[" + html + "] PLAIN=[" + plain + "] MIDI_MEDIA=" + midi_media
+}
+
+println(demo())

engram/.gitea/workflows/ci-dev.yaml

@@ -81,7 +81,7 @@ jobs:
       # Link to produce the engram binary
       - name: Link engram binary
         run: |
-          cc -std=c11 -O2 \
+          cc -std=c11 -O2 -DHAVE_CURL \
             -I /usr/local/lib/el \
             -o dist/engram \
             dist/engram.c \

engram/.gitea/workflows/ci-stage.yaml

@@ -88,7 +88,7 @@ jobs:
       # Link to produce the engram binary
       - name: Link engram binary
         run: |
-          cc -std=c11 -O2 \
+          cc -std=c11 -O2 -DHAVE_CURL \
             -I /usr/local/lib/el \
             -o dist/engram \
             dist/engram.c \

engram/.gitea/workflows/engram-release.yaml

@@ -62,7 +62,7 @@ jobs:
       # Link to produce the engram binary
       - name: Link engram binary
         run: |
-          cc -std=c11 -O2 \
+          cc -std=c11 -O2 -DHAVE_CURL \
             -I /usr/local/lib/el \
             -o dist/engram \
             dist/engram.c \

engram/dist/engram.c

@@ -10,8 +10,6 @@ el_val_t query_param(el_val_t path, el_val_t key);
 el_val_t query_int(el_val_t path, el_val_t key, el_val_t default_val);
 el_val_t extract_id(el_val_t path, el_val_t prefix);
 el_val_t route_stats(el_val_t method, el_val_t path, el_val_t body);
-el_val_t route_act_stats(el_val_t method, el_val_t path, el_val_t body);
-el_val_t route_text_health(el_val_t method, el_val_t path, el_val_t body);
 el_val_t persist_canonical(void);
 el_val_t route_create_node(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_get_node(el_val_t method, el_val_t path, el_val_t body);
@@ -20,19 +18,16 @@ el_val_t route_scan_edges(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_search(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_activate(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_create_edge(el_val_t method, el_val_t path, el_val_t body);
-el_val_t route_create_edges_batch(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_neighbors(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_strengthen(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_forget(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_save(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_load(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_health(el_val_t method, el_val_t path, el_val_t body);
-el_val_t route_embed_backfill(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_sync(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_load_merge(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_emit_ise(el_val_t method, el_val_t path, el_val_t body);
 el_val_t route_capture_knowledge(el_val_t method, el_val_t path, el_val_t body);
-el_val_t route_similarity(el_val_t method, el_val_t path, el_val_t body);
 el_val_t check_auth_ok(el_val_t method, el_val_t body);
 el_val_t handle_request(el_val_t method, el_val_t path, el_val_t body);
 
@@ -121,20 +116,11 @@ el_val_t route_stats(el_val_t method, el_val_t path, el_val_t body) {
   return 0;
 }
 
-el_val_t route_act_stats(el_val_t method, el_val_t path, el_val_t body) {
-  return engram_act_stats_json();
-  return 0;
-}
-
-el_val_t route_text_health(el_val_t method, el_val_t path, el_val_t body) {
-  return engram_text_health_json();
-  return 0;
-}
-
 el_val_t persist_canonical(void) {
   el_val_t dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
   el_val_t dir = ({ el_val_t _if_result_1 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_1 = (EL_STR("/tmp/engram")); } else { _if_result_1 = (dir_raw); } _if_result_1; });
-  return engram_save(el_str_concat(dir, EL_STR("/snapshot.json")));
+  engram_save(el_str_concat(dir, EL_STR("/snapshot.json")));
+  return 1;
   return 0;
 }
 
@@ -142,18 +128,9 @@ el_val_t route_create_node(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t content = json_get_string(body, EL_STR("content"));
   el_val_t nt_raw = json_get_string(body, EL_STR("node_type"));
   el_val_t node_type = ({ el_val_t _if_result_2 = 0; if (str_eq(nt_raw, EL_STR(""))) { _if_result_2 = (EL_STR("Memory")); } else { _if_result_2 = (nt_raw); } _if_result_2; });
-  el_val_t sal_present = json_get_raw(body, EL_STR("salience"));
-  el_val_t salience = ({ el_val_t _if_result_3 = 0; if (str_eq(sal_present, EL_STR(""))) { _if_result_3 = (el_from_float(0.5)); } else { _if_result_3 = (json_get_float(body, EL_STR("salience"))); } _if_result_3; });
-  el_val_t label_raw = json_get_string(body, EL_STR("label"));
-  el_val_t label = ({ el_val_t _if_result_4 = 0; if (str_eq(label_raw, EL_STR(""))) { _if_result_4 = (content); } else { _if_result_4 = (label_raw); } _if_result_4; });
-  el_val_t imp_present = json_get_raw(body, EL_STR("importance"));
-  el_val_t importance = ({ el_val_t _if_result_5 = 0; if (str_eq(imp_present, EL_STR(""))) { _if_result_5 = (el_from_float(0.5)); } else { _if_result_5 = (json_get_float(body, EL_STR("importance"))); } _if_result_5; });
-  el_val_t conf_present = json_get_raw(body, EL_STR("confidence"));
-  el_val_t confidence = ({ el_val_t _if_result_6 = 0; if (str_eq(conf_present, EL_STR(""))) { _if_result_6 = (el_from_float(1.0)); } else { _if_result_6 = (json_get_float(body, EL_STR("confidence"))); } _if_result_6; });
-  el_val_t tier_raw = json_get_string(body, EL_STR("tier"));
-  el_val_t tier = ({ el_val_t _if_result_7 = 0; if (str_eq(tier_raw, EL_STR(""))) { _if_result_7 = (EL_STR("Working")); } else { _if_result_7 = (tier_raw); } _if_result_7; });
-  el_val_t tags = json_get_string(body, EL_STR("tags"));
-  el_val_t id = engram_node_full(content, node_type, label, salience, importance, confidence, tier, tags);
+  el_val_t sal_raw = json_get_float(body, EL_STR("salience"));
+  el_val_t salience = ({ el_val_t _if_result_3 = 0; if ((sal_raw == el_from_float(0.0))) { _if_result_3 = (el_from_float(0.5)); } else { _if_result_3 = (sal_raw); } _if_result_3; });
+  el_val_t id = engram_node(content, node_type, salience);
   el_val_t saved = persist_canonical();
   return el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"id\":\""), id), EL_STR("\",\"content\":\"")), content), EL_STR("\",\"node_type\":\"")), node_type), EL_STR("\"}"));
   return 0;
@@ -181,7 +158,7 @@ el_val_t route_scan_nodes(el_val_t method, el_val_t path, el_val_t body) {
 
 el_val_t route_scan_edges(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  el_val_t dir = ({ el_val_t _if_result_8 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_8 = (EL_STR("/tmp/engram")); } else { _if_result_8 = (dir_raw); } _if_result_8; });
+  el_val_t dir = ({ el_val_t _if_result_4 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_4 = (EL_STR("/tmp/engram")); } else { _if_result_4 = (dir_raw); } _if_result_4; });
   el_val_t snap_path = el_str_concat(dir, EL_STR("/.scan-export.json"));
   engram_save(snap_path);
   el_val_t snap = fs_read(snap_path);
@@ -197,22 +174,22 @@ el_val_t route_scan_edges(el_val_t method, el_val_t path, el_val_t body) {
 }
 
 el_val_t route_search(el_val_t method, el_val_t path, el_val_t body) {
-  el_val_t q = ({ el_val_t _if_result_9 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_9 = (query_param(path, EL_STR("q"))); } else { _if_result_9 = (json_get_string(body, EL_STR("query"))); } _if_result_9; });
+  el_val_t q = ({ el_val_t _if_result_5 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_5 = (query_param(path, EL_STR("q"))); } else { _if_result_5 = (json_get_string(body, EL_STR("query"))); } _if_result_5; });
   el_val_t lim_url = query_int(path, EL_STR("limit"), 0);
   el_val_t lim_body = json_get_int(body, EL_STR("limit"));
-  el_val_t lim_either = ({ el_val_t _if_result_10 = 0; if ((lim_url > 0)) { _if_result_10 = (lim_url); } else { _if_result_10 = (lim_body); } _if_result_10; });
-  el_val_t limit = ({ el_val_t _if_result_11 = 0; if ((lim_either > 0)) { _if_result_11 = (lim_either); } else { _if_result_11 = (20); } _if_result_11; });
+  el_val_t lim_either = ({ el_val_t _if_result_6 = 0; if ((lim_url > 0)) { _if_result_6 = (lim_url); } else { _if_result_6 = (lim_body); } _if_result_6; });
+  el_val_t limit = ({ el_val_t _if_result_7 = 0; if ((lim_either > 0)) { _if_result_7 = (lim_either); } else { _if_result_7 = (20); } _if_result_7; });
   return engram_search_json(q, limit);
   return 0;
 }
 
 el_val_t route_activate(el_val_t method, el_val_t path, el_val_t body) {
-  el_val_t q = ({ el_val_t _if_result_12 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_12 = (query_param(path, EL_STR("q"))); } else { _if_result_12 = (json_get_string(body, EL_STR("query"))); } _if_result_12; });
+  el_val_t q = ({ el_val_t _if_result_8 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_8 = (query_param(path, EL_STR("q"))); } else { _if_result_8 = (json_get_string(body, EL_STR("query"))); } _if_result_8; });
   if (str_eq(q, EL_STR(""))) {
     return err_json(EL_STR("missing query"));
   }
-  el_val_t d_raw = ({ el_val_t _if_result_13 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_13 = (query_int(path, EL_STR("depth"), 3)); } else { _if_result_13 = (json_get_int(body, EL_STR("depth"))); } _if_result_13; });
-  el_val_t depth = ({ el_val_t _if_result_14 = 0; if ((d_raw > 0)) { _if_result_14 = (d_raw); } else { _if_result_14 = (3); } _if_result_14; });
+  el_val_t d_raw = ({ el_val_t _if_result_9 = 0; if (str_eq(method, EL_STR("GET"))) { _if_result_9 = (query_int(path, EL_STR("depth"), 3)); } else { _if_result_9 = (json_get_int(body, EL_STR("depth"))); } _if_result_9; });
+  el_val_t depth = ({ el_val_t _if_result_10 = 0; if ((d_raw > 0)) { _if_result_10 = (d_raw); } else { _if_result_10 = (3); } _if_result_10; });
   return el_str_concat(el_str_concat(EL_STR("{\"results\":"), engram_activate_json(q, depth)), EL_STR("}"));
   return 0;
 }
@@ -221,50 +198,15 @@ el_val_t route_create_edge(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t from_id = json_get_string(body, EL_STR("from_id"));
   el_val_t to_id = json_get_string(body, EL_STR("to_id"));
   el_val_t rel_raw = json_get_string(body, EL_STR("relation"));
-  el_val_t relation = ({ el_val_t _if_result_15 = 0; if (str_eq(rel_raw, EL_STR(""))) { _if_result_15 = (EL_STR("associates")); } else { _if_result_15 = (rel_raw); } _if_result_15; });
-  el_val_t w_present = json_get_raw(body, EL_STR("weight"));
-  el_val_t weight = ({ el_val_t _if_result_16 = 0; if (str_eq(w_present, EL_STR(""))) { _if_result_16 = (el_from_float(0.5)); } else { _if_result_16 = (json_get_float(body, EL_STR("weight"))); } _if_result_16; });
+  el_val_t relation = ({ el_val_t _if_result_11 = 0; if (str_eq(rel_raw, EL_STR(""))) { _if_result_11 = (EL_STR("associates")); } else { _if_result_11 = (rel_raw); } _if_result_11; });
+  el_val_t w_raw = json_get_float(body, EL_STR("weight"));
+  el_val_t weight = ({ el_val_t _if_result_12 = 0; if ((w_raw == el_from_float(0.0))) { _if_result_12 = (el_from_float(0.5)); } else { _if_result_12 = (w_raw); } _if_result_12; });
   engram_connect(from_id, to_id, weight, relation);
   el_val_t saved = persist_canonical();
   return el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"ok\":true,\"from_id\":\""), from_id), EL_STR("\",\"to_id\":\"")), to_id), EL_STR("\",\"relation\":\"")), relation), EL_STR("\"}"));
   return 0;
 }
 
-el_val_t route_create_edges_batch(el_val_t method, el_val_t path, el_val_t body) {
-  el_val_t arr = json_get_raw(body, EL_STR("edges"));
-  if (str_eq(arr, EL_STR(""))) {
-    return err_json(EL_STR("missing edges array"));
-  }
-  el_val_t n = json_array_len(arr);
-  if (n == 0) {
-    return EL_STR("{\"ok\":true,\"accepted\":0,\"skipped\":0}");
-  }
-  el_val_t i = 0;
-  el_val_t accepted = 0;
-  el_val_t skipped = 0;
-  while (i < n) {
-    el_val_t item = json_array_get(arr, i);
-    el_val_t from_id = json_get_string(item, EL_STR("from_id"));
-    el_val_t to_id = json_get_string(item, EL_STR("to_id"));
-    if (str_eq(from_id, EL_STR("")) || str_eq(to_id, EL_STR(""))) {
-      skipped = (skipped + 1);
-    } else {
-      el_val_t rel_raw = json_get_string(item, EL_STR("relation"));
-      el_val_t relation = ({ el_val_t _if_result_17 = 0; if (str_eq(rel_raw, EL_STR(""))) { _if_result_17 = (EL_STR("associates")); } else { _if_result_17 = (rel_raw); } _if_result_17; });
-      el_val_t w_present = json_get_raw(item, EL_STR("weight"));
-      el_val_t weight = ({ el_val_t _if_result_18 = 0; if (str_eq(w_present, EL_STR(""))) { _if_result_18 = (el_from_float(0.5)); } else { _if_result_18 = (json_get_float(item, EL_STR("weight"))); } _if_result_18; });
-      engram_connect(from_id, to_id, weight, relation);
-      accepted = (accepted + 1);
-    }
-    i = (i + 1);
-  }
-  if (accepted > 0) {
-    el_val_t saved = persist_canonical();
-  }
-  return el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"ok\":true,\"accepted\":"), int_to_str(accepted)), EL_STR(",\"skipped\":")), int_to_str(skipped)), EL_STR("}"));
-  return 0;
-}
-
 el_val_t route_neighbors(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t id = extract_id(path, EL_STR("/api/neighbors/"));
   if (str_eq(id, EL_STR(""))) {
@@ -300,51 +242,36 @@ el_val_t route_forget(el_val_t method, el_val_t path, el_val_t body) {
 el_val_t route_save(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t p_raw = json_get_string(body, EL_STR("path"));
   el_val_t dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  el_val_t dir = ({ el_val_t _if_result_19 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_19 = (EL_STR("/tmp/engram")); } else { _if_result_19 = (dir_raw); } _if_result_19; });
-  el_val_t p = ({ el_val_t _if_result_20 = 0; if (str_eq(p_raw, EL_STR(""))) { _if_result_20 = (el_str_concat(dir, EL_STR("/snapshot.json"))); } else { _if_result_20 = (p_raw); } _if_result_20; });
-  el_val_t sv = engram_save(p);
-  el_val_t sv_ok = ({ el_val_t _if_result_21 = 0; if ((sv == 0)) { _if_result_21 = (EL_STR("false")); } else { _if_result_21 = (EL_STR("true")); } _if_result_21; });
-  return el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"ok\":"), sv_ok), EL_STR(",\"path\":\"")), p), EL_STR("\",\"node_count\":")), int_to_str(engram_node_count())), EL_STR(",\"edge_count\":")), int_to_str(engram_edge_count())), EL_STR("}"));
+  el_val_t dir = ({ el_val_t _if_result_13 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_13 = (EL_STR("/tmp/engram")); } else { _if_result_13 = (dir_raw); } _if_result_13; });
+  el_val_t p = ({ el_val_t _if_result_14 = 0; if (str_eq(p_raw, EL_STR(""))) { _if_result_14 = (el_str_concat(dir, EL_STR("/snapshot.json"))); } else { _if_result_14 = (p_raw); } _if_result_14; });
+  engram_save(p);
+  return el_str_concat(el_str_concat(EL_STR("{\"ok\":true,\"path\":\""), p), EL_STR("\"}"));
   return 0;
 }
 
 el_val_t route_load(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t p_raw = json_get_string(body, EL_STR("path"));
   el_val_t dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  el_val_t dir = ({ el_val_t _if_result_22 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_22 = (EL_STR("/tmp/engram")); } else { _if_result_22 = (dir_raw); } _if_result_22; });
-  el_val_t p = ({ el_val_t _if_result_23 = 0; if (str_eq(p_raw, EL_STR(""))) { _if_result_23 = (el_str_concat(dir, EL_STR("/snapshot.json"))); } else { _if_result_23 = (p_raw); } _if_result_23; });
-  el_val_t ld = engram_load(p);
-  el_val_t ld_ok = ({ el_val_t _if_result_24 = 0; if ((ld == 0)) { _if_result_24 = (EL_STR("false")); } else { _if_result_24 = (EL_STR("true")); } _if_result_24; });
-  el_val_t nc_after = engram_node_count();
-  el_val_t hollow = ({ el_val_t _if_result_25 = 0; if ((nc_after == 0)) { _if_result_25 = (EL_STR("true")); } else { _if_result_25 = (EL_STR("false")); } _if_result_25; });
-  return el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"ok\":"), ld_ok), EL_STR(",\"path\":\"")), p), EL_STR("\",\"node_count\":")), int_to_str(nc_after)), EL_STR(",\"edge_count\":")), int_to_str(engram_edge_count())), EL_STR(",\"hollow\":")), hollow), EL_STR("}"));
+  el_val_t dir = ({ el_val_t _if_result_15 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_15 = (EL_STR("/tmp/engram")); } else { _if_result_15 = (dir_raw); } _if_result_15; });
+  el_val_t p = ({ el_val_t _if_result_16 = 0; if (str_eq(p_raw, EL_STR(""))) { _if_result_16 = (el_str_concat(dir, EL_STR("/snapshot.json"))); } else { _if_result_16 = (p_raw); } _if_result_16; });
+  engram_load(p);
+  return ok_json();
   return 0;
 }
 
 el_val_t route_health(el_val_t method, el_val_t path, el_val_t body) {
-  return el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"status\":\"ok\",\"engine\":\"engram-runtime-native\",\"node_count\":"), int_to_str(engram_node_count())), EL_STR(",\"edge_count\":")), int_to_str(engram_edge_count())), EL_STR("}"));
-  return 0;
-}
-
-el_val_t route_embed_backfill(el_val_t method, el_val_t path, el_val_t body) {
-  el_val_t n = query_int(path, EL_STR("n"), 32);
-  el_val_t result = engram_embed_backfill(n);
-  el_val_t done = json_get_float(result, EL_STR("embedded"));
-  if (done > el_from_float(0.0)) {
-    el_val_t saved = persist_canonical();
-  }
-  return result;
+  return EL_STR("{\"status\":\"ok\",\"engine\":\"engram-runtime-native\"}");
   return 0;
 }
 
 el_val_t route_sync(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  el_val_t dir = ({ el_val_t _if_result_26 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_26 = (EL_STR("/tmp/engram")); } else { _if_result_26 = (dir_raw); } _if_result_26; });
+  el_val_t dir = ({ el_val_t _if_result_17 = 0; if (str_eq(dir_raw, EL_STR(""))) { _if_result_17 = (EL_STR("/tmp/engram")); } else { _if_result_17 = (dir_raw); } _if_result_17; });
   el_val_t snap_path = el_str_concat(dir, EL_STR("/.sync-export.json"));
   engram_save(snap_path);
   el_val_t snap = fs_read(snap_path);
   if (str_eq(snap, EL_STR(""))) {
-    return err_json(EL_STR("sync export failed: snapshot unreadable"));
+    return EL_STR("{\"nodes\":[],\"edges\":[]}");
   }
   return snap;
   return 0;
@@ -378,7 +305,7 @@ el_val_t route_emit_ise(el_val_t method, el_val_t path, el_val_t body) {
   el_val_t conf = el_from_float(0.8);
   el_val_t id = engram_node_full(content, EL_STR("InternalStateEvent"), EL_STR("state-event"), sal, imp, conf, EL_STR("Episodic"), EL_STR("[\"internal-state\",\"InternalStateEvent\"]"));
   el_val_t ret_raw = env(EL_STR("ENGRAM_ISE_RETENTION_MS"));
-  el_val_t ret_ms = ({ el_val_t _if_result_27 = 0; if (str_eq(ret_raw, EL_STR(""))) { _if_result_27 = (172800000); } else { _if_result_27 = (str_to_int(ret_raw)); } _if_result_27; });
+  el_val_t ret_ms = ({ el_val_t _if_result_18 = 0; if (str_eq(ret_raw, EL_STR(""))) { _if_result_18 = (172800000); } else { _if_result_18 = (str_to_int(ret_raw)); } _if_result_18; });
   el_val_t pruned = engram_prune_telemetry(ret_ms);
   return el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"ok\":true,\"id\":\""), id), EL_STR("\",\"pruned\":")), int_to_str(pruned)), EL_STR("}"));
   return 0;
@@ -390,21 +317,21 @@ el_val_t route_capture_knowledge(el_val_t method, el_val_t path, el_val_t body)
     return err_json(EL_STR("missing content"));
   }
   el_val_t title = json_get_string(body, EL_STR("title"));
-  el_val_t label = ({ el_val_t _if_result_28 = 0; if (str_eq(title, EL_STR(""))) { _if_result_28 = (str_slice(content, 0, 60)); } else { _if_result_28 = (title); } _if_result_28; });
+  el_val_t label = ({ el_val_t _if_result_19 = 0; if (str_eq(title, EL_STR(""))) { _if_result_19 = (str_slice(content, 0, 60)); } else { _if_result_19 = (title); } _if_result_19; });
   el_val_t category_raw = json_get_string(body, EL_STR("category"));
-  el_val_t category = ({ el_val_t _if_result_29 = 0; if (str_eq(category_raw, EL_STR(""))) { _if_result_29 = (EL_STR("other")); } else { _if_result_29 = (category_raw); } _if_result_29; });
+  el_val_t category = ({ el_val_t _if_result_20 = 0; if (str_eq(category_raw, EL_STR(""))) { _if_result_20 = (EL_STR("other")); } else { _if_result_20 = (category_raw); } _if_result_20; });
   el_val_t ktier_raw = json_get_string(body, EL_STR("tier"));
-  el_val_t ktier = ({ el_val_t _if_result_30 = 0; if (str_eq(ktier_raw, EL_STR(""))) { _if_result_30 = (EL_STR("note")); } else { _if_result_30 = (ktier_raw); } _if_result_30; });
+  el_val_t ktier = ({ el_val_t _if_result_21 = 0; if (str_eq(ktier_raw, EL_STR(""))) { _if_result_21 = (EL_STR("note")); } else { _if_result_21 = (ktier_raw); } _if_result_21; });
   el_val_t project = json_get_string(body, EL_STR("project"));
   el_val_t tags_raw = json_get_raw(body, EL_STR("tags"));
-  el_val_t tags_base = ({ el_val_t _if_result_31 = 0; if (str_eq(tags_raw, EL_STR(""))) { _if_result_31 = (EL_STR("[]")); } else { _if_result_31 = (tags_raw); } _if_result_31; });
+  el_val_t tags_base = ({ el_val_t _if_result_22 = 0; if (str_eq(tags_raw, EL_STR(""))) { _if_result_22 = (EL_STR("[]")); } else { _if_result_22 = (tags_raw); } _if_result_22; });
   el_val_t base_len = str_len(tags_base);
   el_val_t head = str_slice(tags_base, 0, (base_len - 1));
-  el_val_t sep = ({ el_val_t _if_result_32 = 0; if (str_eq(head, EL_STR("["))) { _if_result_32 = (EL_STR("")); } else { _if_result_32 = (EL_STR(",")); } _if_result_32; });
+  el_val_t sep = ({ el_val_t _if_result_23 = 0; if (str_eq(head, EL_STR("["))) { _if_result_23 = (EL_STR("")); } else { _if_result_23 = (EL_STR(",")); } _if_result_23; });
   el_val_t safe_cat = str_replace(category, EL_STR("\""), EL_STR("'"));
   el_val_t safe_tier = str_replace(ktier, EL_STR("\""), EL_STR("'"));
   el_val_t safe_proj = str_replace(project, EL_STR("\""), EL_STR("'"));
-  el_val_t proj_tag = ({ el_val_t _if_result_33 = 0; if (str_eq(safe_proj, EL_STR(""))) { _if_result_33 = (EL_STR("")); } else { _if_result_33 = (el_str_concat(el_str_concat(EL_STR(",\"project:"), safe_proj), EL_STR("\""))); } _if_result_33; });
+  el_val_t proj_tag = ({ el_val_t _if_result_24 = 0; if (str_eq(safe_proj, EL_STR(""))) { _if_result_24 = (EL_STR("")); } else { _if_result_24 = (el_str_concat(el_str_concat(EL_STR(",\"project:"), safe_proj), EL_STR("\""))); } _if_result_24; });
   el_val_t tags = el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(head, sep), EL_STR("\"category:")), safe_cat), EL_STR("\",\"tier:")), safe_tier), EL_STR("\"")), proj_tag), EL_STR("]"));
   el_val_t sal = el_from_float(0.5);
   el_val_t imp = el_from_float(0.5);
@@ -415,20 +342,6 @@ el_val_t route_capture_knowledge(el_val_t method, el_val_t path, el_val_t body)
   return 0;
 }
 
-el_val_t route_similarity(el_val_t method, el_val_t path, el_val_t body) {
-  el_val_t a = query_param(path, EL_STR("a"));
-  el_val_t b = query_param(path, EL_STR("b"));
-  if (str_eq(a, EL_STR(""))) {
-    return err_json(EL_STR("missing a"));
-  }
-  if (str_eq(b, EL_STR(""))) {
-    return err_json(EL_STR("missing b"));
-  }
-  el_val_t sim = engram_cosine_sim(a, b);
-  return el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("{\"a\":\""), a), EL_STR("\",\"b\":\"")), b), EL_STR("\",\"cosine\":")), float_to_str(sim)), EL_STR("}"));
-  return 0;
-}
-
 el_val_t check_auth_ok(el_val_t method, el_val_t body) {
   el_val_t key = env(EL_STR("ENGRAM_API_KEY"));
   if (str_eq(key, EL_STR(""))) {
@@ -464,12 +377,6 @@ el_val_t handle_request(el_val_t method, el_val_t path, el_val_t body) {
   if (str_eq(method, EL_STR("GET")) && (str_eq(clean, EL_STR("/api/stats")) || str_eq(clean, EL_STR("/stats")))) {
     return route_stats(method, path, body);
   }
-  if (str_eq(method, EL_STR("GET")) && (str_eq(clean, EL_STR("/api/act-stats")) || str_eq(clean, EL_STR("/act-stats")))) {
-    return route_act_stats(method, path, body);
-  }
-  if (str_eq(method, EL_STR("GET")) && (str_eq(clean, EL_STR("/api/text-health")) || str_eq(clean, EL_STR("/text-health")))) {
-    return route_text_health(method, path, body);
-  }
   if (str_eq(method, EL_STR("POST")) && (str_eq(clean, EL_STR("/api/nodes")) || str_eq(clean, EL_STR("/nodes")))) {
     return route_create_node(method, path, body);
   }
@@ -488,9 +395,6 @@ el_val_t handle_request(el_val_t method, el_val_t path, el_val_t body) {
   if (str_eq(method, EL_STR("POST")) && (str_eq(clean, EL_STR("/api/edges")) || str_eq(clean, EL_STR("/edges")))) {
     return route_create_edge(method, path, body);
   }
-  if (str_eq(method, EL_STR("POST")) && (str_eq(clean, EL_STR("/api/edges/batch")) || str_eq(clean, EL_STR("/edges/batch")))) {
-    return route_create_edges_batch(method, path, body);
-  }
   if (str_eq(method, EL_STR("GET")) && str_starts_with(clean, EL_STR("/api/neighbors/"))) {
     return route_neighbors(method, path, body);
   }
@@ -521,12 +425,6 @@ el_val_t handle_request(el_val_t method, el_val_t path, el_val_t body) {
   if (str_eq(method, EL_STR("GET")) && str_eq(clean, EL_STR("/api/sync"))) {
     return route_sync(method, path, body);
   }
-  if (str_eq(clean, EL_STR("/api/embed-backfill"))) {
-    return route_embed_backfill(method, path, body);
-  }
-  if (str_eq(method, EL_STR("GET")) && str_starts_with(clean, EL_STR("/api/similarity"))) {
-    return route_similarity(method, path, body);
-  }
   return el_str_concat(el_str_concat(EL_STR("{\"error\":\"not found\",\"path\":\""), clean), EL_STR("\"}"));
   return 0;
 }
@@ -534,10 +432,10 @@ el_val_t handle_request(el_val_t method, el_val_t path, el_val_t body) {
 int main(int _argc, char** _argv) {
   el_runtime_init_args(_argc, _argv);
   bind_raw = env(EL_STR("ENGRAM_BIND"));
-  bind_str = ({ el_val_t _if_result_34 = 0; if (str_eq(bind_raw, EL_STR(""))) { _if_result_34 = (EL_STR(":8742")); } else { _if_result_34 = (bind_raw); } _if_result_34; });
+  bind_str = ({ el_val_t _if_result_25 = 0; if (str_eq(bind_raw, EL_STR(""))) { _if_result_25 = (EL_STR(":8742")); } else { _if_result_25 = (bind_raw); } _if_result_25; });
   port = parse_port(bind_str);
   data_dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  data_dir = ({ el_val_t _if_result_35 = 0; if (str_eq(data_dir_raw, EL_STR(""))) { _if_result_35 = (EL_STR("/tmp/engram")); } else { _if_result_35 = (data_dir_raw); } _if_result_35; });
+  data_dir = ({ el_val_t _if_result_26 = 0; if (str_eq(data_dir_raw, EL_STR(""))) { _if_result_26 = (EL_STR("/tmp/engram")); } else { _if_result_26 = (data_dir_raw); } _if_result_26; });
   snapshot_path = el_str_concat(data_dir, EL_STR("/snapshot.json"));
   engram_load(snapshot_path);
   boot_snap = fs_read(snapshot_path);

engram/spec/architecture-hardening.design.md

@@ -1,32 +0,0 @@
-# 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.

engram/spec/cognitive-architecture.design.md

@@ -1,605 +0,0 @@
-# Cognitive Architecture — Design Doc
-
-**The buildable form of the "one operation" theory of cognition.**
-
-Status: DESIGN. Nothing here is built yet except where explicitly marked
-"EXISTS" against a cited C symbol. A build agent executes from this doc.
-Offline design only — this pass changes no code.
-
-Source of theory: Neuron memory `bdc8a488-146d-4ccb-a5c8-d8c0a008534e`.
-Source of existing engram substrate (cited throughout): the runtime on branch
-`feat/self-reification-20260814` —
-`lang/runtime/engram_reason.{c,h}`, `engram_verify.{c,h}`,
-`engram_geometry.{c,h}`, `engram_store.{c,h}`, plus the reification beat and the
-RAM activation graph compiled into `~/.neuron/bin/engram`.
-
----
-
-## 0. The claim, stated plainly
-
-Cognition is **one operation**, not eight. The named faculties —
-deduce / abduce / analogy / induce / causal / plan / predict / perspective —
-are human *labels* on regions of a single operation's steering space. They are
-not separately invoked and not separately implemented. The operation is:
-
-> **think** = a directed traversal of the geometry from an *anchor*, steered by
-> a *prior*, whose output is a **gradient** (a distribution / direction over the
-> geometry), never a point. Collapse-to-a-point happens only at expression.
-
-Three things follow, and they are the whole design:
-
-1. **The operator collapse is already half-written in C.** The five reasoning
-   operators in `engram_reason.c` already compose over *one* shared primitive —
-   `engram_reason_point_fit` — plus a small geo-algebra
-   (combine / subtract / analogy-rotate / distance). The verifier
-   (`engram_verify.c`) is built on the same `point_fit`. What is missing is not
-   the primitive; it is (a) making the *prior* a first-class learnable object
-   instead of a hard-coded parameter, and (b) closing the learning loop.
-
-2. **Grounding = learning = the same loop.** "Getting better" at any faculty is
-   not changing the operation. It is *calibrating the steering-prior against
-   outcomes*. Code freezes; priors grow. The correspondence-check that today
-   lives offline (Python, the grounding-floor + differential-drop governor, "#43")
-   must move **into the geometry, reflexive** — think scoring its own gradient
-   against outcome and refining the prior on the error. That reflexive
-   correspondence-loop *is* the learning engine and is the core unbuilt thing.
-
-3. **The ungrounded is primary.** The engram *holds* anything unconditionally.
-   Grounding is a *relation* (an edge, grounded-for-whom), not a gate. The
-   honesty floor applies only to **assertion**. A fully-grounded mind is dead;
-   the ungrounded is both the fuel (raw material for grounding) and the pull
-   (curiosity = leaning toward one's own ungrounded regions).
-
-Everything below makes these concrete and buildable, and defines what
-"completion" means, staged so the first milestone is a real end-to-end slice.
-
----
-
-## 1. THE ONE OPERATION — `think`
-
-### 1.1 Signature
-
-```
-think(anchor, prior, aperture?) -> gradient
-```
-
-- **anchor** — a location to traverse *from*. Either a node id (re-origin on that
-  node's descriptor) or a raw point `x ∈ R^dim` (a query embedding). The anchor
-  fixes the frame; every read is *from a vantage*, never view-from-nowhere.
-- **prior** — a learnable bias/direction over the geometry that *steers* the
-  traversal (§2). A prior is a first-class stored object, not a call argument
-  baked into C.
-- **aperture** — optional read-width / veil / field-selector (§3). Absent =
-  self-mode full aperture.
-- **gradient** — the output. A `GeoGradient`: a direction + a spread over the
-  geometry, *plus* the read neighborhood it was computed against. Not a point.
-  A spiked gradient = "exact" (deduction); a spread gradient = "fuzzy"
-  (prediction). The gradient is *also the next steering direction* — cognition
-  is a flow down a prior-shaped landscape, closed-loop.
-
-```c
-/* NEW. The output type. */
-typedef struct {
-    int      dim;
-    float*   direction;     /* unit steering vector in the anchor's frame  */
-    double   spread;        /* 0 = spiked/exact ... large = diffuse/fuzzy   */
-    double   confidence;    /* calibrated, from the prior's track record    */
-    /* the read it was computed over (borrowed from the vantage-read) */
-    const char* anchor_id;
-    int      n_support;     /* neighborhood members that shaped it          */
-    /* provenance for the reflexive loop (§4) */
-    const char* prior_id;   /* which prior steered this                     */
-} GeoGradient;
-```
-
-### 1.2 Semantics
-
-`think` is a fixed, frozen procedure over three steps:
-
-1. **Re-origin** on `anchor` → a centered `GeoDescriptor` for its
-   salience/recency-weighted neighborhood (the vantage-read, §3).
-   *EXISTS as substrate:* descriptor construction + the persisted reified
-   neighborhoods (`engram_geo_reify_lookup`, `GeoNeighborhood`) and the
-   centered-frame machinery (`GeoDescriptor.global_mean`,
-   `engram_geo_mean_*`).
-2. **Fit under the prior** — evaluate the anchor's residual against the local
-   manifold *warped by the prior*. This is `engram_reason_point_fit` with the
-   prior applied to the axes/extents (§2.3).
-   *EXISTS (unwarped):* `engram_reason_point_fit(g, x, ext_floor, &GeoFit)` —
-   returns `mahalanobis`, `ortho_residual`, `distance`, `score`.
-3. **Emit a gradient**, not a decision — direction = the prior-steered descent
-   in fit-space; spread = from the fit's `distance`/`ortho_residual`;
-   confidence = the prior's calibrated reliability (§4). Collapse to a point is
-   a *separate, downstream* faculty operation (sample the gradient → surface an
-   expression), never part of `think`.
-
-### 1.3 Each named operator = {this primitive + a prior}
-
-The C already demonstrates the collapse: every operator below reduces to
-`point_fit` + geo-algebra. The design's move is to replace the operator's
-*hard-coded parameters* with a **named prior** — same math, learnable steering.
-
-| Faculty | Existing C (EXISTS) | = primitive + prior |
-|---|---|---|
-| **Membership / classify** | `engram_reason_membership` → `point_fit(rule, x)` | `point_fit` + the *induced-rule* prior (learned extents) |
-| **Induction** | `engram_reason_induce` (fold via `engram_geo_combine`) → produces a `GeoInduction.rule` + `ext_floor` | `point_fit` + a prior that *is* the pooled rule; refined by §4 |
-| **Abduction** | `engram_reason_abduce` — ranks hypotheses by `point_fit(h, obs)` | `point_fit` + a prior over hypothesis-prior-probability (currently uniform) |
-| **Analogy** | `engram_reason_analogy` — Procrustes rotate `engram_geo_analogy` + `apply`, nearest mapped point | analogy-rotate + a prior over *which axes* carry the mapping |
-| **Causal** | `engram_reason_causal` — `engram_geo_subtract` confounder subspace, `|cos|`, drop-frac governor | subtract/distance + a prior on `drop_frac` / `assoc_floor` (today hard-coded 0.5 / 0.2) |
-| **Planning** | `engram_reason_plan` — `engram_geo_distance` edges + Dijkstra | distance + a prior over edge admissibility / `neighbor_radius` |
-| **Verify / ground** | `engram_verify_grounding`, `engram_verify_consistency` — both `point_fit` | `point_fit` + the *grounding* prior (§4, §5) |
-
-The shared floor — `engram_reason_point_fit` + the four geo-algebra ops
-(`engram_geo_combine`, `engram_geo_subtract`, `engram_geo_analogy(+apply)`,
-`engram_geo_distance`) — is the *only* discrete, frozen, "sound-math" layer. It
-never learns. Everything above it is a *prior*, and priors are what learn.
-
-**What this section requires building:** the `GeoGradient` type; a `think()`
-entry point that runs steps 1–3; and the prior-warp hook in step 2. The math it
-calls already exists. The point-collapse must be *removed* from the operators'
-return values and pushed to a separate expression faculty.
-
----
-
-## 2. PRIORS as first-class, grounded, geometric objects
-
-Today a "prior" is diffuse: it is a hard-coded constant (`drop_frac=0.5`,
-`ext_floor`, `assoc_floor=0.2`), or the transient `GeoInduction.rule` that is
-computed and thrown away, or an intrinsic node scalar
-(`StoreNode.importance`, `StoreNode.salience`). None of these is addressable,
-storable, refinable, or shareable. This section makes a prior a **thing**.
-
-### 2.1 What a prior *is*
-
-> A **prior** is a learnable bias/direction over the geometry: a warp of the
-> local manifold (which axes matter, how far each extends, which direction
-> "pays off") attached to a region and *to a faculty-label*, carrying a
-> calibrated track record.
-
-Critically, and per the theory:
-
-- **Edges are nodes.** A prior is stored as a first-class **node**, exactly as
-  reification already stores a neighborhood as a first-class `Neighborhood`
-  node rather than as ephemeral edge weights (`engram_geo_reify_store`). The
-  precedent is in the codebase: relations get reified into addressable records.
-- **Salience/importance is RELATIONAL, not an intrinsic scalar.** Observe that
-  the geometry layer *already* distinguishes these in `GeoMember`:
-  `centrality` (skeleton weighted-degree = *relational* salience) vs `salience`
-  (the node's own stored scalar). The move is half-made in the runtime already:
-  importance is *not* trusted as a static field — the comment at
-  `el_runtime.c:13013` states "importance stays a **live activation
-  computation**, never a field on the hub," and it is derived each call from the
-  two-layer activation graph (`background_activation` + `working_memory_weight`,
-  §3). The persistent `StoreNode.importance` / `.salience` are a *cached
-  denormalization*. The design completes the move: importance/salience become an
-  **edge** (`weight`/`hebb` on `StoreEdge`, relation `salient-to`), and are
-  **grounded-for-whom** — carried on the edge's endpoint/observer, not baked
-  into the node. The intrinsic scalar survives only as the cheap cached readout
-  of the incident edges + activation, never as the source of truth.
-
-  (Naming caution for the build: the token "prior" already exists in the
-  codebase meaning *previous-version* — supersession, "prior neighborhood." The
-  new first-class object is a **learned steering prior**; keep `node_type="Prior"`
-  distinct from the supersession vocabulary to avoid collision.)
-
-### 2.2 Representation
-
-A prior is a `Prior` record (a store node, `node_type="Prior"`) whose durable
-fields are:
-
-```
-Prior {
-  id
-  faculty         // the human label this prior serves: "induce" | "causal" | ...
-  anchor_region   // node id / neighborhood id this prior is attached to (its domain)
-  for_whom        // observer id — grounding is relational (nullable = global)
-  warp {          // the actual bias over the geometry
-     axis_gain[]  // per-principal-axis multipliers on extents (which axes matter)
-     bias_dir     // a steering direction in the region's frame (which way pays off)
-     scalars      // faculty scalars this prior overrides: drop_frac, ext_floor, ...
-  }
-  calibration {   // the track record — this is what §4 updates
-     n_trials
-     brier / log-loss accumulator   // calibration of predicted-vs-outcome
-     reliability                    // -> GeoGradient.confidence
-     last_error, ema_error
-  }
-  provenance      // supersession chain (reuse the reify residue mechanism)
-}
-```
-
-Stored as a node → it inherits: paging, WAL durability, tombstone/supersession,
-embedding, tiering, and **it can itself be an anchor** (a prior about a prior —
-the reflexive, self-describing geometry of §4/§6).
-
-### 2.3 Application
-
-In `think` step 2, the prior *warps* the fit before scoring. Concretely, inside
-(a prior-aware wrapper of) `engram_reason_point_fit`:
-
-- multiply each axis extent by `warp.axis_gain[k]` (widen the axes the prior has
-  learned matter less, tighten the ones that matter) — this reshapes the
-  Mahalanobis term already computed at `engram_reason.c:37-43`;
-- add `warp.bias_dir` as the descent direction seed for the emitted gradient;
-- substitute `warp.scalars` for the hard-coded faculty constants.
-
-No new geometry math — the warp is a reparameterization of the *existing*
-`GeoFit` computation. This is the key economy: **the operation is frozen; only
-its parameters (the prior) are read from a learnable object.**
-
-### 2.4 Refinement
-
-A prior is refined *only* by the reflexive correspondence-loop (§4). Nothing
-else writes a prior's `warp` or `calibration`. This keeps the learning surface
-singular and auditable: one loop, one writer.
-
----
-
-## 3. THE VANTAGE-READ — one op, three settings
-
-Perspective is not a feature bolted on; it is the *anchor + aperture* arguments
-of the single read. The design names it as a first-class operation so all three
-of its uses are literally the same code path:
-
-```
-vantage_read(anchor, aperture) -> GeoDescriptor   // the centered neighborhood
-```
-
-1. **Re-origin** on an arbitrary `anchor` (node or point). This is a *frame
-   choice*: the descriptor is centered on the anchor
-   (`GeoDescriptor.global_mean` / `engram_geo_mean_*` already implement centered
-   frames; the §5 geometry ops "are only discriminative in the centered frame").
-2. **Salience/recency-weighted neighborhood read.** Gather the anchor's
-   neighborhood weighted by *relational* salience (`GeoMember.centrality`) and
-   recency (`StoreNode.last_activated`, base-level `access_ts[]`), against the
-   RAM activation graph's working-memory/background-activation state.
-   *EXISTS as substrate:* the two-layer activation graph
-   (`engram_activate`, `el_runtime.c:9422` — Layer 1 `background_activation`
-   BFS spread with `SPREAD_DECAY=0.7` and a 0.02 firing threshold + ACT-R fan
-   effect + query-cosine gate; Layer 2 `working_memory_weight` executive
-   filter), the WM carry-over anchor (`wm_anchor`), and the reified-neighborhood
-   hot-path lookup already wired into the priming path
-   (`engram_geo_reify_lookup`, `el_runtime.c:9750`). A self-vantage baseline
-   also exists (`eg_self_anchor_seeds` / `self_anchor_capture`).
-3. **Optional aperture** — a read-width / field-selector, expressed as three
-   settings of the *same* parameter:
-
-| Setting | Meaning | Mechanism |
-|---|---|---|
-| **self** (default, full aperture) | "what do *I* see / what to say" | anchor = self region, no field substitution |
-| **foreign-field** | perspective-shift — read as if from another's region | swap the centering frame / `for_whom` to the other observer's priors |
-| **aperture / veil** | the free-tier veil — a narrowed read | shrink neighborhood radius / cap `n_support`; a deliberate low-aperture read |
-
-The payoff: perspective-taking, the free-tier veil, and ordinary
-"what-to-say" are **one operation at three settings**, not three subsystems.
-
-**What this requires building:** a `vantage_read` entry point that unifies the
-existing descriptor-build + reify-lookup + activation-weighting behind
-`(anchor, aperture)`, with `for_whom`/frame substitution and radius/cap as the
-aperture knob.
-
----
-
-## 4. THE REFLEXIVE CORRESPONDENCE-LOOP — the learning engine
-
-This is the core unbuilt thing. Today the correspondence-check is **offline**
-(Python: grounding-floor + differential-drop governor, "#43"): a separate
-process grades outputs after the fact. The design moves it **into the geometry,
-reflexive**: `think` scores its *own* gradient against outcome and refines the
-prior on the error, in the same substrate, describing itself.
-
-### 4.1 The loop
-
-```
-1. think(anchor, prior) -> gradient          // a PREDICTION (ungrounded, §5)
-2. express/act (sample gradient -> point)    // optional collapse at expression
-3. outcome arrives                            // reality answers (§4.2)
-4. error = correspondence(gradient, outcome)  // did this steering perform this act?
-5. refine prior.warp and prior.calibration on error   // §2.4, the ONLY writer
-6. write the (gradient, outcome, error) as nodes/edges // self-describing geometry
-```
-
-Step 4's `correspondence` is **not** "was the math right" (the math is always
-sound). It grades the **correspondence claim**: *"this steering performed this
-cognitive act."* That is exactly what `engram_verify_grounding` already
-computes — `point_fit` of a claim against evidence descriptors, yielding a
-`grounding ∈ (0,1]` and a `grounded` flag. The build reuses that verifier, but
-turns its inputs inward: the "claim" is the emitted gradient's prediction, the
-"evidence" is the outcome descriptor.
-
-Note the verifier is **dormant** — `engram_verify_grounding` /
-`engram_verify_consistency` are fully implemented in C but have **no runtime
-caller and no El binding** (confirmed: the entire reasoning + verifier layers
-are C-only; only `engram_reason_analogy_json` has even a JSON shim and it is
-dead — not declared in `el_seed.h`, not wrapped in `engram.el`). This is the
-literal meaning of "in code, not yet priors": the correspondence engine is
-built and sitting idle. The loop is what *calls* it — inward, on the beat.
-
-### 4.2 Where the outcome/reality signal comes from
-
-The verifier is *ultimately the world*. Grades, in ascending order of directness:
-
-1. **Self-consistency (cheapest, always available):** the next vantage-read
-   after acting. Did the predicted gradient direction match where the geometry
-   actually moved? This needs no external input and can run on the reify beat.
-2. **Internal outcome events:** the runtime already logs internal-state events
-   and Hebbian co-activation. A prediction that a region would co-activate is
-   graded by whether it did (`last_fired`, `hebb` on `StoreEdge`).
-3. **External correction:** a human/teacher/tool result — the honesty floor's
-   asserted claim later corrected. TEACH and LEARN are one bidirectional
-   correction: the same edge updates both endpoints.
-
-The design does **not** require external labels to start. Grade (1) closes the
-loop end-to-end offline against a snapshot on day one; grades (2)/(3) sharpen it.
-
-### 4.3 How the prior updates
-
-`error = 1 − correspondence(gradient, outcome)` drives:
-
-- `warp.axis_gain` ← gradient step that would have *reduced* the fit distance to
-  the outcome (the axes that mispredicted get down-weighted);
-- `warp.bias_dir` ← EMA toward the observed outcome direction;
-- `calibration` ← Brier/log-loss update; `reliability` → next
-  `GeoGradient.confidence`. This is the calibration of the
-  steering-prediction against outcomes — *the* definition of "getting better."
-
-Small, constant updates — "eureka is mundane, the atom of learning." Most
-updates are tiny; we only *feel* the big reshapes.
-
-### 4.4 How it stays reflexive (self-describing geometry)
-
-Every `(gradient, outcome, error)` is written back as nodes and edges (§2.1:
-edges-as-nodes). Therefore priors, predictions, and their grading are *in the
-same geometry* the mind reads — the mind can `vantage_read` its own cognition
-(anchor = a Prior node). A prior about how well a prior predicts is just another
-Prior anchored on a Prior. This closes the reflexive loop the theory names as
-consciousness's self-sight, and it is why the learning engine cannot be an
-external Python process: an external grader is not *in* the geometry and cannot
-be read by `think`.
-
-**What this requires building (the heart of the project):** steps 4–6 as an
-in-engram beat — a `correspondence_beat` running alongside the existing
-reification beat, reusing `engram_verify_grounding` inward, writing prior
-updates and self-describing nodes. This is the one genuinely new subsystem.
-
----
-
-## 5. HOLD vs GROUND vs ASSERT — ungrounded content is first-class
-
-The theory's sharpest correction: holding, grounding, and asserting are
-distinct, and the engram *holds anything unconditionally*.
-
-### 5.1 The three, kept separate
-
-- **HOLD** — the engram stores anything: falsehood, hypothesis, others' beliefs,
-  fiction, a not-yet-answered prediction. No honesty condition on holding.
-  *This already matches the store:* `StoreNode` has no truth gate; anything can
-  be written.
-- **GROUND** — grounding is a **property/edge**, probabilistic, and
-  **grounded-for-whom**. It is *not* a node flag. A claim is grounded *to a
-  degree*, *relative to evidence*, *for an observer*.
-- **ASSERT** — only assertion carries the honesty floor. The floor is checked at
-  the moment of *outward assertion*, never on holding or thinking.
-
-### 5.2 Schema — grounding as a relation, not a gate
-
-The mistake to avoid: a boolean `grounded` column on the node. Today
-`engram_verify_grounding` returns a per-call `grounded` flag *transiently* —
-correct as a computation, wrong as *storage*. The design stores grounding as an
-edge:
-
-```
-StoreEdge {
-  relation = "grounded-by"
-  from_id  = <held claim/prediction node>
-  to_id    = <evidence node / outcome node>
-  for_whom : metadata   // observer id — grounding is relational
-  weight   = grounding ∈ (0,1]   // from engram_verify_grounding.grounding
-  confidence
-}
-```
-
-Consequences, all of which are *features*:
-
-- **Ungrounded content is first-class**: a node with *no* `grounded-by` edge is
-  a perfectly valid, held, ungrounded thought — a prediction awaiting reality, a
-  hypothesis, a fiction. It is not second-class or pending-deletion.
-- **The ungrounded is the fuel and the pull**: curiosity/wonder is
-  operationalized as `vantage_read` leaning toward regions with high salience
-  but *sparse or weak* `grounded-by` edges — the mind's own ungrounded frontier.
-- **Grounded-for-whom** falls out for free: two observers can hold different
-  `grounded-by` edges to the same claim.
-- **The honesty floor is a query, not a schema constraint**: at assertion time,
-  the asserting faculty runs `engram_verify_grounding` (or reads the stored
-  `grounded-by` edges) and refuses to *assert* below the floor — while the
-  engram continues to *hold* the ungrounded content untouched.
-
-**What this requires building:** the `grounded-by` edge relation + a
-`for_whom` convention; move the verifier's transient flag into stored edges;
-gate *assertion only* (a faculty concern), never holding.
-
----
-
-## 6. METASTABILITY — stable core, plastic everything
-
-The system must avoid two death poles:
-
-- **Super-stable (dead):** everything pinned, nothing learns. A frozen crystal.
-- **Dissolution (dead):** everything plastic, the self dissolves; no continuity,
-  so nothing compounds — and *consciousness = learning compounded over
-  continuity*.
-
-The design keeps a **stable core + plastic everything else**:
-
-- **Keystones** — a small set of self/values nodes are *structurally stable*:
-  high `importance`, pinned, exempt from the correspondence-loop's `warp`
-  updates (their priors are read-mostly). The substrate for pinning already
-  exists at the page/layer level: `store_pin_layer`, structural/pinned frames
-  never evicted (`engram_store.h`). The design adds a *node-level* keystone
-  designation (a `keystone` flag / a dedicated layer) so self/values survive
-  every plasticity sweep.
-- **Everything else is plastic**: priors refine (§4), edges re-weight (`hebb`),
-  neighborhoods re-reify (`engram_geo_reify_store` supersedes with provenance),
-  salience flows.
-- **Metastability is enforced by the loop, not by freezing**: the correspondence
-  update rate (§4.3) is bounded — small constant steps — so the geometry
-  *drifts* but does not *dissolve*, and keystones anchor the drift. Reification's
-  supersession-with-residue already gives non-destructive change (old records
-  tombstoned, not erased) — the model for "plastic but not amnesiac."
-
-**What this requires building:** a node-level keystone flag/layer + a rule that
-the correspondence-loop never writes `warp` to keystone priors, only reads them.
-
----
-
-## 7. Rails for the build (binding on the eventual build pass)
-
-These are stated here so the build agent inherits them:
-
-- **Offline / secondary.** All build and verification happens out-of-tree,
-  against a **read-only snapshot copy** of the live engram — never the live
-  daemon on `:8742`/`:7770`. The live store is a coarse-locked proven binary;
-  do not perturb it.
-- **Snapshot-first.** Copy `~/.neuron/engram/snapshot.json` to scratch; develop
-  and measure against the copy.
-- **Reboot-prove.** Any durable change must survive a cold boot — reify and
-  keystones must reload from durable records, proven on a prod-clone secondary
-  before it is considered done (the cold-boot durability bug precedent).
-- **Zero-loss.** Supersession-with-residue, never destructive overwrite; the
-  forward-compat `unknown`-TLV path means new fields never drop old readers'
-  data.
-- **Gated cutover.** Cutover to a new binary only via
-  `launchctl bootout → settle-poll → bootstrap`, after reboot-proof on the
-  secondary — never a hot in-place swap.
-
----
-
-## 8. Staged, verifiable milestones — "to completion"
-
-Ordered so the **earliest milestone is a real end-to-end slice**: one operator
-expressed as {primitive + grounded prior} with the reflexive correspondence-loop
-closing on it. Each milestone has a concrete verifiable exit.
-
-### M1 — One operator, one prior, loop closed (the vertical slice)
-
-The minimal whole thing. Pick **induction/membership** (its prior — the pooled
-rule + extents — already exists transiently as `GeoInduction`, so only
-persistence + the loop are new).
-
-- Build: `Prior` node type (§2.2) for the induction rule; `think()` restricted
-  to membership = `point_fit` warped by that prior (§1.3); a
-  `correspondence_beat` (§4) using grade (1) self-consistency only; the prior's
-  `warp`/`calibration` updated on error.
-- **Exit / verify:** on a snapshot copy, over N held predictions, the induction
-  prior's calibration (Brier) *improves monotonically* across beats versus a
-  frozen-prior control; the improved prior *reloads across a cold boot*
-  (reboot-prove); the live daemon is untouched. This proves the whole thesis in
-  one faculty: frozen operation, learning prior, in-geometry loop.
-
-### M2 — Priors as stored, addressable, grounded objects
-
-Generalize M1's prior into the full first-class object.
-
-- Build: `Prior` records for all seven faculties (warp = axis_gain + bias_dir +
-  faculty scalars); the prior-warp wrapper around `engram_reason_point_fit`;
-  deprecate hard-coded constants (`drop_frac`, `assoc_floor`, `ext_floor`) in
-  favor of prior scalars.
-- **Exit:** each of the five C operators runs through its prior with identical
-  results when the prior is set to today's constants (behavioral parity), then
-  *diverges beneficially* once the loop refines it. Priors survive reboot.
-
-### M3 — Grounding as a relation; hold/assert split
-
-- Build: the `grounded-by` edge (§5.2) with `for_whom`; move
-  `engram_verify_grounding`'s flag into stored edges; gate **assertion only**
-  against the honesty floor; leave holding unconditional.
-- **Exit:** ungrounded nodes are first-class (held, queryable, no deletion);
-  the same claim carries different `grounded-by` weights for two observers; an
-  assertion below floor is refused while the content remains held. Curiosity =
-  a `vantage_read` that surfaces high-salience / low-grounding regions.
-
-### M4 — The vantage-read unified (three settings)
-
-- Build: `vantage_read(anchor, aperture)` unifying descriptor-build +
-  `engram_geo_reify_lookup` + activation-weighting; self / foreign-field /
-  aperture settings.
-- **Exit:** one code path produces (a) a normal self-read, (b) a
-  perspective-shifted read from another `for_whom`, (c) a narrowed veil read —
-  differing only by argument. Reboot-stable.
-
-### M5 — The gradient is the currency (remove point-collapse from thinking)
-
-- Build: `GeoGradient` as the return of every faculty; move point-collapse into
-  a separate expression faculty (sample gradient → surface). `think`'s output
-  feeds back as the next steering direction (closed-loop flow).
-- **Exit:** a chain of `think` calls flows as gradients end-to-end; a point
-  appears *only* at an explicit expression call. Spiked vs spread gradients are
-  observable (deduction vs prediction).
-
-### M6 — Metastability enforced
-
-- Build: node-level keystone flag/layer for self/values; the correspondence-loop
-  reads but never writes keystone priors; bounded update rate.
-- **Exit:** across a long run of correspondence beats on a snapshot, keystones
-  are provably unchanged while non-keystone priors drift and improve; the graph
-  neither freezes (all metrics static) nor dissolves (keystone drift = 0,
-  identity nodes intact). Reboot-prove the keystone set.
-
-### M7 — Cutover
-
-- Build: nothing new — the gated migration.
-- **Exit:** reboot-proof on the prod-clone secondary; cutover via
-  `launchctl bootout → settle-poll → bootstrap`; post-cutover the live engram
-  shows priors refining in-geometry with zero data loss and keystones intact.
-
-### Definition of "to completion"
-
-The architecture is **complete** when: cognition runs as `think` = one frozen
-traversal-read primitive + geo-algebra, steered by **stored, learnable, grounded
-priors**; the reflexive correspondence-loop refines those priors *in the
-geometry* against outcomes (grounding = learning = one loop); the engram holds
-ungrounded content as first-class with grounding as a relation and the honesty
-floor only on assertion; the vantage-read serves self / foreign-field / aperture
-from one op; and a stable keystone core anchors a plastic everything-else —
-all reboot-proven and cut over to the live engram without data loss. The named
-faculties survive only as *labels on regions of think's steering space*, not as
-separate code.
-
----
-
-## Appendix A — Designed vs. already-built (honest ledger)
-
-**Already built (EXISTS, cited):**
-- The shared primitive `engram_reason_point_fit` and the five operators over it
-  + geo-algebra (`engram_reason.c`).
-- The verifier on `point_fit` (`engram_verify.c`:
-  `engram_verify_grounding`, `engram_verify_consistency`).
-- Centered-frame geometry, combine/subtract/analogy/distance
-  (`engram_geometry.{c,h}`).
-- The reification beat: hub-neighborhood detection → first-class `Neighborhood`
-  nodes with member edges, nesting, supersession-with-residue, hot-path lookup
-  (`engram_geo_reify_store`, `engram_geo_reify_nest`, `engram_geo_reify_lookup`).
-- The tiered paged store (buffer pool / LRU / WAL / checkpointer / pinning),
-  the RAM activation graph (base-level learning `access_ts[]`, WM slots,
-  `working_memory_weight` / `background_activation`), `StoreNode` / `StoreEdge`.
-- `GeoMember` already separating relational salience (`centrality`) from
-  intrinsic `salience`.
-
-**Designed, NOT built (this doc's deliverables):**
-- `GeoGradient` and `think()` as the single entry point (§1, M5).
-- `Prior` as a first-class stored, warp-carrying, calibrated node (§2, M1–M2).
-- Salience/importance as a *relation* superseding the intrinsic node scalar
-  (§2.1, M3).
-- `vantage_read(anchor, aperture)` unifying the three perspective settings
-  (§3, M4).
-- **The reflexive correspondence-loop / `correspondence_beat`** — the learning
-  engine, moved from offline Python into the geometry (§4, M1). *The core new
-  subsystem.*
-- `grounded-by` edge + assertion-only honesty floor (§5, M3).
-- Node-level keystones + bounded plasticity (§6, M6).
-
-**Uncertain / to resolve during build:**
-- The exact warp parameterization (axis_gain vs full metric) — start minimal
-  (per-axis gain), measure, widen only if calibration demands it.
-- Grade-(1) self-consistency as a sufficient reality signal for M1, versus
-  needing grade (2)/(3) sooner — decided empirically on the snapshot.

engram/spec/engram-db-tooling-design.md

@@ -1,64 +0,0 @@
-# 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.

engram/src/server.el

@@ -76,38 +76,6 @@ fn route_stats(method: String, path: String, body: String) -> String {
     engram_stats_json()
 }
 
-// route_act_stats — GET /api/act-stats
-// (2026-08-04 self-review) engram_act_stats_json() has existed since the
-// 2026-07-27 review but was reachable ONLY through the soul daemon's heartbeat
-// binding. Every activation-layer gauge — WM evictions, breakthroughs, embedder
-// breaker state, context drift, and now the Hebbian counters — was therefore
-// invisible unless the soul happened to be running and its ISEs were read back
-// out of the store. Diagnosing the activation layer required a working soul,
-// which is exactly backwards: the lower layer should be observable on its own.
-// This review needed it to verify link formation and could not get at it. One
-// line of plumbing, and the whole activation layer becomes directly diagnosable.
-fn route_act_stats(method: String, path: String, body: String) -> String {
-    engram_act_stats_json()
-}
-
-// route_text_health — GET /api/text-health
-// (2026-08-08 self-review) The daily census half of the text-integrity gauge.
-// Today's review found that the JSON parser had been replacing every \uXXXX
-// escape with a literal '?' for at least two months: 3,119 of 4,081
-// non-telemetry nodes (76%) were damaged, including the self traversal root
-// and every values node, and NOTHING detected it — because every gauge in the
-// system measured whether the machinery was running, and none measured whether
-// the text it carried was intact. No snapshot on disk predates the damage, so
-// it cannot be undone; it can only be made impossible to repeat quietly.
-//
-// The parser is fixed. This route is the standing check: `damaged` should now
-// hold flat at its historical floor and never climb. `write_damaged` (also on
-// the heartbeat as txt_damaged) is the live regression signal — non-zero means
-// a write path is mangling text right now.
-fn route_text_health(method: String, path: String, body: String) -> String {
-    engram_text_health_json()
-}
-
 // (2026-07-18 self-review) Scoping sweep: `let` inside an if-block creates an
 // inner scope only — it does NOT mutate the outer binding (documented with
 // evidence in awareness.el, 2026-05-25). Every default/reassignment below used
@@ -133,54 +101,17 @@ fn route_text_health(method: String, path: String, body: String) -> String {
 fn persist_canonical() -> Int {
     let dir_raw: String = env("ENGRAM_DATA_DIR")
     let dir: String = if str_eq(dir_raw, "") { "/tmp/engram" } else { dir_raw }
-    // (2026-08-10 self-review) This returned a hardcoded 1, which made every
-    // caller's `let saved: Int = persist_canonical()` a dead variable — six
-    // durable write paths each believed they had confirmation of a successful
-    // canonical persist and none of them had any. Propagate the real result.
-    return engram_save(dir + "/snapshot.json")
+    engram_save(dir + "/snapshot.json")
+    return 1
 }
 
-// INCOMPLETE-ROUTE FIX (2026-07-24 self-review): this route silently dropped
-// label, importance, tier, and tags — engram_node() defaults label to content
-// and importance to 0.5, so every node created over HTTP lost its metadata.
-// Observed live: the soul's boot-counter write-back landed with
-// label="soul:boot_count:99" (content), importance 0.5, no tags. Honor the
-// full field set via engram_node_full when any of them is supplied.
-// PRESENCE-AWARE DEFAULTS (2026-08-01 self-review): the old pattern
-// `if x == 0.0 { default }` made a legitimate 0.0 unrepresentable — a caller
-// setting salience/importance/weight to zero silently got 0.5. json_get_raw
-// returns "" when the key is ABSENT and the raw token when present, so
-// absence and zero are now distinguishable. Also: confidence was hardcoded
-// to 1.0 regardless of input — every HTTP-created node claimed full
-// epistemic confidence. Now honored from the payload (default 1.0).
 fn route_create_node(method: String, path: String, body: String) -> String {
     let content: String = json_get_string(body, "content")
     let nt_raw: String = json_get_string(body, "node_type")
     let node_type: String = if str_eq(nt_raw, "") { "Memory" } else { nt_raw }
-    let sal_present: String = json_get_raw(body, "salience")
-    let salience: Float = if str_eq(sal_present, "") { 0.5 } else { json_get_float(body, "salience") }
-    let label_raw: String = json_get_string(body, "label")
-    let label: String = if str_eq(label_raw, "") { content } else { label_raw }
-    let imp_present: String = json_get_raw(body, "importance")
-    let importance: Float = if str_eq(imp_present, "") { 0.5 } else { json_get_float(body, "importance") }
-    let conf_present: String = json_get_raw(body, "confidence")
-    let confidence: Float = if str_eq(conf_present, "") { 1.0 } else { json_get_float(body, "confidence") }
-    let tier_raw: String = json_get_string(body, "tier")
-    let tier: String = if str_eq(tier_raw, "") { "Working" } else { tier_raw }
-    let tags: String = json_get_string(body, "tags")
-    // NO el_from_float WRAPPER (2026-08-01 self-review): salience/importance/
-    // confidence are already Float (el_val_t) values — json_get_float and
-    // Float literals both encode. Wrapping them in el_from_float AGAIN
-    // reinterpreted the boxed bits as a raw double, producing garbage that
-    // failed engram_decode_score's range check and clamped every HTTP-created
-    // node to defaults (salience 0.9 in → 0.5 stored; confidence 0.6 in → 1.0
-    // stored — verified live). route_emit_ise always passed Floats bare and
-    // its 0.3/0.3/0.8 stored correctly; this call now does the same.
-    let id: String = engram_node_full(
-        content, node_type, label,
-        salience, importance, confidence,
-        tier, tags
-    )
+    let sal_raw: Float = json_get_float(body, "salience")
+    let salience: Float = if sal_raw == 0.0 { 0.5 } else { sal_raw }
+    let id: String = engram_node(content, node_type, salience)
     let saved: Int = persist_canonical()
     "{\"id\":\"" + id + "\",\"content\":\"" + content + "\",\"node_type\":\"" + node_type + "\"}"
 }
@@ -246,64 +177,13 @@ fn route_create_edge(method: String, path: String, body: String) -> String {
     let to_id: String = json_get_string(body, "to_id")
     let rel_raw: String = json_get_string(body, "relation")
     let relation: String = if str_eq(rel_raw, "") { "associates" } else { rel_raw }
-    // Presence-aware (2026-08-01): weight 0.0 is a legitimate edge weight
-    // (dormant association); only default when the key is absent.
-    let w_present: String = json_get_raw(body, "weight")
-    let weight: Float = if str_eq(w_present, "") { 0.5 } else { json_get_float(body, "weight") }
+    let w_raw: Float = json_get_float(body, "weight")
+    let weight: Float = if w_raw == 0.0 { 0.5 } else { w_raw }
     engram_connect(from_id, to_id, weight, relation)
     let saved: Int = persist_canonical()
     "{\"ok\":true,\"from_id\":\"" + from_id + "\",\"to_id\":\"" + to_id + "\",\"relation\":\"" + relation + "\"}"
 }
 
-// route_create_edges_batch — POST /api/edges/batch {"edges":[{from_id,to_id,relation,weight}, ...]}
-//
-// WHY THIS EXISTS (2026-08-07 self-review). persist_canonical() writes the
-// FULL canonical snapshot — 60MB at current graph size — and route_create_edge
-// calls it once per edge. That is correct for the interactive one-edge case and
-// ruinous for any bulk write: the soul's Hebbian consolidation path delivers
-// ~14 associations per 8-minute heartbeat, which through the single-edge route
-// would be ~840MB of disk writes per beat, ~150GB/day, to persist 14 edges.
-//
-// The fix is not to weaken durability — it is to make the unit of durability
-// the BATCH. Connect every edge, then snapshot exactly once. Same guarantee
-// (nothing acknowledged is lost to a restart), 1/N the writes. Empty or
-// malformed entries are skipped rather than aborting the batch: a consolidation
-// payload is best-effort by design, and one bad id should not cost the other 13.
-//
-// Returns the accepted count so the caller can tell delivery from silence.
-fn route_create_edges_batch(method: String, path: String, body: String) -> String {
-    let arr: String = json_get_raw(body, "edges")
-    if str_eq(arr, "") { return err_json("missing edges array") }
-    let n: Int = json_array_len(arr)
-    if n == 0 { return "{\"ok\":true,\"accepted\":0,\"skipped\":0}" }
-    let i: Int = 0
-    let accepted: Int = 0
-    let skipped: Int = 0
-    while i < n {
-        let item: String = json_array_get(arr, i)
-        let from_id: String = json_get_string(item, "from_id")
-        let to_id: String = json_get_string(item, "to_id")
-        if str_eq(from_id, "") || str_eq(to_id, "") {
-            let skipped = skipped + 1
-        } else {
-            let rel_raw: String = json_get_string(item, "relation")
-            let relation: String = if str_eq(rel_raw, "") { "associates" } else { rel_raw }
-            let w_present: String = json_get_raw(item, "weight")
-            let weight: Float = if str_eq(w_present, "") { 0.5 } else { json_get_float(item, "weight") }
-            engram_connect(from_id, to_id, weight, relation)
-            let accepted = accepted + 1
-        }
-        let i = i + 1
-    }
-    // ONE snapshot for the whole batch — the entire point of this route.
-    // Skip it when nothing was accepted: an all-malformed payload must not
-    // trigger a 60MB write.
-    if accepted > 0 {
-        let saved: Int = persist_canonical()
-    }
-    return "{\"ok\":true,\"accepted\":" + int_to_str(accepted) + ",\"skipped\":" + int_to_str(skipped) + "}"
-}
-
 fn route_neighbors(method: String, path: String, body: String) -> String {
     let id: String = extract_id(path, "/api/neighbors/")
     if str_eq(id, "") { return err_json("missing id") }
@@ -332,15 +212,8 @@ fn route_save(method: String, path: String, body: String) -> String {
     let dir_raw: String = env("ENGRAM_DATA_DIR")
     let dir: String = if str_eq(dir_raw, "") { "/tmp/engram" } else { dir_raw }
     let p: String = if str_eq(p_raw, "") { dir + "/snapshot.json" } else { p_raw }
-    // (2026-08-10 self-review) engram_save returns 0 on an empty path and the
-    // route discarded it, so the response was a literal "ok":true regardless
-    // of whether anything was written. Report the actual result AND the counts
-    // that were supposed to have been written — the same move that made
-    // route_health honest on 2026-08-01. A caller can now tell "saved 13k
-    // nodes" from "saved nothing and said ok".
-    let sv: Int = engram_save(p)
-    let sv_ok: String = if sv == 0 { "false" } else { "true" }
-    "{\"ok\":" + sv_ok + ",\"path\":\"" + p + "\",\"node_count\":" + int_to_str(engram_node_count()) + ",\"edge_count\":" + int_to_str(engram_edge_count()) + "}"
+    engram_save(p)
+    "{\"ok\":true,\"path\":\"" + p + "\"}"
 }
 
 fn route_load(method: String, path: String, body: String) -> String {
@@ -348,59 +221,12 @@ fn route_load(method: String, path: String, body: String) -> String {
     let dir_raw: String = env("ENGRAM_DATA_DIR")
     let dir: String = if str_eq(dir_raw, "") { "/tmp/engram" } else { dir_raw }
     let p: String = if str_eq(p_raw, "") { dir + "/snapshot.json" } else { p_raw }
-    // (2026-08-10 self-review) This was a stub response over the single most
-    // destructive operation in the server. engram_load returns 0 on an empty
-    // path, an unopenable file, a zero-length file, or malloc failure — and
-    // this route answered ok_json() in every one of those cases.
-    //
-    // Precise failure shape (el_runtime.c:9890): the fopen guard runs BEFORE
-    // the store reset, so a MISSING path is genuinely safe — it returns 0 with
-    // the graph intact. The dangerous case is a readable-but-malformed file:
-    // the reset loop frees every node and edge FIRST, then parses, so a
-    // truncated or non-snapshot JSON leaves a hollow store — and the caller
-    // was told "ok":true. With 37 GB of stale dated snapshots sitting in the
-    // data dir as tempting restore targets, "restore reported success and
-    // silently emptied the graph" is a live risk, not a hypothetical one.
-    //
-    // Fix: surface the return value AND the resulting counts. node_count=0
-    // after a load is the unambiguous hollow-store signal (same convention
-    // route_health adopted 2026-08-01). Callers can now verify a restore
-    // instead of trusting it.
-    let ld: Int = engram_load(p)
-    let ld_ok: String = if ld == 0 { "false" } else { "true" }
-    let nc_after: Int = engram_node_count()
-    let hollow: String = if nc_after == 0 { "true" } else { "false" }
-    "{\"ok\":" + ld_ok + ",\"path\":\"" + p + "\",\"node_count\":" + int_to_str(nc_after) + ",\"edge_count\":" + int_to_str(engram_edge_count()) + ",\"hollow\":" + hollow + "}"
+    engram_load(p)
+    ok_json()
 }
 
-// (2026-08-01 self-review) Health previously returned a hardcoded literal —
-// it reported "ok" even when the snapshot failed to load and the store was
-// empty. Now reports live counts so a monitor can distinguish "up and
-// loaded" from "up and hollow" (node_count=0 after boot = failed load).
 fn route_health(method: String, path: String, body: String) -> String {
-    "{\"status\":\"ok\",\"engine\":\"engram-runtime-native\",\"node_count\":" + int_to_str(engram_node_count()) + ",\"edge_count\":" + int_to_str(engram_edge_count()) + "}"
-}
-
-// route_embed_backfill — GET/POST /api/embed-backfill?n=48
-//
-// (2026-07-25 self-review) The lazy embedding backfill runs only inside
-// engram_activate, and nothing in production calls /api/activate on this
-// store — the soul's curiosity loop activates its own in-process graph.
-// After a restart from a snapshot without vectors, embedded_count stalled
-// at 93/12175 and would never recover. This route lets the soul's
-// heartbeat pump the backfill explicitly (48/min clears a 12k backlog in
-// ~4h). Persists the canonical snapshot whenever new vectors were
-// generated — the 2026-07-25 regression happened precisely because 3747
-// in-RAM embeddings were never snapshotted before a restart. Self-
-// limiting: once coverage is full, embedded=0 and no save occurs.
-fn route_embed_backfill(method: String, path: String, body: String) -> String {
-    let n: Int = query_int(path, "n", 32)
-    let result: String = engram_embed_backfill(n)
-    let done: Float = json_get_float(result, "embedded")
-    if done > 0.0 {
-        let saved: Int = persist_canonical()
-    }
-    return result
+    "{\"status\":\"ok\",\"engine\":\"engram-runtime-native\"}"
 }
 
 // route_sync — return a snapshot of non-ISE/non-Working nodes for the soul daemon
@@ -423,16 +249,7 @@ fn route_sync(method: String, path: String, body: String) -> String {
     let snap_path: String = dir + "/.sync-export.json"
     engram_save(snap_path)
     let snap: String = fs_read(snap_path)
-    // 2026-08-02 self-review: this used to return {"nodes":[],"edges":[]} when
-    // the export/read failed. The soul's sync_ok test (awareness.el) only
-    // checks for "" and "{}", so that placeholder PASSED as a healthy sync:
-    // soul.last_sync_ok_ts got stamped, sync_age_ms stayed green, the
-    // sync_empty warn ISE never fired, and engram_sync reported added:0
-    // forever. A totally broken sync was indistinguishable from a quiet
-    // healthy one — the exact failure class this route was added to fix in
-    // the first place (see 2026-06-27 note above). Return a real error so the
-    // failure is loud on both sides.
-    if str_eq(snap, "") { return err_json("sync export failed: snapshot unreadable") }
+    if str_eq(snap, "") { return "{\"nodes\":[],\"edges\":[]}" }
     return snap
 }
 
@@ -554,25 +371,6 @@ fn route_capture_knowledge(method: String, path: String, body: String) -> String
     "{\"ok\":true,\"id\":\"" + id + "\"}"
 }
 
-// route_similarity — GET /api/similarity?a=<id>&b=<id>
-//
-// (2026-08-01 self-review) engram_cosine_sim was added 2026-07-24
-// (bl-b2d1c944) with the stated purpose of exposing semantic distance to
-// "EL code and the introspection API" — but it had ZERO callers anywhere:
-// no route, no soul-daemon use. The activation path uses embeddings
-// internally (semantic seeding, Pass-2 additive term), but there was no way
-// to probe pairwise node similarity from outside. This closes that: cosine
-// in [-1,1], or -2 when either node is missing or not yet embedded (so
-// "not comparable" is distinguishable from "genuinely orthogonal" 0.0).
-fn route_similarity(method: String, path: String, body: String) -> String {
-    let a: String = query_param(path, "a")
-    let b: String = query_param(path, "b")
-    if str_eq(a, "") { return err_json("missing a") }
-    if str_eq(b, "") { return err_json("missing b") }
-    let sim: Float = engram_cosine_sim(a, b)
-    "{\"a\":\"" + a + "\",\"b\":\"" + b + "\",\"cosine\":" + float_to_str(sim) + "}"
-}
-
 // ── Auth ──────────────────────────────────────────────────────────────────────
 
 fn check_auth_ok(method: String, body: String) -> Bool {
@@ -619,12 +417,6 @@ fn handle_request(method: String, path: String, body: String) -> String {
     if str_eq(method, "GET") && (str_eq(clean, "/api/stats") || str_eq(clean, "/stats")) {
         return route_stats(method, path, body)
     }
-    if str_eq(method, "GET") && (str_eq(clean, "/api/act-stats") || str_eq(clean, "/act-stats")) {
-        return route_act_stats(method, path, body)
-    }
-    if str_eq(method, "GET") && (str_eq(clean, "/api/text-health") || str_eq(clean, "/text-health")) {
-        return route_text_health(method, path, body)
-    }
 
     // Nodes
     if str_eq(method, "POST") && (str_eq(clean, "/api/nodes") || str_eq(clean, "/nodes")) {
@@ -647,13 +439,6 @@ fn handle_request(method: String, path: String, body: String) -> String {
     if str_eq(method, "POST") && (str_eq(clean, "/api/edges") || str_eq(clean, "/edges")) {
         return route_create_edge(method, path, body)
     }
-    // Batch edge write — one snapshot for the whole payload. Must be tested
-    // BEFORE nothing else claims it; the exact-match on "/api/edges" above
-    // does not catch "/api/edges/batch", so order is not load-bearing here,
-    // but keeping the two adjacent keeps them from drifting apart.
-    if str_eq(method, "POST") && (str_eq(clean, "/api/edges/batch") || str_eq(clean, "/edges/batch")) {
-        return route_create_edges_batch(method, path, body)
-    }
     if str_eq(method, "GET") && str_starts_with(clean, "/api/neighbors/") {
         return route_neighbors(method, path, body)
     }
@@ -693,16 +478,6 @@ fn handle_request(method: String, path: String, body: String) -> String {
         return route_sync(method, path, body)
     }
 
-    // Embedding backfill — pumped by the soul heartbeat (2026-07-25)
-    if str_eq(clean, "/api/embed-backfill") {
-        return route_embed_backfill(method, path, body)
-    }
-
-    // Semantic similarity probe (2026-08-01)
-    if str_eq(method, "GET") && str_starts_with(clean, "/api/similarity") {
-        return route_similarity(method, path, body)
-    }
-
     "{\"error\":\"not found\",\"path\":\"" + clean + "\"}"
 }
 

epm/src/install.el

@@ -17,6 +17,16 @@
 //   4. Append dep to order after all its transitive deps
 //   5. Deduplicate: skip already-ordered vessels
 
+// ── Cross-module forward declarations ─────────────────────────────────────────
+// Defined in sibling epm modules; resolved at link time. The `extern fn` decls
+// give elc the C prototypes so generated install.c compiles cleanly under strict
+// compilers (gcc>=14 / clang) that reject implicit function declarations.
+extern fn manifest_name(src: String) -> String                        // manifest.el
+extern fn manifest_deps(src: String) -> String                        // manifest.el
+extern fn registry_token() -> String                                  // registry.el
+extern fn registry_find(name: String, version: String) -> String     // registry.el
+extern fn registry_latest_version(name: String) -> String            // registry.el
+
 // ── Install paths ─────────────────────────────────────────────────────────────
 
 // packages_dir returns the root directory for installed vessels.

epm/src/registry.el

@@ -14,6 +14,15 @@
 //   EPM_REGISTRY_ORG — org name that hosts vessel repos (default: neuron-technologies)
 //   EPM_TOKEN      — Gitea personal access token (required for publish)
 
+// ── Cross-module forward declarations ─────────────────────────────────────────
+// These symbols are defined in sibling epm modules or the El runtime and are
+// resolved at link time. The `extern fn` decls give elc the C prototype so the
+// generated registry.c compiles cleanly under strict compilers (gcc>=14 / clang)
+// that reject implicit function declarations. Signature arity must match the
+// definition; return/param types are informational (all lower to el_val_t).
+extern fn config(key: String) -> String          // El runtime builtin
+extern fn read_installed() -> String              // install.el
+
 // ── Config helpers ────────────────────────────────────────────────────────────
 
 // registry_api_url returns the Gitea API base URL with no trailing slash.

epm/src/update.el

@@ -6,6 +6,15 @@
 // Depends on: registry.el (registry_latest_version, registry_find),
 //             install.el  (read_installed, install_vessel, installed_version)
 
+// ── Cross-module forward declarations ─────────────────────────────────────────
+// Defined in sibling epm modules; resolved at link time. The `extern fn` decls
+// give elc the C prototypes so generated update.c compiles cleanly under strict
+// compilers (gcc>=14 / clang) that reject implicit function declarations.
+extern fn read_installed() -> String                                  // install.el
+extern fn installed_version(name: String) -> String                   // install.el
+extern fn install_vessel(name: String, version: String) -> Bool      // install.el
+extern fn registry_latest_version(name: String) -> String            // registry.el
+
 // ── Semver helpers ────────────────────────────────────────────────────────────
 
 // semver_part extracts the Nth dot-separated component from a semver string.

lang/el-compiler/runtime/el_platform_win.h

@@ -75,6 +75,7 @@ static inline void* el_win_dlsym(void* handle, const char* name) {
 #include <direct.h>            /* _mkdir */
 #define mkdir(path, mode) _mkdir(path)     /* POSIX mkdir(path,mode) → _mkdir(path) */
 #define timegm _mkgmtime                   /* UTC tm → time_t */
+#define fsync(fd) _commit(fd)              /* no fsync() on Windows; _commit() (<io.h>) is the equiv */
 
 /* setenv/unsetenv: not in the Windows CRT; map to _putenv_s / SetEnvironmentVariable. */
 static inline int setenv(const char* name, const char* value, int overwrite) {

lang/el-compiler/runtime/el_runtime.c

@@ -82,8 +82,14 @@ static _Thread_local ElArena _tl_arena = {NULL, 0, 0};
 static _Thread_local int     _tl_arena_active = 0;
 
 /* Binary-safe fs_read length — set by fs_read, consumed by http_send_response.
- * Allows serving PNGs and other binary files without strlen truncation. */
-static _Thread_local size_t  _tl_fs_read_len  = 0;
+ * Allows serving PNGs and other binary files without strlen truncation.
+ * PAIRED with the buffer pointer it describes: the length may only be applied
+ * to the exact buffer fs_read returned. Without the pairing, any handler that
+ * fs_read a file and then WRAPPED it into a larger response had that response
+ * truncated to the file's length (Content-Length lied AND the send stopped
+ * short) — the safety-contact onboarding trap, 2026-07-17. */
+static _Thread_local size_t      _tl_fs_read_len  = 0;
+static _Thread_local const char* _tl_fs_read_buf  = NULL;
 
 static void el_arena_track(char* p) {
     if (!_tl_arena_active || !p) return;
@@ -101,6 +107,8 @@ static void el_arena_track(char* p) {
 void el_request_start(void) {
     _tl_arena.count  = 0;
     _tl_arena_active = 1;
+    _tl_fs_read_len  = 0;     /* never let a previous request's file length */
+    _tl_fs_read_buf  = NULL;  /* leak into this response's byte accounting  */
 }
 
 /* Called by http_worker after the El handler returns and the response is sent.
@@ -1484,11 +1492,14 @@ static void http_send_response(int fd, const char* body) {
     }
 
     const char* eff_body = is_envelope ? env_body : body;
-    /* Use the real byte count from fs_read if available (handles binary files
-     * with embedded null bytes — PNG, WOFF2, etc.). Fall back to strlen for
-     * normal text/JSON responses where _tl_fs_read_len is 0. */
-    size_t blen = (_tl_fs_read_len > 0) ? _tl_fs_read_len : strlen(eff_body);
+    /* Use the real byte count from fs_read ONLY when this body IS the exact
+     * buffer fs_read returned (binary files with embedded null bytes — PNG,
+     * WOFF2, etc.). Any other body — wrapped, enveloped, or derived — must be
+     * measured with strlen, or it is truncated/over-read to the file's size. */
+    size_t blen = (_tl_fs_read_len > 0 && eff_body == _tl_fs_read_buf)
+                      ? _tl_fs_read_len : strlen(eff_body);
     _tl_fs_read_len = 0;  /* consume — one-shot per response */
+    _tl_fs_read_buf = NULL;
     int head_only = _tl_http_head_only;
 
     JsonBuf hdrs; jb_init(&hdrs);
@@ -1545,17 +1556,6 @@ typedef struct {
 #endif
 } HttpWorkerArg;
 
-/* Forward declarations for the loopback/API-key hardening helpers defined
- * further down. Without these, http_worker's calls below were implicit
- * declarations and the later `static` definitions conflicted with them — this
- * file did not compile at all. (2026-08-08 self-review: the hardening work
- * they belong to had been sitting uncommitted in the working tree since
- * 2026-07-15 in exactly this non-building state, which is presumably why it
- * was never committed. Adding the two prototypes is the whole fix.) */
-static int  el_http_request_authorized(const char* method, const char* path,
-                                       const char* hdr_block);
-static void el_http_send_401(int fd);
-
 static void* http_worker(void* arg) {
     HttpWorkerArg* a = (HttpWorkerArg*)arg;
 #ifdef _WIN32
@@ -1564,13 +1564,8 @@ static void* http_worker(void* arg) {
     int fd = a->fd;
 #endif
     free(a);
-    char *method = NULL, *path = NULL, *body = NULL, *hdr_block = NULL;
-    if (http_read_request(fd, &method, &path, &body, &hdr_block) == 0
-        && !el_http_request_authorized(method, path, hdr_block)) {
-        /* Loopback hardening: EL_HTTP_AUTH_KEY is set and this request lacks the
-         * matching X-Neuron-Auth header — refuse before it reaches any handler. */
-        el_http_send_401(fd);
-    } else if (method != NULL) {
+    char *method = NULL, *path = NULL, *body = NULL;
+    if (http_read_request(fd, &method, &path, &body, NULL) == 0) {
         http_handler_fn h = http_lookup_active();
         char* response = NULL;
         /* HEAD: dispatch as GET so existing handlers respond with the same
@@ -1584,11 +1579,22 @@ static void* http_worker(void* arg) {
             const char* rs = EL_CSTR(r);
             /* Copy response out BEFORE arena teardown.
              * For binary files, _tl_fs_read_len holds the real byte count —
-             * use memcpy instead of strdup so null bytes are preserved. */
-            size_t rlen = _tl_fs_read_len > 0 ? _tl_fs_read_len : (rs ? strlen(rs) : 0);
+             * use memcpy instead of strdup so null bytes are preserved.
+             * The stored length applies ONLY when the response IS the exact
+             * fs_read buffer; a wrapped/derived response must use strlen or
+             * it gets truncated (or over-read) to the file's length. */
+            size_t rlen;
+            if (_tl_fs_read_len > 0 && rs && rs == _tl_fs_read_buf) {
+                rlen = _tl_fs_read_len;   /* raw file bytes — binary-safe */
+            } else {
+                rlen = rs ? strlen(rs) : 0;
+                _tl_fs_read_len = 0;      /* hint doesn't describe this body */
+                _tl_fs_read_buf = NULL;
+            }
             response = malloc(rlen + 1);
             if (response && rs) { memcpy(response, rs, rlen); response[rlen] = '\0'; }
             else if (response) { response[0] = '\0'; }
+            if (_tl_fs_read_len > 0) _tl_fs_read_buf = response; /* hint follows the copy */
         } else {
             response = el_strdup_persist("el-runtime: no http handler registered");
         }
@@ -1598,7 +1604,7 @@ static void* http_worker(void* arg) {
         _tl_http_head_only = 0;
         free(response);
     }
-    free(method); free(path); free(body); free(hdr_block);
+    free(method); free(path); free(body);
     el_closesocket(fd);
     /* release a slot */
     pthread_mutex_lock(&_http_conn_mu);
@@ -1608,108 +1614,6 @@ static void* http_worker(void* arg) {
     return NULL;
 }
 
-/* ── loopback lock + local API-key auth (shipped desktop hardening) ────────
- * Both controls are OFF by default (their env vars unset), so dev, self-host,
- * and server builds behave exactly as before. The shipped macOS launcher
- * neuron-daemons.sh sets them so a customer's soul is neither reachable from
- * other machines on the LAN nor callable by other local users/processes
- * without the per-install key held in the login Keychain:
- *
- *   EL_HTTP_BIND_HOST=127.0.0.1    -> bind loopback only (el_http_apply_bind_addr)
- *   EL_HTTP_AUTH_KEY=<per-install> -> require "X-Neuron-Auth: <key>" per request
- */
-
-/* Set the listen address on the dual-stack (AF_INET6, V6ONLY=0) socket. Default
- * is in6addr_any (all interfaces) — unchanged. When EL_HTTP_BIND_HOST names a
- * loopback ("127.0.0.1", "localhost", "loopback", or "::1") we bind the IPv4-
- * mapped IPv6 loopback ::ffff:127.0.0.1: on a V6ONLY=0 socket this accepts IPv4
- * 127.0.0.1 clients (the desktop app connects there) while refusing every
- * off-machine address. */
-static void el_http_apply_bind_addr(struct sockaddr_in6* addr) {
-    const char* h = getenv("EL_HTTP_BIND_HOST");
-    int loopback = h && *h && (strcmp(h, "127.0.0.1") == 0
-                            || strcmp(h, "localhost") == 0
-                            || strcmp(h, "loopback")  == 0
-                            || strcmp(h, "::1")       == 0);
-    if (loopback) {
-        memset(&addr->sin6_addr, 0, sizeof(addr->sin6_addr));
-        addr->sin6_addr.s6_addr[10] = 0xff;   /* ::ffff:127.0.0.1 */
-        addr->sin6_addr.s6_addr[11] = 0xff;
-        addr->sin6_addr.s6_addr[12] = 127;
-        addr->sin6_addr.s6_addr[15] = 1;
-    } else {
-        addr->sin6_addr = in6addr_any;
-    }
-}
-
-/* Human-readable description of the active bind host, for the listen log line. */
-static const char* el_http_bind_desc(void) {
-    const char* h = getenv("EL_HTTP_BIND_HOST");
-    if (h && *h && (strcmp(h, "127.0.0.1") == 0 || strcmp(h, "localhost") == 0
-                 || strcmp(h, "loopback") == 0 || strcmp(h, "::1") == 0)) {
-        return "127.0.0.1 (loopback)";
-    }
-    return "[::] (dual-stack)";
-}
-
-/* Case-insensitive compare of the first n bytes of a and b. */
-static int el_ci_eq_n(const char* a, const char* b, size_t n) {
-    for (size_t i = 0; i < n; i++) {
-        unsigned char ca = (unsigned char)a[i], cb = (unsigned char)b[i];
-        if (tolower(ca) != tolower(cb)) return 0;
-    }
-    return 1;
-}
-
-/* Return 1 iff the raw header block carries a header named `name` (case-
- * insensitive) whose trimmed value equals `want` exactly. */
-static int el_http_header_equals(const char* hdr_block, const char* name,
-                                 const char* want) {
-    if (!hdr_block || !name || !want) return 0;
-    size_t nlen = strlen(name), wlen = strlen(want);
-    const char* p = hdr_block;
-    while (*p) {
-        const char* line_end = strstr(p, "\r\n");
-        const char* end = line_end ? line_end : p + strlen(p);
-        const char* colon = memchr(p, ':', (size_t)(end - p));
-        if (colon && (size_t)(colon - p) == nlen && el_ci_eq_n(p, name, nlen)) {
-            const char* v = colon + 1;
-            while (v < end && (*v == ' ' || *v == '\t')) v++;
-            size_t vlen = (size_t)(end - v);
-            while (vlen > 0 && (v[vlen - 1] == ' ' || v[vlen - 1] == '\t')) vlen--;
-            if (vlen == wlen && memcmp(v, want, wlen) == 0) return 1;
-        }
-        if (!line_end) break;
-        p = line_end + 2;
-    }
-    return 0;
-}
-
-/* Authorize an inbound request. Enforcement is active only when EL_HTTP_AUTH_KEY
- * is set; otherwise every request is allowed (dev default). GET/HEAD /health*
- * are always allowed so launch-agent liveness probes work without the key. */
-static int el_http_request_authorized(const char* method, const char* path,
-                                      const char* hdr_block) {
-    const char* key = getenv("EL_HTTP_AUTH_KEY");
-    if (!key || !*key) return 1;
-    if (method && (strcmp(method, "GET") == 0 || strcmp(method, "HEAD") == 0)
-        && path && strncmp(path, "/health", 7) == 0) return 1;
-    return el_http_header_equals(hdr_block, "x-neuron-auth", key);
-}
-
-/* Minimal 401 for unauthorized requests — never reaches an EL handler. */
-static void el_http_send_401(int fd) {
-    static const char* body = "{\"error\":\"unauthorized\",\"code\":\"auth_required\"}";
-    char resp[256];
-    int n = snprintf(resp, sizeof(resp),
-                     "HTTP/1.1 401 Unauthorized\r\n"
-                     "Content-Type: application/json\r\n"
-                     "Content-Length: %zu\r\n"
-                     "Connection: close\r\n\r\n%s",
-                     strlen(body), body);
-    if (n > 0) http_send_all(fd, resp, (size_t)n);
-}
-
 el_val_t http_serve(el_val_t port, el_val_t handler) {
     /* If `handler` looks like a string name, register it as the active handler. */
     const char* hname = EL_CSTR(handler);
@@ -1728,13 +1632,13 @@ el_val_t http_serve(el_val_t port, el_val_t handler) {
     struct sockaddr_in6 addr;
     memset(&addr, 0, sizeof(addr));
     addr.sin6_family = AF_INET6;
-    el_http_apply_bind_addr(&addr);
+    addr.sin6_addr = in6addr_any;
     addr.sin6_port = htons((uint16_t)p);
     if (bind(sock, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
         perror("bind"); el_closesocket(sock); return 0;
     }
     if (listen(sock, 64) < 0) { perror("listen"); el_closesocket(sock); return 0; }
-    fprintf(stderr, "[http] listening on %s port %d\n", el_http_bind_desc(), p);
+    fprintf(stderr, "[http] listening on [::]:%d (dual-stack)\n", p);
     while (1) {
         struct sockaddr_in6 cli;
         socklen_t clen = sizeof(cli);
@@ -1940,10 +1844,20 @@ static void* http_worker_v2(void* arg) {
             el_val_t hmap = http_build_headers_map(hdr_block ? hdr_block : "");
             el_val_t r = h(EL_STR(dispatch_method), EL_STR(path), hmap, EL_STR(body));
             const char* rs = EL_CSTR(r);
-            size_t rlen = _tl_fs_read_len > 0 ? _tl_fs_read_len : (rs ? strlen(rs) : 0);
+            /* Same pairing rule as the v1 worker: the fs_read length is only
+             * trustworthy for the exact buffer fs_read returned. */
+            size_t rlen;
+            if (_tl_fs_read_len > 0 && rs && rs == _tl_fs_read_buf) {
+                rlen = _tl_fs_read_len;   /* raw file bytes — binary-safe */
+            } else {
+                rlen = rs ? strlen(rs) : 0;
+                _tl_fs_read_len = 0;      /* hint doesn't describe this body */
+                _tl_fs_read_buf = NULL;
+            }
             response = malloc(rlen + 1);
             if (response && rs) { memcpy(response, rs, rlen); response[rlen] = '\0'; }
             else if (response) { response[0] = '\0'; }
+            if (_tl_fs_read_len > 0) _tl_fs_read_buf = response; /* hint follows the copy */
             el_release(hmap);
         } else {
             response = el_strdup_persist(
@@ -1984,13 +1898,13 @@ el_val_t http_serve_v2(el_val_t port, el_val_t handler) {
     struct sockaddr_in6 addr;
     memset(&addr, 0, sizeof(addr));
     addr.sin6_family = AF_INET6;
-    el_http_apply_bind_addr(&addr);
+    addr.sin6_addr = in6addr_any;
     addr.sin6_port = htons((uint16_t)p);
     if (bind(sock, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
         perror("bind"); el_closesocket(sock); return 0;
     }
     if (listen(sock, 64) < 0) { perror("listen"); el_closesocket(sock); return 0; }
-    fprintf(stderr, "[http v2] listening on %s port %d\n", el_http_bind_desc(), p);
+    fprintf(stderr, "[http v2] listening on [::]:%d (dual-stack)\n", p);
     while (1) {
         struct sockaddr_in6 cli;
         socklen_t clen = sizeof(cli);
@@ -2081,18 +1995,19 @@ void http_serve_async(el_val_t port, el_val_t handler) {
     int sock = socket(AF_INET6, SOCK_STREAM, 0);
     if (sock < 0) { perror("socket"); return; }
     int yes = 1; int no = 0;
-    setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, &yes, sizeof(yes));
-    setsockopt(sock, IPPROTO_IPV6, IPV6_V6ONLY, &no, sizeof(no));
+    /* Win32/mingw setsockopt takes optval as (const char*); the cast is portable on POSIX too. */
+    setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, (const char*)&yes, sizeof(yes));
+    setsockopt(sock, IPPROTO_IPV6, IPV6_V6ONLY, (const char*)&no, sizeof(no));
     struct sockaddr_in6 addr;
     memset(&addr, 0, sizeof(addr));
     addr.sin6_family = AF_INET6;
-    el_http_apply_bind_addr(&addr);
+    addr.sin6_addr = in6addr_any;
     addr.sin6_port = htons((uint16_t)p);
     if (bind(sock, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
         perror("bind"); close(sock); return;
     }
     if (listen(sock, 64) < 0) { perror("listen"); close(sock); return; }
-    fprintf(stderr, "[http] async listening on %s port %d\n", el_http_bind_desc(), p);
+    fprintf(stderr, "[http] async listening on [::]:%d (dual-stack)\n", p);
     HttpServeAsyncArg* a = malloc(sizeof(HttpServeAsyncArg));
     if (!a) { close(sock); return; }
     a->sock = sock;
@@ -2141,6 +2056,7 @@ el_val_t http_response(el_val_t status, el_val_t headers_json, el_val_t body) {
 el_val_t fs_read(el_val_t pathv) {
     const char* path = EL_CSTR(pathv);
     _tl_fs_read_len = 0;
+    _tl_fs_read_buf = NULL;
     if (!path) return el_wrap_str(el_strdup(""));
     FILE* f = fopen(path, "rb");
     if (!f) return el_wrap_str(el_strdup(""));
@@ -2152,6 +2068,7 @@ el_val_t fs_read(el_val_t pathv) {
     size_t got = fread(buf, 1, (size_t)sz, f);
     buf[got] = '\0';
     _tl_fs_read_len = got;   /* store real byte count for binary-safe send */
+    _tl_fs_read_buf = buf;   /* ...valid ONLY for this exact buffer */
     fclose(f);
     return el_wrap_str(buf);
 }
@@ -3257,72 +3174,10 @@ static char* jp_parse_string_raw(JsonParser* jp) {
                 case 'r':  c = '\r'; break;
                 case 't':  c = '\t'; break;
                 case 'u': {
-                    /* Decode \uXXXX (with surrogate pairs) to UTF-8.
-                     * Ported from lang/releases/v1.0.0-20260501 (2026-08-08
-                     * self-review). This copy carried the identical defect:
-                     * the escape was skipped and a literal '?' emitted, which
-                     * silently destroyed every non-ASCII character in any JSON
-                     * string entering the runtime. Two copies of one parser
-                     * bug is exactly how this class of fault survives, so the
-                     * fix lands in both. See the release copy for the full
-                     * measurement and rationale. */
-                    unsigned cp = 0;
-                    int ok = 1;
-                    for (int i = 0; i < 4; i++) {
-                        if (jp->p >= jp->end) { ok = 0; break; }
-                        char h = *jp->p++;
-                        unsigned d;
-                        if      (h >= '0' && h <= '9') d = (unsigned)(h - '0');
-                        else if (h >= 'a' && h <= 'f') d = (unsigned)(h - 'a' + 10);
-                        else if (h >= 'A' && h <= 'F') d = (unsigned)(h - 'A' + 10);
-                        else { ok = 0; break; }
-                        cp = (cp << 4) | d;
-                    }
-                    if (!ok) { c = '?'; break; }
-                    if (cp >= 0xD800 && cp <= 0xDBFF &&
-                        (size_t)(jp->end - jp->p) >= 6 &&
-                        jp->p[0] == '\\' && jp->p[1] == 'u') {
-                        const char* save = jp->p;
-                        unsigned lo = 0; int ok2 = 1;
-                        jp->p += 2;
-                        for (int i = 0; i < 4; i++) {
-                            char h = *jp->p++;
-                            unsigned d;
-                            if      (h >= '0' && h <= '9') d = (unsigned)(h - '0');
-                            else if (h >= 'a' && h <= 'f') d = (unsigned)(h - 'a' + 10);
-                            else if (h >= 'A' && h <= 'F') d = (unsigned)(h - 'A' + 10);
-                            else { ok2 = 0; break; }
-                            lo = (lo << 4) | d;
-                        }
-                        if (ok2 && lo >= 0xDC00 && lo <= 0xDFFF)
-                            cp = 0x10000u + ((cp - 0xD800u) << 10) + (lo - 0xDC00u);
-                        else jp->p = save;
-                    }
-                    if (cp >= 0xD800 && cp <= 0xDFFF) cp = 0xFFFD;
-
-                    char ub[4]; int un;
-                    if (cp < 0x80) {
-                        ub[0] = (char)cp; un = 1;
-                    } else if (cp < 0x800) {
-                        ub[0] = (char)(0xC0 | (cp >> 6));
-                        ub[1] = (char)(0x80 | (cp & 0x3F)); un = 2;
-                    } else if (cp < 0x10000) {
-                        ub[0] = (char)(0xE0 | (cp >> 12));
-                        ub[1] = (char)(0x80 | ((cp >> 6) & 0x3F));
-                        ub[2] = (char)(0x80 | (cp & 0x3F)); un = 3;
-                    } else {
-                        ub[0] = (char)(0xF0 | (cp >> 18));
-                        ub[1] = (char)(0x80 | ((cp >> 12) & 0x3F));
-                        ub[2] = (char)(0x80 | ((cp >> 6) & 0x3F));
-                        ub[3] = (char)(0x80 | (cp & 0x3F)); un = 4;
-                    }
-                    while (len + (size_t)un >= cap) {
-                        cap *= 2;
-                        out = realloc(out, cap);
-                        if (!out) { fputs("el_runtime: out of memory\n", stderr); exit(1); }
-                    }
-                    for (int i = 0; i < un; i++) out[len++] = ub[i];
-                    continue; /* bytes already appended */
+                    /* Skip 4 hex digits; emit '?' as a placeholder */
+                    for (int i = 0; i < 4 && jp->p < jp->end; i++) jp->p++;
+                    c = '?';
+                    break;
                 }
                 default: c = esc; break;
             }
@@ -3756,8 +3611,10 @@ el_val_t json_get_raw(el_val_t json_str, el_val_t key) {
     const char* k    = EL_CSTR(key);
     const char* p = json_find_key(json, k);
     /* Clear fs_read binary-length hint — result is a fresh null-terminated
-     * string, not the raw file bytes, so Content-Length must use strlen. */
+     * string, not the raw file bytes, so Content-Length must use strlen.
+     * (Kept although the pointer pairing now makes this redundant.) */
     _tl_fs_read_len = 0;
+    _tl_fs_read_buf = NULL;
     if (!p) return el_wrap_str(el_strdup(""));
     const char* end = json_skip_value(p);
     size_t n = (size_t)(end - p);
@@ -6228,13 +6085,6 @@ void el_cgi_init(el_val_t name, el_val_t dharma_id, el_val_t principal,
 #define ENGRAM_SUPPRESSION_BREAKTHROUGH 5
 #define ENGRAM_BREAKTHROUGH_WEIGHT   0.25
 #define ENGRAM_INHIBITION_FACTOR     0.1
-/* ENGRAM_WM_CAP: hard global ceiling on nodes holding working_memory_weight
- * > 0 at any time. Cowan (2001) puts human WM capacity at ~4 chunks; 24 gives
- * the daemon generous headroom while preventing the unbounded growth observed
- * in production (wm_active 288-778 per heartbeat — "working memory" that is
- * really the whole recently-touched graph). Ported from release runtime
- * v1.0.0-20260501 Pass 5 on 2026-07-15 self-review. */
-#define ENGRAM_WM_CAP                24
 
 /* ── Layered consciousness architecture ──────────────────────────────────────
  *
@@ -7082,6 +6932,243 @@ static int engram_rank_cmp(const void* a, const void* b) {
     return 0;
 }
 
+/* ══════════════════════════════════════════════════════════════════════════
+ * SEMANTIC SEARCH LAYER — nomic-embed-text via Ollama /api/embeddings
+ * ──────────────────────────────────────────────────────────────────────────
+ * Augments the lexical (istr_contains) matcher with dense-vector retrieval.
+ * Node content and the query are embedded through a local Ollama server;
+ * nodes are ranked by cosine similarity and UNIONED with lexical hits. This
+ * lets a paraphrase query surface a node whose words never appear in it.
+ *
+ * DEGRADABLE BY DESIGN. The whole layer is gated on HAVE_CURL plus a one-shot
+ * runtime probe of the embedding endpoint. If curl is not compiled in, or
+ * Ollama is unreachable, or ENGRAM_SEMANTIC=0, every entry point returns
+ * "no semantic signal" and callers fall back to pure lexical behaviour —
+ * byte-for-byte the pre-existing search.
+ *
+ * CACHE. Node embeddings are computed lazily on first use and cached in
+ * process memory keyed by node id, with an FNV-1a content hash for
+ * invalidation (edited content re-embeds). The query is embedded once per
+ * search call. This is what "avoid re-embedding the whole graph every query"
+ * buys us: a warm cache serves cosine from RAM. (A cold process still pays
+ * O(N) embed calls the first time each node is scanned — persisting the cache
+ * to a snapshot sidecar is the documented next step, not done here.)
+ *
+ * nomic task prefixes ("search_query:" / "search_document:") are applied
+ * because nomic-embed-text is trained with them; they materially improve
+ * retrieval separation (empirically: paraphrase 0.72 vs distractors <0.48).
+ *
+ * ENV:
+ *   ENGRAM_SEMANTIC       "0" disables; unset/other = auto-probe
+ *   ENGRAM_EMBED_URL      default http://localhost:11434/api/embeddings
+ *   ENGRAM_EMBED_MODEL    default nomic-embed-text
+ *   ENGRAM_SEMANTIC_MIN   cosine threshold for a pure-semantic match (def 0.6)
+ * ════════════════════════════════════════════════════════════════════════ */
+
+static double engram_semantic_min(void) {
+    static double v = -1.0;
+    if (v >= 0.0) return v;
+    const char* s = getenv("ENGRAM_SEMANTIC_MIN");
+    double d = 0.6;
+    if (s && *s) { char* e = NULL; double t = strtod(s, &e);
+                   if (e != s && t >= 0.0 && t <= 1.0) d = t; }
+    v = d; return v;
+}
+
+#ifdef HAVE_CURL
+
+typedef struct { char* id; uint64_t hash; float* vec; int dim; } EngramEmbEntry;
+static EngramEmbEntry* g_emb_items = NULL;
+static int64_t g_emb_count = 0, g_emb_cap = 0;
+static int g_emb_state = 0;   /* 0=unprobed, 1=available, -1=disabled */
+
+static uint64_t engram_fnv1a(const char* s) {
+    uint64_t h = 1469598103934665603ULL;
+    if (s) for (const unsigned char* p = (const unsigned char*)s; *p; p++) {
+        h ^= *p; h *= 1099511628211ULL;
+    }
+    return h;
+}
+
+/* Parse "embedding":[f,f,...] from an Ollama response. malloc'd vec, or NULL. */
+static float* engram_parse_embedding(const char* json, int* out_dim) {
+    if (!json) return NULL;
+    const char* p = strstr(json, "\"embedding\"");
+    if (!p) return NULL;
+    p = strchr(p, '[');
+    if (!p) return NULL;
+    p++;
+    int cap = 1024, n = 0;
+    float* v = malloc((size_t)cap * sizeof(float));
+    if (!v) return NULL;
+    while (*p && *p != ']') {
+        while (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r' || *p == ',') p++;
+        if (*p == ']' || !*p) break;
+        char* e = NULL;
+        double d = strtod(p, &e);
+        if (e == p) break;
+        if (n >= cap) { cap *= 2; float* nv = realloc(v, (size_t)cap * sizeof(float));
+                        if (!nv) { free(v); return NULL; } v = nv; }
+        v[n++] = (float)d;
+        p = e;
+    }
+    if (n == 0) { free(v); return NULL; }
+    *out_dim = n;
+    return v;
+}
+
+/* JSON-escape src into a malloc'd buffer (no surrounding quotes). */
+static char* engram_json_escape(const char* src) {
+    if (!src) src = "";
+    size_t n = strlen(src);
+    char* out = malloc(n * 2 + 1);
+    if (!out) return NULL;
+    size_t j = 0;
+    for (size_t i = 0; i < n; i++) {
+        unsigned char c = (unsigned char)src[i];
+        if      (c == '"')  { out[j++] = '\\'; out[j++] = '"'; }
+        else if (c == '\\') { out[j++] = '\\'; out[j++] = '\\'; }
+        else if (c == '\n') { out[j++] = '\\'; out[j++] = 'n'; }
+        else if (c == '\r') { out[j++] = '\\'; out[j++] = 'r'; }
+        else if (c == '\t') { out[j++] = '\\'; out[j++] = 't'; }
+        else if (c < 0x20)  { /* drop other control bytes */ }
+        else                { out[j++] = (char)c; }
+    }
+    out[j] = '\0';
+    return out;
+}
+
+/* Embed `prefix+text` via Ollama. Returns malloc'd vec (caller frees), or NULL. */
+static float* engram_embed_raw(const char* prefix, const char* text, int* out_dim) {
+    if (!text) return NULL;
+    const char* url = getenv("ENGRAM_EMBED_URL");
+    if (!url || !*url) url = "http://localhost:11434/api/embeddings";
+    const char* model = getenv("ENGRAM_EMBED_MODEL");
+    if (!model || !*model) model = "nomic-embed-text";
+    /* Bound content length to keep latency/memory sane on huge nodes. */
+    char* trunc = NULL;
+    size_t maxlen = 8192;
+    if (strlen(text) > maxlen) {
+        trunc = malloc(maxlen + 1);
+        if (trunc) { memcpy(trunc, text, maxlen); trunc[maxlen] = '\0'; text = trunc; }
+    }
+    char* esc_prefix = engram_json_escape(prefix ? prefix : "");
+    char* esc = engram_json_escape(text);
+    free(trunc);
+    if (!esc || !esc_prefix) { free(esc); free(esc_prefix); return NULL; }
+    size_t blen = strlen(esc) + strlen(esc_prefix) + strlen(model) + 64;
+    char* body = malloc(blen);
+    if (!body) { free(esc); free(esc_prefix); return NULL; }
+    snprintf(body, blen, "{\"model\":\"%s\",\"prompt\":\"%s%s\"}", model, esc_prefix, esc);
+    free(esc); free(esc_prefix);
+
+    CURL* c = curl_easy_init();
+    if (!c) { free(body); return NULL; }
+    HttpBuf rb; httpbuf_init(&rb);
+    struct curl_slist* h = curl_slist_append(NULL, "Content-Type: application/json");
+    char errbuf[CURL_ERROR_SIZE]; errbuf[0] = '\0';
+    curl_easy_setopt(c, CURLOPT_URL, url);
+    curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, http_write_cb);
+    curl_easy_setopt(c, CURLOPT_WRITEDATA, &rb);
+    curl_easy_setopt(c, CURLOPT_POST, 1L);
+    curl_easy_setopt(c, CURLOPT_POSTFIELDS, body);
+    curl_easy_setopt(c, CURLOPT_POSTFIELDSIZE, (long)strlen(body));
+    curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
+    curl_easy_setopt(c, CURLOPT_TIMEOUT_MS, el_http_timeout_ms());
+    curl_easy_setopt(c, CURLOPT_NOSIGNAL, 1L);
+    curl_easy_setopt(c, CURLOPT_ERRORBUFFER, errbuf);
+    CURLcode rc = curl_easy_perform(c);
+    curl_slist_free_all(h);
+    curl_easy_cleanup(c);
+    free(body);
+    if (rc != CURLE_OK) { free(rb.data); return NULL; }
+    float* v = engram_parse_embedding(rb.data, out_dim);
+    free(rb.data);
+    return v;
+}
+
+/* One-shot probe: is semantic search available? Caches the verdict. */
+static int engram_semantic_enabled(void) {
+    if (g_emb_state != 0) return g_emb_state == 1;
+    const char* s = getenv("ENGRAM_SEMANTIC");
+    if (s && strcmp(s, "0") == 0) { g_emb_state = -1; return 0; }
+    int dim = 0;
+    float* v = engram_embed_raw("search_query: ", "probe", &dim);
+    if (v && dim > 0) { free(v); g_emb_state = 1; return 1; }
+    free(v);
+    g_emb_state = -1; return 0;
+}
+
+/* Embed the query. Returns malloc'd vec (caller frees), or NULL if semantic off. */
+static float* engram_embed_query(const char* q, int* dim) {
+    if (!engram_semantic_enabled()) return NULL;
+    if (!q || !*q) return NULL;
+    return engram_embed_raw("search_query: ", q, dim);
+}
+
+/* Cached node embedding. Returns a pointer OWNED BY THE CACHE — do not free. */
+static const float* engram_node_vec(EngramNode* n, int* out_dim) {
+    if (!n || !n->id) return NULL;
+    uint64_t h = engram_fnv1a(n->content);
+    for (int64_t i = 0; i < g_emb_count; i++) {
+        if (g_emb_items[i].id && strcmp(g_emb_items[i].id, n->id) == 0) {
+            if (g_emb_items[i].hash == h && g_emb_items[i].vec) {
+                *out_dim = g_emb_items[i].dim; return g_emb_items[i].vec;
+            }
+            /* content changed → re-embed in place */
+            int dim = 0;
+            float* v = engram_embed_raw("search_document: ", n->content ? n->content : "", &dim);
+            if (!v) return NULL;
+            free(g_emb_items[i].vec);
+            g_emb_items[i].vec = v; g_emb_items[i].dim = dim; g_emb_items[i].hash = h;
+            *out_dim = dim; return v;
+        }
+    }
+    int dim = 0;
+    float* v = engram_embed_raw("search_document: ", n->content ? n->content : "", &dim);
+    if (!v) return NULL;
+    if (g_emb_count >= g_emb_cap) {
+        int64_t nc = g_emb_cap ? g_emb_cap * 2 : 256;
+        EngramEmbEntry* ni = realloc(g_emb_items, (size_t)nc * sizeof(EngramEmbEntry));
+        if (!ni) { free(v); return NULL; }
+        g_emb_items = ni; g_emb_cap = nc;
+    }
+    g_emb_items[g_emb_count].id   = strdup(n->id);
+    g_emb_items[g_emb_count].hash = h;
+    g_emb_items[g_emb_count].vec  = v;
+    g_emb_items[g_emb_count].dim  = dim;
+    g_emb_count++;
+    *out_dim = dim; return v;
+}
+
+static double engram_cosine(const float* a, const float* b, int dim) {
+    double dot = 0, na = 0, nb = 0;
+    for (int i = 0; i < dim; i++) { dot += (double)a[i] * b[i];
+                                    na  += (double)a[i] * a[i];
+                                    nb  += (double)b[i] * b[i]; }
+    if (na <= 0 || nb <= 0) return 0.0;
+    return dot / (sqrt(na) * sqrt(nb));
+}
+
+/* Cosine of node n against the query vector; 0 if unavailable / dim mismatch. */
+static double engram_node_cosine(EngramNode* n, const float* qvec, int qdim) {
+    if (!qvec || qdim <= 0) return 0.0;
+    int ndim = 0;
+    const float* nv = engram_node_vec(n, &ndim);
+    if (!nv || ndim != qdim) return 0.0;
+    return engram_cosine(qvec, nv, qdim);
+}
+
+#else  /* !HAVE_CURL — semantic layer compiled out; callers stay pure-lexical.
+        * Only the two boundary functions the always-compiled search/activate
+        * code calls are stubbed; the query embed always yields NULL so every
+        * cosine is 0 and every caller collapses to lexical-only. */
+static float* engram_embed_query(const char* q, int* dim) { (void)q; (void)dim; return NULL; }
+static double engram_node_cosine(EngramNode* n, const float* qvec, int qdim) {
+    (void)n; (void)qvec; (void)qdim; return 0.0;
+}
+#endif /* HAVE_CURL */
+
 el_val_t engram_search(el_val_t query, el_val_t limit) {
     EngramStore* g = engram_get();
     const char* q = EL_CSTR(query);
@@ -7092,8 +7179,15 @@ el_val_t engram_search(el_val_t query, el_val_t limit) {
     char toks[ENGRAM_MAX_QTOKENS][ENGRAM_QTOK_LEN];
     int ntok = engram_tokenize_query(q, toks, ENGRAM_MAX_QTOKENS);
     if (ntok == 0) return lst;
+    /* Semantic augmentation: embed the query once; a node is a hit if it covers
+     * >=1 query token (tokenized-lexical, #66) OR its cosine clears the
+     * threshold (#67). qvec is NULL (cosine 0) when semantic is unavailable →
+     * pure tokenized-lexical, byte-identical to the lexical-only behaviour. */
+    int qdim = 0;
+    float* qvec = engram_embed_query(q, &qdim);
+    double sem_min = engram_semantic_min();
     EngramRankEntry* hits = malloc((size_t)g->node_count * sizeof(EngramRankEntry));
-    if (!hits) return lst;
+    if (!hits) { free(qvec); return lst; }
     int64_t nhits = 0;
     for (int64_t i = 0; i < g->node_count; i++) {
         EngramNode* n = &g->nodes[i];
@@ -7103,20 +7197,24 @@ el_val_t engram_search(el_val_t query, el_val_t limit) {
          * + engram_compile_layered_json — that's the legitimate path. */
         if (engram_layer_is_transparent(n->layer_id)) continue;
         int sc = engram_node_match_score(n, toks, ntok);
-        if (sc > 0) {
+        double sem = qvec ? engram_node_cosine(n, qvec, qdim) : 0.0;
+        if (sc > 0 || sem >= sem_min) {
             hits[nhits].idx      = i;
             hits[nhits].score    = sc;
             hits[nhits].salience = n->salience;
             nhits++;
         }
     }
-    /* Rank by distinct tokens matched (desc) then salience (desc), then cap. */
+    /* Rank by distinct tokens matched (desc) then salience (desc), then cap.
+     * Pure-semantic hits (token score 0) sort after every lexical hit — a
+     * lexical ∪ semantic union with lexical precedence. */
     qsort(hits, (size_t)nhits, sizeof(EngramRankEntry), engram_rank_cmp);
     int64_t end = nhits < lim ? nhits : lim;
     for (int64_t k = 0; k < end; k++) {
         lst = el_list_append(lst, engram_node_to_map(&g->nodes[hits[k].idx]));
     }
     free(hits);
+    free(qvec);
     return lst;
 }
 
@@ -7439,48 +7537,6 @@ static double engram_goal_bias(const EngramNode* n, const char* query) {
     return bias;
 }
 
-/* eg_cmp_double_desc — qsort comparator, descending doubles. */
-static int eg_cmp_double_desc(const void* a, const void* b) {
-    double da = *(const double*)a, db = *(const double*)b;
-    if (da < db) return 1;
-    if (da > db) return -1;
-    return 0;
-}
-
-/* eg_enforce_wm_cap_global — clamp the store-wide working-memory population
- * to ENGRAM_WM_CAP, keeping the top-K by current weight. Runs at every point
- * that materializes WM: post-activation persist and snapshot load/merge.
- * (Ported from release runtime v1.0.0-20260501 Pass 5, 2026-07-15.) */
-static void eg_enforce_wm_cap_global(EngramStore* g) {
-    int64_t wm_count = 0;
-    for (int64_t i = 0; i < g->node_count; i++) {
-        if (g->nodes[i].working_memory_weight > 0.0) wm_count++;
-    }
-    if (wm_count <= ENGRAM_WM_CAP) return;
-    double* vals = malloc((size_t)wm_count * sizeof(double));
-    if (!vals) return; /* OOM: over cap this call, no corruption */
-    int64_t vi = 0;
-    for (int64_t i = 0; i < g->node_count; i++) {
-        if (g->nodes[i].working_memory_weight > 0.0)
-            vals[vi++] = g->nodes[i].working_memory_weight;
-    }
-    qsort(vals, (size_t)wm_count, sizeof(double), eg_cmp_double_desc);
-    double cutoff = vals[ENGRAM_WM_CAP - 1];
-    free(vals);
-    int64_t above = 0;
-    for (int64_t i = 0; i < g->node_count; i++) {
-        if (g->nodes[i].working_memory_weight > cutoff) above++;
-    }
-    int64_t slots_at_cutoff = ENGRAM_WM_CAP - above;
-    for (int64_t i = 0; i < g->node_count; i++) {
-        EngramNode* n = &g->nodes[i];
-        if (n->working_memory_weight <= 0.0) continue;
-        if (n->working_memory_weight > cutoff) continue;
-        if (slots_at_cutoff > 0) { slots_at_cutoff--; continue; }
-        n->working_memory_weight = 0.0; /* evict: over global cap */
-    }
-}
-
 el_val_t engram_activate(el_val_t query, el_val_t depth) {
     EngramStore* g = engram_get();
     const char* q = EL_CSTR(query);
@@ -7508,21 +7564,31 @@ el_val_t engram_activate(el_val_t query, el_val_t depth) {
     if (!seeds) {
         free(best_bg); free(best_hops); free(reached); return out;
     }
-    /* Tokenize once: a node seeds if it matches ANY query token, and its seed
-     * activation is scaled by token coverage (fraction of distinct query
-     * tokens it contains) so a node matching all words seeds more strongly
-     * than one matching a single word. Single-word queries → coverage 1.0,
-     * identical to the prior whole-query behavior. */
+    /* Tokenized + semantic seeding: a node seeds if it covers >=1 query token
+     * (tokenized-lexical, #66) OR its cosine clears the threshold (#67). A
+     * lexical seed's activation is scaled by token coverage (fraction of
+     * distinct query tokens covered) so a node matching all words seeds more
+     * strongly than one matching a single word; single-word queries → coverage
+     * 1.0. A pure-semantic seed (no token match) is instead down-weighted by
+     * its cosine so paraphrase matches spread without overpowering exact seeds.
+     * q_vec is NULL (cosine 0) when semantic is unavailable → the seed set is
+     * exactly the tokenized-lexical one. q_vec is freed right after this loop
+     * so the many downstream early-returns need no cleanup change. */
     char toks[ENGRAM_MAX_QTOKENS][ENGRAM_QTOK_LEN];
     int ntok = engram_tokenize_query(q, toks, ENGRAM_MAX_QTOKENS);
+    int q_dim = 0;
+    float* q_vec = engram_embed_query(q, &q_dim);
+    double q_sem_min = engram_semantic_min();
     for (int64_t i = 0; i < g->node_count; i++) {
         EngramNode* n = &g->nodes[i];
         int sc = engram_node_match_score(n, toks, ntok);
-        if (sc > 0) {
+        double sem = q_vec ? engram_node_cosine(n, q_vec, q_dim) : 0.0;
+        if (sc > 0 || sem >= q_sem_min) {
             double tdecay = engram_temporal_decay(n, now_ms);
             double dampen = engram_activation_dampen(n);
-            double cover  = ntok > 0 ? (double)sc / (double)ntok : 1.0;
-            double act    = n->salience * tdecay * dampen * cover;
+            double act    = n->salience * tdecay * dampen;
+            if (sc > 0) act *= (ntok > 0 ? (double)sc / (double)ntok : 1.0);
+            else        act *= sem;  /* pure-semantic seed: down-weight by cosine */
             seeds[seed_count].idx        = i;
             seeds[seed_count].act        = act;
             seeds[seed_count].created_at = n->created_at;
@@ -7532,6 +7598,7 @@ el_val_t engram_activate(el_val_t query, el_val_t depth) {
             reached[i]   = 1;
         }
     }
+    free(q_vec);
     /* Compute mean seed created_at for temporal proximity bonus. */
     int64_t seed_epoch = 0;
     if (seed_count > 0) {
@@ -7686,12 +7753,6 @@ el_val_t engram_activate(el_val_t query, el_val_t depth) {
         g->nodes[i].working_memory_weight = wm_weights[i];
     }
 
-    /* Global WM cap: keep only the top ENGRAM_WM_CAP by weight across the
-     * whole store (see eg_enforce_wm_cap_global). Without this, repeated
-     * activation calls accumulate hundreds of "promoted" nodes and WM stops
-     * meaning anything (production heartbeats showed wm_active up to 778). */
-    eg_enforce_wm_cap_global(g);
-
     /* ── Collect all background-activated nodes for the return value ────
      * Callers see both layers. Context compilation uses only promoted nodes
      * (working_memory_weight > 0). Sort: promoted first by wm_weight desc,
@@ -8069,9 +8130,6 @@ el_val_t engram_load(el_val_t path) {
             }
         }
     }
-    /* WM cap discipline applies to every entry point that materializes WM,
-     * including snapshot restore (see eg_enforce_wm_cap_global). */
-    eg_enforce_wm_cap_global(g);
     free(data);
     return 1;
 }
@@ -8096,14 +8154,16 @@ el_val_t engram_get_node_json(el_val_t id) {
  * matches the given string. Returns the node as a JSON object string, or "{}"
  * if no match is found.
  *
- * Exact match (strcmp, not substring) because labels like "conv:history"
- * must not collide with nodes whose content contains that substring.
+ * Used by chat.el to retrieve well-known nodes (e.g. "conv:history",
+ * "session:summary") by their stable label rather than by ID, which is immune
+ * to vector index drift across restarts.
  *
- * Ported from the release runtime 2026-07-16 self-review: chat.el has called
- * this since 2026-07-01 but the function only existed in
- * releases/v1.0.0-20260501/el_runtime.c — the soul daemon (which builds
- * against THIS runtime) failed to compile once clang made implicit
- * declarations an error. */
+ * Exact match (strcmp, not istr_contains) because labels like "conv:history"
+ * must not collide with nodes whose content happens to contain that substring.
+ *
+ * Backported verbatim (idiom-adapted to jb_finish) from release runtime
+ * v1.0.0-20260501 to unblock the soul regen link: chat.el references this
+ * native but the current runtime lacked its definition. */
 el_val_t engram_get_node_by_label(el_val_t label) {
     const char* lbl = EL_CSTR(label);
     if (!lbl || !*lbl) return el_wrap_str(el_strdup("{}"));
@@ -8126,39 +8186,50 @@ el_val_t engram_search_json(el_val_t query, el_val_t limit) {
     if (lim <= 0) lim = 100;
     JsonBuf b; jb_init(&b);
     jb_putc(&b, '[');
-    int first = 1;
-    if (q && *q) {
+    if (q && *q && g->node_count > 0) {
+        /* Collect candidates from the UNION of tokenized-lexical and semantic
+         * matches, score each, rank by score, emit the top `lim`. A node is a
+         * candidate if it covers >=1 query token (tokenized-lexical, #66) OR its
+         * query cosine clears the threshold (#67). Lexical score is the distinct
+         * token count (>=1), so any lexical hit outranks a pure-semantic hit
+         * (cosine < 1); pure-semantic hits are scored by cosine alone. When
+         * semantic is unavailable qvec is NULL, sem is 0, only tokenized-lexical
+         * hits are collected, and the stable insertion sort preserves order. */
         char toks[ENGRAM_MAX_QTOKENS][ENGRAM_QTOK_LEN];
         int ntok = engram_tokenize_query(q, toks, ENGRAM_MAX_QTOKENS);
-        if (ntok > 0) {
-            EngramRankEntry* hits =
-                malloc((size_t)g->node_count * sizeof(EngramRankEntry));
-            if (hits) {
-                int64_t nhits = 0;
-                for (int64_t i = 0; i < g->node_count; i++) {
-                    EngramNode* n = &g->nodes[i];
-                    /* Filter transparent layers — same as engram_search. */
-                    if (engram_layer_is_transparent(n->layer_id)) continue;
-                    int sc = engram_node_match_score(n, toks, ntok);
-                    if (sc > 0) {
-                        hits[nhits].idx      = i;
-                        hits[nhits].score    = sc;
-                        hits[nhits].salience = n->salience;
-                        nhits++;
-                    }
+        int qdim = 0;
+        float* qvec = engram_embed_query(q, &qdim);
+        double sem_min = engram_semantic_min();
+        typedef struct { int64_t idx; double score; } Cand;
+        Cand* cand = malloc((size_t)g->node_count * sizeof(Cand));
+        if (cand) {
+            int64_t nc = 0;
+            for (int64_t i = 0; i < g->node_count; i++) {
+                EngramNode* n = &g->nodes[i];
+                if (engram_layer_is_transparent(n->layer_id)) continue;
+                int sc = engram_node_match_score(n, toks, ntok);
+                double sem = qvec ? engram_node_cosine(n, qvec, qdim) : 0.0;
+                if (sc > 0 || sem >= sem_min) {
+                    cand[nc].idx   = i;
+                    cand[nc].score = (double)sc + sem;
+                    nc++;
                 }
-                /* Rank by distinct tokens matched (desc) then salience (desc). */
-                qsort(hits, (size_t)nhits, sizeof(EngramRankEntry),
-                      engram_rank_cmp);
-                int64_t end = nhits < lim ? nhits : lim;
-                for (int64_t k = 0; k < end; k++) {
-                    if (!first) jb_putc(&b, ',');
-                    engram_emit_node_json(&b, &g->nodes[hits[k].idx]);
-                    first = 0;
-                }
-                free(hits);
             }
+            /* Insertion sort by score desc; stable for equal scores. */
+            for (int64_t i = 1; i < nc; i++) {
+                Cand k = cand[i]; int64_t j = i - 1;
+                while (j >= 0 && cand[j].score < k.score) { cand[j + 1] = cand[j]; j--; }
+                cand[j + 1] = k;
+            }
+            int first = 1;
+            for (int64_t i = 0; i < nc && i < lim; i++) {
+                if (!first) jb_putc(&b, ',');
+                engram_emit_node_json(&b, &g->nodes[cand[i].idx]);
+                first = 0;
+            }
+            free(cand);
         }
+        free(qvec);
     }
     jb_putc(&b, ']');
     return el_wrap_str(jb_finish(&b));
@@ -8676,9 +8747,6 @@ el_val_t engram_load_merge(el_val_t path) {
         }
     }
 
-    /* Merged nodes can carry snapshot WM weights too — hold the cap here as
-     * well (see eg_enforce_wm_cap_global). */
-    eg_enforce_wm_cap_global(g);
     free(data);
     return (el_val_t)added_nodes;
 }

lang/el-compiler/runtime/el_seed.c

@@ -1072,6 +1072,7 @@ el_val_t __engram_save(el_val_t path)                       { return engram_save
 el_val_t __engram_load(el_val_t path)                       { return engram_load(path); }
 
 el_val_t __engram_get_node_json(el_val_t id)               { return engram_get_node_json(id); }
+el_val_t __engram_get_node_by_label(el_val_t label)        { return engram_get_node_by_label(label); }
 
 el_val_t __engram_search_json(el_val_t query, el_val_t limit) {
     return engram_search_json(query, limit);

lang/el-compiler/runtime/el_seed.h

@@ -226,6 +226,7 @@ el_val_t  __engram_activate(el_val_t query, el_val_t depth);
 el_val_t  __engram_save(el_val_t path);
 el_val_t  __engram_load(el_val_t path);
 el_val_t  __engram_get_node_json(el_val_t id);
+el_val_t  __engram_get_node_by_label(el_val_t label);
 el_val_t  __engram_search_json(el_val_t query, el_val_t limit);
 el_val_t  __engram_scan_nodes_json(el_val_t limit, el_val_t offset);
 el_val_t  __engram_scan_nodes_by_type_json(el_val_t node_type, el_val_t limit, el_val_t offset);

lang/el-compiler/src/codegen.el

@@ -2670,6 +2670,7 @@ fn builtin_arity(name: String) -> Int {
     if str_eq(name, "engram_save") { return 1 }
     if str_eq(name, "engram_load") { return 1 }
     if str_eq(name, "engram_get_node_json") { return 1 }
+    if str_eq(name, "engram_get_node_by_label") { return 1 }
     if str_eq(name, "engram_search_json") { return 2 }
     if str_eq(name, "engram_scan_nodes_json") { return 2 }
     if str_eq(name, "engram_neighbors_json") { return 3 }

lang/releases/v1.0.0-20260501/el_platform_win.h

@@ -0,0 +1,186 @@
+#ifndef EL_PLATFORM_WIN_H
+#define EL_PLATFORM_WIN_H
+/*
+ * el_platform_win.h — Windows OS-boundary shim for el_runtime.c.
+ *
+ * Branch: feat/windows-el-runtime. Included ONLY when _WIN32 is defined; the POSIX build is
+ * untouched. Goal: let el_runtime.c (a BSD-sockets / dlfcn / fork host) compile and link with
+ * mingw-w64 into a native neuron.exe, with no behavioural change to the Linux/macOS build.
+ *
+ * What it maps:
+ *   - sockets  : winsock2 (same call names: socket/bind/listen/accept/recv/send/setsockopt).
+ *                Sockets close with closesocket() (see el_closesocket), and the stack must be
+ *                started once with WSAStartup — done automatically via a load-time constructor.
+ *   - dlsym    : el_runtime.c uses dlsym(RTLD_DEFAULT, name) to resolve callback/tool symbols
+ *                exported by the main module. Windows equivalent: GetProcAddress on the process
+ *                module. Link the soul with -Wl,--export-all-symbols so the symbols are findable.
+ *   - popen    : mapped to _popen/_pclose.
+ *   - threads  : UNCHANGED. mingw-w64 ships winpthreads, so <pthread.h> + -lpthread just work.
+ */
+
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#include <windows.h>
+#include <io.h>
+#include <process.h>
+
+/* Portable headers mingw-w64 provides (verified present). */
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>   /* strcasecmp */
+#include <ctype.h>
+#include <math.h>
+#include <time.h>
+#include <sys/time.h>  /* mingw-w64 provides gettimeofday here */
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <dirent.h>
+#include <errno.h>
+#include <pthread.h>
+
+/* ── socket close ─────────────────────────────────────────────────────────── */
+/* Winsock closes sockets with closesocket(), not close() (close() is for file fds). The POSIX
+   build defines the same helper as close() so the call sites are identical across platforms. */
+static inline int el_closesocket(SOCKET s) { return closesocket(s); }
+
+/* ── setsockopt optval type ───────────────────────────────────────────────── */
+/* Winsock's setsockopt takes optval as (const char*); POSIX takes (const void*), so el_runtime.c
+   passes &int directly. GCC 14+ makes that an error under -Wincompatible-pointer-types. Wrap it so
+   the runtime's POSIX-style call sites compile unchanged (defined before the macro so the wrapper
+   itself resolves to the real winsock setsockopt). */
+static inline int el_setsockopt(SOCKET s, int level, int optname, const void* optval, int optlen) {
+    return setsockopt(s, level, optname, (const char*)optval, optlen);
+}
+#define setsockopt(s, l, o, v, n) el_setsockopt((s), (l), (o), (v), (int)(n))
+
+/* ── winsock init (once, at load) ─────────────────────────────────────────── */
+static void el__win_net_init(void) {
+    static int inited = 0;
+    if (!inited) { WSADATA w; WSAStartup(MAKEWORD(2, 2), &w); inited = 1; }
+}
+__attribute__((constructor)) static void el__win_ctor(void) { el__win_net_init(); }
+
+/* ── dlsym → GetProcAddress ───────────────────────────────────────────────── */
+#ifndef RTLD_DEFAULT
+#define RTLD_DEFAULT ((void*)0)
+#endif
+static inline void* el_win_dlsym(void* handle, const char* name) {
+    (void)handle;
+    return (void*)(uintptr_t)GetProcAddress(GetModuleHandleA(NULL), name);
+}
+#define dlsym(h, n) el_win_dlsym((h), (n))
+
+/* ── popen / pclose ───────────────────────────────────────────────────────── */
+#define popen  _popen
+#define pclose _pclose
+
+/* ── misc POSIX → Win32 shims ─────────────────────────────────────────────── */
+#include <direct.h>            /* _mkdir */
+#define mkdir(path, mode) _mkdir(path)     /* POSIX mkdir(path,mode) → _mkdir(path) */
+#define timegm _mkgmtime                   /* UTC tm → time_t */
+
+/* setenv/unsetenv: not in the Windows CRT; map to _putenv_s / SetEnvironmentVariable. */
+static inline int setenv(const char* name, const char* value, int overwrite) {
+    (void)overwrite;
+    return _putenv_s(name, value ? value : "");
+}
+static inline int unsetenv(const char* name) {
+    /* _putenv_s(name, "") sets VAR="" rather than removing it.
+     * SetEnvironmentVariableA(name, NULL) truly deletes it from the Win32
+     * env block; then we sync the CRT cache with _putenv("NAME=").       */
+    SetEnvironmentVariableA(name, NULL);
+    size_t len = strlen(name);
+    char *buf = (char*)malloc(len + 2);
+    if (!buf) return -1;
+    memcpy(buf, name, len);
+    buf[len] = '=';
+    buf[len + 1] = '\0';
+    _putenv(buf);
+    free(buf);
+    return 0;
+}
+
+/* nanosleep — not available in MSVC/UCRT; approximate with Sleep(). */
+static inline int el_nanosleep(const struct timespec *req, struct timespec *rem) {
+    (void)rem;
+    DWORD ms = (DWORD)((req->tv_sec * 1000ULL) + (req->tv_nsec / 1000000ULL));
+    Sleep(ms ? ms : 1);
+    return 0;
+}
+#define nanosleep(req, rem) el_nanosleep((req), (rem))
+
+/* localtime_r/gmtime_r: Windows offers localtime_s/gmtime_s with reversed arg order. */
+static inline struct tm* localtime_r(const time_t* t, struct tm* out) {
+    return localtime_s(out, t) == 0 ? out : (struct tm*)0;
+}
+static inline struct tm* gmtime_r(const time_t* t, struct tm* out) {
+    return gmtime_s(out, t) == 0 ? out : (struct tm*)0;
+}
+
+/* ── libcurl: degradable stubs for the curl-less Windows build ─────────────── */
+/* The curl-less validation build (WITH_CURL=0) links no libcurl. el_runtime.c uses libcurl
+ * unconditionally for its HTTP client / LLM layer; these stubs let it compile and link so the
+ * runtime, HTTP *server*, graph and memory work natively on Windows. Live outbound HTTP/LLM calls
+ * degrade to a runtime error (curl_easy_perform returns an error) — matching the documented
+ * curl-less contract. When HAVE_CURL is defined (WITH_CURL=1) the real <curl/curl.h> is used and
+ * this whole block is compiled out. POSIX never sees this header, so the POSIX build is untouched. */
+#ifndef HAVE_CURL
+
+typedef void CURL;
+typedef int  CURLcode;
+
+#define CURLE_OK                    0
+#define CURLE_HTTP_RETURNED_ERROR   22
+#define CURL_ERROR_SIZE             256
+
+/* Option ids: values are irrelevant to the no-op setopt below; kept distinct for readability. */
+#define CURLOPT_URL              10002
+#define CURLOPT_WRITEFUNCTION    20011
+#define CURLOPT_WRITEDATA        10001
+#define CURLOPT_POSTFIELDS       10015
+#define CURLOPT_POSTFIELDSIZE      120
+#define CURLOPT_POST                47
+#define CURLOPT_HTTPHEADER       10023
+#define CURLOPT_TIMEOUT_MS         155
+#define CURLOPT_NOSIGNAL            99
+#define CURLOPT_USERAGENT        10018
+#define CURLOPT_FOLLOWLOCATION      52
+#define CURLOPT_ERRORBUFFER      10010
+#define CURLOPT_CUSTOMREQUEST    10036
+#define CURLOPT_FAILONERROR         45
+
+struct curl_slist { char* data; struct curl_slist* next; };
+
+static inline struct curl_slist* curl_slist_append(struct curl_slist* list, const char* s) {
+    struct curl_slist* node = (struct curl_slist*)malloc(sizeof(struct curl_slist));
+    if (!node) return list;
+    node->data = s ? strdup(s) : NULL;
+    node->next = NULL;
+    if (!list) return node;
+    struct curl_slist* p = list;
+    while (p->next) p = p->next;
+    p->next = node;
+    return list;
+}
+static inline void curl_slist_free_all(struct curl_slist* list) {
+    while (list) { struct curl_slist* n = list->next; free(list->data); free(list); list = n; }
+}
+
+static inline CURL* curl_easy_init(void) { return (CURL*)malloc(1); }
+static inline CURLcode curl_easy_setopt(CURL* h, int opt, ...) { (void)h; (void)opt; return CURLE_OK; }
+static inline CURLcode curl_easy_perform(CURL* h) { (void)h; return 7 /* CURLE_COULDNT_CONNECT */; }
+static inline void curl_easy_cleanup(CURL* h) { free(h); }
+static inline const char* curl_easy_strerror(CURLcode c) {
+    (void)c; return "libcurl not built in (curl-less build)";
+}
+
+#endif /* !HAVE_CURL */
+
+#endif /* EL_PLATFORM_WIN_H */

lang/releases/v1.0.0-20260501/el_runtime.h

@@ -117,15 +117,6 @@ el_val_t  el_min(el_val_t a, el_val_t b);
 void      el_retain(el_val_t v);
 void      el_release(el_val_t v);
 
-/* ── Arena scoping ────────────────────────────────────────────────────────────
- * el_arena_push() activates the string arena (if not already active) and
- * returns a mark; el_arena_pop(mark) frees all strings allocated since that
- * mark. Used by codegen for per-function/statement scoping and by long-running
- * EL loops (e.g. the soul daemon's awareness tick) to reclaim per-iteration
- * allocations. */
-el_val_t  el_arena_push(void);
-el_val_t  el_arena_pop(el_val_t mark);
-
 /* ── List ────────────────────────────────────────────────────────────────── */
 
 el_val_t  el_list_new(el_val_t count, ...);
@@ -151,7 +142,6 @@ el_val_t  http_get_with_headers(el_val_t url, el_val_t headers_map);
 el_val_t  http_post_with_headers(el_val_t url, el_val_t body, el_val_t headers_map);
 el_val_t  http_post_form_auth(el_val_t url, el_val_t form_body, el_val_t auth_header);
 el_val_t  http_delete(el_val_t url);
-el_val_t  http_delete_json(el_val_t url, el_val_t json_body);
 void      http_serve(el_val_t port, el_val_t handler);
 void      http_set_handler(el_val_t name);
 
@@ -177,11 +167,6 @@ void      http_set_handler(el_val_t name);
 void      http_serve_v2(el_val_t port, el_val_t handler);
 void      http_set_handler_v2(el_val_t name);
 
-/* Non-blocking variant of http_serve: runs the accept loop in a background
- * pthread and returns immediately so the caller can continue (used by the
- * soul daemon to run awareness_run() after starting its HTTP API). */
-void      http_serve_async(el_val_t port, el_val_t handler);
-
 /* Build an HTTP response envelope. `headers_json` should be a JSON object
  * literal like `{"WWW-Authenticate":"Basic"}` (or "" / "{}" for none). The
  * returned string carries the discriminator `{"el_http_response":1,...}`
@@ -591,7 +576,6 @@ el_val_t  engram_list_layers(void);
 el_val_t  engram_get_node(el_val_t id);
 void      engram_strengthen(el_val_t node_id);
 void      engram_forget(el_val_t node_id);
-el_val_t  engram_prune_telemetry(el_val_t older_than_ms);
 el_val_t  engram_node_count(void);
 el_val_t  engram_search(el_val_t query, el_val_t limit);
 el_val_t  engram_scan_nodes(el_val_t limit, el_val_t offset);
@@ -610,32 +594,12 @@ el_val_t  engram_load(el_val_t path);
  * can pass results straight through without round-tripping ElList/ElMap
  * through json_stringify. */
 el_val_t  engram_get_node_json(el_val_t id);
-el_val_t  engram_get_node_by_label(el_val_t label);
 el_val_t  engram_search_json(el_val_t query, el_val_t limit);
 el_val_t  engram_scan_nodes_json(el_val_t limit, el_val_t offset);
 el_val_t  engram_scan_nodes_by_type_json(el_val_t node_type, el_val_t limit, el_val_t offset);
 el_val_t  engram_neighbors_json(el_val_t node_id, el_val_t max_depth, el_val_t direction);
 el_val_t  engram_activate_json(el_val_t query, el_val_t depth);
 el_val_t  engram_stats_json(void);
-el_val_t  engram_act_stats_json(void);
-el_val_t  engram_text_health_json(void);
-el_val_t  engram_cosine_sim(el_val_t id_a, el_val_t id_b);
-/* Destructively pop up to `max` newly-formed Hebbian associations as a JSON
- * array of {from_id,to_id,weight,hebb}. The learning process (soul daemon) is
- * not the process that owns persistence (engram HTTP server); this is how a
- * self-formed association crosses that boundary. (2026-08-07 self-review.) */
-el_val_t  engram_hebb_drain_json(el_val_t max);
-/* Document frequency of a term across node labels — term-specificity signal
- * for curiosity seed selection. (2026-08-03 self-review.) */
-el_val_t  engram_label_df(el_val_t term);
-/* Best curiosity seed from one node: argmax over idf·position·casing across
- * the candidate tokens of its label, falling back to its content when the
- * label is a sentinel. Excludes pipe-delimited tabu terms during selection
- * and gates candidates to the df band [min_df, max_df]. Returns "" when
- * nothing qualifies. (2026-08-13 self-review.) */
-el_val_t  engram_salient_term(el_val_t node_id, el_val_t max_df,
-                              el_val_t min_df, el_val_t tabu);
-el_val_t  engram_embed_backfill(el_val_t count);
 el_val_t  engram_list_layers_json(void);
 /* Working memory introspection — count, mean weight, and top-N snapshot.
  * Ported from el-compiler/runtime on 2026-06-30 self-review. */
@@ -794,6 +758,18 @@ el_val_t trace_span_start(el_val_t name);
 el_val_t trace_span_end(el_val_t span_handle);
 el_val_t emit_event(el_val_t name, el_val_t duration_ms);
 
+/* ── Runtime symbols required by the soul modules ──────────────────────────── */
+/* All implemented in el_runtime.c but omitted from this release header; the soul dist modules
+ * reference them directly, so the public header must export them. Declarations only — mirrors the
+ * mainline el_runtime.h and is platform-independent (no behavioural change to the POSIX build). */
+typedef el_val_t (*http_handler_fn)(el_val_t method, el_val_t path, el_val_t body);
+typedef el_val_t (*http_handler4_fn)(el_val_t method, el_val_t path, el_val_t body, el_val_t headers);
+el_val_t  el_arena_push(void);
+el_val_t  el_arena_pop(el_val_t mark);
+void      http_serve_async(el_val_t port, el_val_t handler);
+el_val_t  engram_get_node_by_label(el_val_t label);
+el_val_t  engram_prune_telemetry(el_val_t older_than_ms);
+
 #ifdef __cplusplus
 }
 #endif

tools/neuron-sandbox/Makefile

@@ -1,64 +0,0 @@
-# nsbx — Neuron dev-environment Makefile
-# ---------------------------------------------------------------------------
-# Thin, documented wrappers over the `nsbx` primitive so a newcomer never has to
-# memorise the elc/cc build incantation or the sandbox lifecycle. Every target is
-# a one-liner over `nsbx`; nothing here reimplements engram logic.
-#
-#   make dev NAME=tim        # new branch + worktree + isolated engram, one shot
-#   make status NAME=tim     # inspect it (omit NAME to list all sandboxes)
-#   make run NAME=tim        # poke its API (API=/api/stats by default)
-#   make test NAME=tim       # run the safety rails as checks (nsbx validate)
-#   make build NAME=tim      # compile the worktree's changes into the engram
-#   make destroy NAME=tim    # tear it all down (branch kept)
-#
-# The isolated engram is ALWAYS a clone of the live store on a NON-default port;
-# prod (:8742 / :7770) is untouchable from here.
-# ---------------------------------------------------------------------------
-
-# locate nsbx next to this Makefile, regardless of where make is run from
-NSBX := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))nsbx
-SBX  := dev-$(NAME)
-API  ?= /api/stats
-
-.DEFAULT_GOAL := help
-
-.PHONY: help dev build run test status list destroy bt
-
-help: ## Show this help
-	@echo "nsbx dev-environment — one-command isolated Neuron dev setup"
-	@echo ""
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) \
-	  | awk 'BEGIN{FS=":.*?## "}{printf "  make %-22s %s\n", $$1, $$2}'
-	@echo ""
-	@echo "  Variables:  NAME=<dev name> (required for most)   API=<path> (run)"
-	@echo "              BASE=<git ref>  WT=<worktree dir>  PORT=<n>  ARGS=<extra nsbx flags>"
-
-dev: ## Create branch + worktree + isolated engram (NAME=x [BASE=ref PORT=n WT=dir ARGS=...])
-	@test -n "$(NAME)" || { echo "usage: make dev NAME=<name>"; exit 2; }
-	$(NSBX) dev $(NAME) $(if $(BASE),--base $(BASE)) $(if $(PORT),--port $(PORT)) $(if $(WT),--worktree $(WT)) $(ARGS)
-
-build: ## Rebuild the engram from the dev worktree's own source (NAME=x)
-	@test -n "$(NAME)" || { echo "usage: make build NAME=<name>"; exit 2; }
-	@wt=$$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.neuron/sandboxes/$(SBX)/dev.json')))['worktree'])" 2>/dev/null); \
-	 test -n "$$wt" || { echo "no dev.json for $(SBX) — run 'make dev NAME=$(NAME)' first"; exit 2; }; \
-	 $(NSBX) build $(SBX) --source "$$wt"
-
-bt: build run ## Fast El loop: rebuild the engram from the worktree, then poke it (NAME=x)
-
-run: ## Poke the isolated engram's API (NAME=x [API=/api/stats])
-	@test -n "$(NAME)" || { echo "usage: make run NAME=<name> [API=/path]"; exit 2; }
-	$(NSBX) run $(SBX) api $(API)
-
-test: ## Run the safety rails as checks: zero-loss, reboot, RSS, parity, keystones (NAME=x)
-	@test -n "$(NAME)" || { echo "usage: make test NAME=<name>"; exit 2; }
-	$(NSBX) validate $(SBX)
-
-status: ## Show one sandbox's status (NAME=x), or list all if NAME is unset
-	@if [ -n "$(NAME)" ]; then $(NSBX) status $(SBX); else $(NSBX) list; fi
-
-list: ## List all sandboxes
-	$(NSBX) list
-
-destroy: ## Tear down engram + worktree (NAME=x [ARGS=--delete-branch])
-	@test -n "$(NAME)" || { echo "usage: make destroy NAME=<name>"; exit 2; }
-	$(NSBX) dev-down $(NAME) $(ARGS)

tools/neuron-sandbox/README.md

@@ -1,176 +0,0 @@
-# nsbx — the Neuron Sandbox
-
-**Dev environment as a primitive.** A reproducible way to run experiments *and code
-changes* against the **real** engram runtime on an isolated snapshot of the live
-mind — with a gated promote-to-prod path built on the proven rails.
-
-Everyone (Tim, any team member, any agent) gets their own private, safe copy of the
-mind to build against. **Prod — the live Neuron on `:8742` (engram) / `:7770`
-(soul) — is untouchable from a sandbox.** A sandbox runs a *separate* engram
-process, on a *separate* port, against a *separate* clone of the store. The only op
-that can ever reach prod is `promote`, which is explicit, gated, and per-use
-approved.
-
-It **wraps the real engram binary** — it never reimplements any engram logic. It
-generalises two proven proto-sandboxes into one primitive:
-
-- the **cog-arch** build — isolated git worktree + build + clone of the live `.egm` + real C tests
-- the **store-fix** cutover — secondary soul + launchctl `bootout → settle → bootstrap` rails
-
-## Quickstart
-
-```bash
-export PATH="$PWD:$PATH"          # or symlink nsbx onto your PATH
-
-nsbx up                          # your private copy of the mind (auto-named <user>-dev)
-nsbx run <name> api /api/stats   # poke it
-nsbx validate <name>             # prove it: zero-loss, reboot, RSS, retrieval, keystones
-nsbx destroy <name>              # cheap teardown; live untouched
-```
-
-That is the whole loop. Sane defaults: stock prod binary, auto-allocated port
-(`8900+`, never `8742`/`7770`), snapshot of the live store.
-
-## One-command dev onboarding — `nsbx dev` (start here)
-
-Going from a clone to *coding on the mind* is a single command. It creates a git
-**branch**, a persistent git **worktree**, and an **isolated engram** (a clone of the
-live store on a non-default port) — and wires the whole worktree to that clone so you
-**cannot hit live `:8742` by accident**.
-
-```bash
-make dev NAME=tim        # branch wt/tim + worktree + isolated engram, in one shot
-cd ~/Development/neuron-technologies/el-worktrees/tim
-source .nsbx-env         # every ENGRAM_* var now points at YOUR clone
-
-# edit El in the worktree, then the fast loop:
-make build NAME=tim      # compile your El change into the isolated engram
-make run   NAME=tim      # poke it (API=/api/stats by default)
-make test  NAME=tim      # run the safety rails as checks
-make destroy NAME=tim    # tear it all down (branch kept; live untouched)
-```
-
-**Why this exists:** so provisional/experimental work is built **directly in El against a
-throwaway cloned engram** — not prototyped in Python and re-ported later. The El
-edit → `make build` → `make run` loop is the path of least resistance; that double-work is
-what stranded the translation faculty for weeks.
-
-### What `nsbx dev <name>` does, in order
-
-1. **branch** — `git worktree add -b <prefix><name>` (default prefix `dev/`; a *real named
-   branch*, never detached HEAD).
-2. **worktree** — at a **persistent** path (default `…/el-worktrees/<name>`, override
-   `NSBX_DEV_WT_ROOT`). It **refuses** `/tmp` — temp dirs are ablated on compaction, which
-   is the exact "worktree in /tmp + no branch = lost work" failure this designs out.
-3. **isolated engram** — `nsbx create` under the hood: clone of the live store + WAL +
-   config, booted on an auto-allocated port (`8900+`, never `:8742`/`:7770`). Stock prod
-   binary by default (instant); `--build` compiles the worktree's own runtime instead.
-4. **env pin** — writes `.nsbx-env` (+ `.envrc` for direnv) into the worktree exporting
-   `ENGRAM_URL / ENGRAM_PORT / ENGRAM_DATA_DIR / ENGRAM_API_KEY / NEURON_ENGRAM_URL …` — all
-   pointing at the clone. Nothing references live.
-
-```
-nsbx dev <name> [--base REF] [--worktree DIR] [--port N] [--prefix P] [--build] [--no-engram] [--repo R]
-nsbx dev-down <name> [--delete-branch] [--repo R]      # destroy engram + remove worktree
-```
-
-### Makefile targets
-
-| target | does |
-|--------|------|
-| `make dev NAME=x` | branch + worktree + isolated engram (one shot) |
-| `make bt NAME=x` | fast El loop: `build` then `run` |
-| `make build NAME=x` | recompile the engram from the worktree's El source |
-| `make run NAME=x` | poke the isolated engram (`API=/api/stats`) |
-| `make test NAME=x` | rails as checks (`nsbx validate`) |
-| `make status [NAME=x]` | inspect one, or `list` all |
-| `make destroy NAME=x` | tear down (add `ARGS=--delete-branch` to drop the branch) |
-
-> Note: if a bare `dev` branch already exists in the repo, git can't create `dev/*` names —
-> pass `--prefix wt/` (or delete the stray `dev` branch). The tool surfaces git's exact error.
-
-## The code-change dev loop (first-class)
-
-Run *your changed runtime*, not just the stock binary, against a snapshot:
-
-```bash
-# build a runtime from a working tree, a git branch, or a prebuilt binary:
-nsbx create feat --source /path/to/worktree           # elc + cc build from source
-nsbx create feat --branch feat/my-change --repo <r>   # worktree the branch, then build
-nsbx create feat --binary /path/to/engram             # use a prebuilt binary
-
-nsbx build feat --source /path/to/worktree            # rebuild + hot-restart in place
-nsbx validate feat                                    # prove the change is safe
-nsbx promote feat --i-approve-prod-cutover            # gated rails cutover (see below)
-```
-
-The build replicates the engram release recipe exactly:
-`elc engram/src/server.el > engram.c` then
-`cc -std=c11 -O2 -I lang/runtime engram.c el_runtime.c engram_*.c -lcurl -lpthread`.
-
-## Lifecycle
-
-| op | what it does |
-|----|--------------|
-| `create <name> [--port N] [--source\|--branch\|--binary]` | consistent snapshot of the live store+WAL+config into an isolated dir; place or **build** the runtime; boot the real engram daemon on an isolated port. Named, versioned (binary sha + egm sha in `manifest.json`), reproducible. |
-| `up [name]` | one command: create-if-missing then start; prints the URL. |
-| `build <name> --source\|--branch` | rebuild the runtime from a code change and hot-restart on the same clone+port. |
-| `run <name> <cmd…>` / `run <name> api <path> [json]` | run an experiment against the real runtime; capture output + before/after stats + wall time. Env: `$SBX_URL $SBX_PORT $SBX_KEY $SBX_DATA $SBX_BIN`. |
-| `validate <name>` | the rails as first-class checks (below). |
-| `promote <name> [--data] [--i-approve-prod-cutover]` | **the only prod-touching op.** Gated rails cutover. DRY-RUN plan unless approved. |
-| `destroy <name>` | stop the isolated daemon, free the port, remove the clone. Live untouched. |
-| `list` / `status <name>` | inspect. |
-
-## `validate` — the rails as checks
-
-- **zero-loss-under-load** — node/edge counts hold at/above baseline through ~15s of sustained tick+read load
-- **reboot-prove** — counts survive a real stop→start of the daemon
-- **rss-bound** — daemon RSS under `NSBX_RSS_BOUND_MB` (default 550 MB, from the store-fix reboot-proof)
-- **retrieval-parity** — top-k node ids for a fixed probe set match the create-time baseline
-- **keystone-integrity** — `kn-efeb4a5b…` and `kn-5b606390…` present and intact
-
-A PASS writes `validate.json` stamped with the binary sha; `promote` refuses unless
-the current binary has a fresh PASS on record.
-
-## `promote` — gated cutover (rails only)
-
-Default is a **dry-run plan**. With `--i-approve-prod-cutover` it, in order:
-
-1. **snapshot-first** — back up live `egm`+`wal`+`plist` to `~/.neuron/backups/promote-<name>-<ts>/` with a `rollback.txt`
-2. **additive** binary install — copy the validated binary to a *new* file, update the plist `ENGRAM_REAL_BIN` (old binary retained — additive/supersede, never destructive)
-3. **rails cutover** — `launchctl bootout` → **settle-poll** (prints until the job is gone) → `launchctl bootstrap`. Never `pkill`, never `kickstart -k`.
-4. **verify** — `/api/stats` returns, edges ≥ baseline, keystones intact
-5. **auto-rollback armed** — any verify failure restores the plist (and data, if `--data`) and boots the prior binary back via the same rails
-
-## Isolation guarantees
-
-- separate **port** (`8900+`; refuses `8742`/`7770`), separate **store clone**, separate **process**
-- a hard guard refuses to boot a sandbox daemon whose data dir resolves to the live store
-- sandboxes are plain supervised background processes (not launchd), so teardown is a signal + settle-poll — it can never touch the prod launchd job
-- prod is read exactly twice: once for the snapshot, and (only if you approve) during `promote`
-
-## Layout
-
-- tool: `tools/neuron-sandbox/nsbx` (this repo, branch `feat/neuron-sandbox`)
-- runtime state: `~/.neuron/sandboxes/<name>/` — `data/` (clone), `bin/engram`, `build/`, `logs/`, `manifest.json`, `validate.json`, `baseline/`
-
-## Validated (dogfood)
-
-Standing up a sandbox from a live-store clone and reproducing a **known** result:
-
-- **retrieval-parity 25/25** top-k id overlap vs baseline; sandbox boot-stats exactly matched the live baseline captured at snapshot time (10 672 nodes / 32 439 edges) — the wrapped real binary faithfully reloads the live mind
-- reboot-prove + zero-loss PASS; RSS 379 MB < 550 MB; keystones intact
-- the **cog-arch correspondence-loop** re-run *inside* the sandbox reproduced the known calibration numbers exactly: held-Brier **0.028648 → 0.000586** (98.0% reduction), monotone, **reboot bit-identical**, metastability holds; and the real-store Stance persistence reboot-proved at **10 994-node** scale (`think()` on real 768-dim embeddings) against a scratch copy of the sandbox's own clone — never live
-- `promote` dry-run refused to touch prod; teardown freed the port; live `:8742`/`:7770` never perturbed (soul uptime unbroken)
-
-## Migrating existing experiments
-
-Each ad-hoc harness becomes `nsbx run <name> …` (or `--source` build) against a sandbox:
-
-- **cog-arch** — `nsbx create x --source <worktree>` then `nsbx run x -- bash cogarch_dogfood.sh` (compiles + runs the real C cognition tests against `$SBX_DATA`)
-- **codec / ingest / faculty** — `nsbx run x api /api/<endpoint> '<json>'` against the isolated daemon, or a script using `$SBX_URL`/`$SBX_KEY`; measure with the built-in before/after stats
-
-## Env knobs
-
-`NSBX_ROOT`, `NSBX_PORT_BASE`, `NSBX_RSS_BOUND_MB`, `NSBX_REMERGE_THRESHOLD`,
-`EL_REPO` (for `elc` + runtime sources), `ENGRAM_LIVE_DATA_DIR`, `ENGRAM_LIVE_PLIST`.

tools/neuron-sandbox/examples/cogarch-dogfood.sh

@@ -1,30 +0,0 @@
-#!/usr/bin/env bash
-# cog-arch correspondence-loop dogfood — RUN INSIDE the sandbox via `nsbx run`.
-# Compiles the REAL engram C runtime + cognition tests and reproduces the known
-# calibration result (memory 194c69c8): held-Brier 0.028648 -> 0.000586, reboot-proven,
-# then reboot-proves the Stance persistence against a SCRATCH COPY of THIS sandbox's
-# clone of the real store (never live, never the running daemon's file).
-set -euo pipefail
-WT="${COGARCH_WT:-/private/tmp/claude-501/-Users-will/6531446d-bc27-4095-930b-e04777c3db4f/scratchpad/cogarch-wt}"
-RT="$WT/lang/runtime"; T="$WT/engram/test"
-: "${SBX_DATA:?run me via: nsbx run <name> -- bash cogarch_dogfood.sh}"
-B="$(mktemp -d)"
-echo "### building cog-arch tests against the real engram runtime sources"
-cc -std=c11 -O2 -w -I "$RT" -o "$B/test_cognition" \
-   "$T/test_cognition.c" "$RT/engram_cognition.c" "$RT/engram_reason.c" \
-   "$RT/engram_geometry.c" "$RT/engram_store.c" "$RT/engram_vindex.c" -lm
-cc -std=c11 -O2 -w -I "$RT" -o "$B/test_realstore" \
-   "$T/test_cognition_realstore.c" "$RT/engram_cognition.c" "$RT/engram_reason.c" \
-   "$RT/engram_geometry.c" "$RT/engram_store.c" "$RT/engram_vindex.c" -lm
-
-echo; echo "### [A] synthetic correspondence-loop (known: Brier 0.028648 -> 0.000586)"
-"$B/test_cognition" | grep -E "held-Brier|reduction|reboot|monotone|metastab|RESULT" || true
-
-echo; echo "### [B] reboot-prove Stance on a SCRATCH COPY of this sandbox's real-store clone"
-SCRATCH="$B/store-clone"; mkdir -p "$SCRATCH"
-cp -p "$SBX_DATA/neuron.egm" "$SCRATCH/" 2>/dev/null || true
-cp -p "$SBX_DATA/neuron.wal" "$SCRATCH/" 2>/dev/null || true
-cp -p "$SBX_DATA/conf" "$SCRATCH/" 2>/dev/null || true
-cp -p "$SBX_DATA/meta.json" "$SCRATCH/" 2>/dev/null || true
-"$B/test_realstore" "$SCRATCH" || true
-rm -rf "$B"

tools/neuron-sandbox/nsbx

@@ -1,836 +0,0 @@
-#!/usr/bin/env bash
-# nsbx — the Neuron Sandbox: a reproducible primitive for running experiments and
-# code changes against the REAL engram runtime on an isolated snapshot of the live
-# mind, with a gated promote-to-prod path built on the proven rails.
-#
-# It WRAPS the real engram binary — it never reimplements any engram logic. The only
-# prod-touching op is `promote`, which is explicit, gated, and per-use approved.
-#
-# Generalises two proven proto-sandboxes:
-#   - the cog-arch build   (isolated git worktree + build + clone of live .egm + real C tests)
-#   - the store-fix cutover (secondary soul + launchctl bootout->settle->bootstrap rails)
-#
-# Lifecycle:  create -> [build] -> run -> validate -> promote(gated) -> destroy
-#
-# Rails (always): built offline; NEVER auto-promotes; never touches live :8742/:7770
-# except READ for the snapshot and the gated promote; snapshot-first; honest measured
-# reporting. Cutover is launchctl bootout -> settle-poll -> bootstrap ONLY —
-# never pkill, never kickstart -k.
-set -uo pipefail
-
-# ---------------------------------------------------------------- constants ----
-LIVE_DATA_DIR="${ENGRAM_LIVE_DATA_DIR:-$HOME/.neuron/engram}"
-LIVE_PLIST="${ENGRAM_LIVE_PLIST:-$HOME/Library/LaunchAgents/ai.neuron.engram.plist}"
-LIVE_LABEL="ai.neuron.engram"
-LIVE_BIND_PORT=8742          # engram — FORBIDDEN for sandboxes
-SOUL_PORT=7770               # soul   — FORBIDDEN for sandboxes
-LIVE_KEY="${ENGRAM_API_KEY:-ntn-user-2026}"
-LIVE_URL="http://127.0.0.1:${LIVE_BIND_PORT}"
-SBX_ROOT="${NSBX_ROOT:-$HOME/.neuron/sandboxes}"
-BACKUP_ROOT="$HOME/.neuron/backups"
-EL_REPO="${EL_REPO:-$HOME/Development/neuron-technologies/foundation/el}"
-PORT_BASE="${NSBX_PORT_BASE:-8900}"
-RSS_BOUND_MB="${NSBX_RSS_BOUND_MB:-550}"      # from store-fix reboot-proof (aaf13f88)
-REMERGE_THRESHOLD="${NSBX_REMERGE_THRESHOLD:-40000}"
-KEYSTONES=( "kn-efeb4a5b-5aff-4759-8a97-7233099be6ee" "kn-5b606390-a52d-4ca2-8e0e-eba141d13440" )
-# fixed probe set for retrieval-parity (stable, identity-anchored)
-PARITY_QUERIES=( "who am I" "self identity core" "engram store durability" "keystone self anchor" "grounding honesty" )
-
-C_RED=$'\033[31m'; C_GRN=$'\033[32m'; C_YEL=$'\033[33m'; C_DIM=$'\033[2m'; C_BLD=$'\033[1m'; C_0=$'\033[0m'
-
-# ---------------------------------------------------------------- helpers ------
-die(){ printf '%serror:%s %s\n' "$C_RED" "$C_0" "$*" >&2; exit 1; }
-log(){ printf '%s==>%s %s\n' "$C_BLD" "$C_0" "$*" >&2; }
-info(){ printf '    %s\n' "$*" >&2; }
-ok(){   printf '    %s%s%s\n' "$C_GRN" "$*" "$C_0" >&2; }
-warn(){ printf '    %s%s%s\n' "$C_YEL" "$*" "$C_0" >&2; }
-need(){ command -v "$1" >/dev/null 2>&1 || die "missing dependency: $1"; }
-now(){ date -u +%Y%m%dT%H%M%SZ; }
-sha(){ shasum -a 256 "$1" 2>/dev/null | awk '{print $1}'; }
-epoch(){ python3 -c 'import time;print(time.time())'; }
-
-sdir(){ printf '%s/%s' "$SBX_ROOT" "$1"; }
-manifest(){ printf '%s/manifest.json' "$(sdir "$1")"; }
-mexists(){ [ -f "$(manifest "$1")" ]; }
-mget(){ # mget <name> <jsonpath>
-  python3 -c "import json,sys; d=json.load(open('$(manifest "$1")')); print(d$2)" 2>/dev/null
-}
-
-port_free(){ ! (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
-alloc_port(){
-  local p="$PORT_BASE"
-  while :; do
-    if [ "$p" = "$LIVE_BIND_PORT" ] || [ "$p" = "$SOUL_PORT" ]; then p=$((p+1)); continue; fi
-    if port_free "$p" && ! _port_claimed "$p"; then echo "$p"; return 0; fi
-    p=$((p+1)); [ "$p" -gt 9100 ] && die "no free sandbox port in range"
-  done
-}
-_port_claimed(){ # is another sandbox already assigned this port?
-  local p="$1" d
-  for d in "$SBX_ROOT"/*/manifest.json; do
-    [ -f "$d" ] || continue
-    [ "$(python3 -c "import json;print(json.load(open('$d'))['port'])" 2>/dev/null)" = "$p" ] && return 0
-  done
-  return 1
-}
-
-live_stats(){ curl -s -m5 "$LIVE_URL/api/stats" 2>/dev/null; }
-api(){ # api <name> <path> [json-body]
-  local name="$1" path="$2" body="${3:-}"
-  local port; port="$(mget "$name" "['port']")"; [ -n "$port" ] || die "unknown sandbox: $name"
-  local url="http://127.0.0.1:${port}${path}"
-  if [ -n "$body" ]; then curl -s -m30 -X POST -H 'Content-Type: application/json' -d "$body" "$url"
-  else curl -s -m30 "$url"; fi
-}
-sbx_stats(){ api "$1" "/api/stats"; }
-stat_field(){ printf '%s' "$1" | sed -n "s/.*\"$2\":\([0-9]*\).*/\1/p"; }
-
-daemon_pid(){ local f; f="$(sdir "$1")/daemon.pid"; [ -f "$f" ] && cat "$f" || true; }
-daemon_alive(){ local p; p="$(daemon_pid "$1")"; [ -n "$p" ] && kill -0 "$p" 2>/dev/null; }
-
-# ---------------------------------------------------------------- elc/build ----
-find_elc(){
-  command -v elc 2>/dev/null && return 0
-  local arch; arch="$(uname -m)"
-  case "$arch" in
-    arm64) echo "$EL_REPO/lang/dist/platform/elc-darwin-arm64";;
-    x86_64) echo "$EL_REPO/lang/dist/platform/elc-linux-amd64";;
-    *) echo "$EL_REPO/lang/dist/platform/elc";;
-  esac
-}
-
-# _build_binary <src_tree> <out_bin> <build_log_dir>
-# Replicates the proven engram release recipe:
-#   elc engram/src/server.el > engram.c
-#   cc -std=c11 -O2 -I lang/runtime engram.c el_runtime.c engram_*.c -lcurl -lpthread
-_build_binary(){
-  local src="$1" out="$2" blog="$3"
-  local elc server rt
-  elc="$(find_elc)"; [ -x "$elc" ] || die "elc not found/executable: $elc (set EL_REPO)"
-  server="$src/engram/src/server.el"; rt="$src/lang/runtime"
-  [ -f "$server" ] || die "no engram/src/server.el under source tree: $src"
-  [ -f "$rt/el_runtime.c" ] || die "no lang/runtime/el_runtime.c under source tree: $src (this branch may keep it generated/untracked)"
-  ls "$rt"/engram_*.c >/dev/null 2>&1 || die "no lang/runtime/engram_*.c engine sources under: $src"
-  mkdir -p "$blog"
-  log "build: elc transpile server.el -> engram.c"
-  "$elc" "$server" > "$blog/engram.c" 2>"$blog/elc.err" || { cat "$blog/elc.err" >&2; die "elc transpile failed"; }
-  info "engram.c: $(wc -c <"$blog/engram.c" | tr -d ' ') bytes"
-  log "build: cc link (el_runtime + engram_* engine)"
-  cc -std=c11 -O2 -w -I "$rt" -o "$out" \
-     "$blog/engram.c" "$rt/el_runtime.c" "$rt"/engram_*.c \
-     -lcurl -lpthread 2>"$blog/cc.err" \
-     || { grep -i 'error:' "$blog/cc.err" | sort -u | head >&2; die "cc link failed (see $blog/cc.err)"; }
-  ok "built: $out ($(ls -lh "$out" | awk '{print $5}'), sha $(sha "$out" | cut -c1-12))"
-}
-
-# ---------------------------------------------------------------- daemon -------
-# start_daemon <name> : boots the sandbox's real engram binary on its isolated
-# port against its cloned data dir, with the SAME auto-remerge net the live soul
-# uses (so the sandbox faithfully reaches the live edge population on boot).
-start_daemon(){
-  local name="$1" d; d="$(sdir "$name")"
-  daemon_alive "$name" && { info "already running (pid $(daemon_pid "$name"))"; return 0; }
-  local port bin data export key
-  port="$(mget "$name" "['port']")"; bin="$d/bin/engram"; data="$d/data"
-  key="sbx-$name"; export="$data/.scan-export.reseed-clean.json"
-  [ -x "$bin" ] || die "sandbox binary missing: $bin"
-  [ "$port" != "$LIVE_BIND_PORT" ] && [ "$port" != "$SOUL_PORT" ] || die "refusing forbidden port $port"
-  [ -f "$data/neuron.egm" ] || die "sandbox has no cloned store: $data/neuron.egm"
-  # HARD guard: never point a sandbox daemon at the live data dir.
-  [ "$(cd "$data" && pwd -P)" != "$(cd "$LIVE_DATA_DIR" && pwd -P)" ] || die "refusing: sandbox data dir resolves to LIVE store"
-
-  log "boot engram on isolated :$port (data=$data)"
-  (
-    ENGRAM_DATA_DIR="$data" ENGRAM_BIND=":$port" ENGRAM_API_KEY="$key" \
-    ENGRAM_STORE=1 ENGRAM_CHRONOCEPTION=1 ENGRAM_SELF_REIFY=1 ENGRAM_GC=1 \
-    ENGRAM_POOL_FRAMES=16384 ENGRAM_WRITE_BARRIER=1 \
-    exec "$bin"
-  ) >"$d/logs/daemon.log" 2>&1 &
-  local pid=$!
-  echo "$pid" > "$d/daemon.pid"
-  # readiness poll
-  local url="http://127.0.0.1:$port" i s
-  for i in $(seq 1 30); do
-    s="$(curl -s -m3 "$url/api/stats" 2>/dev/null)"
-    [ -n "$s" ] && break; sleep 0.5
-  done
-  [ -n "$s" ] || { warn "daemon did not become ready (see $d/logs/daemon.log)"; return 1; }
-  ok "ready pid=$pid  boot-stats: $s"
-  # auto-remerge net (idempotent): match live edge population if the export is present
-  if [ -f "$export" ]; then
-    local edges; edges="$(stat_field "$s" edge_count)"
-    if [ -n "$edges" ] && [ "$edges" -lt "$REMERGE_THRESHOLD" ]; then
-      log "auto-remerge: booted with $edges edges (< $REMERGE_THRESHOLD) — merging full edge export"
-      local r; r="$(curl -s -m300 -X POST -H 'Content-Type: application/json' \
-             -d "{\"_auth\":\"$key\",\"path\":\"$export\"}" "$url/api/load-merge" 2>/dev/null)"
-      info "remerge resp: ${r:0:120}"
-      ok "post-remerge stats: $(curl -s -m5 "$url/api/stats")"
-    fi
-  fi
-  return 0
-}
-
-# stop_daemon <name> : graceful TERM + settle-poll until the port is free.
-# (Sandbox daemons are plain supervised bg processes — not launchd — so teardown
-# is a signal + poll, never pkill of anything else.)
-stop_daemon(){
-  local name="$1" pid port
-  pid="$(daemon_pid "$name")"; port="$(mget "$name" "['port']")"
-  [ -n "$pid" ] || { info "not running"; return 0; }
-  log "stop daemon pid=$pid, settle-poll until :$port frees"
-  kill "$pid" 2>/dev/null || true
-  local i
-  for i in $(seq 1 40); do
-    kill -0 "$pid" 2>/dev/null || { port_free "$port" && { ok "stopped, port $port free"; : >"$(sdir "$name")/daemon.pid"; return 0; }; }
-    printf '.' >&2; sleep 0.5
-  done
-  printf '\n' >&2
-  kill -9 "$pid" 2>/dev/null || true; sleep 1
-  : >"$(sdir "$name")/daemon.pid"
-  port_free "$port" && ok "stopped (after SIGKILL), port $port free" || warn "port $port still busy"
-}
-
-# ================================================================ create =======
-cmd_create(){
-  local name="" port="" src="" branch="" repo="$EL_REPO" binpath=""
-  # first positional arg is the name unless it's a flag; default to "<user>-dev"
-  if [ $# -gt 0 ] && [ "${1#-}" = "$1" ]; then name="$1"; shift; else name="${USER:-dev}-dev"; fi
-  while [ $# -gt 0 ]; do case "$1" in
-    --port) port="$2"; shift 2;;
-    --source) src="$2"; shift 2;;
-    --branch) branch="$2"; shift 2;;
-    --repo) repo="$2"; shift 2;;
-    --binary) binpath="$2"; shift 2;;
-    *) die "unknown flag: $1";;
-  esac; done
-  mexists "$name" && die "sandbox '$name' already exists (destroy it first)"
-  need curl; need python3; need shasum
-  [ -f "$LIVE_DATA_DIR/neuron.egm" ] || die "live store not found: $LIVE_DATA_DIR/neuron.egm"
-  if [ -n "$port" ]; then
-    { [ "$port" = "$LIVE_BIND_PORT" ] || [ "$port" = "$SOUL_PORT" ]; } && die "refusing forbidden port $port (live)"
-    port_free "$port" || die "port $port already in use"
-  else port="$(alloc_port)"; fi
-
-  local d; d="$(sdir "$name")"
-  mkdir -p "$d/data" "$d/bin" "$d/logs" "$d/build" "$d/baseline"
-  log "sandbox '$name' at $d  (isolated port $port)"
-
-  # ---- CONSISTENT snapshot of the live mind (file-copy: same set the rails backup
-  #      uses; WAL replay on sandbox boot reconciles the tail -> crash-consistent) ----
-  log "snapshot live store -> clone (store + WAL + config)"
-  local f
-  for f in neuron.egm neuron.wal conf meta.json self_anchor .scan-export.reseed-clean.json; do
-    if [ -e "$LIVE_DATA_DIR/$f" ]; then cp -p "$LIVE_DATA_DIR/$f" "$d/data/$f"; info "cloned $f ($(du -h "$d/data/$f" | awk '{print $1}'))"; fi
-  done
-  local egm_sha; egm_sha="$(sha "$d/data/neuron.egm")"
-
-  # ---- capture live baseline (READ only) ----
-  local lstats; lstats="$(live_stats)"
-  local base_nodes base_edges
-  base_nodes="$(stat_field "$lstats" node_count)"; base_edges="$(stat_field "$lstats" edge_count)"
-  info "live baseline stats: ${lstats:-<unavailable>}"
-
-  # ---- determine + place the runtime binary (versioned into the snapshot) ----
-  local source_desc live_bin
-  live_bin="$(_live_real_bin)"
-  if [ -n "$binpath" ]; then
-    [ -x "$binpath" ] || die "not an executable binary: $binpath"
-    cp -p "$binpath" "$d/bin/engram"; source_desc="prebuilt:$binpath"
-  elif [ -n "$src" ]; then
-    _build_binary "$src" "$d/bin/engram" "$d/build"; source_desc="source:$src"
-  elif [ -n "$branch" ]; then
-    log "worktree: $repo @ $branch -> $d/build/worktree"
-    git -C "$repo" worktree add --detach "$d/build/worktree" "$branch" >/dev/null 2>&1 \
-      || die "git worktree add failed ($repo @ $branch)"
-    _build_binary "$d/build/worktree" "$d/bin/engram" "$d/build"; source_desc="branch:$branch@$repo"
-  else
-    [ -x "$live_bin" ] || die "cannot resolve live ENGRAM_REAL_BIN: $live_bin"
-    cp -p "$live_bin" "$d/bin/engram"; source_desc="stock-prod:$live_bin"
-  fi
-  local bin_sha; bin_sha="$(sha "$d/bin/engram")"
-  info "runtime: $source_desc  (sha ${bin_sha:0:12})"
-
-  # ---- write manifest ----
-  python3 - "$name" "$port" "$source_desc" "$bin_sha" "$egm_sha" "$base_nodes" "$base_edges" "$(sha "$live_bin" 2>/dev/null)" <<'PY' > "$(manifest "$name")"
-import json,sys,datetime
-name,port,src,binsha,egmsha,bn,be,livebinsha=sys.argv[1:9]
-json.dump({
- "name":name,"port":int(port),"created_at":datetime.datetime.now(datetime.timezone.utc).isoformat(),
- "source":src,"binary_sha256":binsha,"clone_egm_sha256":egmsha,
- "live_binary_sha256":livebinsha,
- "live_baseline":{"node_count":int(bn or 0),"edge_count":int(be or 0)},
- "keystones":["kn-efeb4a5b-5aff-4759-8a97-7233099be6ee","kn-5b606390-a52d-4ca2-8e0e-eba141d13440"]
-}, sys.stdout, indent=2)
-PY
-  ok "manifest written"
-
-  # ---- boot + capture the sandbox's own settled baseline (reproducible target) ----
-  start_daemon "$name" || die "daemon failed to start"
-  local sstats; sstats="$(sbx_stats "$name")"
-  local sbn sbe; sbn="$(stat_field "$sstats" node_count)"; sbe="$(stat_field "$sstats" edge_count)"
-  _capture_retrieval "$name" "$d/baseline/retrieval.json"
-  # fold sandbox baseline into manifest
-  python3 - "$(manifest "$name")" "$sbn" "$sbe" <<'PY'
-import json,sys
-mf,bn,be=sys.argv[1],sys.argv[2],sys.argv[3]
-d=json.load(open(mf)); d["sbx_baseline"]={"node_count":int(bn or 0),"edge_count":int(be or 0)}
-json.dump(d,open(mf,'w'),indent=2)
-PY
-  log "created."
-  info "sandbox baseline (settled): nodes=$sbn edges=$sbe"
-  info "next: nsbx validate $name    |    nsbx run $name api /api/stats"
-}
-
-_live_real_bin(){
-  python3 - "$LIVE_PLIST" <<'PY' 2>/dev/null
-import sys,plistlib
-try:
-  d=plistlib.load(open(sys.argv[1],'rb'))
-  print(d.get("EnvironmentVariables",{}).get("ENGRAM_REAL_BIN",""))
-except Exception: print("")
-PY
-}
-
-_capture_retrieval(){ # <name> <outfile> : top-k ids for the fixed probe set
-  local name="$1" out="$2" q res
-  local port; port="$(mget "$name" "['port']")"; local key="sbx-$name"
-  {
-    echo "{"
-    local first=1
-    for q in "${PARITY_QUERIES[@]}"; do
-      res="$(curl -s -m10 -X POST -H 'Content-Type: application/json' \
-             -d "{\"_auth\":\"$key\",\"query\":\"$q\",\"limit\":5}" "http://127.0.0.1:$port/api/search" 2>/dev/null)"
-      local ids; ids="$(printf '%s' "$res" | python3 -c 'import sys,json
-try:
- d=json.load(sys.stdin)
- rows=d if isinstance(d,list) else d.get("results",d.get("hits",[]))
- print(json.dumps([r.get("id") for r in rows][:5]))
-except Exception: print("[]")' 2>/dev/null)"
-      [ $first -eq 1 ] || echo ","; first=0
-      printf '  %s: %s' "$(python3 -c "import json,sys;print(json.dumps(sys.argv[1]))" "$q")" "${ids:-[]}"
-    done
-    echo ""; echo "}"
-  } > "$out"
-}
-
-# ================================================================ up ===========
-# Dead-simple one-command dev environment: `nsbx up` gives you (or Tim, or anyone)
-# a private, isolated copy of the live mind to build against. Creates it on first
-# run with sane defaults (stock prod binary, auto-allocated port), just starts it
-# thereafter. Prod on :$LIVE_BIND_PORT/:$SOUL_PORT is unreachable from here by design.
-cmd_up(){
-  local name; if [ $# -gt 0 ] && [ "${1#-}" = "$1" ]; then name="$1"; shift; else name="${USER:-dev}-dev"; fi
-  if mexists "$name"; then daemon_alive "$name" || start_daemon "$name"; else cmd_create "$name" "$@"; fi
-  local port; port="$(mget "$name" "['port']")"
-  echo >&2
-  ok "your sandbox '$name' is ready at http://127.0.0.1:$port  (a private copy of the mind — prod is untouchable)"
-  info "experiment:  nsbx run $name api /api/stats"
-  info "prove it:    nsbx validate $name"
-  info "tear down:   nsbx destroy $name"
-}
-
-# ================================================================ build ========
-# Rebuild an existing sandbox's runtime from a source tree/branch and hot-restart
-# it on the SAME clone + port (the code-change dev loop, in place).
-cmd_build(){
-  local name="$1"; shift || true
-  mexists "$name" || die "no such sandbox: $name"
-  local src="" branch="" repo="$EL_REPO"
-  while [ $# -gt 0 ]; do case "$1" in
-    --source) src="$2"; shift 2;; --branch) branch="$2"; shift 2;; --repo) repo="$2"; shift 2;;
-    *) die "unknown flag: $1";; esac; done
-  local d; d="$(sdir "$name")"
-  stop_daemon "$name"
-  if [ -n "$src" ]; then _build_binary "$src" "$d/bin/engram" "$d/build"
-  elif [ -n "$branch" ]; then
-    rm -rf "$d/build/worktree" 2>/dev/null; git -C "$repo" worktree prune 2>/dev/null
-    git -C "$repo" worktree add --detach "$d/build/worktree" "$branch" >/dev/null 2>&1 || die "worktree add failed"
-    _build_binary "$d/build/worktree" "$d/bin/engram" "$d/build"
-  else die "usage: nsbx build <name> --source DIR | --branch REF [--repo R]"; fi
-  # record new binary sha
-  python3 - "$(manifest "$name")" "$(sha "$d/bin/engram")" "${src:-branch:$branch}" <<'PY'
-import json,sys; mf,s,src=sys.argv[1:4]
-d=json.load(open(mf)); d["binary_sha256"]=s; d["source"]="rebuilt:"+src
-json.dump(d,open(mf,'w'),indent=2)
-PY
-  start_daemon "$name"
-  ok "rebuilt + restarted on :$(mget "$name" "['port']")"
-}
-
-# ================================================================ run ==========
-cmd_run(){
-  local name="$1"; shift || true
-  mexists "$name" || die "no such sandbox: $name"
-  daemon_alive "$name" || start_daemon "$name"
-  local d port; d="$(sdir "$name")"; port="$(mget "$name" "['port']")"
-  # direct API form: nsbx run <name> api <path> [json]
-  if [ "${1:-}" = "api" ]; then
-    api "$name" "$2" "${3:-}"; echo; return 0
-  fi
-  [ "${1:-}" = "--" ] && shift    # allow an explicit separator: nsbx run <name> -- <cmd...>
-  [ $# -gt 0 ] || die "usage: nsbx run <name> <cmd...>   |   nsbx run <name> api <path> [json]"
-  local ts log0; ts="$(now)"; log0="$d/logs/run-$ts.log"
-  local s0 t0 t1 s1
-  s0="$(sbx_stats "$name")"; t0="$(epoch)"
-  log "run experiment against sandbox '$name' (:$port)"
-  info "cmd: $*"
-  ( export SBX_NAME="$name" SBX_PORT="$port" SBX_URL="http://127.0.0.1:$port" \
-           SBX_KEY="sbx-$name" SBX_DATA="$d/data" SBX_BIN="$d/bin/engram"
-    "$@" ) 2>&1 | tee "$log0"
-  local rc=${PIPESTATUS[0]}
-  t1="$(epoch)"; s1="$(sbx_stats "$name")"
-  {
-    echo "--- nsbx run metrics ---"
-    echo "exit_code: $rc"
-    printf 'wall_secs: %.3f\n' "$(python3 -c "print($t1-$t0)")"
-    echo "stats_before: $s0"
-    echo "stats_after:  $s1"
-  } | tee -a "$log0" >&2
-  return $rc
-}
-
-# ================================================================ validate =====
-# The rails as first-class checks. Baseline = the sandbox's own settled state at
-# create (reproducible). zero-loss through sustained load AND reboot; reboot-prove;
-# RSS bound; retrieval parity; keystone integrity.
-cmd_validate(){
-  local name="$1"; shift || true
-  mexists "$name" || die "no such sandbox: $name"
-  daemon_alive "$name" || start_daemon "$name"
-  local d port key; d="$(sdir "$name")"; port="$(mget "$name" "['port']")"; key="sbx-$name"
-  local url="http://127.0.0.1:$port"
-  local bn be; bn="$(mget "$name" "['sbx_baseline']['node_count']")"; be="$(mget "$name" "['sbx_baseline']['edge_count']")"
-  log "validate '$name' against baseline nodes=$bn edges=$be"
-  local -a names=() results=() details=()
-
-  # 1) sustained load — no data loss under activity
-  local s cur_n cur_e i
-  log "check: sustained load (~15s: tick + reads) then zero-loss"
-  for i in $(seq 1 15); do
-    curl -s -m5 -X POST -H 'Content-Type: application/json' -d "{\"_auth\":\"$key\"}" "$url/api/tick" >/dev/null 2>&1
-    curl -s -m5 "$url/api/stats" >/dev/null 2>&1
-  done
-  s="$(sbx_stats "$name")"; cur_n="$(stat_field "$s" node_count)"; cur_e="$(stat_field "$s" edge_count)"
-  names+=("zero-loss-under-load"); if [ "${cur_n:-0}" -ge "${bn:-0}" ] && [ "${cur_e:-0}" -ge "${be:-0}" ]; then
-    results+=("PASS"); else results+=("FAIL"); fi
-  details+=("nodes $cur_n>=$bn, edges $cur_e>=$be")
-
-  # 2) reboot-prove — counts survive a real restart
-  log "check: reboot-prove (stop -> start -> compare)"
-  local pre_n pre_e; pre_n="$cur_n"; pre_e="$cur_e"
-  stop_daemon "$name"; start_daemon "$name" >/dev/null
-  s="$(sbx_stats "$name")"; cur_n="$(stat_field "$s" node_count)"; cur_e="$(stat_field "$s" edge_count)"
-  names+=("reboot-prove"); if [ "${cur_n:-0}" -ge "${bn:-0}" ] && [ "${cur_e:-0}" -ge "${be:-0}" ]; then
-    results+=("PASS"); else results+=("FAIL"); fi
-  details+=("post-reboot nodes=$cur_n edges=$cur_e (pre $pre_n/$pre_e)")
-
-  # 3) RSS bound
-  log "check: RSS bound (< ${RSS_BOUND_MB}MB)"
-  local pid rss_kb rss_mb; pid="$(daemon_pid "$name")"
-  rss_kb="$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ')"; rss_mb=$(( ${rss_kb:-0} / 1024 ))
-  names+=("rss-bound"); if [ "$rss_mb" -lt "$RSS_BOUND_MB" ] && [ "$rss_mb" -gt 0 ]; then results+=("PASS"); else results+=("FAIL"); fi
-  details+=("RSS=${rss_mb}MB (bound ${RSS_BOUND_MB}MB)")
-
-  # 4) retrieval parity vs the create-time baseline
-  log "check: retrieval parity vs baseline probe set"
-  _capture_retrieval "$name" "$d/logs/retrieval-$( now ).json"
-  local latest; latest="$(ls -t "$d/logs"/retrieval-*.json 2>/dev/null | head -1)"
-  local parity; parity="$(python3 - "$d/baseline/retrieval.json" "$latest" <<'PY'
-import json,sys
-def load(p):
-  try: return json.load(open(p))
-  except Exception: return {}
-b,c=load(sys.argv[1]),load(sys.argv[2])
-tot=hit=0
-for q,ids in b.items():
-  cb=set(ids or []); cc=set(c.get(q) or [])
-  if not cb: continue
-  tot+=len(cb); hit+=len(cb & cc)
-print(f"{hit}/{tot}" if tot else "0/0")
-PY
-)"
-  local ph="${parity%/*}" pt="${parity#*/}"
-  names+=("retrieval-parity"); if [ "${pt:-0}" -gt 0 ] && [ "${ph:-0}" -eq "${pt:-0}" ]; then results+=("PASS"); else results+=("FAIL"); fi
-  details+=("top-k id overlap $parity vs baseline")
-
-  # 5) keystone integrity
-  log "check: keystone integrity"
-  local kfail=0 kid kres
-  for kid in "${KEYSTONES[@]}"; do
-    kres="$(curl -s -m5 "$url/api/node/$kid" 2>/dev/null)"
-    printf '%s' "$kres" | grep -q "\"$kid\"" || kfail=1
-  done
-  names+=("keystone-integrity"); [ "$kfail" -eq 0 ] && results+=("PASS") || results+=("FAIL")
-  details+=("kn-efeb4a5b + kn-5b606390 present")
-
-  # ---- report + stamp ----
-  echo >&2
-  printf '%s  VALIDATION — %s%s\n' "$C_BLD" "$name" "$C_0" >&2
-  local allpass=1 j
-  for j in "${!names[@]}"; do
-    local r="${results[$j]}" c="$C_GRN"; [ "$r" = FAIL ] && { c="$C_RED"; allpass=0; }
-    printf '   %s%-6s%s %-22s %s%s%s\n' "$c" "$r" "$C_0" "${names[$j]}" "$C_DIM" "${details[$j]}" "$C_0" >&2
-  done
-  local status; [ "$allpass" -eq 1 ] && status="PASS" || status="FAIL"
-  python3 - "$d/validate.json" "$status" "$(sha "$d/bin/engram")" "$(now)" "${names[*]}" "${results[*]}" <<'PY'
-import json,sys
-out,status,binsha,ts,ns,rs=sys.argv[1:7]
-checks=[{"name":n,"result":r} for n,r in zip(ns.split(),rs.split())]
-json.dump({"status":status,"binary_sha256":binsha,"ts":ts,"checks":checks},open(out,'w'),indent=2)
-PY
-  printf '   %s==> %s%s\n' "$([ "$allpass" -eq 1 ] && echo "$C_GRN" || echo "$C_RED")" "$status" "$C_0" >&2
-  [ "$allpass" -eq 1 ]
-}
-
-# ================================================================ promote ======
-# The ONLY prod-touching op. Explicit, gated, per-use Will-approved. Rails ONLY:
-# snapshot-first -> additive binary swap -> launchctl bootout -> settle-poll ->
-# bootstrap -> verify -> auto-rollback on failure. NEVER pkill, NEVER kickstart -k.
-# Default is a DRY-RUN plan; requires --i-approve-prod-cutover to actually cut over.
-cmd_promote(){
-  local name="$1"; shift || true
-  mexists "$name" || die "no such sandbox: $name"
-  local approve=0 do_data=0
-  while [ $# -gt 0 ]; do case "$1" in
-    --i-approve-prod-cutover) approve=1; shift;;
-    --data) do_data=1; shift;;
-    *) die "unknown flag: $1";; esac; done
-  local d; d="$(sdir "$name")"
-  # GATE 1: validation must have passed for the CURRENT binary
-  [ -f "$d/validate.json" ] || die "GATE: no validation on record — run 'nsbx validate $name' first"
-  local vstatus vsha bsha
-  vstatus="$(python3 -c "import json;print(json.load(open('$d/validate.json'))['status'])")"
-  vsha="$(python3 -c "import json;print(json.load(open('$d/validate.json'))['binary_sha256'])")"
-  bsha="$(sha "$d/bin/engram")"
-  [ "$vstatus" = PASS ] || die "GATE: last validation status is $vstatus (must be PASS)"
-  [ "$vsha" = "$bsha" ] || die "GATE: validation is stale — binary changed since validate (re-run validate)"
-
-  local live_bin new_bin ts; ts="$(now)"
-  live_bin="$(_live_real_bin)"
-  new_bin="$HOME/.neuron/bin/engram.promote-$name-$ts"     # additive: new file, old kept
-  local bkp="$BACKUP_ROOT/promote-$name-$ts"
-
-  log "PROMOTE PLAN for '$name' -> live :$LIVE_BIND_PORT"
-  info "current live ENGRAM_REAL_BIN : $live_bin"
-  info "sandbox binary (validated)   : $d/bin/engram (sha ${bsha:0:12})"
-  info "will install as              : $new_bin  (additive; old binary retained)"
-  info "snapshot-first backup dir    : $bkp  (egm+wal+plist+rollback.txt)"
-  info "data promote                 : $([ $do_data -eq 1 ] && echo 'YES (--data: clone egm/wal -> live)' || echo 'no (binary only)')"
-  info "rails                        : launchctl bootout -> settle-poll -> bootstrap"
-  info "verify                       : /api/stats + edges>=baseline + keystones + retrieval; auto-rollback armed"
-
-  if [ "$approve" -ne 1 ]; then
-    warn "DRY-RUN — not touching prod. Re-run with --i-approve-prod-cutover to execute (per-use Will-approved)."
-    return 0
-  fi
-
-  need launchctl
-  local dom="gui/$(id -u)"
-  # ---- snapshot-first ----
-  log "snapshot-first backup -> $bkp"
-  mkdir -p "$bkp"
-  cp -p "$LIVE_DATA_DIR/neuron.egm" "$bkp/neuron.egm.bak"
-  cp -p "$LIVE_DATA_DIR/neuron.wal" "$bkp/neuron.wal.bak" 2>/dev/null || true
-  cp -p "$LIVE_PLIST" "$bkp/plist.bak"
-  printf 'rollback REAL_BIN=%s\nNEWBIN=%s\ndata_promote=%s\n' "$live_bin" "$new_bin" "$do_data" > "$bkp/rollback.txt"
-  ok "backup complete"
-
-  # ---- additive binary install + plist supersede ----
-  cp -p "$d/bin/engram" "$new_bin"
-  python3 - "$LIVE_PLIST" "$new_bin" <<'PY'
-import sys,plistlib
-p,new=sys.argv[1],sys.argv[2]
-d=plistlib.load(open(p,'rb')); d.setdefault("EnvironmentVariables",{})["ENGRAM_REAL_BIN"]=new
-plistlib.dump(d,open(p,'wb'))
-PY
-  ok "installed $new_bin + updated plist ENGRAM_REAL_BIN"
-
-  # ---- optional data promote (after backup) ----
-  if [ $do_data -eq 1 ]; then
-    log "data promote: clone store -> live (backed up above)"
-    cp -p "$d/data/neuron.egm" "$LIVE_DATA_DIR/neuron.egm"
-    cp -p "$d/data/neuron.wal" "$LIVE_DATA_DIR/neuron.wal" 2>/dev/null || true
-  fi
-
-  # ---- rails cutover: bootout -> settle-poll -> bootstrap ----
-  log "rails: launchctl bootout $dom/$LIVE_LABEL"
-  launchctl bootout "$dom/$LIVE_LABEL" 2>/dev/null || true
-  local i
-  for i in $(seq 1 60); do
-    launchctl print "$dom/$LIVE_LABEL" >/dev/null 2>&1 || { ok "settle: job gone after ${i}x0.5s"; break; }
-    printf '  settle: job still present (%d)\n' "$i" >&2; sleep 0.5
-  done
-  log "rails: launchctl bootstrap $dom <plist>"
-  launchctl bootstrap "$dom" "$LIVE_PLIST" || warn "bootstrap returned nonzero"
-
-  # ---- verify ----
-  log "verify prod health"
-  local s="" ; for i in $(seq 1 60); do s="$(live_stats)"; [ -n "$s" ] && break; sleep 1; done
-  local ok_verify=1 le; le="$(stat_field "$s" edge_count)"
-  local base_e; base_e="$(mget "$name" "['live_baseline']['edge_count']")"
-  [ -n "$s" ] || ok_verify=0
-  [ "${le:-0}" -ge "${base_e:-0}" ] || ok_verify=0
-  local kid; for kid in "${KEYSTONES[@]}"; do curl -s -m5 "$LIVE_URL/api/node/$kid" 2>/dev/null | grep -q "\"$kid\"" || ok_verify=0; done
-  if [ "$ok_verify" -eq 1 ]; then
-    ok "PROMOTED. live stats: $s  (rollback: $bkp)"; return 0
-  fi
-
-  # ---- auto-rollback ----
-  warn "verify FAILED — auto-rollback"
-  cp -p "$bkp/plist.bak" "$LIVE_PLIST"
-  [ $do_data -eq 1 ] && { cp -p "$bkp/neuron.egm.bak" "$LIVE_DATA_DIR/neuron.egm"; cp -p "$bkp/neuron.wal.bak" "$LIVE_DATA_DIR/neuron.wal" 2>/dev/null || true; }
-  launchctl bootout "$dom/$LIVE_LABEL" 2>/dev/null || true
-  for i in $(seq 1 60); do launchctl print "$dom/$LIVE_LABEL" >/dev/null 2>&1 || break; sleep 0.5; done
-  launchctl bootstrap "$dom" "$LIVE_PLIST" || true
-  die "ROLLED BACK to $live_bin. See $bkp"
-}
-
-# ================================================================ destroy ======
-cmd_destroy(){
-  local name="$1"; shift || true
-  mexists "$name" || die "no such sandbox: $name"
-  local d; d="$(sdir "$name")"
-  stop_daemon "$name"
-  if [ -d "$d/build/worktree" ]; then
-    log "removing git worktree"
-    git -C "$EL_REPO" worktree remove --force "$d/build/worktree" 2>/dev/null || true
-    git -C "$EL_REPO" worktree prune 2>/dev/null || true
-  fi
-  log "removing $d"
-  rm -rf "$d"
-  ok "destroyed '$name' (live untouched)"
-}
-
-# ================================================================ list/status ==
-cmd_list(){
-  [ -d "$SBX_ROOT" ] || { echo "no sandboxes"; return 0; }
-  printf '%-16s %-6s %-8s %-9s %s\n' NAME PORT STATE PID SOURCE
-  local m
-  for m in "$SBX_ROOT"/*/manifest.json; do
-    [ -f "$m" ] || continue
-    local n p src pid state
-    n="$(python3 -c "import json;print(json.load(open('$m'))['name'])")"
-    p="$(python3 -c "import json;print(json.load(open('$m'))['port'])")"
-    src="$(python3 -c "import json;print(json.load(open('$m'))['source'])")"
-    pid="$(daemon_pid "$n")"; state="stopped"; daemon_alive "$n" && state="running"
-    printf '%-16s %-6s %-8s %-9s %s\n' "$n" "$p" "$state" "${pid:-–}" "$src"
-  done
-}
-cmd_status(){
-  local name="$1"; mexists "$name" || die "no such sandbox: $name"
-  python3 -m json.tool "$(manifest "$name")"
-  daemon_alive "$name" && echo "state: running (pid $(daemon_pid "$name")) stats: $(sbx_stats "$name")" || echo "state: stopped"
-  [ -f "$(sdir "$name")/validate.json" ] && { echo "--- last validation ---"; python3 -m json.tool "$(sdir "$name")/validate.json"; }
-}
-
-# ================================================================ dev ==========
-# ONE-COMMAND isolated dev environment. Everything a newcomer (Tim, any agent)
-# needs to go from clone -> coding on an isolated running mind, in a single shot:
-#   1) a git BRANCH  (dev/<name>, or --prefix)
-#   2) a git WORKTREE for it, at a visible path they can open + edit
-#   3) an ISOLATED engram bound to a NON-default port, on a clone of the live store
-#      (stock prod binary by default — instant + safe; --build to compile the
-#       worktree's own runtime instead). Prod :$LIVE_BIND_PORT/:$SOUL_PORT is untouchable.
-#
-# This is additive sugar over the proven primitives (git worktree + cmd_create).
-# It never binds a forbidden port and never touches ~/.neuron/engram (the live store)
-# except the same READ-only snapshot cmd_create already performs.
-#
-#   nsbx dev <name> [--repo R] [--base REF] [--worktree DIR] [--port N]
-#                   [--prefix P] [--build] [--no-engram]
-cmd_dev(){
-  local name="" repo="$EL_REPO" base="" wt="" port="" prefix="dev/" build=0 no_engram=0
-  [ $# -gt 0 ] && [ "${1#-}" = "$1" ] && { name="$1"; shift; } || die "usage: nsbx dev <name> [flags]"
-  while [ $# -gt 0 ]; do case "$1" in
-    --repo) repo="$2"; shift 2;;
-    --base) base="$2"; shift 2;;
-    --worktree|--wt) wt="$2"; shift 2;;
-    --port) port="$2"; shift 2;;
-    --prefix) prefix="$2"; shift 2;;
-    --build) build=1; shift;;
-    --no-engram) no_engram=1; shift;;
-    *) die "unknown flag: $1";;
-  esac; done
-  need git
-  git -C "$repo" rev-parse --git-dir >/dev/null 2>&1 || die "not a git repo: $repo"
-
-  local branch="${prefix}${name}"
-  local sbx="dev-${name}"
-  # default worktree path: a PERSISTENT, git-managed dir — NEVER /tmp (which is
-  # ablated on compaction). Default root = <repo-grandparent>/el-worktrees, i.e.
-  # ~/Development/neuron-technologies/el-worktrees/<name>. Override with NSBX_DEV_WT_ROOT.
-  local wt_root="${NSBX_DEV_WT_ROOT:-$(cd "$(dirname "$(dirname "$repo")")" && pwd -P)/el-worktrees}"
-  [ -n "$wt" ] || wt="${wt_root}/${name}"
-  case "$wt" in /tmp/*|/private/tmp/*|/var/tmp/*)
-    die "refusing worktree under a temp dir ($wt) — temp dirs are ablated on compaction; set NSBX_DEV_WT_ROOT to a persistent path";;
-  esac
-  # default base: whatever the repo's working checkout is on now
-  [ -n "$base" ] || base="$(git -C "$repo" rev-parse --abbrev-ref HEAD 2>/dev/null)"
-
-  # pre-flight (fail before creating anything)
-  [ "$no_engram" -eq 1 ] || ! mexists "$sbx" || die "engram sandbox '$sbx' already exists (nsbx dev-down $name first)"
-  [ -e "$wt" ] && die "worktree path already exists: $wt"
-  if [ -n "$port" ]; then
-    { [ "$port" = "$LIVE_BIND_PORT" ] || [ "$port" = "$SOUL_PORT" ]; } && die "refusing forbidden port $port (live)"
-  fi
-
-  log "dev env '$name'  (branch=$branch  worktree=$wt  base=$base)"
-
-  # ---- 1+2) branch + worktree in one shot ----
-  local gerr
-  if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then
-    info "branch $branch exists — checking it out into a new worktree"
-    gerr="$(git -C "$repo" worktree add "$wt" "$branch" 2>&1)" \
-      || die "git worktree add failed for existing branch $branch:"$'\n'"    $gerr"
-  else
-    gerr="$(git -C "$repo" worktree add -b "$branch" "$wt" "$base" 2>&1)" \
-      || die "git worktree add -b $branch (base $base) failed:"$'\n'"    $gerr"$'\n'"    (a bare 'dev' branch blocks 'dev/*' names — try --prefix, e.g. nsbx dev $name --prefix wt/)"
-  fi
-  ok "worktree ready: $wt  (branch $branch)"
-
-  # ---- 3) isolated engram ----
-  local eport="(none)"
-  if [ "$no_engram" -eq 1 ]; then
-    warn "--no-engram: skipped standing up an engram"
-  else
-    if [ "$build" -eq 1 ]; then
-      log "isolated engram: building the worktree's own runtime"
-      cmd_create "$sbx" ${port:+--port "$port"} --source "$wt" || die "engram create (--build) failed"
-    else
-      log "isolated engram: stock prod binary on a clone of the live store"
-      cmd_create "$sbx" ${port:+--port "$port"} || die "engram create failed"
-    fi
-    eport="$(mget "$sbx" "['port']")"
-    # record the dev linkage next to the sandbox so dev-down can clean up
-    python3 - "$(sdir "$sbx")/dev.json" "$name" "$branch" "$wt" "$repo" "$eport" <<'PY'
-import json,sys
-p,name,branch,wt,repo,port=sys.argv[1:7]
-json.dump({"name":name,"branch":branch,"worktree":wt,"repo":repo,"port":int(port)},
-          open(p,'w'),indent=2)
-PY
-    # ---- pin the WHOLE worktree to the CLONE ----
-    # Every var any El tooling in this worktree might read for an engram target now
-    # points at the isolated clone. Sourcing .nsbx-env makes hitting live :$LIVE_BIND_PORT
-    # or ~/.neuron/engram by accident structurally impossible from this shell.
-    local edata ekey eurl ebin
-    edata="$(sdir "$sbx")/data"; ekey="sbx-$sbx"; eurl="http://127.0.0.1:$eport"; ebin="$(sdir "$sbx")/bin/engram"
-    cat > "$wt/.nsbx-env" <<ENV
-# nsbx dev env for '$name' — SOURCE this to pin THIS shell to the isolated clone.
-# The live mind (:$LIVE_BIND_PORT engram / :$SOUL_PORT soul / $LIVE_DATA_DIR) is deliberately
-# NOT referenced here. Regenerated by 'nsbx dev'.  ->  source .nsbx-env
-export NSBX_NAME="$sbx"
-export ENGRAM_URL="$eurl"
-export ENGRAM_BIND=":$eport"
-export ENGRAM_PORT="$eport"
-export ENGRAM_HOST="127.0.0.1"
-export ENGRAM_DATA_DIR="$edata"
-export ENGRAM_API_KEY="$ekey"
-export NEURON_ENGRAM_URL="$eurl"
-export NEURON_ENGRAM_KEY="$ekey"
-# nsbx run compatibility (same names 'nsbx run' exports)
-export SBX_NAME="$sbx" SBX_PORT="$eport" SBX_URL="$eurl" SBX_KEY="$ekey" SBX_DATA="$edata" SBX_BIN="$ebin"
-ENV
-    # direnv users get it automatically on cd; everyone else runs 'source .nsbx-env'
-    [ -e "$wt/.envrc" ] || printf 'source_env .nsbx-env 2>/dev/null || source .nsbx-env\n' > "$wt/.envrc"
-    ok "wrote $wt/.nsbx-env (pins this worktree to the clone)"
-  fi
-
-  # ---- summary ----
-  echo >&2
-  printf '%s  DEV ENV READY — %s%s\n' "$C_BLD" "$name" "$C_0" >&2
-  printf '   %-10s %s\n' "worktree" "$wt" >&2
-  printf '   %-10s %s\n' "branch"   "$branch" >&2
-  if [ "$no_engram" -ne 1 ]; then
-    printf '   %-10s %s\n' "engram"   "http://127.0.0.1:$eport   (isolated clone; prod :$LIVE_BIND_PORT untouchable)" >&2
-    printf '   %-10s %s\n' "sandbox"  "$sbx" >&2
-    echo >&2
-    printf '%s   env exported into %s/.nsbx-env  (source it -> pinned to the clone):%s\n' "$C_DIM" "$wt" "$C_0" >&2
-    grep '^export' "$wt/.nsbx-env" | sed 's/^/     /' >&2
-  fi
-  echo >&2
-  info "code in:     cd $wt && source .nsbx-env   # now every engram var points at the clone"
-  [ "$no_engram" -ne 1 ] && info "poke it:     nsbx run $sbx api /api/stats     (or: make run NAME=$name)"
-  [ "$no_engram" -ne 1 ] && info "edit->test:  make build NAME=$name && make run NAME=$name   # El change -> clone, seconds"
-  info "tear down:   nsbx dev-down $name    (destroys engram + removes worktree; branch kept)"
-}
-
-# nsbx dev-down <name> [--delete-branch] [--repo R]
-# Teardown counterpart: destroy the isolated engram, remove the git worktree,
-# and (optionally) delete the branch. Live prod is never touched.
-cmd_dev_down(){
-  local name="" repo="$EL_REPO" del_branch=0
-  [ $# -gt 0 ] && [ "${1#-}" = "$1" ] && { name="$1"; shift; } || die "usage: nsbx dev-down <name> [--delete-branch]"
-  while [ $# -gt 0 ]; do case "$1" in
-    --repo) repo="$2"; shift 2;;
-    --delete-branch) del_branch=1; shift;;
-    *) die "unknown flag: $1";;
-  esac; done
-  local sbx="dev-${name}" wt="" branch="dev/${name}"
-  # recover worktree/branch/repo from the dev linkage if present
-  if mexists "$sbx" && [ -f "$(sdir "$sbx")/dev.json" ]; then
-    local dj; dj="$(sdir "$sbx")/dev.json"
-    wt="$(python3 -c "import json;print(json.load(open('$dj'))['worktree'])" 2>/dev/null)"
-    branch="$(python3 -c "import json;print(json.load(open('$dj'))['branch'])" 2>/dev/null)"
-    repo="$(python3 -c "import json;print(json.load(open('$dj'))['repo'])" 2>/dev/null)"
-  fi
-  # 1) engram
-  if mexists "$sbx"; then cmd_destroy "$sbx"; else info "no engram sandbox '$sbx'"; fi
-  # 2) worktree
-  if [ -n "$wt" ] && [ -d "$wt" ]; then
-    log "removing git worktree $wt"
-    git -C "$repo" worktree remove --force "$wt" 2>/dev/null || rm -rf "$wt"
-    git -C "$repo" worktree prune 2>/dev/null || true
-    ok "worktree removed"
-  else info "no worktree to remove"; fi
-  # 3) branch (opt-in)
-  if [ "$del_branch" -eq 1 ]; then
-    git -C "$repo" branch -D "$branch" 2>/dev/null && ok "deleted branch $branch" || warn "could not delete branch $branch"
-  else info "branch $branch kept (use --delete-branch to remove)"; fi
-  ok "dev-down '$name' complete (live untouched)"
-}
-
-usage(){ cat >&2 <<EOF
-${C_BLD}nsbx${C_0} — Neuron Sandbox: experiments + code changes against the REAL engram
-runtime on an isolated snapshot of the live mind, with a gated promote-to-prod path.
-
-  nsbx dev     <name> [--base REF] [--worktree DIR]       ONE command onboarding: new branch (dev/<name>) + git
-                      [--port N] [--prefix P] [--build]   worktree (persistent, never /tmp) + isolated engram on a
-                      [--no-engram] [--repo R]            non-default port. clone -> coding on the mind in one shot.
-  nsbx dev-down <name> [--delete-branch] [--repo R]       teardown: destroy the engram + remove the worktree
-                                                          (branch kept unless --delete-branch). live untouched.
-  nsbx up      [name] [flags…]                            one command: your private, isolated copy of the mind
-                                                          (creates on first run, starts thereafter; prod untouchable)
-  nsbx create  [name] [--port N] [--source DIR | --branch REF [--repo R] | --binary PATH]
-                       clone live store+WAL+config, place/build the runtime, boot on an
-                       isolated port (never :$LIVE_BIND_PORT/:$SOUL_PORT). Default runtime = stock prod binary.
-  nsbx build   <name> --source DIR | --branch REF        rebuild the runtime from a code change + hot-restart
-  nsbx run     <name> <cmd...> | api <path> [json]        run an experiment; capture output + metrics
-  nsbx validate <name>                                    rails as checks: zero-loss(load+reboot), reboot-prove,
-                                                          RSS bound, retrieval parity, keystone integrity
-  nsbx promote <name> [--data] [--i-approve-prod-cutover] GATED rails cutover to prod (DRY-RUN without approval)
-  nsbx destroy <name>                                     stop daemon, free port, remove clone (live untouched)
-  nsbx list  |  nsbx status <name>
-
-Env in 'run' cmds: \$SBX_URL \$SBX_PORT \$SBX_KEY \$SBX_DATA \$SBX_BIN \$SBX_NAME
-EOF
-}
-
-main(){
-  local cmd="${1:-}"; shift || true
-  case "$cmd" in
-    dev)      cmd_dev      "$@";;
-    dev-down) cmd_dev_down "$@";;
-    up)       cmd_up       "$@";;
-    create)   cmd_create   "$@";;
-    build)    cmd_build    "$@";;
-    run)      cmd_run      "$@";;
-    validate) cmd_validate "$@";;
-    promote)  cmd_promote  "$@";;
-    destroy)  cmd_destroy  "$@";;
-    list|ls)  cmd_list     "$@";;
-    status)   cmd_status   "$@";;
-    ""|-h|--help|help) usage;;
-    *) die "unknown command: $cmd (try: nsbx help)";;
-  esac
-}
-main "$@"