# cagire-forth

Stack-based Forth VM for the Cagire sequencer. Tokenizes, compiles, and executes step scripts to produce audio and MIDI commands.

## Modules

| Module | Description |
|--------|-------------|
| `vm` | Interpreter loop, `Forth::evaluate()` entry point |
| `compiler` | Tokenization (with source spans) and single-pass compilation to ops |
| `ops` | `Op` enum (~90 variants) |
| `types` | `Value`, `StepContext`, shared state types |
| `words/` | Built-in word definitions: `core`, `sound`, `music`, `midi`, `effects`, `sequencing`, `compile` |
| `theory/` | Music theory lookups: `scales` (~200 patterns), `chords` (interval arrays) |

## Key Types

- **`Forth`** — VM instance, holds stacks and compilation state
- **`Value`** — Stack value (int, float, string, list, quotation, ...)
- **`StepContext`** — Per-step evaluation context (step index, tempo, variables, ...)
- **`Op`** — Compiled operation; nondeterministic variants carry `Option<SourceSpan>` for tracing
- **`ExecutionTrace`** — Records executed/selected spans and resolved values during evaluation