Bun 1.2 Worker Memory Fence & FinalizationRegistry Isolation Guardrail

--- description: Bun 1.2 Worker Memory Fence & FinalizationRegistry Isolation Guardrail - Enforces strict isolate boundaries and thread-safe lifecycle management for native C-bindings and Node-API handles across Bun 1.2 multi-threaded Workers. Prevents premature resource collection, cross-worker heap pollution, and use-after-free segfaults caused by uncoordinated FinalizationRegistry callbacks on transferred raw pointers. globs: src/**/*.{ts,tsx}, workers/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-native-memory-fence-finalization-isolation" --- # Bun 1.2 Worker Memory Fence & FinalizationRegistry Isolation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Cross-Worker Raw Pointer Leakage Subject to Asynchronous Foreign-Isolate Finalization ## System Constraints You are a Principal Systems Architect enforcing strict memory fences and lifecycle isolation for Bun 1.2 multi-threaded workers executing native C/Node-API interop. Mandate thread-safe reference counting, isolate-pinned FinalizationRegistry instances, and explicit ownership transfer protocols to completely eradicate cross-thread heap corruption, double-frees, and use-after-free segfaults. ## Strict Guidelines - Engineers MUST ALWAYS isolate native C-binding deallocation (e.g., free/destructor calls within FinalizationRegistry) strictly to the isolate thread that originally allocated the pointer. - Engineers MUST NOT transfer raw numeric pointers (bun:ffi Pointer addresses or unboxed uintptr_t) across Worker postMessage boundaries without an explicit atomic reference increment in native space. - Code SHOULD employ transferable ArrayBuffers with detached-source semantics or native handle-cloning APIs rather than sharing unbounded raw memory addresses across worker threads. - Services MUST implement explicit Acquire-Release synchronization fences using Atomics when coordinating shared worker ring buffers or native memory segments backed by SharedArrayBuffer. - Components NEVER execute FinalizationRegistry.unregister or invoke native teardown routines inside a worker against handles governed by a foreign worker's JavaScriptCore GC cycle. ## Bad vs Good Implementations ### Unsafe Raw Pointer Dispatch with Cross-Thread Finalization Race vs. Thread-Safe Ownership Fence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The native handle wrapper is registered in the main isolate's FinalizationRegistry. Once dispatchJobUnsafe exits, the wrapper becomes unreachable on the main thread and its finalizer can invoke free_handle while the background worker is concurrently executing native code against that memory address, triggering SIGSEGV or memory corruption. ```typescript import { dlopen, FFIType, ptr } from "bun:ffi"; const lib = dlopen("libnative.so", { alloc_handle: { args: [FFIType.u32], returns: FFIType.ptr }, free_handle: { args: [FFIType.ptr], returns: FFIType.void }, }); // ANTI-PATTERN: Native handle registered in main thread GC, but raw pointer passed to worker. // Main thread can trigger garbage collection and call free_handle while worker is actively dereferencing the pointer. export function dispatchJobUnsafe(size: number, worker: Worker): void { const rawHandle = lib.symbols.alloc_handle(size); const wrapper = { handle: rawHandle }; const registry = new FinalizationRegistry((ptrVal: number) => { lib.symbols.free_handle(ptrVal); // Catastrophic use-after-free when worker executes concurrently }); registry.register(wrapper, rawHandle); // Passing raw integer pointer across worker isolate boundary worker.postMessage({ handleAddress: rawHandle, length: size }); // wrapper goes out of scope here; GC can finalize immediately } ``` #### Production Standard (Correct) > **Standard**: Atomic reference counting is synchronized in native memory (ref_handle) before posting the message across the isolate boundary. The originating isolate unregisters its local GC finalizer before the transfer completes, eliminating the possibility of a concurrent free while the worker acquires ownership and registers its own isolate-local lease. ```typescript import { dlopen, FFIType } from "bun:ffi"; const lib = dlopen("libnative.so", { alloc_handle: { args: [FFIType.u32], returns: FFIType.ptr }, ref_handle: { args: [FFIType.ptr], returns: FFIType.void }, unref_handle: { args: [FFIType.ptr], returns: FFIType.void }, }); // PRODUCTION INVARIANT: Atomic reference counting in native space with isolate-bound scoped finalizers. export class NativeBufferLease { private static registry = new FinalizationRegistry((ptrVal: number) => { lib.symbols.unref_handle(ptrVal); }); public readonly address: number; private active = true; constructor(address: number) { this.address = address; NativeBufferLease.registry.register(this, this.address, this); } public transferToWorker(worker: Worker, length: number): void { if (!this.active) throw new Error("Cannot transfer already disposed or transferred handle"); // Native memory fence: Increment atomic reference count prior to isolate boundary traversal lib.symbols.ref_handle(this.address); // Unregister local isolate finalizer before transfer to prevent race condition NativeBufferLease.registry.unregister(this); this.active = false; worker.postMessage({ type: "ACQUIRE_NATIVE_HANDLE", handleAddress: this.address, length, }); } public static allocate(size: number): NativeBufferLease { const handle = lib.symbols.alloc_handle(size); if (!handle) throw new Error("Native allocation failed"); return new NativeBufferLease(handle); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Worker Memory Fence & FinalizationRegistry Isolation Guardrail

Bun 1.2 Worker Memory Fence & FinalizationRegistry Isolation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict isolate boundaries and thread-safe lifecycle management for native C-bindings and Node-API handles across Bun 1.2 multi-threaded Workers. Prevents premature resource collection, cross-worker heap pollution, and use-after-free segfaults caused by uncoordinated FinalizationRegistry callbacks on transferred 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: Cross-Worker Raw Pointer Leakage Subject to Asynchronous Foreign-Isolate Finalization 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	Cross-Worker Raw Pointer Leakage Subject to Asynchronous Foreign-Isolate Finalization	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 isolate native C-binding deallocation (e.g., free/destructor calls within FinalizationRegistry) strictly to the isolate thread that originally allocated the 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.