Bun 1.2 Off-Heap FFI Memory Lifecycle and Pointer Pinning Guardrail

--- description: Bun 1.2 Off-Heap FFI Memory Lifecycle and Pointer Pinning Guardrail - Enforces deterministic lifecycle management, explicit pointer pinning, and strict ownership boundaries for off-heap memory across the JavaScriptCore-to-Rust native bridge via bun:ffi. Eliminates use-after-free, memory corruption, and double-free hazards caused by JavaScriptCore garbage collection sweeping memory backing buffers while active native threads hold raw pointers. globs: src/**/*.{ts,tsx}, native/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-off-heap-lifecycle-invariants" --- # Bun 1.2 Off-Heap FFI Memory Lifecycle and Pointer Pinning Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Passing Ephemeral JSC Buffers or Naked Pointers to Asynchronous Native FFI Without Explicit Lifetime Pinning ## System Constraints You are a Principal Software Architect enforcing zero-trust off-heap memory invariants in Bun 1.2 `bun:ffi` native integrations. JavaScriptCore's garbage collector is unaware of native Rust allocations and asynchronous thread executions; therefore, implicit garbage collection MUST NEVER be trusted with off-heap lifetimes. Every foreign pointer crossing the FFI boundary must adhere to strict RAII disposal, explicit rooting/pinning, and bidirectional allocation symmetry. ## Strict Guidelines - Engineers MUST ALWAYS enforce allocation symmetry: memory allocated in Rust (`Box::into_raw`) must be freed by a corresponding Rust FFI export (`Box::from_raw`), NEVER by JavaScript runtime engines. - Engineers MUST ALWAYS pin underlying JavaScript buffers using explicit RAII wrappers implementing TypeScript 5.2+ `Symbol.dispose` or `Symbol.asyncDispose` to ensure pointers outlive native asynchronous workloads. - Engineers MUST NOT rely on JavaScriptCore `FinalizationRegistry` for deterministic memory freeing, as GC execution is non-deterministic and leads to off-heap memory exhaustion under high throughput. - Code MUST explicitly validate pointer nullity and boundary bounds (`ptr === 0n || ptr === null`) before dispatching any call to foreign symbols. - Services MUST ensure that views created via `toArrayBuffer(ptr, byteOffset, byteLength)` are treated as ephemeral borrow views and invalidated immediately upon the native resource disposal. - Components NEVER pass direct pointers from transient typed arrays (e.g., `ptr(new Uint8Array(...))`) to native functions that execute asynchronously or retain the pointer beyond the call stack. ## Bad vs Good Implementations ### Naive Ephemeral Buffer FFI Dispatch (Use-After-Free Hazard) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `tempBuffer` is allocated inside the JSC nursery heap. If an asynchronous native Rust thread retains `rawPtr`, Bun's garbage collector can collect or relocate `tempBuffer` as soon as `processData` returns, causing memory corruption or segmentation faults when Rust dereferences the pointer. ```typescript import { dlopen, FFIType, ptr } from "bun:ffi"; const lib = dlopen("libnative.so", { process_async: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void, }, free_buffer: { args: [FFIType.ptr], returns: FFIType.void, }, }); export function processData(data: Uint8Array): void { // VULNERABILITY: JSC GC can collect or compact `tempBuffer` during async native execution const tempBuffer = new Uint8Array(data); const rawPtr = ptr(tempBuffer); lib.symbols.process_async(rawPtr, BigInt(tempBuffer.byteLength)); // Non-deterministic cleanup or premature drop causes immediate UAF in Rust worker thread } ``` #### Production Standard (Correct) > **Standard**: Memory is allocated off-heap directly by Rust, ensuring JavaScriptCore cannot relocate or collect it. Ownership is governed deterministically through TypeScript 5.2 `using` declaration and `Symbol.dispose`, ensuring identical allocation/deallocation symmetry without relying on GC. ```typescript import { dlopen, FFIType, ptr, toArrayBuffer } from "bun:ffi"; interface NativeLibrary { allocate_native_buffer: (size: bigint) => bigint; process_async_blocking: (ptr: bigint, size: bigint) => void; free_native_buffer: (ptr: bigint, size: bigint) => void; } const lib = dlopen("libnative.so", { allocate_native_buffer: { args: [FFIType.u64], returns: [FFIType.ptr] }, process_async_blocking: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void }, free_native_buffer: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.void }, }).symbols as unknown as NativeLibrary; export class PinnedNativeBuffer implements Disposable { readonly rawPtr: bigint; readonly byteLength: bigint; private disposed = false; constructor(size: number) { this.byteLength = BigInt(size); this.rawPtr = lib.allocate_native_buffer(this.byteLength); if (this.rawPtr === 0n) { throw new Error("Native allocation failed: Out of memory"); } } get buffer(): ArrayBuffer { if (this.disposed) throw new Error("Access violation: PinnedNativeBuffer already disposed"); return toArrayBuffer(Number(this.rawPtr), 0, Number(this.byteLength)); } [Symbol.dispose](): void { if (!this.disposed) { this.disposed = true; lib.free_native_buffer(this.rawPtr, this.byteLength); } } } export function executeSafeProcessing(data: Uint8Array): void { using pinned = new PinnedNativeBuffer(data.byteLength); new Uint8Array(pinned.buffer).set(data); // Rust owns and processes safely; buffer is pinned and out of reach of JSC GC lib.process_async_blocking(pinned.rawPtr, pinned.byteLength); // Deterministically freed by Rust deallocator at block exit via Symbol.dispose } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Off-Heap FFI Memory Lifecycle and Pointer Pinning Guardrail

Bun 1.2 Off-Heap FFI Memory Lifecycle and Pointer Pinning Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic lifecycle management, explicit pointer pinning, and strict ownership boundaries for off-heap memory across the JavaScriptCore-to-Rust native bridge via bun:ffi. Eliminates use-after-free, memory corruption, and double-free hazards caused by JavaScriptCore garbage collection sweeping memory backing buffers while active native threads hold raw pointers. 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 Ephemeral JSC Buffers or Naked Pointers to Asynchronous Native FFI Without Explicit Lifetime Pinning 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 Ephemeral JSC Buffers or Naked Pointers to Asynchronous Native FFI Without Explicit Lifetime Pinning	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 enforce allocation symmetry

Engineers MUST ALWAYS enforce allocation symmetry: memory allocated in Rust (`Box::into_raw`) must be freed by a corresponding Rust FFI export (`Box::from_raw`), NEVER by JavaScript runtime engines.

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.