feat(types): nominal identity + key-safe TypeTable mutation, ban raw update [stdlib D]

Phase D of the unified resolver: make the TypeTable safe to key by nominal
identity before same-name type shadows land (Phase E). Behavior-preserving —
nominal_id=0 means structural (today's keying, byte-identical); single-author
names intern to the same TypeId as before.

types.zig:
- StructInfo/EnumInfo/UnionInfo/TaggedUnionInfo/ErrorSetInfo gain
  `nominal_id: u32 = 0`. hash/eql fold it into the nominal arms ONLY, and only
  when nonzero, so legacy (structural) interning hashes/compares byte-identically.
- internNominal(info, nominal_id): stamps the id into the nominal arm then
  interns; nonzero id on a non-nominal info trips an assert.
- updatePreservingKey(id, info): field-fill that asserts the intern key is
  unchanged (replaces the forward-decl stub→full pattern).
- replaceKeyedInfo(id, info): the one legitimate re-key (anon rename
  __anon → Parent.field); removes the stale key and installs the new one.
- findUniqueByName: quarantined findByName that asserts ≤1 match.
- type_decl_tids: decl-node → TypeId identity map (the fn_decl_fids analogue),
  consumed by the resolver in Phase E.

Ban raw TypeTable.update outside types.zig (the acceptance bar): every caller
in lower.zig / type_bridge.zig / protocols.zig is reclassified — forward-decl
field fills route through updatePreservingKey, qualifyAnonType's rename through
replaceKeyedInfo. The raw `update` method is removed. Inline named type-decl
registration ("current winners") routes through internNominal(info, 0).

Tests (types.test.zig): forward-decl field fill (stable key), anon rename
(re-key), generic struct instantiation, type-returning function, parameterized
protocol value struct, same display-name → distinct nominal ids, plus an
old==new assertion (internNominal(.,0) byte-identical to legacy intern),
findUniqueByName, and the type_decl_tids identity map.

Gate: zig build (0), zig build test (421/421), run_examples (477, byte-identical),
m3te ios-sim build via worktree binary (0). No shadows registered; stubs intact.

src/ir/lower.zig

@@ -914,7 +914,7 @@ pub const Lowering = struct {
                                         .fields = inst_info.@"struct".fields,
                                     } };
                                     const alias_id = if (self.module.types.findByName(alias_name_id)) |existing| existing else self.module.types.intern(alias_info);
-                                    self.module.types.update(alias_id, alias_info);
+                                    self.module.types.updatePreservingKey(alias_id, alias_info);
                                 }
                             } else if (std.mem.eql(u8, callee_name, "Vector")) {
                                 // Builtin type constructor — checked BEFORE
@@ -951,7 +951,7 @@ pub const Lowering = struct {
                                     .fields = inst_info.@"struct".fields,
                                 } };
                                 const alias_id = if (self.module.types.findByName(alias_name_id)) |existing| existing else self.module.types.intern(alias_info);
-                                self.module.types.update(alias_id, alias_info);
+                                self.module.types.updatePreservingKey(alias_id, alias_info);
                             }
                         } else {
                             // Builtin parameterised type (Vector(N, T) etc) —
@@ -13242,7 +13242,7 @@ pub const Lowering = struct {
         // Register the monomorphized struct
         const info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items } };
         const id = if (table.findByName(name_id)) |existing| existing else table.intern(info);
-        table.update(id, info);
+        table.updatePreservingKey(id, info);
 
         // Bind the template name to this concrete instance so a method's
         // `self: *Combined` (the template name) resolves to `*Combined__s64_s64`
@@ -13347,7 +13347,7 @@ pub const Lowering = struct {
                 .fields = struct_fields.items,
             } };
             const mangled_id = if (table.findByName(mangled_name_id)) |existing| existing else table.intern(mangled_info);
-            table.update(mangled_id, mangled_info);
+            table.updatePreservingKey(mangled_id, mangled_info);
 
             // If there's a real alias, also register under alias name and in alias map
             if (has_alias) {
@@ -13357,7 +13357,7 @@ pub const Lowering = struct {
                     .fields = struct_fields.items,
                 } };
                 const alias_id = if (table.findByName(alias_name_id)) |existing| existing else table.intern(alias_info);
-                table.update(alias_id, alias_info);
+                table.updatePreservingKey(alias_id, alias_info);
 
                 // Store defaults if any
                 if (struct_decl.field_defaults.len > 0) {
@@ -13429,7 +13429,7 @@ pub const Lowering = struct {
             .tag_type = .s64,
         } };
         const id = if (table.findByName(alias_name_id)) |existing| existing else table.intern(info);
-        table.update(id, info);
+        table.updatePreservingKey(id, info);
 
         // Also register under mangled name
         if (!std.mem.eql(u8, alias_name, mangled_name)) {
@@ -13440,7 +13440,7 @@ pub const Lowering = struct {
                 .tag_type = .s64,
             } };
             const mid = if (table.findByName(mangled_name_id)) |existing| existing else table.intern(mangled_info);
-            table.update(mid, mangled_info);
+            table.updatePreservingKey(mid, mangled_info);
         }
 
         return id;
@@ -13621,8 +13621,8 @@ pub const Lowering = struct {
         // Check if a forward-reference placeholder already exists (with empty fields)
         // If so, update it in-place rather than creating a duplicate
         const info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items } };
-        const id = if (table.findByName(name_id)) |existing| existing else table.intern(info);
+        const id = if (table.findByName(name_id)) |existing| existing else table.internNominal(info, 0);
-        table.update(id, info);
+        table.updatePreservingKey(id, info);
 
         // Store field defaults for struct literal lowering
         if (sd.field_defaults.len > 0) {
@@ -13668,7 +13668,7 @@ pub const Lowering = struct {
                 if (!std.mem.eql(u8, old_name, "__anon")) return;
                 const qualified = std.fmt.allocPrint(self.alloc, "{s}.{s}", .{ parent_name, field_name }) catch return;
                 const qname_id = table.internString(qualified);
-                table.update(ty, .{ .@"union" = .{ .name = qname_id, .fields = u.fields } });
+                table.replaceKeyedInfo(ty, .{ .@"union" = .{ .name = qname_id, .fields = u.fields } });
             },
             .tagged_union => |u| {
                 const old_name = table.getString(u.name);
@@ -13685,26 +13685,26 @@ pub const Lowering = struct {
                                 const suffix = sname["__anon".len..]; // .VariantName
                                 const sq = std.fmt.allocPrint(self.alloc, "{s}{s}", .{ qualified, suffix }) catch continue;
                                 const sq_id = table.internString(sq);
-                                table.update(f.ty, .{ .@"struct" = .{ .name = sq_id, .fields = finfo.@"struct".fields } });
+                                table.replaceKeyedInfo(f.ty, .{ .@"struct" = .{ .name = sq_id, .fields = finfo.@"struct".fields } });
                             }
                         }
                     }
                 }
-                table.update(ty, .{ .tagged_union = .{ .name = qname_id, .fields = u.fields, .tag_type = u.tag_type, .backing_type = u.backing_type, .explicit_tag_values = u.explicit_tag_values } });
+                table.replaceKeyedInfo(ty, .{ .tagged_union = .{ .name = qname_id, .fields = u.fields, .tag_type = u.tag_type, .backing_type = u.backing_type, .explicit_tag_values = u.explicit_tag_values } });
             },
             .@"enum" => |e| {
                 const old_name = table.getString(e.name);
                 if (!std.mem.eql(u8, old_name, "__anon")) return;
                 const qualified = std.fmt.allocPrint(self.alloc, "{s}.{s}", .{ parent_name, field_name }) catch return;
                 const qname_id = table.internString(qualified);
-                table.update(ty, .{ .@"enum" = .{ .name = qname_id, .variants = e.variants, .explicit_values = e.explicit_values } });
+                table.replaceKeyedInfo(ty, .{ .@"enum" = .{ .name = qname_id, .variants = e.variants, .explicit_values = e.explicit_values } });
             },
             .@"struct" => |s| {
                 const old_name = table.getString(s.name);
                 if (!std.mem.eql(u8, old_name, "__anon")) return;
                 const qualified = std.fmt.allocPrint(self.alloc, "{s}.{s}", .{ parent_name, field_name }) catch return;
                 const qname_id = table.internString(qualified);
-                table.update(ty, .{ .@"struct" = .{ .name = qname_id, .fields = s.fields } });
+                table.replaceKeyedInfo(ty, .{ .@"struct" = .{ .name = qname_id, .fields = s.fields } });
             },
             else => {},
         }
@@ -13758,7 +13758,7 @@ pub const Lowering = struct {
         }
         const struct_info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items, .is_protocol = true } };
         const id = if (table.findByName(name_id)) |existing| existing else table.intern(struct_info);
-        table.update(id, struct_info);
+        table.updatePreservingKey(id, struct_info);
 
         // Method infos resolved with the type-arg binding (T → s64).
         const saved_tb = self.type_bindings;

src/ir/protocols.zig

@@ -282,7 +282,7 @@ pub const ProtocolResolver = struct {
 
         const struct_info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items, .is_protocol = true } };
         const id = if (table.findByName(name_id)) |existing| existing else table.intern(struct_info);
-        table.update(id, struct_info);
+        table.updatePreservingKey(id, struct_info);
 
         // Build protocol method info for dispatch
         var method_infos = std.ArrayList(ProtocolMethodInfo).empty;

src/ir/type_bridge.zig

@@ -367,8 +367,8 @@ fn resolveInlineEnum(ed: *const ast.EnumDecl, table: *TypeTable, alias_map: Alia
                                     .name = qname_id,
                                     .fields = sfields.items,
                                 } };
-                                field_ty = table.intern(sinfo);
+                                field_ty = table.internNominal(sinfo, 0);
-                                table.update(field_ty, sinfo);
+                                table.updatePreservingKey(field_ty, sinfo);
                             }
                         } else {
                             field_ty = resolveAstType(vt, table, alias_map, consts);
@@ -424,8 +424,8 @@ fn resolveInlineEnum(ed: *const ast.EnumDecl, table: *TypeTable, alias_map: Alia
             .backing_type = backing_type,
             .explicit_tag_values = explicit_tag_vals,
         } };
-        const id = table.intern(info);
+        const id = table.internNominal(info, 0);
-        table.update(id, info);
+        table.updatePreservingKey(id, info);
         return id;
     }
 
@@ -482,8 +482,8 @@ fn resolveInlineEnum(ed: *const ast.EnumDecl, table: *TypeTable, alias_map: Alia
         .explicit_values = explicit_vals,
         .backing_type = enum_backing,
     } };
-    const id = table.intern(info);
+    const id = table.internNominal(info, 0);
-    table.update(id, info);
+    table.updatePreservingKey(id, info);
     return id;
 }
 
@@ -505,8 +505,8 @@ fn resolveInlineStruct(sd: *const ast.StructDecl, table: *TypeTable, alias_map:
         .name = name_id,
         .fields = fields.items,
     } };
-    const id = table.intern(info);
+    const id = table.internNominal(info, 0);
-    table.update(id, info);
+    table.updatePreservingKey(id, info);
     return id;
 }
 
@@ -528,8 +528,8 @@ fn resolveInlineUnion(ud: *const ast.UnionDecl, table: *TypeTable, alias_map: Al
         .name = name_id,
         .fields = fields.items,
     } };
-    const id = table.intern(info);
+    const id = table.internNominal(info, 0);
-    table.update(id, info);
+    table.updatePreservingKey(id, info);
     return id;
 }
 

src/ir/types.test.zig

@@ -1,6 +1,7 @@
 // Tests for types.zig
 const std = @import("std");
 const types = @import("types.zig");
+const ast = @import("../ast.zig");
 const TypeId = types.TypeId;
 const TypeTable = types.TypeTable;
 const TypeInfo = types.TypeInfo;
@@ -287,3 +288,199 @@ test "isUnsignedInt: user-defined arbitrary-width ints" {
     const ptr_ty = table.ptrTo(.u32);
     try std.testing.expect(!table.isUnsignedInt(ptr_ty));
 }
+
+// ── Phase D: nominal identity + key-safe mutation ───────────────────────
+
+test "phase D: forward-decl field fill preserves intern key" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const foo = table.internString("Foo");
+    const no_fields = [_]TypeInfo.StructInfo.Field{};
+    const stub: TypeInfo = .{ .@"struct" = .{ .name = foo, .fields = &no_fields } };
+    const id = table.internNominal(stub, 0);
+
+    // Full definition arrives later; same name (and nominal id) → same key.
+    const fields = [_]TypeInfo.StructInfo.Field{
+        .{ .name = table.internString("x"), .ty = .s64 },
+        .{ .name = table.internString("y"), .ty = .s64 },
+    };
+    table.updatePreservingKey(id, .{ .@"struct" = .{ .name = foo, .fields = &fields } });
+
+    // TypeId stable, fields filled, and a fresh structural intern of the same
+    // name still resolves to it (the field-fill didn't touch the key).
+    try std.testing.expectEqual(@as(usize, 2), table.get(id).@"struct".fields.len);
+    try std.testing.expectEqual(id, table.internNominal(stub, 0));
+    try std.testing.expectEqual(id, table.findByName(foo).?);
+}
+
+test "phase D: anon rename re-keys intern_map" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const anon = table.internString("__anon");
+    const fields = [_]TypeInfo.StructInfo.Field{
+        .{ .name = table.internString("x"), .ty = .s64 },
+    };
+    const id = table.internNominal(.{ .@"struct" = .{ .name = anon, .fields = &fields } }, 0);
+    try std.testing.expectEqual(id, table.findByName(anon).?);
+
+    const qualified = table.internString("Parent.field");
+    table.replaceKeyedInfo(id, .{ .@"struct" = .{ .name = qualified, .fields = &fields } });
+
+    // Old name no longer resolves; new name does; same TypeId.
+    try std.testing.expect(table.findByName(anon) == null);
+    try std.testing.expectEqual(id, table.findByName(qualified).?);
+    // Re-keyed: structural intern under the new name dedups to the same id...
+    try std.testing.expectEqual(id, table.intern(.{ .@"struct" = .{ .name = qualified, .fields = &fields } }));
+    // ...and the stale old key is gone, so a fresh "__anon" gets a NEW id.
+    const fresh = table.intern(.{ .@"struct" = .{ .name = anon, .fields = &fields } });
+    try std.testing.expect(fresh != id);
+}
+
+test "phase D: generic struct instantiation interns by distinct names" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const f1 = [_]TypeInfo.StructInfo.Field{.{ .name = table.internString("e"), .ty = .f32 }};
+    const vec3a = table.internNominal(.{ .@"struct" = .{ .name = table.internString("Vec__3"), .fields = &f1 } }, 0);
+    const vec4 = table.internNominal(.{ .@"struct" = .{ .name = table.internString("Vec__4"), .fields = &f1 } }, 0);
+    // Distinct instantiations → distinct ids.
+    try std.testing.expect(vec3a != vec4);
+    // Re-instantiating the same monomorph → same id (structural dedup by name).
+    const vec3b = table.internNominal(.{ .@"struct" = .{ .name = table.internString("Vec__3"), .fields = &f1 } }, 0);
+    try std.testing.expectEqual(vec3a, vec3b);
+    // A forward-decl fill on the instantiation keeps the id.
+    const f2 = [_]TypeInfo.StructInfo.Field{
+        .{ .name = table.internString("e"), .ty = .f32 },
+        .{ .name = table.internString("f"), .ty = .f32 },
+    };
+    table.updatePreservingKey(vec3a, .{ .@"struct" = .{ .name = table.internString("Vec__3"), .fields = &f2 } });
+    try std.testing.expectEqual(vec3a, table.findByName(table.internString("Vec__3")).?);
+}
+
+test "phase D: type-returning function result interns stably" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    // `Complex(u32)` registers a struct under the mangled alias name; interning
+    // the same instantiation twice is stable.
+    const name = table.internString("Complex__u32");
+    const fields = [_]TypeInfo.StructInfo.Field{
+        .{ .name = table.internString("re"), .ty = .u32 },
+        .{ .name = table.internString("im"), .ty = .u32 },
+    };
+    const info: TypeInfo = .{ .@"struct" = .{ .name = name, .fields = &fields } };
+    const a = table.internNominal(info, 0);
+    const b = table.internNominal(info, 0);
+    try std.testing.expectEqual(a, b);
+    try std.testing.expectEqual(a, table.findByName(name).?);
+}
+
+test "phase D: parameterized protocol value struct interns stably" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    // `instantiateParamProtocol` registers a `{ctx, __vtable}` value struct
+    // under a mangled name (e.g. `VL__s64`). Same instantiation → same id.
+    const void_ptr = table.ptrTo(.void);
+    const fields = [_]TypeInfo.StructInfo.Field{
+        .{ .name = table.internString("ctx"), .ty = void_ptr },
+        .{ .name = table.internString("__vtable"), .ty = void_ptr },
+    };
+    const info: TypeInfo = .{ .@"struct" = .{ .name = table.internString("VL__s64"), .fields = &fields, .is_protocol = true } };
+    const a = table.intern(info);
+    const b = table.intern(info);
+    try std.testing.expectEqual(a, b);
+    // A different parameterization is a different name → different id.
+    const other = table.intern(.{ .@"struct" = .{ .name = table.internString("VL__f64"), .fields = &fields, .is_protocol = true } });
+    try std.testing.expect(other != a);
+}
+
+test "phase D: same display-name distinct nominal ids" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const foo = table.internString("Foo");
+    const f = [_]TypeInfo.StructInfo.Field{.{ .name = table.internString("x"), .ty = .s64 }};
+    const base: TypeInfo = .{ .@"struct" = .{ .name = foo, .fields = &f } };
+
+    const a = table.internNominal(base, 1);
+    const b = table.internNominal(base, 2);
+    const structural = table.internNominal(base, 0);
+    // Three authors of "Foo" → three distinct TypeIds.
+    try std.testing.expect(a != b);
+    try std.testing.expect(a != structural);
+    try std.testing.expect(b != structural);
+    // Re-interning the same nominal id is idempotent.
+    try std.testing.expectEqual(a, table.internNominal(base, 1));
+    try std.testing.expectEqual(b, table.internNominal(base, 2));
+    // The nominal id is recorded on the stored info.
+    try std.testing.expectEqual(@as(u32, 1), table.get(a).@"struct".nominal_id);
+    try std.testing.expectEqual(@as(u32, 2), table.get(b).@"struct".nominal_id);
+    try std.testing.expectEqual(@as(u32, 0), table.get(structural).@"struct".nominal_id);
+
+    // Same disambiguation holds for the enum and error_set nominal arms.
+    const bar = table.internString("Bar");
+    const variants = [_]types.StringId{ table.internString("a"), table.internString("b") };
+    const e1 = table.internNominal(.{ .@"enum" = .{ .name = bar, .variants = &variants } }, 1);
+    const e2 = table.internNominal(.{ .@"enum" = .{ .name = bar, .variants = &variants } }, 2);
+    try std.testing.expect(e1 != e2);
+
+    const baz = table.internString("Baz");
+    const tags = [_]u32{ 1, 2 };
+    const es1 = table.internNominal(.{ .error_set = .{ .name = baz, .tags = &tags } }, 1);
+    const es2 = table.internNominal(.{ .error_set = .{ .name = baz, .tags = &tags } }, 2);
+    try std.testing.expect(es1 != es2);
+}
+
+test "phase D: internNominal(.,0) is byte-identical to legacy intern (old==new)" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const f = [_]TypeInfo.StructInfo.Field{.{ .name = table.internString("x"), .ty = .s64 }};
+    const variants = [_]types.StringId{table.internString("v")};
+    const tags = [_]u32{7};
+
+    const cases = [_]TypeInfo{
+        .{ .@"struct" = .{ .name = table.internString("S"), .fields = &f } },
+        .{ .@"enum" = .{ .name = table.internString("E"), .variants = &variants } },
+        .{ .@"union" = .{ .name = table.internString("U"), .fields = &f } },
+        .{ .tagged_union = .{ .name = table.internString("T"), .fields = &f, .tag_type = .s64 } },
+        .{ .error_set = .{ .name = table.internString("Err"), .tags = &tags } },
+    };
+    for (cases) |info| {
+        const old = table.intern(info); // legacy structural path
+        const new = table.internNominal(info, 0); // new API, structural id
+        try std.testing.expectEqual(old, new);
+    }
+}
+
+test "phase D: findUniqueByName returns the sole match" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const foo = table.internString("Foo");
+    try std.testing.expect(table.findUniqueByName(foo) == null);
+    const id = table.internNominal(.{ .@"struct" = .{ .name = foo, .fields = &.{} } }, 0);
+    try std.testing.expectEqual(id, table.findUniqueByName(foo).?);
+}
+
+test "phase D: type_decl_tids maps decl node to TypeId" {
+    const alloc = std.testing.allocator;
+    var table = TypeTable.init(alloc);
+    defer table.deinit();
+
+    const id = table.internNominal(.{ .@"struct" = .{ .name = table.internString("Node1"), .fields = &.{} } }, 0);
+    var node = ast.Node{ .span = .{ .start = 0, .end = 0 }, .data = .{ .int_literal = .{ .value = 0 } } };
+    try table.type_decl_tids.put(&node, id);
+    try std.testing.expectEqual(id, table.type_decl_tids.get(&node).?);
+}

src/ir/types.zig

@@ -1,5 +1,6 @@
 const std = @import("std");
 const Allocator = std.mem.Allocator;
+const ast = @import("../ast.zig");
 
 // ── TypeId ──────────────────────────────────────────────────────────────
 // Opaque handle into the TypeTable. First 16 slots are reserved for builtins.
@@ -95,6 +96,10 @@ pub const TypeInfo = union(enum) {
         // null ctx == none) rather than the standard `{T, i1}` discriminated
         // layout — matching how `?Closure` works.
         is_protocol: bool = false,
+        // Stable nominal identity, assigned once per decl pointer. Folds into
+        // the intern key so two same-display-name authors get distinct TypeIds.
+        // `0` == structural: the type is keyed by display name alone (legacy).
+        nominal_id: u32 = 0,
 
         pub const Field = struct {
             name: StringId,
@@ -108,11 +113,13 @@ pub const TypeInfo = union(enum) {
         is_flags: bool = false,
         explicit_values: ?[]const i64 = null, // for flags (power-of-2) or custom values
         backing_type: ?TypeId = null, // e.g. u32 for `enum u32 { ... }`
+        nominal_id: u32 = 0, // stable nominal identity; 0 == structural (legacy)
     };
 
     pub const UnionInfo = struct {
         name: StringId,
         fields: []const StructInfo.Field,
+        nominal_id: u32 = 0, // stable nominal identity; 0 == structural (legacy)
     };
 
     pub const TaggedUnionInfo = struct {
@@ -121,6 +128,7 @@ pub const TypeInfo = union(enum) {
         tag_type: TypeId, // tag integer type (e.g. .u32, .s64)
         backing_type: ?TypeId = null, // enum struct backing (e.g. { tag: u32; _: u32; payload: [30]u32; })
         explicit_tag_values: ?[]const i64 = null, // explicit variant values (e.g., quit :: 0x100)
+        nominal_id: u32 = 0, // stable nominal identity; 0 == structural (legacy)
     };
 
     pub const ArrayInfo = struct {
@@ -200,6 +208,7 @@ pub const TypeInfo = union(enum) {
     pub const ErrorSetInfo = struct {
         name: StringId,
         tags: []const u32, // sorted global tag ids
+        nominal_id: u32 = 0, // stable nominal identity; 0 == structural (legacy)
     };
 };
 
@@ -323,6 +332,11 @@ pub const TypeTable = struct {
     tags: TagRegistry,
     /// Maps TypeInfo → TypeId for dedup of structural types
     intern_map: std.HashMap(TypeKey, TypeId, TypeKeyContext, 80),
+    /// Stable nominal identity: type-decl AST node → its TypeId. The
+    /// `fn_decl_fids` analogue — one entry per declaring node, so two
+    /// same-display-name declarations resolve to distinct TypeIds via their
+    /// own node pointer. Populated by the resolver when it assigns nominal ids.
+    type_decl_tids: std.AutoHashMap(*const ast.Node, TypeId),
     alloc: Allocator,
     /// Owns the element/param slices duped by the type constructors
     /// (`functionType*`, `closureType*`, `packType`). Freed wholesale in
@@ -339,6 +353,7 @@ pub const TypeTable = struct {
             .strings = StringPool.init(alloc),
             .tags = TagRegistry.init(alloc),
             .intern_map = std.HashMap(TypeKey, TypeId, TypeKeyContext, 80).init(alloc),
+            .type_decl_tids = std.AutoHashMap(*const ast.Node, TypeId).init(alloc),
             .alloc = alloc,
             .slice_arena = std.heap.ArenaAllocator.init(alloc),
         };
@@ -376,6 +391,7 @@ pub const TypeTable = struct {
         self.strings.deinit(self.alloc);
         self.tags.deinit(self.alloc);
         self.intern_map.deinit();
+        self.type_decl_tids.deinit();
         self.slice_arena.deinit();
     }
 
@@ -396,13 +412,48 @@ pub const TypeTable = struct {
         return id;
     }
 
-    /// Update the TypeInfo for an existing TypeId. Used when a forward-declared
+    /// Intern a nominal type (struct/enum/union/tagged_union/error_set) under a
-    /// type (e.g., struct with empty fields) gets its full definition later.
+    /// stable nominal identity. `nominal_id` folds into the intern key so two
-    pub fn update(self: *TypeTable, id: TypeId, info: TypeInfo) void {
+    /// authors that share a display name still get distinct TypeIds. With
-        const idx = id.index();
+    /// `nominal_id == 0` this is byte-identical to `intern` (structural keying),
-        if (idx < self.infos.items.len) {
+    /// which is the only id used until same-name shadows land. Passing a nonzero
-            self.infos.items[idx] = info;
+    /// id for a non-nominal info is a caller bug (the id would be dropped).
+    pub fn internNominal(self: *TypeTable, info: TypeInfo, nominal_id: u32) TypeId {
+        var stamped = info;
+        switch (stamped) {
+            .@"struct" => |*s| s.nominal_id = nominal_id,
+            .@"enum" => |*e| e.nominal_id = nominal_id,
+            .@"union" => |*u| u.nominal_id = nominal_id,
+            .tagged_union => |*u| u.nominal_id = nominal_id,
+            .error_set => |*e| e.nominal_id = nominal_id,
+            else => std.debug.assert(nominal_id == 0),
         }
+        return self.intern(stamped);
+    }
+
+    /// Replace the TypeInfo for an existing TypeId WITHOUT changing its intern
+    /// key. Used when a forward-declared type (struct with empty fields) gets
+    /// its full definition later: the key is the display name + nominal id, and
+    /// a field-fill touches neither. Asserts the key is unchanged so a real
+    /// re-key can't sneak through this path (use `replaceKeyedInfo` for that).
+    pub fn updatePreservingKey(self: *TypeTable, id: TypeId, info: TypeInfo) void {
+        const idx = id.index();
+        const old = self.infos.items[idx];
+        std.debug.assert((TypeKeyContext{}).eql(.{ .info = old }, .{ .info = info }));
+        self.infos.items[idx] = info;
+    }
+
+    /// Replace the TypeInfo for an existing TypeId AND re-key `intern_map` to
+    /// match the new info. The one legitimate re-key is the anonymous-type
+    /// rename (`__anon` → `Parent.field`), which mutates the display name and
+    /// therefore the key. Removes the stale key and installs the new one so the
+    /// renamed type interns and looks up under its new name only.
+    pub fn replaceKeyedInfo(self: *TypeTable, id: TypeId, info: TypeInfo) void {
+        const idx = id.index();
+        const old = self.infos.items[idx];
+        _ = self.intern_map.remove(.{ .info = old });
+        self.infos.items[idx] = info;
+        self.intern_map.put(.{ .info = info }, id) catch unreachable;
     }
 
     /// Find a named type (struct/union/enum) by its StringId name.
@@ -422,6 +473,30 @@ pub const TypeTable = struct {
         return null;
     }
 
+    /// Source-sensitive variant of `findByName`: asserts at most one named type
+    /// matches, then returns it (or null). Quarantines the global first-match
+    /// scan — new resolver code that must not silently pick a first-of-many
+    /// author uses this so a same-name collision trips the assert instead of
+    /// resolving arbitrarily.
+    pub fn findUniqueByName(self: *const TypeTable, name: StringId) ?TypeId {
+        var found: ?TypeId = null;
+        for (self.infos.items, 0..) |info, i| {
+            const n: ?StringId = switch (info) {
+                .@"struct" => |s| s.name,
+                .@"union" => |u| u.name,
+                .tagged_union => |u| u.name,
+                .@"enum" => |e| e.name,
+                .error_set => |e| e.name,
+                else => null,
+            };
+            if (n != null and n.? == name) {
+                std.debug.assert(found == null);
+                found = TypeId.fromIndex(@intCast(i));
+            }
+        }
+        return found;
+    }
+
     // ── Convenience constructors ────────────────────────────────────────
 
     pub fn ptrTo(self: *TypeTable, pointee: TypeId) TypeId {
@@ -949,12 +1024,29 @@ fn hashTypeInfo(h: *std.hash.Wyhash, info: TypeInfo) void {
             h.update(&.{pack_present});
             if (c.pack_start) |ps| h.update(std.mem.asBytes(&ps));
         },
-        .@"struct" => |s| h.update(std.mem.asBytes(&s.name)),
+        // Nominal arms key by display name; `nominal_id` joins the key only when
-        .@"enum" => |e| h.update(std.mem.asBytes(&e.name)),
+        // nonzero, so structural (legacy) interning hashes byte-identically.
-        .@"union" => |u| h.update(std.mem.asBytes(&u.name)),
+        .@"struct" => |s| {
-        .tagged_union => |u| h.update(std.mem.asBytes(&u.name)),
+            h.update(std.mem.asBytes(&s.name));
+            if (s.nominal_id != 0) h.update(std.mem.asBytes(&s.nominal_id));
+        },
+        .@"enum" => |e| {
+            h.update(std.mem.asBytes(&e.name));
+            if (e.nominal_id != 0) h.update(std.mem.asBytes(&e.nominal_id));
+        },
+        .@"union" => |u| {
+            h.update(std.mem.asBytes(&u.name));
+            if (u.nominal_id != 0) h.update(std.mem.asBytes(&u.nominal_id));
+        },
+        .tagged_union => |u| {
+            h.update(std.mem.asBytes(&u.name));
+            if (u.nominal_id != 0) h.update(std.mem.asBytes(&u.nominal_id));
+        },
         .protocol => |p| h.update(std.mem.asBytes(&p.name)),
-        .error_set => |e| h.update(std.mem.asBytes(&e.name)),
+        .error_set => |e| {
+            h.update(std.mem.asBytes(&e.name));
+            if (e.nominal_id != 0) h.update(std.mem.asBytes(&e.nominal_id));
+        },
         .tuple => |t| {
             for (t.fields) |f| h.update(std.mem.asBytes(&f));
             if (t.names) |ns| for (ns) |n| h.update(std.mem.asBytes(&n));
@@ -1002,12 +1094,14 @@ fn typeInfoEql(a: TypeInfo, b: TypeInfo) bool {
             if (c.pack_start) |cp| if (cp != d.pack_start.?) return false;
             return c.ret == d.ret;
         },
-        .@"struct" => |s| s.name == b.@"struct".name,
+        // Nominal arms compare display name + nominal id. With both ids 0 this is
-        .@"enum" => |e| e.name == b.@"enum".name,
+        // name-only equality (legacy); a nonzero id distinguishes same-name authors.
-        .@"union" => |u| u.name == b.@"union".name,
+        .@"struct" => |s| s.name == b.@"struct".name and s.nominal_id == b.@"struct".nominal_id,
-        .tagged_union => |u| u.name == b.tagged_union.name,
+        .@"enum" => |e| e.name == b.@"enum".name and e.nominal_id == b.@"enum".nominal_id,
+        .@"union" => |u| u.name == b.@"union".name and u.nominal_id == b.@"union".nominal_id,
+        .tagged_union => |u| u.name == b.tagged_union.name and u.nominal_id == b.tagged_union.nominal_id,
         .protocol => |p| p.name == b.protocol.name,
-        .error_set => |e| e.name == b.error_set.name,
+        .error_set => |e| e.name == b.error_set.name and e.nominal_id == b.error_set.nominal_id,
         .tuple => |t| {
             const u = b.tuple;
             if (t.fields.len != u.fields.len) return false;