stage0

stage0/include/core_map.h

@@ -0,0 +1,175 @@
+#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 size_t usize;
+
+#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)
+
+/**
+ * 插入（若键已存在则更新值）
+ * 注意：扩容使用 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)
+
+/**
+ * 查询：若找到，*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;                                                                    \
+  }))
+
+/**
+ * 删除指定键
+ */
+#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 <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/spl_cli.c

@@ -0,0 +1,55 @@
+/* spl_cli.c — SIR VM launcher
+ *
+ * Loads a compiled .sir binary and runs it via the SIR VM.
+ * Built-in syscalls are auto-registered via spl_syscall_register().
+ *
+ * Usage:
+ *   spl_cli <file.sir> [entry_point]
+ */
+
+#include "spl_ir.h"
+#include "spl_syscall.h"
+#include "spl_vm.h"
+
+#include <stdio.h>
+
+int main(int argc, const char **argv) {
+    if (argc < 2) {
+        fprintf(stderr, "Usage: spl_cli <file.sir> [entry_point]\n");
+        return 1;
+    }
+
+    const char *path = argv[1];
+    const char *entry = argc >= 3 ? argv[2] : "main";
+
+    spl_prog_t prog;
+    if (spl_prog_load_from_file(path, &prog) != 0) {
+        fprintf(stderr, "spl_cli: cannot load '%s'\n", path);
+        return 1;
+    }
+
+    spl_syscall_register(&prog);
+
+    spl_vm_t vm;
+    spl_vm_init(&vm);
+    if (spl_vm_load_prog(&vm, &prog) != 0) {
+        fprintf(stderr, "vm: prog '%s' not found\n", entry);
+        spl_prog_drop(&prog);
+        return 1;
+    }
+    if (spl_vm_prepare(&vm, entry, argc, argv, NULL) != 0) {
+        fprintf(stderr, "vm: entry point '%s' not found\n", entry);
+        spl_prog_drop(&prog);
+        return 1;
+    }
+
+    int ret = spl_vm_run_until(&vm, 0);
+    spl_vm_drop(&vm);
+    spl_prog_drop(&prog);
+
+    if (ret < 0) {
+        fprintf(stderr, "spl_cli: VM error (exit_code=%d)\n", vm.exit_code);
+        return (int)vm.exit_code;
+    }
+    return (int)vm.exit_code;
+}

stage0/spl_disasm.c

@@ -0,0 +1,76 @@
+/* spl_disasm.c — SIR bytecode disassembler
+ *
+ * Usage: spl_disasm <file.sir>
+ */
+
+#include "spl_ir.h"
+#include <stdio.h>
+
+int main(int argc, const char **argv) {
+    if (argc < 2) {
+        fprintf(stderr, "Usage: spl_disasm <file.sir>\n");
+        return 1;
+    }
+
+    spl_prog_t prog;
+    if (spl_prog_load_from_file(argv[1], &prog) != 0) {
+        fprintf(stderr, "spl_disasm: cannot load '%s'\n", argv[1]);
+        return 1;
+    }
+
+    printf(";; SPL bytecode dump: %s\n", argv[1]);
+    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_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_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_ins_t *ins = &vec_at(prog.insns, i);
+        printf("%4zd: %s", i, spl_opcode_name((spl_opcode_t)ins->opcode));
+        if (ins->type != SPL_VOID)
+            printf(" %s", spl_type_name((spl_type_t)ins->type));
+        printf(" %zd", ins->imm);
+
+        /* annotate jumps / calls */
+        if (ins->opcode == SPL_JMP || ins->opcode == SPL_BZ || ins->opcode == SPL_BNZ) {
+            long long target = (long long)i + 1 + (long long)ins->imm;
+            printf("  ; -> %zd", target);
+        } else if (ins->opcode == SPL_CALL) {
+            printf("  ; nargs=%zd, from stack", (long long)ins->imm);
+        } else if (ins->opcode == SPL_CALLI) {
+            printf("  ; indirect call");
+        } else if (ins->opcode == SPL_GADDR) {
+            printf("  ; gdata[%zd]", (long long)ins->imm);
+        }
+        printf("\n");
+    }
+
+    spl_prog_drop(&prog);
+    return 0;
+}

stage0/spl_ir.c

@@ -0,0 +1,474 @@
+/* spl_ir.c — SIR 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_ir.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);
+    map_init(prog->symtab, MAP_HASH_STR, MAP_CMP_STR);
+}
+
+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);
+}
+
+/* ---- LE read/write helpers ---- */
+
+static inline spl_val_t rd64(const unsigned char **p) {
+    spl_val_t v = (spl_val_t)(*p)[0] | ((spl_val_t)(*p)[1] << 8) | ((spl_val_t)(*p)[2] << 16) |
+                  ((spl_val_t)(*p)[3] << 24) | ((spl_val_t)(*p)[4] << 32) |
+                  ((spl_val_t)(*p)[5] << 40) | ((spl_val_t)(*p)[6] << 48) |
+                  ((spl_val_t)(*p)[7] << 56);
+    *p += 8;
+    return v;
+}
+
+static inline void wr64(unsigned char **p, spl_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_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_val_t i = 0; i < nfuncs; i++) {
+        spl_func_t func = {0};
+        spl_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_val_t i = 0; i < ninsns; i++) {
+        if ((size_t)(p - data) + 12 > (size_t)len) {
+            free(data);
+            return -1;
+        }
+        spl_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_val_t i = 0; i < nnatives; i++) {
+        spl_native_t nat = {0};
+        spl_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_val_t i = 0; i < nstrs; i++) {
+        spl_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_val_t i = 0; i < ndata; i++) {
+        spl_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);
+    }
+
+    free(data);
+    return 0;
+}
+
+int spl_prog_store_to_file(const char *fname, spl_prog_t *prog) {
+    unsigned char *buf, *p;
+    int i;
+    size_t total;
+    spl_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);
+
+    /* 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 = 0; i < ndata; 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_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 = 0; i < ndata; i++) {
+        spl_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_func(spl_prog_t *prog, spl_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_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_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 vec_size(prog->gdata);
+}
+
+spl_val_t spl_prog_emit(spl_prog_t *prog, uint16_t opcode, uint16_t type, spl_val_t imm) {
+    spl_ins_t ins = {opcode, type, imm};
+    spl_val_t addr = vec_size(prog->insns);
+    vec_push(prog->insns, ins);
+    return addr;
+}
+
+int spl_prog_add_func_simple(spl_prog_t *prog, const char *name, spl_val_t nargs) {
+    spl_func_t func = {0};
+    if (!prog || !name)
+        return -1;
+    func.name = strdup(name);
+    func.idx_of_strtab = 0;
+    func.nargs = nargs;
+    func.ninsns = 0;
+    func.address = vec_size(prog->insns);
+    vec_push(prog->funcs, func);
+    return (int)vec_size(prog->funcs) - 1;
+}
+
+void spl_prog_end_func(spl_prog_t *prog, int func_idx) {
+    if (!prog || func_idx < 0 || func_idx >= (int)vec_size(prog->funcs))
+        return;
+    spl_func_t *func = &vec_at(prog->funcs, func_idx);
+    func->ninsns = vec_size(prog->insns) - func->address;
+}
+
+int spl_prog_add_str(spl_prog_t *prog, const char *str) {
+    if (!prog || !str)
+        return -1;
+    vec_push(prog->strtab, strdup(str));
+    return (int)vec_size(prog->strtab) - 1;
+}
+
+spl_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_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_opcode_name(spl_opcode_t opcode) { return opcode_name[opcode]; }
+const char *spl_type_name(spl_type_t type) {
+    switch (type) {
+    case SPL_VOID:
+        return "void";
+    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_PTR:
+        return "ptr";
+    default:
+        return "???";
+    }
+}
+
+void spl_ins_dump(spl_ins_t *ins, spl_val_t addr) {
+    printf("%4zu: %s", addr, spl_opcode_name((spl_opcode_t)ins->opcode));
+    if (ins->type != SPL_VOID)
+        printf(" %s", spl_type_name((spl_type_t)ins->type));
+    printf(" %zd:%zx", ins->imm, ins->imm);
+    printf("\n");
+}

stage0/spl_ir.h

@@ -0,0 +1,221 @@
+/* spl_ir.h - SPL Intermediate Representation: instruction set and binary format
+ */
+
+#ifndef __SPL_IR_H__
+#define __SPL_IR_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 = 0,
+    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_type_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_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") \
+    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,    1,   1,   "print top of stack as hex")
+
+/* clang-format on */
+
+typedef enum {
+#define X(opcode, name, argc, pop, push, desc) opcode,
+    SPL_OPCODES(X)
+#undef X
+} spl_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)
+ *
+ * === Calling Convention ===
+ *
+ * Before CALL:
+ *   - args pushed left-to-right
+ *   - target address pushed last
+ *
+ * CALL (imm = nargs):
+ *   1. pop target address
+ *   2. callstack[cp++] = {saved_fp, saved_ip, nargs}
+ *   3. fp = sp - nargs    (fp points to arg0)
+ *   4. ip = target address
+ *
+ * ALLOC k:
+ *   sp += k  (slots zeroed; local[j] = stacks.data[fp + nargs + j])
+ *
+ * LADDR imm:
+ *   push &stacks.data[fp + imm]
+ *   (imm < nargs accesses args; imm >= nargs accesses locals)
+ *
+ * GADDR imm:
+ *   push prog->gdata[imm]  (pointer to global data blob)
+ *
+ * RET:
+ *   1. pop retval if non-void type
+ *   2. sp = fp
+ *   3. pop frame; fp = saved_fp, ip = saved_ip
+ *   4. push retval if non-void type
+ *
+ * CALLI (indirect call):
+ *   - stack before:  ..., arg0, ..., argN-1, nargs, func_addr
+ *   1. pop func_addr, then pop nargs
+ *   2. same as CALL steps 2-4
+ */
+
+#define SPL_BINFMT_MAGIC "SPLBIN\0\0"
+// All SIR stack values are ptr-bit unsigned integers
+typedef usize spl_val_t;
+
+typedef struct spl_ins {
+    uint8_t opcode;
+    uint8_t type;
+    spl_val_t imm;
+} spl_ins_t;
+typedef VEC(spl_ins_t) spl_ins_vec_t;
+
+typedef struct spl_func {
+    char *name;
+    spl_val_t idx_of_strtab;
+    spl_val_t nargs;
+    spl_val_t ninsns;
+    spl_val_t address;
+} spl_func_t;
+typedef VEC(spl_func_t) spl_func_vec_t;
+
+/* Native function pointer type */
+typedef spl_val_t (*spl_fn_t)(int nargs, spl_val_t *args);
+typedef struct spl_native {
+    char *name;
+    spl_val_t idx_of_strtab;
+    spl_fn_t impl_fn;
+} spl_native_t;
+typedef VEC(spl_native_t) spl_native_vec_t;
+
+typedef struct {
+    unsigned char *data;
+    usize size;
+} spl_gdata_t;
+typedef VEC(spl_gdata_t) spl_data_t;
+typedef VEC(const char *) spl_strtab_t;
+typedef MAP(const char *, const char *) spl_symtab_t;
+/* Opaque handle for loaded program */
+typedef struct spl_prog {
+    spl_ins_vec_t insns;
+    spl_func_vec_t funcs;
+    spl_native_vec_t natives;
+    spl_data_t gdata;
+    spl_strtab_t strtab;
+    spl_symtab_t symtab;
+} spl_prog_t;
+
+void spl_prog_init(spl_prog_t *prog);
+void spl_prog_drop(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_data(spl_prog_t *prog, void *ptr, usize size);
+int spl_prog_add_func(spl_prog_t *prog, spl_func_t *func);
+int spl_prog_add_native(spl_prog_t *prog, spl_native_t *native);
+
+spl_func_t *spl_prog_get_func(spl_prog_t *prog, const char *name);
+spl_native_t *spl_prog_get_native(spl_prog_t *prog, const char *name);
+
+/* High-level program construction helpers */
+spl_val_t spl_prog_emit(spl_prog_t *prog, uint16_t opcode, uint16_t type, spl_val_t imm);
+int spl_prog_add_func_simple(spl_prog_t *prog, const char *name, spl_val_t nargs);
+void spl_prog_end_func(spl_prog_t *prog, int func_idx);
+int spl_prog_add_str(spl_prog_t *prog, const char *str);
+
+/* Opcode name lookup for debugging/dumping */
+const char *spl_opcode_name(spl_opcode_t opcode);
+const char *spl_type_name(spl_type_t type);
+
+void spl_ins_dump(spl_ins_t *ins, spl_val_t addr);
+
+#endif /* __SPL_IR_H__ */

stage0/spl_syscall.c

@@ -0,0 +1,329 @@
+/* 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 "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_val_t name(int nargs, spl_val_t *args) {                                            \
+        CHECK_NARGS(#name, 0);                                                                     \
+        (void)args;                                                                                \
+        return (spl_val_t)(uintptr_t)(ret_expr);                                                   \
+    }
+
+#define SYSCALL_1(name, t1, ret_expr)                                                              \
+    static spl_val_t name(int nargs, spl_val_t *args) {                                            \
+        CHECK_NARGS(#name, 1);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        return (spl_val_t)(uintptr_t)(ret_expr);                                                   \
+    }
+
+#define SYSCALL_2(name, t1, t2, ret_expr)                                                          \
+    static spl_val_t name(int nargs, spl_val_t *args) {                                            \
+        CHECK_NARGS(#name, 2);                                                                     \
+        t1 a1 = (t1)(uintptr_t)args[0];                                                            \
+        t2 a2 = (t2)(uintptr_t)args[1];                                                            \
+        return (spl_val_t)(uintptr_t)(ret_expr);                                                   \
+    }
+
+#define SYSCALL_3(name, t1, t2, t3, ret_expr)                                                      \
+    static spl_val_t name(int nargs, spl_val_t *args) {                                            \
+        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_val_t)(uintptr_t)(ret_expr);                                                   \
+    }
+
+#define SYSCALL_4(name, t1, t2, t3, t4, ret_expr)                                                  \
+    static spl_val_t name(int nargs, spl_val_t *args) {                                            \
+        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_val_t)(uintptr_t)(ret_expr);                                                   \
+    }
+
+/* =================================================================
+ * OS syscalls
+ * ================================================================= */
+
+/* os_exit — terminate process with the given exit code */
+SYSCALL_1(os_exit, int, (exit(a1), (spl_val_t)0))
+
+/* os_putchar — write a single character to stdout */
+SYSCALL_1(os_putchar, int, putchar(a1))
+
+/* os_getchar — read a single character from stdin */
+SYSCALL_0(os_getchar, getchar())
+
+/* os_putint — print an integer to stdout */
+SYSCALL_1(os_putint, int, (fprintf(stdout, "%d", a1), (spl_val_t)0))
+
+/* os_putstr — print a string to stdout (no trailing newline) */
+SYSCALL_1(os_putstr, const char *, (fputs(a1, stdout), (spl_val_t)0))
+
+/* os_fopen — open a file, returns FILE* as spl_val_t */
+SYSCALL_2(os_fopen, const char *, const char *, (uintptr_t)fopen(a1, a2))
+
+/* os_fclose — close a file, returns 0 on success */
+SYSCALL_1(os_fclose, FILE *, fclose(a1))
+
+/* os_fread — read from file, returns number of items read */
+SYSCALL_4(os_fread, void *, size_t, size_t, FILE *, fread(a1, a2, a3, a4))
+
+/* os_fwrite — write to file, returns number of items written */
+SYSCALL_4(os_fwrite, const void *, size_t, size_t, FILE *, fwrite(a1, a2, a3, a4))
+
+/* os_fsize — get file size in bytes */
+static spl_val_t os_fsize(int nargs, spl_val_t *args) {
+    CHECK_NARGS("os_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_val_t)(uintptr_t)sz;
+}
+
+/* os_read_file — read entire file into a malloc'd, null-terminated buffer */
+static spl_val_t os_read_file(int nargs, spl_val_t *args) {
+    CHECK_NARGS("os_read_file", 1);
+    const char *path = (const char *)(uintptr_t)args[0];
+    FILE *f = fopen(path, "rb");
+    if (!f)
+        return 0;
+    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_val_t)(uintptr_t)buf;
+}
+
+/* os_alloc — allocate memory (malloc) */
+SYSCALL_1(os_alloc, size_t, (uintptr_t)malloc(a1))
+
+/* os_free — free memory */
+SYSCALL_1(os_free, void *, (free(a1), (spl_val_t)0))
+
+/* os_realloc — reallocate memory (realloc) */
+SYSCALL_2(os_realloc, void *, size_t, (uintptr_t)realloc(a1, a2))
+
+/* os_strlen — get string length */
+SYSCALL_1(os_strlen, const char *, strlen(a1))
+
+/* os_strcmp — compare two strings */
+SYSCALL_2(os_strcmp, const char *, const char *, strcmp(a1, a2))
+
+/* os_memcpy — copy memory, returns dst */
+SYSCALL_3(os_memcpy, void *, const void *, size_t, (memcpy(a1, a2, a3), (uintptr_t)a1))
+
+/* =================================================================
+ * 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_val_t vm_new(int nargs, spl_val_t *args) {
+    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_val_t)(uintptr_t)vm;
+}
+
+/* vm_drop — destroy a sub-VM and its loaded program */
+static spl_val_t vm_drop(int nargs, spl_val_t *args) {
+    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_val_t vm_load(int nargs, spl_val_t *args) {
+    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_val_t)(uintptr_t)prog;
+}
+
+/* vm_push — push a value onto the sub-VM's stack (for passing arguments) */
+static spl_val_t vm_push(int nargs, spl_val_t *args) {
+    CHECK_NARGS("vm_push", 2);
+    spl_vm_t *vm = (spl_vm_t *)(uintptr_t)args[0];
+    spl_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_val_t vm_call(int nargs, spl_val_t *args) {
+    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_val_t call_nargs = args[2];
+    if (!vm || !name)
+        return -1;
+
+    spl_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_native_t table[] = {
+        /* OS operations */
+        {"os_exit", 0, os_exit},
+        {"os_putchar", 0, os_putchar},
+        {"os_getchar", 0, os_getchar},
+        {"os_putint", 0, os_putint},
+        {"os_putstr", 0, os_putstr},
+        {"os_fopen", 0, os_fopen},
+        {"os_fclose", 0, os_fclose},
+        {"os_fread", 0, os_fread},
+        {"os_fwrite", 0, os_fwrite},
+        {"os_fsize", 0, os_fsize},
+        {"os_read_file", 0, os_read_file},
+        {"os_alloc", 0, os_alloc},
+        {"os_free", 0, os_free},
+        {"os_realloc", 0, os_realloc},
+        {"os_strlen", 0, os_strlen},
+        {"os_strcmp", 0, os_strcmp},
+        {"os_memcpy", 0, os_memcpy},
+        /* 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_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_ir.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,66 @@
+/* spl_vm.h — SIR interpreter */
+
+#ifndef __SPL_VM_H__
+#define __SPL_VM_H__
+
+#include "include/core_vec.h"
+#include "spl_ir.h"
+#include <stdint.h>
+
+#define SPL_STACK_CANARY ((spl_val_t)0xDEADBEEFCAFEBABEull)
+
+typedef struct {
+    uintptr_t saved_fp;
+    uintptr_t saved_ip;
+    spl_val_t nargs;
+} spl_callframe_t;
+
+typedef VEC(spl_val_t) spl_stack_vec_t;
+typedef VEC(spl_callframe_t) spl_frame_vec_t;
+
+typedef struct {
+    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 */
+    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_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);
+
+void spl_vm_dump_instr(spl_vm_t *vm, spl_val_t ip);
+void spl_vm_stackdump(spl_vm_t *vm, spl_val_t sp);
+int spl_vm_backtrace(spl_vm_t *vm, spl_val_t fp);
+
+#endif /* __SPL_VM_H__ */

stage0/test_spl_vm.c

@@ -0,0 +1,876 @@
+/* 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_ir.h"
+#include "spl_vm.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ================================================================
+ * Binary-writing helpers (mirrors spl_ir.c internal format)
+ * ================================================================ */
+
+/* Write spl_val_t (8 LE bytes), advance pointer */
+#define LE64(p, v)                                                                                 \
+    do {                                                                                           \
+        unsigned char *_p = (p);                                                                   \
+        spl_val_t _v = (spl_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_ins_t ins(uint16_t op, uint16_t type, spl_val_t imm) {
+    spl_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_val_t nargs, const spl_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_val_t)ninsns); /* ninsns */
+    LE64(p, 0);                 /* nnatives */
+    LE64(p, 0);                 /* nstrs */
+    LE64(p, 0);                 /* ndata */
+
+    /* func entry */
+    LE64(p, (spl_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_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_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_ins_t *instns, int ninsns, spl_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_val_t native_add_impl(int nargs, spl_val_t *args) {
+    return (nargs >= 2) ? args[0] + args[1] : 0;
+}
+
+/* ================================================================
+ * Stack tests
+ * ================================================================ */
+
+void test_push_imm(void) {
+    spl_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_ins_t p[] = {ins(SPL_PUSH, SPL_I32, (spl_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_ins_t add_insns[] = {ins(SPL_LADDR, SPL_VOID, 0), ins(SPL_LOAD, SPL_I64, 0),
+                             ins(SPL_LADDR, SPL_VOID, 1), ins(SPL_LOAD, SPL_I64, 0),
+                             ins(SPL_ADD, SPL_I64, 0),    ins(SPL_RET, SPL_I64, 0)};
+    spl_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_val_t)ninsns_t);
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, 0);
+
+    /* func[0]: "add" */
+    LE64(p, (spl_val_t)nlen0);
+    memcpy(p, "add", nlen0);
+    p += nlen0;
+    memset(p, 0, npad0);
+    p += npad0;
+    LE64(p, 0);
+    LE64(p, 2);
+    LE64(p, (spl_val_t)nadd);
+    LE64(p, 0);
+
+    /* func[1]: "main" */
+    LE64(p, (spl_val_t)nlen1);
+    memcpy(p, "main", nlen1);
+    p += nlen1;
+    memset(p, 0, npad1);
+    p += npad1;
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, (spl_val_t)nmain);
+    LE64(p, (spl_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_ins_t add_insns[] = {ins(SPL_LADDR, SPL_VOID, 0), ins(SPL_LOAD, SPL_I64, 0),
+                             ins(SPL_LADDR, SPL_VOID, 1), ins(SPL_LOAD, SPL_I64, 0),
+                             ins(SPL_ADD, SPL_I64, 0),    ins(SPL_RET, SPL_I64, 0)};
+    spl_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_val_t)ninsns_t);
+    LE64(p, 0);
+    LE64(p, 0);
+    LE64(p, 0);
+
+    /* func[0]: add */
+    LE64(p, (spl_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_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_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_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_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_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_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_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_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_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_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_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_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},
+};