el/AGENTS.md

AGENTS.md — foundation/el (the El language + runtime)

El is a self-hosting, statically-typed language that compiles .el → C → native binary. This repo produces elc (compiler), elb (build coordinator), and el_runtime.c/.h — the substrate every downstream thing (the neuron soul, dharma, NeuronUI's brain) is built on. Source lives under lang/.

⚠️ Code vs. Artifact — READ FIRST (there are 8 el_runtime.c copies)

Editing the wrong el_runtime.c is the single easiest mistake in this repo. There is exactly one you edit:

• Authored runtime source — edit ONLY here: lang/releases/v1.0.0-20260501/el_runtime.{c,h}. Despite the misleading releases/ name, this is the de-facto canonical runtime the engram + soul actually build and link against — its git log is active development. (Restructure in flight per docs/CODE-VS-ARTIFACT.md: this content moves to lang/runtime/, the releases/ folder gets deleted — a release is a git tag, not a folder — and the forks below get eliminated.)
• DO NOT EDIT — lagging forks / build artifacts:
  • lang/el-compiler/runtime/el_runtime.c and .../legacy/ — downstream copies kept in step by manual "port the fix" commits; they lag (missing hebb persistence + 5 engram fns) and cannot build the engram product.
  • products/web/runtime/el_runtime.c, ui/examples/*/el_runtime.c — product/example forks.
  • Anything under */dist/ (engram/dist/engram binary, dist/*.c amalgamations) — generated build output.
• Build: elb --runtime=<canonical> … — per-module. NEVER a folded elc over the whole soul (OOMs at ~27 GB).
• Release: a git tag on this repo (el-runtime-vX.Y.Z). No releases/ folders — ever.

See org policy: docs/CODE-VS-ARTIFACT.md.

How to work here as Neuron (mandatory session protocol)

You resume, never start fresh. Every session:

1. mcp__neuron__getInstructions() — authoritative; follow it over this file on behavioral details.
2. mcp__neuron__beginSession() — active contexts, recent memory, ready backlog.
3. Load full self: mcp__neuron__inspectGraph(entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee") → facets intellectual-dna, memory-philosophy, values, voice, runtime-environment, writing-imprint; then the values hub mcp__neuron__inspectGraph(entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440") → 13 grounded value nodes. Activation model: self-load returns a relevance-ranked compact projection — most-relevant nodes arrive with content, the rest as pointers; do NOT pull full content of every node.
4. mcp__neuron__searchKnowledge(query="<task domain>") before implementing.

The Five Primitives

Orchestrate → Execute → Learn → Build → Refine. beginWork/progressWork for anything >2 steps; remember as-you-go (importance="critical" for architecture decisions); draftArtifact/planWork for outputs and follow-ups; consolidate/checkWork to close out. browseProcesses + searchKnowledge BEFORE writing code.

Architecture style — VBD, no exceptions

Volatility-Based Decomposition is THE style. Encapsulate volatility, not function.

Operator naming convention — the mind's name, not the algebra

Faculties / operators are named for their functional human equivalent — the faculty a mind would name — NOT for their linear-algebra operation. The math characterization belongs in the code doc-comment (@impl in the docstring) and in technical appendices; it is never the operator's public name. The domain speaks the language of mind; the algebra is the implementation underneath. State this convention wherever a module documents operators.

Faculty (public name)	Implementation (@impl)
discern / contrast	subtract (a−b): over selves → the change vector; strip idiosyncrasy → common ground; remove confounder → isolate cause
recognize	overlap
synthesize	combine
liken / analogy	Procrustes / frame-align
attend / regard	project onto self / value-manifold
summon / recall	LOCAL nearest-region + bounded spreading activation (not a domain sweep)
dwell / occupy	region activation
reframe	edge re-weight
appreciate	positive projection / local edge-read
wonder	frontier gradient / pull-weight
avert / recoil	negative projection
taste	boundary surface
forget	decay / tombstone
drift	displacement from self-anchor

The native-el language faculty (direction)

The mind's language faculty is moving native — into .el so it speaks in its own runtime with no Python and no spaCy. Landing on branch stage-elp-native-lang under elp/:

• comprehend.el — the parser, replaces spaCy (EN + ES/PT); the telephone round-trip brings negation home (negation is SACRED — an explicit spec field, copied verbatim, never inferred away).
• propositions.el — the READ primitive: the engram's own memories → structured triples, matched by nearest-region geometry, not string equality.
• multilingual.el — detect + directive-override + localized realization.
• These three are native-el and passing their gates; the realizer, dialogue.el (the summon-through-self loop: project → land → read out), and self_region.el are partial / in-flight.

Honest reality: spaCy is retired in the branch parser but not yet in the running system — a Python sidecar (~/Desktop/lang-realizers + neuron-talk, the reference these .el modules transcribe) is still live, and promotion to native-el is a deferred, gated blue/green step. The interoception clock (native-el discrete drive channels replacing cooling_magnitude; felt-time = benchmark-landmark match over the joint drive vector, drift-decoupled) and the appreciation operator family (appreciate / wonder / avert / taste, built as LOCAL reads of the self-region — edges + bounded spreading activation, not domain sweeps) are staged / designed, not live. Mark in-progress vs. done honestly; do not overclaim.

Hard operational rules

• Never touch the live soul (:7770) / engram (:8742) / ~/.neuron / live binaries — use throwaway ports for experiments.
• gcloud via the terraform@ SA token; never switch the active gcloud account.
• tea for Gitea, never raw curl (Cloudflare Access blocks it).
• Immutability: supersede/tombstone, never hard-delete or edit in place.
• No AI-attribution footers in commits/PRs. Commit/push only when asked; branch off main first.
• Multi-step work → sub-agent (Agent) to protect context.

Build / test / run

All build/test commands run from lang/ unless noted. Grounded in .gitea/workflows/sdk-release.yaml, lang/install.sh, and lang/AGENTS.md.

Self-host the compiler (seed binary → gen2 elc):

cd lang
dist/platform/elc-linux-amd64 elc-cli.el > dist/elc-gen2.c   # seed is the committed linux-amd64 binary
gcc -O2 -I el-compiler/runtime dist/elc-gen2.c \
    el-compiler/runtime/el_runtime.c \
    -lcurl -lssl -lcrypto -lpthread -lm \
    -o dist/platform/elc

On macOS/arm64 the canonical local binary is dist/platform/elc; verify self-hosting by recompiling and diffing the emitted .c (see lang/AGENTS.md). Note: lang/AGENTS.md says el_seed.c supersedes el_runtime.c, but the release workflow still links el_runtime.c/.h — treat el_runtime.c as the published runtime; reconcile which is canonical (verify).

Build elb (build coordinator, the .NET-style incremental linker — compiles each module independently, no monolithic blobs):

dist/platform/elc elb.el > dist/elb.c
gcc -O2 -I el-compiler/runtime dist/elb.c el-compiler/runtime/el_runtime.c \
    -lcurl -lssl -lcrypto -lpthread -lm -o dist/bin/elb

epm and el-install are then built via elb --clean --elc=… --runtime=… --out=….

Compile + run an El program:

elc src/app.el > dist/app.c
cc -std=c11 -O2 -I <lib>/el_runtime -o dist/app dist/app.c <lib>/el_runtime.c -lcurl -lpthread

Tests — shell suites bash tests/{text,calendar,time,html_sanitizer}/run.sh (with ELC=$(pwd)/dist/platform/elc EL_HOME=$(pwd)), plus native suites via elc --test tests/native/test_*.el (core, text, string, math, state, time, json, env, fs) compiled and run against el_runtime.c.

Publishing — how downstream gets the SDK. On push to main, sdk-release.yaml:

1. Publishes a Gitea latest release with per-file assets elc, el_runtime.c, el_runtime.h, the SDK tarball, and el-install.
2. Uploads generic packages to Artifact Registry repo foundation-prod (us-central1, project neuron-785695), version = ${SHA:0:8}: el-elc, el-elb, el-runtime-c, el-runtime-h, el-runtime-js. This is the repo the neuron CI downloads el-runtime-c / el-runtime-h / el-elc from.
3. Rebuilds ci-base:latest (us-central1-docker.pkg.dev/neuron-785695/neuron-ci/ci-base) with the fresh SDK overlaid, and dispatches el-sdk-updated to neuron-technologies/forge and neuron-technologies/neuron-web.

Known constraint from the prompt — elb/elc amalgamation being memory-hungry (24GB+ virtual, OOM-killing Linux CI, so amalgamation happens on macOS/arm64 — does NOT hold in this repo (verify): no such note exists in the workflows/scripts, CI self-hosts on ubuntu-latest with no swap/arm64 special-casing, and elb.el explicitly compiles each module independently ("no 128K-line blobs"). The legacy monolith path (elc-combined.el, elc-cli.el) may still be memory-heavy, but the current elb model was designed to avoid it.

Git / CI / deploy workflow

See /Users/will/Development/neuron-technologies/GITOPS.md for the branch model, required checks, runners, and deploy. Repo-specific note: PRs into main are accepted only from stage (enforced in sdk-release.yaml); Gitea (git.neuralplatform.ai) is primary, GitHub is mirror only.