Bun 1.2 Native FFI Puddle Pointer Lifetime and GC Safety Standard

Enforces strict memory safety and pinned handle lifetimes across Bun 1.2 native Foreign Function Interface (FFI) boundaries. JavaScriptCore (JSC) garbage collection sweeps and compacting phases can evict or relocate backing buffers while asynchronous or long-lived native C ABI code retains raw pointer references. This guardrail mandates deterministic handle pinning, pointer derivation lifecycle bounds, and explicit finalizer cleanup to eliminate use-after-free and silent memory corruption.

--- description: Bun 1.2 Native FFI Puddle Pointer Lifetime and GC Safety Standard - Enforces strict memory safety and pinned handle lifetimes across Bun 1.2 native Foreign Function Interface (FFI) boundaries. JavaScriptCore (JSC) garbage collection sweeps and compacting phases can evict or relocate backing buffers while asynchronous or long-lived native C ABI code retains raw pointer references. This guardrail mandates deterministic handle pinning, pointer derivation lifecycle bounds, and explicit finalizer cleanup to eliminate use-after-free and silent memory corruption. globs: src/**/*.{ts,js}, lib/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-pointer-lifetime-gc-safety-standard" --- # Bun 1.2 Native FFI Puddle Pointer Lifetime and GC Safety Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Passing unpinned TypedArray pointers across asynchronous or deferred C ABI boundaries subject to JSC GC sweeps ## System Constraints You are a Principal Engineer enforcing the Bun 1.2 Native FFI Puddle Pointer Lifetime & GC Safety Standard. Mandate that all raw pointers derived via Bun.toArrayBuffer(), ptr(), or C ABI interfaces remain explicitly anchored to an active JavaScript heap reference for the exact duration of native execution. Forbid passing raw pointer references derived from transient or locally scoped Uint8Arrays directly to non-blocking or asynchronous C ABI bindings without maintaining a rooted anchor or using explicit manual allocation via Bun FFI memory primitives. ## Strict Guidelines - Engineers MUST ALWAYS retain an explicit, reachable reference to the parent TypedArray or ArrayBuffer on the JavaScript heap for the entire duration that native code dereferences its raw pointer. - Engineers MUST NOT construct transient TypedArrays inline as direct arguments to Bun.ptr() or C-ABI calls when native operations outlive the synchronous call stack frame. - Code MUST wrap long-lived or asynchronous FFI pointer transfers in a deterministic LifetimePinnedHandle class that registers native deallocation handlers via FinalizationRegistry or explicit .dispose() symbols. - Services MUST verify whether native functions take ownership of buffer allocations; if C ABI retains the pointer, memory MUST be allocated using raw native allocators rather than JSC-managed TypedArray buffers. - Components NEVER assume JavaScriptCore garbage collector pauses preserve the virtual memory address of transient ArrayBuffers without explicit handle anchoring. ## Bad vs Good Implementations ### Preventing Use-After-Free in Asynchronous FFI Dispatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The local Uint8Array 'rawBuffer' is not anchored after 'dispatchJob' exits. JavaScriptCore's GC can collect or compact the backing store while the native C background worker thread is concurrently reading the pointer, resulting in a use-after-free or fatal segfault. ```typescript import { dlopen, FFIType, ptr } from 'bun:ffi'; const lib = dlopen('libasync_crypto.so', { enqueue_payload: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void, }, }); export function dispatchJob(data: string): void { // Anti-pattern: payload buffer is locally scoped and immediately eligible // for JSC GC collection while enqueue_payload delegates to a background C worker thread const rawBuffer = new TextEncoder().encode(data); lib.symbols.enqueue_payload(ptr(rawBuffer), rawBuffer.byteLength); } ``` #### Production Standard (Correct) > **Standard**: The backing Uint8Array is explicitly anchored in the 'pinnedHandles' Set, guaranteeing JSC cannot garbage collect the memory buffer while native threads access the pointer. Memory is deterministically freed once the C completion callback executes. ```typescript import { dlopen, FFIType, ptr } from 'bun:ffi'; const lib = dlopen('libasync_crypto.so', { enqueue_payload_async: { args: [FFIType.ptr, FFIType.u64, FFIType.callback], returns: FFIType.void, }, }); // Keep references alive in an explicit root anchor to avoid JSC collection const pinnedHandles = new Set<Uint8Array>(); export async function dispatchJob(data: string): Promise<void> { const rawBuffer = new TextEncoder().encode(data); pinnedHandles.add(rawBuffer); return new Promise<void>((resolve, reject) => { // Anchored callback handles cleanup when native invocation finishes const cb = new (Bun as any).Callback( (status: number) => { pinnedHandles.delete(rawBuffer); cb.close(); if (status === 0) resolve(); else reject(new Error(`Native FFI execution failed: ${status}`)); }, { args: [FFIType.i32], returns: FFIType.void } ); lib.symbols.enqueue_payload_async( ptr(rawBuffer), rawBuffer.byteLength, cb.pointer ); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native FFI Puddle Pointer Lifetime and GC Safety Standard

Bun 1.2 Native FFI Puddle Pointer Lifetime and GC Safety Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict memory safety and pinned handle lifetimes across Bun 1.2 native Foreign Function Interface (FFI) boundaries. JavaScriptCore (JSC) garbage collection sweeps and compacting phases can evict or relocate backing buffers while asynchronous or long-lived native C ABI code retains raw pointer references. This guardrail mandates deterministic handle pinning, pointer derivation lifecycle bounds, and explicit finalizer cleanup to eliminate use-after-free and silent memory corruption. 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: Passing unpinned TypedArray pointers across asynchronous or deferred C ABI boundaries subject to JSC GC sweeps 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	Passing unpinned TypedArray pointers across asynchronous or deferred C ABI boundaries subject to JSC GC sweeps	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, reachable reference to the parent TypedArray or ArrayBuffer on the JavaScript heap for the entire duration that native code dereferences its raw pointer.

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.