Reversal / Decisions — §5 Geometry Operators EL Cutover

Date: 2026-08-13 Branch: engram-tiered-storage (worktree /tmp/engram-tiered-wt) Parent commit: 5336cfe (M9 §5 geometry operators as C functions + EL builtins, staged) Scope: make the six engram geometry operators callable from a compiled .el program, and demonstrate it on real store data. Staged, reversible. NOT pushed, NOT tagged. Live :8742 daemon and ~/.neuron/engram never touched.

What this delivers

On 5336cfe the six operators existed as heavy-runtime C functions (engram_geo_*_json in lang/runtime/el_runtime.c:12287-12385, declared in el_runtime.h:627-632) but the EL call surface was deferred. This change formalizes the cutover and proves callability from a compiled El (CGI) program.

Key finding (why no OOM-prone compiler rebuild was needed)

The shipped compiler lang/dist/platform/elc already emits a direct C call for these builtins. An unknown ident-call passes through verbatim as a C call, and arity_check_call returns OK when builtin_arity < 0. So a compiled .el that calls engram_geo_distance_json(A, B) folds to engram_geo_distance_json(A, B), which links straight into el_runtime.c. No self-host fold of elc-cli.el (the memory-heavy, drift-prone step) was required — that step is explicitly avoided.

Files changed (all in the engram worktree, commit on `engram-tiered-storage`)

lang/el-compiler/src/codegen.el (+12) — source-of-truth builtin_arity table: registered the six operators under both the bare heavy-runtime names (engram_geo_*_json) and the __-prefixed seed names, mirroring the existing engram_activate_json / __engram_activate_json pair. Effect: a future legitimately-rebuilt elc validates arg counts. No effect on the shipped binary.
lang/elc.c (+36) — the folded-C mirror of the same table, kept in sync with codegen.el. (lang/elc.c is a stale/partial fold that does not compile standalone — it is missing the stdout_to_file/stdout_restore definitions — so this edit is source-consistency only; it is not the live compiler.)
lang/runtime/engram.el (+31) — six module wrappers engram_geo_*_json(...) -> String { return __engram_geo_*_json(...) }, mirroring the existing engram_activate_json wrapper. Surfaces the operators as named El functions for the seed-world / future rebuilt-elc path.
lang/runtime/engram_geometry.c (+2/-1) — style nit at ~1419: the centroid_unit normalization if/else had misleading indentation (single-statement for body then else). Braced the if arm. Behavior identical; not a numerical change.

Verification performed (real, on-machine)

Compiled-EL demo (scratchpad/geo_ops_demo.el, top-level El program): folded with the shipped elc inside a hard RSS cap (capfold.sh monitor, peak RSS ~4MB), cc-linked against el_runtime.c + engram_store.c + engram_geometry.c + engram_vindex.c, run against a COPY of the store (demostore/neuron.egm from real_copy.egm, 13,036 nodes, throwaway HOME, no server, not :8742). Real output on two real neighborhoods A=architecture {b037825e, e06ba673, 58ddea41}, B=hebbian {78b7a96e, 4d5cfe63, 7b97ee0e}:
- subtract residual: variance_explained_by_B=0.447564, residual_scale=0.304879, removed_dims=3, residual_n_axes=8, centroid_diff_mag=0.125119
- subtract setdiff: n_only=43, removed=72, centroid_diff_mag=0.125119
- distance: centroid_distance=0.125119, centroid_cosine=0.778572, wasserstein2=0.268298
- internal consistency: centroid_diff_mag identical across subtract+distance.
C unit suite test_geo_ops.c: 20/20 checks pass, ASan+UBSan clean, after the engram_geometry.c edit. No regression.

How to reverse

Everything is a single worktree commit on a non-pushed branch.

Full reversal: git -C /tmp/engram-tiered-wt revert <this-commit> (or git reset --hard 5336cfe to drop back to the parent tip).
Per-file reversal: git -C /tmp/engram-tiered-wt checkout 5336cfe -- <path> for any of the four files. Each edit is additive/local:
- The arity entries (codegen.el, elc.c) are inert unless elc is rebuilt.
- The engram.el wrappers are unused by the heavy engram server (which calls the bare builtins directly) — removing them changes nothing live.
- The engram_geometry.c brace change is behavior-neutral.
No runtime/deploy reversal needed: nothing was deployed. :8742, the launch agent, and ~/.neuron/engram were never modified. No tag, no push.

Deferred / open

elc binary rebuild with the arity table baked in is deferred. The canonical rebuild path (elc elc-cli.el > elc-new.c; AGENTS.md) is the self-host fold — the memory-heavy, compiler-revision-drift step. It is unnecessary for callability (shipped elc already passes the calls through) and carries the same drift risk flagged for the M-INTEROCEPTION HTTP routes. Do it only as part of a deliberate, capped compiler-cutover.
HTTP routes for the operators (server.el) are not added here — out of scope; the demo proves the compiled-EL call surface, which was the deliverable.

5.2 KiB Raw Blame History