Svelte 5 Deep Reactive Proxy Fencing ($state.raw) for High-Frequency Telemetry

--- description: Svelte 5 Deep Reactive Proxy Fencing ($state.raw) for High-Frequency Telemetry - Prevents catastrophic reactive proxy instantiation and garbage collection thrashing in Svelte 5 applications processing high-frequency data streams. Mandates the use of $state.raw for streaming telemetry, time-series arrays, and binary buffers to bypass recursive proxy wrapping. Enforces atomic reference reassignments rather than in-place deep property mutations. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte5-deep-reactive-proxy-fencing-state-raw" --- # Svelte 5 Deep Reactive Proxy Fencing ($state.raw) for High-Frequency Telemetry > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Deep Proxy Wrapping of Ingested High-Frequency Stream Payloads via Standard $state() ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Deep Reactive Proxy Fencing ($state.raw). In Svelte 5, $state recursively wraps objects, arrays, and maps into reactive Proxies. Under high-frequency data ingestion (e.g., WebSockets, Web Workers, Canvas/WebGL feeds, 60Hz+ telemetry), deep proxying induces excessive CPU cycles, heap fragmentation, and GC spikes. You must enforce $state.raw boundaries on all high-throughput, immutable, or externally managed data structures, requiring atomic reference updates over internal mutations. ## Strict Guidelines - Engineers MUST ALWAYS declare streaming feeds, time-series arrays, Canvas/WebGL buffers, and bulk collections using '$state.raw()' instead of standard '$state()'. - Engineers MUST NOT mutate nested properties or invoke mutating array methods (push, splice, sort) on references declared with '$state.raw()', as raw state does not track internal mutations. - Code MUST apply state updates to '$state.raw()' targets strictly via atomic reference reassignment (e.g., 'data = Object.freeze(nextData)' or immutable slice/concat batches). - Services handling high-frequency transports (e.g., WebSocket, SSE, WebRTC DataChannels) MUST buffer inbound payloads off-thread or in plain variables before applying debounced/batched updates to a '$state.raw()' rune. - Components NEVER use standard '$state()' for large third-party class instances, ASTs, or immutable API payloads containing deeply nested trees. ## Bad vs Good Implementations ### High-Frequency WebSocket Telemetry Ingestion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $state() for high-frequency telemetry forces Svelte to recursively wrap every incoming MetricPayload and its nested structures into reactive Proxies. At 60-120Hz, this generates tens of thousands of transient proxy objects, leading to major garbage collection pauses and dropped frames. ```typescript import { onMount } from 'svelte'; interface MetricPayload { id: string; timestamp: number; values: number[]; metadata: Record<string, string>; } // ANTI-PATTERN: Standard $state deeply proxies every incoming packet, // creating thousands of Proxy allocations per second and inducing GC spikes. let telemetryStream = $state<MetricPayload[]>([]); onMount(() => { const socket = new WebSocket('wss://telemetry.internal/stream'); socket.onmessage = (event) => { const payload: MetricPayload = JSON.parse(event.data); // Mutating array in-place triggers deep reactivity traversal telemetryStream.push(payload); if (telemetryStream.length > 10000) { telemetryStream.shift(); } }; return () => socket.close(); }); ``` #### Production Standard (Correct) > **Standard**: By using $state.raw(), Svelte avoids Proxy wrapping on incoming payloads. Batching updates via requestAnimationFrame and reassigning the reference atomically limits reactivity triggers to once per render frame, eliminating GC pauses. ```typescript import { onMount } from 'svelte'; interface MetricPayload { readonly id: string; readonly timestamp: number; readonly values: readonly number[]; readonly metadata: Readonly<Record<string, string>>; } const MAX_BUFFER = 10000; // INVARIANT: $state.raw avoids deep proxy overhead entirely. let telemetryStream = $state.raw<readonly MetricPayload[]>([]); onMount(() => { const socket = new WebSocket('wss://telemetry.internal/stream'); let pendingBatch: MetricPayload[] = []; let rafId: number; const flush = () => { if (pendingBatch.length > 0) { const merged = telemetryStream.concat(pendingBatch); // Atomic reassignment satisfies $state.raw reactivity without proxies telemetryStream = merged.length > MAX_BUFFER ? merged.slice(merged.length - MAX_BUFFER) : merged; pendingBatch = []; } rafId = requestAnimationFrame(flush); }; rafId = requestAnimationFrame(flush); socket.onmessage = (event) => { pendingBatch.push(JSON.parse(event.data)); }; return () => { cancelAnimationFrame(rafId); socket.close(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Deep Reactive Proxy Fencing ($state.raw) for High-Frequency Telemetry

Svelte 5 Deep Reactive Proxy Fencing ($state.raw) for High-Frequency Telemetry defines an industrial-grade behavioral standard for frontend engineering. Prevents catastrophic reactive proxy instantiation and garbage collection thrashing in Svelte 5 applications processing high-frequency data streams. Mandates the use of $state.raw for streaming telemetry, time-series arrays, and binary buffers to bypass recursive proxy wrapping. Enforces atomic reference reassignments rather than in-place deep property mutations. 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 Deep Proxy Wrapping of Ingested High-Frequency Stream Payloads via Standard $state() 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 Deep Proxy Wrapping of Ingested High-Frequency Stream Payloads via Standard $state()	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 declare streaming feeds, time-series arrays, Canvas/WebGL buffers, and bulk collections using '$state.raw()' instead of standard '$state()'.

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.