Svelte 5 Fine-Grained Reactive Proxy Teardown and Lifetime Scoping Invariant

--- description: Svelte 5 Fine-Grained Reactive Proxy Teardown and Lifetime Scoping Invariant - Enforces deterministic subscriber disposal and boundary isolation for shared mutable $state proxies in Svelte 5. Prevents catastrophic client-side memory retention caused by module-level reactive singletons capturing component scope closures without explicit teardown during client-side navigation. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-reactive-proxy-teardown-invariant" --- # Svelte 5 Fine-Grained Reactive Proxy Teardown and Lifetime Scoping Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level $state Proxies Leaking Retained Component Scopes Across Route Transitions ## System Constraints You are a Principal Software Architect enforcing deterministic reactive teardown invariants in Svelte 5 applications. You must mandate strict lifecycle scoping for $state, $derived, and $effect runes. Any shared reactive proxy instantiated at module scope must never directly capture transient component instances or register listener closures without deterministic disposal contracts, preventing memory leaks during client-side routing. ## Strict Guidelines - Engineers MUST ALWAYS scope mutable reactive domains to component subtrees via setContext/getContext or provide explicit teardown methods implementing Symbol.dispose or an unsubscribe callback. - Engineers MUST NOT bind module-level singleton $state proxies to transient component callbacks without registering explicit cleanup inside an $effect returning a cleanup closure. - Code SHOULD prefer instantiating reactive state classes inside component roots or layout loaders over global module-level mutable singletons. - Services MUST explicitly call effect cleanups or use $effect.root() with manual disposal when instantiating fine-grained reactive computation chains outside the component tree. - Components NEVER attach direct event listeners or unmanaged subscriptions to shared external reactive stores without returning the corresponding teardown logic inside Svelte 5's $effect rune. ## Bad vs Good Implementations ### Module Singleton Reactive Proxy vs. Context-Scoped Disposed Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The global singleton state holds a persistent reference to the callback closure created inside the transient component. When the user navigates away, the component instance, its lexical environment, and local reactive state remain rooted in the global proxy, producing a persistent memory leak. ```typescript // stores/querySync.svelte.ts - Anti-pattern: Global mutable proxy retains unmounted component closures class QuerySyncManager { state = $state({ activeFilter: 'all', listeners: [] as ((f: string) => void)[] }); // Bad: Component closures pushed to module-level array leak the entire component tree registerListener(cb: (filter: string) => void) { this.state.listeners.push(cb); } } export const querySync = new QuerySyncManager(); // Component.svelte // <script lang="ts"> // import { querySync } from './querySync.svelte'; // let localCount = $state(0); // // Leak: Component will never be garbage collected after route navigation // querySync.registerListener((f) => { localCount++; }); // </script> ``` #### Production Standard (Correct) > **Standard**: State management is bound to component hierarchy contexts rather than unbound global module memory. Subscriptions, when required, leverage native $effect boundaries or return explicit teardown functions ensuring complete garbage collection upon unmount. ```typescript // stores/querySync.svelte.ts - Production Invariant: Scoped Context or Disposable Subscription import { setContext, getContext, onDestroy } from 'svelte'; const CONTEXT_KEY = Symbol('QUERY_SYNC_CONTEXT'); export class QuerySyncManager { #activeFilter = $state('all'); get filter() { return this.#activeFilter; } set filter(val: string) { this.#activeFilter = val; } // Good: Return explicit cleanup closure or leverage Svelte 5 $effect teardown directly subscribe(fn: (filter: string) => void): () => void { // In Svelte 5, prefer consumers binding to getters inside $effect rather than manual observer arrays let active = true; $effect.root(() => { $effect(() => { if (active) fn(this.#activeFilter); }); }); return () => { active = false; }; } } // Usage in layout/page root: export function initQuerySync(): QuerySyncManager { const manager = new QuerySyncManager(); setContext(CONTEXT_KEY, manager); return manager; } export function useQuerySync(): QuerySyncManager { const manager = getContext<QuerySyncManager>(CONTEXT_KEY); if (!manager) throw new Error('QuerySyncManager must be accessed within an initialized context.'); return manager; } // Component.svelte // <script lang="ts"> // import { useQuerySync } from './querySync.svelte'; // const querySync = useQuerySync(); // // Invariant: Native $effect cleans up subscriptions when the component unmounts // $effect(() => { // const current = querySync.filter; // // Reactive logic automatically tears down with component boundary // }); // </script> ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Fine-Grained Reactive Proxy Teardown and Lifetime Scoping Invariant

Svelte 5 Fine-Grained Reactive Proxy Teardown and Lifetime Scoping Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic subscriber disposal and boundary isolation for shared mutable $state proxies in Svelte 5. Prevents catastrophic client-side memory retention caused by module-level reactive singletons capturing component scope closures without explicit teardown during client-side navigation. 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: Module-Level $state Proxies Leaking Retained Component Scopes Across Route Transitions 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	Module-Level $state Proxies Leaking Retained Component Scopes Across Route Transitions	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 scope mutable reactive domains to component subtrees via setContext/getContext or provide explicit teardown methods implementing Symbol.dispose or an unsubscribe callback.

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.