Svelte 5 Runes $state.raw Mutation Isolation Guardrail

--- description: Svelte 5 Runes $state.raw Mutation Isolation Guardrail - Mandates explicit shallow reactivity using `$state.raw` for high-frequency or large-scale streaming datasets to eliminate runaway deep-proxy memory overhead. Enforces complete reference re-assignment when emitting state changes and strictly forbids in-place deep mutations on raw runes. Isolates UI render cycles from high-throughput payload ingestion to guarantee sub-16ms frame budgets in real-time dashboards. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-state-raw-mutation-isolation-guardrail" --- # Svelte 5 Runes $state.raw Mutation Isolation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Deep Reactive Proxy Poisoning via Deep $state Wrappers on High-Frequency Ingestion Streams ## System Constraints You are a Principal Frontend Architect enforcing the Svelte 5 Runes `$state.raw` Mutation Isolation Guardrail. Deep reactivity via `$state()` wraps entire object graphs in dynamic JavaScript Proxies, causing catastrophic GC pressure, unbounded memory leaks, and microtask churn when processing high-frequency streaming data (e.g., WebSockets, SSE, telemetry). You must mandate `$state.raw()` for all streaming buffers, immutable replacement semantics for data updates, and surgical isolation between data processing buffers and reactive presentation state. ## Strict Guidelines - Engineers MUST ALWAYS use `$state.raw<T[]>()` or `$state.raw<Record<string, T>>()` for collections updated at high frequencies (>10Hz) or containing large object graphs (>1,000 nodes). - Engineers MUST NOT invoke mutating collection methods (`.push()`, `.splice()`, `.sort()`, or key mutations) directly on `$state.raw` bindings, as Svelte 5 will not detect internal mutations without reference changes. - Code SHOULD buffer inbound socket/telemetry updates outside the reactive graph and project updates into `$state.raw` references using batch throttling (e.g., `requestAnimationFrame` or fixed interval slicing). - Services MUST produce fresh root references (e.g., `ticks = [...newTicks]`, `buffer = Object.freeze(nextState)`) when updating `$state.raw` to deterministically trigger downstream `$derived` and template invalidations. - Components NEVER store raw high-frequency transport payloads inside standard `$state()` containers. ## Bad vs Good Implementations ### High-Frequency WebSocket Ingestion in Svelte 5 Store/Module #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using standard `$state` recursively wraps incoming telemetry events in reactive proxies. At 60+ Hz, this leads to excessive GC pressure, microtask queue saturation, and runaway memory leaks as the proxy graph grows. ```typescript // Anti-pattern: Deep proxying thousands of updates per second leads to catastrophic memory retention export class TelemetryFeed { // Bad: Deep proxy allocated across millions of nested payload nodes data = $state<Array<{ id: string; metric: number; timestamp: number }>>([]); constructor(socket: WebSocket) { socket.onmessage = (event) => { const payload = JSON.parse(event.data); // Bad: In-place mutation with deep proxy tracking forces recursive proxy traversals this.data.push(payload); if (this.data.length > 5000) { this.data.shift(); } }; } } ``` #### Production Standard (Correct) > **Standard**: Declaring `$state.raw` avoids deep-proxy wrapping of objects. Staging incoming messages in an unmonitored local queue and flushing them once per animation frame via reference reassignment guarantees deterministic garbage collection and fluid rendering. ```typescript // Production Standard: Shallow reactivity with immutable batch replacement export class TelemetryFeed { // Invariant: Enforce raw, non-proxied container data = $state.raw<readonly { id: string; metric: number; timestamp: number }[]>([]); private queue: { id: string; metric: number; timestamp: number }[] = []; private rafId: number | null = null; constructor(socket: WebSocket) { socket.onmessage = (event) => { this.queue.push(JSON.parse(event.data)); this.scheduleFlush(); }; } private scheduleFlush(): void { if (this.rafId !== null) return; this.rafId = requestAnimationFrame(() => { this.flush(); this.rafId = null; }); } private flush(): void { if (this.queue.length === 0) return; const merged = [...this.data, ...this.queue].slice(-5000); this.queue = []; // Invariant: Structural re-assignment ensures zero proxy overhead and triggers shallow invalidation this.data = Object.freeze(merged); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes $state.raw Mutation Isolation Guardrail

Svelte 5 Runes $state.raw Mutation Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Mandates explicit shallow reactivity using `$state.raw` for high-frequency or large-scale streaming datasets to eliminate runaway deep-proxy memory overhead. Enforces complete reference re-assignment when emitting state changes and strictly forbids in-place deep mutations on raw runes. Isolates UI render cycles from high-throughput payload ingestion to guarantee sub-16ms frame budgets in real-time dashboards. 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 Reactive Proxy Poisoning via Deep $state Wrappers on High-Frequency Ingestion Streams 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 Reactive Proxy Poisoning via Deep $state Wrappers on High-Frequency Ingestion Streams	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[]>()` or `$state.raw<Record<string, T>>()` for collections updated at high frequencies (>10Hz) or containing large object graphs (>1,000 nodes).

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.