feat(#58): gengo --test --profile resource profiling

Each test block already runs through one isolated loop in
Runtime.runPathWithProvider (vm.callGlobal per __test_N global,
sequential, pass/fail tracked) -- exactly the wrapping point needed,
making this smaller than its P3/v0.9.0 label suggested.

Stack peak reuses the verifier-proved f.max_stack bound
enterFunctionFrame*/already checks on every call -- an upper bound on
capacity used, zero new cost on the push/pop hot path. Heap/object
peaks hook the 8 allocation success points (GC only ever shrinks
usage, never raises it, so allocation time is sufficient). Ops count
forces the existing budget-accounting dispatch path on for the run
(normally skipped via a batched heartbeat when no real max_ops is
set) -- the one part of this with a real, expected speed cost.

All three gated behind a new Policy.profile_mode field, zero cost
when off. tools/time-bench.sh compare shows no regression on any
benchmark.

Author: ganehag

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This changelog tracks notable language/runtime changes by implementation date.
 
+## 2026-07-21 (latest) (v0.5.1-dev)
+
+### Tooling — `gengo --test --profile` (#58)
+
+Each `test` block already compiles to a synthetic `__test_N` global run through one isolated loop in `Runtime.runPathWithProvider` (`vm.callGlobal`, sequential, pass/fail tracked) — that loop turned out to be exactly the wrapping point #58 needed, making this a smaller change than its `P3`/`v0.9.0` label suggested.
+
+- **Stack peak**: reuses the verifier-proved `f.max_stack` bound `enterFunctionFrame`/`enterFunctionFrameWarm` already check on every call (`ctx.vs.stack_top + f.max_stack`) — an upper bound on capacity used, not a per-push sampled maximum, so it costs one extra branch at an already-existing call-entry checkpoint instead of touching the push/pop hot path at all.
+- **Heap bytes / live objects peak**: `usedBytes()`/`liveObjectCount()` only ever grow at allocation time (GC only shrinks them), so checking-and-updating a peak at `vmAllocObject`/`vmAllocManagedSlice`/`vmAllocManagedBytes`'s 8 success points is sufficient to capture the true peak.
+- **Ops count**: `ops_budget_remaining` only decrements when a real `max_ops` budget is set — an unbudgeted run takes a batched "heartbeat" dispatch path specifically to avoid a per-instruction accounting cost. `profile_mode` forces the interval to 1 (tick every instruction) with no real budget, so `budget_before - budget_after` gives an exact per-block count; this is the one part of the feature with a real, expected runtime cost (a diagnostic flag, not something to run by default).
+
+All three are gated behind a new `Policy.profile_mode` field, zero cost when off. Verified with `tools/time-bench.sh compare`: no measurable regression on any benchmark.
+
 ## 2026-07-21 (later) (v0.5.1-dev)
 
 ### Embedding — std natives are no longer host-overridable

docs/changelog.md

@@ -26,6 +26,10 @@
 - **`cap:env`** — New capability module for process environment access. `env.get(name)` returns `string|null`; `env.list()` returns `[string]string`. Requires the host to enable the `env` capability; a script importing `cap:env` without host permission fails at compile time.
 - **`std.Arg`** — Built-in variant covering all primitive scalar types (`Int`, `Float`, `Decimal`, `Rune`, `Bool`, `Str`, `Err`). Use it to write type-safe heterogeneous variadic functions without exposing `any`.
 
+### Tooling (unreleased)
+
+- **`gengo --test --profile`** — reports each `test` block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line, so integrators can size `engine_init_with_config`'s resource ceilings from measured workload data instead of guessing. Does not affect pass/fail behavior or the exit code; does cost real speed (forces per-instruction accounting on for the run), so it's a diagnostic flag, not something to leave on by default.
+
 ### Fixes (unreleased)
 
 - Struct and enum variable declarations following a `std` import no longer trigger a spurious "unknown field in std" compile error.

docs/cli.md

@@ -35,6 +35,7 @@ script from standard input instead.
 | `--version` | Print the CLI version and exit. |
 | `--disasm` | Compile and print a bytecode disassembly without running the script. This is an implementation-debugging aid, not language semantics. |
 | `--test` | Run top-level `test` blocks rather than ordinary script execution. A failed test exits unsuccessfully. |
+| `--profile` | With `--test`, print each block's instruction count and peak heap bytes/stack depth/live object count, plus a final peak-across-all-blocks summary line. Does not affect pass/fail behavior or the exit code. Forces per-instruction instruction counting on for the run, which costs real speed — a diagnostic aid, not something to leave on by default. |
 | `--cap name` | Enable one named capability. Repeat for several capabilities. See `capabilities.md`; no capability is enabled merely by importing it. |
 | `--modules path` | Permit source imports from one additional directory. Repeatable, up to eight paths. The script directory remains the default source root. |
 | `--max-ops n` | Limit VM instruction execution to `n`. `0` means unlimited. This limit does not account for work inside host callbacks. |

src/lang/vm.zig

@@ -972,6 +972,7 @@ inline fn enterFunctionFrameWarm(ctx: VMContext, f: @import("value.zig").FuncObj
     // exceeds f.max_stack slots above the entry stack_top, so opcode handlers
     // may use unchecked stack ops inside this frame.
     if (ctx.vs.stack_top + f.max_stack > ctx.vs.stack.len) return error.StackOverflow;
+    recordProfileStackPeak(ctx, f.max_stack);
     ctx.vs.frames[ctx.vs.frame_top] = .{
         .ret_ip = @intCast(ctx.vs.ip),
         .base = @intCast(ctx.vs.stack_top - f.arity),
@@ -985,6 +986,18 @@ inline fn enterFunctionFrameWarm(ctx: VMContext, f: @import("value.zig").FuncObj
     ctx.vs.ip = f.ip;
 }
 
+// gengo --test --profile only: this is the verifier-proved *capacity*
+// consumed by the frame being entered (ctx.vs.stack_top + f.max_stack), not
+// a per-push sampled maximum — reusing the same bound enterFunctionFrame*
+// already checks means zero new cost on the push/pop hot path. An upper
+// bound on capacity used is also the more useful number for sizing an
+// embedder's stack limit than one observed sample run's exact depth.
+inline fn recordProfileStackPeak(ctx: VMContext, max_stack: u16) void {
+    if (!ctx.vs.policy.profile_mode) return;
+    const candidate = ctx.vs.stack_top + max_stack;
+    if (candidate > ctx.vs.peak_stack_depth) ctx.vs.peak_stack_depth = candidate;
+}
+
 fn enterFunctionFrame(ctx: VMContext, f: @import("value.zig").FuncObj, func_obj: *Object, closure: ?*Object, argc: u8) !void {
     var effective_argc = argc;
     if (f.is_variadic) {
@@ -1031,6 +1044,7 @@ fn enterFunctionFrame(ctx: VMContext, f: @import("value.zig").FuncObj, func_obj:
     if (ctx.vs.frame_top >= ctx.vs.frames.len) return error.CallStackOverflow;
     // See enterFunctionFrameWarm: verifier-proved bound, checked once per call.
     if (ctx.vs.stack_top + f.max_stack > ctx.vs.stack.len) return error.StackOverflow;
+    recordProfileStackPeak(ctx, f.max_stack);
     ctx.vs.frames[ctx.vs.frame_top] = .{
         .ret_ip = @intCast(ctx.vs.ip),
         .base = @intCast(ctx.vs.stack_top - f.arity),

src/lang/vm_gc.zig

@@ -209,6 +209,19 @@ fn gcStress() bool {
     return gc_stress;
 }
 
+// gengo --test --profile only: object-slot and managed-slice allocation are
+// the only two places usedBytes()/liveObjectCount() can grow — GC only ever
+// shrinks them — so checking here after a successful allocation is
+// sufficient to capture the true peak, without touching the push/pop hot
+// path at all.
+inline fn recordProfilePeaks(ctx: VMContext) void {
+    if (!ctx.vs.policy.profile_mode) return;
+    const objs = ctx.hs.liveObjectCount();
+    if (objs > ctx.vs.peak_live_objects) ctx.vs.peak_live_objects = objs;
+    const bytes = ctx.hs.usedBytes();
+    if (bytes > ctx.vs.peak_heap_bytes) ctx.vs.peak_heap_bytes = bytes;
+}
+
 pub fn vmAllocObject(ctx: VMContext) !*Object {
     if (gcStress()) collectGarbage(ctx);
     if (ctx.hs.liveObjectCount() >= ctx.vs.next_gc_objects) {
@@ -217,12 +230,14 @@ pub fn vmAllocObject(ctx: VMContext) !*Object {
     }
     if (ctx.hs.allocObject()) |o| {
         ctx.vs.alloc_object_calls += 1;
+        recordProfilePeaks(ctx);
         return o;
     }
     collectGarbage(ctx);
     ctx.vs.next_gc_objects = nextGcObjects(ctx, ctx.hs.liveObjectCount());
     if (ctx.hs.allocObject()) |o| {
         ctx.vs.alloc_object_calls += 1;
+        recordProfilePeaks(ctx);
         return o;
     }
     return error.OutOfMemory;
@@ -253,17 +268,20 @@ pub fn vmAllocManagedSlice(ctx: VMContext, comptime T: type, n: usize) ![]T {
     }
     if (ctx.hs.allocManagedSlice(T, n)) |s| {
         ctx.vs.alloc_managed_slice_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     collectGarbage(ctx);
     ctx.vs.next_gc_heap_bytes = gcStepThreshold(ctx, ctx.hs.usedBytes());
     if (ctx.hs.allocManagedSlice(T, n)) |s| {
         ctx.vs.alloc_managed_slice_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     ctx.hs.compactManagedHeap();
     if (ctx.hs.allocManagedSlice(T, n)) |s| {
         ctx.vs.alloc_managed_slice_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     return error.OutOfMemory;
@@ -289,19 +307,22 @@ pub fn vmAllocManagedBytes(ctx: VMContext, n: usize) ![]u8 {
     }
     if (ctx.hs.allocBytesManaged(n)) |s| {
         ctx.vs.alloc_managed_bytes_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     collectGarbage(ctx);
     ctx.vs.next_gc_heap_bytes = gcStepThreshold(ctx, ctx.hs.usedBytes());
     if (ctx.hs.allocBytesManaged(n)) |s| {
         ctx.vs.alloc_managed_bytes_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     // Last resort: compact live managed data into a contiguous region so that
     // fragmentation caused by live objects between freed blocks is eliminated.
     ctx.hs.compactManagedHeap();
     if (ctx.hs.allocBytesManaged(n)) |s| {
         ctx.vs.alloc_managed_bytes_calls += 1;
+        recordProfilePeaks(ctx);
         return s;
     }
     return error.OutOfMemory;

src/lang/vm_state.zig

@@ -36,6 +36,11 @@ pub const Policy = struct {
     allow_io: bool = true,
     native_backend: NativeBackend = .embedded,
     max_ops: ?u64 = null,
+    // gengo --test --profile: forces per-instruction gas accounting on (see
+    // dispatchGasInterval in vm.zig) even with no real max_ops budget, so
+    // ops_budget_remaining decrements every instruction instead of only
+    // every ~4M-instruction heartbeat, and enables the peak_* fields below.
+    profile_mode: bool = false,
     enable_predicates: bool = true,
 };
 
@@ -70,6 +75,13 @@ pub const State = struct {
     frame_top: usize = 0,
     std_module: ?*Object = null,
     host_checked: bool = false,
+    // gengo --test --profile only (see Policy.profile_mode). The caller
+    // (Runtime's test-block loop) resets each to the current baseline
+    // before running a block, then reads it back after — these only ever
+    // grow during execution, they are not reset by the VM itself.
+    peak_stack_depth: usize = 0,
+    peak_heap_bytes: usize = 0,
+    peak_live_objects: usize = 0,
     configured_heap_size: usize = 0,
     next_gc_objects: usize = 256,
     next_gc_heap_bytes: usize = 0,
@@ -227,7 +239,12 @@ pub const State = struct {
 
     pub fn setPolicy(self: *State, policy: Policy) void {
         self.policy = policy;
-        self.ops_budget_remaining = policy.max_ops orelse std.math.maxInt(u64);
+        // profile_mode with no real budget: anything other than maxInt(u64)
+        // makes dispatchGasInterval tick every instruction instead of only
+        // every heartbeat, so ops_budget_remaining actually decrements and
+        // (budget_before - budget_after) gives an exact per-block op count.
+        self.ops_budget_remaining = policy.max_ops orelse
+            (if (policy.profile_mode) std.math.maxInt(u64) - 1 else std.math.maxInt(u64));
     }
 
     fn currentIpIdx(self: *State, cs: *const chunk.State) usize {

src/main.zig

@@ -435,6 +435,7 @@ fn runCli(argv: []const []const u8) void {
     var backend: vm.Policy.NativeBackend = .embedded;
     var max_ops: ?u64 = null;
     var test_mode: bool = false;
+    var profile_mode: bool = false;
     var disasm_mode: bool = false;
     var cap_names: [8][]const u8 = undefined;
     var cap_count: usize = 0;
@@ -455,6 +456,7 @@ fn runCli(argv: []const []const u8) void {
             io.write("  --version          Print version and exit\n");
             io.write("  --disasm           Compile and print bytecode disassembly; do not run\n");
             io.write("  --test             Run test blocks in the script\n");
+            io.write("  --profile          With --test, report peak ops/heap/stack/objects per block\n");
             io.write("  --cap <name>       Enable a named capability (repeatable)\n");
             io.write("  --modules <path>   Allow imports from an extra directory (repeatable)\n");
             io.write("  --max-ops <n>      Limit instruction count (0 = unlimited)\n");
@@ -579,6 +581,11 @@ fn runCli(argv: []const []const u8) void {
             script_index += 1;
             continue;
         }
+        if (std.mem.eql(u8, a, "--profile")) {
+            profile_mode = true;
+            script_index += 1;
+            continue;
+        }
         if (std.mem.eql(u8, a, "--version")) {
             io.write("Gengoscript v");
             io.write(build_opts.version);
@@ -650,6 +657,7 @@ fn runCli(argv: []const []const u8) void {
         .allow_io = true,
         .native_backend = backend,
         .max_ops = max_ops,
+        .profile_mode = profile_mode,
     }, heap_size, max_objects, vms.MaxStack, vms.MaxFrames, cfg.max_defers, std.heap.page_allocator) catch {
         io.werr("gengo: runtime init failed\n");
         die(1);

src/runtime/runtime.zig

@@ -422,11 +422,37 @@ pub const Runtime = struct {
         if (test_mode and self.test_count > 0) {
             var passed: u8 = 0;
             var failed: u8 = 0;
+            const profiling = self.vm_state.policy.profile_mode;
+            // Component-wise max across all blocks, not a sum — "what's the
+            // largest any single block needed" is the number that sizes an
+            // embedder's engine_init_with_config ceilings.
+            var peak_ops: u64 = 0;
+            var peak_heap: usize = 0;
+            var peak_stack: usize = 0;
+            var peak_objects: usize = 0;
             var ti: u8 = 0;
             while (ti < self.test_count) : (ti += 1) {
                 var name_buf: [32]u8 = undefined;
                 const name = std.fmt.bufPrint(&name_buf, "__test_{d}", .{ti}) catch continue;
-                _ = vm.callGlobal(.{ .cs = self.chunk_state, .gs = &self.globals_state, .hs = &self.heap_state, .vs = &self.vm_state }, name, &[_]Value{}) catch |err| {
+
+                const ops_before = self.vm_state.ops_budget_remaining;
+                if (profiling) {
+                    self.vm_state.peak_stack_depth = self.vm_state.stack_top;
+                    self.vm_state.peak_heap_bytes = self.heap_state.usedBytes();
+                    self.vm_state.peak_live_objects = self.heap_state.liveObjectCount();
+                }
+
+                const call_result = vm.callGlobal(.{ .cs = self.chunk_state, .gs = &self.globals_state, .hs = &self.heap_state, .vs = &self.vm_state }, name, &[_]Value{});
+
+                const ops_used = ops_before -% self.vm_state.ops_budget_remaining;
+                if (profiling) {
+                    peak_ops = @max(peak_ops, ops_used);
+                    peak_heap = @max(peak_heap, self.vm_state.peak_heap_bytes);
+                    peak_stack = @max(peak_stack, self.vm_state.peak_stack_depth);
+                    peak_objects = @max(peak_objects, self.vm_state.peak_live_objects);
+                }
+
+                _ = call_result catch |err| {
                     failed += 1;
                     io.werr("FAIL: ");
                     io.werr(self.test_names[ti]);
@@ -437,23 +463,44 @@ pub const Runtime = struct {
                         io.werr(": ");
                         io.werr(emsg);
                     }
+                    if (profiling) self.writeProfileColumns(ops_used, self.vm_state.peak_heap_bytes, self.vm_state.peak_stack_depth, self.vm_state.peak_live_objects);
                     io.werr("\n");
                     continue;
                 };
                 passed += 1;
                 io.werr("PASS: ");
                 io.werr(self.test_names[ti]);
+                if (profiling) self.writeProfileColumns(ops_used, self.vm_state.peak_heap_bytes, self.vm_state.peak_stack_depth, self.vm_state.peak_live_objects);
                 io.werr("\n");
             }
             io.werr("\n");
             io.writeInt(@intCast(passed));
             io.werr(" passed, ");
             io.writeInt(@intCast(failed));
             io.werr(" failed\n");
+            if (profiling) {
+                io.werr("peak across all tests: ");
+                self.writeProfileColumns(peak_ops, peak_heap, peak_stack, peak_objects);
+                io.werr("\n");
+            }
             if (failed > 0) self.test_failed = true;
         }
     }
 
+    // gengo --test --profile: appended after a PASS/FAIL line and used
+    // standalone for the final "peak across all tests" summary.
+    fn writeProfileColumns(self: *Runtime, ops: u64, heap_bytes: usize, stack_depth: usize, objects: usize) void {
+        _ = self;
+        io.werr("  ops=");
+        io.werrUint(ops);
+        io.werr(" heap=");
+        io.werrUint(@intCast(heap_bytes));
+        io.werr(" stack=");
+        io.werrUint(@intCast(stack_depth));
+        io.werr(" objects=");
+        io.werrUint(@intCast(objects));
+    }
+
     // Run src without resetting globals or heap — allows successive REPL lines
     // to share definitions and allocated objects.
     pub fn runIncremental(self: *Runtime, src: []const u8) !void {