@@ -2751,6 +2751,8 @@ pub const Context = struct {
27512751 /// owner along with its arena heap. Standalone contexts leave this null.
27522752 shared_jit_owner: ?*jit.Owner = null,
27532753 enable_jit: bool = true,
2754+ /// Test-only forced execution contract. Public contexts remain automatic.
2755+ bytecode_execution_mode: interp.BytecodeExecutionMode = .automatic,
27542756 /// Reusable allocator used as the GC heap's cell backing. It recycles
27552757 /// per-cell slabs for allocation/lifecycle performance and becomes
27562758 /// internally locked under `parallel_gc`, so multiple mutators can allocate
@@ -3303,6 +3305,10 @@ pub const Context = struct {
33033305 /// of the stable embedder options surface.
33043306 pub const TestingOptions = struct {
33053307 enable_jit: bool = true,
3308+ /// Force plain synchronous execution through one tier for exact
3309+ /// differentials. `required` throws instead of silently accepting a
3310+ /// compiler or template fallback as VM coverage.
3311+ bytecode_execution_mode: interp.BytecodeExecutionMode = .automatic,
33063312 enable_threads: bool = false,
33073313 enable_gc: bool = false,
33083314 concurrent_gc: bool = false,
@@ -3872,6 +3878,7 @@ pub const Context = struct {
38723878 .jit_owner = jit.Owner.init(allocator),
38733879 .shared_jit_owner = primary.shared_jit_owner orelse &primary.jit_owner,
38743880 .enable_jit = primary.enable_jit,
3881+ .bytecode_execution_mode = primary.bytecode_execution_mode,
38753882 .owner_thread = primary.owner_thread,
38763883 .sab_retains = .{ .gpa = allocator },
38773884 .env = .{ .arena = a, .fn_scope = true },
@@ -3960,6 +3967,7 @@ pub const Context = struct {
39603967 primary.assertOwnerThread();
39613968 return createWithTestingOptionsForSharedOwner(primary.host_gpa, .{
39623969 .enable_jit = primary.enable_jit,
3970+ .bytecode_execution_mode = primary.bytecode_execution_mode,
39633971 .enable_gc = true,
39643972 .wasm_features = primary.wasm_features,
39653973 }, primary);
@@ -4035,6 +4043,7 @@ pub const Context = struct {
40354043 .jit_owner = jit.Owner.init(context_gpa),
40364044 .shared_jit_owner = if (shared_owner) |owner| owner.shared_jit_owner orelse &owner.jit_owner else null,
40374045 .enable_jit = options.enable_jit,
4046+ .bytecode_execution_mode = options.bytecode_execution_mode,
40384047 .owner_thread = std.Thread.getCurrentId(),
40394048 .sab_retains = .{ .gpa = context_gpa },
40404049 .env = .{ .arena = a, .fn_scope = true }, // global is a variable scope
@@ -4282,6 +4291,7 @@ pub const Context = struct {
42824291 .profile_statement_ctx = self.profile_statement_ctx,
42834292 .profile_statement_hook = self.profile_statement_hook,
42844293 .bytecode_admission_inventory = &self.bytecode_admission_inventory,
4294+ .bytecode_execution_mode = self.bytecode_execution_mode,
42854295 .debug_statement_locations = &self.debug_statement_locations,
42864296 .debug_registry_lock = if (self.parallel_js) &self.debug_registry_lock else null,
42874297 .debug_script_ctx = self,
@@ -7223,13 +7233,21 @@ pub const Context = struct {
72237233 }
72247234
72257235 const outcome: interp.EvalError!value.Value = admission: {
7236+ if (self.bytecode_execution_mode == .tree_walker) {
7237+ self.bytecode_admission_inventory.record(.program_forced_tree_walker);
7238+ break :admission machine.eval(prog);
7239+ }
72267240 if (self.debug_statement_hook != null) {
72277241 self.bytecode_admission_inventory.record(.program_debugger);
7242+ if (self.bytecode_execution_mode == .required)
7243+ break :admission machine.throwError("InternalError", "required bytecode program is blocked by debugger execution");
72287244 break :admission machine.eval(prog);
72297245 }
7230- if (scriptTreeWalkPolicy(owned_source)) |reason| {
7231- self.bytecode_admission_inventory.record(reason);
7232- break :admission machine.eval(prog);
7246+ if (self.bytecode_execution_mode != .required) {
7247+ if (scriptTreeWalkPolicy(owned_source)) |reason| {
7248+ self.bytecode_admission_inventory.record(reason);
7249+ break :admission machine.eval(prog);
7250+ }
72337251 }
72347252 switch (compiler.Compiler.admitProgram(a, prog) catch return error.OutOfMemory) {
72357253 .compiled => |chunk| {
@@ -7238,6 +7256,8 @@ pub const Context = struct {
72387256 },
72397257 .rejected => |reason| {
72407258 self.bytecode_admission_inventory.record(interp.programRejectionAdmission(reason));
7259+ if (self.bytecode_execution_mode == .required)
7260+ break :admission machine.throwError("InternalError", "required bytecode program was rejected by the compiler");
72417261 break :admission machine.eval(prog);
72427262 },
72437263 }
@@ -18174,6 +18194,125 @@ test "bytecode admission source policies retain causal reasons" {
1817418194 for (cases) |case| try std.testing.expectEqual(case.reason, Context.scriptTreeWalkPolicy(case.source));
1817518195}
1817618196
18197+ test "forced tree-walker and required bytecode preserve exact observable state" {
18198+ const source =
18199+ \\globalThis.tierTrace = [];
18200+ \\function tierDifferential(seed) {
18201+ \\ "use strict";
18202+ \\ var box = { value: seed };
18203+ \\ var trace = [];
18204+ \\ function bump(value) {
18205+ \\ box.value = box.value + value;
18206+ \\ trace.push(box.value);
18207+ \\ return box.value;
18208+ \\ }
18209+ \\ var sum = 0;
18210+ \\ for (var i = 0; i < 16; i = i + 1)
18211+ \\ sum = sum + bump((i & 3) + 1);
18212+ \\ globalThis.tierTrace = trace.join(",");
18213+ \\ globalThis.tierBox = box.value;
18214+ \\ return sum + box.value;
18215+ \\}
18216+ \\tierDifferential(7);
18217+ ;
18218+
18219+ const tree_ctx = try Context.createWithTestingOptions(std.testing.allocator, .{
18220+ .enable_jit = false,
18221+ .bytecode_execution_mode = .tree_walker,
18222+ });
18223+ defer tree_ctx.destroy();
18224+ const bytecode_ctx = try Context.createWithTestingOptions(std.testing.allocator, .{
18225+ .enable_jit = false,
18226+ .bytecode_execution_mode = .required,
18227+ });
18228+ defer bytecode_ctx.destroy();
18229+
18230+ const tree_result = try tree_ctx.evaluate(source);
18231+ const bytecode_result = try bytecode_ctx.evaluate(source);
18232+ try std.testing.expectEqual(tree_result.rawBits(), bytecode_result.rawBits());
18233+ try std.testing.expectEqualStrings(
18234+ (try tree_ctx.evaluate("tierTrace + '|' + tierBox")).asStr(),
18235+ (try bytecode_ctx.evaluate("tierTrace + '|' + tierBox")).asStr(),
18236+ );
18237+
18238+ const tree = tree_ctx.bytecodeAdmissionSnapshot();
18239+ try std.testing.expectEqual(@as(u64, 2), tree.count(.program_forced_tree_walker));
18240+ try std.testing.expectEqual(@as(u64, 2), tree.count(.plain_forced_tree_walker));
18241+ try std.testing.expectEqual(@as(u64, 0), tree.count(.program_compiled));
18242+
18243+ const bytecode = bytecode_ctx.bytecodeAdmissionSnapshot();
18244+ try std.testing.expectEqual(@as(u64, 2), bytecode.count(.program_compiled));
18245+ try std.testing.expectEqual(@as(u64, 2), bytecode.count(.template_plain_compiled));
18246+ try std.testing.expectEqual(@as(u64, 0), bytecode.count(.program_forced_tree_walker));
18247+ try std.testing.expectEqual(@as(u64, 0), bytecode.count(.template_plain_fallback));
18248+ }
18249+
18250+ test "required bytecode rejects an uncompiled function instead of counting fallback coverage" {
18251+ const ctx = try Context.createWithTestingOptions(std.testing.allocator, .{
18252+ .enable_jit = false,
18253+ .bytecode_execution_mode = .required,
18254+ });
18255+ defer ctx.destroy();
18256+
18257+ try std.testing.expectError(error.Throw, ctx.evaluate(
18258+ \\function needsParameterPrologue(value = 1) { return value; }
18259+ \\needsParameterPrologue();
18260+ ));
18261+ const exception = ctx.exception orelse return error.TestUnexpectedResult;
18262+ try std.testing.expectEqualStrings("InternalError", exception.asObj().errorName());
18263+ try std.testing.expectEqualStrings(
18264+ "required bytecode function has no compiled chunk",
18265+ exception.asObj().getOwn("message").?.asStr(),
18266+ );
18267+ const inventory = ctx.bytecodeAdmissionSnapshot();
18268+ try std.testing.expectEqual(@as(u64, 1), inventory.count(.program_compiled));
18269+ try std.testing.expectEqual(@as(u64, 1), inventory.count(.template_plain_rejected_parameter_prologue));
18270+ try std.testing.expectEqual(@as(u64, 0), inventory.count(.template_plain_fallback));
18271+ }
18272+
18273+ test "forced tree-walker and required bytecode preserve exception and side effects" {
18274+ const source =
18275+ \\globalThis.tierBeforeThrow = 0;
18276+ \\function tierThrow(seed) {
18277+ \\ "use strict";
18278+ \\ globalThis.tierBeforeThrow = seed * 2;
18279+ \\ throw new TypeError("tier-boom");
18280+ \\}
18281+ \\tierThrow(9);
18282+ ;
18283+ const modes = [_]interp.BytecodeExecutionMode{ .tree_walker, .required };
18284+ var side_effects: [modes.len]u64 = undefined;
18285+
18286+ for (modes, 0..) |mode, index| {
18287+ const ctx = try Context.createWithTestingOptions(std.testing.allocator, .{
18288+ .enable_jit = false,
18289+ .bytecode_execution_mode = mode,
18290+ });
18291+ defer ctx.destroy();
18292+
18293+ try std.testing.expectError(error.Throw, ctx.evaluate(source));
18294+ const exception = ctx.exception orelse return error.TestUnexpectedResult;
18295+ try std.testing.expectEqualStrings("TypeError", exception.asObj().errorName());
18296+ try std.testing.expectEqualStrings("tier-boom", exception.asObj().getOwn("message").?.asStr());
18297+ side_effects[index] = (try ctx.evaluate("tierBeforeThrow")).rawBits();
18298+
18299+ const inventory = ctx.bytecodeAdmissionSnapshot();
18300+ switch (mode) {
18301+ .tree_walker => {
18302+ try std.testing.expectEqual(@as(u64, 2), inventory.count(.program_forced_tree_walker));
18303+ try std.testing.expectEqual(@as(u64, 1), inventory.count(.plain_forced_tree_walker));
18304+ },
18305+ .required => {
18306+ try std.testing.expectEqual(@as(u64, 2), inventory.count(.program_compiled));
18307+ try std.testing.expectEqual(@as(u64, 1), inventory.count(.template_plain_compiled));
18308+ },
18309+ .automatic => unreachable,
18310+ }
18311+ }
18312+
18313+ try std.testing.expectEqual(side_effects[0], side_effects[1]);
18314+ }
18315+
1817718316test "bytecode admission inventory merges concurrent realm records" {
1817818317 if (builtin.single_threaded) return error.SkipZigTest;
1817918318 var inventory = interp.BytecodeAdmissionInventory{};
0 commit comments