Track full JavaScript multithreading roadmap

[chrisbbreuer]

Goal

Track the work needed to move from today's experimental shared-realm thread surface to faithful JavaScript multithreading across agents.

Current baseline

• Context.createWith(.{ .enable_threads = true }) exposes shared-realm Thread, Lock, Condition, ThreadLocal, property-mode Atomics.wait/notify/waitAsync, and proposal-aligned Atomics.Mutex / Atomics.Condition entry points.
• The current WebKit PR-249 thread allowlist is 168/168 green.
• This is still serialized by the VM/GIL layer and is not full parallel JS heap mutation.

Work to build

• Agent boundaries: make context ownership and C-API handle affinity explicit, and define which values may cross threads.
• Worker agents: one context per OS thread with its own global object, realms, job queues, allocator state, module loader hooks, cancellation, and teardown.
• Structured clone and transfer: implement structuredClone, message passing, ArrayBuffer transfer/detach, and host hooks for worker lifecycle.
• Shared-memory baseline: complete SharedArrayBuffer, typed-array views over shared storage, Atomics, .agent, and wait/notify semantics across agents.
• Scheduler and queues: separate per-agent microtasks from host tasks, preserve deterministic promise ordering, and define blocking behavior.
• Heap and lifetime model: replace or contain the arena with a tracing GC, roots, write barriers, and cross-agent ownership rules before shared object graphs are safe.
• Concurrency validation: expand the PR-249 corpus, add stress tests for transfer/detach races, shared typed-array atomics, worker teardown, host callbacks, and ThreadSanitizer runs.

TC39 structs/proposal-structs

Track tc39/proposal-structs. Fixed-layout structs, shared structs, Atomics.Mutex, and Atomics.Condition are relevant to the eventual data model for parallel JS. They should layer on top of workers, structured clone, SharedArrayBuffer, Atomics, and the GC/lifetime work rather than replace those foundations.

Acceptance signal

• Roadmap docs describe the above prerequisites clearly.
• Thread tests document what is green today versus what remains serialized or unsupported.
• Shared structs are revisited when either the proposal reaches Stage 3 or zig-js has the GC foundation needed for shared object lifetimes.