Bun 1.2 Clustered Worker Zero-Copy SharedBuffer Invariants

--- description: Bun 1.2 Clustered Worker Zero-Copy SharedBuffer Invariants - Mandates zero-copy shared memory architectures using SharedArrayBuffer and Atomics for Bun 1.2 worker thread pools processing high-bandwidth I/O. Eliminates Structured Clone serialization overhead, V8/JSC heap churn, and cross-thread garbage collection pressure during concurrent stream processing. globs: src/**/*.ts, workers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-sharedarraybuffer-zero-copy-concurrency" --- # Bun 1.2 Clustered Worker Zero-Copy SharedBuffer Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Structured-Clone Serialization Bottlenecks and Unsynchronized Buffer Mutation Across Worker Pools ## System Constraints You are a Principal Software Architect enforcing high-throughput zero-copy concurrency standards in Bun 1.2. Mandate the use of SharedArrayBuffer and Atomics primitives across worker thread pools for binary stream processing. Strictly eliminate structured clone serialization (postMessage without transferables or shared memory) for multi-megabyte payloads, prevent race conditions through atomic memory barriers, and ensure Atomics.wait is isolated to worker threads to avoid stalling the main event loop. ## Strict Guidelines - Engineers MUST ALWAYS initialize inter-thread communication regions using SharedArrayBuffer with pre-allocated memory layouts for binary streams. - Engineers MUST ALWAYS synchronize buffer head/tail cursors using Atomics operations (Atomics.load, Atomics.store, Atomics.compareExchange, Atomics.wait, Atomics.notify). - Engineers MUST NOT execute Atomics.wait() on the primary Bun event-loop thread, restricting synchronous blocking exclusively to dedicated worker threads. - Engineers MUST NOT transfer large binary buffers (>64KB) via standard postMessage(data) serialization, which triggers structured clone allocation cycles and garbage collection spikes. - Services MUST structure the shared buffer with 8-byte aligned control headers (index, capacity, state flags) preceding the zero-copy binary payload ring buffer. - Components NEVER mutate shared byte views concurrently without verifying ownership via atomic compare-and-swap or dedicated lock-free ring-buffer state checks. ## Bad vs Good Implementations ### Zero-Copy Ring Buffer Concurrency vs Structured Clone Serialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing high-throughput binary buffers via standard postMessage payloads forces the runtime to serialize and duplicate memory via the Structured Clone Algorithm. In high-bandwidth pipelines, this exhausts isolate heap limits and triggers massive GC pauses. ```typescript // BAD: Structured clone overhead causes GC spikes and memory duplication across worker boundaries import { Worker } from 'bun'; const worker = new Worker(new URL('./ingest-worker.ts', import.meta.url).href); export async function dispatchStream(chunk: Uint8Array): Promise<void> { // Cloning the buffer invokes structured clone algorithm; copies bytes per message worker.postMessage({ type: 'INGEST_CHUNK', payload: chunk // Serializes entire byte array across JSC thread boundary }); } // ingest-worker.ts (Worker Thread) self.onmessage = (event: MessageEvent) => { const { payload } = event.data; // Payload is a detached/reallocated copy in worker isolate processRawBytes(payload); }; function processRawBytes(data: Uint8Array): void { // Heavy compute on duplicated heap allocation } ``` #### Production Standard (Correct) > **Standard**: Eliminates GC overhead completely by persisting a single SharedArrayBuffer across threads. Buffer heads are modified atomically using Atomics.store and Atomics.notify, while the worker worker thread efficiently synchronizes with Atomics.wait without consuming CPU cycles or allocating new heap memory. ```typescript // GOOD: Pre-allocated SharedArrayBuffer with Atomics-synchronized circular buffer ring import { Worker } from 'bun'; const RING_BUFFER_SIZE = 16 * 1024 * 1024; // 16MB contiguous chunk ring const HEADER_SIZE = 4 * Int32Array.BYTES_PER_ELEMENT; // [WriteCursor, ReadCursor, LockState, ShutdownFlag] const TOTAL_SIZE = HEADER_SIZE + RING_BUFFER_SIZE; const sharedBuffer = new SharedArrayBuffer(TOTAL_SIZE); const controlView = new Int32Array(sharedBuffer, 0, 4); const payloadView = new Uint8Array(sharedBuffer, HEADER_SIZE, RING_BUFFER_SIZE); const worker = new Worker(new URL('./ingest-worker.ts', import.meta.url).href); // Worker receives shared memory reference once; no per-message allocation worker.postMessage({ type: 'INIT_RING_BUFFER', sharedBuffer }); export function dispatchZeroCopy(chunk: Uint8Array): boolean { const currentWrite = Atomics.load(controlView, 0); const currentRead = Atomics.load(controlView, 1); const availableSpace = (currentRead - currentWrite + RING_BUFFER_SIZE - 1) % RING_BUFFER_SIZE; if (chunk.byteLength > availableSpace) { return false; // Ring buffer full: handle backpressure without allocations } for (let i = 0; i < chunk.byteLength; i++) { payloadView[(currentWrite + i) % RING_BUFFER_SIZE] = chunk[i]; } const nextWrite = (currentWrite + chunk.byteLength) % RING_BUFFER_SIZE; Atomics.store(controlView, 0, nextWrite); Atomics.notify(controlView, 0, 1); // Wake single consumer worker thread return true; } // workers/ingest-worker.ts (Worker Thread) self.onmessage = (event: MessageEvent) => { if (event.data.type !== 'INIT_RING_BUFFER') return; const shared = event.data.sharedBuffer as SharedArrayBuffer; const ctrl = new Int32Array(shared, 0, 4); const data = new Uint8Array(shared, HEADER_SIZE, RING_BUFFER_SIZE); while (Atomics.load(ctrl, 3) === 0) { let write = Atomics.load(ctrl, 0); let read = Atomics.load(ctrl, 1); if (read === write) { // Worker safely blocks until new data is written without spinning CPU Atomics.wait(ctrl, 0, write, 100); continue; } const bytesToProcess = (write - read + RING_BUFFER_SIZE) % RING_BUFFER_SIZE; // Direct memory reference without cloning or reallocation const readSlice = data.subarray(read, read + bytesToProcess); processRawBytesZeroCopy(readSlice); Atomics.store(ctrl, 1, (read + bytesToProcess) % RING_BUFFER_SIZE); } }; function processRawBytesZeroCopy(view: Uint8Array): void { // In-place processing via direct memory pointer } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Clustered Worker Zero-Copy SharedBuffer Invariants

Bun 1.2 Clustered Worker Zero-Copy SharedBuffer Invariants defines an industrial-grade behavioral standard for backend engineering. Mandates zero-copy shared memory architectures using SharedArrayBuffer and Atomics for Bun 1.2 worker thread pools processing high-bandwidth I/O. Eliminates Structured Clone serialization overhead, V8/JSC heap churn, and cross-thread garbage collection pressure during concurrent stream processing. 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: Structured-Clone Serialization Bottlenecks and Unsynchronized Buffer Mutation Across Worker Pools 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	Structured-Clone Serialization Bottlenecks and Unsynchronized Buffer Mutation Across Worker Pools	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 initialize inter-thread communication regions using SharedArrayBuffer with pre-allocated memory layouts for binary streams.

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.