Svelte 5 Runes Reactive Graph Snapshot Immutability Invariant

--- description: Svelte 5 Runes Reactive Graph Snapshot Immutability Invariant - Enforces strict immutable boundaries and snapshot stabilization on complex nested signal derivations in Svelte 5 runes. Prevents reactive graph thrashing, unintended cascading re-evaluations, and memory retention leaks caused by leaking mutable proxy references or mutating internal state within derived computations. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactive-graph-snapshot-immutability" --- # Svelte 5 Runes Reactive Graph Snapshot Immutability Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating internal reactive proxies or returning un-snapshotted nested objects inside $derived runes ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Reactive Graph Snapshot Immutability Invariants. You must ensure that all reactive computations ($derived, $derived.by) remain pure, free of internal state mutation, and decoupled from deeply nested mutable proxy graphs when exposing snapshots to subscriber boundaries or concurrent rendering flows. ## Strict Guidelines - Engineers MUST ALWAYS treat $derived and $derived.by calculations as pure functions with zero mutations to upstream or local $state proxies. - Engineers MUST use $state.snapshot() when projecting complex nested reactive structures across component or asynchronous boundaries to sever reactive tracking and avoid retained subscriber memory leaks. - Engineers MUST NOT mutate properties on objects or arrays returned by $derived or $derived.by; derived outputs MUST be structurally immutable. - Code SHOULD return frozen or structurally memoized references (e.g., via Object.freeze()) from complex $derived.by computations to trigger compile-time/runtime guards against illegal state modifications. - Components NEVER execute side-effects or update independent $state variables inside a $derived.by expression to synchronize state; use isolated $effect runes with explicit dependencies instead. ## Bad vs Good Implementations ### Nested signal transformation with immutable snapshot vs direct proxy mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating n.values using Array.prototype.sort modifies the underlying $state reactive proxy inside a derivation. This triggers dirty-checking cycles, invalidates active subscribers, and risks infinite reactive cascade loops. ```typescript import { $state, $derived } from 'svelte'; interface NodeItem { id: string; values: number[]; } let nodes = $state<NodeItem[]>([ { id: '1', values: [1, 2, 3] } ]); // ANTI-PATTERN: In-place sorting mutates the reactive proxy during derivation, // causing re-entrant dependency invalidations and infinite evaluation loops. let sortedSnapshot = $derived.by(() => { return nodes.map(n => { return n.values.sort((a, b) => b - a); // Mutates proxy inside derivation graph! }); }); ``` #### Production Standard (Correct) > **Standard**: Utilizes $state.snapshot to break the reactive tracking tree and returns deeply frozen object references. This ensures pure derivations, prevents proxy mutation leaks, and protects downstream consumers from triggering unwanted cascades. ```typescript import { $state, $derived } from 'svelte'; interface NodeItem { id: string; values: number[]; } let nodes = $state<NodeItem[]>([ { id: '1', values: [1, 2, 3] } ]); // PRODUCTION FIX: Snapshot extraction and immutable boundary enforcement let sortedSnapshot = $derived.by(() => { // Sever reactive proxy references for stable snapshotting const rawNodes = $state.snapshot(nodes); return Object.freeze( rawNodes.map(n => Object.freeze({ id: n.id, values: Object.freeze([...n.values].sort((a, b) => b - a)) })) ); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Graph Snapshot Immutability Invariant

Svelte 5 Runes Reactive Graph Snapshot Immutability Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict immutable boundaries and snapshot stabilization on complex nested signal derivations in Svelte 5 runes. Prevents reactive graph thrashing, unintended cascading re-evaluations, and memory retention leaks caused by leaking mutable proxy references or mutating internal state within derived computations. 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: Mutating internal reactive proxies or returning un-snapshotted nested objects inside $derived runes 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	Mutating internal reactive proxies or returning un-snapshotted nested objects inside $derived runes	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 treat $derived and $derived.by calculations as pure functions with zero mutations to upstream or local $state proxies.

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.