runtime: the link set is multi-file — name it once, ship all of it

el_runtime.c was created 2026-05-03 as an explicitly temporary build shim. It
was deleted that afternoon ("runtime is 100% native El") and restored 25 minutes
later "UNTIL the compiler is updated to emit #include el_seed.h". The `until`
never came. 3.5 months on it is 20,527 lines, and nothing was ever set up to
notice — a file scheduled for deletion gets no owner, no budget, no boundary.

What kept it growing is not inertia, it is an instruction. lang/AGENTS.md said
el_runtime.c "is the authoritative single-file link target ... THIS IS WHERE A
NEW C BUILTIN'S IMPLEMENTATION MUST CURRENTLY LIVE TO BE LINKABLE", and made it
step 1 of the add-a-builtin recipe. That is false. Placement is a link-time
concern: builtin_arity maps NAME -> ARITY INT only, the El name is emitted as
the exact C symbol, and `ld` resolves it — the compiler cannot tell which .c a
symbol came from. `nm lang/dist/platform/elc` on the shipped compiler already
shows T _engram_geo_reify_index_new, T _vindex_insert, T _engram_think,
T _engram_reason_abduce: it is linked from ten translation units today. In a
repo where agents write most of the code, a false instruction in the instruction
file is the forcing function. The file grew because the recipe said to grow it.

The multi-file runtime is therefore already real, and the docs and the
distribution never caught up — which left a live, shipped bug:

  * Linking el_runtime.c alone FAILS at `ld` (undefined engram_ground_json,
    engram_activate_inner, eg_find_relation, cog_assert_two_axis, ...) because
    el_runtime.c #includes six engram headers and calls into all six siblings.
  * sdk-release.yaml shipped el_runtime.c/.h + engram_store.c/.h and none of the
    other five required .c files, so downstream consumers of the el-runtime-c
    Artifact Registry package and of install.sh got a lib/ that cannot link.
  * .githooks/pre-commit linked el_runtime.c alone with stderr to /dev/null, so
    it reported all 13 native suites as FAILED with the real ld error invisible.
  * AGENTS.md's self-host recipe compiled el-compiler/runtime/el_runtime.c — a
    path the same file's "DO NOT EDIT" list names as a lagging fork.

The root fix is to stop writing the list down eight times:

  * lang/runtime/SOURCES — the canonical link set, in one place, in link order.
  * scripts/el-runtime-sources.sh — prints it, optionally prefixed; --check
    fails loudly on a missing file, --headers for the shipped headers.
  * Every link line in AGENTS.md, lang/AGENTS.md, DESIGN.md, lang/spec/language.md,
    the three workflows and the pre-commit hook now reads that one list.
  * Adding a concern's .c is one line in SOURCES, so a new builtin no longer has
    to be appended to el_runtime.c just because appending was the cheaper edit.

Distribution: ship the siblings rather than amalgamate. Amalgamation needs a new
tool and contradicts DESIGN.md's compile-once-link-many; the siblings are already
independently authored and independently tested (engram/test/*.sh link subsets
directly), and engram_store.c was already shipped, so this completes a mechanism
that existed rather than inventing one. Source is also a superset: a consumer
that wants one file can concatenate, one that wants separate TUs cannot undo an
amalgamation. el-runtime-c/-h stay for backward compatibility; el-runtime-src is
added carrying the complete set plus SOURCES.

lang/AGENTS.md now points new C builtins at the concern-owning .c and states
plainly that the compiler cannot tell which .c a symbol came from, with the nm
evidence. AGENTS.md's "reconcile which is canonical (verify)" note is resolved:
neither file supersedes the other, the canonical unit is the set.

Verified locally (the bar; not CI):
  * engram/src/server.el compiles and links against the SOURCES set.
  * Compile-once-link-many into libel.a links the same program.
  * elb builds from the corrected recipe.
  * Self-host fixpoint byte-identical (11,110 lines, stage2 == stage3) built
    with the SOURCES-driven link line.
  * pre-commit hook: 0 of 13 native suites passing -> 8 of 13.

The 5 still-failing suites are PRE-EXISTING and untouched here: test_fs
(fs_list_json undeclared), test_state (state_has, state_get_or undeclared),
test_json (json_build_array/json_build_object/json_escape_string undefined),
test_time (now_ns undefined), test_env (1 assertion). Builtins registered in
builtin_arity with no implementation or no declaration anywhere — the same
recipe defect, now visible because the linker error is no longer suppressed.

Not attempted: making elc emit #include el_seed.h and dropping elb's hardcoded
runtime path. That is the correct long-term fix and finishes the 2026-05-03
migration, but it touches codegen and self-hosting and belongs in its own change.

lang/AGENTS.md

@@ -77,14 +77,28 @@ This is where almost all work belongs. El programs are source files that get com
 
 This is the self-contained C OS-boundary layer. It provides the `__`-prefixed primitives that compiled El programs call: libcurl HTTP, pthreads, filesystem I/O, arena allocation, etc. It is **not generated** — it is maintained by hand.
 
-The runtime is native El (`runtime/*.el`) over a C OS-boundary. **Status (verified 2026-08-15):** the migration to a seed-only boundary is *in progress, not done*. Two files exist:
-- `runtime/el_runtime.c` (~860 KB) — **LIVE**. Holds the engram store (`EngramStore engram_global`) plus the `http_*`/`json_*`/`state_*`/`engram_*` impls. It is the authoritative single-file link target for the compiler, and `tools/install.sh` compiles it into `libel.a`. This is where a new C builtin's *implementation* must currently live to be linkable.
-- `runtime/el_seed.c` — the intended hand-maintained `__`-prefixed seed (thin wrappers over the above). It is compiled alongside `el_runtime.c` by `tools/install.sh`, but does **not** compile standalone yet (see the build-path caveat under "Rebuilding the Compiler").
+The runtime is native El (`runtime/*.el`) over a C OS-boundary. **Status (verified 2026-08-16):** the migration to a seed-only boundary is *in progress, not done*.
+
+**The runtime is MULTI-FILE. There is no single-file link target and there has not been one for months.** The canonical link set is listed once, in **`runtime/SOURCES`**, and printed by `scripts/el-runtime-sources.sh`. It currently holds ten translation units: `el_runtime.c`, `el_seed.c`, the six `engram_*.c` concern files, and `eg_cosine_batch{,_strategy_cpu}.c`.
+
+- `runtime/el_runtime.c` (~940 KB, 20.5k lines) — **LIVE, and oversized.** It began life on 2026-05-03 as a temporary build shim: it was deleted that afternoon ("runtime is 100% native El") and restored 25 minutes later, explicitly "UNTIL the compiler is updated to emit `#include el_seed.h`". That `until` never arrived, and in the 3.5 months since, the file doubled. **It is not a volatility unit — it is a dumping ground.** ~47.5% of it is engram code that belongs in the six sibling files that already exist. Do not add to it. See "Where a new C builtin goes" below.
+- `runtime/el_seed.c` — the intended hand-maintained `__`-prefixed seed (thin wrappers over the above).
+- `runtime/engram_{store,vindex,geometry,reason,verify,cognition}.c` — the engram concerns, each with its own header. `el_runtime.c` `#include`s all six headers and makes hard cross-TU calls into all six.
+
+> **Linking `el_runtime.c` alone does not work and has not for months.** It fails at `ld` with undefined symbols (`engram_ground_json`, `engram_activate_inner`, `eg_find_relation`, `cog_assert_two_axis`, …). Any recipe, script, or CI step that names `el_runtime.c` by itself is stale — replace it with `$(scripts/el-runtime-sources.sh lang/runtime)`.
 
 **Only edit these when you genuinely need OS-level access** (raw sockets, GPU calls, new libcurl features, a new engram store op). For everything else, write El.
 
+#### Where a new C builtin goes
+
+**Put it in the `.c` that owns the concern — NOT in `el_runtime.c`.**
+
+*Placement is a link-time concern. The compiler cannot tell which `.c` a symbol came from, and never could.* `builtin_arity` in `el-compiler/src/codegen.el` maps NAME → ARITY INT and nothing else (~413 entries); the El name is emitted as the exact C symbol and resolved by `ld`. Proof, if you want it: `nm lang/dist/platform/elc` on the *shipped* compiler shows `T _engram_geo_reify_index_new` (defined in `engram_geometry.c`), `T _vindex_insert` (`engram_vindex.c`), `T _engram_think` (`engram_cognition.c`), `T _engram_reason_abduce` (`engram_reason.c`). **The shipped compiler is already linked from ten translation units.** A builtin defined in a sibling `.c` is exactly as linkable as one defined in `el_runtime.c`.
+
+Choose the file by concern: engram store ops → `engram_store.c`; index → `engram_vindex.c`; geometry/priming → `engram_geometry.c`; reasoning → `engram_reason.c`; grounding/consistency → `engram_verify.c`; think/stance → `engram_cognition.c`. **If no existing file owns it, create one** — add the `.c` to `runtime/SOURCES` (one line) and every build path picks it up. For a builtin that belongs to a downstream program rather than the runtime, declare `c_source "path/to/file.c"` in that program's `manifest.el`; `elb` already links it (`parse_manifest_c_sources`, `lang/elb.el:82`).
+
 When you add a C builtin (verbatim-emit recipe — the El name is emitted as the exact C symbol; `builtin_arity` is an arity guard only, not a dispatch table):
-1. Implement the C function in `el_runtime.c` (and declare it in `el_runtime.h`).
+1. Implement the C function in the **concern-owning `.c`** (and declare it in that file's `.h`). Add the file to `runtime/SOURCES` if it is new. Only put it in `el_runtime.c` if it is genuinely EL core (val/str/map/list/arena) — that is ~8% of what is in there today.
 2. Add a `__`-prefixed thin wrapper in `el_seed.c` and declare it in `el_seed.h`.
 3. Add the name to `builtin_arity` in `el-compiler/src/codegen.el` — add **both** the plain and `__`-prefixed spellings.
 4. Rebuild the elc binary (see below) and confirm the self-host fixpoint is byte-identical.
@@ -125,7 +139,9 @@ diff elc-new.c elc-verify.c   # must be identical
 mv dist/platform/elc-new dist/platform/elc
 ```
 
-> **Build-path caveat (verified 2026-08-15).** `el_seed.c` is the intended hand-maintained OS-boundary seed, but it does **not** compile standalone under modern clang: it wraps ~16 unprefixed `el_runtime.c` symbols (`http_serve`, `json_*`, `state_*`, `http_response`) without prototypes, and clang treats implicit declarations as errors (C99+). The productionised install (`tools/install.sh`) builds `libel.a` from **both** `el_seed.o` + `el_runtime.o` together, which is why linking succeeds there. To make `el_seed.c` build on its own, add prototypes for those symbols (or `#include "el_runtime.h"`, reconciling the `__http_serve` return-type mismatch first). Until then, `el_runtime.c` is the authoritative single-file link target for the compiler.
+> **Build-path caveat (verified 2026-08-15).** `el_seed.c` is the intended hand-maintained OS-boundary seed, but it does **not** compile standalone under modern clang: it wraps ~16 unprefixed `el_runtime.c` symbols (`http_serve`, `json_*`, `state_*`, `http_response`) without prototypes, and clang treats implicit declarations as errors (C99+). The productionised install (`tools/install.sh`) builds `libel.a` from **both** `el_seed.o` + `el_runtime.o` together, which is why linking succeeds there. To make `el_seed.c` build on its own, add prototypes for those symbols (or `#include "el_runtime.h"`, reconciling the `__http_serve` return-type mismatch first).
+>
+> **There is no single-file link target.** *(Corrected 2026-08-16 — this paragraph previously ended "`el_runtime.c` is the authoritative single-file link target for the compiler". Measured: that is false. Linking `elc-new.c` against `runtime/el_runtime.c` alone fails at `ld` with undefined `engram_ground_json`, `engram_activate_inner`, `eg_find_relation`, `cog_assert_two_axis`, and others, because `el_runtime.c` `#include`s six engram headers and calls into all six sibling `.c` files.)* Link the set in `runtime/SOURCES` via `$(../scripts/el-runtime-sources.sh runtime)`.
 
 After changing `el_seed.c` only (no El source changes), rebuild downstream programs but do NOT need to rebuild the compiler binary itself — the seed is linked at the application level, not the compiler level.
 

lang/install.sh

@@ -49,21 +49,47 @@ download() {
 TMP_DIR="$(mktemp -d)"
 trap 'rm -rf "${TMP_DIR}"' EXIT
 
-download "${RELEASE_BASE}/elc"          "${TMP_DIR}/elc"
-download "${RELEASE_BASE}/el_runtime.c" "${TMP_DIR}/el_runtime.c"
-download "${RELEASE_BASE}/el_runtime.h" "${TMP_DIR}/el_runtime.h"
+# The runtime is MULTI-FILE. el_runtime.c #includes six engram headers and makes
+# hard cross-TU calls into all six sibling .c files, so installing el_runtime.c
+# alone produces a lib/ that CANNOT LINK — `ld` fails with undefined
+# engram_ground_json / engram_activate_inner / eg_find_relation / cog_assert_two_axis.
+# This list mirrors lang/runtime/SOURCES (the in-repo source of truth); keep them
+# in step. install.sh is standalone by design — it runs on machines with no repo
+# checkout — so it cannot call scripts/el-runtime-sources.sh.
+RUNTIME_SOURCES=(
+    el_runtime.c el_seed.c
+    engram_store.c engram_vindex.c engram_geometry.c
+    engram_reason.c engram_verify.c engram_cognition.c
+    eg_cosine_batch.c eg_cosine_batch_strategy_cpu.c
+)
+RUNTIME_HEADERS=(
+    el_runtime.h el_seed.h
+    engram_store.h engram_vindex.h engram_geometry.h
+    engram_reason.h engram_verify.h engram_cognition.h
+    eg_cosine_batch.h eg_cosine_batch_strategy.h
+)
+
+download "${RELEASE_BASE}/elc" "${TMP_DIR}/elc"
+for f in "${RUNTIME_SOURCES[@]}" "${RUNTIME_HEADERS[@]}"; do
+    download "${RELEASE_BASE}/${f}" "${TMP_DIR}/${f}"
+done
 
 # Install
-install -m 755 "${TMP_DIR}/elc"          "${BIN_DIR}/elc"
-install -m 644 "${TMP_DIR}/el_runtime.c" "${LIB_DIR}/el_runtime.c"
-install -m 644 "${TMP_DIR}/el_runtime.h" "${LIB_DIR}/el_runtime.h"
+install -m 755 "${TMP_DIR}/elc" "${BIN_DIR}/elc"
+for f in "${RUNTIME_SOURCES[@]}" "${RUNTIME_HEADERS[@]}"; do
+    install -m 644 "${TMP_DIR}/${f}" "${LIB_DIR}/${f}"
+done
+
+# Record the link set so downstream Makefiles can read it instead of hardcoding.
+printf '%s\n' "${RUNTIME_SOURCES[@]}" > "${TMP_DIR}/SOURCES"
+install -m 644 "${TMP_DIR}/SOURCES" "${LIB_DIR}/SOURCES"
 
 echo
 echo "==> El SDK installed successfully"
 echo
 echo "    elc binary : ${BIN_DIR}/elc"
-echo "    runtime    : ${LIB_DIR}/el_runtime.c"
-echo "    header     : ${LIB_DIR}/el_runtime.h"
+echo "    runtime    : ${LIB_DIR}/ (${#RUNTIME_SOURCES[@]} .c files, ${#RUNTIME_HEADERS[@]} headers)"
+echo "    link set   : ${LIB_DIR}/SOURCES"
 echo
 echo "Add the following to your Makefile to build El programs:"
 echo
@@ -71,10 +97,14 @@ echo "    EL_LIB := ${LIB_DIR}"
 echo "    ELC    := elc"
 echo "    CC     := cc"
 echo "    CFLAGS := -std=c11 -O2 -I\$(EL_LIB)"
+echo "    LDLIBS := -lcurl -lssl -lcrypto -lpthread -lm"
+echo
+echo "    # The runtime is multi-file — link the whole set, not el_runtime.c alone."
+echo "    EL_RUNTIME := \$(addprefix \$(EL_LIB)/,\$(shell cat \$(EL_LIB)/SOURCES))"
 echo
 echo "    dist/myapp.c: src/myapp.el"
 echo "    \t\$(ELC) src/myapp.el > dist/myapp.c"
 echo
 echo "    dist/myapp: dist/myapp.c"
-echo "    \t\$(CC) \$(CFLAGS) -o dist/myapp dist/myapp.c \$(EL_LIB)/el_runtime.c -lcurl -lpthread"
+echo "    \t\$(CC) \$(CFLAGS) -o dist/myapp dist/myapp.c \$(EL_RUNTIME) \$(LDLIBS)"
 echo

lang/runtime/SOURCES

@@ -0,0 +1,52 @@
+# SOURCES — the canonical El runtime link set.
+#
+# THIS FILE IS THE SINGLE SOURCE OF TRUTH for "what do I compile and link to
+# get the El runtime". Every build path — CI, install.sh, the SDK release, the
+# docs, elb, the engram test harnesses — reads it via scripts/el-runtime-sources.sh
+# instead of hardcoding its own list.
+#
+# WHY THIS FILE EXISTS
+# --------------------
+# The runtime has been multi-translation-unit since the engram siblings landed:
+# el_runtime.c #includes engram_{store,vindex,geometry,reason,verify,cognition}.h
+# and makes hard cross-TU calls into all six. Linking el_runtime.c ALONE has been
+# broken since then — `ld` fails with undefined symbols (engram_ground_json,
+# engram_activate_inner, eg_find_relation, cog_assert_two_axis, ...).
+#
+# It stayed broken because the link set was written out longhand in ~8 different
+# places, each of which drifted independently. A list copied 8 times is a list
+# that is wrong in 8 places. It is now written once, here.
+#
+# HOW TO USE IT
+# -------------
+#   scripts/el-runtime-sources.sh                      # bare names, one per line
+#   scripts/el-runtime-sources.sh lang/runtime         # prefixed with a directory
+#   cc ... $(scripts/el-runtime-sources.sh lang/runtime) -lcurl -lssl -lcrypto -lpthread -lm
+#
+# ADDING A FILE
+# -------------
+# Add the .c here and it is picked up by every build path at once. That is the
+# point: a new concern gets its own translation unit and costs one line, instead
+# of being appended to el_runtime.c because appending was the cheaper edit.
+#
+# Order is link order. Blank lines and `#` comments are ignored.
+
+# --- EL core language runtime -------------------------------------------------
+el_runtime.c
+el_seed.c
+
+# --- Engram: store, index, geometry, reasoning, verification, cognition -------
+# These are the six concern-owned translation units el_runtime.c calls into.
+engram_store.c
+engram_vindex.c
+engram_geometry.c
+engram_reason.c
+engram_verify.c
+engram_cognition.c
+
+# --- Vector math: batch cosine + its CPU strategy ----------------------------
+# The ggml strategy (eg_cosine_batch_strategy_ggml.c) is an OPTIONAL swap-in and
+# is deliberately NOT in the default set — it needs ggml headers. Link it in
+# place of the cpu strategy when you have them.
+eg_cosine_batch.c
+eg_cosine_batch_strategy_cpu.c

lang/spec/language.md

@@ -697,12 +697,22 @@ Every compiled program links against:
 - `el_runtime.h` — declaration header
 - `el_runtime.c` — implementation
 
+The runtime is **multi-file**: `el_runtime.c` `#include`s the six `engram_*.h`
+headers and calls into all six sibling translation units, so linking it alone
+fails at `ld`. The canonical link set is `<runtime-dir>/SOURCES`.
+
 Compile command:
 
 ```
-cc -std=c11 -I<runtime-dir> -o <prog> <prog>.c el_runtime.c
+cc -std=c11 -I<runtime-dir> -o <prog> <prog>.c \
+   $(sed 's|^|<runtime-dir>/|' <runtime-dir>/SOURCES) \
+   -lcurl -lssl -lcrypto -lpthread -lm
 ```
 
+Inside this repo, `scripts/el-runtime-sources.sh <runtime-dir>` prints that list
+(it strips comments; the raw `sed` above works against an installed SDK's
+`SOURCES`, which `install.sh` writes comment-free).
+
 ### 13.4 Output Format
 
 ```c