fmpl copilot-instructions.md

FMPL Copilot Instructions

Project Overview

FMPL is a streaming-first DSL for building AI agents with grammars, capabilities, and durable state. It features:

• Prototype-based objects with Goblins-inspired patterns (spawn, facets, bcom)
• OMeta-style PEG grammars with inheritance and memoization for parsing any stream (text, bytes, objects)
• Indexed RPN bytecode VM with async support (<- operator, streams)
• Fjall-backed persistence for live image and streaming overflow
• Pattern matching via @ operator for parsing and data transformation

Architecture

Rust workspace with 4 crates:

• fmpl-core/ — Lexer, parser, compiler, bytecode VM, object system, grammar engine
• fmpl-cli/ — REPL with rustyline history
• fmpl-web/ — Axum server with HTMX frontend
• fmpl-tui/ — Ratatui TUI for agentic LLM interaction (Ctrl+L for chat mode)

Core flow: Source → Lexer (logos) → Parser (recursive descent) → AST → Compiler → Indexed RPN bytecode → VM execution

Critical Patterns

1. Indexed RPN Execution (NOT stack-based)

The VM uses Indexed RPN: each instruction stores its result in values[ip], operands reference results by instruction index. See vm.rs.

// WRONG: Traditional stack-based thinking
// RIGHT: Operands are InstrIndex, results stored at IP
Frame { values: Vec<Value>, ip: usize }

// Instructions reference operands by index:
Add { lhs: InstrIndex(5), rhs: InstrIndex(7) }  // Add results from instructions 5 and 7

When adding instructions, operands MUST be InstrIndex references to previous results, not immediate values.

2. Async Operations Return Streams

Async calls (<- expr) return Value::AsyncStream that must be consumed:

• In REPL: wait_for_async() blocks until stream completes
• In code: Use @ operator to pattern-match stream events
• Example: @ http_response { %{ok: data} => process(data), %{error: e} => handle(e) }

3. Grammar Application with @