Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrail

--- description: Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrail - Enforces strict mathematical purity in Svelte 5 reactive derivations and prevents cyclic dependency graphs. Prohibits state mutation side effects inside `$derived` and `$derived.by` blocks while mandating termination bounds and untracked reads in `$effect` synchronizations. 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-reactive-graph-cycle-derived-mutation" --- # Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating $state Inside $derived Blocks or Creating Unbounded $effect Feedback Loops ## System Constraints You are a Principal Engineer enforcing Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrails. Mandate absolute purity in signal projections ($derived, $derived.by) and deterministic termination in reaction blocks ($effect, $effect.pre). Reject any code modifying reactive state inside derived signal graphs. ## Strict Guidelines - Engineers MUST ALWAYS keep `$derived` and `$derived.by` pure, synchronous, idempotent, and free of observable side effects. - Engineers MUST NOT mutate any `$state` or trigger functions that cause state transitions within a `$derived` or `$derived.by` computation. - Code MUST use `untrack()` inside `$effect` blocks when reading a signal whose subsequent mutation within the same effect should not re-trigger that effect. - Components NEVER synchronize state between two `$state` variables using bidirectional `$effect` handlers; use unidirectional derived state or single-source-of-truth normalization instead. - Services MUST NOT construct circular dependency chains between distinct signals (A -> B -> A) that exceed Svelte's maximum reactive iteration limit. ## Bad vs Good Implementations ### State Mutation Inside Derived Signal Projection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating `auditLog` inside `$derived.by` violates the pure functional contract of derived signals. This causes unpredictable graph invalidation cycles, triggers extraneous subscriber notifications, and risks hard runtime errors if `auditLog` is read higher in the dependency tree. ```typescript import { untrack } from 'svelte'; let rawFilter = $state(''); let auditLog = $state<string[]>([]); // ANTI-PATTERN: Mutating $state inside $derived creates side-effects during graph propagation const normalizedFilter = $derived.by(() => { const sanitized = rawFilter.trim().toLowerCase(); auditLog.push(`Filter changed to: ${sanitized}`); // SIDE EFFECT: Mutates state in derived computation return sanitized; }); ``` #### Production Standard (Correct) > **Standard**: Derivation remains an idempotent projection of `rawFilter`. The telemetry side effect is quarantined inside `$effect`, using `untrack()` around `auditLog` to ensure that mutating `auditLog` does not establish an accidental circular subscription to itself. ```typescript import { untrack } from 'svelte'; let rawFilter = $state(''); let auditLog = $state<string[]>([]); // PURE: $derived computes value deterministically without side effects const normalizedFilter = $derived(rawFilter.trim().toLowerCase()); // SIDE EFFECTS: Coordinated strictly within an explicit $effect boundary $effect(() => { const current = normalizedFilter; untrack(() => { auditLog = [...auditLog, `Filter changed to: ${current}`]; }); }); ``` ### Bidirectional State Synchronization Cycle vs Pure Derived State #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Synchronizing two distinct `$state` atoms using symmetric `$effect` blocks produces an infinite microtask cycle (ping-ponging state updates) exceeding Svelte's maximum update depth. ```typescript let celsius = $state(0); let fahrenheit = $state(32); // ANTI-PATTERN: Bidirectional circular $effect coupling causes infinite execution loops $effect(() => { fahrenheit = (celsius * 9) / 5 + 32; }); $effect(() => { celsius = ((fahrenheit - 32) * 5) / 9; }); ``` #### Production Standard (Correct) > **Standard**: Eliminates redundant state. `celsius` is the canonical source of truth, `fahrenheit` is a read-only projection, and reverse operations are explicitly modeled through procedural event handlers rather than reactive feedback loops. ```typescript let celsius = $state(0); // Pure derived projection: Single source of truth with zero cyclic feedback const fahrenheit = $derived((celsius * 9) / 5 + 32); function updateFromFahrenheit(val: number) { celsius = ((val - 32) * 5) / 9; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrail

Svelte 5 Reactive Graph Cycle & Derived Mutation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict mathematical purity in Svelte 5 reactive derivations and prevents cyclic dependency graphs. Prohibits state mutation side effects inside `$derived` and `$derived.by` blocks while mandating termination bounds and untracked reads in `$effect` synchronizations. 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 $state Inside $derived Blocks or Creating Unbounded $effect Feedback Loops 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 $state Inside $derived Blocks or Creating Unbounded $effect Feedback Loops	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 keep `$derived` and `$derived.by` pure, synchronous, idempotent, and free of observable 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.