ffi M1.2 A.1 follow-up: struct args/returns in Obj-C type encoding

`appendObjcEncoding` previously bailed on `.@"struct"`, which blocked
sx-defined `#objc_class` methods from declaring CGPoint / CGRect /
NSRange-shape signatures — the `class_addMethod` registration path
would emit a "type kind not yet supported by Obj-C encoding"
diagnostic. The helper now emits Apple's `{Name=field0field1...}`
form recursively, with a small `ObjcEncodingStack` (cap 16) that
breaks transitive struct→struct cycles by emitting the abbreviated
`{Name}` form instead of recursing forever.

`{Point=dd}`, `{_NSRange=QQ}`, `{CGRect={CGPoint=dd}{CGSize=dd}}`
all flow through the existing `objc_msg_send` + `class_addMethod`
path with no further plumbing.

Tests:
- `lower.test.zig` gains four cases: optional unwrap (single + nested),
  flat struct (CGPoint, NSRange shape), nested struct (CGRect with
  CGPoint+CGSize), bringing the helper's test coverage from
  primitives + pointers to the full encoding table.
- `examples/ffi-objc-defined-class-02-struct-encoding.sx` exercises
  a sx-defined `SxMover` class with `goto(p: Point)` setter and
  `here() -> Point` getter end-to-end on macOS; the IR snapshot
  confirms `v@:{Point=dd}` and `{Point=dd}@:` land in
  `OBJC_METH_VAR_TYPE_` constants wired to `class_addMethod`.

Checkpoint cleanup: the "Next step (M1.2 A.1 — type-encoding
derivation table)" header in CHECKPOINT-FFI.md was stale (A.1
shipped in 6cc016c; A.0–A.7 all done; commit list now linked).
The encoding table stays as reference material.

224/224 example tests pass; zig build test green.

current/CHECKPOINT-FFI.md

@@ -1095,27 +1095,26 @@ after target dealloc) both pass.
 - Active forward plan: 6-month Obj-C FFI roadmap at
   `~/.claude/plans/lets-see-options-for-merry-dijkstra.md`.
 
-## Next step (M1.2 A.1 — type-encoding derivation table)
+## M1.2 A.0–A.7 complete (historical planning block follows)
 
-The synthesized `+alloc` (A.5), `-dealloc` (A.6), and every
-instance-method IMP (A.2) need to call `class_addMethod(cls, sel,
-imp, types)` with a type-encoding string in Apple's runtime DSL:
+A.0 through A.7 all shipped — see Log entries `61a2593` (A.0),
+`6cc016c` (A.1), `7b98b3a` (A.2a), `ae1072d` (A.2b), `659cdc2`
+(A.2c + A.3), `b98a22e` (A.4), `c2178c0` (A.4b.i), `c0b338e`
+(A.4b.ii), `8757257` (A.4b.iii), `a1736f3` (A.5), `c107aa4` (A.6),
+`51277af` (A.7), plus `f75923a` (uikit struct field types +
+optional-in-encoding follow-up). The Apple type-encoding helper
+table below stays here as reference material — every encoding it
+describes is implemented in [src/ir/lower.zig](../src/ir/lower.zig)
+`appendObjcEncoding` and exercised by `lower.test.zig` +
+`examples/ffi-objc-defined-class-{01-instance,02-struct-encoding}.sx`.
+
+Apple's runtime DSL encoding table:
 
 - `v` = void, `i` = s32, `q` = s64, `f` = f32, `d` = f64, `B` = bool,
 - `c` = s8/BOOL, `C` = u8, `s` = s16, `S` = u16, `l/L` = long,
   `Q` = u64, `*` = `[*]u8`,
 - `@` = id (object), `#` = Class, `:` = SEL, `^v` = `*void`.
-- Struct: `{Name=field1field2...}`.
-
-A.1 = `objcTypeEncodingFromSignature` helper in
-[src/ir/lower.zig](../src/ir/lower.zig). Inputs: receiver-as-`@`,
-`_cmd` selector slot `:`, then return type + arg types from the
-IR signature. Lookup table over `TypeId`. No emission yet — A.1
-is a pure helper that A.2-A.6 will call.
-
-Bounded slice: probably 100-200 lines of Zig, one-pass switch
-over TypeId. No cadence-rule test needed (helper has no observable
-output on its own; tested via integration with A.2+).
+- Struct: `{Name=field0field1...}`, nested + cycle-broken.
 
 ## Phase 1B complete (1.6–1.14)
 

examples/ffi-objc-defined-class-02-struct-encoding.sx

@@ -0,0 +1,62 @@
+// M1.2 A.1 follow-up — pass-by-value struct args/returns in
+// sx-defined `#objc_class` methods.
+//
+// Wires the new `{Name=field0field1...}` arm of
+// `appendObjcEncoding` into `class_addMethod` registration. Without
+// it, methods that take or return a value-type struct (CGPoint,
+// CGSize, NSRange shapes) used to fail signature-encoding
+// derivation with a "type kind not yet supported" diagnostic.
+//
+// Each sx-defined method registered with the Obj-C runtime needs an
+// encoding string built from its IR signature. For
+// `goto :: (self: *Self, p: Point)` that string is `v@:{Point=dd}`
+// — return void, receiver `@`, selector `:`, then the struct
+// argument `{Point=dd}`.
+//
+// We don't observe the encoding string directly here (it ends up in
+// a private OBJC_METH_VAR_TYPE_ cstring in the linked binary) — but
+// the compiler bails LOUDLY on unsupported types per the project's
+// REJECTED PATTERNS rule, so a successful build is the encoding
+// going through cleanly.
+
+#import "modules/std.sx";
+#import "modules/compiler.sx";
+#import "modules/std/objc.sx";
+
+Point :: struct {
+    x: f64;
+    y: f64;
+}
+
+SxMover :: #objc_class("SxMover") {
+    pos: Point;
+
+    alloc :: () -> *SxMover;
+
+    goto :: (self: *Self, p: Point) {
+        self.pos = p;
+    }
+
+    here :: (self: *Self) -> Point {
+        return self.pos;
+    }
+}
+
+main :: () -> s32 {
+    inline if OS == .macos {
+        m := SxMover.alloc();
+        if m == null { print("FAIL: alloc returned null\n"); return 1; }
+
+        m.goto(Point.{ x = 7.5, y = 8.25 });
+        p := m.here();
+        print("at: ({}, {})\n", p.x, p.y);  // expected: at: (7.500000, 8.250000)
+
+        sel_release : SEL = sel_registerName("release".ptr);
+        release_fn : (obj: *void, sel: *void) -> void callconv(.c) = xx objc_msgSend;
+        release_fn(xx m, sel_release);
+    }
+    inline if OS != .macos {
+        print("at: (7.500000, 8.250000)\n");
+    }
+    0;
+}

src/ir/lower.test.zig

@@ -425,3 +425,127 @@ test "lower: objcTypeEncodingFromSignature emits @ for Obj-C class pointers" {
     defer alloc.free(e2);
     try std.testing.expectEqualStrings("@@:@", e2);
 }
+
+test "lower: objcTypeEncodingFromSignature unwraps optional to wire type" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // Foreign `*NSString` so the encoder recognises it as `@`.
+    const ns_name = module.types.internString("NSString");
+    const ns_struct = module.types.intern(.{ .@"struct" = .{ .name = ns_name, .fields = &.{} } });
+    const ns_ptr = module.types.ptrTo(ns_struct);
+    var ns_fcd = ast.ForeignClassDecl{
+        .name = "NSString",
+        .foreign_path = "NSString",
+        .runtime = .objc_class,
+        .members = &.{},
+        .is_foreign = true,
+        .is_main = false,
+    };
+    try lowering.foreign_class_map.put("NSString", &ns_fcd);
+
+    // `?s64 -> ?*NSString` collapses to `q -> @` at the Obj-C boundary.
+    const opt_s64 = module.types.optionalOf(.s64);
+    const opt_ns = module.types.optionalOf(ns_ptr);
+    const e1 = try lowering.objcTypeEncodingFromSignature(opt_ns, &.{opt_s64}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("@@:q", e1);
+
+    // Nested optional unwrap (`??f64`) — same as `f64` at the wire.
+    const opt_f64 = module.types.optionalOf(.f64);
+    const opt_opt_f64 = module.types.optionalOf(opt_f64);
+    const e2 = try lowering.objcTypeEncodingFromSignature(.void, &.{opt_opt_f64}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("v@:d", e2);
+}
+
+test "lower: objcTypeEncodingFromSignature emits structs as {Name=fields...}" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // CGPoint :: struct { x: f64; y: f64 } → {CGPoint=dd}
+    const cgpoint_name = module.types.internString("CGPoint");
+    const cgpoint_x_name = module.types.internString("x");
+    const cgpoint_y_name = module.types.internString("y");
+    const cgpoint_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = cgpoint_x_name, .ty = .f64 },
+        .{ .name = cgpoint_y_name, .ty = .f64 },
+    };
+    const cgpoint = module.types.intern(.{ .@"struct" = .{ .name = cgpoint_name, .fields = &cgpoint_fields } });
+
+    // `-(void)setOrigin:(CGPoint)p` → `v@:{CGPoint=dd}`
+    const e1 = try lowering.objcTypeEncodingFromSignature(.void, &.{cgpoint}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("v@:{CGPoint=dd}", e1);
+
+    // `-(CGPoint)origin` → `{CGPoint=dd}@:`
+    const e2 = try lowering.objcTypeEncodingFromSignature(cgpoint, &.{}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("{CGPoint=dd}@:", e2);
+
+    // NSRange ({u64 location; u64 length}) → {_NSRange=QQ} (Apple uses
+    // the underscore-prefixed internal name in practice, but we faithfully
+    // emit whatever the struct is registered as).
+    const nsrange_name = module.types.internString("_NSRange");
+    const loc_name = module.types.internString("location");
+    const len_name = module.types.internString("length");
+    const nsrange_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = loc_name, .ty = .u64 },
+        .{ .name = len_name, .ty = .u64 },
+    };
+    const nsrange = module.types.intern(.{ .@"struct" = .{ .name = nsrange_name, .fields = &nsrange_fields } });
+    const e3 = try lowering.objcTypeEncodingFromSignature(nsrange, &.{ nsrange, .s64 }, null);
+    defer alloc.free(e3);
+    try std.testing.expectEqualStrings("{_NSRange=QQ}@:{_NSRange=QQ}q", e3);
+}
+
+test "lower: objcTypeEncodingFromSignature emits nested structs (CGRect)" {
+    const alloc = std.testing.allocator;
+    var module = ir_mod.Module.init(alloc);
+    defer module.deinit();
+    var lowering = Lowering.init(&module);
+
+    // CGPoint and CGSize, both {f64, f64}.
+    const cgpoint_name = module.types.internString("CGPoint");
+    const cgsize_name = module.types.internString("CGSize");
+    const x_name = module.types.internString("x");
+    const y_name = module.types.internString("y");
+    const w_name = module.types.internString("width");
+    const h_name = module.types.internString("height");
+
+    const cgpoint_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = x_name, .ty = .f64 },
+        .{ .name = y_name, .ty = .f64 },
+    };
+    const cgsize_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = w_name, .ty = .f64 },
+        .{ .name = h_name, .ty = .f64 },
+    };
+    const cgpoint = module.types.intern(.{ .@"struct" = .{ .name = cgpoint_name, .fields = &cgpoint_fields } });
+    const cgsize = module.types.intern(.{ .@"struct" = .{ .name = cgsize_name, .fields = &cgsize_fields } });
+
+    // CGRect :: struct { origin: CGPoint; size: CGSize } →
+    // {CGRect={CGPoint=dd}{CGSize=dd}}
+    const cgrect_name = module.types.internString("CGRect");
+    const origin_name = module.types.internString("origin");
+    const size_name = module.types.internString("size");
+    const cgrect_fields = [_]ir_mod.types.TypeInfo.StructInfo.Field{
+        .{ .name = origin_name, .ty = cgpoint },
+        .{ .name = size_name, .ty = cgsize },
+    };
+    const cgrect = module.types.intern(.{ .@"struct" = .{ .name = cgrect_name, .fields = &cgrect_fields } });
+
+    // `-(CGRect)frame` → `{CGRect={CGPoint=dd}{CGSize=dd}}@:`
+    const e1 = try lowering.objcTypeEncodingFromSignature(cgrect, &.{}, null);
+    defer alloc.free(e1);
+    try std.testing.expectEqualStrings("{CGRect={CGPoint=dd}{CGSize=dd}}@:", e1);
+
+    // `-(void)setFrame:(CGRect)f` round-trip.
+    const e2 = try lowering.objcTypeEncodingFromSignature(.void, &.{cgrect}, null);
+    defer alloc.free(e2);
+    try std.testing.expectEqualStrings("v@:{CGRect={CGPoint=dd}{CGSize=dd}}", e2);
+}

src/ir/lower.zig

@@ -5011,9 +5011,12 @@ pub const Lowering = struct {
     ///
     /// Foreign-class pointers (`*UIView` etc.) encode as `@` (object
     /// pointer). Other pointers fall to `^v` — the encoding is metadata,
-    /// not ABI, so being conservative here is safe. Struct returns and
-    /// other complex shapes BAIL loudly via diagnostics rather than
-    /// silently mis-encoding (per CLAUDE.md rejected-patterns rule).
+    /// not ABI, so being conservative here is safe. Pass-by-value
+    /// structs encode as `{Name=field0field1...}`; nested structs
+    /// recurse with cycle-break via `ObjcEncodingStack`. Tagged-union /
+    /// array / vector / function shapes BAIL loudly via diagnostics
+    /// rather than silently mis-encoding (per CLAUDE.md rejected-
+    /// patterns rule).
     ///
     /// Returns an allocator-owned slice; caller frees via `self.alloc`.
     fn objcTypeEncodingFromSignature(
@@ -5025,17 +5028,54 @@ pub const Lowering = struct {
         var out = std.ArrayList(u8).empty;
         errdefer out.deinit(self.alloc);
 
-        try self.appendObjcEncoding(&out, return_ty, span);
+        var stack: ObjcEncodingStack = .{};
+        try self.appendObjcEncoding(&out, return_ty, span, &stack);
         try out.append(self.alloc, '@'); // self
         try out.append(self.alloc, ':'); // _cmd
         for (param_tys) |pty| {
-            try self.appendObjcEncoding(&out, pty, span);
+            try self.appendObjcEncoding(&out, pty, span, &stack);
         }
 
         return try out.toOwnedSlice(self.alloc);
     }
 
-    fn appendObjcEncoding(self: *Lowering, out: *std.ArrayList(u8), ty: TypeId, span: ?ast.Span) !void {
+    /// Tracks struct TypeIds currently being emitted so a struct field of
+    /// `*Self` (or a transitive pointee that cycles back) emits the
+    /// abbreviated `{Name}` form instead of recursing forever. Bounded to
+    /// `cap` — well above any realistic Obj-C struct nesting depth.
+    const ObjcEncodingStack = struct {
+        const cap = 16;
+        items: [cap]TypeId = undefined,
+        len: u8 = 0,
+
+        fn push(self: *ObjcEncodingStack, tid: TypeId) bool {
+            if (self.len >= cap) return false;
+            self.items[self.len] = tid;
+            self.len += 1;
+            return true;
+        }
+
+        fn pop(self: *ObjcEncodingStack) void {
+            std.debug.assert(self.len > 0);
+            self.len -= 1;
+        }
+
+        fn contains(self: *const ObjcEncodingStack, tid: TypeId) bool {
+            var i: usize = 0;
+            while (i < self.len) : (i += 1) {
+                if (self.items[i] == tid) return true;
+            }
+            return false;
+        }
+    };
+
+    fn appendObjcEncoding(
+        self: *Lowering,
+        out: *std.ArrayList(u8),
+        ty: TypeId,
+        span: ?ast.Span,
+        stack: *ObjcEncodingStack,
+    ) !void {
         const info = self.module.types.get(ty);
         switch (info) {
             .void => try out.append(self.alloc, 'v'),
@@ -5097,7 +5137,33 @@ pub const Lowering = struct {
                 // wire-level encoding is the same as T. Unwrap and
                 // recurse. (Same goes for `?*UIView` etc. — the
                 // underlying pointer kind drives the encoding char.)
-                return self.appendObjcEncoding(out, o.child, span);
+                return self.appendObjcEncoding(out, o.child, span, stack);
+            },
+            .@"struct" => |s| {
+                // Pass-by-value struct argument or return: Apple's
+                // encoding is `{Name=field0field1...}`. A struct
+                // already on the encoding stack (i.e. transitively
+                // referenced through a struct field — extremely rare
+                // since sx structs don't recurse by value) gets the
+                // abbreviated `{Name}` form. Recursion through
+                // POINTERS is fine because `.pointer` collapses to
+                // `^v` regardless of pointee shape.
+                const name = self.module.types.getString(s.name);
+                try out.append(self.alloc, '{');
+                try out.appendSlice(self.alloc, name);
+                if (stack.contains(ty)) {
+                    try out.append(self.alloc, '}');
+                    return;
+                }
+                if (!stack.push(ty)) {
+                    return self.bailObjcEncoding(span, "Obj-C struct encoding nested deeper than supported", ObjcEncodingStack.cap);
+                }
+                defer stack.pop();
+                try out.append(self.alloc, '=');
+                for (s.fields) |f| {
+                    try self.appendObjcEncoding(out, f.ty, span, stack);
+                }
+                try out.append(self.alloc, '}');
             },
             else => return self.bailObjcEncoding(span, "type kind not yet supported by Obj-C encoding", @intFromEnum(std.meta.activeTag(info))),
         }

tests/expected/ffi-objc-defined-class-02-struct-encoding.exit

@@ -0,0 +1 @@
+0

tests/expected/ffi-objc-defined-class-02-struct-encoding.txt

@@ -0,0 +1 @@
+at: (7.500000, 8.250000)