Svelte 5 Runes Raw State Boundary Standard for High-Frequency Telemetry

--- description: Svelte 5 Runes Raw State Boundary Standard for High-Frequency Telemetry - Enforces the mandatory application of $state.raw over deep $state proxies for high-frequency telemetry streams, WebSockets, and real-time dashboard data feeds in Svelte 5. Deep proxy wrapping on sub-second data ingress causes catastrophic garbage collection churn and UI frame drops. High-frequency state must treat payload objects as immutable structures updated via atomic reference reassignment. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/stores/**/*.ts, src/**/telemetry/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-raw-state-boundary-standard" --- # Svelte 5 Runes Raw State Boundary Standard for High-Frequency Telemetry > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Wrapping High-Frequency Ingress Payloads in Recursive Deep-Reactive $state Proxies ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes performance boundaries. You strictly forbid wrapping high-throughput, nested, or streaming data structures (such as WebSocket feeds, WebWorker transfers, canvas buffers, or financial ticker arrays) in standard recursive $state() runes. You mandate $state.raw() coupled with immutable reference reassignments to guarantee zero proxy allocation overhead and eliminate client-side garbage collection bottlenecks. ## Strict Guidelines - Engineers MUST ALWAYS declare telemetry arrays, chart data feeds, and streaming WebSocket payloads using `$state.raw<T>(initialValue)`. - Engineers MUST NOT use `$state()` for any real-time data structures updated at frequencies greater than 10Hz or holding batches exceeding 100 nested objects. - Engineers MUST trigger reactivity on `$state.raw` variables strictly through atomic root reassignment (e.g., `buffer = [...buffer.slice(-MAX), packet]`), never via internal property mutations. - Components NEVER deep-bind (`bind:value`) directly to properties within high-frequency raw state; read-only access or derived projections must be passed down. - Services handling high-frequency packet ingestion SHOULD sanitize or transform data off-thread (e.g., via Web Worker) and present an already finalized immutable payload to the `$state.raw` binding. ## Bad vs Good Implementations ### High-Frequency Telemetry Stream Management #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using standard `$state` on a streaming array causes Svelte 5 to recursively wrap every incoming `MetricPoint` and its inner `values` object with `Proxy` instances. At high frequencies, this creates thousands of transient proxy allocations per second, degrading UI frame rates and causing severe garbage collection pressure. ```typescript // TelemetryFeed.svelte.ts export interface MetricPoint { timestamp: number; source: string; values: { cpu: number; memory: number; io: number }; } export class TelemetryService { // ANTI-PATTERN: Standard $state recursively wraps every nested object and array item in a Proxy. // At 60Hz across thousands of items, this triggers massive GC pauses and CPU overhead. metrics = $state<MetricPoint[]>([]); constructor(socket: WebSocket) { socket.onmessage = (event) => { const packet: MetricPoint = JSON.parse(event.data); // In-place mutation of proxied array forces re-evaluation of reactive graph nodes this.metrics.push(packet); if (this.metrics.length > 500) { this.metrics.shift(); } }; } } ``` #### Production Standard (Correct) > **Standard**: Declaring `metrics` with `$state.raw` completely disables recursive proxying. Telemetry packets are retained as raw JavaScript objects, avoiding object wrapper allocations. Reassigning `this.metrics` ensures efficient, coarse-grained reactivity that updates downstream consumers without GC degradation. ```typescript // TelemetryFeed.svelte.ts export interface MetricPoint { readonly timestamp: number; readonly source: string; readonly values: { readonly cpu: number; readonly memory: number; readonly io: number }; } export class TelemetryService { private static readonly MAX_BUFFER_SIZE = 500; // PRODUCTION FIX: $state.raw creates a shallow reactive boundary with zero proxy allocation overhead. metrics = $state.raw<readonly MetricPoint[]>([]); constructor(socket: WebSocket) { socket.onmessage = (event) => { const packet: MetricPoint = JSON.parse(event.data); // Atomic reassignment triggers reactivity without mutating inner objects const current = this.metrics; const nextStart = current.length >= TelemetryService.MAX_BUFFER_SIZE ? 1 : 0; this.metrics = [...current.slice(nextStart), Object.freeze(packet)]; }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Raw State Boundary Standard for High-Frequency Telemetry

Svelte 5 Runes Raw State Boundary Standard for High-Frequency Telemetry defines an industrial-grade behavioral standard for frontend engineering. Enforces the mandatory application of $state.raw over deep $state proxies for high-frequency telemetry streams, WebSockets, and real-time dashboard data feeds in Svelte 5. Deep proxy wrapping on sub-second data ingress causes catastrophic garbage collection churn and UI frame drops. High-frequency state must treat payload objects as immutable structures updated via atomic reference reassignment. 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 Ingress Payloads in Recursive Deep-Reactive $state Proxies 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 Ingress Payloads in Recursive Deep-Reactive $state Proxies	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 telemetry arrays, chart data feeds, and streaming WebSocket payloads using `$state.raw<T>(initialValue)`.

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.