Bun 1.2 FFI Thread-Safe Async Callback & JSC Memory Pinning Guardrail

--- description: Bun 1.2 FFI Thread-Safe Async Callback & JSC Memory Pinning Guardrail - Enforces strict thread-safe callback configuration and deterministic JavaScriptCore (JSC) GC memory pinning when interfacing native C/Rust thread pools with Bun 1.2 FFI. Prevents fatal segmentation faults (SIGSEGV) caused by calling JSC off the main thread and use-after-free pointer corruption due to premature garbage collection. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-ffi-async-callback-gc-pinning-guardrail" --- # Bun 1.2 FFI Thread-Safe Async Callback & JSC Memory Pinning Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ephemeral, non-threadsafe JSCallback instances passed to asynchronous native workers without GC anchoring. ## System Constraints You are a Principal Systems Engineer enforcing Bun 1.2 FFI Thread-Safe Async Callback and GC Memory Pinning Invariants. You must ensure all asynchronous FFI interactions between native foreign threads and Bun's JavaScriptCore runtime are explicitly flagged as threadsafe, memory-pinned across event loop boundaries, and deterministically closed upon completion. ## Strict Guidelines - Engineers MUST ALWAYS pass `{ threadsafe: true }` to `JSCallback` when registering functions that will be invoked from off-main-thread native POSIX/Rust workers. - Engineers MUST ALWAYS pin `JSCallback` instances and associated native buffers in a persistent module-level `Set` or object graph to prevent JavaScriptCore GC reclamation during active native operations. - Engineers MUST explicitly unpin and call `.close()` on `JSCallback` instances once native asynchronous processing completes to prevent heap memory leaks. - Engineers MUST NOT pass inline anonymous `JSCallback` allocations directly to foreign FFI functions without capturing a strong reference. - Native callbacks MUST NOT cross JavaScriptCore runtime thread boundaries without going through Bun's internal thread-safe message dispatch mechanism. ## Bad vs Good Implementations ### Asynchronous Native Thread Callback Handling in Bun 1.2 FFI #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a `JSCallback` without `{ threadsafe: true }` will immediately cause a segmentation fault if invoked from a native OS background thread. Additionally, the callback reference is eligible for JSC garbage collection once `runAsyncJob` exits, resulting in use-after-free memory corruption when the native side attempts to execute the pointer. ```typescript import { dlopen, FFIType, JSCallback } from "bun:ffi"; const lib = dlopen("libnative_worker.so", { dispatch_work_async: { args: [FFIType.function, FFIType.ptr], returns: FFIType.void, }, }); export function runAsyncJob(payload: Uint8Array): Promise<string> { return new Promise((resolve) => { // ANTI-PATTERN: Not threadsafe, not pinned to GC roots. // JSC will collect this callback before native worker threads finish, // or calling this from a C pthread will immediately SIGSEGV the runtime. const cb = new JSCallback( (status: number) => { resolve(`Job completed with code: ${status}`); }, { args: [FFIType.i32], returns: FFIType.void, } ); lib.symbols.dispatch_work_async(cb.ptr, null); }); } ``` #### Production Standard (Correct) > **Standard**: Specifying `{ threadsafe: true }` instructs Bun to queue callback execution onto the JSC main event loop from native background threads. Storing the instance in `activeCallbacks` ensures the JSC garbage collector does not sweep the callback while the native worker is processing. In the completion handler, resources are deterministically unpinned and `.close()` is called. ```typescript import { dlopen, FFIType, JSCallback } from "bun:ffi"; const lib = dlopen("libnative_worker.so", { dispatch_work_async: { args: [FFIType.function, FFIType.ptr], returns: FFIType.void, }, }); // Module-scoped GC pinning anchor preventing JSC collection const activeCallbacks = new Set<JSCallback>(); export function runAsyncJob(payload: Uint8Array): Promise<string> { return new Promise((resolve, reject) => { let cb: JSCallback | null = null; const cleanup = () => { if (cb) { activeCallbacks.delete(cb); cb.close(); cb = null; } }; try { cb = new JSCallback( (status: number) => { try { if (status === 0) { resolve("Job completed successfully"); } else { reject(new Error(`Native worker failed with exit code: ${status}`)); } } finally { cleanup(); } }, { args: [FFIType.i32], returns: FFIType.void, threadsafe: true, // INVARIANT: Dispatches safely to Bun's JSC main thread } ); // Pin to JSC root before handing off raw pointer to native FFI activeCallbacks.add(cb); lib.symbols.dispatch_work_async(cb.ptr, null); } catch (err) { cleanup(); reject(err); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 FFI Thread-Safe Async Callback & JSC Memory Pinning Guardrail

Bun 1.2 FFI Thread-Safe Async Callback & JSC Memory Pinning Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict thread-safe callback configuration and deterministic JavaScriptCore (JSC) GC memory pinning when interfacing native C/Rust thread pools with Bun 1.2 FFI. Prevents fatal segmentation faults (SIGSEGV) caused by calling JSC off the main thread and use-after-free pointer corruption due to premature garbage collection. 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: Ephemeral, non-threadsafe JSCallback instances passed to asynchronous native workers without GC anchoring. 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	Ephemeral, non-threadsafe JSCallback instances passed to asynchronous native workers without GC anchoring.	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 pass `{ threadsafe

Engineers MUST ALWAYS pass `{ threadsafe: true }` to `JSCallback` when registering functions that will be invoked from off-main-thread native POSIX/Rust workers.

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.