fmpl: Instructions file for Codex

AGENTS.md

Workflow rules and gotchas for working in this repo. Codebase inventory, key-file locations, and doc pointers live in DEV.md.

Design Principles (read first)

Durable invariants live in docs/design-principles.md. These override iteration scope when in conflict. If you are about to make a change that would violate a principle, stop — the principle wins, the change needs to be reframed. Currently captured: metacircular bootstrap (DESIGN-001), single canonical list-form for structured data (DESIGN-002), symbols for type names (DESIGN-003), tree-based IR with named temporaries (DESIGN-004), grammar inheritance deferred (DESIGN-005).

Orientation

FMPL is a streaming-first DSL for AI agents: prototype objects, OMeta-style PEG grammars, pattern matching via @, and an Indexed RPN bytecode VM.

• Core flow: Source → Lexer (logos) → Parser → AST → Compiler → Indexed RPN bytecode → VM
• Bootstrap pipeline: ast::parse(source) → ast @ ast_to_ir.expr → ir::compile(ir) → code::eval(code) — the FMPL-in-FMPL path being built toward self-hosting
• Current limitations are tracked in docs/known-gaps.md, grouped by root cause.

Build & Test

just build                       # REQUIRED build: bootstraps the FMPL-generated parser, then builds
just test                        # full suite with the canonical parser active
cargo test -p fmpl-core <name>   # targeted test during development
just repl                        # REPL (dot-prefixed commands: .help, .quit)
just web                         # web server (port 3000)
just tui                         # TUI (Ctrl+L for LLM chat)

• Plain cargo build silently uses the Rust fallback parser, not the canonical FMPL-generated one. Use just build (or run the two bootstrap steps in README). canonical_pipeline_parity fails loudly if the fallback is active.
• Changing parser codegen (ir_to_rust.rs) or anything the generated parser embeds? Read the bump policy in fmpl-core/src/parser_epoch.rs and bump PARSER_EPOCH.
• Feature flags: fjall-persistence (durable storage), trampolined-grammar (bounded stack), cross_compile (dormant — needs the external execution_tape crate, see Cargo.toml comments).
• Test helpers: eval(&mut vm, source) for VM tests, parse(source) for parser tests; wiremock for async HTTP tests (see tests/async_curl.rs).