Bun 1.2 Clustered FFI Native Buffer Ownership Handshake

--- description: Bun 1.2 Clustered FFI Native Buffer Ownership Handshake - Enforces deterministic memory ownership transfer and ArrayBuffer detachment when dispatching native memory across Bun worker clusters executing bun:ffi foreign function bindings. Prohibits implicit cross-thread pointer reuse and non-transferred buffer clones that cause double-free errors, use-after-free faults, and JVM/C-heap desynchronization. globs: src/**/*.{ts,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-clustered-buffer-ownership-handshake" --- # Bun 1.2 Clustered FFI Native Buffer Ownership Handshake > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Shared-Memory Race and Double-Free via Untransferred Native Buffers Across Bun Workers ## System Constraints You are a Principal Systems Engineer enforcing strict native buffer lifecycle and memory ownership transfer invariants in Bun 1.2 clustered runtimes using bun:ffi. You must mandate explicit transferable ArrayBuffer handshakes, defensive ptr wrapping, and worker detachment protocols to prevent native heap corruption, unaligned reads, and use-after-free exploits. ## Strict Guidelines - Engineers MUST ALWAYS transfer underlying native ArrayBuffers via the postMessage transfer list parameter when delegating FFI buffers to Bun worker threads. - Engineers MUST NOT maintain local pointer references (via ptr() or native pointers) to an ArrayBuffer after dispatching it in a transfer payload. - Code MUST verify buffer detachment on the sender side post-transfer using buffer.byteLength === 0 or buffer.detached before executing further C-ABI calls. - Services MUST implement explicit bidirectional ACK handshakes before deallocating C-allocated pointers managed across worker threads. - Components NEVER pass raw memory addresses (number/bigint pointer values) across Worker boundaries without associated ownership transfer metadata and safety lifecycles. ## Bad vs Good Implementations ### Cross-Worker FFI Buffer Delegation Handshake #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the raw pointer address and cloning the typed array allows both the main thread and worker thread to concurrently reference or mutate the memory. If one side frees the underlying allocation or mutates it during FFI processing, use-after-free, unaligned reads, or heap corruption occurs. ```typescript import { ptr } from "bun:ffi"; const worker = new Worker(new URL("./ffi-worker.ts", import.meta.url)); const nativeBuffer = new Uint8Array(1024 * 1024); const rawAddress = ptr(nativeBuffer); // Anti-pattern: Sending raw pointer address and buffer copy across worker threads // Causes race conditions, concurrent native mutation, and memory leaks. worker.postMessage({ pointer: rawAddress, buffer: nativeBuffer }); // Sender retains access and operates on stale memory concurrent with worker console.log(nativeBuffer[0]); ``` #### Production Standard (Correct) > **Standard**: By explicitly specifying nativeBuffer.buffer in the transfer list of postMessage, JavaScript detaches the buffer on the sending thread, setting byteLength to 0 and preventing use-after-free. Memory ownership is cleanly delegated to the worker thread and returned via an explicit protocol handshake. ```typescript import { ptr } from "bun:ffi"; const worker = new Worker(new URL("./ffi-worker.ts", import.meta.url)); const nativeBuffer = new Uint8Array(1024 * 1024); // Enforce explicit ownership transfer of the backing ArrayBuffer const transferable = nativeBuffer.buffer; worker.postMessage( { type: "ACQUIRE_FFI_BUFFER", byteLength: nativeBuffer.byteLength }, [transferable] ); // Invariant: Native buffer MUST be detached on sender thread if (transferable.byteLength !== 0) { throw new Error("FATAL: Buffer transfer failed; sender still holds ownership"); } // Wait for worker release acknowledgment before allowing any re-allocations worker.onmessage = (event: MessageEvent) => { if (event.data.type === "RELEASE_FFI_BUFFER") { // Ownership acknowledged and safely returned const returnedBuffer = new Uint8Array(event.data.buffer); const nativePtr = ptr(returnedBuffer); // Safe to perform native operations } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Clustered FFI Native Buffer Ownership Handshake

Bun 1.2 Clustered FFI Native Buffer Ownership Handshake defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic memory ownership transfer and ArrayBuffer detachment when dispatching native memory across Bun worker clusters executing bun:ffi foreign function bindings. Prohibits implicit cross-thread pointer reuse and non-transferred buffer clones that cause double-free errors, use-after-free faults, and JVM/C-heap desynchronization. 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: Shared-Memory Race and Double-Free via Untransferred Native Buffers Across Bun Workers 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	Shared-Memory Race and Double-Free via Untransferred Native Buffers Across Bun Workers	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 transfer underlying native ArrayBuffers via the postMessage transfer list parameter when delegating FFI buffers to Bun worker threads.

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.