stage1 重构代码 语法上重新实现解包语法

- 实现 as 类型转换运算符、修复 &&/|| 短路求值 bug。
- 在 splc1.spl 中实现 Vec/Map/Emit 基础库（~50 个方法）。
- 修复实例方法调用中 self 参数被错误丢弃的 bug。

.gitignore

@@ -2,3 +2,12 @@
 !.gitignore
 
 build/
+
+*.sir
+
+*.o
+*.obj
+
+*.old
+*.exe
+*.out

gramma.pest

@@ -0,0 +1,427 @@
+Root             = { SOI ~ ContainerMembers ~ EOI }
+ContainerMembers = { ExternalHeaderList ~ (ContainerDeclaration ~ (COMMA | SEMICOLON)*)* }
+
+HeaderItem         = { (AT | SHARP) ~ IDENTIFIER ~ (LPAREN ~ ExprList? ~ RPAREN)? }
+HeaderList         = { HeaderItem* }
+DeclHeader         = { HeaderList? ~ KEYWORD_pub? }
+ExternalHeaderItem = { (AT | SHARP) ~ BANG ~ IDENTIFIER ~ (LPAREN ~ ExprList? ~ RPAREN)? }
+ExternalHeaderList = { ExternalHeaderItem* }
+
+BindingIdent = { IDENTIFIER | UNDERSCORE }
+
+ContainerDeclaration = {
+    FnDecl
+  | VarDecl
+  | ConstDecl
+  | TypeDecl
+  | MemberDecl
+  | ComptimeDecl
+  | HeaderList ~ Block
+}
+
+ComptimeDecl = { KEYWORD_comptime ~ (Block | Expr) }
+
+FnDecl = {
+    DeclHeader ~ KEYWORD_comptime? ~ KEYWORD_fn ~ IDENTIFIER ~ LPAREN ~ ParamDeclList ~ RPAREN ~ (COLON ~ TypeExpr)? ~ (SEMICOLON | Block)
+}
+
+ParamDeclList = { (ParamDecl ~ COMMA)* ~ (ParamDecl | DOT3)? }
+ParamDecl     = { HeaderList? ~ BindingIdent ~ COLON ~ TypeExpr }
+
+VarDecl   = { DeclHeader ~ KEYWORD_var ~ VarBody }
+ConstDecl = { DeclHeader ~ KEYWORD_const ~ VarBody }
+VarBody   = { Pattern ~ (COLON ~ TypeExpr)? ~ (EQUAL ~ Expr)? }
+
+TypeDecl = { DeclHeader ~ KEYWORD_type ~ IDENTIFIER ~ EQUAL ~ TypeExpr }
+
+MemberDecl = { DeclHeader ~ IDENTIFIER ~ (COLON ~ TypeExpr)? ~ (EQUAL ~ Expr)? }
+
+Pattern     = { PatternAtom ~ (COMMA ~ PatternAtom)* }
+PatternAtom = {
+    UNDERSCORE
+  | AnonymousAggregatePattern
+  | DOT ~ IDENTIFIER ~ (LPAREN ~ Pattern? ~ RPAREN)?
+  | LPAREN ~ Pattern? ~ RPAREN
+  | PatternLiteral
+  | IDENTIFIER
+}
+
+AnonymousAggregatePattern = { DOT ~ LBRACE ~ PatternFieldList? ~ RBRACE }
+PatternFieldList          = { PatternField ~ ((COMMA | SEMICOLON) ~ PatternField)* ~ (COMMA | SEMICOLON)? }
+PatternField              = { DOT ~ IDENTIFIER ~ (EQUAL ~ PatternAtom)? }
+
+PatternLiteral = {
+    FLOAT_LITERAL
+  | INTEGER_LITERAL
+  | CHAR_LITERAL
+  | STRING_LITERAL
+  | KEYWORD_true
+  | KEYWORD_false
+  | KEYWORD_null
+}
+
+Block     = { LBRACE ~ Statement* ~ Expr? ~ RBRACE }
+Statement = {
+    RetStatement
+  | BreakStatement
+  | ContinueStatement
+  | DeferStatement
+  | DeclStatement
+  | ExprStatement
+  | ComptimeStatement
+}
+
+DeclStatement     = { (VarDecl | ConstDecl | TypeDecl) ~ (COMMA | SEMICOLON)? }
+ExprStatement     = { Expr ~ (COMMA | SEMICOLON)? }
+ComptimeStatement = { ComptimeDecl ~ (COMMA | SEMICOLON)? }
+
+RetStatement      = { KEYWORD_ret ~ Expr? ~ (COMMA | SEMICOLON)? }
+BreakStatement    = { KEYWORD_break ~ Label? ~ Expr? ~ (COMMA | SEMICOLON)? }
+ContinueStatement = { KEYWORD_continue ~ Label? ~ (COMMA | SEMICOLON)? }
+DeferStatement    = { KEYWORD_defer ~ (Block | Statement) ~ (COMMA | SEMICOLON)? }
+
+Label = { DOLLAR ~ IDENTIFIER }
+
+Expr = { AssignExpr }
+
+AssignExpr  = { BoolOrExpr ~ (AssignOp ~ AssignExpr)? }
+BoolOrExpr  = { BoolAndExpr ~ (BOOL_OR ~ BoolAndExpr)* }
+BoolAndExpr = { BitOrExpr ~ (BOOL_AND ~ BitOrExpr)* }
+BitOrExpr   = { BitXorExpr ~ (PIPE ~ BitXorExpr)* }
+BitXorExpr  = { BitAndExpr ~ (CARET ~ BitAndExpr)* }
+BitAndExpr  = { CmpEqExpr ~ (AMPERSAND ~ CmpEqExpr)* }
+CmpEqExpr   = { CmpExpr ~ ((EQ_EQ | BANG_EQUAL) ~ CmpExpr)* }
+CmpExpr     = { ArrowExpr ~ ((L_ARROW_EQ | L_ARROW | R_ARROW_EQ | R_ARROW) ~ ArrowExpr)* }
+
+ArrowExpr = { RangeExpr ~ ((THIN_R_ARROW | THIN_L_ARROW | FAT_D_ARROW | THIN_D_ARROW) ~ RangeExpr)* }
+
+RangeExpr  = { ShiftExpr ~ (DOT2 ~ ShiftExpr?)? }
+ShiftExpr  = { AddExpr ~ ((L_ARROW2_EQ | L_ARROW2 | R_ARROW2_EQ | R_ARROW2) ~ AddExpr)* }
+AddExpr    = { MulExpr ~ ((PLUS | MINUS) ~ MulExpr)* }
+MulExpr    = { CastExpr ~ ((ASTERISK | SLASH | PERCENT) ~ CastExpr)* }
+CastExpr   = { PrefixExpr ~ (KEYWORD_as ~ TypeExpr)* }
+PrefixExpr = { PrefixOp* ~ PostfixExpr }
+PrefixOp   = { MINUS | BANG | TILDE | AMPERSAND }
+
+PostfixExpr = {
+    PrimaryExpr ~ (LPAREN ~ ExprList ~ RPAREN | DOT ~ IDENTIFIER | DOT ~ ASTERISK | LBRACKET ~ Expr ~ RBRACKET | LBRACKET ~ Expr ~ DOT2 ~ Expr? ~ RBRACKET)*
+}
+
+ExprList = { (Expr ~ COMMA)* ~ Expr? }
+
+PrimaryExpr = {
+    FLOAT_LITERAL
+  | INTEGER_LITERAL
+  | CHAR_LITERAL
+  | STRING_LITERAL
+  | KEYWORD_true
+  | KEYWORD_false
+  | KEYWORD_null
+  | TupleLiteral
+  | AggregateLiteral
+  | AnonymousAggregateLiteral
+  | ArrayLiteral
+  | AnonymousArrayLiteral
+  | VariantConstruct
+  | ComptimeCallExpr
+  | IDENTIFIER
+  | Block
+  | IfExpr
+  | IfVarExpr
+  | WhileExpr
+  | LoopExpr
+  | ForExpr
+  | MatchExpr
+  | FnTypeExpr
+}
+
+TupleLiteral = { ParenExpr }
+
+AggregateLiteral          = { IDENTIFIER ~ LBRACE ~ StructInitList? ~ RBRACE }
+AnonymousAggregateLiteral = { DOT ~ LBRACE ~ StructInitList? ~ RBRACE }
+
+StructInitList = { StructInit ~ ((COMMA | SEMICOLON) ~ StructInit)* ~ (COMMA | SEMICOLON)? }
+StructInit     = { DOT ~ IDENTIFIER ~ (EQUAL ~ Expr)? }
+
+VariantConstruct = { DOT ~ IDENTIFIER ~ (LPAREN ~ ExprList? ~ RPAREN)? }
+
+ArrayLiteral = {
+    LBRACKET ~ RBRACKET ~ TypeExpr ~ LBRACKET ~ ExprList? ~ RBRACKET
+  | LBRACKET ~ (INTEGER_LITERAL | UNDERSCORE) ~ RBRACKET ~ TypeExpr ~ LBRACKET ~ ExprList? ~ RBRACKET
+}
+
+AnonymousArrayLiteral = {
+    DOT ~ LBRACKET ~ ExprList? ~ RBRACKET
+}
+
+ExprNoStruct = { AssignExprNoStruct }
+
+AssignExprNoStruct  = { BoolOrExprNoStruct ~ (AssignOp ~ AssignExprNoStruct)? }
+BoolOrExprNoStruct  = { BoolAndExprNoStruct ~ (BOOL_OR ~ BoolAndExprNoStruct)* }
+BoolAndExprNoStruct = { BitOrExprNoStruct ~ (BOOL_AND ~ BitOrExprNoStruct)* }
+BitOrExprNoStruct   = { BitXorExprNoStruct ~ (PIPE ~ BitXorExprNoStruct)* }
+BitXorExprNoStruct  = { BitAndExprNoStruct ~ (CARET ~ BitAndExprNoStruct)* }
+BitAndExprNoStruct  = { CmpEqExprNoStruct ~ (AMPERSAND ~ CmpEqExprNoStruct)* }
+CmpEqExprNoStruct   = { CmpExprNoStruct ~ ((EQ_EQ | BANG_EQUAL) ~ CmpExprNoStruct)* }
+CmpExprNoStruct     = { ArrowExprNoStruct ~ ((L_ARROW_EQ | L_ARROW | R_ARROW_EQ | R_ARROW) ~ ArrowExprNoStruct)* }
+
+ArrowExprNoStruct = { RangeExprNoStruct ~ ((THIN_R_ARROW | THIN_L_ARROW | FAT_D_ARROW | THIN_D_ARROW) ~ RangeExprNoStruct)* }
+
+RangeExprNoStruct  = { ShiftExprNoStruct ~ (DOT2 ~ ShiftExprNoStruct?)? }
+ShiftExprNoStruct  = { AddExprNoStruct ~ ((L_ARROW2_EQ | L_ARROW2 | R_ARROW2_EQ | R_ARROW2) ~ AddExprNoStruct)* }
+AddExprNoStruct    = { MulExprNoStruct ~ ((PLUS | MINUS) ~ MulExprNoStruct)* }
+MulExprNoStruct    = { CastExprNoStruct ~ ((ASTERISK | SLASH | PERCENT) ~ CastExprNoStruct)* }
+CastExprNoStruct   = { PrefixExprNoStruct ~ (KEYWORD_as ~ TypeExpr)* }
+PrefixExprNoStruct = { PrefixOp* ~ PostfixExprNoStruct }
+
+PostfixExprNoStruct = {
+    PrimaryExprNoStruct ~ (LPAREN ~ ExprList ~ RPAREN | DOT ~ IDENTIFIER | DOT ~ ASTERISK | LBRACKET ~ Expr ~ RBRACKET | LBRACKET ~ Expr ~ DOT2 ~ Expr? ~ RBRACKET)*
+}
+
+PrimaryExprNoStruct = {
+    FLOAT_LITERAL
+  | INTEGER_LITERAL
+  | CHAR_LITERAL
+  | STRING_LITERAL
+  | KEYWORD_true
+  | KEYWORD_false
+  | KEYWORD_null
+  | TupleLiteral
+  | AnonymousAggregateLiteral
+  | ArrayLiteral
+  | AnonymousArrayLiteral
+  | VariantConstruct
+  | ComptimeCallExpr
+  | IDENTIFIER
+  | Block
+  | IfExpr
+  | IfVarExpr
+  | WhileExpr
+  | LoopExpr
+  | ForExpr
+  | MatchExpr
+  | FnTypeExpr
+}
+
+VarBodyNoStruct = { Pattern ~ (COLON ~ TypeExpr)? ~ (EQUAL ~ ExprNoStruct)? }
+
+TypeExpr = { HeaderList? ~ TypePrefixExpr }
+
+TypePrefixExpr = { ASTERISK* ~ TypePostfixExpr }
+
+TypePostfixExpr = {
+    TypePrimary ~ (LPAREN ~ TypeExprList ~ RPAREN | DOT ~ IDENTIFIER | LBRACKET ~ TypeExpr ~ RBRACKET | KEYWORD_as ~ TypeExpr)*
+}
+
+TypePrimary = {
+    IDENTIFIER
+  | KEYWORD_i8
+  | KEYWORD_u8
+  | KEYWORD_i16
+  | KEYWORD_u16
+  | KEYWORD_i32
+  | KEYWORD_u32
+  | KEYWORD_i64
+  | KEYWORD_u64
+  | KEYWORD_f32
+  | KEYWORD_f64
+  | KEYWORD_isize
+  | KEYWORD_usize
+  | KEYWORD_bool
+  | KEYWORD_void
+  | KEYWORD_ptr
+  | FnTypeExpr
+  | AggregateTypeExpr
+  | TypeParenExpr
+  | ArrayTypeExpr
+}
+
+ArrayTypeExpr = {
+    LBRACKET ~ RBRACKET ~ TypeExpr
+  | LBRACKET ~ (INTEGER_LITERAL | UNDERSCORE) ~ RBRACKET ~ TypeExpr
+}
+
+TypeParenExpr = {
+    LPAREN ~ RPAREN
+  | LPAREN ~ TypeExpr ~ COMMA ~ (TypeExpr ~ COMMA)* ~ TypeExpr? ~ RPAREN
+  | LPAREN ~ TypeExpr ~ RPAREN
+}
+
+TypeExprList = { (TypeExpr ~ COMMA)* ~ TypeExpr? }
+
+FnTypeExpr = { KEYWORD_comptime? ~ KEYWORD_fn ~ LPAREN ~ TypeExprList? ~ RPAREN ~ (COLON ~ TypeExpr)? }
+
+AggregateTypeExpr = { (KEYWORD_struct | KEYWORD_union | KEYWORD_enum | KEYWORD_shape) ~ LBRACE ~ ContainerMembers ~ RBRACE }
+
+IfExpr    = { KEYWORD_if ~ ExprNoStruct ~ Block ~ (KEYWORD_else ~ (Block | IfExpr | IfVarExpr))? }
+IfVarExpr = { KEYWORD_if ~ KEYWORD_var ~ VarBodyNoStruct ~ Block ~ (KEYWORD_else ~ (Block | IfExpr | IfVarExpr))? }
+
+WhileExpr = { Label? ~ KEYWORD_while ~ ExprNoStruct ~ Block ~ (KEYWORD_else ~ (Block | Expr))? }
+LoopExpr  = { Label? ~ KEYWORD_loop ~ Block }
+ForExpr   = { Label? ~ KEYWORD_for ~ Pattern ~ COLON ~ ExprNoStruct ~ (COMMA ~ ExprNoStruct)* ~ Block ~ (KEYWORD_else ~ (Block | Expr))? }
+
+MatchExpr = { KEYWORD_match ~ ExprNoStruct ~ LBRACE ~ MatchArm* ~ RBRACE }
+MatchArm  = { Pattern ~ FAT_R_ARROW ~ Block ~ COMMA? }
+
+ComptimeCallExpr = { AT ~ IDENTIFIER ~ LPAREN ~ ExprList? ~ RPAREN }
+ParenExpr        = {
+    LPAREN ~ RPAREN
+  | LPAREN ~ Expr ~ COMMA ~ (Expr ~ COMMA)* ~ Expr? ~ RPAREN
+  | LPAREN ~ Expr ~ RPAREN
+}
+
+AssignOp   = { EQUAL | PLUS_EQ | MINUS_EQ | ASTERISK_EQ | SLASH_EQ | PERCENT_EQ | AMPERSAND_EQ | PIPE_EQ | CARET_EQ | L_ARROW2_EQ | R_ARROW2_EQ }
+BOOL_OR    = { PIPE ~ PIPE }
+BOOL_AND   = { AMPERSAND ~ AMPERSAND }
+EQ_EQ      = { EQUAL ~ EQUAL }
+BANG_EQUAL = { BANG ~ EQUAL }
+
+keyword_suffix    = _{ !(ASCII_ALPHANUMERIC | "_") }
+KEYWORD_fn        = @{ "fn" ~ keyword_suffix }
+KEYWORD_type      = @{ "type" ~ keyword_suffix }
+KEYWORD_pub       = @{ "pub" ~ keyword_suffix }
+KEYWORD_var       = @{ "var" ~ keyword_suffix }
+KEYWORD_const     = @{ "const" ~ keyword_suffix }
+KEYWORD_if        = @{ "if" ~ keyword_suffix }
+KEYWORD_else      = @{ "else" ~ keyword_suffix }
+KEYWORD_while     = @{ "while" ~ keyword_suffix }
+KEYWORD_loop      = @{ "loop" ~ keyword_suffix }
+KEYWORD_for       = @{ "for" ~ keyword_suffix }
+KEYWORD_as        = @{ "as" ~ keyword_suffix }
+KEYWORD_match     = @{ "match" ~ keyword_suffix }
+KEYWORD_ret       = @{ "ret" ~ keyword_suffix }
+KEYWORD_break     = @{ "break" ~ keyword_suffix }
+KEYWORD_continue  = @{ "continue" ~ keyword_suffix }
+KEYWORD_defer     = @{ "defer" ~ keyword_suffix }
+KEYWORD_shape     = @{ "shape" ~ keyword_suffix }
+KEYWORD_struct    = @{ "struct" ~ keyword_suffix }
+KEYWORD_union     = @{ "union" ~ keyword_suffix }
+KEYWORD_enum      = @{ "enum" ~ keyword_suffix }
+KEYWORD_comptime  = @{ "comptime" ~ keyword_suffix }
+KEYWORD_void      = @{ "void" ~ keyword_suffix }
+KEYWORD_bool      = @{ "bool" ~ keyword_suffix }
+KEYWORD_isize     = @{ "isize" ~ keyword_suffix }
+KEYWORD_usize     = @{ "usize" ~ keyword_suffix }
+KEYWORD_ptr       = @{ "ptr" ~ keyword_suffix }
+KEYWORD_true      = @{ "true" ~ keyword_suffix }
+KEYWORD_false     = @{ "false" ~ keyword_suffix }
+KEYWORD_null      = @{ "null" ~ keyword_suffix }
+KEYWORD_undefined = @{ "undefined" ~ keyword_suffix }
+KEYWORD_i8        = @{ "i8" ~ keyword_suffix }
+KEYWORD_u8        = @{ "u8" ~ keyword_suffix }
+KEYWORD_i16       = @{ "i16" ~ keyword_suffix }
+KEYWORD_u16       = @{ "u16" ~ keyword_suffix }
+KEYWORD_i32       = @{ "i32" ~ keyword_suffix }
+KEYWORD_u32       = @{ "u32" ~ keyword_suffix }
+KEYWORD_i64       = @{ "i64" ~ keyword_suffix }
+KEYWORD_u64       = @{ "u64" ~ keyword_suffix }
+KEYWORD_f32       = @{ "f32" ~ keyword_suffix }
+KEYWORD_f64       = @{ "f64" ~ keyword_suffix }
+
+FAT_D_ARROW  = { "<=>" }
+THIN_D_ARROW = { "<->" }
+L_ARROW2_EQ  = { "<<=" }
+R_ARROW2_EQ  = { ">>=" }
+DOT3         = { "..." }
+THIN_R_ARROW = { "<-" }
+THIN_L_ARROW = { "->" }
+L_ARROW_EQ   = { "<=" }
+R_ARROW_EQ   = { ">=" }
+L_ARROW2     = { "<<" }
+R_ARROW2     = { ">>" }
+FAT_R_ARROW  = { "=>" }
+PLUS_EQ      = { "+=" }
+MINUS_EQ     = { "-=" }
+ASTERISK_EQ  = { "*=" }
+SLASH_EQ     = { "/=" }
+PERCENT_EQ   = { "%=" }
+AMPERSAND_EQ = { "&=" }
+PIPE_EQ      = { "|=" }
+CARET_EQ     = { "^=" }
+DOT2         = { ".." }
+LPAREN       = { "(" }
+RPAREN       = { ")" }
+LBRACKET     = { "[" }
+RBRACKET     = { "]" }
+LBRACE       = { "{" }
+RBRACE       = { "}" }
+COMMA        = { "," }
+SEMICOLON    = { ";" }
+COLON        = { ":" }
+DOT          = { "." }
+AT           = { "@" }
+SHARP        = { "#" }
+DOLLAR       = { "$" }
+EQUAL        = { "=" }
+PLUS         = { "+" }
+MINUS        = { "-" }
+ASTERISK     = { "*" }
+SLASH        = { "/" }
+PERCENT      = { "%" }
+AMPERSAND    = { "&" }
+PIPE         = { "|" }
+CARET        = { "^" }
+TILDE        = { "~" }
+BANG         = { "!" }
+L_ARROW      = { "<" }
+R_ARROW      = { ">" }
+UNDERSCORE   = { "_" }
+
+keyword    = _{
+    KEYWORD_fn
+  | KEYWORD_type
+  | KEYWORD_var
+  | KEYWORD_const
+  | KEYWORD_if
+  | KEYWORD_else
+  | KEYWORD_while
+  | KEYWORD_loop
+  | KEYWORD_for
+  | KEYWORD_as
+  | KEYWORD_match
+  | KEYWORD_ret
+  | KEYWORD_break
+  | KEYWORD_continue
+  | KEYWORD_defer
+  | KEYWORD_shape
+  | KEYWORD_struct
+  | KEYWORD_union
+  | KEYWORD_enum
+  | KEYWORD_comptime
+  | KEYWORD_void
+  | KEYWORD_bool
+  | KEYWORD_true
+  | KEYWORD_false
+  | KEYWORD_null
+  | KEYWORD_undefined
+  | KEYWORD_i8
+  | KEYWORD_u8
+  | KEYWORD_i16
+  | KEYWORD_u16
+  | KEYWORD_i32
+  | KEYWORD_u32
+  | KEYWORD_i64
+  | KEYWORD_u64
+  | KEYWORD_f32
+  | KEYWORD_f64
+  | KEYWORD_isize
+  | KEYWORD_usize
+  | KEYWORD_ptr
+}
+IDENTIFIER = @{
+    !(keyword ~ !(ASCII_ALPHANUMERIC | "_")) ~ (ASCII_ALPHA | "_" ~ (ASCII_ALPHANUMERIC | "_")) ~ (ASCII_ALPHANUMERIC | "_")*
+}
+
+INTEGER_LITERAL = { DECIMAL | HEX | BINARY | OCTAL | "0" }
+DECIMAL         = { ASCII_NONZERO_DIGIT ~ (ASCII_DIGIT | "_")* }
+HEX             = { "0" ~ ("x" | "X") ~ ASCII_HEX_DIGIT ~ (ASCII_HEX_DIGIT | "_")* }
+BINARY          = { "0" ~ ("b" | "B") ~ ASCII_BIN_DIGIT ~ (ASCII_BIN_DIGIT | "_")* }
+OCTAL           = { "0" ~ ("o" | "O") ~ ASCII_OCT_DIGIT ~ (ASCII_OCT_DIGIT | "_")* }
+FLOAT_LITERAL   = { ASCII_DIGIT ~ "." ~ ASCII_DIGIT ~ (ASCII_DIGIT | "_")* }
+CHAR_LITERAL    = { "'" ~ (!"'" ~ ANY) ~ "'" }
+STRING_LITERAL  = { "\"" ~ ANY* ~ "\"" }
+
+COMMENT       = _{ LINE_COMMENT | BLOCK_COMMENT }
+LINE_COMMENT  =  { "//" ~ (!"\n" ~ ANY)* }
+BLOCK_COMMENT =  { "/*" ~ ANY* ~ "*/" }
+WHITESPACE    = _{ " " | "\t" | "\r" | "\n" }

nob.c

@@ -0,0 +1,430 @@
+
+#define SPL_CFLAGS "-Wall", "-Wextra", "-O0", "-g", "-D_CRT_SECURE_NO_WARNINGS"
+#define nob_cc_flags(cmd) nob_cmd_append(cmd, SPL_CFLAGS)
+#undef UNICODE
+#define NOB_IMPLEMENTATION
+#include "nob.h"
+#undef NOB_IMPLEMENTATION
+#include "nob_popen.h"
+#ifdef _WIN32
+#include <consoleapi2.h>
+#endif
+#define BUILD_FOLDER "build/"
+
+// Content of the .cflags stamp file; must match SPL_CFLAGS above.
+#define CFLAGS_STR "-Wall -Wextra -O0 -g"
+// Stamp file whose mtime is refreshed whenever the flags change so that all
+// object files get rebuilt.
+static const char *CFLAGS_STAMP = BUILD_FOLDER ".cflags";
+
+/* clang-format off */
+#define VM_SRCS "stage0/spl_mcode.c", "stage0/spl_syscall.c", "stage0/spl_vm.c",
+static const char *spl_cli_srcs[] = {"stage0/spl_cli.c", VM_SRCS};
+static const char *test_srcs[] = {"stage0/test_spl_vm.c", VM_SRCS};
+static const char *splc0_srcs[] = {
+    "stage1/splc0.c",
+    "stage1/spl_diag.c",
+    "stage1/spl_tok.c",
+    "stage1/spl_lexer.c",
+    "stage1/spl_ast.c",
+    "stage1/spl_parser.c",
+    "stage1/spl_dumptree.c",
+    "stage1/spl_type.c",
+    "stage1/spl_lang_type.c",
+    "stage1/spl_attr.c",
+    "stage1/spl_scope.c",
+    "stage1/spl_sema.c",
+    "stage1/spl_intrin.c",
+    "stage1/spl_ir.c",
+    "stage1/spl_ast2ir.c",
+    "stage1/spl_layout.c",
+    "stage1/spl_ir2vm.c",
+    "stage0/spl_mcode.c",
+};
+/* clang-format on */
+
+typedef struct {
+    const char *name;
+    const char **srcs;
+    size_t srcs_count;
+} target_t;
+
+static target_t exe_targets[] = {
+    {"spl_cli", spl_cli_srcs, NOB_ARRAY_LEN(spl_cli_srcs)},
+    {"test", test_srcs, NOB_ARRAY_LEN(test_srcs)},
+    {"splc0", splc0_srcs, NOB_ARRAY_LEN(splc0_srcs)},
+};
+
+static const target_t *find_exe_target(const char *name) {
+    for (size_t i = 0; i < NOB_ARRAY_LEN(exe_targets); ++i) {
+        if (strcmp(exe_targets[i].name, name) == 0) {
+            return &exe_targets[i];
+        }
+    }
+    return NULL;
+}
+
+static const char *obj_path(const char *src) {
+    // "stage0/spl_vm.c" -> "build/stage0_spl_vm.o"
+    size_t prefix_len = strlen(BUILD_FOLDER);
+    char *out = (char *)nob_temp_alloc(prefix_len + strlen(src) + 2 + 1);
+    char *w = out;
+    memcpy(w, BUILD_FOLDER, prefix_len);
+    w += prefix_len;
+    for (const char *p = src; *p && *p != '.'; ++p) {
+        *w++ = (*p == '/' || *p == '\\') ? '_' : *p;
+    }
+    memcpy(w, ".o", 3);
+    return out;
+}
+
+static bool sync_cflags_stamp(void) {
+    Nob_String_View cflags = nob_sv_from_cstr(CFLAGS_STR);
+    Nob_String_Builder old = {0};
+    bool changed = true;
+    if (nob_file_exists(CFLAGS_STAMP) && nob_read_entire_file(CFLAGS_STAMP, &old)) {
+        changed = !nob_sv_eq(nob_sb_to_sv(old), cflags);
+    }
+    nob_sb_free(old);
+
+    if (changed) {
+        if (!nob_write_entire_file(CFLAGS_STAMP, cflags.data, cflags.count)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+static bool prepare_build(void) {
+    if (!nob_mkdir_if_not_exists(BUILD_FOLDER))
+        return false;
+    return sync_cflags_stamp();
+}
+
+static bool build_object(const char *src) {
+    const char *obj = obj_path(src);
+    if (!nob_file_exists(src)) {
+        nob_log(NOB_ERROR, "source file `%s` does not exist", src);
+        return false;
+    }
+
+    const char *inputs[] = {src, CFLAGS_STAMP};
+    int needs = nob_needs_rebuild(obj, inputs, NOB_ARRAY_LEN(inputs));
+    if (needs < 0)
+        return false;
+    if (needs == 0)
+        return true;
+
+    Nob_Cmd cmd = {0};
+    nob_cc(&cmd);
+    nob_cc_flags(&cmd);
+    nob_cmd_append(&cmd, "-c");
+    nob_cc_inputs(&cmd, src);
+    nob_cc_output(&cmd, obj);
+    return nob_cmd_run(&cmd);
+}
+
+static bool link_exe(const target_t *target) {
+    const char *exe = nob_temp_sprintf(BUILD_FOLDER "%s", target->name);
+    const char **objs = (const char **)nob_temp_alloc(sizeof(const char *) * target->srcs_count);
+    for (size_t i = 0; i < target->srcs_count; ++i) {
+        objs[i] = obj_path(target->srcs[i]);
+    }
+
+    int needs = nob_needs_rebuild(exe, objs, target->srcs_count);
+    if (needs < 0)
+        return false;
+    if (needs == 0)
+        return true;
+
+    Nob_Cmd cmd = {0};
+    nob_cc(&cmd);
+    nob_cc_flags(&cmd);
+    for (size_t i = 0; i < target->srcs_count; ++i) {
+        nob_cc_inputs(&cmd, objs[i]);
+    }
+    nob_cc_output(&cmd, exe);
+    return nob_cmd_run(&cmd);
+}
+
+static bool build_target(const char *name) {
+    const target_t *target = find_exe_target(name);
+    if (target == NULL) {
+        nob_log(NOB_ERROR, "unknown target `%s`", name);
+        return false;
+    }
+
+    for (size_t i = 0; i < target->srcs_count; ++i) {
+        if (!build_object(target->srcs[i])) {
+            return false;
+        }
+    }
+    return link_exe(target);
+}
+
+static bool build_all(void) {
+    for (size_t i = 0; i < NOB_ARRAY_LEN(exe_targets); ++i) {
+        if (!build_target(exe_targets[i].name)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+static void parse_expect(const char *name, Nob_Cmd_Result *expect) {
+    Nob_String_Builder sb = {0};
+    nob_read_entire_file(name, &sb);
+    Nob_String_View sv = nob_sb_to_sv(sb);
+    while (sv.count > 0) {
+        Nob_String_View line = nob_sv_chop_by_delim(&sv, '\n');
+        line = nob_sv_trim_left(line); // 去掉前导空格
+
+        if (!nob_sv_starts_with(line, nob_sv_from_cstr("//"))) {
+            break;
+        }
+
+        Nob_String_View rest = nob_sv_from_parts(line.data + 2, line.count - 2);
+        rest = nob_sv_trim_left(rest);
+
+        if (rest.count == 0)
+            continue;
+
+        if (!nob_sv_starts_with(rest, nob_sv_from_cstr("Expect"))) {
+            break;
+        }
+        rest = nob_sv_from_parts(rest.data + 6, rest.count - 6);
+        rest = nob_sv_trim_left(rest);
+
+        // 按 '=' 分割
+        Nob_String_View key = nob_sv_chop_by_delim(&rest, '=');
+        key = nob_sv_trim(key);
+        Nob_String_View value = nob_sv_trim(rest);
+
+        if (nob_sv_eq(key, nob_sv_from_cstr("retcode"))) {
+            int val = 0;
+            for (size_t i = 0; i < value.count && isdigit(value.data[i]); ++i) {
+                val = val * 10 + (value.data[i] - '0');
+            }
+            // printf("expected code %d\n", val);
+            expect->exit_code = val;
+        } else if (nob_sv_eq(key, nob_sv_from_cstr("stdout"))) {
+        }
+    }
+}
+
+static bool test_once(const char *fname, void *user_data) {
+    (void)user_data;
+
+    const char *compiler_path = "splc0";
+    const char *cli_path = "spl_cli";
+    const char *target_sir = BUILD_FOLDER "test.sir";
+
+    Nob_Cmd cmd = {0};
+    if (!build_target(compiler_path)) {
+        return 1;
+    }
+    cmd.count = 0;
+
+    nob_cmd_append(&cmd, nob_temp_sprintf(BUILD_FOLDER "%s", compiler_path));
+    nob_cmd_append(&cmd, fname, target_sir);
+    if (!nob_cmd_run(&cmd)) {
+        return false;
+    }
+
+    if (!build_target(cli_path)) {
+        return 1;
+    }
+    cmd.count = 0;
+    nob_cmd_append(&cmd, nob_temp_sprintf(BUILD_FOLDER "%s", cli_path));
+    nob_cmd_append(&cmd, target_sir);
+    // nob_cmd_run(&cmd);
+
+    Nob_Cmd_Result result = {0};
+    Nob_String_Builder cmd_str = {0};
+    nob_cmd_render(cmd, &cmd_str);
+
+    Nob_String_View sv = nob_sb_to_sv(cmd_str);
+    nob_cmd_capture_popen(nob_temp_sv_to_cstr(sv), &result);
+    // Expect retcode = number
+
+    Nob_Cmd_Result expect = {0};
+    parse_expect(fname, &expect);
+
+    if (expect.exit_code != result.exit_code) {
+        nob_log(NOB_ERROR, "Expect code `%d`, Result code `%d`", expect.exit_code,
+                result.exit_code);
+        return false;
+    }
+
+    nob_cmd_result_free(result);
+    return true;
+}
+
+static bool test_once_with_dump(const char *fname, void *user_data) {
+    const char *target_name = "splc0";
+    if (!prepare_build())
+        return 1;
+    if (!build_target(target_name))
+        return 1;
+    Nob_Cmd cmd = {0};
+    nob_cmd_append(&cmd, nob_temp_sprintf(BUILD_FOLDER "%s", target_name));
+    nob_cmd_append(&cmd, "--dump", (char *)user_data, fname, BUILD_FOLDER "t.sir");
+    return nob_cmd_run(&cmd);
+}
+
+typedef bool (*test_fn_t)(const char *fname, void *user_data);
+static bool run_test(Nob_Files *files, test_fn_t test_once, void *user_data) {
+    const char *test_folder = "./tests/stage1/";
+
+    if (!prepare_build()) {
+        return 1;
+    }
+
+    Nob_File_Paths paths = {0};
+    nob_read_entire_dir(test_folder, &paths);
+    for (int i = 0; i < files->count; i += 1) {
+        for (int j = 0; j < paths.count; j += 1) {
+            String_View sv = sv_from_cstr(paths.items[j]);
+            // printf("--- test " SV_Fmt " ---\n", SV_Arg(sv));
+            if (!strstr(paths.items[j], files->items[i])) {
+                continue;
+            }
+            const char *tname = nob_temp_sprintf("%s%s", test_folder, paths.items[j]);
+            printf("--- test %s ---\n", tname);
+            if (test_once(tname, user_data) == false)
+                return false;
+        }
+    }
+
+    return true;
+}
+
+static bool delete_walk_entry(Nob_Walk_Entry entry) { return nob_delete_file(entry.path); }
+
+static bool delete_directory_recursively(const char *dir_path) {
+    return nob_walk_dir(dir_path, delete_walk_entry, .post_order = true);
+}
+
+static void print_help(const char *program_name) {
+    nob_log(NOB_INFO, "SPL C-side bootstrap build system (nob)");
+    nob_log(NOB_INFO, "%s", " ");
+    nob_log(NOB_INFO, "Usage: %s <command> [args...]", program_name);
+    nob_log(NOB_INFO, "%s", " ");
+    nob_log(NOB_INFO, "Commands:");
+    nob_log(NOB_INFO, "    build [targets...]  build all targets or the given ones");
+    nob_log(NOB_INFO, "    run <target> [args] build and run a target");
+    nob_log(NOB_INFO, "    test                build and run VM unit tests");
+    nob_log(NOB_INFO, "    clean               remove build artifacts");
+    nob_log(NOB_INFO, "    list                list all targets");
+    nob_log(NOB_INFO, "    help/-h/--help      print this help message");
+    nob_log(NOB_INFO, "%s", " ");
+    nob_log(NOB_INFO, "Targets:");
+    for (size_t i = 0; i < NOB_ARRAY_LEN(exe_targets); ++i) {
+        nob_log(NOB_INFO, "    %s", exe_targets[i].name);
+    }
+}
+
+int main(int argc, char **argv) {
+#ifdef _WIN32
+    SetConsoleOutputCP(CP_UTF8);
+#endif
+    NOB_GO_REBUILD_URSELF_PLUS(argc, argv, "nob.h", "nob_popen.h");
+    set_log_handler(nob_cancer_log_handler);
+
+    const char *program_name = nob_shift(argv, argc);
+    const char *command_name = "build";
+    if (argc > 0) {
+        command_name = nob_shift(argv, argc);
+    }
+
+    if (strcmp(command_name, "build") == 0) {
+        if (!prepare_build())
+            return 1;
+        if (argc > 0) {
+            while (argc > 0) {
+                const char *target_name = nob_shift(argv, argc);
+                if (!build_target(target_name))
+                    return 1;
+            }
+        } else {
+            if (!build_all())
+                return 1;
+        }
+        return 0;
+    }
+
+    if (strcmp(command_name, "run") == 0) {
+        if (argc <= 0) {
+            nob_log(NOB_ERROR, "usage: %s run <target> [args...]", program_name);
+            return 1;
+        }
+        const char *target_name = nob_shift(argv, argc);
+        if (!prepare_build())
+            return 1;
+        if (!build_target(target_name))
+            return 1;
+        Nob_Cmd cmd = {0};
+        nob_cmd_append(&cmd, nob_temp_sprintf(BUILD_FOLDER "%s", target_name));
+        while (argc > 0) {
+            nob_cmd_append(&cmd, nob_shift(argv, argc));
+        }
+        return nob_cmd_run(&cmd) ? 0 : 1;
+    }
+
+    if (strcmp(command_name, "test") == 0) {
+        Nob_Files files = {0};
+        test_fn_t tfn = test_once;
+        const char *mode_name = NULL;
+        if (argc > 0) {
+            mode_name = nob_shift(argv, argc);
+            if (strcmp(mode_name, "lex") == 0 || strcmp(mode_name, "ast") == 0 ||
+                strcmp(mode_name, "sema") == 0 || strcmp(mode_name, "ir") == 0 ||
+                strcmp(mode_name, "vm") == 0) {
+                tfn = test_once_with_dump;
+            } else if (strcmp(mode_name, "run") == 0) {
+                // HACK
+                Nob_Cmd cmd = {0};
+                nob_cmd_append(&cmd, BUILD_FOLDER "spl_cli", "-d");
+                nob_cmd_append(&cmd, BUILD_FOLDER "test.sir");
+                return nob_cmd_run(&cmd) ? 0 : 1;
+            } else {
+                da_append(&files, mode_name);
+            }
+        }
+
+        while (argc > 0) {
+            da_append(&files, nob_shift(argv, argc));
+        }
+
+        return run_test(&files, tfn, (void *)mode_name) ? 0 : 1;
+    }
+
+    if (strcmp(command_name, "clean") == 0) {
+        if (nob_file_exists(BUILD_FOLDER)) {
+            if (!delete_directory_recursively(BUILD_FOLDER))
+                return 1;
+        }
+        nob_log(NOB_INFO, "cleaned %s", BUILD_FOLDER);
+        return 0;
+    }
+
+    if (strcmp(command_name, "list") == 0) {
+        for (size_t i = 0; i < NOB_ARRAY_LEN(exe_targets); ++i) {
+            nob_log(NOB_INFO, "%s:", exe_targets[i].name);
+            for (size_t j = 0; j < exe_targets[i].srcs_count; ++j) {
+                nob_log(NOB_INFO, "    %s", exe_targets[i].srcs[j]);
+            }
+        }
+        return 0;
+    }
+
+    if (strcmp(command_name, "help") == 0 || strcmp(command_name, "-h") == 0 ||
+        strcmp(command_name, "--help") == 0) {
+        print_help(program_name);
+        return 0;
+    }
+
+    nob_log(NOB_ERROR, "unknown command `%s`", command_name);
+    print_help(program_name);
+    return 1;
+}

nob_popen.h

@@ -0,0 +1,145 @@
+#ifndef __NOB_POPEN_H__
+#define __NOB_POPEN_H__
+
+#include "nob.h"
+
+typedef struct {
+    Nob_String_Builder out; // stdout 内容
+    int exit_code;          // 实际退出码
+    bool ok;                // 是否成功启动
+} Nob_Cmd_Result;
+
+typedef struct {
+    const char **items;
+    int capacity;
+    int count;
+} Nob_Files;
+
+// 运行命令，捕获 stdout（Windows 下会合并 stderr）和真实退出码。
+// 返回 true 仅表示命令成功启动并完成，不代表 exit_code == 0。
+bool nob_cmd_capture_popen(const char *tname, Nob_Cmd_Result *res) {
+    memset(res, 0, sizeof(*res));
+
+#ifdef _WIN32
+    // ---------- Windows: CreateProcessA + 匿名管道 ----------
+    SECURITY_ATTRIBUTES sa = {0};
+    sa.nLength = sizeof(sa);
+    sa.bInheritHandle = TRUE;
+    sa.lpSecurityDescriptor = NULL;
+
+    HANDLE hRead = NULL;
+    HANDLE hWrite = NULL;
+    if (!CreatePipe(&hRead, &hWrite, &sa, 0)) {
+        nob_log(NOB_ERROR, "CreatePipe failed: %s", nob_win32_error_message(GetLastError()));
+        return false;
+    }
+
+    // 读端不能被继承，否则父进程 ReadFile 永远等不到 EOF
+    if (!SetHandleInformation(hRead, HANDLE_FLAG_INHERIT, 0)) {
+        nob_log(NOB_ERROR, "SetHandleInformation failed: %s",
+                nob_win32_error_message(GetLastError()));
+        CloseHandle(hRead);
+        CloseHandle(hWrite);
+        return false;
+    }
+
+    STARTUPINFOA si = {0};
+    si.cb = sizeof(si);
+    si.dwFlags = STARTF_USESTDHANDLES;
+    si.hStdInput = GetStdHandle(STD_INPUT_HANDLE);
+    si.hStdOutput = hWrite;
+    si.hStdError = hWrite; // 把 stderr 也并入 out，需要分离的话另开一条管道
+
+    PROCESS_INFORMATION pi = {0};
+
+    // CreateProcessA 会就地修改 lpCommandLine，必须传可写缓冲
+    char *cmdline = NULL;
+    {
+        size_t n = strlen(tname) + 1;
+        cmdline = (char *)malloc(n);
+        if (!cmdline) {
+            CloseHandle(hRead);
+            CloseHandle(hWrite);
+            nob_log(NOB_ERROR, "malloc failed");
+            return false;
+        }
+        memcpy(cmdline, tname, n);
+    }
+
+    BOOL ok = CreateProcessA(NULL,             // lpApplicationName: 让系统从 lpCommandLine 里解析
+                             cmdline,          // lpCommandLine
+                             NULL,             // lpProcessAttributes
+                             NULL,             // lpThreadAttributes
+                             TRUE,             // bInheritHandles: 必须为 TRUE，才能继承管道写端
+                             CREATE_NO_WINDOW, // 不弹黑窗；想弹就传 0
+                             NULL,             // lpEnvironment
+                             NULL,             // lpCurrentDirectory
+                             &si, &pi);
+
+    free(cmdline);
+
+    // 无论成功与否，父进程都不再需要写端（子进程已持有自己的副本）
+    CloseHandle(hWrite);
+
+    if (!ok) {
+        nob_log(NOB_ERROR, "CreateProcessA failed for \"%s\": %s", tname,
+                nob_win32_error_message(GetLastError()));
+        CloseHandle(hRead);
+        return false;
+    }
+
+    // ---------- 读取 stdout ----------
+    {
+        char buffer[4096];
+        DWORD n = 0;
+        while (ReadFile(hRead, buffer, sizeof(buffer), &n, NULL) && n > 0) {
+            nob_sb_append_buf(&res->out, buffer, (size_t)n);
+        }
+    }
+    CloseHandle(hRead);
+
+    // ---------- 等待并取真实退出码 ----------
+    WaitForSingleObject(pi.hProcess, INFINITE);
+    DWORD code = 0;
+    if (!GetExitCodeProcess(pi.hProcess, &code)) {
+        nob_log(NOB_ERROR, "GetExitCodeProcess failed: %s",
+                nob_win32_error_message(GetLastError()));
+        code = (DWORD)-1;
+    }
+    res->exit_code = (int)code;
+
+    CloseHandle(pi.hProcess);
+    CloseHandle(pi.hThread);
+
+#else
+    // ---------- POSIX: popen ----------
+    FILE *fp = popen(tname, "r");
+    if (!fp) {
+        nob_log(NOB_ERROR, "popen failed: %s", strerror(errno));
+        return false;
+    }
+
+    char buffer[4096];
+    while (fgets(buffer, sizeof(buffer), fp)) {
+        nob_sb_append_cstr(&res->out, buffer);
+    }
+
+    int status = pclose(fp);
+    if (status == -1) {
+        nob_log(NOB_ERROR, "pclose failed: %s", strerror(errno));
+        return false;
+    }
+    if (WIFEXITED(status))
+        status = WEXITSTATUS(status);
+    else if (WIFSIGNALED(status))
+        status = 128 + WTERMSIG(status);
+    res->exit_code = status;
+#endif
+
+    res->ok = true;
+    return true;
+}
+
+#define nob_cmd_result_free(res) nob_sb_free((res).out)
+
+#endif /* __NOB_POPEN_H__ */

stage0/include/color.h

@@ -0,0 +1,61 @@
+/**
+ * @file color.h
+ * @brief ANSI终端颜色控制码定义
+ *
+ * 提供跨平台的终端文本颜色和样式控制支持
+ */
+
+#ifndef __SCC_TERMINAL_COLOR_H__
+#define __SCC_TERMINAL_COLOR_H__
+
+/* clang-format off */
+/// @name 前景色控制码
+/// @{
+#define ANSI_FG_BLACK   "\33[30m"   ///< 黑色前景
+#define ANSI_FG_RED     "\33[31m"   ///< 红色前景
+#define ANSI_FG_GREEN   "\33[32m"   ///< 绿色前景
+#define ANSI_FG_YELLOW  "\33[33m"   ///< 黄色前景
+#define ANSI_FG_BLUE    "\33[34m"   ///< 蓝色前景
+#define ANSI_FG_MAGENTA "\33[35m"   ///< 品红色前景
+#define ANSI_FG_CYAN    "\33[36m"   ///< 青色前景
+#define ANSI_FG_WHITE   "\33[37m"   ///< 白色前景
+/// @}
+
+/// @name 背景色控制码
+/// @{
+#define ANSI_BG_BLACK   "\33[40m"   ///< 黑色背景
+#define ANSI_BG_RED     "\33[41m"   ///< 红色背景
+#define ANSI_BG_GREEN   "\33[42m"   ///< 绿色背景
+#define ANSI_BG_YELLOW  "\33[43m"   ///< 黄色背景
+#define ANSI_BG_BLUE    "\33[44m"   ///< 蓝色背景
+#define ANSI_BG_MAGENTA "\33[45m"   ///< 品红色背景（注：原始代码此处应为45m）
+#define ANSI_BG_CYAN    "\33[46m"   ///< 青色背景
+#define ANSI_BG_WHITE   "\33[47m"   ///< 白色背景
+/// @}
+
+/// @name 文字样式控制码
+/// @{
+#define ANSI_UNDERLINED "\33[4m"    ///< 下划线样式
+#define ANSI_BOLD       "\33[1m"    ///< 粗体样式
+#define ANSI_NONE       "\33[0m"    ///< 重置所有样式
+/// @}
+/* clang-format on */
+
+/**
+ * @def ANSI_FMT
+ * @brief 安全文本格式化宏
+ * @param str 目标字符串
+ * @param fmt ANSI格式序列（可组合多个样式）
+ *
+ * @note 当定义ANSI_FMT_DISABLE时自动禁用颜色输出
+ * @code
+ * printf(ANSI_FMT("Warning!", ANSI_FG_YELLOW ANSI_BOLD));
+ * @endcode
+ */
+#ifndef ANSI_FMT_DISABLE
+#define ANSI_FMT(str, fmt) fmt str ANSI_NONE ///< 启用样式包裹
+#else
+#define ANSI_FMT(str, fmt) str ///< 禁用样式输出
+#endif
+
+#endif /* __SCC_TERMINAL_COLOR_H__ */

stage0/include/core_map.h

@@ -0,0 +1,252 @@
+#ifndef __CORE_MAP_H__
+#define __CORE_MAP_H__
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifndef nullptr
+#define nullptr NULL
+#endif
+typedef uintptr_t usize;
+typedef intptr_t isize;
+
+#define MAP_TYPEOF __typeof__
+
+/* 状态常量 */
+#define __MAP_SLOT_EMPTY 0
+#define __MAP_SLOT_OCCUPIED 1
+#define __MAP_SLOT_DELETED 2
+
+/* 默认负载因子 factor/128 */
+#define MAP_DEFAULT_LOAD_FACTOR 70
+
+/* ---------- 默认哈希/比较函数 ---------- */
+#define MAP_HASH_INT(k) ((usize)((k) * 2654435761U))
+#define MAP_CMP_INT(a, b) ((a) != (b))
+
+static inline usize map_hash_str(const char *s) {
+    usize h = 5381;
+    while (*s)
+        h = ((h << 5) + h) + (unsigned char)*s++;
+    return h;
+}
+#define MAP_HASH_STR map_hash_str
+#define MAP_CMP_STR strcmp
+
+/* ---------- 数据结构宏 ---------- */
+#define MAP_SLOT(key_t, val_t)                                                                     \
+    struct {                                                                                       \
+        key_t key;                                                                                 \
+        val_t val;                                                                                 \
+        char state;                                                                                \
+    }
+
+#define MAP(key_t, val_t)                                                                          \
+    struct {                                                                                       \
+        usize size;                                                                                \
+        usize cap;                                                                                 \
+        MAP_SLOT(key_t, val_t) * data;                                                             \
+        usize (*hash)(key_t);                                                                      \
+        int (*cmp)(key_t, key_t);                                                                  \
+    }
+
+/* ---------- 操作宏 ---------- */
+
+/** 初始化，必须提供哈希和比较函数 */
+#define map_init(map, hash_fn, cmp_fn)                                                             \
+    do {                                                                                           \
+        (map).size = 0;                                                                            \
+        (map).cap = 0;                                                                             \
+        (map).data = nullptr;                                                                      \
+        (map).hash = (hash_fn);                                                                    \
+        (map).cmp = (cmp_fn);                                                                      \
+    } while (0)
+
+/** 释放内部数组 */
+#define map_free(map)                                                                              \
+    do {                                                                                           \
+        free((map).data);                                                                          \
+        (map).data = nullptr;                                                                      \
+        (map).size = (map).cap = 0;                                                                \
+    } while (0)
+
+/** 遍历所有有效元素 */
+#define map_for(map, idx)                                                                          \
+    for (usize(idx) = 0; (idx) < (map).cap; ++(idx))                                               \
+        if ((map).data[(idx)].state == __MAP_SLOT_OCCUPIED)
+
+#define unsafe_map_at(map, idx) ((map).data[(idx)])
+
+/**
+ * 插入（若键已存在则更新值）
+ * 注意：扩容使用 realloc，失败会 abort（可自行修改错误处理）
+ */
+#define map_put(map, _key, _val)                                                                   \
+    do {                                                                                           \
+        /* 扩容 */                                                                                 \
+        if ((map).cap == 0 || (map).size * 128 / (map).cap >= MAP_DEFAULT_LOAD_FACTOR) {           \
+            usize new_cap = (map).cap == 0 ? 8 : (map).cap * 2;                                    \
+            MAP_SLOT(MAP_TYPEOF((map).data->key), MAP_TYPEOF((map).data->val)) *new_data =         \
+                calloc(new_cap, sizeof(*new_data));                                                \
+            if (!new_data)                                                                         \
+                abort();                                                                           \
+            /* 重新插入旧元素 */                                                                   \
+            for (usize _i = 0; _i < (map).cap; ++_i) {                                             \
+                if ((map).data[_i].state == __MAP_SLOT_OCCUPIED) {                                 \
+                    usize _h = (map).hash((map).data[_i].key) & (new_cap - 1);                     \
+                    while (new_data[_h].state == __MAP_SLOT_OCCUPIED)                              \
+                        _h = (_h + 1) & (new_cap - 1);                                             \
+                    new_data[_h].key = (map).data[_i].key;                                         \
+                    new_data[_h].val = (map).data[_i].val;                                         \
+                    new_data[_h].state = __MAP_SLOT_OCCUPIED;                                      \
+                }                                                                                  \
+            }                                                                                      \
+            free((map).data);                                                                      \
+            (map).data = (void *)new_data;                                                         \
+            (map).cap = new_cap;                                                                   \
+        }                                                                                          \
+        /* 查找或插入 */                                                                           \
+        usize _mask = (map).cap - 1;                                                               \
+        usize _idx = (map).hash(_key) & _mask;                                                     \
+        usize _first_del = (usize) - 1;                                                            \
+        while ((map).data[_idx].state != __MAP_SLOT_EMPTY) {                                       \
+            if ((map).data[_idx].state == __MAP_SLOT_OCCUPIED &&                                   \
+                (map).cmp((map).data[_idx].key, _key) == 0) {                                      \
+                (map).data[_idx].val = _val;                                                       \
+                break;                                                                             \
+            }                                                                                      \
+            if ((map).data[_idx].state == __MAP_SLOT_DELETED && _first_del == (usize) - 1)         \
+                _first_del = _idx;                                                                 \
+            _idx = (_idx + 1) & _mask;                                                             \
+        }                                                                                          \
+        if ((map).data[_idx].state == __MAP_SLOT_EMPTY) {                                          \
+            usize _target = (_first_del != (usize) - 1) ? _first_del : _idx;                       \
+            (map).data[_target].key = _key;                                                        \
+            (map).data[_target].val = _val;                                                        \
+            (map).data[_target].state = __MAP_SLOT_OCCUPIED;                                       \
+            ++(map).size;                                                                          \
+        }                                                                                          \
+    } while (0)
+
+/**
+ * 插入（仅当键不存在时），若键已存在则静默跳过，不更新值
+ * 与 map_put 的差异仅在"键已存在时"：map_put 更新值，map_put_new 放弃
+ */
+#define map_put_new(map, _key, _val)                                                               \
+    do {                                                                                           \
+        /* 扩容 */                                                                                 \
+        if ((map).cap == 0 || (map).size * 128 / (map).cap >= MAP_DEFAULT_LOAD_FACTOR) {           \
+            usize new_cap = (map).cap == 0 ? 8 : (map).cap * 2;                                    \
+            MAP_SLOT(MAP_TYPEOF((map).data->key), MAP_TYPEOF((map).data->val)) *new_data =         \
+                calloc(new_cap, sizeof(*new_data));                                                \
+            if (!new_data)                                                                         \
+                abort();                                                                           \
+            /* 重新插入旧元素 */                                                                   \
+            for (usize _i = 0; _i < (map).cap; ++_i) {                                             \
+                if ((map).data[_i].state == __MAP_SLOT_OCCUPIED) {                                 \
+                    usize _h = (map).hash((map).data[_i].key) & (new_cap - 1);                     \
+                    while (new_data[_h].state == __MAP_SLOT_OCCUPIED)                              \
+                        _h = (_h + 1) & (new_cap - 1);                                             \
+                    new_data[_h].key = (map).data[_i].key;                                         \
+                    new_data[_h].val = (map).data[_i].val;                                         \
+                    new_data[_h].state = __MAP_SLOT_OCCUPIED;                                      \
+                }                                                                                  \
+            }                                                                                      \
+            free((map).data);                                                                      \
+            (map).data = (void *)new_data;                                                         \
+            (map).cap = new_cap;                                                                   \
+        }                                                                                          \
+        /* 查找 */                                                                                 \
+        usize _mask = (map).cap - 1;                                                               \
+        usize _idx = (map).hash(_key) & _mask;                                                     \
+        usize _first_del = (usize) - 1;                                                            \
+        while ((map).data[_idx].state != __MAP_SLOT_EMPTY) {                                       \
+            if ((map).data[_idx].state == __MAP_SLOT_OCCUPIED &&                                   \
+                (map).cmp((map).data[_idx].key, _key) == 0) {                                      \
+                break; /* 已存在，不更新 */                                                         \
+            }                                                                                      \
+            if ((map).data[_idx].state == __MAP_SLOT_DELETED && _first_del == (usize) - 1)         \
+                _first_del = _idx;                                                                 \
+            _idx = (_idx + 1) & _mask;                                                             \
+        }                                                                                          \
+        if ((map).data[_idx].state == __MAP_SLOT_EMPTY) {                                          \
+            usize _target = (_first_del != (usize) - 1) ? _first_del : _idx;                       \
+            (map).data[_target].key = _key;                                                        \
+            (map).data[_target].val = _val;                                                        \
+            (map).data[_target].state = __MAP_SLOT_OCCUPIED;                                       \
+            ++(map).size;                                                                          \
+        }                                                                                          \
+    } while (0)
+
+/**
+ * 查询：若找到，*out_val 被赋值为对应值并返回 1；否则返回 0
+ */
+#define map_get(map, _key, out_val)                                                                \
+    (({                                                                                            \
+        int _found = 0;                                                                            \
+        if ((map).cap > 0) {                                                                       \
+            usize _mask = (map).cap - 1;                                                           \
+            usize _idx = (map).hash(_key) & _mask;                                                 \
+            while ((map).data[_idx].state != __MAP_SLOT_EMPTY) {                                   \
+                if ((map).data[_idx].state == __MAP_SLOT_OCCUPIED &&                               \
+                    (map).cmp((map).data[_idx].key, _key) == 0) {                                  \
+                    *out_val = (map).data[_idx].val;                                               \
+                    _found = 1;                                                                    \
+                    break;                                                                         \
+                }                                                                                  \
+                _idx = (_idx + 1) & _mask;                                                         \
+            }                                                                                      \
+        }                                                                                          \
+        _found;                                                                                    \
+    }))
+
+/**
+ * 查询（续探）：首次调用前将 *in_out_idx 置为 (usize)-1，
+ * 则从键自身的 hash 桶开始查找；命中后 *out_val 被赋值、返回 1，
+ * 且 *in_out_idx 更新为命中槽位，下次调用从该槽的下一个继续探测（碰撞续探）。
+ * 扫描到空槽返回 0。用于 key 碰撞后需要回表二次比较的场景。
+ */
+#define map_get_continue(map, _key, out_val, in_out_idx)                                           \
+    (({                                                                                            \
+        int _found = 0;                                                                            \
+        if ((map).cap > 0) {                                                                       \
+            usize _mask = (map).cap - 1;                                                           \
+            usize _idx = (*(in_out_idx) == (usize) - 1) ? (map).hash(_key) & _mask                 \
+                                                        : (*(in_out_idx) + 1) & _mask;            \
+            while ((map).data[_idx].state != __MAP_SLOT_EMPTY) {                                   \
+                if ((map).data[_idx].state == __MAP_SLOT_OCCUPIED &&                               \
+                    (map).cmp((map).data[_idx].key, _key) == 0) {                                  \
+                    *out_val = (map).data[_idx].val;                                               \
+                    *(in_out_idx) = _idx;                                                          \
+                    _found = 1;                                                                    \
+                    break;                                                                         \
+                }                                                                                  \
+                _idx = (_idx + 1) & _mask;                                                         \
+            }                                                                                      \
+        }                                                                                          \
+        _found;                                                                                    \
+    }))
+
+/**
+ * 删除指定键
+ */
+#define map_del(map, _key)                                                                         \
+    do {                                                                                           \
+        if ((map).cap == 0)                                                                        \
+            break;                                                                                 \
+        usize _mask = (map).cap - 1;                                                               \
+        usize _idx = (map).hash(_key) & _mask;                                                     \
+        while ((map).data[_idx].state != __MAP_SLOT_EMPTY) {                                       \
+            if ((map).data[_idx].state == __MAP_SLOT_OCCUPIED &&                                   \
+                (map).cmp((map).data[_idx].key, _key) == 0) {                                      \
+                (map).data[_idx].state = __MAP_SLOT_DELETED;                                       \
+                --(map).size;                                                                      \
+                break;                                                                             \
+            }                                                                                      \
+            _idx = (_idx + 1) & _mask;                                                             \
+        }                                                                                          \
+    } while (0)
+
+#endif /* __CORE_MAP_H__ */

stage0/include/core_vec.h

@@ -0,0 +1,258 @@
+/**
+ * @file vec.h
+ * @brief 动态数组（Dynamic Array）实现
+ *
+ * 提供类型安全的动态数组容器实现，支持自动扩容和基本操作
+ */
+
+#ifndef __CORE_VEC_H__
+#define __CORE_VEC_H__
+
+#define __CORE_VEC_USE_STD__
+#ifndef __CORE_VEC_USE_STD__
+#include "core_log.h"
+
+#include "core_impl.h"
+#include "core_type.h"
+#define __vec_realloc realloc
+#define __vec_free free
+#define __vec_memcpy memcpy
+#else
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifndef nullptr
+#define nullptr NULL
+#endif
+typedef size_t usize;
+#define __vec_realloc realloc
+#define __vec_free free
+#define __vec_memcpy memcpy
+
+#ifndef LOG_FATAL
+#include <stdio.h>
+#define LOG_FATAL(...)                                                                             \
+    do {                                                                                           \
+        printf(__VA_ARGS__);                                                                       \
+        abort();                                                                                   \
+    } while (0)
+#endif
+
+#ifndef Assert
+#include <assert.h>
+#define Assert(cond) assert(cond)
+#endif
+#endif
+
+/** @defgroup vec_struct 数据结构定义 */
+
+/**
+ * @def VEC(type)
+ * @brief 声明向量结构体
+ * @param type 存储的数据类型
+ *
+ * 生成包含size/cap/data三个字段的结构体定义：
+ * - size: 当前元素数量
+ * - cap: 数组容量
+ * - data: 存储数组指针
+ * @example
+ * VEC(char) string; <=> char[dynamic_array] string;
+ * struct people { VEC(char) name; int age; VEC(struct people) children;
+ * };
+ */
+#define VEC(type)                                                                                  \
+    struct {                                                                                       \
+        usize size;                                                                                \
+        usize cap;                                                                                 \
+        type *data;                                                                                \
+    }
+
+/** @defgroup vec_operations 动态数组操作宏 */
+
+/**
+ * @def vec_init(vec)
+ * @brief 初始化向量结构体
+ * @param vec 要初始化的向量结构体变量
+ *
+ * @note 此宏不会分配内存，仅做零初始化
+ */
+#define vec_init(vec)                                                                              \
+    do {                                                                                           \
+        (vec).size = 0, (vec).cap = 0, (vec).data = 0;                                             \
+    } while (0)
+
+#define vec_realloc(vec, new_cap)                                                                  \
+    do {                                                                                           \
+        void *data = __vec_realloc((vec).data, new_cap * sizeof(*(vec).data));                     \
+        if (!data) {                                                                               \
+            LOG_FATAL("vector_push: realloc failed\n");                                            \
+        }                                                                                          \
+        (vec).cap = new_cap;                                                                       \
+        (vec).data = data;                                                                         \
+    } while (0)
+
+#define vec_size(vec) ((vec).size)
+#define vec_cap(vec) ((vec).cap)
+#define vec_for(vec, idx) for (usize idx = 0; idx < vec_size(vec); idx += 1)
+
+/**
+ * @def vec_push(vec, value)
+ * @brief 添加元素到向量末尾
+ * @param vec 目标向量结构体
+ * @param value 要添加的值（需匹配存储类型）
+ *
+ * @note 当容量不足时自动扩容为2倍（初始容量为4）
+ * @warning 内存分配失败时会触发LOG_FATAL
+ */
+#define vec_push(vec, value)                                                                       \
+    do {                                                                                           \
+        if ((vec).size >= (vec).cap) {                                                             \
+            usize cap = (vec).cap ? (vec).cap * 2 : 4;                                             \
+            vec_realloc(vec, cap);                                                                 \
+        }                                                                                          \
+        Assert((vec).data != nullptr);                                                             \
+        (vec).data[(vec).size++] = value;                                                          \
+    } while (0)
+
+/**
+ * @def vec_pop(vec)
+ * @brief 弹出最后一个元素
+ * @param vec 目标向量结构体
+ * @return 最后元素的引用
+ * @warning 需确保size > 0时使用
+ */
+#define vec_pop(vec) ((vec).data[--(vec).size])
+
+/**
+ * @def vec_at(vec, idx)
+ * @brief 获取指定索引元素
+ * @param vec 目标向量结构体
+ * @param idx 元素索引（0 <= idx < size）
+ * @return 对应元素的引用
+ */
+#define vec_at(vec, idx) (((vec).data)[idx])
+
+/**
+ * @def vec_idx(vec, ptr)
+ * @brief 获取元素指针对应的索引
+ * @param vec 目标向量结构体
+ * @param ptr 元素指针（需在data数组范围内）
+ * @return 元素索引值
+ */
+#define vec_idx(vec, ptr) ((ptr) - (vec).data)
+
+/**
+ * @def vec_free(vec)
+ * @brief 释放向量内存
+ * @param vec 目标向量结构体
+ *
+ * @note 释放后需重新初始化才能再次使用
+ */
+#define vec_free(vec)                                                                              \
+    do {                                                                                           \
+        if ((vec).data == nullptr)                                                                 \
+            break;                                                                                 \
+        __vec_free((vec).data);                                                                    \
+        (vec).data = nullptr;                                                                      \
+        (vec).size = (vec).cap = 0;                                                                \
+    } while (0)
+
+#define vec_unsafe_get_data(vec) ((vec).data)
+
+#define vec_unsafe_from_buffer(vec, buffer, buffer_size)                                           \
+    do {                                                                                           \
+        (vec).size = buffer_size;                                                                  \
+        (vec).cap = (vec).size;                                                                    \
+        (vec).data = buffer;                                                                       \
+    } while (0)
+
+#define vec_unsafe_from_static_array(vec, array)                                                   \
+    do {                                                                                           \
+        (vec).size = sizeof(array) / sizeof((array)[0]);                                           \
+        (vec).cap = (vec).size;                                                                    \
+        (vec).data = array;                                                                        \
+    } while (0)
+
+/**
+ * @def vec_sized_realloc(vec, elem_size, new_cap)
+ * @brief 内部宏：按 elem_size 重新分配内存
+ */
+#define vec_sized_realloc(vec, elem_size, new_cap)                                                 \
+    do {                                                                                           \
+        void *new_data = __vec_realloc((vec).data, (new_cap) * (elem_size));                       \
+        if (!new_data)                                                                             \
+            LOG_FATAL("vec_sized_realloc: failed\n");                                              \
+        (vec).data = new_data;                                                                     \
+        (vec).cap = new_cap;                                                                       \
+    } while (0)
+
+/**
+ * @def vec_sized_push(vec, elem_size, src_ptr)
+ * @brief 添加一个元素（从 src_ptr 拷贝 elem_size 字节）
+ * @param vec        VEC(type) 定义的向量变量（type 可为 char 或 void）
+ * @param elem_size  每个元素占用的字节数
+ * @param src_ptr    源数据的指针
+ * @param copy_size  要拷贝的字节数
+ *
+ * @note 使用前需确保 vec.data 类型与 src_ptr 无关，内部会按字节拷贝。
+ *       推荐声明时为 `VEC(char)` 或 `VEC(unsigned char)`。
+ */
+#define vec_sized_push(vec, elem_size, src_ptr, copy_size)                                         \
+    do {                                                                                           \
+        if ((vec).size >= (vec).cap) {                                                             \
+            usize new_cap = (vec).cap ? (vec).cap * 2 : 4;                                         \
+            vec_sized_realloc(vec, elem_size, new_cap);                                            \
+        }                                                                                          \
+        char *slot = (char *)(vec).data + (vec).size * (elem_size);                                \
+        __vec_memcpy(slot, (src_ptr), (copy_size));                                                \
+        (vec).size++;                                                                              \
+    } while (0)
+
+/**
+ * @def vec_sized_at_ptr(vec, elem_size, idx)
+ * @brief 获取第 idx 个元素的指针（void*）
+ * @return 指向元素的指针，需转换为具体类型使用
+ */
+#define vec_sized_at_ptr(vec, elem_size, idx) ((void *)((char *)(vec).data + (idx) * (elem_size)))
+
+/**
+ * @def vec_sized_foreach(vec, elem_size, elem_ptr_var, block)
+ * @brief 遍历所有元素
+ * @param elem_ptr_var  循环内的变量名（void* 类型）
+ * @param block         循环体语句块
+ */
+#define vec_sized_foreach(vec, elem_size, elem_ptr_var, block)                                     \
+    do {                                                                                           \
+        for (usize __i = 0; __i < (vec).size; ++__i) {                                             \
+            void *elem_ptr_var = vec_sized_at_ptr(vec, elem_size, __i);                            \
+            block;                                                                                 \
+        }                                                                                          \
+    } while (0)
+
+/**
+ * @def vec_sized_pop(vec, elem_size)
+ * @brief 弹出最后一个元素（仅减小 size，不返回数据）
+ */
+#define vec_sized_pop(vec, elem_size)                                                              \
+    do {                                                                                           \
+        if ((vec).size == 0)                                                                       \
+            LOG_FATAL("vec_sized_pop: empty\n");                                                   \
+        (vec).size--;                                                                              \
+    } while (0)
+
+/**
+ * @def vec_sized_clear(vec)
+ * @brief 清空向量（重置 size = 0，不释放内存）
+ */
+#define vec_sized_clear(vec) ((vec).size = 0)
+
+/**
+ * @def vec_sized_free(vec)
+ * @brief 释放向量内存（与原始 vec_free 相同，可复用）
+ * @note 注意：如果元素内部有堆资源，需在释放前自行遍历调用析构函数。
+ */
+#define vec_sized_free(vec) vec_free(vec)
+
+#endif /* __CORE_VEC_H__ */

stage0/include/log.c

@@ -0,0 +1,88 @@
+#include "log.h"
+
+static inline int log_snprintf(char *s, size_t n, const char *format, ...) {
+    int ret;
+    va_list args;
+    va_start(args, format);
+    ret = log_vsnprintf(s, n, format, args);
+    va_end(args);
+    return ret;
+}
+
+int log_default_handler(logger_t *module, log_level_t level, const char *file, int line,
+                        const char *func, const char *fmt, ...) {
+    const char *level_str;
+    int offset = 0;
+    va_list args;
+    va_start(args, fmt);
+    /* clang-format off */
+    switch (level) {
+    case LOG_LEVEL_DEBUG: level_str = "DEBUG"; break;
+    case LOG_LEVEL_INFO:  level_str = "INFO "; break;
+    case LOG_LEVEL_WARN:  level_str = "WARN "; break;
+    case LOG_LEVEL_ERROR: level_str = "ERROR"; break;
+    case LOG_LEVEL_FATAL: level_str = "FATAL"; break;
+    case LOG_LEVEL_TRACE: level_str = "TRACE"; break;
+    default:              level_str = "NOTSET"; break;
+    }
+/// @note: 定义 __LOG_NO_COLOR__ 会取消颜色输出
+#ifndef __LOG_NO_COLOR__
+    const char *color_code;
+    switch (level) {
+        case LOG_LEVEL_DEBUG: color_code = ANSI_FG_CYAN; break;
+        case LOG_LEVEL_INFO:  color_code = ANSI_FG_GREEN; break;
+        case LOG_LEVEL_TRACE: color_code = ANSI_FG_BLUE; break;
+        case LOG_LEVEL_WARN:  color_code = ANSI_FG_YELLOW; break;
+        case LOG_LEVEL_ERROR: color_code = ANSI_FG_RED; break;
+        case LOG_LEVEL_FATAL: color_code = ANSI_FG_RED ANSI_UNDERLINED; break;
+        default: color_code = ANSI_NONE;
+    }
+    /* clang-format on */
+    offset = log_snprintf(module->buf, sizeof(module->buf),
+                          ANSI_BOLD "%s[%s] %s - %s:%d in %s()" ANSI_NONE " ", color_code,
+                          level_str, module->name, file, line, func);
+#else
+    offset = log_snprintf(module->buf, sizeof(module->buf), "[%s] %s - %s:%d in %s() ", level_str,
+                          module->name, file, line, func);
+#endif
+    /* 然后写入用户消息（如果有） */
+    if (fmt && fmt[0]) {
+        log_vsnprintf(module->buf + offset, sizeof(module->buf) - offset, fmt, args);
+    }
+    va_end(args);
+    log_puts(module->buf);
+    // for clangd warning
+    // clang-analyzer-deadcode.DeadStores
+    (void)color_code;
+    (void)level_str;
+    if (level & LOG_LEVEL_FATAL) {
+        log_abort();
+    }
+    return 0;
+}
+
+logger_t __default_logger_root = {
+    .name = "root",
+    .level = LOG_LEVEL_ALL,
+    .handler = log_default_handler,
+};
+
+void init_logger(logger_t *logger, const char *name) {
+    logger->name = name;
+    logger->handler = log_default_handler;
+    log_set_level(logger, LOG_LEVEL_ALL);
+}
+
+void log_set_level(logger_t *logger, int level) {
+    if (logger)
+        logger->level = level;
+    else
+        __default_logger_root.level = level;
+}
+
+void log_set_handler(logger_t *logger, log_handler handler) {
+    if (logger)
+        logger->handler = handler;
+    else
+        __default_logger_root.handler = handler;
+}

stage0/include/log.h

@@ -0,0 +1,193 @@
+/**
+ * @file log.h
+ * @brief 日志系统核心模块（支持多级日志、断言和异常处理）
+ */
+
+#ifndef __SCC_LOG_IMPL_H__
+#define __SCC_LOG_IMPL_H__
+
+#include "color.h"
+#include <stdarg.h>
+
+#ifdef __SCC_LOG_IMPL_USE_STD_IMPL__
+#include <stdio.h>
+#include <stdlib.h>
+#define log_vsnprintf vsnprintf
+#define log_puts puts
+#define log_abort() exit(1)
+#endif
+
+#ifdef __GNUC__ // GCC, Clang
+#define __scc_log_unreachable() (__builtin_unreachable())
+#elif defined _MSC_VER // MSVC
+#define __scc_log_unreachable() (__assume(false))
+#elif defined __SCC_BUILTIN_UNREACHEABLE__ // The SCC Compiler (my compiler)
+#define __scc_log_unreachable() (__scc_builtin_unreachable())
+#else
+#define __scc_log_unreachable() ((void)0)
+#endif
+
+#ifndef log_vsnprintf
+#define log_vsnprintf(...)
+#warning "log_vsnprintf not defined"
+#endif
+
+#ifndef log_puts
+#define log_puts(...)
+#warning "log_puts not defined"
+#endif
+
+#ifndef log_abort
+#define log_abort(...)
+#warning "log_abort not defined"
+#endif
+
+/**
+ * @brief 日志级别枚举
+ *
+ * 定义日志系统的输出级别和组合标志位
+ */
+typedef enum log_level {
+    LOG_LEVEL_NOTSET = 0,     ///< 未设置级别（继承默认配置）
+    LOG_LEVEL_DEBUG = 1 << 0, ///< 调试信息（开发阶段详细信息）
+    LOG_LEVEL_INFO = 1 << 1,  ///< 常规信息（系统运行状态）
+    LOG_LEVEL_WARN = 1 << 2,  ///< 警告信息（潜在问题提示）
+    LOG_LEVEL_ERROR = 1 << 3, ///< 错误信息（可恢复的错误）
+    LOG_LEVEL_FATAL = 1 << 4, ///< 致命错误（导致程序终止的严重错误）
+    LOG_LEVEL_TRACE = 1 << 5, ///< 追踪（性能追踪或者栈帧追踪）
+    LOG_LEVEL_ALL = 0xFF,     ///< 全级别标志（组合所有日志级别）
+} log_level_t;
+
+#ifndef LOGGER_MAX_BUF_SIZE
+#define LOGGER_MAX_BUF_SIZE 512 ///< 单条日志最大缓冲区尺寸
+#endif
+
+typedef struct logger logger_t;
+
+typedef int (*log_handler)(logger_t *module, log_level_t level, const char *file, int line,
+                           const char *func, const char *fmt, ...);
+
+/**
+ * @brief 日志器实例结构体
+ *
+ * 每个日志器实例维护独立的配置和缓冲区
+ */
+struct logger {
+    const char *name;  ///< 日志器名称（用于模块区分）
+    log_level_t level; ///< 当前设置的日志级别
+    union {
+        log_handler handler;
+        void *user_handler;
+    }; ///< 日志处理回调函数
+    void *user_data;               ///< 用户自定义数据
+    char buf[LOGGER_MAX_BUF_SIZE]; ///< 格式化缓冲区
+};
+
+int log_default_handler(logger_t *module, log_level_t level, const char *file, int line,
+                        const char *func, const char *fmt, ...);
+extern logger_t __default_logger_root;
+#ifndef LOG_DEFAULT_HANDLER
+#define LOG_DEFAULT_HANDLER &__default_logger_root
+#endif
+
+/**
+ * @brief 初始化日志实例 其余参数设置为默认值
+ * @param[in] logger 日志器实例指针
+ * @param[in] name 日志器名称（nullptr表示获取默认日志器名称）
+ */
+void init_logger(logger_t *logger, const char *name);
+
+/**
+ * @brief 设置日志级别
+ * @param[in] logger 目标日志器实例
+ * @param[in] level 要设置的日志级别（可组合多个级别）
+ */
+void log_set_level(logger_t *logger, int level);
+
+/**
+ * @brief 设置自定义日志处理器
+ * @param[in] logger 目标日志器实例
+ * @param[in] handler 自定义处理函数（nullptr恢复默认处理）
+ */
+void log_set_handler(logger_t *logger, log_handler handler);
+
+#ifndef LOG_MAX_MAROC_BUF_SIZE
+#define LOG_MAX_MAROC_BUF_SIZE LOGGER_MAX_BUF_SIZE ///< 宏展开缓冲区尺寸
+#endif
+
+#define SCC_LOG_HANDLE_ARGS(_module_, _level_, ...)                                                \
+    (_module_), (_level_), __FILE__, __LINE__, __func__, ##__VA_ARGS__
+
+#define SCC_LOG_IMPL(_module_, _level_, _fmt_, ...)                                                \
+    do {                                                                                           \
+        /* TODO check _module_ is nullptr */                                                       \
+        if ((_module_)->handler && ((_module_)->level & (_level_)))                                \
+            (_module_)->handler(SCC_LOG_HANDLE_ARGS(_module_, _level_, _fmt_, ##__VA_ARGS__));     \
+    } while (0)
+
+/* clang-format off */
+/// @name 模块日志宏
+/// @{
+#define MLOG_NOTSET(module, ...)SCC_LOG_IMPL(module, LOG_LEVEL_NOTSET, __VA_ARGS__) ///< 未分类日志
+#define MLOG_DEBUG(module, ...) SCC_LOG_IMPL(module, LOG_LEVEL_DEBUG, __VA_ARGS__) ///< 调试日志（需启用DEBUG级别）
+#define MLOG_INFO(module, ...)  SCC_LOG_IMPL(module, LOG_LEVEL_INFO, __VA_ARGS__) ///< 信息日志（常规运行日志）
+#define MLOG_WARN(module, ...)  SCC_LOG_IMPL(module, LOG_LEVEL_WARN, __VA_ARGS__) ///< 警告日志（潜在问题）
+#define MLOG_ERROR(module, ...) SCC_LOG_IMPL(module, LOG_LEVEL_ERROR, __VA_ARGS__) ///< 错误日志（可恢复错误）
+#define MLOG_FATAL(module, ...) SCC_LOG_IMPL(module, LOG_LEVEL_FATAL, __VA_ARGS__) ///< 致命错误日志（程序终止前）
+#define MLOG_TRACE(module, ...) SCC_LOG_IMPL(module, LOG_LEVEL_TRACE, __VA_ARGS__) ///< 追踪日志（调用栈跟踪）
+/// @}
+
+/// @name 快捷日志宏
+/// @{
+#define LOG_NOTSET(...) SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_NOTSET, __VA_ARGS__) ///< 未分类日志
+#define LOG_DEBUG(...)  SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_DEBUG, __VA_ARGS__) ///< 调试日志（需启用DEBUG级别）
+#define LOG_INFO(...)   SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_INFO, __VA_ARGS__) ///< 信息日志（常规运行日志）
+#define LOG_WARN(...)   SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_WARN, __VA_ARGS__) ///< 警告日志（潜在问题）
+#define LOG_ERROR(...)  SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_ERROR, __VA_ARGS__) ///< 错误日志（可恢复错误）
+#define LOG_FATAL(...)  SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_FATAL, __VA_ARGS__) ///< 致命错误日志（程序终止前）
+#define LOG_TRACE(...)  SCC_LOG_IMPL(LOG_DEFAULT_HANDLER, LOG_LEVEL_TRACE, __VA_ARGS__) ///< 追踪日志（调用栈跟踪）
+/// @}
+/* clang-format on */
+
+/**
+ * @def _Assert
+ * @brief 断言检查内部宏
+ * @param cond 检查条件表达式
+ * @param ... 错误信息参数（格式字符串+参数）
+ */
+#define _Assert(cond, ...)                                                                         \
+    ((void)((cond) || (__default_logger_root.handler(SCC_LOG_HANDLE_ARGS(                          \
+                           &__default_logger_root, LOG_LEVEL_FATAL, __VA_ARGS__)),                 \
+                       log_abort(), __scc_log_unreachable(), 0)))
+
+/// @name 断言工具宏
+/// @{
+#define __INNERSCC_LOG_IMPL_STR(str) #str
+#define _SCC_LOG_IMPL_STR(str) __INNERSCC_LOG_IMPL_STR(str)
+#define AssertFmt(cond, format, ...)                                                               \
+    _Assert(cond, "Assertion Failure: " format, ##__VA_ARGS__)                ///< 带格式的断言检查
+#define PanicFmt(format, ...) _Assert(0, "Panic: " format, ##__VA_ARGS__)     ///< 立即触发致命错误
+#define Assert(cond) AssertFmt(cond, "cond is `" _SCC_LOG_IMPL_STR(cond) "`") ///< 基础断言检查
+#define Panic(...) PanicFmt(__VA_ARGS__)                     ///< 触发致命错误（带自定义消息）
+#define TODO() PanicFmt("TODO please implement me")          ///< 标记未实现代码（触发致命错误）
+#define UNREACHABLE() PanicFmt("UNREACHABLE")                ///< 触发致命错误（代码不可达）
+#define FIXME(str) PanicFmt("FIXME " _SCC_LOG_IMPL_STR(str)) ///< 提醒开发者修改代码（触发致命错误）
+/// @}
+
+/**
+ * @brief 静态断言（编译时）
+ *
+ * 利用数组大小不能为负的特性
+ * 或使用 _Static_assert (C11)
+ */
+#if __STDC_VERSION__ >= 201112L
+#define StaticAssert _Static_assert
+#else
+#define StaticAssert(cond, msg) extern char __static_assertion[(cond) ? 1 : -1]
+#endif
+
+#ifdef __SCC_LOG_IMPL_IMPORT_SRC__
+#include "log.c"
+#endif
+
+#endif /* __SCC_LOG_IMPL_H__ */

stage0/include/utils.h

@@ -0,0 +1,10 @@
+#ifndef __UTILS_H__
+#define __UTILS_H__
+
+#define __SCC_LOG_IMPL_USE_STD_IMPL__
+#include "log.h"
+
+#include "core_map.h"
+#include "core_vec.h"
+
+#endif /* __UTILS_H__ */

stage0/spl_cli.c

@@ -0,0 +1,699 @@
+/* spl_cli.c SIR VM launcher + gdb-style interactive debugger
+ *
+ * Usage:  spl_cli [options] <file.sir> [args...]
+ *   -d, --debug       stack-canary checks
+ *   -g, --debug-cli   interactive debugger (REPL)
+ *   --entry <name>    entry function (default: main)
+ *   --trace           print every instruction
+ *   -h, --help        show help
+ *
+ * spl 程序 argv：argv[0]=file.sir，argv[1..]=args。
+ * REPL 配合 splc0 -g（.sir 尾部内嵌 debug 段：IR 行 + VAR 行）可显示
+ * 当前 IR 节点/源行/局部变量。
+ */
+
+#include "spl_mcode.h"
+#include "spl_syscall.h"
+#include "spl_vm.h"
+
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ================================================================
+ * 命令行解析
+ * ================================================================ */
+
+typedef struct {
+    int debug;
+    int debug_cli;
+    int trace;
+    int disasm;
+    const char *entry;
+    const char *path;  /* file.sir */
+    const char **args; /* spl 程序参数（file.sir 之后） */
+    int nargs;
+} cli_opts_t;
+
+static void usage(void) {
+    fprintf(stderr, "Usage: spl_cli [options] <file.sir> [args...]\n"
+                    "  -d, --debug       stack-canary checks\n"
+                    "  -g, --debug-cli   interactive debugger (REPL)\n"
+                    "  --disasm          disasm dump sir\n"
+                    "  --entry <name>    entry function (default: main)\n"
+                    "  --trace           print every instruction\n"
+                    "  -h, --help        show help\n");
+}
+
+/* options 可穿插；`--` 终止 option 解析（本身不作为 file/args）。
+ * 第一个非 option 为 file.sir，其后为 spl args。 */
+static int parse_args(int argc, const char **argv, cli_opts_t *o) {
+    memset(o, 0, sizeof *o);
+    o->entry = "main";
+    int i = 1;
+    for (; i < argc; i++) {
+        const char *a = argv[i];
+        if (a[0] == '-' && a[1]) {
+            if (strcmp(a, "--") == 0) {
+                i++;
+                break;
+            }
+            if (strcmp(a, "-d") == 0 || strcmp(a, "--debug") == 0) {
+                o->debug = 1;
+            } else if (strcmp(a, "-g") == 0 || strcmp(a, "--debug-cli") == 0) {
+                o->debug_cli = 1;
+            } else if (strcmp(a, "--trace") == 0) {
+                o->trace = 1;
+            } else if (strcmp(a, "--disasm") == 0) {
+                o->disasm = 1;
+            } else if (strcmp(a, "--entry") == 0) {
+                if (i + 1 >= argc) {
+                    fprintf(stderr, "spl_cli: --entry needs a name\n");
+                    return -1;
+                }
+                o->entry = argv[++i];
+            } else if (strcmp(a, "-h") == 0 || strcmp(a, "--help") == 0) {
+                usage();
+                return -1;
+            } else {
+                fprintf(stderr, "spl_cli: unknown option '%s'\n", a);
+                usage();
+                return -1;
+            }
+        } else {
+            break;
+        }
+    }
+    /* 跳过前导 `--`（pipeline 调用会带 `--` 分隔 file 与 args） */
+    while (i < argc && strcmp(argv[i], "--") == 0)
+        i++;
+    if (i >= argc) {
+        fprintf(stderr, "spl_cli: missing <file.sir>\n");
+        usage();
+        return -1;
+    }
+    o->path = argv[i++];
+    while (i < argc && strcmp(argv[i], "--") == 0)
+        i++;
+    o->args = argv + i;
+    o->nargs = argc - i;
+    return 0;
+}
+
+/* ================================================================
+ * Debug map（splc0 -g 追加在 .sir 尾部的文本段）
+ *   IR  <ip> <node_ref> <line> <kind>
+ *   VAR <func> <name> <fp_offset> <tid> <is_param>
+ * ================================================================ */
+
+typedef struct {
+    usize ip;
+    usize ref;
+    int line;
+    char kind[64];
+} dbg_irline_t;
+typedef VEC(dbg_irline_t) dbg_irline_vec_t;
+
+typedef struct {
+    char func[128];
+    char name[128];
+    usize offset;
+    usize tid;
+    int is_param;
+} dbg_var_t;
+typedef VEC(dbg_var_t) dbg_var_vec_t;
+
+typedef struct {
+    dbg_irline_vec_t irlines;
+    dbg_var_vec_t vars;
+    int loaded;
+} dbg_map_t;
+
+static void dbg_map_load(dbg_map_t *m, const char *text) {
+    memset(m, 0, sizeof *m);
+    vec_init(m->irlines);
+    vec_init(m->vars);
+    m->loaded = 0;
+    if (!text)
+        return;
+    const char *p = strstr(text, "SPLDBG");
+    if (!p)
+        return;
+    p += 6;
+    while (p && *p) {
+        const char *nl = strchr(p, '\n');
+        size_t len = nl ? (size_t)(nl - p) : strlen(p);
+        char line[512];
+        if (len >= sizeof line)
+            len = sizeof line - 1;
+        memcpy(line, p, len);
+        line[len] = 0;
+        if (strncmp(line, "IR ", 3) == 0) {
+            dbg_irline_t ir;
+            memset(&ir, 0, sizeof ir);
+            sscanf(line + 3, "%zu %zu %d %63s", &ir.ip, &ir.ref, &ir.line, ir.kind);
+            vec_push(m->irlines, ir);
+        } else if (strncmp(line, "VAR ", 4) == 0) {
+            dbg_var_t v;
+            memset(&v, 0, sizeof v);
+            sscanf(line + 4, "%127s %127s %zu %zu %d", v.func, v.name, &v.offset, &v.tid,
+                   &v.is_param);
+            vec_push(m->vars, v);
+        }
+        if (!nl)
+            break;
+        p = nl + 1;
+    }
+    m->loaded = 1;
+}
+
+/* 当前 ip 所属 IR 节点行（ip 恰好是某节点首指令） */
+static const dbg_irline_t *irline_at_exact(dbg_map_t *m, usize ip) {
+    for (usize i = 0; i < m->irlines.size; i++)
+        if (m->irlines.data[i].ip == ip)
+            return &m->irlines.data[i];
+    return NULL;
+}
+
+/* ================================================================
+ * 调试器核心
+ * ================================================================ */
+
+typedef struct {
+    spl_vm_t *vm;
+    spl_prog_t *prog;
+    const char *entry;
+    dbg_map_t map;
+    usize last_ptr; /* p 最近读到的值（x 无参重读） */
+    int quit;
+} dbg_t;
+
+/* ---- 位置/指令显示辅助 ---- */
+
+static const char *fn_name_at(spl_prog_t *prog, usize ip) {
+    for (usize i = 0; i < vec_size(prog->funcs); i++) {
+        spl_vm_func_t *f = &vec_at(prog->funcs, i);
+        if (ip >= f->address && ip < f->address + f->ninsns)
+            return f->name ? f->name : "?";
+    }
+    return "?";
+}
+
+/* ip 所在函数的指令范围 [*start, *end) */
+static void cur_func_bounds(spl_prog_t *prog, usize ip, usize *start, usize *end) {
+    *start = 0;
+    *end = vec_size(prog->insns);
+    for (usize i = 0; i < vec_size(prog->funcs); i++) {
+        spl_vm_func_t *f = &vec_at(prog->funcs, i);
+        if (ip >= f->address && ip < f->address + f->ninsns) {
+            *start = f->address;
+            *end = f->address + f->ninsns;
+            return;
+        }
+    }
+}
+
+/* 格式化一条指令（不含行号前缀） */
+static void fmt_insn(const spl_vm_ins_t *ins, char *buf, size_t n) {
+    snprintf(buf, n, "%-11s %-5s %zu", spl_vm_opcode_name(ins->opcode),
+             spl_vm_type_kind_name(ins->type), ins->imm);
+}
+
+static void dbg_show_location(dbg_t *d) {
+    spl_vm_t *vm = d->vm;
+    if (vm->ip >= vec_size(vm->prog->insns)) {
+        printf("  (end of program)\n");
+        return;
+    }
+    char ib[80];
+    fmt_insn(&vec_at(vm->prog->insns, vm->ip), ib, sizeof ib);
+    printf("  %s @ ip=%zu   %s   [sp=%zu fp=%zu cp=%zu]\n", fn_name_at(vm->prog, vm->ip), vm->ip,
+           ib, vm->sp, vm->fp, vm->cp);
+    const dbg_irline_t *ir = irline_at_exact(&d->map, vm->ip);
+    if (ir)
+        printf("     -> ir node#%zu line %d  %s\n", ir->ref, ir->line, ir->kind);
+}
+
+static void dbg_handle_status(dbg_t *d, int r) {
+    if (r == 1) {
+        printf("  program halted, exit_code=%d\n", d->vm->exit_code);
+        d->quit = 1;
+    } else if (r == 2) {
+        printf("  breakpoint hit\n");
+    } else if (r == -1) {
+        printf("  VM error: %s\n", d->vm->error_msg[0] ? d->vm->error_msg : "(no detail)");
+        d->quit = 1;
+    }
+}
+
+/* ---- 变量查找（p / x 复用） ---- */
+
+static dbg_var_t *dbg_find_var(dbg_t *d, const char *fn, const char *name) {
+    for (usize i = 0; i < d->map.vars.size; i++) {
+        dbg_var_t *v = &d->map.vars.data[i];
+        if (strcmp(v->func, fn) == 0 && strcmp(v->name, name) == 0)
+            return v;
+    }
+    return NULL;
+}
+
+/* ================================================================
+ * 命令
+ * ================================================================ */
+
+static int cmd_help(dbg_t *d, const char *args);
+static int cmd_run(dbg_t *d, const char *args);
+static int cmd_step(dbg_t *d, const char *args);
+static int cmd_next(dbg_t *d, const char *args);
+static int cmd_finish(dbg_t *d, const char *args);
+static int cmd_break(dbg_t *d, const char *args);
+static int cmd_delete(dbg_t *d, const char *args);
+static int cmd_info(dbg_t *d, const char *args);
+static int cmd_list(dbg_t *d, const char *args);
+static int cmd_backtrace(dbg_t *d, const char *args);
+static int cmd_stack(dbg_t *d, const char *args);
+static int cmd_x(dbg_t *d, const char *args);
+static int cmd_p(dbg_t *d, const char *args);
+static int cmd_quit(dbg_t *d, const char *args);
+
+typedef struct {
+    const char *name;
+    const char *alias;
+    const char *usage;
+    const char *help;
+    int (*fn)(dbg_t *, const char *);
+} dbg_cmd_t;
+
+static const dbg_cmd_t cmds[] = {
+    /* 会话 */
+    {"help", "h", "[cmd]", "list commands / help", cmd_help},
+    {"quit", "q", "", "quit debugger", cmd_quit},
+    /* 执行 */
+    {"run", "r", "", "run to next breakpoint or exit", cmd_run},
+    {"continue", "c", "", "alias of run", cmd_run},
+    {"step", "s", "", "step one instruction (into calls)", cmd_step},
+    {"next", "n", "", "step over a call", cmd_next},
+    {"finish", "f", "", "run until current function returns", cmd_finish},
+    /* 断点 */
+    {"break", "b", "<fn|ip>", "set breakpoint (no arg: list)", cmd_break},
+    {"delete", "d", "", "clear all breakpoints", cmd_delete},
+    /* 信息 */
+    {"info", "i", "b|stack|locals|args|var", "breakpoints/stack/locals", cmd_info},
+    {"list", "l", "[N]", "disassemble ip±N of current function", cmd_list},
+    {"backtrace", "bt", "", "print call stack backtrace", cmd_backtrace},
+    {"stack", "st", "", "dump stack words", cmd_stack},
+    /* 内存/变量 */
+    {"x", "x", "<var|addr|fp+N>", "read memory (no arg: last pointer)", cmd_x},
+    {"print", "p", "<var>", "print local variable (needs splc0 -g)", cmd_p},
+    {NULL, NULL, NULL, NULL, NULL},
+};
+
+static const dbg_cmd_t *find_cmd(const char *name) {
+    for (const dbg_cmd_t *c = cmds; c->name; c++)
+        if (!strcmp(c->name, name) || (c->alias && !strcmp(c->alias, name)))
+            return c;
+    return NULL;
+}
+
+static int cmd_help(dbg_t *d, const char *args) {
+    (void)d;
+    if (*args) {
+        const dbg_cmd_t *c = find_cmd(args);
+        if (c) {
+            printf("  %-10s %-22s %s", c->name, c->usage, c->help);
+            if (c->alias)
+                printf("   (alias: %s)", c->alias);
+            printf("\n");
+        } else {
+            printf("  unknown command '%s'\n", args);
+        }
+        return 0;
+    }
+    printf("commands:\n");
+    for (const dbg_cmd_t *c = cmds; c->name; c++) {
+        printf("  %-10s %-22s %s", c->name, c->usage, c->help);
+        if (c->alias)
+            printf("   (alias: %s)", c->alias);
+        printf("\n");
+    }
+    return 0;
+}
+
+/* ---- 执行 ---- */
+
+static int ip_is_breakpoint(dbg_t *d) {
+    for (usize i = 0; i < vec_size(d->vm->breakpoints); i++)
+        if (d->vm->breakpoints.data[i] == (usize)d->vm->ip)
+            return 1;
+    return 0;
+}
+
+static int cmd_run(dbg_t *d, const char *args) {
+    (void)args;
+    if (ip_is_breakpoint(d)) /* 越过当前断点指令，避免原地重停 */
+        spl_vm_skip_breakpoint(d->vm);
+    dbg_handle_status(d, spl_vm_run_until(d->vm, 0));
+    return 0;
+}
+
+static int cmd_step(dbg_t *d, const char *args) {
+    (void)args;
+    dbg_handle_status(d, spl_vm_run_once(d->vm));
+    return 0;
+}
+
+static int cmd_next(dbg_t *d, const char *args) {
+    (void)args;
+    /* 执行 1 条；若进入被调（cp 增），继续执行到返回原深度 */
+    usize base_cp = d->vm->cp;
+    int r = spl_vm_run_once(d->vm);
+    if (r)
+        return dbg_handle_status(d, r), 0;
+    while (d->vm->cp > base_cp) {
+        r = spl_vm_run_once(d->vm);
+        if (r)
+            return dbg_handle_status(d, r), 0;
+    }
+    return 0;
+}
+
+static int cmd_finish(dbg_t *d, const char *args) {
+    (void)args;
+    usize base_cp = d->vm->cp;
+    while (d->vm->cp >= base_cp) {
+        int r = spl_vm_run_once(d->vm);
+        if (r)
+            return dbg_handle_status(d, r), 0;
+    }
+    return 0;
+}
+
+/* ---- 断点 ---- */
+
+static int is_all_digits(const char *s) {
+    if (!*s)
+        return 0;
+    for (; *s; s++)
+        if (!isdigit((unsigned char)*s))
+            return 0;
+    return 1;
+}
+
+static int cmd_break(dbg_t *d, const char *args) {
+    if (!*args) {
+        printf("  ip breakpoints:\n");
+        for (usize i = 0; i < vec_size(d->vm->breakpoints); i++)
+            printf("    %zu\n", d->vm->breakpoints.data[i]);
+        printf("  fn breakpoints:\n");
+        for (usize i = 0; i < vec_size(d->vm->fn_breakpoints); i++)
+            printf("    %s\n", d->vm->fn_breakpoints.data[i]);
+        return 0;
+    }
+    while (*args && isspace((unsigned char)*args))
+        args++;
+    if (is_all_digits(args)) {
+        usize ip = (usize)strtoul(args, NULL, 10);
+        spl_vm_add_breakpoint(d->vm, ip);
+        printf("  breakpoint at ip=%zu\n", ip);
+    } else {
+        spl_vm_add_breakpoint_fn(d->vm, args);
+        printf("  breakpoint at function '%s'\n", args);
+    }
+    return 0;
+}
+
+static int cmd_delete(dbg_t *d, const char *args) {
+    (void)args;
+    spl_vm_clear_breakpoints(d->vm);
+    printf("  breakpoints cleared\n");
+    return 0;
+}
+
+/* ---- 信息 ---- */
+
+/* 列出当前函数变量：args_flag=1 列参数，local_flag=1 列局部 */
+static void list_vars(dbg_t *d, int args_flag, int local_flag) {
+    if (!d->map.loaded) {
+        printf("  no debug info (compile with splc0 -g)\n");
+        return;
+    }
+    const char *fn = fn_name_at(d->prog, d->vm->ip);
+    int any = 0;
+    for (usize i = 0; i < d->map.vars.size; i++) {
+        dbg_var_t *v = &d->map.vars.data[i];
+        if (strcmp(v->func, fn) != 0)
+            continue;
+        if ((v->is_param && !args_flag) || (!v->is_param && !local_flag))
+            continue;
+        printf("  %-20s @ fp+%-5zu %s\n", v->name, v->offset, v->is_param ? "[param]" : "[local]");
+        any = 1;
+    }
+    if (!any)
+        printf("  (no matching variables in %s)\n", fn);
+}
+
+static int cmd_info(dbg_t *d, const char *args) {
+    while (*args && isspace((unsigned char)*args))
+        args++;
+    if (!strncmp(args, "b", 1) || !strncmp(args, "break", 5))
+        return cmd_break(d, "");
+    if (!strncmp(args, "st", 2) || !strncmp(args, "stack", 5))
+        spl_vm_stackdump(d->vm, d->vm->sp);
+    else if (!strncmp(args, "l", 1) || !strncmp(args, "local", 5))
+        list_vars(d, 0, 1);
+    else if (!strncmp(args, "a", 1) || !strncmp(args, "arg", 3))
+        list_vars(d, 1, 0);
+    else if (!strncmp(args, "v", 1) || !strncmp(args, "var", 3))
+        list_vars(d, 1, 1);
+    else
+        printf("  usage: info b|stack|locals|args|var\n");
+    return 0;
+}
+
+/* l [N]：当前函数内 ip±N 反汇编 */
+static int cmd_list(dbg_t *d, const char *args) {
+    usize ip = d->vm->ip;
+    long half = 5;
+    if (*args)
+        half = strtol(args, NULL, 10);
+    if (half < 0)
+        half = 0;
+    usize fstart, fend;
+    cur_func_bounds(d->prog, ip, &fstart, &fend);
+    usize lo = (ip > (usize)half) ? ip - (usize)half : fstart;
+    usize hi = ip + (usize)half;
+    if (hi >= fend)
+        hi = fend - 1;
+    if (lo < fstart)
+        lo = fstart;
+    for (usize i = lo; i <= hi; i++) {
+        char ib[80];
+        fmt_insn(&vec_at(d->prog->insns, i), ib, sizeof ib);
+        printf("%s%6zu: %s", i == ip ? "=>" : "  ", i, ib);
+        const dbg_irline_t *ir = irline_at_exact(&d->map, i);
+        if (ir)
+            printf("   || node#%zu line %d %s", ir->ref, ir->line, ir->kind);
+        printf("\n");
+    }
+    return 0;
+}
+
+static int cmd_backtrace(dbg_t *d, const char *args) {
+    (void)args;
+    spl_vm_backtrace(d->vm, d->vm->fp);
+    return 0;
+}
+
+static int cmd_stack(dbg_t *d, const char *args) {
+    (void)args;
+    spl_vm_stackdump(d->vm, d->vm->sp);
+    return 0;
+}
+
+/* ---- 内存 / 变量 ---- */
+
+static int cmd_x(dbg_t *d, const char *args) {
+    while (*args && isspace((unsigned char)*args))
+        args++;
+    unsigned long long addr = 0;
+    if (*args) {
+        if (strncmp(args, "fp+", 3) == 0 || strncmp(args, "sp+", 3) == 0) {
+            int is_fp = args[0] == 'f';
+            unsigned long long off = strtoull(args + 3, NULL, 0);
+            addr = (uintptr_t)((char *)&d->vm->stacks.data[is_fp ? d->vm->fp : d->vm->sp] + off);
+            printf("  (%s+%llu)\n", is_fp ? "fp" : "sp", off);
+        } else if (d->map.loaded && !isdigit((unsigned char)*args)) {
+            const char *fn = fn_name_at(d->prog, d->vm->ip);
+            dbg_var_t *v = dbg_find_var(d, fn, args);
+            if (v) {
+                addr = (uintptr_t)((char *)&d->vm->stacks.data[d->vm->fp] + v->offset);
+                printf("  (%s @ fp+%zu)\n", v->name, v->offset);
+            } else {
+                printf("  no variable '%s' in %s\n", args, fn);
+            }
+        } else {
+            addr = strtoull(args, NULL, 0);
+        }
+    } else {
+        addr = (unsigned long long)d->last_ptr;
+    }
+    if (!addr) {
+        printf("  usage: x <var|addr|fp+N>   (no arg: re-read last printed pointer)\n");
+        return 0;
+    }
+    unsigned char *sbase = (unsigned char *)d->vm->stacks.data;
+    usize slen = d->vm->config.max_stack_depth * sizeof(spl_vm_val_t);
+    printf("  addr=%#llx  stack=[%p,+%zu)  in=%d\n", addr, sbase, slen,
+           addr >= (uintptr_t)sbase && addr < (uintptr_t)(sbase + slen));
+    unsigned char *p = (unsigned char *)(uintptr_t)addr;
+    printf("  ");
+    for (int i = 0; i < 32; i++)
+        printf("%02x ", p[i]);
+    printf("\n");
+    return 0;
+}
+
+static int cmd_p(dbg_t *d, const char *args) {
+    while (*args && isspace((unsigned char)*args))
+        args++;
+    if (!*args) {
+        printf("  usage: p <varname>\n");
+        return 0;
+    }
+    if (!d->map.loaded) {
+        printf("  no debug info (compile with splc0 -g)\n");
+        return 0;
+    }
+    const char *fn = fn_name_at(d->prog, d->vm->ip);
+    dbg_var_t *v = dbg_find_var(d, fn, args);
+    if (!v) {
+        printf("  no variable '%s' in %s\n", args, fn);
+        return 0;
+    }
+    spl_vm_val_t *addr = (spl_vm_val_t *)((char *)&d->vm->stacks.data[d->vm->fp] + v->offset);
+    printf("  %s = %zu (0x%zx)  @ fp+%zu\n", v->name, *addr, *addr, v->offset);
+    d->last_ptr = (usize)*addr; /* 供 x 无参重读 */
+    return 0;
+}
+
+static int cmd_quit(dbg_t *d, const char *args) {
+    (void)args;
+    d->quit = 1;
+    return 0;
+}
+
+static void repl_loop(dbg_t *d) {
+    char line[1024];
+    while (!d->quit) {
+        dbg_show_location(d);
+        printf("spl-dbg> ");
+        fflush(stdout);
+        if (!fgets(line, sizeof line, stdin))
+            break;
+        char *nl = strchr(line, '\n');
+        if (nl)
+            *nl = 0;
+        char *p = line;
+        while (*p && isspace((unsigned char)*p))
+            p++;
+        if (!*p)
+            continue;
+        /* 拆命令名 + 参数 */
+        char *sp = p;
+        while (*sp && !isspace((unsigned char)*sp))
+            sp++;
+        char saved = *sp;
+        *sp = 0;
+        const dbg_cmd_t *c = find_cmd(p);
+        *sp = saved;
+        char *args = sp;
+        while (*args && isspace((unsigned char)*args))
+            args++;
+        if (c) {
+            c->fn(d, args);
+        } else {
+            printf("  unknown command '%s' (h for help)\n", p);
+        }
+    }
+}
+
+int main(int argc, const char **argv) {
+    cli_opts_t o;
+    if (parse_args(argc, argv, &o) != 0)
+        return 1;
+
+    spl_prog_t prog;
+    if (spl_prog_load_from_file(o.path, &prog) != 0) {
+        fprintf(stderr, "spl_cli: cannot load '%s'\n", o.path);
+        return 1;
+    }
+
+    if (o.disasm) {
+        spl_prog_dump(&prog);
+        return 0;
+    }
+    spl_syscall_register(&prog);
+
+    spl_vm_t vm;
+    spl_vm_init(&vm);
+    if (o.debug) {
+        fprintf(stderr, "spl_cli: debug mode on\n");
+        spl_vm_set_debug(&vm, 1);
+    }
+    if (o.trace) {
+        fprintf(stderr, "spl_cli: trace mode on\n");
+        spl_vm_set_trace(&vm, 1);
+    }
+    if (spl_vm_load_prog(&vm, &prog) != 0) {
+        fprintf(stderr, "spl_cli: failed to load prog\n");
+        spl_vm_drop(&vm);
+        spl_prog_drop(&prog);
+        return 1;
+    }
+
+    /* spl 程序 argv：argv[0]=file.sir（程序名），argv[1..]=args */
+    const char **spl_argv = (const char **)malloc(sizeof(char *) * (size_t)(o.nargs + 1));
+    if (!spl_argv) {
+        spl_vm_drop(&vm);
+        spl_prog_drop(&prog);
+        return 1;
+    }
+    spl_argv[0] = o.path;
+    for (int i = 0; i < o.nargs; i++)
+        spl_argv[i + 1] = o.args[i];
+
+    if (spl_vm_prepare(&vm, o.entry, o.nargs + 1, spl_argv, NULL) != 0) {
+        fprintf(stderr, "spl_cli: entry point '%s' not found\n", o.entry);
+        free(spl_argv);
+        spl_vm_drop(&vm);
+        spl_prog_drop(&prog);
+        return 1;
+    }
+
+    int ret = 0;
+    if (o.debug_cli) {
+        dbg_t d;
+        d.vm = &vm;
+        d.prog = &prog;
+        d.entry = o.entry;
+        d.quit = 0;
+        d.last_ptr = 0;
+        dbg_map_load(&d.map, prog.debug);
+        repl_loop(&d);
+        vec_free(d.map.irlines);
+        vec_free(d.map.vars);
+    } else {
+        ret = spl_vm_run_until(&vm, 0);
+        if (ret == 2)
+            fprintf(stderr, "spl_cli: hit breakpoint (run with -g to debug)\n");
+    }
+
+    free(spl_argv);
+    spl_vm_drop(&vm);
+    spl_prog_drop(&prog);
+
+    if (ret < 0)
+        return 1;
+    return (int)vm.exit_code;
+}

stage0/spl_mcode.c

@@ -0,0 +1,532 @@
+/* spl_mcode.c - SPL VM machine code binary serialization, deserialization, and utilities
+ *
+ * Binary format (all metadata fields are spl_val_t = uint64_t LE):
+ *   [HEADER]     magic(8) nfuncs(8) ninsns(8) nnatives(8) nstrs(8) ndata(8)
+ *   [FUNCS]      each: name_len(8) name(padded to 8) idx_of_strtab(8)
+ *                       nargs(8) ninsns(8) address(8)
+ *   [INSTRS]     each: opcode(2) type(2) imm(8) = 12 bytes
+ *   [NATIVES]    each: name_len(8) name(padded to 8) idx_of_strtab(8)
+ *   [STRTAB]     each: slen(8) str(slen bytes, padded to 8)
+ */
+
+#include "spl_mcode.h"
+
+void spl_prog_init(spl_prog_t *prog) {
+    if (!prog)
+        return;
+    vec_init(prog->insns);
+    vec_init(prog->funcs);
+    vec_init(prog->natives);
+    vec_init(prog->strtab);
+    vec_init(prog->gdata);
+    vec_push(prog->gdata, (spl_vm_gdata_t){0});
+    map_init(prog->symtab, MAP_HASH_STR, MAP_CMP_STR);
+    prog->debug = NULL;
+}
+
+void spl_prog_drop(spl_prog_t *prog) {
+    if (!prog)
+        return;
+    vec_free(prog->insns);
+    /* free each func name */
+    vec_for(prog->funcs, i) { free(vec_at(prog->funcs, i).name); }
+    vec_free(prog->funcs);
+    /* free each native name */
+    vec_for(prog->natives, i) { free(vec_at(prog->natives, i).name); }
+    vec_free(prog->natives);
+    /* free each gdata entry */
+    vec_for(prog->gdata, i) { free(vec_at(prog->gdata, i).data); }
+    vec_free(prog->gdata);
+    /* free each strtab entry */
+    vec_for(prog->strtab, i) { free((void *)vec_at(prog->strtab, i)); }
+    vec_free(prog->strtab);
+    map_free(prog->symtab);
+    if (prog->debug) {
+        free(prog->debug);
+    }
+    prog->debug = NULL;
+}
+
+void spl_prog_dump(spl_prog_t *prog) {
+    printf(";; SPL bytecode dump: \n");
+    printf(";; ninsns=%zu nfuncs=%zu nnatives=%zu nstrs=%zu\n\n", vec_size(prog->insns),
+           vec_size(prog->funcs), vec_size(prog->natives), vec_size(prog->strtab));
+
+    if (vec_size(prog->funcs) > 0) {
+        printf(";; --- functions ---\n");
+        for (usize i = 0; i < vec_size(prog->funcs); i++) {
+            spl_vm_func_t *f = &vec_at(prog->funcs, i);
+            printf("  %s  nargs=%zu ninsns=%zu addr=%zu\n", f->name ? f->name : "(anon)", f->nargs,
+                   f->ninsns, f->address);
+        }
+        printf("\n");
+    }
+
+    if (vec_size(prog->natives) > 0) {
+        printf(";; --- natives ---\n");
+        for (int i = 0; i < (int)vec_size(prog->natives); i++) {
+            spl_vm_native_t *n = &vec_at(prog->natives, i);
+            printf("  %s\n", n->name ? n->name : "(anon)");
+        }
+        printf("\n");
+    }
+
+    if (vec_size(prog->strtab) > 0) {
+        printf(";; --- string table ---\n");
+        for (int i = 0; i < (int)vec_size(prog->strtab); i++) {
+            printf("  %d: \"%s\"\n", i, vec_at(prog->strtab, i));
+        }
+        printf("\n");
+    }
+
+    printf(";; --- instructions ---\n");
+    for (usize i = 0; i < vec_size(prog->insns); i++) {
+        spl_vm_ins_t *ins = &vec_at(prog->insns, i);
+        printf("%4zd: %s", i, spl_vm_opcode_name((spl_vm_opcode_t)ins->opcode));
+        if (ins->type != SPL_VOID)
+            printf(" %s", spl_vm_type_kind_name((spl_vm_kind_t)ins->type));
+        printf(" %zd", ins->imm);
+
+        /* annotate jumps / calls */
+        if (ins->opcode == SPL_JMP || ins->opcode == SPL_BZ || ins->opcode == SPL_BNZ) {
+            spl_vm_val_t target = i + 1 + ins->imm;
+            printf("  ; -> %zu", target);
+        } else if (ins->opcode == SPL_CALL) {
+            printf("  ; nargs=%zu, from stack", ins->imm);
+        } else if (ins->opcode == SPL_CALLI) {
+            printf("  ; indirect call");
+        } else if (ins->opcode == SPL_GADDR) {
+            printf("  ; gdata[%zu]", ins->imm);
+        }
+        printf("\n");
+    }
+}
+
+/* ---- LE read/write helpers ---- */
+
+static inline spl_vm_val_t rd64(const unsigned char **p) {
+    spl_vm_val_t v = (spl_vm_val_t)(*p)[0] | ((spl_vm_val_t)(*p)[1] << 8) |
+                     ((spl_vm_val_t)(*p)[2] << 16) | ((spl_vm_val_t)(*p)[3] << 24) |
+                     ((spl_vm_val_t)(*p)[4] << 32) | ((spl_vm_val_t)(*p)[5] << 40) |
+                     ((spl_vm_val_t)(*p)[6] << 48) | ((spl_vm_val_t)(*p)[7] << 56);
+    *p += 8;
+    return v;
+}
+
+static inline void wr64(unsigned char **p, spl_vm_val_t v) {
+    *(*p)++ = (unsigned char)(v);
+    *(*p)++ = (unsigned char)(v >> 8);
+    *(*p)++ = (unsigned char)(v >> 16);
+    *(*p)++ = (unsigned char)(v >> 24);
+    *(*p)++ = (unsigned char)(v >> 32);
+    *(*p)++ = (unsigned char)(v >> 40);
+    *(*p)++ = (unsigned char)(v >> 48);
+    *(*p)++ = (unsigned char)(v >> 56);
+}
+
+/* Round n up to next multiple of 8 */
+#define ALIGN8(n) (((n) + 7) & ~7)
+
+int spl_prog_load_from_file(const char *fname, spl_prog_t *prog) {
+    FILE *f;
+    unsigned char *data;
+    long len;
+    const unsigned char *p;
+    spl_vm_val_t nfuncs, ninsns, nnatives, nstrs, ndata;
+
+    if (!fname || !prog)
+        return -1;
+
+    f = fopen(fname, "rb");
+    if (!f)
+        return -1;
+    fseek(f, 0, SEEK_END);
+    len = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    if (len < 48) {
+        fclose(f);
+        return -1;
+    }
+    data = (unsigned char *)malloc((size_t)len);
+    if (!data) {
+        fclose(f);
+        return -1;
+    }
+    if (fread(data, 1, (size_t)len, f) != (size_t)len) {
+        free(data);
+        fclose(f);
+        return -1;
+    }
+    fclose(f);
+
+    p = data;
+
+    /* magic */
+    if (p[0] != 'S' || p[1] != 'P' || p[2] != 'L' || p[3] != 'B' || p[4] != 'I' || p[5] != 'N' ||
+        p[6] != '\0' || p[7] != '\0') {
+        free(data);
+        return -1;
+    }
+    p += 8;
+
+    spl_prog_init(prog);
+
+    /* header counts */
+    nfuncs = rd64(&p);
+    ninsns = rd64(&p);
+    nnatives = rd64(&p);
+    nstrs = rd64(&p);
+    ndata = rd64(&p);
+
+    /* ---- function table ---- */
+    for (spl_vm_val_t i = 0; i < nfuncs; i++) {
+        spl_vm_func_t func = {0};
+        spl_vm_val_t nlen = rd64(&p);
+        usize pad = ALIGN8((usize)nlen) - (usize)nlen;
+
+        func.name = (char *)malloc((usize)nlen);
+        if (!func.name) {
+            free(data);
+            return -1;
+        }
+        memcpy(func.name, p, (usize)nlen);
+        p += (usize)nlen + pad;
+
+        func.idx_of_strtab = rd64(&p);
+        func.nargs = rd64(&p);
+        func.ninsns = rd64(&p);
+        func.address = rd64(&p);
+        vec_push(prog->funcs, func);
+    }
+
+    /* ---- instructions ---- */
+    for (spl_vm_val_t i = 0; i < ninsns; i++) {
+        if ((size_t)(p - data) + 12 > (size_t)len) {
+            free(data);
+            return -1;
+        }
+        spl_vm_ins_t ins;
+        ins.opcode = (uint16_t)p[0] | ((uint16_t)p[1] << 8);
+        ins.type = (uint16_t)p[2] | ((uint16_t)p[3] << 8);
+        p += 4;
+        ins.imm = rd64(&p);
+        vec_push(prog->insns, ins);
+    }
+
+    /* ---- native table ---- */
+    for (spl_vm_val_t i = 0; i < nnatives; i++) {
+        spl_vm_native_t nat = {0};
+        spl_vm_val_t nlen = rd64(&p);
+        usize pad = ALIGN8((usize)nlen) - (usize)nlen;
+
+        nat.name = (char *)malloc((usize)nlen);
+        if (!nat.name) {
+            free(data);
+            return -1;
+        }
+        memcpy(nat.name, p, (usize)nlen);
+        p += (usize)nlen + pad;
+
+        nat.idx_of_strtab = rd64(&p);
+        nat.impl_fn = NULL; /* function pointer can't be serialised */
+        vec_push(prog->natives, nat);
+    }
+
+    /* ---- string table ---- */
+    for (spl_vm_val_t i = 0; i < nstrs; i++) {
+        spl_vm_val_t slen = rd64(&p);
+        usize pad = ALIGN8((usize)slen) - (usize)slen;
+        char *s = (char *)malloc((usize)slen + 1);
+        if (!s) {
+            free(data);
+            return -1;
+        }
+        memcpy(s, p, (usize)slen);
+        s[(usize)slen] = '\0';
+        p += (usize)slen + pad;
+        vec_push(prog->strtab, s);
+    }
+
+    /* ---- global data ---- */
+    for (spl_vm_val_t i = 0; i < ndata; i++) {
+        spl_vm_gdata_t entry;
+        entry.size = rd64(&p);
+        usize pad = ALIGN8(entry.size) - entry.size;
+        entry.data = (unsigned char *)malloc(entry.size);
+        if (!entry.data) {
+            free(data);
+            return -1;
+        }
+        memcpy(entry.data, p, entry.size);
+        p += entry.size + pad;
+        vec_push(prog->gdata, entry);
+    }
+
+    /* ---- debug 段（splc0 -g 追加在文件尾部） ---- */
+    prog->debug = NULL;
+    prog->debug_size = 0;
+    {
+        ptrdiff_t used = p - data;
+        if (used >= 0 && (usize)used < (usize)len) {
+            size_t dlen = (size_t)len - (size_t)used;
+            char *dbg = (char *)malloc(dlen + 1);
+            if (dbg) {
+                memcpy(dbg, data + used, dlen);
+                dbg[dlen] = 0;
+                prog->debug = dbg;
+                prog->debug_size = dlen;
+            }
+        }
+    }
+
+    free(data);
+    return 0;
+}
+
+int spl_prog_store_to_file(const char *fname, spl_prog_t *prog) {
+    unsigned char *buf, *p;
+    spl_vm_val_t i;
+    size_t total;
+    spl_vm_val_t nfuncs, ninsns, nnatives, nstrs, ndata;
+    usize nlen, pad;
+
+    if (!fname || !prog)
+        return -1;
+
+    nfuncs = vec_size(prog->funcs);
+    ninsns = vec_size(prog->insns);
+    nnatives = vec_size(prog->natives);
+    nstrs = vec_size(prog->strtab);
+    ndata = vec_size(prog->gdata) - 1; /* jump 0 node */
+
+    /* Calculate total size */
+    total = 8                    /* magic */
+            + 8 + 8 + 8 + 8 + 8; /* 5 counts (nfuncs+ninsns+nnatives+nstrs+ndata) */
+
+    /* funcs */
+    for (i = 0; i < nfuncs; i++) {
+        nlen = strlen(vec_at(prog->funcs, i).name) + 1; /* include null */
+        total +=
+            8 + ALIGN8(nlen) + 8 + 8 + 8 + 8; /* nlen + name(pad) + idx + nargs + ninsns + addr */
+    }
+
+    /* insns */
+    total += ninsns * 12; /* opcode(2) + type(2) + imm(8) */
+
+    /* natives */
+    for (i = 0; i < nnatives; i++) {
+        nlen = strlen(vec_at(prog->natives, i).name) + 1;
+        total += 8 + ALIGN8(nlen) + 8; /* nlen + name(pad) + idx_of_strtab */
+    }
+
+    /* strtab */
+    for (i = 0; i < nstrs; i++) {
+        nlen = strlen(vec_at(prog->strtab, i));
+        total += 8 + ALIGN8(nlen); /* slen + str(pad) */
+    }
+
+    /* gdata */
+    for (i = 1; i < vec_size(prog->gdata); i++) {
+        usize dsize = vec_at(prog->gdata, i).size;
+        total += 8 + ALIGN8(dsize); /* dsize + data(pad) */
+    }
+
+    buf = (unsigned char *)malloc(total);
+    if (!buf)
+        return -1;
+    p = buf;
+
+    /* magic */
+    memcpy(p, "SPLBIN\0\0", 8);
+    p += 8;
+
+    /* counts */
+    wr64(&p, nfuncs);
+    wr64(&p, ninsns);
+    wr64(&p, nnatives);
+    wr64(&p, nstrs);
+    wr64(&p, ndata);
+
+    /* ---- function table ---- */
+    for (i = 0; i < nfuncs; i++) {
+        const char *name = vec_at(prog->funcs, i).name;
+        nlen = strlen(name) + 1;
+        pad = ALIGN8(nlen) - nlen;
+        wr64(&p, nlen);
+        memcpy(p, name, nlen);
+        p += nlen;
+        memset(p, 0, pad);
+        p += pad;
+        wr64(&p, vec_at(prog->funcs, i).idx_of_strtab);
+        wr64(&p, vec_at(prog->funcs, i).nargs);
+        wr64(&p, vec_at(prog->funcs, i).ninsns);
+        wr64(&p, vec_at(prog->funcs, i).address);
+    }
+
+    /* ---- instructions ---- */
+    for (i = 0; i < ninsns; i++) {
+        spl_vm_ins_t *ins = &vec_at(prog->insns, i);
+        *p++ = (unsigned char)(ins->opcode);
+        *p++ = (unsigned char)(ins->opcode >> 8);
+        *p++ = (unsigned char)(ins->type);
+        *p++ = (unsigned char)(ins->type >> 8);
+        wr64(&p, ins->imm);
+    }
+
+    /* ---- native table ---- */
+    for (i = 0; i < nnatives; i++) {
+        const char *name = vec_at(prog->natives, i).name;
+        nlen = strlen(name) + 1;
+        pad = ALIGN8(nlen) - nlen;
+        wr64(&p, nlen);
+        memcpy(p, name, nlen);
+        p += nlen;
+        memset(p, 0, pad);
+        p += pad;
+        wr64(&p, vec_at(prog->natives, i).idx_of_strtab);
+    }
+
+    /* ---- string table ---- */
+    for (i = 0; i < nstrs; i++) {
+        const char *s = vec_at(prog->strtab, i);
+        nlen = strlen(s);
+        pad = ALIGN8(nlen) - nlen;
+        wr64(&p, nlen);
+        memcpy(p, s, nlen);
+        p += nlen;
+        memset(p, 0, pad);
+        p += pad;
+    }
+
+    /* ---- global data ---- */
+    for (i = 1; i <= ndata; i++) {
+        spl_vm_gdata_t *entry = &vec_at(prog->gdata, i);
+        pad = ALIGN8(entry->size) - entry->size;
+        wr64(&p, entry->size);
+        memcpy(p, entry->data, entry->size);
+        p += entry->size;
+        memset(p, 0, pad);
+        p += pad;
+    }
+
+    /* Write file */
+    FILE *f = fopen(fname, "wb");
+    if (!f) {
+        free(buf);
+        return -1;
+    }
+    fwrite(buf, 1, total, f);
+    fclose(f);
+    free(buf);
+    return 0;
+}
+
+int spl_prog_add_instr(spl_prog_t *prog, uint8_t opcode, uint8_t type, spl_vm_val_t imm) {
+    if (!prog)
+        return 0;
+    spl_vm_ins_t ins = (spl_vm_ins_t){.opcode = opcode, .type = type, .imm = imm};
+    vec_push(prog->insns, ins);
+    return vec_size(prog->insns);
+}
+
+int spl_prog_add_func(spl_prog_t *prog, spl_vm_func_t *func) {
+    if (!prog || !func)
+        return 0;
+    vec_push(prog->funcs, *func);
+    return vec_size(prog->funcs);
+}
+
+int spl_prog_add_native(spl_prog_t *prog, spl_vm_native_t *native) {
+    if (!prog || !native)
+        return 0;
+    vec_push(prog->natives, *native);
+    return vec_size(prog->natives);
+}
+
+int spl_prog_add_data(spl_prog_t *prog, void *ptr, usize size) {
+    spl_vm_gdata_t entry;
+    if (!prog)
+        return 0;
+    entry.data = (unsigned char *)malloc(size);
+    if (!entry.data)
+        return 0;
+    memcpy(entry.data, ptr, size);
+    entry.size = size;
+    vec_push(prog->gdata, entry);
+    return (int)(vec_size(prog->gdata) - 1);
+}
+
+spl_vm_func_t *spl_prog_get_func(spl_prog_t *prog, const char *name) {
+    if (!prog || !name)
+        return NULL;
+    vec_for(prog->funcs, i) {
+        const char *match_name = vec_at(prog->funcs, i).name;
+        if (match_name && strcmp(match_name, name) == 0) {
+            return &vec_at(prog->funcs, i);
+        }
+    }
+    return NULL;
+}
+
+spl_vm_native_t *spl_prog_get_native(spl_prog_t *prog, const char *name) {
+    if (!prog || !name)
+        return NULL;
+    vec_for(prog->natives, i) {
+        const char *match_name = vec_at(prog->natives, i).name;
+        if (match_name && strcmp(match_name, name) == 0) {
+            return &vec_at(prog->natives, i);
+        }
+    }
+    return NULL;
+}
+
+const char *opcode_name[] = {
+#define X(opcode, name, argc, pop, push, desc) [opcode] = name,
+    SPL_OPCODES(X)
+#undef X
+};
+const char *spl_vm_opcode_name(spl_vm_opcode_t opcode) { return opcode_name[opcode]; }
+const char *spl_vm_type_kind_name(spl_vm_kind_t type) {
+    switch (type) {
+    case SPL_VOID:
+        return "void";
+    case SPL_BOOL:
+        return "bool";
+    case SPL_I8:
+        return "i8";
+    case SPL_U8:
+        return "u8";
+    case SPL_I16:
+        return "i16";
+    case SPL_U16:
+        return "u16";
+    case SPL_I32:
+        return "i32";
+    case SPL_U32:
+        return "u32";
+    case SPL_I64:
+        return "i64";
+    case SPL_U64:
+        return "u64";
+    case SPL_F32:
+        return "f32";
+    case SPL_F64:
+        return "f64";
+    case SPL_USIZE:
+        return "usize";
+    case SPL_ISIZE:
+        return "isize";
+    case SPL_PTR:
+        return "ptr";
+    default:
+        return "???";
+    }
+}
+
+void spl_vm_ins_dump(spl_vm_ins_t *ins, spl_vm_val_t addr) {
+    printf("%4zu: %s", addr, spl_vm_opcode_name((spl_vm_opcode_t)ins->opcode));
+    if (ins->type != SPL_VOID)
+        printf(" %s", spl_vm_type_kind_name((spl_vm_kind_t)ins->type));
+    printf(" %zd:%zx", ins->imm, ins->imm);
+    printf("\n");
+}

stage0/spl_mcode.h

@@ -0,0 +1,211 @@
+/* spl_mcode.h - SPL VM Machine Code: instruction set and binary format
+ */
+
+#ifndef __SPL_MCODE_H__
+#define __SPL_MCODE_H__
+
+#include "include/core_map.h"
+#include "include/core_vec.h"
+#include <stddef.h>
+#include <stdint.h>
+
+typedef uintptr_t usize;
+typedef intptr_t isize;
+
+typedef enum {
+    SPL_VOID,
+    SPL_BOOL,
+    SPL_I8,
+    SPL_U8,
+    SPL_I16,
+    SPL_U16,
+    SPL_I32,
+    SPL_U32,
+    SPL_I64,
+    SPL_U64,
+    SPL_ISIZE,
+    SPL_USIZE,
+    SPL_F32,
+    SPL_F64,
+    SPL_PTR,
+    SPL_TYPE_COUNT,
+} spl_vm_kind_t;
+
+/* clang-format off */
+#define SPL_OPCODES(X) \
+    /* opcode,         name,       argc, pop, push, desc */ \
+    X(SPL_ERROR,     "error",       0,    0,   0,   "invalid opcode / internal error") \
+    /* 栈操作 */ \
+    X(SPL_PUSH,      "push",        1,    0,   1,   "push immediate") \
+    X(SPL_DUP,       "dup",         0,    0,   1,   "duplicate top of stack") \
+    X(SPL_DROP,      "drop",        0,    1,   0,   "discard top of stack") \
+    X(SPL_SWAP,      "swap",        0,    2,   2,   "swap top two elements") \
+    X(SPL_PICK,      "pick",        1,    0,   1,   "push copy of stack[imm] (0=TOS)") \
+    X(SPL_ROT,       "rot",         0,    3,   3,   "rotate top three (a b c -- b c a)") \
+    /* 算术 */ \
+    X(SPL_ADD,       "add",         0,    2,   1,   "integer addition") \
+    X(SPL_SUB,       "sub",         0,    2,   1,   "integer subtraction") \
+    X(SPL_MUL,       "mul",         0,    2,   1,   "integer multiplication") \
+    X(SPL_DIV_S,     "div_s",       0,    2,   1,   "signed division") \
+    X(SPL_DIV_U,     "div_u",       0,    2,   1,   "unsigned division") \
+    X(SPL_REM_S,     "rem_s",       0,    2,   1,   "signed remainder") \
+    X(SPL_REM_U,     "rem_u",       0,    2,   1,   "unsigned remainder") \
+    X(SPL_NEG,       "neg",         0,    1,   1,   "two's complement negation") \
+    /* 位运算 */ \
+    X(SPL_AND,       "and",         0,    2,   1,   "bitwise AND") \
+    X(SPL_OR,        "or",          0,    2,   1,   "bitwise OR") \
+    X(SPL_XOR,       "xor",         0,    2,   1,   "bitwise XOR") \
+    X(SPL_NOT,       "not",         0,    1,   1,   "bitwise NOT") \
+    X(SPL_SHL,       "shl",         0,    2,   1,   "left shift") \
+    X(SPL_SHR_U,     "shr_u",       0,    2,   1,   "logical right shift (zero-fill)") \
+    X(SPL_SHR_S,     "shr_s",       0,    2,   1,   "arithmetic right shift (sign-fill)") \
+    /* 比较 */ \
+    X(SPL_EQ,        "eq",          0,    2,   1,   "equal") \
+    X(SPL_NE,        "ne",          0,    2,   1,   "not equal") \
+    X(SPL_SLT,       "slt",         0,    2,   1,   "signed less than") \
+    X(SPL_SLE,       "sle",         0,    2,   1,   "signed less or equal") \
+    X(SPL_ULT,       "ult",         0,    2,   1,   "unsigned less than") \
+    X(SPL_ULE,       "ule",         0,    2,   1,   "unsigned less or equal") \
+    X(SPL_SGT,       "sgt",         0,    2,   1,   "signed greater than") \
+    X(SPL_SGE,       "sge",         0,    2,   1,   "signed greater or equal") \
+    X(SPL_UGT,       "ugt",         0,    2,   1,   "unsigned greater than") \
+    X(SPL_UGE,       "uge",         0,    2,   1,   "unsigned greater or equal") \
+    /* 类型转换 */ \
+    X(SPL_TRUNC,     "trunc",       1,    1,   1,   "truncate to low imm bits") \
+    X(SPL_SEXT,      "sext",        1,    1,   1,   "sign-extend from bit imm") \
+    X(SPL_ZEXT,      "zext",        1,    1,   1,   "zero-extend from bit imm") \
+    /* 控制流 */ \
+    X(SPL_JMP,       "jmp",         1,    0,   0,   "unconditional jump (offset isize)") \
+    X(SPL_BZ,        "bz",          1,    1,   0,   "pop; jump if zero (offset isize)") \
+    X(SPL_BNZ,       "bnz",         1,    1,   0,   "pop; jump if non-zero (offset isize)") \
+    X(SPL_HALT,      "halt",        0,    0,   0,   "stop execution") \
+    /* 函数调用 */ \
+    X(SPL_CALL,      "call",        1,    0,   0,   "call function pop function offset, call it") \
+    X(SPL_CALLI,     "calli",       0,    1,   0,   "indirect call: pop function address, call it") \
+    X(SPL_RET,       "ret",         0,    0,   0,   "return from function") \
+    /* 栈帧局部变量 */ \
+    X(SPL_ALLOC,     "alloc",       1,    0,   0,   "allocate imm zero-slots on stack") \
+    X(SPL_LADDR,     "laddr",       1,    0,   1,   "push address of local at fp + imm bytes") \
+    X(SPL_GADDR,     "gaddr",       1,    0,   1,   "push address of global at gp + imm") \
+    /* 间接内存访问 */ \
+    X(SPL_LOAD,      "load",        0,    1,   1,   "load sizeof(type)-bits zero-extended") \
+    X(SPL_STORE,     "store",       0,    2,   0,   "store low sizeof(type)-bits") \
+    /* 原生接口 */ \
+    X(SPL_NCALL,     "ncall",       1,    0,   1,   "call native function by index") \
+    X(SPL_NLIB,      "nlib",        1,    0,   0,   "dlopen library (name idx)") \
+    /* 调试 */ \
+    X(SPL_BK,        "breakpoint",  0,    0,   0,   "break point when exec will stop run") \
+    X(SPL_DBG,       "dbg",         0,    0,   0,   "print VM debug info (stack, backtrace, locals)")
+
+/* clang-format on */
+
+typedef enum {
+#define X(opcode, name, argc, pop, push, desc) opcode,
+    SPL_OPCODES(X)
+#undef X
+} spl_vm_opcode_t;
+
+/*
+ * Binary format (all metadata fields spl_val_t LE):
+ *   magic[8] = "SPLBIN\0\0"
+ *   nfuncs, ninsns, nnatives, nstrs, ndata
+ *   [func table]  each: name_len, name(pad8), idx_of_strtab, nargs, ninsns, address
+ *   [insns]       each: opcode(2) type(2) imm(8) = 12 bytes
+ *   [natives]     each: name_len, name(pad8), idx_of_strtab
+ *   [strtab]      each: slen, str(pad8)
+ *   [gdata]       each: dsize(8), data(dsize bytes, padded to 8)
+ *
+ * === Aggregate Return ABI (sret) ===
+ *
+ * 凡返回值类型为聚合（struct / union / enum / array / shape），
+ * 采用调用者分配 / 被调用者填充的间接返回约定：
+ *
+ * Before CALL:
+ *   - caller 在自己的帧里 alloca 一块 RetTy 大小的空间
+ *   - 该空间的地址作为第 0 个实参先压栈
+ *   - 其余实参照常从左到右压栈
+ *   - target 地址最后压栈
+ *   - CALL imm = 普通实参个数 + 1
+ *
+ * Callee 进入后:
+ *   - fp+0 存放 sret 指针
+ *   - 形参 i 位于 fp + 8*(i+1)
+ *   - 返回值直接写入 *(fp+0)，然后执行 RET void
+ *
+ * Caller 侧:
+ *   - 调用完成后，CALL 结果槽保存 sret 指针；
+ *     后续对聚合值的所有读取都通过该指针进行
+ */
+
+#define SPL_BINFMT_MAGIC "SPLBIN\0\0"
+// All SIR stack values are ptr-bit unsigned integers
+typedef usize spl_vm_val_t;
+
+typedef struct spl_vm_ins {
+    uint8_t opcode;
+    uint8_t type;
+    spl_vm_val_t imm;
+} spl_vm_ins_t;
+typedef VEC(spl_vm_ins_t) spl_vm_ins_vec_t;
+
+typedef struct spl_vm_func {
+    char *name;
+    spl_vm_val_t idx_of_strtab;
+    spl_vm_val_t nargs;
+    spl_vm_val_t ninsns;
+    spl_vm_val_t address;
+} spl_vm_func_t;
+typedef VEC(spl_vm_func_t) spl_vm_func_vec_t;
+
+/* Native function pointer type */
+struct spl_vm;
+typedef struct spl_vm spl_vm_t;
+typedef spl_vm_val_t (*spl_vm_fn_t)(spl_vm_t *vm, int nargs, spl_vm_val_t *args);
+typedef struct spl_vm_native {
+    char *name;
+    spl_vm_val_t idx_of_strtab;
+    spl_vm_fn_t impl_fn;
+} spl_vm_native_t;
+typedef VEC(spl_vm_native_t) spl_vm_native_vec_t;
+
+typedef struct {
+    unsigned char *data;
+    usize size;
+} spl_vm_gdata_t;
+typedef VEC(spl_vm_gdata_t) spl_vm_data_t;
+typedef VEC(const char *) spl_vm_strtab_t;
+typedef MAP(const char *, const char *) spl_vm_symtab_t;
+/* Opaque handle for loaded program */
+typedef struct spl_prog {
+    spl_vm_ins_vec_t insns;
+    spl_vm_func_vec_t funcs;
+    spl_vm_native_vec_t natives;
+    spl_vm_data_t gdata;
+    spl_vm_strtab_t strtab;
+    spl_vm_symtab_t symtab;
+    char *debug; /* 文件尾部 debug 段（splc0 -g 追加的文本），无则 NULL */
+    usize debug_size;
+} spl_prog_t;
+
+void spl_prog_init(spl_prog_t *prog);
+void spl_prog_drop(spl_prog_t *prog);
+void spl_prog_dump(spl_prog_t *prog);
+
+int spl_prog_load_from_file(const char *fname, spl_prog_t *prog);
+int spl_prog_store_to_file(const char *fname, spl_prog_t *prog);
+
+int spl_prog_add_instr(spl_prog_t *prog, uint8_t opcode, uint8_t type, spl_vm_val_t imm);
+int spl_prog_add_data(spl_prog_t *prog, void *ptr, usize size);
+int spl_prog_add_func(spl_prog_t *prog, spl_vm_func_t *func);
+int spl_prog_add_native(spl_prog_t *prog, spl_vm_native_t *native);
+
+spl_vm_func_t *spl_prog_get_func(spl_prog_t *prog, const char *name);
+spl_vm_native_t *spl_prog_get_native(spl_prog_t *prog, const char *name);
+
+/* Opcode name lookup for debugging/dumping */
+const char *spl_vm_opcode_name(spl_vm_opcode_t opcode);
+const char *spl_vm_type_kind_name(spl_vm_kind_t type);
+
+void spl_vm_ins_dump(spl_vm_ins_t *ins, spl_vm_val_t addr);
+
+#endif /* __SPL_MCODE_H__ */

stage0/spl_syscall.c

@@ -0,0 +1,505 @@
+/* spl_syscall.c - built-in syscall implementations + registration
+ *
+ * All syscalls validate nargs, cast spl_val_t args to the expected C types,
+ * execute, and return the result as spl_val_t.
+ *
+ * Simple syscalls use the SYSCALL_N macros; complex ones are written
+ * manually but follow the same template.
+ */
+
+#include "spl_syscall.h"
+#include "include/core_map.h"
+#include "include/core_vec.h"
+#include "spl_mcode.h"
+#include "spl_vm.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* =================================================================
+ * Macro templates
+ *
+ * Each SYSCALL_N macro:
+ *  1. Validates nargs (prints error and returns -1 on mismatch)
+ *  2. Casts args[n] from spl_val_t to the specified C type via
+ *     (type)(uintptr_t) - this handles both integer and pointer types
+ *  3. Evaluates the expression and returns the result as spl_val_t
+ * ================================================================= */
+
+#define CHECK_NARGS(fname, expected)                                                               \
+    do {                                                                                           \
+        if (nargs != (expected)) {                                                                 \
+            fprintf(stderr, fname ": expected " #expected " args, got %d\n", nargs);               \
+            return -1;                                                                             \
+        }                                                                                          \
+    } while (0)
+
+#define SYSCALL_0(name, ret_expr)                                                                  \
+    static spl_vm_val_t name(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {                       \
+        (void)_vm;                                                                                 \
+        CHECK_NARGS(#name, 0);                                                                     \
+        (void)args;                                                                                \
+        return (spl_vm_val_t)(uintptr_t)(ret_expr);                                                \
+    }
+
+#define SYSCALL_1(name, t1, ret_expr)                                                              \
+    static spl_vm_val_t name(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {                       \
+        (void)_vm;                                                                                 \
+        CHECK_NARGS(#name, 1);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        return (spl_vm_val_t)(uintptr_t)(ret_expr);                                                \
+    }
+
+#define SYSCALL_2(name, t1, t2, ret_expr)                                                          \
+    static spl_vm_val_t name(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {                       \
+        (void)_vm;                                                                                 \
+        CHECK_NARGS(#name, 2);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        t2 a2 = (t2)(uintptr_t)args[1];                                                            \
+        return (spl_vm_val_t)(uintptr_t)(ret_expr);                                                \
+    }
+
+#define SYSCALL_3(name, t1, t2, t3, ret_expr)                                                      \
+    static spl_vm_val_t name(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {                       \
+        (void)_vm;                                                                                 \
+        CHECK_NARGS(#name, 3);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        t2 a2 = (t2)(uintptr_t)args[1];                                                            \
+        t3 a3 = (t3)(uintptr_t)args[2];                                                            \
+        return (spl_vm_val_t)(uintptr_t)(ret_expr);                                                \
+    }
+
+#define SYSCALL_4(name, t1, t2, t3, t4, ret_expr)                                                  \
+    static spl_vm_val_t name(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {                       \
+        (void)_vm;                                                                                 \
+        CHECK_NARGS(#name, 4);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        t2 a2 = (t2)(uintptr_t)args[1];                                                            \
+        t3 a3 = (t3)(uintptr_t)args[2];                                                            \
+        t4 a4 = (t4)(uintptr_t)args[3];                                                            \
+        return (spl_vm_val_t)(uintptr_t)(ret_expr);                                                \
+    }
+
+/* syscall / VM 内部统一地址检查宏。
+ * 失败时打印 ctx + 地址 + size + ip，置 native_error，return 0。
+ * 要求所在函数有可用的 _vm 变量。 */
+#define ADDRCHECK(vm, ptr, size, ctx)                                                              \
+    do {                                                                                           \
+        uintptr_t _acp = (uintptr_t)(ptr);                                                         \
+        usize _acs = (usize)(size);                                                                \
+        if (!spl_vm_addr_valid(_acp, _acs)) {                                                      \
+            fprintf(stderr, "%s: invalid address %p size=%zu (ip=%zu fp=%zu sp=%zu)\n", (ctx),     \
+                    (void *)_acp, _acs, (vm)->ip, (vm)->fp, (vm)->sp);                             \
+            spl_vm_backtrace((vm), (vm)->fp);                                                      \
+            (vm)->exit_code = 2;                                                                   \
+            return 0;                                                                              \
+        }                                                                                          \
+    } while (0)
+
+/* syscall 内部：把当前栈和调用栈打印出来，供出错时定位 */
+#define SYSCALL_DUMP(vm)                                                                           \
+    do {                                                                                           \
+        fprintf(stderr, "  --- syscall dump (sp=%zu fp=%zu cp=%zu ip=%zu) ---\n", (vm)->sp,        \
+                (vm)->fp, (vm)->cp, (vm)->ip);                                                     \
+        spl_vm_backtrace((vm), (vm)->fp);                                                          \
+        spl_vm_stackdump((vm), (vm)->sp);                                                          \
+    } while (0)
+
+/* syscall 内部：报告致命错误，dump 后让 VM 停在当前 ip */
+#define SYSCALL_FAIL(vm, ...)                                                                      \
+    do {                                                                                           \
+        fprintf(stderr, "syscall error: ");                                                        \
+        fprintf(stderr, __VA_ARGS__);                                                              \
+        fprintf(stderr, "\n");                                                                     \
+        SYSCALL_DUMP(vm);                                                                          \
+        (vm)->exit_code = 1;                                                                       \
+        return 0;                                                                                  \
+    } while (0)
+
+/* =================================================================
+ * OS syscalls
+ * ================================================================= */
+
+/* vm_exit - terminate process with the given exit code */
+SYSCALL_1(vm_exit, int, (exit(a1), (spl_vm_val_t)0))
+
+/* vm_putchar - write a single character to stdout */
+SYSCALL_1(vm_putchar, int, putchar(a1))
+
+/* vm_getchar - read a single character from stdin */
+SYSCALL_0(vm_getchar, getchar())
+
+/* vm_putint - print an integer to stdout */
+SYSCALL_1(vm_putint, int, (fprintf(stdout, "%d", a1), (spl_vm_val_t)0))
+
+/* vm_putstr - print a string to stdout (no trailing newline) */
+SYSCALL_1(vm_putstr, const char *, (fputs(a1, stdout), (spl_vm_val_t)0))
+
+/* vm_fopen - open a file, returns FILE* as spl_val_t */
+SYSCALL_2(vm_fopen, const char *, const char *, (uintptr_t)fopen(a1, a2))
+
+/* vm_fclose - close a file, returns 0 on success */
+SYSCALL_1(vm_fclose, FILE *, fclose(a1))
+
+/* vm_fread - read from file, returns number of items read */
+SYSCALL_4(vm_fread, void *, size_t, size_t, FILE *, fread(a1, a2, a3, a4))
+
+/* vm_fwrite - write to file, returns number of items written */
+SYSCALL_4(vm_fwrite, const void *, size_t, size_t, FILE *, fwrite(a1, a2, a3, a4))
+
+/* vm_fsize - get file size in bytes */
+static spl_vm_val_t vm_fsize(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_fsize", 1);
+    FILE *f = (FILE *)(uintptr_t)args[0];
+    long cur = ftell(f);
+    fseek(f, 0, SEEK_END);
+    long sz = ftell(f);
+    fseek(f, cur, SEEK_SET);
+    return (spl_vm_val_t)(uintptr_t)sz;
+}
+
+SYSCALL_0(vm_stdin, stdin)
+SYSCALL_0(vm_stdout, stdout)
+SYSCALL_0(vm_stderr, stderr)
+
+/* vm_read_file - read entire file into a malloc'd, null-terminated buffer */
+static spl_vm_val_t vm_read_file(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_read_file", 1);
+    const char *path = (const char *)(uintptr_t)args[0];
+    if (path == nullptr) {
+        fprintf(stderr, "filepath can't be null");
+        return 0;
+    }
+    FILE *f = fopen(path, "rb");
+    if (!f) {
+        fprintf(stderr, "filepath %s can't be open", path);
+        return 1;
+    }
+    fseek(f, 0, SEEK_END);
+    long sz = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    char *buf = (char *)malloc((size_t)sz + 1);
+    if (!buf) {
+        fclose(f);
+        return 0;
+    }
+    size_t nread = fread(buf, 1, (size_t)sz, f);
+    fclose(f);
+    buf[nread] = '\0';
+    return (spl_vm_val_t)(uintptr_t)buf;
+}
+
+static spl_vm_val_t vm_alloc(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    CHECK_NARGS("vm_alloc", 1);
+    size_t sz = (size_t)args[0];
+    if (sz == 0)
+        SYSCALL_FAIL(_vm, "vm_alloc: zero size");
+    if (sz > (size_t)1 << 32)
+        SYSCALL_FAIL(_vm, "vm_alloc: size too large (%zu)", sz);
+    void *p = malloc(sz);
+    if (!p)
+        SYSCALL_FAIL(_vm, "vm_alloc: malloc(%zu) failed", sz);
+    return (spl_vm_val_t)(uintptr_t)p;
+}
+
+static spl_vm_val_t vm_free(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_free", 1);
+    void *p = (void *)(uintptr_t)args[0];
+    if (p)
+        free(p);
+    return 0;
+}
+
+static spl_vm_val_t vm_realloc(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    CHECK_NARGS("vm_realloc", 2);
+    void *p = (void *)(uintptr_t)args[0];
+    size_t sz = (size_t)args[1];
+    if (!p)
+        SYSCALL_FAIL(_vm, "vm_realloc: NULL ptr");
+    if (sz == 0)
+        SYSCALL_FAIL(_vm, "vm_realloc: zero size");
+    ADDRCHECK(_vm, p, 1, "vm_realloc");
+    void *np = realloc(p, sz);
+    if (!np)
+        SYSCALL_FAIL(_vm, "vm_realloc: realloc(%p, %zu) failed", p, sz);
+    return (spl_vm_val_t)(uintptr_t)np;
+}
+
+static spl_vm_val_t vm_memcpy(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    CHECK_NARGS("vm_memcpy", 3);
+    void *dst = (void *)(uintptr_t)args[0];
+    const void *src = (const void *)(uintptr_t)args[1];
+    size_t size = (size_t)args[2];
+    if (size == 0)
+        return (spl_vm_val_t)(uintptr_t)dst;
+    ADDRCHECK(_vm, dst, size, "vm_memcpy(dst)");
+    ADDRCHECK(_vm, src, size, "vm_memcpy(src)");
+    memcpy(dst, src, size);
+    return (spl_vm_val_t)(uintptr_t)dst;
+}
+
+static spl_vm_val_t vm_memcmp(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    CHECK_NARGS("vm_memcmp", 3);
+    const void *a = (const void *)(uintptr_t)args[0];
+    const void *b = (const void *)(uintptr_t)args[1];
+    size_t size = (size_t)args[2];
+    if (size == 0)
+        return 0;
+    ADDRCHECK(_vm, a, size, "vm_memcmp(a)");
+    ADDRCHECK(_vm, b, size, "vm_memcmp(b)");
+    return (spl_vm_val_t)memcmp(a, b, size);
+}
+
+static spl_vm_val_t vm_printf(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    if (nargs <= 0)
+        return 0;
+
+    /* args[0] 是 SPL 的 []u8 format 参数。VM 里 slice 作为参数传递时，
+       栈上压的是"指向 slice 结构体的指针"，结构为 {ptr:*u8, len:u64} */
+    const spl_vm_val_t *fmt_slice = (const spl_vm_val_t *)args[0];
+    const char *fmt = (const char *)fmt_slice[0];
+    usize fmt_len = (usize)fmt_slice[1];
+
+    if (nargs <= 1) {
+        fwrite(fmt, 1, fmt_len, stdout);
+        return (spl_vm_val_t)nargs;
+    }
+
+    typedef VEC(char) string_builder_t;
+    string_builder_t buffer;
+    vec_init(buffer);
+
+    int arg_idx = 1; /* 0 是 format */
+    char tmp_buf[32];
+
+    for (usize i = 0; i < fmt_len; ++i) {
+        if (fmt[i] != '%') {
+            vec_push(buffer, fmt[i]);
+            continue;
+        }
+        if (++i >= fmt_len)
+            break;
+        if (arg_idx >= nargs)
+            break;
+
+        switch (fmt[i]) {
+        case 'd': {
+            memset(tmp_buf, 0, sizeof(tmp_buf));
+            snprintf(tmp_buf, sizeof(tmp_buf), "%zd", (isize)args[arg_idx]);
+            for (usize j = 0; tmp_buf[j] != '\0'; ++j)
+                vec_push(buffer, tmp_buf[j]);
+            arg_idx++;
+            break;
+        }
+        case 'c':
+            vec_push(buffer, (char)args[arg_idx]);
+            arg_idx++;
+            break;
+        case 's': {
+            const spl_vm_val_t *s = (const spl_vm_val_t *)args[arg_idx];
+            const char *p = (const char *)s[0];
+            usize l = (usize)s[1];
+            for (usize j = 0; j < l; ++j)
+                vec_push(buffer, p[j]);
+            arg_idx++;
+            break;
+        }
+        default:
+            vec_push(buffer, '%');
+            vec_push(buffer, fmt[i]);
+            break;
+        }
+    }
+
+    if (vec_size(buffer) > 0)
+        fwrite(buffer.data, 1, vec_size(buffer), stdout);
+    vec_free(buffer);
+    return (spl_vm_val_t)nargs;
+}
+
+/* =================================================================
+ * VM syscalls (for comptime - compile-time code execution)
+ *
+ * These let SPL code create isolated sub-VMs, load compiled .sir
+ * programs into them, push arguments, call functions, and run.
+ * ================================================================= */
+
+/* vm_new - create a new sub-VM instance, returns spl_vm_t* */
+static spl_vm_val_t vm_new(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_new", 0);
+    (void)args;
+    spl_vm_t *vm = (spl_vm_t *)malloc(sizeof(spl_vm_t));
+    if (!vm)
+        return 0;
+    spl_vm_init(vm);
+    return (spl_vm_val_t)(uintptr_t)vm;
+}
+
+/* vm_drop - destroy a sub-VM and its loaded program */
+static spl_vm_val_t vm_drop(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_drop", 1);
+    spl_vm_t *vm = (spl_vm_t *)(uintptr_t)args[0];
+    if (!vm)
+        return 0;
+    if (vm->prog) {
+        spl_prog_drop(vm->prog);
+        free(vm->prog);
+        vm->prog = NULL;
+    }
+    spl_vm_drop(vm);
+    free(vm);
+    return 0;
+}
+
+/* vm_load - load a .sir file, register syscalls, return spl_prog_t* */
+static spl_vm_val_t vm_load(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_load", 2);
+    spl_vm_t *vm = (spl_vm_t *)(uintptr_t)args[0];
+    const char *path = (const char *)(uintptr_t)args[1];
+    if (!vm || !path)
+        return -1;
+
+    spl_prog_t *prog = (spl_prog_t *)malloc(sizeof(spl_prog_t));
+    if (!prog)
+        return -1;
+    if (spl_prog_load_from_file(path, prog) != 0) {
+        free(prog);
+        return -1;
+    }
+    spl_syscall_register(prog);
+    if (spl_vm_load_prog(vm, prog) != 0) {
+        spl_prog_drop(prog);
+        free(prog);
+        return -1;
+    }
+    return (spl_vm_val_t)(uintptr_t)prog;
+}
+
+/* vm_push - push a value onto the sub-VM's stack (for passing arguments) */
+static spl_vm_val_t vm_push(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_push", 2);
+    spl_vm_t *vm = (spl_vm_t *)(uintptr_t)args[0];
+    spl_vm_val_t val = args[1];
+    if (!vm)
+        return -1;
+    if (vm->sp >= vm->config.max_stack_depth) {
+        fprintf(stderr, "vm_push: stack overflow\n");
+        return -1;
+    }
+    vm->stacks.data[vm->sp++] = val;
+    return 0;
+}
+
+/* vm_call - call a function by name with pre-pushed arguments
+ *
+ * Args (3): vm, function_name, nargs
+ * The arguments should already be on the sub-VM's stack via vm_push.
+ *
+ * Mirrors the CALL instruction's frame setup:
+ *   - Pushes a sentinel frame (saved_ip=-1) if cp==0 so RET halts properly
+ *   - Pushes the actual call frame
+ *   - Sets fp = sp - nargs  (so arg0 = data[fp], arg1 = data[fp+1], ...)
+ *   - Sets ip to the function address
+ */
+static spl_vm_val_t vm_call(spl_vm_t *_vm, int nargs, spl_vm_val_t *args) {
+    (void)_vm;
+    CHECK_NARGS("vm_call", 3);
+    spl_vm_t *vm = (spl_vm_t *)(uintptr_t)args[0];
+    const char *name = (const char *)(uintptr_t)args[1];
+    spl_vm_val_t call_nargs = args[2];
+    if (!vm || !name)
+        return -1;
+
+    spl_vm_func_t *func = spl_prog_get_func(vm->prog, name);
+    if (!func) {
+        fprintf(stderr, "vm_call: function '%s' not found\n", name);
+        return -1;
+    }
+    if (vm->cp >= vm->config.max_call_depth - 1) {
+        fprintf(stderr, "vm_call: call stack overflow\n");
+        return -1;
+    }
+
+    /* Sentinel frame so the entry function's RET halts cleanly */
+    if (vm->cp == 0) {
+        vm->frames.data[vm->cp].saved_fp = 0;
+        vm->frames.data[vm->cp].saved_ip = (uintptr_t)-1;
+        vm->frames.data[vm->cp].nargs = 0;
+        vm->cp++;
+    }
+
+    /* Actual call frame (same logic as the CALL instruction) */
+    vm->frames.data[vm->cp].saved_fp = vm->fp;
+    vm->frames.data[vm->cp].saved_ip = vm->ip;
+    vm->frames.data[vm->cp].nargs = call_nargs;
+    vm->cp++;
+    vm->fp = vm->sp - call_nargs;
+    vm->ip = (uintptr_t)func->address;
+    return 0;
+}
+
+/* vm_run - run a sub-VM to completion, returns exit_code */
+SYSCALL_1(vm_run, spl_vm_t *, spl_vm_run_until(a1, 0))
+
+/* =================================================================
+ * Registration
+ *
+ * Called after loading a .sir file.  Matches native declarations in
+ * prog->natives against known syscall names and hooks up impl_fn.
+ * ================================================================= */
+
+void spl_syscall_register(spl_prog_t *prog) {
+    static spl_vm_native_t table[] = {
+        /* OS operations */
+        {"vm_exit", 0, vm_exit},
+        {"vm_putchar", 0, vm_putchar},
+        {"vm_getchar", 0, vm_getchar},
+        {"vm_putint", 0, vm_putint},
+        {"vm_putstr", 0, vm_putstr},
+        {"vm_fopen", 0, vm_fopen},
+        {"vm_fclose", 0, vm_fclose},
+        {"vm_fread", 0, vm_fread},
+        {"vm_fwrite", 0, vm_fwrite},
+        {"vm_fsize", 0, vm_fsize},
+        {"vm_stdin", 0, vm_stdin},
+        {"vm_stdout", 0, vm_stdout},
+        {"vm_stderr", 0, vm_stderr},
+        {"vm_read_file", 0, vm_read_file},
+        {"vm_alloc", 0, vm_alloc},
+        {"vm_free", 0, vm_free},
+        {"vm_realloc", 0, vm_realloc},
+        {"vm_memcpy", 0, vm_memcpy},
+        {"vm_memcmp", 0, vm_memcmp},
+        {"vm_printf", 0, vm_printf},
+        /* VM operations (comptime) */
+        {"vm_new", 0, vm_new},
+        {"vm_drop", 0, vm_drop},
+        {"vm_load", 0, vm_load},
+        {"vm_push", 0, vm_push},
+        {"vm_call", 0, vm_call},
+        {"vm_run", 0, vm_run},
+    };
+    int n = (int)(sizeof(table) / sizeof(table[0]));
+    if (!prog)
+        return;
+    vec_for(prog->natives, i) {
+        spl_vm_native_t *nat = &vec_at(prog->natives, i);
+        if (!nat->name || nat->impl_fn)
+            continue;
+        for (int j = 0; j < n; j++) {
+            if (strcmp(nat->name, table[j].name) == 0) {
+                nat->impl_fn = table[j].impl_fn;
+                break;
+            }
+        }
+    }
+}

stage0/spl_syscall.h

@@ -0,0 +1,22 @@
+/* spl_syscall.h - built-in syscall layer for SIR VM
+ *
+ * Provides I/O native functions (putchar, getchar, file ops, etc.)
+ * that compiled SPL programs can call via NCALL.
+ *
+ * spl_syscall_register() must be called AFTER spl_prog_load_from_file()
+ * and BEFORE spl_vm_run_until().  It matches native declarations in the
+ * loaded program against known syscall names and hooks up the C
+ * implementations.
+ */
+
+#ifndef __SPL_SYSCALL_H__
+#define __SPL_SYSCALL_H__
+
+#include "spl_mcode.h"
+
+/* Register all known built-in syscalls into prog->natives[].
+ * Entries whose name matches a known syscall get their impl_fn set;
+ * unmatched entries remain NULL (will error at runtime if called). */
+void spl_syscall_register(spl_prog_t *prog);
+
+#endif /* __SPL_SYSCALL_H__ */

stage0/spl_vm.h

@@ -0,0 +1,80 @@
+/* spl_vm.h - SIR interpreter */
+
+#ifndef __SPL_VM_H__
+#define __SPL_VM_H__
+
+#include "include/core_vec.h"
+#include "spl_mcode.h"
+#include <stdint.h>
+
+#define SPL_STACK_CANARY ((spl_vm_val_t)0xDEADBEEFCAFEBABEull)
+
+typedef struct {
+    uintptr_t saved_sp;
+    uintptr_t saved_fp;
+    uintptr_t saved_ip;
+    spl_vm_val_t nargs;
+} spl_callframe_t;
+
+typedef VEC(spl_vm_val_t) spl_stack_vec_t;
+typedef VEC(spl_callframe_t) spl_frame_vec_t;
+
+typedef struct spl_vm {
+    spl_stack_vec_t stacks;
+    spl_frame_vec_t frames;
+    uintptr_t gp; // global pointer
+    uintptr_t sp; // stack pointer
+    uintptr_t fp; // frame pointer
+    uintptr_t cp; // call pointer
+    uintptr_t ip; // instr pointer
+    int exit_code;
+    int trace;                  /* non-zero to print each instruction */
+    int debug;                  /* non-zero to enable canary checks */
+    int debug_addr;             /* non-zero to check for low-address memory access */
+    int skip_bp;                /* non-zero: run_once 忽略下一次断点（continue 越过当前断点指令） */
+    VEC(usize) breakpoints;     /* ip 断点（执行到该指令前暂停，run_once 返回 2） */
+    VEC(char *) fn_breakpoints; /* 函数名断点（CALL/CALLI 目标函数入口暂停） */
+    spl_prog_t *prog;
+    char error_msg[1024];
+    struct {
+        uintptr_t max_stack_depth;
+        uintptr_t max_call_depth;
+    } config;
+} spl_vm_t;
+
+/* Initialize VM with default sizes (SPL_DEFAULT_STACK_SIZE /
+ * SPL_DEFAULT_CALL_DEPTH) */
+void spl_vm_init(spl_vm_t *vm);
+
+/* Initialize VM with custom sizes (pass 0 to use defaults) */
+void spl_vm_init_ex(spl_vm_t *vm, int stack_size, int call_depth);
+
+/* Free dynamically allocated memory in VM */
+void spl_vm_drop(spl_vm_t *vm);
+
+int spl_vm_addr_valid(uintptr_t p, usize size);
+
+int spl_vm_load_prog(spl_vm_t *vm, spl_prog_t *prog);
+int spl_vm_prepare(spl_vm_t *vm, const char *entry, int argc, const char **argv, const char **envp);
+
+/* Enable/disable instruction-level tracing */
+void spl_vm_set_trace(spl_vm_t *vm, int enabled);
+
+/* Enable/disable debug mode (stack canary protection) */
+void spl_vm_set_debug(spl_vm_t *vm, int enabled);
+
+int spl_vm_run_once(spl_vm_t *vm);
+int spl_vm_run_until(spl_vm_t *vm, size_t step);
+
+/* 断点：ip 断点 / 函数名断点（CALL/CALLI 目标函数入口）。命中时 run_once 返回 2。 */
+void spl_vm_add_breakpoint(spl_vm_t *vm, usize ip);
+void spl_vm_add_breakpoint_fn(spl_vm_t *vm, const char *name);
+void spl_vm_clear_breakpoints(spl_vm_t *vm);
+/* 让 run_once 执行当前指令（忽略一次断点命中）；continue 越过当前断点用 */
+void spl_vm_skip_breakpoint(spl_vm_t *vm);
+
+void spl_vm_dump_instr(spl_vm_t *vm, spl_vm_val_t ip);
+void spl_vm_stackdump(spl_vm_t *vm, spl_vm_val_t sp);
+int spl_vm_backtrace(spl_vm_t *vm, spl_vm_val_t fp);
+
+#endif /* __SPL_VM_H__ */

stage0/test_spl_vm.c

@@ -0,0 +1,878 @@
+/* test_spl_vm.c – unit tests for SPL VM using acutest.h
+ *
+ * Constructs SIR binaries, writes to temp files, loads via
+ * spl_prog_load_from_file, and runs via the spl_vm_t API.
+ */
+
+#include "include/acutest.h"
+#include "spl_mcode.h"
+#include "spl_vm.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ================================================================
+ * Binary-writing helpers (mirrors spl_mcode.c internal format)
+ * ================================================================ */
+
+/* Write spl_val_t (8 LE bytes), advance pointer */
+#define LE64(p, v)                                                                                 \
+    do {                                                                                           \
+        unsigned char *_p = (p);                                                                   \
+        spl_vm_val_t _v = (spl_vm_val_t)(v);                                                       \
+        *_p++ = (unsigned char)(_v);                                                               \
+        *_p++ = (unsigned char)(_v >> 8);                                                          \
+        *_p++ = (unsigned char)(_v >> 16);                                                         \
+        *_p++ = (unsigned char)(_v >> 24);                                                         \
+        *_p++ = (unsigned char)(_v >> 32);                                                         \
+        *_p++ = (unsigned char)(_v >> 40);                                                         \
+        *_p++ = (unsigned char)(_v >> 48);                                                         \
+        *_p++ = (unsigned char)(_v >> 56);                                                         \
+        (p) = _p;                                                                                  \
+    } while (0)
+
+/* Convenience: build spl_ins_t from raw fields */
+static spl_vm_ins_t ins(uint16_t op, uint16_t type, spl_vm_val_t imm) {
+    spl_vm_ins_t x;
+    x.opcode = op;
+    x.type = type;
+    x.imm = imm;
+    return x;
+}
+
+/* Build a single-function SIR binary in malloc'd memory.
+ * Returns buffer that must be freed by caller. */
+static unsigned char *build_binary(const char *fname, spl_vm_val_t nargs,
+                                   const spl_vm_ins_t *instns, int ninsns, size_t *out_len) {
+    size_t nlen = strlen(fname) + 1;
+    size_t npad = ((nlen + 7) / 8) * 8 - nlen;
+    size_t sz = 8 + 8 + 8 + 8 + 8 + 8             /* magic + 5 counts */
+                + 8 + nlen + npad + 8 + 8 + 8 + 8 /* func entry */
+                + (size_t)ninsns * 12;            /* instructions */
+    unsigned char *buf = (unsigned char *)malloc(sz);
+    unsigned char *p = buf;
+
+    memcpy(p, "SPLBIN\0\0", 8);
+    p += 8;                        /* magic */
+    LE64(p, 1);                    /* nfuncs */
+    LE64(p, (spl_vm_val_t)ninsns); /* ninsns */
+    LE64(p, 0);                    /* nnatives */
+    LE64(p, 0);                    /* nstrs */
+    LE64(p, 0);                    /* ndata */
+
+    /* func entry */
+    LE64(p, (spl_vm_val_t)nlen); /* name_len */
+    memcpy(p, fname, nlen);
+    p += nlen;
+    memset(p, 0, npad);
+    p += npad;
+    LE64(p, 0); /* idx_of_strtab */
+    LE64(p, nargs);
+    LE64(p, (spl_vm_val_t)ninsns);
+    LE64(p, 0); /* address = 0 */
+
+    for (int i = 0; i < ninsns; i++) {
+        *p++ = (unsigned char)(instns[i].opcode);
+        *p++ = (unsigned char)(instns[i].opcode >> 8);
+        *p++ = (unsigned char)(instns[i].type);
+        *p++ = (unsigned char)(instns[i].type >> 8);
+        LE64(p, instns[i].imm);
+    }
+
+    *out_len = sz;
+    return buf;
+}
+
+/* ================================================================
+ * VM test helpers (file-based prog load)
+ * ================================================================ */
+
+static const char *TMPFILE = "test_spl_vm_tmp.bin";
+
+/* Write binary buffer to temp file */
+static int write_temp(const unsigned char *bin, size_t len) {
+    FILE *f = fopen(TMPFILE, "wb");
+    if (!f)
+        return -1;
+    fwrite(bin, 1, len, f);
+    fclose(f);
+    return 0;
+}
+
+/* Run a single-function program, return exit code (or -1 on failure). */
+static int run(const spl_vm_ins_t *instns, int ninsns) {
+    size_t len;
+    unsigned char *bin = build_binary("main", 0, instns, ninsns, &len);
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, len) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        if (spl_vm_load_prog(&vm, &prog) == 0) {
+            if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+                int ret = spl_vm_run_until(&vm, 0);
+                if (ret == 1) /* halted normally */
+                    rc = (int)vm.exit_code;
+                else if (ret == 0) /* still running (shouldn't happen with halt) */
+                    rc = -2;
+            }
+        }
+    }
+    spl_vm_drop(&vm);
+    remove(TMPFILE);
+    free(bin);
+    return rc;
+}
+
+/* Run with native functions registered. */
+static int run_with_natives(const spl_vm_ins_t *instns, int ninsns, spl_vm_native_t *natives,
+                            int nnatives) {
+    size_t len;
+    unsigned char *bin = build_binary("main", 0, instns, ninsns, &len);
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, len) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        for (int i = 0; i < nnatives; i++)
+            spl_prog_add_native(&prog, &natives[i]);
+        if (spl_vm_load_prog(&vm, &prog) == 0) {
+            if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+                int ret = spl_vm_run_until(&vm, 0);
+                if (ret == 1)
+                    rc = (int)vm.exit_code;
+                else if (ret == 0)
+                    rc = -2;
+            }
+        }
+    }
+    spl_vm_drop(&vm);
+    remove(TMPFILE);
+    free(bin);
+    return rc;
+}
+
+/* ================================================================
+ * Native function for NCALL tests
+ * ================================================================ */
+
+static spl_vm_val_t native_add_impl(int nargs, spl_vm_val_t *args) {
+    return (nargs >= 2) ? args[0] + args[1] : 0;
+}
+
+/* ================================================================
+ * Stack tests
+ * ================================================================ */
+
+void test_push_imm(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 42), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 2) == 42);
+}
+
+void test_dup(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 99), ins(SPL_DUP, SPL_VOID, 0),
+                        ins(SPL_ADD, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 198);
+}
+
+void test_drop(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 1), ins(SPL_PUSH, SPL_I32, 2),
+                        ins(SPL_DROP, SPL_VOID, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_swap(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 1), ins(SPL_PUSH, SPL_I32, 2),
+                        ins(SPL_SWAP, SPL_VOID, 0), ins(SPL_DROP, SPL_VOID, 0),
+                        ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 5) == 2);
+}
+
+void test_pick(void) {
+    /* push 10, 20, 30, pick 1 -> copy 20, add -> 50 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 10), ins(SPL_PUSH, SPL_I32, 20),
+                        ins(SPL_PUSH, SPL_I32, 30), ins(SPL_PICK, SPL_VOID, 1),
+                        ins(SPL_ADD, SPL_I32, 0),   ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 6) == 50);
+}
+
+/* ================================================================
+ * Arithmetic tests
+ * ================================================================ */
+
+void test_add(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 2), ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_ADD, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 5);
+}
+
+void test_sub(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 10), ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_SUB, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 7);
+}
+
+void test_mul(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 6), ins(SPL_PUSH, SPL_I32, 7),
+                        ins(SPL_MUL, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 42);
+}
+
+void test_div(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 100), ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_DIV_S, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 33);
+}
+
+void test_rem(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 100), ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_REM_S, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_neg(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 42), ins(SPL_NEG, SPL_I32, 0),
+                        ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 3) == -42);
+}
+
+void test_i64_arith(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I64, 42), ins(SPL_RET, SPL_I64, 0)};
+    TEST_CHECK(run(p, 2) == 42);
+}
+
+/* ================================================================
+ * Bitwise tests
+ * ================================================================ */
+
+void test_and(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFF00), ins(SPL_PUSH, SPL_U32, 0x0FF0),
+                        ins(SPL_AND, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 0x0F00);
+}
+
+void test_or(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFF00), ins(SPL_PUSH, SPL_U32, 0x00FF),
+                        ins(SPL_OR, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 0xFFFF);
+}
+
+void test_xor(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFF), ins(SPL_PUSH, SPL_U32, 0x0FF0),
+                        ins(SPL_XOR, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 0xF00F);
+}
+
+void test_not(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFF0000), ins(SPL_NOT, SPL_U32, 0),
+                        ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 3) == (unsigned int)0x0000FFFF);
+}
+
+void test_shl(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 1), ins(SPL_PUSH, SPL_U32, 10),
+                        ins(SPL_SHL, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1024);
+}
+
+void test_shr(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 1024), ins(SPL_PUSH, SPL_U32, 10),
+                        ins(SPL_SHR_U, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_shr_s(void) {
+    /* arithmetic right shift: -1024 >> 5 sign-extends */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, (spl_vm_val_t)(int32_t)-1024),
+                        ins(SPL_PUSH, SPL_U32, 5), ins(SPL_SHR_S, SPL_I32, 0),
+                        ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == -32);
+}
+
+/* ================================================================
+ * Comparison tests
+ * ================================================================ */
+
+void test_eq(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 42), ins(SPL_PUSH, SPL_I32, 42),
+                        ins(SPL_EQ, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_neq(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 42), ins(SPL_PUSH, SPL_I32, 99),
+                        ins(SPL_NE, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_lt(void) {
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 10), ins(SPL_PUSH, SPL_I32, 20),
+                        ins(SPL_SLT, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_gt_signed(void) {
+    /* -1 > 1 should be 0 (false) for signed compare */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_I32, 1),
+                        ins(SPL_SGT, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 0);
+}
+
+void test_sle(void) {
+    /* -1 <= 1 -> true (1) for signed */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_I32, 1),
+                        ins(SPL_SLE, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_sge(void) {
+    /* -1 >= 1 -> false (0) for signed */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_I32, 1),
+                        ins(SPL_SGE, SPL_I32, 0), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 4) == 0);
+}
+
+void test_ult(void) {
+    /* 0xFFFFFFFF < 1 -> false (0) for unsigned */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_U32, 1),
+                        ins(SPL_ULT, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 0);
+}
+
+void test_ule(void) {
+    /* 0xFFFFFFFF <= 0xFFFFFFFF -> true (1) */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_U32, 0xFFFFFFFF),
+                        ins(SPL_ULE, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_ugt(void) {
+    /* 0xFFFFFFFF > 1 -> true (1) for unsigned */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_U32, 1),
+                        ins(SPL_UGT, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+void test_uge(void) {
+    /* 0xFFFFFFFF >= 1 -> true (1) */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFFFFFF), ins(SPL_PUSH, SPL_U32, 1),
+                        ins(SPL_UGE, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+/* ================================================================
+ * Control flow tests (relative offset)
+ * ================================================================ */
+
+void test_jmp(void) {
+    /* push 1, jmp +3 (skip next 2 insns), push 2 (skipped), push 3, add, ret -> 4 */
+    /* jmp at ip=1, after fetch ip=2, target ip=3 (push 3) => offset = 1 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 1), ins(SPL_JMP, SPL_VOID, 1),
+                        ins(SPL_PUSH, SPL_I32, 2), ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_ADD, SPL_I32, 0),  ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 6) == 4);
+}
+
+void test_bz_bnz(void) {
+    /* push 0, bz +2 (skip to ret with 1) -> return 1 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 0),  ins(SPL_BZ, SPL_VOID, 2),
+                        ins(SPL_PUSH, SPL_I32, 99), ins(SPL_RET, SPL_I32, 0),
+                        ins(SPL_PUSH, SPL_I32, 1),  ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 6) == 1);
+
+    /* push 1, bnz +2 (skip to ret with 42) -> return 42 */
+    spl_vm_ins_t q[] = {ins(SPL_PUSH, SPL_I32, 1),  ins(SPL_BNZ, SPL_VOID, 2),
+                        ins(SPL_PUSH, SPL_I32, 99), ins(SPL_RET, SPL_I32, 0),
+                        ins(SPL_PUSH, SPL_I32, 42), ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(q, 6) == 42);
+}
+
+/* ================================================================
+ * Memory tests (ALLOC, LADDR, LD, ST)
+ * ================================================================ */
+
+void test_alloc_laddr_st64_ld64(void) {
+    /* alloc 1 local, laddr + st64 42, laddr + ld64 back -> 42 */
+    spl_vm_ins_t p[] = {
+        ins(SPL_ALLOC, SPL_VOID, 1), /* 0: alloc 1 local */
+        ins(SPL_LADDR, SPL_VOID, 0), /* 1: addr of local[0] */
+        ins(SPL_PUSH, SPL_I64, 42),  /* 2: value */
+        ins(SPL_STORE, SPL_I64, 0),  /* 3: store */
+        ins(SPL_LADDR, SPL_VOID, 0), /* 4: addr of local[0] */
+        ins(SPL_LOAD, SPL_I64, 0),   /* 5: load */
+        ins(SPL_RET, SPL_I64, 0)     /* 6: ret */
+    };
+    TEST_CHECK(run(p, 7) == 42);
+}
+
+void test_alloc_zeroed(void) {
+    /* alloc 1 local, laddr + ld64 -> should be 0 (zero-initialized) */
+    spl_vm_ins_t p[] = {ins(SPL_ALLOC, SPL_VOID, 1), ins(SPL_LADDR, SPL_VOID, 0),
+                        ins(SPL_LOAD, SPL_I64, 0), ins(SPL_RET, SPL_I64, 0)};
+    TEST_CHECK(run(p, 4) == 0);
+}
+
+/* ================================================================
+ * Indirect memory load/store tests (stack-based, no heap)
+ * ================================================================ */
+
+void test_ld_st64(void) {
+    /* alloc 8 slots, st64 42, ld64 back -> 42 */
+    spl_vm_ins_t p[] = {ins(SPL_ALLOC, SPL_VOID, 8), ins(SPL_LADDR, SPL_VOID, 0),
+                        ins(SPL_DUP, SPL_VOID, 0),   ins(SPL_PUSH, SPL_I64, 42),
+                        ins(SPL_STORE, SPL_I64, 0),  ins(SPL_LOAD, SPL_I64, 0),
+                        ins(SPL_RET, SPL_I64, 0)};
+    TEST_CHECK(run(p, 7) == 42);
+}
+
+void test_ld_st32(void) {
+    spl_vm_ins_t p[] = {ins(SPL_ALLOC, SPL_VOID, 8), ins(SPL_LADDR, SPL_VOID, 0),
+                        ins(SPL_DUP, SPL_VOID, 0),   ins(SPL_PUSH, SPL_I64, 0xAABBCCDD),
+                        ins(SPL_STORE, SPL_U32, 0),  ins(SPL_LOAD, SPL_U32, 0),
+                        ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 7) == (int)0xAABBCCDD);
+}
+
+void test_ld_st16(void) {
+    spl_vm_ins_t p[] = {ins(SPL_ALLOC, SPL_VOID, 8), ins(SPL_LADDR, SPL_VOID, 0),
+                        ins(SPL_DUP, SPL_VOID, 0),   ins(SPL_PUSH, SPL_I64, 0xBEEF),
+                        ins(SPL_STORE, SPL_U16, 0),  ins(SPL_LOAD, SPL_U16, 0),
+                        ins(SPL_RET, SPL_U16, 0)};
+    TEST_CHECK(run(p, 7) == 0xBEEF);
+}
+
+void test_ld_st8(void) {
+    spl_vm_ins_t p[] = {ins(SPL_ALLOC, SPL_VOID, 8), ins(SPL_LADDR, SPL_VOID, 0),
+                        ins(SPL_DUP, SPL_VOID, 0),   ins(SPL_PUSH, SPL_I64, 0xAB),
+                        ins(SPL_STORE, SPL_U8, 0),   ins(SPL_LOAD, SPL_U8, 0),
+                        ins(SPL_RET, SPL_U8, 0)};
+    TEST_CHECK(run(p, 7) == 0xAB);
+}
+
+/* ================================================================
+ * Function call tests (relative offset CALL)
+ * ================================================================ */
+
+void test_call_add(void) {
+    /*
+     * add(a, b)   address 0, 6 insns, 2 args
+     * main()      address 6, 5 insns, 0 args
+     *
+     * add (ip=0):
+     *   laddr 0     ip=0   arg0 addr
+     *   ld64        ip=1   load arg0
+     *   laddr 1     ip=2   arg1 addr
+     *   ld64        ip=3   load arg1
+     *   add i64     ip=4
+     *   ret i64     ip=5
+     *
+     * main (ip=6):
+     *   push 10     ip=6
+     *   push 20     ip=7
+     *   push 0      ip=8   target address = add at 0
+     *   call 2      ip=9   nargs=2
+     *   ret i64     ip=10
+     */
+    spl_vm_ins_t add_insns[] = {ins(SPL_LADDR, SPL_VOID, 0), ins(SPL_LOAD, SPL_I64, 0),
+                                ins(SPL_LADDR, SPL_VOID, 8), ins(SPL_LOAD, SPL_I64, 0),
+                                ins(SPL_ADD, SPL_I64, 0),    ins(SPL_RET, SPL_I64, 0)};
+    spl_vm_ins_t main_insns[] = {ins(SPL_PUSH, SPL_I32, 10), ins(SPL_PUSH, SPL_I32, 20),
+                                 ins(SPL_PUSH, SPL_VOID, 0), ins(SPL_CALL, SPL_VOID, 2),
+                                 ins(SPL_RET, SPL_I64, 0)};
+
+    int nadd = (int)(sizeof(add_insns) / sizeof(add_insns[0]));
+    int nmain = (int)(sizeof(main_insns) / sizeof(main_insns[0]));
+    int ninsns_t = nadd + nmain;
+    size_t nlen0 = strlen("add") + 1;
+    size_t npad0 = ((nlen0 + 7) / 8) * 8 - nlen0;
+    size_t nlen1 = strlen("main") + 1;
+    size_t npad1 = ((nlen1 + 7) / 8) * 8 - nlen1;
+    size_t sz = 8 + 8 + 8 + 8 + 8 + 8               /* magic + 5 counts */
+                + 8 + nlen0 + npad0 + 8 + 8 + 8 + 8 /* func 0 */
+                + 8 + nlen1 + npad1 + 8 + 8 + 8 + 8 /* func 1 */
+                + (size_t)ninsns_t * 12;
+    unsigned char *bin = (unsigned char *)malloc(sz);
+    unsigned char *p = bin;
+
+    memcpy(p, "SPLBIN\0\0", 8);
+    p += 8;
+    LE64(p, 2);
+    LE64(p, (spl_vm_val_t)ninsns_t);
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, 0);
+
+    /* func[0]: "add" */
+    LE64(p, (spl_vm_val_t)nlen0);
+    memcpy(p, "add", nlen0);
+    p += nlen0;
+    memset(p, 0, npad0);
+    p += npad0;
+    LE64(p, 0);
+    LE64(p, 2);
+    LE64(p, (spl_vm_val_t)nadd);
+    LE64(p, 0);
+
+    /* func[1]: "main" */
+    LE64(p, (spl_vm_val_t)nlen1);
+    memcpy(p, "main", nlen1);
+    p += nlen1;
+    memset(p, 0, npad1);
+    p += npad1;
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, (spl_vm_val_t)nmain);
+    LE64(p, (spl_vm_val_t)nadd); /* address */
+
+    for (int i = 0; i < nadd; i++) {
+        *p++ = (unsigned char)(add_insns[i].opcode);
+        *p++ = (unsigned char)(add_insns[i].opcode >> 8);
+        *p++ = (unsigned char)(add_insns[i].type);
+        *p++ = (unsigned char)(add_insns[i].type >> 8);
+        LE64(p, add_insns[i].imm);
+    }
+    for (int i = 0; i < nmain; i++) {
+        *p++ = (unsigned char)(main_insns[i].opcode);
+        *p++ = (unsigned char)(main_insns[i].opcode >> 8);
+        *p++ = (unsigned char)(main_insns[i].type);
+        *p++ = (unsigned char)(main_insns[i].type >> 8);
+        LE64(p, main_insns[i].imm);
+    }
+
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, sz) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        spl_vm_load_prog(&vm, &prog);
+        if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+            int ret = spl_vm_run_until(&vm, 0);
+            if (ret == 1)
+                rc = (int)vm.exit_code;
+        }
+        spl_vm_drop(&vm);
+    }
+    remove(TMPFILE);
+    free(bin);
+    TEST_CHECK(rc == 30);
+}
+
+/* ================================================================
+ * CALLI test
+ * ================================================================ */
+
+void test_calli(void) {
+    /*
+     * add (ip=0, 2 args):
+     *   laddr 0     ip=0
+     *   ld64        ip=1
+     *   laddr 1     ip=2
+     *   ld64        ip=3
+     *   add i64     ip=4
+     *   ret i64     ip=5
+     *
+     * main (ip=6, 0 args):
+     *   push 10     ip=6
+     *   push 20     ip=7
+     *   push 2      ip=8  (nargs)
+     *   push 0      ip=9  (address of add)
+     *   calli       ip=10
+     *   ret i64     ip=11
+     */
+    spl_vm_ins_t add_insns[] = {ins(SPL_LADDR, SPL_VOID, 0), ins(SPL_LOAD, SPL_I64, 0),
+                                ins(SPL_LADDR, SPL_VOID, 8), ins(SPL_LOAD, SPL_I64, 0),
+                                ins(SPL_ADD, SPL_I64, 0),    ins(SPL_RET, SPL_I64, 0)};
+    spl_vm_ins_t main_insns[] = {ins(SPL_PUSH, SPL_I32, 10),  ins(SPL_PUSH, SPL_I32, 20),
+                                 ins(SPL_PUSH, SPL_VOID, 2),  ins(SPL_PUSH, SPL_VOID, 0),
+                                 ins(SPL_CALLI, SPL_VOID, 0), ins(SPL_RET, SPL_I64, 0)};
+
+    int ninsns_t = 6 + 6;
+    size_t nlen0 = strlen("add") + 1;
+    size_t npad0 = ((nlen0 + 7) / 8) * 8 - nlen0;
+    size_t nlen1 = strlen("main") + 1;
+    size_t npad1 = ((nlen1 + 7) / 8) * 8 - nlen1;
+    size_t sz = 8 + 8 + 8 + 8 + 8 + 8 + 8 + nlen0 + npad0 + 8 + 8 + 8 + 8 + 8 + nlen1 + npad1 + 8 +
+                8 + 8 + 8 + (size_t)ninsns_t * 12;
+    unsigned char *bin = (unsigned char *)malloc(sz);
+    unsigned char *p = bin;
+
+    memcpy(p, "SPLBIN\0\0", 8);
+    p += 8;
+    LE64(p, 2);
+    LE64(p, (spl_vm_val_t)ninsns_t);
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, 0);
+
+    /* func[0]: add */
+    LE64(p, (spl_vm_val_t)nlen0);
+    memcpy(p, "add", nlen0);
+    p += nlen0;
+    memset(p, 0, npad0);
+    p += npad0;
+    LE64(p, 0);
+    LE64(p, 2);
+    LE64(p, 6);
+    LE64(p, 0);
+
+    /* func[1]: main */
+    LE64(p, (spl_vm_val_t)nlen1);
+    memcpy(p, "main", nlen1);
+    p += nlen1;
+    memset(p, 0, npad1);
+    p += npad1;
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, 6);
+    LE64(p, 6);
+
+    for (int i = 0; i < 6; i++) {
+        *p++ = (unsigned char)(add_insns[i].opcode);
+        *p++ = (unsigned char)(add_insns[i].opcode >> 8);
+        *p++ = (unsigned char)(add_insns[i].type);
+        *p++ = (unsigned char)(add_insns[i].type >> 8);
+        LE64(p, add_insns[i].imm);
+    }
+    for (int i = 0; i < 6; i++) {
+        *p++ = (unsigned char)(main_insns[i].opcode);
+        *p++ = (unsigned char)(main_insns[i].opcode >> 8);
+        *p++ = (unsigned char)(main_insns[i].type);
+        *p++ = (unsigned char)(main_insns[i].type >> 8);
+        LE64(p, main_insns[i].imm);
+    }
+
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, sz) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        spl_vm_load_prog(&vm, &prog);
+        if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+            int ret = spl_vm_run_until(&vm, 0);
+            if (ret == 1)
+                rc = (int)vm.exit_code;
+        }
+        spl_vm_drop(&vm);
+    }
+    remove(TMPFILE);
+    free(bin);
+    TEST_CHECK(rc == 30);
+}
+
+/* ================================================================
+ * Global data (GADDR) test
+ * ================================================================ */
+
+void test_gaddr_ld32(void) {
+    /* Load program, add global data, GADDR + LD32 to read it back */
+    spl_vm_ins_t p[] = {ins(SPL_GADDR, SPL_VOID, 0), ins(SPL_LOAD, SPL_U32, 0),
+                        ins(SPL_RET, SPL_U32, 0)};
+    size_t len;
+    unsigned char *bin = build_binary("main", 0, p, 3, &len);
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, len) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        uint32_t val = 0xDEADBEEF;
+        spl_prog_add_data(&prog, &val, sizeof(val));
+
+        spl_vm_load_prog(&vm, &prog);
+        if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+            int ret = spl_vm_run_until(&vm, 0);
+            if (ret == 1)
+                rc = (int)vm.exit_code;
+        }
+        spl_vm_drop(&vm);
+    }
+    remove(TMPFILE);
+    free(bin);
+    TEST_CHECK(rc == (int)0xDEADBEEF);
+}
+
+void test_gaddr_multi(void) {
+    /* Two global data entries: read second one via GADDR 1 */
+    spl_vm_ins_t p[] = {ins(SPL_GADDR, SPL_VOID, 1), ins(SPL_LOAD, SPL_U32, 0),
+                        ins(SPL_RET, SPL_U32, 0)};
+    size_t len;
+    unsigned char *bin = build_binary("main", 0, p, 3, &len);
+    spl_prog_t prog;
+    spl_vm_t vm;
+    int rc = -1;
+
+    spl_vm_init(&vm);
+    if (write_temp(bin, len) == 0 && spl_prog_load_from_file(TMPFILE, &prog) == 0) {
+        uint32_t a = 0xAAAAAAAA, b = 0xBBBBBBBB;
+        spl_prog_add_data(&prog, &a, sizeof(a));
+        spl_prog_add_data(&prog, &b, sizeof(b));
+
+        spl_vm_load_prog(&vm, &prog);
+        if (spl_vm_prepare(&vm, "main", 0, NULL, NULL) == 0) {
+            int ret = spl_vm_run_until(&vm, 0);
+            if (ret == 1)
+                rc = (int)vm.exit_code;
+        }
+        spl_vm_drop(&vm);
+    }
+    remove(TMPFILE);
+    free(bin);
+    TEST_CHECK(rc == (int)0xBBBBBBBB);
+}
+
+/* ================================================================
+ * Native call test
+ * ================================================================ */
+
+void test_ncall(void) {
+    /* main() -> i32 { return native_add(30, 12); } */
+    /* NCALL imm = nargs, native index is pushed separately */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 30), ins(SPL_PUSH, SPL_I32, 12),
+                        ins(SPL_PUSH, SPL_VOID, 0), ins(SPL_NCALL, SPL_I32, 2),
+                        ins(SPL_RET, SPL_I32, 0)};
+    spl_vm_native_t nat[] = {{"native_add", 0, native_add_impl}};
+    TEST_CHECK(run_with_natives(p, 5, nat, 1) == 42);
+}
+
+/* ================================================================
+ * Type conversion tests
+ * ================================================================ */
+
+void test_trunc(void) {
+    /* push 0xABCD, trunc to 8 bits -> 0xCD */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xABCD), ins(SPL_TRUNC, SPL_U8, 8),
+                        ins(SPL_RET, SPL_U8, 0)};
+    TEST_CHECK(run(p, 3) == 0xCD);
+}
+
+void test_sext(void) {
+    /* push 0x80, sext from 8 bits -> 0xFFFFFF80 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 0x80), ins(SPL_SEXT, SPL_I32, 8),
+                        ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 3) == (int)(int8_t)(0x80));
+}
+
+void test_zext(void) {
+    /* push 0xFFFF, zext from 8 bits -> 0xFF */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 0xFFFF), ins(SPL_ZEXT, SPL_U32, 8),
+                        ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 3) == 0xFF);
+}
+
+/* ================================================================
+ * Extended arithmetic tests (unsigned div/rem)
+ * ================================================================ */
+
+void test_div_u(void) {
+    /* unsigned: 100 / 3 = 33 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 100), ins(SPL_PUSH, SPL_U32, 3),
+                        ins(SPL_DIV_U, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 33);
+}
+
+void test_rem_u(void) {
+    /* unsigned: 100 % 3 = 1 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_U32, 100), ins(SPL_PUSH, SPL_U32, 3),
+                        ins(SPL_REM_U, SPL_U32, 0), ins(SPL_RET, SPL_U32, 0)};
+    TEST_CHECK(run(p, 4) == 1);
+}
+
+/* ================================================================
+ * Edge case tests
+ * ================================================================ */
+
+void test_many_ops(void) {
+    /* (1+2) * (3+4) = 21 */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 1), ins(SPL_PUSH, SPL_I32, 2),
+                        ins(SPL_ADD, SPL_I32, 0),  ins(SPL_PUSH, SPL_I32, 3),
+                        ins(SPL_PUSH, SPL_I32, 4), ins(SPL_ADD, SPL_I32, 0),
+                        ins(SPL_MUL, SPL_I32, 0),  ins(SPL_RET, SPL_I32, 0)};
+    TEST_CHECK(run(p, 8) == 21);
+}
+
+void test_halt(void) {
+    /* push 77, halt -> exit code 0 (HALT doesn't pop) */
+    spl_vm_ins_t p[] = {ins(SPL_PUSH, SPL_I32, 77), ins(SPL_HALT, SPL_VOID, 0)};
+    TEST_CHECK(run(p, 2) == 0);
+}
+
+/* ================================================================
+ * Bad program tests
+ * ================================================================ */
+
+void test_bad_magic(void) {
+    unsigned char bad[8] = {0, 0, 0, 0, 0, 0, 0, 0};
+    spl_prog_t prog;
+    if (write_temp(bad, 8) == 0) {
+        TEST_CHECK(spl_prog_load_from_file(TMPFILE, &prog) != 0);
+        remove(TMPFILE);
+    }
+}
+
+void test_empty(void) {
+    TEST_CHECK(spl_prog_load_from_file("nonexistent_file_xyz.bin", NULL) != 0);
+}
+
+/* ================================================================
+ * Test list
+ * ================================================================ */
+
+TEST_LIST = {
+    {"push", test_push_imm},
+    {"dup", test_dup},
+    {"drop", test_drop},
+    {"swap", test_swap},
+    {"pick", test_pick},
+    {"add", test_add},
+    {"sub", test_sub},
+    {"mul", test_mul},
+    {"div", test_div},
+    {"rem", test_rem},
+    {"neg", test_neg},
+    {"i64_arith", test_i64_arith},
+    {"and", test_and},
+    {"or", test_or},
+    {"xor", test_xor},
+    {"not", test_not},
+    {"shl", test_shl},
+    {"shr", test_shr},
+    {"shr_s", test_shr_s},
+    {"eq", test_eq},
+    {"neq", test_neq},
+    {"lt", test_lt},
+    {"gt_signed", test_gt_signed},
+    {"sle", test_sle},
+    {"sge", test_sge},
+    {"ult", test_ult},
+    {"ule", test_ule},
+    {"ugt", test_ugt},
+    {"uge", test_uge},
+    {"jmp", test_jmp},
+    {"bz_bnz", test_bz_bnz},
+    {"alloc_laddr_ld_st", test_alloc_laddr_st64_ld64},
+    {"alloc_zeroed", test_alloc_zeroed},
+    {"call_add", test_call_add},
+    {"calli", test_calli},
+    {"gaddr_ld32", test_gaddr_ld32},
+    {"gaddr_multi", test_gaddr_multi},
+    {"ncall", test_ncall},
+    {"div_u", test_div_u},
+    {"rem_u", test_rem_u},
+    {"trunc", test_trunc},
+    {"sext", test_sext},
+    {"zext", test_zext},
+    {"ld_st8", test_ld_st8},
+    {"ld_st16", test_ld_st16},
+    {"ld_st32", test_ld_st32},
+    {"ld_st64", test_ld_st64},
+    {"many_ops", test_many_ops},
+    {"halt", test_halt},
+    {"bad_magic", test_bad_magic},
+    {"empty", test_empty},
+    {NULL, NULL},
+};

stage1/spl_ast.c

@@ -0,0 +1,429 @@
+#include "spl_ast.h"
+
+const char *spl_ast_kind_name(spl_ast_node_kind_t kind) {
+    static const char *const names[] = {
+#define X(a, b, c) #c,
+        SPL_AST_KIND_TABLE
+#undef X
+    };
+    if ((usize)kind < sizeof(names) / sizeof(names[0]))
+        return names[kind];
+    return "?";
+}
+
+const char *spl_binary_op_name(spl_binary_op_t op) {
+    static const char *const names[] = {
+#define X(a, b, c, name) #name,
+        SPL_BINARY_OP_TABLE
+#undef X
+    };
+    if ((usize)op < sizeof(names) / sizeof(names[0]))
+        return names[op];
+    return "?";
+}
+
+const char *spl_unary_op_name(spl_unary_op_t op) {
+    switch (op) {
+    case SPL_UNARY_OP_MINUS:
+        return "neg";
+    case SPL_UNARY_OP_NOT:
+        return "not";
+    case SPL_UNARY_OP_BIT_NOT:
+        return "bitnot";
+    case SPL_UNARY_OP_ADDRESS:
+        return "addr";
+    case SPL_UNARY_OP_DEREF:
+        return "deref";
+    default:
+        return "?";
+    }
+}
+
+void spl_ast_init(spl_ast_t *ast, const spl_tok_vec_t *tok_vec) {
+    ast->input = *tok_vec;
+    vec_init(ast->node_buckets);
+    vec_init(ast->str_buckets);
+    ast->root = 0;
+
+    spl_ast_node_t n = {0};
+    vec_push(ast->node_buckets, n);
+}
+
+void spl_ast_drop(spl_ast_t *ast) {
+    if (!ast)
+        return;
+    vec_for(ast->str_buckets, idx) { free(vec_at(ast->str_buckets, idx)); }
+    vec_free(ast->str_buckets);
+    vec_for(ast->node_buckets, idx) { vec_free(vec_at(ast->node_buckets, idx).attrs); }
+    vec_free(ast->node_buckets);
+    vec_free(ast->input);
+    ast->root = 0;
+}
+
+spl_ast_node_t *spl_ast_node(spl_ast_t *ast, spl_ast_node_ref_t node) {
+    if (!ast || node == 0 || node >= ast->node_buckets.size)
+        return NULL;
+    return &ast->node_buckets.data[node];
+}
+
+typedef VEC(char) dump_stack_t;
+
+static void dump_node(spl_ast_t *ast, spl_ast_node_ref_t node_ref, dump_stack_t *stack, bool last);
+
+void spl_ast_dump(spl_ast_t *ast, spl_ast_node_ref_t node) {
+    if (!ast || !node || node >= ast->node_buckets.size)
+        return;
+    dump_stack_t stack;
+    vec_init(stack);
+    printf("AST:\n");
+    dump_node(ast, node, &stack, true);
+    vec_free(stack);
+}
+
+#define dump_vec(_ast, _vec, _stack)                                                               \
+    do {                                                                                           \
+        vec_for(_vec, _i) { dump_node(_ast, vec_at(_vec, _i), _stack, _i + 1 == vec_size(_vec)); } \
+    } while (0)
+
+static void dump_node(spl_ast_t *ast, spl_ast_node_ref_t node_ref, dump_stack_t *stack, bool last) {
+    spl_ast_node_t *node = &ast->node_buckets.data[node_ref];
+
+    for (usize i = 0; i < vec_size(*stack); i++)
+        printf("%s", vec_at(*stack, i) ? "  " : "| ");
+    printf("%s%s #%zu", last ? "`-" : "|-", spl_ast_kind_name(node->kind), node_ref);
+    if (node->dbg.fname)
+        printf(" [%d:%d]", node->dbg.line, node->dbg.col);
+    printf("\n");
+
+    vec_push(*stack, last);
+
+    switch (node->kind) {
+    case SPL_AST_ROOT:
+        if (node->root.members)
+            dump_node(ast, node->root.members, stack, true);
+        break;
+
+    case SPL_AST_CONTAINER_MEMBERS:
+        dump_vec(ast, node->container_members.external_tags, stack);
+        dump_vec(ast, node->container_members.declarations, stack);
+        break;
+
+    case SPL_AST_TAG_ITEM:
+    case SPL_AST_EXTERNAL_TAG_ITEM:
+        dump_vec(ast, node->tag_item.args, stack);
+        break;
+
+    case SPL_AST_FN_DECL:
+        dump_vec(ast, node->fn_decl.tag_list, stack);
+        dump_vec(ast, node->fn_decl.params, stack);
+        if (node->fn_decl.ret_type)
+            dump_node(ast, node->fn_decl.ret_type, stack, false);
+        if (node->fn_decl.body)
+            dump_node(ast, node->fn_decl.body, stack, true);
+        break;
+
+    case SPL_AST_VAR_DECL:
+    case SPL_AST_CONST_DECL:
+        dump_vec(ast, node->var_const_decl.attr_list, stack);
+        if (node->var_const_decl.pattern)
+            dump_node(ast, node->var_const_decl.pattern, stack, false);
+        if (node->var_const_decl.type)
+            dump_node(ast, node->var_const_decl.type, stack, false);
+        if (node->var_const_decl.init_expr)
+            dump_node(ast, node->var_const_decl.init_expr, stack, true);
+        break;
+
+    case SPL_AST_TYPE_DECL:
+        if (node->type_decl.type_expr)
+            dump_node(ast, node->type_decl.type_expr, stack, true);
+        break;
+
+    case SPL_AST_MEMBER_DECL:
+        dump_vec(ast, node->member_decl.attr_list, stack);
+        if (node->member_decl.type_expr)
+            dump_node(ast, node->member_decl.type_expr, stack, false);
+        if (node->member_decl.init_expr)
+            dump_node(ast, node->member_decl.init_expr, stack, true);
+        break;
+
+    case SPL_AST_PARAM_DECL:
+        dump_vec(ast, node->param_decl.attr_list, stack);
+        if (node->param_decl.type_expr)
+            dump_node(ast, node->param_decl.type_expr, stack, true);
+        break;
+
+    case SPL_AST_COMPTIME_DECL:
+        if (node->comptime_decl.body)
+            dump_node(ast, node->comptime_decl.body, stack, true);
+        break;
+
+    case SPL_AST_TOP_LEVEL_BLOCK:
+        dump_vec(ast, node->top_level_block.tag_list, stack);
+        if (node->top_level_block.block)
+            dump_node(ast, node->top_level_block.block, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_RET:
+        if (node->statement_ret.expr)
+            dump_node(ast, node->statement_ret.expr, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_BREAK:
+        if (node->statement_break.label)
+            dump_node(ast, node->statement_break.label, stack, false);
+        if (node->statement_break.expr)
+            dump_node(ast, node->statement_break.expr, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_CONTINUE:
+        if (node->statement_continue.label)
+            dump_node(ast, node->statement_continue.label, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_DEFER:
+    case SPL_AST_STATEMENT_COMPTIME:
+        if (node->statement_defer.body)
+            dump_node(ast, node->statement_defer.body, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_DECL:
+        if (node->statement_decl.decl)
+            dump_node(ast, node->statement_decl.decl, stack, true);
+        break;
+
+    case SPL_AST_STATEMENT_EXPR:
+        if (node->statement_expr.expr)
+            dump_node(ast, node->statement_expr.expr, stack, true);
+        break;
+
+    case SPL_AST_AGGREGATE_MEMBER:
+        dump_vec(ast, node->aggregate_member.attr_list, stack);
+        if (node->aggregate_member.type_expr)
+            dump_node(ast, node->aggregate_member.type_expr, stack, false);
+        if (node->aggregate_member.init_expr)
+            dump_node(ast, node->aggregate_member.init_expr, stack, true);
+        break;
+
+    case SPL_AST_STRUCT_INIT_ITEM:
+        if (node->struct_init_item.expr)
+            dump_node(ast, node->struct_init_item.expr, stack, true);
+        break;
+
+    case SPL_AST_MATCH_ARM:
+        if (node->match_arm.pattern)
+            dump_node(ast, node->match_arm.pattern, stack, false);
+        if (node->match_arm.body)
+            dump_node(ast, node->match_arm.body, stack, true);
+        break;
+
+    case SPL_AST_LABEL:
+        break;
+
+    case SPL_AST_EXPR_INT_LIT:
+    case SPL_AST_EXPR_FLOAT_LIT:
+    case SPL_AST_EXPR_CHAR_LIT:
+    case SPL_AST_EXPR_STRING_LIT:
+    case SPL_AST_EXPR_BOOL_LIT:
+    case SPL_AST_EXPR_NULL_LIT:
+    case SPL_AST_EXPR_UNDEFINED_LIT:
+    case SPL_AST_EXPR_IDENT:
+        break;
+
+    case SPL_AST_EXPR_UNARY:
+        if (node->unary.operand)
+            dump_node(ast, node->unary.operand, stack, true);
+        break;
+
+    case SPL_AST_EXPR_BINARY:
+        if (node->binary.left)
+            dump_node(ast, node->binary.left, stack, false);
+        if (node->binary.right)
+            dump_node(ast, node->binary.right, stack, true);
+        break;
+
+    case SPL_AST_EXPR_CALL:
+        if (node->call.callee)
+            dump_node(ast, node->call.callee, stack, false);
+        dump_vec(ast, node->call.args, stack);
+        break;
+
+    case SPL_AST_EXPR_FIELD:
+        if (node->field.obj)
+            dump_node(ast, node->field.obj, stack, true);
+        break;
+
+    case SPL_AST_EXPR_INDEX:
+        if (node->index.obj)
+            dump_node(ast, node->index.obj, stack, false);
+        if (node->index.index)
+            dump_node(ast, node->index.index, stack, true);
+        break;
+
+    case SPL_AST_EXPR_SLICE:
+        if (node->slice.obj)
+            dump_node(ast, node->slice.obj, stack, false);
+        if (node->slice.begin)
+            dump_node(ast, node->slice.begin, stack, false);
+        if (node->slice.end)
+            dump_node(ast, node->slice.end, stack, true);
+        break;
+
+    case SPL_AST_EXPR_CAST:
+        if (node->cast.expr)
+            dump_node(ast, node->cast.expr, stack, false);
+        if (node->cast.type)
+            dump_node(ast, node->cast.type, stack, true);
+        break;
+
+    case SPL_AST_EXPR_TUPLE:
+        dump_vec(ast, node->tuple.elems, stack);
+        break;
+
+    case SPL_AST_EXPR_ARRAY_LIT:
+        if (node->array_literal.elem_type)
+            dump_node(ast, node->array_literal.elem_type, stack, false);
+        dump_vec(ast, node->array_literal.elems, stack);
+        break;
+
+    case SPL_AST_EXPR_AGGREGATE_LIT:
+        dump_vec(ast, node->aggregate_literal.fields, stack);
+        break;
+
+    case SPL_AST_EXPR_COMPTIME_CALL:
+        dump_vec(ast, node->comptime_call.args, stack);
+        break;
+
+    case SPL_AST_EXPR_BLOCK:
+        dump_vec(ast, node->block.stmts, stack);
+        if (node->block.tail_expr)
+            dump_node(ast, node->block.tail_expr, stack, true);
+        break;
+
+    case SPL_AST_EXPR_IF:
+        if (node->if_expr.cond)
+            dump_node(ast, node->if_expr.cond, stack, false);
+        if (node->if_expr.then_block)
+            dump_node(ast, node->if_expr.then_block, stack, false);
+        if (node->if_expr.else_branch)
+            dump_node(ast, node->if_expr.else_branch, stack, true);
+        break;
+
+    case SPL_AST_EXPR_IFVAR:
+        if (node->ifvar_expr.var_decl)
+            dump_node(ast, node->ifvar_expr.var_decl, stack, false);
+        if (node->ifvar_expr.then_block)
+            dump_node(ast, node->ifvar_expr.then_block, stack, false);
+        if (node->ifvar_expr.else_branch)
+            dump_node(ast, node->ifvar_expr.else_branch, stack, true);
+        break;
+
+    case SPL_AST_EXPR_WHILE:
+        if (node->while_expr.label)
+            dump_node(ast, node->while_expr.label, stack, false);
+        if (node->while_expr.cond)
+            dump_node(ast, node->while_expr.cond, stack, false);
+        if (node->while_expr.body)
+            dump_node(ast, node->while_expr.body, stack, false);
+        if (node->while_expr.else_branch)
+            dump_node(ast, node->while_expr.else_branch, stack, true);
+        break;
+
+    case SPL_AST_EXPR_LOOP:
+        if (node->loop_expr.label)
+            dump_node(ast, node->loop_expr.label, stack, false);
+        if (node->loop_expr.body)
+            dump_node(ast, node->loop_expr.body, stack, true);
+        break;
+
+    case SPL_AST_EXPR_FOR:
+        if (node->for_expr.label)
+            dump_node(ast, node->for_expr.label, stack, false);
+        dump_vec(ast, node->for_expr.iter_exprs, stack);
+        if (node->for_expr.pattern)
+            dump_node(ast, node->for_expr.pattern, stack, false);
+        if (node->for_expr.body)
+            dump_node(ast, node->for_expr.body, stack, false);
+        if (node->for_expr.else_branch)
+            dump_node(ast, node->for_expr.else_branch, stack, true);
+        break;
+
+    case SPL_AST_EXPR_MATCH:
+        if (node->match_expr.matched_expr)
+            dump_node(ast, node->match_expr.matched_expr, stack, false);
+        dump_vec(ast, node->match_expr.arms, stack);
+        break;
+
+    case SPL_AST_EXPR_FN_TYPE:
+        dump_vec(ast, node->fn_type.params, stack);
+        if (node->fn_type.ret_type)
+            dump_node(ast, node->fn_type.ret_type, stack, true);
+        break;
+
+    case SPL_AST_TYPE_PATH:
+        break;
+
+    case SPL_AST_TYPE_POINTER:
+        if (node->type_pointer.pointee)
+            dump_node(ast, node->type_pointer.pointee, stack, true);
+        break;
+
+    case SPL_AST_TYPE_ARRAY:
+        if (node->type_array.elem_type)
+            dump_node(ast, node->type_array.elem_type, stack, true);
+        break;
+
+    case SPL_AST_TYPE_SLICE:
+        if (node->type_slice.elem_type)
+            dump_node(ast, node->type_slice.elem_type, stack, true);
+        break;
+
+    case SPL_AST_TYPE_FN:
+        dump_vec(ast, node->type_fn.params, stack);
+        if (node->type_fn.ret_type)
+            dump_node(ast, node->type_fn.ret_type, stack, true);
+        break;
+
+    case SPL_AST_TYPE_PAREN:
+        dump_vec(ast, node->type_paren.types, stack);
+        break;
+
+    case SPL_AST_TYPE_AGGREGATE:
+        dump_vec(ast, node->type_aggregate.members, stack);
+        break;
+
+    case SPL_AST_TYPE_COMPTIME_CALL:
+        dump_vec(ast, node->type_comptime_call.args, stack);
+        break;
+
+    case SPL_AST_PATTERN_IDENT:
+    case SPL_AST_PATTERN_UNDERSCORE:
+        break;
+
+    case SPL_AST_PATTERN_DOT:
+        if (node->pattern_dot.sub_pattern)
+            dump_node(ast, node->pattern_dot.sub_pattern, stack, true);
+        break;
+
+    case SPL_AST_PATTERN_TUPLE:
+        dump_vec(ast, node->pattern_tuple.patterns, stack);
+        break;
+
+    case SPL_AST_PATTERN_LIST:
+        dump_vec(ast, node->pattern_list.patterns, stack);
+        break;
+
+    case SPL_AST_PATTERN_AGGREGATE:
+        dump_vec(ast, node->pattern_aggregate.fields, stack);
+        break;
+
+    case SPL_AST_PATTERN_FIELD:
+        if (node->pattern_field.pattern)
+            dump_node(ast, node->pattern_field.pattern, stack, true);
+        break;
+
+    default:
+        break;
+    }
+
+    (void)vec_pop(*stack);
+}

stage1/spl_ast.h

@@ -0,0 +1,478 @@
+#ifndef __SPL_AST_H__
+#define __SPL_AST_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_attr.h"
+#include "spl_dbg.h"
+#include "spl_tok.h"
+
+/* clang-format off */
+#define SPL_AST_KIND_TABLE                                            \
+    X(SPL_AST_NONE,                 V0, none)                         \
+    X(SPL_AST_ROOT,                 V0, root)                         \
+    X(SPL_AST_CONTAINER_MEMBERS,    V0, container_members)            \
+    X(SPL_AST_EXTERNAL_TAG_ITEM,    V0, external_tag_item)            \
+    X(SPL_AST_TAG_ITEM,             V0, tag_item)                     \
+    X(SPL_AST_COMPTIME_DECL,        V0, comptime_decl)                \
+    X(SPL_AST_TOP_LEVEL_BLOCK,      V0, top_level_block)              \
+    X(SPL_AST_FN_DECL,              V0, fn_decl)                      \
+    X(SPL_AST_VAR_DECL,             V0, var_decl)                     \
+    X(SPL_AST_CONST_DECL,           V0, const_decl)                   \
+    X(SPL_AST_TYPE_DECL,            V0, type_decl)                    \
+    X(SPL_AST_MEMBER_DECL,          V0, member_decl)                  \
+    X(SPL_AST_PARAM_DECL,           V0, param_decl)                   \
+    X(SPL_AST_STATEMENT_RET,        V0, statement_ret)                \
+    X(SPL_AST_STATEMENT_BREAK,      V0, statement_break)              \
+    X(SPL_AST_STATEMENT_CONTINUE,   V0, statement_continue)           \
+    X(SPL_AST_STATEMENT_DEFER,      V0, statement_defer)              \
+    X(SPL_AST_STATEMENT_COMPTIME,   V0, statement_comptime)           \
+    X(SPL_AST_STATEMENT_DECL,       V0, statement_decl)               \
+    X(SPL_AST_STATEMENT_EXPR,       V0, statement_expr)               \
+    X(SPL_AST_AGGREGATE_MEMBER,     V0, aggregate_member)             \
+    X(SPL_AST_STRUCT_INIT_ITEM,     V0, struct_init_item)             \
+    X(SPL_AST_MATCH_ARM,            V0, match_arm)                    \
+    X(SPL_AST_LABEL,                V0, label)                        \
+    X(SPL_AST_EXPR_INT_LIT,         V0, int_lit)                      \
+    X(SPL_AST_EXPR_FLOAT_LIT,       V0, float_lit)                    \
+    X(SPL_AST_EXPR_CHAR_LIT,        V0, char_lit)                     \
+    X(SPL_AST_EXPR_STRING_LIT,      V0, string_lit)                   \
+    X(SPL_AST_EXPR_BOOL_LIT,        V0, bool_lit)                     \
+    X(SPL_AST_EXPR_NULL_LIT,        V0, null_lit)                     \
+    X(SPL_AST_EXPR_UNDEFINED_LIT,   V0, undefined_lit)                \
+    X(SPL_AST_EXPR_IDENT,           V0, ident)                        \
+    X(SPL_AST_EXPR_UNARY,           V0, unary)                        \
+    X(SPL_AST_EXPR_BINARY,          V0, binary)                       \
+    X(SPL_AST_EXPR_CALL,            V0, call)                         \
+    X(SPL_AST_EXPR_FIELD,           V0, field)                        \
+    X(SPL_AST_EXPR_INDEX,           V0, index)                        \
+    X(SPL_AST_EXPR_SLICE,           V0, slice)                        \
+    X(SPL_AST_EXPR_CAST,            V0, cast)                         \
+    X(SPL_AST_EXPR_TUPLE,           V0, tuple)                        \
+    X(SPL_AST_EXPR_ARRAY_LIT,       V0, array_literal)                \
+    X(SPL_AST_EXPR_AGGREGATE_LIT,   V0, aggregate_literal)            \
+    X(SPL_AST_EXPR_COMPTIME_CALL,   V0, comptime_call)                \
+    X(SPL_AST_EXPR_BLOCK,           V0, block)                        \
+    X(SPL_AST_EXPR_IF,              V0, if_expr)                      \
+    X(SPL_AST_EXPR_IFVAR,           V0, ifvar_expr)                   \
+    X(SPL_AST_EXPR_WHILE,           V0, while_expr)                   \
+    X(SPL_AST_EXPR_LOOP,            V0, loop_expr)                    \
+    X(SPL_AST_EXPR_FOR,             V0, for_expr)                     \
+    X(SPL_AST_EXPR_MATCH,           V0, match_expr)                   \
+    X(SPL_AST_EXPR_FN_TYPE,         V0, fn_type)                      \
+    X(SPL_AST_TYPE_PATH,            V0, type_path)                    \
+    X(SPL_AST_TYPE_POINTER,         V0, type_pointer)                 \
+    X(SPL_AST_TYPE_ARRAY,           V0, type_array)                   \
+    X(SPL_AST_TYPE_SLICE,           V0, type_slice)                   \
+    X(SPL_AST_TYPE_FN,              V0, type_fn)                      \
+    X(SPL_AST_TYPE_PAREN,           V0, type_paren)                   \
+    X(SPL_AST_TYPE_AGGREGATE,       V0, type_aggregate)               \
+    X(SPL_AST_TYPE_COMPTIME_CALL,   V0, type_comptime_call)           \
+    X(SPL_AST_PATTERN_IDENT,        V0, pattern_ident)                \
+    X(SPL_AST_PATTERN_UNDERSCORE,   V0, pattern_underscore)           \
+    X(SPL_AST_PATTERN_DOT,          V0, pattern_dot)                  \
+    X(SPL_AST_PATTERN_TUPLE,        V0, pattern_tuple)                \
+    X(SPL_AST_PATTERN_LIST,         V0, pattern_list)                 \
+    X(SPL_AST_PATTERN_AGGREGATE,    V0, pattern_aggregate)            \
+    X(SPL_AST_PATTERN_FIELD,        V0, pattern_field)
+/* clang-format on */
+
+typedef enum {
+#ifdef X
+#undef X
+#endif
+#define X(name, ...) name,
+    SPL_AST_KIND_TABLE
+#undef X
+        SPL_AST_COUNT,
+} spl_ast_node_kind_t;
+
+/* clang-format off */
+#define SPL_BINARY_OP_TABLE                                            \
+    X(SPL_OP_ASSIGN,                1,  'R', =)                          \
+    X(SPL_OP_ASSIGN_ADD,            1,  'R', +=)                         \
+    X(SPL_OP_ASSIGN_SUB,            1,  'R', -=)                         \
+    X(SPL_OP_ASSIGN_MUL,            1,  'R', *=)                         \
+    X(SPL_OP_ASSIGN_DIV,            1,  'R', /=)                         \
+    X(SPL_OP_ASSIGN_MOD,            1,  'R', %=)                         \
+    X(SPL_OP_ASSIGN_AND,            1,  'R', &=)                         \
+    X(SPL_OP_ASSIGN_OR,             1,  'R', |=)                         \
+    X(SPL_OP_ASSIGN_XOR,            1,  'R', ^=)                         \
+    X(SPL_OP_ASSIGN_LSHIFT,         1,  'R', <<=)                        \
+    X(SPL_OP_ASSIGN_RSHIFT,         1,  'R', >>=)                        \
+    X(SPL_OP_BOOL_OR,               2,  'L', ||)                         \
+    X(SPL_OP_BOOL_AND,              3,  'L', &&)                         \
+    X(SPL_OP_BIT_OR,                4,  'L', |)                          \
+    X(SPL_OP_BIT_XOR,               5,  'L', ^)                          \
+    X(SPL_OP_BIT_AND,               6,  'L', &)                          \
+    X(SPL_OP_CMP_EQ,                7,  'L', ==)                         \
+    X(SPL_OP_CMP_NE,                7,  'L', !=)                         \
+    X(SPL_OP_CMP_LE,                8,  'L', <=)                         \
+    X(SPL_OP_CMP_GE,                8,  'L', >=)                         \
+    X(SPL_OP_CMP_LT,                8,  'L', <)                          \
+    X(SPL_OP_CMP_GT,                8,  'L', >)                          \
+    X(SPL_OP_ARROW_LEFT,            9,  'L', <-)                         \
+    X(SPL_OP_ARROW_RIGHT,           9,  'L', ->)                         \
+    X(SPL_OP_ARROW_FAT_BOTH,        9,  'L', <=>)                        \
+    X(SPL_OP_ARROW_THIN_BOTH,       9,  'L', <->)                        \
+    X(SPL_OP_ARROW_FAT_RIGHT,       9,  'L', =>)                         \
+    X(SPL_OP_RANGE,                 10, 'L', ..)                         \
+    X(SPL_OP_LSHIFT,                11, 'L', <<)                         \
+    X(SPL_OP_RSHIFT,                11, 'L', >>)                         \
+    X(SPL_OP_ADD,                   12, 'L', +)                          \
+    X(SPL_OP_SUB,                   12, 'L', -)                          \
+    X(SPL_OP_MUL,                   13, 'L', *)                          \
+    X(SPL_OP_DIV,                   13, 'L', /)                          \
+    X(SPL_OP_MOD,                   13, 'L', %)
+/* clang-format on */
+
+typedef enum {
+#ifdef X
+#undef X
+#endif
+#define X(name, ...) name,
+    SPL_BINARY_OP_TABLE
+#undef X
+} spl_binary_op_t;
+
+typedef enum {
+    SPL_UNARY_OP_MINUS,
+    SPL_UNARY_OP_NOT,
+    SPL_UNARY_OP_BIT_NOT,
+    SPL_UNARY_OP_ADDRESS,
+    SPL_UNARY_OP_DEREF,
+} spl_unary_op_t;
+
+struct spl_ast_node;
+typedef struct spl_ast_node spl_ast_node_t;
+typedef usize spl_ast_node_ref_t;
+typedef VEC(spl_ast_node_ref_t) spl_ast_node_ref_vec_t;
+
+struct spl_ast_node {
+    spl_ast_node_kind_t kind;
+    spl_dbg_node_t dbg;
+
+    usize resolved_def_id;
+    usize resolved_lang_tid;
+    usize expected_lang_tid;
+    spl_attr_id_vec_t attrs;
+
+    union {
+        struct {
+            spl_ast_node_ref_t members;
+        } root;
+
+        struct {
+            spl_ast_node_ref_vec_t external_tags;
+            spl_ast_node_ref_vec_t declarations;
+        } container_members;
+
+        struct {
+            spl_ast_node_ref_vec_t tag_list;
+            bool is_comptime;
+            const char *name;
+            spl_ast_node_ref_vec_t params;
+            spl_ast_node_ref_t ret_type;
+            spl_ast_node_ref_t body;
+        } fn_decl;
+
+        struct {
+            spl_ast_node_ref_vec_t attr_list;
+            spl_ast_node_ref_t pattern;
+            spl_ast_node_ref_t type;
+            spl_ast_node_ref_t init_expr;
+        } var_const_decl;
+
+        struct {
+            spl_ast_node_ref_vec_t attr_list;
+            const char *name;
+            spl_ast_node_ref_t type_expr;
+        } type_decl;
+
+        struct {
+            spl_ast_node_ref_vec_t attr_list;
+            const char *name;
+            spl_ast_node_ref_t type_expr;
+            spl_ast_node_ref_t init_expr;
+        } member_decl;
+
+        struct {
+            spl_ast_node_ref_vec_t attr_list;
+            const char *name;
+            spl_ast_node_ref_t type_expr;
+        } param_decl;
+
+        struct {
+            bool is_at;
+            bool is_external;
+            const char *name;
+            spl_ast_node_ref_vec_t args;
+        } tag_item;
+
+        struct {
+            spl_ast_node_ref_t body;
+        } comptime_decl;
+
+        struct {
+            spl_ast_node_ref_vec_t tag_list;
+            spl_ast_node_ref_t block;
+        } top_level_block;
+
+        struct {
+            spl_ast_node_ref_t expr;
+        } statement_ret;
+
+        struct {
+            spl_ast_node_ref_t label;
+            spl_ast_node_ref_t expr;
+        } statement_break;
+
+        struct {
+            spl_ast_node_ref_t label;
+        } statement_continue;
+
+        struct {
+            spl_ast_node_ref_t body;
+        } statement_defer;
+        struct {
+            spl_ast_node_ref_t body;
+        } statement_comptime;
+        struct {
+            spl_ast_node_ref_t decl;
+        } statement_decl;
+        struct {
+            spl_ast_node_ref_t expr;
+        } statement_expr;
+
+        struct {
+            spl_ast_node_ref_vec_t attr_list;
+            const char *name;
+            spl_ast_node_ref_t type_expr;
+            spl_ast_node_ref_t init_expr;
+        } aggregate_member;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_t expr;
+        } struct_init_item;
+
+        struct {
+            spl_ast_node_ref_t pattern;
+            spl_ast_node_ref_t body;
+        } match_arm;
+
+        struct {
+            const char *name;
+        } label;
+
+        spl_mpa_int_t int_lit;
+        spl_mpa_float_t float_lit;
+        struct {
+            char val;
+        } char_lit;
+        struct {
+            const char *data;
+            usize len;
+        } string_lit;
+        struct {
+            bool val;
+        } bool_lit;
+
+        struct {
+            const char *name;
+        } ident;
+
+        struct {
+            spl_unary_op_t op;
+            spl_ast_node_ref_t operand;
+        } unary;
+
+        struct {
+            spl_binary_op_t op;
+            spl_ast_node_ref_t left;
+            spl_ast_node_ref_t right;
+        } binary;
+
+        struct {
+            spl_ast_node_ref_t callee;
+            spl_ast_node_ref_vec_t args;
+        } call;
+
+        struct {
+            spl_ast_node_ref_t obj;
+            const char *field;
+        } field;
+
+        struct {
+            spl_ast_node_ref_t obj;
+            spl_ast_node_ref_t index;
+        } index;
+
+        struct {
+            spl_ast_node_ref_t obj;
+            spl_ast_node_ref_t begin;
+            spl_ast_node_ref_t end;
+        } slice;
+
+        struct {
+            spl_ast_node_ref_t expr;
+            spl_ast_node_ref_t type;
+        } cast;
+
+        struct {
+            spl_ast_node_ref_vec_t elems;
+        } tuple;
+
+        struct {
+            bool has_len;
+            usize len;
+            bool is_underscore_len;
+            spl_ast_node_ref_t elem_type;
+            spl_ast_node_ref_vec_t elems;
+        } array_literal;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_vec_t fields;
+        } aggregate_literal;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_vec_t args;
+        } comptime_call;
+
+        struct {
+            spl_ast_node_ref_vec_t stmts;
+            spl_ast_node_ref_t tail_expr;
+        } block;
+
+        struct {
+            spl_ast_node_ref_t cond;
+            spl_ast_node_ref_t then_block;
+            spl_ast_node_ref_t else_branch;
+        } if_expr;
+
+        struct {
+            spl_ast_node_ref_t var_decl;
+            spl_ast_node_ref_t then_block;
+            spl_ast_node_ref_t else_branch;
+        } ifvar_expr;
+
+        struct {
+            spl_ast_node_ref_t label;
+            spl_ast_node_ref_t cond;
+            spl_ast_node_ref_t body;
+            spl_ast_node_ref_t else_branch;
+        } while_expr;
+
+        struct {
+            spl_ast_node_ref_t label;
+            spl_ast_node_ref_t body;
+        } loop_expr;
+
+        struct {
+            spl_ast_node_ref_t label;
+            spl_ast_node_ref_vec_t iter_exprs;
+            spl_ast_node_ref_t pattern;
+            spl_ast_node_ref_t body;
+            spl_ast_node_ref_t else_branch;
+        } for_expr;
+
+        struct {
+            spl_ast_node_ref_t matched_expr;
+            spl_ast_node_ref_vec_t arms;
+        } match_expr;
+
+        struct {
+            bool is_comptime;
+            spl_ast_node_ref_vec_t params;
+            spl_ast_node_ref_t ret_type;
+        } fn_type;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_vec_t generic_args;
+        } type_path;
+
+        struct {
+            spl_ast_node_ref_t pointee;
+        } type_pointer;
+
+        struct {
+            bool has_len;
+            isize len;
+            bool is_underscore_len;
+            spl_ast_node_ref_t elem_type;
+        } type_array;
+
+        struct {
+            spl_ast_node_ref_t elem_type;
+        } type_slice;
+
+        struct {
+            bool is_comptime;
+            spl_ast_node_ref_vec_t params;
+            spl_ast_node_ref_t ret_type;
+        } type_fn;
+
+        struct {
+            spl_ast_node_ref_vec_t types;
+        } type_paren;
+
+        struct {
+            const char *kind_name;
+            spl_ast_node_ref_vec_t members;
+        } type_aggregate;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_vec_t args;
+        } type_comptime_call;
+
+        struct {
+            const char *name;
+        } pattern_ident;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_t sub_pattern;
+        } pattern_dot;
+
+        struct {
+            spl_ast_node_ref_vec_t patterns;
+        } pattern_tuple;
+        struct {
+            spl_ast_node_ref_vec_t patterns;
+        } pattern_list;
+
+        struct {
+            spl_ast_node_ref_vec_t fields;
+        } pattern_aggregate;
+
+        struct {
+            const char *name;
+            spl_ast_node_ref_t pattern;
+        } pattern_field;
+    };
+};
+
+typedef VEC(spl_ast_node_t) spl_ast_node_vec_t;
+typedef VEC(char *) spl_ast_cstr_ref_vec_t;
+typedef struct spl_ast {
+    spl_tok_vec_t input;
+    spl_ast_node_vec_t node_buckets;
+    spl_ast_cstr_ref_vec_t str_buckets;
+    spl_ast_node_ref_t root;
+} spl_ast_t;
+typedef VEC(spl_ast_t *) spl_ast_ptr_vec_t;
+
+void spl_ast_init(spl_ast_t *ast, const spl_tok_vec_t *tok_vec /*move*/);
+void spl_ast_drop(spl_ast_t *ast);
+
+spl_ast_node_t *spl_ast_node(spl_ast_t *ast, spl_ast_node_ref_t node);
+void spl_ast_dump(spl_ast_t *ast, spl_ast_node_ref_t node);
+
+const char *spl_ast_kind_name(spl_ast_node_kind_t kind);
+const char *spl_binary_op_name(spl_binary_op_t op);
+const char *spl_unary_op_name(spl_unary_op_t op);
+
+#endif /* __SPL_AST_H__ */

stage1/spl_ast2ir.h

@@ -0,0 +1,39 @@
+#ifndef __SPL_AST2IR_H__
+#define __SPL_AST2IR_H__
+
+#include "spl_diag.h"
+#include "spl_ir.h"
+#include "spl_sema.h"
+
+typedef MAP(spl_def_id_t, spl_ir_node_ref_t) spl_def2ir_map_t;
+
+typedef struct {
+    usize cont_blk;
+    const char *label;
+    spl_ir_node_ref_vec_t breaks;
+    spl_ir_node_ref_t result_slot;
+    spl_type_id_t result_tid;
+} spl_loop_ctx_t;
+typedef VEC(spl_loop_ctx_t) spl_loop_ctx_vec_t;
+
+typedef VEC(spl_ast_node_ref_t) spl_defer_stack_t;
+
+typedef struct {
+    const spl_sema_t *sema;
+    spl_ir_builder_t *ir;
+    spl_ast_t *ast;
+    spl_def2ir_map_t def2ir_map;
+    spl_loop_ctx_vec_t loop_stack;
+    spl_defer_stack_t defer_stack;
+    spl_lang_type_id_t cur_ret_lang;
+    usize cur_defer_base;
+
+    spl_diag_t *diag;
+} spl_ast2ir_t;
+
+void spl_ast2ir_init(spl_ast2ir_t *ast2ir, spl_ir_builder_t *ir, const spl_sema_t *sema);
+void spl_ast2ir_drop(spl_ast2ir_t *ast2ir);
+
+void spl_ast2ir_run(spl_ast2ir_t *ast2ir, spl_ast_ptr_vec_t ast_vec);
+
+#endif /* __SPL_AST2IR_H__ */

stage1/spl_attr.c

@@ -0,0 +1,152 @@
+#include "spl_attr.h"
+
+static spl_attr_info_t spl_builtin_attrs[] = {
+    {NULL, "extern", SPL_ATTR_STAGE_IR, SPL_ATTR_TARGET_DECL, SPL_ATTR_REQUIRED, 1, 1},
+    {NULL, "inline", SPL_ATTR_STAGE_OPT, SPL_ATTR_TARGET_DECL, SPL_ATTR_OPTIONAL, 0, 0},
+    {NULL, "noinline", SPL_ATTR_STAGE_OPT, SPL_ATTR_TARGET_DECL, SPL_ATTR_OPTIONAL, 0, 0},
+    {NULL, "align", SPL_ATTR_STAGE_LAYOUT, SPL_ATTR_TARGET_TYPE, SPL_ATTR_REQUIRED, 1, 1},
+    {NULL, "volatile", SPL_ATTR_STAGE_IR, SPL_ATTR_TARGET_EXPR, SPL_ATTR_REQUIRED, 0, 0},
+    {NULL, "atomic", SPL_ATTR_STAGE_IR, SPL_ATTR_TARGET_EXPR, SPL_ATTR_REQUIRED, 0, 1},
+};
+
+void spl_attr_init(spl_attr_t *ctx) {
+    vec_init(ctx->table);
+    vec_push(ctx->table, (spl_attr_node_t){0});
+    vec_init(ctx->registry);
+    spl_attr_register_builtins(ctx);
+}
+
+void spl_attr_drop(spl_attr_t *ctx) {
+    for (usize i = 1; i < vec_size(ctx->table); ++i)
+        vec_free(vec_at(ctx->table, i).args);
+    vec_free(ctx->table);
+    vec_free(ctx->registry);
+}
+
+spl_attr_id_t spl_attr_alloc(spl_attr_t *ctx, spl_attr_info_t *info, spl_attr_arg_vec_t args) {
+    spl_attr_node_t a = {0};
+    a.info = info;
+    a.args = args;
+    vec_push(ctx->table, a);
+    return vec_size(ctx->table) - 1;
+}
+
+spl_attr_node_t *spl_attr_node(const spl_attr_t *ctx, spl_attr_id_t id) {
+    if (!id || id >= vec_size(ctx->table))
+        return NULL;
+    return &vec_at(ctx->table, id);
+}
+
+void spl_attr_registry_add(spl_attr_t *ctx, spl_attr_info_t *info) {
+    vec_push(ctx->registry, info);
+}
+
+static int name_eq(const char *a, const char *b) {
+    if (a == NULL && b == NULL)
+        return 1;
+    if (a == NULL || b == NULL)
+        return 0;
+    return strcmp(a, b) == 0;
+}
+
+spl_attr_info_t *spl_attr_lookup(spl_attr_t *ctx, const char *ns, const char *name) {
+    for (usize i = 0; i < vec_size(ctx->registry); ++i) {
+        spl_attr_info_t *info = vec_at(ctx->registry, i);
+        if (name_eq(info->ns, ns) && strcmp(info->name, name) == 0)
+            return info;
+    }
+    return NULL;
+}
+
+void spl_attr_register_builtins(spl_attr_t *ctx) {
+    usize n = sizeof(spl_builtin_attrs) / sizeof(spl_builtin_attrs[0]);
+    for (usize i = 0; i < n; ++i)
+        spl_attr_registry_add(ctx, &spl_builtin_attrs[i]);
+}
+
+static const char *attr_stage_name(spl_attr_stage_t s) {
+    switch (s) {
+    case SPL_ATTR_STAGE_SEMA:
+        return "SEMA";
+    case SPL_ATTR_STAGE_LAYOUT:
+        return "LAYOUT";
+    case SPL_ATTR_STAGE_IR:
+        return "IR";
+    case SPL_ATTR_STAGE_OPT:
+        return "OPT";
+    case SPL_ATTR_STAGE_BACKEND:
+        return "BACKEND";
+    }
+    return "?";
+}
+
+static const char *attr_target_name(spl_attr_target_t t) {
+    switch (t) {
+    case SPL_ATTR_TARGET_DECL:
+        return "DECL";
+    case SPL_ATTR_TARGET_TYPE:
+        return "TYPE";
+    case SPL_ATTR_TARGET_EXPR:
+        return "EXPR";
+    case SPL_ATTR_TARGET_STMT:
+        return "STMT";
+    }
+    return "?";
+}
+
+static const char *attr_demand_name(spl_attr_demand_t d) {
+    return d == SPL_ATTR_REQUIRED ? "REQUIRED" : "OPTIONAL";
+}
+
+void spl_attr_dump_id(const spl_attr_t *ctx, spl_attr_id_t id) {
+    if (!ctx || !id) {
+        printf("?");
+        return;
+    }
+    spl_attr_node_t *a = spl_attr_node(ctx, id);
+    if (!a || !a->info) {
+        printf("?");
+        return;
+    }
+    printf("%s", a->info->name);
+    if (vec_size(a->args) > 0) {
+        printf("(");
+        for (usize i = 0; i < vec_size(a->args); ++i) {
+            if (i > 0)
+                printf(", ");
+            spl_attr_arg_t *arg = &vec_at(a->args, i);
+            switch (arg->kind) {
+            case SPL_ATTR_ARG_INT:
+                printf("%zd", arg->value.i);
+                break;
+            case SPL_ATTR_ARG_STR:
+                printf("\"%s\"", arg->value.s ? arg->value.s : "");
+                break;
+            case SPL_ATTR_ARG_DEF:
+                printf("def#%zu", arg->value.d);
+                break;
+            case SPL_ATTR_ARG_TYPE:
+                printf("type#%zu", arg->value.t);
+                break;
+            }
+        }
+        printf(")");
+    }
+}
+
+void spl_attr_dump(const spl_attr_t *ctx) {
+    if (!ctx)
+        return;
+    printf("AttrTable:\n");
+    for (usize i = 1; i < vec_size(ctx->table); ++i) {
+        spl_attr_node_t *a = &vec_at(ctx->table, i);
+        printf("  #%zu ", i);
+        spl_attr_dump_id(ctx, i);
+        if (a->info) {
+            printf(" [stage=%s target=%s demand=%s consumed=0x%x]", attr_stage_name(a->info->stage),
+                   attr_target_name(a->info->target), attr_demand_name(a->info->demand),
+                   a->consumed_mask);
+        }
+        printf("\n");
+    }
+}

stage1/spl_attr.h

@@ -0,0 +1,85 @@
+#ifndef __SPL_ATTR_H__
+#define __SPL_ATTR_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_mpa.h"
+
+typedef enum {
+    SPL_ATTR_STAGE_SEMA,
+    SPL_ATTR_STAGE_LAYOUT,
+    SPL_ATTR_STAGE_IR,
+    SPL_ATTR_STAGE_OPT,
+    SPL_ATTR_STAGE_BACKEND,
+} spl_attr_stage_t;
+
+typedef enum {
+    SPL_ATTR_TARGET_DECL,
+    SPL_ATTR_TARGET_TYPE,
+    SPL_ATTR_TARGET_EXPR,
+    SPL_ATTR_TARGET_STMT,
+} spl_attr_target_t;
+
+typedef enum {
+    SPL_ATTR_OPTIONAL,
+    SPL_ATTR_REQUIRED,
+} spl_attr_demand_t;
+
+typedef struct {
+    const char *ns;
+    const char *name;
+    spl_attr_stage_t stage;
+    spl_attr_target_t target;
+    spl_attr_demand_t demand;
+    int min_args;
+    int max_args;
+} spl_attr_info_t;
+
+typedef enum {
+    SPL_ATTR_ARG_INT,
+    SPL_ATTR_ARG_STR,
+    SPL_ATTR_ARG_DEF,
+    SPL_ATTR_ARG_TYPE,
+} spl_attr_arg_kind_t;
+
+typedef struct {
+    spl_attr_arg_kind_t kind;
+    union {
+        isize i;
+        const char *s;
+        usize d;
+        usize t;
+    } value;
+} spl_attr_arg_t;
+typedef VEC(spl_attr_arg_t) spl_attr_arg_vec_t;
+
+typedef usize spl_attr_id_t;
+
+typedef struct {
+    spl_attr_info_t *info;
+    spl_attr_arg_vec_t args;
+    uint32_t consumed_mask;
+} spl_attr_node_t;
+typedef VEC(spl_attr_node_t) spl_attr_node_vec_t;
+typedef VEC(spl_attr_id_t) spl_attr_id_vec_t;
+
+typedef VEC(spl_attr_info_t *) spl_attr_registry_t;
+
+typedef struct {
+    spl_attr_node_vec_t table;
+    spl_attr_registry_t registry;
+} spl_attr_t;
+
+void spl_attr_init(spl_attr_t *ctx);
+void spl_attr_drop(spl_attr_t *ctx);
+
+spl_attr_id_t spl_attr_alloc(spl_attr_t *ctx, spl_attr_info_t *info, spl_attr_arg_vec_t args);
+spl_attr_node_t *spl_attr_node(const spl_attr_t *ctx, spl_attr_id_t id);
+
+void spl_attr_registry_add(spl_attr_t *ctx, spl_attr_info_t *info);
+spl_attr_info_t *spl_attr_lookup(spl_attr_t *ctx, const char *ns, const char *name);
+void spl_attr_register_builtins(spl_attr_t *ctx);
+
+void spl_attr_dump(const spl_attr_t *ctx);
+void spl_attr_dump_id(const spl_attr_t *ctx, spl_attr_id_t id);
+
+#endif /* __SPL_ATTR_H__ */

stage1/spl_dbg.h

@@ -0,0 +1,25 @@
+#ifndef __SPL_DBG_H__
+#define __SPL_DBG_H__
+
+typedef struct {
+    const char *fname;
+    int line;
+    int col;
+
+    const char *dbg_name;
+    // TODO
+} spl_dbg_node_t;
+
+#define SPL_FATAL(dbg, fmt, ...)                                                                   \
+    LOG_FATAL("fatal at %s:%d:%d " fmt, ((dbg) && (dbg)->fname ? (dbg)->fname : "<null>"),         \
+              ((dbg) ? (dbg)->line : 0), ((dbg) ? (dbg)->col : 0), ##__VA_ARGS__)
+
+#define SPL_ERROR(dbg, fmt, ...)                                                                   \
+    LOG_ERROR("error at %s:%d:%d " fmt, ((dbg) && (dbg)->fname ? (dbg)->fname : "<null>"),         \
+              ((dbg) ? (dbg)->line : 0), ((dbg) ? (dbg)->col : 0), ##__VA_ARGS__)
+
+#define SPL_WARN(dbg, fmt, ...)                                                                    \
+    LOG_ERROR("warn at %s:%d:%d " fmt, ((dbg) && (dbg)->fname ? (dbg)->fname : "<null>"),          \
+              ((dbg) ? (dbg)->line : 0), ((dbg) ? (dbg)->col : 0), ##__VA_ARGS__)
+
+#endif /* __SPL_DBG_H__ */

stage1/spl_diag.c

@@ -0,0 +1,368 @@
+#include "spl_diag.h"
+#include "../stage0/include/color.h"
+
+#include <stdarg.h>
+
+static const char *const g_kind_names[] = {
+    [SPL_DIAG_KIND_NONE] = "none",
+    [SPL_DIAG_KIND_LEX_UNEXPECTED] = "lex_unexpected",
+    [SPL_DIAG_KIND_PARSE_EXPECTED] = "parse_expected",
+    [SPL_DIAG_KIND_PARSE_UNRECOGNIZED] = "parse_unrecognized",
+    [SPL_DIAG_KIND_UNDEFINED_SYMBOL] = "undefined_symbol",
+    [SPL_DIAG_KIND_DUPLICATE_SYMBOL] = "duplicate_symbol",
+    [SPL_DIAG_KIND_TYPE_MISMATCH] = "type_mismatch",
+    [SPL_DIAG_KIND_ARG_COUNT_MISMATCH] = "arg_count_mismatch",
+    [SPL_DIAG_KIND_NOT_A_FUNCTION] = "not_a_function",
+    [SPL_DIAG_KIND_NO_FIELD] = "no_field",
+    [SPL_DIAG_KIND_NO_METHOD] = "no_method",
+    [SPL_DIAG_KIND_INDEX_BASE_INVALID] = "index_base_invalid",
+    [SPL_DIAG_KIND_TUPLE_INDEX_OOB] = "tuple_index_oob",
+    [SPL_DIAG_KIND_FITS_OVERFLOW] = "fits_overflow",
+    [SPL_DIAG_KIND_CIRCULAR_DEP] = "circular_dep",
+    [SPL_DIAG_KIND_BREAK_OUTSIDE_LOOP] = "break_outside_loop",
+    [SPL_DIAG_KIND_CONTINUE_OUTSIDE_LOOP] = "continue_outside_loop",
+    [SPL_DIAG_KIND_UNDEFINED_LABEL] = "undefined_label",
+    [SPL_DIAG_KIND_CAST_INVALID] = "cast_invalid",
+    [SPL_DIAG_KIND_UNKNOWN_ATTR] = "unknown_attr",
+    [SPL_DIAG_KIND_UNKNOWN_INTRIN] = "unknown_intrin",
+    [SPL_DIAG_KIND_INTRIN_ARG_COUNT] = "intrin_arg_count",
+    [SPL_DIAG_KIND_VAR_UNINITIALIZED] = "var_uninitialized",
+    [SPL_DIAG_KIND_CANNOT_INFER] = "cannot_infer",
+    [SPL_DIAG_KIND_MUST_RETURN_VALUE] = "must_return_value",
+    [SPL_DIAG_KIND_UNHANDLED_NODE] = "unhandled_node",
+    [SPL_DIAG_KIND_IMPLICIT_CAST_FAIL] = "implicit_cast_fail",
+    [SPL_DIAG_KIND_NO_LVALUE] = "no_lvalue",
+    [SPL_DIAG_KIND_BAD_FIELD_INDEX] = "bad_field_index",
+    [SPL_DIAG_KIND_BAD_BLOCK] = "bad_block",
+    [SPL_DIAG_KIND_IR_UNKNOWN_KIND] = "ir_unknown_kind",
+    [SPL_DIAG_KIND_FRAME_OVERFLOW] = "frame_overflow",
+    [SPL_DIAG_KIND_INTERNAL] = "internal",
+};
+
+const char *spl_diag_kind_name(spl_diag_kind_t k) {
+    if ((usize)k < sizeof(g_kind_names) / sizeof(g_kind_names[0]) && g_kind_names[k])
+        return g_kind_names[k];
+    return "unknown";
+}
+
+static const char *const g_stage_names[] = {
+    [SPL_STAGE_NONE] = "none",     [SPL_STAGE_LEX] = "lex",       [SPL_STAGE_PARSE] = "parse",
+    [SPL_STAGE_SEMA] = "sema",     [SPL_STAGE_AST2IR] = "ast2ir", [SPL_STAGE_IR2VM] = "ir2vm",
+    [SPL_STAGE_DRIVER] = "driver",
+};
+
+const char *spl_diag_stage_name(spl_diag_stage_t s) {
+    if ((usize)s < sizeof(g_stage_names) / sizeof(g_stage_names[0]) && g_stage_names[s])
+        return g_stage_names[s];
+    return "?";
+}
+
+const char *spl_diag_level_name(spl_diag_level_t l) {
+    switch (l) {
+    case SPL_DIAG_LEVEL_NOTE:
+        return "note";
+    case SPL_DIAG_LEVEL_WARN:
+        return "warn";
+    case SPL_DIAG_LEVEL_ERROR:
+        return "error";
+    case SPL_DIAG_LEVEL_FATAL:
+        return "fatal";
+    }
+    return "?";
+}
+
+static const char *level_color(spl_diag_level_t l) {
+    switch (l) {
+    case SPL_DIAG_LEVEL_NOTE:
+        return ANSI_FG_CYAN;
+    case SPL_DIAG_LEVEL_WARN:
+        return ANSI_FG_YELLOW;
+    case SPL_DIAG_LEVEL_ERROR:
+        return ANSI_FG_RED;
+    case SPL_DIAG_LEVEL_FATAL:
+        return ANSI_FG_RED ANSI_UNDERLINED;
+    }
+    return ANSI_NONE;
+}
+
+static char *diag_strdup(const char *s) {
+    if (!s)
+        return NULL;
+    usize n = strlen(s);
+    char *r = malloc(n + 1);
+    if (!r)
+        return NULL;
+    memcpy(r, s, n);
+    r[n] = '\0';
+    return r;
+}
+
+void spl_diag_init(spl_diag_t *d, void *fout) {
+    memset(d, 0, sizeof *d);
+    vec_init(d->ctx);
+    vec_init(d->records);
+    d->collect = true;
+    d->fout = fout;
+    d->color = true;
+    d->stage = SPL_STAGE_NONE;
+}
+
+static void frame_free(spl_diag_frame_t *f) {
+    free(f->fn_name);
+    free(f->label);
+    f->fn_name = NULL;
+    f->label = NULL;
+}
+
+static void record_free(spl_diag_record_t *r) {
+    free(r->message);
+    r->message = NULL;
+    for (usize i = 0; i < vec_size(r->ctx); ++i)
+        frame_free(&vec_at(r->ctx, i));
+    vec_free(r->ctx);
+    for (usize i = 0; i < vec_size(r->notes); ++i)
+        free(vec_at(r->notes, i).message);
+    vec_free(r->notes);
+}
+
+void spl_diag_reset(spl_diag_t *d) {
+    for (usize i = 0; i < vec_size(d->ctx); ++i)
+        frame_free(&vec_at(d->ctx, i));
+    d->ctx.size = 0;
+
+    for (usize i = 0; i < vec_size(d->records); ++i)
+        record_free(&vec_at(d->records, i));
+    d->records.size = 0;
+
+    d->num_printed = 0;
+    d->n_errors = 0;
+    d->n_warns = 0;
+    d->n_fatals = 0;
+}
+
+void spl_diag_drop(spl_diag_t *d) {
+    spl_diag_reset(d);
+    vec_free(d->ctx);
+    vec_free(d->records);
+}
+
+void spl_diag_set_stage(spl_diag_t *d, spl_diag_stage_t stage) { d->stage = stage; }
+
+void spl_diag_set_output(spl_diag_t *d, FILE *out) { d->fout = out; }
+
+void spl_diag_set_color(spl_diag_t *d, bool enabled) { d->color = enabled; }
+
+void spl_diag_set_collect(spl_diag_t *d, bool enabled) { d->collect = enabled; }
+
+void spl_diag_push(spl_diag_t *d, const spl_dbg_node_t *loc, const char *fn_name,
+                   const char *label) {
+    spl_diag_frame_t f = {0};
+    if (loc)
+        f.loc = *loc;
+    f.fn_name = fn_name ? diag_strdup(fn_name) : NULL;
+    f.label = label ? diag_strdup(label) : NULL;
+    vec_push(d->ctx, f);
+}
+
+void spl_diag_pop(spl_diag_t *d) {
+    if (vec_size(d->ctx) == 0)
+        return;
+    frame_free(&vec_at(d->ctx, vec_size(d->ctx) - 1));
+    d->ctx.size--;
+}
+
+usize spl_diag_depth(const spl_diag_t *d) { return vec_size(d->ctx); }
+
+static spl_diag_frame_vec_t ctx_snapshot(const spl_diag_t *d) {
+    spl_diag_frame_vec_t snap;
+    vec_init(snap);
+    for (usize i = 0; i < vec_size(d->ctx); ++i) {
+        spl_diag_frame_t *src = &vec_at(d->ctx, i);
+        spl_diag_frame_t f = {0};
+        f.loc = src->loc;
+        f.fn_name = src->fn_name ? diag_strdup(src->fn_name) : NULL;
+        f.label = src->label ? diag_strdup(src->label) : NULL;
+        vec_push(snap, f);
+    }
+    return snap;
+}
+
+static void frame_desc(const spl_diag_frame_t *f, char *buf, usize cap) {
+    if (f->fn_name && f->label)
+        snprintf(buf, cap, "%s %s", f->label, f->fn_name);
+    else if (f->fn_name)
+        snprintf(buf, cap, "%s", f->fn_name);
+    else if (f->label)
+        snprintf(buf, cap, "%s", f->label);
+    else
+        snprintf(buf, cap, "?");
+}
+
+static void print_loc(FILE *out, const spl_dbg_node_t *loc) {
+    if (loc && loc->fname)
+        fprintf(out, "%s:%d:%d", loc->fname, loc->line, loc->col);
+    else
+        fprintf(out, "<no-loc>");
+}
+
+static void print_record(const spl_diag_t *d, const spl_diag_record_t *r) {
+    FILE *out = (FILE *)d->fout;
+    if (!out)
+        return;
+    const char *col = d->color ? level_color(r->level) : "";
+    const char *rst = d->color ? ANSI_NONE : "";
+
+    fprintf(out, "%s%s[%s:%s]%s: ", col, spl_diag_level_name(r->level),
+            spl_diag_stage_name(r->stage), spl_diag_kind_name(r->kind), rst);
+    print_loc(out, &r->loc);
+    fputc('\n', out);
+
+    fprintf(out, "    %s\n", r->message ? r->message : "");
+
+    for (usize i = vec_size(r->ctx); i > 0; --i) {
+        char buf[256];
+        frame_desc(&vec_at(r->ctx, i - 1), buf, sizeof buf);
+        fprintf(out, "    in %s at ", buf);
+        print_loc(out, &vec_at(r->ctx, i - 1).loc);
+        fputc('\n', out);
+    }
+
+    for (usize i = 0; i < vec_size(r->notes); ++i) {
+        spl_diag_note_t *n = &vec_at(r->notes, i);
+        const char *ncol = d->color ? ANSI_FG_CYAN : "";
+        fprintf(out, "%snote%s: ", ncol, rst);
+        print_loc(out, &n->loc);
+        fputc('\n', out);
+        fprintf(out, "    %s\n", n->message ? n->message : "");
+    }
+}
+
+static void emit(spl_diag_t *d, spl_diag_level_t level, spl_diag_kind_t kind,
+                 const spl_dbg_node_t *loc, const char *fmt, va_list ap) {
+    va_list ap2;
+    va_copy(ap2, ap);
+    int need = vsnprintf(NULL, 0, fmt, ap);
+    if (need < 0)
+        need = 0;
+
+    char *msg = malloc((usize)need + 1);
+    if (msg)
+        vsnprintf(msg, (usize)need + 1, fmt, ap2);
+    va_end(ap2);
+
+    spl_diag_record_t rec = {0};
+    rec.level = level;
+    rec.stage = d->stage;
+    rec.kind = kind;
+    if (loc)
+        rec.loc = *loc;
+    rec.message = msg;
+    rec.ctx = ctx_snapshot(d);
+    vec_init(rec.notes);
+
+    if (level == SPL_DIAG_LEVEL_ERROR)
+        d->n_errors++;
+    else if (level == SPL_DIAG_LEVEL_FATAL) {
+        d->n_errors++;
+        d->n_fatals++;
+    } else if (level == SPL_DIAG_LEVEL_WARN)
+        d->n_warns++;
+
+    if (d->fout) {
+        print_record(d, &rec);
+        d->num_printed++;
+    }
+
+    if (d->collect)
+        vec_push(d->records, rec);
+    else
+        record_free(&rec);
+}
+
+void spl_diag_note(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                   ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    emit(d, SPL_DIAG_LEVEL_NOTE, kind, loc, fmt, ap);
+    va_end(ap);
+}
+
+void spl_diag_warn(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                   ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    emit(d, SPL_DIAG_LEVEL_WARN, kind, loc, fmt, ap);
+    va_end(ap);
+}
+
+void spl_diag_error(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                    ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    emit(d, SPL_DIAG_LEVEL_ERROR, kind, loc, fmt, ap);
+    va_end(ap);
+}
+
+void spl_diag_fatal(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                    ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    emit(d, SPL_DIAG_LEVEL_FATAL, kind, loc, fmt, ap);
+    va_end(ap);
+}
+
+void spl_diag_attach_note(spl_diag_t *d, const spl_dbg_node_t *loc, const char *fmt, ...) {
+    if (vec_size(d->records) == 0)
+        return;
+    spl_diag_record_t *last = &vec_at(d->records, vec_size(d->records) - 1);
+
+    va_list ap;
+    va_start(ap, fmt);
+    int need = vsnprintf(NULL, 0, fmt, ap);
+    va_end(ap);
+    if (need < 0)
+        need = 0;
+
+    char *msg = malloc((usize)need + 1);
+    if (msg) {
+        va_start(ap, fmt);
+        vsnprintf(msg, (usize)need + 1, fmt, ap);
+        va_end(ap);
+    }
+
+    spl_diag_note_t n = {0};
+    if (loc)
+        n.loc = *loc;
+    n.message = msg;
+    vec_push(last->notes, n);
+}
+
+bool spl_diag_has_error(const spl_diag_t *d) { return d->n_errors > 0; }
+
+bool spl_diag_has_fatal(const spl_diag_t *d) { return d->n_fatals > 0; }
+
+usize spl_diag_error_count(const spl_diag_t *d) { return d->n_errors; }
+
+usize spl_diag_warn_count(const spl_diag_t *d) { return d->n_warns; }
+
+void spl_diag_summary(const spl_diag_t *d) {
+    FILE *out = (FILE *)d->fout;
+    if (!out)
+        return;
+
+    /* 把还没实时打印过的记录补打一遍。
+       collect == false 时 records 是空的，num_printed 可能非零，
+       用 records.size 兜底避免越界。 */
+    usize printed_limit = d->num_printed;
+    if (printed_limit > vec_size(d->records))
+        printed_limit = vec_size(d->records);
+
+    for (usize i = printed_limit; i < vec_size(d->records); ++i)
+        print_record(d, &vec_at(d->records, i));
+
+    /* 计数 */
+    const char *ecol = d->color && d->n_errors > 0 ? ANSI_FG_RED : "";
+    const char *rst = d->color ? ANSI_NONE : "";
+    fprintf(out, "%s%zu error%s, %zu warning%s%s\n", ecol, d->n_errors, d->n_errors == 1 ? "" : "s",
+            d->n_warns, d->n_warns == 1 ? "" : "s", rst);
+}

stage1/spl_diag.h

@@ -0,0 +1,165 @@
+#ifndef __SPL_DIAG_H__
+#define __SPL_DIAG_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_dbg.h"
+
+typedef enum {
+    SPL_DIAG_LEVEL_NOTE = 0,
+    SPL_DIAG_LEVEL_WARN,
+    SPL_DIAG_LEVEL_ERROR,
+    SPL_DIAG_LEVEL_FATAL,
+} spl_diag_level_t;
+
+typedef enum {
+    SPL_STAGE_NONE = 0,
+    SPL_STAGE_LEX,
+    SPL_STAGE_PARSE,
+    SPL_STAGE_SEMA,
+    SPL_STAGE_AST2IR,
+    SPL_STAGE_IR2VM,
+    SPL_STAGE_DRIVER,
+} spl_diag_stage_t;
+
+/* kind 枚举：边写边补。新增时放对应分组末尾即可。 */
+typedef enum {
+    SPL_DIAG_KIND_NONE = 0,
+
+    /* 词法 / 语法 */
+    SPL_DIAG_KIND_LEX_UNEXPECTED,
+    SPL_DIAG_KIND_PARSE_EXPECTED,
+    SPL_DIAG_KIND_PARSE_UNRECOGNIZED,
+
+    /* sema */
+    SPL_DIAG_KIND_UNDEFINED_SYMBOL,
+    SPL_DIAG_KIND_DUPLICATE_SYMBOL,
+    SPL_DIAG_KIND_TYPE_MISMATCH,
+    SPL_DIAG_KIND_ARG_COUNT_MISMATCH,
+    SPL_DIAG_KIND_NOT_A_FUNCTION,
+    SPL_DIAG_KIND_NO_FIELD,
+    SPL_DIAG_KIND_NO_METHOD,
+    SPL_DIAG_KIND_INDEX_BASE_INVALID,
+    SPL_DIAG_KIND_TUPLE_INDEX_OOB,
+    SPL_DIAG_KIND_FITS_OVERFLOW,
+    SPL_DIAG_KIND_CIRCULAR_DEP,
+    SPL_DIAG_KIND_BREAK_OUTSIDE_LOOP,
+    SPL_DIAG_KIND_CONTINUE_OUTSIDE_LOOP,
+    SPL_DIAG_KIND_UNDEFINED_LABEL,
+    SPL_DIAG_KIND_CAST_INVALID,
+    SPL_DIAG_KIND_UNKNOWN_ATTR,
+    SPL_DIAG_KIND_UNKNOWN_INTRIN,
+    SPL_DIAG_KIND_INTRIN_ARG_COUNT,
+    SPL_DIAG_KIND_VAR_UNINITIALIZED,
+    SPL_DIAG_KIND_CANNOT_INFER,
+    SPL_DIAG_KIND_MUST_RETURN_VALUE,
+
+    /* ast2ir */
+    SPL_DIAG_KIND_UNHANDLED_NODE,
+    SPL_DIAG_KIND_IMPLICIT_CAST_FAIL,
+    SPL_DIAG_KIND_NO_LVALUE,
+    SPL_DIAG_KIND_BAD_FIELD_INDEX,
+    SPL_DIAG_KIND_BAD_BLOCK,
+
+    /* ir2vm */
+    SPL_DIAG_KIND_IR_UNKNOWN_KIND,
+    SPL_DIAG_KIND_FRAME_OVERFLOW,
+
+    /* 通用 */
+    SPL_DIAG_KIND_INTERNAL,
+} spl_diag_kind_t;
+
+typedef struct {
+    spl_dbg_node_t loc;
+    char *fn_name;
+    char *label;
+} spl_diag_frame_t;
+typedef VEC(spl_diag_frame_t) spl_diag_frame_vec_t;
+
+typedef struct {
+    spl_dbg_node_t loc;
+    char *message;
+} spl_diag_note_t;
+typedef VEC(spl_diag_note_t) spl_diag_note_vec_t;
+
+typedef struct {
+    spl_diag_level_t level;
+    spl_diag_stage_t stage;
+    spl_diag_kind_t kind;
+    spl_dbg_node_t loc;
+    char *message;
+    spl_diag_frame_vec_t ctx;
+    spl_diag_note_vec_t notes;
+} spl_diag_record_t;
+typedef VEC(spl_diag_record_t) spl_diag_record_vec_t;
+
+typedef struct spl_diag {
+    spl_diag_frame_vec_t ctx;
+    spl_diag_record_vec_t records;
+    usize num_printed;
+    bool collect;
+    usize n_errors;
+    usize n_warns;
+    usize n_fatals;
+    spl_diag_stage_t stage;
+    void *fout;
+    bool color;
+} spl_diag_t;
+
+void spl_diag_init(spl_diag_t *d, void *fout);
+void spl_diag_drop(spl_diag_t *d);
+void spl_diag_reset(spl_diag_t *d);
+void spl_diag_set_stage(spl_diag_t *d, spl_diag_stage_t stage);
+void spl_diag_set_output(spl_diag_t *d, FILE *out);
+void spl_diag_set_color(spl_diag_t *d, bool enabled);
+void spl_diag_set_collect(spl_diag_t *d, bool enabled);
+
+void spl_diag_push(spl_diag_t *d, const spl_dbg_node_t *loc, const char *fn_name,
+                   const char *label);
+void spl_diag_pop(spl_diag_t *d);
+usize spl_diag_depth(const spl_diag_t *d);
+
+/* ============================================================
+ * 发射
+ *
+ * 每个级别都生成独立的 spl_diag_record_t：
+ *   - 计入 records（collect=true 时）
+ *   - error/fatal 计入 n_errors，warn 计入 n_warns
+ *   - 立刻输出到 out（如果非 NULL）
+ *
+ * 四种级别的语义区别：
+ *   note  —— 一般信息；不阻塞；用在前序诊断之外的独立说明
+ *   warn  —— 警告；不阻塞；driver 可忽略
+ *   error —— 用户代码错误；调用者应 return 0
+ *   fatal —— 用户代码错误到数据结构已损坏；调用者必须 return 0
+ * ============================================================ */
+void spl_diag_note(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                   ...);
+void spl_diag_warn(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                   ...);
+void spl_diag_error(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                    ...);
+void spl_diag_fatal(spl_diag_t *d, spl_diag_kind_t kind, const spl_dbg_node_t *loc, const char *fmt,
+                    ...);
+
+/* 挂到最近一条记录（records 末尾）的 notes 列表下。
+ * 不生成独立记录、不计入计数，输出时显示为：
+ *     note: <loc>
+ *         <msg>
+ * 使用场景：辅助说明前一条诊断，例如
+ *     spl_diag_error(d, DUPLICATE_SYMBOL, &n->dbg, "duplicate symbol `foo`");
+ *     spl_diag_attach_note(d, &prev->dbg, "previously defined here");
+ * 约束：只在 records 非空时生效；否则静默丢弃，不报错。 */
+void spl_diag_attach_note(spl_diag_t *d, const spl_dbg_node_t *loc, const char *fmt, ...);
+
+bool spl_diag_has_error(const spl_diag_t *d);
+bool spl_diag_has_fatal(const spl_diag_t *d);
+usize spl_diag_error_count(const spl_diag_t *d);
+usize spl_diag_warn_count(const spl_diag_t *d);
+
+void spl_diag_summary(const spl_diag_t *d);
+
+const char *spl_diag_kind_name(spl_diag_kind_t k);
+const char *spl_diag_stage_name(spl_diag_stage_t s);
+const char *spl_diag_level_name(spl_diag_level_t l);
+
+#endif /* __SPL_DIAG_H__ */

stage1/spl_dumptree.c

@@ -0,0 +1,26 @@
+/* spl_dumptree.c 可配置的树形打印模块（只用基本 ASCII）*/
+
+#include "spl_dumptree.h"
+#include <stdarg.h>
+
+const spl_dumptree_style_t spl_dumptree_ascii_style = {
+    "| ",
+    "|-",
+    "`-",
+    "  ",
+};
+
+void spl_dumptree_print(const spl_dumptree_style_t *st, const char *prefix, int is_last,
+                        const char *fmt, ...) {
+    va_list ap;
+    printf("%s%s ", prefix, is_last ? st->last_branch : st->branch);
+    va_start(ap, fmt);
+    vprintf(fmt, ap);
+    va_end(ap);
+    printf("\n");
+}
+
+void spl_dumptree_child_prefix(const spl_dumptree_style_t *st, const char *prefix, int is_last,
+                               char *out, size_t cap) {
+    snprintf(out, cap, "%s%s", prefix, is_last ? st->space : st->vertical);
+}

stage1/spl_dumptree.h

@@ -0,0 +1,31 @@
+/* spl_dumptree.h 可配置的树形打印模块（只用基本 ASCII）*/
+
+#ifndef __SPL_DUMPTREE_H__
+#define __SPL_DUMPTREE_H__
+
+#include <stddef.h>
+#include <stdio.h>
+
+/* 可配置的缩进字符串 */
+typedef struct {
+    const char *vertical;    /* "| "  */
+    const char *branch;      /* "|-"  */
+    const char *last_branch; /* "`-"  */
+    const char *space;       /* "  "  */
+} spl_dumptree_style_t;
+
+/* 默认 ASCII 风格 */
+extern const spl_dumptree_style_t spl_dumptree_ascii_style;
+
+/* 打印一行节点标签：prefix + 分支符 + label
+ * prefix  已累积的缩进骨架（不含分支符）
+ * is_last 本节点是否为同级最后一个子节点
+ * fmt     printf 风格 label */
+void spl_dumptree_print(const spl_dumptree_style_t *st, const char *prefix, int is_last,
+                        const char *fmt, ...);
+
+/* 生成子节点的缩进骨架：parent_prefix + (parent_is_last ? space : vertical) */
+void spl_dumptree_child_prefix(const spl_dumptree_style_t *st, const char *prefix, int is_last,
+                               char *out, size_t cap);
+
+#endif /* __SPL_DUMPTREE_H__ */

stage1/spl_emit.h

@@ -0,0 +1,4 @@
+#ifndef __SPL_EMIT_H__
+#define __SPL_EMIT_H__
+
+#endif /* __SPL_EMIT_H__ */

stage1/spl_intrin.c

@@ -0,0 +1,99 @@
+#include "spl_intrin.h"
+
+static const spl_intrin_info_t g_intrin_table[] = {
+    [SPL_INTRIN_NONE] = {0},
+    [SPL_INTRIN_SIZEOF] = {"@sizeof", SPL_INTRIN_SIZEOF, SPL_INTRIN_FORM_CALL, 1, 1,
+                           SPL_INTRIN_RESULT_USIZE},
+    [SPL_INTRIN_ALIGNOF] = {"@alignof", SPL_INTRIN_ALIGNOF, SPL_INTRIN_FORM_CALL, 1, 1,
+                            SPL_INTRIN_RESULT_USIZE},
+    [SPL_INTRIN_ASSERT] = {"@assert", SPL_INTRIN_ASSERT, SPL_INTRIN_FORM_CALL, 1, 2,
+                           SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_BREAKPOINT] = {"@breakpoint", SPL_INTRIN_BREAKPOINT, SPL_INTRIN_FORM_CALL, 0, 0,
+                               SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_LEN] = {"len", SPL_INTRIN_LEN, SPL_INTRIN_FORM_FIELD, 0, 0,
+                        SPL_INTRIN_RESULT_USIZE},
+    [SPL_INTRIN_INT_CAST] = {"@int_cast", SPL_INTRIN_INT_CAST, SPL_INTRIN_FORM_CALL, 2, 2,
+                             SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_TRUNCATE] = {"@truncate", SPL_INTRIN_TRUNCATE, SPL_INTRIN_FORM_CALL, 2, 2,
+                             SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_BIT_CAST] = {"@bit_cast", SPL_INTRIN_BIT_CAST, SPL_INTRIN_FORM_CALL, 2, 2,
+                             SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_FLOAT_CAST] = {"@float_cast", SPL_INTRIN_FLOAT_CAST, SPL_INTRIN_FORM_CALL, 2, 2,
+                               SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_INT_FROM_FLOAT] = {"@int_from_float", SPL_INTRIN_INT_FROM_FLOAT,
+                                   SPL_INTRIN_FORM_CALL, 2, 2, SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_FLOAT_FROM_INT] = {"@float_from_int", SPL_INTRIN_FLOAT_FROM_INT,
+                                   SPL_INTRIN_FORM_CALL, 2, 2, SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_INT_FROM_BOOL] = {"@int_from_bool", SPL_INTRIN_INT_FROM_BOOL, SPL_INTRIN_FORM_CALL,
+                                  1, 2, SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_INT_FROM_PTR] = {"@int_from_ptr", SPL_INTRIN_INT_FROM_PTR, SPL_INTRIN_FORM_CALL, 1,
+                                 2, SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_PTR_FROM_INT] = {"@ptr_from_int", SPL_INTRIN_PTR_FROM_INT, SPL_INTRIN_FORM_CALL, 2,
+                                 2, SPL_INTRIN_RESULT_UNIT},
+    [SPL_INTRIN_PTR_CAST] = {"@ptr_cast", SPL_INTRIN_PTR_CAST, SPL_INTRIN_FORM_CALL, 2, 2,
+                             SPL_INTRIN_RESULT_UNIT},
+};
+
+static const usize g_intrin_count = sizeof(g_intrin_table) / sizeof(g_intrin_table[0]);
+
+const spl_intrin_info_t *spl_intrin_info(spl_intrin_t kind) {
+    if ((usize)kind >= g_intrin_count)
+        return NULL;
+    return &g_intrin_table[kind];
+}
+
+spl_intrin_t spl_intrin_lookup_call(const char *name) {
+    if (!name)
+        return SPL_INTRIN_NONE;
+    const char *n = name[0] == '@' ? name + 1 : name;
+    for (usize i = 1; i < g_intrin_count; ++i) {
+        const spl_intrin_info_t *d = &g_intrin_table[i];
+        if (d->form != SPL_INTRIN_FORM_CALL)
+            continue;
+        const char *dn = d->name[0] == '@' ? d->name + 1 : d->name;
+        if (strcmp(dn, n) == 0)
+            return d->kind;
+    }
+    return SPL_INTRIN_NONE;
+}
+
+spl_intrin_t spl_intrin_lookup_field(spl_lang_type_kind_t recv_kind, const char *field) {
+    if (!field)
+        return SPL_INTRIN_NONE;
+    if (strcmp(field, "len") == 0) {
+        if (recv_kind == SPL_LANG_TYPE_ARRAY || recv_kind == SPL_LANG_TYPE_SLICE)
+            return SPL_INTRIN_LEN;
+    }
+    return SPL_INTRIN_NONE;
+}
+
+spl_intrin_t spl_intrin_lookup_cast(spl_type_t *type, spl_type_id_t ft, spl_type_id_t tt) {
+    /* 这是 `as` 的展开规则表。要调整 as 的语义，改这里。 */
+    spl_type_node_t *f = spl_type_node(type, ft);
+    spl_type_node_t *t = spl_type_node(type, tt);
+    if (!f || !t)
+        return SPL_INTRIN_NONE;
+
+    if (f->kind == SPL_TYPE_INT && t->kind == SPL_TYPE_INT) {
+        usize fb = f->int_type.bits;
+        usize tb = t->int_type.bits;
+        if (fb == tb)
+            return SPL_INTRIN_BIT_CAST;
+        if (fb > tb)
+            return SPL_INTRIN_TRUNCATE;
+        return SPL_INTRIN_INT_CAST;
+    }
+    if (f->kind == SPL_TYPE_FLOAT && t->kind == SPL_TYPE_FLOAT)
+        return SPL_INTRIN_FLOAT_CAST;
+    if (f->kind == SPL_TYPE_BOOL && t->kind == SPL_TYPE_INT)
+        return SPL_INTRIN_INT_FROM_BOOL;
+    if (f->kind == SPL_TYPE_PTR && t->kind == SPL_TYPE_INT)
+        return SPL_INTRIN_INT_FROM_PTR;
+    if (f->kind == SPL_TYPE_INT && t->kind == SPL_TYPE_PTR)
+        return SPL_INTRIN_PTR_FROM_INT;
+    if (f->kind == SPL_TYPE_PTR && t->kind == SPL_TYPE_PTR)
+        return SPL_INTRIN_PTR_CAST;
+
+    /* int float 刻意不在这里：只能通过显式 builtin 调用。 */
+    return SPL_INTRIN_NONE;
+}

stage1/spl_intrin.h

@@ -0,0 +1,56 @@
+#ifndef __SPL_INTRIN_H__
+#define __SPL_INTRIN_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_lang_type.h"
+
+typedef enum {
+    SPL_INTRIN_NONE = 0,
+    SPL_INTRIN_SIZEOF,
+    SPL_INTRIN_ALIGNOF,
+    SPL_INTRIN_ASSERT,
+    SPL_INTRIN_BREAKPOINT,
+    SPL_INTRIN_LEN,
+    SPL_INTRIN_INT_CAST,
+    SPL_INTRIN_TRUNCATE,
+    SPL_INTRIN_BIT_CAST,
+    SPL_INTRIN_FLOAT_CAST,
+    SPL_INTRIN_INT_FROM_FLOAT,
+    SPL_INTRIN_FLOAT_FROM_INT,
+    SPL_INTRIN_INT_FROM_BOOL,
+    SPL_INTRIN_INT_FROM_PTR,
+    SPL_INTRIN_PTR_FROM_INT,
+    SPL_INTRIN_PTR_CAST,
+} spl_intrin_t;
+
+typedef enum {
+    SPL_INTRIN_FORM_CALL = 1,  /* @sizeof(...)  @assert(...) */
+    SPL_INTRIN_FORM_FIELD = 2, /* recv.len                   */
+} spl_intrin_form_t;
+
+typedef enum {
+    SPL_INTRIN_RESULT_UNIT,
+    SPL_INTRIN_RESULT_BOOL,
+    SPL_INTRIN_RESULT_USIZE,
+} spl_intrin_result_t;
+
+typedef struct {
+    const char *name;
+    spl_intrin_t kind;
+    spl_intrin_form_t form;
+    int min_args; /* FIELD 形态忽略 */
+    int max_args; /* -1 = variadic  */
+    spl_intrin_result_t result;
+} spl_intrin_info_t;
+
+spl_intrin_t spl_intrin_lookup_call(const char *name);
+spl_intrin_t spl_intrin_lookup_field(spl_lang_type_kind_t recv_kind, const char *field);
+spl_intrin_t spl_intrin_lookup_cast(spl_type_t *type, spl_type_id_t ft, spl_type_id_t tt);
+
+const spl_intrin_info_t *spl_intrin_info(spl_intrin_t kind);
+
+/* ---- 与 IR 侧共享的类型布局约定 ---- */
+#define SPL_SLICE_PTR_FIELD_IDX 0
+#define SPL_SLICE_LEN_FIELD_IDX 1
+
+#endif /* __SPL_INTRIN_H__ */

stage1/spl_ir.c

@@ -0,0 +1,847 @@
+#include "spl_ir.h"
+
+const char *spl_ir_kind_name(spl_ir_kind_t kind) {
+    static const char *const names[] = {
+#define X(a, b, c) #a,
+        SPL_IR_FN_TABLE
+#undef X
+    };
+    if ((usize)kind < sizeof(names) / sizeof(names[0]))
+        return names[kind];
+    return "?";
+}
+
+void spl_ir_init(spl_ir_t *ir) {
+    vec_init(ir->funcs);
+    vec_push(ir->funcs, (spl_ir_func_t){0});
+    // vec_init(ir->gdata);
+    // vec_push(ir->gdata, (spl_ir_node_t){0});
+}
+
+static void node_drop_vecs(spl_ir_node_t *n) {
+    if (!n)
+        return;
+    switch (n->kind) {
+    case SPL_IR_AGG_CONSTRUCT:
+        vec_free(n->agg_construct.fields);
+        break;
+    case SPL_IR_CONTROL_CALL:
+        vec_free(n->control_call.params);
+        break;
+    case SPL_IR_DBG_PANIC:
+        free((char *)n->dbg_panic.msg);
+        break;
+    default:
+        break;
+    }
+}
+
+void spl_ir_drop(spl_ir_t *ir) {
+    vec_for(ir->funcs, i) {
+        spl_ir_func_t *f = &vec_at(ir->funcs, i);
+        vec_for(f->nodes, j) {
+            vec_free(vec_at(f->nodes, j).attrs);
+            node_drop_vecs(&vec_at(f->nodes, j));
+        }
+        vec_free(f->attrs);
+        vec_free(f->nodes);
+    }
+    vec_free(ir->funcs);
+    // vec_for(ir->gdata, i) { node_drop_vecs(&vec_at(ir->gdata, i)); }
+    // vec_free(ir->gdata);
+}
+
+// 申请空的 ir_func 返回 id
+spl_ir_func_ref_t spl_ir_alloc_fn(spl_ir_t *ir) {
+    if (ir == NULL) {
+        return 0;
+    }
+    spl_ir_func_t f = {0};
+    vec_init(f.nodes);
+    vec_push(f.nodes, (spl_ir_node_t){0});
+    vec_push(ir->funcs, f);
+    return vec_size(ir->funcs) - 1;
+}
+
+// 从 fn_id 申请空的 ir_node 返回 id
+spl_ir_node_ref_t spl_ir_alloc_node(spl_ir_t *ir, spl_ir_func_ref_t fn_id) {
+    if (!fn_id || fn_id >= vec_size(ir->funcs)) {
+        return 0;
+    }
+    spl_ir_func_t *f = &vec_at(ir->funcs, fn_id);
+    spl_ir_node_t n = {0};
+    vec_push(f->nodes, n);
+    return vec_size(f->nodes) - 1;
+}
+
+// 从 fn_id 里通过 node_id 获取 ir_node
+spl_ir_node_t *spl_ir_node(spl_ir_t *ir, spl_ir_func_ref_t fn_id, spl_ir_node_ref_t node_id) {
+    if (!fn_id || fn_id >= vec_size(ir->funcs)) {
+        return NULL;
+    }
+    spl_ir_func_t *f = &vec_at(ir->funcs, fn_id);
+    if (!node_id || node_id >= vec_size(f->nodes)) {
+        return NULL;
+    }
+    return &vec_at(f->nodes, node_id);
+}
+
+// 从 fn_id 获取 ir_func
+spl_ir_func_t *spl_ir_func(spl_ir_t *ir, spl_ir_func_ref_t fn_id) {
+    if (!fn_id || fn_id >= vec_size(ir->funcs)) {
+        return NULL;
+    }
+    return &vec_at(ir->funcs, fn_id);
+}
+
+static inline void ir_dump_type(const spl_type_t *ty, spl_type_id_t tid) {
+    printf("(");
+    spl_type_pure_dump((spl_type_t *)ty, tid);
+    printf(")");
+}
+
+static inline void ir_dump_ref(spl_ir_node_ref_t ref) {
+    if (ref == 0) {
+        printf(" _");
+    } else {
+        printf(" %%%zu", ref);
+    }
+}
+
+static void ir_dump_node(const spl_type_t *ty, spl_ir_node_t *n) {
+    switch (n->kind) {
+    case SPL_IR_ARITH_ADD:
+    case SPL_IR_ARITH_SUB:
+    case SPL_IR_ARITH_MUL:
+    case SPL_IR_ARITH_DIV:
+    case SPL_IR_ARITH_REM:
+    case SPL_IR_ARITH_AND:
+    case SPL_IR_ARITH_OR:
+    case SPL_IR_ARITH_XOR:
+    case SPL_IR_ARITH_SHL:
+    case SPL_IR_ARITH_SHR:
+        ir_dump_type(ty, n->arith.tid);
+        ir_dump_ref(n->arith.left);
+        ir_dump_ref(n->arith.right);
+        break;
+    case SPL_IR_ARITH_NEG:
+    case SPL_IR_ARITH_ABS:
+    case SPL_IR_ARITH_NOT:
+        ir_dump_type(ty, n->arith.tid);
+        ir_dump_ref(n->arith.left);
+        break;
+    case SPL_IR_CMP_EQ:
+    case SPL_IR_CMP_NE:
+    case SPL_IR_CMP_LT:
+    case SPL_IR_CMP_LE:
+    case SPL_IR_CMP_GT:
+    case SPL_IR_CMP_GE:
+        ir_dump_type(ty, n->cmp.tid);
+        ir_dump_ref(n->cmp.a);
+        ir_dump_ref(n->cmp.b);
+        break;
+    case SPL_IR_CAST_TRUNC:
+    case SPL_IR_CAST_ZEXT:
+    case SPL_IR_CAST_SEXT:
+    case SPL_IR_CAST_FEXT:
+    case SPL_IR_CAST_FTRUNC:
+    case SPL_IR_CAST_BITCAST:
+    case SPL_IR_CAST_PTR2INT:
+    case SPL_IR_CAST_INT2PTR:
+    case SPL_IR_CAST_BOOL2INT:
+    case SPL_IR_CASE_INT2FLOAT:
+    case SPL_IR_CASE_FLOAT2INT:
+        printf(" ");
+        spl_type_pure_dump((spl_type_t *)ty, n->cast.from_tid);
+        printf(" -> ");
+        spl_type_pure_dump((spl_type_t *)ty, n->cast.to_tid);
+        ir_dump_ref(n->cast.val);
+        break;
+    case SPL_IR_MEM_ALLOCA:
+        ir_dump_type(ty, n->mem_alloc.tid);
+        ir_dump_ref(n->mem_alloc.count);
+        break;
+    case SPL_IR_MEM_GLOBAL_ALLOC:
+        ir_dump_type(ty, n->mem_global_alloc.tid);
+        printf(" g#%zu", n->mem_global_alloc.const_node);
+        break;
+    case SPL_IR_MEM_LOAD:
+        ir_dump_type(ty, n->mem_load.tid);
+        ir_dump_ref(n->mem_load.ptr);
+        break;
+    case SPL_IR_MEM_STORE:
+        ir_dump_type(ty, n->mem_store.tid);
+        ir_dump_ref(n->mem_store.ptr);
+        ir_dump_ref(n->mem_store.val);
+        break;
+    case SPL_IR_MEM_OFFSET:
+        ir_dump_type(ty, n->mem_offset.tid);
+        ir_dump_ref(n->mem_offset.ptr);
+        ir_dump_ref(n->mem_offset.offset);
+        break;
+    case SPL_IR_MEM_FIELD_PTR:
+        ir_dump_type(ty, n->mem_field_ptr.tid);
+        ir_dump_ref(n->mem_field_ptr.agg);
+        printf(" #%zu", n->mem_field_ptr.field_idx);
+        break;
+    case SPL_IR_MEM_COPY:
+        ir_dump_type(ty, n->mem_copy.tid);
+        ir_dump_ref(n->mem_copy.dst);
+        ir_dump_ref(n->mem_copy.src);
+        ir_dump_ref(n->mem_copy.size);
+        break;
+    case SPL_IR_MEM_SET:
+        ir_dump_type(ty, n->mem_set.tid);
+        ir_dump_ref(n->mem_set.dst);
+        ir_dump_ref(n->mem_set.val);
+        ir_dump_ref(n->mem_set.size);
+        break;
+    case SPL_IR_TYPE_CONST: {
+        ir_dump_type(ty, n->type_const.tid);
+        spl_type_node_t *t = spl_type_node((spl_type_t *)ty, n->type_const.tid);
+        if (t && t->kind == SPL_TYPE_FLOAT) {
+            printf(" float=%f", n->type_const.float_lit);
+        } else if (t && t->kind == SPL_TYPE_FN) {
+            printf(" fn#%zu", n->type_const.fn);
+            // } else if (t && t->kind == SPL_TYPE_PTR) {
+            //     printf(" str=\"%s\"", n->type_const.cstr_lit ? n->type_const.cstr_lit : "?");
+        } else if (t && t->kind == SPL_TYPE_INT && t->int_type.bits == 8) {
+            printf(" char='%c'", n->type_const.ch_lit);
+        } else {
+            printf(" int=%zu", n->type_const.int_lit);
+        }
+        break;
+    }
+    case SPL_IR_TYPE_BITSIZEOF:
+        ir_dump_type(ty, n->bitsizeof.tid);
+        break;
+    case SPL_IR_TYPE_SIZEOF:
+        ir_dump_type(ty, n->ir_sizeof.tid);
+        break;
+    case SPL_IR_TYPE_ALIGNOF:
+        ir_dump_type(ty, n->ir_alignof.tid);
+        break;
+    case SPL_IR_TYPE_OFFSETOF:
+        ir_dump_type(ty, n->ir_offsetof.tid);
+        ir_dump_ref(n->ir_offsetof.field_idx);
+        break;
+    case SPL_IR_TYPE_FIELD_COUNT:
+        ir_dump_type(ty, n->field_count.tid);
+        break;
+    case SPL_IR_AGG_CONSTRUCT:
+        ir_dump_type(ty, n->agg_construct.tid);
+        vec_for(n->agg_construct.fields, i) ir_dump_ref(vec_at(n->agg_construct.fields, i));
+        break;
+    case SPL_IR_AGG_EXTRACT:
+        ir_dump_type(ty, n->agg_extract.tid);
+        printf(" #%zu", n->agg_extract.field_idx);
+        ir_dump_ref(n->agg_extract.val);
+        break;
+    case SPL_IR_AGG_INSERT:
+        ir_dump_type(ty, n->agg_insert.tid);
+        printf(" #%zu", n->agg_insert.field_idx);
+        ir_dump_ref(n->agg_insert.agg);
+        ir_dump_ref(n->agg_insert.field);
+        break;
+    case SPL_IR_CONTROL_SELECT:
+        ir_dump_type(ty, n->control_select.tid);
+        ir_dump_ref(n->control_select.cond);
+        ir_dump_ref(n->control_select.true_val);
+        ir_dump_ref(n->control_select.false_val);
+        break;
+    case SPL_IR_CONTROL_BR:
+        ir_dump_ref(n->control_br.cond);
+        ir_dump_ref(n->control_br.true_label);
+        ir_dump_ref(n->control_br.false_label);
+        break;
+    case SPL_IR_CONTROL_JMP:
+        ir_dump_ref(n->control_jmp.label);
+        break;
+    case SPL_IR_CONTROL_CALL:
+        ir_dump_type(ty, n->control_call.tid);
+        ir_dump_ref(n->control_call.func);
+        vec_for(n->control_call.params, i) ir_dump_ref(vec_at(n->control_call.params, i));
+        break;
+    case SPL_IR_CONTROL_PARAM:
+        ir_dump_type(ty, n->control_param.tid);
+        ir_dump_ref(n->control_param.idx);
+        break;
+    case SPL_IR_CONTROL_RET:
+        ir_dump_type(ty, n->control_ret.tid);
+        ir_dump_ref(n->control_ret.val);
+        break;
+    case SPL_IR_CONTROL_UNREACHABLE:
+    case SPL_IR_CONTROL_TRAP:
+    case SPL_IR_DBG_BREAKPOINT:
+        break;
+    case SPL_IR_DBG_PANIC:
+        printf(" \"%.*s\"", (int)n->dbg_panic.len, n->dbg_panic.msg);
+        break;
+    }
+}
+
+static void ir_dump_attr_list(const spl_attr_t *attr, spl_attr_id_vec_t *ids) {
+    if (!attr || !ids || vec_size(*ids) == 0)
+        return;
+    printf(" attrs=[");
+    for (usize i = 0; i < vec_size(*ids); ++i) {
+        if (i > 0)
+            printf(", ");
+        spl_attr_dump_id(attr, vec_at(*ids, i));
+    }
+    printf("]");
+}
+
+void spl_ir_dump(spl_ir_t *ir, const spl_type_t *ty, const spl_attr_t *attr) {
+    vec_for(ir->funcs, i) {
+        if (i == 0)
+            continue;
+        spl_ir_func_t *func = &vec_at(ir->funcs, i);
+        printf("func %s %%%zu", func->name ? func->name : "?", i);
+        printf(" tid = ");
+        spl_type_pure_dump((spl_type_t *)ty, func->fn_tid);
+        ir_dump_attr_list(attr, &func->attrs);
+        printf("\n");
+
+        vec_for(func->nodes, j) {
+            if (j == 0)
+                continue;
+            spl_ir_node_t *node = &vec_at(func->nodes, j);
+            printf("  #%zu ", j);
+            printf("%s", spl_ir_kind_name(node->kind));
+            ir_dump_node(ty, node);
+            ir_dump_attr_list(attr, &node->attrs);
+            printf("\n");
+        }
+    }
+    // if (vec_size(ir->gdata) > 1) {
+    //     printf("gdata:\n");
+    //     vec_for(ir->gdata, i) {
+    //         if (i == 0)
+    //             continue;
+    //         spl_ir_node_t *node = &vec_at(ir->gdata, i);
+    //         printf("  #%zu ", i);
+    //         printf("%s", spl_ir_kind_name(node->kind));
+    //         ir_dump_node(ty, node);
+    //         printf("\n");
+    //     }
+    // }
+}
+
+// IR Builder
+
+// 从当前 fn 申请新的 node 并注入到当前基本块
+static spl_ir_node_ref_t builder_alloc_node(spl_ir_builder_t *b, spl_ir_kind_t kind) {
+    Assert(!b->terminated && "emit into a terminated block");
+    spl_ir_node_ref_t ref = spl_ir_alloc_node(&b->ir, b->current_fn);
+    Assert(ref != 0);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->kind = kind;
+    n->dbg = b->dbg;
+    vec_init(n->attrs);
+
+    if (b->current_block >= vec_size(b->blocks)) {
+        Panic("unknown bblock");
+        return 0;
+    }
+
+    spl_ir_node_ref_t *slot = &vec_at(b->blocks, b->current_block);
+    if (*slot == 0)
+        *slot = ref;
+
+    return ref;
+}
+
+void spl_ir_builder_init(spl_ir_builder_t *b) {
+    spl_ir_init(&b->ir);
+    b->current_fn = 0;
+    b->dbg = (spl_dbg_node_t){0};
+    vec_init(b->blocks);
+    b->current_block = 0;
+    vec_init(b->fixups);
+    b->terminated = false;
+}
+
+void spl_ir_builder_drop(spl_ir_builder_t *b) {
+    spl_ir_drop(&b->ir);
+    vec_free(b->blocks);
+    vec_free(b->fixups);
+}
+
+spl_ir_func_ref_t spl_ir_builder_fn_begin(spl_ir_builder_t *b, const char *name,
+                                          spl_type_id_t fn_tid) {
+    if (b->current_fn) {
+        spl_ir_builder_fn_end(b);
+    }
+    spl_ir_func_ref_t fid = spl_ir_alloc_fn(&b->ir);
+    spl_ir_func_t *f = spl_ir_func(&b->ir, fid);
+    f->name = name;
+    vec_init(f->attrs);
+    f->fn_tid = fn_tid;
+
+    b->current_fn = fid;
+    b->current_block = 0;
+    b->blocks.size = 0;
+    b->fixups.size = 0;
+    b->terminated = false;
+    return fid;
+}
+
+spl_ir_func_ref_t spl_ir_builder_fn_reserve(spl_ir_builder_t *b, const char *name,
+                                            spl_type_id_t fn_tid) {
+    spl_ir_func_ref_t fid = spl_ir_alloc_fn(&b->ir);
+    spl_ir_func_t *f = spl_ir_func(&b->ir, fid);
+    f->name = name;
+    vec_init(f->attrs);
+    f->fn_tid = fn_tid;
+    return fid;
+}
+
+void spl_ir_builder_fn_begin_at(spl_ir_builder_t *b, spl_ir_func_ref_t fid) {
+    if (b->current_fn && b->current_fn != fid) {
+        spl_ir_builder_fn_end(b);
+    }
+    b->current_fn = fid;
+    b->current_block = 0;
+    b->blocks.size = 0;
+    b->fixups.size = 0;
+    b->terminated = false;
+}
+
+void spl_ir_builder_fn_end(spl_ir_builder_t *b) {
+    spl_ir_func_t *f = spl_ir_func(&b->ir, b->current_fn);
+    if (!f) {
+        Panic("ir func not found");
+        return;
+    }
+
+    vec_for(b->fixups, i) {
+        spl_ir_fix_t *fx = &vec_at(b->fixups, i);
+        spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, fx->node);
+        if (!n) {
+            SPL_ERROR(&n->dbg, "unknown node in func");
+            continue;
+        }
+        spl_ir_node_ref_t target = 0;
+        if (fx->block < vec_size(b->blocks)) {
+            target = vec_at(b->blocks, fx->block);
+        }
+        if (target == 0) {
+            Panic("reloc to empty/unknown bblock #%zu", fx->block);
+        }
+        switch (fx->slot) {
+        case SPL_IR_FIX_BR_TRUE:
+            n->control_br.true_label = target;
+            break;
+        case SPL_IR_FIX_BR_FALSE:
+            n->control_br.false_label = target;
+            break;
+        case SPL_IR_FIX_JMP:
+            n->control_jmp.label = target;
+            break;
+        }
+    }
+
+    b->current_block = 0;
+    b->blocks.size = 0;
+    b->fixups.size = 0;
+    b->terminated = false;
+}
+
+usize spl_ir_builder_block_begin(spl_ir_builder_t *b) {
+    vec_push(b->blocks, (spl_ir_block_t){0});
+    usize block = vec_size(b->blocks) - 1;
+    b->current_block = block;
+    b->terminated = false;
+    return block;
+}
+
+void spl_ir_builder_block_end(spl_ir_builder_t *b) {
+    if (!b->terminated) {
+        Panic("bblock must be end of terminated");
+    }
+    if (b->current_block != 0 && b->current_block < vec_size(b->blocks) &&
+        vec_at(b->blocks, b->current_block) == 0) {
+        Panic("bblock #%zu is empty (no entry node emitted)", b->current_block);
+    }
+}
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *builder, spl_type_id_t x_tid,        \
+                                            spl_ir_node_ref_t x_left, spl_ir_node_ref_t x_right) { \
+        spl_ir_node_ref_t ref = builder_alloc_node(builder, kind);                                 \
+        spl_ir_node_t *n = spl_ir_node(&builder->ir, builder->current_fn, ref);                    \
+        n->arith.tid = x_tid;                                                                      \
+        n->arith.left = x_left;                                                                    \
+        n->arith.right = x_right;                                                                  \
+        return ref;                                                                                \
+    }
+SPL_IR_BIN_ARITH_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *builder, spl_type_id_t x_tid,        \
+                                            spl_ir_node_ref_t x_val) {                             \
+        spl_ir_node_ref_t ref = builder_alloc_node(builder, kind);                                 \
+        spl_ir_node_t *n = spl_ir_node(&builder->ir, builder->current_fn, ref);                    \
+        n->arith.tid = x_tid;                                                                      \
+        n->arith.left = x_val;                                                                     \
+        n->arith.right = 0;                                                                        \
+        return ref;                                                                                \
+    }
+SPL_IR_UN_ARITH_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *builder, spl_type_id_t x_tid,        \
+                                            spl_ir_node_ref_t x_a, spl_ir_node_ref_t x_b) {        \
+        spl_ir_node_ref_t ref = builder_alloc_node(builder, kind);                                 \
+        spl_ir_node_t *n = spl_ir_node(&builder->ir, builder->current_fn, ref);                    \
+        n->cmp.tid = x_tid;                                                                        \
+        n->cmp.a = x_a;                                                                            \
+        n->cmp.b = x_b;                                                                            \
+        return ref;                                                                                \
+    }
+SPL_IR_CMP_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *builder, spl_type_id_t x_from,       \
+                                            spl_type_id_t x_to, spl_ir_node_ref_t x_val) {         \
+        spl_ir_node_ref_t ref = builder_alloc_node(builder, kind);                                 \
+        spl_ir_node_t *n = spl_ir_node(&builder->ir, builder->current_fn, ref);                    \
+        n->cast.from_tid = x_from;                                                                 \
+        n->cast.to_tid = x_to;                                                                     \
+        n->cast.val = x_val;                                                                       \
+        return ref;                                                                                \
+    }
+SPL_IR_CAST_TABLE
+#undef X
+
+spl_ir_node_ref_t spl_ir_builder_mem_alloca(spl_ir_builder_t *b, spl_type_id_t tid,
+                                            spl_ir_node_ref_t count) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_ALLOCA);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_alloc.tid = tid;
+    n->mem_alloc.count = count;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_global_alloc(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  spl_ir_node_ref_t const_node) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_GLOBAL_ALLOC);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_global_alloc.tid = tid;
+    n->mem_global_alloc.const_node = const_node;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_load(spl_ir_builder_t *b, spl_type_id_t tid,
+                                          spl_ir_node_ref_t ptr) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_LOAD);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_load.tid = tid;
+    n->mem_load.ptr = ptr;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_store(spl_ir_builder_t *b, spl_type_id_t tid,
+                                           spl_ir_node_ref_t ptr, spl_ir_node_ref_t val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_STORE);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_store.tid = tid;
+    n->mem_store.ptr = ptr;
+    n->mem_store.val = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_offset(spl_ir_builder_t *b, spl_type_id_t tid,
+                                            spl_ir_node_ref_t ptr, spl_ir_node_ref_t offset) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_OFFSET);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_offset.tid = tid;
+    n->mem_offset.ptr = ptr;
+    n->mem_offset.offset = offset;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_field(spl_ir_builder_t *b, spl_type_id_t tid,
+                                           spl_ir_node_ref_t agg, usize field_idx) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_FIELD_PTR);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_field_ptr.tid = tid;
+    n->mem_field_ptr.agg = agg;
+    n->mem_field_ptr.field_idx = field_idx;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_copy(spl_ir_builder_t *b, spl_type_id_t tid,
+                                          spl_ir_node_ref_t dst, spl_ir_node_ref_t src,
+                                          spl_ir_node_ref_t size) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_COPY);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_copy.tid = tid;
+    n->mem_copy.dst = dst;
+    n->mem_copy.src = src;
+    n->mem_copy.size = size;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_mem_set(spl_ir_builder_t *b, spl_type_id_t tid,
+                                         spl_ir_node_ref_t dst, spl_ir_node_ref_t val,
+                                         spl_ir_node_ref_t size) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_MEM_SET);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->mem_set.tid = tid;
+    n->mem_set.dst = dst;
+    n->mem_set.val = val;
+    n->mem_set.size = size;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_bool(spl_ir_builder_t *b, spl_type_id_t tid, bool val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.bool_lit = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_ptr(spl_ir_builder_t *b, spl_type_id_t tid, void *val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.ptr_lit = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_int(spl_ir_builder_t *b, spl_type_id_t tid, usize val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.int_lit = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_float(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  double val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.float_lit = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_bytes(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  const void *data, usize len) {
+    (void)len;
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.ptr_lit = (void *)data;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_char(spl_ir_builder_t *b, spl_type_id_t tid, char val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.ch_lit = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_const_fn(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_func_ref_t val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_CONST);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->type_const.tid = tid;
+    n->type_const.fn = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_bitsizeof(spl_ir_builder_t *b, spl_type_id_t tid) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_BITSIZEOF);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->bitsizeof.tid = tid;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_sizeof(spl_ir_builder_t *b, spl_type_id_t tid) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_SIZEOF);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->ir_sizeof.tid = tid;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_alignof(spl_ir_builder_t *b, spl_type_id_t tid) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_ALIGNOF);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->ir_alignof.tid = tid;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_offsetof(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_node_ref_t field_idx) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_OFFSETOF);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->ir_offsetof.tid = tid;
+    n->ir_offsetof.field_idx = field_idx;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_type_field_count(spl_ir_builder_t *b, spl_type_id_t tid) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_TYPE_FIELD_COUNT);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->field_count.tid = tid;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_agg_construct(spl_ir_builder_t *b, spl_type_id_t tid) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_AGG_CONSTRUCT);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->agg_construct.tid = tid;
+    vec_init(n->agg_construct.fields);
+    return ref;
+}
+
+void spl_ir_builder_agg_construct_field(spl_ir_builder_t *b, spl_ir_node_ref_t node,
+                                        spl_ir_node_ref_t field) {
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, node);
+    Assert(n != NULL);
+    vec_push(n->agg_construct.fields, field);
+}
+
+spl_ir_node_ref_t spl_ir_builder_agg_extract(spl_ir_builder_t *b, spl_type_id_t tid,
+                                             spl_type_id_t field_tid, usize field_idx,
+                                             spl_ir_node_ref_t val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_AGG_EXTRACT);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->agg_extract.tid = tid;
+    n->agg_extract.field_tid = field_tid;
+    n->agg_extract.field_idx = field_idx;
+    n->agg_extract.val = val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_agg_insert(spl_ir_builder_t *b, spl_type_id_t tid, usize field_idx,
+                                            spl_ir_node_ref_t agg, spl_ir_node_ref_t field) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_AGG_INSERT);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->agg_insert.tid = tid;
+    n->agg_insert.field_idx = field_idx;
+    n->agg_insert.agg = agg;
+    n->agg_insert.field = field;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_select(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                spl_ir_node_ref_t cond, spl_ir_node_ref_t true_val,
+                                                spl_ir_node_ref_t false_val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_SELECT);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_select.tid = tid;
+    n->control_select.cond = cond;
+    n->control_select.true_val = true_val;
+    n->control_select.false_val = false_val;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_br(spl_ir_builder_t *b, spl_ir_node_ref_t cond) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_BR);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_br.cond = cond;
+    n->control_br.true_label = 0;
+    n->control_br.false_label = 0;
+    b->terminated = true;
+    return ref;
+}
+
+void spl_ir_builder_control_br_fixup(spl_ir_builder_t *b, spl_ir_node_ref_t ref, usize true_block,
+                                     usize false_block) {
+    spl_ir_node_t *node = spl_ir_node(&b->ir, b->current_fn, ref);
+    if (!(node && node->kind == SPL_IR_CONTROL_BR)) {
+        Panic("fixup must be valid jmp ir node");
+    }
+    spl_ir_fix_t f1 = {.node = ref, .slot = SPL_IR_FIX_BR_TRUE, .block = true_block};
+    vec_push(b->fixups, f1);
+    spl_ir_fix_t f2 = {.node = ref, .slot = SPL_IR_FIX_BR_FALSE, .block = false_block};
+    vec_push(b->fixups, f2);
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_jmp(spl_ir_builder_t *b) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_JMP);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_jmp.label = 0;
+    b->terminated = true;
+    return ref;
+}
+
+void spl_ir_builder_control_jmp_fixup(spl_ir_builder_t *b, spl_ir_node_ref_t ref,
+                                      usize target_block) {
+    spl_ir_node_t *node = spl_ir_node(&b->ir, b->current_fn, ref);
+    if (!(node && node->kind == SPL_IR_CONTROL_JMP)) {
+        Panic("fixup must be valid jmp ir node");
+    }
+    spl_ir_fix_t fx = {.node = ref, .slot = SPL_IR_FIX_JMP, .block = target_block};
+    vec_push(b->fixups, fx);
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_call(spl_ir_builder_t *b, spl_type_id_t tid,
+                                              spl_ir_node_ref_t func) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_CALL);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_call.tid = tid;
+    n->control_call.func = func;
+    vec_init(n->control_call.params);
+    return ref;
+}
+
+void spl_ir_builder_control_call_param(spl_ir_builder_t *b, spl_ir_node_ref_t call_node,
+                                       spl_ir_node_ref_t arg) {
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, call_node);
+    Assert(n != NULL);
+    vec_push(n->control_call.params, arg);
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_param(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_node_ref_t idx) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_PARAM);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_param.tid = tid;
+    n->control_param.idx = idx;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_ret(spl_ir_builder_t *b, spl_type_id_t tid,
+                                             spl_ir_node_ref_t val) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_RET);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->control_ret.tid = tid;
+    n->control_ret.val = val;
+    b->terminated = true;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_unreachable(spl_ir_builder_t *b) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_UNREACHABLE);
+    b->terminated = true;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_control_trap(spl_ir_builder_t *b) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_CONTROL_TRAP);
+    b->terminated = true;
+    return ref;
+}
+
+spl_ir_node_ref_t spl_ir_builder_dbg_breakpoint(spl_ir_builder_t *b) {
+    return builder_alloc_node(b, SPL_IR_DBG_BREAKPOINT);
+}
+
+spl_ir_node_ref_t spl_ir_builder_dbg_panic(spl_ir_builder_t *b, const char *msg, usize len) {
+    spl_ir_node_ref_t ref = builder_alloc_node(b, SPL_IR_DBG_PANIC);
+    spl_ir_node_t *n = spl_ir_node(&b->ir, b->current_fn, ref);
+    n->dbg_panic.msg = msg;
+    n->dbg_panic.len = len;
+    return ref;
+}

stage1/spl_ir.h

@@ -0,0 +1,425 @@
+#ifndef __SPL_IR_H__
+#define __SPL_IR_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_dbg.h"
+#include "spl_type.h"
+
+#include "spl_attr.h"
+
+/* clang-format off */
+#define SPL_IR_FN_TABLE                                      \
+    X(arith.add,           V0, SPL_IR_ARITH_ADD)             \
+    X(arith.sub,           V0, SPL_IR_ARITH_SUB)             \
+    X(arith.mul,           V0, SPL_IR_ARITH_MUL)             \
+    X(arith.div,           V0, SPL_IR_ARITH_DIV)             \
+    X(arith.rem,           V0, SPL_IR_ARITH_REM)             \
+    X(arith.neg,           V0, SPL_IR_ARITH_NEG)             \
+    X(arith.abs,           V0, SPL_IR_ARITH_ABS)             \
+    X(arith.and,           V0, SPL_IR_ARITH_AND)             \
+    X(arith.or,            V0, SPL_IR_ARITH_OR)              \
+    X(arith.xor,           V0, SPL_IR_ARITH_XOR)             \
+    X(arith.shl,           V0, SPL_IR_ARITH_SHL)             \
+    X(arith.shr,           V0, SPL_IR_ARITH_SHR)             \
+    X(arith.not,           V0, SPL_IR_ARITH_NOT)             \
+    X(cmp.eq,              V0, SPL_IR_CMP_EQ)                \
+    X(cmp.ne,              V0, SPL_IR_CMP_NE)                \
+    X(cmp.lt,              V0, SPL_IR_CMP_LT)                \
+    X(cmp.le,              V0, SPL_IR_CMP_LE)                \
+    X(cmp.gt,              V0, SPL_IR_CMP_GT)                \
+    X(cmp.ge,              V0, SPL_IR_CMP_GE)                \
+    X(cast.trunc,          V0, SPL_IR_CAST_TRUNC)            \
+    X(cast.zext,           V0, SPL_IR_CAST_ZEXT)             \
+    X(cast.sext,           V0, SPL_IR_CAST_SEXT)             \
+    X(cast.fext,           V0, SPL_IR_CAST_FEXT)             \
+    X(cast.ftrunc,         V0, SPL_IR_CAST_FTRUNC)           \
+    X(cast.bitcast,        V0, SPL_IR_CAST_BITCAST)          \
+    X(cast.ptr2int,        V0, SPL_IR_CAST_PTR2INT)          \
+    X(cast.int2ptr,        V0, SPL_IR_CAST_INT2PTR)          \
+    X(cast.bool2int,       V0, SPL_IR_CAST_BOOL2INT)         \
+    X(case.int2float,      V0, SPL_IR_CASE_INT2FLOAT)        \
+    X(case.float2int,      V0, SPL_IR_CASE_FLOAT2INT)        \
+    X(mem.alloca,          V0, SPL_IR_MEM_ALLOCA)            \
+    X(mem.global_alloc,    V0, SPL_IR_MEM_GLOBAL_ALLOC)      \
+    X(mem.load,            V0, SPL_IR_MEM_LOAD)              \
+    X(mem.store,           V0, SPL_IR_MEM_STORE)             \
+    X(mem.offset,          V0, SPL_IR_MEM_OFFSET)            \
+    X(mem.field,           V0, SPL_IR_MEM_FIELD_PTR)         \
+    X(mem.copy,            V0, SPL_IR_MEM_COPY)              \
+    X(mem.set,             V0, SPL_IR_MEM_SET)               \
+    X(type.const,          V0, SPL_IR_TYPE_CONST)            \
+    X(type.bitsizeof,      V0, SPL_IR_TYPE_BITSIZEOF)        \
+    X(type.sizeof,         V0, SPL_IR_TYPE_SIZEOF)           \
+    X(type.alignof,        V0, SPL_IR_TYPE_ALIGNOF)          \
+    X(type.offsetof,       V0, SPL_IR_TYPE_OFFSETOF)         \
+    X(type.field_count,    V0, SPL_IR_TYPE_FIELD_COUNT)      \
+    X(agg.construct,       V0, SPL_IR_AGG_CONSTRUCT)         \
+    X(agg.extract,         V0, SPL_IR_AGG_EXTRACT)           \
+    X(agg.insert,          V0, SPL_IR_AGG_INSERT)            \
+    X(control.select,      V0, SPL_IR_CONTROL_SELECT)        \
+    X(control.br,          V0, SPL_IR_CONTROL_BR)            \
+    X(control.jmp,         V0, SPL_IR_CONTROL_JMP)           \
+    X(control.call,        V0, SPL_IR_CONTROL_CALL)          \
+    X(control.param,       V0, SPL_IR_CONTROL_PARAM)         \
+    X(control.ret,         V0, SPL_IR_CONTROL_RET)           \
+    X(control.unreachable, V0, SPL_IR_CONTROL_UNREACHABLE)   \
+    X(control.trap,        V0, SPL_IR_CONTROL_TRAP)          \
+    X(dbg.breakpoint,      V0, SPL_IR_DBG_BREAKPOINT)        \
+    X(dbg.panic,           V0, SPL_IR_DBG_PANIC)             \
+
+typedef enum {
+#ifdef X
+#undef X
+#endif
+#define X(a, b, c) c,
+    SPL_IR_FN_TABLE
+#undef X
+} spl_ir_kind_t;
+/* clang-format on */
+
+typedef usize spl_ir_node_ref_t; /* 0 is error */
+typedef VEC(spl_ir_node_ref_t) spl_ir_node_ref_vec_t;
+
+typedef usize spl_ir_func_ref_t; /* 0 is error */
+
+#define SPL_ENUM_TAG_FIELD_IDX 0
+
+typedef struct {
+    spl_ir_kind_t kind;
+    spl_dbg_node_t dbg;
+    spl_attr_id_vec_t attrs;
+    union {
+        spl_type_id_t tid;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t left;
+            spl_ir_node_ref_t right;
+        } arith;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t a;
+            spl_ir_node_ref_t b;
+        } cmp;
+        struct {
+            spl_type_id_t from_tid;
+            spl_type_id_t to_tid;
+            spl_ir_node_ref_t val;
+        } cast;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t count;
+        } mem_alloc;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t const_node;
+        } mem_global_alloc;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t ptr;
+        } mem_load;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t ptr;
+            spl_ir_node_ref_t val;
+        } mem_store;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t ptr;
+            spl_ir_node_ref_t offset;
+        } mem_offset;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t agg;
+            usize field_idx;
+        } mem_field_ptr;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t dst;
+            spl_ir_node_ref_t src;
+            spl_ir_node_ref_t size;
+        } mem_copy;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t dst;
+            spl_ir_node_ref_t val;
+            spl_ir_node_ref_t size;
+        } mem_set;
+        struct {
+            spl_type_id_t tid;
+            union {
+                bool bool_lit;
+                void *ptr_lit;
+                usize int_lit;
+                double float_lit;
+                // const char *cstr_lit;
+                char ch_lit;
+                spl_ir_func_ref_t fn;
+            };
+        } type_const;
+        struct {
+            spl_type_id_t tid;
+        } bitsizeof;
+        struct {
+            spl_type_id_t tid;
+        } ir_sizeof;
+        struct {
+            spl_type_id_t tid;
+        } ir_alignof;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t field_idx;
+        } ir_offsetof;
+        struct {
+            spl_type_id_t tid;
+        } field_count;
+
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_vec_t fields;
+        } agg_construct;
+        struct {
+            spl_type_id_t tid;
+            spl_type_id_t field_tid;
+            usize field_idx;
+            spl_ir_node_ref_t val;
+        } agg_extract;
+        struct {
+            spl_type_id_t tid;
+            usize field_idx;
+            spl_ir_node_ref_t agg;
+            spl_ir_node_ref_t field;
+        } agg_insert;
+
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t cond;
+            spl_ir_node_ref_t true_val;
+            spl_ir_node_ref_t false_val;
+        } control_select;
+        struct {
+            spl_ir_node_ref_t cond;
+            spl_ir_node_ref_t true_label;
+            spl_ir_node_ref_t false_label;
+        } control_br;
+        struct {
+            spl_ir_node_ref_t label;
+        } control_jmp;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t func;
+            spl_ir_node_ref_vec_t params;
+        } control_call;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t idx;
+        } control_param;
+        struct {
+            spl_type_id_t tid;
+            spl_ir_node_ref_t val;
+        } control_ret;
+
+        struct {
+            const char *msg;
+            usize len;
+        } dbg_panic;
+    };
+} spl_ir_node_t;
+typedef VEC(spl_ir_node_t) spl_ir_node_vec_t;
+
+typedef struct {
+    const char *name;
+    spl_attr_id_vec_t attrs;
+    spl_type_id_t fn_tid;
+    spl_ir_node_vec_t nodes;
+} spl_ir_func_t;
+typedef VEC(spl_ir_func_t) spl_ir_func_vec_t;
+
+typedef spl_ir_node_ref_t spl_ir_block_t;
+typedef VEC(spl_ir_block_t) spl_ir_block_vec_t;
+
+typedef struct {
+    spl_ir_node_ref_t node;
+    enum { SPL_IR_FIX_BR_TRUE, SPL_IR_FIX_BR_FALSE, SPL_IR_FIX_JMP } slot;
+    spl_ir_node_ref_t block;
+} spl_ir_fix_t;
+typedef VEC(spl_ir_fix_t) spl_ir_fix_vec_t;
+
+typedef struct {
+    spl_ir_func_vec_t funcs;
+} spl_ir_t;
+
+void spl_ir_init(spl_ir_t *ir);
+void spl_ir_drop(spl_ir_t *ir);
+
+spl_ir_node_ref_t spl_ir_alloc_node(spl_ir_t *ir, spl_ir_func_ref_t fn_id);
+spl_ir_func_ref_t spl_ir_alloc_fn(spl_ir_t *ir);
+
+spl_ir_node_t *spl_ir_node(spl_ir_t *ir, spl_ir_func_ref_t fn_id, spl_ir_node_ref_t node_id);
+spl_ir_func_t *spl_ir_func(spl_ir_t *ir, spl_ir_func_ref_t fn_id);
+
+void spl_ir_dump(spl_ir_t *ir, const spl_type_t *ty, const spl_attr_t *attr);
+const char *spl_ir_kind_name(spl_ir_kind_t kind);
+
+typedef struct {
+    spl_ir_t ir;
+    spl_dbg_node_t dbg;
+    spl_ir_func_ref_t current_fn;    /* 当前函数 */
+    spl_ir_node_ref_t current_block; /* 当前发射块（0 = 未设） */
+    spl_ir_block_vec_t blocks;       /* 当前函数的基本块表 */
+    spl_ir_fix_vec_t fixups;         /* 跳转回填表 */
+    bool terminated;                 /* 当前块已以 br/jmp/ret 终止 */
+} spl_ir_builder_t;
+
+/* clang-format off */
+#define SPL_IR_BIN_ARITH_TABLE                              \
+    X(arith_add,     SPL_IR_ARITH_ADD)                      \
+    X(arith_sub,     SPL_IR_ARITH_SUB)                      \
+    X(arith_mul,     SPL_IR_ARITH_MUL)                      \
+    X(arith_div,     SPL_IR_ARITH_DIV)                      \
+    X(arith_rem,     SPL_IR_ARITH_REM)                      \
+    X(arith_and,     SPL_IR_ARITH_AND)                      \
+    X(arith_or,      SPL_IR_ARITH_OR)                       \
+    X(arith_xor,     SPL_IR_ARITH_XOR)                      \
+    X(arith_shl,     SPL_IR_ARITH_SHL)                      \
+    X(arith_shr,     SPL_IR_ARITH_SHR)
+#define SPL_IR_UN_ARITH_TABLE                               \
+    X(arith_neg,     SPL_IR_ARITH_NEG)                      \
+    X(arith_abs,     SPL_IR_ARITH_ABS)                      \
+    X(arith_not,     SPL_IR_ARITH_NOT)
+#define SPL_IR_CMP_TABLE                                    \
+    X(cmp_eq,        SPL_IR_CMP_EQ)                         \
+    X(cmp_ne,        SPL_IR_CMP_NE)                         \
+    X(cmp_lt,        SPL_IR_CMP_LT)                         \
+    X(cmp_le,        SPL_IR_CMP_LE)                         \
+    X(cmp_gt,        SPL_IR_CMP_GT)                         \
+    X(cmp_ge,        SPL_IR_CMP_GE)
+#define SPL_IR_CAST_TABLE                                   \
+    X(cast_trunc,     SPL_IR_CAST_TRUNC)                    \
+    X(cast_zext,      SPL_IR_CAST_ZEXT)                     \
+    X(cast_sext,      SPL_IR_CAST_SEXT)                     \
+    X(cast_fext,      SPL_IR_CAST_FEXT)                     \
+    X(cast_ftrunc,    SPL_IR_CAST_FTRUNC)                   \
+    X(cast_bitcast,   SPL_IR_CAST_BITCAST)                  \
+    X(cast_ptr2int,   SPL_IR_CAST_PTR2INT)                  \
+    X(cast_int2ptr,   SPL_IR_CAST_INT2PTR)                  \
+    X(cast_bool2int,  SPL_IR_CAST_BOOL2INT)                 \
+    X(case_int2float, SPL_IR_CASE_INT2FLOAT)                \
+    X(case_float2int, SPL_IR_CASE_FLOAT2INT)
+/* clang-format on */
+void spl_ir_builder_init(spl_ir_builder_t *b);
+void spl_ir_builder_drop(spl_ir_builder_t *b);
+
+spl_ir_func_ref_t spl_ir_builder_fn_begin(spl_ir_builder_t *b, const char *name,
+                                          spl_type_id_t fn_tid);
+spl_ir_func_ref_t spl_ir_builder_fn_reserve(spl_ir_builder_t *b, const char *name,
+                                            spl_type_id_t fn_tid);
+void spl_ir_builder_fn_begin_at(spl_ir_builder_t *b, spl_ir_func_ref_t fid);
+void spl_ir_builder_fn_end(spl_ir_builder_t *b);
+
+usize spl_ir_builder_block_begin(spl_ir_builder_t *b);
+void spl_ir_builder_block_end(spl_ir_builder_t *b);
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *b, spl_type_id_t tid,                \
+                                            spl_ir_node_ref_t left, spl_ir_node_ref_t right);
+SPL_IR_BIN_ARITH_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *b, spl_type_id_t tid,                \
+                                            spl_ir_node_ref_t val);
+SPL_IR_UN_ARITH_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *builder, spl_type_id_t tid,          \
+                                            spl_ir_node_ref_t a, spl_ir_node_ref_t b);
+SPL_IR_CMP_TABLE
+#undef X
+
+#define X(name, kind)                                                                              \
+    spl_ir_node_ref_t spl_ir_builder_##name(spl_ir_builder_t *b, spl_type_id_t from_tid,           \
+                                            spl_type_id_t to_tid, spl_ir_node_ref_t val);
+SPL_IR_CAST_TABLE
+#undef X
+
+/* memory */
+
+spl_ir_node_ref_t spl_ir_builder_mem_alloca(spl_ir_builder_t *b, spl_type_id_t tid,
+                                            spl_ir_node_ref_t count);
+spl_ir_node_ref_t spl_ir_builder_mem_global_alloc(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  spl_ir_node_ref_t const_node);
+spl_ir_node_ref_t spl_ir_builder_mem_load(spl_ir_builder_t *b, spl_type_id_t tid,
+                                          spl_ir_node_ref_t ptr);
+spl_ir_node_ref_t spl_ir_builder_mem_store(spl_ir_builder_t *b, spl_type_id_t tid,
+                                           spl_ir_node_ref_t ptr, spl_ir_node_ref_t val);
+spl_ir_node_ref_t spl_ir_builder_mem_offset(spl_ir_builder_t *b, spl_type_id_t tid,
+                                            spl_ir_node_ref_t ptr, spl_ir_node_ref_t offset);
+spl_ir_node_ref_t spl_ir_builder_mem_field(spl_ir_builder_t *b, spl_type_id_t tid,
+                                           spl_ir_node_ref_t agg, usize field_idx);
+spl_ir_node_ref_t spl_ir_builder_mem_copy(spl_ir_builder_t *b, spl_type_id_t tid,
+                                          spl_ir_node_ref_t dst, spl_ir_node_ref_t src,
+                                          spl_ir_node_ref_t size);
+spl_ir_node_ref_t spl_ir_builder_mem_set(spl_ir_builder_t *b, spl_type_id_t tid,
+                                         spl_ir_node_ref_t dst, spl_ir_node_ref_t val,
+                                         spl_ir_node_ref_t size);
+
+/* type const */
+
+spl_ir_node_ref_t spl_ir_builder_type_const_ptr(spl_ir_builder_t *b, spl_type_id_t tid, void *val);
+spl_ir_node_ref_t spl_ir_builder_type_const_bool(spl_ir_builder_t *b, spl_type_id_t tid, bool val);
+spl_ir_node_ref_t spl_ir_builder_type_const_int(spl_ir_builder_t *b, spl_type_id_t tid, usize val);
+spl_ir_node_ref_t spl_ir_builder_type_const_float(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  double val);
+spl_ir_node_ref_t spl_ir_builder_type_const_bytes(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                  const void *data, usize len);
+spl_ir_node_ref_t spl_ir_builder_type_const_char(spl_ir_builder_t *b, spl_type_id_t tid, char val);
+spl_ir_node_ref_t spl_ir_builder_type_const_fn(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_func_ref_t val);
+
+/* type */
+
+spl_ir_node_ref_t spl_ir_builder_type_bitsizeof(spl_ir_builder_t *b, spl_type_id_t tid);
+spl_ir_node_ref_t spl_ir_builder_type_sizeof(spl_ir_builder_t *b, spl_type_id_t tid);
+spl_ir_node_ref_t spl_ir_builder_type_alignof(spl_ir_builder_t *b, spl_type_id_t tid);
+spl_ir_node_ref_t spl_ir_builder_type_offsetof(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_node_ref_t field_idx);
+spl_ir_node_ref_t spl_ir_builder_type_field_count(spl_ir_builder_t *b, spl_type_id_t tid);
+
+/* agg */
+
+spl_ir_node_ref_t spl_ir_builder_agg_construct(spl_ir_builder_t *b, spl_type_id_t tid);
+void spl_ir_builder_agg_construct_field(spl_ir_builder_t *b, spl_ir_node_ref_t node,
+                                        spl_ir_node_ref_t field);
+spl_ir_node_ref_t spl_ir_builder_agg_extract(spl_ir_builder_t *b, spl_type_id_t tid,
+                                             spl_type_id_t field_tid, usize field_idx,
+                                             spl_ir_node_ref_t val);
+spl_ir_node_ref_t spl_ir_builder_agg_insert(spl_ir_builder_t *b, spl_type_id_t tid, usize field_idx,
+                                            spl_ir_node_ref_t agg, spl_ir_node_ref_t field);
+
+/* control */
+
+spl_ir_node_ref_t spl_ir_builder_control_select(spl_ir_builder_t *b, spl_type_id_t tid,
+                                                spl_ir_node_ref_t cond, spl_ir_node_ref_t true_val,
+                                                spl_ir_node_ref_t false_val);
+spl_ir_node_ref_t spl_ir_builder_control_br(spl_ir_builder_t *b, spl_ir_node_ref_t cond);
+void spl_ir_builder_control_br_fixup(spl_ir_builder_t *b, spl_ir_node_ref_t ref, usize true_block,
+                                     usize false_block);
+spl_ir_node_ref_t spl_ir_builder_control_jmp(spl_ir_builder_t *b);
+void spl_ir_builder_control_jmp_fixup(spl_ir_builder_t *b, spl_ir_node_ref_t ref,
+                                      usize target_block);
+spl_ir_node_ref_t spl_ir_builder_control_call(spl_ir_builder_t *b, spl_type_id_t tid,
+                                              spl_ir_node_ref_t func);
+void spl_ir_builder_control_call_param(spl_ir_builder_t *b, spl_ir_node_ref_t call_node,
+                                       spl_ir_node_ref_t arg);
+spl_ir_node_ref_t spl_ir_builder_control_param(spl_ir_builder_t *b, spl_type_id_t tid,
+                                               spl_ir_node_ref_t idx);
+spl_ir_node_ref_t spl_ir_builder_control_ret(spl_ir_builder_t *b, spl_type_id_t tid,
+                                             spl_ir_node_ref_t val);
+spl_ir_node_ref_t spl_ir_builder_control_unreachable(spl_ir_builder_t *b);
+spl_ir_node_ref_t spl_ir_builder_control_trap(spl_ir_builder_t *b);
+
+spl_ir_node_ref_t spl_ir_builder_dbg_breakpoint(spl_ir_builder_t *b);
+spl_ir_node_ref_t spl_ir_builder_dbg_panic(spl_ir_builder_t *b, const char *msg, usize len);
+
+#endif /* __SPL_IR_H__ */

stage1/spl_ir2vm.h

@@ -0,0 +1,36 @@
+#ifndef __SPL_IR2VM_H__
+#define __SPL_IR2VM_H__
+
+#include "spl_diag.h"
+#include "spl_ir.h"
+#include "spl_type.h"
+
+#include "../stage0/spl_mcode.h"
+
+typedef struct {
+    spl_ir_func_ref_t fid;
+    VEC(usize) node_first_ip;
+} spl_ir2vm_fdbg_t;
+typedef VEC(spl_ir2vm_fdbg_t) spl_ir2vm_fdbg_vec_t;
+
+typedef MAP(spl_ir_func_ref_t, isize) spl_extern_idx_map_t;
+
+typedef struct {
+    const spl_ir_t *ir;
+    const spl_type_t *type;
+    const spl_attr_t *attr;
+    spl_extern_idx_map_t extern_native;
+    spl_prog_t prog;
+
+    spl_diag_t *diag;
+} spl_ir2vm_t;
+
+void spl_ir2vm_init(spl_ir2vm_t *ctx, const spl_ir_t *ir, const spl_type_t *type,
+                    const spl_attr_t *attr);
+void spl_ir2vm_drop(spl_ir2vm_t *ctx);
+
+int spl_ir2vm_run_func(spl_ir2vm_t *ctx, spl_ir_func_ref_t ref);
+int spl_ir2vm_run(spl_ir2vm_t *ctx);
+void spl_ir2vm_dump(spl_ir2vm_t *ctx);
+
+#endif /* __SPL_IR2VM_H__ */

stage1/spl_lang_type.c

@@ -0,0 +1,799 @@
+#include "spl_lang_type.h"
+
+static usize spl_lang_type_hash(spl_lang_type_node_t n) {
+    usize hash = (usize)n.kind * 131 + n.ir_type_id;
+    switch (n.kind) {
+    case SPL_LANG_TYPE_PTR:
+    case SPL_LANG_TYPE_SLICE:
+    case SPL_LANG_TYPE_RANGE:
+        hash += n.extra.elem;
+        break;
+    case SPL_LANG_TYPE_TUPLE:
+        for (usize i = 0; i < vec_size(n.extra.elems); i++) {
+            hash += vec_at(n.extra.elems, i);
+        }
+        break;
+    case SPL_LANG_TYPE_FN:
+        hash += n.extra.fn.ret;
+        for (usize i = 0; i < vec_size(n.extra.fn.params); i++) {
+            hash += vec_at(n.extra.fn.params, i);
+        }
+        break;
+    case SPL_LANG_TYPE_STRUCT:
+    case SPL_LANG_TYPE_UNION:
+    case SPL_LANG_TYPE_ENUM:
+    case SPL_LANG_TYPE_SHAPE:
+        for (usize i = 0; i < vec_size(n.methods); i++) {
+            spl_lang_method_t *m = &vec_at(n.methods, i);
+            hash += m->def_id * 31;
+            if (m->name) {
+                const char *s = m->name;
+                while (*s)
+                    hash = hash * 31 + (usize)(*s++);
+            }
+        }
+        break;
+    default:
+        break;
+    }
+    return hash;
+}
+
+static int spl_lang_type_eq(spl_lang_type_node_t n1, spl_lang_type_node_t n2) {
+    if (n1.kind != n2.kind || n1.ir_type_id != n2.ir_type_id)
+        return 1;
+    switch (n1.kind) {
+    case SPL_LANG_TYPE_PTR:
+    case SPL_LANG_TYPE_SLICE:
+    case SPL_LANG_TYPE_RANGE:
+        return n1.extra.elem != n2.extra.elem;
+    case SPL_LANG_TYPE_TUPLE:
+        if (vec_size(n1.extra.elems) != vec_size(n2.extra.elems))
+            return 1;
+        for (usize i = 0; i < vec_size(n1.extra.elems); i++) {
+            if (vec_at(n1.extra.elems, i) != vec_at(n2.extra.elems, i))
+                return 1;
+        }
+        return 0;
+    case SPL_LANG_TYPE_FN:
+        if (n1.extra.fn.ret != n2.extra.fn.ret)
+            return 1;
+        if (vec_size(n1.extra.fn.params) != vec_size(n2.extra.fn.params))
+            return 1;
+        for (usize i = 0; i < vec_size(n1.extra.fn.params); i++) {
+            if (vec_at(n1.extra.fn.params, i) != vec_at(n2.extra.fn.params, i))
+                return 1;
+        }
+        return 0;
+    case SPL_LANG_TYPE_STRUCT:
+    case SPL_LANG_TYPE_UNION:
+    case SPL_LANG_TYPE_ENUM:
+    case SPL_LANG_TYPE_SHAPE:
+        if (vec_size(n1.methods) != vec_size(n2.methods))
+            return 1;
+        for (usize i = 0; i < vec_size(n1.methods); i++) {
+            spl_lang_method_t *a = &vec_at(n1.methods, i);
+            spl_lang_method_t *b = &vec_at(n2.methods, i);
+            if (a->def_id != b->def_id)
+                return 1;
+            if ((a->name == NULL) != (b->name == NULL))
+                return 1;
+            if (a->name && strcmp(a->name, b->name) != 0)
+                return 1;
+        }
+        return 0;
+    default:
+        return 0;
+    }
+}
+
+static usize spl_lang_map_hash(usize k) { return MAP_HASH_INT(k); }
+static int spl_lang_map_cmp(usize a, usize b) { return MAP_CMP_INT(a, b); }
+
+static void spl_lang_node_free_extra(spl_lang_type_node_t *n) {
+    switch (n->kind) {
+    case SPL_LANG_TYPE_TUPLE:
+        vec_free(n->extra.elems);
+        break;
+    case SPL_LANG_TYPE_FN:
+        vec_free(n->extra.fn.params);
+        break;
+    case SPL_LANG_TYPE_STRUCT:
+    case SPL_LANG_TYPE_UNION:
+    case SPL_LANG_TYPE_ENUM:
+    case SPL_LANG_TYPE_SHAPE:
+        vec_free(n->methods);
+        break;
+    default:
+        break;
+    }
+}
+
+spl_lang_type_id_t spl_lang_node_push(spl_lang_type_t *type, spl_lang_type_node_t *node) {
+    usize hash = spl_lang_type_hash(*node);
+    usize idx = (usize)-1;
+    spl_lang_type_id_t cand = 0;
+    while (map_get_continue(type->lang_map, hash, &cand, &idx)) {
+        spl_lang_type_node_t *existing = &vec_at(type->lang_table, cand);
+        if (spl_lang_type_eq(*existing, *node) == 0) {
+            spl_lang_node_free_extra(node);
+            return cand;
+        }
+    }
+    spl_lang_type_id_t id = vec_size(type->lang_table);
+    vec_push(type->lang_table, *node);
+    map_put_new(type->lang_map, hash, id);
+    node->kind = SPL_LANG_TYPE_ERROR;
+    return id;
+}
+
+void spl_lang_type_init(spl_lang_type_t *type) {
+    spl_type_init(&type->ir);
+
+    vec_init(type->lang_table);
+    spl_lang_type_node_t lang_node = {0};
+    vec_push(type->lang_table, lang_node);
+    map_init(type->lang_map, spl_lang_map_hash, spl_lang_map_cmp);
+
+    vec_init(type->def_table);
+    vec_push(type->def_table, (spl_def_node_t){0});
+}
+
+void spl_lang_type_drop(spl_lang_type_t *type) {
+    for (usize i = 0; i < vec_size(type->lang_table); i++) {
+        spl_lang_type_node_t *n = &vec_at(type->lang_table, i);
+        spl_lang_node_free_extra(n);
+    }
+    map_free(type->lang_map);
+    vec_free(type->lang_table);
+
+    vec_free(type->def_table);
+
+    spl_type_drop(&type->ir);
+}
+
+spl_lang_type_node_t *spl_lang_type_node(const spl_lang_type_t *type, spl_lang_type_id_t id) {
+    if (!id || id >= vec_size(type->lang_table))
+        return NULL;
+    return &vec_at(type->lang_table, id);
+}
+
+spl_def_node_t *spl_def_node(const spl_lang_type_t *type, spl_def_id_t id) {
+    if (!id || id >= vec_size(type->def_table))
+        return NULL;
+    return &vec_at(type->def_table, id);
+}
+
+spl_type_id_t spl_lang_type_get_ir_type(spl_lang_type_t *type, spl_lang_type_id_t lang_id) {
+    spl_lang_type_node_t *n = spl_lang_type_node(type, lang_id);
+    return n ? n->ir_type_id : 0;
+}
+
+spl_type_id_t spl_lang_reserve_ir(spl_lang_type_t *type) {
+    spl_type_node_t empty = {0};
+    empty.kind = SPL_TYPE_ERROR;
+    empty.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    vec_push(type->ir.type_table, empty);
+    return vec_size(type->ir.type_table) - 1;
+}
+
+void spl_lang_define_ir(spl_lang_type_t *type, spl_type_id_t id, spl_type_node_t *node) {
+    if (!id || id >= vec_size(type->ir.type_table))
+        return;
+    spl_type_node_t *slot = &vec_at(type->ir.type_table, id);
+    /* slot 原是空 ERROR 节点，无 vec 字段可释放。node 的 vec 字段 move 进 slot。
+       占位 id 不写 type_map，不参与 hash-consing。 */
+    *slot = *node;
+    node->kind = SPL_TYPE_ERROR;
+}
+
+static spl_lang_type_id_t spl_lang_node_simple(spl_lang_type_t *type,
+                                               spl_lang_type_kind_t lang_kind,
+                                               spl_type_id_t ir_type_id) {
+    spl_lang_type_node_t node = {0};
+    node.kind = lang_kind;
+    node.ir_type_id = ir_type_id;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_error(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_ERROR);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_ERROR, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_infer(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_INFER);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_INFER, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_never(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_NEVER);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_NEVER, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_any(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_ANY);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_ANY, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_unit(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_UNIT);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_UNIT, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_bool(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_BOOL);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_BOOL, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_int(spl_lang_type_t *type, usize bits, int is_signed) {
+    spl_type_id_t ir = spl_type_builder_int(&type->ir, bits, is_signed);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_INT, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_float(spl_lang_type_t *type, usize bits) {
+    spl_type_id_t ir = spl_type_builder_float(&type->ir, bits);
+    return spl_lang_node_simple(type, SPL_LANG_TYPE_FLOAT, ir);
+}
+
+spl_lang_type_id_t spl_lang_make_array(spl_lang_type_t *type, spl_lang_type_id_t elem_lang,
+                                       usize len) {
+    spl_type_id_t elem_ir = spl_lang_type_get_ir_type(type, elem_lang);
+    if (!elem_ir)
+        return 0;
+    spl_type_id_t ir = spl_type_builder_array(&type->ir, elem_ir, len);
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_ARRAY;
+    node.ir_type_id = ir;
+    node.extra.elem = elem_lang;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_ptr(spl_lang_type_t *type, spl_lang_type_id_t pointee_lang) {
+    spl_type_id_t pointee_ir = spl_lang_type_get_ir_type(type, pointee_lang);
+    if (!pointee_ir)
+        return 0;
+    spl_type_id_t ir = spl_type_builder_ptr(&type->ir, pointee_ir);
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_PTR;
+    node.ir_type_id = ir;
+    node.extra.elem = pointee_lang;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_slice(spl_lang_type_t *type, spl_lang_type_id_t elem_lang) {
+    spl_type_id_t elem_ir = spl_lang_type_get_ir_type(type, elem_lang);
+    if (!elem_ir)
+        return 0;
+
+    spl_lang_type_id_t ptr_lang = spl_lang_make_ptr(type, elem_lang);
+    spl_lang_type_id_t usize_lang = spl_lang_make_int(type, sizeof(void *) * 8, 0);
+    spl_type_id_t ptr_ir = spl_lang_type_get_ir_type(type, ptr_lang);
+    spl_type_id_t usize_ir = spl_lang_type_get_ir_type(type, usize_lang);
+
+    spl_type_member_vec_t members;
+    vec_init(members);
+    spl_type_member_t m1 = {.name = "ptr", .type_id = ptr_ir};
+    spl_type_member_t m2 = {.name = "len", .type_id = usize_ir};
+    vec_push(members, m1);
+    vec_push(members, m2);
+
+    spl_type_layout_t layout = {.mode = SPL_TYPE_LAYOUT_AUTO, .fixed_align_bits = 0};
+    spl_type_id_t struct_ir = spl_type_builder_agg(&type->ir, SPL_TYPE_STRUCT, &members, 0, layout);
+
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_SLICE;
+    node.ir_type_id = struct_ir;
+    node.extra.elem = elem_lang;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_tuple(spl_lang_type_t *type, const spl_lang_type_id_t *elems,
+                                       usize count) {
+    spl_type_member_vec_t members;
+    vec_init(members);
+    for (usize i = 0; i < count; i++) {
+        spl_type_id_t elem_ir = spl_lang_type_get_ir_type(type, elems[i]);
+        if (!elem_ir) {
+            vec_free(members);
+            return 0;
+        }
+        char name[32];
+        snprintf(name, sizeof(name), "%zu", i);
+        spl_type_member_t m = {.name = strdup(name), .type_id = elem_ir};
+        vec_push(members, m);
+    }
+    spl_type_layout_t layout = {.mode = SPL_TYPE_LAYOUT_AUTO, .fixed_align_bits = 0};
+    spl_type_id_t struct_ir = spl_type_builder_agg(&type->ir, SPL_TYPE_STRUCT, &members, 0, layout);
+
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_TUPLE;
+    node.ir_type_id = struct_ir;
+    vec_init(node.extra.elems);
+    for (usize i = 0; i < count; i++) {
+        vec_push(node.extra.elems, elems[i]);
+    }
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_range(spl_lang_type_t *type, spl_lang_type_id_t elem_lang) {
+    spl_type_id_t elem_ir = spl_lang_type_get_ir_type(type, elem_lang);
+    if (!elem_ir)
+        return 0;
+
+    spl_type_member_vec_t members;
+    vec_init(members);
+    spl_type_member_t m1 = {.name = "start", .type_id = elem_ir};
+    spl_type_member_t m2 = {.name = "end", .type_id = elem_ir};
+    vec_push(members, m1);
+    vec_push(members, m2);
+
+    spl_type_layout_t layout = {.mode = SPL_TYPE_LAYOUT_AUTO, .fixed_align_bits = 0};
+    spl_type_id_t struct_ir = spl_type_builder_agg(&type->ir, SPL_TYPE_STRUCT, &members, 0, layout);
+
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_RANGE;
+    node.ir_type_id = struct_ir;
+    node.extra.elem = elem_lang;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_fn(spl_lang_type_t *type, spl_lang_type_id_t ret_lang,
+                                    const spl_lang_type_id_t *params_lang, usize nparams) {
+    spl_type_id_t ret_ir = spl_lang_type_get_ir_type(type, ret_lang);
+    if (!ret_ir)
+        return 0;
+    spl_type_id_vec_t param_irs;
+    vec_init(param_irs);
+    for (usize i = 0; i < nparams; i++) {
+        spl_type_id_t pir = spl_lang_type_get_ir_type(type, params_lang[i]);
+        if (!pir) {
+            vec_free(param_irs);
+            return 0;
+        }
+        vec_push(param_irs, pir);
+    }
+    spl_type_id_t fn_ir =
+        spl_type_builder_fn(&type->ir, ret_ir, param_irs.data, vec_size(param_irs));
+    vec_free(param_irs);
+
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_FN;
+    node.ir_type_id = fn_ir;
+    node.extra.fn.ret = ret_lang;
+    vec_init(node.extra.fn.params);
+    for (usize i = 0; i < nparams; i++) {
+        vec_push(node.extra.fn.params, params_lang[i]);
+    }
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_aggregate(spl_lang_type_t *type, spl_lang_type_kind_t kind,
+                                           const char *name, const spl_lang_type_id_t *members_lang,
+                                           usize nmembers) {
+    spl_type_node_kind_t tk;
+    switch (kind) {
+    case SPL_LANG_TYPE_STRUCT:
+        tk = SPL_TYPE_STRUCT;
+        break;
+    case SPL_LANG_TYPE_UNION:
+        tk = SPL_TYPE_UNION;
+        break;
+    case SPL_LANG_TYPE_ENUM:
+        tk = SPL_TYPE_ENUM;
+        break;
+    case SPL_LANG_TYPE_SHAPE:
+        tk = SPL_TYPE_SHAPE;
+        break;
+    default:
+        return 0;
+    }
+
+    spl_type_member_vec_t members;
+    vec_init(members);
+    for (usize i = 0; i < nmembers; i++) {
+        spl_type_id_t member_ir = spl_lang_type_get_ir_type(type, members_lang[i]);
+        if (!member_ir) {
+            vec_free(members);
+            return 0;
+        }
+        char field_name[32];
+        snprintf(field_name, sizeof(field_name), "%zu", i);
+        spl_type_member_t m = {.name = strdup(field_name), .type_id = member_ir};
+        vec_push(members, m);
+    }
+    spl_type_layout_t layout = {.mode = SPL_TYPE_LAYOUT_AUTO, .fixed_align_bits = 0};
+    spl_type_id_t agg_ir = spl_type_builder_agg(&type->ir, tk, &members, 0, layout);
+
+    spl_lang_type_node_t node = {0};
+    node.kind = kind;
+    node.ir_type_id = agg_ir;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_lang_make_varargs(spl_lang_type_t *type) {
+    spl_type_id_t ir = spl_type_builder_simple(&type->ir, SPL_TYPE_UNIT);
+    spl_lang_type_node_t node = {0};
+    node.kind = SPL_LANG_TYPE_VARARGS;
+    node.ir_type_id = ir;
+    return spl_lang_node_push(type, &node);
+}
+
+spl_lang_type_id_t spl_type_lookup_builtin(spl_lang_type_t *type, const char *name) {
+    if (!name || !*name)
+        return 0;
+    if (strcmp(name, "bool") == 0)
+        return spl_lang_make_bool(type);
+    if (strcmp(name, "void") == 0)
+        return spl_lang_make_unit(type);
+    if (strcmp(name, "isize") == 0)
+        return spl_lang_make_int(type, sizeof(void *) * 8, 1);
+    if (strcmp(name, "usize") == 0)
+        return spl_lang_make_int(type, sizeof(void *) * 8, 0);
+    if (strcmp(name, "any") == 0)
+        return spl_lang_make_any(type);
+    char prefix = name[0];
+    if (prefix == 'i' || prefix == 'u' || prefix == 'f') {
+        const char *rest = name + 1;
+        char *end;
+        long bits = strtol(rest, &end, 10);
+        if (end != rest && *end == '\0' && bits > 0) {
+            if (prefix == 'i')
+                return spl_lang_make_int(type, (usize)bits, 1);
+            if (prefix == 'u')
+                return spl_lang_make_int(type, (usize)bits, 0);
+            if (prefix == 'f')
+                return spl_lang_make_float(type, (usize)bits);
+        }
+    }
+    return 0;
+}
+
+bool spl_lang_type_is_subtype(const spl_lang_type_t *type, spl_lang_type_id_t sub,
+                              spl_lang_type_id_t super) {
+    if (sub == 0 || super == 0)
+        return false;
+    if (sub == super)
+        return true;
+
+    spl_lang_type_node_t *nsub = spl_lang_type_node(type, sub);
+    spl_lang_type_node_t *nsuper = spl_lang_type_node(type, super);
+    if (!nsub || !nsuper)
+        return false;
+
+    if (nsub->kind == SPL_LANG_TYPE_NEVER)
+        return true;
+    if (nsuper->kind == SPL_LANG_TYPE_ANY)
+        return true;
+
+    if (nsub->kind == SPL_LANG_TYPE_INT && nsuper->kind == SPL_LANG_TYPE_INT) {
+        spl_type_node_t *ir_sub = spl_type_node(&type->ir, nsub->ir_type_id);
+        if (!ir_sub)
+            return false;
+        return ir_sub->int_type.bits == 0;
+    }
+
+    if (nsub->kind == SPL_LANG_TYPE_FLOAT && nsuper->kind == SPL_LANG_TYPE_FLOAT) {
+        spl_type_node_t *ir_sub = spl_type_node(&type->ir, nsub->ir_type_id);
+        if (!ir_sub)
+            return false;
+        return ir_sub->float_type.bits == 0;
+    }
+
+    if (nsub->kind == SPL_LANG_TYPE_PTR && nsuper->kind == SPL_LANG_TYPE_PTR) {
+        if (nsub->extra.elem == nsuper->extra.elem)
+            return true;
+        spl_lang_type_node_t *sub_elem = spl_lang_type_node(type, nsub->extra.elem);
+        spl_lang_type_node_t *super_elem = spl_lang_type_node(type, nsuper->extra.elem);
+        if (sub_elem && sub_elem->kind == SPL_LANG_TYPE_NEVER)
+            return true;
+        if (super_elem && super_elem->kind == SPL_LANG_TYPE_ANY)
+            return true;
+        return false;
+    }
+
+    return false;
+}
+
+spl_lang_type_id_t spl_lang_type_join(const spl_lang_type_t *type, spl_lang_type_id_t a,
+                                      spl_lang_type_id_t b) {
+    if (a == 0 || b == 0)
+        return 0;
+    if (a == b)
+        return a;
+
+    spl_lang_type_node_t *na = spl_lang_type_node(type, a);
+    spl_lang_type_node_t *nb = spl_lang_type_node(type, b);
+    if (!na || !nb)
+        return 0;
+
+    if (na->kind == SPL_LANG_TYPE_NEVER)
+        return b;
+    if (nb->kind == SPL_LANG_TYPE_NEVER)
+        return a;
+    if (na->kind == SPL_LANG_TYPE_ANY || nb->kind == SPL_LANG_TYPE_ANY)
+        return spl_lang_make_any((spl_lang_type_t *)type);
+
+    bool a_int = na->kind == SPL_LANG_TYPE_INT;
+    bool b_int = nb->kind == SPL_LANG_TYPE_INT;
+    bool a_flt = na->kind == SPL_LANG_TYPE_FLOAT;
+    bool b_flt = nb->kind == SPL_LANG_TYPE_FLOAT;
+
+    if (a_int && b_int) {
+        spl_type_node_t *ira = spl_type_node(&type->ir, na->ir_type_id);
+        spl_type_node_t *irb = spl_type_node(&type->ir, nb->ir_type_id);
+        if (!ira || !irb)
+            return 0;
+        bool a_ct = ira->int_type.bits == 0;
+        bool b_ct = irb->int_type.bits == 0;
+        if (a_ct && b_ct)
+            return a;
+        if (a_ct)
+            return b;
+        if (b_ct)
+            return a;
+        return 0;
+    }
+
+    if (a_flt && b_flt) {
+        spl_type_node_t *ira = spl_type_node(&type->ir, na->ir_type_id);
+        spl_type_node_t *irb = spl_type_node(&type->ir, nb->ir_type_id);
+        if (!ira || !irb)
+            return 0;
+        bool a_ct = ira->float_type.bits == 0;
+        bool b_ct = irb->float_type.bits == 0;
+        if (a_ct && b_ct)
+            return a;
+        if (a_ct)
+            return b;
+        if (b_ct)
+            return a;
+        return 0;
+    }
+
+    if (a_int && b_flt) {
+        spl_type_node_t *ira = spl_type_node(&type->ir, na->ir_type_id);
+        spl_type_node_t *irb = spl_type_node(&type->ir, nb->ir_type_id);
+        if (ira && irb && ira->int_type.bits == 0 && irb->float_type.bits == 0)
+            return spl_lang_make_float((spl_lang_type_t *)type, 0);
+        return 0;
+    }
+    if (a_flt && b_int) {
+        spl_type_node_t *ira = spl_type_node(&type->ir, na->ir_type_id);
+        spl_type_node_t *irb = spl_type_node(&type->ir, nb->ir_type_id);
+        if (ira && irb && ira->float_type.bits == 0 && irb->int_type.bits == 0)
+            return spl_lang_make_float((spl_lang_type_t *)type, 0);
+        return 0;
+    }
+
+    if (na->kind == SPL_LANG_TYPE_PTR && nb->kind == SPL_LANG_TYPE_PTR) {
+        if (na->extra.elem == nb->extra.elem)
+            return a;
+
+        spl_lang_type_node_t *ea = spl_lang_type_node(type, na->extra.elem);
+        spl_lang_type_node_t *eb = spl_lang_type_node(type, nb->extra.elem);
+
+        if (ea && ea->kind == SPL_LANG_TYPE_NEVER)
+            return b;
+        if (eb && eb->kind == SPL_LANG_TYPE_NEVER)
+            return a;
+        if (ea && ea->kind == SPL_LANG_TYPE_ANY)
+            return a;
+        if (eb && eb->kind == SPL_LANG_TYPE_ANY)
+            return b;
+
+        return 0;
+    }
+
+    return 0;
+}
+
+bool spl_lang_mpa_int_fits(const spl_lang_type_t *type, spl_lang_type_id_t target,
+                           spl_mpa_int_t v) {
+    spl_lang_type_node_t *nt = spl_lang_type_node(type, target);
+    if (!nt || nt->kind != SPL_LANG_TYPE_INT)
+        return false;
+    spl_type_node_t *ir = spl_type_node(&type->ir, nt->ir_type_id);
+    if (!ir)
+        return false;
+    uint32_t bits = (uint32_t)ir->int_type.bits;
+    if (bits == 0)
+        return true;
+    bool target_signed = ir->int_type.is_signed != 0;
+    uint64_t uval = v.bits;
+
+    if (target_signed) {
+        if (bits >= 64)
+            return true;
+        uint64_t hi = ((uint64_t)1 << (bits - 1)) - 1;
+        return uval <= hi;
+    }
+    if (bits >= 64)
+        return true;
+    uint64_t hi = ((uint64_t)1 << bits) - 1;
+    return uval <= hi;
+}
+
+spl_def_id_t spl_def_alloc(spl_lang_type_t *type, spl_def_node_kind_t kind, const char *name,
+                           spl_dbg_node_t dbg, struct spl_ast *owner_ast, usize ast_node_ref) {
+    spl_def_node_t n = {0};
+    n.kind = kind;
+    n.name = name;
+    n.dbg_node = dbg;
+    n.lang_id = 0;
+    n.owner_ast = owner_ast;
+    n.ast_node_ref = ast_node_ref;
+    n.state = SPL_DECL_UNRESOLVED;
+    n.owner_def = 0;
+    vec_push(type->def_table, n);
+    return vec_size(type->def_table) - 1;
+}
+
+void spl_def_resolve(spl_lang_type_t *type, spl_def_id_t id, spl_lang_type_id_t lang_id) {
+    spl_def_node_t *d = spl_def_node(type, id);
+    if (d)
+        d->lang_id = lang_id;
+}
+
+spl_lang_type_id_t spl_def_get_lang_id(spl_lang_type_t *type, spl_def_id_t def_id) {
+    spl_def_node_t *d = spl_def_node(type, def_id);
+    return d ? d->lang_id : 0;
+}
+
+spl_type_id_t spl_def_get_type_id(spl_lang_type_t *type, spl_def_id_t def_id) {
+    spl_lang_type_id_t lang = spl_def_get_lang_id(type, def_id);
+    return lang ? spl_lang_type_get_ir_type(type, lang) : 0;
+}
+
+static void spl_lang_type_dump_rec(spl_lang_type_t *type, spl_lang_type_id_t id,
+                                   spl_lang_type_id_vec_t *stack) {
+    for (usize i = 0; i < vec_size(*stack); i++) {
+        if (vec_at(*stack, i) == id) {
+            printf("<rec#%zu>", id);
+            return;
+        }
+    }
+    if (vec_size(*stack) > 32) {
+        printf("...");
+        return;
+    }
+    vec_push(*stack, id);
+
+    spl_lang_type_node_t *n = spl_lang_type_node(type, id);
+    if (!n) {
+        printf("none");
+        vec_pop(*stack);
+        return;
+    }
+    switch (n->kind) {
+    case SPL_LANG_TYPE_ERROR:
+        printf("error");
+        break;
+    case SPL_LANG_TYPE_INFER:
+        printf("infer");
+        break;
+    case SPL_LANG_TYPE_NEVER:
+        printf("never");
+        break;
+    case SPL_LANG_TYPE_ANY:
+        printf("any");
+        break;
+    case SPL_LANG_TYPE_UNIT:
+        printf("unit");
+        break;
+    case SPL_LANG_TYPE_BOOL:
+        printf("bool");
+        break;
+    case SPL_LANG_TYPE_VARARGS:
+        printf("...");
+        break;
+    case SPL_LANG_TYPE_INT: {
+        spl_type_node_t *tn = spl_type_node(&type->ir, n->ir_type_id);
+        if (tn && tn->int_type.bits == 0)
+            printf("comptime_int");
+        else
+            spl_type_pure_dump(&type->ir, n->ir_type_id);
+        break;
+    }
+    case SPL_LANG_TYPE_FLOAT: {
+        spl_type_node_t *tn = spl_type_node(&type->ir, n->ir_type_id);
+        if (tn && tn->float_type.bits == 0)
+            printf("comptime_float");
+        else
+            spl_type_pure_dump(&type->ir, n->ir_type_id);
+        break;
+    }
+    case SPL_LANG_TYPE_PTR:
+        printf("*");
+        spl_lang_type_dump_rec(type, n->extra.elem, stack);
+        break;
+    case SPL_LANG_TYPE_ARRAY: {
+        spl_type_node_t *tn = spl_type_node(&type->ir, n->ir_type_id);
+        printf("[%zu]", tn->array_type.len);
+        spl_type_pure_dump(&type->ir, n->ir_type_id);
+    } break;
+    case SPL_LANG_TYPE_SLICE:
+        printf("[]");
+        spl_lang_type_dump_rec(type, n->extra.elem, stack);
+        break;
+    case SPL_LANG_TYPE_TUPLE:
+        printf("(");
+        for (usize i = 0; i < vec_size(n->extra.elems); i++) {
+            if (i)
+                printf(",");
+            spl_lang_type_dump_rec(type, vec_at(n->extra.elems, i), stack);
+        }
+        printf(")");
+        break;
+    case SPL_LANG_TYPE_RANGE:
+        spl_lang_type_dump_rec(type, n->extra.elem, stack);
+        printf("..");
+        spl_lang_type_dump_rec(type, n->extra.elem, stack);
+        break;
+    case SPL_LANG_TYPE_FN:
+        printf("fn(");
+        for (usize i = 0; i < vec_size(n->extra.fn.params); i++) {
+            if (i)
+                printf(",");
+            spl_lang_type_dump_rec(type, vec_at(n->extra.fn.params, i), stack);
+        }
+        printf(")");
+        spl_lang_type_dump_rec(type, n->extra.fn.ret, stack);
+        break;
+    case SPL_LANG_TYPE_STRUCT:
+    case SPL_LANG_TYPE_UNION:
+    case SPL_LANG_TYPE_ENUM:
+    case SPL_LANG_TYPE_SHAPE:
+        spl_type_pure_dump(&type->ir, n->ir_type_id);
+        break;
+    }
+
+    vec_pop(*stack);
+}
+
+void spl_lang_type_dump(spl_lang_type_t *type, spl_lang_type_id_t id) {
+    spl_lang_type_id_vec_t stack;
+    vec_init(stack);
+    spl_lang_type_dump_rec(type, id, &stack);
+    vec_free(stack);
+}
+
+void spl_type_def_dump(spl_lang_type_t *type, spl_def_id_t id) {
+    spl_def_node_t *node = spl_def_node(type, id);
+    if (!node) {
+        printf("none");
+        return;
+    }
+    const char *def_kind_name = "unknown";
+    switch (node->kind) {
+    case SPL_DEF_ERROR:
+        def_kind_name = "error";
+        break;
+    case SPL_DEF_SCALAR:
+        def_kind_name = "scalar";
+        break;
+    case SPL_DEF_MEMBER:
+        def_kind_name = "member";
+        break;
+    case SPL_DEF_VAR:
+        def_kind_name = "var";
+        break;
+    case SPL_DEF_FN:
+        def_kind_name = "fn";
+        break;
+    case SPL_DEF_AGG:
+        def_kind_name = "agg";
+        break;
+    case SPL_DEF_BUILTIN:
+        def_kind_name = "builtin";
+        break;
+    case SPL_DEF_DISTINCT:
+        def_kind_name = "distinct";
+        break;
+    case SPL_DEF_ALIAS:
+        def_kind_name = "alias";
+        break;
+    }
+    printf("kind=%s lang_id=%zu name=%s", def_kind_name, node->lang_id,
+           node->name ? node->name : "?");
+}

stage1/spl_lang_type.h

@@ -0,0 +1,153 @@
+#ifndef __SPL_LANG_TYPE_H__
+#define __SPL_LANG_TYPE_H__
+
+#include "../stage0/include/utils.h"
+#include "spl_dbg.h"
+#include "spl_mpa.h"
+#include "spl_type.h"
+
+typedef usize spl_lang_type_id_t;
+typedef VEC(spl_lang_type_id_t) spl_lang_type_id_vec_t;
+typedef usize spl_def_id_t;
+typedef VEC(spl_def_id_t) spl_def_id_vec_t;
+
+typedef enum {
+    SPL_LANG_TYPE_ERROR,
+    SPL_LANG_TYPE_INFER,
+    SPL_LANG_TYPE_NEVER,
+    SPL_LANG_TYPE_ANY,
+    SPL_LANG_TYPE_UNIT,
+    SPL_LANG_TYPE_BOOL,
+    SPL_LANG_TYPE_INT,
+    SPL_LANG_TYPE_FLOAT,
+    SPL_LANG_TYPE_PTR,
+    SPL_LANG_TYPE_ARRAY,
+    SPL_LANG_TYPE_SLICE,
+    SPL_LANG_TYPE_TUPLE,
+    SPL_LANG_TYPE_RANGE,
+    SPL_LANG_TYPE_FN,
+    SPL_LANG_TYPE_STRUCT,
+    SPL_LANG_TYPE_UNION,
+    SPL_LANG_TYPE_ENUM,
+    SPL_LANG_TYPE_SHAPE,
+    SPL_LANG_TYPE_VARARGS,
+} spl_lang_type_kind_t;
+
+typedef struct {
+    const char *name;
+    spl_def_id_t def_id;
+} spl_lang_method_t;
+typedef VEC(spl_lang_method_t) spl_lang_method_vec_t;
+
+typedef struct {
+    spl_lang_type_kind_t kind;
+    spl_type_id_t ir_type_id;
+    spl_lang_method_vec_t methods;
+    union {
+        spl_lang_type_id_t elem;
+        spl_lang_type_id_vec_t elems;
+        struct {
+            spl_lang_type_id_vec_t params;
+            spl_lang_type_id_t ret;
+        } fn;
+    } extra;
+} spl_lang_type_node_t;
+typedef VEC(spl_lang_type_node_t) spl_lang_type_vec_t;
+typedef MAP(usize, spl_lang_type_id_t) spl_lang_type_map_t;
+
+typedef enum {
+    SPL_DEF_ERROR,
+    SPL_DEF_SCALAR,
+    SPL_DEF_MEMBER,
+    SPL_DEF_VAR,
+    SPL_DEF_FN,
+    SPL_DEF_AGG,
+    SPL_DEF_DISTINCT,
+    SPL_DEF_ALIAS,
+    SPL_DEF_BUILTIN,
+} spl_def_node_kind_t;
+
+typedef enum {
+    SPL_DECL_UNRESOLVED,
+    SPL_DECL_RESOLVING,
+    SPL_DECL_RESOLVED,
+    SPL_DECL_ERROR,
+} spl_decl_state_t;
+
+struct spl_ast;
+
+typedef struct {
+    spl_def_node_kind_t kind;
+    const char *name;
+    spl_dbg_node_t dbg_node;
+    spl_lang_type_id_t lang_id;
+    struct spl_ast *owner_ast;
+    usize ast_node_ref;
+    spl_decl_state_t state;
+    spl_def_id_t owner_def;
+} spl_def_node_t;
+typedef VEC(spl_def_node_t) spl_def_node_vec_t;
+
+typedef struct {
+    spl_type_t ir;
+    spl_lang_type_vec_t lang_table;
+    spl_lang_type_map_t lang_map;
+    spl_def_node_vec_t def_table;
+} spl_lang_type_t;
+
+void spl_lang_type_init(spl_lang_type_t *type);
+void spl_lang_type_drop(spl_lang_type_t *type);
+
+spl_lang_type_node_t *spl_lang_type_node(const spl_lang_type_t *type, spl_lang_type_id_t id);
+spl_lang_type_id_t spl_lang_node_push(spl_lang_type_t *type, spl_lang_type_node_t *node);
+
+spl_type_id_t spl_lang_type_get_ir_type(spl_lang_type_t *type, spl_lang_type_id_t lang_id);
+
+/* 前向引用支持：reserve 一个 type_table 空槽位（kind=ERROR）作为身份锚点，
+   让 *Node / []Node 这类成员能拿到稳定 pointee；成员解析完后再调 define
+   把真实内容填进去。占位槽位**不写 type_map**，不参与 hash-consing——
+   后续相同形状的类型走 spl_type_node_push 会生成独立 id，语义等价。 */
+spl_type_id_t spl_lang_reserve_ir(spl_lang_type_t *type);
+void spl_lang_define_ir(spl_lang_type_t *type, spl_type_id_t id, spl_type_node_t *node);
+
+spl_lang_type_id_t spl_lang_make_error(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_infer(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_never(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_any(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_unit(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_bool(spl_lang_type_t *type);
+spl_lang_type_id_t spl_lang_make_int(spl_lang_type_t *type, usize bits, int is_signed);
+spl_lang_type_id_t spl_lang_make_float(spl_lang_type_t *type, usize bits);
+spl_lang_type_id_t spl_lang_make_ptr(spl_lang_type_t *type, spl_lang_type_id_t pointee);
+spl_lang_type_id_t spl_lang_make_array(spl_lang_type_t *type, spl_lang_type_id_t elem, usize len);
+spl_lang_type_id_t spl_lang_make_slice(spl_lang_type_t *type, spl_lang_type_id_t elem);
+spl_lang_type_id_t spl_lang_make_tuple(spl_lang_type_t *type, const spl_lang_type_id_t *elems,
+                                       usize count);
+spl_lang_type_id_t spl_lang_make_range(spl_lang_type_t *type, spl_lang_type_id_t elem);
+spl_lang_type_id_t spl_lang_make_fn(spl_lang_type_t *type, spl_lang_type_id_t ret,
+                                    const spl_lang_type_id_t *params, usize nparams);
+spl_lang_type_id_t spl_lang_make_aggregate(spl_lang_type_t *type, spl_lang_type_kind_t kind,
+                                           const char *name, const spl_lang_type_id_t *members,
+                                           usize nmembers);
+spl_lang_type_id_t spl_lang_make_varargs(spl_lang_type_t *type);
+
+spl_lang_type_id_t spl_type_lookup_builtin(spl_lang_type_t *type, const char *name);
+
+bool spl_lang_type_is_subtype(const spl_lang_type_t *type, spl_lang_type_id_t sub,
+                              spl_lang_type_id_t super);
+spl_lang_type_id_t spl_lang_type_join(const spl_lang_type_t *type, spl_lang_type_id_t a,
+                                      spl_lang_type_id_t b);
+
+bool spl_lang_mpa_int_fits(const spl_lang_type_t *type, spl_lang_type_id_t target, spl_mpa_int_t v);
+
+spl_def_id_t spl_def_alloc(spl_lang_type_t *type, spl_def_node_kind_t kind, const char *name,
+                           spl_dbg_node_t dbg, struct spl_ast *owner_ast, usize ast_node_ref);
+void spl_def_resolve(spl_lang_type_t *type, spl_def_id_t id, spl_lang_type_id_t lang_id);
+spl_def_node_t *spl_def_node(const spl_lang_type_t *type, spl_def_id_t id);
+spl_lang_type_id_t spl_def_get_lang_id(spl_lang_type_t *type, spl_def_id_t def_id);
+spl_type_id_t spl_def_get_type_id(spl_lang_type_t *type, spl_def_id_t def_id);
+
+void spl_lang_type_dump(spl_lang_type_t *type, spl_lang_type_id_t id);
+void spl_type_def_dump(spl_lang_type_t *type, spl_def_id_t id);
+
+#endif /* __SPL_LANG_TYPE_H__ */

stage1/spl_layout.c

@@ -0,0 +1,298 @@
+#include "spl_layout.h"
+
+static void infos_grow(spl_layout_t *layout, usize n) {
+    while (vec_size(layout->infos) < n) {
+        spl_layout_info_t info = {0};
+        vec_init(info.field_bit_offsets);
+        vec_init(info.field_bit_sizes);
+        vec_push(layout->infos, info);
+    }
+}
+
+static spl_layout_info_t *infos_at(spl_layout_t *layout, spl_type_id_t id) {
+    if (id == 0 || id >= vec_size(layout->infos))
+        return NULL;
+    return &vec_at(layout->infos, id);
+}
+
+void spl_layout_add_scalar(spl_layout_t *layout, usize size, usize abi_align) {
+    spl_layout_scalar_t s = {0};
+    s.size = size;
+    s.abi_align = abi_align;
+    s.pref_align = abi_align;
+    vec_init(s.invalid_values);
+    vec_push(layout->scalars, s);
+}
+
+void spl_layout_add_ptr(spl_layout_t *layout, usize addr_space, usize size, usize align) {
+    spl_layout_ptr_t p = {0};
+    p.add_space = addr_space;
+    p.ptr_size = size;
+    p.ptr_align = align;
+    vec_push(layout->pointers, p);
+}
+
+void spl_layout_init(spl_layout_t *layout, spl_layout_target_t *target) {
+    vec_init(layout->scalars);
+    vec_init(layout->pointers);
+    vec_init(layout->infos);
+    layout->target = target;
+
+    /* 默认聚合策略：按最大字段对齐，不允许重排 */
+    layout->aggregate.allow_field_reordering = false;
+    layout->aggregate.align_rule = ALIGN_MAX;
+    layout->aggregate.fixed_align = 0;
+
+    /* 常见 64 位平台的默认布局。
+       若目标平台不适用，调用者 clear 后自行 add_*。 */
+    spl_layout_add_scalar(layout, 1, 1); /* i8 / u8 / bool */
+    spl_layout_add_scalar(layout, 2, 2); /* i16 / u16 */
+    spl_layout_add_scalar(layout, 4, 4); /* i32 / u32 / f32 */
+    spl_layout_add_scalar(layout, 8, 8); /* i64 / u64 / f64 */
+
+    usize ps = sizeof(void *);
+    spl_layout_add_ptr(layout, 0, ps, ps);
+}
+
+void spl_layout_drop(spl_layout_t *layout) {
+    for (usize i = 0; i < vec_size(layout->scalars); ++i)
+        vec_free(vec_at(layout->scalars, i).invalid_values);
+    vec_free(layout->scalars);
+
+    vec_free(layout->pointers);
+
+    for (usize i = 0; i < vec_size(layout->infos); ++i) {
+        vec_free(vec_at(layout->infos, i).field_bit_offsets);
+        vec_free(vec_at(layout->infos, i).field_bit_sizes);
+    }
+    vec_free(layout->infos);
+}
+
+static const spl_layout_scalar_t *scalar_for_size(spl_layout_t *layout, usize size_bytes) {
+    for (usize i = 0; i < vec_size(layout->scalars); ++i) {
+        spl_layout_scalar_t *s = &vec_at(layout->scalars, i);
+        if (s->size == size_bytes)
+            return s;
+    }
+    return NULL;
+}
+
+static const spl_layout_ptr_t *default_ptr(spl_layout_t *layout) {
+    if (vec_size(layout->pointers) == 0)
+        return NULL;
+    return &vec_at(layout->pointers, 0);
+}
+
+static bool layout_scalar(spl_layout_t *layout, spl_type_node_t *tn, spl_layout_info_t *out) {
+    usize size_bits = 0;
+    switch (tn->kind) {
+    case SPL_TYPE_INT:
+        if (tn->int_type.bits == 0)
+            return false; /* comptime_int 未落地 */
+        size_bits = tn->int_type.bits;
+        break;
+    case SPL_TYPE_FLOAT:
+        if (tn->float_type.bits == 0)
+            return false; /* comptime_float 未落地 */
+        size_bits = tn->float_type.bits;
+        break;
+    case SPL_TYPE_BOOL:
+        size_bits = 8;
+        break;
+    default:
+        return false;
+    }
+    usize size_bytes = (size_bits + 7) / 8;
+    const spl_layout_scalar_t *sl = scalar_for_size(layout, size_bytes);
+    if (!sl)
+        return false;
+
+    out->size_bits = sl->size * 8;
+    out->align_bits = sl->abi_align * 8;
+    return true;
+}
+
+static bool layout_ptr(spl_layout_t *layout, spl_layout_info_t *out) {
+    const spl_layout_ptr_t *pl = default_ptr(layout);
+    if (!pl)
+        return false;
+    out->size_bits = pl->ptr_size * 8;
+    out->align_bits = pl->ptr_align * 8;
+    return true;
+}
+
+static usize round_up_bits(usize x, usize align_bits) {
+    if (align_bits <= 1)
+        return x;
+    usize a = align_bits;
+    return (x + a - 1) / a * a;
+}
+
+static bool layout_agg(spl_layout_t *layout, spl_type_node_t *tn, spl_layout_info_t *out) {
+    usize n = vec_size(tn->agg_type.variants);
+
+    if (tn->kind == SPL_TYPE_ENUM) {
+        spl_type_id_t tag_tid = tn->agg_type.tag_type;
+        if (!tag_tid)
+            return false;
+        spl_layout_info_t *tag_info = infos_at(layout, tag_tid);
+        if (!tag_info || !tag_info->resolved)
+            return false;
+
+        usize tag_align_bits = tag_info->align_bits ? tag_info->align_bits : 8;
+        usize payload_align_bits = 8;
+        usize payload_size_bits = 0;
+
+        for (usize i = 0; i < n; ++i) {
+            spl_type_member_t *m = &vec_at(tn->agg_type.variants, i);
+            spl_layout_info_t *fi = infos_at(layout, m->type_id);
+            if (!fi || !fi->resolved)
+                return false;
+            usize fa = fi->align_bits ? fi->align_bits : 8;
+            if (fa > payload_align_bits)
+                payload_align_bits = fa;
+            if (fi->size_bits > payload_size_bits)
+                payload_size_bits = fi->size_bits;
+        }
+
+        usize payload_off = round_up_bits(tag_info->size_bits, payload_align_bits);
+        usize final_align_bits =
+            tag_align_bits > payload_align_bits ? tag_align_bits : payload_align_bits;
+        out->size_bits = round_up_bits(payload_off + payload_size_bits, final_align_bits);
+        out->align_bits = final_align_bits;
+        return true;
+    }
+
+    if (n == 0) {
+        out->size_bits = 0;
+        out->align_bits = 8;
+        return true;
+    }
+
+    usize max_align_bits = 8;
+    usize offset_bits = 0;
+    bool is_union = (tn->kind == SPL_TYPE_UNION);
+
+    for (usize i = 0; i < n; ++i) {
+        spl_type_member_t *m = &vec_at(tn->agg_type.variants, i);
+        spl_layout_info_t *fi = infos_at(layout, m->type_id);
+        if (!fi || !fi->resolved)
+            return false;
+
+        usize field_align_bits = fi->align_bits ? fi->align_bits : 8;
+
+        if (is_union) {
+            vec_push(out->field_bit_offsets, 0);
+            vec_push(out->field_bit_sizes, fi->size_bits);
+            if (fi->size_bits > out->size_bits)
+                out->size_bits = fi->size_bits;
+        } else {
+            offset_bits = round_up_bits(offset_bits, field_align_bits);
+            vec_push(out->field_bit_offsets, offset_bits);
+            vec_push(out->field_bit_sizes, fi->size_bits);
+            offset_bits += fi->size_bits;
+        }
+        if (field_align_bits > max_align_bits)
+            max_align_bits = field_align_bits;
+    }
+
+    usize final_align_bits = max_align_bits;
+    if (layout->aggregate.align_rule == ALIGN_FIXED) {
+        final_align_bits = layout->aggregate.fixed_align * 8;
+    } else if (layout->aggregate.align_rule == ALIGN_MAX_WITH_MIN) {
+        usize min_bits = layout->aggregate.fixed_align * 8;
+        if (final_align_bits < min_bits)
+            final_align_bits = min_bits;
+    }
+
+    if (is_union)
+        out->size_bits = round_up_bits(out->size_bits, final_align_bits);
+    else
+        out->size_bits = round_up_bits(offset_bits, final_align_bits);
+    out->align_bits = final_align_bits;
+    return true;
+}
+
+static void resolve_type(spl_layout_t *layout, spl_type_t *type, spl_type_id_t id) {
+    spl_layout_info_t *info = infos_at(layout, id);
+    if (!info || info->resolved)
+        return;
+
+    spl_type_node_t *tn = spl_type_node(type, id);
+    if (!tn)
+        return;
+
+    /* 先标记已解析：自引用类型（通过 ptr）不会无限递归，
+       但保持防御性写法。 */
+    info->resolved = true;
+
+    switch (tn->kind) {
+    case SPL_TYPE_ERROR:
+    case SPL_TYPE_INFER:
+    case SPL_TYPE_FORALL:
+    case SPL_TYPE_EXISTS:
+    case SPL_TYPE_NEVER:
+    case SPL_TYPE_UNIT:
+        info->size_bits = 0;
+        info->align_bits = 8;
+        return;
+
+    case SPL_TYPE_ANY:
+        /* 顶层类型：stage1 按不透明指针处理 */
+        layout_ptr(layout, info);
+        return;
+
+    case SPL_TYPE_BOOL:
+    case SPL_TYPE_INT:
+    case SPL_TYPE_FLOAT:
+        layout_scalar(layout, tn, info);
+        return;
+
+    case SPL_TYPE_PTR:
+        layout_ptr(layout, info);
+        return;
+
+    case SPL_TYPE_ARRAY: {
+        resolve_type(layout, type, tn->array_type.element);
+        spl_layout_info_t *elem = infos_at(layout, tn->array_type.element);
+        if (!elem || !elem->resolved)
+            return;
+        info->size_bits = elem->size_bits * tn->array_type.len;
+        info->align_bits = elem->align_bits;
+        return;
+    }
+
+    case SPL_TYPE_STRUCT:
+    case SPL_TYPE_UNION:
+    case SPL_TYPE_ENUM:
+    case SPL_TYPE_SHAPE: {
+        for (usize i = 0; i < vec_size(tn->agg_type.variants); ++i) {
+            spl_type_member_t *m = &vec_at(tn->agg_type.variants, i);
+            resolve_type(layout, type, m->type_id);
+        }
+        layout_agg(layout, tn, info);
+        return;
+    }
+
+    case SPL_TYPE_FN:
+        /* 函数类型按函数指针布局 */
+        for (usize i = 0; i < vec_size(tn->fn_type.params); ++i)
+            resolve_type(layout, type, vec_at(tn->fn_type.params, i));
+        resolve_type(layout, type, tn->fn_type.ret);
+        layout_ptr(layout, info);
+        return;
+    }
+}
+
+void spl_layout_resolve(spl_layout_t *layout, spl_type_t *type) {
+    infos_grow(layout, vec_size(type->type_table));
+    for (usize i = 1; i < vec_size(type->type_table); ++i)
+        resolve_type(layout, type, i);
+}
+
+const spl_layout_info_t *spl_layout_info_of(spl_layout_t *layout, spl_type_id_t id) {
+    spl_layout_info_t *info = infos_at(layout, id);
+    if (!info || !info->resolved)
+        return NULL;
+    return info;
+}

stage1/spl_layout.h

@@ -0,0 +1,56 @@
+#ifndef __SPL_LAYOUT_H__
+#define __SPL_LAYOUT_H__
+
+#include "spl_type.h"
+
+typedef struct {
+    usize size;
+    usize abi_align;
+    usize pref_align;
+    VEC(usize) invalid_values;
+} spl_layout_scalar_t;
+
+typedef struct {
+    usize add_space;
+    usize ptr_size;
+    usize ptr_align;
+} spl_layout_ptr_t;
+
+typedef struct {
+    bool allow_field_reordering;
+    enum { ALIGN_MAX, ALIGN_FIXED, ALIGN_MAX_WITH_MIN } align_rule;
+    usize fixed_align;
+} spl_layout_agg_t;
+
+typedef struct {
+    usize size_bits;
+    usize align_bits;
+    VEC(usize) field_bit_offsets;
+    VEC(usize) field_bit_sizes;
+    bool resolved;
+} spl_layout_info_t;
+
+typedef struct {
+    enum { SPL_BIG_ENDIAN, SPL_LITTLE_ENDIAN } endian; // TODO 更多位存储方式
+
+} spl_layout_target_t;
+
+typedef struct {
+    VEC(spl_layout_scalar_t) scalars;
+    VEC(spl_layout_ptr_t) pointers;
+    spl_layout_agg_t aggregate;
+    VEC(spl_layout_info_t) infos;
+    spl_layout_target_t *target;
+} spl_layout_t;
+
+void spl_layout_init(spl_layout_t *layout, spl_layout_target_t *target);
+void spl_layout_drop(spl_layout_t *layout);
+
+void spl_layout_resolve(spl_layout_t *layout, spl_type_t *type);
+
+void spl_layout_add_scalar(spl_layout_t *layout, usize size, usize abi_align);
+void spl_layout_add_ptr(spl_layout_t *layout, usize addr_space, usize size, usize align);
+
+const spl_layout_info_t *spl_layout_info_of(spl_layout_t *layout, spl_type_id_t id);
+
+#endif /* __SPL_LAYOUT_H__ */

stage1/spl_lexer.c

@@ -0,0 +1,500 @@
+/* spl_lexer.c - SPL lexical analyzer */
+
+#include "spl_lexer.h"
+#include "spl_tok.h"
+#include <ctype.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Character classification */
+static int is_ident_start(char c) { return isalpha((unsigned char)c) || c == '_'; }
+
+static int is_ident_cont(char c) { return isalnum((unsigned char)c) || c == '_'; }
+
+/* Keyword lookup: if ident is a keyword, return its token type, else TOK_IDENT */
+static spl_tok_type_t keyword_type(const char *ident, usize len) {
+#define X(name, enum_name, dummy)                                                                  \
+    if (len == sizeof(#name) - 1 && memcmp(ident, #name, len) == 0)                                \
+        return enum_name;
+    KEYWORD_TABLE
+#undef X
+    return TOK_IDENT;
+}
+
+/* Escape sequence decoder - returns the decoded character,
+ * advances *s past the escape sequence, returns 0 on success,
+ * non-zero on error. */
+int spl_decode_escape(const char **s, char *out) {
+    if (**s != '\\') {
+        *out = **s;
+        (*s)++;
+        return 0;
+    }
+    (*s)++; /* skip backslash */
+    switch (**s) {
+    case 'n':
+        *out = '\n';
+        break;
+    case 't':
+        *out = '\t';
+        break;
+    case 'r':
+        *out = '\r';
+        break;
+    case '\\':
+        *out = '\\';
+        break;
+    case '"':
+        *out = '"';
+        break;
+    case '\'':
+        *out = '\'';
+        break;
+    case '0':
+        *out = '\0';
+        break;
+    case 'x': {
+        (*s)++;
+        char hex[3] = {0, 0, 0};
+        int i;
+        for (i = 0; i < 2 && isxdigit((unsigned char)**s); i++, (*s)++) {
+            hex[i] = **s;
+        }
+        if (i == 0)
+            return -1;
+        *out = (char)strtol(hex, NULL, 16);
+        return 0;
+    }
+    default:
+        return -1;
+    }
+    (*s)++;
+    return 0;
+}
+
+spl_tok_vec_t spl_lex(const char *source, const char *fname) {
+    spl_tok_vec_t toks;
+    vec_init(toks);
+
+    usize line = 1;
+    usize col = 1;
+    usize offset = 0;
+    usize len = strlen(source);
+
+    while (offset < len) {
+        const char *start = source + offset;
+        char c = *start;
+
+        /* Skip whitespace (but not newlines - emit TOK_ENDLINE) */
+        if (c == ' ' || c == '\t' || c == '\r') {
+            offset++;
+            col++;
+            continue;
+        }
+
+        /* Newline */
+        if (c == '\n') {
+            spl_tok_t tok;
+            memset(&tok, 0, sizeof(tok));
+            tok.type = TOK_ENDLINE;
+            tok.lexeme = start;
+            tok.len = 1;
+            tok.fname = fname;
+            tok.offset = offset;
+            tok.line = line;
+            tok.col = col;
+            vec_push(toks, tok);
+            offset++;
+            line++;
+            col = 1;
+            continue;
+        }
+
+        /* Line comment */
+        if (c == '/' && offset + 1 < len && source[offset + 1] == '/') {
+            const char *nl = (const char *)memchr(start, '\n', len - offset);
+            usize clen = nl ? (usize)(nl - start) : (len - offset);
+            spl_tok_t tok;
+            memset(&tok, 0, sizeof(tok));
+            tok.type = TOK_LINE_COMMENT;
+            tok.lexeme = start;
+            tok.len = clen;
+            tok.fname = fname;
+            tok.offset = offset;
+            tok.line = line;
+            tok.col = col;
+            vec_push(toks, tok);
+            offset += clen;
+            col += clen;
+            continue;
+        }
+
+        /* Block comment */
+        if (c == '/' && offset + 1 < len && source[offset + 1] == '*') {
+            offset += 2;
+            col += 2;
+            usize depth = 1;
+            while (offset + 1 < len && depth > 0) {
+                if (source[offset] == '*' && source[offset + 1] == '/') {
+                    depth--;
+                    offset += 2;
+                    col += 2;
+                    if (depth == 0)
+                        break;
+                } else if (source[offset] == '/' && source[offset + 1] == '*') {
+                    depth++;
+                    offset += 2;
+                    col += 2;
+                } else {
+                    if (source[offset] == '\n') {
+                        line++;
+                        col = 1;
+                    } else {
+                        col++;
+                    }
+                    offset++;
+                }
+            }
+            continue;
+        }
+
+        /* Char literal: 'x' */
+        if (c == '\'') {
+            offset++;
+            col++;
+            char buf[16];
+            int bi = 0;
+            memset(buf, 0, sizeof(buf));
+
+            if (offset < len) {
+                const char *cp = source + offset;
+                if (spl_decode_escape(&cp, &buf[bi])) {
+                    buf[bi] = source[offset];
+                    cp = source + offset + 1;
+                }
+                bi++;
+                offset = (usize)(cp - source);
+                col += (usize)(cp - (start + 1));
+            }
+
+            if (offset < len && source[offset] == '\'') {
+                offset++;
+                col++;
+            }
+
+            spl_tok_t tok;
+            memset(&tok, 0, sizeof(tok));
+            tok.type = TOK_CHAR_LITERAL;
+            tok.lexeme = start;
+            tok.len = (usize)((source + offset) - start);
+            tok.fname = fname;
+            tok.offset = start - source;
+            tok.line = line;
+            tok.col = col - tok.len;
+            vec_push(toks, tok);
+            continue;
+        }
+
+        /* String literal: "..." */
+        if (c == '"') {
+            offset++;
+            col++;
+            while (offset < len) {
+                if (source[offset] == '\\') {
+                    offset++;
+                    col++;
+                    if (offset < len) {
+                        offset++;
+                        col++;
+                    }
+                } else if (source[offset] == '"') {
+                    offset++;
+                    col++;
+                    break;
+                } else if (source[offset] == '\n') {
+                    line++;
+                    col = 1;
+                    offset++;
+                } else {
+                    offset++;
+                    col++;
+                }
+            }
+
+            spl_tok_t tok;
+            memset(&tok, 0, sizeof(tok));
+            tok.type = TOK_STRING_LITERAL;
+            tok.lexeme = start;
+            tok.len = (usize)((source + offset) - start);
+            tok.fname = fname;
+            tok.offset = start - source;
+            tok.line = line;
+            tok.col = col - tok.len;
+            vec_push(toks, tok);
+            continue;
+        }
+
+        /* Identifiers and keywords */
+        if (is_ident_start(c)) {
+            const char *id_start = start;
+            usize id_len = 0;
+            while (offset < len && is_ident_cont(source[offset])) {
+                offset++;
+                id_len++;
+                col++;
+            }
+
+            spl_tok_type_t tt = keyword_type(id_start, id_len);
+            spl_tok_t tok;
+            memset(&tok, 0, sizeof(tok));
+            tok.type = tt;
+            tok.lexeme = id_start;
+            tok.len = id_len;
+            tok.fname = fname;
+            tok.offset = id_start - source;
+            tok.line = line;
+            tok.col = col - id_len;
+            vec_push(toks, tok);
+            continue;
+        }
+
+        /* Numbers: integers and floats */
+        if (isdigit((unsigned char)c)) {
+            const char *num_start = start;
+            int is_float = 0;
+
+            /* Check for hex/bin/oct prefix */
+            if (c == '0' && offset + 1 < len) {
+                char nc = source[offset + 1];
+                if (nc == 'x' || nc == 'X') {
+                    /* Hex literal */
+                    offset += 2;
+                    col += 2;
+                    while (offset < len &&
+                           (isxdigit((unsigned char)source[offset]) || source[offset] == '_')) {
+                        offset++;
+                        col++;
+                    }
+                    goto emit_int;
+                }
+                if (nc == 'b' || nc == 'B') {
+                    /* Binary literal */
+                    offset += 2;
+                    col += 2;
+                    while (offset < len && (source[offset] == '0' || source[offset] == '1' ||
+                                            source[offset] == '_')) {
+                        offset++;
+                        col++;
+                    }
+                    goto emit_int;
+                }
+                if (nc == 'o' || nc == 'O') {
+                    /* Octal literal */
+                    offset += 2;
+                    col += 2;
+                    while (offset < len && ((source[offset] >= '0' && source[offset] <= '7') ||
+                                            source[offset] == '_')) {
+                        offset++;
+                        col++;
+                    }
+                    goto emit_int;
+                }
+            }
+
+            /* Decimal integer or float */
+            while (offset < len &&
+                   (isdigit((unsigned char)source[offset]) || source[offset] == '_')) {
+                offset++;
+                col++;
+            }
+
+            if (offset < len && source[offset] == '.' && offset + 1 < len &&
+                isdigit((unsigned char)source[offset + 1])) {
+                is_float = 1;
+                offset++;
+                col++;
+                while (offset < len && isdigit((unsigned char)source[offset])) {
+                    offset++;
+                    col++;
+                }
+            }
+
+            if (is_float) {
+                spl_tok_t tok;
+                memset(&tok, 0, sizeof(tok));
+                tok.type = TOK_FLOAT_LITERAL;
+                tok.lexeme = num_start;
+                tok.len = (usize)((source + offset) - num_start);
+                tok.fname = fname;
+                tok.offset = num_start - source;
+                tok.line = line;
+                tok.col = col - tok.len;
+                vec_push(toks, tok);
+                continue;
+            }
+
+        emit_int:
+            {
+                spl_tok_t tok;
+                memset(&tok, 0, sizeof(tok));
+                tok.type = TOK_INT_LITERAL;
+                tok.lexeme = num_start;
+                tok.len = (usize)((source + offset) - num_start);
+                tok.fname = fname;
+                tok.offset = num_start - source;
+                tok.line = line;
+                tok.col = col - tok.len;
+                vec_push(toks, tok);
+                continue;
+            }
+        }
+
+        /* Multi-character operators (longest match) */
+#define TRY_OP1(c1, tok1)                                                                          \
+    if (c == (c1)) {                                                                               \
+        spl_tok_t tok;                                                                             \
+        memset(&tok, 0, sizeof(tok));                                                              \
+        tok.type = (tok1);                                                                         \
+        tok.lexeme = start;                                                                        \
+        tok.len = 1;                                                                               \
+        tok.fname = fname;                                                                         \
+        tok.offset = offset;                                                                       \
+        tok.line = line;                                                                           \
+        tok.col = col;                                                                             \
+        vec_push(toks, tok);                                                                       \
+        offset++;                                                                                  \
+        col++;                                                                                     \
+        continue;                                                                                  \
+    }
+
+/* Helper: try to match a two-char operator */
+#define TRY_OP2(c1, c2, tok2, tok1)                                                                \
+    if (c == (c1) && offset + 1 < len && source[offset + 1] == (c2)) {                             \
+        spl_tok_type_t op_type = (tok2);                                                           \
+        usize op_len = 2;                                                                          \
+        spl_tok_t tok;                                                                             \
+        memset(&tok, 0, sizeof(tok));                                                              \
+        tok.type = op_type;                                                                        \
+        tok.lexeme = start;                                                                        \
+        tok.len = op_len;                                                                          \
+        tok.fname = fname;                                                                         \
+        tok.offset = offset;                                                                       \
+        tok.line = line;                                                                           \
+        tok.col = col;                                                                             \
+        vec_push(toks, tok);                                                                       \
+        offset += op_len;                                                                          \
+        col += op_len;                                                                             \
+        continue;                                                                                  \
+    }
+
+#define TRY_OP3(c1, c2, c3, tok3, tok2, tok1)                                                      \
+    if (c == (c1) && offset + 1 < len && source[offset + 1] == (c2)) {                             \
+        spl_tok_type_t op_type = (tok2);                                                           \
+        usize op_len = 2;                                                                          \
+        if (offset + 2 < len && source[offset + 2] == (c3)) {                                      \
+            op_type = (tok3);                                                                      \
+            op_len = 3;                                                                            \
+        }                                                                                          \
+        spl_tok_t tok;                                                                             \
+        memset(&tok, 0, sizeof(tok));                                                              \
+        tok.type = op_type;                                                                        \
+        tok.lexeme = start;                                                                        \
+        tok.len = op_len;                                                                          \
+        tok.fname = fname;                                                                         \
+        tok.offset = offset;                                                                       \
+        tok.line = line;                                                                           \
+        tok.col = col;                                                                             \
+        vec_push(toks, tok);                                                                       \
+        offset += op_len;                                                                          \
+        col += op_len;                                                                             \
+        continue;                                                                                  \
+    }
+
+        /* Three-char operators first */
+        TRY_OP3('<', '-', '>', TOK_ARROW_BOTH, TOK_RIGHT_ARROW, TOK_LT)
+        TRY_OP3('<', '=', '>', TOK_FAT_ARROW_BOTH, TOK_LE, TOK_LT)
+        TRY_OP3('<', '<', '=', TOK_ASSIGN_L_SH, TOK_L_SH, TOK_LT)
+        TRY_OP3('>', '>', '=', TOK_ASSIGN_R_SH, TOK_R_SH, TOK_GT)
+        TRY_OP3('.', '.', '.', TOK_ELLIPSIS, TOK_RANGE, TOK_DOT)
+
+        /* Two-char operators */
+        TRY_OP2('=', '=', TOK_EQ, TOK_ASSIGN)
+        TRY_OP2('=', '>', TOK_RIGHT_FAT_ARROW, TOK_ASSIGN)
+        TRY_OP2('!', '=', TOK_NEQ, TOK_NOT)
+        TRY_OP2('<', '=', TOK_LE, TOK_LT)
+        TRY_OP2('>', '=', TOK_GE, TOK_GT)
+        TRY_OP2('&', '&', TOK_AND_AND, TOK_AND)
+        TRY_OP2('|', '|', TOK_OR_OR, TOK_OR)
+        TRY_OP2('+', '=', TOK_ASSIGN_ADD, TOK_ADD)
+        TRY_OP2('-', '=', TOK_ASSIGN_SUB, TOK_SUB)
+        TRY_OP2('*', '=', TOK_ASSIGN_MUL, TOK_MUL)
+        TRY_OP2('/', '=', TOK_ASSIGN_DIV, TOK_DIV)
+        TRY_OP2('%', '=', TOK_ASSIGN_MOD, TOK_MOD)
+        TRY_OP2('&', '=', TOK_ASSIGN_AND, TOK_AND)
+        TRY_OP2('|', '=', TOK_ASSIGN_OR, TOK_OR)
+        TRY_OP2('^', '=', TOK_ASSIGN_XOR, TOK_XOR)
+        TRY_OP2('<', '-', TOK_LEFT_ARROW, TOK_LT)
+        TRY_OP2('-', '>', TOK_RIGHT_ARROW, TOK_SUB)
+        TRY_OP2(':', '=', TOK_COLON_ASSIGN, TOK_COLON)
+
+        /* Single-character operators */
+        TRY_OP1('+', TOK_ADD);
+        TRY_OP1('-', TOK_SUB);
+        TRY_OP1('*', TOK_MUL);
+        TRY_OP1('/', TOK_DIV);
+        TRY_OP1('%', TOK_MOD);
+        TRY_OP1('&', TOK_AND);
+        TRY_OP1('|', TOK_OR);
+        TRY_OP1('^', TOK_XOR);
+        TRY_OP1('~', TOK_BIT_NOT);
+        TRY_OP1('!', TOK_NOT);
+        TRY_OP1('<', TOK_LT);
+        TRY_OP1('>', TOK_GT);
+        TRY_OP1('=', TOK_ASSIGN);
+        TRY_OP1('.', TOK_DOT);
+        TRY_OP1(',', TOK_COMMA);
+        TRY_OP1(';', TOK_SEMICOLON);
+        TRY_OP1(':', TOK_COLON);
+        TRY_OP1('(', TOK_L_PAREN);
+        TRY_OP1(')', TOK_R_PAREN);
+        TRY_OP1('[', TOK_L_BRACKET);
+        TRY_OP1(']', TOK_R_BRACKET);
+        TRY_OP1('{', TOK_L_BRACE);
+        TRY_OP1('}', TOK_R_BRACE);
+        TRY_OP1('#', TOK_SHARP);
+        TRY_OP1('@', TOK_AT);
+        TRY_OP1('$', TOK_DOLLAR);
+        TRY_OP1('?', TOK_COND);
+
+        // TODO
+        spl_tok_t tok;
+        memset(&tok, 0, sizeof(tok));
+        tok.type = TOK_UNKNOWN;
+        tok.lexeme = start;
+        tok.len = 1;
+        tok.fname = fname;
+        tok.offset = offset;
+        tok.line = line;
+        tok.col = col;
+        vec_push(toks, tok);
+        offset++;
+        col++;
+        continue;
+    }
+
+    /* EOF token */
+    {
+        spl_tok_t tok;
+        memset(&tok, 0, sizeof(tok));
+        tok.type = TOK_EOF;
+        tok.lexeme = source + offset;
+        tok.len = 0;
+        tok.fname = fname;
+        tok.offset = offset;
+        tok.line = line;
+        tok.col = col;
+        vec_push(toks, tok);
+    }
+
+    return toks;
+}

stage1/spl_lexer.h

@@ -0,0 +1,13 @@
+/* spl_lexer.h - 独立词法分析器 */
+#ifndef __SPL_LEXER_H__
+#define __SPL_LEXER_H__
+
+#include "spl_tok.h"
+
+/* Lexer entry point */
+spl_tok_vec_t spl_lex(const char *source, const char *fname);
+
+/* Decode escape sequence, advance *s past it. Returns 0 on success. */
+int spl_decode_escape(const char **s, char *out);
+
+#endif /* __SPL_LEXER_H__ */

stage1/spl_mpa.h

@@ -0,0 +1,14 @@
+#ifndef __SPL_MPA_H__
+#define __SPL_MPA_H__
+
+#include <stdint.h>
+
+typedef struct {
+    uint64_t bits;
+} spl_mpa_int_t;
+
+typedef struct {
+    double bits;
+} spl_mpa_float_t;
+
+#endif /* __SPL_MPA_H__ */

stage1/spl_parser.h

@@ -0,0 +1,21 @@
+#ifndef __SPL_PARSER_H__
+#define __SPL_PARSER_H__
+
+#include "spl_ast.h"
+#include "spl_diag.h"
+
+typedef struct spl_parser {
+    spl_ast_t *ast;
+    spl_diag_t *diag;
+    usize pos;
+    int failed;
+    int stop_agg;
+    usize error_count;
+} spl_parser_t;
+
+void spl_parser_init(spl_parser_t *p);
+void spl_parser_drop(spl_parser_t *p);
+
+void spl_ast_parse(spl_parser_t *p, spl_ast_t *ast);
+
+#endif /* __SPL_PARSER_H__ */

stage1/spl_scope.c

@@ -0,0 +1,46 @@
+#include "spl_scope.h"
+
+void spl_scope_init(spl_scope_t *scope) {
+    vec_init(scope->scopes);
+    vec_push(scope->scopes, (spl_scope_node_t){0});
+    scope->current_scope = 0;
+    scope->root_scope = 0;
+}
+
+void spl_scope_drop(spl_scope_t *scope) {
+    for (usize i = 0; i < vec_size(scope->scopes); ++i) {
+        map_free(vec_at(scope->scopes, i).symbols);
+    }
+    vec_free(scope->scopes);
+    scope->current_scope = 0;
+    scope->root_scope = 0;
+}
+
+spl_scope_id_t spl_scope_alloc(spl_scope_t *scope) {
+    spl_scope_node_t n = {0};
+    n.parent = scope->current_scope;
+    map_init(n.symbols, MAP_HASH_STR, MAP_CMP_STR);
+    vec_push(scope->scopes, n);
+    return vec_size(scope->scopes) - 1;
+}
+
+bool spl_scope_insert(spl_scope_t *scope, spl_scope_id_t id, spl_symbol_t symbol) {
+    Assert(id != 0 && id < vec_size(scope->scopes));
+    spl_scope_node_t *node = &vec_at(scope->scopes, id);
+    spl_symbol_t old = {0};
+    if (map_get(node->symbols, symbol.name, &old))
+        return false;
+    map_put(node->symbols, symbol.name, symbol);
+    return true;
+}
+
+bool spl_scope_find(spl_scope_t *scope, const char *name, spl_symbol_t *out) {
+    if (!scope || !name || !out)
+        return false;
+    for (spl_scope_id_t id = scope->current_scope; id != 0; id = vec_at(scope->scopes, id).parent) {
+        spl_scope_node_t *s = &vec_at(scope->scopes, id);
+        if (map_get(s->symbols, name, out))
+            return true;
+    }
+    return false;
+}

stage1/spl_scope.h

@@ -0,0 +1,42 @@
+#ifndef __SPL_SCOPE_H__
+#define __SPL_SCOPE_H__
+
+#include "spl_lang_type.h"
+
+typedef usize spl_scope_id_t;
+
+typedef enum {
+    SPL_SYMBOL_KIND_ERROR,
+    SPL_SYMBOL_KIND_VAR,
+    SPL_SYMBOL_KIND_MEMBER,
+    SPL_SYMBOL_KIND_FN,
+    SPL_SYMBOL_KIND_TYPE,
+} spl_symbol_kind_t;
+
+typedef struct {
+    const char *name;
+    spl_symbol_kind_t kind;
+    spl_def_id_t node;
+} spl_symbol_t;
+
+typedef VEC(const char *) spl_symbol_path_t;
+
+typedef struct {
+    spl_scope_id_t parent;
+    MAP(const char *, spl_symbol_t) symbols;
+} spl_scope_node_t;
+typedef VEC(spl_scope_node_t) spl_scope_node_vec_t;
+
+typedef struct {
+    spl_scope_node_vec_t scopes;
+    spl_scope_id_t root_scope;
+    spl_scope_id_t current_scope;
+} spl_scope_t;
+
+void spl_scope_init(spl_scope_t *scope);
+void spl_scope_drop(spl_scope_t *scope);
+spl_scope_id_t spl_scope_alloc(spl_scope_t *scope);
+bool spl_scope_insert(spl_scope_t *scope, spl_scope_id_t id, spl_symbol_t symbol);
+bool spl_scope_find(spl_scope_t *scop, const char *symbol_name, spl_symbol_t *out);
+
+#endif /* __SPL_SCOPE_H__ */

stage1/spl_sema.h

@@ -0,0 +1,43 @@
+#ifndef __SPL_SEMA_H__
+#define __SPL_SEMA_H__
+
+#include "spl_ast.h"
+#include "spl_attr.h"
+#include "spl_diag.h"
+#include "spl_lang_type.h"
+#include "spl_mpa.h"
+#include "spl_scope.h"
+#include "spl_type.h"
+
+typedef struct spl_module_loader spl_module_loader_t;
+struct spl_module_loader {
+    /* 从 from_fname 所在目录解析 path；返回该文件的 ast（已 init + parse）。
+       失败（文件不存在 / parse 错误 / 环）返回 NULL。
+       loader 拥有 ast 的生命周期；sema 不负责释放。 */
+    spl_ast_t *(*load)(void *user, const char *from_fname, const char *path, spl_diag_t *diag);
+    void *user;
+};
+
+typedef struct {
+    spl_ast_t *ast;
+    spl_lang_type_t *type;
+    spl_scope_t *scope;
+    spl_symbol_t root;
+    spl_attr_t *attr;
+    spl_lang_type_id_t current_aggregate_lang;
+    spl_lang_type_id_t current_fn_ret_tid;
+    spl_lang_type_id_t current_loop_break_tid;
+    spl_symbol_path_t label_stack;
+    const spl_module_loader_t *loader;
+    spl_diag_t *diag;
+} spl_sema_t;
+
+void spl_sema_init(spl_sema_t *sema, spl_ast_t *ast, spl_lang_type_t *type, spl_scope_t *scope,
+                   spl_attr_t *attr);
+void spl_sema_drop(spl_sema_t *sema);
+
+void spl_sema_run_module(spl_sema_t *sema, spl_ast_node_ref_t module_ref);
+void spl_sema_run(spl_sema_t *sema);
+void spl_sema_dump(spl_sema_t *sema);
+
+#endif /* __SPL_SEMA_H__ */

stage1/spl_tok.c

@@ -0,0 +1,15 @@
+#include "spl_tok.h"
+
+const char *spl_tok_type_name(spl_tok_type_t t) {
+    static const char *const names[] = {
+#define X(name, enum_name, dummy) #enum_name,
+        KEYWORD_TABLE
+#undef X
+#define X(name, enum_name, dummy) #enum_name,
+            TOKEN_TABLE
+#undef X
+    };
+    if ((usize)t < sizeof(names) / sizeof(names[0]))
+        return names[t];
+    return "?";
+}

stage1/spl_tok.h

@@ -0,0 +1,132 @@
+/* spl_tok.h - Token type definitions (extracted from spl_lexer.h) */
+#ifndef __SPL_TOK_H__
+#define __SPL_TOK_H__
+
+#include "../stage0/include/utils.h"
+
+/* clang-format off */
+#define KEYWORD_TABLE \
+    X(any           , KW_ANY            , SPL_V0) \
+    X(as            , KW_AS             , SPL_V0) \
+    X(bool          , KW_BOOL           , SPL_V0) \
+    X(break         , KW_BREAK          , SPL_V0) \
+    X(catch         , KW_CATCH          , SPL_V0) \
+    X(comptime      , KW_COMPTIME       , SPL_V0) \
+    X(const         , KW_CONST          , SPL_V0) \
+    X(continue      , KW_CONTINUE       , SPL_V0) \
+    X(defer         , KW_DEFER          , SPL_V0) \
+    X(else          , KW_ELSE           , SPL_V0) \
+    X(enum          , KW_ENUM           , SPL_V0) \
+    X(errdefer      , KW_ERRDEFER       , SPL_V0) \
+    X(false         , KW_FALSE          , SPL_V0) \
+    X(fn            , KW_FN             , SPL_V0) \
+    X(for           , KW_FOR            , SPL_V0) \
+    X(if            , KW_IF             , SPL_V0) \
+    X(loop          , KW_LOOP           , SPL_V0) \
+    X(match         , KW_MATCH          , SPL_V0) \
+    X(null          , KW_NULL           , SPL_V0) \
+    X(ret           , KW_RET            , SPL_V0) \
+    X(shape         , KW_SHAPE          , SPL_V0) \
+    X(struct        , KW_STRUCT         , SPL_V0) \
+    X(true          , KW_TRUE           , SPL_V0) \
+    X(try           , KW_TRY            , SPL_V0) \
+    X(type          , KW_TYPE           , SPL_V0) \
+    X(undefined     , KW_UNDEFINED      , SPL_V0) \
+    X(union         , KW_UNION          , SPL_V0) \
+    X(var           , KW_VAR            , SPL_V0) \
+    X(while         , KW_WHILE          , SPL_V0) \
+    X(_             , KW_UNDERSCORE     , SPL_V0) \
+    // KEYWORD_TABLE
+
+#define TOKEN_TABLE \
+    X(unknown   , TOK_UNKNOWN           , SPL_V0 ) \
+    X(EOF       , TOK_EOF               , SPL_V0 ) \
+    X(blank     , TOK_BLANK             , SPL_V0 ) \
+    X(endline   , TOK_ENDLINE           , SPL_V0 ) \
+    X("#"       , TOK_SHARP             , SPL_V0 ) \
+    X("@"       , TOK_AT                , SPL_V0 ) \
+    X("$"       , TOK_DOLLAR            , SPL_V0 ) \
+    X("=="      , TOK_EQ                , SPL_V0 ) \
+    X("="       , TOK_ASSIGN            , SPL_V0 ) \
+    X("+="      , TOK_ASSIGN_ADD        , SPL_V0 ) \
+    X("+"       , TOK_ADD               , SPL_V0 ) \
+    X("-="      , TOK_ASSIGN_SUB        , SPL_V0 ) \
+    X("->"      , TOK_RIGHT_ARROW       , SPL_V0 ) \
+    X("<-"      , TOK_LEFT_ARROW        , SPL_V0 ) \
+    X("<->"     , TOK_ARROW_BOTH        , SPL_V0 ) \
+    X("<=>"     , TOK_FAT_ARROW_BOTH    , SPL_V0 ) \
+    X("=>"      , TOK_RIGHT_FAT_ARROW   , SPL_V0 ) \
+    X("-"       , TOK_SUB               , SPL_V0 ) \
+    X("*="      , TOK_ASSIGN_MUL        , SPL_V0 ) \
+    X("*"       , TOK_MUL               , SPL_V0 ) \
+    X("/="      , TOK_ASSIGN_DIV        , SPL_V0 ) \
+    X("/"       , TOK_DIV               , SPL_V0 ) \
+    X("//"      , TOK_LINE_COMMENT      , SPL_V0 ) \
+    X("/* */"   , TOK_BLOCK_COMMENT     , SPL_V0 ) \
+    X("%="      , TOK_ASSIGN_MOD        , SPL_V0 ) \
+    X("%"       , TOK_MOD               , SPL_V0 ) \
+    X("&&"      , TOK_AND_AND           , SPL_V0 ) \
+    X("&="      , TOK_ASSIGN_AND        , SPL_V0 ) \
+    X("&"       , TOK_AND               , SPL_V0 ) \
+    X("||"      , TOK_OR_OR             , SPL_V0 ) \
+    X("|="      , TOK_ASSIGN_OR         , SPL_V0 ) \
+    X("|"       , TOK_OR                , SPL_V0 ) \
+    X("^="      , TOK_ASSIGN_XOR        , SPL_V0 ) \
+    X("^"       , TOK_XOR               , SPL_V0 ) \
+    X("<<="     , TOK_ASSIGN_L_SH       , SPL_V0 ) \
+    X("<<"      , TOK_L_SH              , SPL_V0 ) \
+    X("<="      , TOK_LE                , SPL_V0 ) \
+    X("<"       , TOK_LT                , SPL_V0 ) \
+    X(">>="     , TOK_ASSIGN_R_SH       , SPL_V0 ) \
+    X(">>"      , TOK_R_SH              , SPL_V0 ) \
+    X(">="      , TOK_GE                , SPL_V0 ) \
+    X(">"       , TOK_GT                , SPL_V0 ) \
+    X("!"       , TOK_NOT               , SPL_V0 ) \
+    X("!="      , TOK_NEQ               , SPL_V0 ) \
+    X("~"       , TOK_BIT_NOT           , SPL_V0 ) \
+    X("["       , TOK_L_BRACKET         , SPL_V0 ) \
+    X("]"       , TOK_R_BRACKET         , SPL_V0 ) \
+    X("("       , TOK_L_PAREN           , SPL_V0 ) \
+    X(")"       , TOK_R_PAREN           , SPL_V0 ) \
+    X("{"       , TOK_L_BRACE           , SPL_V0 ) \
+    X("}"       , TOK_R_BRACE           , SPL_V0 ) \
+    X(";"       , TOK_SEMICOLON         , SPL_V0 ) \
+    X(","       , TOK_COMMA             , SPL_V0 ) \
+    X(":"       , TOK_COLON             , SPL_V0 ) \
+    X(":="      , TOK_COLON_ASSIGN      , SPL_V0 ) \
+    X("."       , TOK_DOT               , SPL_V0 ) \
+    X(".."      , TOK_RANGE             , SPL_V0 ) \
+    X("..."     , TOK_ELLIPSIS          , SPL_V0 ) \
+    X("?"       , TOK_COND              , SPL_V0 ) \
+    X(ident     , TOK_IDENT             , SPL_V0 ) \
+    X(int       , TOK_INT_LITERAL       , SPL_V0 ) \
+    X(float     , TOK_FLOAT_LITERAL     , SPL_V0 ) \
+    X(char      , TOK_CHAR_LITERAL      , SPL_V0 ) \
+    X(string    , TOK_STRING_LITERAL    , SPL_V0 ) \
+    // TOKEN_TABLE
+/* clang-format on */
+
+typedef enum {
+#define X(name, enum_name, dummy) enum_name,
+    KEYWORD_TABLE
+#undef X
+#define X(name, enum_name, dummy) enum_name,
+        TOKEN_TABLE
+#undef X
+} spl_tok_type_t;
+
+typedef struct {
+    spl_tok_type_t type;
+    const char *lexeme;
+    usize len;
+    const char *fname;
+    usize offset;
+    usize line;
+    usize col;
+} spl_tok_t;
+
+typedef VEC(spl_tok_t) spl_tok_vec_t;
+
+const char *spl_tok_type_name(spl_tok_type_t t);
+
+#endif /* __SPL_TOK_H__ */

stage1/spl_type.c

@@ -0,0 +1,418 @@
+#include "spl_type.h"
+
+static usize spl_type_hash(spl_type_node_t n) {
+    usize hash = (usize)n.kind * 131;
+    switch (n.kind) {
+    case SPL_TYPE_ERROR:
+    case SPL_TYPE_UNIT:
+    case SPL_TYPE_ANY:
+    case SPL_TYPE_NEVER:
+    case SPL_TYPE_INFER:
+    case SPL_TYPE_FORALL:
+    case SPL_TYPE_EXISTS:
+    case SPL_TYPE_BOOL:
+        break;
+    case SPL_TYPE_INT:
+        hash += n.int_type.bits + (usize)n.int_type.is_signed;
+        break;
+    case SPL_TYPE_FLOAT:
+        hash += n.float_type.bits;
+        break;
+    case SPL_TYPE_PTR:
+        hash += n.ptr_type.pointee;
+        break;
+    case SPL_TYPE_ARRAY:
+        hash += n.array_type.element + n.array_type.len;
+        break;
+    case SPL_TYPE_STRUCT:
+    case SPL_TYPE_UNION:
+    case SPL_TYPE_ENUM:
+    case SPL_TYPE_SHAPE:
+        hash += (usize)n.layout.mode * 31 + n.layout.fixed_align_bits;
+        hash += n.agg_type.tag_type;
+        for (usize i = 0; i < vec_size(n.agg_type.variants); i++) {
+            spl_type_member_t *m = &n.agg_type.variants.data[i];
+            hash += m->type_id;
+            if (m->name) {
+                const char *s = m->name;
+                while (*s) {
+                    hash = hash * 31 + (usize)(*s++);
+                }
+            }
+        }
+        break;
+    case SPL_TYPE_FN:
+        hash += n.fn_type.ret;
+        for (usize i = 0; i < vec_size(n.fn_type.params); i++) {
+            hash += vec_at(n.fn_type.params, i);
+        }
+        break;
+    }
+    return hash;
+}
+
+static int spl_type_eq(spl_type_node_t n1, spl_type_node_t n2) {
+    if (n1.kind != n2.kind)
+        return 1;
+    switch (n1.kind) {
+    case SPL_TYPE_ERROR:
+    case SPL_TYPE_UNIT:
+    case SPL_TYPE_ANY:
+    case SPL_TYPE_NEVER:
+    case SPL_TYPE_INFER:
+    case SPL_TYPE_FORALL:
+    case SPL_TYPE_EXISTS:
+    case SPL_TYPE_BOOL:
+        return 0;
+    case SPL_TYPE_INT:
+        return (n1.int_type.bits != n2.int_type.bits) ||
+               (n1.int_type.is_signed != n2.int_type.is_signed);
+    case SPL_TYPE_FLOAT:
+        return n1.float_type.bits != n2.float_type.bits;
+    case SPL_TYPE_PTR:
+        return n1.ptr_type.pointee != n2.ptr_type.pointee;
+    case SPL_TYPE_ARRAY:
+        return (n1.array_type.element != n2.array_type.element) ||
+               (n1.array_type.len != n2.array_type.len);
+    case SPL_TYPE_STRUCT:
+    case SPL_TYPE_UNION:
+    case SPL_TYPE_ENUM:
+    case SPL_TYPE_SHAPE:
+        if (n1.layout.mode != n2.layout.mode ||
+            n1.layout.fixed_align_bits != n2.layout.fixed_align_bits)
+            return 1;
+        if (n1.agg_type.tag_type != n2.agg_type.tag_type)
+            return 1;
+        if (vec_size(n1.agg_type.variants) != vec_size(n2.agg_type.variants))
+            return 1;
+        for (usize i = 0; i < vec_size(n1.agg_type.variants); i++) {
+            spl_type_member_t *a = &n1.agg_type.variants.data[i];
+            spl_type_member_t *b = &n2.agg_type.variants.data[i];
+            if (a->type_id != b->type_id)
+                return 1;
+            if ((a->name == NULL) != (b->name == NULL))
+                return 1;
+            if (a->name && strcmp(a->name, b->name) != 0)
+                return 1;
+        }
+        return 0;
+    case SPL_TYPE_FN:
+        if (n1.fn_type.ret != n2.fn_type.ret)
+            return 1;
+        if (vec_size(n1.fn_type.params) != vec_size(n2.fn_type.params))
+            return 1;
+        for (usize i = 0; i < vec_size(n1.fn_type.params); i++) {
+            if (vec_at(n1.fn_type.params, i) != vec_at(n2.fn_type.params, i))
+                return 1;
+        }
+        return 0;
+    }
+    return 1;
+}
+
+static usize spl_type_map_hash(usize k) { return MAP_HASH_INT(k); }
+static int spl_type_map_cmp(usize a, usize b) { return MAP_CMP_INT(a, b); }
+
+static void spl_type_node_free_vecs(spl_type_node_t *tn) {
+    switch (tn->kind) {
+    case SPL_TYPE_STRUCT:
+    case SPL_TYPE_UNION:
+    case SPL_TYPE_ENUM:
+    case SPL_TYPE_SHAPE:
+        vec_free(tn->agg_type.variants);
+        break;
+    case SPL_TYPE_FN:
+        vec_free(tn->fn_type.params);
+        break;
+    default:
+        break;
+    }
+}
+
+spl_type_id_t spl_type_node_push(spl_type_t *type, spl_type_node_t *tn) {
+    usize hash = spl_type_hash(*tn);
+    usize idx = (usize)-1;
+    spl_type_id_t cand = 0;
+    while (map_get_continue(type->type_map, hash, &cand, &idx)) {
+        spl_type_node_t *existing = &vec_at(type->type_table, cand);
+        if (spl_type_eq(*existing, *tn) == 0) {
+            spl_type_node_free_vecs(tn);
+            return cand;
+        }
+    }
+    spl_type_id_t id = vec_size(type->type_table);
+    vec_push(type->type_table, *tn);
+    map_put_new(type->type_map, hash, id);
+    tn->kind = SPL_TYPE_ERROR;
+    return id;
+}
+
+void spl_type_init(spl_type_t *type) {
+    vec_init(type->type_table);
+    spl_type_node_t type_node = {0};
+    vec_push(type->type_table, type_node);
+    map_init(type->type_map, spl_type_map_hash, spl_type_map_cmp);
+}
+
+void spl_type_drop(spl_type_t *type) {
+    for (usize i = 0; i < vec_size(type->type_table); i++) {
+        spl_type_node_t *n = &vec_at(type->type_table, i);
+        spl_type_node_free_vecs(n);
+    }
+    map_free(type->type_map);
+    vec_free(type->type_table);
+}
+
+spl_type_node_t *spl_type_node(const spl_type_t *type, spl_type_id_t id) {
+    if (!id || id >= vec_size(type->type_table))
+        return NULL;
+    return &vec_at(type->type_table, id);
+}
+
+bool spl_type_is_subtype(const spl_type_t *type, spl_type_id_t sub, spl_type_id_t super) {
+    if (sub == 0 || super == 0)
+        return false;
+    if (sub == super)
+        return true;
+
+    spl_type_node_t *nsub = spl_type_node(type, sub);
+    spl_type_node_t *nsuper = spl_type_node(type, super);
+    if (!nsub || !nsuper)
+        return false;
+
+    if (nsub->kind == SPL_TYPE_NEVER)
+        return true;
+    if (nsuper->kind == SPL_TYPE_ANY)
+        return true;
+
+    if (nsub->kind == SPL_TYPE_INT && nsuper->kind == SPL_TYPE_INT) {
+        if (nsub->int_type.bits == 0)
+            return true;
+        if (nsub->int_type.is_signed == nsuper->int_type.is_signed) {
+            return nsub->int_type.bits <= nsuper->int_type.bits;
+        }
+        if (!nsub->int_type.is_signed && nsuper->int_type.is_signed) {
+            return nsuper->int_type.bits > nsub->int_type.bits;
+        }
+        return false;
+    }
+    if (nsub->kind == SPL_TYPE_FLOAT && nsuper->kind == SPL_TYPE_FLOAT) {
+        if (nsub->float_type.bits == 0)
+            return true;
+        return nsub->float_type.bits <= nsuper->float_type.bits;
+    }
+
+    return false;
+}
+
+static void spl_type_pure_dump_rec(spl_type_t *type, spl_type_id_t id, spl_type_id_vec_t *stack) {
+    for (usize i = 0; i < vec_size(*stack); i++) {
+        if (vec_at(*stack, i) == id) {
+            printf("<rec#%zu>", id);
+            return;
+        }
+    }
+    if (vec_size(*stack) > 32) {
+        printf("...");
+        return;
+    }
+    vec_push(*stack, id);
+
+    spl_type_node_t *n = spl_type_node(type, id);
+    if (!n) {
+        printf("none");
+        vec_pop(*stack);
+        return;
+    }
+    switch (n->kind) {
+    case SPL_TYPE_ERROR:
+        printf("error");
+        break;
+    case SPL_TYPE_UNIT:
+        printf("unit");
+        break;
+    case SPL_TYPE_ANY:
+        printf("any");
+        break;
+    case SPL_TYPE_NEVER:
+        printf("never");
+        break;
+    case SPL_TYPE_INFER:
+        printf("infer");
+        break;
+    case SPL_TYPE_FORALL:
+    case SPL_TYPE_EXISTS:
+        printf("quant");
+        break;
+    case SPL_TYPE_BOOL:
+        printf("bool");
+        break;
+    case SPL_TYPE_INT:
+        if (n->int_type.bits == 0)
+            printf("comptime_int");
+        else
+            printf("%s%zu", n->int_type.is_signed ? "i" : "u", n->int_type.bits);
+        break;
+    case SPL_TYPE_FLOAT:
+        if (n->float_type.bits == 0)
+            printf("comptime_float");
+        else
+            printf("f%zu", n->float_type.bits);
+        break;
+    case SPL_TYPE_PTR:
+        printf("*");
+        spl_type_pure_dump_rec(type, n->ptr_type.pointee, stack);
+        break;
+    case SPL_TYPE_ARRAY:
+        printf("[%zu]", n->array_type.len);
+        spl_type_pure_dump_rec(type, n->array_type.element, stack);
+        break;
+    case SPL_TYPE_STRUCT:
+    case SPL_TYPE_UNION:
+    case SPL_TYPE_ENUM:
+    case SPL_TYPE_SHAPE: {
+        const char *kw = "struct";
+        if (n->kind == SPL_TYPE_UNION)
+            kw = "union";
+        else if (n->kind == SPL_TYPE_ENUM)
+            kw = "enum";
+        else if (n->kind == SPL_TYPE_SHAPE)
+            kw = "shape";
+        printf("%s{", kw);
+        for (usize i = 0; i < vec_size(n->agg_type.variants); i++) {
+            if (i)
+                printf(", ");
+            spl_type_member_t *m = &n->agg_type.variants.data[i];
+            printf("%s:", m->name ? m->name : "?");
+            spl_type_pure_dump_rec(type, m->type_id, stack);
+        }
+        printf("}");
+        break;
+    }
+    case SPL_TYPE_FN:
+        printf("fn(");
+        for (usize i = 0; i < vec_size(n->fn_type.params); i++) {
+            if (i)
+                printf(",");
+            spl_type_pure_dump_rec(type, vec_at(n->fn_type.params, i), stack);
+        }
+        printf(")");
+        spl_type_pure_dump_rec(type, n->fn_type.ret, stack);
+        break;
+    }
+
+    vec_pop(*stack);
+}
+
+void spl_type_pure_dump(spl_type_t *type, spl_type_id_t id) {
+    spl_type_id_vec_t stack;
+    vec_init(stack);
+    spl_type_pure_dump_rec(type, id, &stack);
+    vec_free(stack);
+}
+
+spl_type_id_t spl_type_fn_param_tid(spl_type_t *type, spl_type_id_t fn_tid, usize idx) {
+    spl_type_node_t *n = spl_type_node(type, fn_tid);
+    if (!n || n->kind != SPL_TYPE_FN || idx >= vec_size(n->fn_type.params))
+        return 0;
+    return vec_at(n->fn_type.params, idx);
+}
+
+static const spl_type_member_t *spl_type_agg_member_find(spl_type_t *type, spl_type_id_t tid,
+                                                         const char *name, usize *out_idx) {
+    spl_type_node_t *n = spl_type_node(type, tid);
+    if (!n || !name)
+        return NULL;
+    if (n->kind == SPL_TYPE_STRUCT || n->kind == SPL_TYPE_UNION || n->kind == SPL_TYPE_ENUM ||
+        n->kind == SPL_TYPE_SHAPE) {
+        for (usize i = 0; i < vec_size(n->agg_type.variants); i++) {
+            spl_type_member_t *m = &n->agg_type.variants.data[i];
+            if (m->name && strcmp(m->name, name) == 0) {
+                if (out_idx)
+                    *out_idx = i;
+                return m;
+            }
+        }
+    }
+    return NULL;
+}
+
+const spl_type_member_t *spl_type_agg_member(spl_type_t *type, spl_type_id_t tid,
+                                             const char *name) {
+    return spl_type_agg_member_find(type, tid, name, NULL);
+}
+
+bool spl_type_agg_member_idx(spl_type_t *type, spl_type_id_t tid, const char *name,
+                             usize *out_idx) {
+    return spl_type_agg_member_find(type, tid, name, out_idx) != NULL;
+}
+
+spl_type_id_t spl_type_builder_simple(spl_type_t *type, spl_type_node_kind_t kind) {
+    spl_type_node_t tn = {0};
+    tn.kind = kind;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_int(spl_type_t *type, usize bits, int is_signed) {
+    spl_type_node_t tn = {0};
+    tn.kind = SPL_TYPE_INT;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    tn.int_type.bits = bits;
+    tn.int_type.is_signed = is_signed;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_float(spl_type_t *type, usize bits) {
+    spl_type_node_t tn = {0};
+    tn.kind = SPL_TYPE_FLOAT;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    tn.float_type.bits = bits;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_ptr(spl_type_t *type, spl_type_id_t pointee) {
+    spl_type_node_t tn = {0};
+    tn.kind = SPL_TYPE_PTR;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    tn.ptr_type.pointee = pointee;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_array(spl_type_t *type, spl_type_id_t element, usize len) {
+    spl_type_node_t tn = {0};
+    tn.kind = SPL_TYPE_ARRAY;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    tn.array_type.element = element;
+    tn.array_type.len = len;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_fn(spl_type_t *type, spl_type_id_t ret, const spl_type_id_t *params,
+                                  usize nparams) {
+    spl_type_node_t tn = {0};
+    tn.kind = SPL_TYPE_FN;
+    tn.layout.mode = SPL_TYPE_LAYOUT_AUTO;
+    vec_init(tn.fn_type.params);
+    for (usize i = 0; i < nparams; i++) {
+        vec_push(tn.fn_type.params, params[i]);
+    }
+    tn.fn_type.ret = ret;
+    return spl_type_node_push(type, &tn);
+}
+
+spl_type_id_t spl_type_builder_agg(spl_type_t *type, spl_type_node_kind_t tk,
+                                   spl_type_member_vec_t *variants, spl_type_id_t tag_type,
+                                   spl_type_layout_t layout) {
+    spl_type_node_t tn = {0};
+    tn.kind = tk;
+    tn.layout = layout;
+    tn.agg_type.variants = *variants;
+    vec_init(*variants);
+    if (tk == SPL_TYPE_ENUM) {
+        tn.agg_type.tag_type = tag_type;
+    } else {
+        tn.agg_type.tag_type = 0;
+    }
+    return spl_type_node_push(type, &tn);
+}

stage1/spl_type.h

@@ -0,0 +1,111 @@
+#ifndef __SPL_TYPE_H__
+#define __SPL_TYPE_H__
+
+#include "../stage0/include/utils.h"
+
+typedef usize spl_type_id_t;
+typedef VEC(spl_type_id_t) spl_type_id_vec_t;
+
+typedef enum {
+    SPL_TYPE_ERROR,
+    SPL_TYPE_NEVER, // bottom type
+    SPL_TYPE_ANY,   // top type
+    SPL_TYPE_UNIT,
+    SPL_TYPE_INFER,
+    SPL_TYPE_BOOL,
+    SPL_TYPE_INT,
+    SPL_TYPE_FLOAT,
+    SPL_TYPE_PTR,
+    SPL_TYPE_ARRAY,
+    SPL_TYPE_STRUCT,
+    SPL_TYPE_UNION,
+    SPL_TYPE_ENUM,
+    SPL_TYPE_FN,
+    SPL_TYPE_FORALL, // TODO delete
+    SPL_TYPE_EXISTS, // TODO delete
+    SPL_TYPE_SHAPE,
+} spl_type_node_kind_t;
+
+typedef enum {
+    SPL_TYPE_LAYOUT_AUTO,
+    SPL_TYPE_LAYOUT_EXTERN_C,
+    SPL_TYPE_LAYOUT_PACKED,
+} spl_type_layout_mode_t;
+
+typedef struct {
+    spl_type_layout_mode_t mode;
+    usize fixed_align_bits;
+} spl_type_layout_t;
+
+typedef struct {
+    const char *name;
+    spl_type_id_t type_id;
+    usize ast_node_ref;
+} spl_type_member_t;
+typedef VEC(spl_type_member_t) spl_type_member_vec_t;
+
+typedef struct {
+    spl_type_node_kind_t kind;
+    spl_type_layout_t layout;
+    union {
+        struct {
+            usize bits;
+            int is_signed;
+        } int_type;
+        struct {
+            usize bits;
+        } float_type;
+        struct {
+            spl_type_id_t pointee;
+        } ptr_type;
+        struct {
+            spl_type_id_t element;
+            usize len;
+        } array_type;
+        struct {
+            spl_type_member_vec_t variants;
+            spl_type_id_t tag_type;
+        } agg_type;
+        struct {
+            spl_type_id_vec_t params;
+            spl_type_id_t ret;
+        } fn_type;
+        struct {
+        } shape_type;
+    };
+} spl_type_node_t;
+typedef VEC(spl_type_node_t) spl_type_node_vec_t;
+
+typedef MAP(usize, spl_type_id_t) spl_type_node_map_t;
+
+typedef struct {
+    spl_type_node_vec_t type_table;
+    spl_type_node_map_t type_map;
+} spl_type_t;
+
+void spl_type_init(spl_type_t *type);
+void spl_type_drop(spl_type_t *type);
+
+spl_type_node_t *spl_type_node(const spl_type_t *type, spl_type_id_t id);
+spl_type_id_t spl_type_node_push(spl_type_t *type, spl_type_node_t *type_node);
+
+spl_type_id_t spl_type_builder_simple(spl_type_t *type, spl_type_node_kind_t kind);
+spl_type_id_t spl_type_builder_int(spl_type_t *type, usize bits, int is_signed);
+spl_type_id_t spl_type_builder_float(spl_type_t *type, usize bits);
+spl_type_id_t spl_type_builder_ptr(spl_type_t *type, spl_type_id_t pointee);
+spl_type_id_t spl_type_builder_array(spl_type_t *type, spl_type_id_t element, usize len);
+spl_type_id_t spl_type_builder_fn(spl_type_t *type, spl_type_id_t ret, const spl_type_id_t *params,
+                                  usize nparams);
+spl_type_id_t spl_type_builder_agg(spl_type_t *type, spl_type_node_kind_t tk,
+                                   spl_type_member_vec_t *variants, spl_type_id_t tag_type,
+                                   spl_type_layout_t layout);
+
+void spl_type_pure_dump(spl_type_t *type, spl_type_id_t id);
+
+bool spl_type_is_subtype(const spl_type_t *type, spl_type_id_t sub, spl_type_id_t super);
+
+spl_type_id_t spl_type_fn_param_tid(spl_type_t *type, spl_type_id_t fn_tid, usize idx);
+const spl_type_member_t *spl_type_agg_member(spl_type_t *type, spl_type_id_t tid, const char *name);
+bool spl_type_agg_member_idx(spl_type_t *type, spl_type_id_t tid, const char *name, usize *out_idx);
+
+#endif /* __SPL_TYPE_H__ */

stage1/splc0.c

@@ -0,0 +1,374 @@
+/* splc0.c - SPL compiler CLI (stage 1, 引导用)
+ *
+ *   splc0 --dump tokens|ast|sema|ir|vm <file>    dump 前端产物
+ *   splc0 <in> <out>                             编译
+ */
+#define __SCC_LOG_IMPL_IMPORT_SRC__
+#include "../stage0/include/utils.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "spl_ast.h"
+#include "spl_ast2ir.h"
+#include "spl_diag.h"
+#include "spl_ir2vm.h"
+#include "spl_lexer.h"
+#include "spl_parser.h"
+#include "spl_sema.h"
+#include "spl_tok.h"
+
+typedef enum {
+    DUMP_NONE,
+    DUMP_TOKEN,
+    DUMP_AST,
+    DUMP_SEMA,
+    DUMP_IR,
+    DUMP_VM,
+} dump_t;
+
+typedef struct {
+    spl_ast_t *ast;
+    char *abs_path;
+    char *src;
+} spl_driver_module_t;
+typedef VEC(spl_driver_module_t) spl_driver_module_vec_t;
+
+typedef struct {
+    spl_ast_t main_ast;
+    spl_tok_vec_t main_toks;
+    char *main_path;
+
+    spl_driver_module_vec_t modules;
+    MAP(const char *, usize) path_to_idx;
+
+    spl_diag_t *diag;
+} spl_driver_t;
+
+static char *read_file(const char *path, long *out_len) {
+    FILE *f = fopen(path, "rb");
+    if (!f) {
+        fprintf(stderr, "path `%s` ", path);
+        perror("fopen");
+        return NULL;
+    }
+    fseek(f, 0, SEEK_END);
+    long len = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    char *buf = malloc((size_t)len + 1);
+    if (!buf) {
+        fclose(f);
+        return NULL;
+    }
+    size_t nread = fread(buf, 1, (size_t)len, f);
+    fclose(f);
+    buf[nread] = '\0';
+    if (out_len)
+        *out_len = (long)nread;
+    return buf;
+}
+
+/* 注意：按值接收，内部 vec_free 释放与调用方共享的 data 指针。
+   调用后原 vec 视为已消费，不要再使用。 */
+static void dump_tokens(spl_tok_vec_t toks) {
+    printf("tokens got (%zu)\n", toks.size);
+    for (usize i = 0; i < toks.size; i++) {
+        const spl_tok_t *t = &toks.data[i];
+        printf("[%s] %.*s (%zu:%zu)\n", spl_tok_type_name(t->type), (int)t->len, t->lexeme, t->line,
+               t->col);
+    }
+    vec_free(toks);
+}
+
+/* 把 import_path 拼接到 importing_file 所在目录。
+   from_fname 为空时按相对 cwd 处理。绝对路径直接透传。 */
+static void resolve_relative(const char *from, const char *path, char *out, usize cap) {
+    if (!from || !path) {
+        if (cap)
+            out[0] = 0;
+        return;
+    }
+    if (path[0] == '/' || path[0] == '\\' || (path[0] && path[1] == ':')) {
+        snprintf(out, cap, "%s", path);
+        return;
+    }
+    const char *last_sep = NULL;
+    for (const char *p = from; *p; ++p)
+        if (*p == '/' || *p == '\\')
+            last_sep = p;
+    if (!last_sep) {
+        snprintf(out, cap, "%s", path);
+        return;
+    }
+    usize dir_len = (usize)(last_sep - from) + 1;
+    snprintf(out, cap, "%.*s%s", (int)dir_len, from, path);
+}
+
+static spl_ast_t *driver_load(void *user, const char *from_fname, const char *path,
+                              spl_diag_t *diag) {
+    spl_driver_t *d = user;
+    char abs[1024];
+    resolve_relative(from_fname, path, abs, sizeof abs);
+
+    usize idx;
+    if (map_get(d->path_to_idx, abs, &idx)) {
+        spl_ast_t *a = vec_at(d->modules, idx).ast;
+        if (!a) {
+            spl_diag_error(diag, SPL_DIAG_KIND_CIRCULAR_DEP, NULL, "circular import: `%s`", abs);
+            return NULL;
+        }
+        return a;
+    }
+
+    /* 先登记 ast=NULL 占位：若后续解析过程中又有 @import 指回本路径，
+       会命中这里，判定为环。 */
+    char *key = strdup(abs);
+    idx = vec_size(d->modules);
+    spl_driver_module_t placeholder = {.ast = NULL, .abs_path = key, .src = NULL};
+    vec_push(d->modules, placeholder);
+    map_put(d->path_to_idx, key, idx);
+
+    long len = 0;
+    char *src = read_file(abs, &len);
+    if (!src) {
+        spl_diag_error(diag, SPL_DIAG_KIND_LEX_UNEXPECTED, NULL, "@import: cannot open `%s`", abs);
+        return NULL;
+    }
+    (void)len;
+
+    /* key 同时用作 lexer 的 fname：token.fname 与 map key 共享一份 strdup，
+       减少一次分配；cleanup 时只 free module.abs_path */
+    spl_tok_vec_t toks = spl_lex(src, key);
+    spl_ast_t *ast = malloc(sizeof *ast);
+    spl_ast_init(ast, &toks);
+    spl_parser_t parser;
+    spl_parser_init(&parser);
+    parser.diag = diag;
+    spl_ast_parse(&parser, ast);
+    spl_parser_drop(&parser);
+
+    vec_at(d->modules, idx).ast = ast;
+    vec_at(d->modules, idx).src = src;
+    return ast;
+}
+
+static int compile_spl(const char *src, const char *fname, const char *outpath, int gen_debug,
+                       dump_t dump) {
+    (void)gen_debug;
+
+    spl_diag_t diag;
+    spl_diag_init(&diag, stderr);
+
+    spl_driver_t drv = {0};
+    drv.diag = &diag;
+    drv.main_path = strdup(fname);
+    drv.main_toks = spl_lex(src, drv.main_path);
+    spl_ast_init(&drv.main_ast, &drv.main_toks);
+    map_init(drv.path_to_idx, MAP_HASH_STR, MAP_CMP_STR);
+    vec_init(drv.modules);
+
+    int rc = 0;
+
+    /* dump_tokens 消费 drv.main_toks（共享 data），之后 main_ast.input 悬空，
+       所以这条分支必须在 spl_ast_parse 之前、且不能再 drop main_ast。 */
+    if (dump == DUMP_TOKEN) {
+        dump_tokens(drv.main_toks);
+        free(drv.main_path);
+        map_free(drv.path_to_idx);
+        spl_diag_drop(&diag);
+        return 0;
+    }
+
+    spl_attr_t attr;
+    spl_lang_type_t lang_type;
+    spl_scope_t scope;
+    spl_sema_t sema;
+    spl_ast2ir_t a2ir;
+    spl_ir_builder_t ir_builder;
+    spl_ir2vm_t ir2vm;
+    spl_ast_ptr_vec_t all_asts;
+
+    int attr_ok = 0, lang_type_ok = 0, scope_ok = 0;
+    int sema_ok = 0, a2ir_ok = 0, irb_ok = 0, ir2vm_ok = 0;
+
+    spl_diag_set_stage(&diag, SPL_STAGE_PARSE);
+    spl_parser_t parser;
+    spl_parser_init(&parser);
+    parser.diag = &diag;
+    spl_ast_parse(&parser, &drv.main_ast);
+    spl_parser_drop(&parser);
+    if (spl_diag_has_error(&diag) || spl_diag_has_fatal(&diag)) {
+        spl_diag_summary(&diag);
+        rc = 1;
+        goto cleanup;
+    }
+    if (dump == DUMP_AST) {
+        spl_ast_dump(&drv.main_ast, drv.main_ast.root);
+        goto cleanup;
+    }
+
+    spl_attr_init(&attr);
+    attr_ok = 1;
+    spl_lang_type_init(&lang_type);
+    lang_type_ok = 1;
+    spl_scope_init(&scope);
+    scope_ok = 1;
+
+    spl_sema_init(&sema, &drv.main_ast, &lang_type, &scope, &attr);
+    sema_ok = 1;
+    spl_module_loader_t loader = {.load = driver_load, .user = &drv};
+    sema.loader = &loader;
+    spl_diag_set_stage(&diag, SPL_STAGE_SEMA);
+    sema.diag = &diag;
+    spl_sema_run(&sema);
+    if (spl_diag_has_error(&diag) || spl_diag_has_fatal(&diag)) {
+        spl_diag_summary(&diag);
+        rc = 1;
+        goto cleanup;
+    }
+    if (dump == DUMP_SEMA) {
+        spl_sema_dump(&sema);
+        spl_ast_dump(&drv.main_ast, drv.main_ast.root);
+        goto cleanup;
+    }
+
+    /* 收集所有 ast：主文件在前，被 import 的文件按加载顺序在后。
+       ast2ir 内部会 vec_free(all_asts)。 */
+    vec_init(all_asts);
+    vec_push(all_asts, &drv.main_ast);
+    for (usize i = 0; i < vec_size(drv.modules); ++i)
+        vec_push(all_asts, vec_at(drv.modules, i).ast);
+
+    spl_ir_builder_init(&ir_builder);
+    irb_ok = 1;
+    spl_ast2ir_init(&a2ir, &ir_builder, &sema);
+    a2ir_ok = 1;
+    spl_diag_set_stage(&diag, SPL_STAGE_AST2IR);
+    a2ir.diag = &diag;
+    spl_ast2ir_run(&a2ir, all_asts);
+    if (spl_diag_has_error(&diag) || spl_diag_has_fatal(&diag)) {
+        spl_diag_summary(&diag);
+        rc = 1;
+        goto cleanup;
+    }
+    if (dump == DUMP_IR) {
+        spl_ir_dump(&ir_builder.ir, &lang_type.ir, &attr);
+        goto cleanup;
+    }
+
+    spl_ir2vm_init(&ir2vm, &a2ir.ir->ir, &lang_type.ir, &attr);
+    ir2vm_ok = 1;
+    spl_diag_set_stage(&diag, SPL_STAGE_IR2VM);
+    ir2vm.diag = &diag;
+    rc = spl_ir2vm_run(&ir2vm);
+    if (spl_diag_has_error(&diag) || spl_diag_has_fatal(&diag)) {
+        spl_diag_summary(&diag);
+        goto cleanup;
+    }
+    if (dump == DUMP_VM) {
+        spl_prog_dump(&ir2vm.prog);
+        goto cleanup;
+    }
+
+    spl_prog_store_to_file(outpath, &ir2vm.prog);
+    rc = 0;
+
+cleanup:
+    if (ir2vm_ok)
+        spl_ir2vm_drop(&ir2vm);
+    if (a2ir_ok)
+        spl_ast2ir_drop(&a2ir);
+    if (irb_ok)
+        spl_ir_builder_drop(&ir_builder);
+    if (sema_ok)
+        spl_sema_drop(&sema);
+    if (scope_ok)
+        spl_scope_drop(&scope);
+    if (lang_type_ok)
+        spl_lang_type_drop(&lang_type);
+    if (attr_ok)
+        spl_attr_drop(&attr);
+
+    spl_ast_drop(&drv.main_ast);
+    for (usize i = 0; i < vec_size(drv.modules); ++i) {
+        spl_ast_t *a = vec_at(drv.modules, i).ast;
+        if (a) {
+            spl_ast_drop(a);
+            free(a);
+        }
+        free(vec_at(drv.modules, i).abs_path);
+        free(vec_at(drv.modules, i).src);
+    }
+    vec_free(drv.modules);
+    /* map 的 key 是 module 里 strdup 出的 abs_path，已随 module 释放 */
+    map_free(drv.path_to_idx);
+    free(drv.main_path);
+    spl_diag_drop(&diag);
+    return rc;
+}
+
+int main(int argc, char **argv) {
+    if (argc < 2) {
+        LOG_FATAL("Usage: splc0 [--dump <flags>] <in> [out]");
+        return 1;
+    }
+    if (strcmp(argv[1], "--help") == 0 || strcmp(argv[1], "-h") == 0) {
+        LOG_INFO("splc0 <in> <out>              compile (.spl -> .sir, stage B)");
+        LOG_INFO("splc0 --dump <flags> <file>   dump: lex,ast,sema,ir,vm,none");
+        return 0;
+    }
+    int argi = 1;
+    if (argi >= argc) {
+        LOG_FATAL("Usage: splc0 [--dump <flags>] <in> [out]");
+        return 1;
+    }
+
+    dump_t dump = DUMP_NONE;
+    if (strcmp(argv[argi], "--dump") == 0) {
+        if (argc < argi + 3) {
+            LOG_INFO("splc0: --dump need <flags> <file>");
+            return 1;
+        }
+
+        const char *flags = argv[argi + 1];
+        if (strcmp(flags, "lex") == 0) {
+            dump = DUMP_TOKEN;
+        } else if (strcmp(flags, "ast") == 0) {
+            dump = DUMP_AST;
+        } else if (strcmp(flags, "sema") == 0) {
+            dump = DUMP_SEMA;
+        } else if (strcmp(flags, "ir") == 0) {
+            dump = DUMP_IR;
+        } else if (strcmp(flags, "vm") == 0) {
+            dump = DUMP_VM;
+        } else if (strcmp(flags, "none") == 0) {
+            dump = DUMP_NONE;
+        } else {
+            LOG_FATAL("splc0: --dump takes one of lex|ast|sema|ir|vm|none, got `%s`", flags);
+            return 1;
+        }
+        argi += 2;
+    }
+    /* splc0 [-g] <in> <out> */
+    if (argc < argi + 2) {
+        LOG_FATAL("Usage: splc0 <in> <out> [-g]  or  splc0 --dump <flags> <file>\n");
+        return 1;
+    }
+    int gen_debug = 0;
+    if (strcmp(argv[argi], "-g") == 0) {
+        gen_debug = 1;
+        argi++;
+    }
+    if (argc < argi + 2) {
+        LOG_FATAL("Usage: splc0 <in> <out> [-g]  or  splc0 --dump <flags> <file>\n");
+        return 1;
+    }
+    long len;
+    char *src = read_file(argv[argi], &len);
+    if (!src)
+        return 1;
+    int rc = compile_spl(src, argv[argi], argv[argi + 1], gen_debug, dump);
+    free(src);
+    return rc;
+}