From 6414ef236b909276c7f39f92cc0ee704cb99b758 Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Tue, 9 Jun 2026 21:23:58 +0300
Subject: [PATCH] docs: update ROADMAP and PHASE8 for closures with captures

---
 docs/PHASE8_STRATEGY.md |  1 +
 docs/ROADMAP.md         | 33 ++++++++++++++++++++++-----------
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/docs/PHASE8_STRATEGY.md b/docs/PHASE8_STRATEGY.md
index e24df06..c2b7874 100644
--- a/docs/PHASE8_STRATEGY.md
+++ b/docs/PHASE8_STRATEGY.md
@@ -295,6 +295,7 @@ Crates.io е непреодолимо предимство. Ние се конк
 - ✅ `bux new`, `bux init`, `bux test`, `bux fmt` — готово
 - ✅ Basic borrow checker (`@[Checked]`) — готово
 - ✅ Closures (capture-less anonymous functions) — готово
+- ✅ Closures with captures — готово
 - 🎯 Target: Можеш да напишеш `bux` package manager на Bux
 
 ### Milestone B: "Използваем за systems programming" (2 месеца)
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 3c75b14..0a6091d 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -128,23 +128,34 @@ let s = HttpResponse(404, body: "err");         // positional + named mixed
 ---
 
 ### 6. Closures / Anonymous Functions
-**Why:** Callbacks, iterators, functional APIs. Currently only named functions exist.
+**Status:** ✅ Implemented in both bootstrap and selfhost. Capture-less and with captures.
 
 **Syntax:**
 ```bux
+// Capture-less closure
 let add: func(int, int) -> int = |a, b| { return a + b; };
-let nums: Array<int> = Array_New<int>();
+
+// Closure with captures
+let base: int = 10;
+let adder: func(int) -> int = |a: int| -> int { return a + base; };
+let result: int = adder(5);  // 15
+
+// Pass closure to higher-order function
 Array_Filter(nums, |x| { return x > 10; });
 ```
 
-**Implementation Steps:**
-1. New AST node: `ClosureExpr` with `params`, `body`, `captures`
-2. Parser: parse `|param1, param2| -> Type { body }`
-3. Type system: closure type as `func(Args) -> Ret` + implicit capture struct
-4. C backend: generate struct with captured vars + function pointer
-5. Lifetime: ensure captures outlive closure usage
+**Implementation:**
+- Capture-less closures: generate global thunk function, return `&thunk` as function pointer.
+- Closures with captures:
+  1. Sema: `Scope_LookupUpTo` identifies captured variables from outer scope.
+  2. HIR Lower: generate `__closure_env_N` struct + global instance `__closure_env_instance_N`.
+  3. At closure creation site: emit capture assignments (`env_instance.x = x;`).
+  4. In thunk body: rewrite captured identifiers to `env_instance.x` via `hFieldAccess`.
+  5. C backend: emit env struct definition + global instance before thunk function.
 
-**Complexity:** High — touches parser, sema, type system, C backend.
+**Limitations:** One global instance per closure AST node (no multiple instances). No loop/return support in closures yet.
+
+**Complexity:** High — touches parser, sema, type system, HIR/LIR backend.
 
 ---
 
@@ -237,6 +248,6 @@ Task::Spawn(Worker, rx);
 6. ✅ **Basic borrow checker (`@[Checked]`)** — Done (selfhost)
 7. ✅ **`bux fmt`, `bux test`, `bux new`, `bux init`** — Done (selfhost)
 8. ✅ **Closures (capture-less)** — Done. Enables callbacks and higher-order functions.
-9. **Closures with captures** — Needs capture analysis + environment struct. **← NEXT**
-10. **`for x in collection`** — Depends on closures with captures or trait system.
+9. ✅ **Closures with captures** — Done. Global env struct per closure AST node.
+10. **`for x in collection`** — Depends on closures with captures or trait system. **← NEXT**
 11. **Destructors / Drop** — High complexity, needs ownership + move semantics.