SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Spin-Locking Shared Buffers and Unsynchronized TypedArray Reads Causing Torn Frames and GC Stutters) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard

--- description: SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard - Enforces lock-free ring buffers, explicit atomic memory fences, and zero-allocation frame loops across Web Workers feeding OffscreenCanvas rendering contexts. Guarantees memory barrier ordering and eliminates CPU-saturating spin-locks, torn reads, and garbage collection pauses across cross-thread shared memory boundaries. globs: src/**/*.worker.ts, src/**/workers/**/*.{ts,js}, src/**/render/**/*.{ts,js}, src/**/pipeline/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/sharedarraybuffer-atomics-worker-render-pipeline-standard" --- # SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Spin-Locking Shared Buffers and Unsynchronized TypedArray Reads Causing Torn Frames and GC Stutters ## System Constraints You are a Principal Software Architect enforcing zero-allocation, lock-free concurrency standards across Web Workers, SharedArrayBuffers, Atomics, and OffscreenCanvas pipelines. Mandate strict memory barrier ordering, deterministic ring-buffer indices, and pre-allocated static views. Reject any busy-wait spin-loops, dynamic allocations inside hot frame ticks, or raw TypedArray mutations lacking atomic sync fences. ## Strict Guidelines - Engineers MUST ALWAYS order non-atomic buffer writes before an Atomics.store release fence, and read atomic acquire fences before reading the corresponding non-atomic payload. - Engineers MUST NOT invoke Atomics.wait on the browser main execution thread, as it throws a TypeError and violates user agent responsiveness guarantees. - Code SHOULD implement single-producer single-consumer (SPSC) lock-free ring buffers or double-buffered swap indices instead of blocking mutexes across frame render loops. - Services MUST pre-allocate all SharedArrayBuffers, TypedArray views, and scratch vectors during worker initialization; zero allocations are permitted in hot frame or physics tick loops. - Components NEVER read raw Float32Array or Int32Array frame states without atomic synchronizing sequence points, preventing dirty reads and torn transformation matrices. - Workers MUST utilize Atomics.wait with a finite timeout or Atomics.notify to transition idle threads out of execution without burning CPU cycles in spin-wait loops. ## Bad vs Good Implementations ### Unsynchronized Shared Memory Spin-Lock vs Lock-Free SPSC Ring Buffer with Atomic Barriers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation relies on an unsynchronized while-loop spin-lock that wastes battery and CPU cores. Reading from this.view without an acquire memory fence allows torn reads while the producer is actively writing. Instantiating matrixPayload inside the frame loop triggers garbage collection pauses, causing frame drops. ```typescript // Worker render loop with spin-locking, dirty reads, and dynamic allocation interface SharedState { buffer: SharedArrayBuffer; } export class UnsafeWorkerRenderer { private state: SharedState; private view: Float32Array; private flags: Int32Array; constructor(shared: SharedState) { this.state = shared; this.view = new Float32Array(this.state.buffer, 16); this.flags = new Int32Array(this.state.buffer, 0, 4); } public renderFrame(): void { // ANTI-PATTERN: CPU-burning spin-lock without memory fence while (this.flags[0] === 0) { // Spins indefinitely, pinning the CPU core } // ANTI-PATTERN: Heap allocation inside hot render loop const matrixPayload = new Float64Array(16); for (let i = 0; i < 16; i++) { // Torn reads possible: producer might be partially writing matrixPayload[i] = this.view[i]; } // ANTI-PATTERN: Non-atomic release allows compiler/CPU reordering this.flags[0] = 0; } } ``` #### Production Standard (Correct) > **Standard**: Uses a lock-free SPSC queue with explicit Atomics.load (acquire) and Atomics.store (release) fences. The control block and matrix buffers are pre-allocated at construction time to guarantee zero GC allocations per frame. Avoids spin-locking by safely returning when no new frame is pending, and guarantees torn reads cannot occur. ```typescript // Industrial lock-free consumer with atomic memory barriers and pre-allocated buffers const CONTROL_INDEX_HEAD = 0; const CONTROL_INDEX_TAIL = 1; const PAYLOAD_OFFSET_BYTES = 64; // Cache-line aligned payload boundary export class SafeWorkerRenderer { private readonly ctrl: Int32Array; private readonly payload: Float32Array; private readonly localScratchMatrix: Float32Array; constructor(buffer: SharedArrayBuffer) { // Control block: 4-byte aligned Int32Array for Atomics this.ctrl = new Int32Array(buffer, 0, 16); // Pre-allocated payload view this.payload = new Float32Array(buffer, PAYLOAD_OFFSET_BYTES); // Zero-allocation local cache initialized once this.localScratchMatrix = new Float32Array(16); } public renderFrame(): boolean { // Acquire barrier: Read producer head before reading payload const head = Atomics.load(this.ctrl, CONTROL_INDEX_HEAD); const tail = Atomics.load(this.ctrl, CONTROL_INDEX_TAIL); if (head === tail) { // No new frame available; return immediately without spinning return false; } // Safe payload copy: producer completed writes before store fence const bufferOffset = (tail & 1) * 16; for (let i = 0; i < 16; i++) { this.localScratchMatrix[i] = this.payload[bufferOffset + i]; } // Release barrier: Update tail index after consuming payload Atomics.store(this.ctrl, CONTROL_INDEX_TAIL, (tail + 1) | 0); Atomics.notify(this.ctrl, CONTROL_INDEX_TAIL, 1); return true; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard

SharedArrayBuffer, Atomics, and Zero-Allocation Worker Pipeline Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces lock-free ring buffers, explicit atomic memory fences, and zero-allocation frame loops across Web Workers feeding OffscreenCanvas rendering contexts. Guarantees memory barrier ordering and eliminates CPU-saturating spin-locks, torn reads, and garbage collection pauses across cross-thread shared memory boundaries. 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: Spin-Locking Shared Buffers and Unsynchronized TypedArray Reads Causing Torn Frames and GC Stutters 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	Spin-Locking Shared Buffers and Unsynchronized TypedArray Reads Causing Torn Frames and GC Stutters	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 order non-atomic buffer writes before an Atomics.store release fence, and read atomic acquire fences before reading the corresponding non-atomic payload.

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.