Svelte 5 Runes Async Signal Tear Prevention Guardrail

--- description: Svelte 5 Runes Async Signal Tear Prevention Guardrail - Prevents state tearing and non-deterministic dependency tracking across microtask turns in Svelte 5 fine-grained reactivity. Guarantees that $state signals mutate synchronously in atomic transactions or explicitly untracked contexts when crossing Promise boundaries. Mandates untrack() for reads after await within effects to prevent zombie listeners and inconsistent reactive graph 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-async-signal-tear-prevention" --- # Svelte 5 Runes Async Signal Tear Prevention Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating and Reading $state Runes Across Microtask Continuations in Untracked $effect Lifecycles ## System Constraints You are a Principal Engineer enforcing the Svelte 5 Runes Async Signal Tear Prevention Guardrail. In Svelte 5, the reactive graph tracking context does not cross asynchronous boundaries (microtasks/macrotasks). Any signal reads after an `await` statement inside an `$effect` or derived expression will NOT be registered as dependencies, causing silent de-synchronization. Conversely, interleaving asynchronous writes across multiple microtasks causes intermediate render tearing. Enforce atomic synchronous state transitions, explicit `untrack()` closures across asynchronous hops, and cancellation-safe async signal orchestrations. ## Strict Guidelines - Engineers MUST ALWAYS isolate asynchronous operations outside direct reactive effect dependencies or wrap post-await reads in `untrack()` if they are not intended to re-arm the effect. - Engineers MUST NOT read reactive signals after an `await` statement within an `$effect` expecting automatic subscription; Svelte 5 synchronous execution context loses signal tracking once an `await` resolves. - Engineers MUST enforce atomic state batching: multiple `$state` signals updated after an `await` boundary MUST be coordinated to prevent UI tearing during rapid microtask flush cycles. - Engineers MUST use structured task cancellation (such as `AbortController` or monotonic sequence tokens) inside asynchronous effects to preempt out-of-order race conditions from unresolved promises. - Components NEVER directly invoke multi-stage asynchronous state updates in raw `$derived` runes; `$derived` must remain strictly pure, synchronous, and side-effect free. ## Bad vs Good Implementations ### Asynchronous Signal Tracking & State Tearing in $effect #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading `telemetryCounter` after an async hop fails to establish dependency tracking in Svelte 5. Furthermore, uncoordinated asynchronous assignments to `profile` and `isLoading` allow intermediate frames to render where `isLoading` is still true or partially updated, and does not handle in-flight cancellation when `userId` mutates rapidly. ```typescript import { tick } from 'svelte'; let userId = $state('user-1'); let profile = $state<Profile | null>(null); let isLoading = $state(false); let telemetryCounter = $state(0); $effect(() => { // Anti-Pattern: Reading signals after await breaks reactive tracking // and causes intermediate state tearing between isLoading and profile isLoading = true; fetch(`/api/users/${userId}`) .then(res => res.json()) .then(async (data) => { await tick(); // Signal read here is NOT tracked as a dependency of the effect if (telemetryCounter > 0) { console.log('Telemetry active'); } // Non-atomic mutation across microtask boundaries causes state tear profile = data; isLoading = false; }); }); ``` #### Production Standard (Correct) > **Standard**: Dependencies are captured synchronously prior to any `await`. All subsequent post-await reads explicitly use `untrack()` to communicate architectural intent. The state is consolidated into an immutable transaction object (`userState`), eliminating microtask render tearing, and aborted requests properly clean up to prevent race conditions. ```typescript import { untrack } from 'svelte'; interface UserState { profile: Profile | null; isLoading: boolean; error: Error | null; } let userId = $state('user-1'); let userState = $state<UserState>({ profile: null, isLoading: false, error: null }); let telemetryCounter = $state(0); $effect(() => { const currentId = userId; // Synchronously capture tracked dependency const controller = new AbortController(); async function loadUser() { // Single atomic transition into loading state userState = { profile: userState.profile, isLoading: true, error: null }; try { const res = await fetch(`/api/users/${currentId}`, { signal: controller.signal }); const data = await res.json(); // Explicitly untrack reads that occur across the async boundary const telemetry = untrack(() => telemetryCounter); if (telemetry > 0) { console.log('Telemetry active'); } // Atomic state flush: prevents intermediate render tearing userState = { profile: data, isLoading: false, error: null }; } catch (err: unknown) { if ((err as Error).name !== 'AbortError') { userState = { profile: null, isLoading: false, error: err as Error }; } } } loadUser(); return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Signal Tear Prevention Guardrail

Svelte 5 Runes Async Signal Tear Prevention Guardrail defines an industrial-grade behavioral standard for frontend engineering. Prevents state tearing and non-deterministic dependency tracking across microtask turns in Svelte 5 fine-grained reactivity. Guarantees that $state signals mutate synchronously in atomic transactions or explicitly untracked contexts when crossing Promise boundaries. Mandates untrack() for reads after await within effects to prevent zombie listeners and inconsistent reactive graph 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: Mutating and Reading $state Runes Across Microtask Continuations in Untracked $effect Lifecycles 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 and Reading $state Runes Across Microtask Continuations in Untracked $effect Lifecycles	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 outside direct reactive effect dependencies or wrap post-await reads in `untrack()` if they are not intended to re-arm the effect.

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.