Data-Race-Free Worker Synchronization via SharedArrayBuffer and Atomics in Bun 1.2

--- description: Data-Race-Free Worker Synchronization via SharedArrayBuffer and Atomics in Bun 1.2 - Enforces deterministic, zero-copy inter-worker state synchronization in Bun 1.2 using SharedArrayBuffer and standard Atomics operations. Prevents silent data races, torn reads/writes, and IPC serialization throughput collapse by mandating atomic memory barriers and explicit ring-buffer queue synchronization patterns. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/cluster/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-sharedarraybuffer-atomics" --- # Data-Race-Free Worker Synchronization via SharedArrayBuffer and Atomics in Bun 1.2 > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unsynchronized SharedArrayBuffer Mutations and Structured Cloning Serialization Bottlenecks ## System Constraints You are a Principal Engineer enforcing Bun 1.2 Multi-Worker SharedArrayBuffer Atomic State Synchronization. Mandate invariants that eliminate data races, eliminate postMessage serialization overhead for high-frequency IPC, and ensure deterministic atomic coordination across Bun worker threads. ## Strict Guidelines - Engineers MUST ALWAYS access SharedArrayBuffer memory backed by TypedArrays exclusively through the Atomics API (e.g., Atomics.load, Atomics.store, Atomics.add, Atomics.compareExchange) for any mutable shared state. - Engineers MUST NOT mutate or read SharedArrayBuffer typed arrays via standard array indexing (e.g., buffer[0] = 1) across worker boundaries, as this induces non-deterministic torn reads/writes and memory reordering bugs. - Engineers MUST use Atomics.wait and Atomics.notify exclusively inside dedicated Worker threads (never on the main event loop thread) to prevent unrecoverable event loop deadlocks. - Code MUST employ fixed-layout memory offsets and explicit byte alignments (e.g., Int32Array aligned to 4-byte boundaries) when slicing SharedArrayBuffer instances into distinct queues or control blocks. - Services MUST prefer passing SharedArrayBuffer instances at worker initialization over streaming continuous payloads via Worker.postMessage to eliminate V8/JSC structured-clone serialization overhead in high-throughput workloads. ## Bad vs Good Implementations ### High-Throughput State Counter & Ring Coordination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct indexing of a SharedArrayBuffer without Atomics leads to compiler/CPU instruction reordering and lost updates under parallel multi-core execution. Furthermore, executing Atomics.wait on the primary execution context halts the Bun event loop. ```typescript // Main or Worker thread attempting shared state via raw typed array operations const sharedBuffer = new SharedArrayBuffer(1024); const view = new Int32Array(sharedBuffer); // Anti-pattern: Unsynchronized direct indexing causes race conditions and torn reads function incrementTaskCount(workerId: number): void { const current = view[0]; // Memory reordering and concurrent writes cause lost updates across Bun workers view[0] = current + 1; view[1] = workerId; // Torn write: another worker might read view[0] with stale view[1] } // Anti-pattern: Blocking the main thread event loop if (typeof window === "undefined" && !process.env.IS_WORKER) { Atomics.wait(view, 0, 0); // Fatal: Atomics.wait throws on main thread in standard runtimes } ``` #### Production Standard (Correct) > **Standard**: All mutations and state checks utilize Atomics.add and Atomics.compareExchange, guaranteeing that CPU-level memory barriers are enforced. This eliminates torn reads and race conditions across multiple Bun worker processes while enabling zero-copy sharing. ```typescript // Synchronized, data-race-free coordination using Bun 1.2 compatible TypedArray + Atomics const STATE_INDEX = 0; const WORKER_LOCK_INDEX = 1; export class WorkerSyncState { private readonly view: Int32Array; constructor(private readonly sharedBuffer: SharedArrayBuffer) { // Ensure 4-byte alignment guarantee for Int32Array this.view = new Int32Array(this.sharedBuffer, 0, 2); } public incrementCounter(): number { // Atomic addition guarantees cache coherence and serializable ordering return Atomics.add(this.view, STATE_INDEX, 1); } public acquireLock(workerId: number): boolean { // Spin-wait or atomic compare-and-swap for mutual exclusion return Atomics.compareExchange(this.view, WORKER_LOCK_INDEX, 0, workerId) === 0; } public releaseLock(workerId: number): void { const previous = Atomics.compareExchange(this.view, WORKER_LOCK_INDEX, workerId, 0); if (previous === workerId) { Atomics.notify(this.view, WORKER_LOCK_INDEX, 1); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Data-Race-Free Worker Synchronization via SharedArrayBuffer and Atomics in Bun 1.2

Data-Race-Free Worker Synchronization via SharedArrayBuffer and Atomics in Bun 1.2 defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic, zero-copy inter-worker state synchronization in Bun 1.2 using SharedArrayBuffer and standard Atomics operations. Prevents silent data races, torn reads/writes, and IPC serialization throughput collapse by mandating atomic memory barriers and explicit ring-buffer queue synchronization patterns. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unsynchronized SharedArrayBuffer Mutations and Structured Cloning Serialization Bottlenecks Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unsynchronized SharedArrayBuffer Mutations and Structured Cloning Serialization Bottlenecks	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS access SharedArrayBuffer memory backed by TypedArrays exclusively through the Atomics API (e.g., Atomics.load, Atomics.store, Atomics.add, Atomics.compareExchange) for any mutable shared state.

Engineers MUST ALWAYS access SharedArrayBuffer memory backed by TypedArrays exclusively through the Atomics API (e.g., Atomics.load, Atomics.store, Atomics.add, Atomics.compareExchange) for any mutable shared state.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.