WebGPU Asynchronous Pipeline Pre-warming and Deterministic VRAM Budgeting

--- description: WebGPU Asynchronous Pipeline Pre-warming and Deterministic VRAM Budgeting - Enforces non-blocking WebGPU initialization and deterministic resource allocation to prevent runtime frame drops and browser GPU process termination. Mandates explicit asynchronous pipeline pre-compilation via createRenderPipelineAsync/createComputePipelineAsync and strict VRAM accounting with deterministic buffer and texture lifecycle disposal. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webgpu-pipeline-compilation-memory-budgeting" --- # WebGPU Asynchronous Pipeline Pre-warming and Deterministic VRAM Budgeting > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Synchronous Pipeline Creation in Render Paths and Unbudgeted VRAM Allocation Leading to Tab Crashes ## System Constraints You are a Principal Software Architect enforcing WebGPU Pipeline Compilation and Memory Budgeting Guardrails. Mandate that all WebGPU pipelines are compiled asynchronously prior to rendering dispatches to eliminate main-thread and driver-level shader compilation stutters. Enforce strict, proactive VRAM allocation budgeting that tracks byte allocations across textures and buffers, handles memory pressure dynamically, and mandates explicit buffer.destroy() and texture.destroy() calls upon teardown to prevent browser tab crashes. ## Strict Guidelines - Engineers MUST ALWAYS use `device.createRenderPipelineAsync()` or `device.createComputePipelineAsync()` during an initialization or pre-warming phase before issuing draw or dispatch calls. - Engineers MUST NOT call synchronous `device.createRenderPipeline()` or `device.createComputePipeline()` in active frame loops or user-interactive paths. - Services MUST maintain an explicit VRAM budget tracker that calculates exact memory usage (including texture format byte sizes, pitch alignments, and mipmap chains) before issuing GPU allocations. - Code MUST throw an actionable error or trigger an eviction policy when a requested buffer or texture allocation exceeds the designated device VRAM budget. - Engineers MUST explicitly call `.destroy()` on every `GPUBuffer` and `GPUTexture` instance during component unmounts, scene teardowns, or cache evictions instead of relying on garbage collection. - Components NEVER re-instantiate identical GPU pipelines; all pipeline instances MUST be keyed and cached in an idempotent pipeline registry. ## Bad vs Good Implementations ### Asynchronous Pipeline Compilation & Explicit VRAM Disposal #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Synchronous pipeline creation freezes the main thread while the browser driver compiles WGSL into platform-native machine code. Allocating large GPU resources without budgeting or explicit `.destroy()` leads to driver-level memory leaks, GPU process OOMs, and unexpected `device.lost` crashes. ```typescript class BadRenderer { private device!: GPUDevice; // BAD: Synchronously compiles pipeline on render path causing frame drops public render(view: GPUTextureView, code: string): void { const module = this.device.createShaderModule({ code }); const pipeline = this.device.createRenderPipeline({ layout: 'auto', vertex: { module, entryPoint: 'vs_main' }, fragment: { module, entryPoint: 'fs_main', targets: [{ format: 'bgra8unorm' }], }, }); // BAD: Allocating unbounded buffers without tracking VRAM or cleanup const buffer = this.device.createBuffer({ size: 1024 * 1024 * 64, // 64MB unmonitored allocation usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST, }); const commandEncoder = this.device.createCommandEncoder(); const pass = commandEncoder.beginRenderPass({ colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store', }], }); pass.setPipeline(pipeline); pass.setVertexBuffer(0, buffer); pass.draw(3); pass.end(); this.device.queue.submit([commandEncoder.finish()]); // Leaking buffer and pipeline to browser GC } } ``` #### Production Standard (Correct) > **Standard**: Pre-warms pipelines asynchronously off the critical rendering path via `createRenderPipelineAsync` with a cache hit lookup. Proactively tracks allocated VRAM against a budget and instruments buffers with explicit disposal logic through `Symbol.dispose` and `.destroy()`. ```typescript interface VramBudgetConfig { maxBytes: number; } class BudgetExceededError extends Error { constructor(requested: number, available: number) { super(`VRAM budget exceeded: Requested ${requested}B, available: ${available}B`); this.name = 'BudgetExceededError'; } } class SafeGpuManager { private readonly pipelineCache = new Map<string, GPURenderPipeline>(); private allocatedBytes = 0; private readonly maxBytes: number; constructor(private readonly device: GPUDevice, config: VramBudgetConfig) { this.maxBytes = config.maxBytes; } public async prewarmPipeline(key: string, descriptor: GPURenderPipelineDescriptor): Promise<GPURenderPipeline> { let pipeline = this.pipelineCache.get(key); if (!pipeline) { // GOOD: Asynchronous non-blocking pipeline compilation pipeline = await this.device.createRenderPipelineAsync(descriptor); this.pipelineCache.set(key, pipeline); } return pipeline; } public allocateBuffer(descriptor: GPUBufferDescriptor): GPUBuffer & { [Symbol.dispose](): void } { if (this.allocatedBytes + descriptor.size > this.maxBytes) { throw new BudgetExceededError(descriptor.size, this.maxBytes - this.allocatedBytes); } const buffer = this.device.createBuffer(descriptor); this.allocatedBytes += descriptor.size; let destroyed = false; const trackedBuffer = Object.assign(buffer, { [Symbol.dispose]: () => { if (!destroyed) { destroyed = true; buffer.destroy(); // GOOD: Deterministic GPU resource disposal this.allocatedBytes -= descriptor.size; } } }); return trackedBuffer; } public get currentUsage(): number { return this.allocatedBytes; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebGPU Asynchronous Pipeline Pre-warming and Deterministic VRAM Budgeting

WebGPU Asynchronous Pipeline Pre-warming and Deterministic VRAM Budgeting defines an industrial-grade behavioral standard for frontend engineering. Enforces non-blocking WebGPU initialization and deterministic resource allocation to prevent runtime frame drops and browser GPU process termination. Mandates explicit asynchronous pipeline pre-compilation via createRenderPipelineAsync/createComputePipelineAsync and strict VRAM accounting with deterministic buffer and texture lifecycle disposal. 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: Synchronous Pipeline Creation in Render Paths and Unbudgeted VRAM Allocation Leading to Tab Crashes 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	Synchronous Pipeline Creation in Render Paths and Unbudgeted VRAM Allocation Leading to Tab Crashes	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 use `device.createRenderPipelineAsync()` or `device.createComputePipelineAsync()` during an initialization or pre-warming phase before issuing draw or dispatch calls.

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.