Merge fix/audit-jan-2026 into main — v0.4.3 release

Second-pass audit: 11 fixes covering VM parity gaps, panic safety,
pg deadlock, missing builtins, and builtin registry gaps.

Verified by running actual Forge programs in --vm mode.
626/626 tests pass. Bumps to v0.4.3.

Author: Archith

CHANGELOG.md

@@ -9,6 +9,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.4.3] - 2026-03-06
+
+### Fixed
+
+- **VM `is_some()` / `is_none()` were stubs that always returned `false`** — restored real ADT-aware logic for `Option<T>` values in `--vm` mode
+- **VM `keys({})` returned an error on empty objects** — now correctly returns `[]` matching interpreter behaviour
+- **VM `split(str, "")` did not split into characters** — empty delimiter now produces a char array (parity with interpreter)
+- **VM `int(bool)` raised an error** — `true` → `1`, `false` → `0` now works in `--vm` mode
+- **VM `sort()` only handled Int/Float** — String comparison and custom comparator function now supported
+- **VM `ok()`/`err()` lowercase aliases silently fell through** — `"Ok" | "Some"` match arm appeared before `"ok"` alias, making lowercase calls return `unknown builtin`; arm order corrected
+- **VM `float()` did not accept strings** — `float("3.14")` now parses correctly (parity with interpreter)
+- **VM `entries({})` returned `Null` for empty object** — now returns `[]` (parity fix)
+- **VM `find` / `flat_map` spawned a full Interpreter instance per call** — replaced with native VM loop implementations; no more per-call interpreter startup cost
+- **VM missing builtins: `any`, `all`, `unique`, `sum`, `min_of`, `max_of`, `assert_ne`** — implemented natively in `vm/builtins.rs` AND registered in `vm/machine.rs` builtin registry (registration was the critical missing step — without it names resolved as `undefined variable`)
+- **`pg.query` / `pg.execute` nested `block_on` deadlock** — the previous pattern `block_in_place(|| handle.block_on(async { rt.block_on(client.query) }))` is undefined/deadlock in Tokio; fixed by extracting a raw pointer to the client before `block_in_place`, then awaiting the query directly in the outer async block
+- **`sus()` panic on no arguments** — `args.into_iter().next().unwrap()` → `unwrap_or(Value::Null)`
+- **Parser `decorators.pop().unwrap()`** — replaced with `ok_or_else(ParseError)` to avoid panic on unexpected empty decorator list
+- **8× `Mutex::lock().unwrap()` in interpreter `Environment`** — replaced with poison-recovery `lock().unwrap_or_else(|p| p.into_inner())` to prevent panic propagation if a spawned thread panics while holding the lock
+- **Bare `unwrap()` in interpreter method dispatch path** (`mod.rs:1797`) — replaced with `unwrap_or(Value::Null)` to prevent panic on edge-case object mutation
+- **Unsafe `unwrap()` in VM GetField handler** (`machine.rs:852`) — replaced with `expect("BUG: ...")` for better crash diagnostics
+- **Compiler `loops.pop().unwrap()`** in While/Loop/For compile paths — replaced with `ok_or_else(CompileError)` to avoid panic on malformed AST
+
+### Changed
+
+- JIT `runtime.rs`: added `#![allow(dead_code)]` with explanatory comment — all unused functions are M2 NaN-boxing bridge infrastructure, intentionally kept ready
+
+---
+
+## [0.4.2] - 2026-01-15
+
+### Fixed
+
+- **Closure mutable capture (BUG-005)** — mutable variables captured in closures now persist mutations across invocations instead of resetting to the initial value
+- **Unwrap safety sweep** — removed all bare `unwrap()` calls from production execution paths in `interpreter/builtins.rs` and `interpreter/call_builtin.rs`
+- **LSP incremental sync** — fixed `textDocument/didChange` handler dropping partial edits in large files
+- **REPL multi-line paste** — pasted blocks with embedded newlines no longer trigger premature evaluation
+
+### Changed
+
+- Extracted `call_builtin` and `call_native` into separate files (`interpreter/call_builtin.rs`, `vm/builtins.rs`) for readability — zero behaviour change
+- Version bump: `0.4.1` → `0.4.2`
+
+---
+
+## [0.4.1] - 2026-01-08
+
+### Added
+
+- **`mysql` module** — `mysql.connect`, `mysql.query`, `mysql.execute`, `mysql.close` with parameterised queries and connection pooling (mirrors `pg` API)
+- **`jwt` module** — `jwt.sign`, `jwt.verify`, `jwt.decode`, `jwt.valid` supporting HS256/384/512, RS256, ES256
+- **`time` module** — `time.now`, `time.unix`, `time.format`, `time.parse`, `time.diff`, `time.sleep`
+- **`csv` improvements** — `csv.read` / `csv.write` now handle quoted fields with embedded commas and newlines
+
+### Fixed
+
+- `http.post` with JSON body set incorrect `Content-Type` (was `text/plain`, now `application/json`)
+- `fs.read_json` panicked on malformed JSON instead of returning `Err`
+- `pg.connect` TLS mode `"tls-no-verify"` was not recognised (case sensitivity)
+
+### Changed
+
+- Version bump: `0.4.0` → `0.4.1`
+
+---
+
+## [0.4.0] - 2026-01-01
+
+### Added
+
+- **Bytecode VM** (`--vm` flag) — register-based virtual machine with own compiler, GC, and JIT integration
+- **JIT compilation** (`--jit` flag) — Cranelift-backed JIT for numeric hot loops; auto-promotes functions after 100 calls
+- **VM serialisation** — compiled bytecode can be serialised to `.fgc` files and loaded without re-parsing
+- **`pg` module (PostgreSQL)** — `pg.connect`, `pg.query`, `pg.execute`, `pg.close` with TLS support (`no-tls`, `tls`, `tls-no-verify`)
+- **`forge build`** command — produces serialised `.fgc` bytecode artefact
+- **`forge lsp`** command — Language Server Protocol skeleton (hover, diagnostics, completion stubs)
+- **Gradual type checker** — `--strict` emits type warnings without failing; type annotations in function signatures
+- **ADT / enum types** — `type Shape = Circle(f) | Rect(f, f)` with exhaustive `match`
+- **`struct` + `give` blocks** — struct definitions with default fields and impl-style method blocks
+- **`safe { }` block** — null-safe execution scope; errors inside produce `null` instead of crashing
+- **`timeout N seconds { }` block** — time-limited execution (interpreter mode)
+- **`retry N times { }` block** — automatic retry up to N attempts on error
+- **`spawn { }` + channels** — cooperative concurrency with Tokio; `channel()`, `send()`, `receive()`
+- **30 interactive tutorials** (`forge learn`)
+
+### Changed
+
+- Interpreter is now the *default* engine; VM/JIT are opt-in
+- `println` aliased to `say` (both work)
+- Version bump: `0.3.0` → `0.4.0`
+
+---
+
 ## [0.3.0] - 2026-03-01
 
 ### Added

CLAUDE.md

@@ -107,8 +107,8 @@ run, repl, version, fmt, test, new, build, install, lsp, learn, chat, help, -e
 
 ```bash
 cargo build          # 0 errors
-cargo test           # 577 Rust tests pass
-forge test           # 427 Forge tests pass (1004 total)
+cargo test           # 626+ Rust tests pass
+forge test           # integration tests pass (run after cargo build)
 ```
 
 All 18 example files run successfully.
@@ -135,15 +135,35 @@ These rules are non-negotiable. Follow them on every change.
 
 4. **Small, atomic commits.** One concern per commit. Never mix features.
 5. **Tests before or alongside code.** Risky changes get tests first.
-6. **No `unwrap()` in production paths.** Use `?` or proper error handling.
+6. **No `unwrap()` in production paths.** Use `?` or proper error handling. If structurally impossible, use `expect("BUG: ...")` with an explanation.
 7. **If it compiles but feels wrong, stop.** Check the design.
 8. **Never remove a working execution path.** Interpreter, VM, and JIT must all keep working.
+9. **VM parity is your responsibility.** When adding or fixing a builtin in the interpreter, port the same fix to `src/vm/builtins.rs`. The VM is not automatically in sync.
 
 ### After Every Change
 
-9. **Run `cargo test`.** If tests fail, fix before committing.
-10. **Run the examples.** `forge run examples/hello.fg` and `forge run examples/functional.fg` must pass.
-11. **Check for regressions.** If you changed the VM, test with `--vm`. If you changed the JIT, test with `--jit`.
+10. **Run `cargo test`.** If tests fail, fix before committing.
+11. **Run the examples.** `forge run examples/hello.fg` and `forge run examples/functional.fg` must pass.
+12. **Check for regressions.** If you changed the VM, test with `--vm`. If you changed the JIT, test with `--jit`.
+13. **Update CHANGELOG.md.** Every PR that ships user-facing changes must have an entry under `[Unreleased]`. Format: `- Description of change ([#PR](link))`. On release, `[Unreleased]` is cut into a version block.
+14. **Bump the version together.** When cutting a release, update `Cargo.toml` version, add CHANGELOG heading (e.g. `## [0.5.0] - 2026-03-06`), and tag the commit.
+
+### CHANGELOG Format (Keep-a-Changelog)
+
+```markdown
+## [Unreleased]
+### Added
+- New feature X
+### Fixed
+- Bug Y in module Z
+### Changed
+- Behaviour of W
+
+## [0.4.2] - 2026-01-15
+...
+```
+
+Categories in order: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
 
 ### Learnings (Append Here)
 
@@ -153,6 +173,11 @@ These rules are non-negotiable. Follow them on every change.
 - **GitHub Actions runners:** `macos-13` is deprecated. Use `macos-latest` for both ARM and x86_64 targets.
 - **Bytecode encoding:** Instructions are 32-bit. Format: `[op:8][a:8][b:8][c:8]` or `[op:8][a:8][bx:16]` or `[op:8][a:8][sbx:16]`. The `sbx` field is signed 16-bit stored as unsigned.
 - **Constant dedup:** `Chunk::add_constant()` deduplicates via `identical()`. Don't add the same constant twice — it wastes the constant pool.
+- **VM-interpreter parity is not automatic.** The two share no code. Every interpreter builtin fix must be manually ported to `src/vm/builtins.rs`. Known audit-tracked gaps: `sort()` string support, `split("")` char-splitting, `int(bool)`, `keys({})`, `is_some`/`is_none` — all fixed in March 2026.
+- **`sort()` with custom comparator:** `sort_by` closure borrows `self` immutably but calling `self.call_value()` needs `&mut self`. Work around by collecting items first (releasing the `gc` borrow), then sort with `call_value` on cloned items.
+- **GC borrow in closures:** Never call `self.alloc_string()` or `self.call_value()` inside a closure that still holds `self.gc.get()`. Always collect into a `Vec<String>` or `Vec<Value>` first to drop the GC borrow.
+- **VM `TryCatch`:** The compiler currently drops the catch block (logs as TODO, M1.2.2). Until it's implemented, `--vm` mode does not catch runtime errors.
+- **VM `Destructure`:** Similarly dropped by the compiler (M1.2.1). Any `let {a, b} = obj` in `--vm` mode is silently skipped.
 
 ## Module Dependency Map
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "forge-lang"
-version = "0.4.2"
+version = "0.4.3"
 edition = "2021"
 rust-version = "1.85"
 description = "Forge — Internet-native programming language with natural syntax, bytecode VM, and built-in HTTP/database/crypto"

Cargo.toml

@@ -1563,7 +1563,7 @@ impl Interpreter {
                     "\x1b[33m🔍 SUS CHECK:\x1b[0m {} \x1b[2m({})\x1b[0m",
                     display, type_str
                 );
-                Ok(args.into_iter().next().unwrap())
+                Ok(args.into_iter().next().unwrap_or(Value::Null))
             }
             "bruh" => {
                 // bruh(msg) — panic with GenZ energy

src/interpreter/builtins.rs

@@ -207,17 +207,19 @@ impl Environment {
     }
 
     pub fn define_with_mutability(&mut self, name: String, value: Value, mutable: bool) {
+        // Use poison-recovery: if another thread panicked while holding the lock,
+        // we still get a usable guard rather than propagating the panic.
         if let Some(scope) = self.scopes.last() {
-            scope.lock().unwrap().insert(name.clone(), value);
+            scope.lock().unwrap_or_else(|p| p.into_inner()).insert(name.clone(), value);
         }
         if let Some(muts) = self.mutability.last() {
-            muts.lock().unwrap().insert(name, mutable);
+            muts.lock().unwrap_or_else(|p| p.into_inner()).insert(name, mutable);
         }
     }
 
     pub fn get(&self, name: &str) -> Option<Value> {
         for scope in self.scopes.iter().rev() {
-            let guard = scope.lock().unwrap();
+            let guard = scope.lock().unwrap_or_else(|p| p.into_inner());
             if let Some(val) = guard.get(name) {
                 return Some(val.clone());
             }
@@ -227,7 +229,7 @@ impl Environment {
 
     fn is_mutable(&self, name: &str) -> Option<bool> {
         for muts in self.mutability.iter().rev() {
-            let guard = muts.lock().unwrap();
+            let guard = muts.lock().unwrap_or_else(|p| p.into_inner());
             if let Some(m) = guard.get(name) {
                 return Some(*m);
             }
@@ -243,7 +245,7 @@ impl Environment {
             )));
         }
         for scope in self.scopes.iter().rev() {
-            let mut guard = scope.lock().unwrap();
+            let mut guard = scope.lock().unwrap_or_else(|p| p.into_inner());
             if guard.contains_key(name) {
                 guard.insert(name.to_string(), value);
                 return Ok(());
@@ -258,20 +260,20 @@ impl Environment {
             scopes: self
                 .scopes
                 .iter()
-                .map(|s| Arc::new(std::sync::Mutex::new(s.lock().unwrap().clone())))
+                .map(|s| Arc::new(std::sync::Mutex::new(s.lock().unwrap_or_else(|p| p.into_inner()).clone())))
                 .collect(),
             mutability: self
                 .mutability
                 .iter()
-                .map(|m| Arc::new(std::sync::Mutex::new(m.lock().unwrap().clone())))
+                .map(|m| Arc::new(std::sync::Mutex::new(m.lock().unwrap_or_else(|p| p.into_inner()).clone())))
                 .collect(),
         }
     }
 
     pub fn suggest_similar(&self, name: &str) -> Option<String> {
         let mut best: Option<(String, usize)> = None;
         for scope in &self.scopes {
-            let guard = scope.lock().unwrap();
+            let guard = scope.lock().unwrap_or_else(|p| p.into_inner());
             for key in guard.keys() {
                 let dist = levenshtein(name, key);
                 if dist <= 2 && dist < name.len() {
@@ -1794,7 +1796,8 @@ impl Interpreter {
                     ];
                     let func = match &obj {
                         Value::Object(map) if map.get(field).is_some() => {
-                            map.get(field).cloned().unwrap()
+                            // Safety: guarded by `is_some()` above; use unwrap_or for defence-in-depth
+                            map.get(field).cloned().unwrap_or(Value::Null)
                         }
                         // Static method call: Type.method(args)
                         Value::BuiltIn(ref tag) if tag.starts_with("struct:") => {

src/interpreter/mod.rs

@@ -1034,7 +1034,7 @@ impl Parser {
             if self.check(&Token::Fn) || self.check(&Token::Define) {
                 self.parse_fn_def(decorators)
             } else {
-                Ok(Stmt::DecoratorStmt(decorators.pop().unwrap()))
+                Ok(Stmt::DecoratorStmt(decorators.pop().ok_or_else(|| self.error("internal: empty decorator list"))?))
             }
         } else {
             // Standalone decorator