comptime-API: strip the byte-weld; pivot to a flat-memory comptime VM
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
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user