Tracking: 2026-07 modularity review — gated boundaries hold, ungated ones have already drifted

[InauguralPhysicist]

Umbrella for the modularity review of main @ 8e8970a (release suite 3216/3216, ASan+UBSan 3220/3220, leak tally 0 — nothing here is currently failing).

The organizing finding

Modularity in this codebase is not a question of design taste. Every boundary with an automated gate is at zero drift; every comparable boundary without one has already broken. The same team, the same conventions, the same review discipline — the gate is the whole difference.

Boundary	Gated?	Measured state
SANDBOX_ALLOW[]	yes — tests/test_sandbox_allow.eigs	148 entries, 0 phantom
Builtin ↔ docs	yes — tools/stdlib_index_check.sh (with --selftest)	clean
Extension builtin names	yes — ext_names.h X-macro	correct by construction
Opcode metadata tables	no	3 of 4 tables drifted (#737)
eigenlsp.c builtin_docs[]	no	68 of 235 builtins, 1 phantom (#742)
ASTType switch exhaustiveness	bought, then opted out	1 of 38 exhaustive (#738)

So the recommendation across all of these is one recommendation: extend the gate patterns the project already invented. tools/stdlib_index_check.sh even ships a --selftest that injects a fake undocumented builtin to prove the gate isn't vacuously green — that self-proving pattern generalizes directly to the opcode tables and the LSP registry.

Filed

Correctness-adjacent (drift that is already a defect)

• Opcode metadata tables have already drifted: OP_TRAJECTORY_SLOT missing from the untrusted-chunk verifier, 4 opcodes disassemble as "???", 15 desync the disassembler #737 — opcode metadata tables drifted: OP_TRAJECTORY_SLOT missing from the untrusted-chunk verifier, 4 opcodes disassemble as "???", 15 desync the disassembler
• -Werror=switch is in CFLAGS but defeated by a default: arm in 37 of 38 ASTType switches — the enforcement is bought and then opted out of #738 — -Werror=switch is in CFLAGS but defeated by default: in 37 of 38 ASTType switches; the opcode tables switch on uint8_t so -Wswitch cannot apply at all
• Lockstep invariants enforced only by prose: gc_clear_node misses an edge GC_FOR_EACH_CHILD reports, and CallFrame has 5 hand-written init sites #743 — gc_clear_node misses an owned edge GC_FOR_EACH_CHILD reports (VAL_FN's chunk); CallFrame has 5 hand-written init sites and 2 teardown loops
• Multi-state boundary: trace.c is entirely process-global and ext_http's per-connection worker calls trace_shutdown(), destroying the process tape on every request #739 — multi-state boundary: trace.c is entirely process-global and ext_http's per-connection worker calls trace_shutdown(); g_exit_requested is never reset

Structure

• Build: every variant writes src/eigenscript, which is why the test runner needs a binary fingerprint guard — a per-variant objdir retires both #740 — every build variant writes src/eigenscript, which is why the test runner needs a binary fingerprint guard and CLAUDE.md needs a prohibition; a per-variant objdir retires both
• EIGENSCRIPT_FREESTANDING leaks 52 #ifdef blocks into builtins.c and 6 into lint.c, though the repo already has two clean gating patterns #741 — EIGENSCRIPT_FREESTANDING leaks 52 #ifdef blocks into builtins.c and 6 into lint.c, though ext_store.c and jit.c already demonstrate two clean gating patterns
• Env composition is duplicated across 5 call sites: make gfx + the embedding API yields a runtime with no gfx builtins, and eigenlsp's builtin table is 24% complete #742 — env composition duplicated across 5 sites: make gfx + the embedding API yields no gfx builtins; eigenlsp.c's builtin table is 24% complete
• Layering is convention, not structure: no per-layer headers, eigenscript.h is a 1253-line umbrella, eigenscript.c carries two dead extension includes, vm.c has 32 stale externs #744 — layering: no per-layer headers, eigenscript.h is a 1253-line umbrella in 29 TUs, eigenscript.c carries two dead extension includes, vm.c has 32 stale externs
• matmul/softmax have two implementations selected by EIGENSCRIPT_EXT_MODEL — a build flag forking a numeric kernel that nothing diffs #745 — matmul/softmax forked by EIGENSCRIPT_EXT_MODEL (structural fork; I could not demonstrate a numeric divergence — see the issue for the negative result)

Root cause folded into an existing issue

• sort_by of [xs, num] frees every element of xs — heap-use-after-free + garbage output (out-of-VM builtin calls skip the borrow compensation) #720 — vm_borrow_scan is static in vm.c, so the other TUs cannot call it; there are 4 uncompensated sites, not 3, and the Debug-build guard for the #546 borrow-scan cap: full-scan past the cap and abort on a missed borrow #548 guard covers only the 3 that were already correct (comment)

Corrections to my own earlier claims, recorded so nobody re-derives them

• g_vm, g_try_depth, and g_arena are not globals — they are bridge macros onto EigsThread (eigenscript.h:716-784). The EigsState/EigsThread seam works and most of the runtime obeys it; Multi-state boundary: trace.c is entirely process-global and ext_http's per-connection worker calls trace_shutdown(), destroying the process tape on every request #739 is about the few subsystems never migrated.
• A machine-readable stdlib index does already exist (tools/gen_lsp_stdlib_index.sh → src/lsp_stdlib_index.h), which narrows AI discoverability: llms.txt is invisible to agents working in the repo, BUILTINS.md omits map/filter/reduce, and there is no machine-readable API index #734 considerably (comment).
• CLAUDE.md's claim that observer: measure every ValType, and make a new one a build error #709 made a new ValType a build error does not hold — val_type_name ends in default: return "?", and there are zero _Static_asserts in src/ (see -Werror=switch is in CFLAGS but defeated by a default: arm in 37 of 38 ASTType switches — the enforcement is bought and then opted out of #738).
• CLAUDE.md routes work to three skills that do not exist in the repo: eigenscript-extend-vm (cited as holding the "update all N sites" checklist that would have prevented Opcode metadata tables have already drifted: OP_TRAJECTORY_SLOT missing from the untrusted-chunk verifier, 4 opcodes disassemble as "???", 15 desync the disassembler #737), eigenscript-jit, and aot-differential. .claude/skills/ contains only write-eigenscript.

What is well-factored (do not "fix" these — extend them)

ext_names.h (X-macro registry, with the ~120-name drift it killed documented in the header) · jit.h (opaque handle, zero conditional compilation, standalone-testable via jit_smoke.c) · ext_store.c (zero file-scope globals, per-state handle table, whole-TU freestanding gate) · tools/stdlib_index_check.sh (self-proving gate) · the src/freestanding/ seam (no forked runtime logic, two-stage symbol gate plus a glibc differential) · the acyclic header graph · EIGS_JIT_ENABLED collapsing arch+freestanding into one symbol used 7 times.

Suggested order

#738 first — it is the cheapest and it mechanically prevents #737's class from recurring. Then #737 and #743 (already-drifted invariants), then #740 (retires two existing workarounds), then the rest.