closures capture outer-scope let by value; mutations invisible after closure runs

[cs01]

Bug

Closures capture outer-scope variables by value, not by reference. Mutations to a captured let inside a closure are not visible in the outer scope after the closure runs.

Example:

let done = false;
socket.on("connect", () => {
  done = true;          // modifies inner copy
});
// ...
if (!done) { /* this branch always runs even after 'connect' fires */ }

Impact

Event-driven code can't signal completion to the outer scope via captured flags. Hit in tests/fixtures/net/tcp-echo.ts (PR #585) — the test had to signal via stdout sentinel lines instead of a captured boolean.

Note

This is a design question as much as a bug — full reference capture requires box-allocation of captured vars. May need an RFC before implementation. Lower priority than the straight codegen bugs but should be tracked.

[cs01]

Design options captured from discussion

1. Box all captured lets — simple codegen, uniform. Every captured let becomes a heap cell; reads/writes go through a load/store. Cost: an allocation per captured mutable, indirect access even when not needed.

2. Box only mutated ones — needs a semantic pass (mutation-after-capture analysis, which closure-mutation-checker.ts already partially does) to decide per-variable. More complex, better perf.

3. Document by-value + compile-error on post-capture mutation — current behavior, just make it loud. Zero runtime cost, but breaks idiomatic JS patterns users will expect to work.

Current state

Option 3 is already shipped: src/semantic/closure-mutation-checker.ts detects post-capture assignments and emits a compile error before codegen (called from LLVMGenerator.generateParts()). The example in the bug description now gets rejected at compile time rather than producing silently wrong native code.

Path forward

Short-term: option 3 holds (already in place).
Long-term: option 2 (box only mutated vars). Leverage the existing mutation analysis in closure-mutation-checker — instead of rejecting, tag the variable as "needs boxing" and teach codegen to emit an i8* heap cell + load/store for those specific captures. Keep option 1 off the table (uniform boxing is a perf regression for the common non-mutated case).