Goal
Track the work needed for zig-js to support a logically sound multithreaded JavaScript runtime beyond the current shell/thread corpus work.
Motivation
We want JavaScript execution to scale across threads while preserving ECMAScript semantics, host integration, GC correctness, and predictable test262/conformance behavior. The design should be general to zig-js consumers, not tied to one embedding.
Areas To Design
- Agent and realm ownership rules for concurrent execution.
- SharedArrayBuffer, Atomics, waiter tables, and host wake/sleep behavior.
- GC safepoints, stack scanning, finalization, weak references, and world-stop coordination.
- Promise/microtask scheduling across thread-local and shared queues.
- Module/global object isolation and cross-agent object transfer rules.
- Embedding API shape for creating workers, joining, cancellation, and shutdown.
- Deterministic conformance gates for unit tests, the vendored thread corpus, and test262.
TC39 Structs Angle
Evaluate tc39/proposal-structs as a possible future-facing primitive for shared structured data. The architecture should identify which pieces would benefit from structs, where current SharedArrayBuffer/Atomics is enough, and what abstractions would let us adopt structs without rewriting the threading model.
Acceptance Direction
- Document an architecture with phased milestones.
- Keep existing single-thread behavior and test262 progress stable.
- Add focused conformance gates for each phase before enabling broader parallel execution.
- Avoid Craft-specific naming or assumptions in public docs and APIs.