Canonical: JavaScript multithreading support

[chrisbbreuer]

Canonical Tracker

This is the single canonical issue for JavaScript multithreading in zig-js.
Older duplicate roadmap issues should point here instead of tracking similar
work in parallel.

Authoritative design and status docs live in docs/threads:

• docs/threads/index.md - start here and support matrix.
• docs/threads/api.md - current shared-realm thread API.
• docs/threads/testing.md - exact Zig 0.17-dev verification commands.
• docs/threads/limits.md - current GIL semantics and Layer-C blockers.
• docs/threads/bindings.md - mutable-state rulings.
• docs/threads/P7-gc-design.md, docs/threads/P7-gil-removal.md, and
  docs/threads/P8-structs.md - GC, GIL removal, and TC39 structs planning.

Current State

• Layer A isolated agents / workers / shared memory are implemented: real
  OS-thread agents, retained SharedArrayBuffer storage, typed-array
  Atomics.wait / notify / waitAsync, structured clone, ArrayBuffer
  transfer/detach, and Worker APIs are covered by unit and conformance tests.
• Layer B shared-realm Thread is implemented behind
  Context.createWith(.{ .enable_threads = true }): Thread, Lock,
  Condition, ThreadLocal, ConcurrentAccessError, property-mode
  Atomics.*, and proposal-aligned Atomics.Mutex / Atomics.Condition
  entry points.
• Shared-realm threads run on real OS threads, share one realm and object
  identity, and are serialized by the context GIL. This is concurrency, not
  true parallel JS heap mutation.
• C-API JSStringRef values are immutable and use atomic retain/release.
  GC-enabled JSValueRef wrappers use counted JSValueProtect /
  JSValueUnprotect roots; JSValueRef and JSObjectRef access remains
  context-affine.
• Shape transition maps are synchronized with a per-shape transition_lock, so
  concurrent same-name transitions converge on one child shape. Ordinary
  named-property helper paths, named-property delete/rebuild, and VM
  plain-property inline caches are synchronized with Object.property_lock,
  covering helper-routed shape publication, slot vector updates, accessor maps,
  attribute maps, and key order. Per-promise settlement and reaction-list state
  is synchronized with Promise.lock; awaitValue, async thenable guards, and
  GC tracing use locked snapshots/marking for that state. Object.elements_lock
  is now the indexed-storage synchronization funnel: central dense-array
  get/set/delete/length paths, packed reverse/sort/splice fast paths, Map/Set
  helper methods, Map/Set forEach slot snapshots, native Set helper scans,
  and Map/Set cursors use it.
• Remaining direct Object.elements side doors, arena allocation around
  transitions, microtask queues, async waiter arrays, running stack roots, and
  Value atomicity remain Layer-C blockers protected by the context GIL.
• The WebKit PR-249 thread allowlist is currently documented as 209/209
  green. Remaining reference-only files are tracked in
  docs/threads/testing.md with concrete reasons.
• The GC is opt-in (enable_gc) and now collects mid-script, including
  while peer threads are parked, not only at quiescent points: zig-js uses
  the sibling zig-gc collector for precise mark-sweep, driven at the engines'
  (steps & 1023) safepoints. Live Values the precise tracer can't see are
  rooted by conservative native-stack + register scanning (src/stack_scan.zig):
  the collecting thread's own stack, plus every parked peer's published scan
  range (the multi-thread safepoint protocol — a parking thread publishes its
  range before releasing the GIL; a safety net aborts collection unless every
  peer is parked-and-published). VM Exec operand stacks are registered as
  precise roots. The GC now reclaims at safepoints under the full threading
  model with the GIL held, and marks incrementally (M2): a Dijkstra
  insertion write barrier is wired into every post-creation heap→heap
  reference-store funnel (Object slots/elements/accessors, Environment bindings,
  VM property IC, Promise/Generator, Map/Set, proto reparent), with mid-cycle
  allocations born grey and a finish-time root re-scan; collectMidScript steps
  startMarking/markStep/finishMarking for GC-on contexts. Layer-C / GIL
  removal now needs a Value atomicity story (NaN-boxing, blocker #7), then M3
  (drop the GIL, mark concurrently behind this barrier) with a TSan campaign.

Work Still Tracked Here

• Keep docs/threads and this issue aligned whenever thread behavior, counts,
  or blockers change.
• Promote PR-249 files only when the engine implements the behavior and the
  file passes reliably under Zig 0.17-dev.
• Finish the GC/root story needed for Layer C: stack roots for arbitrary
  running/parked native frames, safe collection around shared-realm threads,
  write barriers or stop-the-world coordination, and dependency work in
  ~/Code/Libraries/zig-gc when the collector mechanism belongs there.
• Design and implement the remaining object/value synchronization before
  removing the GIL: remaining direct Object.elements side doors, microtask
  queues, async waiter arrays, and ordinary Value slots must have a real
  concurrent access story. Keep transition-map mutation funneled through
  Shape.transition, named-property metadata funneled through
  Object.property_lock, indexed storage funneled through
  Object.elements_lock, and Promise state funneled through Promise.lock.
• Decide the final Value representation / atomicity model before true
  parallel heap mutation.
• Keep C-API context affinity rules explicit; do not expose test-only host
  knobs as stable embedder APIs until they have a real public contract.
• Track TC39 proposal-structs only through this issue and
  docs/threads/P8-structs.md; do not open another parallel
  structs/threading tracker.

Verification Gates

Use Zig 0.17-dev:

zig build test
zig build threads-test
zig build threads-test -Dthreads-case=atomics/property-waitasync-timeout.js
zig build test -Dtsan=true
bun run docs:build

Thread work should also run focused PR-249 cases for the touched behavior,
update the allowlist/count docs when promotion is real, and keep
docs/threads/bindings.md current for every new mutable global or threadlocal
state.

[chrisbbreuer]

Also should keep an eye on this one oven-sh/WebKit#249 - maybe we can reuse quite a bit of it

[chrisbbreuer]

Progress 2026-06-10: Phases 0–2 are implemented and on main (through d85c080).

• P0: Context thread-affinity guardrails (debug asserts, C-API thread rules), docs/threads/bindings.md audit (10 globals ruled; found two the plan missed: Math.random's process-global PRNG and the global symbol counter — both fixed in P2), PR-249 corpus vendored under reference/webkit-249/ (240 test files + full docs/threads specs + THREAD.md, head 25375a99).
• P1: src/shared_buffer.zig — refcounted process-wide SAB storage, in-place CAS grow, RetainList per realm; ArrayBufferData reworked behind bytes() (compiler-forced audit of all ~56 byte-access sites); Atomics RMW/CAS/load/store are single SeqCst hardware ops (raw-bits path also fixed BigInt64 precision); 8-byte-aligned buffers.
• P2: src/agent.zig — $262.agent on real OS threads with the INTERPRETING.md broadcast rendezvous; Atomics.wait genuinely blocks (FIFO waiter table, per-ticket condition + timeout, [[CanBlock]]); notify really wakes; real sleep/monotonicNow; the cooperative model is deleted. Atomics-subtree workers run one test per process so a deadlock costs one 30s timeout.

Score: 41,898 → 42,137/47,928 (87.9%); built-ins/Atomics 308 → 349/388 (89.9%), zero host-fails (no hangs in two full runs). End-to-end concurrency is unit-tested (agent parks → broadcast → blocked wait → cross-thread notify → report).

Remaining Atomics failures are mostly Atomics.waitAsync (101 test files) → that's Phase 3, designed in docs/threads/P2-agents.md (async tickets on the same waiter table + drain-loop integration in Context.evaluate). Also still open from P2: the CanBlockIsFalse runner mode (2 tests).

[chrisbbreuer]

Phase 3 landed (9999301, 28baab2): Atomics.waitAsync settles for real — async tickets share the blocking waiters' FIFO lists (spec notify ordering across wait/waitAsync), and the realm's drain tail resolves the promises on notify/deadline/teardown, abandoning unsettleable infinite waits instead of hanging. The CanBlockIsFalse runner mode closes the last Phase 2 box (both tests now scored and passing).

42,230/47,930 (88.1%); built-ins/Atomics 356/390 (91.3%), still zero host-fails. ~34 Atomics failures remain (under diagnosis). Next big block: Phase 4 structured clone.

[chrisbbreuer]

Phase 4 landed (ba41807): structured clone. src/structured_clone.zig serializes value graphs into a self-contained byte stream (deliberately so — it's the Phase 5 postMessage wire format) and deserializes into any realm's arena. Full type coverage incl. cycles/identity, array holes, SAB storage sharing, and { transfer } (move + detach); DataCloneError for the unclonables. The structuredClone global is installed. test262 unchanged at 42,230/47,930 (88.1%) — additive feature, zero regressions, gate run confirms.

Still open from Phase 4: ArrayBuffer.prototype.transfer predates this work (already done). Next: Phase 5 — embedder Worker API (spawn = Context-per-thread + this wire format + the agent group's channel machinery), then Phase 6 (GIL Thread API, port the vendored PR-249 corpus).