Add GC finalizer for WasmModule to prevent memory leaks

- MarkSweepGc: add finalizer registry (FinalizerEntry map)
  - registerFinalizer(ptr, deinit_fn): register non-GC object for cleanup
  - markFinalizer(ptr): mark as live during trace
  - sweepFinalizers(): invoke deinit on unmarked, called after sweep
  - deinit: run all remaining finalizers on shutdown
- wasm_types: register wasmModuleFinalizer in wrapInner()
  - gc_ref global set via setGc() from runner.zig/nrepl.zig
- gc.zig traceValue: wasm_module uses markFinalizer instead of markPtr
  - wasm_fn marks parent module alive (view into module, not independent)

Fixes: WasmModule allocated via wasm_alloc (non-GC) was never deinited
when CW GC collected the wrapper Value, leaking zwasm internal memory.

Author: chaploud

src/app/repl/nrepl.zig

@@ -76,6 +76,7 @@ pub fn startServer(gpa_allocator: Allocator, port: u16) !void {
     var env = Env.init(gpa_allocator);
     defer env.deinit();
     env.gc = @ptrCast(&gc);
+    @import("../../runtime/wasm_types.zig").setGc(&gc);
 
     registry.registerBuiltins(&env) catch {
         std.debug.print("Error: failed to register builtins\n", .{});

src/app/runner.zig

@@ -517,6 +517,8 @@ pub fn bootstrapFromCache(gc_alloc: Allocator, env: *Env, gc: ?*gc_mod.MarkSweep
     if (gc) |g| {
         g.threshold = @max(g.bytes_allocated * 2, g.threshold);
         env.gc = @ptrCast(g);
+        // Register GC reference for Wasm module finalizer support
+        @import("../runtime/wasm_types.zig").setGc(g);
     }
 }
 

src/runtime/gc.zig

@@ -172,6 +172,11 @@ pub const MarkSweepGc = struct {
     const MAX_FREE_POOLS = 16; // Up to 16 distinct (size, alignment) pairs
     const MAX_FREE_PER_POOL = 4096; // Max cached blocks per pool
 
+    pub const FinalizerEntry = struct {
+        marked: bool = false,
+        deinit_fn: *const fn (usize) void,
+    };
+
     pub const AllocInfo = struct {
         len: usize,
         alignment: Alignment,
@@ -213,6 +218,16 @@ pub const MarkSweepGc = struct {
     free_pools: [MAX_FREE_POOLS]FreePool = [_]FreePool{.{}} ** MAX_FREE_POOLS,
     free_pool_count: u8 = 0,
 
+    // --- Finalizer registry for non-GC-managed objects (e.g. WasmModule) ---
+    //
+    // Objects allocated outside the GC (via wasm_alloc, page_allocator, etc.)
+    // cannot be tracked by the normal mark-sweep allocations map. To ensure
+    // their deinit() is called when no GC roots reference them, we maintain
+    // a separate finalizer registry. Each entry stores a pointer and a
+    // deinit callback. During traceValue, live finalizable objects are marked
+    // via markFinalizer(). After sweep, unmarked finalizers are invoked.
+    finalizers: std.AutoArrayHashMapUnmanaged(usize, FinalizerEntry) = .empty,
+
     // --- Allocation profiling (37.1) ---
     alloc_buckets: if (profile_alloc) [MAX_ALLOC_BUCKETS]AllocBucket else void =
         if (profile_alloc) .{AllocBucket{ .size = 0, .count = 0, .total_bytes = 0 }} ** MAX_ALLOC_BUCKETS else {},
@@ -239,6 +254,11 @@ pub const MarkSweepGc = struct {
     }
 
     pub fn deinit(self: *MarkSweepGc) void {
+        // Run finalizers for all remaining finalizable objects
+        for (self.finalizers.keys(), self.finalizers.values()) |addr, entry| {
+            entry.deinit_fn(addr);
+        }
+        self.finalizers.deinit(self.backing);
         // Free all tracked allocations through backing
         const keys = self.allocations.keys();
         const vals = self.allocations.values();
@@ -297,6 +317,41 @@ pub const MarkSweepGc = struct {
         }
     }
 
+    /// Register a non-GC-managed object for finalizer-based cleanup.
+    /// When the object is no longer reachable (not marked during trace),
+    /// deinit_fn is called with the pointer address, then the entry is removed.
+    pub fn registerFinalizer(self: *MarkSweepGc, ptr: anytype, deinit_fn: *const fn (usize) void) void {
+        const addr = @intFromPtr(ptr);
+        self.finalizers.put(self.backing, addr, .{ .deinit_fn = deinit_fn }) catch {};
+    }
+
+    /// Mark a finalizable object as live during the trace phase.
+    pub fn markFinalizer(self: *MarkSweepGc, ptr: anytype) void {
+        const addr = @intFromPtr(ptr);
+        if (self.finalizers.getPtr(addr)) |entry| {
+            entry.marked = true;
+        }
+    }
+
+    /// Sweep finalizers: invoke deinit on unmarked entries, reset marks on live ones.
+    fn sweepFinalizers(self: *MarkSweepGc) void {
+        var i: usize = 0;
+        while (i < self.finalizers.count()) {
+            const vals = self.finalizers.values();
+            if (!vals[i].marked) {
+                const keys = self.finalizers.keys();
+                const addr = keys[i];
+                const entry = vals[i];
+                self.finalizers.swapRemoveAt(i);
+                entry.deinit_fn(addr);
+                // Don't increment — swapRemove moved last element to i
+            } else {
+                vals[i].marked = false;
+                i += 1;
+            }
+        }
+    }
+
     /// Sweep all unmarked allocations, recycling to free pools or freeing.
     /// Marked allocations have their mark bit reset for the next cycle.
     ///
@@ -493,6 +548,7 @@ pub const MarkSweepGc = struct {
         defer self.gc_mutex.unlock();
         traceRoots(self, roots);
         self.sweep();
+        self.sweepFinalizers();
     }
 
     fn gcShouldCollect(ptr: *anyopaque) bool {
@@ -519,6 +575,7 @@ pub const MarkSweepGc = struct {
         if (self.bytes_allocated < self.threshold) return;
         traceRoots(self, roots);
         self.sweep();
+        self.sweepFinalizers();
         // Grow threshold if live set is still above it (avoid re-triggering every cycle)
         if (self.bytes_allocated >= self.threshold) {
             self.threshold = self.bytes_allocated * 2;
@@ -1032,9 +1089,10 @@ pub fn traceValue(gc: *MarkSweepGc, val: Value) void {
             }
         },
 
-        // Wasm InterOp — opaque native objects, not GC-traced
-        .wasm_module => gc.markPtr(val.asWasmModule()),
-        .wasm_fn => gc.markPtr(val.asWasmFn()),
+        // Wasm InterOp — WasmModule allocated via wasm_alloc (non-GC), tracked by finalizer registry.
+        // WasmFn is a view into WasmModule — keep module alive when fn is reachable.
+        .wasm_module => gc.markFinalizer(val.asWasmModule()),
+        .wasm_fn => gc.markFinalizer(val.asWasmFn().module),
 
         .matcher => {
             const m = val.asMatcher();

src/runtime/wasm_types.zig

@@ -25,6 +25,16 @@ const zwasm = if (enable_wasm) @import("zwasm") else struct {};
 /// Without this, GC sweeps the ~1MB zwasm VM causing segfaults.
 const wasm_alloc = if (enable_wasm) std.heap.smp_allocator else std.heap.page_allocator;
 
+const gc_mod = @import("gc.zig");
+
+/// GC reference for finalizer registration. Set by main.zig after bootstrap.
+var gc_ref: ?*gc_mod.MarkSweepGc = null;
+
+/// Set the GC reference so WasmModule can register finalizers.
+pub fn setGc(gc: *gc_mod.MarkSweepGc) void {
+    gc_ref = gc;
+}
+
 // ============================================================
 // CW-specific types
 // ============================================================
@@ -117,9 +127,18 @@ pub const WasmModule = struct {
         self.export_fns = buildExportInfo(wasm_alloc, inner) catch &[_]ExportInfo{};
         self.cached_fns = buildCachedFns(wasm_alloc, self) catch &[_]WasmFn{};
         self.wit_funcs = &[_]wit_parser.WitFunc{};
+        // Register GC finalizer so deinit() is called when no roots reference this module
+        if (gc_ref) |gc| {
+            gc.registerFinalizer(self, wasmModuleFinalizer);
+        }
         return self;
     }
 
+    fn wasmModuleFinalizer(addr: usize) void {
+        const self: *WasmModule = @ptrFromInt(addr);
+        self.deinit();
+    }
+
     pub fn deinit(self: *WasmModule) void {
         if (comptime !enable_wasm) return;
         const allocator = self.allocator;