Svelte 5 Runes Reactive Isolation & High-Frequency State Invariant

--- description: Svelte 5 Runes Reactive Isolation & High-Frequency State Invariant - Enforces deterministic boundaries between fine-grained reactive state ($state) and high-frequency or deeply nested external datasets ($state.raw). Prevents infinite cross-component render loops, memory exhaustion from recursive Proxy wrapping, and cascading downstream recalculations. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactive-isolation-standard" --- # Svelte 5 Runes Reactive Isolation & High-Frequency State Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Wrapping High-Frequency Telemetry in Deep $state Proxies with Bidirectional Effect Feedback ## System Constraints You are a Principal Engineer enforcing the Svelte 5 Runes Reactive Isolation Standard. Svelte 5 replaces stores with explicit compiler runes ($state, $state.raw, $derived, $effect). Deep reactive proxies created by $state introduce unacceptable GC overhead and circular trigger hazards when exposed to high-frequency streaming (e.g., WebSockets, Canvas/WebGL loops, telemetry). You must enforce $state.raw for high-frequency or external payloads, strict reference-replacement semantics, and non-reactive reads via untrack() to prevent infinite cascade loops. ## Strict Guidelines - Engineers MUST ALWAYS use $state.raw() instead of $state() for high-frequency streaming payloads (e.g., WebSockets, sensors, WebRTC, animation frames) to prevent recursive Proxy wrapping. - Engineers MUST NEVER mutate nested properties of a $state.raw() object; updates MUST be applied via atomic reference reassignment (e.g., state = Object.freeze({ ...state, update })). - Engineers MUST ALWAYS isolate cyclical reads within $effect or $effect.pre using untrack() when synchronizing local state with upstream rune-based properties. - Code SHOULD prefer $derived.by() for expensive transformations, isolating volatile reference updates from invariant sub-branches of the component tree. - Services MUST NEVER expose deeply mutable $state instances directly to consuming components; wrap mutations in explicit command methods or emit immutable snapshots via $state.raw. - Components NEVER bind two-way ($bindable) to non-primitive leaves of deep $state structures across architectural boundaries. ## Bad vs Good Implementations ### High-Frequency Stream Synchronization: Deep $state vs. $state.raw with untrack #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $state on high-frequency stream targets creates a deep tree of reactive Proxies. Mutating nested arrays pushes change notifications through all proxy levels on every tick. Inside $effect, mutating tracked dependencies causes an immediate infinite re-render loop. ```typescript import { $state, $effect } from 'svelte'; // ANTI-PATTERN: Wrapping 60Hz telemetry in deep reactive proxy // and mutating in an unshielded effect loop interface Telemetry { id: string; metrics: { cpu: number[]; memory: number } } export class TelemetryBridge { // Anti-pattern: Deep proxy created on complex, rapidly changing object data = $state<Telemetry>({ id: 'node-1', metrics: { cpu: [], memory: 0 } }); constructor(socket: WebSocket) { socket.onmessage = (event) => { const payload = JSON.parse(event.data); // Anti-pattern: In-place mutation triggers recursive proxy traps on every frame this.data.metrics.cpu.push(payload.cpu); this.data.metrics.memory = payload.memory; }; } } export function syncTelemetry(bridge: TelemetryBridge, onThreshold: (val: number) => void) { $effect(() => { // Anti-pattern: Reading deep properties creates an implicit dependency // Mutating bridge data here creates an immediate circular cascade if (bridge.data.metrics.memory > 90) { onThreshold(bridge.data.metrics.memory); bridge.data.id = 'warning-' + bridge.data.id; // Triggers infinite effect cycle } }); } ``` #### Production Standard (Correct) > **Standard**: $state.raw creates a zero-proxy-overhead shallow reactive signal. High-frequency payloads are updated via full object reference replacement. Reading the snapshot inside $effect and isolating operational callbacks via untrack() avoids infinite cyclical reactive invalidations. ```typescript import { untrack } from 'svelte'; interface Telemetry { readonly id: string; readonly metrics: { readonly cpu: readonly number[]; readonly memory: number } } export class TelemetryBridge { // Invariant: Use $state.raw for high-frequency or reference-swapped state data = $state.raw<Telemetry>({ id: 'node-1', metrics: { cpu: [], memory: 0 } }); constructor(socket: WebSocket) { socket.onmessage = (event) => { const payload = JSON.parse(event.data); // Invariant: Atomic immutable replacement; bypasses proxy traversal this.data = { id: this.data.id, metrics: { cpu: [...this.data.metrics.cpu.slice(-50), payload.cpu], memory: payload.memory } }; }; } } export function syncTelemetry(bridge: TelemetryBridge, onThreshold: (val: number) => void) { $effect(() => { // Invariant: Read only what determines reactivity const current = bridge.data; // Invariant: Isolate side-effects and subsequent reads using untrack() untrack(() => { if (current.metrics.memory > 90) { onThreshold(current.metrics.memory); } }); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Isolation & High-Frequency State Invariant

Svelte 5 Runes Reactive Isolation & High-Frequency State Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic boundaries between fine-grained reactive state ($state) and high-frequency or deeply nested external datasets ($state.raw). Prevents infinite cross-component render loops, memory exhaustion from recursive Proxy wrapping, and cascading downstream recalculations. 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: Wrapping High-Frequency Telemetry in Deep $state Proxies with Bidirectional Effect Feedback 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	Wrapping High-Frequency Telemetry in Deep $state Proxies with Bidirectional Effect Feedback	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() instead of $state() for high-frequency streaming payloads (e.g., WebSockets, sensors, WebRTC, animation frames) to prevent recursive Proxy wrapping.

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.