Threads: maintain the shared-realm JavaScript memory model

[chrisbbreuer]

Parent: #1

Goal

Keep the public contract for JavaScript-defined races, engine-state races, synchronization, and GC publication precise as the runtime evolves.

Current baseline

docs/threads/memory-model.md now defines:

• Lock/Atomics.Mutex release-to-acquire publication.
• Condition wait release/reacquire semantics, predicate-loop requirements, non-buffered notifications, and the fact that notify alone is not a publication substitute.
• Sequentially consistent typed-array Atomics and per-(object, key) property-Atomics linearization/publication.
• Thread join/asyncJoin completion, result/exception identity, and prior-side-effect publication.
• Per-queue microtask FIFO and synchronized cross-thread queue handoff without a promised global order across independent producers.
• The boundary between ordinary racing values, explicit ConcurrentAccessError restriction, and engine-state corruption.
• GC reachability publication as an internal safety mechanism that does not create JavaScript happens-before.

ThreadSanitizer currently runs without a suppression file. Intentional JavaScript shared-buffer byte races are either synchronized in the engine paths or must be handled by a future narrow, load-bearing suppression witness; engine metadata, synchronization, GC, root, lifetime, and handle state remain unsuppressed. Recent maintenance also hardened engine-owned lifetime/handle state: SharedBufferStorage retain counts and C-API protected-handle counts use checked increments, and C value/object boxes carry owner-context tags so context-taking APIs fail closed on wrong-realm handles.

Completed milestone

• Specify ordering guarantees for Lock, Condition, property Atomics, typed-array Atomics, Thread join/asyncJoin, and task/microtask delivery.
• Document which ordinary object races have unspecified values versus explicit ConcurrentAccessError behavior.
• Align GC write-barrier/publication rules with the landed nursery and concurrent full collector.
• Add litmus tests for the documented happens-before guarantees.
• Audit the memory-model docs and suppression boundary for the nursery/shared-state changes.
• Remove stale TSan suppression wiring and keep required gates running suppression-free.
• Harden shared-buffer and C-API handle lifetime accounting against refcount/protection-count wraparound and wrong-context handle use.

Ongoing maintenance

• Re-run the focused memory model: normal and TSan tests whenever synchronization or queue handoff changes.
• Add a minimized litmus test before strengthening any public ordering claim.
• Keep GC publication explicitly separate from program synchronization.
• Keep test-only controls excluded from the stable embedder API.
• Re-audit the no-suppression ThreadSanitizer policy whenever a new raw program-byte access helper is introduced. If a future suppression becomes necessary, land it with a deterministic witness that fails without the suppression and passes with it.
• Keep owner-context and lifetime/refcount invariants regression-gated whenever public C handles or shared backing storage change.

Acceptance criteria

• Public guarantees have executable witnesses.
• TSan runs remain suppression-free, or any future suppression is narrow and load-bearing.
• Test-only controls remain clearly excluded from the stable embedder API.

[chrisbbreuer]

Landed 6b215b3 test(threads): specify memory-model publication edges on main.

Public contract added

• Releasing a Lock / Atomics.Mutex publishes prior ordinary writes to the next successful acquire of that lock.
• Condition.wait releases and reacquires the associated lock; the reacquire publishes the predicate state. Notifications are not buffered, may be spurious, and are not a substitute for locking the predicate.
• Typed-array Atomics are sequentially consistent.
• Property Atomics linearize per addressed (object, key) and publish earlier sequenced writes when the reader observes the atomic publication.
• join() and asyncJoin() publish completion side effects and preserve returned/thrown value identity, including already-completed joins.
• Spawned threads drain their own FIFO microtasks before completion publication; cross-thread queue handoff is synchronized, but independent producers have no promised global total order.
• Ordinary shared-object/collection races remain program races with unspecified winning/intermediate values.
• ConcurrentAccessError applies only after explicit successful Thread.restrict ownership.
• GC barriers, remembered owners, root handshakes, and born-cell publication preserve reachability but do not create JavaScript happens-before.

Executable witnesses

Six focused no-GIL unit tests now cover:

• Lock release + Condition reacquire publication of nested ordinary object writes.
• Property Atomics flag publication of an ordinary object payload.
• Typed-array Atomics flag publication of an ordinary object payload.
• join side effects, return identity, thrown identity, and asyncJoin settlement.
• Per-thread FIFO microtask drain before completion.

Verification

• zig build test -Dtest-filter='memory model:'
• zig build test -Dtsan=true -Dtest-filter='memory model:'
• zig build test
• bun run docs:build
• git diff --check

This slice changes docs/tests only. The full all-tests TSan sweep and clean 227/227 corpus had already passed immediately before it on the same runtime commit; they were not rerun after this docs/test-only commit.

#12 remains open as a maintenance tracker: any future strengthening of the public contract still requires a focused executable witness, and new raw byte-access helpers still require suppression-boundary review.

[chrisbbreuer]

Memory-model maintenance check after the per-queue microtask lock change in caad91e:

• Local focused gate passed: zig build test -Dtest-filter="memory model:".
• This specifically rechecks the documented lock/condition publication, property/typed-array Atomics publication, join/asyncJoin publication, and per-thread microtask FIFO-before-completion witnesses after moving no-GIL microtask synchronization from a realm-wide lock to queue-local locks.
• The public memory-model text already describes per-queue FIFO plus synchronized cross-thread handoff without a global order across independent producers, so no contract text needed to change.

Fresh CI for the pushed chunk is still running, with early green checks including docs, test262-parallel, threads-nogil-witness, tsan-parallel-js, and threadfuzz-verify: https://github.com/zig-utils/zig-js/actions/runs/29114710319.

[chrisbbreuer]

Memory-model/lifecycle guard fix landed in zig-js a0375cb (fix(threads): pair backing unlocks with acquisitions).

Root cause from tsan-threadfuzz-lifecycle: Object.lockBacking() was gated by the global element_locks_enabled flag, and unlockBacking() checked the flag again at defer time. In parallel lifecycle setup, that flag can flip between the two checks, so a context could attempt to unlock an unheld std.atomic.Mutex while installing the Thread API.

Fix: lockBacking() now returns whether it actually acquired the lock, and all unlocks use that captured boolean. Added a focused regression: Object backing lock pairs unlock with actual acquisition.

Focused validation also passed the exact local lifecycle TSan command: zig build threadfuzz -Dtsan=true -Dfuzz-lifecycle=true -Dfuzz-iters=2 → 112 programs from seed 1, 0 failures.

CI rerun: https://github.com/zig-utils/zig-js/actions/runs/29116066646

[chrisbbreuer]

Pushed another small CI hardening chunk: 87c4c8b (fix(threads): enable binding locks before thread builtins).\n\nWhat changed:\n- Replaced the old set/unset parallel synchronization switch with an enable-only process-wide helper.\n- For threaded parallel/concurrent-GC contexts, binding/object/IC synchronization is enabled before Thread/Atomics builtins are installed. That closes the lock/unlock mismatch seen in CI where Environment.get() could take the fast path before another lifecycle thread flipped binding locks on, then unlock a mutex it never acquired.\n- The flags are left enabled process-wide once needed, avoiding false→true→false races across concurrent context startup.\n\nFocused local checks run before push:\n- zig build test -Dtest-filter="Object backing lock pairs unlock with actual acquisition"\n- zig build test -Dtest-filter="enable_threads: Object backing allocator stays synchronized under parallel_js"\n\nI did not rerun the broad/slow fuzz gates locally. The previous main CI run also exposed separate midgc termination-reaction failures; I’m tracking those under the mid-script/lifecycle fuzzing issues rather than mixing them into this lifecycle-lock chunk.

[chrisbbreuer]

Correction to the previous binding-lock note: 87c4c8b enabled synchronization before threaded builtins, but CI showed a remaining create-time race earlier in setup (). Pushed 641c5e9 to make true from process start, eliminating the false→true lock/unlock mismatch for binding tables during concurrent context creation.\n\nThis is intentionally conservative and compatible with the "perfect tool first" direction: we can later replace the process flag with a per-call acquisition token or owner guard if profiling shows the default binding lock cost matters.\n\nFocused checks: two lock-pair/backing tests passed, and non-TSan passed locally.

[chrisbbreuer]

Correction to the previous binding-lock note, with shell-safe wording: 87c4c8b enabled synchronization before threaded builtins, but CI showed a remaining create-time race earlier in setup at Context.createWithTestingOptions while reading the $262 global binding. Pushed 641c5e9 to make Environment binding locks true from process start, eliminating the false-to-true lock/unlock mismatch for binding tables during concurrent context creation.

This is intentionally conservative and aligned with the perfect-tool-first direction: we can later replace the process flag with a per-call acquisition token or owner guard if profiling shows the default binding lock cost matters.

Focused checks: two lock-pair/backing tests passed, and non-TSan threadfuzz lifecycle 2 1 passed locally.

[chrisbbreuer]

Shared-memory-model maintenance update pushed in zig-js@0b29b20 (fix(dataview): serialize resize races):

• DataView.prototype.get*/set* now validate the live view bounds and read/write through the same backing-byte snapshot while holding ArrayBufferData.lockBuffer when a non-shared resizable buffer can be resized by a peer.
• Added a shared-realm witness where one Thread repeatedly performs DataView reads/writes while the owner resizes the same resizable ArrayBuffer.
• Local validation:
  • zig build test -Dtest-filter="DataView access serializes with parallel ArrayBuffer resize" --summary none
  • zig build test -Dtsan=true -Dtest-filter="DataView access serializes with parallel ArrayBuffer resize" --summary none

This is an engine-state race fix; JavaScript-level racy values remain intentionally distinct from engine storage safety.

[chrisbbreuer]

Additional shared-memory-model safety update pushed in zig-js@227b69a (fix(arraybuffer): lock immutable slice copy):

• ArrayBuffer.prototype.sliceToImmutable now re-checks the resolved source range and copies from the source through ArrayBufferData.lockBuffer when peer resize/free is possible. This mirrors the existing ArrayBuffer.prototype.slice source-side UAF guard.
• Added a shared-realm witness where one thread repeatedly calls sliceToImmutable(0, 64) while the owner resizes the same resizable ArrayBuffer.
• Local validation:
  • zig build test -Dtest-filter="ArrayBuffer sliceToImmutable serializes with parallel resize" --summary none
  • zig build test -Dtsan=true -Dtest-filter="ArrayBuffer sliceToImmutable serializes with parallel resize" --summary none

This is another engine-state race/security hardening fix; it does not strengthen JavaScript program-race ordering claims.

[chrisbbreuer]

Docs follow-up pushed in zig-js@334ebf0 (docs(threads): document buffer resize guards):

• Updated the value.ArrayBufferData synchronization audit to include DataView read/write helpers and ArrayBuffer bulk-copy guards (slice / sliceToImmutable) alongside typed-array element helpers.
• Updated the testing guide to mention the deterministic DataView access and sliceToImmutable resize-race witnesses, not just constructor races.
• Validation for this docs-only chunk: git diff --check plus stale wording scan for the replaced phrases.

[chrisbbreuer]

Security-quality/bindings-audit update pushed in zig-js@e962457 (fix(math): seed random from entropy):

• Math.random() no longer starts every process/thread from one fixed deterministic DefaultPrng seed.
• The PRNG remains threadlocal, preserving the no-GIL race-free ruling, but is now lazily seeded from the engine std.Io.randomSecure entropy source. If secure entropy is unavailable, it falls back to a thread-id-mixed deterministic seed rather than failing JS execution.
• Added a focused Math.random unit witness for [0, 1) values and advancing stream behavior.
• Local validation:
  • zig build test -Dtest-filter="Math.random" --summary none
  • zig build test -Dtest-filter="Math" --summary none
  • zig build test -Dtsan=true -Dtest-filter="Math.random" --summary none

This closes the stale audit note that called out the fixed seed as a future quality pass.

[chrisbbreuer]

Follow-up pushed in 97fd03d5 (fix(math): harden random entropy fallback).

This keeps the secure entropy path as the normal Math.random seed source, but removes the fixed fallback constant if randomSecure is unavailable: the fallback now mixes the awake timestamp and current thread id before seeding the per-thread PRNG. This is still a fallback, but it avoids silently returning to deterministic streams in unusual environments.

Focused validation:

• zig build test -Dtest-filter="Math.random" --summary none
• zig build test -Dtsan=true -Dtest-filter="Math.random" --summary none
• git diff --check