Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard

--- description: Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard - Enforces strict memory isolation and deterministic lifecycle recycling for Bun 1.2 Worker pools in high-concurrency multi-tenant runtimes. Mandates post-task Resident Set Size (RSS) telemetry verification, draining thresholds, and non-blocking worker recreation to preempt JavaScriptCore heap fragmentation and OS thread starvation. globs: src/**/*.ts, src/workers/**/*.ts, src/pool/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-isolated-worker-pool-max-rss-recycle-standard" --- # Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Worker Lifespans Causing JSC Heap Fragmentation and Process SIGKILL ## System Constraints You are a Principal Systems Architect enforcing the Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard. Multi-tenant untrusted or high-throughput execution models under Bun's JavaScriptCore runtime must never allow persistent worker threads to accumulate uncollected C++ heap buffers or fragmented RSS. You must reject any static, unmonitored worker pool implementations and enforce deterministic RSS thresholds, graceful task completion draining, explicit worker termination, and asynchronous worker re-seeding. ## Strict Guidelines - Services MUST monitor per-worker Resident Set Size (RSS) after every dispatch cycle using `process.memoryUsage().rss` reported over IPC. - Engineers MUST set a hard ceiling for Max-RSS (e.g., 256MB) and a Max-Task count threshold per isolated worker instance. - Engineers MUST NOT reuse a worker instance once its RSS crosses the configured threshold; the worker MUST be marked in a `DRAINING` state. - Workers marked `DRAINING` MUST complete current in-flight executions, reject new incoming dispatches, and explicitly call `worker.terminate()` or receive a SIGTERM IPC directive. - Code SHOULD implement non-blocking backpressure queues with explicit acquisition timeouts to prevent thread-pool resource starvation. - Components NEVER instantiate unbounded `new Worker(...)` calls dynamically inside hot request paths without routing through an isolated, bounded lifecycle manager. ## Bad vs Good Implementations ### Persistent Unbounded Worker Pool vs. Monitored Auto-Recycling Worker Pool #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Workers are retained indefinitely. In multi-tenant environments, string retention, ArrayBuffers, and JavaScriptCore heap fragmentation steadily inflate the RSS. Bun will eventually hit platform memory ceilings, causing the host OS to terminate the master runtime via OOM SIGKILL. ```typescript import { Worker } from 'worker_threads'; // ANTI-PATTERN: Indefinite worker reuse without RSS bounds or lifecycle recycling export class UnboundedWorkerPool { private workers: Worker[] = []; private index = 0; constructor(poolSize: number) { for (let i = 0; i < poolSize; i++) { this.workers.push(new Worker(new URL('./tenant-task.ts', import.meta.url))); } } public async executeTask(payload: unknown): Promise<unknown> { // Round-robin dispatch with zero memory accounting const worker = this.workers[this.index++ % this.workers.length]; return new Promise((resolve, reject) => { const onMessage = (res: unknown) => { cleanup(); resolve(res); }; const onError = (err: Error) => { cleanup(); reject(err); }; const cleanup = () => { worker.off('message', onMessage); worker.off('error', onError); }; worker.on('message', onMessage); worker.on('error', onError); worker.postMessage(payload); }); } } ``` #### Production Standard (Correct) > **Standard**: Tracks both the task count and post-execution RSS reported by the worker. When thresholds are reached, or if an unexpected exception corrupts the isolate state, the worker is safely evicted and terminated (`worker.terminate()`), and a fresh worker isolate is spawned. ```typescript export interface TaskResult<T> { data: T; rssBytes: number; } export class RecycledWorkerPool { private static readonly MAX_RSS_BYTES = 256 * 1024 * 1024; // 256MB private static readonly MAX_TASKS_PER_WORKER = 500; private activeWorkers = new Set<Worker>(); private idleWorkers: Worker[] = []; private taskCounts = new WeakMap<Worker, number>(); constructor(private readonly poolSize: number, private readonly scriptUrl: URL) { for (let i = 0; i < this.poolSize; i++) { this.spawnWorker(); } } private spawnWorker(): Worker { const worker = new Worker(this.scriptUrl.href, { smol: true }); this.taskCounts.set(worker, 0); this.activeWorkers.add(worker); this.idleWorkers.push(worker); return worker; } private async recycleWorker(worker: Worker): Promise<void> { this.activeWorkers.delete(worker); const index = this.idleWorkers.indexOf(worker); if (index !== -1) { this.idleWorkers.splice(index, 1); } await worker.terminate(); this.spawnWorker(); } public async execute<T, R>(payload: T): Promise<R> { const worker = this.idleWorkers.pop() ?? this.spawnWorker(); const count = (this.taskCounts.get(worker) ?? 0) + 1; this.taskCounts.set(worker, count); try { const result = await new Promise<TaskResult<R>>((resolve, reject) => { const handleMsg = (ev: MessageEvent<TaskResult<R>>) => { worker.removeEventListener('message', handleMsg); worker.removeEventListener('error', handleErr); resolve(ev.data); }; const handleErr = (err: ErrorEvent) => { worker.removeEventListener('message', handleMsg); worker.removeEventListener('error', handleErr); reject(err.error); }; worker.addEventListener('message', handleMsg); worker.addEventListener('error', handleErr); worker.postMessage(payload); }); if (result.rssBytes >= RecycledWorkerPool.MAX_RSS_BYTES || count >= RecycledWorkerPool.MAX_TASKS_PER_WORKER) { await this.recycleWorker(worker); } else { this.idleWorkers.push(worker); } return result.data; } catch (error) { await this.recycleWorker(worker); throw error; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard

Bun 1.2 Isolated Worker Pool Max-RSS Auto-Recycle Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict memory isolation and deterministic lifecycle recycling for Bun 1.2 Worker pools in high-concurrency multi-tenant runtimes. Mandates post-task Resident Set Size (RSS) telemetry verification, draining thresholds, and non-blocking worker recreation to preempt JavaScriptCore heap fragmentation and OS thread starvation. 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 Worker Lifespans Causing JSC Heap Fragmentation and Process SIGKILL 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 Worker Lifespans Causing JSC Heap Fragmentation and Process SIGKILL	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:

Services MUST monitor per-worker Resident Set Size (RSS) after every dispatch cycle using `process.memoryUsage().rss` reported over IPC.

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.