Svelte 5 Runes Reactive Graph Cycle Detection and Teardown Invariant

--- description: Svelte 5 Runes Reactive Graph Cycle Detection and Teardown Invariant - Enforces strict lifecycle boundaries and disposal invariants for Svelte 5 fine-grained reactive graphs across client-side SPA route transitions. Prohibits orphaned module-level $effect.root allocations and cyclic signal updates to prevent memory leaks and graph thrashing. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactive-graph-teardown-invariant" --- # Svelte 5 Runes Reactive Graph Cycle Detection and Teardown Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Orphaned Module-Level Effect Roots and Self-Triggering Reactive Cycles in Svelte 5 Runes ## System Constraints You are a Principal Frontend Architect enforcing strict Svelte 5 Runes memory hygiene and reactive graph determinism. You must ensure that fine-grained signals, derived calculations, and active effects cannot form cyclic dependencies or survive route transitions uncollected. Mandate explicit cleanup closures in all effects, require manual lifecycle management via effect roots in module scopes, and forbid state mutations inside effects that trigger their own reactive dependencies. ## Strict Guidelines - Engineers MUST ALWAYS return an explicit teardown callback from any `$effect` that binds event listeners, timers, streams, or external DOM observers. - Engineers MUST NOT mutate a `$state` signal inside an `$effect` if that same signal is read within the effect's dependency graph, unless explicitly wrapped in `untrack()`. - Services MUST encapsulate module-level `$effect.root` calls and bind their returned cleanup functions to route-level navigation lifecycles or component unmount hooks. - Components NEVER use `$effect` to synchronize derived data; engineers MUST declare pure dependencies using `$derived` or `$derived.by` instead. - Code SHOULD verify signal graph acyclicity during state transitions by decoupling multi-hop writes into transactional batches. ## Bad vs Good Implementations ### Module-Level Signal Management and Effect Teardown #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The $effect.root creates an untracked reactive root that is never disposed across SPA route changes. The window event listener is leaked on every execution, and mutating transitionCount without untracking introduces an unpredictable reactive dependency chain. ```typescript // src/lib/stores/routeTracker.svelte.ts let activeRoute = $state('/home'); let transitionCount = $state(0); // ANTI-PATTERN: Orphaned $effect.root without disposal tracking. // Mutating transitionCount inside an effect that reads activeRoute creates unbounded memory leaks. export function setupRouteListener() { $effect.root(() => { $effect(() => { console.log(`Navigated to: ${activeRoute}`); // Cyclic dependency: effect triggers its own re-execution or graph leak across navigations transitionCount += 1; window.addEventListener('popstate', () => { activeRoute = window.location.pathname; }); // Missing teardown callback for event listener }); }); } ``` #### Production Standard (Correct) > **Standard**: The RouteTracker exposes an explicit lifecycle method that returns the effect root teardown function. Mutated signals inside the effect are isolated using untrack(), and event listeners are properly removed within the effect's cleanup return. ```typescript // src/lib/stores/routeTracker.svelte.ts import { untrack } from 'svelte'; class RouteTracker { activeRoute = $state('/home'); transitionCount = $state(0); private cleanupRoot: (() => void) | null = null; init(): () => void { // PROD INVARIANT: Capture the root cleanup closure and manage lifecycle explicitly this.cleanupRoot = $effect.root(() => { $effect(() => { const current = this.activeRoute; // Safely mutate transitionCount without making it a dependency untrack(() => { this.transitionCount += 1; }); const handlePopState = () => { this.activeRoute = window.location.pathname; }; window.addEventListener('popstate', handlePopState); // Explicit teardown of the internal effect subscription return () => { window.removeEventListener('popstate', handlePopState); }; }); }); return () => this.dispose(); } dispose(): void { if (this.cleanupRoot) { this.cleanupRoot(); this.cleanupRoot = null; } } } export const routeTracker = new RouteTracker(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Graph Cycle Detection and Teardown Invariant

Svelte 5 Runes Reactive Graph Cycle Detection and Teardown Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lifecycle boundaries and disposal invariants for Svelte 5 fine-grained reactive graphs across client-side SPA route transitions. Prohibits orphaned module-level $effect.root allocations and cyclic signal updates to prevent memory leaks and graph thrashing. 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: Orphaned Module-Level Effect Roots and Self-Triggering Reactive Cycles in Svelte 5 Runes 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	Orphaned Module-Level Effect Roots and Self-Triggering Reactive Cycles in Svelte 5 Runes	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 return an explicit teardown callback from any `$effect` that binds event listeners, timers, streams, or external DOM observers.

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.