WebGPU Compute Pipeline Memory Synchronization and Pass Transition Guardrail

--- description: WebGPU Compute Pipeline Memory Synchronization and Pass Transition Guardrail - Enforces deterministic memory coherence across dependent compute dispatches during client-side WebGPU parallel ML inference. WebGPU does not guarantee write-after-read (WAR), read-after-write (RAW), or write-after-write (WAW) coherence between dispatches within the same compute pass. Engineers must separate dependent kernel dispatches across explicit compute pass boundaries or command encoder transitions to introduce hardware-level execution and memory barriers. globs: src/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webgpu-compute-pipeline-memory-synchronization-barrier" --- # WebGPU Compute Pipeline Memory Synchronization and Pass Transition Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Consecutive Dispatches Sharing Read-Write Storage Buffers Within a Single Compute Pass ## System Constraints You are a Principal Software Architect enforcing hardware-level execution and memory synchronization barriers in WebGPU compute pipelines. In WebGPU, dispatches within the same compute pass execute concurrently without sequential barrier guarantees, leading to non-deterministic race conditions and silent tensor data corruption when kernels have data dependencies. Mandate explicit compute pass termination or pipeline barriers between dependent storage buffer read/write operations. ## Strict Guidelines - Engineers MUST ALWAYS end the current `GPUComputePassEncoder` via `.end()` before dispatching a subsequent compute kernel that depends on memory written by the previous kernel. - Engineers MUST NOT dispatch kernels with Write-After-Read (WAR), Read-After-Write (RAW), or Write-After-Write (WAW) dependencies within the exact same `GPUComputePassEncoder`. - Code MUST structure multi-step neural network execution (e.g., GEMM followed by LayerNorm or Softmax) across distinct compute passes or distinct command submissions when intermediate tensor outputs serve as subsequent inputs. - Services MUST ensure that storage buffers bound with `read_write` access qualifiers in WGSL are not simultaneously read or written by concurrent workgroups without intra-pass workgroup barriers (`workgroupBarrier()`) within a single dispatch or inter-pass barriers across dispatches. - Pipelines NEVER rely on sequential JavaScript `passEncoder.dispatchWorkgroups()` calls to imply sequential GPU memory visibility, as dispatches inside a single pass may overlap execution pipelines. ## Bad vs Good Implementations ### Separating Dependent Inference Dispatches with Explicit Compute Pass Transitions #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In WebGPU, consecutive dispatch calls inside the same compute pass encoder are allowed to overlap and execute out of order on GPU hardware. If the second dispatch reads from or writes to the storage buffer written by the first dispatch, a severe Read-After-Write (RAW) data race occurs, producing non-deterministic inference corruption. ```typescript export function runInferenceStep(device: GPUDevice, encoder: GPUCommandEncoder, gemmPipeline: GPUComputePipeline, actPipeline: GPUComputePipeline, gemmBindGroup: GPUBindGroup, actBindGroup: GPUBindGroup): void { // Anti-pattern: Chaining dependent compute dispatches within a single compute pass. // WebGPU compute passes do not insert memory barriers between dispatches. const pass = encoder.beginComputePass({ label: 'fused_matmul_activation_pass' }); pass.setPipeline(gemmPipeline); pass.setBindGroup(0, gemmBindGroup); pass.dispatchWorkgroups(16, 16); // BUG: actPipeline reads intermediate tensor from gemmPipeline's output storage buffer // while gemm workgroups may still be executing, causing silent data races and corrupted logits. pass.setPipeline(actPipeline); pass.setBindGroup(0, actBindGroup); pass.dispatchWorkgroups(16, 16); pass.end(); } ``` #### Production Standard (Correct) > **Standard**: Calling `pass.end()` and opening a new compute pass forces the WebGPU driver and underlying hardware APIs (Vulkan, Metal, DirectX 12) to insert pipeline barriers and memory visibility synchronization tokens, guaranteeing that all storage buffer writes from the GEMM dispatch are fully committed before the activation dispatch begins reading. ```typescript export function runInferenceStep(device: GPUDevice, encoder: GPUCommandEncoder, gemmPipeline: GPUComputePipeline, actPipeline: GPUComputePipeline, gemmBindGroup: GPUBindGroup, actBindGroup: GPUBindGroup): void { // Invariant Fix: End the first compute pass to establish an implicit execution // and memory synchronization barrier between dependent dispatches. const gemmPass = encoder.beginComputePass({ label: 'gemm_compute_pass' }); gemmPass.setPipeline(gemmPipeline); gemmPass.setBindGroup(0, gemmBindGroup); gemmPass.dispatchWorkgroups(16, 16); gemmPass.end(); // Flushes writes and enforces GPU memory synchronization barrier // Second compute pass guarantees all prior storage buffer writes are visible const actPass = encoder.beginComputePass({ label: 'activation_compute_pass' }); actPass.setPipeline(actPipeline); actPass.setBindGroup(0, actBindGroup); actPass.dispatchWorkgroups(16, 16); actPass.end(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebGPU Compute Pipeline Memory Synchronization and Pass Transition Guardrail

WebGPU Compute Pipeline Memory Synchronization and Pass Transition Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic memory coherence across dependent compute dispatches during client-side WebGPU parallel ML inference. WebGPU does not guarantee write-after-read (WAR), read-after-write (RAW), or write-after-write (WAW) coherence between dispatches within the same compute pass. Engineers must separate dependent kernel dispatches across explicit compute pass boundaries or command encoder transitions to introduce hardware-level execution and memory barriers. 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: Consecutive Dispatches Sharing Read-Write Storage Buffers Within a Single Compute Pass 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	Consecutive Dispatches Sharing Read-Write Storage Buffers Within a Single Compute Pass	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 end the current `GPUComputePassEncoder` via `.end()` before dispatching a subsequent compute kernel that depends on memory written by the previous kernel.

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.