Bun 1.2 Native Addon Boundary & Deterministic Async Queue Standard

--- description: Bun 1.2 Native Addon Boundary & Deterministic Async Queue Standard - Enforces deterministic backpressure and thread isolation when executing C++ native addons (Node-API/Bun FFI) alongside high-throughput TypeScript edge workers in Bun 1.2. Prevents JavaScriptCore (JSC) microtask starvation, event-loop lag, and unmanaged native memory heap thrashing by mandating off-main-thread execution and bounded queue scheduling. globs: src/**/*.{ts,tsx}, src/workers/**/*.{ts,js}, src/native/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-deterministic-native-addon-queue-standard" --- # Bun 1.2 Native Addon Boundary & Deterministic Async Queue Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing blocking C++ FFI bindings synchronously on the main thread inside concurrent microtask chains, starving JSC event-loop ticks. ## System Constraints You are a Principal Software Architect enforcing Bun 1.2 Native Addon Boundary and Deterministic Async Queue invariants. JavaScriptCore processes microtasks prior to I/O ticks; any native C++ call or Bun FFI invocation exceeding 2ms on the main event loop starves microtasks, stalls TCP keep-alives, and exhausts system memory. You must enforce off-thread worker isolation, explicit bounded concurrency via token-bucket queues, and zero-copy typed buffer lifecycle management. ## Strict Guidelines - Engineers MUST ALWAYS isolate CPU-intensive C++ native addons or Bun FFI functions into dedicated 'Bun.Worker' threads or native C++ threadpools via 'napi_create_async_work'. - Engineers MUST NOT execute synchronous FFI routines directly inside HTTP request handlers or unbounded 'Promise.all' loops on the main thread. - Code SHOULD enforce deterministic queue backpressure using a bounded concurrency controller (maximum concurrency = physical CPU cores - 1) before delegating tasks to native workers. - Services MUST explicitly pass TypedArray memory buffers using transferable objects or zero-copy pointers, and explicitly clean up external native pointers to avoid GC heap thrashing. - Components NEVER yield control to the microtask queue using recursive 'queueMicrotask' or resolved 'Promise.resolve().then()' inside native task loops; macrotask yields ('await Bun.sleep(0)') must be used if executing batch slices on the main thread. ## Bad vs Good Implementations ### Offloading Heavy Native C++ Addon Calls to Bounded Worker Queue #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing native FFI synchronously directly inside Bun.serve completely blocks JavaScriptCore's thread. Network I/O, timer events, and microtasks are starved, driving latency into seconds and causing connection drops under moderate concurrency. ```typescript import { cc } from 'bun:ffi'; // ANTI-PATTERN: Synchronous C++ symbol binding executed on main thread const { symbols } = cc({ source: './native/transform.cpp', symbols: { process_buffer: { args: ['ptr', 'size'], returns: 'void', }, }, }); Bun.serve({ port: 3000, async fetch(req) { const payload = new Uint8Array(await req.arrayBuffer()); // CRITICAL BUG: Direct synchronous FFI call blocks the JavaScriptCore event loop. // Under concurrent load, this starves I/O microtasks and explodes memory. symbols.process_buffer(payload, payload.byteLength); return new Response(payload); }, }); ``` #### Production Standard (Correct) > **Standard**: Offloads the C++ addon execution to dedicated Bun.Worker threads bounded by available CPU cores. Transfers ArrayBuffers zero-copy to prevent heap thrashing and protects the primary JavaScriptCore event loop from microtask starvation. ```typescript import { Worker } from 'bun'; // PRODUCTION FIX: Deterministic Bounded Work Queue with Worker Isolation interface WorkItem { payload: Uint8Array; resolve: (value: Uint8Array) => void; reject: (reason: unknown) => void; } class NativeAddonPool { private queue: WorkItem[] = []; private activeWorkers = 0; private readonly maxConcurrency = Math.max(1, navigator.hardwareConcurrency - 1); private workers: Worker[] = []; constructor(workerScript: URL) { for (let i = 0; i < this.maxConcurrency; i++) { this.workers.push(new Worker(workerScript)); } } public async execute(payload: Uint8Array): Promise<Uint8Array> { return new Promise<Uint8Array>((resolve, reject) => { this.queue.push({ payload, resolve, reject }); this.drain(); }); } private drain(): void { while (this.activeWorkers < this.maxConcurrency && this.queue.length > 0) { const item = this.queue.shift(); if (!item) break; const worker = this.workers[this.activeWorkers % this.workers.length]; this.activeWorkers++; const onMessage = (event: MessageEvent<Uint8Array>) => { cleanup(); this.activeWorkers--; item.resolve(event.data); this.drain(); }; const onError = (error: ErrorEvent) => { cleanup(); this.activeWorkers--; item.reject(error); this.drain(); }; const cleanup = () => { worker.removeEventListener('message', onMessage); worker.removeEventListener('error', onError); }; worker.addEventListener('message', onMessage); worker.addEventListener('error', onError); // Zero-copy transfer of underlying ArrayBuffer worker.postMessage(item.payload, [item.payload.buffer]); } } } const pool = new NativeAddonPool(new URL('./transform.worker.ts', import.meta.url)); Bun.serve({ port: 3000, async fetch(req) { const buffer = await req.arrayBuffer(); const payload = new Uint8Array(buffer); try { const processed = await pool.execute(payload); return new Response(processed); } catch (err) { return new Response('Native Processing Failed', { status: 500 }); } }, }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native Addon Boundary & Deterministic Async Queue Standard

Bun 1.2 Native Addon Boundary & Deterministic Async Queue Standard defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic backpressure and thread isolation when executing C++ native addons (Node-API/Bun FFI) alongside high-throughput TypeScript edge workers in Bun 1.2. Prevents JavaScriptCore (JSC) microtask starvation, event-loop lag, and unmanaged native memory heap thrashing by mandating off-main-thread execution and bounded queue scheduling. 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: Executing blocking C++ FFI bindings synchronously on the main thread inside concurrent microtask chains, starving JSC event-loop ticks. 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	Executing blocking C++ FFI bindings synchronously on the main thread inside concurrent microtask chains, starving JSC event-loop ticks.	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 CPU-intensive C++ native addons or Bun FFI functions into dedicated 'Bun.Worker' threads or native C++ threadpools via 'napi_create_async_work'.

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.