feat(resolver): cache specializations by (target file, binding tuple) (#63)

Two call sites that resolve to the same parametric sub-circuit with the
same width-binding tuple now share a single specialized ir.Module
instead of producing duplicate bodies. The cache lives for the duration
of one project resolution and is keyed by a flat string
"{target_file_id}@{w0},{w1},..." so std.StringHashMap can carry it
without a custom hasher.

The positional encoding is load-bearing: (4, 2) and (2, 4) for a
<W, S> callee are distinct keys even though their value multisets
match, so a multi-param caller cannot accidentally collapse two
semantically different specializations.

Four tests pin the behavior in place:

* Identical single-param bindings produce one shared module.
* Distinct single-param bindings produce two separate modules.
* Multi-param identical tuples share.
* Multi-param distinct tuples (same values, different positions) do
  not share.

Engine bench golden matches; the cache only changes resolver-level
structural sharing, never the topology or simulation result.

Author: jeffersonmourak

lib/resolver/resolve_bodies.zig

@@ -148,6 +148,22 @@ const SpecResult = struct {
     sources: std.ArrayList([]const u8),
 };
 
+fn buildSpecializationKey(
+    allocator: std.mem.Allocator,
+    target_file_id: u32,
+    bindings: []const single_resolver.WidthBinding,
+) ![]u8 {
+    var buf: std.ArrayList(u8) = .{};
+    errdefer buf.deinit(allocator);
+    const writer = buf.writer(allocator);
+    try writer.print("{d}@", .{target_file_id});
+    for (bindings, 0..) |b, idx| {
+        if (idx > 0) try buf.append(allocator, ',');
+        try writer.print("{d}", .{b.value});
+    }
+    return buf.toOwnedSlice(allocator);
+}
+
 fn specializeCallSites(
     allocator: std.mem.Allocator,
     modules_list: *std.ArrayList(ir.Module),
@@ -157,6 +173,17 @@ fn specializeCallSites(
     spec: *SpecResult,
     diagnostic_list: *diagnostics.DiagnosticList,
 ) !void {
+    // Cache keyed by "{target_file_id}@{w0},{w1},...". Two call sites with
+    // the same target and the same width-binding tuple share one specialized
+    // module instead of duplicating the body. Keys are owned by the cache
+    // and freed on scope exit.
+    var spec_cache = std.StringHashMap(u32).init(allocator);
+    defer {
+        var it = spec_cache.iterator();
+        while (it.next()) |entry| allocator.free(entry.key_ptr.*);
+        spec_cache.deinit();
+    }
+
     const original_file_count = file_paths.len;
     for (asts, 0..) |maybe_caller_ast, caller_file_id_usize| {
         if (caller_file_id_usize >= original_file_count) break;
@@ -229,13 +256,21 @@ fn specializeCallSites(
                 if (!ok) continue;
             }
 
+            const cache_key = try buildSpecializationKey(allocator, target_file_id, bindings.items);
+            if (spec_cache.get(cache_key)) |cached_file_id| {
+                allocator.free(cache_key);
+                ir_comp.kind.sub_circuit_ref.specialized_target_file = .{ .value = cached_file_id };
+                continue;
+            }
+
             const spec_file_id: u32 = @intCast(modules_list.items.len);
             const specialized = single_resolver.resolveWithBindings(
                 allocator,
                 target_ast,
                 spec_file_id,
                 bindings.items,
             ) catch |err| {
+                allocator.free(cache_key);
                 std.debug.print("specialization failed for '{s}': {s}\n", .{ ast_inst.type_name.text, @errorName(err) });
                 continue;
             };
@@ -249,6 +284,8 @@ fn specializeCallSites(
             try spec.paths.append(allocator, synthetic_path);
             try spec.sources.append(allocator, "");
 
+            try spec_cache.put(cache_key, spec_file_id);
+
             ir_comp.kind.sub_circuit_ref.specialized_target_file = .{ .value = spec_file_id };
         }
     }

tests/fixtures/projects/distinct_bindings/root.circ

@@ -0,0 +1,7 @@
+import wide_not "wide_not.circ"
+input[4] x
+input[8] y
+wide_not inst_a[4](a=x)
+wide_not inst_b[8](a=y)
+output[4] out_a(in=inst_a.o)
+output[8] out_b(in=inst_b.o)

tests/fixtures/projects/distinct_bindings/wide_not.circ

@@ -0,0 +1,3 @@
+input<W>[W] a
+not[W] inv(in=a)
+output[W] o(in=inv.out)

tests/fixtures/projects/multi_param_distinct/mux_lib.circ

@@ -0,0 +1,6 @@
+input<W, S>[W] data
+input<W, S>[S] select
+not[W] data_inv(in=data)
+not[S] sel_inv(in=select)
+output[W] data_out(in=data_inv.out)
+output[S] sel_out(in=sel_inv.out)

tests/fixtures/projects/multi_param_distinct/root.circ

@@ -0,0 +1,11 @@
+import mux "mux_lib.circ"
+input[4] x1
+input[2] s1
+input[2] x2
+input[4] s2
+mux inst_a[4, 2](data=x1, select=s1)
+mux inst_b[2, 4](data=x2, select=s2)
+output[4] a_data(in=inst_a.data_out)
+output[2] a_sel(in=inst_a.sel_out)
+output[2] b_data(in=inst_b.data_out)
+output[4] b_sel(in=inst_b.sel_out)

tests/fixtures/projects/multi_param_shared/mux_lib.circ

@@ -0,0 +1,6 @@
+input<W, S>[W] data
+input<W, S>[S] select
+not[W] data_inv(in=data)
+not[S] sel_inv(in=select)
+output[W] data_out(in=data_inv.out)
+output[S] sel_out(in=sel_inv.out)

tests/fixtures/projects/multi_param_shared/root.circ

@@ -0,0 +1,11 @@
+import mux "mux_lib.circ"
+input[4] x1
+input[2] s1
+input[4] x2
+input[2] s2
+mux inst_a[4, 2](data=x1, select=s1)
+mux inst_b[4, 2](data=x2, select=s2)
+output[4] a_data(in=inst_a.data_out)
+output[2] a_sel(in=inst_a.sel_out)
+output[4] b_data(in=inst_b.data_out)
+output[2] b_sel(in=inst_b.sel_out)

tests/fixtures/projects/shared_spec/root.circ

@@ -0,0 +1,7 @@
+import wide_not "wide_not.circ"
+input[4] x
+input[4] y
+wide_not inst_a[4](a=x)
+wide_not inst_b[4](a=y)
+output[4] out_a(in=inst_a.o)
+output[4] out_b(in=inst_b.o)

tests/fixtures/projects/shared_spec/wide_not.circ

@@ -0,0 +1,3 @@
+input<W>[W] a
+not[W] inv(in=a)
+output[W] o(in=inv.out)

tests/resolver/resolve_bodies_test.zig

@@ -226,3 +226,74 @@ test "parameter binding order follows source declaration, not reference" {
     try std.testing.expectEqual(@as(u8, 4), lookupPinWidth(spec, "data_out", .output).?);
     try std.testing.expectEqual(@as(u8, 8), lookupPinWidth(spec, "aux_out", .output).?);
 }
+
+fn countSpecializations(project: @import("ir_types").Project) usize {
+    var count: usize = 0;
+    for (project.file_paths) |path| {
+        if (std.mem.startsWith(u8, path, "<specialization:")) count += 1;
+    }
+    return count;
+}
+
+fn countCallSitesTargeting(project: @import("ir_types").Project, expected_target_file_id_min: u32) usize {
+    // Count caller-side sub_circuit_ref components whose specialized_target_file
+    // points at some appended specialization (file_id >= original_file_count).
+    var count: usize = 0;
+    for (project.files) |module| {
+        for (module.components) |comp| {
+            switch (comp.kind) {
+                .sub_circuit_ref => |ref| {
+                    if (ref.specialized_target_file) |target| {
+                        if (target.value >= expected_target_file_id_min) count += 1;
+                    }
+                },
+                else => {},
+            }
+        }
+    }
+    return count;
+}
+
+test "cache: identical bindings share one specialization" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    // Two call sites at width 4 → cache produces exactly one specialization
+    // module despite two sub_circuit_ref components pointing into it.
+    const project = try resolveProject(allocator, fixtureRoot("shared_spec"));
+    try std.testing.expectEqual(@as(usize, 1), countSpecializations(project));
+    try std.testing.expectEqual(@as(usize, 2), countCallSitesTargeting(project, @intCast(project.file_paths.len - 1)));
+}
+
+test "cache: distinct bindings produce separate specializations" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    // Call sites at width 4 and width 8 → cache misses on the second key
+    // and produces two distinct specialization modules.
+    const project = try resolveProject(allocator, fixtureRoot("distinct_bindings"));
+    try std.testing.expectEqual(@as(usize, 2), countSpecializations(project));
+}
+
+test "cache: multi-param identical bindings share one specialization" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    // Two call sites at (W=4, S=2) → one shared specialization.
+    const project = try resolveProject(allocator, fixtureRoot("multi_param_shared"));
+    try std.testing.expectEqual(@as(usize, 1), countSpecializations(project));
+}
+
+test "cache: multi-param distinct binding tuples are not shared" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    // (4, 2) vs (2, 4) are distinct cache keys even though they share the
+    // same width values — order matters.
+    const project = try resolveProject(allocator, fixtureRoot("multi_param_distinct"));
+    try std.testing.expectEqual(@as(usize, 2), countSpecializations(project));
+}