el/lang/AGENTS.md

# El Language — Agent Guide

El is a self-hosting, statically-typed language that compiles to C. This file orients agents that work on El itself or on programs written in El.

---

## 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).

**The compiler pipeline:**
```
elc-cli.el
  └─ imports: compiler.el
       └─ imports: lexer.el, parser.el, codegen.el, codegen-js.el
```

The canonical compiler binary is `dist/platform/elc`. It was produced by running an earlier version of itself on `elc-cli.el`.

---

## The Two Layers — Know Which One You're In

### Layer 1: El programs (`.el` files)

This is where almost all work belongs. El programs are source files that get compiled by `elc`. New library functions, application logic, and language-level utilities all go here as `.el` files.

**Do not add C code when El can express it.** If functionality can be built from existing El primitives (string ops, `exec`, `fs_read/write`, `http_post`, etc.), write it in El.

### Layer 2: The C seed (`el-compiler/runtime/el_seed.c`)

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 old `el_runtime.c` has been archived to `el-compiler/runtime/legacy/`. The runtime is now native El (`runtime/*.el`). `el_seed.c` replaces `el_runtime.c` as the sole C compilation dependency.

**Only edit `el_seed.c` when you genuinely need OS-level access** (raw sockets, GPU calls, new libcurl features). For everything else, write El.

When you do add a C builtin:
1. Add the C function to `el_seed.c`
2. Declare it in `el_seed.h`
3. Add it to the `builtin_arity` table in `el-compiler/src/codegen.el` (so the compiler knows the arg count)
4. Rebuild the elc binary (see below)

---

## Rebuilding the Compiler

After changing any `.el` source in `el-compiler/src/`:

```bash
cd /Users/will/Development/neuron-technologies/foundation/el
./dist/platform/elc elc-cli.el > elc-new.c
cc -std=c11 -I el-compiler/runtime -lcurl -lpthread \
   -o dist/platform/elc-new \
   elc-new.c el-compiler/runtime/el_seed.c
# Verify self-hosting:
./dist/platform/elc-new elc-cli.el > elc-verify.c
diff elc-new.c elc-verify.c   # should be identical
mv dist/platform/elc-new dist/platform/elc
```

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.

---

## How El Programs Are Built

Each El application has a `build.sh` that:
1. Concatenates all `.el` source files (stripping `import` lines)
2. Runs `elc` to produce a `.c` file
3. Runs `cc` linking against `el_seed.c`

Example (cgi-studio daemon):
```bash
cd products/cgi-studio/el-daemon
./build.sh
```

When you add a new `.el` file to an application, add it to that application's `build.sh` concat list.

---

## Parallelism in El

El is single-threaded at the application level. Parallelism is achieved through subprocess fan-out:

```el
// Pattern: write payloads to temp files, exec bash script with & and wait,
// read results back from temp files.
fn http_post_parallel(urls: [String], bodies: [String]) -> [String] {
    // ... bash fan-out via exec() ...
}
```

Use `exec()` (blocking) or `exec_bg()` (fire-and-forget) with shell scripts to run concurrent work. There is no goroutine or async/await — parallelism goes through the OS process layer.

---

## Key Files

| Path | What it is |
|------|-----------|
| `dist/platform/elc` | Canonical compiler binary (arm64 Mac) |
| `el-compiler/src/codegen.el` | Code generator — builtin arity table lives here |
| `el-compiler/src/lexer.el` | Lexer |
| `el-compiler/src/parser.el` | Parser |
| `el-compiler/runtime/el_seed.c` | Self-contained C OS-boundary layer (replaces el_runtime.c) |
| `el-compiler/runtime/el_seed.h` | Seed header (C function declarations) |
| `spec/language.md` | Language specification |
| `BOOTSTRAP.md` | How to recover the compiler from scratch |
| `elc-cli.el` | Compiler entry point |
| `elc-combined.el` | Pre-merged single-file compiler (used during early bootstrap) |

---

## HTTP Timeout

The El HTTP client (libcurl) defaults to **60 seconds**. Override per-process via `EL_HTTP_TIMEOUT_MS` env var. Set it before spawning any subprocess that makes long API calls:

```el
exec("EL_HTTP_TIMEOUT_MS=300000 " + SOME_BIN + " " + args + " 2>&1")
```

---

## Rules

- New library functions → write in El
- New OS/hardware primitives → write in C and register in `codegen.el` arity table
- Never edit `dist/platform/elc` directly — always rebuild from source
- Never modify `el_seed.c` to add functionality that El can express