Surface stack interp trap reasons through the globals header

The iOS C stack interp only distinguished watchdog cancellation
structurally; assertion-failed and call-stack-overflow traps were
stringly set on ctx->error and printed to stderr. Host callers had
no way to branch on the trap kind via read_trap_reason() the way
they can on the JIT/LLVM paths.

Add a numeric trap_reason to the C Ctx set alongside each ctx->error
assignment (and on cancel), mirror it in the Rust bridge, and reserve
CANCEL_FLAG_RESERVED bytes at the start of stack_codegen globals so
the FFI iOS path can write the reason into TRAP_REASON_OFFSET. The
entry-point call now returns false for any trap, matching the LLVM
setjmp semantics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wtholliday

src/compiler.rs

@@ -1749,7 +1749,8 @@ mod tests {
         assert!(compiler.check(), "type check failed");
         compiler.specialize().expect("specialize failed");
 
-        let globals_info = compiler.globals_info_with_offset(0);
+        let globals_info =
+            compiler.globals_info_with_offset(crate::cancel::CANCEL_FLAG_RESERVED as usize);
         let input_offset = globals_info
             .iter()
             .find(|g| g.0 == "input")

src/ffi.rs

@@ -395,7 +395,8 @@ pub unsafe extern "C" fn lyte_compiler_compile(ptr: *mut LyteCompiler) -> *mut L
             match c.compiler.compile_stack() {
                 Ok(stack_program) => {
                     let globals_size = stack_program.globals_size;
-                    let globals_info = make_globals_info(0);
+                    let globals_info =
+                        make_globals_info(crate::cancel::CANCEL_FLAG_RESERVED as usize);
 
                     let mut entry_points = Vec::new();
                     for ep_name in &entry_point_names {
@@ -639,8 +640,18 @@ pub unsafe extern "C" fn lyte_entry_point_call(
         program
             .backend
             .set_cancel_callback(program.cancel_callback, program.cancel_userdata);
+        // Clear any prior trap reason so read_trap_reason() reflects only
+        // this invocation even if the caller reuses the globals buffer.
+        *(globals.add(crate::cancel::TRAP_REASON_OFFSET as usize) as *mut u32) =
+            crate::cancel::TRAP_NONE;
         program.backend.call_entry(ep.func_idx, globals);
-        result = !program.backend.cancelled();
+        let reason = program.backend.trap_reason();
+        // Mirror the structural trap reason into the globals header so
+        // read_trap_reason() works uniformly across JIT/LLVM/VM/stack.
+        *(globals.add(crate::cancel::TRAP_REASON_OFFSET as usize) as *mut u32) = reason;
+        // Any trap (cancelled / call-stack-overflow / assertion-failed)
+        // surfaces as a failed call, matching the LLVM setjmp path.
+        result = reason == crate::cancel::TRAP_NONE;
     }
 
     // Clear print callback.

src/stack_codegen.rs

@@ -91,8 +91,15 @@ impl StackCodegen {
     }
 
     /// Collect global variables and compute their offsets.
+    ///
+    /// Reserves `CANCEL_FLAG_RESERVED` bytes at the start of the globals
+    /// buffer for the cancel/trap header (cancel counter, callback,
+    /// trap_reason, jmp_buf). The header layout matches the one used by
+    /// the JIT/LLVM backends, which lets the FFI layer write the stack
+    /// interp's structural trap reason to `TRAP_REASON_OFFSET` so hosts
+    /// can call `read_trap_reason(globals)` uniformly across backends.
     fn declare_globals(&mut self, decls: &DeclTable) {
-        let mut offset: i32 = 0;
+        let mut offset: i32 = crate::cancel::CANCEL_FLAG_RESERVED;
         for decl in &decls.decls {
             match decl {
                 Decl::Global {

src/stack_interp.c

@@ -35,6 +35,7 @@ static int enter_function(Ctx* ctx, uint32_t func_idx, uint64_t** out_locals) {
     size_t fs_needed = fs_base + total_slots;
     if (fs_needed > ctx->frame_stack_cap) {
         ctx->error = "stack overflow";
+        ctx->trap_reason = STACK_TRAP_CALL_STACK_OVERFLOW;
         ctx->done = 1;
         *out_locals = NULL;
         return 0;
@@ -178,6 +179,7 @@ static int64_t ipow(int64_t base, uint32_t exp) {
             ctx->cancel_counter = CANCEL_CHECK_INTERVAL; \
             if (ctx->cancel_callback && ctx->cancel_callback(ctx->cancel_userdata)) { \
                 ctx->cancelled = true; \
+                ctx->trap_reason = STACK_TRAP_CANCELLED; \
                 ctx->done = 1; \
                 return; \
             } \
@@ -676,6 +678,7 @@ HANDLER(op_call) {
 
     if (ctx->call_depth >= ctx->call_stack_cap) {
         ctx->error = "call stack overflow";
+        ctx->trap_reason = STACK_TRAP_CALL_STACK_OVERFLOW;
         ctx->done = 1;
         return;
     }
@@ -776,6 +779,7 @@ HANDLER(op_call_closure) {
 
     if (ctx->call_depth >= ctx->call_stack_cap) {
         ctx->error = "call stack overflow";
+        ctx->trap_reason = STACK_TRAP_CALL_STACK_OVERFLOW;
         ctx->done = 1;
         return;
     }
@@ -851,6 +855,7 @@ HANDLER(op_call_indirect) {
 
     if (ctx->call_depth >= ctx->call_stack_cap) {
         ctx->error = "call stack overflow";
+        ctx->trap_reason = STACK_TRAP_CALL_STACK_OVERFLOW;
         ctx->done = 1;
         return;
     }
@@ -1033,6 +1038,7 @@ HANDLER(op_assert) {
     fflush(stdout);
     if (val == 0) {
         ctx->error = "assertion failed";
+        ctx->trap_reason = STACK_TRAP_ASSERTION_FAILED;
         ctx->done = 1;
         return; // Break the tail-call chain back to stack_interp_run.
     }
@@ -1787,6 +1793,7 @@ int64_t stack_interp_run(Ctx* ctx, uint32_t entry_func) {
     ctx->done = 0;
     ctx->result = 0;
     ctx->error = NULL;
+    ctx->trap_reason = STACK_TRAP_NONE;
     ctx->frame_stack_size = 0;
     ctx->call_depth = 0;
     ctx->cancelled = false;

src/stack_interp.h

@@ -17,6 +17,13 @@
 // CancelCallback in src/cancel.rs.
 typedef bool (*CancelCallback)(void* user_data);
 
+// Trap reason codes. Must stay in sync with TRAP_* in src/cancel.rs so
+// the host can read ctx->trap_reason uniformly across backends.
+#define STACK_TRAP_NONE                0u
+#define STACK_TRAP_CANCELLED           1u
+#define STACK_TRAP_CALL_STACK_OVERFLOW 2u
+#define STACK_TRAP_ASSERTION_FAILED    3u
+
 // Instruction encoding: 32 bytes (4 x u64).
 // [0] handler function pointer
 // [1] imm0 (local index, constant, jump offset, etc.)
@@ -104,6 +111,13 @@ typedef struct Ctx {
     // Set to true if the callback returned true. The host distinguishes
     // a clean exit from cancellation by reading this after run() returns.
     bool           cancelled;
+
+    // Structural trap reason set alongside `error` at each trap site (and
+    // on cancellation). Lets the host distinguish assertion-failed vs
+    // call-stack-overflow vs cancelled without string matching. Matches
+    // the TRAP_* codes in src/cancel.rs so read_trap_reason() in the
+    // globals buffer can surface the same value across backends.
+    uint32_t       trap_reason;
 } Ctx;
 
 // Handler function signature.

src/stack_interp_bridge.rs

@@ -50,6 +50,7 @@ struct Ctx {
     cancel_userdata: *mut u8,
     cancel_counter: i32,
     cancelled: bool,
+    trap_reason: u32,
 }
 
 extern "C" {
@@ -803,6 +804,7 @@ impl StackBackend {
             cancel_userdata: std::ptr::null_mut(),
             cancel_counter: crate::cancel::CANCEL_CHECK_INTERVAL,
             cancelled: false,
+            trap_reason: crate::cancel::TRAP_NONE,
         };
 
         Self {
@@ -832,6 +834,13 @@ impl StackBackend {
         self.ctx.cancelled
     }
 
+    /// Structural trap reason from the most recent `call_entry`. Matches
+    /// the TRAP_* constants in `crate::cancel` so the host can handle
+    /// this value the same way as `read_trap_reason()` on JIT/LLVM.
+    pub fn trap_reason(&self) -> u32 {
+        self.ctx.trap_reason
+    }
+
     /// Run `entry_func` with the given external globals buffer.
     /// The globals buffer must remain valid for the duration of the call.
     pub fn call_entry(&mut self, entry_func: u32, external_globals: *mut u8) -> i64 {
@@ -882,5 +891,38 @@ mod tests {
             backend.cancelled(),
             "expected the C interp's infinite loop to be cancelled"
         );
+        assert_eq!(
+            backend.trap_reason(),
+            crate::cancel::TRAP_CANCELLED,
+            "cancel callback should surface as TRAP_CANCELLED"
+        );
+    }
+
+    #[test]
+    fn test_assert_failure_surfaces_trap_reason() {
+        // `0 debug.assert` fires the assertion trap. The bridge should
+        // expose it as TRAP_ASSERTION_FAILED instead of only printing to
+        // stderr — this is the iOS gap vs. the LLVM/JIT path.
+        let mut func = StackFunction::new("entry");
+        func.emit(StackOp::I64Const(0));
+        func.emit(StackOp::Assert);
+        func.local_count = 3; // min scalar slots used by enter_function
+
+        let mut program = StackProgram::new();
+        program.entry = program.add_function(func);
+
+        let mut backend = StackBackend::new(&program);
+        let mut globals: Vec<u8> = vec![0u8; program.globals_size.max(1)];
+        backend.call_entry(program.entry, globals.as_mut_ptr());
+
+        assert!(
+            !backend.cancelled(),
+            "assertion trap is not a cancellation"
+        );
+        assert_eq!(
+            backend.trap_reason(),
+            crate::cancel::TRAP_ASSERTION_FAILED,
+            "failed debug.assert should surface as TRAP_ASSERTION_FAILED"
+        );
     }
 }