fix: io.zig trace state not thread-local; deterministic ghost trace events from std bootstrap; wire engine-api-test into CI

Three follow-ups to the engine C-API race fix:

1. io.zig's write/read overrides and trace state (write_override,
   werr_override, read_override, g_trace_fn, g_trace_userdata,
   g_trace_handle, g_trace_prev_line) had the same non-thread-local pattern
   as engine.zig/host_abi.zig's already-fixed fields. Made all threadlocal.

2. The pre-existing "engine_set_trace_fn fires per source line" failure
   was assumed to be order-dependent test pollution, but a debug print
   showed the exact same {1, 7, 1, 2, 3} line sequence on every run --
   fully deterministic, since engine.zig's native test runner
   (tools/standalone_runner.zig) runs tests in fixed file order with no
   shuffling. Root cause: vm.zig's dispatchTick fired a trace event for
   every instruction while active, including the embedded std-library
   bootstrap bytecode every program executes at startup (defining
   std.array.count and friends as globals) regardless of whether the
   script references std. The ghost 1 and 7 were two instructions from
   that bootstrap's own function definition, using array.gengo's own line
   numbers colliding with the user script's. Fixed by skipping trace
   firing for ip < chunk_state.std_script_code_end.

3. engine-api-test (144 tests) was never wired into `zig build test`, so
   it never ran in CI or the pre-push hook -- including the previous
   commit's new concurrency regression test. Wired it into the main test
   step. This surfaced two more tests with heap/object/stack/frame/defer
   sizes hardcoded to the default preset, exceeding -Dpreset=stress's
   tighter ceilings; both now scale to whatever ceiling
   engine_init_with_config actually enforces.

Verified under standard, -Dpreset=stress, and -Dgc_stress=true builds,
each now including engine-api-test.

Author: ganehag

CHANGELOG.md

@@ -4,6 +4,53 @@ This changelog tracks notable language/runtime changes by implementation date.
 
 ## 2026-08-21
 
+### Fix — the two follow-ups flagged after the engine C-API race fix
+
+The previous fix (below) left two things flagged rather than fixed. Both
+addressed now:
+
+1. **`io.zig`'s trace state was the same non-thread-local pattern.** Fixed
+   by making `write_override`/`werr_override`/`read_override`/`g_trace_fn`/
+   `g_trace_userdata`/`g_trace_handle`/`g_trace_prev_line` all `threadlocal`,
+   matching `engine.zig`/`host_abi.zig`.
+
+2. **The pre-existing `engine_set_trace_fn fires per source line` failure
+   was real, not flaky — and not test-order pollution as first suspected.**
+   `engine.zig`'s native test runner (`tools/standalone_runner.zig`) runs
+   `builtin.test_functions` in fixed file-declaration order with no
+   shuffling, so the failure was 100% deterministic (confirmed via a debug
+   print showing the exact same `{1, 7, 1, 2, 3}` line sequence on every
+   run — not `{1, 2, 3}` as the test expected). Root cause: `dispatchTick`
+   (`vm.zig`) fired a trace event for every instruction while a trace
+   callback was active, including the embedded std-library bootstrap
+   bytecode every program executes at startup regardless of whether it
+   references `std` (defining `std.array.count` and friends as globals) —
+   the ghost `1` and `7` were two instructions from that bootstrap's own
+   `count` function definition (line 1 and line 7, `array.gengo`'s own
+   line numbers, colliding with the user script's line numbers in the
+   trace stream). Fixed by skipping trace firing for
+   `ip < chunk_state.std_script_code_end` (0, hence a no-op, when std
+   scripts weren't compiled in — e.g. the REPL) — a host's line-level
+   tracer should never see line numbers from a library implementation
+   detail the embedding user didn't write and can't map back to their own
+   source, whether that's the once-per-program bootstrap or a genuine call
+   into a std-library function implemented in Gengoscript itself.
+
+3. **`engine-api-test` (144 tests, including both fixes above and the
+   previous race-condition regression test) is now wired into `zig build
+   test`**, so it runs under every CI lane and the pre-push hook instead of
+   never running at all. This surfaced two more pre-existing tests
+   (`engine_call converts wires in the selected engine heap`,
+   `engine_call converts a large host-supplied wire array without
+   corrupting elements under heap pressure`) that hardcoded heap/object/
+   stack/frame/defer sizes tuned only to the default preset — both now
+   scale to whatever preset's ceiling `engine_init_with_config` actually
+   enforces, verified passing under `-Dpreset=stress`'s much tighter
+   limits specifically, not just the default preset.
+
+Verified under standard, `-Dpreset=stress`, and `-Dgc_stress=true` builds,
+each including the newly-wired `engine-api-test` step.
+
 ### Fix — cross-thread engine C-API race: wrong callback (and ctx) could serve the wrong engine
 
 Follow-up to an independent LLM's Tengo-vs-Gengo comparison, which flagged

build.zig

@@ -451,6 +451,13 @@ pub fn build(b: *std.Build) void {
     test_step.dependOn(&run_vm_safety.step);
     test_step.dependOn(&run_vm_value.step);
     test_step.dependOn(&run_embedding.step);
+    // engine.zig's own native test suite (engine_api_test, ~144 tests)
+    // was never wired into `test` — same class of gap as src/main.zig's
+    // tests above (found 2026-08-19). Discovered while adding a
+    // regression test for a real cross-thread engine C-API race
+    // (2026-08-21): the test caught the bug, but nothing in `zig build
+    // test` or the pre-push hook would ever have run it.
+    test_step.dependOn(&run_engine_api_tests.step);
     test_step.dependOn(&run_engine_runner.step);
     test_step.dependOn(&run_fuzz_runner.step);
     test_step.dependOn(&install_engine_debug.step);

src/engine.zig

@@ -1568,12 +1568,20 @@ test "engine_call rejects deeply nested host-supplied wire arguments instead of
 }
 
 test "engine_call converts wires in the selected engine heap" {
+    // engine_init_with_config rejects any field above the build's compiled-in
+    // preset ceiling (engine_init_with_config's validateCeiling calls, by
+    // design — an embedder can't request more than the build allows). Clamp
+    // every field to the ambient ceiling so this test passes under every
+    // preset (found failing under -Dpreset=stress's 256KB/512-object/
+    // 128-stack/16-frame/32-defer ceilings, all below this test's original
+    // fixed request) instead of hardcoding values tuned to only the default
+    // preset.
     const config: InstanceConfig = .{
-        .heap_size_bytes = 1024 * 1024,
-        .max_objects = 2048,
-        .max_stack = 512,
-        .max_frames = 64,
-        .max_defers = 128,
+        .heap_size_bytes = @min(cfg.heap_size_bytes, 1024 * 1024),
+        .max_objects = @min(cfg.max_objects, 2048),
+        .max_stack = @min(cfg.max_stack, 512),
+        .max_frames = @min(cfg.max_frames, 64),
+        .max_defers = @min(cfg.max_defers, 128),
         .max_ops = -1,
         .allow_io = false,
     };
@@ -1592,7 +1600,14 @@ test "engine_call converts wires in the selected engine heap" {
     const second_engine = getEngine(second).?;
     second_engine.runtime.inner.activate();
     const second_ctx = vms.VMContext.fromActive();
-    var ballast: [60000]u8 = undefined;
+    // Scaled to the actual (possibly preset-clamped) heap size above, not a
+    // fixed 60000 — under -Dpreset=stress's 256KB ceiling, 14 * 60000-byte
+    // roots alone (840KB) would overflow the heap before the test's own
+    // assertions ever ran. /24 leaves comfortable headroom for the compiled
+    // function and chunk/globals overhead under every preset while still
+    // filling most of the heap (genuine pressure) under the default preset.
+    const ballast_size = config.heap_size_bytes / 24;
+    var ballast: [ballast_size]u8 = undefined;
     @memset(&ballast, 'b');
     var roots: [14]Value = undefined;
     for (&roots) |*root| {
@@ -1603,7 +1618,7 @@ test "engine_call converts wires in the selected engine heap" {
         for (roots) |_| second_ctx.vs.popTempRoot();
     }
 
-    var data: [60000]u8 = undefined;
+    var data: [ballast_size]u8 = undefined;
     @memset(&data, 'a');
     var arg: ValueWire = .{
         .tag = @intFromEnum(WireTag.string),
@@ -1641,12 +1656,16 @@ test "engine_call converts wires in the selected engine heap" {
 // is primarily a correctness check for large host-supplied wire arrays
 // under a small, tightly configured heap.
 test "engine_call converts a large host-supplied wire array without corrupting elements under heap pressure" {
+    // See the previous test's comment: engine_init_with_config rejects any
+    // field above the build's compiled-in preset ceiling, and every field
+    // here except heap_size_bytes exceeded -Dpreset=stress's ceilings
+    // (512/128/16/32 objects/stack/frames/defers).
     const config: InstanceConfig = .{
         .heap_size_bytes = 96 * 1024,
-        .max_objects = 2048,
-        .max_stack = 256,
-        .max_frames = 64,
-        .max_defers = 64,
+        .max_objects = @min(cfg.max_objects, 2048),
+        .max_stack = @min(cfg.max_stack, 256),
+        .max_frames = @min(cfg.max_frames, 64),
+        .max_defers = @min(cfg.max_defers, 64),
         .max_ops = -1,
         .allow_io = false,
     };
@@ -1669,7 +1688,11 @@ test "engine_call converts a large host-supplied wire array without corrupting e
     ;
     try std.testing.expectEqual(0, engine_run(h, @intFromPtr(src.ptr), src.len));
 
-    const N = 600;
+    // Each element becomes one converted managed-heap object, so N must
+    // stay well under the clamped max_objects ceiling too (600 exceeds
+    // -Dpreset=stress's 512-object ceiling on its own, before even counting
+    // the chunk/globals/compiled-function overhead sharing that budget).
+    const N = @min(600, config.max_objects / 2);
     var bufs: [N][16]u8 = undefined;
     var elem_wires: [N]ValueWire = undefined;
     for (0..N) |i| {

src/lang/vm.zig

@@ -2532,7 +2532,19 @@ noinline fn dispatchTick(ctx: VMContext) !u64 {
         if (ctx.vs.ops_budget_remaining == 0) return error.InstructionBudgetExceeded;
         ctx.vs.ops_budget_remaining -= 1;
     }
-    if (io.traceActive()) io.fireTrace(ctx.cs.lineAt(ctx.vs.ip), ctx.cs.colAt(ctx.vs.ip));
+    // std_script_code_end marks where the embedded std-library bootstrap
+    // bytecode ends and real user code begins (0 when std scripts weren't
+    // compiled in, e.g. the REPL, so this comparison is a no-op there).
+    // Every program executes the std-script bootstrap once at startup
+    // (defining std.array.count and friends as globals) regardless of
+    // whether it references std at all, and a call into a std-library
+    // function implemented in Gengoscript itself also runs bytecode in
+    // this same range — neither should surface line numbers from a
+    // library source the embedding host's user never wrote, and doing so
+    // was a real bug: a fresh engine's very first traced run fired two
+    // ghost events from the std bootstrap before the user script's own
+    // three lines, both silently corrupting the trace sequence.
+    if (io.traceActive() and ctx.vs.ip >= ctx.cs.std_script_code_end) io.fireTrace(ctx.cs.lineAt(ctx.vs.ip), ctx.cs.colAt(ctx.vs.ip));
     return dispatchGasInterval(ctx);
 }
 

src/runtime/io.zig

@@ -25,13 +25,22 @@ pub const WriteFn = *const fn (s: []const u8) void;
 pub const ReadFn = *const fn (buf: []u8, is_line: bool) isize;
 pub const TraceFn = *const fn (userdata: ?*anyopaque, handle: i32, line: i32, col: i32) callconv(.c) void;
 
-var write_override: ?WriteFn = null;
-var werr_override: ?WriteFn = null;
-var read_override: ?ReadFn = null;
-var g_trace_fn: ?TraceFn = null;
-var g_trace_userdata: ?*anyopaque = null;
-var g_trace_handle: i32 = -1;
-var g_trace_prev_line: u32 = 0xFFFF_FFFF;
+// threadlocal: set for the duration of one engine_run/engine_call by
+// engine.zig's pushEngineState/popEngineState, the same as
+// g_active_engine/write_callback/read_callback there and
+// native_host_call_fn/_ctx in host_abi.zig. As plain (non-threadlocal)
+// vars, two threads calling into different engines concurrently could
+// interleave these writes so one engine's trace/write/read calls fired
+// through the other engine's callback and userdata — see engine.zig's
+// g_active_engine doc comment for the full writeup and the two-thread
+// repro that caught the analogous bug in those other fields.
+threadlocal var write_override: ?WriteFn = null;
+threadlocal var werr_override: ?WriteFn = null;
+threadlocal var read_override: ?ReadFn = null;
+threadlocal var g_trace_fn: ?TraceFn = null;
+threadlocal var g_trace_userdata: ?*anyopaque = null;
+threadlocal var g_trace_handle: i32 = -1;
+threadlocal var g_trace_prev_line: u32 = 0xFFFF_FFFF;
 
 pub fn setWriteOverrides(w: WriteFn, e: WriteFn) void {
     write_override = w;