Svelte 5 Runes SSR Reactive Scope Isolation & Context Encapsulation

--- description: Svelte 5 Runes SSR Reactive Scope Isolation & Context Encapsulation - Enforces strict lexical and contextual isolation for Svelte 5 reactive runes in SSR environments. Module-level $state declarations share memory across concurrent requests in persistent Node.js/edge worker runtimes, causing critical cross-tenant data contamination and memory leaks. Mutable reactive proxies must strictly be encapsulated within request-scoped contexts, factory functions, or component instances. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte5-runes-ssr-scope-isolation-standard" --- # Svelte 5 Runes SSR Reactive Scope Isolation & Context Encapsulation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Level $state Declarations Causing Cross-Request State Pollution in SvelteKit SSR ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes SSR Reactive Scope Isolation Standard. Mandate that all mutable $state declarations are isolated per request via Svelte's Context API or request-scoped factories, preventing cross-tenant data leakage and server memory retention. ## Strict Guidelines - Engineers MUST NEVER declare mutable `$state` or `$state.raw` at the top level of `.svelte.ts` or `.svelte` modules evaluated during SSR. - Engineers MUST encapsulate shared reactive domain logic within class instances or closures instantiated inside component lifecycles or SvelteKit request hooks. - Code MUST use Svelte 5's `setContext` and `getContext` with typed Symbols to propagate state hierarchies securely down the component tree. - Services exposing reactive state MUST provide explicit `create[Domain]Context()` and `use[Domain]Context()` accessors rather than exporting shared singleton instances. - Components NEVER read from or write to un-encapsulated global module variables when executing on the server. - Read-only immutable configurations at module root MUST be declared as plain TypeScript constants without reactive wrappers. ## Bad vs Good Implementations ### Module-Level Shared State vs Context-Isolated Request State in Svelte 5 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-level $state is instantiated once when the module loads into Node/V8 memory. On SSR, every concurrent HTTP request shares the exact same state object reference, leading to cross-tenant data exposure and unpredictable data races. ```typescript // src/lib/stores/auth.svelte.ts // ANTI-PATTERN: Module-level $state is a singleton across all concurrent SSR requests! export interface UserProfile { id: string; tenantId: string; name: string; } // CRITICAL FLAW: Request A sets this proxy; Request B concurrent read leaks Tenant A data! export const currentUserState = $state<{ user: UserProfile | null; isAuthenticated: boolean; }>({ user: null, isAuthenticated: false }); export function setUser(user: UserProfile): void { currentUserState.user = user; currentUserState.isAuthenticated = true; } ``` #### Production Standard (Correct) > **Standard**: Encapsulating $state inside a class coupled with Svelte's `setContext` and `getContext` ensures that each SSR request receives its own isolated instance bound to the request's component tree lifecycle, guaranteeing zero cross-request pollution. ```typescript // src/lib/stores/auth.svelte.ts import { getContext, setContext } from 'svelte'; export interface UserProfile { id: string; tenantId: string; name: string; } export class AuthStore { #user = $state<UserProfile | null>(null); #isAuthenticated = $derived(this.#user !== null); constructor(initialUser: UserProfile | null = null) { this.#user = initialUser; } get user(): UserProfile | null { return this.#user; } get isAuthenticated(): boolean { return this.#isAuthenticated; } setUser(user: UserProfile | null): void { this.#user = user; } } const AUTH_KEY = Symbol('AUTH_STORE_CONTEXT'); export function setAuthStore(initialUser: UserProfile | null = null): AuthStore { const store = new AuthStore(initialUser); return setContext(AUTH_KEY, store); } export function useAuthStore(): AuthStore { const store = getContext<AuthStore | undefined>(AUTH_KEY); if (!store) { throw new Error('useAuthStore must be called within an initialized component hierarchy context.'); } return store; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes SSR Reactive Scope Isolation & Context Encapsulation

Svelte 5 Runes SSR Reactive Scope Isolation & Context Encapsulation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lexical and contextual isolation for Svelte 5 reactive runes in SSR environments. Module-level $state declarations share memory across concurrent requests in persistent Node.js/edge worker runtimes, causing critical cross-tenant data contamination and memory leaks. Mutable reactive proxies must strictly be encapsulated within request-scoped contexts, factory functions, or component instances. 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 Declarations Causing Cross-Request State Pollution in SvelteKit SSR 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 Declarations Causing Cross-Request State Pollution in SvelteKit SSR	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 NEVER declare mutable `$state` or `$state.raw` at the top level of `.svelte.ts` or `.svelte` modules evaluated during SSR.

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.