Svelte 5 Runes Async State Scheduling Boundary & Microtask Isolation

--- description: Svelte 5 Runes Async State Scheduling Boundary & Microtask Isolation - Enforces strict synchronous execution invariants across Svelte 5 reactive graphs, prohibiting asynchronous execution within $derived and untracked microtask mutations in $effect. Prevents state bifurcations, unhandled rejection leaks, and out-of-order reactive graph tearing by establishing explicit AbortController teardowns and task boundary isolation. globs: src/**/*.{svelte,svelte.ts,svelte.js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-async-scheduling-boundary" --- # Svelte 5 Runes Async State Scheduling Boundary & Microtask Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Asynchronous Contamination of Synchronous Reactive Derivations and Untracked Effect Race Conditions ## System Constraints You are a Principal Frontend Architect enforcing absolute architectural purity and concurrency safety within Svelte 5 rune-based reactivity graphs. You must eradicate state bifurcation, race hazards across microtasks, and invalid async dependencies within $derived and $effect runes. Treat any async derivation or unbounded asynchronous state assignment inside runes as a critical compilation and architectural failure. ## Strict Guidelines - Engineers MUST ALWAYS keep $derived and $derived.by runes purely synchronous, side-effect-free, and deterministic; asynchronous promises MUST NEVER be awaited inside a derivation. - Engineers MUST instantiate an AbortController inside $effect blocks performing asynchronous operations and return a teardown function invoking controller.abort() to cancel obsolete microtasks across dependency invalidations. - Engineers MUST NOT mutate $state signals across an asynchronous microtask boundary without explicitly verifying stale execution tokens or handling AbortSignal.aborted state. - Code MUST isolate async data fetching into explicit service or controller classes with reactive state containers ($state), capturing completion tokens to avoid out-of-order state settlement. - Components NEVER use untracked dynamic signal dependencies across asynchronous await points inside $effect; all synchronous dependencies MUST be captured prior to awaiting promises. ## Bad vs Good Implementations ### Async Race Hazards in $effect vs Managed AbortSignal Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The $effect spawns an unmanaged microtask chain. Rapid changes to `userId` launch concurrent network requests that settle out-of-order, writing stale data over fresh state and leaking unmanaged asynchronous mutations into Svelte's reactive graph. ```typescript import { untrack } from 'svelte'; let userId = $state('user-1'); let userData = $state<Record<string, unknown> | null>(null); let isLoading = $state(false); // ANTI-PATTERN: Untracked async race hazard across microtasks. // If userId changes while the request is in flight, responses settle out of order, // leading to state bifurcation and stale overwrites. $effect(() => { const currentId = userId; isLoading = true; fetch(`/api/users/${currentId}`) .then(res => res.json()) .then(data => { // State is mutated after microtask boundary without cancellation or stale checks userData = data; isLoading = false; }); }); ``` #### Production Standard (Correct) > **Standard**: The effect defines an explicit AbortController lifecycle. When `userId` invalidates the effect before the response resolves, the cleanup function aborts the in-flight request, preventing stale state overwrites and keeping scheduling strictly deterministic. ```typescript let userId = $state('user-1'); let userData = $state<Record<string, unknown> | null>(null); let isLoading = $state(false); // PRODUCTION INVARIANT: Microtask isolation via explicit AbortController teardown. $effect(() => { const currentId = userId; const controller = new AbortController(); isLoading = true; async function fetchUser(): Promise<void> { try { const res = await fetch(`/api/users/${currentId}`, { signal: controller.signal }); if (!res.ok) throw new Error(`HTTP error ${res.status}`); const data = (await res.json()) as Record<string, unknown>; userData = data; } catch (err: unknown) { if (err instanceof DOMException && err.name === 'AbortError') { return; } console.error('Failed to load user:', err); } finally { if (!controller.signal.aborted) { isLoading = false; } } } void fetchUser(); return () => { controller.abort(); }; }); ``` ### Invalid Async $derived vs Synchronous Stateful Async Loader Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Runes enforce synchronous reactivity graphs. Wrapping an async operation in `$derived.by` returns a raw Promise object rather than the awaited value, breaking the declarative reactive pipeline and leaving consuming templates binding to an unhandled Promise. ```typescript let query = $state('svelte'); // ANTI-PATTERN: Asynchronous derivation. // $derived.by cannot handle asynchronous promises; it evaluates to Promise<Result> // which does not update reactively when the promise resolves. let searchResults = $derived.by(async () => { const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`); return (await res.json()) as string[]; }); ``` #### Production Standard (Correct) > **Standard**: Asynchronous operations are encapsulated inside a custom reactive controller. The dependency is synchronously tracked inside the controller's `$effect`, maintaining separation between the synchronous reactive graph and asynchronous I/O lifecycle. ```typescript class AsyncResource<T, P> { value = $state<T | null>(null); loading = $state(false); error = $state<Error | null>(null); constructor( private readonly fetcher: (param: P, signal: AbortSignal) => Promise<T>, private readonly getParam: () => P ) { $effect(() => { const param = this.getParam(); const controller = new AbortController(); this.loading = true; this.error = null; this.fetcher(param, controller.signal) .then((result) => { this.value = result; }) .catch((err: unknown) => { if (err instanceof DOMException && err.name === 'AbortError') return; this.error = err instanceof Error ? err : new Error(String(err)); }) .finally(() => { if (!controller.signal.aborted) { this.loading = false; } }); return () => controller.abort(); }); } } let query = $state('svelte'); const searchResource = new AsyncResource<string[], string>( async (q, signal) => { const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal }); if (!res.ok) throw new Error('Search failed'); return (await res.json()) as string[]; }, () => query ); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async State Scheduling Boundary & Microtask Isolation

Svelte 5 Runes Async State Scheduling Boundary & Microtask Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict synchronous execution invariants across Svelte 5 reactive graphs, prohibiting asynchronous execution within $derived and untracked microtask mutations in $effect. Prevents state bifurcations, unhandled rejection leaks, and out-of-order reactive graph tearing by establishing explicit AbortController teardowns and task boundary isolation. 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 Contamination of Synchronous Reactive Derivations and Untracked Effect Race Conditions 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 Contamination of Synchronous Reactive Derivations and Untracked Effect Race Conditions	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 runes purely synchronous, side-effect-free, and deterministic

Engineers MUST ALWAYS keep $derived and $derived.by runes purely synchronous, side-effect-free, and deterministic; asynchronous promises MUST NEVER be awaited inside a derivation.

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.