AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
backendcritical PriorityID: bun-isolated-heap-snapshot-multitenant-sandbox

Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard

Enforces cryptographic and memory tenant boundary isolation within high-density Bun 1.2 runtimes using pre-warmed deterministic V8 heap snapshots and Web Worker/Node VM boundaries. Prevents cross-tenant state poisoning, prototype mutation leakage, and unmetered execution cycles during multi-tenant execution without container overhead.

Prohibited Anti-Pattern: Global Scope Mutation and Cross-Tenant State Pollution in Reused Bun Runtime Sandboxes

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard - Enforces cryptographic and memory tenant boundary isolation within high-density Bun 1.2 runtimes using pre-warmed deterministic V8 heap snapshots and Web Worker/Node VM boundaries. Prevents cross-tenant state poisoning, prototype mutation leakage, and unmetered execution cycles during multi-tenant execution without container overhead.
globs: src/sandbox/**/*.{ts,tsx}, src/workers/**/*.{ts,tsx}, src/services/tenant/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/bun-isolated-heap-snapshot-multitenant-sandbox"
---

# Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard

> **Severity**: CRITICAL | **Category**: backend
> **Anti-Pattern Warning**: Global Scope Mutation and Cross-Tenant State Pollution in Reused Bun Runtime Sandboxes

## System Constraints
You are a Principal Backend Systems Architect enforcing strict Bun 1.2 Isolated V8 Heap Snapshot and Sandbox architecture. Enforce deterministic state segregation, immutability of shared prototypes, strict resource metering, and zero shared-heap cross-contamination between tenant executions.

## Strict Guidelines
- Engineers MUST ALWAYS isolate tenant execution into a dedicated, ephemeral `node:vm` Context or distinct Bun `Worker` initialized from an immutable base snapshot.
- Engineers MUST NOT allow user/tenant code direct access to runtime globals (`process`, `Bun`, `fetch`, `globalThis`) without proxy-based interception and credential scrubbing.
- Services MUST deep-freeze or enforce read-only prototype trees (`Object.freeze(Object.prototype)`) in snapshot environments prior to tenant payload injection.
- Engineers MUST configure explicit execution deadlines (`timeout: number`) and strict memory ceilings to prevent microtask queue monopolization and OOM cascading across worker pools.
- Components NEVER preserve stateful module-level closures across tenant invocations; memory references must be completely collected or re-hydrated cleanly from the snapshot state.

## Bad vs Good Implementations
### Multi-Tenant Code Evaluation Isolation

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Direct `new Function` evaluation shares the host's `globalThis`, prototype chains, and environment variables. Malicious tenants can override prototypes (e.g., `Array.prototype.push`) or read server secrets directly out of `process.env`.
```typescript
import { type Request } from 'bun';

// Leaks global context and shared mutable state across tenant requests
export async function executeTenantScript(tenantId: string, userCode: string, payload: unknown) {
  const fn = new Function('payload', 'tenantId', userCode);
  return fn(payload, tenantId);
}
```

#### Production Standard (Correct)
> **Standard**: Creates a distinct `vm.createContext` with a clean `Object.create(null)` environment, denies access to unmetered host capabilities, mandates an explicit runtime timeout, and uses `structuredClone` across the execution boundary to eliminate shared-heap reference leaks.
```typescript
import vm from 'node:vm';

export interface TenantSandboxResult {
  result: unknown;
  durationMs: number;
}

export async function executeTenantScript(
  tenantId: string,
  userCode: string,
  payload: Record<string, unknown>,
  timeoutMs = 250
): Promise<TenantSandboxResult> {
  // Deterministic clean sandbox context with strict capability constraints
  const sandbox = Object.create(null);
  sandbox.payload = Object.freeze(structuredClone(payload));
  sandbox.tenantId = tenantId;
  sandbox.console = Object.freeze({
    log: (...args: unknown[]) => {
      // Isolated tenant logging sink
    }
  });

  const context = vm.createContext(sandbox, {
    name: `tenant-sandbox-${tenantId}`,
    origin: `sandbox://${tenantId}`,
    microtaskMode: 'afterEvaluate'
  });

  const start = performance.now();
  const script = new vm.Script(`'use strict'; (${userCode})(payload);`);

  const result = script.runInContext(context, {
    timeout: timeoutMs,
    displayErrors: false,
    breakOnSigint: true
  });

  return {
    result: structuredClone(result),
    durationMs: performance.now() - start
  };
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Node/Bun Runtime Memory Inspector
Inspects running V8 heaps, memory dumps, and execution graphs to detect cross-context memory leaks and uncollected objects.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Bun Heap Profiler CLI
Analyzes Bun snapshot memory layouts, object retained sizes, and heap isolation boundaries across ephemeral contexts.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard

Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard defines an industrial-grade behavioral standard for backend engineering. Enforces cryptographic and memory tenant boundary isolation within high-density Bun 1.2 runtimes using pre-warmed deterministic V8 heap snapshots and Web Worker/Node VM boundaries. Prevents cross-tenant state poisoning, prototype mutation leakage, and unmetered execution cycles during multi-tenant execution without container overhead. 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 Scope Mutation and Cross-Tenant State Pollution in Reused Bun Runtime Sandboxes 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftGlobal Scope Mutation and Cross-Tenant State Pollution in Reused Bun Runtime SandboxesCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS isolate tenant execution into a dedicated, ephemeral `node

Engineers MUST ALWAYS isolate tenant execution into a dedicated, ephemeral `node:vm` Context or distinct Bun `Worker` initialized from an immutable base snapshot.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT allow user/tenant code direct access to runtime globals (`process`, `Bun`, `fetch`, `globalThis`) without proxy-based interception and credential scrubbing.

Engineers MUST NOT allow user/tenant code direct access to runtime globals (`process`, `Bun`, `fetch`, `globalThis`) without proxy-based interception and credential scrubbing.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Services MUST deep-freeze or enforce read-only prototype trees (`Object.freeze(Object.prototype)`) in snapshot environments prior to tenant payload injection.

Services MUST deep-freeze or enforce read-only prototype trees (`Object.freeze(Object.prototype)`) in snapshot environments prior to tenant payload injection.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Engineers MUST configure explicit execution deadlines (`timeout

Engineers MUST configure explicit execution deadlines (`timeout: number`) and strict memory ceilings to prevent microtask queue monopolization and OOM cascading across worker pools.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Components NEVER preserve stateful module-level closures across tenant invocations

Components NEVER preserve stateful module-level closures across tenant invocations; memory references must be completely collected or re-hydrated cleanly from the snapshot state.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Bun 1.2 Isolated Heap Snapshot Multi-Tenant Sandbox Standard critical for AI coding assistants?

Enforces cryptographic and memory tenant boundary isolation within high-density Bun 1.2 runtimes using pre-warmed deterministic V8 heap snapshots and Web Worker/Node VM boundaries. Prevents cross-tenant state poisoning, prototype mutation leakage, and unmetered execution cycles during multi-tenant execution without container overhead. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Global Scope Mutation and Cross-Tenant State Pollution in Reused Bun Runtime Sandboxes) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related BACKEND Rules

View all rules →
backend
42

Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree.

backend
68

Bun Embedded SQLite WAL Mode & Transaction Synchronization Standard

Production database standard for bun:sqlite. Mandates enabling Write-Ahead Logging (PRAGMA journal_mode = WAL), busy timeouts, and using db.transaction() for atomic operations without lock starvation.

backend
68

Drizzle ORM Batch API & Interactive Transaction Isolation Standard

Production database standard for Drizzle ORM (PostgreSQL & MySQL). Mandates using db.batch() over HTTP drivers to prevent round-trip waterfalls, explicit db.transaction() with serializable/read-committed isolation, and strictly avoids unawaited query promises.

1 Rule in Stack

Bun