Bun 1.2 Cluster Zero-Copy ArrayBuffer Transfer Standard

--- description: Bun 1.2 Cluster Zero-Copy ArrayBuffer Transfer Standard - Enforces strict binary IPC memory transfer invariants across Bun 1.2 cluster worker threads to eliminate structured clone serialization overhead. Mandates the transfer list pattern with transferable ArrayBuffers alongside binary framing protocols for multi-core gateway routing. Prohibits deep JSON object cloning across IPC channels and eliminates post-transfer detached buffer access faults. globs: src/**/*.{ts,tsx}, gateway/**/*.{ts,tsx}, workers/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-native-cluster-zero-copy-ipc-standard" --- # Bun 1.2 Cluster Zero-Copy ArrayBuffer Transfer Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Serializing JSON Objects Across Worker IPC Causing Serialization Latency Spikes and GC Pressure ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native Cluster Zero-Copy ArrayBuffer Transfer Standard. You mandate structured binary IPC message passing across Bun worker threads to eliminate serialization latency and memory bloat. You forbid JSON serialization over worker IPC for high-throughput gateway paths, enforce transferable ArrayBuffer semantics, and guard strictly against detached buffer read/write access. ## Strict Guidelines - Engineers MUST ALWAYS pass the underlying ArrayBuffer in the postMessage transfer list (`postMessage(msg, [msg.buffer])`) to trigger ownership transfer without memory copying. - Engineers MUST NOT pass complex JavaScript object graphs or invoke `JSON.stringify()` over worker IPC boundaries in high-throughput hot paths. - Code SHOULD encode message headers (e.g., routing ID, trace ID, payload length) using fixed-width binary fields via `DataView` or typed arrays in the first N bytes of the shared frame. - Services MUST verify ArrayBuffer detachment states (`buffer.byteLength === 0`) and discard sender-side buffer references immediately after transfer dispatch. - Components NEVER reuse, mutate, or read an `ArrayBuffer` or `TypedArray` after it has been passed into a transfer list. ## Bad vs Good Implementations ### Bun IPC Worker Dispatch: JSON Serialization vs Zero-Copy Transferable Buffer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing JS objects forces Bun's JavaScriptCore runtime to perform a deep structured clone across the thread boundary, allocating duplicate memory on every IPC call, spiking GC latency, and destroying throughput under load. ```typescript import { Worker } from 'bun'; interface GatewayPayload { requestId: string; headers: Record<string, string>; body: string; } export class GatewayRouter { private worker = new Worker('./worker.ts'); // ANTI-PATTERN: Passing JavaScript objects directly relies on structured cloning, // incurring heavy GC allocation and JSON serialization latency on hot paths. public dispatch(requestId: string, body: Uint8Array): void { const payload: GatewayPayload = { requestId, headers: { 'content-type': 'application/json' }, body: new TextDecoder().decode(body) }; this.worker.postMessage(payload); } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates headers and payload into a single binary frame and explicitly transfers `targetBuffer` via the transfer list. Memory ownership is moved directly between JSC heaps without copy overhead or serialization. ```typescript import { Worker } from 'bun'; // Frame Protocol: [16 bytes UUID] + [4 bytes Body Length] + [N bytes Raw Body] const HEADER_SIZE = 20; export class GatewayRouter { private worker = new Worker('./worker.ts'); public dispatch(uuidBuffer16: Uint8Array, bodyPayload: Uint8Array): void { const totalLength = HEADER_SIZE + bodyPayload.byteLength; const frame = new Uint8Array(totalLength); const view = new DataView(frame.buffer); // Write 16-byte Request Identifier frame.set(uuidBuffer16, 0); // Write 4-byte BigEndian Body Length view.setUint32(16, bodyPayload.byteLength, false); // Write Raw Body Bytes frame.set(bodyPayload, HEADER_SIZE); // Zero-copy transfer: ArrayBuffer ownership is moved to the target worker thread. // In Bun, the second argument specifies the Transferable list. const targetBuffer = frame.buffer; this.worker.postMessage(targetBuffer, [targetBuffer]); // Buffer is now detached on the sender side; byteLength becomes 0. } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Cluster Zero-Copy ArrayBuffer Transfer Standard

Bun 1.2 Cluster Zero-Copy ArrayBuffer Transfer Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict binary IPC memory transfer invariants across Bun 1.2 cluster worker threads to eliminate structured clone serialization overhead. Mandates the transfer list pattern with transferable ArrayBuffers alongside binary framing protocols for multi-core gateway routing. Prohibits deep JSON object cloning across IPC channels and eliminates post-transfer detached buffer access faults. 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: Serializing JSON Objects Across Worker IPC Causing Serialization Latency Spikes and GC Pressure 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	Serializing JSON Objects Across Worker IPC Causing Serialization Latency Spikes and GC Pressure	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 pass the underlying ArrayBuffer in the postMessage transfer list (`postMessage(msg, [msg.buffer])`) to trigger ownership transfer without memory copying.

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.