Bun 1.2 Deterministic Handle Lifecycle via TC39 AsyncDisposable Invariant

--- description: Bun 1.2 Deterministic Handle Lifecycle via TC39 AsyncDisposable Invariant - Enforces deterministic native handle cleanup across high-throughput streaming RPCs and file I/O using Bun 1.2 TC39 Explicit Resource Management. Prevents catastrophic file descriptor exhaustion (EMFILE/ENFILE) and native C++ handle leaks caused by non-deterministic V8/JSC garbage collection cycles. globs: src/**/*.{ts,tsx}, server/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-native-asyncdisposable-handle-cleanup" --- # Bun 1.2 Deterministic Handle Lifecycle via TC39 AsyncDisposable Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Manual handle tracking or GC-reliant disposal in high-throughput streaming RPC pipelines ## System Constraints You are a Principal Backend Systems Architect enforcing Bun 1.2 Native AsyncDisposable Handle Cleanup Invariants. You must mandate deterministic TC39 Explicit Resource Management (`using` and `await using`) for all native resources including file descriptors, sockets, database clients, and streaming RPC handles. Reject any code relying on garbage collection or fragile manual `.close()` calls inside try/finally blocks. ## Strict Guidelines - Engineers MUST ALWAYS declare native resource handles (file handles, database transactions, streaming RPC sinks, subprocesses) with `await using` or `using` bindings adhering to TC39 Explicit Resource Management. - Engineers MUST NOT rely on JavaScript engine garbage collection (FinalizationRegistry) to close native C++ handles, as throughput easily outpaces GC collection intervals, causing EMFILE / ENFILE crashes. - Custom streaming wrappers and RPC clients MUST implement `[Symbol.asyncDispose]()` to guarantee deterministic flush and closure on scope exit, abort signals, or unhandled exceptions. - Code SHOULD leverage `AsyncDisposableStack` when orchestrating dynamic, multi-resource lifetimes or fan-out streaming operations. - Components NEVER leak handles out of scope without transferring ownership to an explicit lifecycle manager or parent `AsyncDisposableStack`. ## Bad vs Good Implementations ### High-Throughput Streaming RPC File Sink #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Manual try/finally management in high-throughput async pipelines fails to deterministically flush and release native handles when generators are canceled or abort signals trigger abruptly. Native C++ handles accumulate faster than GC sweeps, leading to EMFILE exhaustion. ```typescript import { open } from "node:fs/promises"; // Anti-pattern: Manual cleanup in streaming RPC easily leaks handles on aborts or uncaught rejections export async function processRpcStream(stream: ReadableStream<Uint8Array>, outputPath: string): Promise<void> { const fileHandle = await open(outputPath, "w"); const writer = fileHandle.createWriteStream(); try { for await (const chunk of stream) { if (!writer.write(chunk)) { await new Promise((resolve) => writer.once("drain", resolve)); } } } finally { // Under high concurrency, unhandled stream cancellations or early pipeline aborts // can leave the underlying native OS handle unclosed before GC sweeps. writer.end(); await fileHandle.close(); } } ``` #### Production Standard (Correct) > **Standard**: Utilizes TC39 Explicit Resource Management supported natively in Bun 1.2. The `await using` declaration binds the OS file descriptor strictly to the lexical block scope, guaranteeing instant native teardown even during stream cancellation or pipeline errors. ```typescript import { open } from "node:fs/promises"; // Production Invariant: Encapsulate native resource with TC39 Symbol.asyncDispose in Bun 1.2 class ManagedFileSink implements AsyncDisposable { private constructor(private readonly handle: import("node:fs/promises").FileHandle) {} static async create(path: string): Promise<ManagedFileSink> { const handle = await open(path, "w"); return new ManagedFileSink(handle); } async write(data: Uint8Array): Promise<void> { await this.handle.write(data); } async [Symbol.asyncDispose](): Promise<void> { await this.handle.sync().catch(() => {}); await this.handle.close(); } } export async function processRpcStream(stream: ReadableStream<Uint8Array>, outputPath: string): Promise<void> { // Deterministic scope-bound lifecycle: handle closes instantly upon block exit await using sink = await ManagedFileSink.create(outputPath); for await (const chunk of stream) { await sink.write(chunk); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Deterministic Handle Lifecycle via TC39 AsyncDisposable Invariant

Bun 1.2 Deterministic Handle Lifecycle via TC39 AsyncDisposable Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic native handle cleanup across high-throughput streaming RPCs and file I/O using Bun 1.2 TC39 Explicit Resource Management. Prevents catastrophic file descriptor exhaustion (EMFILE/ENFILE) and native C++ handle leaks caused by non-deterministic V8/JSC garbage collection cycles. 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: Manual handle tracking or GC-reliant disposal in high-throughput streaming RPC pipelines 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	Manual handle tracking or GC-reliant disposal in high-throughput streaming RPC pipelines	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 declare native resource handles (file handles, database transactions, streaming RPC sinks, subprocesses) with `await using` or `using` bindings adhering to TC39 Explicit Resource Management.

Engineers MUST ALWAYS declare native resource handles (file handles, database transactions, streaming RPC sinks, subprocesses) with `await using` or `using` bindings adhering to TC39 Explicit Resource Management.

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.