add mutation fuzzer and update docs

Author: dylan-sutton-chavez

.gitignore

@@ -1,40 +1,44 @@
-# Rust
-**/target/
-Cargo.lock
-
-# macOS
-.DS_Store
-**/.DS_Store
-._*
-
-# Windows
-Thumbs.db
-Desktop.ini
-
-# Editors
-.vscode/
-.idea/
-*.swp
-
-# Node (for the demo)
-node_modules/
-**/node_modules/
-dist/
-*.log
-
-# Next.js / Nextra (docs)
-.next/
-**/.next/
-out/
-**/out/
-
-# WASM
-pkg/
-**/pkg/
-
-# Cloudflare
-.wrangler/
-
-# Secrets
-.env
-.env.*
+# Rust
+**/target/
+Cargo.lock
+
+# macOS
+.DS_Store
+**/.DS_Store
+._*
+
+# Windows
+Thumbs.db
+Desktop.ini
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# Node (for the demo)
+node_modules/
+**/node_modules/
+dist/
+*.log
+
+# Next.js / Nextra (docs)
+.next/
+**/.next/
+out/
+**/out/
+
+# WASM
+pkg/
+**/pkg/
+
+# Cloudflare
+.wrangler/
+
+# Secrets
+.env
+.env.*
+
+# fuzzer output
+crashes/
+**/crashes/

Cargo.toml

@@ -28,3 +28,9 @@ lto = true
 codegen-units = 1
 panic = "abort"
 strip = true
+
+[profile.fuzz]
+inherits = "release"
+opt-level = 3
+strip = false
+debug = true

compiler/Cargo.toml

@@ -16,6 +16,10 @@ crate-type = ["cdylib", "rlib"]
 test = false
 doctest = false
 
+[[bin]]
+name = "fuzz"
+path = "src/bin/fuzz.rs"
+
 [[test]]
 name = "tests"
 path = "tests/main.rs"

compiler/README.md

@@ -15,13 +15,14 @@ Single-pass pipeline: source -> SSA bytecode chunk; stack interpreter with adapt
 * **VM** (`modules/vm/`) flat-match dispatch, scalar + instance-dunder inline caches, pure-function template memoization, NaN-boxed 64-bit `Val` with a mark-and-sweep arena.
 * **Resolver** (`modules/packages/`) host-injected; native imports register for `CallExtern` dispatch.
 
-Full rationale, NaN-box patterns, IC thresholds, GC roots, and intentional omissions: [Design](https://edgepython.com/implementation/design). Lexer and parser internals: [Lexical](https://edgepython.com/implementation/lexical), [Syntax](https://edgepython.com/implementation/syntax).
+Full rationale, NaN-box patterns, IC thresholds, GC roots, and intentional omissions: [Design](https://edgepython.com/implementation/design). Lexer and parser internals: [Lexical](https://edgepython.com/implementation/lexical), [Syntax](https://edgepython.com/implementation/syntax). Fuzzer internals and mutation strategies: [Fuzzing](https://edgepython.com/implementation/fuzzing).
 
 ## Layout
 
 ```text
 ├── src
 │   ├── main
+│   ├── bin
 │   ├── modules
 │   │   ├── lexer
 │   │   ├── packages
@@ -64,6 +65,16 @@ fn main() {
 
 The download URL is derived from `CARGO_PKG_VERSION`, so a tag bump is the only retarget. Use `branch = "main"` for unreleased work. Requires `curl` on PATH; gated by the default-on `prebuilt` feature.
 
+## Fuzzer
+
+```bash
+# build and run
+cargo run --bin fuzz --profile fuzz
+
+# reproduce a crash
+cargo run --bin compiler crashes/crash_000001.py
+```
+
 ## References
 
 1. **Aho, Sethi & Ullman**, *Compilers: Principles, Techniques and Tools* (1986). LUT-based lexer.