elle AGENTS.md

Elle

Elle is a Lisp. Source text becomes bytecode; bytecode runs on a VM.

This is not a toy. The implementation targets correctness, performance, and clarity — in that order. We compile through multiple IRs, we have proper lexical scoping with closure capture analysis, and a unified signal/capability system: signals flow up (from callee to caller), capabilities flow down (from parent fiber to child). See signals for the full design.

You are an LLM. You will make mistakes. The test suite will catch them. Run the tests. Read the error messages. They are designed to be helpful.

origin/main is always green. Every commit on main passes every test — Elle scripts, Rust tests, examples, documentation. This is enforced by CI and a merge queue. If a test fails on your branch, your branch caused it. "Pre-existing defect" is not a valid explanation when main is green. Fix every failure before merging — no skip lists, no expected failures, no excuses. See CONTRIBUTING.md for the full policy.

Contents

• Architecture
• Signals and capabilities
• Products
• Directories
• Testing
• Invariants
• Intentional oddities
• Conventions
• Maintaining documentation
• Where to start

Architecture

Source → Reader → Syntax → Expander → Syntax → Analyzer → HIR → Lowerer → LIR → Emitter → Bytecode → VM

This is the only compilation pipeline. Source locations flow through the entire pipeline: Syntax spans → HIR spans → LIR SpannedInstr → LocationMap in bytecode. Error messages include file:line:col information.

Key modules

Pipeline (compilation order):

• reader — Lexing and parsing to Syntax
• syntax — Syntax types, macro expansion
• hir — Binding resolution, capture analysis, signal inference, linting, symbol extraction, docstring extraction
• lir — SSA form with virtual registers, basic blocks, SpannedInstr for source tracking
• compiler — Bytecode instruction definitions, debug formatting
• pipeline — Compilation entry points (see src/pipeline/AGENTS.md)