Svelte 5 Runes State-Tearing Isolation and Async Mutation Standard

--- description: Svelte 5 Runes State-Tearing Isolation and Async Mutation Standard - Enforces strict transactional mutation boundaries and microtask isolation for Svelte 5 runes ($state, $derived, $effect) across asynchronous operations and island boundaries. Eliminates state tearing, stale tracking leaks across await points, and uncontrolled DOM flush loops in distributed reactive contexts. 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-state-tearing-isolation" --- # Svelte 5 Runes State-Tearing Isolation and Async Mutation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Asynchronous Rune Mutation Across Microtask Boundaries Causing State Tearing and Orphan Flush Cycles ## System Constraints You are a Principal Engineer enforcing the Svelte 5 Runes Reactive State-Tearing Isolation Standard. Mandate that all asynchronous operations interacting with Svelte 5 reactive primitives ($state, $derived, $effect) use strict transactional cancellation, generation gating, and untracked read boundaries. Svelte 5 reactivity tracking terminates at the first suspension point (await) in an effect. Mutating or consuming naked runes across asynchronous microtask intervals invites race conditions, state tearing, and cyclic DOM mutation cascades across client islands. ## Strict Guidelines - Engineers MUST ALWAYS isolate asynchronous operations within $effect by using explicit AbortController instances or generational request tokens to invalidate out-of-order completions. - Engineers MUST NOT read or mutate reactive runes ($state) after an 'await' boundary within an $effect without wrapping reads in untrack() and validating execution lifecycle validity. - Code SHOULD encapsulate cross-island shared reactive state in dedicated class-based Rune stores (*.svelte.ts) implementing atomic transactional commit patterns. - Services MUST coordinate multi-island DOM mutation flushes using svelte's tick() when dependent downstream calculations rely on stable, rendered DOM geometries. - Components NEVER execute bare async fetch-and-assign patterns directly inside raw $effect rune blocks without defensive error handling and teardown cleanup functions. ## Bad vs Good Implementations ### Asynchronous Effect State Tearing vs Transactional Generation-Gated Rune Store #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Svelte 5 effects synchronously track dependencies prior to the first microtask boundary. Fetch callbacks resolve asynchronously without abort signaling, causing out-of-order network responses to overwrite newer state (state tearing) and creating orphaned reactive assignments that trigger unpredictable re-renders. ```typescript import { untrack } from 'svelte'; // ANTI-PATTERN: State tearing across async boundary in Svelte 5 let query = $state(''); let data = $state<Item[]>([]); let loading = $state(false); $effect(() => { if (!query) return; loading = true; // Reactive tracking disconnects at 'await'. Subsequent microtasks run detached, // causing state tearing if 'query' changes before fetch resolves. fetch(`/api/search?q=${query}`) .then(res => res.json()) .then((result: Item[]) => { data = result; loading = false; }); }); ``` #### Production Standard (Correct) > **Standard**: The good pattern leverages an AbortController returned from the $effect cleanup phase, preventing stale async responses from tearing state. Post-await mutations are wrapped inside untrack() to prevent accidentally creating implicit dependency subscriptions during deferred microtasks. ```typescript import { untrack } from 'svelte'; // PRODUCTION INVARIANT: Isolated async controller with deterministic cancellation class AsyncSearchStore { query = $state(''); data = $state<Item[]>([]); loading = $state(false); error = $state<Error | null>(null); constructor() { $effect(() => { const currentQuery = this.query; if (!currentQuery.trim()) { this.data = []; this.loading = false; return; } const controller = new AbortController(); this.executeFetch(currentQuery, controller.signal); return () => { controller.abort(); }; }); } private async executeFetch(q: string, signal: AbortSignal) { this.loading = true; try { const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal }); if (!res.ok) throw new Error(`HTTP_${res.status}`); const result = (await res.json()) as Item[]; // Atomic commit: only mutate if the operation was not aborted untrack(() => { if (!signal.aborted) { this.data = result; this.error = null; } }); } catch (err: unknown) { if (signal.aborted) return; untrack(() => { this.error = err instanceof Error ? err : new Error(String(err)); }); } finally { if (!signal.aborted) { untrack(() => { this.loading = false; }); } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes State-Tearing Isolation and Async Mutation Standard

Svelte 5 Runes State-Tearing Isolation and Async Mutation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict transactional mutation boundaries and microtask isolation for Svelte 5 runes ($state, $derived, $effect) across asynchronous operations and island boundaries. Eliminates state tearing, stale tracking leaks across await points, and uncontrolled DOM flush loops in distributed reactive contexts. 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: Asynchronous Rune Mutation Across Microtask Boundaries Causing State Tearing and Orphan Flush Cycles 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	Asynchronous Rune Mutation Across Microtask Boundaries Causing State Tearing and Orphan Flush Cycles	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 isolate asynchronous operations within $effect by using explicit AbortController instances or generational request tokens to invalidate out-of-order completions.

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.