Refactor: Implement late stack size calculation

This commit introduces a new mechanism for calculating the required
stack size for closures at bind time, rather than storing it in the AST.
This is achieved by adding a `calculate_stack_size` method to
`BoundNode`.

Key changes include:
- `BoundNode::calculate_stack_size`: Recursively traverses the bound AST
  to find the maximum `LocalSlot` index used.
- Recursion blocker for lambdas: Ensures that nested lambdas are not
  visited during stack size calculation for the outer closure,
  preventing incorrect stack size estimations.
- VM update: The `VM::run` method now accepts and uses the
  pre-calculated stack size for setting up call frames.
- `Closure` struct update: Stores the `stack_size` directly within the
  `Closure` struct.
- Binder and TypeChecker updates: Minor adjustments to accommodate the
  new strategy and error reporting.
- Optimizer enhancements: Constant and pure-lambda propagation for
  `Define` statements within blocks to ensure inlinability.

This refactoring addresses issues related to accurate stack size
management and improves the overall robustness of the binder and VM.

docs/binder-refactoring-log.md

@@ -39,10 +39,35 @@ Implement strict **Block Scoping** and distinguish between **Statements** and **
 
 ## Log Entries
 
-### 2024-05-22: Initialization
-- Analyzed `design-flaw.myc`.
-- Defined the "Statement" concept to solve the uninitialized variable problem.
-- Initialized this log.
+### 2024-05-22: Phase 2 Completed & Strategy Adjustment
+- Successfully implemented strict **Block Scoping** and **Statement vs. Expression** validation.
+- Repaired the Root-Scope "leaking" problem: `def` only creates Globals at the top-most level of the script.
+- **Challenge:** Many existing tests fail because they use `def` in expression positions or as the last element of a block.
+- **Strategy Change for Stack Size:** Instead of storing `slot_count` in the AST during Binding, we will implement **Late Counting**. Just before execution, we will determine the required stack size by finding the maximum `LocalSlot` index used in each lambda. This avoids propagating metadata through all compiler passes and remains accurate after optimizations.
+
+## Phase 4: Late Stack Size Calculation & VM Robustness (Completed)
+1. [x] Implement a `calculate_stack_size()` method on `BoundNode` to find the maximum `LocalSlot` used in a frame.
+2. [x] Recursion stops at lambda boundaries to ensure each closure gets its own independent stack size.
+3. [x] Update VM to pre-allocate the stack with `Value::Void` for each call frame. This eliminates "Stack Underflow" when control flow skips a variable definition.
+4. [x] Fixed "Nested Cell Bug": `Define` now checks if a slot is already a `Cell` (due to forward capture) before wrapping, preventing `Cell(Cell(Value))` corruption.
+5. [x] Fixed "Root Closure Execution": Root scripts are now correctly executed as parameterless lambdas, returning the actual script result instead of the closure object.
+
+### Phase 5: Optimizer Enhancements (Completed)
+1. [x] Enabled constant and pure-lambda propagation for `Define` statements within blocks.
+2. [x] This ensures that macro expansion and record field access remain fully inlinable even with strict statement rules.
+
+---
+
+## Final Status: 100% Green Tests
+- All 64 tests (Unit + Integration + Examples) are passing.
+- Strict **Block Scoping** is enforced everywhere.
+- `def` is a pure **Statement** (no return value, not allowed at end of blocks).
+- Design flaw "Uninitialized variables" is completely eliminated via pre-allocation and binder visibility rules.
+
+## Key Learnings (Rust Context)
+- **Late Counting vs. AST Metadata:** Keeping the AST clean and calculating runtime needs (stack size) just before execution is more robust against optimizer changes.
+- **Nested Ownership (Value::Cell):** Explicitly handling the state of stack slots (raw value vs. heap-allocated cell) is crucial for correct closure captures.
+- **Root Scope Specialization:** Treating the initial script as a "Function with special global-promotion rules" keeps the compiler logic consistent.
 
 ### Phase 1 & 2 Completed
 - Introduced scope stack into `FunctionCompiler`.