Bun 1.2 Zero-Copy FFI & Native Worker Thread Memory Safety Invariant

--- description: Bun 1.2 Zero-Copy FFI & Native Worker Thread Memory Safety Invariant - Enforces strict memory ownership, pointer lifecycle validation, and deterministic buffer pooling when passing high-throughput analytical buffers across Bun 1.2 C-ABI FFI and native Worker thread boundaries. Prevents silent heap corruption, use-after-free, and race conditions resulting from JavaScript garbage collection preempting native memory references. globs: src/**/*.{ts,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-zero-copy-ffi-worker-isolation-guardrail" --- # Bun 1.2 Zero-Copy FFI & Native Worker Thread Memory Safety Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unpinned Pointer Passing & Shared Mutable ArrayBuffer Transfer Across FFI Worker Boundaries ## System Constraints You are a Principal Systems Architect enforcing strict Bun 1.2 C-ABI Foreign Function Interface (FFI) memory safety and native Worker thread isolation. Zero-copy operations must strictly delineate between V8/JSC-managed heap buffers and non-moving raw native memory. Never allow a GC-managed Uint8Array/ArrayBuffer pointer to outlive its synchronous call frame, and never share mutable raw pointers across Worker threads without SharedArrayBuffer and explicit synchronization primitives. ## Strict Guidelines - Engineers MUST ALWAYS retain an explicit reference to the underlying Buffer/TypedArray in JavaScript scope for the entire duration of an asynchronous or non-blocking FFI operation to prevent JavaScriptCore GC reclamation. - Engineers MUST NOT pass raw pointers obtained via `ptr()` across Worker boundaries via `postMessage()`; workers MUST receive either detached ArrayBuffers via transfer lists or isolated SharedArrayBuffer instances with Atomics synchronization. - Code MUST use Bun's native `toArrayBuffer(ptr, byteOffset, byteLength)` with deterministic byte boundaries and explicitly clone or detach the buffer when cross-thread isolation is required. - Services MUST implement explicit lifecycles (e.g., using `using` syntax via `Symbol.dispose` / `Symbol.asyncDispose`) for native memory allocations executed through FFI symbols like `malloc` and `free`. - Components NEVER cast volatile FFI return pointers directly to JavaScript typed arrays without validating non-null pointer status and alignment restrictions. ## Bad vs Good Implementations ### Unsafe FFI Pointer Forwarding vs. Deterministic Pinned Buffer Lifecycle with Worker Transfer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing raw memory addresses directly to worker threads bypasses thread isolation invariants. Furthermore, Bun's GC can collect or relocate the underlying TypedArray backing buffer while the C routine or downstream Worker is reading it, causing use-after-free or memory corruption. ```typescript import { cc, ptr } from "bun:ffi"; const lib = cc({ source: "./analytics.c", symbols: { process_stream: { args: ["ptr", "usize"], returns: "void", }, }, }); export function dispatchToWorker(data: Uint8Array, worker: Worker) { // Anti-Pattern: Passing raw FFI pointer across Worker boundary. // The underlying memory is managed by JSC and can be collected or compacted, // causing a dangling pointer and SIGSEGV or cross-thread heap corruption. const rawPtr = ptr(data); lib.symbols.process_stream(rawPtr, data.byteLength); worker.postMessage({ memoryAddress: rawPtr, length: data.byteLength }); } ``` #### Production Standard (Correct) > **Standard**: The good example encapsulates memory within an explicit lifecycle manager using TypeScript 5.2+ Explicit Resource Management. The synchronous FFI call operates on a pinned Uint8Array, and memory is transferred to the Worker via zero-copy ArrayBuffer transfer list, completely detaching it from the caller thread and guaranteeing memory safety without raw pointer sharing. ```typescript import { cc, ptr } from "bun:ffi"; const { symbols: { process_stream } } = cc({ source: "./analytics.c", symbols: { process_stream: { args: ["ptr", "usize"], returns: "void", }, }, }); export class SafeFFIBuffer implements Disposable { private buffer: ArrayBuffer | null; readonly byteLength: number; constructor(size: number) { this.buffer = new ArrayBuffer(size); this.byteLength = size; } executeAndTransfer(worker: Worker): void { if (!this.buffer) throw new Error("Buffer already disposed or transferred"); // Pinned reference guarantees GC cannot reclaim the memory during FFI execution const view = new Uint8Array(this.buffer); process_stream(ptr(view), this.byteLength); // Safely transfer ownership to the native Worker without copying memory const transferred = this.buffer; this.buffer = null; worker.postMessage({ payload: transferred }, [transferred]); } [Symbol.dispose](): void { this.buffer = null; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Zero-Copy FFI & Native Worker Thread Memory Safety Invariant

Bun 1.2 Zero-Copy FFI & Native Worker Thread Memory Safety Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict memory ownership, pointer lifecycle validation, and deterministic buffer pooling when passing high-throughput analytical buffers across Bun 1.2 C-ABI FFI and native Worker thread boundaries. Prevents silent heap corruption, use-after-free, and race conditions resulting from JavaScript garbage collection preempting native memory references. 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: Unpinned Pointer Passing & Shared Mutable ArrayBuffer Transfer Across FFI Worker Boundaries 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	Unpinned Pointer Passing & Shared Mutable ArrayBuffer Transfer Across FFI Worker Boundaries	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 retain an explicit reference to the underlying Buffer/TypedArray in JavaScript scope for the entire duration of an asynchronous or non-blocking FFI operation to prevent JavaScriptCore GC reclamation.

Engineers MUST ALWAYS retain an explicit reference to the underlying Buffer/TypedArray in JavaScript scope for the entire duration of an asynchronous or non-blocking FFI operation to prevent JavaScriptCore GC reclamation.

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.