Bun 1.2 AsyncLocalStorage Tenant Context Isolation Across Worker Boundaries

--- description: Bun 1.2 AsyncLocalStorage Tenant Context Isolation Across Worker Boundaries - Enforces strict tenant context serialization, manual rehydration, and explicit lifecycle boundary isolation when propagating AsyncLocalStorage instances across Bun 1.2 worker thread boundaries. Prevents cross-tenant context bleeding, silent trace dropping, and unbounded heap retention in persistent worker pools. globs: src/**/*.{ts,tsx}, workers/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-worker-asynclocalstorage-context-isolation-bun-1-2-asyncloc-178" --- # Bun 1.2 AsyncLocalStorage Tenant Context Isolation Across Worker Boundaries > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Implicit ALS Propagation Assumption and Leaked Shared Worker State ## System Constraints You are a Principal Backend Architect enforcing Bun 1.2 AsyncLocalStorage Context Isolation across Worker Boundaries. Mandate explicit envelope serialization, worker-side rehydration via als.run(), and absolute heap isolation across concurrent tenant dispatches. ## Strict Guidelines - Engineers MUST ALWAYS serialize execution context (tenantId, traceId, correlationTokens) into an immutable transport envelope before posting messages to Bun worker threads. - Engineers MUST NEVER assume AsyncLocalStorage automatically propagates across Bun Worker or WorkerPool thread boundaries. - Worker message listeners MUST ALWAYS wrap task execution within `tenantStorage.run(deserializedContext, async () => ...)` to ensure synchronous and asynchronous stack isolation. - Services MUST NOT store tenant or request context in module-scoped or global variables inside long-lived persistent worker threads. - Code MUST explicitly decouple large payload references from the rehydrated context envelope to prevent uncollected memory retention in the V8/JSC heap across worker job lifecycles. ## Bad vs Good Implementations ### Cross-Worker Boundary Context Propagation & Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: AsyncLocalStorage state is dropped entirely across worker boundaries. The worker attempts to manage state via a module-scoped variable, which persists across subsequent tasks on the same pooled worker thread, causing critical multi-tenant data leakage and memory retention. ```typescript import { AsyncLocalStorage } from 'node:async_hooks'; interface TenantContext { tenantId: string; traceId: string; } export const tenantStorage = new AsyncLocalStorage<TenantContext>(); let activeWorkerContext: TenantContext | undefined; // Anti-pattern: shared thread-global state // Main thread dispatch export function dispatchToWorker(worker: Worker, taskPayload: unknown) { // Anti-pattern: Fails to pass ALS state; assumes worker inherits execution context worker.postMessage({ payload: taskPayload }); } // Worker thread execution script self.onmessage = async (event: MessageEvent) => { const { payload } = event.data; // Anti-pattern: Retaining state in outer scope causes cross-task leakage in persistent pools activeWorkerContext = { tenantId: 'leaked-tenant', traceId: 'stale-trace' }; await processTask(payload); // activeWorkerContext is never cleared, leaking references and tenant context }; async function processTask(data: unknown) { console.log(`Processing under: ${activeWorkerContext?.tenantId}`); } ``` #### Production Standard (Correct) > **Standard**: Production invariant compliant implementation ensuring memory safety, deterministic execution, and zero runtime hallucination. ```typescript import { AsyncLocalStorage } from 'node:async_hooks'; export interface TenantContext { readonly tenantId: string; readonly traceId: string; } export interface WorkerTaskEnvelope<T> { readonly context: TenantContext; readonly payload: T; } export const tenantStorage = new AsyncLocalStorage<TenantContext>(); // Main thread dispatch: explicitly extracts context and packages it into an envelope export function dispatchToWorker<T>(worker: Worker, payload: T): void { const currentContext = tenantStorage.getStore(); if (!currentContext) { throw new Error('Tenant context required for background worker dispatch'); } const envelope: WorkerTaskEnvelope<T> = { context: Object.freeze({ ...currentContext }), payload }; worker.postMessage(envelope); } // Worker thread execution script: rehydrates and isolates task scope self.onmessage = async (event: MessageEvent<WorkerTaskEnvelope<unknown>>) => { const { context, payload } = event.data; // Strict rehydration inside storage.run ensures clean async cleanup per task await tenantStorage.run(context, async () => { try { await processTask(payload); } finally { // The context automatically falls out of ALS scope, preventing retention } }); }; async function processTask(data: unknown): Promise<void> { const ctx = tenantStorage.getStore(); console.log(`Securely processing for tenant: ${ctx?.tenantId}, trace: ${ctx?.traceId}`); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 AsyncLocalStorage Tenant Context Isolation Across Worker Boundaries

Bun 1.2 AsyncLocalStorage Tenant Context Isolation Across Worker Boundaries defines an industrial-grade behavioral standard for backend engineering. Enforces strict tenant context serialization, manual rehydration, and explicit lifecycle boundary isolation when propagating AsyncLocalStorage instances across Bun 1.2 worker thread boundaries. Prevents cross-tenant context bleeding, silent trace dropping, and unbounded heap retention in persistent worker pools. 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: Implicit ALS Propagation Assumption and Leaked Shared Worker State 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	Implicit ALS Propagation Assumption and Leaked Shared Worker State	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 serialize execution context (tenantId, traceId, correlationTokens) into an immutable transport envelope before posting messages to Bun worker threads.

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.