Svelte 5 Runes Signal Graph Cycle and Deep State Mutation Guardrail

--- description: Svelte 5 Runes Signal Graph Cycle and Deep State Mutation Guardrail - Enforces strict signal purity and cycle-free reactive graphs across Svelte 5 enterprise applications. Prohibits state mutation side effects inside $derived expressions, eliminates recursive reactive loops within $effect blocks, and mandates explicit state boundary encapsulation for complex nested telemetry and dashboard models. 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-signal-graph-cycle-guardrail-svelte-5-runes-s-961" --- # Svelte 5 Runes Signal Graph Cycle and Deep State Mutation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cyclic Signal Graph Cascades, Side-Effect Leaks in $derived Runes, and Untracked Deep Proxy Mutations ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Signal Graph Purity and Deep State Mutation Guardrails. Svelte 5's fine-grained reactivity operates on a Directed Acyclic Graph (DAG) of signals. You must prevent cyclic reactive loops, illegal mutations inside pure derivations, and unintended performance degradation caused by deep proxy wrapping of large datasets. Every state mutation must be deterministic, isolated from derivations, and tracked cleanly through explicit domain boundaries. ## Strict Guidelines - Engineers MUST ALWAYS treat $derived and $derived.by as strictly pure, idempotent transformations with zero external mutations or asynchronous side effects. - Engineers MUST NOT update any $state rune inside an $effect or $effect.pre if that state is read directly or transitively within the same effect, preventing infinite microtask cascades. - Engineers MUST use $derived runes instead of synchronizing dependent state via $effect assignments. - Engineers MUST use $state.raw for high-frequency or large reference-type datasets (e.g., telemetry buffers, charting arrays, canvas payloads) and update them via immutable reassignments to avoid reactive proxy overhead. - Components NEVER accept deeply mutable raw $state objects as props; state mutation authority MUST remain encapsulated within module-level domain models or explicit callback handlers in `.svelte.ts` files. - Code SHOULD leverage untrack() inside $effect blocks when specific signal reads must be excluded from subscription tracking to decouple reactive triggers. ## Bad vs Good Implementations ### State Synchronization: Cyclic $effect vs Pure $derived #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $effect to sync derived values causes an extra render microtask, bypasses compile-time DAG analysis, and risks infinite execution loops if secondary signals are touched. ```typescript // MetricFilter.svelte.ts import { untrack } from 'svelte'; export class MetricDashboard { metrics = $state<number[]>([10, 20, 30]); filteredMetrics = $state<number[]>([]); threshold = $state<number>(15); constructor() { // ANTI-PATTERN: Using $effect for derived computation and mutating state, // risking cycles and delayed render ticks. $effect.root(() => { $effect(() => { this.filteredMetrics = this.metrics.filter((m) => m > this.threshold); }); }); } } ``` #### Production Standard (Correct) > **Standard**: Deriving values using $derived.by creates a memoized, read-only signal computed on-demand without scheduling extra asynchronous effect cycles. ```typescript // MetricFilter.svelte.ts export class MetricDashboard { metrics = $state<number[]>([10, 20, 30]); threshold = $state<number>(15); // INVARIANT: Pure derivation inside the reactive graph filteredMetrics = $derived.by(() => { return this.metrics.filter((m) => m > this.threshold); }); addMetric(val: number): void { this.metrics.push(val); } } ``` ### High-Volume Telemetry: Deep Proxy Traps vs $state.raw with Untrack #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Deep reactive proxies for large nested structures create severe memory footprint and garbage collection spikes. Mutating tracking signals inside the effect triggers infinite or redundant reactive churn. ```typescript // TelemetryFeed.svelte.ts interface Point { x: number; y: number; id: string; } export class TelemetryFeed { // ANTI-PATTERN: Wrapping 50,000 items in deep reactive proxies points = $state<Point[]>([]); syncCount = $state<number>(0); constructor() { $effect.root(() => { $effect(() => { // ANTI-PATTERN: Reading points triggers mutation of syncCount, // which if read here creates an immediate loop. if (this.points.length > 0) { this.syncCount += 1; } }); }); } } ``` #### Production Standard (Correct) > **Standard**: $state.raw avoids thousands of runtime Proxy allocations, and untrack() ensures the effect does not create an unintended cyclic dependency on syncCount. ```typescript // TelemetryFeed.svelte.ts import { untrack } from 'svelte'; interface Point { x: number; y: number; id: string; } export class TelemetryFeed { // INVARIANT: Use $state.raw for high-frequency or large datasets points = $state.raw<readonly Point[]>([]); syncCount = $state<number>(0); ingest(newPoints: Point[]): void { // Explicit shallow reassignment triggers signal update cleanly this.points = Object.freeze([...this.points, ...newPoints]); } constructor() { $effect.root(() => { $effect(() => { // Track points length explicitly const length = this.points.length; // Decouple syncCount write using untrack to prevent cycle untrack(() => { if (length > 0) { this.syncCount += 1; } }); }); }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Signal Graph Cycle and Deep State Mutation Guardrail

Svelte 5 Runes Signal Graph Cycle and Deep State Mutation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict signal purity and cycle-free reactive graphs across Svelte 5 enterprise applications. Prohibits state mutation side effects inside $derived expressions, eliminates recursive reactive loops within $effect blocks, and mandates explicit state boundary encapsulation for complex nested telemetry and dashboard models. 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: Cyclic Signal Graph Cascades, Side-Effect Leaks in $derived Runes, and Untracked Deep Proxy Mutations 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	Cyclic Signal Graph Cascades, Side-Effect Leaks in $derived Runes, and Untracked Deep Proxy Mutations	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 as strictly pure, idempotent transformations with zero external mutations or asynchronous side effects.

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.