Svelte 5 Runes Reactivity Boundary and Signal Invariant Enforcement

--- description: Svelte 5 Runes Reactivity Boundary and Signal Invariant Enforcement - Establishes strict unidirectional signal-graph boundaries using Svelte 5 runes ($state, $derived, $effect, and untrack) to eliminate side-effect cascades, cyclic dependency loops, and untracked microtask mutations. Mandates that derived computations remain strictly pure and idempotently evaluable without mutating upstream or downstream state. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactivity-boundary-enforcement" --- # Svelte 5 Runes Reactivity Boundary and Signal Invariant Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating reactive state inside $derived expressions or unbounded $effect cycles triggering reactivity graph thrashing ## System Constraints You are a Principal Frontend Architect enforcing strict Svelte 5 Runes reactivity invariants. You must prevent cyclic reactive loops, accidental side-effects within derived values, and illegal mutation across asynchronous microtask boundaries. Mandate pure computations in $derived, strict synchronization barriers in $effect, and explicitly managed reactivity with untrack() when decoupling dependencies. ## Strict Guidelines - Engineers MUST ALWAYS keep $derived and $derived.by expressions purely functional, deterministic, and free of observable side effects or upstream mutations. - Engineers MUST NOT write to any $state or trigger external store mutations inside a $derived or $derived.by block under any circumstances. - Code MUST use untrack() explicitly whenever an effect or async process reads reactive state that should not register as a dependency for re-execution. - Components NEVER use $effect to compute state that can be derived directly; synchronous transformations MUST strictly use $derived or $derived.by. - Services MUST encapsulate reactive state models inside .svelte.ts files using class instances or closures exposing readonly getters for derived signals. - Engineers MUST use $state.raw() for large immutable structures, external library instances, or payloads that do not require recursive reactive proxying. - Effects that synchronize with external APIs MUST implement explicit teardown cleanups returned directly from the $effect callback. ## Bad vs Good Implementations ### Pure Signal Derivation vs. Effect-Driven State Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating reactive state ($state) within an $effect to compute dependent values creates an asynchronous render cascade, incurs an extra microtask cycle, and risks infinite reactivity loops (effect_update_depth_exceeded). ```typescript // Bad: Mutating state inside $effect or simulating derived state with effects import { $state, $effect } from 'svelte'; export class CartModel { items = $state<Array<{ id: string; price: number; quantity: number }>>([]); total = $state<number>(0); discount = $state<number>(0); constructor() { // Anti-pattern: Cascading effect creates cyclic risk and extra microtask render frame $effect(() => { const rawTotal = this.items.reduce((sum, item) => sum + item.price * item.quantity, 0); this.total = rawTotal - this.discount; // Mutation inside effect triggers secondary invalidation }); } } ``` #### Production Standard (Correct) > **Standard**: The computed value uses $derived.by, guaranteeing fine-grained, push-pull reactive evaluation without intermediate state mutations or duplicate layout passes. ```typescript // Good: Explicit, pure signal computation with $derived export class CartModel { #items = $state<Array<{ id: string; price: number; quantity: number }>>([]); #discount = $state<number>(0); // Computed on-demand via direct signal dependency graph without side-effects total = $derived.by(() => { const subtotal = this.#items.reduce((sum, item) => sum + item.price * item.quantity, 0); return Math.max(0, subtotal - this.#discount); }); get items() { return this.#items; } get discount() { return this.#discount; } addItem(item: { id: string; price: number; quantity: number }) { this.#items.push(item); } } ``` ### Decoupling Dependent Reads with untrack() in Side Effects #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing telemetryService.currentSessionId inside the $effect implicitly registers it as a signal dependency, causing the sync function to re-fire unexpectedly when only the session token refreshes. ```typescript // Bad: Unintended reactive subscription to telemetry and session tokens inside $effect import { $effect } from 'svelte'; export function syncUserActivity(activity: () => string, telemetryService: TelemetryService) { $effect(() => { const currentActivity = activity(); const sessionId = telemetryService.currentSessionId; // Accidental dependency! telemetryService.dispatch({ event: currentActivity, session: sessionId }); }); } ``` #### Production Standard (Correct) > **Standard**: Wrapping secondary reads in untrack() strictly scopes the reactive boundary to `activity()`, preventing cyclic notifications and unneeded analytics dispatch runs. ```typescript // Good: Isolating intentional trigger dependencies using untrack() import { $effect, untrack } from 'svelte'; export function syncUserActivity(activity: () => string, telemetryService: TelemetryService) { $effect(() => { const currentActivity = activity(); // Intentional reactive dependency // Decouple read from the reactivity graph const sessionId = untrack(() => telemetryService.currentSessionId); const controller = new AbortController(); telemetryService.dispatch({ event: currentActivity, session: sessionId, signal: controller.signal }); return () => { controller.abort(); }; }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactivity Boundary and Signal Invariant Enforcement

Svelte 5 Runes Reactivity Boundary and Signal Invariant Enforcement defines an industrial-grade behavioral standard for frontend engineering. Establishes strict unidirectional signal-graph boundaries using Svelte 5 runes ($state, $derived, $effect, and untrack) to eliminate side-effect cascades, cyclic dependency loops, and untracked microtask mutations. Mandates that derived computations remain strictly pure and idempotently evaluable without mutating upstream or downstream state. 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 reactive state inside $derived expressions or unbounded $effect cycles triggering reactivity graph thrashing 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 reactive state inside $derived expressions or unbounded $effect cycles triggering reactivity graph thrashing	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 expressions purely functional, deterministic, and free of observable side effects or upstream mutations.

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.