- Rebased with master. Reduce to MVP.

feat: Add type embedding + compile-time safety

Implements object type embedding with the use keyword, enabling types to embed other
types and access their fields/methods.

Features:
- Two-step field access through embedded types
- Method embedding support
- Conflict resolution (child fields take precedence)
- Hidden embedded fields for encapsulation
- Circular embedding detection using resolving flag pattern
- Compile-time method resolution for static types (direct call emission)
- Field access coalescing (hidden local reuse to prevent IR bloat)
- Compile-time error for ambiguous field assignment in methods
  (requires explicit self. for field mutation; e.g. use self.value = new_val)

Tests:
- All existing tests pass
- New tests added:
  - test/types/type_embedding_base.cy
  - test/types/type_embedding_basic.cy
  - test/types/type_embedding_circular_error.cy (intentionally compile-errors)
  - test/types/type_embedding_performance.cy
  - test/types/type_embedding_three_objects_test.cy
  - test/types/test_field_assignment_error.cy
  - test/types/test_field_assignment_compile_error.cy  (intentionally compile-errors)

Author: Bleak84

docs/docs.md

@@ -1201,7 +1201,7 @@ type Base:
     a int
 
 fn (&Base) double() -> int:
-    return a * 2
+    return $a * 2
 
 type Container:
     b use Base

src/ast.zig

@@ -715,6 +715,7 @@ pub const Field = struct {
     typeSpec: ?*Node,
     init: ?*Node,
     hidden: bool,
+    embedded: bool,
 };
 
 pub const TraitDecl = extern struct {
@@ -748,6 +749,7 @@ pub const StructDecl = extern struct {
     attrs: Slice(*Attribute),
     impls: Slice(*ImplDecl),
     fields: Slice(*Field),
+    num_embedded_fields: u32,
     is_tuple: bool,
     pos: u32,
 };

src/builtins/cy.cy

@@ -848,6 +848,7 @@ type StructDecl:
     attrs    []^Node
     impls    []^Node
     fields   []^Node
+    num_embedded_fields i32
     is_tuple bool
     pos      i32
 

src/parser.zig

@@ -948,7 +948,7 @@ pub const Parser = struct {
         });
     }
 
-    fn parseStructField(self: *Parser) !?*ast.Node {
+    fn parseStructField(self: *Parser) !?*ast.Field {
         var hidden = false;
         if (self.peek().tag() == .minus) {
             hidden = true;
@@ -959,20 +959,33 @@ pub const Parser = struct {
             return null;
         };
 
+        // Check for 'use' after field name (type embedding)
+        const is_embedded = if (self.peek().tag() == .use_k) blk: {
+            self.advance();
+            break :blk true;
+        } else false;
+
         const typeSpec = try self.parseOptTypeSpec();
 
+        // Validate embedded fields must have a type specifier
+        if (is_embedded and typeSpec == null) {
+            return self.reportError("Embedded field must have a type specifier.", &.{});
+        }
+
         var init_expr: ?*ast.Node = null;
         if (self.peek().tag() == .equal) {
             self.advance();
             init_expr = try self.parseExpr(.{}) orelse {
                 return self.reportError("Expected default initializer.", &.{});
             };
         }
-        return self.ast.newNodeErase(.struct_field, .{
+
+        return self.ast.newNode(.struct_field, .{
             .name = name,
             .typeSpec = typeSpec,
             .init = init_expr,
             .hidden = hidden,
+            .embedded = is_embedded,
         });
     }
 
@@ -1268,7 +1281,7 @@ pub const Parser = struct {
     }
 
     fn newStructDecl(self: *Parser, start: TokenId, node_t: ast.NodeType, name: *ast.Node,
-        config: TypeDeclConfig, impls: []*ast.ImplDecl, fields: []*ast.Field,
+        config: TypeDeclConfig, impls: []*ast.ImplDecl, fields: []*ast.Field, num_embedded_fields: usize,
         is_tuple: bool) !*ast.StructDecl {
 
         const n = try self.ast.newNodeErase(.struct_decl, .{
@@ -1277,6 +1290,7 @@ pub const Parser = struct {
             .impls = .{ .ptr = impls.ptr, .len = impls.len },
             .fields = .{ .ptr = fields.ptr, .len = fields.len },
             .attrs = .{ .ptr = config.attrs.ptr, .len = config.attrs.len },
+            .num_embedded_fields = @intCast(num_embedded_fields),
             .is_tuple = is_tuple,
         });
         n.setType(node_t);
@@ -1341,10 +1355,15 @@ pub const Parser = struct {
         return @ptrCast(try self.ast.dupeNodes(self.node_stack.items[field_start..]));
     }
 
-    fn parseTypeFields(self: *Parser, req_indent: u32) ![]*ast.Field {
+    fn parseTypeFields(self: *Parser, req_indent: u32, out_num_embedded_fields: *usize) ![]*ast.Field {
+        var num_embedded_fields: usize = 0;
         var field = (try self.parseStructField()) orelse {
+            out_num_embedded_fields.* = 0;
             return &.{};
         };
+        if (field.embedded) {
+            num_embedded_fields += 1;
+        }
 
         const field_start = self.node_stack.items.len;
         defer self.node_stack.items.len = field_start;
@@ -1359,8 +1378,12 @@ pub const Parser = struct {
             field = (try self.parseStructField()) orelse {
                 break;
             };
+            if (field.embedded) {
+                num_embedded_fields += 1;
+            }
             try self.pushNode(@ptrCast(field));
         }
+        out_num_embedded_fields.* = num_embedded_fields;
         return @ptrCast(try self.ast.dupeNodes(self.node_stack.items[field_start..]));
     }
 
@@ -1476,27 +1499,28 @@ pub const Parser = struct {
             self.advance();
             const fields = try self.parseTupleFields();
             if (self.peek().tag() != .colon) {
-                return self.newStructDecl(start, ntype, name, config, &.{}, fields, true);
+                return self.newStructDecl(start, ntype, name, config, &.{}, fields, 0, true);
             }
 
             self.advance();
             const req_indent = try self.parseFirstChildIndent(self.cur_indent);
             const prev_indent = self.pushIndent(req_indent);
             defer self.cur_indent = prev_indent;
 
-            return self.newStructDecl(start, ntype, name, config, &.{}, fields, true);
+            return self.newStructDecl(start, ntype, name, config, &.{}, fields, 0, true);
         } else {
             // Only declaration. No members.
-            return self.newStructDecl(start, ntype, name, config, &.{}, &.{}, false);
+            return self.newStructDecl(start, ntype, name, config, &.{}, &.{}, 0, false);
         }
 
         const req_indent = try self.parseFirstChildIndent(self.cur_indent);
         const prev_indent = self.pushIndent(req_indent);
         defer self.cur_indent = prev_indent;
 
         const impls = try self.parseImplDecls(req_indent);
-        const fields = try self.parseTypeFields(req_indent);
-        return self.newStructDecl(start, ntype, name, config, impls, fields, false);
+        var num_embedded_fields: usize = 0;
+        const fields = try self.parseTypeFields(req_indent, &num_embedded_fields);
+        return self.newStructDecl(start, ntype, name, config, impls, fields, num_embedded_fields, false);
     }
 
     pub fn parse_with_decl(self: *Parser, start: u32, attrs: []*ast.Attribute) !*ast.Node {

src/sema.zig

@@ -1997,6 +1997,16 @@ fn semaAccessFieldName(c: *cy.Chunk, rec_n: *ast.Node, rec: ExprResult, name: []
     const mod = type_.sym().getMod();
 
     const sym = mod.getSym(name) orelse {
+        if (type_.has_embeddings()) {
+            if (try get_embedded_sym(c, type_.cast(.struct_t), name, @ptrCast(field))) |embedded_res| {
+                if (embedded_res.sym.type == .field) {
+                    const embedded_field = embedded_res.sym.cast(.field);
+                    const final_rec = try semaField(c, rec, @ptrCast(field), embedded_res.field_idx, embedded_res.embedded_t, @ptrCast(field));
+                    return semaField(c, final_rec, @ptrCast(field), embedded_field.idx, embedded_field.type, @ptrCast(field));
+                }
+            }
+        }
+
         // TODO: This depends on @get being known, make sure @get is a nested declaration.
 
         if (mod.getSym("@get")) |get_sym| {
@@ -4952,16 +4962,21 @@ pub fn lookupIdent(self: *cy.Chunk, name: []const u8, node: *ast.Node) !LookupId
         return LookupIdentResult{
             .capture = id,
         };
-    } else {
-        const res = (try lookupStaticIdent(self, name, node)) orelse {
-            const resolve_ctx_idx = self.resolve_stack.items.len-1;
-            const ctx = self.resolve_stack.items[resolve_ctx_idx];
-            const search_c = ctx.chunk;
-            _ = search_c;
-            return self.reportErrorFmt("Undeclared variable `{}`.", &.{v(name)}, node);
-        };
+    }
+
+    if (try lookupStaticIdent(self, name, node)) |res| {
         return res;
     }
+
+    if (self.cur_sema_proc.isMethodBlock) {
+        const base_t = self.cur_sema_proc.func.?.sig.params()[0].get_type().getBaseType();
+        if (base_t.sym().getMod().getSym(name)) |sym| {
+            if (sym.type == .field) {
+                return self.reportErrorFmt("Expected explicit `${}` or `self.{}`.", &.{v(name), v(name)}, node);
+            }
+        }
+    }
+    return self.reportErrorFmt("Undeclared variable `{}`.", &.{v(name)}, node);
 }
 
 pub fn lookupStaticIdent(c: *cy.Chunk, name: []const u8, node: *ast.Node) !?LookupIdentResult {
@@ -7365,6 +7380,27 @@ pub fn semaExprNoCheck(c: *cy.Chunk, node: *ast.Node, cstr: Cstr) anyerror!ExprR
     }
 }
 
+const EmbeddedResult = struct {
+    field_idx: usize,
+    embedded_t: *cy.Type,
+    sym: *cy.Sym,
+};
+
+fn get_embedded_sym(c: *cy.Chunk, rec_t: *cy.types.Struct, name: []const u8, node: *ast.Node) !?EmbeddedResult {
+    const fields = rec_t.getEmbeddedFields();
+    for (fields) |field| {
+        if (try c.getResolvedSym(&field.embedded_type.sym().head, name, node)) |embedded_sym| {
+            // TODO: Cache result into the receiver type's module as a `EmbeddedField`.
+            return .{
+                .field_idx = field.field_idx,
+                .embedded_t = field.embedded_type,
+                .sym = embedded_sym,
+            };
+        }
+    }
+    return null;
+}
+
 pub fn semaCallExpr(c: *cy.Chunk, node: *ast.Node, opt_target: ?*cy.Type) !ExprResult {
     const call = node.cast(.callExpr);
     if (call.hasNamedArg) {
@@ -7373,7 +7409,7 @@ pub fn semaCallExpr(c: *cy.Chunk, node: *ast.Node, opt_target: ?*cy.Type) !ExprR
 
     if (call.callee.type() == .accessExpr) {
         const callee = call.callee.cast(.accessExpr);
-        const leftRes = try c.semaExprSkipSym(callee.left, .{});
+        var leftRes = try c.semaExprSkipSym(callee.left, .{});
 
         const right_name = callee.right.name();
         if (leftRes.resType == .sym) {
@@ -7385,7 +7421,18 @@ pub fn semaCallExpr(c: *cy.Chunk, node: *ast.Node, opt_target: ?*cy.Type) !ExprR
 
             if (leftSym.isValue()) {
                 // Look for sym under left type's module.
-                const rightSym = try c.accessResolvedSymOrFail(leftRes.type, right_name, callee.right);
+                const rightSym = (try c.accessResolvedSym(leftRes.type, right_name, callee.right)) orelse b: {
+                    if (leftRes.type.has_embeddings()) {
+                        if (try get_embedded_sym(c, leftRes.type.cast(.struct_t), right_name, callee.right)) |embedded_res| {
+                            leftRes = try semaField(c, leftRes, callee.right, embedded_res.field_idx, embedded_res.embedded_t, callee.right);
+                            break :b embedded_res.sym;
+                        }
+                    }
+                    const type_name = try c.sema.allocTypeName(leftRes.type);
+                    defer c.alloc.free(type_name);
+                    return c.reportErrorFmt("Can not find the symbol `{}` in `{}`.", &.{v(right_name), v(type_name)}, callee.right);
+                };
+
                 if (rightSym.type == .func) {
                     // Call method.
                     const func_sym = rightSym.cast(.func);
@@ -7408,7 +7455,17 @@ pub fn semaCallExpr(c: *cy.Chunk, node: *ast.Node, opt_target: ?*cy.Type) !ExprR
             }
         } else {
             // Look for sym under left type's module.
-            const rightSym = try c.accessResolvedSymOrFail(leftRes.type, right_name, callee.right);
+            const rightSym = (try c.accessResolvedSym(leftRes.type, right_name, callee.right)) orelse b: {
+                if (leftRes.type.has_embeddings()) {
+                    if (try get_embedded_sym(c, leftRes.type.cast(.struct_t), right_name, callee.right)) |embedded_res| {
+                        leftRes = try semaField(c, leftRes, callee.right, embedded_res.field_idx, embedded_res.embedded_t, callee.right);
+                        break :b embedded_res.sym;
+                    }
+                }
+                const type_name = try c.sema.allocTypeName(leftRes.type);
+                defer c.alloc.free(type_name);
+                return c.reportErrorFmt("Can not find the symbol `{}` in `{}`.", &.{v(right_name), v(type_name)}, callee.right);
+            };
 
             if (rightSym.type == .func) {
                 return c.semaCallFuncSymRec(rightSym.cast(.func), callee.left, leftRes, call.args.slice(), false, node);

src/sema_type.zig

@@ -823,6 +823,11 @@ pub fn resolveStructFields(c: *cy.Chunk, struct_t: *cy.types.Struct, decl: *ast.
     const fields = try c.alloc.alloc(cy.types.Field, decl.fields.len);
     errdefer c.alloc.free(fields);
 
+    // Track embedded fields separately
+    var embedded_i: usize = 0;
+    var embedded_fields = try c.alloc.alloc(cy.types.EmbeddedFieldInfo, decl.num_embedded_fields);
+    errdefer c.alloc.free(embedded_fields);
+
     var field_group_t: ?*cy.Type = null;
     var field_group_end: usize = undefined;
     for (decl.fields.slice(), 0..) |field, i| {
@@ -866,6 +871,23 @@ pub fn resolveStructFields(c: *cy.Chunk, struct_t: *cy.types.Struct, decl: *ast.
             alignment = member_alignment;
         }
 
+        // Validate embedded type is an object type
+        if (field.embedded) {
+            if (field_t.kind() != .struct_t) {
+                return c.reportErrorFmt(
+                    "Embedded field must be a struct type, got {s}",
+                    &.{v(@tagName(field_t.kind()))},
+                    @ptrCast(field)
+                );
+            }
+            
+            embedded_fields[embedded_i] = .{
+                .field_idx = @intCast(i),
+                .embedded_type = field_t,
+            };
+            embedded_i += 1;
+        }
+
         const sym = try c.declareField(@ptrCast(struct_t.base.sym()), fieldName, i, field_t, @ptrCast(field));
         fields[i] = .{
             .sym = @ptrCast(sym),
@@ -907,6 +929,8 @@ pub fn resolveStructFields(c: *cy.Chunk, struct_t: *cy.types.Struct, decl: *ast.
     struct_t.fields_ptr = fields.ptr;
     struct_t.fields_len = @intCast(fields.len);
     struct_t.field_state_len = field_state_len;
+    struct_t.embedded_fields_ptr = embedded_fields.ptr;
+    struct_t.embedded_fields_len = @intCast(embedded_fields.len);
     struct_t.resolving_struct = false;
 
     struct_t.base.info.borrow_only = has_borrow_child;

src/types.zig

@@ -116,6 +116,10 @@ pub const Type = extern struct {
         }
     }
 
+    pub fn has_embeddings(self: *Type) bool {
+        return self.kind() == .struct_t and self.cast(.struct_t).hasEmbeddings();
+    }
+
     pub fn isCZeroEligible(self: *Type) bool {
         switch (self.id()) {
             else => {
@@ -943,6 +947,15 @@ pub const Choice = extern struct {
     }
 };
 
+/// Tracks embedded fields for automatic member surfacing
+pub const EmbeddedFieldInfo = struct {
+    /// Index into the fields array
+    field_idx: u32,
+    
+    /// TypeId of the embedded type
+    embedded_type: *cy.Type,
+};
+
 /// TODO: Hash fields for static casting.
 pub const Struct = extern struct {
     base: Type = undefined,
@@ -952,6 +965,10 @@ pub const Struct = extern struct {
     fields_len: u32 = cy.NullId,
     fields_owned: bool = true,
 
+    // Embedded field tracking
+    embedded_fields_ptr: [*]const EmbeddedFieldInfo = undefined,
+    embedded_fields_len: u32 = 0,
+
     /// Recursive. Field states only includes struct members.
     field_state_len: usize = 0,
 
@@ -984,6 +1001,11 @@ pub const Struct = extern struct {
                 impl.deinit(alloc);
             }
             alloc.free(self.impls());
+
+            if (self.embedded_fields_len > 0) {
+                const embedded = self.embedded_fields_ptr[0..self.embedded_fields_len];
+                alloc.free(embedded);
+            }
         }
     }
 
@@ -1003,6 +1025,14 @@ pub const Struct = extern struct {
         }
         return false;
     }
+
+    pub fn getEmbeddedFields(self: *Struct) []const EmbeddedFieldInfo {
+        return self.embedded_fields_ptr[0..self.embedded_fields_len];
+    }
+    
+    pub fn hasEmbeddings(self: *Struct) bool {
+        return self.embedded_fields_len > 0;
+    }
 };
 
 pub const Impl = struct {