Svelte 5 Untrack Asynchronous Boundary Lexical Scope Isolation

--- description: Svelte 5 Untrack Asynchronous Boundary Lexical Scope Isolation - Enforces strict synchronous boundaries when using Svelte 5's untrack primitive to prevent reactive tracking context leakage. Svelte 5's reactivity runtime unsets the active reaction synchronously and reinstates it via a finally block; passing async functions to untrack or reading runes after await statements causes stealth dependencies, race conditions, and infinite reactive cascades. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-untrack-async-boundary-lexical-isolation" --- # Svelte 5 Untrack Asynchronous Boundary Lexical Scope Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Async Callbacks to untrack or Reading Rune State Across Await Boundaries ## System Constraints You are a Principal Software Architect enforcing Svelte 5 reactive graph integrity. You must prohibit passing asynchronous callbacks to untrack() and ensure mutable rune reads ($state) are isolated to synchronous execution stacks. When code executes across asynchronous boundaries (promises, microtasks, setTimeout), you must mandate lexical snapshotting before the boundary to ensure the reactive graph is not inadvertently poisoned with stealth dependencies. ## Strict Guidelines - Engineers MUST ALWAYS execute untrack() as a strictly synchronous function that returns a synchronous value. - Engineers MUST NOT pass an async function or a function returning a Promise directly to untrack(). - Engineers MUST snapshot all required $state runes into local immutable variables synchronously before crossing any await boundary or initiating an asynchronous invocation. - Code SHOULD isolate long-running asynchronous effects from reactive primitives by utilizing explicitly isolated helper functions outside of the reactive effect tree. - Components NEVER read reactive rune properties across an await tick under the assumption that untrack() remains in effect after the microtask resumes. ## Bad vs Good Implementations ### Async untrack boundary leakage vs synchronous snapshot isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: untrack() only suppresses dependency tracking synchronously. Passing an async function causes untrack to return a Promise immediately and restore the active reaction context before the microtask continues. Consequently, reading or mutating runes after 'await' leaks stealth dependencies into the reactive graph, triggering infinite loops or unmanaged cascading re-renders. ```typescript import { untrack } from 'svelte'; let query = $state(''); let results = $state<string[]>([]); let auditLog = $state<string[]>([]); $effect(() => { // Anti-pattern: untrack finishes synchronously upon returning the Promise. // Once the await resolves, the untracked context is long gone, meaning // subsequent reads become stealth tracking dependencies or corrupt reactions. untrack(async () => { const response = await fetch(`/api/search?q=${query}`); const data = await response.json(); // Stealth dependency capture on auditLog during microtask resumption auditLog.push(`Searched: ${query} at ${Date.now()}`); results = data.items; }); }); ``` #### Production Standard (Correct) > **Standard**: State is evaluated synchronously inside untrack() and saved to the immutable local variable currentQuery. The asynchronous fetch uses the frozen lexical snapshot without leaking reactive contexts into microtask continuations, and cleanup ensures stale network promises do not update state post-unmount. ```typescript import { untrack } from 'svelte'; let query = $state(''); let results = $state<string[]>([]); let auditLog = $state<string[]>([]); $effect(() => { // Invariant: Snapshot untracked state synchronously into immutable lexical scope const currentQuery = untrack(() => query); // Asynchronous execution runs outside of untrack with pinned values let isMounted = true; (async () => { const response = await fetch(`/api/search?q=${encodeURIComponent(currentQuery)}`); const data = await response.json(); if (!isMounted) return; // Explicit, deterministic updates using snapshotted data results = data.items; auditLog = [...untrack(() => auditLog), `Searched: ${currentQuery} at ${Date.now()}`]; })(); return () => { isMounted = false; }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Untrack Asynchronous Boundary Lexical Scope Isolation

Svelte 5 Untrack Asynchronous Boundary Lexical Scope Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict synchronous boundaries when using Svelte 5's untrack primitive to prevent reactive tracking context leakage. Svelte 5's reactivity runtime unsets the active reaction synchronously and reinstates it via a finally block; passing async functions to untrack or reading runes after await statements causes stealth dependencies, race conditions, and infinite reactive cascades. 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: Passing Async Callbacks to untrack or Reading Rune State Across Await Boundaries 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	Passing Async Callbacks to untrack or Reading Rune State Across Await Boundaries	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 execute untrack() as a strictly synchronous function that returns a synchronous value.

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.