Skip to content

Roadmap: implement every README-declared missing runtime surface #134

Description

@chrisbbreuer

Goal

Implement every runtime and platform surface currently called out in the README's What Is Not Implemented section, with checked-in compatibility inventories and reproducible evidence, so that the section can be removed without qualification.

This is an umbrella issue. Each independently reviewable implementation slice should have its own linked child issue before substantial work begins.

Scope

1. JavaScriptCore compatibility surfaces

  • Check in a versioned inventory of the public JavaScriptCore C API and implement every symbol in the declared target.
  • Check in version-pinned inventories for the private framework/internal surfaces we intentionally target, then implement every inventoried entry.
  • Implement and test the Objective-C bridge, including object/value conversion, exceptions, lifetimes, blocks/callables, and cross-runtime identity.
  • Implement inspector/debugger APIs and protocol behavior, including attach/detach, breakpoints, stepping, evaluation, stack/scope inspection, pause/resume, and exception events.
  • Define version-pinned Bun and Home private-JSC ABI compatibility profiles and implement every symbol and behavior in those profiles.
  • Reject unsupported ABI versions explicitly; no silent no-ops or accidental partial compatibility.

Complete here means complete for the exact checked-in target inventories. Private ABIs are moving targets, so each supported revision must be named and auditable rather than described as universal compatibility.

2. WebAssembly

  • Parser, binary decoder, validator, and deterministic malformed-module diagnostics.
  • Module compilation/instantiation and JS-facing Module, Instance, Memory, Table, Global, and Function behavior.
  • Imports, exports, start functions, traps, growth, bounds checks, numeric conversions, and JS/Wasm exception boundaries.
  • Declare and implement the chosen post-MVP feature set (reference types, bulk memory, multi-value, SIMD, threads, exceptions, GC, etc.) in versioned feature profiles.
  • Run the applicable upstream WebAssembly specification tests with an explicit zero-hidden-skip inventory for the supported profiles.

3. PR-249 reference corpus and shell hooks

  • Inventory every WebAssembly/JIT shell hook used by the PR-249 reference corpus.
  • Promote each relevant reference-only hook into maintained runtime functionality with tests and documentation.
  • Remove or explicitly disposition every corpus exclusion; no untracked skip lists.

4. Production generational GC

5. Optimizing JIT

Removal gate

The README section may be removed only when all of the following are true:

  • Every checklist item above is complete or decomposed into completed linked child issues.
  • A checked-in compatibility matrix names exact OS, architecture, JSC, Bun/Home ABI, WebAssembly feature, GC, and JIT targets.
  • Normal, thread-heavy, no-GIL, leak, sanitizer/TSan, differential, inspector, bridge, API/ABI, WebAssembly, and JIT suites pass for the declared matrix.
  • Relevant upstream/reference corpora publish machine-readable pass/fail/skip inventories, with no unexplained exclusions.
  • Benchmarks and README claims are regenerated from committed artifacts and clearly distinguish correctness coverage from performance coverage.
  • Unsupported hosts or revisions fail clearly at build or runtime rather than exposing partial behavior.

Related work

Child issue map

Public and private embedding

WebAssembly and reference corpus

GC and JIT

Completion evidence

Latest evidence

WebAssembly MVP #141 and its exact wg-1.0 corpus chain #260/#261 remain complete. The versioned post-MVP foundation #262, Core 2 numeric operations #269, and complete structural baseline #263/#270-#278 are now complete. The committed Core 2 inventory at 12ce485e pins official wg-2.0 and WABT 1.0.39 exactly: 27,437/27,437 applicable commands pass across all 90 files, 581 text-format commands are explicitly not applicable, and failures/runner errors are zero. Bounded CI landed in a593fdea; README and detailed evidence were refreshed in 66a953a6. The most recent batched full engine checkpoint remains 1,002/1,002 at af689c4a, and the general JavaScript comparison remains the validated 1,540-sample July 17 matrix because these WebAssembly paths do not execute in its workloads. Fixed-width SIMD #264/#279-#283 is now complete: the exact pinned 56-file score is 25,466/25,466 applicable commands with zero failures/runner errors, and the separate July 18 SIMD matrix preserves 224 scalar/JSC samples with every median above 50 ms. Terminal inventory, CI, architecture/fallback declarations, raw artifacts, README, and reproduction landed through be438ae0. Multi-memory #305 is complete with 829/829 pinned commands and documented robustness/sanitizer gates. Remaining WebAssembly roadmap work is #265-#268. PR-249 foundation #311 pins and checksums all 339 vendored files. #428 is complete at e6d15b1e/fa71b012: the verifier classifies all 259 executables as 243 promoted, 10 optimizing-JIT blocked by #429, and 6 executable terminal dispositions; all five helpers remain classified, and inventory/hook/disposition/evidence drift fails closed. Private property iteration #368 is complete at 4be4789d with its evidence label refreshed at 01cfa77b: Home is now 352/471 private symbols implemented (119 pending), Bun is 344/461 (117 pending), the shared Home consumer links 339/339 symbols, and a dedicated Bun compile-link-runtime fixture passes in Debug and ReleaseSafe.

ArrayBuffer ownership #369 is complete at 07a3e398: Home is 356/471 private symbols implemented (115 pending), Bun is 348/461 (113 pending), both inventories have zero unclassified entries, the Home consumer links 343/343, and the focused engine plus dedicated Bun fixtures pass in Debug and ReleaseSafe.

Value-key property work #370 is complete at 01b3aef3: Home is 359/471 private symbols implemented (112 pending), Bun is 351/461 (110 pending), both inventories have zero unclassified entries, the Home consumer links 346/346, and focused engine plus Bun-profiled fixtures pass in Debug and ReleaseSafe.

Private C-API extensions #371 are complete at 930f177b: Home is 361/471 private symbols implemented (110 pending), Bun is 353/461 (108 pending), both inventories have zero unclassified entries, the Home consumer links 348/348, and focused engine plus dedicated Bun fixtures pass in Debug and ReleaseSafe.

Exact JSC Math.pow operation #372 is complete at 3e96dde2: the private C export and JavaScript builtin share one edge-correct implementation; Home is 362/471 (109 pending), Bun is 354/461 (107 pending), Home links 349/349, and focused plus compiled-consumer evidence passes in Debug and ReleaseSafe.

Current private-ABI evidence

At 172fea6, Home is 375/471 implemented (96 pending), Bun is 367/461 (94 pending), the Home consumer links 362/362, and the focused Bun DOMFormData fixture links 10/10. Debug and ReleaseSafe pass, including 25/25 relocation tests.

Latest private-ABI checkpoint

At 9c51dee, Home is 376/471 implemented (95 pending), Bun is 368/461 (93 pending), and the Home fixture links 363/363. Debug and ReleaseSafe pass for the shared Home and exact Bun evidence.

Checkpoint at 6427d1c: #392 is complete. Home is 409/471 private implemented (62 pending); Bun is 401/461 (60 pending). Exact multi-VM, detach/reentrancy, Debug, and ReleaseSafe evidence passes with zero leaks; benchmark scores are unchanged because this is compatibility work.

Checkpoint at 4275f7c: #404 is complete with exact fixing-main CI evidence. #405 implements all six pinned ReadableStream consumers and is awaiting only its exact main CI gate. Home is 439/471 private symbols implemented (32 pending); Bun is 430/461 (31 pending). Focused engine and external Home/Bun consumers pass in Debug, ReleaseSafe, and TSan; README benchmark scores are unchanged because this is compatibility work.

July 28, 2026 PR-249 terminal checkpoint

f6f8ef1b completes #143, #429, and #430. The pinned 339-file reference tree now records 259 executables as 253 promoted, 0 blocked, and 6 verifier-enforced terminal dispositions, plus five helpers outside the denominator. ReleaseSafe passes 246/246 serialized-required and 253/253 no-GIL-required promoted cases with zero failures or skips; all six terminal dispositions match in both modes. The release matrix reached 9/12 green at that checkpoint.

July 29, 2026 optimizer release checkpoint

9e51e1ff completes #146, #433, and #434. The sole declared optimizer backend is macOS AArch64; 24 seeded serialized/no-GIL differentials require real publication and exact guard deoptimization, normal and TSan focused gates pass 176/176, the full unit suite passes 1,452/1,452, and unsupported macOS/Linux x86-64 builds remain explicit fallback. The machine-readable optimizer inventory and dated raw JavaScriptCore artifact move the release matrix to 10/12 green. Remaining roadmap blockers are #446 automatic shared compaction evidence and #447 moving nursery.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions