WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation

--- description: WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation - Enforces asynchronous shader pre-compilation with persistent IndexedDB pipeline descriptor caching to eliminate UI main-thread jank and shader stutter. Mandates strict GPU queue completion fencing and unmap-before-transfer invariants across dedicated Web Workers to prevent GPUDevice lost panics and concurrent memory mutation. globs: src/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webgpu-pipeline-caching-worker-fence-isolation" --- # WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Main-Thread Synchronous Pipeline Creation and Unfenced Worker Buffer Remapping ## System Constraints You are a Principal Engineer enforcing WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation. Mandate invariants that prevent main-thread micro-stutters and device-loss panics by isolating shader precompilation and multi-worker memory mapping behind strict explicit synchronization fences. ## Strict Guidelines - Engineers MUST ALWAYS invoke `device.createComputePipelineAsync()` instead of synchronous `device.createComputePipeline()` to prevent blocking the rendering or execution thread during driver compilation. - Engineers MUST cache serialized pipeline descriptors or compiled bytecode tokens in IndexedDB or CacheStorage keyed by cryptographic hash of the WGSL shader source code. - Engineers MUST NOT read from or map a staging `GPUBuffer` until `device.queue.onSubmittedWorkDone()` resolves, guaranteeing all device-side compute dispatches have completed execution. - Engineers MUST call `buffer.unmap()` immediately prior to transferring ownership of any underlying `ArrayBuffer` to another Web Worker or dispatching new GPU commands referencing that buffer. - Services MUST monitor `device.lost` and handle device reconstruction gracefully, invalidating all local compute pipeline handles and pending worker fence promises upon device destruction. ## Bad vs Good Implementations ### Compute Pipeline Creation & Safe Worker Staging Readback #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Synchronous pipeline creation blocks the thread while the GPU driver compiles WGSL into machine code. Initiating mapAsync without awaiting onSubmittedWorkDone or failing to unmap before cross-context handoffs risks silent data races and GPUDevice loss panics. ```typescript export async function runComputeBad(device: GPUDevice, shaderCode: string, inputData: Float32Array) { // Anti-pattern: Synchronous compilation causes main-thread micro-stutters const shaderModule = device.createShaderModule({ code: shaderCode }); const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module: shaderModule, entryPoint: 'main' } }); const stagingBuffer = device.createBuffer({ size: inputData.byteLength, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST }); const commandEncoder = device.createCommandEncoder(); // ... encoding compute pass and copy ... device.queue.submit([commandEncoder.finish()]); // Anti-pattern: Mapping immediately without waiting for queue submission fence // Anti-pattern: Posting buffer to worker while mapped or without explicit fence await stagingBuffer.mapAsync(GPUMapMode.READ); const copy = stagingBuffer.getMappedRange().slice(0); postMessage({ buffer: copy }); // Buffer state leaks and mapping stays alive } ``` #### Production Standard (Correct) > **Standard**: Uses asynchronous compilation (createComputePipelineAsync) with SHA-256 cache memoization to prevent UI frame drops. Enforces explicit synchronization with queue.onSubmittedWorkDone() and unmaps the GPUBuffer prior to returning ownership, completely eliminating device loss conditions. ```typescript export async function runComputeGood( device: GPUDevice, shaderCode: string, inputData: Float32Array, pipelineCache: Map<string, GPUComputePipeline> ): Promise<ArrayBuffer> { const shaderHash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(shaderCode)) .then(b => Array.from(new Uint8Array(b)).map(x => x.toString(16).padStart(2, '0')).join('')); let pipeline = pipelineCache.get(shaderHash); if (!pipeline) { const shaderModule = device.createShaderModule({ code: shaderCode }); pipeline = await device.createComputePipelineAsync({ layout: 'auto', compute: { module: shaderModule, entryPoint: 'main' } }); pipelineCache.set(shaderHash, pipeline); } const stagingBuffer = device.createBuffer({ size: inputData.byteLength, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST }); const encoder = device.createCommandEncoder(); // Compute pass dispatches and copyBufferToBuffer omitted for brevity device.queue.submit([encoder.finish()]); // Mandatory fence: guarantee execution completes before initiating map await device.queue.onSubmittedWorkDone(); await stagingBuffer.mapAsync(GPUMapMode.READ, 0, inputData.byteLength); const mappedRange = stagingBuffer.getMappedRange(0, inputData.byteLength); const transferableData = mappedRange.slice(0); stagingBuffer.unmap(); // Explicitly unmap before transferring or releasing stagingBuffer.destroy(); return transferableData; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation

WebGPU Compute Pipeline Compilation Caching & Cross-Worker Buffer Fence Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces asynchronous shader pre-compilation with persistent IndexedDB pipeline descriptor caching to eliminate UI main-thread jank and shader stutter. Mandates strict GPU queue completion fencing and unmap-before-transfer invariants across dedicated Web Workers to prevent GPUDevice lost panics and concurrent memory mutation. 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: Main-Thread Synchronous Pipeline Creation and Unfenced Worker Buffer Remapping 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	Main-Thread Synchronous Pipeline Creation and Unfenced Worker Buffer Remapping	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 invoke `device.createComputePipelineAsync()` instead of synchronous `device.createComputePipeline()` to prevent blocking the rendering or execution thread during driver compilation.

Engineers MUST ALWAYS invoke `device.createComputePipelineAsync()` instead of synchronous `device.createComputePipeline()` to prevent blocking the rendering or execution thread during driver compilation.

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.