feat(resolver): parametric built-in macros with recursive specialization

Rewrite the five built-in macros (or, xor, nand, nor, xnor) with
<W>[W] annotations. The two macros that compose other macros internally
(nor uses or, xnor uses xor) now propagate the parent W through the
inner call site with or inner[W] / xor inner[W] syntax. Existing
scalar callers stay byte-identical via S7.1's default-W-to-1 rule.

Three pieces of new resolver machinery let this happen end to end:

1. Worklist-based specialization. specializeCallSites now iterates a
   queue that includes newly-created spec modules, so width bindings
   propagate through nested parametric calls of arbitrary depth. The
   width-arg resolver looks up parameter references against the
   caller spec's bindings, which is what makes `or inner[W]` inside
   nor's body bind correctly when nor is specialized at W=8.

2. Alias rewrite on specs. The unresolved_name -> sub_circuit_ref
   rewrite the topo loop performs for original files also runs on
   freshly-created spec modules, otherwise nested macro call sites
   stayed unresolved and tripped E001 (visible on fixtures like
   alu_4bit that transitively use xor -> or, nand).

3. ir.Module.source_file_id. Distinguishes "where this module lives
   in project.files" (synthetic id for specs) from "what AST it was
   resolved from" (the original .circ file). Topology serializer's
   import_table lookup and OriginFrame.target_file both follow the
   source_file_id, so tooling sees real source paths and the bench
   topology hash stays byte-identical to pre-S8 for every fixture.

Bench reports golden matches on all 56 fixtures with zero topology
drift; existing scalar usages expand to the same component graph as
pre-S8 even though they now go through specialization.

Author: jeffersonmourak

lib/ir/types.zig

@@ -120,6 +120,16 @@ pub const Module = struct {
     components: []const Component,
     connections: []const Connection,
     imports: []const UnresolvedImport,
+    /// File id of the AST this module was resolved from. For original
+    /// files, equals `file_id`. For specializations, points at the
+    /// parametric callee's original file id so import_table lookups and
+    /// origin-frame tracking can resolve against the user-written source
+    /// instead of the synthetic specialization path.
+    source_file_id: ?FileId = null,
+
+    pub fn effectiveSourceFileId(self: Module) FileId {
+        return self.source_file_id orelse self.file_id;
+    }
 };
 
 pub const Project = struct {

lib/resolver/builtin_circ/nand.circ

@@ -1,5 +1,6 @@
+// parametric in width W (default 1)
 // NAND(a,b) = NOT(AND(a,b))
-input a, b
-and inner(a=a, b=b)
-not n(in=inner.out)
-output out(in=n.out)
+input<W>[W] a, b
+and[W] inner(a=a, b=b)
+not[W] n(in=inner.out)
+output[W] out(in=n.out)

lib/resolver/builtin_circ/nor.circ

@@ -1,5 +1,6 @@
+// parametric in width W (default 1)
 // NOR(a,b) = NOT(OR(a,b))
-input a, b
-or inner(a=a, b=b)
-not n(in=inner.out)
-output out(in=n.out)
+input<W>[W] a, b
+or inner[W](a=a, b=b)
+not[W] n(in=inner.out)
+output[W] out(in=n.out)

lib/resolver/builtin_circ/or.circ

@@ -1,7 +1,8 @@
+// parametric in width W (default 1)
 // OR(a,b) = NOT(AND(NOT(a), NOT(b)))
-input a, b
-not na(in=a)
-not nb(in=b)
-and inner(a=na.out, b=nb.out)
-not n(in=inner.out)
-output out(in=n.out)
+input<W>[W] a, b
+not[W] na(in=a)
+not[W] nb(in=b)
+and[W] inner(a=na.out, b=nb.out)
+not[W] n(in=inner.out)
+output[W] out(in=n.out)

lib/resolver/builtin_circ/xnor.circ

@@ -1,5 +1,6 @@
+// parametric in width W (default 1)
 // XNOR(a,b) = NOT(XOR(a,b))
-input a, b
-xor inner(a=a, b=b)
-not n(in=inner.out)
-output out(in=n.out)
+input<W>[W] a, b
+xor inner[W](a=a, b=b)
+not[W] n(in=inner.out)
+output[W] out(in=n.out)

lib/resolver/builtin_circ/xor.circ

@@ -1,6 +1,7 @@
+// parametric in width W (default 1)
 // XOR(a,b) = AND(OR(a,b), NAND(a,b))
-input a, b
-or o(a=a, b=b)
-nand n(a=a, b=b)
-and gate(a=o.out, b=n.out)
-output out(in=gate.out)
+input<W>[W] a, b
+or o[W](a=a, b=b)
+nand n[W](a=a, b=b)
+and[W] gate(a=o.out, b=n.out)
+output[W] out(in=gate.out)

lib/resolver/resolve_bodies.zig

@@ -164,6 +164,32 @@ fn buildSpecializationKey(
     return buf.toOwnedSlice(allocator);
 }
 
+// One unit of specialization work. Original-file callers enter with empty
+// bindings; each specialization enters with the bindings that produced it
+// and the original-AST file_id it was specialized from (for import lookups
+// and to find the same AST the resolver was driven by).
+const SpecWorkItem = struct {
+    module_file_id: u32,
+    ast_source_file_id: u32,
+    ast_file: ast.File,
+    bindings: []single_resolver.WidthBinding,
+};
+
+fn resolveWidthArg(
+    spec_arg: ast.WidthSpec,
+    caller_bindings: []const single_resolver.WidthBinding,
+) ?u8 {
+    return switch (spec_arg) {
+        .literal => |n| n,
+        .parameter => |name| blk: {
+            for (caller_bindings) |b| {
+                if (std.mem.eql(u8, b.name, name)) break :blk b.value;
+            }
+            break :blk null;
+        },
+    };
+}
+
 fn specializeCallSites(
     allocator: std.mem.Allocator,
     modules_list: *std.ArrayList(ir.Module),
@@ -185,24 +211,49 @@ fn specializeCallSites(
     }
 
     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;
+    var worklist: std.ArrayList(SpecWorkItem) = .{};
+    defer {
+        for (worklist.items) |item| {
+            if (item.bindings.len > 0) allocator.free(item.bindings);
+        }
+        worklist.deinit(allocator);
+    }
+
+    // Seed the worklist with non-parametric original callers; parametric
+    // callees are never directly resolved (the stub module fills their slot
+    // and downstream lookups follow specialized_target_file instead).
+    for (asts, 0..) |maybe_caller_ast, file_id_usize| {
+        if (file_id_usize >= original_file_count) break;
         const caller_ast = maybe_caller_ast orelse continue;
-        const caller_file_id: u32 = @intCast(caller_file_id_usize);
+        if (fileIsParametric(caller_ast)) continue;
+        try worklist.append(allocator, .{
+            .module_file_id = @intCast(file_id_usize),
+            .ast_source_file_id = @intCast(file_id_usize),
+            .ast_file = caller_ast,
+            .bindings = &.{},
+        });
+    }
+
+    while (worklist.items.len > 0) {
+        const item = worklist.orderedRemove(0);
+        defer if (item.bindings.len > 0) allocator.free(item.bindings);
 
-        const input_pin_count = countInputPins(caller_ast);
-        const caller_module = &modules_list.items[caller_file_id];
+        const input_pin_count = countInputPins(item.ast_file);
+        const caller_module = &modules_list.items[item.module_file_id];
         const caller_components = @constCast(caller_module.components);
 
-        for (caller_ast.components, 0..) |ast_inst, ast_idx| {
+        for (item.ast_file.components, 0..) |ast_inst, ast_idx| {
             const ir_comp_idx = input_pin_count + @as(u32, @intCast(ast_idx));
             if (ir_comp_idx >= caller_components.len) continue;
             const ir_comp = &caller_components[ir_comp_idx];
             if (ir_comp.kind != .sub_circuit_ref) continue;
 
+            // Import lookup uses the ORIGINAL file_id the AST came from, not
+            // the spec's synthetic module_file_id (which the import_table
+            // doesn't know about).
             const target_file_id_opt: ?u32 = blk: {
                 for (import_table) |entry| {
-                    if (entry.importing_file != caller_file_id) continue;
+                    if (entry.importing_file != item.ast_source_file_id) continue;
                     if (!std.mem.eql(u8, entry.alias, ast_inst.type_name.text)) continue;
                     break :blk entry.target_file;
                 }
@@ -237,21 +288,23 @@ fn specializeCallSites(
             } else {
                 var ok = true;
                 for (declared_params, supplied) |name, spec_arg| {
-                    switch (spec_arg) {
-                        .literal => |n| try bindings.append(allocator, .{ .name = name, .value = n }),
-                        .parameter => |passed_name| {
-                            const message = try std.fmt.allocPrint(
-                                allocator,
-                                "parameter pass-through is not yet supported; call site supplies parameter '{s}'",
-                                .{passed_name},
-                            );
-                            var d = diagnostics.makeDiagnostic(.E016, diagnosticSpan(ast_inst.span));
-                            d.message = message;
-                            try diagnostic_list.append(allocator, d);
-                            ok = false;
-                            break;
-                        },
-                    }
+                    const value = resolveWidthArg(spec_arg, item.bindings) orelse {
+                        const passed_name = switch (spec_arg) {
+                            .parameter => |n| n,
+                            else => "?",
+                        };
+                        const message = try std.fmt.allocPrint(
+                            allocator,
+                            "unbound parameter '{s}' at call site of '{s}'",
+                            .{ passed_name, ast_inst.type_name.text },
+                        );
+                        var d = diagnostics.makeDiagnostic(.E016, diagnosticSpan(ast_inst.span));
+                        d.message = message;
+                        try diagnostic_list.append(allocator, d);
+                        ok = false;
+                        break;
+                    };
+                    try bindings.append(allocator, .{ .name = name, .value = value });
                 }
                 if (!ok) continue;
             }
@@ -264,7 +317,7 @@ fn specializeCallSites(
             }
 
             const spec_file_id: u32 = @intCast(modules_list.items.len);
-            const specialized = single_resolver.resolveWithBindings(
+            var specialized = single_resolver.resolveWithBindings(
                 allocator,
                 target_ast,
                 spec_file_id,
@@ -274,6 +327,32 @@ fn specializeCallSites(
                 std.debug.print("specialization failed for '{s}': {s}\n", .{ ast_inst.type_name.text, @errorName(err) });
                 continue;
             };
+            // Record the original AST source so downstream lookups
+            // (topology origin frames, project-level import resolution)
+            // can resolve against the user-written file path rather than
+            // the spec's synthetic file id.
+            specialized.source_file_id = .{ .value = target_file_id };
+
+            // Apply the same alias rewrite the topo loop performs on original
+            // file resolutions: any component whose kind is .unresolved_name
+            // and whose name matches an import alias for the spec's source
+            // file becomes a sub_circuit_ref. Without this, nested call sites
+            // inside a spec (e.g. `or inner[W]` in nor.circ) would stay
+            // unresolved and trip E001.
+            const spec_components = @constCast(specialized.components);
+            for (spec_components) |*c| {
+                for (import_table) |entry| {
+                    if (entry.importing_file != target_file_id) continue;
+                    if (!componentMatchesAlias(c.*, entry.alias)) continue;
+                    c.kind = .{
+                        .sub_circuit_ref = .{
+                            .name = entry.alias,
+                            .span = c.span,
+                        },
+                    };
+                    break;
+                }
+            }
 
             try modules_list.append(allocator, specialized);
             const synthetic_path = try std.fmt.allocPrint(
@@ -287,6 +366,17 @@ fn specializeCallSites(
             try spec_cache.put(cache_key, spec_file_id);
 
             ir_comp.kind.sub_circuit_ref.specialized_target_file = .{ .value = spec_file_id };
+
+            // Enqueue the new spec for recursive specialization of any call
+            // sites in its body. Duplicate the bindings into the worklist
+            // entry so the original `bindings` ArrayList can be reused/freed.
+            const owned_bindings = try allocator.dupe(single_resolver.WidthBinding, bindings.items);
+            try worklist.append(allocator, .{
+                .module_file_id = spec_file_id,
+                .ast_source_file_id = target_file_id,
+                .ast_file = target_ast,
+                .bindings = owned_bindings,
+            });
         }
     }
 }

lib/topology/full_serializer.zig

@@ -254,17 +254,28 @@ fn expandModule(
             .sub_circuit_ref => |ref| {
                 var child_module: ?*const ir.Module = null;
                 var target_file_id: u32 = 0;
+                // The import_table lookup resolves the alias to the source
+                // file the user wrote the import for (e.g. or.circ for `or`).
+                // That is the file id we want in the OriginFrame so tooling
+                // sees real source paths in stack traces. The specialized
+                // child_module, when present, is the post-substitution body
+                // the topology walks; it lives at a synthetic file id that
+                // wouldn't make sense for diagnostics.
+                //
+                // The lookup uses `effectiveSourceFileId` so that nested call
+                // sites inside a specialization match against the original
+                // callee's imports rather than the spec's synthetic file id
+                // (the import_table only has entries for original file ids).
+                const lookup_file_id = module.effectiveSourceFileId();
+                for (state.project.import_table) |imp| {
+                    if (imp.importing_file.value == lookup_file_id.value and std.mem.eql(u8, imp.alias, ref.name)) {
+                        target_file_id = imp.target_file.value;
+                        child_module = &state.project.files[imp.target_file.value];
+                        break;
+                    }
+                }
                 if (ref.specialized_target_file) |spec| {
                     child_module = &state.project.files[spec.value];
-                    target_file_id = spec.value;
-                } else {
-                    for (state.project.import_table) |imp| {
-                        if (imp.importing_file.value == module.file_id.value and std.mem.eql(u8, imp.alias, ref.name)) {
-                            child_module = &state.project.files[imp.target_file.value];
-                            target_file_id = imp.target_file.value;
-                            break;
-                        }
-                    }
                 }
                 if (child_module == null) return error.ModuleNotFound;
 

lib/topology/serializer.zig

@@ -210,8 +210,9 @@ fn expandModule(
                 if (ref.specialized_target_file) |spec| {
                     child_module = &state.project.files[spec.value];
                 } else {
+                    const lookup_file_id = module.effectiveSourceFileId();
                     for (state.project.import_table) |imp| {
-                        if (imp.importing_file.value == module.file_id.value and std.mem.eql(u8, imp.alias, ref.name)) {
+                        if (imp.importing_file.value == lookup_file_id.value and std.mem.eql(u8, imp.alias, ref.name)) {
                             child_module = &state.project.files[imp.target_file.value];
                             break;
                         }

tests/fixtures/circuits/nand_4bit_macro.circ

@@ -0,0 +1,3 @@
+input[4] a, b
+nand g[4](a=a, b=b)
+output[4] out(in=g.out)