Bun 1.2 Native C-FFI Pointer Lifetime & Thread-Safe Worker Boundary

--- description: Bun 1.2 Native C-FFI Pointer Lifetime & Thread-Safe Worker Boundary - Enforces strict memory ownership, non-aliased pointer lifecycles, and isolated native resource pinning when executing foreign functions across Bun Worker threads. Prevents use-after-free conditions, double-frees, and v8/JSC GC-induced memory corruption during offloaded cryptographic or hardware-bound operations. globs: src/**/*.ts, workers/**/*.ts, lib/native/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-pointer-lifetime-worker-boundary" --- # Bun 1.2 Native C-FFI Pointer Lifetime & Thread-Safe Worker Boundary > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Transferring raw native pointers or retaining unpinned JS TypedArrays across asynchronous worker boundaries during native C-FFI execution ## System Constraints You are a Principal Systems Engineer enforcing strict native C-FFI memory safety and isolate separation under Bun 1.2. Mandate explicit ownership transfer, pointer pinning, deterministic deallocation, and shared-nothing worker boundaries to eliminate race conditions and segmentation faults. ## Strict Guidelines - Engineers MUST ALWAYS instantiate and execute `bun:ffi` bindings exclusively within the dedicated Worker isolate where the native memory is allocated and freed. - Engineers MUST NOT transfer raw numeric pointers (`bun:ffi` `ptr` or integer representations) across `postMessage` channels, as memory spaces and lifetimes become unverifiable across JavaScript isolates. - Code SHOULD transfer plain `ArrayBuffer` instances via transferable objects (`postMessage(msg, [transferable])`) to enforce single-owner byte boundaries without copying. - Services MUST pin JavaScript TypedArrays using explicit reference anchors or dedicated native buffers until synchronous or asynchronous FFI invocations yield execution back to the runtime. - Components NEVER call free/deallocation symbols on foreign memory from an isolate or worker thread different from the one that originated the allocation, unless the underlying native library explicitly documents thread-safe cross-thread deallocation. ## Bad vs Good Implementations ### Transferring Raw FFI Pointers Across Workers vs. Isolated Worker Execution with Transferable Buffers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing a pointer derived via `ptr(rawData)` across thread/isolate boundaries creates an unsynchronized race condition. The Garbage Collector in the parent thread may reallocate or reclaim `rawData` while the worker processes the memory address, triggering catastrophic use-after-free or memory corruption. ```typescript import { cc, ptr } from 'bun:ffi'; const lib = cc({ source: './crypto.c', symbols: { heavy_encrypt: { args: ['ptr', 'usize'], returns: 'ptr' } }, }); // ANTI-PATTERN: Allocating in main thread and sending raw pointer to worker const rawData = new Uint8Array([1, 2, 3, 4, 5]); const rawPtr = ptr(rawData); const worker = new Worker('./worker.ts'); // Leaks memory or causes use-after-free if rawData is GC'd before or during worker access worker.postMessage({ pointer: rawPtr, length: rawData.byteLength }); ``` #### Production Standard (Correct) > **Standard**: FFI symbols and raw pointer abstractions remain tightly scoped to the worker thread. Input and output buffers are transferred across the isolate boundary via `ArrayBuffer` transfer lists, guaranteeing atomic ownership transfer, zero concurrent aliasing, and immunity to JavaScript GC use-after-free hazards. ```typescript // worker.ts: Encapsulate native FFI bindings entirely within the worker isolate import { cc, ptr, toArrayBuffer } from 'bun:ffi'; declare var self: Worker; const lib = cc({ source: './crypto.c', symbols: { heavy_encrypt: { args: ['ptr', 'usize', 'ptr'], returns: 'void' }, }, }); self.onmessage = (event: MessageEvent<ArrayBuffer>) => { const inputBuffer = event.data; const inputView = new Uint8Array(inputBuffer); const outputView = new Uint8Array(inputBuffer.byteLength); // Maintain explicit synchronous lifetime of typed arrays during the FFI call try { lib.symbols.heavy_encrypt( ptr(inputView), inputView.byteLength, ptr(outputView) ); // Transfer ownership of the result buffer back to the host self.postMessage(outputView.buffer, [outputView.buffer]); } finally { // Buffers transferred or handled deterministically; zero-out references } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native C-FFI Pointer Lifetime & Thread-Safe Worker Boundary

Bun 1.2 Native C-FFI Pointer Lifetime & Thread-Safe Worker Boundary defines an industrial-grade behavioral standard for backend engineering. Enforces strict memory ownership, non-aliased pointer lifecycles, and isolated native resource pinning when executing foreign functions across Bun Worker threads. Prevents use-after-free conditions, double-frees, and v8/JSC GC-induced memory corruption during offloaded cryptographic or hardware-bound operations. 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: Transferring raw native pointers or retaining unpinned JS TypedArrays across asynchronous worker boundaries during native C-FFI execution 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	Transferring raw native pointers or retaining unpinned JS TypedArrays across asynchronous worker boundaries during native C-FFI execution	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 instantiate and execute `bun

Engineers MUST ALWAYS instantiate and execute `bun:ffi` bindings exclusively within the dedicated Worker isolate where the native memory is allocated and freed.

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.