Serialize Protocol/ProtocolFn in bootstrap cache, fix startup regression (D95)

Startup regressed 4.5ms→23.3ms and memory 10MB→226MB because
reloadProtocolNamespaces re-evaluated ~440 lines of protocols.clj +
reducers.clj at every startup. Fix by making Protocol/ProtocolFn values
serializable in the bootstrap cache (D81).

Key changes:
- Protocol: serialize name + method_sigs + impls (nested type→method maps)
- ProtocolFn: serialize method_name + protocol var ref (deferred fixup)
- Fn: serialize closure_bindings (captured upvalues)
- Protocol.generation counter + ProtocolFn.cached_generation for cache
  invalidation when impls change (fixes reify stale cache bug)
- extend_type_method: replace existing methods instead of always appending
- Remove reloadProtocolNamespaces from bootstrap restore path
- Simplify bootstrapFromCache (remove gc parameter, protocol reload)

Result: startup 23.3ms→5.3ms (4.4x), memory 226MB→8.1MB (28x reduction).

Author: chaploud

.dev/decisions.md

@@ -560,3 +560,26 @@ all to reach safe points, then collect with combined root sets.
 **Scope**: Phase 48.2 adds the mutex + registry. Thread spawning (48.3) will
 integrate safe-point coordination. Future optimization: concurrent marking,
 thread-local allocation buffers (TLABs), generational collection.
+
+## D95: Protocol/ProtocolFn Serialization — Eliminating Startup Re-evaluation
+
+**Problem**: After D81 (bootstrap cache), Protocol and ProtocolFn values were not
+serializable. `restoreFromBootstrapCache` called `reloadProtocolNamespaces` to
+re-evaluate protocols.clj + reducers.clj (~440 lines) via TreeWalk at every startup,
+causing 23.3ms startup time and 226MB memory usage.
+
+**Decision**: Serialize Protocol and ProtocolFn values in the bootstrap cache.
+Protocol stores name + method_sigs + impls (nested map of type_key → method_map).
+ProtocolFn stores method_name + protocol var reference (ns + name), resolved via
+deferred fixup after env restore. Fn closure_bindings also serialized.
+
+**Cache invalidation**: Protocol gains a `generation` counter, incremented on every
+`extend_type_method` / `extend-type` call. ProtocolFn inline cache checks
+`cached_generation == protocol.generation` to detect stale entries. This fixes a
+latent bug where VM-compiled reify forms share compile-time type keys, causing the
+monomorphic cache to return stale methods when the same type key gets new impls.
+Also fixed `extend_type_method` to replace existing methods (same name) in the
+method map instead of always appending.
+
+**Result**: Startup 23.3ms → 5.3ms (4.4x), memory 226MB → 8.1MB (28x reduction).
+All upstream tests pass, no regression.

.dev/memo.md

@@ -21,21 +21,21 @@ Native production-grade Clojure runtime. Differentiation vs Babashka:
 
 ## Current Task
 
-Ready for next phase planning. See Task Queue below.
+Phase 60: Startup & Memory Optimization.
+Task 60.3: Binary size audit and optimization.
 
 ## Task Queue
 
-(empty — plan next phase)
+- 60.3: Binary size audit and optimization
+- 60.4: Record benchmarks, update docs
 
 ## Previous Task
 
-F99 fix: apply on infinite lazy seq. Added lazy variadic path to applyFn
-(cons chain + peel fixed params, threadlocal flag for VM/TreeWalk rest packing).
-
-Previous:
-
-Phase 59: Deferred cleanup & test porting (ALL DONE).
-59.1-59.2: Ratio/promote ops upstream tests, coercion fixes.
+Phase 60.1-60.2 complete: Protocol/ProtocolFn serialization (D95).
+Root cause: reloadProtocolNamespaces re-evaluated ~440 lines at every startup.
+Fix: Serialize Protocol/ProtocolFn in bootstrap cache + generation counter
+for ProtocolFn inline cache + method replacement in extend_type_method.
+Result: startup 23.3ms → 5.3ms, memory 226MB → 8.1MB.
 
 ## Known Issues
 

src/compiler/serialize.zig

@@ -849,7 +849,9 @@ pub const TreeWalk = struct {
         // Monomorphic inline cache: check if same type as last dispatch
         const mutable_pf: *value_mod.ProtocolFn = @constCast(pf);
         if (mutable_pf.cached_type_key) |ck| {
-            if (ck.ptr == type_key.ptr or std.mem.eql(u8, ck, type_key)) {
+            if (mutable_pf.cached_generation == pf.protocol.generation and
+                (ck.ptr == type_key.ptr or std.mem.eql(u8, ck, type_key)))
+            {
                 return self.callValue(mutable_pf.cached_method, args);
             }
         }
@@ -866,6 +868,7 @@ pub const TreeWalk = struct {
         // Update cache
         mutable_pf.cached_type_key = type_key;
         mutable_pf.cached_method = fn_val;
+        mutable_pf.cached_generation = pf.protocol.generation;
 
         // Call the impl function
         return self.callValue(fn_val, args);
@@ -954,6 +957,7 @@ pub const TreeWalk = struct {
         const new_impls = self.allocator.create(value_mod.PersistentArrayMap) catch return error.OutOfMemory;
         new_impls.* = .{ .entries = new_entries };
         protocol.impls = new_impls;
+        protocol.generation +%= 1;
 
         return Value.nil_val;
     }
@@ -1007,6 +1011,7 @@ pub const TreeWalk = struct {
             const new_impls = self.allocator.create(value_mod.PersistentArrayMap) catch return error.OutOfMemory;
             new_impls.* = .{ .entries = new_entries };
             protocol.impls = new_impls;
+            protocol.generation +%= 1;
         }
 
         // Create reified object: a map with __type key

src/evaluator/tree_walk.zig

@@ -251,9 +251,7 @@ pub fn main() !void {
         // No args, no file, no :main — start REPL
         var env = Env.init(allocator);
         defer env.deinit();
-        bootstrapFromCache(alloc, &env);
-        gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-        env.gc = @ptrCast(&gc);
+        bootstrapFromCache(alloc, &env, &gc);
         runRepl(alloc, &env, &gc);
     }
 }
@@ -435,12 +433,7 @@ fn evalAndPrint(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSwe
     // bootstrap and evaluation use gc_alloc (MarkSweepGc) for Values.
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-
-    // Enable GC for user evaluation (bootstrap runs without GC).
-    // Reset threshold to avoid immediate sweep on first safe point.
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Dump bytecode if requested (VM only, dump to stderr then exit)
     if (dump_bytecode) {
@@ -486,9 +479,7 @@ fn runMainNs(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepG
     _ = use_vm;
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Generate and evaluate (require 'main-ns)
     var buf: [4096]u8 = undefined;
@@ -505,7 +496,9 @@ fn runMainNs(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepG
 /// Initialize env from pre-compiled bootstrap cache (D81).
 /// Registers builtins (Zig function pointers), then restores Clojure-defined
 /// Vars from the serialized env snapshot embedded at build time.
-fn bootstrapFromCache(gc_alloc: Allocator, env: *Env) void {
+/// Protocol/ProtocolFn values are now serialized directly in the cache,
+/// so no re-evaluation of protocols.clj/reducers.clj is needed.
+fn bootstrapFromCache(gc_alloc: Allocator, env: *Env, gc: ?*gc_mod.MarkSweepGc) void {
     registry.registerBuiltins(env) catch {
         std.debug.print("Error: failed to register builtins\n", .{});
         std.process.exit(1);
@@ -515,6 +508,12 @@ fn bootstrapFromCache(gc_alloc: Allocator, env: *Env) void {
         std.process.exit(1);
     };
     markBootstrapLibs();
+
+    // Enable GC after cache restore for subsequent evaluation.
+    if (gc) |g| {
+        g.threshold = @max(g.bytes_allocated * 2, g.threshold);
+        env.gc = @ptrCast(g);
+    }
 }
 
 /// Mark built-in namespaces as loaded so require skips them.
@@ -551,9 +550,7 @@ fn handleTestCommand(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.Ma
     // Bootstrap
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Load cljw.edn config
     var config_arena = std.heap.ArenaAllocator.init(infra_alloc);
@@ -1565,15 +1562,11 @@ fn readEmbeddedSource(allocator: Allocator) ?[]const u8 {
 fn evalEmbedded(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepGc, source: []const u8, cli_args: []const [:0]const u8) void {
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Set *command-line-args*
     setCommandLineArgs(gc_alloc, &env, cli_args);
 
-    // Enable GC
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
-
     // Evaluate using VM backend
     _ = bootstrap.evalStringVM(gc_alloc, &env, source) catch |e| {
         reportError(e);
@@ -1591,10 +1584,7 @@ fn evalEmbedded(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSwe
 fn startNreplWithFile(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepGc, filepath: []const u8, nrepl_port: u16) void {
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Set up load paths for require resolution
     const dir = std.fs.path.dirname(filepath) orelse ".";
@@ -1638,13 +1628,10 @@ fn startNreplWithFile(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.M
 fn evalEmbeddedWithNrepl(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepGc, source: []const u8, cli_args: []const [:0]const u8, nrepl_port: u16) void {
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     setCommandLineArgs(gc_alloc, &env, cli_args);
 
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
-
     // HTTP servers should run in background so nREPL can start after eval.
     http_server.background_mode = true;
 
@@ -1725,8 +1712,7 @@ fn handleBuildCommand(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.M
     // Bootstrap runtime from cache
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-    _ = gc;
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     // Set up load paths from entry file directory
     const dir = std.fs.path.dirname(source_file.?) orelse ".";
@@ -1828,9 +1814,7 @@ fn handleBuildCommand(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.M
 fn runEmbeddedBytecode(gc_alloc: Allocator, infra_alloc: Allocator, gc: *gc_mod.MarkSweepGc, module_bytes: []const u8) void {
     var env = Env.init(infra_alloc);
     defer env.deinit();
-    bootstrapFromCache(gc_alloc, &env);
-    gc.threshold = @max(gc.bytes_allocated * 2, gc.threshold);
-    env.gc = @ptrCast(gc);
+    bootstrapFromCache(gc_alloc, &env, gc);
 
     _ = bootstrap.runBytecodeModule(gc_alloc, &env, module_bytes) catch |e| {
         reportError(e);

src/main.zig

@@ -1272,11 +1272,6 @@ pub fn restoreFromBootstrapCache(allocator: Allocator, env: *Env, cache_bytes: [
         thread_pool_mod.initAgentVar(agent_v);
     }
 
-    // Re-load protocols and reducers namespaces (protocol/protocol_fn values are not
-    // serializable, so they are nil after cache restore — re-evaluate from source)
-    loadProtocols(allocator, env) catch {};
-    loadReducers(allocator, env) catch {};
-
     // Ensure *ns* is synced
     syncNsVar(env);
 }

src/runtime/bootstrap.zig

@@ -412,6 +412,9 @@ pub const Protocol = struct {
     method_sigs: []const MethodSig,
     /// Maps type_key (string) -> method_map (PersistentArrayMap of method_name -> fn)
     impls: *PersistentArrayMap,
+    /// Incremented when impls are modified (by extend_type_method / extend-type).
+    /// Used by ProtocolFn inline cache to detect stale entries.
+    generation: u32 = 0,
 };
 
 /// Protocol method reference — dispatches on first arg's type key.
@@ -426,6 +429,9 @@ pub const ProtocolFn = struct {
     method_name: []const u8,
     cached_type_key: ?[]const u8 = null,
     cached_method: Value = Value.nil_val,
+    /// Protocol generation at the time of cache update.
+    /// Cache is valid only when this matches protocol.generation.
+    cached_generation: u32 = 0,
 };
 
 /// MultiFn — multimethod with dispatch function and 2-level cache.

src/runtime/value.zig

@@ -838,25 +838,42 @@ pub const VM = struct {
                 // Get or create method map for this type in protocol.impls
                 const existing = protocol.impls.get(Value.initString(self.allocator, type_key));
                 if (existing) |ex_val| {
-                    // Existing method map for this type — add method
+                    // Existing method map for this type — update or add method
                     if (ex_val.tag() != .map) return error.TypeError;
                     const old_map = ex_val.asMap();
-                    const new_entries = self.allocator.alloc(Value, old_map.entries.len + 2) catch return error.OutOfMemory;
-                    if (self.gc == null) self.allocated_slices.append(self.allocator, new_entries) catch return error.OutOfMemory;
-                    @memcpy(new_entries[0..old_map.entries.len], old_map.entries);
-                    new_entries[old_map.entries.len] = Value.initString(self.allocator, method_name);
-                    new_entries[old_map.entries.len + 1] = method_fn;
-                    const new_method_map = self.allocator.create(value_mod.PersistentArrayMap) catch return error.OutOfMemory;
-                    new_method_map.* = .{ .entries = new_entries };
-                    if (self.gc == null) self.allocated_maps.append(self.allocator, new_method_map) catch return error.OutOfMemory;
-                    // Update impls: replace the type_key -> method_map entry
-                    const impls = protocol.impls;
-                    var i: usize = 0;
-                    while (i < impls.entries.len) : (i += 2) {
-                        if (impls.entries[i].eql(Value.initString(self.allocator, type_key))) {
-                            // Mutate in place — protocol.impls is mutable
-                            @constCast(impls.entries)[i + 1] = Value.initMap(new_method_map);
-                            break;
+
+                    // Check if the method already exists in the map (replace in-place)
+                    const method_key = Value.initString(self.allocator, method_name);
+                    var replaced = false;
+                    {
+                        var j: usize = 0;
+                        while (j + 1 < old_map.entries.len) : (j += 2) {
+                            if (old_map.entries[j].eql(method_key)) {
+                                @constCast(old_map.entries)[j + 1] = method_fn;
+                                replaced = true;
+                                break;
+                            }
+                        }
+                    }
+
+                    if (!replaced) {
+                        // New method for this type — append
+                        const new_entries = self.allocator.alloc(Value, old_map.entries.len + 2) catch return error.OutOfMemory;
+                        if (self.gc == null) self.allocated_slices.append(self.allocator, new_entries) catch return error.OutOfMemory;
+                        @memcpy(new_entries[0..old_map.entries.len], old_map.entries);
+                        new_entries[old_map.entries.len] = method_key;
+                        new_entries[old_map.entries.len + 1] = method_fn;
+                        const new_method_map = self.allocator.create(value_mod.PersistentArrayMap) catch return error.OutOfMemory;
+                        new_method_map.* = .{ .entries = new_entries };
+                        if (self.gc == null) self.allocated_maps.append(self.allocator, new_method_map) catch return error.OutOfMemory;
+                        // Update impls: replace the type_key -> method_map entry
+                        const impls = protocol.impls;
+                        var i: usize = 0;
+                        while (i < impls.entries.len) : (i += 2) {
+                            if (impls.entries[i].eql(Value.initString(self.allocator, type_key))) {
+                                @constCast(impls.entries)[i + 1] = Value.initMap(new_method_map);
+                                break;
+                            }
                         }
                     }
                 } else {
@@ -882,6 +899,9 @@ pub const VM = struct {
                     protocol.impls = new_impls;
                 }
 
+                // Invalidate ProtocolFn inline caches by bumping generation
+                protocol.generation +%= 1;
+
                 try self.push(Value.nil_val);
             },
 
@@ -1344,7 +1364,9 @@ pub const VM = struct {
                 const type_key = valueTypeKey(first_arg);
                 const mutable_pf: *ProtocolFn = @constCast(pf);
                 if (mutable_pf.cached_type_key) |ck| {
-                    if (ck.ptr == type_key.ptr or std.mem.eql(u8, ck, type_key)) {
+                    if (mutable_pf.cached_generation == pf.protocol.generation and
+                        (ck.ptr == type_key.ptr or std.mem.eql(u8, ck, type_key)))
+                    {
                         // Cache hit — skip full protocol resolution
                         self.stack[fn_idx] = mutable_pf.cached_method;
                         return self.performCall(arg_count);
@@ -1360,6 +1382,7 @@ pub const VM = struct {
                 // Update cache for next call
                 mutable_pf.cached_type_key = type_key;
                 mutable_pf.cached_method = method_fn;
+                mutable_pf.cached_generation = pf.protocol.generation;
                 self.stack[fn_idx] = method_fn;
                 return self.performCall(arg_count);
             },