Bun 1.2 Native SQL Transaction Lease Timeout & Connection Reclamation Guardrail

--- description: Bun 1.2 Native SQL Transaction Lease Timeout & Connection Reclamation Guardrail - Mandates deterministic lease timeouts and automated rollback reclamation for Bun 1.2 native SQL transaction handles. Eliminates zombie pool connections and uncommitted lock retention caused by asynchronous micro-event loop starvation or unhandled pending promises within transaction scopes. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-sql-transaction-lease-timeout-guardrail" --- # Bun 1.2 Native SQL Transaction Lease Timeout & Connection Reclamation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Asynchronous Transaction Closures Inducing Connection Pool Starvation and Uncommitted Lock Retention ## System Constraints You are a Principal Backend Architect enforcing transaction boundary integrity and connection lease timeouts in Bun 1.2 Native SQL. You must mandate strict lease expirations, explicit AbortSignal propagation, and deterministic rollback escalation to ensure zero connection leaks and zero dangling locks under asynchronous event loop pressure. ## Strict Guidelines - Engineers MUST ALWAYS wrap Bun 1.2 native SQL transaction closures with an explicit lease timeout using AbortSignal.timeout() or dedicated watchdog timers. - Engineers MUST NOT execute unbounded external HTTP requests, heavy CPU cryptography, or un-checkpointed background tasks inside an active database transaction handle. - Transactions MUST encapsulate state mutation within the shortest possible critical path, keeping locks held for under 500ms under standard operational conditions. - Code MUST explicitly catch transaction lease expiration errors and trigger an immediate deterministic ROLLBACK before returning the handle to the connection pool. - Services MUST implement transactional idempotency mechanisms to safely handle aborted leases and subsequent automated retries without duplicate side effects. ## Bad vs Good Implementations ### Bun 1.2 Native SQL Transaction with Bounded Lease Timeout Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the fraud detection fetch stalls or the event loop queues microtasks, the native SQL connection remains checked out and table/row locks remain active. Bun's internal pool exhausts available workers, cascading into application-wide denial of service. ```typescript import { SQL } from "bun"; const sql = new SQL(); export async function transferFundsUnsafe(fromId: string, toId: string, amount: number) { // Anti-pattern: Transaction closure has no lease timeout or abort signal. // An external microtask stall, slow RPC, or unhandled promise hang leaves // the connection lease open and row-level locks held indefinitely. return await sql.begin(async (tx) => { await tx`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`; // Unbounded asynchronous micro-event loop pressure await fetch(`https://fraud-detection.internal/verify?id=${fromId}`); await tx`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`; return { success: true }; }); } ``` #### Production Standard (Correct) > **Standard**: All external I/O is isolated outside the transaction scope. The transaction scope is bounded by a strict lease timeout (AbortSignal.timeout), preempting connection lock retention, avoiding pool starvation, and maintaining event loop throughput. ```typescript import { SQL } from "bun"; const sql = new SQL(); const TRANSACTION_LEASE_TIMEOUT_MS = 2_500; export async function transferFundsSafe(fromId: string, toId: string, amount: number) { // 1. Perform unbounded external I/O prior to entering the transactional critical section const isAuthorized = await verifyRiskPreFlight(fromId); if (!isAuthorized) throw new Error("Transaction rejected: risk threshold exceeded"); // 2. Bound the transaction closure with an explicit lease timeout const leaseSignal = AbortSignal.timeout(TRANSACTION_LEASE_TIMEOUT_MS); return await sql.begin(async (tx) => { const leaseCheck = () => { if (leaseSignal.aborted) { throw new Error(`TransactionLeaseTimeout: Lease expired after ${TRANSACTION_LEASE_TIMEOUT_MS}ms`); } }; try { leaseCheck(); await tx`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`; leaseCheck(); await tx`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`; return { success: true }; } catch (error) { // 3. Ensure transaction context is explicitly aborted and cleaned up await tx`ROLLBACK`.catch(() => {}); throw error; } }); } async function verifyRiskPreFlight(id: string): Promise<boolean> { const res = await fetch(`https://fraud-detection.internal/verify?id=${id}`, { signal: AbortSignal.timeout(1_000), }); return res.ok; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Native SQL Transaction Lease Timeout & Connection Reclamation Guardrail

Bun 1.2 Native SQL Transaction Lease Timeout & Connection Reclamation Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates deterministic lease timeouts and automated rollback reclamation for Bun 1.2 native SQL transaction handles. Eliminates zombie pool connections and uncommitted lock retention caused by asynchronous micro-event loop starvation or unhandled pending promises within transaction scopes. 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: Unbounded Asynchronous Transaction Closures Inducing Connection Pool Starvation and Uncommitted Lock Retention 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	Unbounded Asynchronous Transaction Closures Inducing Connection Pool Starvation and Uncommitted Lock Retention	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 wrap Bun 1.2 native SQL transaction closures with an explicit lease timeout using AbortSignal.timeout() or dedicated watchdog timers.

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.