Svelte 5 Runes Reactive Graph Purity Boundary

--- description: Svelte 5 Runes Reactive Graph Purity Boundary - Enforces strict synchronous dependency tracking and purity invariants across Svelte 5 reactive runes ($derived, $derived.by, $effect). Prevents untracked asynchronous race conditions, memory leaks, and cascading cyclic re-renders by mandating synchronous reads, explicit AbortController lifecycle teardowns, and mutation-free derivation boundaries. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactive-graph-purity" --- # Svelte 5 Runes Reactive Graph Purity Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Untracked Post-Await State Access and Unbounded Async Side Effects in Runes ## System Constraints You are a Principal Software Architect enforcing reactive graph integrity in Svelte 5 codebases. Svelte 5 runes ($state, $derived, $effect) track dependencies strictly via synchronous execution ticks. Reading reactive state past an 'await' boundary severs dependency tracking, and async derivations are strictly prohibited. You must prevent memory leaks, uncancelled race conditions, and infinite re-render loops by enforcing synchronous dependency capturing, explicit cancellation teardowns, and deterministic derived purity. ## Strict Guidelines - Engineers MUST ALWAYS synchronously capture all reactive dependencies at the root execution frame of an $effect before entering any asynchronous boundary (e.g., await, Promise, setTimeout). - Engineers MUST NOT declare $derived or $derived.by callbacks as async functions; $derived expressions must remain purely synchronous, deterministic, and idempotent. - Engineers MUST ALWAYS return a synchronous teardown function from an $effect containing asynchronous operations to abort pending network requests via AbortController and dispose of active timers or listeners. - Code MUST NEVER mutate reactive state ($state) synchronously inside an $effect if that same state is read synchronously within the effect, avoiding 'effect_update_depth_exceeded' cycles. - Services MUST encapsulate asynchronous data-fetching logic inside reusable stateful rune classes (.svelte.ts) that manage their own fetch state, error boundaries, and AbortController lifecycles. - Components NEVER use $effect to synchronize dependent state when $derived or $derived.by can compute it synchronously. ## Bad vs Good Implementations ### Async Effect with Post-Await Untracked Dependency and Missing Cleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Svelte 5 tracks dependencies synchronously during effect execution. Any reactive state read after an await expression (like 'query') is completely invisible to the dependency graph. Rapid updates to 'userId' cause concurrent uncancelled fetch operations where late responses overwrite fresher state. ```typescript // BAD: Reactive dependencies read after await are not tracked; // missing AbortController causes race conditions on fast param changes. let { userId = $bindable() } = $props<{ userId: string }>(); let userData = $state<UserData | null>(null); let query = $state(''); $effect(() => { (async () => { const res = await fetch(`/api/users/${userId}`); userData = await res.json(); // Race condition: query is read AFTER await, untracked by Svelte's reactive graph! console.log(`Fetched for filter: ${query}`); })(); }); ``` #### Production Standard (Correct) > **Standard**: Capturing 'targetId' and 'currentQuery' synchronously guarantees full dependency registration in the graph. The returned teardown function aborts previous requests before re-executing, eliminating race conditions and network payload waste. ```typescript // GOOD: Synchronous snapshotting of dependencies with AbortController lifecycle teardown. let { userId = $bindable() } = $props<{ userId: string }>(); let userData = $state<UserData | null>(null); let query = $state(''); let error = $state<string | null>(null); $effect(() => { // 1. Synchronously capture all reactive dependencies const targetId = userId; const currentQuery = query; const controller = new AbortController(); async function executeFetch(): Promise<void> { try { const res = await fetch(`/api/users/${targetId}?q=${encodeURIComponent(currentQuery)}`, { signal: controller.signal }); if (!res.ok) throw new Error(`HTTP ${res.status}`); userData = await res.json(); error = null; } catch (err: unknown) { if (err instanceof DOMException && err.name === 'AbortError') return; error = err instanceof Error ? err.message : 'Unknown error'; } } executeFetch(); // 2. Synchronous cleanup to abort stale in-flight work return () => { controller.abort(); }; }); ``` ### Impure Asynchronous Derivation vs. Synchronous Derived Rune #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: $derived and $derived.by must be pure and synchronous. Returning a Promise from $derived.by yields an untracked Promise object rather than the resolved value, breaking consumer components and bypassing reactivity. ```typescript // BAD: Attempting async computation inside $derived or $derived.by let count = $state(0); // Invalid: Svelte derived runes cannot be async or contain async side-effects const formattedCount = $derived.by(async () => { const formatted = await formatNumberAsync(count); return formatted; }); ``` #### Production Standard (Correct) > **Standard**: $derived remains strictly pure and instantaneous. Complex asynchronous pipelines are offloaded to dedicated rune controllers that handle promises and abort signals explicitly. ```typescript // GOOD: Use pure synchronous $derived, or encapsulate async state in a dedicated rune module import { createAsyncResource } from '$lib/runes/resource.svelte.ts'; let count = $state(0); // Pure synchronous derivation for derived state const doubled = $derived(count * 2); // Encapsulated async resource handling loading/error/value states const asyncFormatted = createAsyncResource(() => count, (c, signal) => formatNumberAsync(c, signal)); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Graph Purity Boundary

Svelte 5 Runes Reactive Graph Purity Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces strict synchronous dependency tracking and purity invariants across Svelte 5 reactive runes ($derived, $derived.by, $effect). Prevents untracked asynchronous race conditions, memory leaks, and cascading cyclic re-renders by mandating synchronous reads, explicit AbortController lifecycle teardowns, and mutation-free derivation boundaries. 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: Untracked Post-Await State Access and Unbounded Async Side Effects in 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	Untracked Post-Await State Access and Unbounded Async Side Effects in 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 synchronously capture all reactive dependencies at the root execution frame of an $effect before entering any asynchronous boundary (e.g., await, Promise, setTimeout).

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.