tiny.choir.composition.source.module

1const fixture = @import("../fixture/root.zig");2const std = @import("std");3const source = @import("root.zig");4const verification = @import("verification/root.zig");56const Allocator = std.mem.Allocator;78pub const VerificationError = verification.Error;910/// Owns verified semantic partitions, logical boundaries, call sites, and provenance.11/// Physical placement and runtime state are deliberately absent from this product.12pub const PartitionedModule = struct {13    allocator: Allocator,14    name: []const u8,15    boundaries: std.ArrayList(source.Boundary) = .empty,16    partitions: std.ArrayList(source.Partition) = .empty,17    call_sites: std.ArrayList(source.SemanticCallSite) = .empty,1819    pub fn init(allocator: Allocator, name: []const u8) Allocator.Error!PartitionedModule {20        return .{21            .allocator = allocator,22            .name = try allocator.dupe(u8, name),23        };24    }2526    pub fn clone(self: *const PartitionedModule, allocator: Allocator) Allocator.Error!PartitionedModule {27        var copy = try PartitionedModule.init(allocator, self.name);28        errdefer copy.deinit();29        try copy.boundaries.ensureTotalCapacity(allocator, self.boundaries.items.len);30        for (self.boundaries.items) |boundary_value| copy.boundaries.appendAssumeCapacity(try boundary_value.clone(allocator));31        try copy.partitions.ensureTotalCapacity(allocator, self.partitions.items.len);32        for (self.partitions.items) |partition_value| copy.partitions.appendAssumeCapacity(try partition_value.clone(allocator));33        try copy.call_sites.ensureTotalCapacity(allocator, self.call_sites.items.len);34        for (self.call_sites.items) |call_site| copy.call_sites.appendAssumeCapacity(try call_site.clone(allocator));35        return copy;36    }3738    pub fn deinit(self: *PartitionedModule) void {39        var call_site_index = self.call_sites.items.len;40        while (call_site_index != 0) {41            call_site_index -= 1;42            self.call_sites.items[call_site_index].deinit(self.allocator);43        }44        self.call_sites.deinit(self.allocator);45        var partition_index = self.partitions.items.len;46        while (partition_index != 0) {47            partition_index -= 1;48            self.partitions.items[partition_index].deinit(self.allocator);49        }50        self.partitions.deinit(self.allocator);51        var boundary_index = self.boundaries.items.len;52        while (boundary_index != 0) {53            boundary_index -= 1;54            self.boundaries.items[boundary_index].deinit(self.allocator);55        }56        self.boundaries.deinit(self.allocator);57        self.allocator.free(self.name);58        self.* = undefined;59    }6061    pub fn addBoundary(self: *PartitionedModule, spec: source.BoundarySpec) (Allocator.Error || VerificationError)!void {62        try verification.verifyBoundarySpec(spec);63        if (self.boundary(spec.id) != null) return error.DuplicateBoundary;64        try verification.boundary.verifyAliasSpec(self, spec);65        var boundary_value = try source.Boundary.init(self.allocator, spec);66        errdefer boundary_value.deinit(self.allocator);67        try self.boundaries.append(self.allocator, boundary_value);68    }6970    pub fn addPartition(self: *PartitionedModule, spec: source.PartitionSpec) (Allocator.Error || VerificationError)!void {71        if (self.partition(spec.id) != null) return error.DuplicatePartition;72        for (spec.inputs) |id| if (self.boundary(id) == null) return error.MissingBoundary;73        for (spec.outputs) |id| if (self.boundary(id) == null) return error.MissingBoundary;74        try verification.verifyPartitionSpec(self, spec);75        var partition_value = try source.Partition.init(self.allocator, spec);76        errdefer partition_value.deinit(self.allocator);77        try self.partitions.append(self.allocator, partition_value);78    }7980    pub fn addCallSite(self: *PartitionedModule, spec: source.SemanticCallSiteSpec) (Allocator.Error || VerificationError)!void {81        try verification.verifyCallSiteSpec(self, spec);82        var call_site = try source.SemanticCallSite.init(self.allocator, spec);83        errdefer call_site.deinit(self.allocator);84        try self.call_sites.append(self.allocator, call_site);85    }8687    pub fn verify(self: *const PartitionedModule) VerificationError!void {88        try verification.verifyModule(self);89    }9091    pub fn boundary(self: *const PartitionedModule, id: source.BoundaryId) ?*const source.Boundary {92        for (self.boundaries.items) |*boundary_value| {93            if (boundary_value.id.value == id.value) return boundary_value;94        }95        return null;96    }9798    pub fn partition(self: *const PartitionedModule, id: source.PartitionId) ?*const source.Partition {99        for (self.partitions.items) |*partition_value| {100            if (partition_value.id.value == id.value) return partition_value;101        }102        return null;103    }104105    pub fn callSite(self: *const PartitionedModule, id: source.CallSiteId) ?*const source.SemanticCallSite {106        for (self.call_sites.items) |*call_site| {107            if (call_site.id.value == id.value) return call_site;108        }109        return null;110    }111};112113test "partitioned module owns and verifies static boundary descriptors" {114    var module = try PartitionedModule.init(std.testing.allocator, "typed_boundaries");115    defer module.deinit();116117    try std.testing.expectError(error.BoundarySizeMismatch, module.addBoundary(.{118        .id = .{ .value = 1 },119        .name = "wrong_size",120        .element_type = .f32,121        .dimensions = &.{8},122        .byte_size = 31,123        .access = .read,124        .ownership = .borrowed,125        .alias = .disjoint,126        .provenance = .{ .path = "typed.chic", .symbol = "wrong_size" },127    }));128    try std.testing.expectError(error.InvalidBoundaryShape, module.addBoundary(.{129        .id = .{ .value = 1 },130        .name = "zero_extent",131        .element_type = .f32,132        .dimensions = &.{0},133        .byte_size = 4,134        .access = .read,135        .ownership = .borrowed,136        .alias = .disjoint,137        .provenance = .{ .path = "typed.chic", .symbol = "zero_extent" },138    }));139    try std.testing.expectError(error.InvalidBoundaryShape, module.addBoundary(.{140        .id = .{ .value = 1 },141        .name = "overflow",142        .element_type = .f64,143        .dimensions = &.{std.math.maxInt(u64)},144        .byte_size = 8,145        .access = .read,146        .ownership = .borrowed,147        .alias = .disjoint,148        .provenance = .{ .path = "typed.chic", .symbol = "overflow" },149    }));150151    var dimensions = [_]u64{8};152    try module.addBoundary(.{153        .id = .{ .value = 1 },154        .name = "input",155        .element_type = .f32,156        .dimensions = &dimensions,157        .byte_size = 32,158        .access = .read,159        .ownership = .borrowed,160        .alias = .disjoint,161        .provenance = .{ .path = "typed.chic", .symbol = "input" },162    });163    dimensions[0] = 4;164    try std.testing.expectEqualSlices(u64, &.{8}, module.boundary(.{ .value = 1 }).?.dimensions);165    try module.addBoundary(.{166        .id = .{ .value = 2 },167        .name = "scalar",168        .element_type = .f64,169        .dimensions = &.{},170        .byte_size = 8,171        .access = .write,172        .ownership = .produced,173        .alias = .disjoint,174        .provenance = .{ .path = "typed.chic", .symbol = "scalar" },175    });176    try module.verify();177}178179test "partitioned module rejects incomplete and contradictory alias contracts" {180    var module = try PartitionedModule.init(std.testing.allocator, "aliases");181    defer module.deinit();182183    try std.testing.expectError(error.EmptyProvenance, module.addBoundary(.{184        .id = .{ .value = 1 },185        .name = "empty_provenance",186        .element_type = .f32,187        .dimensions = &.{2},188        .byte_size = 8,189        .access = .read,190        .ownership = .borrowed,191        .alias = .disjoint,192        .provenance = .{ .path = "", .symbol = "" },193    }));194    try std.testing.expectError(error.SelfBoundaryAlias, module.addBoundary(.{195        .id = .{ .value = 1 },196        .name = "self_alias",197        .element_type = .f32,198        .dimensions = &.{2},199        .byte_size = 8,200        .access = .read,201        .ownership = .borrowed,202        .alias = .{ .boundary = .{ .value = 1 } },203        .provenance = .{ .path = "aliases.chic", .symbol = "self_alias" },204    }));205    try std.testing.expectError(error.ProducedBoundaryAlias, module.addBoundary(.{206        .id = .{ .value = 2 },207        .name = "produced_alias",208        .element_type = .f32,209        .dimensions = &.{2},210        .byte_size = 8,211        .access = .write,212        .ownership = .produced,213        .alias = .{ .boundary = .{ .value = 1 } },214        .provenance = .{ .path = "aliases.chic", .symbol = "produced_alias" },215    }));216217    try module.addBoundary(.{218        .id = .{ .value = 1 },219        .name = "base",220        .element_type = .f32,221        .dimensions = &.{2},222        .byte_size = 8,223        .access = .read,224        .ownership = .borrowed,225        .alias = .disjoint,226        .provenance = .{ .path = "aliases.chic", .symbol = "base", .line = 1 },227    });228    try module.addBoundary(.{229        .id = .{ .value = 2 },230        .name = "missing",231        .element_type = .f32,232        .dimensions = &.{2},233        .byte_size = 8,234        .access = .read_write,235        .ownership = .borrowed,236        .alias = .{ .boundary = .{ .value = 99 } },237        .provenance = .{ .path = "aliases.chic", .symbol = "missing", .line = 2 },238    });239    try std.testing.expectError(error.MissingAliasBoundary, module.verify());240    module.boundaries.items[1].alias = .{ .boundary = .{ .value = 1 } };241    try module.verify();242    module.boundaries.items[1].ownership = .retained;243    try std.testing.expectError(error.OwnershipMismatch, module.verify());244    module.boundaries.items[1].ownership = .borrowed;245    module.boundaries.items[0].ownership = .produced;246    try std.testing.expectError(error.ProducedAliasTarget, module.verify());247    module.boundaries.items[0].ownership = .borrowed;248    module.boundaries.items[0].alias = .{ .boundary = .{ .value = 2 } };249    try std.testing.expectError(error.NonCanonicalBoundaryAlias, module.verify());250    module.boundaries.items[0].alias = .disjoint;251    module.boundaries.items[1].element_type = .i32;252    try std.testing.expectError(error.BoundaryAliasMismatch, module.verify());253    module.boundaries.items[1].element_type = .f32;254    try std.testing.expectError(error.OwnershipMismatch, module.addBoundary(.{255        .id = .{ .value = 3 },256        .name = "ownership_mismatch",257        .element_type = .f32,258        .dimensions = &.{2},259        .byte_size = 8,260        .access = .read,261        .ownership = .retained,262        .alias = .{ .boundary = .{ .value = 1 } },263        .provenance = .{ .path = "aliases.chic", .symbol = "ownership_mismatch", .line = 3 },264    }));265    try std.testing.expectError(error.NonCanonicalBoundaryAlias, module.addBoundary(.{266        .id = .{ .value = 3 },267        .name = "chain",268        .element_type = .f32,269        .dimensions = &.{2},270        .byte_size = 8,271        .access = .read,272        .ownership = .borrowed,273        .alias = .{ .boundary = .{ .value = 2 } },274        .provenance = .{ .path = "aliases.chic", .symbol = "chain", .line = 3 },275    }));276    try module.verify();277}278279test "partitioned module owns unique semantic product contracts" {280    const records = try fixture.Records.init(std.testing.allocator);281    defer records.deinit();282    var module = try PartitionedModule.init(std.testing.allocator, "products");283    defer module.deinit();284285    try std.testing.expectError(error.EmptyPartition, module.addPartition(.{286        .id = .{ .value = 1 },287        .name = "",288        .pipeline = .choir,289        .product = .{ .producer = "composition-fixture", .source = "1", .stage = "product", .variant = "default" },290        .effect = .unknown,291        .provenance = .{ .path = "products.chic", .symbol = "empty_name" },292    }));293    try std.testing.expectError(error.EmptyProvenance, module.addPartition(.{294        .id = .{ .value = 1 },295        .name = "empty_provenance",296        .pipeline = .choir,297        .product = .{ .producer = "composition-fixture", .source = "1", .stage = "product", .variant = "default" },298        .effect = .unknown,299        .provenance = .{ .path = "", .symbol = "" },300    }));301    try std.testing.expectError(error.EmptyProductRef, module.addPartition(.{302        .id = .{ .value = 1 },303        .name = "empty",304        .pipeline = .choir,305        .product = .{ .producer = "composition-fixture", .source = "1", .stage = "", .variant = "default" },306        .effect = .none,307        .provenance = .{ .path = "products.chic", .symbol = "empty" },308    }));309    var product_name = [_]u8{ 'p', 'r', 'o', 'd', 'u', 'c', 't' };310    try module.addPartition(.{311        .id = .{ .value = 1 },312        .name = "first",313        .pipeline = .choir,314        .product = .{ .producer = "composition-fixture", .source = "7", .stage = &product_name, .variant = "default" },315        .effect = .read,316        .provenance = .{ .path = "products.chic", .symbol = "first" },317    });318    product_name[0] = 'x';319    try std.testing.expectEqualStrings("product", module.partitions.items[0].product.stage);320    try std.testing.expectError(error.DuplicateProductRef, module.addPartition(.{321        .id = .{ .value = 2 },322        .name = "duplicate",323        .pipeline = .accy,324        .product = .{ .producer = "composition-fixture", .source = "7", .stage = "product", .variant = "default" },325        .effect = .none,326        .provenance = .{ .path = "products.chic", .symbol = "duplicate" },327    }));328    try std.testing.expectError(error.ProductIdentityMismatch, source.PipelineInput.init(329        &module,330        .{ .value = 1 },331        .choir,332        try records.key("other", "7", "11"),333    ));334    const input = try source.PipelineInput.init(335        &module,336        .{ .value = 1 },337        .choir,338        try records.key("product", "7", "11"),339    );340    try std.testing.expectEqual(source.Effect.read, module.partitions.items[0].effect);341    try std.testing.expectEqualStrings("11", input.product.record.view().image);342}

1pub const module = @import("module.zig");