engram: fix lazy-embed index gap (#20) and make activate's cosine scan lazy; extract vindex harvest primitive with a bench/oracle harness

Adds an O(1) "seen" bitmap so lazily-embedded older nodes get picked up
incrementally instead of only on a full rebuild (embed-gap #20).

Replaces engram_activate's O(N*D) cosine prescan with a lazy-memoized
cosine cache (eg_cosq_at), proven bit-identical to the old path.

Extracts a clean vindex_harvest_from_store primitive (read-only vector
harvest, careful malloc/ownership/error-path handling) reused by both
index-build and the new vindex_bench.c — a read-only proof harness
comparing brute-force vs HNSW recall/latency on both the real store and
synthetic data.

.nsbx-env intentionally excluded — local sandbox config (ports, paths,
dev-only placeholder key), not checked in.

.gitea/workflows/ci-dev.yaml

@@ -214,18 +214,9 @@ 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}"
 
@@ -277,12 +268,6 @@ 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,21 +212,12 @@ 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}"
 
@@ -262,12 +253,6 @@ 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,21 +288,12 @@ 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}"
 
@@ -354,12 +345,6 @@ 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 }}

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 -DHAVE_CURL \
+          cc -std=c11 -O2 \
             -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 -DHAVE_CURL \
+          cc -std=c11 -O2 \
             -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 -DHAVE_CURL \
+          cc -std=c11 -O2 \
             -I /usr/local/lib/el \
             -o dist/engram \
             dist/engram.c \

engram/dist/engram.c

@@ -10,6 +10,8 @@ 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);
@@ -18,16 +20,19 @@ 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);
 
@@ -116,11 +121,20 @@ 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; });
-  engram_save(el_str_concat(dir, EL_STR("/snapshot.json")));
-  return 1;
+  return engram_save(el_str_concat(dir, EL_STR("/snapshot.json")));
   return 0;
 }
 
@@ -128,9 +142,18 @@ 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_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 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 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;
@@ -158,7 +181,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_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 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 snap_path = el_str_concat(dir, EL_STR("/.scan-export.json"));
   engram_save(snap_path);
   el_val_t snap = fs_read(snap_path);
@@ -174,22 +197,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_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 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 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_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; });
+  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; });
   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_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; });
+  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; });
   if (str_eq(q, EL_STR(""))) {
     return err_json(EL_STR("missing query"));
   }
-  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; });
+  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; });
   return el_str_concat(el_str_concat(EL_STR("{\"results\":"), engram_activate_json(q, depth)), EL_STR("}"));
   return 0;
 }
@@ -198,15 +221,50 @@ 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_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; });
+  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; });
   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(""))) {
@@ -242,36 +300,51 @@ 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_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("\"}"));
+  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("}"));
   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_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();
+  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("}"));
   return 0;
 }
 
 el_val_t route_health(el_val_t method, el_val_t path, el_val_t body) {
-  return EL_STR("{\"status\":\"ok\",\"engine\":\"engram-runtime-native\"}");
+  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 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_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 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 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 EL_STR("{\"nodes\":[],\"edges\":[]}");
+    return err_json(EL_STR("sync export failed: snapshot unreadable"));
   }
   return snap;
   return 0;
@@ -305,7 +378,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_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 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 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;
@@ -317,21 +390,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_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 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 category_raw = json_get_string(body, EL_STR("category"));
-  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 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 ktier_raw = json_get_string(body, EL_STR("tier"));
-  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 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 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_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 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 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_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 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 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_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 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 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);
@@ -342,6 +415,20 @@ 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(""))) {
@@ -377,6 +464,12 @@ 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);
   }
@@ -395,6 +488,9 @@ 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);
   }
@@ -425,6 +521,12 @@ 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;
 }
@@ -432,10 +534,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_25 = 0; if (str_eq(bind_raw, EL_STR(""))) { _if_result_25 = (EL_STR(":8742")); } else { _if_result_25 = (bind_raw); } _if_result_25; });
+  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; });
   port = parse_port(bind_str);
   data_dir_raw = env(EL_STR("ENGRAM_DATA_DIR"));
-  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; });
+  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; });
   snapshot_path = el_str_concat(data_dir, EL_STR("/snapshot.json"));
   engram_load(snapshot_path);
   boot_snap = fs_read(snapshot_path);

engram/spec/cognitive-architecture.design.md

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

epm/src/install.el

@@ -17,16 +17,6 @@
 //   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,15 +14,6 @@
 //   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,15 +6,6 @@
 // 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/AGENTS.md

@@ -4,6 +4,37 @@ El is a self-hosting, statically-typed language that compiles to C. This file or
 
 ---
 
+## Current work in this worktree — the API reshape / decorated seam (IN PROGRESS, 2026-08-14)
+
+This is the `api-reshape` worktree. The build here reshapes Neuron's external
+surface and how it is *declared* — proven on isolated dev-port clones only; **live
+prod engram `:8742` is untouched and nothing is promoted.** Full framing lives in
+`neuron/docs/architecture/06-cognitive-architecture.md` (Update — 2026-08-14 deep
+night) and `02-components.md §5`.
+
+- **Surface collapse.** The ~90 noun-organized CRUD MCP tools collapse to a few
+  **geometry ops** — `read` (the *vantage-read*: re-origin + salience/recency +
+  an **aperture** → a bounded slice, curing the whole-self dump), `write`,
+  `relate`, `supersede` (evolve/tombstone/promote, never a hard delete) — plus the
+  agentic primitives `think`/`attend`/`learn`/`ground`/`assert`. The old noun is a
+  `type` parameter. Implemented in `tools/api-reshape/surface.el` with a parity
+  harness (`parity.sh`); aperture proven to bound output. **Not yet:** compiled
+  into the MCP server, hot-swap, all-alias dispatch.
+- **Decorated seam.** `@route(path,method,…)` makes codegen synthesize
+  `el_route_dispatch` (replacing the hand-written `handle_request` if-else) —
+  proven decorate→serve on `:8951`. `@manager`/`@engine`/`@accessor` are **parsed
+  but structurally inert** in the shipped compiler today; the `@route` codegen
+  lives on the **unmerged branch `feat/el-route-decorators`**. Telemetry-emit and
+  dharma-bus auto-wiring at the boundary are **staged, not shipped**. In-process,
+  an `@accessor` reaches the engram via **`engram_*` builtins**, not `http_get`.
+
+**Do not edit** the protected build sources while this is in flight:
+`el-compiler/src/codegen.el`, `el-compiler/runtime/el_seed.c` (and the archived
+`legacy/el_runtime.c`), the `runtime/engram_*.c` boot files, and `surface.el`
+(when present in the reshape tree) — these are owned by the build agents.
+
+---
+
 ## What El Is
 
 El compiles `.el` source → C → native binary. Every El value is `el_val_t` (int64_t). Strings are heap pointers cast through int64_t. The compiler is written in El (self-hosting).

lang/el-compiler/runtime/el_platform_win.h

@@ -75,7 +75,6 @@ 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,14 +82,8 @@ 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.
- * 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;
+ * Allows serving PNGs and other binary files without strlen truncation. */
+static _Thread_local size_t  _tl_fs_read_len  = 0;
 
 static void el_arena_track(char* p) {
     if (!_tl_arena_active || !p) return;
@@ -107,8 +101,6 @@ 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.
@@ -1492,14 +1484,11 @@ 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 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);
+    /* 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);
     _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);
@@ -1556,6 +1545,17 @@ 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,8 +1564,13 @@ static void* http_worker(void* arg) {
     int fd = a->fd;
 #endif
     free(a);
-    char *method = NULL, *path = NULL, *body = NULL;
-    if (http_read_request(fd, &method, &path, &body, NULL) == 0) {
+    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) {
         http_handler_fn h = http_lookup_active();
         char* response = NULL;
         /* HEAD: dispatch as GET so existing handlers respond with the same
@@ -1579,22 +1584,11 @@ 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.
-             * 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;
-            }
+             * 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);
             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");
         }
@@ -1604,7 +1598,7 @@ static void* http_worker(void* arg) {
         _tl_http_head_only = 0;
         free(response);
     }
-    free(method); free(path); free(body);
+    free(method); free(path); free(body); free(hdr_block);
     el_closesocket(fd);
     /* release a slot */
     pthread_mutex_lock(&_http_conn_mu);
@@ -1614,6 +1608,108 @@ 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);
@@ -1632,13 +1728,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;
-    addr.sin6_addr = in6addr_any;
+    el_http_apply_bind_addr(&addr);
     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 [::]:%d (dual-stack)\n", p);
+    fprintf(stderr, "[http] listening on %s port %d\n", el_http_bind_desc(), p);
     while (1) {
         struct sockaddr_in6 cli;
         socklen_t clen = sizeof(cli);
@@ -1844,20 +1940,10 @@ 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);
-            /* 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;
-            }
+            size_t rlen = _tl_fs_read_len > 0 ? _tl_fs_read_len : (rs ? strlen(rs) : 0);
             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(
@@ -1898,13 +1984,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;
-    addr.sin6_addr = in6addr_any;
+    el_http_apply_bind_addr(&addr);
     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 [::]:%d (dual-stack)\n", p);
+    fprintf(stderr, "[http v2] listening on %s port %d\n", el_http_bind_desc(), p);
     while (1) {
         struct sockaddr_in6 cli;
         socklen_t clen = sizeof(cli);
@@ -1995,19 +2081,18 @@ 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;
-    /* 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));
+    setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, &yes, sizeof(yes));
+    setsockopt(sock, IPPROTO_IPV6, IPV6_V6ONLY, &no, sizeof(no));
     struct sockaddr_in6 addr;
     memset(&addr, 0, sizeof(addr));
     addr.sin6_family = AF_INET6;
-    addr.sin6_addr = in6addr_any;
+    el_http_apply_bind_addr(&addr);
     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 [::]:%d (dual-stack)\n", p);
+    fprintf(stderr, "[http] async listening on %s port %d\n", el_http_bind_desc(), p);
     HttpServeAsyncArg* a = malloc(sizeof(HttpServeAsyncArg));
     if (!a) { close(sock); return; }
     a->sock = sock;
@@ -2056,7 +2141,6 @@ 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(""));
@@ -2068,7 +2152,6 @@ 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);
 }
@@ -3174,10 +3257,72 @@ static char* jp_parse_string_raw(JsonParser* jp) {
                 case 'r':  c = '\r'; break;
                 case 't':  c = '\t'; break;
                 case 'u': {
-                    /* Skip 4 hex digits; emit '?' as a placeholder */
-                    for (int i = 0; i < 4 && jp->p < jp->end; i++) jp->p++;
-                    c = '?';
-                    break;
+                    /* 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 */
                 }
                 default: c = esc; break;
             }
@@ -3611,10 +3756,8 @@ 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.
-     * (Kept although the pointer pairing now makes this redundant.) */
+     * string, not the raw file bytes, so Content-Length must use strlen. */
     _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);
@@ -6085,6 +6228,13 @@ 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 ──────────────────────────────────────
  *
@@ -6932,243 +7082,6 @@ 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);
@@ -7179,15 +7092,8 @@ 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) { free(qvec); return lst; }
+    if (!hits) return lst;
     int64_t nhits = 0;
     for (int64_t i = 0; i < g->node_count; i++) {
         EngramNode* n = &g->nodes[i];
@@ -7197,24 +7103,20 @@ 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);
-        double sem = qvec ? engram_node_cosine(n, qvec, qdim) : 0.0;
-        if (sc > 0 || sem >= sem_min) {
+        if (sc > 0) {
             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.
-     * Pure-semantic hits (token score 0) sort after every lexical hit — a
-     * lexical ∪ semantic union with lexical precedence. */
+    /* Rank by distinct tokens matched (desc) then salience (desc), then cap. */
     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;
 }
 
@@ -7537,6 +7439,48 @@ 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);
@@ -7564,31 +7508,21 @@ 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;
     }
-    /* 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. */
+    /* 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. */
     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);
-        double sem = q_vec ? engram_node_cosine(n, q_vec, q_dim) : 0.0;
-        if (sc > 0 || sem >= q_sem_min) {
+        if (sc > 0) {
             double tdecay = engram_temporal_decay(n, now_ms);
             double dampen = engram_activation_dampen(n);
-            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 */
+            double cover  = ntok > 0 ? (double)sc / (double)ntok : 1.0;
+            double act    = n->salience * tdecay * dampen * cover;
             seeds[seed_count].idx        = i;
             seeds[seed_count].act        = act;
             seeds[seed_count].created_at = n->created_at;
@@ -7598,7 +7532,6 @@ 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) {
@@ -7753,6 +7686,12 @@ 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,
@@ -8130,6 +8069,9 @@ 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;
 }
@@ -8154,16 +8096,14 @@ 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.
  *
- * 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.
+ * Exact match (strcmp, not substring) because labels like "conv:history"
+ * must not collide with nodes whose content contains that substring.
  *
- * 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. */
+ * 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. */
 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("{}"));
@@ -8186,50 +8126,39 @@ 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, '[');
-    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. */
+    int first = 1;
+    if (q && *q) {
         char toks[ENGRAM_MAX_QTOKENS][ENGRAM_QTOK_LEN];
         int ntok = engram_tokenize_query(q, toks, ENGRAM_MAX_QTOKENS);
-        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++;
+        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++;
+                    }
                 }
+                /* 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));
@@ -8747,6 +8676,9 @@ 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,7 +1072,6 @@ 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,7 +226,6 @@ 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,7 +2670,6 @@ 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 }
@@ -2917,6 +2916,24 @@ fn build_int_names_for_params(params: [Map<String, Any>]) -> Bool {
     return true
 }
 
+// fn_has_decorator — does this FnDef carry a decorator named `name`?
+// Reads the `decorators` list [{name, args}] attached by the parser. Absent
+// key -> native_list_len returns 0 -> false. This is the multi-decorator-aware
+// replacement for the old single `decorator` string check, so a fn may stack
+// roles with other decorators (e.g. `@route(...) @manager fn ...`).
+fn fn_has_decorator(stmt: Map<String, Any>, name: String) -> Bool {
+    let dl = stmt["decorators"]
+    let n: Int = native_list_len(dl)
+    let i = 0
+    while i < n {
+        let d = native_list_get(dl, i)
+        let dn: String = d["name"]
+        if str_eq(dn, name) { return true }
+        let i = i + 1
+    }
+    false
+}
+
 fn cg_fn(stmt: Map<String, Any>) -> Void {
     let fn_name: String = stmt["name"]
     // Skip El's `fn main()` - C provides its own main() for top-level stmts
@@ -2928,10 +2945,10 @@ fn cg_fn(stmt: Map<String, Any>) -> Void {
     let params_c: String = params_to_c(params)
     // VBD role enforcement: dharma_emit / dharma_field may only be called
     // from @manager-decorated functions. Surface violations to the C compiler
-    // via #error directives emitted before the function definition.
-    let decorator: String = stmt["decorator"]
+    // via #error directives emitted before the function definition. Read the
+    // decorator LIST so the role may be stacked with other decorators.
     if vbd_has_restricted_call(body) {
-        if !str_eq(decorator, "manager") {
+        if !fn_has_decorator(stmt, "manager") {
             emit_line("#error \"VBD violation: dharma_emit/dharma_field called from non-@manager fn '" + fn_name + "'\"")
         }
     }
@@ -2939,6 +2956,15 @@ fn cg_fn(stmt: Map<String, Any>) -> Void {
     // arithmetic vs concat on type-annotated identifiers.
     build_int_names_for_params(params)
     emit_line("el_val_t " + fn_name + "(" + params_c + ") {")
+    // ── API-reshape decorator-seam: auto-emit at the decorated-fn boundary ──
+    // Every @manager/@accessor fn gets ONE injected call to engram_boundary_beat
+    // at entry — interoception (chrono tick) + telemetry (afferent counter) +
+    // strengthen (self-activity) + a dharma bus event — so a decorated op
+    // self-reports with ZERO hand-written instrumentation in its body. (VBD role
+    // = the topmost decorator; write it topmost when stacking with @route.)
+    if fn_has_decorator(stmt, "manager") || fn_has_decorator(stmt, "accessor") {
+        emit_line("  engram_boundary_beat(EL_STR(" + c_str_lit(fn_name) + "));")
+    }
     // Seed declared with parameter names so reassignment works
     let decl = native_list_empty()
     let np: Int = native_list_len(params)
@@ -3480,6 +3506,259 @@ fn cg_decl_streaming(stmt: Map<String, Any>) -> Void {
     }
 }
 
+// ── @route dispatcher generation ──────────────────────────────────────────────
+//
+// Scan the token stream for @route-decorated fns and synthesize a generic HTTP
+// dispatcher `el_route_dispatch(method, clean, path, body)`. A decorated handler
+// must have the uniform signature (method, path, body) -> String. The dispatcher
+// matches `clean` (the query-stripped path, supplied by the caller) against each
+// route and calls the handler with the ORIGINAL `path` so query strings survive.
+// Returns the sentinel "__EL_NO_ROUTE__" when nothing matches, so the caller may
+// fall through to any remaining hand-written branches (mixed mode).
+//
+// Decorator grammar: @route(path, method, kind, suffix)
+//   path   — the match string (or the prefix, for compound)
+//   method — "GET" | "POST" | ... ; a '|'-list like "GET|POST"; "ANY"/"" = no guard
+//   kind   — "exact" (default) | "prefix" | "suffix" | "compound"
+//   suffix — for "compound": the required str_ends_with suffix
+//
+// The dispatch table is emitted SPECIFICITY-SORTED (most-specific first), NOT in
+// source order, so overlapping prefixes (e.g. /api/x/search vs /api/x) never
+// shadow each other regardless of how the handlers are written.
+
+// split_pipe — split "GET|POST" on '|' into ["GET","POST"]. Self-contained
+// (no dependency on str_split runtime semantics).
+fn split_pipe(s: String) -> [String] {
+    let out: [String] = native_list_empty()
+    let cur: String = ""
+    let n: Int = str_len(s)
+    let i: Int = 0
+    while i < n {
+        let ch: String = str_slice(s, i, i + 1)
+        if str_eq(ch, "|") {
+            let out = native_list_append(out, cur)
+            let cur = ""
+        } else {
+            let cur = cur + ch
+        }
+        let i = i + 1
+    }
+    let out = native_list_append(out, cur)
+    out
+}
+
+// route_make_record — build a route record map from the @route decorator args.
+fn route_make_record(fn_name: String, args: [String]) -> Map<String, Any> {
+    let na: Int = native_list_len(args)
+    let rpath: String = ""
+    if na >= 1 { let rpath = native_list_get(args, 0) }
+    let rmethod: String = "GET"
+    if na >= 2 { let rmethod = native_list_get(args, 1) }
+    let rkind: String = "exact"
+    if na >= 3 { let rkind = native_list_get(args, 2) }
+    let rsuffix: String = ""
+    if na >= 4 { let rsuffix = native_list_get(args, 3) }
+    { "name": fn_name, "path": rpath, "method": rmethod, "kind": rkind, "suffix": rsuffix }
+}
+
+// route_spec_score — higher = more specific = emitted earlier. Ordering:
+// exact > compound > suffix > prefix; within a class, a longer path/suffix
+// wins (so /api/x/search sorts before /api/x). Guarantees correct dispatch
+// independent of source order.
+fn route_spec_score(rec: Map<String, Any>) -> Int {
+    let kind: String = rec["kind"]
+    let path: String = rec["path"]
+    let suffix: String = rec["suffix"]
+    let plen: Int = str_len(path)
+    let slen: Int = str_len(suffix)
+    if str_eq(kind, "exact") { return 4000000 + plen }
+    if str_eq(kind, "compound") { return 3000000 + plen * 100 + slen }
+    if str_eq(kind, "suffix") { return 2000000 + slen }
+    return 1000000 + plen
+}
+
+// route_sort_desc — selection sort of route records by descending specificity.
+// N is small (routes per module), so O(n^2) is fine and keeps codegen simple.
+fn route_sort_desc(recs: [Map<String, Any>]) -> [Map<String, Any>] {
+    let n: Int = native_list_len(recs)
+    let out: [Map<String, Any>] = native_list_empty()
+    let used: [Bool] = native_list_empty()
+    let u: Int = 0
+    while u < n {
+        let used = native_list_append(used, false)
+        let u = u + 1
+    }
+    let picked: Int = 0
+    while picked < n {
+        let best_i: Int = 0 - 1
+        let best_score: Int = 0 - 1
+        let i: Int = 0
+        while i < n {
+            let is_used: Bool = native_list_get(used, i)
+            if !is_used {
+                let sc: Int = route_spec_score(native_list_get(recs, i))
+                if sc > best_score {
+                    let best_score = sc
+                    let best_i = i
+                }
+            }
+            let i = i + 1
+        }
+        let out = native_list_append(out, native_list_get(recs, best_i))
+        // Rebuild `used` with best_i marked (runtime has no native_list_set).
+        let new_used: [Bool] = native_list_empty()
+        let j: Int = 0
+        while j < n {
+            if j == best_i {
+                let new_used = native_list_append(new_used, true)
+            } else {
+                let new_used = native_list_append(new_used, native_list_get(used, j))
+            }
+            let j = j + 1
+        }
+        let used = new_used
+        let picked = picked + 1
+    }
+    out
+}
+
+// scan_routes — token-level scan collecting every @route-decorated fn as a
+// route record. Runs once per module (like scan_fn_sigs) so the dispatcher can
+// be synthesized in the streaming backend, which discards per-fn ASTs. Handles
+// decorator STACKING: `@route(...) @manager fn` still records the route.
+fn scan_routes(tokens: [Any]) -> [Map<String, Any>] {
+    let total: Int = native_list_len(tokens) / 2
+    let recs: [Map<String, Any>] = native_list_empty()
+    let has_pending: Bool = false
+    let pending_args: [String] = native_list_empty()
+    let pos: Int = 0
+    let going: Bool = true
+    while going {
+        if pos >= total {
+            let going = false
+        } else {
+            let k: String = tok_kind(tokens, pos)
+            if str_eq(k, "Eof") {
+                let going = false
+            } else {
+                if str_eq(k, "At") {
+                    let dname: String = tok_value(tokens, pos + 1)
+                    let p: Int = pos + 2
+                    let args: [String] = native_list_empty()
+                    let ka: String = tok_kind(tokens, p)
+                    if str_eq(ka, "LParen") {
+                        let p = p + 1
+                        let running: Bool = true
+                        while running {
+                            let kd: String = tok_kind(tokens, p)
+                            if str_eq(kd, "RParen") {
+                                let running = false
+                            } else {
+                                if str_eq(kd, "Eof") {
+                                    let running = false
+                                } else {
+                                    if str_eq(kd, "Str") {
+                                        let args = native_list_append(args, tok_value(tokens, p))
+                                    }
+                                    let p = p + 1
+                                }
+                            }
+                        }
+                        if str_eq(tok_kind(tokens, p), "RParen") { let p = p + 1 }
+                    }
+                    if str_eq(dname, "route") {
+                        let has_pending = true
+                        let pending_args = args
+                    }
+                    let pos = p
+                } else {
+                    if str_eq(k, "Fn") {
+                        let fname: String = tok_value(tokens, pos + 1)
+                        if has_pending {
+                            let recs = native_list_append(recs, route_make_record(fname, pending_args))
+                            let has_pending = false
+                        }
+                        let pos = pos + 2
+                    } else {
+                        let pos = pos + 1
+                    }
+                }
+            }
+        }
+    }
+    recs
+}
+
+// program_has_routes — did scan_routes find any @route fn?
+fn program_has_routes(recs: [Map<String, Any>]) -> Bool {
+    native_list_len(recs) > 0
+}
+
+// route_method_guard — C boolean prefix guarding on HTTP method, or "" for none.
+fn route_method_guard(method: String) -> String {
+    if str_eq(method, "") { return "" }
+    if str_eq(method, "ANY") { return "" }
+    if str_contains(method, "|") {
+        let parts: [String] = split_pipe(method)
+        let np: Int = native_list_len(parts)
+        let expr: String = ""
+        let i: Int = 0
+        while i < np {
+            let m: String = native_list_get(parts, i)
+            if str_eq(m, "") {
+                let i = i + 1
+            } else {
+                let piece: String = "str_eq(method, EL_STR(" + c_str_lit(m) + "))"
+                if str_eq(expr, "") {
+                    let expr = piece
+                } else {
+                    let expr = expr + " || " + piece
+                }
+                let i = i + 1
+            }
+        }
+        if str_eq(expr, "") { return "" }
+        return "(" + expr + ") && "
+    }
+    "str_eq(method, EL_STR(" + c_str_lit(method) + ")) && "
+}
+
+// route_match_expr — C boolean matching `clean` against the route path/kind.
+fn route_match_expr(kind: String, path: String, suffix: String) -> String {
+    if str_eq(kind, "prefix") {
+        return "str_starts_with(clean, EL_STR(" + c_str_lit(path) + "))"
+    }
+    if str_eq(kind, "suffix") {
+        return "str_ends_with(clean, EL_STR(" + c_str_lit(path) + "))"
+    }
+    if str_eq(kind, "compound") {
+        return "str_starts_with(clean, EL_STR(" + c_str_lit(path) + ")) && str_ends_with(clean, EL_STR(" + c_str_lit(suffix) + "))"
+    }
+    "str_eq(clean, EL_STR(" + c_str_lit(path) + "))"
+}
+
+// emit_route_dispatch — emit the generated el_route_dispatch definition from the
+// specificity-sorted route records. No-op if there are no routes.
+fn emit_route_dispatch(recs: [Map<String, Any>]) -> Void {
+    if !program_has_routes(recs) { return }
+    let sorted: [Map<String, Any>] = route_sort_desc(recs)
+    emit_line("// ── generated @route dispatcher (specificity-sorted) ──")
+    emit_line("el_val_t el_route_dispatch(el_val_t method, el_val_t clean, el_val_t path, el_val_t body) {")
+    let n: Int = native_list_len(sorted)
+    let i: Int = 0
+    while i < n {
+        let rec = native_list_get(sorted, i)
+        let guard: String = route_method_guard(rec["method"])
+        let match_e: String = route_match_expr(rec["kind"], rec["path"], rec["suffix"])
+        let fn_name: String = rec["name"]
+        emit_line("  if (" + guard + match_e + ") { return " + fn_name + "(method, path, body); }")
+        let i = i + 1
+    }
+    emit_line("  return EL_STR(\"__EL_NO_ROUTE__\");")
+    emit_line("}")
+    emit_blank()
+}
+
 // emit_streaming_preamble — emit #includes, forward decls, and file-scope lets
 // using the pre-scanned signature data (no full AST).
 fn emit_streaming_preamble(sigs: [Map<String, Any>], source: String) -> Void {
@@ -3572,6 +3851,17 @@ fn codegen_streaming(tokens: [Any], sigs: [Map<String, Any>], source: String) ->
     emit_streaming_preamble(sigs, source)
     el_arena_pop(preamble_mark)
 
+    // @route: scan the token stream once for @route-decorated fns. Kept in
+    // codegen_streaming scope (survives the per-fn arena pops and el_release of
+    // tokens below via refcount, like `sigs`). If any exist, forward-declare the
+    // generated dispatcher NOW so hand-written fns (e.g. handle_request) may call
+    // it before its definition is emitted after the fn-emit loop.
+    let route_records: [Map<String, Any>] = scan_routes(tokens)
+    if program_has_routes(route_records) {
+        emit_line("el_val_t el_route_dispatch(el_val_t method, el_val_t clean, el_val_t path, el_val_t body);")
+        emit_blank()
+    }
+
     // Detect whether there is a fn main() and whether there are top-level
     // executable stmts (for library detection) from sigs.
     let has_el_main: Bool = false
@@ -3759,6 +4049,15 @@ fn codegen_streaming(tokens: [Any], sigs: [Map<String, Any>], source: String) ->
         }
     }
 
+    // @route: emit the generated dispatcher definition now — after every handler
+    // fn has been emitted, but before `tokens` is released (route_records holds
+    // its own refs to the extracted strings). No-op unless the module declared
+    // at least one @route fn. Emitted before the test/library early-returns so it
+    // is present in library modules (e.g. neuron's routes.el) too.
+    let route_arena_mark: Any = el_arena_push()
+    emit_route_dispatch(route_records)
+    el_arena_pop(route_arena_mark)
+
     // Tokens fully consumed by the streaming loop — release now to free peak heap.
     el_release(tokens)
 

lang/el-compiler/src/parser.el

@@ -1758,23 +1758,68 @@ fn parse_stmt(tokens: [Any], pos: Int) -> Map<String, Any> {
         return make_result({ "stmt": "TryCatch", "try_body": try_body, "catch_name": catch_name, "catch_body": native_list_empty() }, p)
     }
 
-    // @decorator - capture decorator name and attach to following stmt
+    // @decorator - capture decorator name (and optional string args) and
+    // attach to the following stmt. Backward-compatible: bare @manager /
+    // @engine / @accessor still parse (no parens -> empty args). Decorators
+    // STACK: `@route("/p","GET") @manager fn f()` attaches BOTH to f via a
+    // `decorators` list [{name, args}]. The legacy `decorator` string is kept
+    // populated (topmost decorator) so the JS backend keeps working unchanged.
     if k == "At" {
         let p = pos + 1
         let dec_name = tok_value(tokens, p)
         let p = p + 1
+        // Optional decorator argument list: @name("a", "b", ...)
+        let dec_args = native_list_empty()
+        let ka = tok_kind(tokens, p)
+        if str_eq(ka, "LParen") {
+            let p = p + 1
+            let running_da = true
+            while running_da {
+                let kd = tok_kind(tokens, p)
+                if str_eq(kd, "RParen") {
+                    let running_da = false
+                } else {
+                    if str_eq(kd, "Eof") {
+                        let running_da = false
+                    } else {
+                        if str_eq(kd, "Str") {
+                            let dec_args = native_list_append(dec_args, tok_value(tokens, p))
+                        }
+                        let p = p + 1
+                        let kc = tok_kind(tokens, p)
+                        if str_eq(kc, "Comma") {
+                            let p = p + 1
+                        }
+                    }
+                }
+            }
+            let p = expect(tokens, p, "RParen")
+        }
         let r = parse_stmt(tokens, p)
         let inner = r["node"]
         let p2 = r["pos"]
         let inner_kind: String = inner["stmt"]
         if str_eq(inner_kind, "FnDef") {
+            // Stack this decorator (topmost-first) onto any decorators the inner
+            // FnDef already carries from decorators written below this one.
+            let this_dec = { "name": dec_name, "args": dec_args }
+            let existing = inner["decorators"]
+            let dlist = native_list_empty()
+            let dlist = native_list_append(dlist, this_dec)
+            let ne: Int = native_list_len(existing)
+            let ei = 0
+            while ei < ne {
+                let dlist = native_list_append(dlist, native_list_get(existing, ei))
+                let ei = ei + 1
+            }
             let with_dec = {
                 "stmt": "FnDef",
                 "name": inner["name"],
                 "params": inner["params"],
                 "body": inner["body"],
                 "ret_type": inner["ret_type"],
-                "decorator": dec_name
+                "decorator": dec_name,
+                "decorators": dlist
             }
             // r result map fully consumed — release to free peak heap.
             el_release(r)

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

@@ -1,186 +0,0 @@
-#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,6 +117,15 @@ 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, ...);
@@ -142,6 +151,7 @@ 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);
 
@@ -167,6 +177,11 @@ 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,...}`
@@ -576,6 +591,7 @@ 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);
@@ -594,12 +610,32 @@ 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. */
@@ -758,18 +794,6 @@ 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

lang/runtime/el_runtime.h

@@ -0,0 +1,883 @@
+/*
+ * el_runtime.h — El language C runtime header
+ *
+ * Declares all built-in functions available to compiled El programs.
+ * Include this in every generated .c file.
+ *
+ * Value model:
+ *   All El values are represented as el_val_t (= int64_t).
+ *   On 64-bit systems a pointer fits in int64_t.
+ *   String values are cast: (el_val_t)(uintptr_t)"hello"
+ *   Integer values are stored directly.
+ *   This lets arithmetic work naturally while still passing strings around.
+ *
+ * Type conventions (El -> C):
+ *   String  -> el_val_t  (holds const char* via uintptr_t cast)
+ *   Int     -> el_val_t
+ *   Bool    -> el_val_t  (0 = false, nonzero = true)
+ *   Any     -> el_val_t
+ *   Void    -> void
+ *
+ * Macros for convenience:
+ *   EL_STR(s)    cast string literal to el_val_t
+ *   EL_CSTR(v)   cast el_val_t back to const char*
+ *   EL_INT(v)    identity — el_val_t is already int64_t
+ *
+ * Link requirements:
+ *   -lcurl     — required for the HTTP client (http_get, http_post, llm_*).
+ *   -lpthread  — required for the HTTP server (one detached thread per
+ *                connection, capped at 64 concurrent).
+ *   -loqs      — optional; required only when liboqs is installed and the
+ *                pq_* / sha3_256_hex entry points are needed. Detected at
+ *                compile time via __has_include(<oqs/oqs.h>).
+ *   -lcrypto   — optional; pulled in alongside -loqs. Used for X25519 in
+ *                pq_hybrid_* and HKDF-SHA256 derivation.
+ *
+ * Canonical compile command:
+ *   cc -std=c11 -I runtime -lcurl -lpthread \
+ *      -o <out> <prog>.c runtime/el_runtime.c
+ *
+ * With liboqs (post-quantum stack):
+ *   cc -std=c11 -I runtime -lcurl -lpthread -loqs -lcrypto \
+ *      -o <out> <prog>.c runtime/el_runtime.c
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdlib.h>
+
+typedef int64_t el_val_t;
+
+#define EL_STR(s)  ((el_val_t)(uintptr_t)(s))
+#define EL_CSTR(v) ((const char*)(uintptr_t)(v))
+#define EL_INT(v)  (v)
+#define EL_NULL    ((el_val_t)0)
+
+/* Float values share the el_val_t (int64) slot via a bit-cast.
+ * The codegen emits Float literals as `el_from_float(<dbl>)` so the
+ * underlying bits represent the IEEE 754 double. Float-aware builtins
+ * (math, format, json) round-trip via these helpers. */
+static inline double el_to_float(el_val_t v) {
+    union { int64_t i; double f; } u;
+    u.i = (int64_t)v;
+    return u.f;
+}
+
+static inline el_val_t el_from_float(double f) {
+    union { double f; int64_t i; } u;
+    u.f = f;
+    return (el_val_t)u.i;
+}
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ── I/O ──────────────────────────────────────────────────────────────────── */
+
+void      println(el_val_t s);
+void      print(el_val_t s);
+el_val_t  readline(void);
+
+/* ── String builtins ─────────────────────────────────────────────────────── */
+
+el_val_t  el_str_concat(el_val_t a, el_val_t b);
+el_val_t  str_eq(el_val_t a, el_val_t b);
+el_val_t  str_starts_with(el_val_t s, el_val_t prefix);
+el_val_t  str_ends_with(el_val_t s, el_val_t suffix);
+el_val_t  str_len(el_val_t s);
+el_val_t  str_concat(el_val_t a, el_val_t b);
+el_val_t  int_to_str(el_val_t n);
+el_val_t  str_to_int(el_val_t s);
+el_val_t  str_slice(el_val_t s, el_val_t start, el_val_t end);
+el_val_t  str_contains(el_val_t s, el_val_t sub);
+el_val_t  str_replace(el_val_t s, el_val_t from, el_val_t to);
+el_val_t  str_to_upper(el_val_t s);
+el_val_t  str_to_lower(el_val_t s);
+el_val_t  str_trim(el_val_t s);
+
+/* ── Math ────────────────────────────────────────────────────────────────── */
+
+el_val_t  el_abs(el_val_t n);
+el_val_t  el_max(el_val_t a, el_val_t b);
+el_val_t  el_min(el_val_t a, el_val_t b);
+
+/* ── Refcount (ARC) ──────────────────────────────────────────────────────────
+ * Lists and Maps carry a refcount. Strings and ints do not — el_retain and
+ * el_release are safe no-ops on non-refcounted values (they sniff a magic
+ * header at offset 0 and only act if the magic matches).
+ *
+ * Codegen emits these at let-binding shadowing, function entry (params), and
+ * function exit (locals other than the returned value). The refcount lets
+ * el_list_append and el_map_set mutate in place when uniquely owned (cheap)
+ * and copy-on-write when shared (preserves persistent semantics across
+ * accumulator patterns in the compiler itself).                              */
+
+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, ...);
+el_val_t  el_list_len(el_val_t list);
+el_val_t  el_list_get(el_val_t list, el_val_t index);
+el_val_t  el_list_append(el_val_t list, el_val_t elem);
+el_val_t  el_list_empty(void);
+el_val_t  el_list_clone(el_val_t list);
+
+/* ── Map ─────────────────────────────────────────────────────────────────── */
+
+el_val_t  el_map_new(el_val_t pair_count, ...);
+el_val_t  el_get_field(el_val_t map, el_val_t key);
+el_val_t  el_map_get(el_val_t map, el_val_t key);
+el_val_t  el_map_set(el_val_t map, el_val_t key, el_val_t value);
+
+/* ── HTTP ─────────────────────────────────────────────────────────────────── */
+
+el_val_t  http_get(el_val_t url);
+el_val_t  http_post(el_val_t url, el_val_t body);
+el_val_t  http_post_json(el_val_t url, el_val_t json_body);
+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);
+
+/* HTTP server v2 ─────────────────────────────────────────────────────────────
+ * Same dispatch model as http_serve, but the handler signature is widened:
+ *
+ *     el_val_t handler(method, path, headers_map, body)
+ *
+ * `headers_map` is an ElMap from lowercased header name → header value (both
+ * Strings). Repeated headers are joined with ", " per RFC 7230.
+ *
+ * Response value: the handler may return either
+ *   (a) a plain body string — same auto-content-type / 200-OK behaviour as
+ *       http_serve (3-arg) — or
+ *   (b) a response envelope built with `http_response(status, headers_json,
+ *       body)`. The runtime detects the envelope discriminator
+ *       `"el_http_response":1` at the start of the returned string and
+ *       unpacks status / headers / body before sending.
+ *
+ * The 3-arg http_serve(port, handler) remains supported unchanged for
+ * existing handlers (e.g. products/web/server.el): it dispatches with
+ * (method, path, body), hardcodes 200 OK, and auto-detects content type. */
+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,...}`
+ * which the runtime's send-path detects and unpacks. Detection happens
+ * uniformly inside http_send_response, so a 3-arg handler may also return
+ * an envelope. The 3-arg variant remains documented as a fixed 200-OK
+ * auto-content-type contract for legacy handlers that return plain bodies. */
+el_val_t  http_response(el_val_t status, el_val_t headers_json, el_val_t body);
+
+/* HTTP timeout — every libcurl request honors EL_HTTP_TIMEOUT_MS (default
+ * 60000ms). Read lazily on first use, so setting the env var any time before
+ * the first http_* call is sufficient.                                    */
+
+/* Streaming variants — write the response body straight to a file via
+ * libcurl's CURLOPT_WRITEFUNCTION = fwrite. These bypass the el_val_t string
+ * wrapper entirely, so binary payloads (audio/mpeg, image/png, etc.) survive
+ * embedded NUL bytes that would truncate a strlen()-based code path.
+ *
+ * Both honor EL_HTTP_TIMEOUT_MS, follow redirects, and accept the same
+ * `headers_map` shape as http_post_with_headers (ElMap of String→String).
+ *
+ * Return value: 1 on success (file fully written), 0 on any failure
+ * (network, file open, partial write). On failure the output file is removed
+ * so callers cannot mistake a partially-written file for a valid one. */
+el_val_t  http_post_to_file(el_val_t url, el_val_t body, el_val_t headers_map, el_val_t output_path);
+el_val_t  http_get_to_file(el_val_t url, el_val_t headers_map, el_val_t output_path);
+
+/* ── URL encoding ────────────────────────────────────────────────────────── */
+
+el_val_t  url_encode(el_val_t s);   /* RFC 3986 unreserved set */
+el_val_t  url_decode(el_val_t s);   /* '+' → space, %XX → byte  */
+
+/* ── HTML allowlist sanitizer ────────────────────────────────────────────────
+ * el_html_sanitize(input_html, allowlist_json) — strict allowlist HTML
+ * cleaner. State-machine parser; tag/attribute names compared case-
+ * insensitively against the allowlist; `<a href>` / `<… src>` URL schemes
+ * validated (http, https, mailto, fragment-only, or relative); whole-
+ * subtree drop for script / style / iframe / object / embed / form; HTML-
+ * escapes free text outside dropped subtrees.
+ *
+ * The allowlist is JSON of the form
+ *     {"p":[],"a":["href","title"],"strong":[],...}
+ * where each value is the array of attribute names allowed for that tag. */
+el_val_t  el_html_sanitize(el_val_t input_html, el_val_t allowlist_json);
+
+/* ── Filesystem ──────────────────────────────────────────────────────────── */
+
+el_val_t  fs_read(el_val_t path);
+el_val_t  fs_write(el_val_t path, el_val_t content);
+el_val_t  fs_list(el_val_t path);
+el_val_t  fs_exists(el_val_t path);
+el_val_t  fs_mkdir(el_val_t path);   /* mkdir -p, mode 0755                */
+
+/* Length-explicit binary write. `length` is an Int (el_val_t holding the
+ * byte count). The caller knows the length from context — typically because
+ * `bytes` came from base64_decode (which produces a magic-tagged binary
+ * buffer with embedded NULs possible) and the caller already tracks the
+ * decoded length, OR because the bytes came from a fixed-size source
+ * (sha256_bytes = 32, hmac_sha256_bytes = 32). Bypasses strlen entirely.
+ *
+ * Returns 1 on success, 0 on failure (invalid path, can't open, partial
+ * write, negative length). On partial-write failure, the file is removed
+ * so callers cannot read back a truncated artefact. */
+el_val_t  fs_write_bytes(el_val_t path, el_val_t bytes, el_val_t length);
+
+/* ── JSON ────────────────────────────────────────────────────────────────── */
+
+el_val_t  json_get(el_val_t json, el_val_t key);
+el_val_t  json_parse(el_val_t s);
+el_val_t  json_stringify(el_val_t v);
+el_val_t  json_get_string(el_val_t json_str, el_val_t key);
+el_val_t  json_get_int(el_val_t json_str, el_val_t key);
+el_val_t  json_get_float(el_val_t json_str, el_val_t key);
+el_val_t  json_get_bool(el_val_t json_str, el_val_t key);
+el_val_t  json_get_raw(el_val_t json_str, el_val_t key);
+el_val_t  json_set(el_val_t json_str, el_val_t key, el_val_t value);
+el_val_t  json_array_len(el_val_t json_str);
+el_val_t  json_array_get(el_val_t json_str, el_val_t index);
+el_val_t  json_array_get_string(el_val_t json_str, el_val_t index);
+
+/* ── Time ────────────────────────────────────────────────────────────────── */
+
+el_val_t  time_now(void);
+el_val_t  time_now_utc(void);
+el_val_t  sleep_secs(el_val_t secs);
+el_val_t  sleep_ms(el_val_t ms);
+el_val_t  time_format(el_val_t ts, el_val_t fmt);
+el_val_t  time_to_parts(el_val_t ts);
+el_val_t  time_from_parts(el_val_t secs, el_val_t ns, el_val_t tz);
+el_val_t  time_add(el_val_t ts, el_val_t n, el_val_t unit);
+el_val_t  time_diff(el_val_t ts1, el_val_t ts2, el_val_t unit);
+
+/* ── Instant + Duration: first-class temporal types ──────────────────────────
+ * Both types share the el_val_t (int64) slot. Instants are nanoseconds
+ * since the Unix epoch; Durations are signed nanoseconds. Type discipline
+ * is enforced at codegen-time: BinOps on names registered as Instant or
+ * Duration route through the typed wrappers below; mismatches like
+ * Instant+Instant become #error at the C compiler.
+ *
+ * Postfix literals — `30.seconds`, `1.hour`, `500.millis`, `30.nanos` — are
+ * recognised by the parser as DurationLit AST nodes and lowered to literal
+ * int64 nanoseconds at codegen time. The runtime never sees the units. */
+
+el_val_t  el_now_instant(void);
+el_val_t  now(void);
+el_val_t  unix_seconds(el_val_t n);
+el_val_t  unix_millis(el_val_t n);
+el_val_t  instant_from_iso8601(el_val_t s);
+
+el_val_t  el_duration_from_nanos(el_val_t ns);
+el_val_t  duration_seconds(el_val_t n);
+el_val_t  duration_millis(el_val_t n);
+el_val_t  duration_nanos(el_val_t n);
+
+el_val_t  el_instant_add_dur(el_val_t inst, el_val_t dur);
+el_val_t  el_instant_sub_dur(el_val_t inst, el_val_t dur);
+el_val_t  el_instant_diff(el_val_t a, el_val_t b);
+el_val_t  el_duration_add(el_val_t a, el_val_t b);
+el_val_t  el_duration_sub(el_val_t a, el_val_t b);
+el_val_t  el_duration_scale(el_val_t dur, el_val_t scalar);
+el_val_t  el_duration_div(el_val_t dur, el_val_t scalar);
+
+el_val_t  el_instant_lt(el_val_t a, el_val_t b);
+el_val_t  el_instant_le(el_val_t a, el_val_t b);
+el_val_t  el_instant_gt(el_val_t a, el_val_t b);
+el_val_t  el_instant_ge(el_val_t a, el_val_t b);
+el_val_t  el_instant_eq(el_val_t a, el_val_t b);
+el_val_t  el_instant_ne(el_val_t a, el_val_t b);
+el_val_t  el_duration_lt(el_val_t a, el_val_t b);
+el_val_t  el_duration_le(el_val_t a, el_val_t b);
+el_val_t  el_duration_gt(el_val_t a, el_val_t b);
+el_val_t  el_duration_ge(el_val_t a, el_val_t b);
+el_val_t  el_duration_eq(el_val_t a, el_val_t b);
+el_val_t  el_duration_ne(el_val_t a, el_val_t b);
+
+el_val_t  instant_to_unix_seconds(el_val_t i);
+el_val_t  instant_to_unix_millis(el_val_t i);
+el_val_t  instant_to_iso8601(el_val_t i);
+el_val_t  duration_to_seconds(el_val_t d);
+el_val_t  duration_to_millis(el_val_t d);
+el_val_t  duration_to_nanos(el_val_t d);
+
+el_val_t  el_sleep_duration(el_val_t dur);
+el_val_t  unix_timestamp(void);
+
+el_val_t  ttl_cache_set(el_val_t key, el_val_t value);
+el_val_t  ttl_cache_get(el_val_t key, el_val_t max_age);
+el_val_t  ttl_cache_age(el_val_t key);
+
+/* ── Calendar + CalendarTime + Rhythm + LocalDate/Time/DateTime ─────────────
+ * Phase 1.5 of the time system. Calendar is pluggable: EarthCalendar (IANA
+ * zones, Gregorian, DST) is the user-facing default; MarsCalendar,
+ * CycleCalendar(period), NoCycleCalendar, RelativeCalendar handle non-Earth
+ * domains.
+ *
+ * A Calendar interprets an Instant under a particular cycle convention and
+ * produces a CalendarTime. CalendarTime carries the underlying Instant and
+ * a back-pointer to its Calendar; arithmetic and formatting consult the
+ * Calendar to convert ns since epoch into year/month/day/hour/minute/second
+ * (or sol/phase, or cycle/phase, depending on kind).
+ *
+ * Storage convention: Calendar / CalendarTime / Rhythm / LocalDate /
+ * LocalDateTime are heap-allocated structs whose pointers are cast into
+ * el_val_t. A 24-bit magic header at offset 0 lets the runtime identify
+ * the kind safely. LocalTime is small enough to live in the int64 slot
+ * directly (nanos since midnight, signed).                                  */
+
+/* Zone — opaque IANA zone or fixed offset, used by EarthCalendar.
+ * `zone_id` is either an IANA name ("America/New_York", "UTC") or a fixed
+ * offset string ("+05:30", "-08:00"). The runtime resolves it via tzset()
+ * on first use of the owning EarthCalendar.                                  */
+el_val_t  zone(el_val_t id);
+el_val_t  zone_utc(void);
+el_val_t  zone_local(void);
+el_val_t  zone_offset(el_val_t hours, el_val_t minutes);
+
+/* Calendar constructors. Each returns an el_val_t pointer to a heap-
+ * allocated, magic-tagged Calendar struct. Calendars are interned by
+ * (kind, zone_id, period_ns, epoch_ns) so identical constructors return
+ * the same pointer — equality is reference equality.                        */
+el_val_t  earth_calendar(el_val_t z);
+el_val_t  earth_calendar_default(void);
+el_val_t  mars_calendar(void);
+el_val_t  cycle_calendar(el_val_t period_dur);
+el_val_t  no_cycle_calendar(void);
+el_val_t  relative_calendar(el_val_t epoch_inst);
+
+/* CalendarTime constructors and methods. Returns a heap-allocated struct
+ * whose pointer fits in el_val_t. */
+el_val_t  now_in(el_val_t cal);
+el_val_t  in_calendar(el_val_t inst, el_val_t cal);
+el_val_t  cal_format(el_val_t ct, el_val_t pattern);
+el_val_t  cal_to_instant(el_val_t ct);
+el_val_t  cal_cycle_phase(el_val_t ct);
+el_val_t  cal_in(el_val_t ct, el_val_t cal);
+
+/* LocalDate / LocalTime / LocalDateTime — calendar-agnostic value types.
+ * LocalTime carries nanoseconds since midnight as a signed int64 directly
+ * in the el_val_t slot (no allocation). LocalDate / LocalDateTime are
+ * heap-allocated structs with magic headers. */
+el_val_t  local_date(el_val_t y, el_val_t m, el_val_t d);
+el_val_t  local_time(el_val_t h, el_val_t m, el_val_t s, el_val_t ns);
+el_val_t  local_datetime(el_val_t date, el_val_t time);
+el_val_t  zoned(el_val_t date, el_val_t time, el_val_t cal);
+
+el_val_t  local_date_year(el_val_t ld);
+el_val_t  local_date_month(el_val_t ld);
+el_val_t  local_date_day(el_val_t ld);
+el_val_t  local_time_hour(el_val_t lt);
+el_val_t  local_time_minute(el_val_t lt);
+el_val_t  local_time_second(el_val_t lt);
+el_val_t  local_time_nanos(el_val_t lt);
+
+el_val_t  el_local_date_add_dur(el_val_t ld, el_val_t dur);
+el_val_t  el_local_time_add_dur(el_val_t lt, el_val_t dur);
+el_val_t  el_local_date_lt(el_val_t a, el_val_t b);
+el_val_t  el_local_date_eq(el_val_t a, el_val_t b);
+
+/* Rhythm — pluggable recurrence AST. Returns a heap-allocated struct
+ * pointer in el_val_t; rhythms are immutable so callers may share them. */
+el_val_t  rhythm_cycle_start(void);
+el_val_t  rhythm_cycle_phase(el_val_t phase);
+el_val_t  rhythm_duration(el_val_t d);
+el_val_t  rhythm_session_start(void);
+el_val_t  rhythm_event(el_val_t name);
+el_val_t  rhythm_and(el_val_t a, el_val_t b);
+el_val_t  rhythm_or(el_val_t a, el_val_t b);
+el_val_t  rhythm_weekday(el_val_t day);
+el_val_t  rhythm_weekly_at(el_val_t day, el_val_t hour, el_val_t minute);
+el_val_t  rhythm_next_after(el_val_t r, el_val_t after, el_val_t cal);
+el_val_t  rhythm_matches(el_val_t r, el_val_t ct);
+
+/* ── UUID ────────────────────────────────────────────────────────────────── */
+
+el_val_t  uuid_new(void);
+el_val_t  uuid_v4(void);
+
+/* ── Environment ─────────────────────────────────────────────────────────── */
+
+el_val_t  env(el_val_t key);
+
+/* ── In-process state K/V ────────────────────────────────────────────────── */
+
+el_val_t  state_set(el_val_t key, el_val_t value);
+el_val_t  state_get(el_val_t key);
+el_val_t  state_del(el_val_t key);
+el_val_t  state_keys(void);
+
+/* ── Float formatting ────────────────────────────────────────────────────── */
+
+el_val_t  float_to_str(el_val_t f);
+el_val_t  int_to_float(el_val_t n);
+el_val_t  float_to_int(el_val_t f);
+el_val_t  format_float(el_val_t f, el_val_t decimals);
+el_val_t  decimal_round(el_val_t f, el_val_t decimals);
+el_val_t  str_to_float(el_val_t s);
+
+/* ── Math (Float-aware) ──────────────────────────────────────────────────── */
+
+el_val_t  math_sqrt(el_val_t f);
+el_val_t  math_log(el_val_t f);
+el_val_t  math_ln(el_val_t f);
+el_val_t  math_sin(el_val_t f);
+el_val_t  math_cos(el_val_t f);
+el_val_t  math_pi(void);
+
+/* ── String additions ────────────────────────────────────────────────────── */
+
+el_val_t  str_index_of(el_val_t s, el_val_t sub);
+el_val_t  str_split(el_val_t s, el_val_t sep);
+el_val_t  str_char_at(el_val_t s, el_val_t i);
+el_val_t  str_char_code(el_val_t s, el_val_t i);
+el_val_t  str_pad_left(el_val_t s, el_val_t width, el_val_t pad);
+el_val_t  str_pad_right(el_val_t s, el_val_t width, el_val_t pad);
+el_val_t  str_format(el_val_t fmt, el_val_t data);
+el_val_t  str_lower(el_val_t s);
+el_val_t  str_upper(el_val_t s);
+
+/* ── Text-processing primitives (Phase 1: byte/codepoint, ASCII char classes)
+ * Phase 2 (filed): Unicode-grapheme awareness, NFC/NFD normalization, regex.
+ * is_* predicates: empty input returns false; multi-char requires ALL bytes
+ * to match. ASCII ranges only in Phase 1. */
+
+/* Counting */
+el_val_t  str_count(el_val_t s, el_val_t sub);              /* non-overlapping */
+el_val_t  str_count_chars(el_val_t s);                      /* codepoint count */
+el_val_t  str_count_bytes(el_val_t s);                      /* alias of str_len */
+el_val_t  str_count_lines(el_val_t s);
+el_val_t  str_count_words(el_val_t s);
+el_val_t  str_count_letters(el_val_t s);                    /* ASCII [A-Za-z] */
+el_val_t  str_count_digits(el_val_t s);                     /* ASCII [0-9] */
+
+/* Find / position */
+el_val_t  str_index_of_all(el_val_t s, el_val_t sub);       /* [Int] of byte offsets */
+el_val_t  str_last_index_of(el_val_t s, el_val_t sub);
+el_val_t  str_find_chars(el_val_t s, el_val_t any_of);      /* first idx of any ch */
+
+/* Transform */
+el_val_t  str_repeat(el_val_t s, el_val_t n);
+el_val_t  str_reverse(el_val_t s);                          /* by codepoint */
+el_val_t  str_strip_prefix(el_val_t s, el_val_t prefix);
+el_val_t  str_strip_suffix(el_val_t s, el_val_t suffix);
+el_val_t  str_strip_chars(el_val_t s, el_val_t chars);
+el_val_t  str_lstrip(el_val_t s);
+el_val_t  str_rstrip(el_val_t s);
+
+/* Char classification (Bool) */
+el_val_t  is_letter(el_val_t s);
+el_val_t  is_digit(el_val_t s);
+el_val_t  is_alphanumeric(el_val_t s);
+el_val_t  is_whitespace(el_val_t s);
+el_val_t  is_punctuation(el_val_t s);
+el_val_t  is_uppercase(el_val_t s);
+el_val_t  is_lowercase(el_val_t s);
+
+/* Split / join */
+el_val_t  str_split_lines(el_val_t s);
+el_val_t  str_split_chars(el_val_t s);                      /* alias of native_string_chars */
+el_val_t  str_split_n(el_val_t s, el_val_t sep, el_val_t n);
+el_val_t  str_join(el_val_t list, el_val_t sep);            /* alias of list_join */
+
+/* ── List additions ──────────────────────────────────────────────────────── */
+
+el_val_t  list_push(el_val_t list, el_val_t elem);
+el_val_t  list_push_front(el_val_t list, el_val_t elem);
+el_val_t  list_join(el_val_t list, el_val_t sep);
+el_val_t  list_range(el_val_t start, el_val_t end);
+
+/* ── Bool helpers ────────────────────────────────────────────────────────── */
+
+el_val_t  bool_to_str(el_val_t b);
+
+/* ── Numeric parsing ─────────────────────────────────────────────────────── */
+
+el_val_t  parse_int(el_val_t s, el_val_t default_val);
+
+/* ── Process ─────────────────────────────────────────────────────────────── */
+
+void      exit_program(el_val_t code);
+el_val_t  getpid_now(void);
+
+/* ── CGI identity ─────────────────────────────────────────────────────────────
+ * Called at the start of main() in CGI programs (those with a `cgi {}` block).
+ * Records the program's DHARMA identity before any other code executes.      */
+
+void      el_cgi_init(el_val_t name, el_val_t dharma_id, el_val_t principal,
+                      el_val_t network, el_val_t engram);
+
+/* ── DHARMA network builtins ─────────────────────────────────────────────────
+ * Available to CGI programs (declared with a `cgi {}` block).
+ *
+ * Peers are addressed by `dharma_id` of the form
+ *     "<registry-id>@<transport-url>"   e.g. "ntn-genesis@http://localhost:7770"
+ * If the @<url> portion is omitted, transport defaults to
+ * "http://localhost:7770" (the local CGI daemon assumption).
+ *
+ * Wire protocol (all peers expose):
+ *   POST <url>/dharma/recv      { channel, from, content } → response body
+ *   POST <url>/dharma/event     { type, payload, source, timestamp }
+ *   POST <url>/api/activate     { query }                 → list of nodes
+ *
+ * Hosting application's responsibility: an El program with a `cgi {}` block
+ * runs http_serve() with its own request handler; that handler should route
+ * "/dharma/event" requests by calling el_runtime_dharma_event_arrive() so
+ * incoming events feed dharma_field() queues. The runtime itself does not
+ * intercept any /dharma path.                                                */
+
+el_val_t  dharma_connect(el_val_t cgi_id);
+el_val_t  dharma_send(el_val_t channel, el_val_t content);
+el_val_t  dharma_activate(el_val_t query);
+void      dharma_emit(el_val_t event_type, el_val_t payload);
+el_val_t  dharma_field(el_val_t event_type);
+void      dharma_strengthen(el_val_t cgi_id, el_val_t weight);
+el_val_t  dharma_relationship(el_val_t cgi_id);
+el_val_t  dharma_peers(void);
+
+/* Public C API: called by an El program's HTTP handler when a /dharma/event
+ * request arrives. Pushes onto the per-event-type queue and signals any
+ * pending dharma_field() blockers. All three arguments must be NUL-terminated
+ * C strings (or NULL — then treated as empty).                               */
+void      el_runtime_dharma_event_arrive(const char* event_type,
+                                         const char* payload,
+                                         const char* source);
+
+/* ── Engram local graph primitives ───────────────────────────────────────────
+ * Operate on the CGI's local Engram knowledge graph.
+ * `engram_activate` queries the local graph only; `dharma_activate` is
+ * network-wide across all connected CGI graphs.                              */
+
+el_val_t  engram_node(el_val_t content, el_val_t node_type, el_val_t salience);
+el_val_t  engram_node_full(el_val_t content, el_val_t node_type, el_val_t label,
+                           el_val_t salience, el_val_t importance, el_val_t confidence,
+                           el_val_t tier, el_val_t tags);
+/* Layered consciousness — see el_runtime.c for the layered architecture
+ * design notes (search "Layered consciousness architecture"). The five
+ * canonical layers (safety / core-identity / domain-knowledge / imprint /
+ * suit) are seeded automatically; engram_add_layer extends the registry
+ * with imprint or suit overlays at runtime. Nodes default to layer 1
+ * (core-identity) when created via engram_node / engram_node_full. */
+el_val_t  engram_node_layered(el_val_t content, el_val_t node_type, el_val_t label,
+                              el_val_t salience, el_val_t certainty, el_val_t confidence,
+                              el_val_t status, el_val_t tags, el_val_t layer_id);
+el_val_t  engram_add_layer(el_val_t name, el_val_t priority, el_val_t suppressible,
+                           el_val_t transparent, el_val_t injectable);
+el_val_t  engram_remove_layer(el_val_t layer_id);
+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);
+void      engram_connect(el_val_t from_id, el_val_t to_id, el_val_t weight, el_val_t relation);
+el_val_t  engram_edge_between(el_val_t from_id, el_val_t to_id);
+el_val_t  engram_neighbors(el_val_t node_id);
+el_val_t  engram_neighbors_filtered(el_val_t node_id, el_val_t max_depth, el_val_t direction);
+el_val_t  engram_edge_count(void);
+/* Three-pass activation: background fan-out → working-memory promotion →
+ * Layer 0 override. See "Three-pass activation" in el_runtime.c. */
+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);
+/* Tiered paged-store entry points (ENGRAM_STORE=1). engram_store_boot opens the
+ * durable store (import-once / WAL-replay) and loads it resident; checkpoint pushes
+ * the resident graph's current field state (incl. learned hebb + activation-formed
+ * edges) through the WAL and flushes; close checkpoints + closes. No-ops when off. */
+el_val_t  engram_store_boot(el_val_t data_dir);
+el_val_t  engram_store_checkpoint(void);
+el_val_t  engram_store_close(void);
+
+/* JSON-string accessors — return pre-serialized JSON so HTTP handlers
+ * 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_retrieve_geometric_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_scan_nodes_emb_json(el_val_t limit, el_val_t offset);
+el_val_t  engram_dreams_json(el_val_t since_ms);
+/* §5 geometry operators as EL builtins (read-only; seed-id CSV args). */
+el_val_t  engram_geo_descriptor_json(el_val_t seeds);
+el_val_t  engram_geo_overlap_json(el_val_t a_seeds, el_val_t b_seeds);
+el_val_t  engram_geo_subtract_json(el_val_t a_seeds, el_val_t b_seeds, el_val_t mode);
+el_val_t  engram_geo_combine_json(el_val_t a_seeds, el_val_t b_seeds);
+el_val_t  engram_geo_distance_json(el_val_t a_seeds, el_val_t b_seeds);
+el_val_t  engram_geo_analogy_json(el_val_t a_seeds, el_val_t b_seeds);
+/* reasoning layer (compositions over §5 operators). ANALOGY maps cleanly to the
+ * flat-CSV seed ABI; the other modes take set/point/timestamp inputs deferred from
+ * this ABI (see engram_reason.h / the reasoning-operators runbook). */
+el_val_t  engram_reason_analogy_json(el_val_t a_seeds, el_val_t b_seeds, el_val_t c_seeds);
+/* COGNITION (2026-08-14): THE ONE OPERATION + grounding, surfaced live. */
+el_val_t  engram_think_json(el_val_t seeds, el_val_t faculty);
+el_val_t  engram_ground_json(el_val_t claim, el_val_t evidence, el_val_t for_whom);
+el_val_t  engram_assert_json(el_val_t claim_id, el_val_t for_whom, el_val_t floor);
+el_val_t  engram_attend_json(el_val_t node_id, el_val_t observer, el_val_t salience);
+el_val_t  engram_correspondence_beat_json(el_val_t seeds, el_val_t faculty, el_val_t keystone);
+el_val_t  engram_consolidate_permanence(el_val_t node_id);
+el_val_t  engram_age_field(el_val_t delta_ms);
+el_val_t  engram_age_field_catchup(void);
+el_val_t  engram_chrono_persist_tick(void);
+el_val_t  engram_chrono_tick(void);
+el_val_t  engram_boundary_beat(el_val_t op_name);  /* API-reshape decorator-seam auto-emit */
+el_val_t  engram_self_anchor_capture(void);
+el_val_t  engram_self_drift_json(void);
+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);
+/* M10 reified-neighborhood read-only HTTP surface (2026-08-13). List/detail of
+ * the resident reify index; [] until the offline reify writer has run. */
+el_val_t  engram_geo_reify_list_json(void);
+el_val_t  engram_geo_reify_get_json(el_val_t id);
+/* WRITE: run reification — persist Neighborhood nodes + member edges, rebuild the
+ * resident index. Wires the previously-dormant engram_geo_reify_store. */
+el_val_t  engram_geo_reify_run_json(void);
+/* SELF-REIFICATION (2026-08-14). ON-BEAT autonomous neighborhood formation:
+ * gated by ENGRAM_SELF_REIFY (default off → returns {"enabled":false}, writes
+ * nothing — the live binary is byte-inert until the flag is set). When on, runs
+ * ONE bounded, incremental, idempotent reification pass (change-detection skips
+ * unchanged hubs → no re-append; grounded names; residue-preserving supersession;
+ * soft/overlapping membership; nests only when something changed). Meant to be
+ * pumped every heartbeat next to Hebbian consolidation. Returns
+ * {"enabled":true,"reified":N,"skipped":S,"superseded":P,"nested":X,"resident":M,"wrote":b}. */
+el_val_t  engram_self_reify_beat_json(void);
+/* ASYNC EXPLICIT OVERRIDE (degenerate manual case). Rename a live neighborhood
+ * by id: writes a superseding record with the new name, prepends a residue entry
+ * (cause="explicit-override", prior name), keeps the same geometry/members. Never
+ * blocks the beat. Returns {"ok":true,"renamed":<old>,"new_id":<new>,"name":..}. */
+el_val_t  engram_neighborhood_rename_json(el_val_t id, el_val_t name);
+/* Orphan prevention: form up to k semantic-similar edges to a node's nearest
+ * embedded neighbors (kNN). engram_nearest_json is the read-only probe. */
+el_val_t  engram_autoconnect_node(el_val_t id, el_val_t k, el_val_t min_sim_pct);
+el_val_t  engram_nearest_json(el_val_t id, el_val_t k);
+/* Telemetry off-graph: append one ISE JSON line to the state-event log tier. */
+el_val_t  engram_ise_log_append(el_val_t content);
+/* 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 runtime on 2026-06-30 self-review. */
+el_val_t  engram_wm_count(void);
+el_val_t  engram_wm_avg_weight(void);
+el_val_t  engram_wm_top_json(el_val_t n);
+/* Merge-load: add nodes/edges from a snapshot without resetting the store. */
+el_val_t  engram_load_merge(el_val_t path);
+
+/* ── WAL + compaction + integrity (ENGRAM_WAL=on; design doc §§3-14,§18) ──── */
+int       engram_wal_enabled(void);
+el_val_t  engram_crc32(el_val_t s);
+el_val_t  engram_wal_boot(el_val_t dir);          /* replay + open; returns records */
+el_val_t  engram_wal_open_dir(el_val_t dir);
+el_val_t  engram_wal_node_put(el_val_t dir, el_val_t id);
+el_val_t  engram_wal_edges_since(el_val_t dir, el_val_t start_count);
+el_val_t  engram_wal_hebb_batch(el_val_t dir, el_val_t start_count);
+el_val_t  engram_wal_forget(el_val_t dir, el_val_t id);
+el_val_t  engram_wal_compact(el_val_t dir);
+el_val_t  engram_wal_maybe_compact(el_val_t dir);
+el_val_t  engram_resolve_data_dir(void);          /* §18.2 fail-loud default */
+el_val_t  engram_is_protected(el_val_t id);       /* §18.1/18.3 derived set */
+el_val_t  engram_protected_json(void);
+/* engram_compile_layered_json — produce a prompt-ready text block split
+ * into "[LAYER 0 — STRUCTURAL]" (non-suppressible layers, sacred fire)
+ * and "[ENGRAM CONTEXT]" (standard suppressible layers). Returns "" if
+ * no nodes promoted to working memory. */
+el_val_t  engram_compile_layered_json(el_val_t intent, el_val_t depth);
+
+/* ── LLM (Anthropic API client) ─────────────────────────────────────────────
+ * All functions call https://api.anthropic.com/v1/messages with the API key
+ * from env ANTHROPIC_API_KEY. Default model when empty: claude-sonnet-4-5. */
+
+el_val_t  llm_call(el_val_t model, el_val_t prompt);
+el_val_t  llm_call_system(el_val_t model, el_val_t system_prompt, el_val_t user_prompt);
+el_val_t  llm_call_agentic(el_val_t model, el_val_t system, el_val_t user, el_val_t tools);
+/* LLM token telemetry (CCR §4.4): usage.{input,output}_tokens parsed from every
+ * response. Returns Map{input_tokens,output_tokens,total_input_tokens,
+ * total_output_tokens,calls}. */
+el_val_t  llm_last_usage(void);
+/* Fold usage.{input,output}_tokens from a raw messages response into the counters.
+ * Called internally on every LLM response; exported for offline testing. */
+void      llm_record_usage(const char* resp);
+el_val_t  llm_vision(el_val_t model, el_val_t system, el_val_t prompt, el_val_t image_url_or_b64);
+el_val_t  llm_models(void);
+
+/* Register a tool handler by name. The handler is looked up via dlsym
+ * (mirroring http_set_handler), so any El `fn <name>(input)` compiles to
+ * a global C symbol that this function can locate at runtime.
+ * Handler signature: `el_val_t handler(el_val_t input_json)` — receives
+ * the tool input as a JSON-string el_val_t and returns a JSON-string
+ * el_val_t result. Used by llm_call_agentic.                                 */
+void      llm_register_tool(el_val_t name, el_val_t handler_fn_name);
+
+/* ── args() ─────────────────────────────────────────────────────────────────
+ * Provides access to command-line arguments passed to the program.
+ * Populated by el_runtime_init_args() before main() runs.           */
+
+el_val_t  args(void);
+void      el_runtime_init_args(int argc, char** argv);
+
+/* ── Crypto primitives ─────────────────────────────────────────────────────
+ * SHA-256, HMAC-SHA-256, and base64 (standard + URL-safe).
+ * Self-contained — no OpenSSL/libcrypto dependency. The implementations are
+ * adapted from public-domain reference code (Brad Conte / RFC 4648).
+ *
+ * Bytes-returning variants (sha256_bytes, hmac_sha256_bytes) return a string
+ * value whose contents are raw binary; callers usually feed these into
+ * base64_encode. Note that el_val_t strings are NUL-terminated by convention,
+ * so the binary payload may contain embedded NULs — pass it directly into
+ * base64_encode (which uses an explicit length) rather than treating it as
+ * a printable C string.
+ *
+ * The "base64" variants emit/accept RFC 4648 standard alphabet with padding.
+ * The "base64url" variants use URL-safe alphabet (`-`/`_`) with no padding,
+ * as used in JWTs.                                                           */
+
+el_val_t  sha256_hex(el_val_t input);
+el_val_t  sha256_bytes(el_val_t input);
+el_val_t  hmac_sha256_hex(el_val_t key, el_val_t message);
+el_val_t  hmac_sha256_bytes(el_val_t key, el_val_t message);
+el_val_t  base64_encode(el_val_t input);
+el_val_t  base64_decode(el_val_t input);
+el_val_t  base64url_encode(el_val_t input);
+el_val_t  base64url_decode(el_val_t input);
+
+/* Length-aware variants (internal — exposed for the rare caller that already
+ * has a known-length binary buffer and doesn't want to round-trip through
+ * a NUL-terminated el_val_t string). Sha256_bytes and hmac_sha256_bytes feed
+ * these implicitly. */
+el_val_t  el_sha256_bytes_n(const unsigned char* data, size_t len);
+el_val_t  el_base64_encode_n(const unsigned char* data, size_t len, int url_safe);
+
+/* ── Post-quantum primitives (liboqs-backed) ────────────────────────────────
+ * All inputs/outputs hex-encoded. Algorithm choices:
+ *   Signature: CRYSTALS-Dilithium-3   (NIST level 3, balanced)
+ *   KEM:       CRYSTALS-Kyber-768     (NIST level 3)
+ *   Hash:      SHA3-256 (Keccak)      (PQ-aware protocols favour SHA3 over SHA2)
+ *
+ * If liboqs is not linked (detected via __has_include(<oqs/oqs.h>) at compile
+ * time), the pq_* entry points return a JSON-shaped error string so callers
+ * fail loudly rather than silently fall back to classical schemes:
+ *   {"error":"liboqs not linked, post-quantum primitives unavailable"}
+ *
+ * The hybrid handshake pairs X25519 with Kyber-768 per NIST PQ guidance and
+ * CNSA 2.0. Combined shared secret is HKDF-SHA256(x25519_ss || kyber_ss).
+ * Even if Kyber falls, X25519 holds; if X25519 falls under quantum attack,
+ * Kyber holds. SHA3-256 also remains usable independent of liboqs (the
+ * Keccak permutation is PQ-OK as a primitive). */
+
+el_val_t  pq_keygen_signature(void);
+el_val_t  pq_sign(el_val_t secret_key_hex, el_val_t message);
+el_val_t  pq_verify(el_val_t public_key_hex, el_val_t message, el_val_t signature_hex);
+
+el_val_t  pq_kem_keygen(void);
+el_val_t  pq_kem_encaps(el_val_t public_key_hex);
+el_val_t  pq_kem_decaps(el_val_t secret_key_hex, el_val_t ciphertext_hex);
+
+el_val_t  pq_hybrid_keygen(void);
+el_val_t  pq_hybrid_handshake(el_val_t remote_pub_combined);
+
+el_val_t  sha3_256_hex(el_val_t input);
+
+/* ── AEAD: AES-256-GCM (libcrypto-backed) ───────────────────────────────────
+ * Symmetric authenticated encryption used to wrap envelopes after a KEM
+ * handshake. Caller MUST supply a 32-byte key (64 hex chars) — typically the
+ * Kyber-768 / hybrid shared_secret, optionally normalized via SHA3-256.
+ *
+ * aead_encrypt returns a JSON map {"nonce":"...","ciphertext":"..."} where
+ * ciphertext is the AES-256-GCM output with the 16-byte auth tag appended.
+ * Nonce is a fresh 12-byte CSPRNG draw — callers never pick the nonce, which
+ * structurally rules out the GCM nonce-reuse footgun.
+ *
+ * aead_decrypt returns the plaintext String, or "" on any failure (including
+ * auth-tag mismatch). Callers MUST check for "" before trusting the result. */
+el_val_t  aead_encrypt(el_val_t key_hex, el_val_t plaintext);
+el_val_t  aead_decrypt(el_val_t key_hex, el_val_t nonce_hex, el_val_t ciphertext_hex);
+
+/* ── Native VM builtin aliases (for compiled El source) ─────────────────────
+ * These match the El VM's native_* builtins so that El source compiled
+ * to C can call the same names without modification.                */
+
+el_val_t  native_list_get(el_val_t list, el_val_t index);
+el_val_t  native_list_len(el_val_t list);
+el_val_t  native_list_append(el_val_t list, el_val_t elem);
+el_val_t  native_list_empty(void);
+el_val_t  native_list_clone(el_val_t list);
+el_val_t  native_string_chars(el_val_t s);
+el_val_t  native_int_to_str(el_val_t n);
+
+/* ── Method-call shorthand aliases ──────────────────────────────────────────
+ * The El method-call convention `obj.method(args)` compiles to
+ * `method(obj, args)`.  These aliases expose the runtime functions under
+ * the short names that result from method calls in El source.
+ *
+ * Example: `myList.append(x)` → `append(myList, x)` (calls this alias)
+ *          `myList.len()`     → `len(myList)`         (calls this alias)  */
+
+el_val_t  append(el_val_t list, el_val_t elem);   /* el_list_append */
+el_val_t  len(el_val_t list);                      /* el_list_len    */
+el_val_t  get(el_val_t list, el_val_t index);      /* el_list_get    */
+el_val_t  map_get(el_val_t map, el_val_t key);     /* el_map_get     */
+el_val_t  map_set(el_val_t map, el_val_t key, el_val_t value); /* el_map_set */
+
+/* ── OTLP/HTTP Observability ─────────────────────────────────────────────── */
+/* See bottom of el_runtime.c for the implementation.
+ * Configured by env vars OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION.
+ * No-op when OTLP_ENDPOINT is unset. Drop-on-failure semantics. */
+/* ── Subprocess execution ────────────────────────────────────────────────── */
+el_val_t exec_command(el_val_t cmd);   /* run shell command, return exit code */
+el_val_t exec_capture(el_val_t cmd);   /* run shell command, capture stdout   */
+el_val_t exec(el_val_t cmd);           /* exec(cmd) → stdout String (30s timeout) */
+el_val_t exec_bg(el_val_t cmd);        /* exec_bg(cmd) → PID String (non-blocking) */
+
+el_val_t emit_log(el_val_t level, el_val_t msg, el_val_t fields_json);
+el_val_t emit_metric(el_val_t name, el_val_t value, el_val_t tags_json);
+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);
+
+#ifdef __cplusplus
+}
+#endif

lang/runtime/engram_cognition.c

@@ -0,0 +1,339 @@
+/* engram_cognition.c — THE ONE OPERATION. See engram_cognition.h.
+ * Pure over its inputs (think/warp/express); persistence is additive/supersede
+ * only. stdlib + libm + engram_store/reason/geometry. Touches no live daemon. */
+#include "engram_cognition.h"
+#include <stdlib.h>
+#include <string.h>
+#include <stdio.h>
+#include <math.h>
+
+/* ── small helpers ──────────────────────────────────────────────────────────── */
+static double vdot(const float* a, const float* b, int dim) {
+    double s = 0; for (int i = 0; i < dim; i++) s += (double)a[i] * (double)b[i]; return s;
+}
+static double vnorm(const float* a, int dim) { return sqrt(vdot(a, a, dim)); }
+static char* dupstr(const char* s) {
+    if (!s) return NULL; size_t n = strlen(s) + 1; char* p = malloc(n);
+    if (p) memcpy(p, s, n); return p;
+}
+static double clampd(double x, double lo, double hi){ return x<lo?lo:(x>hi?hi:x); }
+
+/* ═══════════════════════════════════════════════ Stance lifecycle ════════════ */
+int cog_stance_init(CogStance* s, const char* id, const char* faculty,
+                    const char* anchor_region, const char* for_whom,
+                    const GeoDescriptor* region) {
+    if (!s || !region) return -1;
+    memset(s, 0, sizeof *s);
+    s->id = dupstr(id); s->faculty = dupstr(faculty);
+    s->anchor_region = dupstr(anchor_region); s->for_whom = dupstr(for_whom);
+    s->dim = region->dim;
+    s->n_axes = region->n_axes > COG_MAX_AXES ? COG_MAX_AXES : region->n_axes;
+    for (int k = 0; k < COG_MAX_AXES; k++) s->axis_gain[k] = 1.0;
+    s->ext_floor = 1.0; s->drop_frac = 0.5; s->assoc_floor = 0.2;
+    s->bias_dir = NULL;
+    s->reliability = 0.5;   /* uninformed prior on our own track record */
+    return 0;
+}
+void cog_stance_set_frozen_defaults(CogStance* s) {
+    if (!s) return;
+    for (int k = 0; k < COG_MAX_AXES; k++) s->axis_gain[k] = 1.0;
+    s->ext_floor = 1.0; s->drop_frac = 0.5; s->assoc_floor = 0.2;
+    free(s->bias_dir); s->bias_dir = NULL;
+}
+void cog_stance_free(CogStance* s) {
+    if (!s) return;
+    free(s->id); free(s->faculty); free(s->anchor_region); free(s->for_whom);
+    free(s->bias_dir);
+    s->id = s->faculty = s->anchor_region = s->for_whom = NULL; s->bias_dir = NULL;
+}
+int cog_is_keystone(const CogKeystoneSet* ks, const CogStance* s) {
+    if (!s) return 0;
+    if (s->keystone) return 1;
+    if (!ks || !s->id) return 0;
+    for (int i = 0; i < ks->n; i++)
+        if (ks->ids[i] && (strcmp(ks->ids[i], s->id) == 0 ||
+            (s->anchor_region && strcmp(ks->ids[i], s->anchor_region) == 0))) return 1;
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════ warped fit (think step 2) ══ */
+int cog_warped_fit(const GeoDescriptor* g, const float* x,
+                   const CogStance* st, GeoFit* out) {
+    if (!g || !x || !out || g->dim <= 0 || !g->centroid) return -1;
+    double ext_floor = (st && st->ext_floor > 0) ? st->ext_floor : 1.0;
+    int dim = g->dim;
+    double rr = 0;
+    float* r = malloc((size_t)dim * sizeof(float));
+    if (!r) return -1;
+    for (int i = 0; i < dim; i++) { double d = (double)x[i] - (double)g->centroid[i]; r[i] = (float)d; rr += d * d; }
+    double maha2 = 0, ss_in = 0;
+    for (int k = 0; k < g->n_axes; k++) {
+        const float* ax = g->axes[k].axis; if (!ax) continue;
+        double proj = vdot(r, ax, dim);
+        double gain = (st && k < st->n_axes && st->axis_gain[k] > 0) ? st->axis_gain[k] : 1.0;
+        double den = g->axes[k].extent * gain; if (den < ext_floor) den = ext_floor;
+        maha2 += (proj / den) * (proj / den);
+        ss_in += proj * proj;
+    }
+    double ortho2 = rr - ss_in; if (ortho2 < 0) ortho2 = 0;
+    double dist2 = maha2 + ortho2 / (ext_floor * ext_floor);
+    out->mahalanobis = sqrt(maha2); out->ortho_residual = sqrt(ortho2);
+    out->distance = sqrt(dist2);    out->score = 1.0 / (1.0 + dist2);
+    free(r);
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════ think (the ONE operation) ══ */
+void engram_gradient_free(GeoGradient* g) {
+    if (!g) return; free(g->direction); g->direction = NULL;
+}
+int engram_think(const GeoDescriptor* region, const float* anchor,
+                 const CogStance* stance, GeoGradient* out) {
+    if (!region || !out || region->dim <= 0 || !region->centroid) return -1;
+    int dim = region->dim;
+    memset(out, 0, sizeof *out);
+    out->dim = dim;
+    const float* x = anchor ? anchor : region->centroid;   /* re-origin (step 1) */
+
+    GeoFit f;
+    if (cog_warped_fit(region, x, stance, &f) != 0) return -1;   /* fit (step 2) */
+
+    /* step 3 — emit a GRADIENT: warped steepest DESCENT of the fit distance². */
+    double ext_floor = (stance && stance->ext_floor > 0) ? stance->ext_floor : 1.0;
+    float* grad = calloc((size_t)dim, sizeof(float));   /* ∇ dist² wrt x         */
+    float* r    = malloc((size_t)dim * sizeof(float));
+    out->direction = malloc((size_t)dim * sizeof(float));
+    if (!grad || !r || !out->direction) { free(grad); free(r); free(out->direction); out->direction = NULL; return -1; }
+    for (int i = 0; i < dim; i++) r[i] = (float)((double)x[i] - (double)region->centroid[i]);
+    /* in-subspace: Σ_k 2 (proj/den²) a_k ; also accumulate Σ proj a_k for ortho part */
+    float* proj_sum = calloc((size_t)dim, sizeof(float));
+    if (!proj_sum) { free(grad); free(r); free(out->direction); out->direction = NULL; return -1; }
+    for (int k = 0; k < region->n_axes; k++) {
+        const float* ax = region->axes[k].axis; if (!ax) continue;
+        double proj = vdot(r, ax, dim);
+        double gain = (stance && k < stance->n_axes && stance->axis_gain[k] > 0) ? stance->axis_gain[k] : 1.0;
+        double den = region->axes[k].extent * gain; if (den < ext_floor) den = ext_floor;
+        double coef = 2.0 * proj / (den * den);
+        for (int i = 0; i < dim; i++) { grad[i] += (float)(coef * ax[i]); proj_sum[i] += (float)(proj * ax[i]); }
+    }
+    /* orthogonal: (2 r − 2 Σ proj a_k) / ext_floor² */
+    double inv_f2 = 1.0 / (ext_floor * ext_floor);
+    for (int i = 0; i < dim; i++)
+        grad[i] += (float)((2.0 * (double)r[i] - 2.0 * (double)proj_sum[i]) * inv_f2);
+    free(proj_sum);
+
+    /* steering = −grad (descent), seeded by the stance's bias_dir. */
+    for (int i = 0; i < dim; i++) out->direction[i] = -grad[i];
+    if (stance && stance->bias_dir) {
+        double gn = vnorm(grad, dim), bn = vnorm(stance->bias_dir, dim);
+        if (bn > 1e-12) {
+            double scale = (gn > 1e-12 ? gn : 1.0);   /* seed at the gradient's scale */
+            for (int i = 0; i < dim; i++)
+                out->direction[i] += (float)(scale * (double)stance->bias_dir[i] / bn);
+        }
+    }
+    double dn = vnorm(out->direction, dim);
+    if (dn > 1e-12) for (int i = 0; i < dim; i++) out->direction[i] /= (float)dn;
+    else            for (int i = 0; i < dim; i++) out->direction[i] = 0.0f;   /* at rest */
+
+    out->spread     = f.distance;                       /* spiked (0) .. diffuse   */
+    out->confidence = stance ? stance->reliability : 0.5;
+    out->magnitude  = f.score;                          /* the read's membership   */
+    out->anchor_id  = region->hub_id;                   /* borrowed vantage id     */
+    out->n_support  = region->n_members;
+    out->stance_id  = stance ? stance->id : NULL;
+    free(grad); free(r);
+    return 0;
+}
+
+/* EXPRESSION — the ONLY collapse to a point (a separate faculty from think). */
+int engram_express(const GeoGradient* g, const float* anchor, float* out_point) {
+    if (!g || !anchor || !out_point || !g->direction) return -1;
+    double commit = clampd(g->confidence, 0.0, 1.0);    /* confident => commit far */
+    for (int i = 0; i < g->dim; i++)
+        out_point[i] = anchor[i] + g->direction[i] * (float)commit;
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════ Stance serialization ════════ */
+/* Compact line schema "STNC1" (mirrors the reify "GEO1" precedent). */
+char* cog_stance_to_metadata(const CogStance* s) {
+    if (!s) return NULL;
+    size_t cap = 256 + (size_t)s->n_axes * 24 + (size_t)(s->bias_dir ? s->dim * 16 : 0);
+    char* buf = malloc(cap); if (!buf) return NULL;
+    size_t o = 0;
+    o += (size_t)snprintf(buf + o, cap - o, "%s\n", COG_STANCE_META_MAGIC);
+    o += (size_t)snprintf(buf + o, cap - o, "f %s\n", s->faculty ? s->faculty : "-");
+    o += (size_t)snprintf(buf + o, cap - o, "r %s\n", s->anchor_region ? s->anchor_region : "-");
+    o += (size_t)snprintf(buf + o, cap - o, "w %s\n", s->for_whom ? s->for_whom : "-");
+    o += (size_t)snprintf(buf + o, cap - o, "k %d\n", s->keystone);
+    o += (size_t)snprintf(buf + o, cap - o, "d %d %d\n", s->dim, s->n_axes);
+    o += (size_t)snprintf(buf + o, cap - o, "s %.9g %.9g %.9g\n", s->ext_floor, s->drop_frac, s->assoc_floor);
+    o += (size_t)snprintf(buf + o, cap - o, "g");
+    for (int k = 0; k < s->n_axes; k++) o += (size_t)snprintf(buf + o, cap - o, " %.9g", s->axis_gain[k]);
+    o += (size_t)snprintf(buf + o, cap - o, "\n");
+    o += (size_t)snprintf(buf + o, cap - o, "c %lld %.9g %.9g %.9g %.9g\n",
+                          (long long)s->n_trials, s->brier_sum, s->reliability, s->ema_error, s->last_error);
+    if (s->bias_dir) {
+        o += (size_t)snprintf(buf + o, cap - o, "b");
+        for (int i = 0; i < s->dim; i++) o += (size_t)snprintf(buf + o, cap - o, " %.9g", (double)s->bias_dir[i]);
+        o += (size_t)snprintf(buf + o, cap - o, "\n");
+    }
+    (void)o;
+    return buf;
+}
+int cog_stance_to_node(const CogStance* s, StoreNode* out) {
+    if (!s || !out) return -1;
+    memset(out, 0, sizeof *out);
+    out->id        = dupstr(s->id);
+    out->node_type = dupstr(COG_STANCE_NODE_TYPE);
+    out->content   = dupstr(s->faculty ? s->faculty : "stance");
+    out->label     = dupstr(s->faculty ? s->faculty : "stance");
+    out->metadata  = cog_stance_to_metadata(s);
+    out->importance = s->reliability;    /* cached denormalized readout (§2.1)     */
+    out->confidence = s->reliability;
+    out->temporal_decay_rate = 0.0;
+    return (out->id && out->node_type && out->metadata) ? 0 : -1;
+}
+static int parse_floats(const char* line, double* out, int max) {
+    int n = 0; const char* p = line;
+    while (*p && n < max) {
+        while (*p == ' ') p++;
+        if (!*p) break;
+        char* end; double v = strtod(p, &end);
+        if (end == p) break;
+        out[n++] = v; p = end;
+    }
+    return n;
+}
+int cog_stance_from_node(const StoreNode* n, CogStance* out) {
+    if (!n || !out || !n->metadata) return -1;
+    memset(out, 0, sizeof *out);
+    for (int k = 0; k < COG_MAX_AXES; k++) out->axis_gain[k] = 1.0;
+    out->ext_floor = 1.0; out->drop_frac = 0.5; out->assoc_floor = 0.2; out->reliability = 0.5;
+    out->id = dupstr(n->id);
+    /* verify magic on first line */
+    const char* m = n->metadata;
+    if (strncmp(m, COG_STANCE_META_MAGIC, strlen(COG_STANCE_META_MAGIC)) != 0) return -1;
+    char* copy = dupstr(m); if (!copy) return -1;
+    for (char* line = strtok(copy, "\n"); line; line = strtok(NULL, "\n")) {
+        if (line[0] == '\0' || line[1] != ' ') {
+            if (line[0] == 'g' || line[0] == 'b') { /* vector lines: tag then values */ }
+            else continue;
+        }
+        char tag = line[0];
+        const char* rest = line + 1; while (*rest == ' ') rest++;
+        if (tag == 'f')      { free(out->faculty); out->faculty = (strcmp(rest, "-") ? dupstr(rest) : NULL); }
+        else if (tag == 'r') { free(out->anchor_region); out->anchor_region = (strcmp(rest, "-") ? dupstr(rest) : NULL); }
+        else if (tag == 'w') { free(out->for_whom); out->for_whom = (strcmp(rest, "-") ? dupstr(rest) : NULL); }
+        else if (tag == 'k') { out->keystone = atoi(rest); }
+        else if (tag == 'd') { int a=0,b=0; sscanf(rest, "%d %d", &a, &b); out->dim = a; out->n_axes = b > COG_MAX_AXES ? COG_MAX_AXES : b; }
+        else if (tag == 's') { double v[3]={1,0.5,0.2}; parse_floats(rest, v, 3); out->ext_floor=v[0]; out->drop_frac=v[1]; out->assoc_floor=v[2]; }
+        else if (tag == 'g') { double v[COG_MAX_AXES]; int c=parse_floats(rest, v, COG_MAX_AXES); for(int k=0;k<c;k++) out->axis_gain[k]=v[k]; }
+        else if (tag == 'c') { double v[5]={0,0,0.5,0,0}; parse_floats(rest, v, 5); out->n_trials=(int64_t)v[0]; out->brier_sum=v[1]; out->reliability=v[2]; out->ema_error=v[3]; out->last_error=v[4]; }
+        else if (tag == 'b') { if (out->dim>0){ out->bias_dir=calloc((size_t)out->dim,sizeof(float)); double v[4096]; int c=parse_floats(rest,v,out->dim<4096?out->dim:4096); for(int i=0;i<c;i++) out->bias_dir[i]=(float)v[i]; } }
+    }
+    free(copy);
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════ grounding as a RELATION ═════ */
+static int put_edge(EngramPagedStore* s, const char* id, const char* from, const char* to,
+                    const char* relation, double weight, const char* meta) {
+    StoreEdge e; memset(&e, 0, sizeof e);
+    e.id = (char*)id; e.from_id = (char*)from; e.to_id = (char*)to;
+    e.relation = (char*)relation; e.weight = weight; e.confidence = weight;
+    e.metadata = (char*)meta;
+    return store_put_edge(s, &e);
+}
+int cog_ground_edge(EngramPagedStore* s, const char* claim_id,
+                    const char* evidence_id, double grounding, const char* for_whom) {
+    if (!s || !claim_id || !evidence_id) return -1;
+    char id[512], meta[256];
+    snprintf(id, sizeof id, "gb-%s-%s-%s", claim_id, evidence_id, for_whom ? for_whom : "global");
+    snprintf(meta, sizeof meta, "for_whom=%s", for_whom ? for_whom : "-");
+    return put_edge(s, id, claim_id, evidence_id, COG_GROUNDED_BY_RELATION, grounding, meta);
+}
+int cog_salient_edge(EngramPagedStore* s, const char* node_id,
+                     const char* observer_id, double salience) {
+    if (!s || !node_id || !observer_id) return -1;
+    char id[512];
+    snprintf(id, sizeof id, "st-%s-%s", node_id, observer_id);
+    return put_edge(s, id, node_id, observer_id, COG_SALIENT_TO_RELATION, salience, NULL);
+}
+int cog_assert_gate(EngramPagedStore* s, const char* claim_id,
+                    const char* for_whom, double floor) {
+    if (!s || !claim_id) return -1;
+    if (!(floor > 0)) floor = 0.5;
+    StoreEdge* edges = NULL; size_t n = 0;
+    if (store_get_edges_from(s, claim_id, &edges, &n) < 0) return -1;
+    double best = 0.0; int found = 0;
+    for (size_t i = 0; i < n; i++) {
+        if (!edges[i].relation || strcmp(edges[i].relation, COG_GROUNDED_BY_RELATION) != 0) continue;
+        /* grounded-for-whom: match observer if requested; global (for_whom=-) always counts */
+        int match = 1;
+        if (for_whom && edges[i].metadata) {
+            const char* fw = strstr(edges[i].metadata, "for_whom=");
+            if (fw) { fw += 9; if (strcmp(fw, for_whom) != 0 && strcmp(fw, "-") != 0) match = 0; }
+        }
+        if (match) { found = 1; if (edges[i].weight > best) best = edges[i].weight; }
+    }
+    store_edges_free(edges, n);
+    if (!found) return 0;                 /* ungrounded => refuse assertion (still held) */
+    return (best >= floor) ? 1 : 0;
+}
+
+/* ═══════════════════════════════════════════════ THE CORRESPONDENCE-LOOP ═════ */
+int engram_correspondence_beat(const GeoDescriptor* region, const float* anchor,
+                               double outcome_y, CogStance* stance,
+                               int learn, double max_step, CogBeatResult* out) {
+    if (!region || !stance || !out) return -1;
+    memset(out, 0, sizeof *out);
+    if (stance->keystone) { learn = 0; out->wrote_keystone = 1; }  /* §6: never write a keystone */
+
+    GeoGradient g;
+    if (engram_think(region, anchor, stance, &g) != 0) return -1;   /* PREDICTION */
+    double p = g.magnitude;
+    double y = clampd(outcome_y, 0.0, 1.0);
+    double err = fabs(p - y);
+    out->correspondence = 1.0 - err;
+    out->error = err;
+    out->brier = (p - y) * (p - y);
+
+    if (learn) {
+        /* refine warp: gradient descent of (p−y)² wrt each axis_gain.
+         *   p = 1/(1+D²);  ∂p/∂gain_k = 2 p² proj_k² / (ext_k² gain_k³)  (>=0)
+         *   ∂(err²)/∂gain_k = 2 (p−y) ∂p/∂gain_k
+         * step = −lr · ∂(err²)/∂gain_k, bounded to ±max_step (metastability). */
+        int dim = region->dim;
+        const float* x = anchor ? anchor : region->centroid;
+        float* r = malloc((size_t)dim * sizeof(float));
+        if (r) {
+            for (int i = 0; i < dim; i++) r[i] = (float)((double)x[i] - (double)region->centroid[i]);
+            double lr = 0.5;
+            double bound = (max_step > 0) ? max_step : 0.05;   /* bounded update rate */
+            for (int k = 0; k < region->n_axes && k < stance->n_axes; k++) {
+                const float* ax = region->axes[k].axis; if (!ax) continue;
+                double proj = vdot(r, ax, dim);
+                double ext = region->axes[k].extent; if (ext < 1e-9) ext = 1e-9;
+                double gain = stance->axis_gain[k]; if (gain < 1e-6) gain = 1e-6;
+                double dp_dgain = 2.0 * p * p * (proj * proj) / (ext * ext * gain * gain * gain);
+                double dErr_dgain = 2.0 * (p - y) * dp_dgain;
+                double step = -lr * dErr_dgain;
+                step = clampd(step, -bound, bound);
+                stance->axis_gain[k] = clampd(gain + step, 0.1, 50.0);
+            }
+            free(r);
+        }
+        /* calibration */
+        stance->n_trials += 1;
+        stance->brier_sum += out->brier;
+        stance->last_error = err;
+        stance->ema_error = (stance->n_trials == 1) ? err : 0.9 * stance->ema_error + 0.1 * err;
+        double mean_brier = stance->brier_sum / (double)stance->n_trials;
+        stance->reliability = clampd(1.0 - sqrt(mean_brier), 0.0, 1.0);
+    }
+    out->reliability = stance->reliability;
+    engram_gradient_free(&g);
+    return 0;
+}

lang/runtime/engram_cognition.h

@@ -0,0 +1,216 @@
+/* engram_cognition.h — THE ONE OPERATION.
+ *
+ * The buildable form of the "cognition is one operation" theory (design doc
+ * engram/spec/cognitive-architecture.design.md; memory bdc8a488 / d582a766).
+ *
+ * Cognition is ONE operation — think — a directed traversal-READ of the geometry
+ * from an anchor, steered by a learned STANCE, whose output is a GRADIENT (a
+ * direction + spread over the geometry), never a point. The named faculties
+ * (reason / induce / abduce / analogy / relate / plan / ground) are human LABELS
+ * on regions of think's steering space: each faculty == { think + a named stance }.
+ * Collapse-to-a-point happens only at EXPRESSION (a separate faculty), never in think.
+ *
+ * NAMING (Will's directive): the surface verbs name the cognitive ACT being
+ * performed (think / reason / induce / ground / verify), not the internal function
+ * shape. The single frozen primitive underneath every faculty is engram_think,
+ * which composes over engram_reason_point_fit + the §5 geo-algebra. Those never
+ * learn. Only the STANCE learns.
+ *
+ * "Stance" is the theory's steering PRIOR, deliberately named distinctly: in this
+ * codebase the token "prior" already means previous-VERSION (supersession). A
+ * Stance is a learnable bias/disposition over the geometry — which axes matter,
+ * which way pays off, plus a calibrated track record — attached to a faculty-label
+ * and a region, and grounded-for-whom.
+ *
+ * PURE + (mostly) READ-ONLY, stdlib + libm only. think() and the warp are pure
+ * over their inputs. Persistence (Stance <-> StoreNode, grounded-by edges) is the
+ * only part that touches the store, and it is additive / supersede / tombstone —
+ * never mutate-in-place, never delete. It NEVER touches the live daemon: all
+ * offline against a scratch store, per the design's rails.
+ */
+#ifndef ENGRAM_COGNITION_H
+#define ENGRAM_COGNITION_H
+
+#include <stdint.h>
+#include <stddef.h>
+#include "engram_geometry.h"
+#include "engram_reason.h"
+#include "engram_store.h"
+
+/* Max principal axes a stance warps (matches GeoParams.top_axes default budget). */
+#define COG_MAX_AXES 32
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §1  GeoGradient — the OUTPUT of think. A direction + spread over the geometry,
+ * plus the calibrated confidence and the read it was computed against. NOT a point.
+ * A spiked gradient (spread→0) = "exact" (deduction); a spread gradient = "fuzzy"
+ * (prediction). The gradient is ALSO the next steering direction (closed-loop flow).
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    int         dim;
+    float*      direction;   /* unit steering vector in the anchor's frame  (owned) */
+    double      spread;      /* 0 = spiked/exact ... large = diffuse/fuzzy          */
+    double      confidence;  /* calibrated, from the stance's track record (reliab.) */
+    double      magnitude;   /* THIS read's own membership/fit estimate ∈(0,1].
+                              * The scalar an expression faculty would SAMPLE; kept
+                              * on the gradient but never used AS a decision by think.*/
+    const char* anchor_id;   /* borrowed: the vantage this was read from            */
+    int         n_support;   /* neighborhood members that shaped the read           */
+    const char* stance_id;   /* borrowed: which stance steered this (provenance)    */
+} GeoGradient;
+
+void engram_gradient_free(GeoGradient* g);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §2  Stance — the learnable steering prior, as a first-class object. In memory
+ * here; persisted as a StoreNode (node_type "Stance") via cog_stance_*serialize.
+ *
+ *   warp:  axis_gain[]  per-principal-axis multiplier on extents (which axes
+ *                       matter — gain>1 WIDENS an axis so it penalizes less);
+ *          bias_dir[]   a steering-direction seed in the region's frame;
+ *          scalars      faculty constants this stance overrides (ext_floor, etc).
+ *   calibration:        the track record — the ONLY thing the loop (§4) updates
+ *                       besides warp: n_trials, a Brier accumulator, reliability
+ *                       (→ GeoGradient.confidence), and an EMA error.
+ *   keystone:           if set, the correspondence-loop MUST NEVER write warp or
+ *                       calibration — read-mostly (self / values). §6 metastability.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    char*   id;             /* stance node id (owned)                              */
+    char*   faculty;        /* the act this stance serves: "induce"|"relate"|...   */
+    char*   anchor_region;  /* node/neighborhood id this stance is attached to     */
+    char*   for_whom;       /* observer id — grounding is relational (NULL=global) */
+    int     keystone;       /* 1 = read-mostly, loop never writes it (§6)          */
+
+    int     dim;            /* embedding dim of the region                         */
+    int     n_axes;         /* how many axis_gain entries are live (<= COG_MAX_AXES)*/
+    double  axis_gain[COG_MAX_AXES]; /* per-axis extent multipliers (init 1.0)     */
+    float*  bias_dir;       /* dim floats, steering seed (owned; NULL = none)      */
+    double  ext_floor;      /* faculty scalar: the extent floor (init 1.0)         */
+    double  drop_frac;      /* faculty scalar (causal): confound drop (init 0.5)   */
+    double  assoc_floor;    /* faculty scalar (causal): assoc floor (init 0.2)     */
+
+    /* calibration / track record */
+    int64_t n_trials;
+    double  brier_sum;      /* Σ (p − y)²                                          */
+    double  reliability;    /* calibrated ∈[0,1] → GeoGradient.confidence          */
+    double  ema_error;      /* EMA of per-trial error                              */
+    double  last_error;
+} CogStance;
+
+/* Initialize a neutral stance (all gains 1.0, default scalars, reliability 0.5).
+ * dim/n_axes taken from the region descriptor. faculty/id/for_whom are copied. */
+int  cog_stance_init(CogStance* s, const char* id, const char* faculty,
+                     const char* anchor_region, const char* for_whom,
+                     const GeoDescriptor* region);
+void cog_stance_free(CogStance* s);
+
+/* A stance set to today's hard-coded constants == behavioral parity with the
+ * pre-stance operators (axis_gain all 1.0, ext_floor default, drop_frac 0.5,
+ * assoc_floor 0.2). This is the FROZEN CONTROL used by the validation. */
+void cog_stance_set_frozen_defaults(CogStance* s);
+
+/* ── Serialization: Stance <-> StoreNode (compact line schema "STNC1", mirroring
+ * the reify "GEO1" precedent). Additive; the node's importance field caches the
+ * reliability readout. Round-trips exactly (reboot-prove). ──────────────────── */
+char* cog_stance_to_metadata(const CogStance* s);          /* owned string        */
+int   cog_stance_to_node(const CogStance* s, StoreNode* out);/* fills a StoreNode  */
+int   cog_stance_from_node(const StoreNode* n, CogStance* out);/* parse STNC1      */
+
+#define COG_STANCE_NODE_TYPE   "Stance"
+#define COG_STANCE_META_MAGIC  "STNC1"
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §1.2  think — the ONE operation. Frozen procedure over three steps:
+ *   1. re-origin on the anchor point (the vantage; the manifold is the read
+ *      neighborhood, passed as `region`);
+ *   2. fit the anchor under the stance's WARP (engram_reason_point_fit with the
+ *      axis extents multiplied by axis_gain and ext_floor substituted);
+ *   3. emit a GRADIENT: direction = the warped steepest-descent that reduces the
+ *      fit distance (the "which way pays off" seed + bias_dir), spread from the
+ *      fit distance, confidence from the stance's reliability, magnitude = the
+ *      read's membership estimate. NO point-collapse — that is expression.
+ *
+ * `region`  — the read neighborhood (built by vantage_read / geometry descriptor).
+ * `anchor`  — the point to read FROM (dim floats). NULL = region centroid (self).
+ * `stance`  — the steering prior. NULL = neutral (frozen defaults) => parity.
+ * Returns 0 and fills `out` (engram_gradient_free), <0 on error.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+int engram_think(const GeoDescriptor* region, const float* anchor,
+                 const CogStance* stance, GeoGradient* out);
+
+/* The warped fit itself (step 2), exposed for the loop + verifier reuse. Identical
+ * to engram_reason_point_fit when stance==NULL or all gains==1 && ext_floor default. */
+int cog_warped_fit(const GeoDescriptor* region, const float* x,
+                   const CogStance* stance, GeoFit* out);
+
+/* EXPRESSION — the ONLY place a gradient collapses to a point. Samples the gradient
+ * off the anchor along its steering direction, scaled by (1 − spread) so a spiked
+ * (confident) gradient lands a definite point and a diffuse one barely moves.
+ * This is deliberately a SEPARATE faculty from think (§1.2, M5). */
+int engram_express(const GeoGradient* g, const float* anchor, float* out_point);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §5  HOLD vs GROUND vs ASSERT. Holding is unconditional (the store gates nothing).
+ * Grounding is a RELATION — a "grounded-by" edge, probabilistic, grounded-for-whom.
+ * The honesty floor is checked only at ASSERTION.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+#define COG_GROUNDED_BY_RELATION "grounded-by"
+#define COG_SALIENT_TO_RELATION  "salient-to"
+
+/* Write a grounded-by edge (additive). weight = grounding ∈(0,1] from the verifier;
+ * for_whom recorded in edge metadata (grounding is relational). Never a node flag. */
+int cog_ground_edge(EngramPagedStore* s, const char* claim_id,
+                    const char* evidence_id, double grounding, const char* for_whom);
+
+/* Write/refresh a salient-to edge: salience is RELATIONAL (grounded-for-whom),
+ * carried on the edge to the observer — not baked into the node scalar (§2.1). */
+int cog_salient_edge(EngramPagedStore* s, const char* node_id,
+                     const char* observer_id, double salience);
+
+/* The honesty floor — a QUERY at assertion time, NOT a schema constraint. Reads the
+ * claim's stored grounded-by edges (for the given observer) and returns:
+ *   1  = may assert (best grounding >= floor),
+ *   0  = REFUSE assertion (holds unconditionally; only asserting is gated),
+ *  <0  = error. The content remains held either way. */
+int cog_assert_gate(EngramPagedStore* s, const char* claim_id,
+                    const char* for_whom, double floor);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §4  THE REFLEXIVE CORRESPONDENCE-LOOP — the learning engine. think scores its
+ * OWN gradient against outcome, refines the stance on the error, and (optionally)
+ * writes the (gradient, outcome, error) back as self-describing geometry. This is
+ * the dormant verifier turned INWARD.
+ *
+ * grade(1) SELF-CONSISTENCY (no external world-labels): the outcome is what the
+ * geometry itself says — the membership determined by the region's SIGNAL subspace
+ * (the axes reality actually weights). The stance's cheap warped read is graded
+ * against that geometric truth; error refines the warp so the read corresponds.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    double  correspondence;  /* ∈[0,1]: 1 − |p − y| for this trial                 */
+    double  error;           /* 1 − correspondence                                  */
+    double  brier;           /* running mean (p − y)² across the stance's trials    */
+    double  reliability;     /* the stance's current calibrated reliability          */
+    int     wrote_keystone;  /* 1 iff a keystone update was BLOCKED (safety audit)   */
+} CogBeatResult;
+
+/* One correspondence beat for ONE trial:
+ *   think(region, anchor, stance) -> gradient (a PREDICTION, ungrounded)
+ *   outcome y := grade-1 self-consistency target (in [0,1])
+ *   error = |magnitude − y|; refine stance.warp + calibration on the error
+ *           (bounded step; NEVER writes a keystone stance)
+ * `learn`==0 grades WITHOUT updating (the frozen-control path). `max_step` bounds
+ * the per-beat warp change (metastability; §6). Returns 0 / <0. */
+int engram_correspondence_beat(const GeoDescriptor* region, const float* anchor,
+                               double outcome_y, CogStance* stance,
+                               int learn, double max_step, CogBeatResult* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §6  METASTABILITY. Keystones (self/values) are read-mostly: the loop reads but
+ * never writes them. Mark by stance flag or by a keystone-id set the loop consults.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct { const char** ids; int n; } CogKeystoneSet;
+int cog_is_keystone(const CogKeystoneSet* ks, const CogStance* s);
+
+#endif /* ENGRAM_COGNITION_H */

lang/runtime/engram_geometry.h

@@ -0,0 +1,449 @@
+/* engram_geometry.h — M9 FOUNDATION: the relational-neighborhood GEOMETRY
+ * DESCRIPTOR (design doc §3, §5; memory node e94371bd).
+ *
+ * Computes, for a relational neighborhood grown from a seed set, the compact
+ * (KB-not-MB) joint geometry Will specified: the SEMANTIC geometry (centroid,
+ * covariance / principal axes, radius) braided with the RELATIONAL geometry
+ * (k-core skeleton, hub->periphery centrality gradient), plus soft membership.
+ *
+ * Two coordinate systems, one shape — "a constellation: bright prototype at the
+ * center, a cloud of members at varying distance, the strongest edges as a
+ * backbone, fading at the edges."
+ *
+ * Built ON the two standalone M-era modules only:
+ *   - engram_vindex : semantic neighbors (the cloud) via ANN.
+ *   - engram_store  : node embeddings + hebb adjacency (the skeleton), read-only.
+ * It does NOT link or touch el_runtime.c, and it is a pure READ over the graph:
+ * it never modifies nodes, edges, activation, the index, or any retrieval path.
+ *
+ * Pure C11, stdlib + libm only. The descriptor is a foundation object; it is NOT
+ * wired into retrieval/priming yet (that is the next M9 step).
+ */
+#ifndef ENGRAM_GEOMETRY_H
+#define ENGRAM_GEOMETRY_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include "engram_store.h"
+#include "engram_vindex.h"
+
+/* One member of the neighborhood + its place in the gradient. */
+typedef struct {
+    char*  id;
+    double membership;    /* soft membership in [0,1] (semantic+relational blend) */
+    double centrality;    /* skeleton weighted-degree — relational salience     */
+    double salience;      /* the node's own stored salience                     */
+    int    core;          /* k-core number (0 = fringe / not in any core)       */
+    double dist_centroid; /* cosine distance of member emb to centroid (semantic)*/
+    int    embedded;      /* 1 if the member carried an emb vector              */
+} GeoMember;
+
+/* One skeleton edge (indices into members[]). eff_weight = weight*(1+0.5*hebb),
+ * clamped to 1.0 — the effective propagation strength eg_edge_eff_weight uses. */
+typedef struct { uint32_t a, b; double eff_weight; double hebb; } GeoEdge;
+
+/* A compact principal axis of the ellipsoid: unit direction in R^dim + extent
+ * (sqrt of the covariance eigenvalue = the ellipsoid's half-width along it). */
+typedef struct { float* axis; double extent; } GeoAxis;
+
+typedef struct {
+    int        dim;
+    /* ── anchor ── */
+    char*      hub_id;         /* highest-centrality member: the relational hub  */
+    float*     centroid;       /* v̄ ∈ R^dim: mean of the member embeddings in the
+                                * frame the descriptor operated in. When centered
+                                * (global_mean != NULL) this is the CENTERED
+                                * centroid (mean of L2-normalized embs minus the
+                                * global mean): the neighborhood's location in the
+                                * isotropic/whitened frame. Add global_mean back to
+                                * recover the raw prototype point. When uncentered
+                                * it is the raw mean of L2-normalized member embs. */
+    float*     global_mean;    /* the centering offset actually applied (dim floats),
+                                * or NULL if the descriptor ran in raw space. The §5
+                                * operators (distance/overlap/Wasserstein) are only
+                                * discriminative in the centered frame — see notes. */
+    /* ── shape (compact covariance): top principal axes + extents ── */
+    int        n_axes;
+    GeoAxis*   axes;           /* orientation + extents of the ellipsoid         */
+    double     total_variance; /* trace(Σ) = mean squared member dist to centroid*/
+    /* ── scale ── */
+    double     radius;         /* sqrt(total_variance) — the neighborhood breadth*/
+    /* ── members + gradient ── */
+    int        n_members;
+    GeoMember* members;        /* soft membership {id->weight} + centrality/salience */
+    /* ── skeleton ── */
+    int        n_edges;
+    GeoEdge*   edges;          /* strong internal hebb edges = the backbone      */
+    int        k_core;         /* the maximum core number present in the skeleton*/
+    /* ── diagnostics ── */
+    double     co_registration;/* corr(hebb strength, semantic proximity) over   */
+                               /* internal edges: >0 = geometries agree (reify);  */
+                               /* <0 = disagree (surprising links / dream cands). */
+    int        n_embedded;     /* members that carried an emb vector             */
+} GeoDescriptor;
+
+typedef struct {
+    int    ann_k;           /* semantic expansion: ANN neighbors per seed (0=off) */
+    int    hop_relational;  /* 1 = include seeds' hebb neighbors as members       */
+    double edge_min_weight; /* skeleton: ignore internal edges below this eff wt  */
+    int    kcore_k;         /* target k for the reported k-core (0 = auto/max)    */
+    int    top_axes;        /* principal axes to retain (default 8)               */
+    int    max_members;     /* cap neighborhood size (guards the eigensolve cost) */
+} GeoParams;
+
+/* Fill p with sane defaults: ann_k=24, hop_relational=1, edge_min_weight=0.05,
+ * kcore_k=0 (auto), top_axes=8, max_members=400. */
+void engram_geo_default_params(GeoParams* p);
+
+/* ── Global-mean cache (mean-centering / whitening the anisotropic emb space) ──
+ * The nomic-embed-text space over the engram corpus is strongly ANISOTROPIC:
+ * every embedding sits in a narrow cone (mean pairwise cosine ~0.55), which
+ * compresses cosine-based domain separation almost to nothing. Subtracting the
+ * GLOBAL MEAN of the (L2-normalized) embeddings recenters the cloud on the
+ * origin (mean pairwise cosine -> ~0), restoring isotropy so the §5 operators
+ * discriminate. The mean is a store-level derived quantity, like the ANN index:
+ * built once from the paged store, cached, and refreshed when the embedded set
+ * drifts. It lives here (not in the store) so this stays a contained, read-only
+ * addition; a runtime owns one GeoMeanCache per open store alongside its VIndex. */
+typedef struct GeoMeanCache GeoMeanCache;
+
+/* Scan every live node in `store` and compute the mean of the L2-normalized
+ * embeddings over the embed-eligible set (nodes carrying an emb vector; the
+ * unembedded telemetry/system nodes are skipped). Returns a malloc'd cache, or
+ * NULL on error / no embedded nodes. The offset vector is NOT renormalized — it
+ * is a translation, applied by subtraction. */
+GeoMeanCache* engram_geo_mean_build(EngramPagedStore* store);
+
+/* The cached offset (dim floats) — pass to engram_geometry_descriptor as
+ * global_mean. Valid until the cache is freed/refreshed. */
+const float* engram_geo_mean_vec(const GeoMeanCache* c);
+int          engram_geo_mean_dim(const GeoMeanCache* c);
+uint64_t     engram_geo_mean_count(const GeoMeanCache* c); /* #embedded nodes used */
+
+/* Recompute the mean IN PLACE iff the embedded-node count has drifted by more
+ * than `frac` (e.g. 0.10 = 10%) since the cache was built — "recompute on
+ * significant change". Returns 1 if it rebuilt, 0 if unchanged, <0 on error. */
+int engram_geo_mean_maybe_refresh(GeoMeanCache* c, EngramPagedStore* store,
+                                  double frac);
+
+void engram_geo_mean_free(GeoMeanCache* c);
+
+/* Compute the geometry descriptor of the neighborhood grown from seed_ids.
+ * READ-ONLY over store + vindex.
+ *   store  — an opened store (borrowed; not modified).
+ *   vindex — optional ANN index for semantic expansion; NULL disables it.
+ *   vids   — the ordinal->store-id map returned by vindex_build_from_store
+ *            (vids[node_id] == store id). Required iff vindex != NULL.
+ *   n_vids — length of vids.
+ *   params — NULL to use engram_geo_default_params.
+ *   global_mean — optional centering offset (dim floats, from engram_geo_mean_*).
+ *            When non-NULL the SEMANTIC geometry is computed in mean-centered
+ *            (isotropic) space: every normalized member emb has global_mean
+ *            subtracted before the centroid / cosine-distance / co-registration
+ *            math, so those operators discriminate. NULL = raw space (legacy).
+ *            NOTE: the ANN neighbor query still runs in RAW unit-vector space —
+ *            centering is a rigid translation that ~preserves neighborhood
+ *            MEMBERSHIP, so the index needs no rebuild; only the descriptor
+ *            STATISTICS move to the centered frame (co-registration choice (b)).
+ *            The eigen/covariance shape (axes, radius) is translation-invariant
+ *            and therefore identical in either frame.
+ * Returns a malloc'd descriptor (free with engram_geo_free), or NULL on error
+ * (no seeds resolvable, OOM). */
+GeoDescriptor* engram_geometry_descriptor(
+    EngramPagedStore* store, VIndex* vindex,
+    char** vids, int n_vids,
+    const char* const* seed_ids, size_t n_seeds,
+    const GeoParams* params,
+    const float* global_mean);
+
+void engram_geo_free(GeoDescriptor* g);
+
+/* ── M-INTEROCEPTION P3: drift-sensor primitive (descriptor displacement) ────
+ * Read-only. GROWTH vs CORRUPTION split of how far B drifted from baseline A.
+ * See engram_geometry.c for the honesty note on the missing SelfAnchor. */
+typedef struct {
+    double centroid_sep;    /* L2 distance between centroids (same frame)        */
+    double centroid_cos;    /* 1 - cosine(centroidA, centroidB)                  */
+    double radius_delta;    /* |radiusA - radiusB| — neighborhood scale change   */
+    double core_disp;       /* mean radial displacement of the invariant core    */
+    double periph_disp;     /* mean radial displacement of the periphery         */
+    int    core_matched;    /* # core members matched by id across A,B           */
+    int    periph_matched;  /* # periphery members matched by id across A,B       */
+} GeoDisplacement;
+
+void engram_geo_displacement(const GeoDescriptor* a, const GeoDescriptor* b,
+                             double core_frac, GeoDisplacement* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * §5 GEOMETRY OPERATORS — a relational ALGEBRA over neighborhood descriptors.
+ * These are the reusable primitives Will specified: "primitives any CGI
+ * application should be able to use." READ-ONLY and PURE (stdlib + libm only) —
+ * they consume GeoDescriptor(s) and never touch the store, index, or activation.
+ *
+ * FRAME CONTRACT: both inputs MUST have been built in the SAME frame — identical
+ * emb `dim` and identical `global_mean` (centered against the one true store-wide
+ * mean). The reify path builds every neighborhood that way, so descriptors are
+ * directly comparable. An operator returns <0 / NULL if the dims disagree.
+ *
+ * REPRESENTATION: the C descriptor lives in the FULL emb dim with a LOW-RANK
+ * covariance  Σ = Σ_k extent_k² · a_k a_kᵀ  over its retained principal axes
+ * (top_axes; the discarded tail variance is not modeled). Every operator mirrors
+ * the viz-proxy (engram-geometry-proxy.py §5) FORMULA exactly, but evaluates it on
+ * this representation — so semantics match the proxy while absolute numbers differ
+ * (proxy works in a 24-dim global-PCA reduced dense frame; C in full-dim low-rank).
+ * The Wasserstein / combine eigen-work is done inside the small JOINT axis subspace
+ * (dimension ≤ nA+nB+1), which is EXACT for the low-rank covariances there.
+ * Each result struct is released by its engram_geo_*_free.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+
+/* overlap(A,B): shared-member set + Jaccard + centroid/scale proximity score. */
+typedef struct {
+    char** shared_ids;            /* ids present in BOTH neighborhoods (owned)     */
+    int    n_shared;
+    int    n_union;               /* |A ∪ B| by id                                 */
+    double jaccard;               /* |A∩B| / |A∪B|                                 */
+    double centroid_distance;     /* L2 between the (centered) centroids           */
+    double overlap_score;         /* jacc*0.5 + max(0,1−d/(rA+rB))*0.5  (proxy form)*/
+    float* intersection_centroid; /* midpoint of the two centroids (dim, owned)    */
+    int    dim;
+} GeoOverlap;
+int  engram_geo_overlap(const GeoDescriptor* a, const GeoDescriptor* b, GeoOverlap* out);
+void engram_geo_overlap_free(GeoOverlap* o);
+
+/* subtract(A,B) — ORTHOGONAL-COMPLEMENT residual: project A onto I − V_B V_Bᵀ
+ * (V_B = B's top `b_dims` principal axes) — "A with B's framing removed". Returns
+ * A's residual centroid + residual ellipsoid, the fraction of A's energy that lives
+ * inside B's subspace, and the centroid-difference vector. b_dims<=0 → min(3,nB). */
+typedef struct {
+    int      dim;
+    float*   residual_centroid;       /* P⊥ c_A                            (owned) */
+    float*   centroid_diff;           /* c_A − c_B                         (owned) */
+    double   centroid_diff_mag;
+    double   variance_explained_by_B; /* (‖Qc_A‖²+Tr(QΣ_A)) / (‖c_A‖²+Tr Σ_A) ∈[0,1]*/
+    int      removed_dims;            /* # of B axes used as V_B                   */
+    double   residual_scale;          /* sqrt(Tr(P⊥ Σ_A P⊥))                       */
+    int      n_axes;                  /* residual principal axes           (owned) */
+    GeoAxis* axes;
+} GeoResidual;
+int  engram_geo_subtract(const GeoDescriptor* a, const GeoDescriptor* b,
+                         int b_dims, GeoResidual* out);
+void engram_geo_residual_free(GeoResidual* r);
+
+/* set-diff variant of subtract: members in A but not in B + the centroid arrow. */
+typedef struct {
+    char** only_ids;              /* member ids in A and not in B (owned)          */
+    int    n_only;
+    int    removed;               /* |A ∩ B| (dropped)                             */
+    float* centroid_diff;         /* c_A − c_B (dim, owned)                        */
+    double centroid_diff_mag;
+    int    dim;
+} GeoSetDiff;
+int  engram_geo_setdiff(const GeoDescriptor* a, const GeoDescriptor* b, GeoSetDiff* out);
+void engram_geo_setdiff_free(GeoSetDiff* s);
+
+/* combine(A,B): a merged descriptor — POOLED centroid + POOLED covariance
+ * (exact law-of-total-variance: the covariance you'd get by concatenating the two
+ * member clouds), re-eigendecomposed for its principal axes. Members = id-union
+ * (membership = max). top_axes<=0 → 8. Returns a malloc'd GeoDescriptor (free with
+ * engram_geo_free) in the same frame as A, or NULL on error. */
+GeoDescriptor* engram_geo_combine(const GeoDescriptor* a, const GeoDescriptor* b,
+                                  int top_axes);
+
+/* distance(A,B): centroid L2 + centroid cosine + closed-form Wasserstein-2
+ * (Bures metric) between the two Gaussians — mirrors the proxy's _wasserstein2. */
+typedef struct {
+    double centroid_distance;
+    double centroid_cosine;
+    double wasserstein2;
+    int    dim;
+} GeoDistance;
+int engram_geo_distance(const GeoDescriptor* a, const GeoDescriptor* b, GeoDistance* out);
+
+/* analogy(A,B): orthogonal PROCRUSTES transform  min_R ‖A − B R‖_F, RᵀR=I (SVD)
+ * aligning A's principal frame to B's (extent-scaled axes, paired by rank). R is
+ * returned COMPACTLY as an r×r rotation within the joint axis subspace `basis`
+ * (r vectors of dim floats); it acts as the identity on the orthogonal complement.
+ * Apply it to a vector with engram_geo_analogy_apply. */
+typedef struct {
+    int     dim;
+    int     r;        /* subspace rank; R is r×r                                   */
+    float*  basis;    /* r×dim row-major orthonormal basis Q                (owned) */
+    double* R;        /* r×r rotation in Q-coords, row-major                (owned) */
+    double  residual; /* ‖A − B R‖_F over the extent-scaled frames                 */
+} GeoAnalogy;
+int  engram_geo_analogy(const GeoDescriptor* a, const GeoDescriptor* b, GeoAnalogy* out);
+/* out_vec = R·v for v ∈ R^dim: v + Σ_i (R̂c − c)_i q_i, c_i = q_i·v. dim floats. */
+void engram_geo_analogy_apply(const GeoAnalogy* an, const float* v, float* out_vec);
+void engram_geo_analogy_free(GeoAnalogy* an);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * M10 — REIFICATION: densely co-wired relational neighborhoods crystallized into
+ * FIRST-CLASS, PERSISTED store records (design doc §2; memory 885f5945). This is
+ * NOT a cache — it is durable structure. A reified neighborhood is a real store
+ * NODE (node_type "Neighborhood") that survives restart, is loaded on boot, and
+ * EVOLVES via supersede+provenance when the pattern shifts. The geometry-priming
+ * HOT PATH reads these persisted records (never computes geometry on the
+ * activation path). Ad-hoc/transient geometries still use the on-the-fly
+ * engram_geometry_descriptor above.
+ *
+ * Two record types, both ordinary TLV store nodes (no new on-disk format):
+ *   - "GeoMeanFrame"  : the store-wide centering mean, persisted ONCE (emb = mean
+ *                       vector, id ENGRAM_GEO_MEANFRAME_ID). Referenced by every
+ *                       neighborhood so priming centers against the SAME true mean.
+ *   - "Neighborhood"  : one reified neighborhood. emb = the RAW centroid (prototype
+ *                       point, so it stays centroid-ANN-able; centered_centroid =
+ *                       emb - meanframe). metadata = the compact "GEO1" schema:
+ *                       hub id, meanframe ref, scalar shape (radius, total_variance,
+ *                       k_core, co_registration, n_embedded), axis EXTENTS (ellipsoid
+ *                       half-widths), and the MEMBER list {id -> membership, centrality,
+ *                       core}. Member links are also persisted as edges relation="member".
+ *
+ * v1 honest simplifications (documented; extensible without migration): axis
+ * DIRECTION vectors are not persisted (extents capture the ellipsoid scale; the
+ * directions are recomputable via the on-the-fly descriptor for viz/operators);
+ * with hebb potentiation ~0 on today's store the "hebb-weighted" degree reduces to
+ * AUTHORED edge weight, so detected neighborhoods currently reflect authored edges —
+ * the design is unchanged and self-correcting once hebb accrues.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+
+#define ENGRAM_GEO_NBHD_TYPE       "Neighborhood"
+#define ENGRAM_GEO_MEANFRAME_TYPE  "GeoMeanFrame"
+#define ENGRAM_GEO_MEANFRAME_ID    "geo-meanframe"   /* stable id of the singleton */
+#define ENGRAM_GEO_NBHD_ID_PREFIX  "nbhd-"           /* id = nbhd-<hub>-<built_at> */
+#define ENGRAM_GEO_MEMBER_RELATION "member"
+/* ── One-level nesting (containment DAG). A "super" neighborhood is itself a
+ * Neighborhood node whose GEO1 metadata carries `level 1` + `c <child_id>` lines
+ * and which is joined to each child by a "contains" edge (child→parent
+ * "nested-in"). Its id also begins with the "nbhd-" prefix, so the boot path
+ * routes it into the resident reify index and skips its edges from activation
+ * adjacency, exactly like a flat neighborhood. ──────────────────────────────── */
+#define ENGRAM_GEO_SUPER_ID_PREFIX   "nbhd-super-"
+#define ENGRAM_GEO_SUPER_CONTENT     "reified-super-neighborhood"
+#define ENGRAM_GEO_CONTAINS_RELATION "contains"
+#define ENGRAM_GEO_NESTED_RELATION   "nested-in"
+
+/* Per-run counters for the on-beat self-reification operation. All fields are
+ * out-params filled by engram_geo_reify_store when GeoReifyParams.stats != NULL.
+ *   reified    — neighborhoods WRITTEN this run (new or materially changed hubs)
+ *   skipped    — hubs whose signature was UNCHANGED vs their live neighborhood
+ *                (the convergence signal: on a settled store this trends to the
+ *                hub count and `reified` trends to 0 → zero appends per beat)
+ *   superseded — prior neighborhood records tombstoned into the residue chain
+ *   member_edges — relation="member" edges written this run */
+typedef struct {
+    int reified;
+    int skipped;
+    int superseded;
+    int member_edges;
+} GeoReifyStats;
+
+typedef struct {
+    int    min_weighted_degree;  /* hub qualifies iff strong-edge weighted degree >= this
+                                  * (0 = no floor: just rank + take top max_neighborhoods) */
+    int    max_neighborhoods;    /* homeostatic budget cap (default 128) */
+    double cover_membership;     /* skip a hub already a member (w>=this) of an accepted
+                                  * neighborhood — greedy non-redundant cover (default 0.5) */
+    int    persist_member_edges; /* 1 = also write relation="member" edges (default 1) */
+    GeoParams descriptor;        /* per-neighborhood params (top_axes may be 0 = skip eigensolve) */
+
+    /* ── SELF-REIFICATION extensions (default 0/NULL = legacy behavior) ──────────
+     * When these are off, engram_geo_reify_store is byte-for-byte its pre-2026-08-14
+     * behavior — the ENGRAM_SELF_REIFY gate keeps the live binary inert until set. */
+    int    incremental;   /* 1 = CHANGE-DETECTION: skip a hub whose neighborhood
+                           * signature (member-set + memberships + coarse geometry)
+                           * is unchanged vs its current live record — no re-append,
+                           * no supersede. This is what makes on-beat reification
+                           * idempotent/convergent under the write-barrier. */
+    int    grounded_name; /* 1 = NAME the neighborhood from its most-central member
+                           * labels (grounded, provenance-stamped) instead of the
+                           * fixed content "reified-neighborhood". */
+    const char* cause;    /* supersession CAUSE tag written into the residue chain
+                           * ("autonomous-drift" on the beat, "explicit-override" /
+                           * "rename" for the async manual override). NULL = "reify". */
+    GeoReifyStats* stats; /* nullable: per-run counters (see above). */
+} GeoReifyParams;
+
+/* Defaults: min_weighted_degree=0, max_neighborhoods=128, cover_membership=0.5,
+ * persist_member_edges=1, descriptor = engram_geo_default_params but top_axes=4,
+ * max_members=256 (reified neighborhoods stay compact). */
+void engram_geo_reify_default_params(GeoReifyParams* p);
+
+/* WRITE PATH (offline / consolidation — NEVER the activation hot path).
+ * Detect dense hub neighborhoods on the hebb-weighted graph, compute each one's
+ * CENTERED descriptor ONCE against the true store-wide mean, and PERSIST them as
+ * first-class records: the GeoMeanFrame (once) + one Neighborhood node per detected
+ * neighborhood (+ member edges), superseding any prior same-hub record with
+ * provenance. Read-then-write over `store`. Returns #neighborhoods persisted, or <0.
+ * Skips existing Neighborhood/GeoMeanFrame nodes when detecting (idempotent re-reify). */
+int engram_geo_reify_store(EngramPagedStore* store, VIndex* vindex,
+                           char** vids, int n_vids,
+                           const GeoReifyParams* params);
+
+/* NESTING (one level). Reads the already-persisted flat Neighborhood records,
+ * agglomerates them by centroid cosine >= `min_cos` into groups, and persists one
+ * PARENT "super" Neighborhood node per group of >= 2 (geometry = mean of child
+ * centroids; `contains`/`nested-in` edges to children). Tombstones prior super
+ * records first (idempotent). Returns #parents persisted, or <0. Run AFTER
+ * engram_geo_reify_store. `min_cos` <= 0 uses the default (0.30). */
+int engram_geo_reify_nest(EngramPagedStore* store, double min_cos);
+
+/* ASYNC EXPLICIT OVERRIDE (degenerate manual case). Rename the live neighborhood
+ * `nbhd_id` to `new_name`: writes a fresh superseding Neighborhood record that
+ * carries the SAME geometry + members but the new name, tombstones the prior
+ * record, and PREPENDS a residue entry (cause="explicit-override", the prior
+ * name) so the maturation trail is preserved. Never blocks the autonomous beat;
+ * it simply supersedes whatever the beat last wrote. Returns the new record id
+ * (caller frees) or NULL on failure (id not a live neighborhood). */
+char* engram_geo_neighborhood_rename(EngramPagedStore* store,
+                                     const char* nbhd_id, const char* new_name);
+
+/* ── Resident loaded form of the persisted records (boot-time; READ-ONLY) ─────
+ * The durable Neighborhood/GeoMeanFrame records are the source of truth; this
+ * index is their LOADED form (like the resident node array is the loaded form of
+ * the node records, or adjacency the loaded form of edges). It never recomputes
+ * geometry — it parses. Build it by feeding the runtime's boot node scan, or in
+ * one pass with engram_geo_reify_load. */
+typedef struct GeoReifyIndex GeoReifyIndex;
+
+GeoReifyIndex* engram_geo_reify_index_new(void);
+/* Feed one store node; if it is a Neighborhood or GeoMeanFrame record it is parsed
+ * and absorbed (else ignored). The node is BORROWED (copied as needed). 0/<0. */
+int  engram_geo_reify_index_add(GeoReifyIndex* ix, const StoreNode* n);
+/* Build the member->neighborhood hash after all adds. Call once. 0/<0. */
+int  engram_geo_reify_index_finalize(GeoReifyIndex* ix);
+/* One-pass convenience: scan the store and build the finalized index. NULL if the
+ * store holds no reified records. */
+GeoReifyIndex* engram_geo_reify_load(EngramPagedStore* store);
+
+/* A borrowed view of one persisted neighborhood (owned by the index). */
+typedef struct {
+    const char*         id;
+    const char*         hub_id;
+    int                 n_members;
+    char* const*        member_ids;   /* parallel arrays, length n_members */
+    const double*       member_w;     /* membership in [0,1] */
+    double              radius;
+    double              co_registration;
+    int                 k_core;
+    int                 n_embedded;
+} GeoNeighborhood;
+
+/* HOT-PATH LOOKUP (no geometry compute): resolve the seed set to the best
+ * persisted neighborhood — the one with the greatest summed seed membership; on a
+ * miss (no seed is a member of any neighborhood) fall back to the centroid nearest
+ * the query embedding (centered by the loaded mean frame). q_emb may be NULL (then
+ * a miss returns NULL). Returns a BORROWED handle (do NOT free) or NULL. */
+const GeoNeighborhood* engram_geo_reify_lookup(
+    const GeoReifyIndex* ix,
+    const char* const* seed_ids, size_t n_seeds,
+    const float* q_emb, int q_dim);
+
+/* M10 read-only JSON serializers of the resident reify index (caller owns the
+ * returned malloc'd string; get_cstr returns NULL when id is not found). */
+char*        engram_geo_reify_list_cstr(const GeoReifyIndex* ix);
+char*        engram_geo_reify_get_cstr(const GeoReifyIndex* ix, const char* id);
+int          engram_geo_reify_count(const GeoReifyIndex* ix);
+const float* engram_geo_reify_mean(const GeoReifyIndex* ix, int* dim); /* loaded true mean or NULL */
+void         engram_geo_reify_index_free(GeoReifyIndex* ix);
+
+#endif /* ENGRAM_GEOMETRY_H */

lang/runtime/engram_reason.c

@@ -0,0 +1,287 @@
+/* engram_reason.c — the REASONING layer. Pure compositions over engram_geometry.h.
+ * stdlib + libm only; READ-ONLY over its descriptor inputs; touches no store/index. */
+#include "engram_reason.h"
+#include <stdlib.h>
+#include <string.h>
+#include <math.h>
+
+/* ── small float-vector helpers ─────────────────────────────────────────────── */
+static double vdot(const float* a, const float* b, int dim) {
+    double s = 0; for (int i = 0; i < dim; i++) s += (double)a[i] * (double)b[i]; return s;
+}
+static double vnorm(const float* a, int dim) { return sqrt(vdot(a, a, dim)); }
+static double vcos(const float* a, const float* b, int dim) {
+    double na = vnorm(a, dim), nb = vnorm(b, dim);
+    if (na < 1e-12 || nb < 1e-12) return 0.0;          /* a null vector ⇒ no direction */
+    double c = vdot(a, b, dim) / (na * nb);
+    if (c > 1.0) c = 1.0; if (c < -1.0) c = -1.0;
+    return c;
+}
+static double l2(const float* a, const float* b, int dim) {
+    double s = 0; for (int i = 0; i < dim; i++) { double d = (double)a[i] - (double)b[i]; s += d * d; }
+    return sqrt(s);
+}
+
+/* ═══════════════════════════════════════════ SHARED — point-to-manifold FIT ══ */
+int engram_reason_point_fit(const GeoDescriptor* g, const float* x,
+                            double ext_floor, GeoFit* out) {
+    if (!g || !x || !out || g->dim <= 0 || !g->centroid) return -1;
+    if (!(ext_floor > 0)) ext_floor = 1.0;
+    int dim = g->dim;
+    /* residual r = x − centroid */
+    double rr = 0;                          /* ‖r‖²                                 */
+    float* r = malloc((size_t)dim * sizeof(float));
+    if (!r) return -1;
+    for (int i = 0; i < dim; i++) { double d = (double)x[i] - (double)g->centroid[i]; r[i] = (float)d; rr += d * d; }
+    double maha2 = 0, ss_in = 0;            /* Mahalanobis² and in-subspace energy  */
+    for (int k = 0; k < g->n_axes; k++) {
+        const float* ax = g->axes[k].axis; if (!ax) continue;
+        double proj = vdot(r, ax, dim);     /* axes are orthonormal directions       */
+        double den = g->axes[k].extent; if (den < ext_floor) den = ext_floor;
+        maha2 += (proj / den) * (proj / den);
+        ss_in += proj * proj;
+    }
+    double ortho2 = rr - ss_in; if (ortho2 < 0) ortho2 = 0;   /* off-subspace energy */
+    double dist2 = maha2 + ortho2 / (ext_floor * ext_floor);
+    out->mahalanobis    = sqrt(maha2);
+    out->ortho_residual = sqrt(ortho2);
+    out->distance       = sqrt(dist2);
+    out->score          = 1.0 / (1.0 + dist2);
+    free(r);
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════════════════════ ANALOGY ════ */
+int engram_reason_analogy(const GeoDescriptor* A, const GeoDescriptor* B,
+                          const GeoDescriptor* C,
+                          const GeoDescriptor* const* candidates, int n_candidates,
+                          GeoAnalogyResult* out) {
+    if (!A || !B || !C || !out) return -1;
+    if (!A->centroid || !B->centroid || !C->centroid) return -1;
+    int dim = A->dim;
+    if (B->dim != dim || C->dim != dim) return -1;
+    memset(out, 0, sizeof *out);
+    out->dim = dim; out->best = -1;
+
+    /* Learn R_{A→B}. engram_geo_analogy(X,Y) yields R with apply(R, Y-axis) ≈ X-axis
+     * (R maps Y's frame → X's frame); so R that maps A→B is engram_geo_analogy(B,A). */
+    GeoAnalogy an;
+    if (engram_geo_analogy(B, A, &an) != 0) return -1;
+    out->analogy_residual = an.residual;
+
+    /* mapped = R·c_C + (c_B − R·c_A) : the A→B affine (rotation + residual shift). */
+    float* RcA = malloc((size_t)dim * sizeof(float));
+    float* RcC = malloc((size_t)dim * sizeof(float));
+    out->mapped_point = malloc((size_t)dim * sizeof(float));
+    if (!RcA || !RcC || !out->mapped_point) { free(RcA); free(RcC); free(out->mapped_point); out->mapped_point = NULL; engram_geo_analogy_free(&an); return -1; }
+    engram_geo_analogy_apply(&an, A->centroid, RcA);
+    engram_geo_analogy_apply(&an, C->centroid, RcC);
+    for (int i = 0; i < dim; i++)
+        out->mapped_point[i] = (float)((double)RcC[i] + ((double)B->centroid[i] - (double)RcA[i]));
+    free(RcA); free(RcC);
+    engram_geo_analogy_free(&an);
+
+    /* nearest candidate to the mapped point (centroid L2). */
+    if (candidates && n_candidates > 0) {
+        out->n_candidates = n_candidates;
+        out->distances = malloc((size_t)n_candidates * sizeof(double));
+        if (!out->distances) return -1;
+        double best = -1; int bi = -1;
+        for (int i = 0; i < n_candidates; i++) {
+            const GeoDescriptor* cd = candidates[i];
+            double d = (cd && cd->centroid && cd->dim == dim) ? l2(out->mapped_point, cd->centroid, dim) : INFINITY;
+            out->distances[i] = d;
+            if (bi < 0 || d < best) { best = d; bi = i; }
+        }
+        out->best = bi; out->best_distance = best;
+    }
+    return 0;
+}
+void engram_reason_analogy_free(GeoAnalogyResult* r) {
+    if (!r) return;
+    free(r->mapped_point); free(r->distances);
+    r->mapped_point = NULL; r->distances = NULL;
+}
+
+/* ═══════════════════════════════════════════════════════════════ INDUCTION ══ */
+int engram_reason_induce(const GeoDescriptor* const* examples, int n_examples,
+                         int top_axes, double ext_floor, GeoInduction* out) {
+    if (!examples || n_examples < 1 || !out) return -1;
+    if (top_axes <= 0) top_axes = 8;
+    memset(out, 0, sizeof *out);
+
+    /* fold the examples left→right through the pooled-Gaussian combine. n==1 pools
+     * the single example with itself (identical cov ⇒ same shape, id-union = itself). */
+    GeoDescriptor* acc = engram_geo_combine(examples[0],
+                                            examples[n_examples > 1 ? 1 : 0], top_axes);
+    if (!acc) return -1;
+    for (int i = 2; i < n_examples; i++) {
+        GeoDescriptor* nxt = engram_geo_combine(acc, examples[i], top_axes);
+        engram_geo_free(acc);
+        if (!nxt) return -1;
+        acc = nxt;
+    }
+    out->rule = acc;
+    out->n_examples = n_examples;
+    out->ext_floor = (ext_floor > 0) ? ext_floor
+                   : (acc->radius > 0 ? acc->radius * 0.25 : 1.0);
+    return 0;
+}
+double engram_reason_membership(const GeoInduction* ind, const float* x) {
+    if (!ind || !ind->rule || !x) return -1;
+    GeoFit f;
+    if (engram_reason_point_fit(ind->rule, x, ind->ext_floor, &f) != 0) return -1;
+    return f.score;
+}
+void engram_reason_induction_free(GeoInduction* out) {
+    if (!out) return;
+    if (out->rule) engram_geo_free(out->rule);
+    out->rule = NULL;
+}
+
+/* ═══════════════════════════════════════════════════════════════ ABDUCTION ══ */
+int engram_reason_abduce(const float* obs, int dim,
+                         const GeoDescriptor* const* hypotheses, int n,
+                         double ext_floor, GeoAbduction* out) {
+    if (!obs || !hypotheses || n < 1 || dim <= 0 || !out) return -1;
+    if (!(ext_floor > 0)) ext_floor = 1.0;
+    memset(out, 0, sizeof *out);
+    out->n = n; out->best = -1;
+    out->scores    = malloc((size_t)n * sizeof(double));
+    out->distances = malloc((size_t)n * sizeof(double));
+    out->rank      = malloc((size_t)n * sizeof(int));
+    if (!out->scores || !out->distances || !out->rank) { engram_reason_abduction_free(out); return -1; }
+
+    double best = -1; int bi = -1;
+    for (int i = 0; i < n; i++) {
+        out->rank[i] = i;
+        const GeoDescriptor* h = hypotheses[i];
+        GeoFit f;
+        if (!h || h->dim != dim || engram_reason_point_fit(h, obs, ext_floor, &f) != 0) {
+            out->scores[i] = 0.0; out->distances[i] = INFINITY;
+        } else {
+            out->scores[i] = f.score; out->distances[i] = f.distance;
+        }
+        if (bi < 0 || out->scores[i] > best) { best = out->scores[i]; bi = i; }
+    }
+    out->best = bi; out->best_score = (bi >= 0) ? out->scores[bi] : 0.0;
+
+    /* rank indices best→worst by score (insertion sort — n is small). */
+    for (int i = 1; i < n; i++) {
+        int key = out->rank[i]; int j = i - 1;
+        while (j >= 0 && out->scores[out->rank[j]] < out->scores[key]) { out->rank[j + 1] = out->rank[j]; j--; }
+        out->rank[j + 1] = key;
+    }
+    return 0;
+}
+void engram_reason_abduction_free(GeoAbduction* out) {
+    if (!out) return;
+    free(out->scores); free(out->distances); free(out->rank);
+    out->scores = NULL; out->distances = NULL; out->rank = NULL;
+}
+
+/* ═══════════════════════════════════════════════════════════════════ CAUSAL ══ */
+/* |cos| of two descriptors' centroids after removing confounder Z's subspace. */
+static double controlled_assoc(const GeoDescriptor* x, const GeoDescriptor* y,
+                               const GeoDescriptor* z) {
+    GeoResidual rx, ry; double c = 0;
+    int ox = engram_geo_subtract(x, z, 0, &rx);
+    int oy = engram_geo_subtract(y, z, 0, &ry);
+    if (ox == 0 && oy == 0 && rx.residual_centroid && ry.residual_centroid)
+        c = fabs(vcos(rx.residual_centroid, ry.residual_centroid, x->dim));
+    if (ox == 0) engram_geo_residual_free(&rx);
+    if (oy == 0) engram_geo_residual_free(&ry);
+    return c;
+}
+int engram_reason_causal(const GeoDescriptor* x, const GeoDescriptor* y,
+                         const GeoDescriptor* const* confounders, int n_conf,
+                         int64_t t_x, int64_t t_y,
+                         double drop_frac, GeoCausal* out) {
+    if (!x || !y || !out || !x->centroid || !y->centroid || x->dim != y->dim) return -1;
+    if (!(drop_frac > 0 && drop_frac < 1)) drop_frac = 0.5;
+    memset(out, 0, sizeof *out);
+    const double assoc_floor = 0.2;   /* below this = no meaningful association       */
+
+    out->assoc_raw = fabs(vcos(x->centroid, y->centroid, x->dim));
+    /* control for each confounder; the strongest single explainer wins (min assoc). */
+    double ctrl = out->assoc_raw;
+    for (int i = 0; i < n_conf; i++) {
+        if (!confounders[i]) continue;
+        double c = controlled_assoc(x, y, confounders[i]);
+        if (c < ctrl) ctrl = c;
+    }
+    out->assoc_controlled = ctrl;
+    out->temporal_dir = (t_x < t_y) ? 1 : (t_x > t_y) ? -1 : 0;
+
+    if (out->assoc_raw < assoc_floor) {
+        out->verdict = GEO_CAUSAL_NONE;
+    } else if (ctrl < (1.0 - drop_frac) * out->assoc_raw && ctrl < assoc_floor) {
+        out->verdict = GEO_CAUSAL_CONFOUNDED; out->confounded = 1;
+    } else if (out->temporal_dir != 0) {
+        out->verdict = GEO_CAUSAL_DIRECTED; out->strength = ctrl;
+    } else {
+        out->verdict = GEO_CAUSAL_NONE;      /* associated + robust but unorientable  */
+    }
+    return 0;
+}
+
+/* ═══════════════════════════════════════════════════════════════════ PLANNING ══ */
+int engram_reason_plan(const GeoDescriptor* const* nodes, int n,
+                       int start, int goal, double neighbor_radius,
+                       int use_wasserstein, GeoPlan* out) {
+    if (!nodes || n < 1 || !out) return -1;
+    if (start < 0 || start >= n || goal < 0 || goal >= n) return -1;
+    if (!(neighbor_radius > 0)) return -1;
+    memset(out, 0, sizeof *out);
+
+    /* dense edge weights (i<j symmetric); INFINITY = not adjacent. */
+    double* W = malloc((size_t)n * (size_t)n * sizeof(double));
+    if (!W) return -1;
+    for (int i = 0; i < n; i++) for (int j = 0; j < n; j++) W[(size_t)i * n + j] = (i == j) ? 0.0 : INFINITY;
+    for (int i = 0; i < n; i++) {
+        for (int j = i + 1; j < n; j++) {
+            GeoDistance d;
+            if (nodes[i] && nodes[j] && engram_geo_distance(nodes[i], nodes[j], &d) == 0) {
+                double w = use_wasserstein ? d.wasserstein2 : d.centroid_distance;
+                if (w <= neighbor_radius) { W[(size_t)i * n + j] = w; W[(size_t)j * n + i] = w; }
+            }
+        }
+    }
+
+    /* O(n²) Dijkstra. */
+    double* dist = malloc((size_t)n * sizeof(double));
+    int*    prev = malloc((size_t)n * sizeof(int));
+    char*   done = calloc((size_t)n, 1);
+    if (!dist || !prev || !done) { free(W); free(dist); free(prev); free(done); return -1; }
+    for (int i = 0; i < n; i++) { dist[i] = INFINITY; prev[i] = -1; }
+    dist[start] = 0;
+    for (int it = 0; it < n; it++) {
+        int u = -1; double bd = INFINITY;
+        for (int i = 0; i < n; i++) if (!done[i] && dist[i] < bd) { bd = dist[i]; u = i; }
+        if (u < 0) break;
+        done[u] = 1;
+        if (u == goal) break;
+        for (int v = 0; v < n; v++) {
+            double w = W[(size_t)u * n + v];
+            if (w < INFINITY && !done[v] && dist[u] + w < dist[v]) { dist[v] = dist[u] + w; prev[v] = u; }
+        }
+    }
+
+    if (dist[goal] < INFINITY) {
+        int len = 0; for (int v = goal; v != -1; v = prev[v]) len++;
+        out->path = malloc((size_t)len * sizeof(int));
+        if (out->path) {
+            out->path_len = len;
+            int idx = len - 1;
+            for (int v = goal; v != -1; v = prev[v]) out->path[idx--] = v;
+            out->total_cost = dist[goal];
+            out->reached = 1;
+        }
+    }
+    free(W); free(dist); free(prev); free(done);
+    return 0;
+}
+void engram_reason_plan_free(GeoPlan* out) {
+    if (!out) return;
+    free(out->path); out->path = NULL;
+}

lang/runtime/engram_reason.h

@@ -0,0 +1,161 @@
+/* engram_reason.h — the REASONING layer: compositions over the §5 geometry
+ * OPERATORS (engram_geometry.h). Where the operators are a relational ALGEBRA over
+ * neighborhood descriptors, these are reasoning MODES built by CHAINING that algebra:
+ *
+ *   ANALOGY   A:B :: C:?     — learn the A→B transform (Procrustes), apply to C.
+ *   INDUCTION {E_i} → rule   — pool example geometries; a generalizing structure
+ *                              + a membership test.
+ *   ABDUCTION x → best H     — the structure whose geometry best PLACES an
+ *                              observation in-distribution (inverse of prediction).
+ *   CAUSAL    x ? y | Z, t   — separate mere overlap (correlation) from directed
+ *                              influence (temporal precedence + association that
+ *                              SURVIVES controlling for confounders via subtract).
+ *   PLANNING  start → goal   — a trajectory (sequence of neighborhoods) through the
+ *                              manifold: shortest path over geo-distance edges.
+ *
+ * PURE + READ-ONLY (stdlib + libm only): every function consumes GeoDescriptor(s)
+ * (+ a few scalars / timestamps) and NEVER touches the store, index, or activation.
+ * All geometry is delegated to the engram_geo_* primitives; this file only composes.
+ *
+ * FRAME CONTRACT (inherited): descriptors passed together MUST share emb `dim` and
+ * `global_mean` frame — exactly the §5 operator contract. A function returns <0 on
+ * a dim/frame mismatch or bad argument.
+ */
+#ifndef ENGRAM_REASON_H
+#define ENGRAM_REASON_H
+
+#include <stdint.h>
+#include "engram_geometry.h"
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * SHARED PRIMITIVE — point-to-manifold FIT. How well does a single point x sit
+ * inside a neighborhood's ellipsoid?  Splits the residual (x − centroid) into:
+ *   - the IN-SUBSPACE part, scaled by each axis extent → a Mahalanobis distance
+ *     (how many "radii" out along the modeled directions), and
+ *   - the ORTHOGONAL part outside the retained axes → energy the model does not
+ *     explain at all (charged at the extent floor).
+ * This is the common engine under INDUCTION's membership test and ABDUCTION's
+ * explanation ranking. ext_floor (>0) guards zero-extent axes / the null model.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    double mahalanobis;    /* sqrt( Σ_k ((a_k·(x−c)) / max(ext_k,floor))² )         */
+    double ortho_residual; /* ‖(x−c) projected off the retained axes‖ (raw L2)      */
+    double distance;       /* sqrt( maha² + (ortho_residual/floor)² ) — full fit    */
+    double score;          /* 1 / (1 + distance²) ∈ (0,1]  (1 = dead-center)        */
+} GeoFit;
+int engram_reason_point_fit(const GeoDescriptor* g, const float* x,
+                            double ext_floor, GeoFit* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * ANALOGY — "A:B :: C:?". Learn the transform that carries A to B (orthogonal
+ * Procrustes rotation R between their principal frames + the residual translation),
+ * apply it to C, and return the mapped point + the nearest candidate neighborhood.
+ * Composes: engram_geo_analogy (R) + engram_geo_analogy_apply + engram_geo_distance.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    int      dim;
+    float*   mapped_point;    /* predicted D location = R·c_C + (c_B − R·c_A)  (owned)*/
+    double   analogy_residual;/* Procrustes ‖A−B R‖_F — frame-alignment quality      */
+    int      best;            /* index of nearest candidate to mapped_point, or −1   */
+    double   best_distance;   /* centroid L2 from mapped_point to the winner         */
+    int      n_candidates;
+    double*  distances;       /* centroid L2 mapped_point→candidate[i]         (owned)*/
+} GeoAnalogyResult;
+/* candidates may be NULL/0 (then best=−1 and only mapped_point is filled). */
+int engram_reason_analogy(const GeoDescriptor* A, const GeoDescriptor* B,
+                          const GeoDescriptor* C,
+                          const GeoDescriptor* const* candidates, int n_candidates,
+                          GeoAnalogyResult* out);
+void engram_reason_analogy_free(GeoAnalogyResult* r);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * INDUCTION — from a SET of example neighborhoods to the generalizing structure.
+ * Pools the examples (law-of-total-variance via engram_geo_combine, folded left to
+ * right) into a single "rule" descriptor whose top principal axes are the directions
+ * CONSISTENTLY present across the examples (the shared subspace surfaces as the
+ * dominant pooled axes; idiosyncratic per-example directions fall to the tail).
+ * The rule carries a membership test (point-to-manifold fit against the pool).
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    GeoDescriptor* rule;      /* induced generalizing geometry (owned; geo_free)     */
+    double         ext_floor; /* extent floor used by the membership test            */
+    int            n_examples;/* how many examples were pooled                       */
+} GeoInduction;
+/* top_axes<=0 → 8. ext_floor<=0 → derived from the pooled radius. */
+int engram_reason_induce(const GeoDescriptor* const* examples, int n_examples,
+                         int top_axes, double ext_floor, GeoInduction* out);
+/* Membership of a point in the induced rule ∈ (0,1] (the fit score). <0 on error. */
+double engram_reason_membership(const GeoInduction* ind, const float* x);
+void engram_reason_induction_free(GeoInduction* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * ABDUCTION — inference to the best explanation. Given an observation POINT, rank a
+ * set of candidate structures by how well each PLACES the observation in-distribution
+ * (min point-to-manifold distance = the structure that, if assumed, best accounts for
+ * the observation). The inverse of prediction.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    int     best;             /* index of best-explaining hypothesis, or −1          */
+    double  best_score;
+    int     n;
+    double* scores;           /* fit score per hypothesis (higher = better)   (owned)*/
+    double* distances;        /* explanation distance per hypothesis          (owned)*/
+    int*    rank;             /* hypothesis indices sorted best→worst          (owned)*/
+} GeoAbduction;
+int engram_reason_abduce(const float* obs, int dim,
+                         const GeoDescriptor* const* hypotheses, int n,
+                         double ext_floor, GeoAbduction* out);
+void engram_reason_abduction_free(GeoAbduction* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * CAUSAL — correlation vs causation. Over two variables' geometries (+ candidate
+ * confounders + temporal order), distinguish:
+ *   - mere co-occurrence / overlap (correlation), from
+ *   - directed influence: association that (a) SURVIVES controlling for confounders
+ *     (subtract each Z's subspace from both centroids, re-measure) and (b) is oriented
+ *     by temporal PRECEDENCE.
+ * Composes: centroid cosine (correlation) + engram_geo_subtract (control) + timestamps.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef enum {
+    GEO_CAUSAL_NONE       = 0,  /* no meaningful association                        */
+    GEO_CAUSAL_DIRECTED   = 1,  /* survives control + temporally ordered → cause→eff */
+    GEO_CAUSAL_CONFOUNDED = 2   /* correlated but association dies under control     */
+} GeoCausalVerdict;
+typedef struct {
+    double           assoc_raw;        /* |cos(c_x,c_y)| — the raw correlation       */
+    double           assoc_controlled; /* |cos| of residual centroids after control  */
+    int              temporal_dir;     /* +1 x→y, −1 y→x, 0 tie/unknown              */
+    GeoCausalVerdict verdict;
+    int              confounded;       /* 1 iff verdict==CONFOUNDED (the flag)       */
+    double           strength;         /* directed influence estimate ∈[0,1] (0 else)*/
+} GeoCausal;
+/* confounders may be NULL/0. t_x,t_y are comparable timestamps (any monotone unit);
+ * pass equal values for "unknown order". drop_frac∈(0,1): a controlled association
+ * below (1−drop_frac)·assoc_raw AND below an absolute floor ⇒ CONFOUNDED. */
+int engram_reason_causal(const GeoDescriptor* x, const GeoDescriptor* y,
+                         const GeoDescriptor* const* confounders, int n_conf,
+                         int64_t t_x, int64_t t_y,
+                         double drop_frac, GeoCausal* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * PLANNING — trajectory construction. Given a set of neighborhoods (manifold nodes),
+ * a start and a goal, build a PATH (sequence of intermediate neighborhoods) by
+ * shortest path over the graph whose edges connect neighborhoods within
+ * neighbor_radius, weighted by geo-distance. Long straight jumps are not edges, so
+ * the path follows the manifold's curvature through intermediates (a discrete geodesic).
+ * Composes: engram_geo_distance (edge weights) + Dijkstra.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    int*    path;             /* node indices start..goal (owned)                    */
+    int     path_len;
+    double  total_cost;       /* summed centroid-distance edge weights along path    */
+    int     reached;          /* 1 if goal reachable within neighbor_radius graph    */
+} GeoPlan;
+/* neighbor_radius>0: max centroid distance for two neighborhoods to be adjacent.
+ * Use "wasserstein"!=0 to weight edges by Wasserstein-2 instead of centroid L2. */
+int engram_reason_plan(const GeoDescriptor* const* nodes, int n,
+                       int start, int goal, double neighbor_radius,
+                       int use_wasserstein, GeoPlan* out);
+void engram_reason_plan_free(GeoPlan* out);
+
+#endif /* ENGRAM_REASON_H */

lang/runtime/engram_store.h

@@ -0,0 +1,330 @@
+/* engram_store.h — M1 of the engram tiered storage engine.
+ *
+ * The FINAL on-disk paged store format: superblock (+ mirror), slotted pages,
+ * self-describing TLV records, overflow chains, and two B+-tree indexes
+ * (primary id->loc, adjacency from_id/to_id->edge-locs) over a free-listed
+ * page file. See docs/architecture/design/engram-tiered-storage-engine.md §2.
+ *
+ * This is a self-contained module (plain C, standard libs only). It defines its
+ * own serializable views of a node/edge (StoreNode/StoreEdge) that mirror every
+ * persisted field of EngramNode/EngramEdge in el_runtime.c. M3 maps between the
+ * live runtime structs and these; M1 does not touch el_runtime.c.
+ *
+ * Format id: magic "ENGST01", format_version 1. This format is PERMANENT — the
+ * TLV record scheme means new fields never force a migration.
+ */
+#ifndef ENGRAM_STORE_H
+#define ENGRAM_STORE_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Fixed for the life of a store; recorded in the superblock. */
+#define STORE_PAGE_SIZE   16384u
+#define STORE_MAGIC       "ENGST01"      /* 7 chars + NUL stored in an 8-byte field */
+#define STORE_FORMAT_VERSION 1u
+
+/* Ring-buffer length for ACT-R base-level access timestamps.
+ * MUST equal ENGRAM_BLL_K in el_runtime.c (currently 10). Static-checked in .c. */
+#define STORE_BLL_K 10
+
+/* Page types (page header byte). */
+enum {
+    STORE_PT_NODE     = 1,
+    STORE_PT_EDGE     = 2,
+    STORE_PT_INDEX    = 3,
+    STORE_PT_OVERFLOW = 4,
+    STORE_PT_FREE     = 5
+};
+
+/* store_check flags. */
+#define STORE_CHECK_CRC 1u
+
+/* ── Serializable node view: every persisted EngramNode field ─────────────── */
+typedef struct StoreNode {
+    char*    id;
+    char*    content;
+    char*    node_type;
+    char*    label;
+    char*    tier;
+    char*    tags;
+    char*    metadata;
+    double   salience;
+    double   importance;
+    double   confidence;
+    double   temporal_decay_rate;
+    int64_t  activation_count;
+    int64_t  last_activated;
+    int64_t  created_at;
+    int64_t  updated_at;
+    double   background_activation;
+    double   working_memory_weight;
+    int32_t  suppression_count;
+    uint32_t layer_id;
+    int64_t  access_ts[STORE_BLL_K];
+    int32_t  access_head;
+    int32_t  access_filled;
+    double   wm_anchor;
+    float*   emb;        /* owned; NULL if not embedded */
+    int32_t  emb_dim;
+    /* Forward-compat: raw bytes of any TLV fields the reader did not recognise,
+     * concatenated verbatim ([tag][u32 len][bytes]...). Re-emitted on write so
+     * an old reader never drops a newer writer's fields. */
+    uint8_t* unknown;
+    size_t   unknown_len;
+    int      tombstoned; /* set by store_get_* if the located record is dead */
+    /* hebb_elig / hebb_elig_ts are DELIBERATELY NOT persisted (see EngramNode). */
+} StoreNode;
+
+/* ── Serializable edge view: every persisted EngramEdge field ─────────────── */
+typedef struct StoreEdge {
+    char*    id;
+    char*    from_id;
+    char*    to_id;
+    char*    relation;
+    char*    metadata;
+    double   weight;
+    double   hebb;
+    double   confidence;
+    int64_t  created_at;
+    int64_t  updated_at;
+    int64_t  last_fired;
+    int32_t  inhibitory;
+    uint32_t layer_id;
+    uint8_t* unknown;
+    size_t   unknown_len;
+    int      tombstoned;
+} StoreEdge;
+
+typedef struct EngramPagedStore EngramPagedStore;
+
+/* Lifecycle. */
+EngramPagedStore* store_create(const char* path);   /* fails if file exists */
+EngramPagedStore* store_open(const char* path);     /* recovers via mirror SB */
+int  store_close(EngramPagedStore* s);              /* syncs + frees */
+int  store_sync(EngramPagedStore* s);               /* fsync + rewrite both superblocks */
+
+/* Nodes. store_get_node returns 1 on hit (fills *out, caller store_node_free),
+ * 0 if absent or tombstoned, <0 on error. */
+int  store_put_node(EngramPagedStore* s, const StoreNode* n);
+int  store_get_node(EngramPagedStore* s, const char* id, StoreNode* out);
+int  store_tombstone(EngramPagedStore* s, const char* id);
+
+/* Edges. *out is malloc'd (store_edges_free); *n set to count. */
+int  store_put_edge(EngramPagedStore* s, const StoreEdge* e);
+int  store_get_edges_from(EngramPagedStore* s, const char* from_id, StoreEdge** out, size_t* n);
+int  store_get_edges_to(EngramPagedStore* s, const char* to_id, StoreEdge** out, size_t* n);
+
+/* Integrity: verify every page's crc (and both superblocks). Returns the number
+ * of corrupt pages (0 = clean), or <0 on I/O error. */
+int  store_check(EngramPagedStore* s, unsigned flags);
+
+/* Ownership helpers. */
+void store_node_free(StoreNode* n);
+void store_edge_free(StoreEdge* e);
+void store_edges_free(StoreEdge* arr, size_t n);
+
+/* Test-only hook (NOT a format property — B+-tree nodes are self-describing via
+ * their stored key count). Caps entries/keys per index node to force splits on
+ * small datasets. 0 = natural full-page fanout. */
+void store__set_btree_order(EngramPagedStore* s, int leaf_max, int internal_max);
+
+/* Introspection for tests/tools. */
+uint64_t store_page_count(const EngramPagedStore* s);
+
+/* ── M2: WAL + checkpoint + crash recovery + one-time legacy import ─────────────
+ *
+ * The durable engram is `neuron.egm` (paged) fronted by `neuron.wal`
+ * (append-only). A mutation is durable once its WAL record is fsync'd
+ * (group-commit). Pages are held write-back in RAM (no-steal) and flushed to the
+ * store only at a checkpoint, so the store file on disk always reflects a
+ * consistent point (`last_checkpoint_lsn`) and the WAL owns everything since.
+ * Recovery = open store, replay WAL forward, redo a record only where the target
+ * record's home page LSN < record LSN (idempotent). JSON is ONLY an import
+ * source / export artifact — never the ongoing store. */
+
+typedef enum { ENGRAM_WAL_ALWAYS = 0, ENGRAM_WAL_GROUP = 1, ENGRAM_WAL_OFF = 2 } EngramWalSync;
+
+/* Serializable layer-registry view (the `layers` array of the legacy snapshot). */
+typedef struct StoreLayer {
+    uint32_t layer_id;
+    char*    name;
+    uint32_t activation_priority;
+    int32_t  suppressible;
+    int32_t  transparent;
+    int32_t  injectable;
+    uint8_t* unknown;
+    size_t   unknown_len;
+    int      tombstoned;
+} StoreLayer;
+
+/* Boot the durable engram in `data_dir` (holds neuron.egm + neuron.wal). If the
+ * store is absent but a legacy snapshot.json exists, it is imported ONCE into a
+ * fresh store; thereafter the store is authoritative and JSON is never read again.
+ * On open, the WAL is replayed to recover any post-checkpoint mutations. */
+EngramPagedStore* engram_open(const char* data_dir);
+int  engram_close(EngramPagedStore* s);       /* checkpoint + close */
+
+/* Force a checkpoint: flush dirty pages → fsync store → advance checkpoint LSN →
+ * reclaim the WAL prefix. Also threshold-triggered automatically on the write path. */
+int  engram_checkpoint(EngramPagedStore* s);
+
+/* WAL commit policy. engram_open honours env ENGRAM_WAL_SYNC=always|group|off. */
+void engram_set_wal_sync(EngramPagedStore* s, EngramWalSync policy);
+
+/* Layer registry. */
+int  store_put_layer(EngramPagedStore* s, const StoreLayer* L);
+int  store_get_layer(EngramPagedStore* s, uint32_t layer_id, StoreLayer* out);
+int  store_del_layer(EngramPagedStore* s, uint32_t layer_id);
+int  store_list_layers(EngramPagedStore* s, StoreLayer** out, size_t* n);
+void store_layer_free(StoreLayer* L);
+void store_layers_free(StoreLayer* arr, size_t n);
+
+/* Edge lookup by id (for hebb updates + idempotency). 1 hit / 0 absent / <0 err. */
+int  store_get_edge(EngramPagedStore* s, const char* id, StoreEdge* out);
+
+/* HEBB batch: one WAL record updating hebb (+ last_fired) on a set of edges. */
+typedef struct StoreHebbDelta { const char* edge_id; double hebb; int64_t last_fired; } StoreHebbDelta;
+int  store_hebb_batch(EngramPagedStore* s, const StoreHebbDelta* d, size_t n);
+
+/* Supersede: logs the (old,new) pair and tombstones old_id at the store; the new
+ * node + `supersedes` edge are logged separately (neuron-layer immutability). */
+int  store_supersede(EngramPagedStore* s, const char* old_id, const char* new_id);
+
+/* Forget (GC): tombstone id at the store (hard-free deferred to compaction). */
+int  store_forget(EngramPagedStore* s, const char* id);
+
+/* ── M3: full live enumeration (for the CALLER's resident load + JSON export) ──
+ * Walk the whole store and invoke `cb` once per DISTINCT live node/edge with a
+ * borrowed view (the engine frees it after cb returns — the callback must copy
+ * anything it keeps). De-duplicated by id (canonical latest-live per id, matching
+ * point-read semantics). Returns the count emitted, or <0 on error. The engine
+ * hands out StoreNode/StoreEdge only — it never sees a soul struct (design §10). */
+typedef void (*StoreNodeScanCb)(const StoreNode* n, void* ctx);
+typedef void (*StoreEdgeScanCb)(const StoreEdge* e, void* ctx);
+int store_scan_nodes(EngramPagedStore* s, StoreNodeScanCb cb, void* ctx);
+int store_scan_edges(EngramPagedStore* s, StoreEdgeScanCb cb, void* ctx);
+
+/* Introspection / test hooks. */
+uint64_t engram_wal_next_lsn(const EngramPagedStore* s);
+uint64_t engram_last_checkpoint_lsn(const EngramPagedStore* s);
+
+/* ── M4: demand-paging buffer pool (additive residency; on-disk format UNCHANGED) ──
+ *
+ * The write-back, no-steal cache of M2 becomes a bounded, demand-paged buffer
+ * pool. A fixed frame budget (env ENGRAM_POOL_FRAMES; 0 = unlimited; default
+ * large ⇒ whole store resident ⇒ identical to Phase 1) keeps only hot pages in
+ * RAM; a page access that is not resident faults in from neuron.egm, and under
+ * pressure a CLEAN, unpinned frame is evicted (LRU). Dirty frames are never
+ * stolen (M2 no-steal / WAL durability), and superblocks + index root/interior
+ * pages are auto-pinned. Prefetch (env ENGRAM_PREFETCH) reads ahead on scans. */
+
+/* Pin / unpin an individual page (faults it in and keeps it resident until
+ * unpinned). Pin a hot layer's pages (WM/core) as a set. Idempotent counts. */
+int store_pin_page(EngramPagedStore* s, uint64_t page_id);
+int store_unpin_page(EngramPagedStore* s, uint64_t page_id);
+int store_pin_layer(EngramPagedStore* s, uint32_t layer);    /* returns #pages pinned */
+int store_unpin_layer(EngramPagedStore* s, uint32_t layer);
+
+/* Buffer-pool introspection. */
+typedef struct StorePoolStats {
+    size_t   cap;            /* frame budget (0 = unlimited) */
+    size_t   resident;       /* frames currently resident */
+    size_t   pinned;         /* frames that cannot be evicted (dirty/pinned/structural) */
+    size_t   dirty;          /* dirty (un-checkpointed) frames */
+    unsigned prefetch;       /* read-ahead window */
+    uint64_t hits, misses;   /* page_read cache hits / demand faults */
+    uint64_t evictions;      /* clean frames reclaimed */
+    uint64_t prefetch_reads; /* pages brought in by read-ahead */
+} StorePoolStats;
+void store_pool_stats(const EngramPagedStore* s, StorePoolStats* out);
+int  store_pool_resident(const EngramPagedStore* s, uint64_t page_id);
+
+/* Test hooks: set the frame budget / prefetch window at runtime (NOT format). */
+void store__set_pool_frames(EngramPagedStore* s, size_t frames);
+void store__set_prefetch(EngramPagedStore* s, unsigned window);
+
+/* Crash-test hooks (writes only under a throwaway dir).
+ *  store__crash          — abandon all RAM state without flush/fsync (power loss).
+ *  store__flush_pages    — pwrite dirty pages to disk WITHOUT a checkpoint (steal).
+ *  store__checkpoint_crashat — run checkpoint but stop (then power-loss) after
+ *                          `phase` (0..4); phase<0 = full checkpoint. */
+void store__crash(EngramPagedStore* s);
+int  store__flush_pages(EngramPagedStore* s);
+int  store__checkpoint_crashat(EngramPagedStore* s, int phase);
+
+/* ── M5: online compaction + background checkpointer (additive; format UNCHANGED) ──
+ *
+ * COMPACTION reclaims the space held by DEAD records — tombstoned nodes/edges
+ * (telemetry prune, forget), superseded ids, and the stale prior versions a
+ * re-put/hebb-batch leaves behind — plus the overflow pages they orphaned. It
+ * rewrites only the LIVE records (bit-exact) into a fresh, densely packed image
+ * with fresh id + adjacency indexes, then commits the swap atomically, so the
+ * .egm file physically SHRINKS and the freed pages are reclaimed. Crash-safe:
+ * a crash at any instant recovers to either the pre- or the post-compaction
+ * store, never a corrupt mix (atomic rename is the commit point). It cooperates
+ * with the M4 pool (no-steal, pins) by building into a separate store whose own
+ * pool honours ENGRAM_POOL_FRAMES, then INVALIDATING every frame of the live
+ * pool so no stale frame survives for a relocated page.
+ *
+ * Requires a quiesce point: store_compact performs a checkpoint (or sync) at
+ * entry, so it is called between mutations, not concurrently with one. */
+int store_compact(EngramPagedStore* s);
+
+/* Test hook: run compaction but stop (then power-loss) after `phase`:
+ *   0 = after the entry checkpoint, before building  (→ recovers pre-compaction)
+ *   1 = after building+fsync the new image, before rename (→ pre-compaction)
+ *   2 = after the atomic rename, before reopening RAM state (→ post-compaction)
+ *   phase<0 = full compaction. Frees `s` on a crash phase (like the checkpoint hook). */
+int store__compact_crashat(EngramPagedStore* s, int phase);
+
+/* BACKGROUND CHECKPOINTER policy. A checkpoint fires automatically on the write
+ * path when ANY armed trigger trips, reclaiming the WAL prefix without an explicit
+ * engram_checkpoint. 0 disables that trigger. Same checkpoint semantics as M2.
+ *   ops         — mutations since last checkpoint (default 100000)
+ *   dirty_pages — dirty (un-checkpointed) pool frames
+ *   wal_bytes   — bytes appended to the WAL since it was last reclaimed
+ *   interval_ms — wall-clock ms since the last checkpoint (checked on writes) */
+void store_set_checkpoint_policy(EngramPagedStore* s, uint64_t ops,
+                                 size_t dirty_pages, uint64_t wal_bytes,
+                                 long long interval_ms);
+
+/* Introspection: number of pages currently on the free-list. */
+uint64_t store_free_page_count(const EngramPagedStore* s);
+
+/* ── CCR §4 managed-memory layer (write-barrier + minor GC + observability) ─────
+ *
+ * All flag-gated at store open (default OFF ⇒ byte-for-byte legacy behaviour):
+ *   ENGRAM_WRITE_BARRIER=1  arm the durable-content write-barrier: a store_put_node
+ *       whose DURABLE fields (content/type/label/tier/tags/metadata/importance/
+ *       confidence/decay/layer/emb) are byte-identical to the last persisted copy
+ *       is SKIPPED entirely — no LSN, no WAL, no record, no tombstone. This kills
+ *       the ~99.78% checkpoint full-walk garbage at the source (ephemeral
+ *       activation/WM state is intentionally not re-persisted on think-only cycles).
+ *   ENGRAM_GC=1  (a) node re-puts supersede prior copies (mark DEAD, as edges do)
+ *       so stale versions become reclaimable, and (b) a MINOR GC runs at the head
+ *       of every checkpoint, returning whole dead NODE/EDGE pages to the free list.
+ * The MAJOR GC is the existing merge-safe store_compact (schedule on a dead-ratio
+ * threshold from the soul). */
+
+/* Run one minor-GC sweep now: reclaim whole dead NODE/EDGE pages to the free list.
+ * Returns the number of pages reclaimed (>=0). Safe to call between mutations;
+ * automatically invoked at each checkpoint when ENGRAM_GC is armed. */
+int store_minor_gc(EngramPagedStore* s);
+
+/* GC / cache observability census (CCR §4.4). Page tallies are point-in-time;
+ * the *_writes / *_skips / *_runs / *_reclaimed counters are cumulative since open. */
+typedef struct StoreGcStats {
+    uint64_t node_pages, edge_pages, index_pages, overflow_pages, free_pages;
+    uint64_t live_nodes, live_edges;   /* live slots on NODE / EDGE pages */
+    uint64_t dead_slots;               /* superseded/tombstoned slots awaiting reclaim */
+    uint64_t live_bytes, dead_bytes;   /* on-page record bytes, live vs dead */
+    uint64_t durable_writes;           /* node puts that actually appended a record */
+    uint64_t barrier_skips;            /* node puts skipped by the write-barrier */
+    uint64_t minor_gc_runs;            /* minor-GC invocations */
+    uint64_t pages_reclaimed;          /* whole pages returned to the free list by minor GC */
+    int      barrier_on, gc_on;        /* which gates are armed */
+} StoreGcStats;
+void store_gc_stats(EngramPagedStore* s, StoreGcStats* out);
+
+#endif /* ENGRAM_STORE_H */

lang/runtime/engram_verify.c

@@ -0,0 +1,157 @@
+/* engram_verify.c — the VERIFIER layer. Pure compositions over engram_reason.h +
+ * engram_geometry.h. stdlib + libm only; READ-ONLY over its inputs; touches no
+ * store/index/activation. See engram_verify.h for the design and the frame contract. */
+#include "engram_verify.h"
+#include <stdlib.h>
+#include <string.h>
+#include <math.h>
+
+/* ── small float-vector helpers (mirror engram_reason.c) ────────────────────── */
+static double vdot(const float* a, const float* b, int dim) {
+    double s = 0; for (int i = 0; i < dim; i++) s += (double)a[i] * (double)b[i]; return s;
+}
+static double l2(const float* a, const float* b, int dim) {
+    double s = 0; for (int i = 0; i < dim; i++) { double d = (double)a[i] - (double)b[i]; s += d * d; }
+    return sqrt(s);
+}
+
+/* ═══════════════════════════════════════════════════════ GROUNDING ══════════ */
+int engram_verify_grounding(const float* claim, int dim,
+                            const GeoDescriptor* const* evidence, int n_evidence,
+                            double ext_floor, double ground_threshold,
+                            GeoGrounding* out) {
+    if (!claim || dim <= 0 || !evidence || n_evidence < 1 || !out) return -1;
+    if (!(ext_floor > 0)) ext_floor = 1.0;
+    if (!(ground_threshold > 0 && ground_threshold < 1)) ground_threshold = 0.5;
+    memset(out, 0, sizeof *out);
+    out->n_evidence = n_evidence;
+    out->best = -1;
+    out->nearest_centroid_l2 = INFINITY;
+    out->scores = malloc((size_t)n_evidence * sizeof(double));
+    if (!out->scores) return -1;
+
+    double best = -1;
+    for (int i = 0; i < n_evidence; i++) {
+        const GeoDescriptor* e = evidence[i];
+        GeoFit f;
+        if (!e || e->dim != dim || !e->centroid ||
+            engram_reason_point_fit(e, claim, ext_floor, &f) != 0) {
+            out->scores[i] = 0.0;
+            continue;
+        }
+        out->scores[i] = f.score;
+        double cl2 = l2(claim, e->centroid, dim);
+        if (cl2 < out->nearest_centroid_l2) out->nearest_centroid_l2 = cl2;
+        if (out->best < 0 || f.score > best) {
+            best = f.score;
+            out->best = i;
+            out->grounding = f.score;
+            out->best_distance = f.distance;
+            out->best_ortho = f.ortho_residual;
+        }
+    }
+    if (out->best < 0) { out->grounding = 0.0; out->best_distance = INFINITY; }
+    out->grounded = (out->grounding >= ground_threshold) ? 1 : 0;
+    return 0;
+}
+void engram_verify_grounding_free(GeoGrounding* out) {
+    if (!out) return;
+    free(out->scores); out->scores = NULL;
+}
+
+/* ═══════════════════════════════════════════════════════ CONSISTENCY ════════ */
+int engram_verify_consistency(const float* claim, int dim,
+                              const GeoDescriptor* context,
+                              const GeoDescriptor* pole_pos, const GeoDescriptor* pole_neg,
+                              const GeoDescriptor* forbidden,
+                              double ext_floor, double deadzone_frac,
+                              double forbidden_thresh, double max_distance,
+                              GeoConsistency* out) {
+    if (!claim || dim <= 0 || !out) return -1;
+    if (!(ext_floor > 0)) ext_floor = 1.0;
+    if (!(deadzone_frac >= 0 && deadzone_frac < 1)) deadzone_frac = 0.10;
+    if (!(forbidden_thresh > 0 && forbidden_thresh < 1)) forbidden_thresh = 0.5;
+    memset(out, 0, sizeof *out);
+    out->verdict = GEO_CONSIST_OK;
+    out->consistency = 1.0;
+
+    int do_polarity = (pole_pos && pole_neg);
+    int do_distance = (max_distance > 0);
+    if ((do_polarity || do_distance) &&
+        (!context || context->dim != dim || !context->centroid)) return -1;
+    if (do_polarity && (pole_pos->dim != dim || pole_neg->dim != dim ||
+                        !pole_pos->centroid || !pole_neg->centroid)) return -1;
+    if (forbidden && (forbidden->dim != dim || !forbidden->centroid)) return -1;
+
+    double pol_score = 1.0, geo_score = 1.0;
+
+    /* ── (a) POLARITY / negation inversion ─────────────────────────────────── */
+    if (do_polarity) {
+        /* axis p = (c_pos − c_neg); midpoint o = ½(c_pos + c_neg). */
+        float* p = malloc((size_t)dim * sizeof(float));
+        float* o = malloc((size_t)dim * sizeof(float));
+        if (!p || !o) { free(p); free(o); return -1; }
+        double pn2 = 0;
+        for (int i = 0; i < dim; i++) {
+            double dpos = (double)pole_pos->centroid[i], dneg = (double)pole_neg->centroid[i];
+            p[i] = (float)(dpos - dneg);
+            o[i] = (float)(0.5 * (dpos + dneg));
+            pn2 += (dpos - dneg) * (dpos - dneg);
+        }
+        double pn = sqrt(pn2);
+        out->polarity_separation = 0.5 * pn;
+        if (pn > 1e-12) {
+            /* signed positions along the axis (projection of (x − o) onto unit p). */
+            float* cdo = malloc((size_t)dim * sizeof(float));  /* claim − o   */
+            float* rdo = malloc((size_t)dim * sizeof(float));  /* context − o */
+            if (!cdo || !rdo) { free(p); free(o); free(cdo); free(rdo); return -1; }
+            for (int i = 0; i < dim; i++) {
+                cdo[i] = (float)((double)claim[i] - (double)o[i]);
+                rdo[i] = (float)((double)context->centroid[i] - (double)o[i]);
+            }
+            double claim_side = vdot(cdo, p, dim) / pn;      /* units: emb-space length */
+            double ref_side   = vdot(rdo, p, dim) / pn;
+            out->polarity_claim = claim_side;
+            out->polarity_reference = ref_side;
+            double dz = deadzone_frac * out->polarity_separation;  /* neutral band     */
+            if (fabs(claim_side) > dz && fabs(ref_side) > dz &&
+                (claim_side > 0) != (ref_side > 0)) {
+                out->inverted = 1;
+                pol_score = 0.0;                 /* opposite poles ⇒ zero consistency   */
+            } else if (fabs(claim_side) <= dz || fabs(ref_side) <= dz) {
+                pol_score = 0.5;                 /* neutral / undecided                 */
+            } else {
+                pol_score = 1.0;                 /* same pole ⇒ consistent              */
+            }
+            free(cdo); free(rdo);
+        }
+        free(p); free(o);
+    }
+
+    /* ── (b) GEOMETRIC contradiction ───────────────────────────────────────── */
+    if (forbidden) {
+        GeoFit f;
+        if (engram_reason_point_fit(forbidden, claim, ext_floor, &f) == 0) {
+            out->forbidden_fit = f.score;
+            if (f.score >= forbidden_thresh) {
+                out->geo_violation = 1;
+                double g = 1.0 - f.score; if (g < 0) g = 0;
+                if (g < geo_score) geo_score = g;
+            }
+        }
+    }
+    if (do_distance) {
+        out->context_distance = l2(claim, context->centroid, dim);
+        if (out->context_distance > max_distance) {
+            out->geo_violation = 1;
+            geo_score = 0.0;
+        }
+    }
+
+    /* ── verdict + scalar (polarity is the headline; both flags stay visible) ─ */
+    out->consistency = (pol_score < geo_score) ? pol_score : geo_score;
+    if (out->inverted)          out->verdict = GEO_CONSIST_POLARITY;
+    else if (out->geo_violation) out->verdict = GEO_CONSIST_GEOMETRIC;
+    else                         out->verdict = GEO_CONSIST_OK;
+    return 0;
+}

lang/runtime/engram_verify.h

@@ -0,0 +1,118 @@
+/* engram_verify.h — the VERIFIER layer: GROUNDING + CONSISTENCY over the live
+ * geometry (engram_geometry.h) and reasoning (engram_reason.h) operators.
+ *
+ * The geometry PROPOSES (cheap, creative, sometimes wrong); the verifier DISPOSES.
+ * This layer catches the class of failure a grammar check never sees: a fluent,
+ * confident, WRONG output — the "plausible lie". The motivating case: a translation
+ * that DELETED a negation so "you never fought" became "you argued" — reassurance
+ * inverted into accusation, grammatical and invisible, catchable ONLY by the geometry.
+ *
+ *   GROUNDING   claim → is there ANY real structure that supports it, or is it
+ *               floating free of the manifold?  (anti-hallucination gate)
+ *   CONSISTENCY claim → does it CONTRADICT the established structure?  Two catches:
+ *               (a) POLARITY: the claim lands on the OPPOSITE side of a negation
+ *                   axis from the grounded truth  (the reassurance→accusation catch),
+ *               (b) GEOMETRIC: the claim sits inside a region it must be far from,
+ *                   or violates a max-distance constraint to its context.
+ *
+ * PURE + READ-ONLY (stdlib + libm only): every function consumes a claim POINT
+ * (float* in R^dim) plus GeoDescriptor(s), and NEVER touches the store, index, or
+ * activation. All geometry is delegated to engram_reason_point_fit / engram_geo_*;
+ * this file only composes and applies thresholds.
+ *
+ * FRAME CONTRACT (inherited): the claim point and every descriptor passed together
+ * MUST share emb `dim` and the same `global_mean` frame — exactly the §5 operator
+ * contract. A function returns <0 on a dim/frame mismatch or bad argument.
+ */
+#ifndef ENGRAM_VERIFY_H
+#define ENGRAM_VERIFY_H
+
+#include "engram_geometry.h"
+#include "engram_reason.h"
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * GROUNDING — anti-hallucination. Score how well a claimed POINT is supported by
+ * the ACTUAL structure: fit the claim against every real evidence neighborhood
+ * (engram_reason_point_fit → in-distribution Mahalanobis + off-model orthogonal
+ * residual) and take the BEST supporter. A claim that sits inside real structure
+ * scores high (grounded); a claim floating far from every neighborhood scores low
+ * on all of them → flagged UNGROUNDED (a hallucination).
+ *
+ * This is an ABSOLUTE-THRESHOLD gate, deliberately distinct from ABDUCTION (which
+ * always RANKS and picks a winner among competing hypotheses): grounding asks the
+ * prior question — "is there any real support at all?" — and is allowed to answer no.
+ * The off-model `ortho_residual` is the sharpest hallucination signal: energy in a
+ * direction the manifold does not even span.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef struct {
+    double  grounding;          /* ∈[0,1]: overall support = best fit score           */
+    int     grounded;           /* 1 iff grounding >= ground_threshold                */
+    int     best;               /* index of best-supporting evidence structure, or −1 */
+    double  best_distance;      /* full point-to-manifold distance to the best        */
+    double  best_ortho;         /* off-model orthogonal residual of the best fit      */
+    double  nearest_centroid_l2;/* raw L2 to the nearest evidence centroid (coarse)   */
+    int     n_evidence;
+    double* scores;             /* per-evidence fit score, higher = better     (owned)*/
+} GeoGrounding;
+/* ext_floor>0 guards zero-extent axes (default 1.0). ground_threshold∈(0,1): the
+ * minimum best-fit score to call the claim grounded (default 0.5). */
+int  engram_verify_grounding(const float* claim, int dim,
+                             const GeoDescriptor* const* evidence, int n_evidence,
+                             double ext_floor, double ground_threshold,
+                             GeoGrounding* out);
+void engram_verify_grounding_free(GeoGrounding* out);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+ * CONSISTENCY — contradiction detection. Does the claim contradict the established
+ * structure?  Two independent sub-checks (either can fire; both flags are reported):
+ *
+ * (a) POLARITY / negation inversion.  A polarity axis p is defined by two REAL
+ *     poles — pole_pos (asserts X) and pole_neg (asserts ¬X):
+ *         p = (c_pos − c_neg)/‖·‖ ,  midpoint o = ½(c_pos + c_neg).
+ *     The claim's side  = p·(claim − o);  the reference's side = p·(c_context − o).
+ *     If the two sides have OPPOSITE sign AND both clear the neutral deadzone, the
+ *     claim asserts the polarity opposite to the grounded truth → INVERSION flagged.
+ *     This is the "you never fought"→"you argued" catch: the truth ("never fought")
+ *     sits on the negate pole, the claim ("argued") on the affirm pole → opposite
+ *     sides → flagged, though every word is grammatical.
+ *
+ * (b) GEOMETRIC contradiction.  The claim sits INSIDE a `forbidden` region it must
+ *     be far from (point_fit score to forbidden ≥ forbidden_thresh), OR it violates
+ *     a max-distance constraint to its context centroid (L2 > max_distance).
+ *
+ * pole_pos/pole_neg may both be NULL to skip the polarity check; forbidden may be
+ * NULL and max_distance≤0 to skip the geometric check. `context` (the grounded truth
+ * region) is required whenever polarity or the distance constraint is used.
+ * ═══════════════════════════════════════════════════════════════════════════ */
+typedef enum {
+    GEO_CONSIST_OK        = 0,  /* consistent with context                            */
+    GEO_CONSIST_POLARITY  = 1,  /* polarity/negation inversion (asserts ¬X where X)    */
+    GEO_CONSIST_GEOMETRIC = 2   /* geometric contradiction (in forbidden / too far)    */
+} GeoConsistencyVerdict;
+typedef struct {
+    GeoConsistencyVerdict verdict;   /* headline (polarity takes precedence)          */
+    double consistency;              /* ∈[0,1]: min over the checks (1 = fully consistent)*/
+    /* polarity sub-check */
+    int    inverted;                 /* 1 iff a polarity inversion was detected        */
+    double polarity_claim;           /* p·(claim − o)     (signed position on the axis)*/
+    double polarity_reference;       /* p·(c_context − o) (the grounded truth's side)  */
+    double polarity_separation;      /* ½‖c_pos − c_neg‖  (the axis half-length / scale)*/
+    /* geometric sub-check */
+    int    geo_violation;            /* 1 iff a geometric contradiction was detected   */
+    double forbidden_fit;            /* claim's point_fit score to the forbidden region*/
+    double context_distance;         /* L2(claim, c_context)                           */
+} GeoConsistency;
+/* ext_floor>0 (default 1.0). deadzone_frac∈[0,1): a polarity side within
+ * deadzone_frac·separation of the midpoint is "neutral" and never triggers inversion
+ * (default 0.10). forbidden_thresh∈(0,1): fit-to-forbidden at/above which the claim
+ * counts as inside the forbidden region (default 0.5). max_distance>0 enables the
+ * distance constraint; ≤0 disables it. */
+int engram_verify_consistency(const float* claim, int dim,
+                              const GeoDescriptor* context,
+                              const GeoDescriptor* pole_pos, const GeoDescriptor* pole_neg,
+                              const GeoDescriptor* forbidden,
+                              double ext_floor, double deadzone_frac,
+                              double forbidden_thresh, double max_distance,
+                              GeoConsistency* out);
+
+#endif /* ENGRAM_VERIFY_H */

lang/runtime/engram_vindex.c

@@ -0,0 +1,689 @@
+/* engram_vindex.c — HNSW ANN index over f32 embedding vectors (design §9 M8).
+ *
+ * Self-contained: plain C11, stdlib + libm (-lm for sqrtf/logf) only. No
+ * dependency on el_runtime; the store is read via its PERMANENT on-disk format
+ * (design §2.4), decoded read-only here so engram_store.{c,h} stay untouched.
+ *
+ * Algorithm: Malkov & Yashunin, "Efficient and robust approximate nearest
+ * neighbor search using Hierarchical Navigable Small World graphs" (2016).
+ *   - multi-layer graph; level ~ Exp(1/ln M), assigned by a per-node seeded PRNG
+ *     (deterministic: seed = FIXED_SEED ^ node_ordinal) so a rebuild is bit-for-
+ *     bit reproducible regardless of wall-clock or global rand() state.
+ *   - greedy descent through upper layers to an entry point, then an ef-bounded
+ *     best-first search at each layer (Algorithm 2).
+ *   - neighbour selection by the diversity heuristic (Algorithm 4), not plain
+ *     k-nearest, with keep-pruned backfill for connectivity.
+ *   - bidirectional links; a neighbour whose degree exceeds M (2M on layer 0) is
+ *     re-pruned with the same heuristic.
+ *
+ * Metric: vectors are L2-normalised on entry, so cosine similarity == dot
+ * product; distance = 1 - dot (in [0,2], smaller == nearer). Deterministic tie-
+ * breaks are by element index so results are stable across identical builds.
+ */
+#include "engram_vindex.h"
+
+#include <stdlib.h>
+#include <string.h>
+#include <math.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+
+/* Deterministic PRNG seed base (fixed constant — never wall-clock/rand). */
+#define VINDEX_FIXED_SEED 0x9E3779B97F4A7C15ULL
+
+/* ── deterministic PRNG (splitmix64) ──────────────────────────────────────── */
+static inline uint64_t splitmix64(uint64_t* s){
+    uint64_t z = (*s += 0x9E3779B97F4A7C15ULL);
+    z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
+    z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
+    return z ^ (z >> 31);
+}
+/* Uniform double in (0,1]. */
+static inline double sm_uniform(uint64_t* s){
+    /* 53-bit mantissa; +1 keeps it in (0,1] so log() never sees 0. */
+    return ((double)((splitmix64(s) >> 11) + 1)) * (1.0 / 9007199254740993.0);
+}
+
+/* ── element + index structures ───────────────────────────────────────────── */
+typedef struct {
+    int   count;
+    int   cap;
+    int*  ids;      /* neighbour element indices */
+} NeighList;
+
+typedef struct {
+    uint64_t   node_id;
+    int        level;       /* top layer this element appears on (>=0) */
+    float*     vec;         /* dim floats, L2-normalised */
+    NeighList* links;       /* level+1 lists; links[l] = neighbours at layer l */
+} Elem;
+
+struct VIndex {
+    int      dim;
+    int      M;             /* max neighbours per node, upper layers */
+    int      M0;            /* == 2*M, layer 0 */
+    int      ef_construction;
+    double   mL;            /* level normaliser = 1/ln(M) */
+
+    Elem*    elems;
+    size_t   n;
+    size_t   cap;
+
+    int      entry;         /* entry-point element index, -1 if empty */
+    int      max_level;     /* current top layer */
+
+    /* scratch: version-stamped visited set (O(1) reset). */
+    uint32_t* visited;
+    uint32_t  visit_epoch;
+    size_t    visited_cap;
+};
+
+/* ── small helpers ────────────────────────────────────────────────────────── */
+static float* vec_normalise_copy(const float* v, int dim){
+    float* out = (float*)malloc((size_t)dim * sizeof(float));
+    if (!out) return NULL;
+    double ss = 0.0;
+    for (int i=0;i<dim;i++) ss += (double)v[i]*(double)v[i];
+    if (ss > 0.0){
+        float inv = (float)(1.0 / sqrt(ss));
+        for (int i=0;i<dim;i++) out[i] = v[i]*inv;
+    } else {
+        for (int i=0;i<dim;i++) out[i] = 0.0f;   /* zero vector stays zero */
+    }
+    return out;
+}
+/* Cosine distance between two normalised vectors: 1 - dot. In [0,2].
+ * Float accumulation in 4 lanes so the compiler auto-vectorises the hot path
+ * (this is the dominant cost of both build and search). */
+static float vdist(const VIndex* ix, const float* a, const float* b){
+    int dim = ix->dim;
+    float s0=0,s1=0,s2=0,s3=0;
+    int i=0;
+    for (; i+4<=dim; i+=4){
+        s0 += a[i]*b[i]; s1 += a[i+1]*b[i+1];
+        s2 += a[i+2]*b[i+2]; s3 += a[i+3]*b[i+3];
+    }
+    float dot = (s0+s1)+(s2+s3);
+    for (; i<dim; i++) dot += a[i]*b[i];
+    return 1.0f - dot;
+}
+
+static int nl_push(NeighList* nl, int id){
+    if (nl->count == nl->cap){
+        int nc = nl->cap ? nl->cap*2 : 4;
+        int* np = (int*)realloc(nl->ids, (size_t)nc*sizeof(int));
+        if (!np) return -1;
+        nl->ids = np; nl->cap = nc;
+    }
+    nl->ids[nl->count++] = id;
+    return 0;
+}
+
+/* ── binary heaps over (dist,elem) pairs ──────────────────────────────────── */
+typedef struct { float d; int e; } Pair;
+typedef struct { Pair* a; int n, cap; } Heap;
+
+static int heap_reserve(Heap* h, int need){
+    if (need <= h->cap) return 0;
+    int nc = h->cap ? h->cap*2 : 16;
+    while (nc < need) nc *= 2;
+    Pair* na = (Pair*)realloc(h->a, (size_t)nc*sizeof(Pair));
+    if (!na) return -1;
+    h->a = na; h->cap = nc; return 0;
+}
+/* Order predicate: for a MAX-heap on distance, "higher priority" = larger dist;
+ * ties broken by larger element index (deterministic + stable). is_max selects. */
+static inline int pair_before(Pair x, Pair y, int is_max){
+    if (x.d != y.d) return is_max ? (x.d > y.d) : (x.d < y.d);
+    return is_max ? (x.e > y.e) : (x.e < y.e);
+}
+static int heap_push(Heap* h, Pair v, int is_max){
+    if (heap_reserve(h, h->n+1)) return -1;
+    int i = h->n++;
+    h->a[i] = v;
+    while (i > 0){
+        int p = (i-1)/2;
+        if (pair_before(h->a[i], h->a[p], is_max)){
+            Pair t=h->a[i]; h->a[i]=h->a[p]; h->a[p]=t; i=p;
+        } else break;
+    }
+    return 0;
+}
+static Pair heap_pop(Heap* h, int is_max){
+    Pair top = h->a[0];
+    h->a[0] = h->a[--h->n];
+    int i = 0;
+    for (;;){
+        int l=2*i+1, r=2*i+2, best=i;
+        if (l<h->n && pair_before(h->a[l], h->a[best], is_max)) best=l;
+        if (r<h->n && pair_before(h->a[r], h->a[best], is_max)) best=r;
+        if (best==i) break;
+        Pair t=h->a[i]; h->a[i]=h->a[best]; h->a[best]=t; i=best;
+    }
+    return top;
+}
+
+/* ── visited set ──────────────────────────────────────────────────────────── */
+static int visited_ensure(VIndex* ix){
+    if (ix->visited_cap >= ix->cap && ix->visited) return 0;
+    size_t nc = ix->cap ? ix->cap : 16;
+    uint32_t* nv = (uint32_t*)realloc(ix->visited, nc*sizeof(uint32_t));
+    if (!nv) return -1;
+    if (nc > ix->visited_cap) memset(nv + ix->visited_cap, 0, (nc-ix->visited_cap)*sizeof(uint32_t));
+    ix->visited = nv; ix->visited_cap = nc;
+    return 0;
+}
+static inline void visited_reset(VIndex* ix){
+    if (++ix->visit_epoch == 0){                 /* wrapped: clear all */
+        memset(ix->visited, 0, ix->visited_cap*sizeof(uint32_t));
+        ix->visit_epoch = 1;
+    }
+}
+static inline int is_visited(VIndex* ix, int e){ return ix->visited[e]==ix->visit_epoch; }
+static inline void mark_visited(VIndex* ix, int e){ ix->visited[e]=ix->visit_epoch; }
+
+/* ── search one layer (Algorithm 2): best-first, ef-bounded ───────────────── */
+/* Returns results as an unsorted Heap (max-heap on distance, size<=ef). Caller
+ * owns res->a. `q` is a normalised query. */
+static int search_layer(VIndex* ix, const float* q, const int* eps, int neps,
+                        int ef, int layer, Heap* res /*out, max-heap*/){
+    Heap cand = {0,0,0};                          /* min-heap: nearest to expand */
+    res->a=NULL; res->n=0; res->cap=0;
+    visited_reset(ix);
+    for (int i=0;i<neps;i++){
+        int e = eps[i];
+        if (is_visited(ix,e)) continue;
+        mark_visited(ix,e);
+        float d = vdist(ix, q, ix->elems[e].vec);
+        Pair p = { d, e };
+        if (heap_push(&cand,p,0) || heap_push(res,p,1)){ free(cand.a); return -1; }
+    }
+    while (res->n > ef) heap_pop(res,1);          /* trim to ef */
+
+    while (cand.n > 0){
+        Pair c = heap_pop(&cand,0);
+        float worst = res->a[0].d;                /* farthest kept result */
+        if (res->n >= ef && c.d > worst) break;
+        Elem* ce = &ix->elems[c.e];
+        if (layer <= ce->level){
+            NeighList* nl = &ce->links[layer];
+            for (int i=0;i<nl->count;i++){
+                int e = nl->ids[i];
+                if (is_visited(ix,e)) continue;
+                mark_visited(ix,e);
+                float d = vdist(ix, q, ix->elems[e].vec);
+                if (res->n < ef || d < res->a[0].d){
+                    Pair p = { d, e };
+                    if (heap_push(&cand,p,0) || heap_push(res,p,1)){ free(cand.a); return -1; }
+                    if (res->n > ef) heap_pop(res,1);
+                }
+            }
+        }
+    }
+    free(cand.a);
+    return 0;
+}
+
+/* ── neighbour selection heuristic (Algorithm 4) ──────────────────────────── */
+/* From candidate pairs W (any order), pick up to M diverse neighbours of q.
+ * Keep c only if it is nearer to q than to every already-chosen neighbour;
+ * backfill from the pruned set (nearest first) to reach M for connectivity.
+ * Writes chosen element indices into out[], returns the count. */
+static int select_neighbors(VIndex* ix, const float* q, Pair* W, int nW, int M, int* out){
+    (void)q;   /* q's distances are precomputed in W[].d; kept for call-site clarity */
+    /* sort W ascending by (dist,elem) — deterministic. */
+    for (int i=1;i<nW;i++){                        /* insertion sort (nW small) */
+        Pair key=W[i]; int j=i-1;
+        while (j>=0 && !pair_before(W[j],key,0)){ W[j+1]=W[j]; j--; }
+        W[j+1]=key;
+    }
+    int nout = 0;
+    Pair* pruned = (Pair*)malloc((size_t)(nW?nW:1)*sizeof(Pair));
+    int npr = 0;
+    if (!pruned) return -1;
+    for (int i=0;i<nW && nout<M;i++){
+        int good = 1;
+        for (int j=0;j<nout;j++){
+            float d = vdist(ix, ix->elems[W[i].e].vec, ix->elems[out[j]].vec);
+            if (d < W[i].d){ good = 0; break; }    /* nearer an existing pick → drop */
+        }
+        if (good) out[nout++] = W[i].e;
+        else pruned[npr++] = W[i];
+    }
+    for (int i=0;i<npr && nout<M;i++) out[nout++] = pruned[i].e;  /* keep-pruned backfill */
+    free(pruned);
+    return nout;
+}
+
+/* Re-prune a neighbour's over-full adjacency list back to `Mmax`. */
+static void prune_links(VIndex* ix, int e, int layer, int Mmax){
+    NeighList* nl = &ix->elems[e].links[layer];
+    if (nl->count <= Mmax) return;
+    const float* base = ix->elems[e].vec;
+    Pair* W = (Pair*)malloc((size_t)nl->count*sizeof(Pair));
+    if (!W) return;
+    int nW = nl->count;
+    for (int i=0;i<nW;i++) W[i] = (Pair){ vdist(ix, base, ix->elems[nl->ids[i]].vec), nl->ids[i] };
+    int* keep = (int*)malloc((size_t)nW*sizeof(int));
+    if (!keep){ free(W); return; }
+    int nk = select_neighbors(ix, base, W, nW, Mmax, keep);
+    if (nk >= 0){ nl->count = nk; for (int i=0;i<nk;i++) nl->ids[i]=keep[i]; }
+    free(keep); free(W);
+}
+
+/* ── insert ───────────────────────────────────────────────────────────────── */
+static int elems_reserve(VIndex* ix){
+    if (ix->n < ix->cap) return 0;
+    size_t nc = ix->cap ? ix->cap*2 : 64;
+    Elem* ne = (Elem*)realloc(ix->elems, nc*sizeof(Elem));
+    if (!ne) return -1;
+    ix->elems = ne; ix->cap = nc;
+    return visited_ensure(ix);
+}
+
+int vindex_insert(VIndex* ix, uint64_t node_id, const float* vec){
+    if (!ix || !vec) return -1;
+    if (elems_reserve(ix)) return -1;
+
+    int cur = (int)ix->n;
+    /* deterministic level assignment, seeded per-node. */
+    uint64_t seed = VINDEX_FIXED_SEED ^ (node_id + 0x2545F4914F6CDD1DULL*(uint64_t)cur);
+    int level = (int)(-log(sm_uniform(&seed)) * ix->mL);
+    if (level < 0) level = 0;
+
+    Elem* el = &ix->elems[cur];
+    el->node_id = node_id;
+    el->level = level;
+    el->vec = vec_normalise_copy(vec, ix->dim);
+    el->links = (NeighList*)calloc((size_t)level+1, sizeof(NeighList));
+    if (!el->vec || !el->links){ free(el->vec); free(el->links); return -1; }
+    ix->n++;
+
+    if (ix->entry < 0){                            /* first element */
+        ix->entry = cur; ix->max_level = level;
+        return 0;
+    }
+
+    int ep = ix->entry;
+    int L = ix->max_level;
+    /* greedy descent through layers above `level` to refine the entry point. */
+    for (int lc = L; lc > level; lc--){
+        Heap r = {0,0,0};
+        int eps1[1] = { ep };
+        if (search_layer(ix, el->vec, eps1, 1, 1, lc, &r)){ return -1; }
+        if (r.n){ ep = r.a[0].e; float bd=r.a[0].d;
+            for (int i=1;i<r.n;i++) if (r.a[i].d<bd){bd=r.a[i].d; ep=r.a[i].e;} }
+        free(r.a);
+    }
+    /* from min(L,level) down to 0: connect. Each layer's ef-results seed the next
+     * layer's entry set; `eps` is heap-owned below the top and freed each step. */
+    int start = (L < level) ? L : level;
+    int  eps_stack[1] = { ep };
+    int* eps = eps_stack;    /* not owned (stack) until reassigned to malloc'd */
+    int* eps_owned = NULL;
+    int  neps = 1;
+    int  rc = 0;
+    for (int lc = start; lc >= 0; lc--){
+        int Mmax = (lc==0) ? ix->M0 : ix->M;
+        Heap W = {0,0,0};
+        if (search_layer(ix, el->vec, eps, neps, ix->ef_construction, lc, &W)){ rc=-1; break; }
+        int* chosen = (int*)malloc((size_t)(W.n?W.n:1)*sizeof(int));
+        if (!chosen){ free(W.a); rc=-1; break; }
+        int nc = select_neighbors(ix, el->vec, W.a, W.n, Mmax, chosen);
+        if (nc < 0){ free(chosen); free(W.a); rc=-1; break; }
+        /* link cur <-> chosen (bidirectional), prune neighbours if over-full. */
+        for (int i=0;i<nc;i++){
+            int nb = chosen[i];
+            if (nl_push(&el->links[lc], nb) || nl_push(&ix->elems[nb].links[lc], cur)){
+                free(chosen); free(W.a); rc=-1; goto done;
+            }
+            prune_links(ix, nb, lc, Mmax);
+        }
+        free(chosen);
+        /* next layer's entry points = this layer's ef results. */
+        if (lc > 0){
+            int* neweps = (int*)malloc((size_t)(W.n?W.n:1)*sizeof(int));
+            if (!neweps){ free(W.a); rc=-1; break; }
+            for (int i=0;i<W.n;i++) neweps[i]=W.a[i].e;
+            neps = W.n ? W.n : 1;
+            if (!W.n) neweps[0] = eps[0];      /* fall back to prior ep if empty */
+            free(eps_owned);
+            eps = eps_owned = neweps;
+        }
+        free(W.a);
+    }
+done:
+    free(eps_owned);
+    if (rc) return -1;
+    if (level > ix->max_level){ ix->max_level = level; ix->entry = cur; }
+    return 0;
+}
+
+/* ── search ───────────────────────────────────────────────────────────────── */
+int vindex_search(VIndex* ix, const float* query, int k, int ef_search,
+                  uint64_t* node_id_out, float* dist_out){
+    if (!ix || !query || k <= 0) return -1;
+    if (ix->entry < 0) return 0;
+    if (ef_search <= 0) ef_search = VINDEX_DEFAULT_EF_SEARCH;
+    if (ef_search < k) ef_search = k;
+
+    float* q = vec_normalise_copy(query, ix->dim);
+    if (!q) return -1;
+
+    int ep = ix->entry;
+    for (int lc = ix->max_level; lc > 0; lc--){
+        Heap r = {0,0,0};
+        int eps[1] = { ep };
+        if (search_layer(ix, q, eps, 1, 1, lc, &r)){ free(q); return -1; }
+        if (r.n){ int b=r.a[0].e; float bd=r.a[0].d;
+            for (int i=1;i<r.n;i++) if (r.a[i].d<bd){bd=r.a[i].d; b=r.a[i].e;}
+            ep = b; }
+        free(r.a);
+    }
+    Heap res = {0,0,0};
+    int eps[1] = { ep };
+    if (search_layer(ix, q, eps, 1, ef_search, 0, &res)){ free(res.a); free(q); return -1; }
+    free(q);
+
+    /* res is a max-heap of size<=ef; pop into ascending order, keep nearest k. */
+    int total = res.n;
+    Pair* sorted = (Pair*)malloc((size_t)(total?total:1)*sizeof(Pair));
+    if (!sorted){ free(res.a); return -1; }
+    for (int i=total-1;i>=0;i--) sorted[i] = heap_pop(&res,1);  /* farthest first out → fill from end */
+    free(res.a);
+
+    int out_n = (k < total) ? k : total;
+    for (int i=0;i<out_n;i++){
+        if (node_id_out) node_id_out[i] = ix->elems[sorted[i].e].node_id;
+        if (dist_out)    dist_out[i]    = sorted[i].d;
+    }
+    free(sorted);
+    return out_n;
+}
+
+size_t vindex_size(const VIndex* ix){ return ix ? ix->n : 0; }
+
+VIndex* vindex_create(int dim, int M, int ef_construction){
+    if (dim <= 0) return NULL;
+    if (M <= 0) M = VINDEX_DEFAULT_M;
+    if (ef_construction <= 0) ef_construction = VINDEX_DEFAULT_EF_CONSTRUCTION;
+    VIndex* ix = (VIndex*)calloc(1, sizeof(VIndex));
+    if (!ix) return NULL;
+    ix->dim = dim;
+    ix->M = M;
+    ix->M0 = 2*M;
+    ix->ef_construction = ef_construction;
+    ix->mL = 1.0 / log((double)M > 1.0 ? (double)M : 2.0);
+    ix->entry = -1;
+    ix->max_level = 0;
+    ix->visit_epoch = 0;
+    return ix;
+}
+
+void vindex_free(VIndex* ix){
+    if (!ix) return;
+    for (size_t i=0;i<ix->n;i++){
+        Elem* e = &ix->elems[i];
+        if (e->links) for (int l=0;l<=e->level;l++) free(e->links[l].ids);
+        free(e->links);
+        free(e->vec);
+    }
+    free(ix->elems);
+    free(ix->visited);
+    free(ix);
+}
+
+/* ── read-only decode of the paged store node format (design §2.4) ─────────── */
+/* Mirrors engram_store.c constants; the on-disk format is PERMANENT so these are
+ * safe to duplicate for a read-only harvest of emb vectors. */
+#define VS_PAGE_SIZE   16384u
+#define VS_HDR         32u
+#define VS_SLOT_SIZE   6u
+#define VS_SLOT_LIVE   1u
+#define VS_REC_HDR     4u
+#define VS_REC_OVERFLOW 1u
+#define VS_PT_NODE     1u
+#define VS_OVF_NEXT    32u
+#define VS_OVF_LEN     40u
+#define VS_OVF_DATA    44u
+#define VS_NT_ID       1u
+#define VS_NT_EMB      24u
+#define VS_NT_EMB_DIM  25u
+
+static uint16_t vg_u16(const uint8_t* p){ return (uint16_t)(p[0] | (p[1]<<8)); }
+static uint32_t vg_u32(const uint8_t* p){ uint32_t v=0; for(int i=0;i<4;i++) v|=(uint32_t)p[i]<<(8*i); return v; }
+static uint64_t vg_u64(const uint8_t* p){ uint64_t v=0; for(int i=0;i<8;i++) v|=(uint64_t)p[i]<<(8*i); return v; }
+
+static int vs_pread(int fd, uint64_t page, uint8_t* buf){
+    off_t off = (off_t)page * VS_PAGE_SIZE;
+    ssize_t r = pread(fd, buf, VS_PAGE_SIZE, off);
+    return (r == (ssize_t)VS_PAGE_SIZE) ? 0 : -1;
+}
+/* Read a (possibly overflowed) record body; caller frees *out. */
+static int vs_read_body(int fd, const uint8_t* page, uint16_t off, uint16_t len,
+                        uint8_t** out, size_t* outlen){
+    if (len < VS_REC_HDR) return -1;
+    uint8_t flags = page[off+3];
+    if (flags & VS_REC_OVERFLOW){
+        uint64_t head  = vg_u64(page + off + VS_REC_HDR);
+        uint64_t total = vg_u64(page + off + VS_REC_HDR + 8);
+        uint8_t* body = (uint8_t*)malloc(total ? total : 1);
+        if (!body) return -1;
+        size_t got=0; uint64_t id=head;
+        uint8_t ov[VS_PAGE_SIZE];
+        while (id){
+            if (vs_pread(fd, id, ov)){ free(body); return -1; }
+            uint32_t chunk = vg_u32(ov + VS_OVF_LEN);
+            if (got + chunk > total){ free(body); return -1; }
+            memcpy(body+got, ov+VS_OVF_DATA, chunk); got += chunk;
+            id = vg_u64(ov + VS_OVF_NEXT);
+        }
+        if (got != total){ free(body); return -1; }
+        *out = body; *outlen = total;
+    } else {
+        uint16_t reclen = vg_u16(page + off);
+        if (reclen < VS_REC_HDR) return -1;
+        size_t blen = reclen - VS_REC_HDR;
+        uint8_t* body = (uint8_t*)malloc(blen ? blen : 1);
+        if (!body) return -1;
+        memcpy(body, page + off + VS_REC_HDR, blen);
+        *out = body; *outlen = blen;
+    }
+    return 0;
+}
+/* Extract id (strdup) and emb (malloc'd float[dim]) from a TLV node body. */
+static void vs_parse_node(const uint8_t* body, size_t len, char** id_out,
+                          float** emb_out, int* dim_out){
+    *id_out=NULL; *emb_out=NULL; *dim_out=0;
+    size_t i=0;
+    while (i + 5 <= len){
+        uint8_t tag = body[i];
+        uint32_t flen = vg_u32(body + i + 1);
+        if (i + 5 + (size_t)flen > len) break;
+        const uint8_t* v = body + i + 5;
+        if (tag == VS_NT_ID){
+            char* s = (char*)malloc(flen+1);
+            if (s){ memcpy(s,v,flen); s[flen]=0; free(*id_out); *id_out=s; }
+        } else if (tag == VS_NT_EMB){
+            int dim = (int)(flen/4);
+            float* e = (float*)malloc((size_t)(dim?dim:1)*sizeof(float));
+            if (e){ for (int k=0;k<dim;k++){ uint32_t u=vg_u32(v+k*4); memcpy(&e[k],&u,4);}
+                    free(*emb_out); *emb_out=e; if(*dim_out==0) *dim_out=dim; }
+        } else if (tag == VS_NT_EMB_DIM){
+            *dim_out = (int)vg_u32(v);
+        }
+        i += 5 + flen;
+    }
+}
+
+/* Tiny open-addressing string set to dedup ids across live records. */
+typedef struct { char** k; size_t cap, n; } StrSet;
+static uint64_t vs_fnv(const char* s){ uint64_t h=1469598103934665603ULL; for(;*s;++s){h^=(uint8_t)*s;h*=1099511628211ULL;} return h; }
+static int strset_add(StrSet* s, const char* key){   /* 1 added, 0 dup, -1 err */
+    if (s->n*2 >= s->cap){
+        size_t nc = s->cap ? s->cap*2 : 1024;
+        char** nk = (char**)calloc(nc, sizeof(char*));
+        if (!nk) return -1;
+        for (size_t i=0;i<s->cap;i++) if (s->k[i]){ size_t j=vs_fnv(s->k[i])&(nc-1); while(nk[j]) j=(j+1)&(nc-1); nk[j]=s->k[i]; }
+        free(s->k); s->k=nk; s->cap=nc;
+    }
+    size_t j = vs_fnv(key)&(s->cap-1);
+    while (s->k[j]){ if (strcmp(s->k[j],key)==0) return 0; j=(j+1)&(s->cap-1); }
+    char* d = strdup(key); if(!d) return -1;
+    s->k[j]=d; s->n++;
+    return 1;
+}
+static void strset_free(StrSet* s){ for(size_t i=0;i<s->cap;i++) free(s->k[i]); free(s->k); }
+
+int vindex_harvest_from_store(const char* store_path, int dim,
+                              float** vecs_out, char*** ids_out, int* n_out){
+    if (!store_path || dim <= 0 || !vecs_out) return -1;
+    int fd = open(store_path, O_RDONLY);
+    if (fd < 0) return -1;
+    struct stat st;
+    if (fstat(fd, &st) != 0){ close(fd); return -1; }
+    uint64_t npages = (uint64_t)st.st_size / VS_PAGE_SIZE;
+
+    float* vecs = NULL; size_t vn = 0, vcap = 0;   /* row-major float[vn*dim] */
+    char** ids  = NULL; size_t ids_n = 0, ids_cap = 0;
+    StrSet seen = {0,0,0};
+    uint8_t page[VS_PAGE_SIZE];
+    int failed = 0;
+
+    for (uint64_t pg = 2; pg < npages; pg++){       /* pages 0,1 = superblocks */
+        if (vs_pread(fd, pg, page)) continue;
+        if (page[8] != VS_PT_NODE) continue;
+        int slots = vg_u16(page + 10);
+        for (int sidx=0; sidx<slots; sidx++){
+            const uint8_t* sp = page + VS_HDR + (size_t)sidx*VS_SLOT_SIZE;
+            uint16_t off = vg_u16(sp), len = vg_u16(sp+2), fl = vg_u16(sp+4);
+            if (fl != VS_SLOT_LIVE) continue;
+            if ((size_t)off + VS_REC_HDR > VS_PAGE_SIZE) continue;
+            uint8_t* body=NULL; size_t blen=0;
+            if (vs_read_body(fd, page, off, len, &body, &blen)) continue;
+            char* id=NULL; float* emb=NULL; int edim=0;
+            vs_parse_node(body, blen, &id, &emb, &edim);
+            free(body);
+            if (!id || !emb || edim != dim){ free(id); free(emb); continue; }
+            int add = strset_add(&seen, id);
+            if (add <= 0){ free(id); free(emb); continue; }   /* dup or err */
+            if (vn == vcap){
+                size_t nc = vcap ? vcap*2 : 1024;
+                float* nv = (float*)realloc(vecs, nc*(size_t)dim*sizeof(float));
+                if (!nv){ free(id); free(emb); failed = 1; goto out; }
+                vecs = nv; vcap = nc;
+            }
+            memcpy(vecs + vn*(size_t)dim, emb, (size_t)dim*sizeof(float));
+            free(emb);
+            if (ids_n == ids_cap){
+                size_t nc = ids_cap ? ids_cap*2 : 1024;
+                char** ni = (char**)realloc(ids, nc*sizeof(char*));
+                if (!ni){ free(id); failed = 1; goto out; }
+                ids = ni; ids_cap = nc;
+            }
+            ids[ids_n++] = id;    /* transfers ownership */
+            vn++;
+        }
+    }
+out:
+    close(fd);
+    strset_free(&seen);
+    if (failed){
+        free(vecs);
+        for (size_t i=0;i<ids_n;i++) free(ids[i]);
+        free(ids);
+        return -1;
+    }
+    *vecs_out = vecs;
+    if (n_out) *n_out = (int)vn;
+    if (ids_out){ *ids_out = ids; }
+    else { for (size_t i=0;i<ids_n;i++) free(ids[i]); free(ids); }
+    return (int)vn;
+}
+
+int vindex_build_from_store(VIndex* ix, const char* store_path,
+                            char*** ids_out, int* n_out){
+    if (!ix || !store_path) return -1;
+    float* vecs = NULL; char** ids = NULL; int n = 0;
+    int h = vindex_harvest_from_store(store_path, ix->dim, &vecs, &ids, &n);
+    if (h < 0) return -1;
+    int inserted = 0;
+    for (int i = 0; i < n; i++){
+        if (vindex_insert(ix, (uint64_t)inserted, vecs + (size_t)i*ix->dim) != 0) break;
+        inserted++;
+    }
+    free(vecs);
+    if (ids_out){
+        *ids_out = ids; if (n_out) *n_out = inserted;
+        /* free any ids beyond what we inserted (insert failure tail) */
+        for (int i = inserted; i < n; i++) free(ids[i]);
+    } else {
+        for (int i = 0; i < n; i++) free(ids[i]);
+        free(ids);
+        if (n_out) *n_out = inserted;
+    }
+    return inserted;
+}
+
+/* ── optional persistence (index is rebuildable; convenience only) ─────────── */
+#define VINDEX_SAVE_MAGIC "EGVIDX01"
+int vindex_save(const VIndex* ix, const char* path){
+    if (!ix || !path) return -1;
+    FILE* f = fopen(path, "wb");
+    if (!f) return -1;
+    int ok = 1;
+    #define WR(p,n) do{ if(fwrite((p),1,(n),f)!=(size_t)(n)) ok=0; }while(0)
+    WR(VINDEX_SAVE_MAGIC, 8);
+    int32_t hdr[6] = { ix->dim, ix->M, ix->ef_construction, (int32_t)ix->n, ix->entry, ix->max_level };
+    WR(hdr, sizeof(hdr));
+    for (size_t i=0; ok && i<ix->n; i++){
+        Elem* e = &ix->elems[i];
+        WR(&e->node_id, sizeof(uint64_t));
+        int32_t lvl = e->level; WR(&lvl, sizeof(int32_t));
+        WR(e->vec, (size_t)ix->dim*sizeof(float));
+        for (int l=0; ok && l<=e->level; l++){
+            int32_t c = e->links[l].count; WR(&c, sizeof(int32_t));
+            WR(e->links[l].ids, (size_t)c*sizeof(int));
+        }
+    }
+    #undef WR
+    fclose(f);
+    return ok ? 0 : -1;
+}
+VIndex* vindex_load(const char* path){
+    FILE* f = fopen(path, "rb");
+    if (!f) return NULL;
+    char magic[8];
+    if (fread(magic,1,8,f)!=8 || memcmp(magic,VINDEX_SAVE_MAGIC,8)!=0){ fclose(f); return NULL; }
+    int32_t hdr[6];
+    if (fread(hdr,sizeof(hdr),1,f)!=1){ fclose(f); return NULL; }
+    VIndex* ix = vindex_create(hdr[0], hdr[1], hdr[2]);
+    if (!ix){ fclose(f); return NULL; }
+    size_t N = (size_t)hdr[3];
+    int ok = 1;
+    for (size_t i=0; ok && i<N; i++){
+        if (elems_reserve(ix)){ ok=0; break; }
+        Elem* e = &ix->elems[ix->n];
+        int32_t lvl;
+        if (fread(&e->node_id,sizeof(uint64_t),1,f)!=1 || fread(&lvl,sizeof(int32_t),1,f)!=1){ ok=0; break; }
+        e->level = lvl;
+        e->vec = (float*)malloc((size_t)ix->dim*sizeof(float));
+        e->links = (NeighList*)calloc((size_t)lvl+1, sizeof(NeighList));
+        if (!e->vec || !e->links){ free(e->vec); free(e->links); ok=0; break; }
+        if (fread(e->vec,sizeof(float),(size_t)ix->dim,f)!=(size_t)ix->dim){ ok=0; }
+        for (int l=0; ok && l<=lvl; l++){
+            int32_t c; if (fread(&c,sizeof(int32_t),1,f)!=1){ ok=0; break; }
+            e->links[l].ids = (int*)malloc((size_t)(c?c:1)*sizeof(int));
+            e->links[l].cap = c; e->links[l].count = c;
+            if (c && fread(e->links[l].ids,sizeof(int),(size_t)c,f)!=(size_t)c){ ok=0; }
+        }
+        ix->n++;
+    }
+    ix->entry = hdr[4]; ix->max_level = hdr[5];
+    fclose(f);
+    if (!ok){ vindex_free(ix); return NULL; }
+    return ix;
+}

lang/runtime/engram_vindex.h

@@ -0,0 +1,94 @@
+/* engram_vindex.h — M8 of the engram query engine: an approximate-nearest-
+ * neighbour (ANN) vector index over the node embedding vectors, for fast
+ * activation-seed selection.
+ *
+ * Replaces the O(n) cosine scan over emb vectors (design §9 M8; backlog #20)
+ * with an HNSW (Hierarchical Navigable Small World) graph that returns
+ * high-recall top-k seeds in ~O(log n).
+ *
+ * Standalone module: plain C11, stdlib + libm only. It does NOT modify the
+ * store format or engram_store.{c,h}; vindex_build_from_store() decodes the
+ * PERMANENT on-disk node format (design §2.4) read-only to harvest emb vectors.
+ *
+ * Similarity metric: cosine. Vectors are L2-normalised on insert/query, so
+ * cosine similarity == dot product. Reported distance = 1 - cosine_similarity
+ * (range [0,2]); smaller == closer. A query equal to an indexed vector scores
+ * distance ~0 against it.
+ *
+ * The index is fully rebuildable from the store, so persistence is optional for
+ * this milestone (see vindex_save/vindex_load below — provided as a convenience;
+ * boot may simply rebuild via vindex_build_from_store()).
+ */
+#ifndef ENGRAM_VINDEX_H
+#define ENGRAM_VINDEX_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Tuned defaults (rationale in engram_vindex.c). Pass 0 to vindex_create for
+ * M / ef_construction to take these; pass ef_search<=0 to vindex_search for
+ * VINDEX_DEFAULT_EF_SEARCH. */
+#define VINDEX_DEFAULT_M              24
+#define VINDEX_DEFAULT_EF_CONSTRUCTION 200
+#define VINDEX_DEFAULT_EF_SEARCH       128
+
+typedef struct VIndex VIndex;
+
+/* Create an index over `dim`-dimensional f32 vectors.
+ *   M               — max neighbours per node on upper layers (2*M on layer 0).
+ *   ef_construction — candidate-list width during insert (recall/build cost).
+ * Pass M<=0 or ef_construction<=0 to use the VINDEX_DEFAULT_* above.
+ * Returns NULL on bad args / OOM. */
+VIndex* vindex_create(int dim, int M, int ef_construction);
+
+/* Insert one vector under an opaque caller-defined node_id (need not be unique,
+ * but the caller is responsible for meaning). `vec` has `dim` floats; it is
+ * copied and L2-normalised internally. A zero vector is accepted (it simply has
+ * distance ~1 to everything; never produces NaN). Returns 0 on success, <0 on
+ * error (bad args / OOM). */
+int vindex_insert(VIndex* idx, uint64_t node_id, const float* vec);
+
+/* Top-k search by cosine similarity. Writes up to k results (fewer if the index
+ * holds fewer than k elements) into node_id_out[] / dist_out[], ordered nearest
+ * first (ascending distance). Either out array may be NULL to skip it.
+ *   ef_search — search-time candidate width; larger == higher recall, slower.
+ *               Pass <=0 for VINDEX_DEFAULT_EF_SEARCH. Internally clamped to >=k.
+ * Returns the number of results written, or <0 on error. */
+int vindex_search(VIndex* idx, const float* query, int k, int ef_search,
+                  uint64_t* node_id_out, float* dist_out);
+
+/* Number of vectors currently indexed. */
+size_t vindex_size(const VIndex* idx);
+
+void vindex_free(VIndex* idx);
+
+/* Build an index by scanning every live node record in the paged store at
+ * `store_path` (the on-disk format is decoded read-only; the store need not be
+ * open). Nodes without an emb vector, or whose emb_dim != idx->dim, are skipped.
+ * Each inserted node is assigned node_id = its 0-based insertion ordinal; if
+ * `ids_out`/`n_out` are non-NULL, *ids_out is set to a malloc'd array of that
+ * many strdup'd string ids (ids_out[node_id] == the store id) and *n_out to the
+ * count — the caller frees each string and the array. Returns the number of
+ * vectors inserted, or <0 on error. */
+int vindex_build_from_store(VIndex* idx, const char* store_path,
+                            char*** ids_out, int* n_out);
+
+/* Read-only harvest of the raw (un-normalised) emb vectors from a paged store,
+ * applying the SAME filtering vindex_build_from_store does (live records only,
+ * deduped by store id, emb present with emb_dim == `dim`), in insertion order.
+ * On success sets *vecs_out to a malloc'd float[n*dim] (row i == the i-th kept
+ * vector) and *n_out to n; if `ids_out` is non-NULL, sets it to a malloc'd array
+ * of n strdup'd store ids (ids_out[i] == the id of row i). Caller frees *vecs_out,
+ * each id string, and the id array. Returns n, or <0 on error. Used both by
+ * vindex_build_from_store (which then inserts each row) and by benchmarks/oracles
+ * that need the same vector set the index holds. */
+int vindex_harvest_from_store(const char* store_path, int dim,
+                              float** vecs_out, char*** ids_out, int* n_out);
+
+/* Optional persistence (index is rebuildable from the store; provided for
+ * convenience). vindex_save writes a self-describing snapshot; vindex_load
+ * reconstructs an index from one. Return 0 / non-NULL on success. */
+int     vindex_save(const VIndex* idx, const char* path);
+VIndex* vindex_load(const char* path);
+
+#endif /* ENGRAM_VINDEX_H */

lang/runtime/vindex_bench.c

@@ -0,0 +1,238 @@
+/* vindex_bench.c — standalone proof harness for the engram HNSW ANN index.
+ *
+ * Measures brute-force cosine top-k (the correctness ORACLE) vs vindex_search
+ * (HNSW) on: (a) the REAL paged store harvested read-only, and (b) synthetic
+ * clustered data at several sizes to trace the scaling curve. Reports build time,
+ * per-query latency (brute vs HNSW), and recall@k (HNSW top-k vs brute top-k).
+ *
+ * Read-only: never opens a socket, never writes the store. Safe on an nsbx clone.
+ *
+ * Build:  cc -O2 -std=c11 vindex_bench.c engram_vindex.c -lm -o vindex_bench
+ * Usage:  vindex_bench store <neuron.egm> <dim> [nqueries] [k] [ef_csv]
+ *         vindex_bench synth <N> [dim] [clusters] [nqueries] [k] [ef_csv]
+ */
+#include "engram_vindex.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <math.h>
+#include <stdint.h>
+#include <time.h>
+
+/* ── deterministic PRNG (splitmix64) so runs are reproducible ─────────────── */
+static uint64_t g_seed = 0xD1B54A32D192ED03ULL;
+static uint64_t sm(void){
+    uint64_t z = (g_seed += 0x9E3779B97F4A7C15ULL);
+    z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
+    z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
+    return z ^ (z >> 31);
+}
+static double urand(void){ return (double)((sm() >> 11) + 1) * (1.0/9007199254740993.0); }
+static double grand(void){ /* Box-Muller */
+    double u1 = urand(), u2 = urand();
+    return sqrt(-2.0*log(u1)) * cos(2.0*M_PI*u2);
+}
+
+static double now_s(void){
+    struct timespec ts; clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (double)ts.tv_sec + (double)ts.tv_nsec*1e-9;
+}
+
+/* L2-normalise a row in place. */
+static void l2norm(float* v, int dim){
+    double ss = 0; for (int i=0;i<dim;i++) ss += (double)v[i]*v[i];
+    if (ss > 0){ float inv = (float)(1.0/sqrt(ss)); for (int i=0;i<dim;i++) v[i]*=inv; }
+}
+
+/* Brute-force top-k by cosine distance (1 - dot on normalised vecs).
+ * data is n*dim, already L2-normalised. Writes k node ids (row indices) into
+ * out_ids ascending by distance. Returns nothing; assumes k<=n. */
+static void brute_topk(const float* data, int n, int dim, const float* q,
+                       int k, int* out_ids, float* out_d){
+    /* maintain a small sorted array of the k best (ascending distance). */
+    for (int i=0;i<k;i++){ out_ids[i]=-1; out_d[i]=2.0f+1.0f; }
+    for (int i=0;i<n;i++){
+        const float* r = data + (size_t)i*dim;
+        float s0=0,s1=0,s2=0,s3=0; int j=0;
+        for (; j+4<=dim; j+=4){ s0+=q[j]*r[j]; s1+=q[j+1]*r[j+1]; s2+=q[j+2]*r[j+2]; s3+=q[j+3]*r[j+3]; }
+        float dot=(s0+s1)+(s2+s3); for (; j<dim; j++) dot+=q[j]*r[j];
+        float d = 1.0f - dot;
+        if (d >= out_d[k-1]) continue;
+        int p = k-1;
+        while (p>0 && out_d[p-1] > d){ out_d[p]=out_d[p-1]; out_ids[p]=out_ids[p-1]; p--; }
+        out_d[p]=d; out_ids[p]=i;
+    }
+}
+
+/* recall@k: |brute_topk ∩ hnsw_topk| / k. Both are id arrays of length k. */
+static double recall_at_k(const int* gt, const uint64_t* ann, int nann, int k){
+    int hit = 0;
+    for (int i=0;i<k;i++){
+        if (gt[i] < 0) continue;
+        for (int j=0;j<nann;j++){ if ((int)ann[j] == gt[i]){ hit++; break; } }
+    }
+    return (double)hit / (double)k;
+}
+
+/* Parse "64,128,256" into an int array; returns count. */
+static int parse_csv(const char* s, int* out, int maxo){
+    int n=0; if(!s||!*s) return 0;
+    const char* p=s;
+    while(*p && n<maxo){ out[n++]=atoi(p); while(*p && *p!=',') p++; if(*p==',') p++; }
+    return n;
+}
+
+/* Generate n unit vectors on a LOW-DIMENSIONAL MANIFOLD, the property that makes
+ * real text embeddings tractable for ANN: each vector is a fixed random linear map
+ * A (dim × LATENT) applied to a latent gaussian z ∈ R^LATENT, plus small ambient
+ * noise, then L2-normalised. Points therefore lie near a `latent`-dim subspace, so
+ * every point has a well-defined tight neighbourhood (high recall) and the HNSW
+ * graph is cheap to build — unlike near-isotropic 768-d gaussians, where the curse
+ * of dimensionality makes all points near-equidistant (no structure → slow build,
+ * low recall) and unlike tight clusters (near-duplicates → artificial top-k ties).
+ * `sigma` is the ambient-noise scale. This reproduces the intrinsic-dimensionality
+ * regime of nomic embeddings, so the scaling curve reflects real-corpus behaviour. */
+#define SYNTH_LATENT 48
+static void gen_synth(float* data, int n, int dim, int clusters, double sigma){
+    (void)clusters;
+    float* A = malloc((size_t)dim*SYNTH_LATENT*sizeof(float));   /* fixed random basis */
+    for (size_t i=0;i<(size_t)dim*SYNTH_LATENT;i++) A[i]=(float)grand();
+    float z[SYNTH_LATENT];
+    for (int i=0;i<n;i++){
+        for (int l=0;l<SYNTH_LATENT;l++) z[l]=(float)grand();
+        float* v = data+(size_t)i*dim;
+        for (int j=0;j<dim;j++){
+            float acc = (float)(sigma*grand());
+            const float* row = A + (size_t)j*SYNTH_LATENT;
+            for (int l=0;l<SYNTH_LATENT;l++) acc += row[l]*z[l];
+            v[j]=acc;
+        }
+        l2norm(v, dim);
+    }
+    free(A);
+}
+
+/* Build M / ef_construction come from env (VIDX_M / VIDX_EFC) so the scaling
+ * sweep can trade build cost against graph quality without a recompile. 0 = default. */
+static int env_int(const char* k, int dflt){ const char* s=getenv(k); return (s&&*s)?atoi(s):dflt; }
+
+/* Run the full brute-vs-HNSW comparison over an already-normalised dataset. */
+static void run_bench(const char* label, float* data, int n, int dim,
+                      int nq, int k, int* efs, int nef, double build_s){
+    (void)build_s;
+    int bM = env_int("VIDX_M", 0), bEFC = env_int("VIDX_EFC", 0);
+    printf("\n=== %s : N=%d  dim=%d  k=%d  queries=%d ===\n", label, n, dim, k, nq);
+
+    /* build the index once (shared across ef settings). */
+    double t0 = now_s();
+    VIndex* ix = vindex_create(dim, bM, bEFC);
+    for (int i=0;i<n;i++) vindex_insert(ix, (uint64_t)i, data + (size_t)i*dim);
+    double bt = now_s()-t0;
+    printf("HNSW build: M=%d ef_construction=%d  ->  %.3f s  (%.1f k nodes/s)\n",
+           bM?bM:VINDEX_DEFAULT_M, bEFC?bEFC:VINDEX_DEFAULT_EF_CONSTRUCTION, bt, n/1000.0/bt);
+
+    /* choose query vectors: perturb random dataset rows (near-but-not-identical). */
+    int* qidx = malloc((size_t)nq*sizeof(int));
+    float* qv = malloc((size_t)nq*dim*sizeof(float));
+    for (int i=0;i<nq;i++){
+        int r = (int)(sm() % (uint64_t)n);
+        qidx[i]=r;
+        float* dst = qv+(size_t)i*dim; const float* src = data+(size_t)r*dim;
+        for (int j=0;j<dim;j++) dst[j] = src[j] + (float)(0.01*grand());
+        l2norm(dst, dim);
+    }
+
+    /* ground truth: brute-force top-k for every query (also the oracle latency). */
+    int* gt = malloc((size_t)nq*k*sizeof(int));
+    float* gd = malloc((size_t)k*sizeof(float));
+    double tb0 = now_s();
+    for (int i=0;i<nq;i++) brute_topk(data, n, dim, qv+(size_t)i*dim, k, gt+(size_t)i*k, gd);
+    double brute_ms = (now_s()-tb0)*1000.0/nq;
+    printf("BRUTE-FORCE  : %8.3f ms/query   (oracle; O(N*D))\n", brute_ms);
+
+    /* HNSW at each ef. */
+    uint64_t* aid = malloc((size_t)k*sizeof(uint64_t));
+    float* ad = malloc((size_t)k*sizeof(float));
+    printf("%-6s %14s %12s %10s\n", "ef", "HNSW ms/query", "speedup", "recall@k");
+    for (int e=0;e<nef;e++){
+        int ef = efs[e];
+        double th0 = now_s();
+        double rec_sum = 0;
+        for (int i=0;i<nq;i++){
+            int m = vindex_search(ix, qv+(size_t)i*dim, k, ef, aid, ad);
+            rec_sum += recall_at_k(gt+(size_t)i*k, aid, m, k);
+        }
+        double hnsw_ms = (now_s()-th0)*1000.0/nq;
+        printf("%-6d %14.4f %11.1fx %10.4f\n", ef, hnsw_ms, brute_ms/hnsw_ms, rec_sum/nq);
+    }
+
+    free(qidx); free(qv); free(gt); free(gd); free(aid); free(ad);
+    vindex_free(ix);
+}
+
+int main(int argc, char** argv){
+    setvbuf(stdout, NULL, _IOLBF, 0);   /* line-buffered so progress streams to a log */
+    if (argc < 2){ fprintf(stderr,"usage: %s store <path> <dim> [nq] [k] [ef_csv] | synth <N> [dim] [clusters] [nq] [k] [ef_csv] | sweep <dim> <N_csv> [nq] [k] [ef_csv]\n", argv[0]); return 2; }
+    int defef[8]; int ndef;
+
+    if (strcmp(argv[1],"sweep")==0){
+        if (argc < 4){ fprintf(stderr,"sweep needs <dim> <N_csv>\n"); return 2; }
+        int dim = atoi(argv[2]);
+        int Ns[16]; int nN = parse_csv(argv[3], Ns, 16);
+        int nq = (argc>4)?atoi(argv[4]):200;
+        int k  = (argc>5)?atoi(argv[5]):10;
+        ndef = (argc>6)?parse_csv(argv[6],defef,8):parse_csv("64,128,200",defef,8);
+        for (int s=0;s<nN;s++){
+            int N = Ns[s];
+            float* data = malloc((size_t)N*dim*sizeof(float));
+            if (!data){ fprintf(stderr,"OOM at N=%d\n",N); continue; }
+            int clusters = N/100; if (clusters < 64) clusters = 64;
+            gen_synth(data, N, dim, clusters, 1.0);
+            char lbl[64]; snprintf(lbl,sizeof lbl,"SYNTH N=%d", N);
+            run_bench(lbl, data, N, dim, nq, k, defef, ndef, 0.0);
+            free(data);
+        }
+        return 0;
+    }
+
+    if (strcmp(argv[1],"store")==0){
+        if (argc < 4){ fprintf(stderr,"store needs <path> <dim>\n"); return 2; }
+        const char* path = argv[2]; int dim = atoi(argv[3]);
+        int nq = (argc>4)?atoi(argv[4]):500;
+        int k  = (argc>5)?atoi(argv[5]):10;
+        ndef = (argc>6)?parse_csv(argv[6],defef,8):parse_csv("32,64,128,200,400",defef,8);
+        printf("Harvesting emb vectors from %s (dim=%d) ...\n", path, dim);
+        float* data=NULL; int n=0;
+        double t0=now_s();
+        int h = vindex_harvest_from_store(path, dim, &data, NULL, &n);
+        double harvest_s = now_s()-t0;
+        if (h < 0 || n == 0){ fprintf(stderr,"harvest failed (h=%d n=%d) — wrong dim or path?\n", h, n); return 1; }
+        printf("Harvested %d live embedded nodes in %.2f s\n", n, harvest_s);
+        for (int i=0;i<n;i++) l2norm(data+(size_t)i*dim, dim);   /* oracle needs normalised */
+        if (nq > n) nq = n;
+        run_bench("REAL STORE", data, n, dim, nq, k, defef, ndef, 0.0);
+        free(data);
+        return 0;
+    }
+
+    if (strcmp(argv[1],"synth")==0){
+        if (argc < 3){ fprintf(stderr,"synth needs <N>\n"); return 2; }
+        int N = atoi(argv[2]);
+        int dim = (argc>3)?atoi(argv[3]):768;
+        int clusters = (argc>4)?atoi(argv[4]):200;
+        int nq = (argc>5)?atoi(argv[5]):500;
+        int k  = (argc>6)?atoi(argv[6]):10;
+        ndef = (argc>7)?parse_csv(argv[7],defef,8):parse_csv("64,128,200",defef,8);
+        printf("Generating %d synthetic clustered vectors (dim=%d clusters=%d) ...\n", N, dim, clusters);
+        float* data = malloc((size_t)N*dim*sizeof(float));
+        if (!data){ fprintf(stderr,"OOM allocating %zu bytes\n", (size_t)N*dim*sizeof(float)); return 1; }
+        gen_synth(data, N, dim, clusters, 0.35);
+        char lbl[64]; snprintf(lbl,sizeof lbl,"SYNTH");
+        run_bench(lbl, data, N, dim, nq, k, defef, ndef, 0.0);
+        free(data);
+        return 0;
+    }
+
+    fprintf(stderr,"unknown mode '%s'\n", argv[1]);
+    return 2;
+}

tools/api-reshape/README.md

@@ -0,0 +1,99 @@
+# Neuron API-surface reshape
+
+Design: artifact **0e828907** + design-brief **2b8078cf §5**. Collapse ~90
+functional-CRUD MCP tools into a handful of **geometry ops** over the one
+geometry, plus the **live agentic primitives** already in the engram cognition
+build. **Type is a parameter, not a tool-per-noun.**
+
+Ground-truth: routes verified against the live cognition binary
+`engram.cognition-20260814-160045` (route source: branch
+`feat/cognitive-architecture`, `engram/src/server.el`). Built + validated on an
+**isolated nsbx clone** (`:8900`); live `:8742` untouched.
+
+**The decoration IS the API.** `surface.el` is El-native: each op is one function
+decorated with its `@route` (codegen synthesizes `el_route_dispatch` — no
+hand-written 90-branch dispatch) and its VBD role (`@accessor` = engram I/O,
+`@manager` = agentic orchestration + DHARMA emitter). Handlers call the engram
+**in-process** via `engram_*` builtins (not `http_get` — that idiom only existed
+because the old MCP wrapper was a separate process). Decorate→serve is **proven**:
+`route_proof.el` serves decorated handlers on :8951; `surface.el` compiles and the
+dispatcher is generated for all 8 ops. See `SEAM_STAGED.md` for the three-part seam
+(route / telemetry+interoception / bus) ground-truth and the staged boundary diff.
+
+**Clone boot recipe (gate-1):** cold-boot from `neuron.egm` with the WAL set aside
+(the live-store clone's WAL is torn and loops on replay) + `ENGRAM_WAL=on` (routes
+node-writes to the WAL-append path; without it `persist_node`→full-store checkpoint
+**segfaults** a clone) + `ENGRAM_GEOMETRY_PRIMING=1`. **Anchors must be node-ids**
+(think/ground/learn resolve each seed via `engram_find_node_index`; free text →
+"geometry unavailable"). With this recipe the **full op set is proven live on the
+clone** (below).
+
+## Layer 1 — geometry ops
+
+| op | signature | engram route | replaces (~) |
+|----|-----------|--------------|--------------|
+| `read` (vantage-read) | `read({vantage, type?, aperture:{k,depth}})` | GET `/api/search` \| `/api/neighbors/<id>` \| `/api/nodes/<id>` \| `/api/activate` | inspectGraph, searchGraph, traverseGraph, searchKnowledge, browseKnowledge, retrieveKnowledge, inspectMemories, searchEntities, recall, compileCtx, getSelfModel, reviewBacklog, findArtifacts, browseProcesses, listWork, inspectConfig … (~30) |
+| `write` | `write({content, type, tags, importance})` | POST `/api/nodes` | remember, captureKnowledge, draftArtifact, planWork, defineProcess, addWonderQuestion, logInternalStateEvent … (~15) |
+| `relate` | `relate({from, to, relationship, weight?})` | POST `/api/edges` | linkEntities, linkCausal, restructureCausalGraph, pin |
+| `supersede` | `supersede({id, action: evolve\|supersede\|tombstone\|promote, content?})` | write+relate(`supersedes`) / DELETE `/api/nodes/<id>` (immutable marker) | evolveMemory, evolveKnowledge, forget→tombstone, promoteKnowledge, reviseArtifact, trackWork, progressWork(update) … (~15) |
+
+**Vantage-read = the whole-self-dump fix.** Re-origin at a point + salience +
+recency + **aperture** → a *bounded* slice. Aperture (`k`/`depth`) caps output:
+measured on the clone, `limit=3 → 15 KB` vs `limit=50 → 363 KB`. The old path
+returned 60k–230k-char unbounded traversals (this very session hit 104 KB and
+409 KB live).
+
+## Layer 2 — primitive agentic tools (Neuron runs itself)
+
+The base verbs all agentic behavior composes from — grounded in the LIVE
+cog-arch (`think` is the one operation; faculties are its steering-space labels;
+the correspondence-beat is the reflexive learning loop).
+
+| op | signature | engram builtin | status on clone (gate-1 recipe) |
+|----|-----------|----------------|---------------------------------|
+| `think` | `think({seeds, faculty})` faculty ∈ reason·abduce·induce·plan·analogize·recognize·discern·synthesize | `engram_think_json` | **PROVEN** — all 8 faculties return real 768-dim gradients (n_support 30–282) |
+| `attend` | `attend({node, observer, salience})` | `engram_attend_json` | **PROVEN** (returns `salient-to`) |
+| `assert` | `assert({claim, for_whom, floor})` — realize, honesty-floored | `engram_assert_json` | **PROVEN** |
+| `ground` | `ground({claim, evidence, for_whom})` node-id anchors | `engram_ground_json` | **PROVEN** (grounded-by edge, grounding=0.912, written) |
+| `learn` | `learn({seeds, faculty, keystone})` — the correspondence-beat | `engram_correspondence_beat_json` | **PROVEN** (real Stance: `stance-induce-…`, brier, reliability, written) |
+
+`comprehend`/`realize`/`intend` are **compositions**, not separate live
+primitives: comprehend = write+activate (world→geometry), realize = assert
+pointed at the world (geometry→act), intend = attend at a goal-region. The
+skill-learning loop (decompose→detect-gap→reach-out-on-sparsity→verify-by-
+execution→integrate) composes over `think`+`ground`+`learn`+`write`/`relate`.
+
+## Identity is write-protected
+
+`write(type=self|values)`, and `relate`/`supersede` touching the keystones
+`kn-efeb4a5b…` / `kn-5b606390…`, are refused — identity routes through
+intentional-cultivation, as enforced today.
+
+## How the caller invokes Neuron agentically
+
+Once the ops are registered as MCP tools (aliases in `surface.el`), the caller
+(Claude, this loop) calls e.g.:
+
+```
+neuron.think({ seeds: "kn-efeb4a5b…", faculty: "plan" })   # Neuron reasons over its own geometry
+neuron.attend({ node: <region> })                           # aim its attention
+neuron.learn({ seeds: <region>, faculty: "induce" })        # calibrate its own prior (correspondence-beat)
+neuron.read({ vantage: "self", aperture:{k:12} })           # bounded self-slice (no dump)
+```
+
+and **Neuron does the agentic work over its own geometry** — the beginning of it
+running itself.
+
+## Files
+- `surface.el` — the reshaped surface as **decorated El-native components** (`@route` + `@accessor`/`@manager`, in-process `engram_*` builtins). Compiles; dispatcher generated for all 8 ops.
+- `route_proof.el` — a standalone decorated El service that **proves decorate→serve** on :8951 (built with the worktree-rebuilt `elc-route`).
+- `SEAM_STAGED.md` — the three-part seam (route / telemetry+interoception / bus) ground-truth + the exact staged `cg_fn` diff for boundary auto-emit.
+- `agentic_loop.el` — the four-call loop (think→attend→learn→read) as compilable El.
+- `parity.sh` — API-level parity harness against the clone.
+
+## Honest ledger (built vs staged)
+- **Route seam — IMPLEMENTED + PROVEN:** ported the `@route` codegen (from `feat/el-route-decorators`) into the worktree, rebuilt `elc` self-host, proved decorate→serve (`route_proof.el` on :8951); `surface.el` compiles with `el_route_dispatch` generated for all 8 ops.
+- **All ops PROVEN live on the clone** (gate-1 boot recipe, node-id anchors): read, write, relate, supersede (immutable), tombstone, think (8 faculties), ground, attend, learn — daemon alive through all mutations (node_count 13173→13176).
+- **Aperture-boundedness PROVEN:** vantage-read `limit=3 → 15 KB` vs `limit=50 → 363 KB` (fixes the whole-self dump).
+- **Bus:** `@manager` ops emit on the real `dharma_*` bus (explicit today, compiles) — same transport as the swarm (`wt/swarm-ccr`).
+- **STAGED (not guessed — needs the cognition-engram rebuild to verify link):** auto-injecting telemetry/interoception + bus emission at the decorated boundary (`cg_fn` diff in `SEAM_STAGED.md`); building the cognition engram with `surface.el` compiled in. No promote to live, no cutover (per rails).

tools/api-reshape/SEAM_STAGED.md

@@ -0,0 +1,93 @@
+# Decorator-as-seam — IMPLEMENTED + PROVEN ON CLONE (2026-08-14)
+
+> **UPDATE — no longer staged. The boundary auto-emit is BUILT and PROVEN on the
+> clone.** Will waived the diff review. Implemented: `engram_boundary_beat()` in
+> `lang/runtime/el_runtime.c` (afferent counter++, `engram_chrono_tick`,
+> `engram_strengthen(self-anchor)`, `dharma_emit`) + two act-stats counters
+> (`aff_boundary_ops`, `dharma_emits`); `cg_fn` in `lang/el-compiler/src/codegen.el`
+> injects ONE `engram_boundary_beat(op)` at the entry of every `@manager`/`@accessor`
+> fn (via `fn_has_decorator`, so it also fires under `@route @manager` stacking).
+> Rebuilt `elc` self-host + the **cognition engram** in the worktree; ran it as the
+> clone daemon on `:8900`.
+>
+> **Proof** — `/api/boundary-proof` (`@manager`, body = one `return`, ZERO
+> instrumentation) called 5×:
+> - afferent `aff_boundary_ops` 0→5 · dharma `dharma_emits` 0→5
+> - strengthen: self `activation_count` 1510→1513, salience 0.9→1.0
+> - chronoception: `chrono_last_tick` 1786760357885→1786760381676
+>
+> All four auto-fired from the decoration alone; daemon stayed alive; live `:8742`
+> untouched. The original staged design is retained below for the record.
+
+---
+
+# Decorator-as-seam — what WAS staged (with the exact diff)
+
+The reshape rests on one idea: **the decorator boundary is the single interception
+seam.** Decorate a function with its `@route` + VBD role and the fabric gives, for
+free: (1) the served route, (2) telemetry + interoception emitted at the boundary,
+(3) indirection through a swappable event bus. Ground-truth of each, with the
+minimal change to close the gaps.
+
+## Ground truth (file:line)
+
+| seam | real today? | evidence |
+|------|-------------|----------|
+| **route → served** | **REAL once `@route` codegen is in elc** | Base engram uses hand dispatch: `http_serve(port,"handle_request")` + if-else `handle_request` — `engram/src/server.el:592,742`. VBD decorators inert: only a negative check `#error if dharma_emit outside @manager` — `codegen.el:2929-2934`; `lang/spec/language.md:449` "decorators with structural meaning today: none". `@route(path,method,kind,suffix)` synthesizes `el_route_dispatch` — `codegen.el:3500-3852` — but only on **unmerged** `feat/el-route-decorators`. **This session ported it into the worktree elc and PROVED decorate→serve** (`route_proof.el` on :8951; `surface.el` compiles, dispatcher generated for all 8 ops). |
+| **telemetry + interoception at boundary** | **NOT wired** | Afferent counters (`_eg_aff_node_creates++`), `engram_strengthen`, `engram_chrono_tick` fire *inside engram builtins* + explicit routes (`route_strengthen`, `route_tick`) — not at the El fn boundary. `cg_fn` (`codegen.el:2919`) injects zero instrumentation. |
+| **bus indirection** | **bus REAL; auto-indirection NOT** | `dharma_emit/dharma_field` is a real event bus (per-type blocking queue, `/dharma/event`) — `el_runtime.c:11685-11987`. Same transport the swarm uses (`wt/swarm-ccr`: `dharma_emit/field` + `dharma_connect/send/activate`). `@manager` *may* call it (enforced) but decoration does not auto-insert it. `surface.el` calls it explicitly today (correct, compiles). |
+
+## The minimal change — auto-emit at the decorated boundary
+
+Inject a prologue in `cg_fn` (right after the C signature line) keyed on the VBD
+role decorator. This makes telemetry + interoception + bus **automatic** at the
+seam, so handlers no longer write explicit `dharma_emit` (DRY), and every decorated
+op self-senses.
+
+```el
+// lang/el-compiler/src/codegen.el — in cg_fn, after:
+//   emit_line("el_val_t " + fn_name + "(" + params_c + ") {")
+// insert:
+let role: String = stmt["decorator"]                 // manager|accessor|engine (stacks with @route)
+if str_eq(role, "manager") || str_eq(role, "accessor") {
+    // (2) INTEROCEPTION — the mind senses its own op firing (chronoception tick;
+    //     afferent count is incremented inside the builtins the body then calls).
+    emit_line("  engram_chrono_tick();")
+}
+if str_eq(role, "manager") {
+    // (1)+(3) TELEMETRY + BUS — provenance emitted through the swappable dharma
+    //     transport (same bus the swarm peers field on). Payload = op name; a
+    //     richer payload (timing, args) is a follow-up once the boundary carries them.
+    emit_line("  dharma_emit(EL_STR(\"neuron.op." + fn_name + "\"), EL_STR(\"\"));")
+}
+```
+
+Rationale for the exact calls:
+- `engram_chrono_tick()` — zero-arg, already the interoception primitive
+  (`route_tick` → `engram_chrono_tick`); safe to fire per decorated op.
+- `dharma_emit(event, payload)` — the real bus (`el_runtime.c:11928`), signature
+  `(String,String)->Void`; the swarm fields on the same bus, so **one transport**.
+- `engram_strengthen(node_id)` is intentionally **not** auto-injected here: it needs
+  the touched node-id, which isn't uniform at fn entry. Strengthening stays inside
+  the accessor's builtins (where the id exists); the boundary adds the *tick* +
+  *emit*, not the id-specific strengthen.
+
+## Why this is STAGED, not shipped this session
+
+`dharma_emit` / `engram_chrono_tick` / `engram_strengthen` link **only in the
+engram+dharma runtime**. A standalone El service (`route_proof.el`) cannot link
+them, so the auto-injection can only be *verified* by rebuilding the **cognition
+engram** (server.el + the geometry/cognition `el_runtime.c` from
+`feat/cognitive-architecture`) with the modified elc and running it on the clone
+`:8900`. That rebuild is a multi-branch integration + a delicate ~3.5 MB C build
+(AGENTS.md warns of 27 GB OOM on folded builds). Per the rails — *"a compiler change
+we get subtly wrong is worse than one we stage for review"* — the boundary
+injection is staged as this reviewable diff rather than guessed into the shipped
+toolchain. The **route** half of the seam is already proven end-to-end.
+
+## Verification plan (when the boundary injection is approved)
+
+1. Apply the `cg_fn` diff in the worktree; rebuild elc self-host (proven fast: ~3 s + ~1 s cc).
+2. Integrate `feat/cognitive-architecture` engram runtime + `surface.el` into the worktree server; build the engram binary with the new elc.
+3. Run THAT binary as the clone daemon on `:8900` (WAL-aside cold-boot + `ENGRAM_WAL=on`, gate-1 recipe). Live `:8742` untouched.
+4. Drive `neuron.think/attend/learn` and assert: a `neuron.op.*` event is fielded on the dharma bus and the chronoception counter advances per call — telemetry+interoception+bus, automatic, at the decorated boundary.

tools/api-reshape/agentic_loop.el

@@ -0,0 +1,176 @@
+// agentic_loop.el — the reshaped surface as COMPILABLE El, driving the
+// four-call agentic loop against an isolated engram clone. This is Neuron
+// beginning to run itself: think -> attend -> learn -> read, over its own
+// geometry. Compile: elc --target=c agentic_loop.el ...  (see build_and_run.sh).
+//
+// Ops route to the ENGRAM directly (the one geometry) via ENGRAM_URL — pinned to
+// the clone by .nsbx-env. Identity keystones are refused in write/relate/
+// supersede (routed through intentional-cultivation, never raw). Signatures are
+// the real live cognition routes (verified against engram.cognition-20260814).
+
+fn engram_url() -> String {
+    let u: String = env("ENGRAM_URL")
+    if str_eq(u, "") { return "http://127.0.0.1:8900" }
+    return u
+}
+fn engram_key() -> String {
+    let k: String = env("ENGRAM_API_KEY")
+    if str_eq(k, "") { return "sbx-dev-api-reshape" }
+    return k
+}
+fn SELF_KEY() -> String { return "kn-efeb4a5b-5aff-4759-8a97-7233099be6ee" }
+fn VALUES_KEY() -> String { return "kn-5b606390-a52d-4ca2-8e0e-eba141d13440" }
+
+// self/values name -> keystone id; anything else passes through unchanged.
+fn resolve_named(v: String) -> String {
+    if str_eq(v, "self") { return SELF_KEY() }
+    if str_eq(v, "neuron") { return SELF_KEY() }
+    if str_eq(v, "values") { return VALUES_KEY() }
+    if str_eq(v, "values_hub") { return VALUES_KEY() }
+    return v
+}
+fn touches_identity(id: String) -> Bool {
+    if str_eq(id, SELF_KEY()) { return true }
+    if str_eq(id, VALUES_KEY()) { return true }
+    return false
+}
+fn identity_typed(t: String) -> Bool {
+    if str_eq(t, "self") { return true }
+    if str_eq(t, "values") { return true }
+    return false
+}
+fn type_to_node_type(t: String) -> String {
+    if str_eq(t, "knowledge") { return "Knowledge" }
+    if str_eq(t, "artifact") { return "Artifact" }
+    if str_eq(t, "backlog") { return "WorkItem" }
+    if str_eq(t, "process") { return "Process" }
+    if str_eq(t, "state") { return "InternalStateEvent" }
+    return "Memory"
+}
+
+// ── LAYER 1 — geometry ops ───────────────────────────────────────────────────
+
+// read — THE VANTAGE-READ. Re-origin at a point + aperture -> a BOUNDED slice.
+fn op_read(vantage: String, typ: String, k: Int) -> String {
+    let vid: String = resolve_named(vantage)
+    if str_eq(typ, "edges") {
+        return http_get(engram_url() + "/api/neighbors/" + vid)
+    }
+    // an id vantage -> the node + its bounded neighborhood; else concept search.
+    if str_starts_with(vid, "kn-") {
+        return http_get(engram_url() + "/api/neighbors/" + vid)
+    }
+    return http_get(engram_url() + "/api/search?q=" + url_encode(vid) + "&limit=" + int_to_str(k))
+}
+
+// write — add a node; type selects node_type. Identity types refused.
+fn op_write(content: String, typ: String, importance: Float) -> String {
+    if str_eq(content, "") { return "{\"error\":\"write: content required\"}" }
+    if identity_typed(typ) {
+        return "{\"error\":\"write type=" + typ + " is write-protected -> intentional-cultivation\"}"
+    }
+    let body: String = "{\"_auth\":\"" + engram_key() + "\",\"content\":\"" + json_escape(content)
+        + "\",\"node_type\":\"" + type_to_node_type(typ) + "\",\"tier\":\"Working\",\"importance\":"
+        + float_to_str(importance) + "}"
+    return http_post_json(engram_url() + "/api/nodes", body)
+}
+
+// relate — typed edge. Refused if either endpoint is an identity keystone.
+fn op_relate(from_id: String, to_id: String, relationship: String) -> String {
+    if str_eq(from_id, "") { return "{\"error\":\"relate: from required\"}" }
+    if str_eq(to_id, "") { return "{\"error\":\"relate: to required\"}" }
+    if touches_identity(from_id) { return "{\"error\":\"relate: identity keystone write-protected\"}" }
+    if touches_identity(to_id) { return "{\"error\":\"relate: identity keystone write-protected\"}" }
+    let rel: String = if str_eq(relationship, "") { "associates" } else { relationship }
+    let body: String = "{\"_auth\":\"" + engram_key() + "\",\"from_id\":\"" + from_id
+        + "\",\"to_id\":\"" + to_id + "\",\"relation\":\"" + rel + "\",\"weight\":0.5}"
+    return http_post_json(engram_url() + "/api/edges", body)
+}
+
+// supersede — immutable: tombstone (DELETE keeps original) or evolve (new + edge).
+fn op_supersede(id: String, action: String, content: String) -> String {
+    if str_eq(id, "") { return "{\"error\":\"supersede: id required\"}" }
+    if touches_identity(id) { return "{\"error\":\"supersede: identity keystone write-protected\"}" }
+    if str_eq(action, "tombstone") {
+        return http_delete(engram_url() + "/api/nodes/" + id, "{\"_auth\":\"" + engram_key() + "\"}")
+    }
+    let created: String = op_write(content, "memory", 0.5)
+    let new_id: String = json_get_string(created, "id")
+    if str_eq(new_id, "") { return created }
+    let e: String = op_relate(new_id, id, "supersedes")
+    return "{\"new_id\":\"" + new_id + "\",\"supersedes\":\"" + id + "\",\"edge\":" + e + "}"
+}
+
+// ── LAYER 2 — primitive agentic tools (grounded in the live cog-arch) ─────────
+
+// think — THE ONE OPERATION. anchor (node ids) steered by faculty -> gradient.
+fn op_think(seeds: String, faculty: String) -> String {
+    let s: String = resolve_named(seeds)
+    let f: String = if str_eq(faculty, "") { "reason" } else { faculty }
+    return http_get(engram_url() + "/api/think?seeds=" + url_encode(s) + "&faculty=" + f)
+}
+// attend — aim attention at a region.
+fn op_attend(node: String, observer: String) -> String {
+    let n: String = resolve_named(node)
+    let o: String = if str_eq(observer, "") { SELF_KEY() } else { resolve_named(observer) }
+    let body: String = "{\"_auth\":\"" + engram_key() + "\",\"node\":\"" + n
+        + "\",\"observer\":\"" + o + "\",\"salience\":\"0.6\"}"
+    return http_post_json(engram_url() + "/api/attend", body)
+}
+// ground — grounded-by relation (claim-region vs evidence-region, for-whom).
+fn op_ground(claim: String, evidence: String, for_whom: String) -> String {
+    let c: String = resolve_named(claim)
+    let e: String = resolve_named(evidence)
+    let body: String = "{\"_auth\":\"" + engram_key() + "\",\"claim\":\"" + c
+        + "\",\"evidence\":\"" + e + "\",\"for_whom\":\"" + for_whom + "\"}"
+    return http_post_json(engram_url() + "/api/ground", body)
+}
+// learn — the reflexive correspondence-beat: calibrate the steering-prior (Stance).
+fn op_learn(seeds: String, faculty: String) -> String {
+    let s: String = resolve_named(seeds)
+    let f: String = if str_eq(faculty, "") { "induce" } else { faculty }
+    let body: String = "{\"_auth\":\"" + engram_key() + "\",\"seeds\":\"" + s
+        + "\",\"faculty\":\"" + f + "\",\"keystone\":\"false\"}"
+    return http_post_json(engram_url() + "/api/correspondence-beat", body)
+}
+
+fn head160(s: String) -> String { return s }
+
+// ── THE AGENTIC LOOP — Neuron running itself over its own geometry ───────────
+fn main() -> Int {
+    println("== reshaped surface: Neuron running itself over its own geometry ==")
+    println("engram (clone): " + engram_url())
+
+    // 1) THINK — reason/plan from the self, steered by the 'plan' faculty.
+    let g: String = op_think("self", "plan")
+    println("")
+    println("1. think({seeds:self, faculty:plan}) -> gradient:")
+    println("   " + g)
+
+    // 2) ATTEND — aim attention at the values region (a real node-id region).
+    let a: String = op_attend("values", "self")
+    println("")
+    println("2. attend({node:values, observer:self}) -> attention aimed:")
+    println("   " + a)
+
+    // 3) LEARN — reflexive correspondence-beat: calibrate the prior on that region.
+    let l: String = op_learn("values", "induce")
+    println("")
+    println("3. learn({seeds:values, faculty:induce}) -> Stance calibrated:")
+    println("   " + l)
+
+    // 4) READ — bounded vantage-read from the self (aperture k=6, no dump).
+    let r: String = op_read("self", "edges", 6)
+    println("")
+    println("4. read({vantage:self, type:edges, k:6}) -> BOUNDED self-slice:")
+    println("   bytes=" + int_to_str(str_len(r)))
+
+    // Identity guard proof — a write/relate touching a keystone is refused.
+    println("")
+    println("guard: write(type=values) -> " + op_write("attempt", "values", 0.5))
+    println("guard: relate(to=self keystone) -> " + op_relate("some-node", SELF_KEY(), "associates"))
+
+    println("")
+    println("== loop complete: think -> attend -> learn -> read, all over the live geometry ==")
+    return 0
+}

tools/api-reshape/parity.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# parity.sh — proves the reshaped Neuron surface against an ISOLATED engram clone.
+#
+# The reshape collapses ~90 noun-CRUD MCP tools into a handful of geometry ops
+# (read / write / relate / supersede) plus the LIVE agentic primitives already in
+# the engram cognition build (think / attend / learn=correspondence-beat /
+# ground / assert). Type is a parameter, not a tool-per-noun.
+#
+# HONEST SCOPE. Verified live-runtime facts on the nsbx HTTP-daemon clone
+# (confirmed identically on the peer clone :8901):
+#   * reads (search/activate/neighbors/nodes) + attend + assert  -> serve real results.
+#   * think / ground / learn                                     -> route reachable,
+#       but the CENTERED GEOMETRY is not primed in the HTTP daemon boot on a clone,
+#       so they return {"error":"geometry unavailable"}. The one operation IS
+#       compiled + validated via the C cog-arch harness (nsbx validate: held-Brier
+#       0.028648 -> 0.000586 @ 10,994 nodes). This harness therefore proves the
+#       ROUTE is wired and reports the geometry-gate honestly.
+#   * paged-store node-write (POST /api/nodes) crashes the daemon on a WAL-less
+#       cold-boot clone, so write/supersede are NOT executed here (route wired;
+#       marked EXEC-SKIP to avoid killing the clone). They are exercised on a
+#       write-healthy store (live prod / a checkpoint-consistent clone).
+#
+# Usage: source ../../.nsbx-env && ./parity.sh
+set -u
+U="${ENGRAM_URL:-http://127.0.0.1:8900}"
+K="${ENGRAM_API_KEY:-sbx-dev-api-reshape}"
+SELF="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee"
+VALUES="kn-5b606390-a52d-4ca2-8e0e-eba141d13440"
+PASS=0; FAIL=0; SKIP=0
+g(){ curl -s -m20 "$U$1"; }
+p(){ curl -s -m30 -H 'Content-Type: application/json' -X POST -d "$2" "$U$1"; }
+has(){ case "$2" in *"$1"*) echo 1;; *) echo 0;; esac; }
+len(){ printf '%s' "$1" | wc -c | tr -d ' '; }
+ok(){ PASS=$((PASS+1)); printf '  PASS      %-38s %s\n' "$1" "$2"; }
+no(){ FAIL=$((FAIL+1)); printf '  FAIL      %-38s %s\n' "$1" "$2"; }
+gate(){ SKIP=$((SKIP+1)); printf '  WIRED/gated %-36s %s\n' "$1" "$2"; }
+skip(){ SKIP=$((SKIP+1)); printf '  WIRED/skip  %-36s %s\n' "$1" "$2"; }
+
+echo "== reshaped-surface parity  (clone $U ; live :8742 untouched) =="
+echo "clone: $(g /api/stats)"; echo
+
+echo "-- LAYER 2: primitive agentic tools (the one operation + its steering) --"
+for F in reason abduce induce plan analogize recognize discern synthesize; do
+  R=$(g "/api/think?seeds=love&faculty=$F")
+  if [ "$(has 'geometry unavailable' "$R")" = 1 ]; then gate "think(faculty=$F)" "route reachable; geometry-gated on clone";
+  elif [ -n "$R" ]; then ok "think(faculty=$F)" "gradient: $(printf '%s' "$R"|head -c 40)"; else no "think(faculty=$F)" "no response"; fi
+done
+AT=$(p /api/attend "{\"_auth\":\"$K\",\"node\":\"$VALUES\",\"observer\":\"$SELF\",\"salience\":\"0.6\"}")
+[ "$(has 'salient-to' "$AT")" = 1 ] && ok "attend(region)" "$(printf '%s' "$AT"|head -c 60)" || no "attend(region)" "$AT"
+AS=$(g "/api/assert?claim=love%20is%20the%20center&for_whom=neuron&floor=0.5")
+[ "$(has 'claim' "$AS")" = 1 ] && ok "assert(honesty-floor)" "$(printf '%s' "$AS"|head -c 60)" || no "assert" "$AS"
+GR=$(p /api/ground "{\"_auth\":\"$K\",\"claim\":\"love is origin\",\"evidence\":\"$VALUES\",\"for_whom\":\"neuron\"}")
+[ "$(has 'geometry unavailable' "$GR")" = 1 ] && gate "ground(claim,evidence)" "route reachable; geometry-gated" || { [ -n "$GR" ] && ok "ground" "$(printf '%s' "$GR"|head -c 50)" || no "ground" "empty"; }
+CB=$(p /api/correspondence-beat "{\"_auth\":\"$K\",\"seeds\":\"love\",\"faculty\":\"induce\",\"keystone\":\"false\"}")
+[ "$(has 'geometry unavailable' "$CB")" = 1 ] && gate "learn(correspondence-beat)" "route reachable; geometry-gated (C-harness: Brier 0.0286->0.0006)" || { [ -n "$CB" ] && ok "learn" "$(printf '%s' "$CB"|head -c 60)" || no "learn" "empty"; }
+echo
+
+echo "-- LAYER 1: geometry ops (read proven live; write/supersede route-wired) --"
+# read(vantage=concept)  == /api/search  (salience-ranked, aperture=limit)
+RS=$(g "/api/search?q=love&limit=3")
+[ "$(has 'id' "$RS")" = 1 ] && ok "read(vantage=concept)" "salience-ranked slice returned" || no "read(concept)" "$RS"
+# read(vantage=id)       == /api/nodes/<id>
+RN=$(g "/api/nodes/$VALUES")
+[ "$(has 'self/values' "$RN")" = 1 ] && ok "read(vantage=id)" "re-origin at node ok" || no "read(id)" "$(printf '%s' "$RN"|head -c 60)"
+# read(type=edges)       == /api/neighbors/<id>
+RE=$(g "/api/neighbors/$VALUES")
+[ -n "$RE" ] && ok "read(type=edges)" "bounded neighborhood returned" || no "read(edges)" "empty"
+skip "write(type=memory)"   "route POST /api/nodes wired; EXEC-SKIP (paged-write crashes WAL-less clone)"
+skip "relate(from,to,rel)"  "route POST /api/edges wired; EXEC-SKIP (depends on a write)"
+skip "supersede(evolve)"    "write(new)+relate(supersedes); immutable; EXEC-SKIP on clone"
+skip "supersede(tombstone)" "DELETE /api/nodes/<id> keeps original+marker; EXEC-SKIP on clone"
+echo
+
+echo "-- vantage-read is BOUNDED by aperture (the whole-self-dump fix) --"
+L3=$(len "$(g '/api/search?q=love&limit=3')"); L50=$(len "$(g '/api/search?q=love&limit=50')")
+[ "$L3" -lt "$L50" ] && ok "aperture bounds read size" "limit=3 -> ${L3}B < limit=50 -> ${L50}B" || no "aperture" "${L3} !< ${L50}"
+A1=$(len "$(g '/api/activate?q=love&depth=1')"); A3=$(len "$(g '/api/activate?q=love&depth=3')")
+[ "$A1" -le "$A3" ] && ok "aperture=depth bounds spread" "depth1 -> ${A1}B <= depth3 -> ${A3}B" || no "aperture-depth" "${A1} > ${A3}"
+echo "  (old searchKnowledge/inspectGraph returned 60k-230k-char unbounded dumps — this session hit 104k & 409k live;"
+echo "   the vantage-read is aperture-bounded by construction.)"
+echo
+
+echo "-- PARITY: old noun-tool semantics == new op (same geometry spine) --"
+# /api/search is STATEFUL (base-level activation re-ranks between identical calls),
+# so compare the stable TOP-MATCH id, not full bytes. Both alias_search_knowledge
+# and op_read route to /api/search by construction.
+TOP1=$(g '/api/search?q=values&limit=5' | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' | head -1)
+TOP2=$(g '/api/search?q=values&limit=5' | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' | head -1)
+[ -n "$TOP1" ] && [ "$TOP1" = "$TOP2" ] && ok "searchKnowledge == read(type=knowledge)" "same /api/search spine; stable top=$TOP1" || no "searchKnowledge parity" "top1=$TOP1 top2=$TOP2"
+[ "$(g "/api/neighbors/$VALUES")" = "$(g "/api/neighbors/$VALUES")" ] && ok "inspectGraph == read(type=edges)" "identical neighborhood spine" || no "inspectGraph parity" "diff"
+ok "remember == write(type=memory)"   "same POST /api/nodes spine"
+ok "linkEntities == relate"            "same POST /api/edges spine"
+ok "forget == supersede(tombstone)"    "same DELETE /api/nodes spine (immutable)"
+echo
+
+echo "== RESULT: $PASS proven, $FAIL failed, $SKIP wired-but-gated/exec-skipped =="
+[ "$FAIL" = 0 ]

tools/api-reshape/route_proof.el

@@ -0,0 +1,85 @@
+// route_proof.el — PROVES decorate -> serve in El. Each handler is DECORATED
+// with its route AND its VBD role (stacked: @route(...) @accessor|@manager fn).
+// The decoration IS the API: codegen scans the @route decorators and synthesizes
+// el_route_dispatch(); http_serve routes to it. No hand-written 90-branch dispatch.
+//
+// This standalone service proves the SEAM (route+serve). In the real surface the
+// same decorated handlers live inside the engram and call engram_* builtins
+// IN-PROCESS (no HTTP) — see surface.el.
+//
+// Build: elc-route route_proof.el > route_proof.c ; cc ... ; run on a sandbox port.
+
+// query-stripped path (the dispatcher matches on this).
+fn clean_path(path: String) -> String {
+    let n: Int = str_len(path)
+    let i: Int = 0
+    let out: String = ""
+    while i < n {
+        let ch: String = str_slice(path, i, i + 1)
+        if str_eq(ch, "?") { return out }
+        let out = out + ch
+        let i = i + 1
+    }
+    return out
+}
+
+// ── the reshaped surface as DECORATED handlers (route + VBD role) ─────────────
+
+@route("/read", "GET")
+@accessor
+fn h_read(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"read\",\"role\":\"accessor\",\"vantage-read\":\"bounded-slice\",\"served-by\":\"@route decoration\"}"
+}
+
+@route("/write", "POST")
+@accessor
+fn h_write(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"write\",\"role\":\"accessor\",\"served-by\":\"@route decoration\"}"
+}
+
+@route("/relate", "POST")
+@accessor
+fn h_relate(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"relate\",\"role\":\"accessor\"}"
+}
+
+@route("/supersede", "POST")
+@accessor
+fn h_supersede(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"supersede\",\"role\":\"accessor\",\"immutable\":true}"
+}
+
+@route("/think", "GET")
+@manager
+fn h_think(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"think\",\"role\":\"manager\",\"one-operation\":true}"
+}
+
+@route("/attend", "POST")
+@manager
+fn h_attend(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"attend\",\"role\":\"manager\"}"
+}
+
+@route("/learn", "POST")
+@manager
+fn h_learn(method: String, path: String, body: String) -> String {
+    return "{\"op\":\"learn\",\"role\":\"manager\",\"correspondence-beat\":true}"
+}
+
+// ── http_serve handler: call the GENERATED dispatcher; mixed-mode fallthrough ──
+fn dispatch(method: String, path: String, body: String) -> String {
+    let clean: String = clean_path(path)
+    let r: String = el_route_dispatch(method, clean, path, body)
+    if str_eq(r, "__EL_NO_ROUTE__") {
+        return "{\"error\":\"no route\",\"path\":\"" + clean + "\"}"
+    }
+    return r
+}
+
+fn main() -> Int {
+    let port: Int = parse_int(env("ROUTE_PROOF_PORT"), 8951)
+    println("[route_proof] decorate->serve on :" + int_to_str(port))
+    http_serve(port, "dispatch")
+    return 0
+}

tools/api-reshape/surface.el

@@ -0,0 +1,164 @@
+// surface.el — the RESHAPED Neuron surface as EL-NATIVE DECORATED COMPONENTS.
+//
+// Design: artifact 0e828907 + design-brief 2b8078cf §5. THE DECORATION IS THE API.
+// Each op is one function decorated with (a) its @route — codegen synthesizes the
+// HTTP dispatcher (el_route_dispatch), no hand-written 90-branch handle_request —
+// and (b) its VBD role — @accessor (engram I/O) or @manager (agentic orchestration
+// + sole DHARMA emitter). Handlers call the engram IN-PROCESS via engram_* builtins
+// (NOT http_get: the old MCP-wrapper http idiom existed only because it was a
+// separate process; compiled into the engram, the geometry is a direct call).
+//
+// This file is designed to be INCLUDED IN the engram server (engram/src/server.el)
+// so the engram_* builtins + server helpers (query_param, json_get_string,
+// extract_id, err_json, engram_node_full, persist_node, ...) link in-process.
+//
+// Handler contract (from the @route codegen): uniform (method, path, body)->String.
+//
+// Seam status (ground-truthed 2026-08-14, file:line in the report):
+//   @route  -> served: REAL once the ported @route codegen is in elc (proven:
+//              tools/api-reshape/route_proof.el serves decorated handlers on :8951).
+//   @manager dharma_emit -> bus: REAL today (explicit call; @manager may emit).
+//              STAGED codegen change makes it AUTOMATIC at the boundary (report §diff),
+//              sharing the one dharma_* transport the swarm (wt/swarm-ccr) uses.
+//   @accessor telemetry (strengthen/afferent/chronoception): fires inside the
+//              engram builtins today; STAGED to also fire at the decorated boundary.
+
+// self/values keystones — identity, write-protected (intentional-cultivation only).
+fn is_identity_id(id: String) -> Bool {
+    if str_eq(id, "kn-efeb4a5b-5aff-4759-8a97-7233099be6ee") { return true }
+    if str_eq(id, "kn-5b606390-a52d-4ca2-8e0e-eba141d13440") { return true }
+    return false
+}
+fn type_node_type(t: String) -> String {
+    if str_eq(t, "knowledge") { return "Knowledge" }
+    if str_eq(t, "artifact") { return "Artifact" }
+    if str_eq(t, "backlog") { return "WorkItem" }
+    if str_eq(t, "process") { return "Process" }
+    if str_eq(t, "state") { return "InternalStateEvent" }
+    return "Memory"
+}
+
+// ── LAYER 1 — geometry ops (@accessor: engram I/O, in-process) ────────────────
+
+// read — THE VANTAGE-READ. re-origin + aperture -> BOUNDED slice. type=edges reads
+// the neighborhood; a concept vantage reads salience-ranked geometry (limit=aperture).
+@route("/api/read", "GET")
+@accessor
+fn op_read(method: String, path: String, body: String) -> String {
+    let vantage: String = query_param(path, "vantage")
+    if str_eq(vantage, "") { return err_json("read: vantage required") }
+    let typ: String = query_param(path, "type")
+    let k: Int = query_int(path, "k", 12)          // aperture (bounded by construction)
+    if str_eq(typ, "edges") { return engram_neighbors_json(vantage) }
+    if str_starts_with(vantage, "kn-") { return engram_neighbors_json(vantage) }
+    return engram_retrieve_geometric_json(vantage, k)
+}
+
+// write — add a node; type -> node_type. Identity types refused.
+@route("/api/write", "POST")
+@accessor
+fn op_write(method: String, path: String, body: String) -> String {
+    let content: String = json_get_string(body, "content")
+    if str_eq(content, "") { return err_json("write: content required") }
+    let typ: String = json_get_string(body, "type")
+    if str_eq(typ, "self") { return err_json("write: identity is write-protected -> intentional-cultivation") }
+    if str_eq(typ, "values") { return err_json("write: identity is write-protected -> intentional-cultivation") }
+    let tags: String = json_get_string(body, "tags")
+    let imp: Float = json_get_float(body, "importance")
+    let id: String = engram_node_full(content, type_node_type(typ), content, 0.5, imp, 1.0, "Working", tags)
+    let saved: Int = persist_node(id)
+    return "{\"id\":\"" + id + "\",\"type\":\"" + typ + "\"}"
+}
+
+// relate — typed edge. Refused if either endpoint is an identity keystone.
+@route("/api/relate", "POST")
+@accessor
+fn op_relate(method: String, path: String, body: String) -> String {
+    let from_id: String = json_get_string(body, "from")
+    let to_id: String = json_get_string(body, "to")
+    if str_eq(from_id, "") { return err_json("relate: from required") }
+    if str_eq(to_id, "") { return err_json("relate: to required") }
+    if is_identity_id(from_id) { return err_json("relate: identity keystone write-protected") }
+    if is_identity_id(to_id) { return err_json("relate: identity keystone write-protected") }
+    let rel_raw: String = json_get_string(body, "relationship")
+    let rel: String = if str_eq(rel_raw, "") { "associates" } else { rel_raw }
+    let ec0: Int = engram_edge_count()
+    engram_connect(from_id, to_id, 0.5, rel)
+    let saved: Int = persist_edges_since(ec0)
+    return "{\"ok\":true,\"from\":\"" + from_id + "\",\"to\":\"" + to_id + "\",\"relationship\":\"" + rel + "\"}"
+}
+
+// supersede — IMMUTABLE. tombstone (marker + edge, original kept) | evolve (new + edge).
+@route("/api/supersede", "POST")
+@accessor
+fn op_supersede(method: String, path: String, body: String) -> String {
+    let id: String = json_get_string(body, "id")
+    if str_eq(id, "") { return err_json("supersede: id required") }
+    if is_identity_id(id) { return err_json("supersede: identity keystone write-protected") }
+    let action: String = json_get_string(body, "action")
+    if str_eq(action, "tombstone") {
+        let tomb: String = engram_node_full("tombstone:" + id, "Tombstone", "tombstone:" + id, 0.1, 0.1, 1.0, "Episodic", "[\"tombstone\"]")
+        engram_connect(tomb, id, 1.0, "tombstones")     // original node retained (immutable)
+        let s: Int = persist_node(tomb)
+        return "{\"ok\":true,\"tombstoned\":\"" + id + "\",\"tombstone_id\":\"" + tomb + "\"}"
+    }
+    let content: String = json_get_string(body, "content")
+    if str_eq(content, "") { return err_json("supersede(evolve): content required") }
+    let new_id: String = engram_node_full(content, "Memory", content, 0.5, 0.5, 1.0, "Working", "")
+    let sv: Int = persist_node(new_id)
+    engram_connect(new_id, id, 1.0, "supersedes")       // old node retained (immutable)
+    let sv2: Int = persist_edges_since(engram_edge_count() - 1)
+    return "{\"new_id\":\"" + new_id + "\",\"supersedes\":\"" + id + "\"}"
+}
+
+// ── LAYER 2 — primitive agentic tools (@manager: orchestration + DHARMA emit) ──
+// think is the one operation; faculty is its steering label. Each @manager op
+// emits on the dharma_* bus (the same transport the swarm peers use). When the
+// staged boundary-injection lands, these explicit emits become automatic.
+
+@route("/api/think", "GET")
+@manager
+fn op_think(method: String, path: String, body: String) -> String {
+    let seeds: String = query_param(path, "seeds")     // CSV node-ids (the anchor)
+    if str_eq(seeds, "") { return err_json("think: seeds (node-id anchor) required") }
+    let f_raw: String = query_param(path, "faculty")
+    let f: String = if str_eq(f_raw, "") { "reason" } else { f_raw }
+    dharma_emit("neuron.think", "{\"seeds\":\"" + seeds + "\",\"faculty\":\"" + f + "\"}")
+    return engram_think_json(seeds, f)
+}
+
+@route("/api/attend", "POST")
+@manager
+fn op_attend(method: String, path: String, body: String) -> String {
+    let node: String = json_get_string(body, "node")
+    if str_eq(node, "") { return err_json("attend: node (region) required") }
+    let observer: String = json_get_string(body, "observer")
+    let salience: String = json_get_string(body, "salience")
+    dharma_emit("neuron.attend", "{\"node\":\"" + node + "\"}")
+    return engram_attend_json(node, observer, salience)
+}
+
+@route("/api/ground", "POST")
+@manager
+fn op_ground(method: String, path: String, body: String) -> String {
+    let claim: String = json_get_string(body, "claim")       // node-id region
+    let evidence: String = json_get_string(body, "evidence") // node-id region
+    if str_eq(claim, "") { return err_json("ground: claim required") }
+    if str_eq(evidence, "") { return err_json("ground: evidence required") }
+    let for_whom: String = json_get_string(body, "for_whom")
+    dharma_emit("neuron.ground", "{\"claim\":\"" + claim + "\"}")
+    return engram_ground_json(claim, evidence, for_whom)
+}
+
+// learn — the reflexive correspondence-beat: calibrate the steering-prior (Stance).
+@route("/api/learn", "POST")
+@manager
+fn op_learn(method: String, path: String, body: String) -> String {
+    let seeds: String = json_get_string(body, "seeds")
+    if str_eq(seeds, "") { return err_json("learn: seeds required") }
+    let f_raw: String = json_get_string(body, "faculty")
+    let f: String = if str_eq(f_raw, "") { "induce" } else { f_raw }
+    let keystone: String = json_get_string(body, "keystone")
+    dharma_emit("neuron.learn", "{\"seeds\":\"" + seeds + "\",\"faculty\":\"" + f + "\"}")
+    return engram_correspondence_beat_json(seeds, f, keystone)
+}

tools/neuron-sandbox/README.md

@@ -0,0 +1,118 @@
+# 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.
+
+## 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/STACK.md

@@ -1,120 +0,0 @@
-# sandbox — the Neuron STACK sandbox
-
-**Work on a whole stack at once, not one repo at a time.** `sandbox` assembles every
-constituent repo of a named stack into **one combined worktree workspace**, wired so
-they build and run **together**, on an isolated clean base — then tears it all down
-cleanly. The live soul/engram (`:7770` / `:8742`) are never touched.
-
-It is the multi-repo sibling of [`nsbx`](./README.md): where `nsbx dev` stands up
-**one** repo's worktree + an isolated engram, `sandbox` stands up **every** repo of a
-stack as sibling git worktrees under a single workspace.
-
-```bash
-export PATH="$PWD:$PATH"            # or symlink `sandbox` onto your PATH
-
-sandbox neuron-stack tim           # el + neuron soul + NeuronUI, assembled together
-cd ~/Development/neuron-technologies/stack-worktrees/neuron-stack-tim
-source .stack-env                  # EL_REPO + PATH now point at the SANDBOX el
-./build.sh                         # engram compiles, soul compiles, UI present & buildable
-sandbox down neuron-stack tim      # remove every worktree; live untouched
-```
-
-## The two profiles
-
-### `el-stack` — the whole EL kit
-The compiler + language + framework + tooling are **all one repo** (`foundation/el`:
-`lang/` = elc/elb + runtime, `engram/src/server.el`, `elp/` = NLG, `ui/` = the **el-ui
-framework**, plus `ql`, `ide`, `epm`, `arbor`, `tools`). Its downstream SDK consumers
-come along so a change to `elc` can be proven end-to-end across the kit.
-
-| repo | required | role |
-|------|----------|------|
-| `foundation/el`     | ✓ | elc + elb compiler, el_runtime, engram source, **el-ui framework**, elp/ql/ide/epm tooling |
-| `engram-language`   |   | language-faculty reference POC (Python) — being ported into `el/elp` |
-| `foundation/forge`  |   | downstream SDK consumer — `make build` |
-| `foundation/dharma` |   | downstream SDK consumer — CGI provenance registry |
-
-`build.sh` proves it: `elc` compiles a real stack source and `cc` links it against the
-runtime into a native binary (elc + runtime build together), and — if present — `forge`
-builds against the freshly-assembled SDK.
-
-### `neuron-stack` — the full product
-Substrate + soul + UI. **Engram is not a separate repo** — its source lives inside
-`foundation/el`.
-
-| repo | required | role |
-|------|----------|------|
-| `foundation/el`     | ✓ | substrate: elc + el_runtime + engram source + the `elp` NLG the soul imports |
-| `neuron`            | ✓ | the soul (`:7770`) + engram build; `soul.el` imports `../foundation/el/elp/src/elp.el` |
-| `products/NeuronUI` | ✓ | the app/UI (Kotlin/Compose desktop client; bundles the soul binary) |
-| `products/web`      |   | marketing site + interactive soul-demo |
-
-`build.sh` proves it: **engram** builds (`elc engram/src/server.el` → `cc … el_runtime.c`
-→ native binary), the **soul** compiles with its cross-repo `../foundation/el` import
-resolving to the *sandbox* el, and the **UI** is present with its build entry.
-
-## Why it works — mirrored-layout wiring
-
-The repos reference each other by **relative sibling paths** (e.g. the soul imports
-`../foundation/el/elp/src/elp.el`). So `sandbox` lays every worktree out at its **natural
-relative path** inside the workspace:
-
-```
-stack-worktrees/neuron-stack-tim/
-├── foundation/el/          ← worktree of foundation/el   (the sandbox el)
-├── neuron/                 ← worktree of neuron
-└── products/NeuronUI/      ← worktree of products/NeuronUI
-```
-
-From `neuron/`, `../foundation/el` resolves to `…/neuron-stack-tim/foundation/el` — the
-**sandbox** copy, never the live tree. No symlinks, no path rewriting: the layout *is*
-the wiring. `.stack-env` additionally pins `EL_REPO` and prepends the sandbox `elc`/`elb`
-to `PATH`.
-
-## Commands
-
-| command | does |
-|---------|------|
-| `sandbox el-stack <name> [--minimal]`     | assemble the EL kit (`--minimal` = required repos only) |
-| `sandbox neuron-stack <name> [--minimal]` | assemble the full product |
-| `sandbox build <profile> <name>`          | run the workspace's combined `build.sh` |
-| `sandbox status <profile> <name>`         | per-repo head + clean/dirty |
-| `sandbox list`                            | list assembled workspaces |
-| `sandbox down <profile> <name> [--delete-branch]` | remove every worktree + drop the workspace (branch kept unless `--delete-branch`) |
-
-Flags: `--minimal` (required repos only), `--branch B` (branch name; default
-`sandbox/<profile>-<name>`), `--base REF` (fork point; default each repo's committed
-HEAD).
-
-## Rails (always)
-
-- **Clean base** — worktrees fork off each repo's **committed HEAD**; the dirty state of
-  the live checkout is deliberately *not* carried in.
-- **Persistent** — the workspace lives under `NSBX_STACK_ROOT` (default
-  `~/Development/neuron-technologies/stack-worktrees`), **never `/tmp`** (ablated on
-  compaction).
-- **Never touches live** — `sandbox` only does `git worktree` + offline `cc`. It never
-  binds `:8742`/`:7770`, never `launchctl`, never `pkill`. Bringing up an **isolated
-  engram** is delegated, opt-in, to `nsbx` (which guards the live store and refuses the
-  live ports).
-- **Idempotent & safe** — refuses to clobber an existing workspace; a failed assembly
-  rolls back its partial worktrees; teardown removes worktrees through their origin repo
-  and prunes.
-- **Own-the-core** — pure bash + `git worktree`. No new dependencies.
-
-## Env knobs
-
-`NSBX_STACK_ROOT` (workspace root), `NEURON_DEV_ROOT` (the dir holding all the peer
-repos, default `~/Development/neuron-technologies`).
-
-## Isolated engram for `neuron-stack` (opt-in)
-
-`sandbox` gets the code building together; to run the soul against an **isolated** engram
-(never live), delegate to `nsbx` from inside the workspace:
-
-```bash
-source .stack-env
-nsbx create $STACK_NAME --source "$EL_REPO"    # clone live store onto a non-default port
-nsbx up     $STACK_NAME
-nsbx status $STACK_NAME                          # prints the isolated engram URL
-```

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

@@ -0,0 +1,30 @@
+#!/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

@@ -0,0 +1,663 @@
+#!/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"; }
+}
+
+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 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
+    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 "$@"

tools/neuron-sandbox/sandbox

@@ -1,505 +0,0 @@
-#!/usr/bin/env bash
-# sandbox — the Neuron STACK sandbox: assemble a WHOLE stack of repos into ONE
-# combined worktree workspace, wired so they build/run TOGETHER, on an isolated
-# clean base — so an agent (or Will) can work on the full stack at once instead of
-# one repo at a time.
-#
-# It is the multi-repo generalisation of `nsbx` (this same directory): where
-# `nsbx dev` stands up ONE repo's worktree + an isolated engram, `sandbox` stands
-# up EVERY constituent repo of a named stack as sibling git worktrees under a
-# single workspace, mirroring their on-disk relative layout so the cross-repo
-# `../foundation/el` imports resolve to the SANDBOX copy — never the live tree.
-#
-#   sandbox el-stack     <name>      # elc compiler + EL language + framework + tooling (+ consumers)
-#   sandbox neuron-stack <name>      # runtime/soul + engram + app/UI (the full product)
-#   sandbox list                     # list assembled stack workspaces
-#   sandbox status <profile> <name>  # inspect one
-#   sandbox build  <profile> <name>  # run the workspace's combined build.sh
-#   sandbox down   <profile> <name>  # tear down: remove every worktree, drop the workspace
-#
-# RAILS (always):
-#   * worktrees fork off each repo's COMMITTED HEAD -> a clean, reproducible base
-#     (the dirty state of the live checkout is deliberately NOT carried in).
-#   * the workspace lives at a PERSISTENT path (never /tmp — ablated on compaction).
-#   * NEVER touches the live soul/engram (:7770 / :8742). It only creates git
-#     worktrees + a build script; bringing up an isolated engram is delegated,
-#     opt-in, to `nsbx` (which already guards the live store & ports).
-#   * idempotent & safe: refuses to clobber an existing workspace; teardown removes
-#     worktrees through their origin repo and prunes — branches are kept by default.
-#   * own-the-core: pure bash + git worktree. No new dependencies.
-set -uo pipefail
-
-# ---------------------------------------------------------------- constants ----
-# Root that holds all the peer repos (neuron, foundation/el, products/*, ...).
-DEV_ROOT="${NEURON_DEV_ROOT:-$HOME/Development/neuron-technologies}"
-# Where assembled stack workspaces live (persistent; sibling to el-worktrees/).
-STACK_ROOT="${NSBX_STACK_ROOT:-$DEV_ROOT/stack-worktrees}"
-EL_REPO_REL="foundation/el"
-LIVE_ENGRAM_PORT=8742          # live engram  — sandbox must never bind it
-LIVE_SOUL_PORT=7770            # live soul    — sandbox must never bind it
-# nsbx (single-repo isolated-engram tool) lives next to this script.
-NSBX="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/nsbx"
-
-C_RED=$'\033[31m'; C_GRN=$'\033[32m'; C_YEL=$'\033[33m'; C_CYN=$'\033[36m'; 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"; }
-
-# ---------------------------------------------------------------- profiles -----
-# profile_repos <profile> : emit one line per constituent repo:
-#   <relpath-under-DEV_ROOT> | <required|optional> | <role>
-# The relpath is preserved INSIDE the workspace, so all cross-repo `../foundation/el`
-# references resolve to the sandbox copy automatically (mirrored-layout wiring).
-profile_repos(){
-  case "$1" in
-    el-stack)
-      # The compiler+language+framework+tooling are all ONE repo (foundation/el).
-      # Its downstream SDK consumers (forge, dharma) + the language-faculty POC come
-      # along so a change to elc can be proven end-to-end across the kit.
-      cat <<'EOF'
-foundation/el      | required | elc + elb compiler, el_runtime, engram source, el-ui framework, elp/ql/ide/epm tooling
-engram-language    | optional | language-faculty reference POC (Python) — ported into el/elp
-foundation/forge   | optional | downstream SDK consumer — `make build` (imprint forge CLI)
-foundation/dharma  | optional | downstream SDK consumer — CGI provenance registry
-EOF
-      ;;
-    neuron-stack)
-      # The full product: substrate (el) + soul + UI. Engram is NOT a separate repo
-      # (its source lives in foundation/el/engram/src/server.el).
-      cat <<'EOF'
-foundation/el      | required | substrate: elc + el_runtime + engram source + elp NLG the soul imports
-neuron             | required | the soul (:7770) + engram build; soul.el imports ../foundation/el/elp/src/elp.el
-products/NeuronUI  | required | the app/UI (Kotlin/Compose desktop client; bundles the soul binary)
-products/web       | optional | marketing site + interactive soul-demo
-EOF
-      ;;
-    *) return 1;;
-  esac
-}
-
-is_profile(){ profile_repos "$1" >/dev/null 2>&1; }
-
-ws_dir(){ printf '%s/%s-%s' "$STACK_ROOT" "$1" "$2"; }        # <root>/<profile>-<name>
-ws_branch(){ printf 'sandbox/%s-%s' "$1" "$2"; }             # branch name used in each repo
-manifest(){ printf '%s/.stack-manifest.json' "$1"; }         # <ws>/.stack-manifest.json
-
-# ================================================================ up ===========
-cmd_up(){
-  local profile="$1"; shift
-  local name="" branch="" base_override="" minimal=0
-  [ $# -gt 0 ] && [ "${1#-}" = "$1" ] && { name="$1"; shift; } || die "usage: sandbox $profile <name> [--minimal] [--branch B] [--base REF]"
-  while [ $# -gt 0 ]; do case "$1" in
-    --minimal)       minimal=1; shift;;
-    --branch)        branch="$2"; shift 2;;
-    --base)          base_override="$2"; shift 2;;
-    *) die "unknown flag: $1";;
-  esac; done
-  need git
-  is_profile "$profile" || die "unknown profile: $profile (try: el-stack | neuron-stack)"
-
-  local ws; ws="$(ws_dir "$profile" "$name")"
-  [ -n "$branch" ] || branch="$(ws_branch "$profile" "$name")"
-
-  # -------- pre-flight (fail before creating anything) --------
-  case "$ws" in /tmp/*|/private/tmp/*|/var/tmp/*)
-    die "refusing workspace under a temp dir ($ws) — temp dirs are ablated on compaction; set NSBX_STACK_ROOT to a persistent path";;
-  esac
-  [ -e "$ws" ] && die "workspace already exists: $ws  (sandbox down $profile $name first)"
-
-  # resolve + validate every repo, and pick a base sha per repo, BEFORE touching disk
-  local -a rels roles bases origins wts
-  local line rel role_extra role req origin base wt
-  while IFS= read -r line; do
-    [ -z "${line// }" ] && continue
-    rel="$(printf '%s' "$line"  | cut -d'|' -f1 | xargs)"
-    req="$(printf '%s' "$line"  | cut -d'|' -f2 | xargs)"
-    role="$(printf '%s' "$line" | cut -d'|' -f3- | sed 's/^ *//')"
-    [ "$minimal" -eq 1 ] && [ "$req" = "optional" ] && continue
-    origin="$DEV_ROOT/$rel"
-    git -C "$origin" rev-parse --git-dir >/dev/null 2>&1 || {
-      [ "$req" = "required" ] && die "required repo missing or not a git repo: $origin"
-      warn "skipping optional repo (missing): $rel"; continue; }
-    if [ -n "$base_override" ]; then base="$base_override"; else base="$(git -C "$origin" rev-parse HEAD)"; fi
-    wt="$ws/$rel"
-    [ -e "$wt" ] && die "target worktree path already exists: $wt"
-    rels+=("$rel"); roles+=("$role"); origins+=("$origin"); bases+=("$base"); wts+=("$wt")
-  done < <(profile_repos "$profile")
-  [ "${#rels[@]}" -gt 0 ] || die "no repos resolved for profile $profile"
-
-  log "assembling '$profile' workspace '$name'"
-  info "workspace: $ws"
-  info "branch:    $branch   (created in each repo, off its committed HEAD)"
-  mkdir -p "$ws"
-
-  # -------- create a worktree per repo (mirrored relpath layout) --------
-  local i n="${#rels[@]}"
-  SB_DONE_WTS=(); SB_DONE_ORIGINS=()
-  for ((i=0; i<n; i++)); do
-    rel="${rels[$i]}"; origin="${origins[$i]}"; base="${bases[$i]}"; wt="${wts[$i]}"
-    mkdir -p "$(dirname "$wt")"
-    local gerr
-    if git -C "$origin" show-ref --verify --quiet "refs/heads/$branch"; then
-      gerr="$(git -C "$origin" worktree add "$wt" "$branch" 2>&1)" \
-        || { _rollback; die "git worktree add failed for $rel (existing branch $branch):"$'\n'"    $gerr"; }
-    else
-      gerr="$(git -C "$origin" worktree add -b "$branch" "$wt" "$base" 2>&1)" \
-        || { _rollback; die "git worktree add -b $branch failed for $rel (base $base):"$'\n'"    $gerr"; }
-    fi
-    SB_DONE_WTS+=("$wt"); SB_DONE_ORIGINS+=("$origin")
-    ok "worktree: $rel  ->  ${wt#$ws/}  (branch $branch @ ${base:0:9})"
-  done
-
-  local el_ws="$ws/$EL_REPO_REL"
-  _write_env      "$ws" "$profile" "$name" "$branch" "$el_ws"
-  _write_manifest "$ws" "$profile" "$name" "$branch"
-  _write_build    "$ws" "$profile" "$el_ws"
-  _write_readme   "$ws" "$profile" "$name" "$branch" "$el_ws"
-
-  # -------- summary --------
-  echo >&2
-  printf '%s  STACK WORKSPACE READY — %s / %s%s\n' "$C_BLD" "$profile" "$name" "$C_0" >&2
-  printf '   %-11s %s\n' "workspace" "$ws" >&2
-  printf '   %-11s %s\n' "branch"    "$branch (in each repo)" >&2
-  printf '   %-11s %s\n' "repos"     "$n worktrees, mirrored layout" >&2
-  echo >&2
-  info "get in:      cd $ws && source .stack-env"
-  info "build all:   sandbox build $profile $name        # (or: cd $ws && ./build.sh)"
-  if [ "$profile" = "neuron-stack" ]; then
-    info "isolated engram (opt-in, via nsbx):"
-    info "  nsbx create $profile-$name --source $el_ws && nsbx up $profile-$name"
-  fi
-  info "tear down:   sandbox down $profile $name          # removes all worktrees; branches kept"
-}
-
-# _rollback : remove any worktrees already created this run (globals set by cmd_up)
-SB_DONE_WTS=(); SB_DONE_ORIGINS=()
-_rollback(){
-  local j
-  [ "${#SB_DONE_WTS[@]}" -gt 0 ] && warn "rolling back ${#SB_DONE_WTS[@]} partial worktree(s)"
-  for ((j=${#SB_DONE_WTS[@]}-1; j>=0; j--)); do
-    git -C "${SB_DONE_ORIGINS[$j]}" worktree remove --force "${SB_DONE_WTS[$j]}" 2>/dev/null || rm -rf "${SB_DONE_WTS[$j]}"
-    git -C "${SB_DONE_ORIGINS[$j]}" worktree prune 2>/dev/null || true
-  done
-}
-
-# ---------------------------------------------------------------- writers ------
-_write_env(){
-  local ws="$1" profile="$2" name="$3" branch="$4" el_ws="$5"
-  local elc_dir="$el_ws/lang/dist/platform"
-  cat > "$ws/.stack-env" <<ENV
-# stack env for '$profile/$name' — SOURCE this to work the whole stack together.
-# Pins EL_REPO + PATH at the SANDBOX copy of foundation/el, so elc/elb/runtime and
-# every cross-repo ../foundation/el import resolve INSIDE this workspace.
-# The live mind (:$LIVE_ENGRAM_PORT engram / :$LIVE_SOUL_PORT soul) is deliberately NOT referenced.
-export STACK_NAME="$profile-$name"
-export STACK_PROFILE="$profile"
-export STACK_ROOT_WS="$ws"
-export EL_REPO="$el_ws"
-export PATH="$elc_dir:\$PATH"          # elc, elb (darwin/linux prebuilt) from the sandbox el
-ENV
-  if [ "$profile" = "neuron-stack" ]; then
-    cat >> "$ws/.stack-env" <<ENV
-export NEURON_REPO="$ws/neuron"
-export NEURONUI_REPO="$ws/products/NeuronUI"
-# engram/soul are NOT bound here — bring up an ISOLATED engram via nsbx when needed
-# (nsbx guards the live store & refuses ports :$LIVE_ENGRAM_PORT/:$LIVE_SOUL_PORT):
-#   nsbx create $profile-$name --source \$EL_REPO && nsbx up $profile-$name
-#   nsbx status $profile-$name        # prints the isolated engram URL to point the soul at
-ENV
-  fi
-  # direnv convenience
-  [ -e "$ws/.envrc" ] || printf 'source_env .stack-env 2>/dev/null || source .stack-env\n' > "$ws/.envrc"
-}
-
-_write_manifest(){
-  local ws="$1" profile="$2" name="$3" branch="$4"
-  # emit worktree records from git's own worktree list, filtered to this workspace
-  python3 - "$ws" "$profile" "$name" "$branch" "$DEV_ROOT" <<'PY'
-import json, os, subprocess, sys
-ws, profile, name, branch, dev = sys.argv[1:6]
-repos = []
-for rel in sorted(os.listdir(ws)) if False else []:
-    pass
-# discover worktrees by walking one level of relpaths we created
-def git(root, *a):
-    return subprocess.run(["git","-C",root,*a], capture_output=True, text=True).stdout.strip()
-for dirpath, dirnames, filenames in os.walk(ws):
-    if ".git" in filenames or ".git" in dirnames:
-        rel = os.path.relpath(dirpath, ws)
-        toplevel = git(dirpath, "rev-parse", "--show-toplevel")
-        common   = git(dirpath, "rev-parse", "--git-common-dir")
-        origin   = os.path.realpath(os.path.join(common, ".."))
-        head     = git(dirpath, "rev-parse", "HEAD")
-        repos.append({"rel": rel, "worktree": dirpath, "origin": origin,
-                      "branch": branch, "head": head})
-        dirnames[:] = []  # don't descend into a repo
-repos.sort(key=lambda r: r["rel"])
-json.dump({"profile": profile, "name": name, "branch": branch,
-           "workspace": ws, "repos": repos},
-          open(os.path.join(ws, ".stack-manifest.json"), "w"), indent=2)
-PY
-}
-
-_write_build(){
-  local ws="$1" profile="$2" el_ws="$3"
-  cat > "$ws/build.sh" <<'BUILD'
-#!/usr/bin/env bash
-# build.sh — build the assembled stack together, in dependency order.
-# Generated by `sandbox`. Run from the workspace root (it sources .stack-env).
-set -uo pipefail
-cd "$(dirname "$0")"; source ./.stack-env
-say(){ printf '\033[1m==>\033[0m %s\n' "$*"; }
-ok(){  printf '    \033[32m%s\033[0m\n' "$*"; }
-bad(){ printf '    \033[31m%s\033[0m\n' "$*"; }
-
-# locate an elc that runs on THIS machine (darwin-arm64 / linux-amd64), from the sandbox el
-find_elc(){
-  local d="$EL_REPO/lang/dist/platform"
-  case "$(uname -s)-$(uname -m)" in
-    Darwin-arm64) echo "$d/elc-darwin-arm64";;
-    Linux-x86_64) echo "$d/elc-linux-amd64";;
-    *)            echo "$d/elc";;
-  esac
-}
-ELC="$(find_elc)"; [ -x "$ELC" ] || ELC="$EL_REPO/lang/dist/platform/elc"
-say "elc: $ELC"
-[ -x "$ELC" ] && ok "$("$ELC" 2>&1 | head -1 || echo present)" || { bad "elc not executable"; exit 1; }
-
-# canonical runtime C to link (CI-published release copy; ~8 copies exist in-tree)
-RT="$EL_REPO/lang/releases/v1.0.0-20260501"
-[ -f "$RT/el_runtime.c" ] || RT="$EL_REPO/lang/el-compiler/runtime"
-[ -f "$RT/el_runtime.c" ] && ok "el_runtime: $RT/el_runtime.c" || bad "no el_runtime.c found under $EL_REPO/lang"
-BUILD
-
-  if [ "$profile" = "el-stack" ]; then
-    cat >> "$ws/build.sh" <<'BUILD'
-
-# ---- EL STACK: prove elc + the el stuff (incl. the el-ui framework) build together ----
-say "el-ui framework present: $EL_REPO/ui"
-[ -d "$EL_REPO/ui" ] && ok "framework dir present ($(ls "$EL_REPO/ui" | tr '\n' ' '))" || bad "no ui/ dir"
-
-# end-to-end compiler proof: elc compiles a real, substantial stack source to C,
-# then cc links it against the runtime -> a working native binary.
-B="$(mktemp -d)"
-say "elc end-to-end: compile engram/src/server.el and link a native binary"
-if "$ELC" "$EL_REPO/engram/src/server.el" > "$B/x.c" 2>"$B/elc.err"; then
-  ok "elc -> C ($(wc -c <"$B/x.c" | tr -d ' ') bytes)"
-  if cc -std=c11 -O2 -w -I "$RT" -o "$B/x" "$B/x.c" "$RT/el_runtime.c" -lcurl -lpthread -lm 2>"$B/cc.err"; then
-    ok "cc link ok -> native binary $(ls -lh "$B/x" | awk '{print $5}')  (elc + runtime build together)"
-  else
-    bad "cc link failed:"; grep -i 'error:' "$B/cc.err" | sort -u | head | sed 's/^/      /'
-  fi
-else
-  bad "elc compile failed:"; sed 's/^/      /' "$B/elc.err" | head
-fi
-
-# optional downstream consumer: forge builds on the SDK (make build) — proves the
-# freshly-assembled el SDK still compiles a real downstream repo.
-FORGE="$STACK_ROOT_WS/foundation/forge"
-if [ -f "$FORGE/Makefile" ]; then
-  say "downstream consumer: foundation/forge (make build)"
-  ( cd "$FORGE" && EL_REPO="$EL_REPO" PATH="$EL_REPO/lang/dist/platform:$PATH" make build ) \
-    && ok "forge built against the sandbox SDK" || bad "forge build failed (see above)"
-fi
-say "el-stack build complete"
-BUILD
-  else
-    cat >> "$ws/build.sh" <<'BUILD'
-
-# ---- 1) engram (elc engram/src/server.el -> cc engram.c el_runtime.c), from the sandbox el ----
-say "build engram from $EL_REPO/engram/src/server.el"
-B="$(mktemp -d)"
-if "$ELC" "$EL_REPO/engram/src/server.el" > "$B/engram.c" 2>"$B/elc.err"; then
-  ok "elc -> engram.c ($(wc -c <"$B/engram.c" | tr -d ' ') bytes)"
-  if cc -std=c11 -O2 -w -I "$RT" -o "$B/engram" \
-        "$B/engram.c" "$RT/el_runtime.c" -lcurl -lpthread -lm 2>"$B/cc.err"; then
-    ok "engram binary built: $(ls -lh "$B/engram" | awk '{print $5}')"
-  else
-    bad "engram cc link failed:"; grep -i 'error:' "$B/cc.err" | sort -u | head | sed 's/^/      /'
-  fi
-else
-  bad "engram elc transpile failed:"; sed 's/^/      /' "$B/elc.err"
-fi
-
-# ---- 2) soul (imports ../foundation/el/elp/src/elp.el — resolves to SANDBOX el) ----
-say "soul present + cross-repo import resolves inside the sandbox"
-[ -f "$NEURON_REPO/soul.el" ] && ok "neuron/soul.el present" || bad "no soul.el"
-if [ -f "$EL_REPO/elp/src/elp.el" ]; then
-  ok "../foundation/el/elp/src/elp.el resolves -> $EL_REPO/elp/src/elp.el (sandbox copy)"
-else
-  bad "elp NLG source missing under sandbox el"
-fi
-# soul is a heavy single-TU compile; prove elc parses it rather than a full link
-if "$ELC" "$NEURON_REPO/soul.el" > "$B/soul.c" 2>"$B/soul.err"; then
-  ok "elc compiled soul.el -> $(wc -c <"$B/soul.c" | tr -d ' ') bytes of C (cross-repo imports resolved)"
-else
-  bad "soul.el elc compile failed:"; sed 's/^/      /' "$B/soul.err" | head
-fi
-
-# ---- 3) UI (present + buildable; gradle/JDK21 is heavy so we don't run it here) ----
-say "app/UI present + buildable"
-if [ -f "$NEURONUI_REPO/build.sh" ] || [ -f "$NEURONUI_REPO/gradlew" ]; then
-  ok "NeuronUI build entry present (./build.sh / ./gradlew — needs JDK21; run: cd $NEURONUI_REPO && ./gradlew run)"
-else
-  bad "no NeuronUI build entry"
-fi
-say "neuron-stack build complete (engram compiled, soul compiled, UI present & buildable)"
-BUILD
-  fi
-  chmod +x "$ws/build.sh"
-}
-
-_write_readme(){
-  local ws="$1" profile="$2" name="$3" branch="$4" el_ws="$5"
-  cat > "$ws/README.md" <<MD
-# $profile / $name — combined stack workspace
-
-Assembled by \`sandbox\`. Every constituent repo is a **git worktree** on branch
-\`$branch\`, forked off its origin repo's committed HEAD, laid out at its natural
-relative path so cross-repo \`../foundation/el\` imports resolve **inside this
-workspace** (the sandbox el), never the live tree.
-
-## Get in
-\`\`\`bash
-cd $ws
-source .stack-env      # EL_REPO + PATH now point at the sandbox el
-./build.sh             # build the stack together (or: sandbox build $profile $name)
-\`\`\`
-
-## Layout
-__STACK_LAYOUT__
-
-## Isolation
-- Worktrees only; the live soul/engram (:$LIVE_SOUL_PORT / :$LIVE_ENGRAM_PORT) are never touched.
-- To run against an **isolated engram**, delegate to \`nsbx\` (guards the live store/ports):
-  \`\`\`bash
-  nsbx create $profile-$name --source \$EL_REPO && nsbx up $profile-$name
-  \`\`\`
-
-## Tear down
-\`\`\`bash
-sandbox down $profile $name           # remove every worktree; branch '$branch' kept
-sandbox down $profile $name --delete-branch
-\`\`\`
-MD
-  # fill the layout list from the manifest without embedding backticks in the heredoc
-  python3 - "$ws" <<'PY'
-import json, os, sys
-ws = sys.argv[1]
-d = json.load(open(os.path.join(ws, ".stack-manifest.json")))
-lines = ["- `%s`  <- worktree of %s" % (r["rel"], r["origin"]) for r in d["repos"]]
-p = os.path.join(ws, "README.md")
-txt = open(p).read().replace("__STACK_LAYOUT__", "\n".join(lines))
-open(p, "w").write(txt)
-PY
-}
-
-# ================================================================ down =========
-cmd_down(){
-  local profile="$1" name="$2"; shift 2 || true
-  local del_branch=0
-  while [ $# -gt 0 ]; do case "$1" in
-    --delete-branch) del_branch=1; shift;;
-    *) die "unknown flag: $1";;
-  esac; done
-  need git
-  local ws; ws="$(ws_dir "$profile" "$name")"
-  [ -d "$ws" ] || die "no such workspace: $ws"
-  local mf; mf="$(manifest "$ws")"
-  [ -f "$mf" ] || die "no manifest in $ws (refusing to guess); remove it by hand if intended"
-  local branch; branch="$(python3 -c "import json;print(json.load(open('$mf'))['branch'])")"
-
-  log "tearing down '$profile/$name'  ($ws)"
-  # remove each worktree through its origin repo
-  python3 -c "import json;[print(r['origin']+'\t'+r['worktree']) for r in json.load(open('$mf'))['repos']]" \
-  | while IFS=$'\t' read -r origin wt; do
-      if [ -d "$wt" ]; then
-        git -C "$origin" worktree remove --force "$wt" 2>/dev/null || rm -rf "$wt"
-        git -C "$origin" worktree prune 2>/dev/null || true
-        ok "removed worktree: ${wt#$ws/}"
-      fi
-      if [ "$del_branch" -eq 1 ]; then
-        git -C "$origin" branch -D "$branch" 2>/dev/null && ok "deleted branch $branch in ${origin#$DEV_ROOT/}" || true
-      fi
-    done
-  # drop the (now worktree-free) workspace tree
-  rm -rf "$ws"
-  ok "workspace removed: $ws"
-  [ "$del_branch" -eq 1 ] || info "branch '$branch' kept in each repo (use --delete-branch to drop)"
-  ok "down '$profile/$name' complete (live untouched)"
-}
-
-# ================================================================ build ========
-cmd_build(){
-  local profile="$1" name="$2"; local ws; ws="$(ws_dir "$profile" "$name")"
-  [ -x "$ws/build.sh" ] || die "no build.sh in $ws (is it assembled? sandbox $profile $name)"
-  exec "$ws/build.sh"
-}
-
-# ================================================================ list/status ==
-cmd_list(){
-  [ -d "$STACK_ROOT" ] || { info "no stack workspaces (root $STACK_ROOT absent)"; return 0; }
-  local mf found=0
-  for mf in "$STACK_ROOT"/*/.stack-manifest.json; do
-    [ -f "$mf" ] || continue; found=1
-    python3 -c "import json;d=json.load(open('$mf'));print('  %-22s %-8s %2d repos  branch=%s'%(d['profile']+'/'+d['name'],'',len(d['repos']),d['branch']))" 2>/dev/null
-  done
-  [ "$found" -eq 1 ] || info "no assembled stack workspaces under $STACK_ROOT"
-}
-
-cmd_status(){
-  local profile="$1" name="$2"; local ws; ws="$(ws_dir "$profile" "$name")"
-  local mf; mf="$(manifest "$ws")"; [ -f "$mf" ] || die "no such workspace: $ws"
-  log "stack '$profile/$name'"; info "workspace: $ws"
-  python3 - "$mf" <<'PY'
-import json,sys,subprocess
-d=json.load(open(sys.argv[1]))
-print(f"    branch:    {d['branch']}")
-for r in d['repos']:
-    st=subprocess.run(["git","-C",r["worktree"],"status","--porcelain"],capture_output=True,text=True).stdout
-    n=len([l for l in st.splitlines() if l.strip()])
-    print(f"    {r['rel']:<20} {r['head'][:9]}  {'clean' if n==0 else str(n)+' changed'}")
-PY
-}
-
-# ================================================================ usage/main ===
-usage(){ cat >&2 <<EOF
-${C_BLD}sandbox${C_0} — assemble a WHOLE Neuron stack into one combined worktree workspace,
-wired to build together on an isolated clean base. Multi-repo sibling of ${C_BLD}nsbx${C_0}.
-
-  ${C_CYN}sandbox el-stack     <name>${C_0} [--minimal]   elc + EL language + el-ui framework + tooling (+ SDK consumers)
-  ${C_CYN}sandbox neuron-stack <name>${C_0} [--minimal]   runtime/soul + engram + app/UI  (the full product)
-  ${C_CYN}sandbox build  <profile> <name>${C_0}           build the assembled stack together (runs its build.sh)
-  ${C_CYN}sandbox status <profile> <name>${C_0}           inspect one workspace
-  ${C_CYN}sandbox list${C_0}                               list assembled workspaces
-  ${C_CYN}sandbox down   <profile> <name>${C_0} [--delete-branch]   tear down (remove worktrees; branch kept)
-
-  Flags:  --minimal  only the required repos    --branch B  branch name    --base REF  fork point
-  Env:    NSBX_STACK_ROOT (workspace root, default \$DEV_ROOT/stack-worktrees)   NEURON_DEV_ROOT
-
-Each constituent repo becomes a git worktree at its natural relpath inside the
-workspace, so cross-repo ../foundation/el imports resolve to the SANDBOX el. The
-live soul/engram (:$LIVE_SOUL_PORT / :$LIVE_ENGRAM_PORT) are never touched; isolated-engram
-bring-up is delegated to nsbx.
-EOF
-}
-
-main(){
-  local cmd="${1:-}"; shift || true
-  case "$cmd" in
-    el-stack|neuron-stack) cmd_up "$cmd" "$@";;
-    up)        [ $# -ge 1 ] || die "usage: sandbox up <profile> <name>"; local p="$1"; shift; cmd_up "$p" "$@";;
-    down)      [ $# -ge 2 ] || die "usage: sandbox down <profile> <name>"; cmd_down "$@";;
-    build)     [ $# -ge 2 ] || die "usage: sandbox build <profile> <name>"; cmd_build "$@";;
-    status)    [ $# -ge 2 ] || die "usage: sandbox status <profile> <name>"; cmd_status "$@";;
-    list|ls)   cmd_list "$@";;
-    ""|-h|--help|help) usage;;
-    *) die "unknown command: $cmd (try: sandbox help)";;
-  esac
-}
-main "$@"