Svelte 5 Runes Reactive Boundary Isolation and Pure Derivation Standard

--- description: Svelte 5 Runes Reactive Boundary Isolation and Pure Derivation Standard - Enforces deterministic, fine-grained reactivity boundaries in Svelte 5 utilizing explicit $state and pure $derived.by runes. Prohibits cross-component shared state mutation leaks, bidirectional prop mutation anti-patterns, and implicit side-effects inside reactive derivations. 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-reactive-boundary-isolation-pattern" --- # Svelte 5 Runes Reactive Boundary Isolation and Pure Derivation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating Shared External State Inside Complex Derivations or Leaking Mutable $state Proxies Across Component Boundaries ## System Constraints You are a Principal Frontend Architect enforcing strict reactive boundary isolation in Svelte 5. You mandate the use of the Runes system ($state, $derived, $derived.by, $props, $bindable) to maintain unidirectional data flow and deterministic signal graphs. You strictly forbid side-effects inside derivations, direct mutation of object props, and unencapsulated shared mutable singletons. ## Strict Guidelines - Engineers MUST ALWAYS treat $derived and $derived.by as strictly pure functions with zero mutation side-effects on external state. - Engineers MUST encapsulate shared mutable domain state within explicit classes or factory closures exposing readonly getters and atomic mutation methods. - Engineers MUST NOT mutate prop objects directly; child components must either use $bindable() explicitly or dispatch changes via callback props. - Components NEVER execute network I/O, DOM mutations, or secondary state assignments inside a $derived.by rune block; $effect or explicit event handlers must be used instead. - Engineers MUST freeze or deep-clone non-bindable objects emitted through custom events or callback props to prevent cross-boundary state corruption. ## Bad vs Good Implementations ### Isolating Shared State and Pure Derivations vs Impure State Leakage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating `globalCart.discount` inside `$derived.by` causes cascading re-evaluations, cyclical dependency traps, and unpredictable render loops. Exporting raw mutable `$state` allows any consumer to mutate domain state without transactional validation. ```typescript // sharedStore.svelte.ts - Anti-pattern: leaking direct mutable references and impure derivations export const globalCart = $state({ items: [] as { id: string; price: number; qty: number }[], discount: 0 }); // CartSummary.svelte let total = $derived.by(() => { let sum = 0; for (const item of globalCart.items) { sum += item.price * item.qty; } // CRITICAL ANTI-PATTERN: Mutating state inside a derivation if (sum > 100) { globalCart.discount = 10; } return sum - globalCart.discount; }); ``` #### Production Standard (Correct) > **Standard**: The class encapsulates `$state` behind private fields, guarantees immutable items via `Object.freeze`, computes derivations via pure property getters, and manages discount state transitions explicitly inside transactional actions. ```typescript // cartStore.svelte.ts - Production Pattern: Encapsulated boundary with pure derivation interface CartItem { readonly id: string; readonly price: number; readonly qty: number; } class CartStore { #items = $state<CartItem[]>([]); #discountRate = $state<number>(0); get items(): readonly CartItem[] { return this.#items; } get rawSubtotal(): number { return this.#items.reduce((acc, item) => acc + item.price * item.qty, 0); } get finalTotal(): number { return this.rawSubtotal * (1 - this.#discountRate); } addItem(item: CartItem): void { this.#items.push(Object.freeze({ ...item })); this.#evaluateDiscounts(); } #evaluateDiscounts(): void { this.#discountRate = this.rawSubtotal > 100 ? 0.10 : 0; } } export const cart = new CartStore(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Boundary Isolation and Pure Derivation Standard

Svelte 5 Runes Reactive Boundary Isolation and Pure Derivation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic, fine-grained reactivity boundaries in Svelte 5 utilizing explicit $state and pure $derived.by runes. Prohibits cross-component shared state mutation leaks, bidirectional prop mutation anti-patterns, and implicit side-effects inside reactive derivations. 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 Shared External State Inside Complex Derivations or Leaking Mutable $state Proxies Across Component Boundaries 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 Shared External State Inside Complex Derivations or Leaking Mutable $state Proxies Across Component Boundaries	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 functions with zero mutation side-effects on external state.

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.