Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail

--- description: Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail - Enforces strict boundaries on asynchronous state mutations within Svelte 5 rune-based reactivity ($effect, $state, and $derived). Prevents unbounded microtask-driven signal cascades, infinite reactive graph flush loops, and orphaned state writes across component teardown or hydration transitions. 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-async-state-mutation-drain-guardrail" --- # Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Async State Mutation Inside $effect Inducing Infinite Microtask Flush Loops ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail. Mandate invariants that prevent infinite reactive loops, async race conditions, and uncoordinated state writes across component lifecycles in Svelte 5 applications. ## Strict Guidelines - Engineers MUST ALWAYS implement cancellation mechanisms (such as AbortController) returned as the cleanup function in an `$effect` that performs asynchronous operations to prevent writes after teardown. - Engineers MUST NOT mutate reactive `$state` fields asynchronously inside an `$effect` if those fields are read synchronously within the same effect prior to an `await`, as this creates self-reinforcing signal invalidation cascades. - Code SHOULD use `untrack()` when reading secondary signals inside asynchronous routines that should not register as re-run triggers for the reactive graph. - Services MUST encapsulate asynchronous pipelines into explicit status containers (e.g., idle, pending, resolved, rejected) rather than scattering discrete, uncoordinated `$state` flags across microtask boundaries. - Components NEVER read `$state` after an `await` expecting it to be tracked by the compiler, because Svelte 5 stops dependency tracking at the first microtask yield. ## Bad vs Good Implementations ### Asynchronous Effect with Re-entrancy Loop vs. Clean Lifecycle Invalidation Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example initiates a fetch inside an $effect without an AbortController cleanup. If the component unmounts or query changes rapidly, out-of-order microtask resolution causes race conditions and mutates state on torn-down branches. Furthermore, uncoordinated flag mutations can trigger erratic flush cascades across dependent runes. ```typescript import { untrack } from 'svelte'; // ANTI-PATTERN: Async mutation causes infinite flush loop and memory leaks post-unmount let query = $state(''); let results = $state<string[]>([]); let isLoading = $state(false); $effect(() => { // Synchronous read registers query as dependency if (query.length > 2) { isLoading = true; fetch(`/api/search?q=${query}`) .then(res => res.json()) .then(data => { // Uncoordinated async write after potential component unmount results = data; isLoading = false; // Mutating dependency or related signal in microtask triggers cascading re-renders }); } }); ``` #### Production Standard (Correct) > **Standard**: The invariant fix binds the async work to an AbortController returned from the $effect cleanup closure. Any new invocation or teardown cancels in-flight network requests. Downstream state updates after the await boundary are guarded against aborted executions and isolated with untrack() to prevent unwanted reactive graph invalidation cascades. ```typescript import { untrack } from 'svelte'; // PRODUCTION FIX: AbortController teardown with isolated signal updates let query = $state(''); let results = $state<string[]>([]); let status = $state<'idle' | 'loading' | 'error'>('idle'); $effect(() => { const currentQuery = query.trim(); if (currentQuery.length <= 2) { results = []; status = 'idle'; return; } const controller = new AbortController(); status = 'loading'; (async () => { try { const response = await fetch(`/api/search?q=${encodeURIComponent(currentQuery)}`, { signal: controller.signal }); if (!response.ok) throw new Error('Search failed'); const data = await response.json(); if (!controller.signal.aborted) { untrack(() => { results = data; status = 'idle'; }); } } catch (err: unknown) { if (err instanceof Error && err.name === 'AbortError') return; if (!controller.signal.aborted) { untrack(() => { status = 'error'; }); } } })(); return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail

Svelte 5 Runes Async State Mutation & Reactive Graph Drain Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundaries on asynchronous state mutations within Svelte 5 rune-based reactivity ($effect, $state, and $derived). Prevents unbounded microtask-driven signal cascades, infinite reactive graph flush loops, and orphaned state writes across component teardown or hydration transitions. 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: Unbounded Async State Mutation Inside $effect Inducing Infinite Microtask Flush 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	Unbounded Async State Mutation Inside $effect Inducing Infinite Microtask Flush 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 implement cancellation mechanisms (such as AbortController) returned as the cleanup function in an `$effect` that performs asynchronous operations to prevent writes after teardown.

Engineers MUST ALWAYS implement cancellation mechanisms (such as AbortController) returned as the cleanup function in an `$effect` that performs asynchronous operations to prevent writes after teardown.

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.