Bun 1.2 Multi-Worker Prepared Statement Cache Coherence Standard

--- description: Bun 1.2 Multi-Worker Prepared Statement Cache Coherence Standard - Enforces strict lifecycle management, bounded caching, and cross-thread schema invalidation for prepared statements within Bun 1.2 multi-threaded worker pools. Prevents off-heap memory fragmentation, unbounded native statement allocations, and stale plan execution against distributed database replicas following dynamic schema alterations or failovers. globs: src/**/*.worker.ts, src/**/workers/**/*.ts, src/**/db/**/*.ts, src/**/repositories/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-multiworker-prepared-statement-coherence-standard" --- # Bun 1.2 Multi-Worker Prepared Statement Cache Coherence Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Global Unbounded Statement Caching and Desynchronized Prepared Plans Across Isolated Bun Worker Threads ## System Constraints You are a Principal Backend Engineer enforcing strict prepared statement cache coherence across isolated Bun 1.2 Web Workers (`Worker` threads). You must mandate isolated statement lifecycle handling, LRU memory bounds on native statement handles, and strict inter-worker broadcast channel invalidation protocols when database topology or schema versions advance. ## Strict Guidelines - Engineers MUST ALWAYS isolate native prepared statement caches per worker thread and bound them with an explicit Least-Recently-Used (LRU) eviction strategy to prevent native handle leaks. - Engineers MUST NOT share raw connection handles or native statement pointers across worker boundaries via postMessage. - Services MUST implement a BroadcastChannel or cross-thread IPC event subscriber within every worker to instantly evict and finalize prepared statement caches upon receiving schema modification or read-replica topology migration signals. - Code SHOULD explicitly call `.finalize()` (or equivalent driver deallocation) on evicted prepared statements to reclaim off-heap C++ memory immediately rather than relying on engine garbage collection. - Workers NEVER execute dynamic SQL concatenations inside prepared statement keys; query templates must use parameterized placeholders and normalized static string keys for cache indexing. ## Bad vs Good Implementations ### Unbounded Static Prepared Statement Cache without Schema Sync vs. Bounded Coherent Worker Cache #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The worker instantiates an unbounded Map of compiled statements that never finalizes evicted statements. Additionally, the worker lacks an IPC invalidation listener; if DDL runs or read-replica topology shifts, the worker executes stale compiled plans against invalidated catalogs. ```typescript import { Database, Statement } from "bun:sqlite"; // ANTI-PATTERN: Worker holds an unbounded module-level statement cache // that never responds to schema migrations, causing stale read execution and native memory bloat const db = new Database(process.env.DB_REPLICA_URL); const statementCache = new Map<string, Statement>(); declare const self: Worker; self.onmessage = (event: MessageEvent<{ query: string; params: any[] }>) => { const { query, params } = event.data; let stmt = statementCache.get(query); if (!stmt) { // Leaks off-heap memory as queries proliferate; ignores ALTER TABLE / DDL changes across replicas stmt = db.prepare(query); statementCache.set(query, stmt); } const results = stmt.all(...params); self.postMessage(results); }; ``` #### Production Standard (Correct) > **Standard**: Employs an explicit LRU eviction mechanism with `.finalize()` cleanup, bounding off-heap native memory. Listens on a cross-worker `BroadcastChannel` to immediately invalidate all cached statements upon schema epoch increment, guaranteeing cache coherence across isolated Bun threads. ```typescript import { Database, Statement } from "bun:sqlite"; interface InvalidationMessage { type: "SCHEMA_INVALIDATION" | "REPLICA_TOPOLOGY_CHANGE"; schemaEpoch: number; } class CoherentStatementCache { private readonly cache = new Map<string, Statement>(); private readonly maxEntries: number; private currentEpoch = 0; constructor(private readonly db: Database, maxEntries = 256) { this.maxEntries = maxEntries; } public getOrPrepare(sqlKey: string, epoch: number): Statement { if (epoch > this.currentEpoch) { this.invalidateAll(); this.currentEpoch = epoch; } const existing = this.cache.get(sqlKey); if (existing) { this.cache.delete(sqlKey); this.cache.set(sqlKey, existing); // Re-insert for LRU freshness return existing; } if (this.cache.size >= this.maxEntries) { const oldestKey = this.cache.keys().next().value; if (oldestKey) { this.evict(oldestKey); } } const stmt = this.db.prepare(sqlKey); this.cache.set(sqlKey, stmt); return stmt; } public evict(sqlKey: string): void { const stmt = this.cache.get(sqlKey); if (stmt) { stmt.finalize(); this.cache.delete(sqlKey); } } public invalidateAll(): void { for (const stmt of this.cache.values()) { stmt.finalize(); } this.cache.clear(); } } declare const self: Worker; const db = new Database(process.env.DB_REPLICA_URL); const statementCache = new CoherentStatementCache(db, 200); let schemaEpoch = 0; const syncChannel = new BroadcastChannel("db_schema_coherence"); syncChannel.onmessage = (event: MessageEvent<InvalidationMessage>) => { if (event.data?.type === "SCHEMA_INVALIDATION" || event.data?.type === "REPLICA_TOPOLOGY_CHANGE") { schemaEpoch = event.data.schemaEpoch; statementCache.invalidateAll(); } }; self.onmessage = (event: MessageEvent<{ sqlTemplate: string; params: any[] }>) => { const { sqlTemplate, params } = event.data; try { const stmt = statementCache.getOrPrepare(sqlTemplate, schemaEpoch); const results = stmt.all(...params); self.postMessage({ success: true, data: results }); } catch (error) { self.postMessage({ success: false, error: (error as Error).message }); } }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Multi-Worker Prepared Statement Cache Coherence Standard

Bun 1.2 Multi-Worker Prepared Statement Cache Coherence Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict lifecycle management, bounded caching, and cross-thread schema invalidation for prepared statements within Bun 1.2 multi-threaded worker pools. Prevents off-heap memory fragmentation, unbounded native statement allocations, and stale plan execution against distributed database replicas following dynamic schema alterations or failovers. 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: Global Unbounded Statement Caching and Desynchronized Prepared Plans Across Isolated Bun Worker Threads 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	Global Unbounded Statement Caching and Desynchronized Prepared Plans Across Isolated Bun Worker Threads	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 prepared statement caches per worker thread and bound them with an explicit Least-Recently-Used (LRU) eviction strategy to prevent native handle leaks.

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.