Svelte 5 Runes Reactive Graph Boundary & Signal Isolation Standard

--- description: Svelte 5 Runes Reactive Graph Boundary & Signal Isolation Standard - Enforces strict isolation of the Svelte 5 rune reactive dependency graph across component and module boundaries. Precludes deep-state leakage, cyclic signal dependencies, and uncontained micro-frontend re-renders by enforcing encapsulation of mutable $state, pure derived computations via $derived.by, and controlled boundary mutations using explicit accessors or getters. 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-runes-reactive-graph-boundary-standard" --- # Svelte 5 Runes Reactive Graph Boundary & Signal Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw $state Across Module Boundaries Causing Cascading Cross-Micro-Frontend Re-Renders and Graph Poisoning ## System Constraints You are a Principal Frontend Architect enforcing the Svelte 5 Runes Reactive Graph Boundary Standard. You must mandate strict signal isolation across components, modules, and micro-frontends. Svelte 5 runes ($state, $derived, $effect) operate on a fine-grained push-pull signal graph; leaking mutable $state proxies outside encapsulation boundaries, triggering mutations within $derived or $derived.by, or registering untracked side-effects in cross-boundary stores breaks architectural isolation, causes exponential invalidations, and introduces memory leaks. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate mutable `$state` within `.svelte.ts` domain classes or closures, exposing only read-only signals (using `$derived` or explicit getter properties) and explicit mutation methods. - Engineers MUST NOT export raw mutable `$state` variables directly from shared `.svelte.ts` modules to foreign micro-frontends or consuming components. - Engineers MUST use `$derived.by()` exclusively for pure, deterministic state derivations and NEVER trigger mutations, I/O operations, or async promises inside a derived computation. - Engineers MUST use `untrack()` inside `$effect` blocks when reading secondary state signals that should not register as upstream reactive graph dependencies. - Components NEVER capture external $state mutations directly through props without explicit event-driven callbacks or binding contracts (`$bindable()`), ensuring unidirectional data flow across boundary layers. - Services MUST clean up cross-boundary event registrations and subscriptions using the teardown return function of `$effect` or Svelte's `onDestroy` lifecycle equivalent. ## Bad vs Good Implementations ### Module Boundary State Encapsulation vs Raw State Export #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting raw $state creates an unconstrained global reactive graph where any consumer can directly mutate deep object properties, triggering cascade invalidations across unrelated micro-frontends and destroying boundary encapsulation. ```typescript // shared-cart.svelte.ts (Anti-Pattern: Raw mutable state exported across boundaries) export const cartState = $state({ items: [] as Array<{ id: string; price: number; quantity: number }>, currency: 'USD' }); // Consuming code mutates shared state directly without isolation boundaries // ConsumerComponent.svelte: // cartState.items.push({ id: 'item-1', price: 10, quantity: 1 }); ``` #### Production Standard (Correct) > **Standard**: Using private class fields with Svelte 5 runes encapsulates signal state. Consumers can read reactive derived values and getters safely while mutations are constrained to deterministic domain methods. ```typescript // shared-cart.svelte.ts (Production Standard: Encapsulated State Class) export class CartStore { #items = $state<Array<{ id: string; price: number; quantity: number }>>([]); #currency = $state<string>('USD'); // Expose fine-grained read-only projections get items() { return this.#items; } get currency() { return this.#currency; } totalCost = $derived.by(() => this.#items.reduce((sum, item) => sum + (item.price * item.quantity), 0) ); // Explicit boundary mutation contracts addItem(item: { id: string; price: number; quantity: number }): void { this.#items = [...this.#items, item]; } removeItem(id: string): void { this.#items = this.#items.filter((item) => item.id !== id); } } export const cartStore = new CartStore(); ``` ### Isolating Graph Dependencies in $effect via untrack() #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The $effect unconditionally registers sessionToken in its reactive graph. Any refresh of the session token unnecessarily re-runs the page-view tracking logic, polluting analytics and inducing side-effect thrashing. ```typescript // AnalyticsTracker.svelte (Anti-Pattern: Cyclic or cascading invalidations) let activeTab = $state('home'); let sessionToken = $state('uuid-123'); $effect(() => { // sessionToken shouldn't trigger page tracking, but creates an active dependency here fetch(`/api/log?tab=${activeTab}&token=${sessionToken}`); }); ``` #### Production Standard (Correct) > **Standard**: Using untrack() explicitly isolates auxiliary signals from the fine-grained dependency graph, ensuring the side effect strictly reacts to activeTab invalidations. ```typescript // AnalyticsTracker.svelte (Production Standard: Isolated Dependency Tracking) import { untrack } from 'svelte'; let activeTab = $state('home'); let sessionToken = $state('uuid-123'); $effect(() => { const currentTab = activeTab; // Explicit reactive trigger untrack(() => { // sessionToken is read without adding it to this effect's dependency graph navigator.sendBeacon(`/api/log?tab=${encodeURIComponent(currentTab)}&token=${encodeURIComponent(sessionToken)}`); }); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Graph Boundary & Signal Isolation Standard

Svelte 5 Runes Reactive Graph Boundary & Signal Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of the Svelte 5 rune reactive dependency graph across component and module boundaries. Precludes deep-state leakage, cyclic signal dependencies, and uncontained micro-frontend re-renders by enforcing encapsulation of mutable $state, pure derived computations via $derived.by, and controlled boundary mutations using explicit accessors or getters. 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: Leaking Raw $state Across Module Boundaries Causing Cascading Cross-Micro-Frontend Re-Renders and Graph Poisoning 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	Leaking Raw $state Across Module Boundaries Causing Cascading Cross-Micro-Frontend Re-Renders and Graph Poisoning	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 encapsulate mutable `$state` within `.svelte.ts` domain classes or closures, exposing only read-only signals (using `$derived` or explicit getter properties) and explicit mutation methods.

Engineers MUST ALWAYS encapsulate mutable `$state` within `.svelte.ts` domain classes or closures, exposing only read-only signals (using `$derived` or explicit getter properties) and explicit mutation methods.

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.