Chore: Fix errors and allign docs implementation.

Author: dylan-sutton-chavez

compiler/src/modules/parser/literals.rs

@@ -446,7 +446,13 @@ impl<'src, I: Iterator<Item = Token>> Parser<'src, I> {
 
     pub(super) fn compile_body(&mut self, params: &[String]) -> SSAChunk {
         let mut body = self.with_fresh_chunk(|s| {
-            for p in params { s.ssa_versions.insert(p.clone(), 0); }
+            for p in params {
+                s.ssa_versions.insert(p.clone(), 0);
+                
+                let bare = p.trim_start_matches('*');
+                let mut buf = [0u8; 128];
+                let _ = s.chunk.push_name(Self::ssa_name(bare, 0, &mut buf));
+            }
             s.compile_block_body();
         });
         body.is_pure = !body.instructions.iter().any(|i| matches!(

compiler/src/modules/vm/builtins.rs

@@ -375,27 +375,6 @@ impl<'a> VM<'a> {
             }
         } else { None };
 
-        // Extrae el nombre de tipo de un Val: acepta HeapObj::Type Y HeapObj::NativeFn.
-        // NativeFn es lo que realmente vive en globals["int"] porque el loop de builtin_fns
-        // sobreescribe al loop de BUILTIN_TYPES durante VM::new().
-        let type_name_of = |t: Val, heap: &HeapPool| -> Option<&'static str> {
-            if !t.is_heap() { return None; }
-            match heap.get(t) {
-                HeapObj::Type(_) => {
-                    // Comparamos por nombre de tipo del objeto t, no del name interno.
-                    // type_name() devuelve "type" para HeapObj::Type — usamos el campo.
-                    None  // manejado en check_one abajo con String comparison
-                }
-                HeapObj::NativeFn(id) => {
-                    let n = id.name();
-                    if matches!(n, "int"|"str"|"float"|"bool"|"list"|"tuple"|"dict"|"set") {
-                        Some(n)
-                    } else { None }
-                }
-                _ => None,
-            }
-        };
-
         let check_one = |t: Val, heap: &HeapPool| -> Result<bool, VmErr> {
             if !t.is_heap() {
                 return Err(VmErr::Type("isinstance() arg 2 must be a type or tuple of types"));

compiler/tests/cases/vm.json

@@ -480,5 +480,9 @@
   {"src": "print(hasattr('hello', 'xyz'))", "output": ["False"], "result": "None"},
   {"src": "print(hasattr([1,2], 'append'))", "output": ["True"], "result": "None"},
   {"src": "m = getattr('hi', 'upper')\nprint(m())", "output": ["HI"], "result": "None"},
-  {"src": "print(getattr('hi', 'xyz', 'default'))", "output": ["default"], "result": "None"}
+  {"src": "print(getattr('hi', 'xyz', 'default'))", "output": ["default"], "result": "None"},
+  {"src": "double = lambda n: n * 2\nsquare = lambda n: n * n\ndef compose(*fns):\n    def piped(x):\n        for f in fns:\n            x = f(x)\n        return x\n    return piped\npipeline = compose(double, square)\nprint([pipeline(x) for x in [1, 2, 3]])", "output": ["[4, 16, 36]"], "result": "None"},
+  {"src": "def outer(*args):\n    def inner():\n        return args\n    return inner\nprint(outer(1, 2, 3)())", "output": ["[1, 2, 3]"], "result": "None"},
+  {"src": "def make(x, y):\n    def get_y():\n        return y\n    return get_y\nprint(make(99, 'hi')())", "output": ["hi"], "result": "None"},
+  {"src": "def compose(f, g):\n    return lambda x: f(g(x))\ninc = lambda n: n + 1\ndbl = lambda n: n * 2\nprint(compose(inc, dbl)(5))", "output": ["11"], "result": "None"}
 ]

demo/packages.json

@@ -0,0 +1,160 @@
+---
+title: "Design"
+description: "Compiler architecture, dispatch model, and runtime layout."
+---
+
+## Overview
+
+Edge Python is a compact bytecode compiler and stack VM for a functional subset of Python 3.13. The release build is approximately 130 KB on `wasm32-unknown-unknown` with `panic=abort` and `opt-level=z`. The codebase is organized as a hand-written lexer, a single-pass Pratt parser that emits SSA-versioned bytecode directly, a peephole optimizer for constant folding, and a token-threaded interpreter with two layers of adaptive specialization on top.
+
+There is no AST and no IR: bytecode is the only intermediate representation between source and execution.
+
+## Pipeline
+
+```text
+source bytes
+   │
+   ▼
+┌──────────┐
+│  Lexer   │  LUT-driven scan, offsets into source, soft-keyword resolution
+└──────────┘
+   │ (start, end, kind) tokens
+   ▼
+┌──────────┐
+│  Parser  │  Pratt precedence, SSA versioning, Phi at joins
+└──────────┘
+   │ SSAChunk { instructions, constants, names, functions, classes }
+   ▼
+┌──────────┐
+│Optimizer │  Constant folding, dead-code compaction, jump remap
+└──────────┘
+   │ same SSAChunk, smaller
+   ▼
+┌──────────┐
+│    VM    │  Token-threaded dispatch, IC, template memoization, mark-sweep GC
+└──────────┘
+   │
+   ▼
+output buffer
+```
+
+## Concepts
+
+- **Offset-based tokens**: Tokens carry `(start, end, kind)` indices into the source buffer. No string copies during lexing; identifier and string content is sliced lazily by the parser.
+- **Single-pass SSA codegen**: Variables are versioned per assignment (`x` → `x_1`, `x_2`). Control-flow joins emit explicit `Phi` opcodes resolved at runtime.
+- **Token-threaded dispatch**: The instruction stream is `Vec<Instruction>` where each `Instruction` is `(opcode: OpCode, operand: u16)`. The hot loop is a flat `match` on the opcode variant. Rust lowers it to a jump table; this is *token threading*, not direct threading (computed-goto is not available in safe Rust).
+- **Per-instruction inline caching**: Each binary op records the type tags of its operands. After 4 stable hits the IC stores a typed `FastOp` (e.g. `AddInt`, `LtFloat`) used as a speculative fast path with a type-guard deopt.
+- **Template memoization**: Pure user functions cache results keyed by their argument tuple. After 2 hits the cached value short-circuits execution. Functions are statically classified as pure/impure during emission, and the runtime tightens the classification by observing `StoreItem`, `StoreAttr`, `Raise`, etc.
+- **NaN-boxed values**: `Val` is a 64-bit union encoding ints, floats, bools, None, and 28-bit heap indices in a single word.
+- **Mark-and-sweep GC**: Triggered when the heap crosses an adaptive threshold. Roots include the stack, globals, iterator frames, the current slot window, and saved live-slot snapshots.
+
+## Bytecode shape
+
+Each `Instruction` is 4 bytes: a 1-byte `OpCode` discriminant (with `#[repr(u8)]` planned), a 2-byte operand, and 1 byte of padding. Opcodes fall into 17 categories — load, store, arith, bitwise, compare, logic, identity, control flow, iter, build, container, comprehension, function, ssa (Phi), yield, side effects, and unsupported (raises at runtime).
+
+```text
+OpCode::LoadConst    operand = constant index
+OpCode::LoadName     operand = name slot
+OpCode::StoreName    operand = name slot
+OpCode::Add / Sub    operand = 0 (IC slot derived from ip)
+OpCode::Call         operand = (kw << 8) | pos
+OpCode::Phi          operand = target slot, sources in chunk.phi_sources
+OpCode::ForIter      operand = jump target on iterator exhaustion
+```
+
+## Dispatch shape
+
+The hot loop reads `cache.fused_ref()[ip]` — a snapshot of the instruction stream where adjacent `LoadAttr + Call` pairs have been fused into the `CallMethod + CallMethodArgs` superinstruction. This fusion is performed once per chunk, cached, and reused across calls.
+
+For arithmetic and comparison opcodes, the loop first checks `cache.get_fast(ip)`. If a `FastOp` is present, the speculative path runs inline and pops two operands without a function call. On a type-guard miss the cache is invalidated and execution falls back to the generic handler. The IC is per-instruction, so monomorphic call sites stabilize independently.
+
+## Memory model
+
+`Val` is 64 bits NaN-boxed:
+
+| Tag       | Pattern                                 | Notes                        |
+|-----------|-----------------------------------------|------------------------------|
+| Float     | any non-canonical IEEE-754              | Quiet NaN remapped           |
+| Int       | `QNAN | SIGN | i48`                     | ±2⁴⁷ inline; BigInt above    |
+| None      | `QNAN | 1`                              |                              |
+| True      | `QNAN | 2`                              |                              |
+| False     | `QNAN | 3`                              |                              |
+| Heap      | `QNAN | 4 | (i28 << 4)`                 | 28-bit index into `HeapPool` |
+
+The heap is an arena of `Option<HeapObj>` slots with a free list. Strings of 64 bytes or fewer are interned in a side hash. Integers above 2⁴⁷ are promoted to `BigInt`, a base-2³² little-endian limb array with Knuth Algorithm D for division. The garbage collector is a single-color mark-and-sweep that runs when `live > gc_threshold` or `alloc_count > max(live/4, 4096)`.
+
+## What the compiler intentionally does *not* do
+
+- No SSA-wide constant propagation through `LoadName`. The load is preserved because removing it pessimizes the IC, super-op, and template paths.
+- No CSE, GVN, LICM, inlining, or closed-form loop folding.
+- No dead-store elimination beyond what falls out of constant folding.
+- No IR — there is exactly one representation between source and dispatch.
+- No JIT. Edge Python stays single-tier and pure Rust. Method JITs need per-architecture stencils; trace JITs duplicate the execution model and complicate the GC contract.
+- No object model. `class` parses but `MakeClass` raises at runtime — the language is functional.
+- No module system. `import` and `from ... import` parse but raise at runtime.
+
+## Architecture
+
+```text
+src/
+├── lib.rs
+├── main.rs
+└── modules/
+    ├── fstr.rs              format helpers without core::fmt
+    ├── fx.rs                FxHashMap / FxHashSet (no_std hasher)
+    ├── lexer/
+    │   ├── mod.rs           public Token / TokenType, lexer entry
+    │   ├── scan.rs          byte-level scanner state machine
+    │   └── tables.rs        BYTE_CLASS, SINGLE_TOK, keyword LUT
+    ├── parser/
+    │   ├── mod.rs           Parser struct, SSA join logic, error recovery
+    │   ├── expr.rs          Pratt precedence climbing, postfix tails
+    │   ├── stmt.rs          statement dispatch, name_stmt with augmented assign
+    │   ├── control.rs       if / for / while / try / with / match / import
+    │   ├── literals.rs      list / dict / set / fstring / call / params
+    │   └── types.rs         OpCode, SSAChunk, Diagnostic, Value
+    └── vm/
+        ├── mod.rs           VM struct, exec loop, dispatch, GC roots
+        ├── cache.rs         OpcodeCache (IC), Templates (memoization), method fusion
+        ├── optimizer.rs     constant folding pass + jump remap
+        ├── ops.rs           binop kernels, equality, truthiness, type tag
+        ├── types.rs         Val, HeapObj, BigInt, DictMap, VmErr, Limits
+        ├── builtins.rs      built-in function bodies (print, len, abs, ...)
+        └── handlers/
+            ├── arith.rs     Add, Sub, Mul, Div, Mod, Pow, FloorDiv, Minus, BitOps, Compare, Logic
+            ├── data.rs      Store, Build, Container, Comprehension, Yield, Side
+            ├── function.rs  Call, MakeFunction, exec_call, dispatch_native
+            └── methods.rs   string / list / dict method tables, dispatch_method
+```
+
+## Capabilities
+
+| Types  | Control flow     | Built-ins         | Lexical         |
+|--------|------------------|-------------------|-----------------|
+| int    | if / elif / else | I/O               | indentation     |
+| float  | for / while      | type conversion   | f-string        |
+| str    | match / case     | introspection     | walrus operator |
+| bool   | functions        | iteration         | comments        |
+| list   | lambdas          | aggregation       | docstrings      |
+| dict   | generators       | math              | underscore      |
+| tuple  | comprehensions   | sequence ops      | complex numbers |
+| set    | try / except     | logical reduction | escape sequences|
+| range  | with             | number formatting | -               |
+| None   | async / await¹   | -                 | -               |
+| BigInt | yield / yield from | -                | -               |
+
+¹ async syntax parses and emits `MakeCoroutine` for compatibility, but there is no event loop — coroutines run synchronously.
+
+## References
+
+1. Aho, Sethi & Ullman. *Compilers: Principles, Techniques and Tools* (1986). LUT-based lexer.
+2. Pratt. *Top Down Operator Precedence* (POPL 1973).
+3. Cytron et al. *Efficiently Computing Static Single Assignment Form* (TOPLAS 1991).
+4. Gudeman. *Representing Type Information in Dynamically Typed Languages* (1993). NaN-boxing.
+5. Deutsch & Schiffman. *Efficient Implementation of the Smalltalk-80 System* (POPL 1984). Inline caching.
+6. Ertl & Gregg. *The Structure and Performance of Efficient Interpreters* (JILP 2003). Threaded dispatch.
+7. Casey et al. *Towards Superinstructions for Java Interpreters* (SCOPES 2003). LoadAttr+Call fusion.
+8. Michie. *Memo Functions and Machine Learning* (Nature 1968). Pure-function memoization.
+9. McCarthy. *Recursive Functions of Symbolic Expressions* (CACM 1960). Mark-sweep GC.
+10. Knuth. *The Art of Computer Programming, Vol. 2* (1981). Algorithm D for BigInt division.
+11. Backus. *Can Programming Be Liberated from the von Neumann Style?* (CACM 1978). Function-level paradigm.