runtime: closure-cycle collector — honest env refcounts + registry mark-sweep

The env<->fn cycle (docs/CLOSURE_CYCLE_GC.md) is now reclaimed, both
mid-run and at exit, following the staged plan in the design note.

Stage 1 — Env lifetime is a real refcount. env_refcount counts every
owner: creator/frame, closures (make_fn), child envs (the parent link
is an owned edge), and a chunk's parked env_cache. env_free's
captured-gated semantics are replaced by env_incref/env_decref;
LOOP_ENV_FRESH/END move the frame's ref explicitly (also fixing the
latent fn_env leak on early return from a loop scope); vm_park_call_env
requires refcount == 1 and the parked env keeps its owned parent ref,
making the take-side parent compare dangling-pointer-free. OP_IMPORT
releases the module env's creator ref so fn-free modules are reclaimed.

Stage 2 — the collector. Captured envs register in a per-thread
intrusive list at OP_CLOSURE (global env excluded); collection triggers
from the registration threshold (zero cost on dispatch/call hot paths)
and once at exit. The universe is everything reachable from registered
envs over owned edges only — env slots, parent, fn->closure, fn->chunk,
chunk->functions[], chunk->env_cache, list/dict elements — and roots
are derived from refcounts alone: any node whose rc exceeds its
in-universe reference count has an external holder, so no VM root-set
enumeration exists to get wrong. Accounting mismatches abort the
collection (leak, never free). Unmarked nodes are pinned, edge-cleared,
and released through the ordinary destructors. gc_collect_at_exit
additionally snapshots global container bindings (pinned, accounted) so
global-scope pure value cycles — a list appended to itself — die at
teardown. spawn() drains the registry and disables collection; spawned
programs keep the previous tolerated-leak behavior, still visible to
LSan.

Results: 500 discarded closures leak 0 allocations (was 6,004); a 100k
closure-churn loop runs ~40% faster with peak RSS 124 MB -> 4.3 MB;
bench_perf / bench_dmg_shape / bench_idxset are flat. Suite: 1832/1832
release and ASan (detect_leaks=1); tolerated-leak tally 28 -> 13, every
remaining report byte-identical to the pre-collector baseline
(spawn-thread programs + pre-existing non-closure shapes); fuzz 44/44.
test_closure_cycles.eigs (17 checks, incl. dict-routed cycles) is now
gated strictly leak-clean — section [87] opts out of rc_ok's tolerance,
so a collector regression fails CI instead of being tallied.

https://claude.ai/code/session_01UiKD8EDViybJuxHbHLr9TW

Author: claude

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to EigenScript are documented here.
 
+## [Unreleased]
+
+### Runtime — closure-cycle collector
+
+- **The env↔fn closure-cycle leak is fixed** (docs/CLOSURE_CYCLE_GC.md).
+  Escaping closures — `define inner ... return inner`, counters,
+  per-iteration handler closures, method dicts — are now reclaimed, both
+  mid-run (registry-threshold collections triggered at closure-capture
+  time, zero cost on the dispatch hot paths) and at exit. A
+  100k-iteration closure-churn loop runs ~40% faster with peak RSS down
+  from ~124 MB to ~4 MB; long-running programs that build closures over
+  time no longer grow without bound.
+- **`Env` lifetime is an honest refcount.** `env_refcount` now counts
+  every owner: the creating frame or C caller, closures, child envs (the
+  `parent` link is an owned edge), and a chunk's parked recycled call
+  env. `env_free`'s captured-gated semantics are replaced by plain
+  `env_incref`/`env_decref`; loop-scope envs move the frame's ref
+  explicitly. This also fixes latent leaks on early `return` from inside
+  a loop scope and makes the env-recycling parent compare
+  dangling-pointer-free.
+- **Exit teardown reclaims global-scope value cycles** too (e.g. a list
+  appended to itself), via a pinned snapshot of global bindings before
+  the final collection. `import` module envs are released when the last
+  closure defined in them dies (previously leaked unconditionally).
+- The collector is conservative by construction: roots are derived from
+  refcounts (any uncounted holder makes a node a root), and an
+  accounting mismatch aborts the collection — the failure mode is a
+  leak, never a use-after-free. Disabled once `spawn` goes
+  multithreaded; spawned programs keep the previous behavior.
+- Suite: `tests/test_closure_cycles.eigs` (now 17 checks, incl. dict-
+  routed cycles and 500 discarded counters) is gated **strictly**
+  leak-clean under ASan — section [87] no longer tolerates a
+  LeakSanitizer exit. The suite-wide tolerated-leak tally drops 28 → 13;
+  every remaining report is byte-identical to the pre-collector
+  baseline (spawn-thread programs + pre-existing non-closure shapes).
+
 ## [0.13.0] — 2026-06-12
 
 A language-features release.

CLAUDE.md

@@ -18,13 +18,15 @@ make jit-smoke  # standalone emitter tests (jit_smoke.c stubs all helpers)
 
 - The suite must pass **both** release and ASan with leaks on:
   `make asan && cd tests && ASAN_OPTIONS=detect_leaks=1 bash run_all_tests.sh`
-  CI enforces `detect_leaks=1`. Known limit: a fn bound by `define`
-  inside the env it captures is an env↔fn refcount cycle the runtime
-  can't reclaim, so closure-heavy tests exit nonzero on a LeakSanitizer
-  report after fully correct output. The runner's `rc_ok` tolerates
-  exactly that case and tallies it in the final summary ("NOTE: N test
-  program(s)..."); any other nonzero exit — crash, assert, UBSan — fails.
-  Watch that tally: a jump means a new leak.
+  CI enforces `detect_leaks=1`. The env↔fn closure cycle is reclaimed by
+  the cycle collector (docs/CLOSURE_CYCLE_GC.md); section [87]
+  (test_closure_cycles.eigs) is gated **strictly** leak-clean — a
+  LeakSanitizer exit there is a collector regression. The runner's
+  `rc_ok` still tolerates LeakSanitizer exits elsewhere and tallies them
+  ("NOTE: N test program(s)..."): currently 13, all spawn-thread
+  programs (collector off once multithreaded) plus pre-existing
+  non-closure shapes. Any other nonzero exit — crash, assert, UBSan —
+  fails. Watch that tally: a jump means a new leak.
 - `make asan` overwrites `src/eigenscript` — rebuild with `make`
   before timing anything.
 - Benchmarks: `tests/bench_perf.eigs` (micro), `tests/bench_dmg_shape.eigs`
@@ -58,7 +60,20 @@ make jit-smoke  # standalone emitter tests (jit_smoke.c stubs all helpers)
   run_all_tests.sh): marker-grep alone used to let a crash *after*
   correct output pass. New .eigs sections should use `check_eigs_suite`
   (rc + marker). The one tolerated nonzero exit is a LeakSanitizer
-  report (known closure-cycle leaks — see the ASan bullet above).
+  report (spawn-thread programs + known non-closure shapes — see the
+  ASan bullet above; section [87] deliberately opts out of that
+  tolerance).
+- **Env refcounts are honest and the cycle collector depends on it**:
+  every owner of an `Env` — frame/creator, closure (`make_fn`), child
+  env (`parent` is an owned edge), parked `chunk->env_cache` — holds a
+  counted ref via `env_incref`/`env_decref`. Never stash a bare `Env*`
+  that outlives its creator. The collector's `GC_FOR_EACH_CHILD` walker
+  and `gc_clear_node` (eigenscript.c) must move in lockstep with the
+  ownership model: a new owning edge out of Value/Env/Chunk goes into
+  both, and only *counted* edges may be traversed (an uncounted edge
+  trips the accounting abort and collection silently stops working).
+  Conservative direction: missing an edge leaks; inventing one frees
+  live memory.
 - **New JIT helpers need stubs in `src/jit_smoke.c`** or `make
   jit-smoke` fails to link.
 - **JIT emitter invariants** (`src/jit.c`): the scanner and the
@@ -121,9 +136,16 @@ make jit-smoke  # standalone emitter tests (jit_smoke.c stubs all helpers)
   /dev/null — `test_terminal.eigs` blocks forever reading a pipe that
   never EOFs (e.g. backgrounded runs).
 
-## Current state: 0.13.0 released; next up
+## Current state: 0.13.0 released + closure-cycle collector; next up
 
-0.13.0 is cut (CHANGELOG.md [0.13.0] is the full record). Highlights on
+0.13.0 is cut (CHANGELOG.md [0.13.0] is the full record). Landed since,
+unreleased: the **closure-cycle collector** — honest `Env` refcounts
+(creator/frame + closures + parent links + parked env_cache all
+counted; `env_free` → `env_incref`/`env_decref`) plus a registry-driven
+mark-sweep over captured envs (docs/CLOSURE_CYCLE_GC.md is the as-built
+record, including the maintainer invariants). Escaping closures are
+reclaimed mid-run and at exit; closure churn is ~40% faster with flat
+RSS; disabled once spawn() goes multithreaded. 0.13.0 highlights on
 top of the language-features run (destructuring, slicing, negative
 indexing, default params, streaming subprocess I/O, recv_timeout,
 multi-arg spawn) and the twelve post-merge fixes (#148–#159):
@@ -156,15 +178,12 @@ multi-arg spawn) and the twelve post-merge fixes (#148–#159):
   cannot push tags, and GITHUB_TOKEN-pushed tags don't retrigger
   workflows — hence the dispatch path.
 
-Suite: ~1830 checks; must pass release **and** ASan with
-detect_leaks=1 (the leak tally — currently 28 — is the gate; a jump
-means a new leak).
+Suite: ~1832 checks; must pass release **and** ASan with
+detect_leaks=1 (the leak tally — currently 13, spawn-thread programs +
+pre-existing non-closure shapes — is the gate; a jump means a new
+leak, and section [87] must stay strictly leak-clean).
 
 Open items, in rough priority:
-- **Closure-cycle collector** — the env↔fn cycle accumulates (~12
-  allocs per escaping closure). Design + staging in
-  docs/CLOSURE_CYCLE_GC.md; it's a dedicated reviewed project (every
-  shortcut is a use-after-free; see the doc before attempting).
 - **`make lsp` fails on macOS runners** (skipped cleanly by the suite;
   add the compile check to the macOS CI leg to surface the error).
 - Windows port (runtime is POSIX-only), package/dependency story,

docs/ARCHITECTURE.md

@@ -201,10 +201,25 @@ malloc/free churn in arithmetic-heavy loops.
 1024 entries) and reused by `env_new`, avoiding allocation in tight
 function-call loops.
 
-**Closure environments.** Environments captured by closures
-(`env->captured = 1`) track a reference count (`env_refcount`, atomic).
-When the last closure referencing an env is freed, the env becomes
-eligible for cleanup.
+**Environment lifetime.** Every `Env` carries an honest reference count
+(`env_refcount`, atomic once spawn() goes multithreaded). The owners are:
+the creating frame or C caller, each closure capturing the env
+(`make_fn`), each child env (the `parent` link is an owned reference),
+and a chunk's parked recycled call env (`env_cache`). `env_decref`
+destroys at zero — there is no special-cased teardown path.
+
+**Cycle collector.** An env that binds a closure capturing it forms an
+`env<->fn` reference cycle that plain counts cannot reclaim. Captured
+envs register in a per-thread list; when the registry crosses an
+adaptive threshold (and once at exit), `gc_collect_cycles` walks the
+subgraph reachable from registered envs over owned edges (env slots,
+`parent`, `fn->closure`, list/dict elements, `fn->chunk->env_cache`),
+counts in-subgraph references per node, and treats any node whose
+refcount exceeds that count as externally rooted. Unmarked remainder is
+cyclic garbage: pinned, edge-cleared, then released through the normal
+destructors. Conservative by construction — any accounting mismatch
+aborts the collection (leaking instead of freeing). Disabled once
+spawn() goes multithreaded. See `docs/CLOSURE_CYCLE_GC.md`.
 
 ## Extensions