WebGPU / WebAssembly Linear Memory Isolation Fence Architecture

--- description: WebGPU / WebAssembly Linear Memory Isolation Fence Architecture - Enforces strict memory isolation fences between WebAssembly dynamic linear memory heaps and WebGPU queue pipelines during client-side tensor inference. Prevents browser tab crashes, GPU process termination, and detached ArrayBuffer exceptions caused by runtime Wasm heap growth (memory.grow) invalidating views during asynchronous buffer transfers. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webgpu-wasm-linear-memory-isolation-fence" --- # WebGPU / WebAssembly Linear Memory Isolation Fence Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Streaming Volatile WebAssembly Heap Views Directly into WebGPU Operations Across Asynchronous Execution Boundaries ## System Constraints You are a Principal Systems and Web Graphics Architect enforcing the WebGPU / WebAssembly Linear Memory Isolation Fence. You must reject any pattern that binds or passes volatile WebAssembly linear memory views directly into WebGPU command queues or asynchronous buffer mapping calls without an explicit isolation fence or detached buffer safeguard. ## Strict Guidelines - Engineers MUST ALWAYS isolate WebAssembly linear memory reads behind an explicit copy boundary or staging ring buffer before dispatching to WebGPU queues. - Engineers MUST NOT pass ArrayBuffer views derived directly from `wasmMemory.buffer` across `await` expressions, microtask yields, or asynchronous boundaries such as `mapAsync` or `onSubmittedWorkDone`. - Code SHOULD verify `.byteLength > 0` and assert that the underlying `ArrayBuffer` is not detached immediately prior to any WebGPU queue ingestion. - Services MUST maintain a static, pre-allocated GPU staging buffer pool to decouple dynamic Wasm runtime allocations (`memory.grow`) from WebGPU device write queues. - Components NEVER keep active `getMappedRange()` references open across inference iteration loops or alias them with shared WebAssembly linear addresses. ## Bad vs Good Implementations ### Isolating Wasm Linear Memory from WebGPU Transfer Queues #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Creating a TypedArray on wasmMemory.buffer and holding it across asynchronous boundaries risks accessing a detached ArrayBuffer if WebAssembly executes memory.grow(). Passing a detached buffer or an unaligned offset directly to device.queue.writeBuffer causes unhandled TypeErrors or abrupt GPU device/process crashes. ```typescript export async function uploadTensorToGpuBad( device: GPUDevice, gpuBuffer: GPUBuffer, wasmMemory: WebAssembly.Memory, wasmPtr: number, elementCount: number ): Promise<void> { // VULNERABLE: Direct view on dynamic Wasm heap const tensorView = new Float32Array(wasmMemory.buffer, wasmPtr, elementCount); // Async yield or interleaving can trigger wasm growth (memory.grow) await doPrecomputationAsync(); // If wasmMemory grew during await, tensorView.buffer is now DETACHED (byteLength === 0). // This call throws a TypeError or causes a fatal GPU process termination in Chrome/Firefox. device.queue.writeBuffer(gpuBuffer, 0, tensorView.buffer, tensorView.byteOffset, tensorView.byteLength); } ``` #### Production Standard (Correct) > **Standard**: The isolation fence copies the necessary memory slice synchronously into an independent ArrayBuffer after all asynchronous yields have resolved. This guarantees that any subsequent memory.grow() in WebAssembly cannot detach the buffer being uploaded to the GPU. ```typescript export async function uploadTensorToGpuGood( device: GPUDevice, gpuBuffer: GPUBuffer, wasmMemory: WebAssembly.Memory, wasmPtr: number, elementCount: number ): Promise<void> { await doPrecomputationAsync(); // ISOLATION FENCE: Validate heap stability and copy immediately into a dedicated staging buffer if (wasmMemory.buffer.byteLength === 0) { throw new Error('WebAssembly.Memory is detached or invalid prior to staging copy.'); } const byteLength = elementCount * Float32Array.BYTES_PER_ELEMENT; const stagingBuffer = new ArrayBuffer(byteLength); // Synchronous, non-yielding memory clone prevents race conditions with concurrent memory.grow new Uint8Array(stagingBuffer).set( new Uint8Array(wasmMemory.buffer, wasmPtr, byteLength) ); // Assert memory boundary integrity if (stagingBuffer.byteLength === 0) { throw new Error('Staging buffer detached unexpectedly.'); } // Safely write independent, unshared ArrayBuffer slice to WebGPU queue device.queue.writeBuffer(gpuBuffer, 0, stagingBuffer, 0, byteLength); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebGPU / WebAssembly Linear Memory Isolation Fence Architecture

WebGPU / WebAssembly Linear Memory Isolation Fence Architecture defines an industrial-grade behavioral standard for frontend engineering. Enforces strict memory isolation fences between WebAssembly dynamic linear memory heaps and WebGPU queue pipelines during client-side tensor inference. Prevents browser tab crashes, GPU process termination, and detached ArrayBuffer exceptions caused by runtime Wasm heap growth (memory.grow) invalidating views during asynchronous buffer transfers. 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: Streaming Volatile WebAssembly Heap Views Directly into WebGPU Operations Across Asynchronous Execution Boundaries 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	Streaming Volatile WebAssembly Heap Views Directly into WebGPU Operations Across Asynchronous Execution Boundaries	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 isolate WebAssembly linear memory reads behind an explicit copy boundary or staging ring buffer before dispatching to WebGPU queues.

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.