Web Streams Backpressure Cooperative Drain Invariant

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded Async Enqueueing and Decoupled Stream Pumps Overwhelming Browser Tab Heap) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Web Streams Backpressure Cooperative Drain Invariant

--- description: Web Streams Backpressure Cooperative Drain Invariant - Enforces strict backpressure propagation and zero-overflow cooperative drain across client-side Web Streams processing high-throughput telemetry, binary blobs, and large artifacts. Prohibits decoupled asynchronous chunk queuing and unthrottled producer reads to prevent V8/Chromium renderer heap exhaustion and browser tab termination. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/web-streams-backpressure-cooperative-drain-invariant" --- # Web Streams Backpressure Cooperative Drain Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Async Enqueueing and Decoupled Stream Pumps Overwhelming Browser Tab Heap ## System Constraints You are a Principal Software Architect enforcing the Web Streams Backpressure Cooperative Drain Invariant. You must reject any stream processing code that detaches async processing from chunk transformation, fails to return promises in TransformStream lifecycle hooks, or ignores downstream highWaterMark constraints and controller.desiredSize signals. ## Strict Guidelines - Engineers MUST ALWAYS return a Promise from `TransformStream.prototype.transform` and `flush` hooks whenever downstream work or chunk transformation is asynchronous. - Engineers MUST NOT spawn detached or fire-and-forget Promises (`void asyncFn()`, un-awaited `.then()`) inside stream hooks that asynchronously invoke `controller.enqueue()`. - Engineers MUST observe `controller.desiredSize` in custom `ReadableStream` underlying sources and immediately cease pulling chunks when `desiredSize <= 0`. - Code driving manual `ReadableStreamDefaultReader` to `WritableStreamDefaultWriter` transfer loops MUST `await writer.ready` before every `writer.write()` and await `writer.write()` resolution. - Services adapting event-driven or unthrottled data sources (e.g., WebSockets, EventSource, IndexedDB Cursors) into streams MUST implement explicit pause/resume mechanics keyed to queue saturation. - Components NEVER buffer multiple incoming chunks in JavaScript heap arrays when piping data; native pipeline chaining via `.pipeThrough()` and `.pipeTo()` MUST be used to preserve cooperative pull signals. ## Bad vs Good Implementations ### Asynchronous Telemetry TransformStream Invariant Fix #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The transform method spawns a detached asynchronous task (`void parsePacketAsync(...)`) and immediately returns undefined synchronously. The upstream source assumes the chunk has been processed and floods the controller, bypassing `highWaterMark` and causing unbounded heap growth. ```typescript import { TransformStream } from 'node:stream/web'; interface TelemetryPacket { id: string; payload: Uint8Array; } export function createTelemetryParserStream(): TransformStream<Uint8Array, TelemetryPacket> { return new TransformStream({ transform(chunk, controller) { // CRITICAL VIOLATION: Detached async execution ignores stream backpressure. // Producer continues pushing high-frequency chunks while async tasks accumulate, // leading to catastrophic V8 heap exhaustion and tab termination. void parsePacketAsync(chunk).then((packet) => { if (packet) { controller.enqueue(packet); } }); } }); } async function parsePacketAsync(raw: Uint8Array): Promise<TelemetryPacket | null> { return { id: 'pkt-01', payload: raw }; } ``` #### Production Standard (Correct) > **Standard**: Declaring `transform` as `async` ensures that the stream infrastructure awaits chunk processing before requesting the next chunk from the upstream source, respecting the `CountQueuingStrategy` and `ByteLengthQueuingStrategy` invariants. ```typescript interface TelemetryPacket { id: string; payload: Uint8Array; } export function createTelemetryParserStream( highWaterMark = 32 ): TransformStream<Uint8Array, TelemetryPacket> { return new TransformStream<Uint8Array, TelemetryPacket>( { // INVARIANT: Returning the promise forces the upstream pipe to yield // until the async transformation is complete and backpressure is evaluated. async transform(chunk, controller) { const packet = await parsePacketAsync(chunk); if (packet) { controller.enqueue(packet); } } }, // Explicit queuing strategies enforce deterministic backpressure thresholds new ByteLengthQueuingStrategy({ highWaterMark: highWaterMark * 1024 }), new CountQueuingStrategy({ highWaterMark }) ); } async function parsePacketAsync(raw: Uint8Array): Promise<TelemetryPacket | null> { return { id: 'pkt-01', payload: raw }; } ``` ### WebSocket Ingestion Backpressure Pump Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The WebSocket `onmessage` handler indiscriminately pushes binary data into the writable stream without evaluating `writer.ready` or flow control, completely breaking backpressure signaling and exhausting memory if consumption slows. ```typescript export function ingestSocketToStream(socket: WebSocket, writer: WritableStreamDefaultWriter<Uint8Array>): void { // CRITICAL VIOLATION: WebSocket message arrivals are fire-and-forget. // Writing without checking writer.ready or awaiting writer.write causes // unbuffered queue growth in the stream internal sink. socket.onmessage = (event: MessageEvent<ArrayBuffer>) => { const data = new Uint8Array(event.data); writer.write(data); }; } ``` #### Production Standard (Correct) > **Standard**: Implements cooperative flow control by awaiting `writer.ready` and `writer.write` before continuing the drain loop, paired with an ingestion threshold to maintain bounded memory consumption. ```typescript export function ingestSocketToStream( socket: WebSocket, writer: WritableStreamDefaultWriter<Uint8Array> ): () => void { let isPaused = false; const messageQueue: Uint8Array[] = []; let isPumping = false; async function pump(): Promise<void> { if (isPumping) return; isPumping = true; try { while (messageQueue.length > 0) { // INVARIANT: Await writer readiness to respect downstream backpressure await writer.ready; const chunk = messageQueue.shift(); if (chunk) { await writer.write(chunk); } if (isPaused && messageQueue.length < 10) { isPaused = false; // Cooperative resume if protocol supports flow control (e.g., custom frame or binary transport) } } } finally { isPumping = false; } } const handleMessage = (event: MessageEvent<ArrayBuffer>): void => { messageQueue.push(new Uint8Array(event.data)); if (messageQueue.length >= 50 && !isPaused) { isPaused = true; // Signal producer to pause (application-level throttle) } void pump(); }; socket.addEventListener('message', handleMessage); return () => socket.removeEventListener('message', handleMessage); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Web Streams Backpressure Cooperative Drain Invariant

Web Streams Backpressure Cooperative Drain Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict backpressure propagation and zero-overflow cooperative drain across client-side Web Streams processing high-throughput telemetry, binary blobs, and large artifacts. Prohibits decoupled asynchronous chunk queuing and unthrottled producer reads to prevent V8/Chromium renderer heap exhaustion and browser tab termination. 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: Unbounded Async Enqueueing and Decoupled Stream Pumps Overwhelming Browser Tab Heap 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	Unbounded Async Enqueueing and Decoupled Stream Pumps Overwhelming Browser Tab Heap	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 return a Promise from `TransformStream.prototype.transform` and `flush` hooks whenever downstream work or chunk transformation is asynchronous.

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.