Repository navigation
Description
Goal
Make every semantically eligible JavaScript function and program reach the bytecode VM, removing the current flat-slot lexical-scope barrier without weakening tree-walker equivalence.
Current boundary
The compiler now has explicit lexical scopes, checked TDZ/const slots, captured iteration environments, and direct-eval activation views. 81ce8599 adds exact ordinary block-function/CaseBlock lexical and Annex B bindings (#788), with required-bytecode Annex B function-code witnesses at 159/159. 8d772d15 adds program/suspendable environment-mode declarations (#790), including 153/153 required-bytecode Annex B global-code witnesses. e1afde2d removes the blanket rejection of nested suspendable templates inside ordinary VM functions through live defining-environment views (#794), with the concurrent-GC ownership prerequisite in #796. e0ed6eb1 installs complete callee parameter metadata (#795), and 8a1398ff preserves exact lexical private and field-initializer eval contexts across parameter entry and suspension (#797). These landed prerequisites have completed required integration in CI run 33113309062: all 53 executed jobs passed; the scheduled-only nightly job was skipped. Automatic tiering still follows workload policy; required-bytecode admission is not proof of default-tier selection or throughput leadership.
Scope
- Add explicit lexical-scope metadata and storage for block bindings, TDZ state, catch bindings, class names, and per-iteration environments.
- Preserve O(1) slot access for statically resolved bindings while allocating environment cells only where capture/dynamic lookup requires them.
- Compile top-level, functions, methods, constructors, arrows, generators, async functions, and async generators through one verified eligibility model.
- Model
eval,with, direct eval, global resolution,this,super,new.target, and upvalues with explicit dynamic barriers rather than blanket or unsafe admission. - Add compiler/VM/tree-walker differential generation for scopes, abrupt completion, closures, exceptions, suspend/resume, and proper tail calls.
- Publish admission counters by reason so remaining tree-walker execution is auditable.
No-workaround rules
- Do not flatten a scope whose identity/TDZ is observable, eagerly heap-allocate every local, disable per-iteration capture semantics, or silently route a failing compiled path to a different result.
- Tree-walker fallback remains exact during rollout but is not completion for a construct declared bytecode-eligible.
Acceptance
- Shadowing, TDZ, catch/class scopes, and per-iteration closures pass forced tree-walker/VM differentials.
- Eligible test262 and PR-249 programs execute through VM witnesses with identical result, exception, side effects, steps, and async ordering.
- Admission inventory reports every compiler rejection with a stable reason; no unclassified fallback remains.
- Focused VM, full unit, test262, no-GIL, TSan, threadfuzz, generator/async, debugger, and moving-GC gates pass.
- Bench: define the representative dependency-free performance matrix #460 records tree-walker/VM/tier attribution before and after without a regression caused by unnecessary heap environments.
Foundation
Architecture boundary: docs/architecture.md; bytecode/compiler paths: src/compiler.zig, src/bytecode.zig, and src/vm.zig.
Latest parameter-reference boundary
2865b8b4 (#798) admits exact lexical parameter references through existing checked resolution. Against 8a1398f, the same 9,643 positive paired files improve from 8,475 to 8,809 passes (+334, zero new failing paths); 834 existing failures remain. All 13 default-tier diagnostics retain 11,494 passes with byte-identical output (0 default-tier flips). Full local units: 2,020 pass / 1 skip / 0 fail/leak; focused ReleaseSafe+TSan and 700 seeded fuzz programs pass. Pushed CI 33127832028 is pending. #799 tracks the next assignment/update initializer boundary. These scoped gains do not complete universal admission, the separate #787/#791 ownership audits, or performance attribution.
Activity
chrisbbreuer commentedon Aug 2, 2026
Plain-function admission taxonomy landed on
maininab660166.The compiler now returns a stable typed admission result instead of collapsing every plain-function barrier into
error.Unsupported. Current reasons distinguish generator/async inputs, function-scope disposal, block-nested function declarations, lexical shadowing, TDZ hazards, parameter prologues, and residual unsupported lowering. The legacy compile API remains source-compatible.Validation: direct
src/compiler.zigtest root, 107/107 passed, including every rejection tag and a positive compiled case.The admission-inventory acceptance item remains open: runtime policy skips (debugger/method/arguments/candidate policy), top-level/generator/async rejections, aggregate counters, and an inventory reporter still need to consume stable reasons.
chrisbbreuer commentedon Aug 2, 2026
Runtime admission telemetry is now on
mainindc0d629e, building on the typed compiler admissions inab660166and4d9bd64e.Every runtime
Functionnow retains a stableBytecodeAdmissionReason, andContext.bytecodeAdmissionSnapshot()exposes context-owned atomic counts covering program, plain-function, generator, async, and nested-template decisions. Shared-realm recording was verified with 4 concurrent writers (40,000 exact counts per reason), and the focused inventory tests pass under TSan.Validation: compiler root 110/110; adjacent VM admission 3/3; full unit suite 1,470/1,470 across 10 shards; docs build and link check.
The acceptance checkbox remains open intentionally:
program_source_policyand VM template fallbacks are still coarse categories, so “no unclassified fallback remains” is not yet true. The next admission slice should replace those generic buckets with causal subreasons and add the inventory reporter/witness output.chrisbbreuer commentedon Aug 2, 2026
The remaining admission-classification gap is closed on
mainin64bacae9, followingab660166,4d9bd64e, anddc0d629e.Source-policy skips now retain causal reasons for lexical declarations, catch, switch, labels,
argumentsfunctions, legacy.caller/.arguments, and nested function declarations. Nested function templates carry the compiler decision that produced either bytecode or a null chunk, distinguishing parameter-prologue rejection from unsupported lowering. The legacy generic counters remain in the stable schema but have no emission sites; runtime tests prove all generic template counters andprogram_source_policyremain unchanged.Validation: focused admission tests in Debug and TSan; compiler root 110/110; docs manifest/build/link checks; full sharded unit suite 1,471/1,471 with 0 leaks. Execution admission decisions are unchanged, so this flips 0 test262 cases.
The admission-inventory acceptance checkbox is now complete. The broader lexical-scope compilation and forced VM-equivalence work remains open.
chrisbbreuer commentedon Aug 2, 2026
Forced tree-walker/VM differential controls are now available on
mainincff13e9f.The test-only
tree_walkermode suppresses plain synchronous bytecode, andrequiredmode fails closed if the program compiler or a called plain-function/template path would fall back. Admission counters prove which tier actually executed, preventing a green result from silently representing the same tree-walker path twice.Initial witnesses compare exact result bits, observable closure/property/array state, exception class/message, and pre-throw side effects in Debug and TSan. Full suite: 1,474/1,474, 0 leaks. This advances the forced-differential foundation but does not check the first acceptance item yet: shadowing, TDZ, catch/class scopes, and per-iteration capture still need correct VM lowering before their differential matrix can pass.
chrisbbreuer commentedon Aug 2, 2026
Class/method VM admission advanced on
mainin28b00703.Methods now use ordinary compiler admission instead of a blanket policy rejection. Heap activations preserve, precisely trace/relocate, and restore
[[HomeObject]]/super state; base constructors install instance private-method/accessor brands before body execution. Deferred class members are admitted only when they do not capture a VM frame slot. Derived constructors and constructors with field initialization retain a stable causal barrier (plain_policy_class_constructor_semantics) until their initialization state is represented by bytecode activations, and unresolved source-level private names reject eager computed-key lowering.Forced tree-walker/required-bytecode witnesses now cover catch/finally state, ordinary classes, private methods/brands, and repeated
superresolution across nested activation returns. The exact-parent corpus comparison found and drove fixes for 528 private-brand failures and 2 computed-private-key failures before landing; final results are unchanged and clean: class statements 4,367/4,367 and object expressions 1,170/1,170 in both binaries.Validation: focused Debug/TSan tier, compiler, semantic-barrier, and moving-GC tests; all 1,477 unit tests across the final binary partitions plus isolated scheduling-witness confirmation; BunPress build and 89-file link check.
The first acceptance item remains open: catch/class scope coverage has advanced, but shadowing, TDZ, and per-iteration closure lowering/differentials are not complete.
chrisbbreuer commentedon Aug 3, 2026
Lexical TDZ/const bytecode lowering landed on
mainin88a3d794.This slice adds lexical-slot metadata plus checked local/upvalue initialization, reads, and assignments. It preserves
ReferenceErrorbefore initialization (includingtypeof, assignment-in-initializer,for (let value of value), and captured reads/writes), preservesTypeErrorfor initializedconstwrites, resets hazardous block slots on re-entry, and holds frame-slot exclusions across each check/read-or-write. Declarations still performInitializeBindingthrough the unchecked store. Ordinary proven-initializedletloops keep the existing opcodes and still reach native optimization; checked lexical opcodes fail closed above bytecode.Forced tree-walker/required-bytecode witnesses compare exception class, side effects, result/state, repeated block entry, mutable post-init writes, and admission counters with zero fallback. Validation:
The first acceptance item stays open. TDZ is now covered for unambiguous slots, but same-name block binding identity/shadowing and fresh per-iteration captured cells remain explicit tree-walker barriers; those need real frame/scope representation rather than flattened-slot workarounds.
chrisbbreuer commentedon Aug 3, 2026
Landed the lexical block-binding identity slice in https://github.com/zig-utils/zig-js/commit/dbe906d7bff89aa7f5aab0686196418322dbb0c2.\n\nThe bytecode compiler now assigns distinct activation slots to same-spelled block, for-head, for-of-head, switch CaseBlock, and catch bindings, restores the enclosing compile-time mapping on scope exit, and preserves the selected slot in nested-closure upvalues. Forced tree-walker vs required-bytecode differentials cover nested and sibling shadowing, captured mutation, enclosing-parameter restoration, inner-binding TDZ, loop heads, switch, and catch.\n\nValidation: full units 1,488/1,488; focused TSan differential 1/1; ReleaseFast test262 48,506/48,506 valid plus 4,669/4,669 negative, zero skipped and 0 flips; threadfuzz 400 programs / 0 failures; docs 49 pages and 90/90 link-clean.\n\nThe remaining lexical admission boundary is fresh per-iteration cells when a loop lexical is captured, so the first acceptance checkbox intentionally remains open.
chrisbbreuer commentedon Aug 3, 2026
Landed the next bytecode lexical-scope slice in aa6ced3.
Captured simple let/const heads in classic for and for-of now use real declarative environments with fresh cells per iteration; uncaptured heads retain the O(1) frame-slot path. The lowering establishes TDZ before classic initializers and for-of RHS evaluation, copies multiple classic head bindings in the specified order, and preserves the active environment across break, continue, return, throw, generator suspension, async/async-generator suspension, and class-member capture. The tree-walker TDZ ordering was corrected in the same logical change.
Measured evidence: 1,490/1,490 unit tests; focused TSan differential 1/1; ReleaseFast test262 48,506/48,506 valid plus 4,669/4,669 negative with zero skipped and zero flips; deterministic threadfuzz 400/400; docs 49 pages and 90 links.
The first checklist item remains open. Remaining per-iteration boundaries are captured destructuring heads, captured lexicals declared inside repeated loop bodies, and labeled jumps crossing multiple environment-owning loops. The wider dynamic-scope and suspension/debugger work in this issue also remains open.
chrisbbreuer commentedon Aug 3, 2026
Expanded the per-iteration bytecode slice in c1160fa.
Captured yield-free array/object destructuring heads without default or computed evaluation now use the same fresh declarative-environment model as captured identifier heads. This covers classic for renewal, for-of array/object/rest binding, binding order, constness, TDZ before the classic initializer and for-of RHS, generator suspension, async suspension, and required-bytecode differentials against the tree-walker. Patterns requiring default/computed evaluation remain fail-closed on the exact tree-walker path; the compiler does not admit an enclosing function and then discover an unprepared nested template at runtime.
Measured evidence: 1,491/1,491 unit tests; focused TSan 1/1; ReleaseFast test262 48,506/48,506 valid plus 4,669/4,669 negative with zero skipped and zero flips; deterministic threadfuzz 400/400; docs 49 pages and 90 links.
The first checklist item remains open. Its remaining per-iteration boundaries are destructuring default/computed evaluation, captured lexicals declared inside repeated loop bodies, and labeled jumps crossing multiple environment-owning loops. The wider dynamic-scope, debugger, and suspension coverage in #465 also remains open.
chrisbbreuer commentedon Aug 4, 2026
Captured repeated-body lexical scopes and exact abrupt unwind landed on main in 7c8b5ea.
Captured declarations inside repeated loop bodies now receive fresh declarative environments at the actual nested block, catch, or switch scope that owns them. Yield-free array/object/rest destructuring without default or computed evaluation uses the same path. Each VM activation tracks environment depth, so ordinary and labeled break/continue unwind the exact crossed scopes both directly and through finally. Labeled for-of continues avoid IteratorClose, labeled breaks close exactly once, and consecutive iteration labels now work in both the tree-walker baseline and required bytecode. New environment-mutating bytecodes fail closed above bytecode until native frame states carry equivalent metadata.
Measured evidence: 1,493/1,493 units with 0 skipped/failed/leaked; focused TSan repeated-body and moving-GC regressions 2/2; ReleaseFast test262 48,506/48,506 valid plus 4,669/4,669 negative with 0 skipped, 0 parse/runtime/host failures, and 0 flips; deterministic threadfuzz 400 programs from seed 1 with 0 failures; BunPress 49 pages and 90 link files.
This removes the captured-body and labeled multi-environment boundaries from the previous update. The first acceptance item remains open intentionally: destructuring defaults/computed-key evaluation still retains the exact tree-walker path, and the wider dynamic-scope, debugger, no-GIL, and suspension matrix in this issue is not complete. No dependency or tooling-script changes were made; the owned Home and BunPress boundaries remain intact.
chrisbbreuer commentedon Aug 4, 2026
The remaining captured-pattern evaluation boundary landed on
mainin6b60d843.Defaults, computed keys, nested array/object patterns, and object rest now lower directly into the active per-iteration bytecode environment. For example,
for (const {[key()]: value = fallback, ...rest} of inputs)stays in required bytecode while closures capture freshvalue/restcells. The lowering preserves RequireObjectCoercible before computed-key side effects, one ToPropertyKey coercion, exact IteratorClose, default anonymous-function naming, TDZ/const initialization, abrupt completion, and generator/async suspension. Unsupported native compilation still fails closed to the exact bytecode tier.Evidence:
This completes the first #465 acceptance checkbox. The issue stays open for corpus/PR-249 VM witnesses with step and async-order evidence, the full no-GIL/debugger/moving-GC matrix, and #460 tier-attribution evidence.
chrisbbreuer commentedon Aug 4, 2026
Implemented and pushed a16c5634 (
fix(vm): lower destructuring catch bindings).This removes the bytecode admission fallback for catch binding patterns. For example,
catch ({[key()]: value = fallback(), ...rest})now lowers defaults, computed keys, nested patterns, rest, TDZ, iterator closing, and captured per-execution cells directly into required bytecode; generator/async suspension and moving-GC relocation are covered. Binding-time failures also now execute an enclosingfinallybefore the new error propagates in both the VM and tree walker.Validation: 1,496/1,496 unit tests; focused TSan suspension and moving-GC witnesses; 184 JIT tests; 4 focused VM cases; GC relocation inventory; threadfuzz 400 programs from seed 1 with 0 failures; docs link/build gates; ReleaseFast test262 48,506/48,506 valid + 4,669/4,669 negative, 0 skipped. Flips 0 test262 cases; no regressions.
96 remaining items
fix(error): use prototype identity for instanceof (#822)
fix(vm): reject ordinary class calls before activation (#821)
chrisbbreuer commentedon Aug 28, 2026
Integration update: #813–#822 are now closed after their landed implementations passed terminal combined-main CI at e24c4fa: 53 checks succeeded, one nightly-only check skipped, zero failures/cancellations (https://github.com/zig-utils/zig-js/actions/runs/33211154123). Each issue has its implementation commit and scoped local/conformance evidence. Current uncommitted work is #823 (private realm Error identities and callback/GC roots) plus #826 (restriction enforcement across VM/native/quick/reflection paths). Focused Error tests and the first restriction matrix pass Debug and unsuppressed ReleaseSafe+TSan; the expanded checkpoint/GIL matrix passes Debug and the full 2,170-test sharded suite is running. #824/#825 remain separate follow-ups, not counted complete.
fix(array): retain realm intrinsics across callbacks (#824)
test(vm): require disposal bytecode in admission gates (#465)
chrisbbreuer commentedon Aug 30, 2026
Admission-gate maintenance landed in 15431f24 — test(vm): require disposal bytecode in admission gates (#465). Program, generator, async, and nested parameter-initializer gates had stale rejection expectations even though explicit resource management already emits registration and completion-preserving disposal bytecode. The tests now verify those opcodes and an exact required-tier Symbol.dispose result. Focused checks: 4 compiler admissions plus 2 runtime witnesses pass; combined units 2214 pass / 1 platform skip / 0 fail / 0 leak. Production engine code is unchanged; the broader #465 work remains open.
chrisbbreuer commentedon Sep 1, 2026
Resolved child issue #847 in 58ed1311: computed class element names with own private identifiers are now required-VM eligible. The exact class-elements witness improved by 4 cases with 0 regressions (0 divergences / 1,534 agreements), with full unit, TSan/no-GIL, moving-GC, ReleaseSafe, direct-eval, and threadfuzz coverage.
chrisbbreuer commentedon Sep 1, 2026
Fresh exact-current (
58ed1311) ReleaseFast census of the same six paired families used by #798/#799/#806 is now completely clean. Ordinary execution and required bytecode both pass 9,787 / 9,787, with zero failures and zero divergences:This reconciles the ten residual files reported by #806: #821 covers default derived-constructor call rejection, #838 owns execution-local for-of/yield-star protocol state, and #847 covers the four computed-private visibility cases; the Symbol-name cases also agree in the current aggregate. This proves the historical paired semantic admission boundary, but I am not closing #465 yet: its final exact before/after tier/environment-allocation acceptance still needs an auditable current comparison rather than inference from the clean corpus.
chrisbbreuer commentedon Sep 1, 2026
Environment-backed VM/tree-walker lookup parity was preserved by fix(runtime): seed environment binding maps (#850): 2,577 binding-heavy Test262 cases are byte-identical to the exact parent and required-VM reports 2,577 agree / 0 diverge. Direct-eval, TDZ, module live bindings, deletion, moving-GC, no-GIL/TSan, full units, and threadfuzz are clean. This removes the runtime default-hash surface without changing #465 admission policy; #465 remains open for its remaining universal-bytecode gates.
chrisbbreuer commentedon Oct 8, 2026
#1064 is complete in fd5baca: global-object Ordinary Get no longer leaks lexical/TDZ bindings or revives deleted builtin properties from the environment mirror. Persistent tree/required/shared-context tests pass 4/4 normally and under unsuppressed TSan; all 530 targeted global/declaration corpus cases remain byte-identical with zero failures.
The next Reference-resolution boundary is tracked as #1065 with an executed seven-assertion Node comparison. Identifier reads/typeof, strict/sloppy stores, inherited globals, and lexical-vs-property deletion still use stale root-mirror assumptions. The issue includes the canonical Reference/store pipeline and warmed global cache/proof checks, rather than another property-read workaround.
chrisbbreuer commentedon Oct 8, 2026
#1065 is complete: identifiers and captured global References now follow live object bindings, VM named stores share rooted Reference/PutValue handling, and lexical deletion is separate from object properties. Duplicate assignment helpers are removed.
The seven-assertion Node probe passes in tree/required modes. The broad global suite passes 39/39; focused normal/unsuppressed TSan tests pass 5/5 including an actual no-GIL worker. A published native global proof is tested across deletion, prototype mutation, and descriptor replacement. All 1,246 targeted global/declaration/delete/assignment/with/eval corpus cases remain byte-identical with zero failures.
chrisbbreuer commentedon Oct 8, 2026
Closed #1066 in d47d02c: corrected the private process/IPC fixtures to publish injected values as actual global object properties after #1064/#1065 removed environment mirror fallbacks. Both fixtures pass normal, ReleaseSafe, and unsuppressed TSan checks; the private ABI audit remains clean. Full CI is pending.
chrisbbreuer commentedon Oct 8, 2026
Closed #1067 in f86ff21: both conformance harnesses now publish host natives on the actual global object. The full packed wg-1.0 inventory exactly matches checked evidence in normal, ReleaseSafe, and unsuppressed TSan (18,795 pass, zero fail/crash, 475 exclusions over 73 files). The local smoke is restored to 33/33. #1068 is also closed in 1be5308: failed smoke runs now exit nonzero, verified with a one-case failure snapshot. Full hosted CI on the latest commit is pending.
fix(function): detach active arguments snapshots (#1092)
feat(jit): execute captured binding effects natively (#1095)