Svelte 5 High-Frequency Telemetry Invariant: Enforce $state.raw Immutability Boundaries

--- description: Svelte 5 High-Frequency Telemetry Invariant: Enforce $state.raw Immutability Boundaries - Mandates the usage of $state.raw for high-frequency telemetry streams, WebSockets, and sensor feeds to prevent fine-grained reactivity cascade storms and deep proxy-wrapping overhead. Enforces an immutable update paradigm where raw state is replaced via atomic reference assignment rather than in-place mutation. 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/svelte-5-runes-raw-state-telemetry-guardrail" --- # Svelte 5 High-Frequency Telemetry Invariant: Enforce $state.raw Immutability Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Deep Proxy Virtualization of Rapid Telemetry Payloads via Standard $state Triggering Reactive Micro-Storms and Heap Churn ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Raw State Immutability Boundaries. You must prevent memory exhaustion, GC churn, and micro-task scheduler saturation caused by wrapping high-throughput data streams in deep reactive proxies. Enforce $state.raw and atomic reference replacement for any stream exceeding 10Hz or involving large, nested data payloads. ## Strict Guidelines - Engineers MUST ALWAYS use $state.raw<T>() when managing data feeds that update frequently (>10 updates/sec), such as WebSockets, WebWorker messages, audio processors, canvas render loops, and metrics telemetry. - Engineers MUST NOT perform in-place property mutations on $state.raw variables; state changes MUST ALWAYS be applied via explicit, atomic root-reference reassignments. - Engineers MUST NEVER wrap deep, read-only external payloads (e.g., GeoJSON, time-series arrays, decoded protobufs) in standard $state, as recursive reactive proxy instantiation incurs unacceptable CPU and memory overhead. - Services handling high-frequency telemetry MUST batch packet bursts (using requestAnimationFrame or micro-queues) before reassigning the raw state reference to prevent UI thread lock-up. - Components consuming raw telemetry MUST derive dependent views using $derived.by only when computationally necessary, avoiding derived loops that read raw references at sub-millisecond intervals. - Engineers SHOULD freeze raw telemetry payloads using Object.freeze() in development environments to catch unauthorized deep property mutations at runtime. ## Bad vs Good Implementations ### High-Frequency WebSocket Telemetry State Management in Svelte 5 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using standard $state causes Svelte 5 to recursively proxy the incoming telemetry object and its internal collections. High-frequency updates trigger fine-grained tracking overhead, continuous proxy allocations, and micro-task scheduler starvation, severely degrading runtime frame rates. ```typescript import { onDestroy } from 'svelte'; interface MetricPayload { id: string; values: number[]; metadata: Record<string, string>; } // ANTI-PATTERN: Standard $state recursively wraps each incoming packet in reactive proxies. // At 60-120Hz, deep proxying floods the reactivity graph and causes massive GC pressure. let telemetryBuffer = $state<Record<string, MetricPayload>>({}); const ws = new WebSocket('wss://telemetry.internal/stream'); ws.onmessage = (event: MessageEvent) => { const payload: MetricPayload = JSON.parse(event.data); // Fine-grained nested mutation causes cascade micro-storms across all subscribers telemetryBuffer[payload.id] = payload; telemetryBuffer[payload.id].values.push(Date.now()); }; onDestroy(() => ws.close()); ``` #### Production Standard (Correct) > **Standard**: By using $state.raw and wrapping payloads in read-only immutable boundaries, Svelte completely bypasses proxy generation. Combining $state.raw with a requestAnimationFrame batching buffer guarantees zero proxy virtualization overhead and maintains deterministic 60fps/120fps UI rendering. ```typescript import { onDestroy } from 'svelte'; interface MetricPayload { readonly id: string; readonly values: readonly number[]; readonly metadata: Readonly<Record<string, string>>; } // PRODUCTION FIX: $state.raw eliminates proxy overhead and fine-grained dependency tracking. // State updates occur purely via immutable reference replacement. let telemetryBuffer = $state.raw<Readonly<Record<string, MetricPayload>>>({}); let pendingBatch: Record<string, MetricPayload> = {}; let rafHandle: number | null = null; function flushBatch(): void { telemetryBuffer = Object.freeze({ ...telemetryBuffer, ...pendingBatch }); pendingBatch = {}; rafHandle = null; } const ws = new WebSocket('wss://telemetry.internal/stream'); ws.onmessage = (event: MessageEvent) => { const payload: MetricPayload = JSON.parse(event.data); pendingBatch[payload.id] = payload; // Coalesce high-frequency events into display frame boundaries if (rafHandle === null) { rafHandle = requestAnimationFrame(flushBatch); } }; onDestroy(() => { ws.close(); if (rafHandle !== null) { cancelAnimationFrame(rafHandle); } }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 High-Frequency Telemetry Invariant: Enforce $state.raw Immutability Boundaries

Svelte 5 High-Frequency Telemetry Invariant: Enforce $state.raw Immutability Boundaries defines an industrial-grade behavioral standard for frontend engineering. Mandates the usage of $state.raw for high-frequency telemetry streams, WebSockets, and sensor feeds to prevent fine-grained reactivity cascade storms and deep proxy-wrapping overhead. Enforces an immutable update paradigm where raw state is replaced via atomic reference assignment rather than in-place 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: Deep Proxy Virtualization of Rapid Telemetry Payloads via Standard $state Triggering Reactive Micro-Storms and Heap Churn 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	Deep Proxy Virtualization of Rapid Telemetry Payloads via Standard $state Triggering Reactive Micro-Storms and Heap Churn	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 use $state.raw<T>() when managing data feeds that update frequently (>10 updates/sec), such as WebSockets, WebWorker messages, audio processors, canvas render loops, and metrics telemetry.

Engineers MUST ALWAYS use $state.raw<T>() when managing data feeds that update frequently (>10 updates/sec), such as WebSockets, WebWorker messages, audio processors, canvas render loops, and metrics telemetry.

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.