lab/sx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

comptime-API: strip the byte-weld; pivot to a flat-memory comptime VM

Browse Source 
The byte-weld (sx structs whose layout was validated to mirror the
compiler's Zig records) plus the serialization/marshaling bridge was the
wrong direction: it bolted a parallel layout regime and hand-built
byte-copies onto a comptime value model that fundamentally isn't bytes.

Strip the struct-weld machinery:
- compiler_lib.zig loses the type registry (weldStruct / bound_types /
  BoundType / FieldLayout / findType / SxField / LayoutMismatch /
  validateStructLayout); it is now just the intern/text_of function
  host-call bridge (kept as the Phase-3 compiler-call seed).
- nominal.zig loses validateWeldedStruct / weldedFieldOrderStr + the
  sd.abi == .zig validation call.
- Remove the struct-weld unit tests and examples 0625/0627 (welded
  structs) + 1183/1186 (weld-layout diagnostics).
- The #library / abi / extern syntax stays.

Record the new direction: a bytecode VM over flat, byte-addressable
memory so comptime values are native bytes (no weld/validation/marshal),
target-aware (preserves cross-compilation) and sandboxed. See
current/PLAN-COMPILER-VM.md (Phase 0 strip -> Phase 1 flat-memory value
model -> Phase 2 bytecode -> Phase 3 compiler-API on flat memory).
design/comptime-compiler-api.md gets a SUPERSEDED banner. Also drop the
"~500 lines / split the step" rule from CLAUDE.md.
This commit is contained in:
agra
2026-06-17 19:29:36 +03:00
parent 40d075ca98
commit 18af8eb845
23 changed files with 505 additions and 498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
src/ir/compiler_lib.test.zig
View File

@@ -1,139 +1,11 @@
// Tests for the comptime `compiler` library's binding registry.
// Tests for the comptime `compiler` library's function bridge.
const std = @import("std");
const compiler_lib = @import("compiler_lib.zig");
const types = @import("types.zig");
// Lock: `findType("Field")` resolves to the welded `StructInfo.Field` type, and
// its baked layout EQUALS the real Zig type's `@sizeOf`/`@alignOf`/`@offsetOf`.
// This is the foundation the layout sub-step builds on — the welded record's
// offsets come from the implementation, so they can't drift.
test "compiler_lib: Field welds to StructInfo.Field's real layout" {
const FieldZig = types.TypeInfo.StructInfo.Field;
const bt = compiler_lib.findType("Field") orelse return error.MissingBoundType;
try std.testing.expectEqualStrings("Field", bt.sx_name);
try std.testing.expectEqual(@sizeOf(FieldZig), bt.size);
try std.testing.expectEqual(@alignOf(FieldZig), bt.alignment);
// Two u32 fields, in declaration order.
try std.testing.expectEqual(@as(usize, 2), bt.fields.len);
try std.testing.expectEqualStrings("name", bt.fields[0].name);
try std.testing.expectEqual(@offsetOf(FieldZig, "name"), bt.fields[0].offset);
try std.testing.expectEqual(@as(usize, 4), bt.fields[0].size);
try std.testing.expectEqualStrings("ty", bt.fields[1].name);
try std.testing.expectEqual(@offsetOf(FieldZig, "ty"), bt.fields[1].offset);
try std.testing.expectEqual(@as(usize, 4), bt.fields[1].size);
// Sanity: the concrete shape the design calls out — two u32s, 8 bytes.
try std.testing.expectEqual(@as(usize, 8), bt.size);
try std.testing.expectEqual(@as(usize, 0), bt.fields[0].offset);
try std.testing.expectEqual(@as(usize, 4), bt.fields[1].offset);
}
// Lock: a name NOT on the export list is unreachable — `findType` returns null
// (the safety boundary; the welded-decl path falls through to a clean error,
// never a silent default).
test "compiler_lib: unexported name returns null" {
try std.testing.expect(compiler_lib.findType("NotExported") == null);
try std.testing.expect(compiler_lib.findType("") == null);
}
// Lock: a faithful sx header for `Field` validates clean (the natural two-u32
// layout matches the welded type).
test "compiler_lib: validateStructLayout accepts a faithful Field header" {
const bt = compiler_lib.findType("Field").?;
const sx = [_]compiler_lib.SxField{
.{ .name = "name", .size = 4 },
.{ .name = "ty", .size = 4 },
};
try std.testing.expect(compiler_lib.validateStructLayout(bt, &sx, 8) == null);
}
// Lock: every drift the assertion is meant to catch surfaces as the right
// `LayoutMismatch` variant (field count / name / size / total), and the first
// mismatch wins.
test "compiler_lib: validateStructLayout flags each kind of drift" {
const bt = compiler_lib.findType("Field").?;
// Wrong field count (one field instead of two).
{
const sx = [_]compiler_lib.SxField{.{ .name = "name", .size = 4 }};
const m = compiler_lib.validateStructLayout(bt, &sx, 4).?;
try std.testing.expect(m == .field_count);
try std.testing.expectEqual(@as(usize, 2), m.field_count.expected);
try std.testing.expectEqual(@as(usize, 1), m.field_count.got);
}
// Wrong field name (reorder / rename) at index 1.
{
const sx = [_]compiler_lib.SxField{
.{ .name = "name", .size = 4 },
.{ .name = "kind", .size = 4 },
};
const m = compiler_lib.validateStructLayout(bt, &sx, 8).?;
try std.testing.expect(m == .field_name);
try std.testing.expectEqual(@as(usize, 1), m.field_name.index);
try std.testing.expectEqualStrings("ty", m.field_name.expected);
try std.testing.expectEqualStrings("kind", m.field_name.got);
}
// Wrong field size (retype to an 8-byte field).
{
const sx = [_]compiler_lib.SxField{
.{ .name = "name", .size = 4 },
.{ .name = "ty", .size = 8 },
};
const m = compiler_lib.validateStructLayout(bt, &sx, 12).?;
try std.testing.expect(m == .field_size);
try std.testing.expectEqual(@as(usize, 1), m.field_size.index);
try std.testing.expectEqual(@as(usize, 4), m.field_size.expected);
try std.testing.expectEqual(@as(usize, 8), m.field_size.got);
}
// Right fields, wrong total (padding drift).
{
const sx = [_]compiler_lib.SxField{
.{ .name = "name", .size = 4 },
.{ .name = "ty", .size = 4 },
};
const m = compiler_lib.validateStructLayout(bt, &sx, 16).?;
try std.testing.expect(m == .total_size);
try std.testing.expectEqual(@as(usize, 8), m.total_size.expected);
try std.testing.expectEqual(@as(usize, 16), m.total_size.got);
}
}
// Lock: `StructInfo` is reflected in MEMORY order — Zig reorders it from source
// order (name, fields, is_protocol, nominal_id) to (fields@0, name@16,
// nominal_id@20, is_protocol@24). The registry must present the fields in that
// memory order, since an sx welded header must declare them so to be
// byte-identical.
test "compiler_lib: StructInfo is reflected in Zig memory order" {
const StructInfoZig = types.TypeInfo.StructInfo;
const bt = compiler_lib.findType("StructInfo").?;
try std.testing.expectEqual(@sizeOf(StructInfoZig), bt.size);
try std.testing.expectEqual(@as(usize, 4), bt.fields.len);
// Memory order: fields, name, nominal_id, is_protocol.
try std.testing.expectEqualStrings("fields", bt.fields[0].name);
try std.testing.expectEqual(@offsetOf(StructInfoZig, "fields"), bt.fields[0].offset);
try std.testing.expectEqualStrings("name", bt.fields[1].name);
try std.testing.expectEqual(@offsetOf(StructInfoZig, "name"), bt.fields[1].offset);
try std.testing.expectEqualStrings("nominal_id", bt.fields[2].name);
try std.testing.expectEqual(@offsetOf(StructInfoZig, "nominal_id"), bt.fields[2].offset);
try std.testing.expectEqualStrings("is_protocol", bt.fields[3].name);
try std.testing.expectEqual(@offsetOf(StructInfoZig, "is_protocol"), bt.fields[3].offset);
// Offsets are strictly ascending (memory order).
try std.testing.expect(bt.fields[0].offset < bt.fields[1].offset);
try std.testing.expect(bt.fields[1].offset < bt.fields[2].offset);
try std.testing.expect(bt.fields[2].offset < bt.fields[3].offset);
}
// Lock: the welded-function export list resolves the round-trip readers and
// rejects unexported names (the boundary the interp's dispatch consults).
// Lock: the compiler-function export list resolves the round-trip readers and
// rejects unexported names (the boundary `weldedCompilerFn` + the interp's
// dispatch consult).
test "compiler_lib: findFn resolves exported functions, rejects others" {
try std.testing.expect(compiler_lib.findFn("intern") != null);
try std.testing.expect(compiler_lib.findFn("text_of") != null);

170
src/ir/compiler_lib.zig
View File

@@ -1,21 +1,20 @@
//! The comptime `compiler` library's binding registry — the curated surface of
//! the compiler's own types (layout-welded) and functions (host-call bridged)
//! reachable from comptime sx via `abi(.zig) extern compiler`. See
//! `design/comptime-compiler-api.md`.
//! The comptime `compiler` library's function bridge — the curated set of the
//! compiler's own functions reachable from comptime sx via
//! `abi(.zig) extern compiler`. See `current/PLAN-COMPILER-VM.md`.
//!
//! **This registry IS the safety boundary.** Only the entries registered here
//! are bindable from user comptime code; anything not on the export list is
//! unreachable. A welded `Name :: struct abi(.zig) extern compiler { … }` (or a
//! welded fn) resolves its layout/dispatch against this table, not the ordinary
//! extern-lib path.
//! **This registry IS the safety boundary.** Only the functions registered here
//! are bindable from user comptime code; a name not on the export list is
//! rejected at declaration (`weldedCompilerFn`), and the interpreter dispatches a
//! welded call to the matching Zig handler instead of dlsym.
//!
//! **Layout is welded, not guessed.** Because the sx compiler is itself a Zig
//! program, the real internal type's layout is available at compiler-build time:
//! each `BoundType` bakes `@sizeOf`/`@alignOf`/`@offsetOf` from the bound Zig
//! type. A `types.zig` change re-bakes the offsets on the next build, so both
//! sides move together. The sx-side `struct abi(.zig) …` declaration is then a
//! *header* checked against these offsets (the build-time layout-equality
//! assertion lands in the layout sub-step).
//! **Direction note (2026-06-17 pivot).** The byte-weld of TYPES (sx structs whose
//! layout was validated to mirror the compiler's Zig records) was stripped — it
//! bolted a parallel layout regime + hand-marshaling onto a comptime value model
//! that isn't bytes. The replacement is a flat-memory comptime VM where values are
//! native bytes, so the compiler-API needs no weld/validation/marshaling (Phase 3
//! of the plan re-homes the type/function exposure on that VM). `intern`/`text_of`
//! survive here as the first compiler-call seed: clean scalar host-calls (string in,
//! handle out), no weld involved.
const std = @import("std");
const types = @import("types.zig");
@@ -25,135 +24,10 @@ const Interpreter = interp_mod.Interpreter;
const InterpError = interp_mod.InterpError;
const StringId = types.StringId;
/// One field of a welded type: its sx-visible name plus the byte offset + size
/// taken from the bound Zig type.
pub const FieldLayout = struct {
name: []const u8,
offset: usize,
size: usize,
};
/// A type exported by the `compiler` library, welded to a real internal Zig
/// type. `size`/`alignment`/`fields` are baked from that Zig type at
/// compiler-build time (so they cannot drift from the implementation).
pub const BoundType = struct {
/// The sx-side name a welded `struct abi(.zig) extern compiler` uses.
sx_name: []const u8,
size: usize,
alignment: usize,
fields: []const FieldLayout,
};
/// The real internal Zig type each welded export binds to. Kept as named
/// aliases so the binding sites read as a curated list.
const FieldZig = types.TypeInfo.StructInfo.Field; // { name: StringId, ty: TypeId } — two u32s
const StructInfoZig = types.TypeInfo.StructInfo; // { name, fields: []Field, is_protocol, nominal_id } — Zig-reordered
/// Bake a `BoundType` by REFLECTING the real Zig struct type `T` — field names
/// from `@typeInfo`, offsets from `@offsetOf`, sizes from `@sizeOf`. Nothing is
/// maintained by hand: a `types.zig` change re-bakes on the next compiler build.
/// Fields are returned in ascending-OFFSET (memory) order, which is the order an
/// sx welded header must declare them in to be byte-identical (Zig may reorder a
/// struct's fields from source order). The sx-visible field name IS the Zig
/// field identifier.
fn weldStruct(comptime sx_name: []const u8, comptime T: type) BoundType {
const zig_fields = @typeInfo(T).@"struct".fields;
comptime var layouts: [zig_fields.len]FieldLayout = undefined;
inline for (zig_fields, 0..) |zf, i| {
layouts[i] = .{
.name = zf.name,
.offset = @offsetOf(T, zf.name),
.size = @sizeOf(zf.type),
};
}
// Sort into memory order so the sx header is checked against the layout the
// compiler actually uses (declaration order != memory order under Zig's
// auto-layout).
comptime std.sort.insertion(FieldLayout, &layouts, {}, struct {
fn lt(_: void, a: FieldLayout, b: FieldLayout) bool {
return a.offset < b.offset;
}
}.lt);
const frozen = layouts;
return .{
.sx_name = sx_name,
.size = @sizeOf(T),
.alignment = @alignOf(T),
.fields = &frozen,
};
}
/// The welded-type export list. Each entry reflects a real internal Zig type;
/// the sx header that binds it must mirror these fields IN THIS (memory) ORDER.
/// `Field` (two u32s) is naturally ordered; `StructInfo` is Zig-reordered
/// (`fields`@0, `name`@16, `nominal_id`@20, `is_protocol`@24).
pub const bound_types = [_]BoundType{
weldStruct("Field", FieldZig),
weldStruct("StructInfo", StructInfoZig),
};
/// Look up a welded type by its sx name. Returns null when the name is not on
/// the `compiler` library's export list (the lookup the welded-decl resolution
/// path consults instead of the ordinary extern-lib path).
pub fn findType(sx_name: []const u8) ?*const BoundType {
for (&bound_types) |*bt| {
if (std.mem.eql(u8, bt.sx_name, sx_name)) return bt;
}
return null;
}
/// The name of the only welded library. A `struct abi(.zig) extern <lib>` with a
/// different `<lib>` is rejected — `compiler` is the sole comptime weld source.
/// The name of the only compiler library. A `fn abi(.zig) extern <lib>` with a
/// different `<lib>` is rejected — `compiler` is the sole comptime bind source.
pub const lib_name = "compiler";
/// One field of an sx welded-struct declaration, as the lowering observed it:
/// the field's sx name plus the size the sx type system computed for its type.
pub const SxField = struct {
name: []const u8,
size: usize,
};
/// The first way an sx welded-struct declaration fails to faithfully mirror the
/// bound Zig type. The sx declaration is a *header* checked against the real
/// implementation, so any drift is a build error rather than a silent
/// reinterpretation. The caller renders the chosen variant into a diagnostic.
pub const LayoutMismatch = union(enum) {
/// The sx declaration has a different field count than the welded type.
field_count: struct { expected: usize, got: usize },
/// Field `index` carries the wrong sx name (a weld is positional + by-name).
field_name: struct { index: usize, expected: []const u8, got: []const u8 },
/// Field `index` (`name`) is a different size than the welded type's field.
field_size: struct { index: usize, name: []const u8, expected: usize, got: usize },
/// The total struct size differs (padding / alignment drift).
total_size: struct { expected: usize, got: usize },
};
/// Check an sx welded-struct declaration against the bound Zig type. Returns the
/// FIRST mismatch, or null if the sx declaration is a faithful header. Fields are
/// checked positionally + by name + by size, and the total size is compared — for
/// a natural (C-like) layout this catches a missing/extra field (count), a rename
/// or reorder (name), a retype (size), and padding drift (total). Explicit
/// per-field OFFSET overrides (for non-natural Zig layouts — slices, reordered or
/// `union(enum)` fields) arrive with `StructInfo` in Phase 2; `Field`'s two-u32
/// natural layout needs none.
pub fn validateStructLayout(
bt: *const BoundType,
sx_fields: []const SxField,
sx_total_size: usize,
) ?LayoutMismatch {
if (sx_fields.len != bt.fields.len)
return .{ .field_count = .{ .expected = bt.fields.len, .got = sx_fields.len } };
for (sx_fields, bt.fields, 0..) |sf, bf, i| {
if (!std.mem.eql(u8, sf.name, bf.name))
return .{ .field_name = .{ .index = i, .expected = bf.name, .got = sf.name } };
if (sf.size != bf.size)
return .{ .field_size = .{ .index = i, .name = bf.name, .expected = bf.size, .got = sf.size } };
}
if (sx_total_size != bt.size)
return .{ .total_size = .{ .expected = bt.size, .got = sx_total_size } };
return null;
}
// ── Functions (comptime-only, host-call bridged) ────────────────────────────
/// A welded `compiler` function: dispatched under the comptime interpreter to its
@@ -167,16 +41,16 @@ pub const BoundFn = struct {
handler: FnHandler,
};
/// The welded-function export list. Start small (Phase 1): the `StringId`
/// round-trip readers. `find_type` / the guarded `register_*` mutators join in
/// later phases.
/// The compiler-function export list. The `StringId` round-trip readers are the
/// seed; the type-table API (lookup / register) is re-homed onto the flat-memory
/// VM in Phase 3 of `PLAN-COMPILER-VM.md`.
pub const bound_fns = [_]BoundFn{
.{ .sx_name = "intern", .handler = handleIntern },
.{ .sx_name = "text_of", .handler = handleTextOf },
};
/// Look up a welded function by its sx name. Returns null when the name is not on
/// the `compiler` library's function-export list.
/// Look up a compiler function by its sx name. Returns null when the name is not
/// on the export list.
pub fn findFn(sx_name: []const u8) ?*const BoundFn {
for (&bound_fns) |*bf| {
if (std.mem.eql(u8, bf.sx_name, sx_name)) return bf;

80
src/ir/lower/nominal.zig
View File

@@ -6,7 +6,6 @@ const mod_mod = @import("../module.zig");
const type_bridge = @import("../type_bridge.zig");
const program_index_mod = @import("../program_index.zig");
const resolver_mod = @import("../resolver.zig");
const compiler_lib = @import("../compiler_lib.zig");
const StructTemplate = program_index_mod.StructTemplate;
const TemplateParam = program_index_mod.TemplateParam;
@@ -674,13 +673,7 @@ pub fn registerStructDecl(self: *Lowering, sd: *const ast.StructDecl, source_fil
// any forward-reference stub. Same-name structs in DIFFERENT sources get
// distinct TypeIds instead of last-wins clobbering the first.
const info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items } };
const struct_tid = self.internNamedTypeDecl(decl_key, name_id, info, nominal_id);
// Welded `struct abi(.zig) extern compiler { … }`: the sx declaration is a
// header checked against the compiler's real Zig type — validate the layout
// matches the binding registry (a mismatch is a build error). See
// design/comptime-compiler-api.md.
if (sd.abi == .zig) validateWeldedStruct(self, sd, struct_tid, fields.items);
_ = self.internNamedTypeDecl(decl_key, name_id, info, nominal_id);
// Store field defaults for struct literal lowering
if (sd.field_defaults.len > 0) {
@@ -716,77 +709,6 @@ pub fn registerStructDecl(self: *Lowering, sd: *const ast.StructDecl, source_fil
}
}
/// Validate a welded `struct abi(.zig) extern <lib> { … }` against the `compiler`
/// library's binding registry: the bound library must be `compiler`, the name
/// must be on the export list, and the sx-declared layout must match the real Zig
/// type's (the sx side is a *header* checked against the implementation). Any
/// failure is a build-gating `.err` diagnostic — never a silent reinterpretation.
fn validateWeldedStruct(self: *Lowering, sd: *const ast.StructDecl, tid: TypeId, fields: []const types.TypeInfo.StructInfo.Field) void {
const diags = self.diagnostics orelse return;
const table = &self.module.types;
// A span that points into the struct (its first field, else zero) — the decl
// has no name span of its own.
const span: ast.Span = if (sd.field_types.len > 0) sd.field_types[0].span else .{ .start = 0, .end = 0 };
// The bound library must be the sole welded source.
if (sd.extern_lib == null or !std.mem.eql(u8, sd.extern_lib.?, compiler_lib.lib_name)) {
diags.addFmt(.err, span, "abi(.zig) struct '{s}' must bind the compiler library — write `extern {s}`", .{ sd.name, compiler_lib.lib_name });
return;
}
// The name must be on the curated export list (the safety boundary).
const bt = compiler_lib.findType(sd.name) orelse {
diags.addFmt(.err, span, "'{s}' is not a type exported by the '{s}' library", .{ sd.name, compiler_lib.lib_name });
return;
};
// Build the observed sx layout (field name + computed size) and total size.
var sx_fields = std.ArrayList(compiler_lib.SxField).empty;
defer sx_fields.deinit(self.alloc);
for (fields) |f| {
sx_fields.append(self.alloc, .{
.name = table.getString(f.name),
.size = table.typeSizeBytes(f.ty),
}) catch return;
}
const total = table.typeSizeBytes(tid);
const mismatch = compiler_lib.validateStructLayout(bt, sx_fields.items, total) orelse return;
// The compiler type's fields, in the memory order an sx header must mirror —
// included in the order/count diagnostics so the fix is obvious.
const order = weldedFieldOrderStr(self.alloc, bt);
defer if (order.len > 0) self.alloc.free(order);
switch (mismatch) {
.field_count => |m| diags.addFmt(.err, span, "welded type '{s}': the compiler type has {d} field(s) but the declaration has {d} — declare them in memory order: {s}", .{ sd.name, m.expected, m.got, order }),
.field_name => |m| {
// Distinguish "this name isn't a field at all" from "right field set,
// wrong order".
const exists = blk: {
for (bt.fields) |bf| if (std.mem.eql(u8, bf.name, m.got)) break :blk true;
break :blk false;
};
if (exists)
diags.addFmt(.err, span, "welded type '{s}': wrong field order at position {d} — found '{s}', the compiler type has '{s}' here (memory order: {s})", .{ sd.name, m.index, m.got, m.expected, order })
else
diags.addFmt(.err, span, "welded type '{s}': field '{s}' is not a field of the compiler type (its fields, in memory order: {s})", .{ sd.name, m.got, order });
},
.field_size => |m| diags.addFmt(.err, span, "welded type '{s}': type layout mismatch — field '{s}' is {d} byte(s) in the compiler type but {d} as declared", .{ sd.name, m.name, m.expected, m.got }),
.total_size => |m| diags.addFmt(.err, span, "welded type '{s}': layout mismatch — the compiler type is {d} byte(s) but the declaration is {d} (alignment/padding)", .{ sd.name, m.expected, m.got }),
}
}
/// The bound type's field names in memory order, `, `-joined, for diagnostics.
/// Returns an owned string; empty (no free needed) on allocation failure.
fn weldedFieldOrderStr(alloc: std.mem.Allocator, bt: *const compiler_lib.BoundType) []const u8 {
var buf = std.ArrayList(u8).empty;
for (bt.fields, 0..) |bf, i| {
if (i > 0) buf.appendSlice(alloc, ", ") catch return "";
buf.appendSlice(alloc, bf.name) catch return "";
}
return buf.toOwnedSlice(alloc) catch "";
}
/// Register a top-level ENUM decl under a per-decl nominal identity (E6a) —
/// the enum twin of `registerStructDecl`. A GENUINE same-name shadow already
/// reserved its DISTINCT slot up-front in `scanDecls` (the first at id 0, the