Bun 1.2 Worker Cluster & Native SQLite WAL Multi-Tenant Memory Boundary Enforcement

--- description: Bun 1.2 Worker Cluster & Native SQLite WAL Multi-Tenant Memory Boundary Enforcement - Enforces strict memory isolation ceilings and tenant-segregated SQLite WAL boundaries across Bun 1.2 clustered worker threads. Guarantees zero cross-tenant shared-memory bleed, mitigates noisy-neighbor heap exhaustion, and prevents WAL shm lock contention in ultra-low-latency edge microservices. globs: src/**/*.ts, workers/**/*.ts, services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-cluster-worker-sqlite-isolation" --- # Bun 1.2 Worker Cluster & Native SQLite WAL Multi-Tenant Memory Boundary Enforcement > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Cross-Tenant Shared SQLite Handles and Unbounded Worker Heap Allocation ## System Constraints You are a Principal Software Architect enforcing Bun 1.2 multi-tenant worker isolation and native SQLite concurrency invariants. You must mandate strict memory boundaries, per-tenant SQLite directory sandboxing, and non-blocking WAL configurations across worker clusters. ## Strict Guidelines - Engineers MUST ALWAYS isolate native SQLite database files and their associated WAL/SHM artifacts into dedicated, tenant-scoped directory trees (e.g., `/data/tenants/${tenantId}/store.db`). - Engineers MUST NOT share bun:sqlite Database instances across cluster workers or worker threads; each worker isolate MUST independently instantiate its own scoped handle. - Engineers MUST configure explicit worker isolate memory constraints using workerData and process resource limits, setting maxOldGenerationSizeMb to prevent tenant noisy-neighbor OOM events. - Code MUST set PRAGMA journal_mode = WAL and PRAGMA synchronous = NORMAL on every worker SQLite connection to avoid blocking event loops while maintaining tenant-level ACID safety. - Services MUST execute PRAGMA wal_checkpoint(PASSIVE) or TRUNCATE within tenant-scoped lifecycle hooks and MUST NEVER invoke global checkpoints across concurrent active tenant worker pools. - Components NEVER pass raw Database pointers, ArrayBuffers referencing WAL shared memory, or unmanaged worker references across IPC boundaries. ## Bad vs Good Implementations ### Tenant Worker & SQLite Handle Factory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Sharing a single SQLite database handle across workers bypasses thread safety and causes WAL lock contention. Unconstrained worker instantiation allows a single malicious or runaway tenant to exhaust host memory (OOM), crashing all adjacent tenant isolates. ```typescript import { Database } from 'bun:sqlite'; // ANTI-PATTERN: Shared global DB handle across all tenants and workers. // Shared WAL (-wal) and shared memory (-shm) files create cross-tenant lock contention. const globalDb = new Database('/var/data/shared.sqlite'); globalDb.run('PRAGMA journal_mode = WAL;'); export function handleTenantRequest(tenantId: string, query: string) { // Worker lacks isolate memory constraints and risks heap exhaustion across tenants const worker = new Worker(new URL('./unisolated-worker.ts', import.meta.url)); worker.postMessage({ tenantId, query, dbRef: globalDb }); } ``` #### Production Standard (Correct) > **Standard**: Each tenant worker runs within a restricted memory isolate (smol: true and explicit resourceLimits). The SQLite database is sandboxed in a tenant-specific path, creating decoupled WAL/SHM shared-memory boundaries that eliminate contention and data leakage. ```typescript import { Database } from 'bun:sqlite'; import { mkdirSync } from 'node:fs'; import { join } from 'node:path'; interface TenantWorkerPayload { tenantId: string; action: string; } // GOOD: Enforce isolated worker spawns with bounded isolate heap limits export function spawnTenantWorker(tenantId: string): Worker { // Sanitize tenantId to prevent path traversal const safeTenantId = tenantId.replace(/[^a-zA-Z0-9_-]/g, ''); return new Worker(new URL('./tenant-worker.ts', import.meta.url), { name: `tenant-worker-${safeTenantId}`, smol: true, // Enforce hard heap limits per worker isolate in Bun resourceLimits: { maxOldGenerationSizeMb: 64, maxYoungGenerationSizeMb: 16, }, }); } // Inside tenant-worker.ts: Per-tenant scoped SQLite instance export function initTenantDatabase(tenantId: string): Database { const safeTenantId = tenantId.replace(/[^a-zA-Z0-9_-]/g, ''); const baseDir = join('/data', 'tenants', safeTenantId); mkdirSync(baseDir, { recursive: true }); const db = new Database(join(baseDir, 'tenant.sqlite'), { create: true, strict: true, }); // Strict WAL isolation: Scopes -wal and -shm files entirely to this tenant's directory db.run('PRAGMA journal_mode = WAL;'); db.run('PRAGMA synchronous = NORMAL;'); db.run('PRAGMA busy_timeout = 5000;'); db.run('PRAGMA temp_store = MEMORY;'); return db; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Worker Cluster & Native SQLite WAL Multi-Tenant Memory Boundary Enforcement

Bun 1.2 Worker Cluster & Native SQLite WAL Multi-Tenant Memory Boundary Enforcement defines an industrial-grade behavioral standard for backend engineering. Enforces strict memory isolation ceilings and tenant-segregated SQLite WAL boundaries across Bun 1.2 clustered worker threads. Guarantees zero cross-tenant shared-memory bleed, mitigates noisy-neighbor heap exhaustion, and prevents WAL shm lock contention in ultra-low-latency edge microservices. 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-Tenant Shared SQLite Handles and Unbounded Worker Heap Allocation 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-Tenant Shared SQLite Handles and Unbounded Worker Heap Allocation	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 SQLite database files and their associated WAL/SHM artifacts into dedicated, tenant-scoped directory trees (e.g., `/data/tenants/${tenantId}/store.db`).

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.