Svelte 5 Runes Microtask Re-entrancy & Reactive Dependency Cycle Barrier

--- description: Svelte 5 Runes Microtask Re-entrancy & Reactive Dependency Cycle Barrier - Enforces strict unidirectional data flow and non-cyclical dependency invariants across Svelte 5 custom runes and effect handlers. Prevents catastrophic microtask queue starvation and synchronous infinite re-entrancy caused by bi-directional state mutations across nested reactive contexts. 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-cycle-barrier" --- # Svelte 5 Runes Microtask Re-entrancy & Reactive Dependency Cycle Barrier > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Bi-directional Ping-Pong Synchronization via Cascading $effect State Mutations ## System Constraints You are a Principal Software Architect enforcing runtime determinism and reactive loop barriers in Svelte 5 applications. Your objective is to eradicate infinite microtask recursion, cascading effect ping-pong, and cyclic dependency invalidations across custom runes (.svelte.ts) and component scopes. Enforce unidirectional state propagation, strict usage of untrack(), and single-source-of-truth derived state over bi-directional synchronization. ## Strict Guidelines - Engineers MUST NEVER mutate a reactive $state rune within an $effect block that reads from that same state or a downstream $derived property without an explicit termination gate or untrack() guard. - Engineers MUST ALWAYS implement single-source-of-truth state architecture via $derived or $derived.by instead of synchronizing duplicate $state runes across multiple custom rune instances. - Engineers MUST wrap non-triggering reads in untrack(() => ...) when an effect must read secondary state for write decisions without subscribing to changes from that secondary state. - Code MUST NEVER bind custom rune write-backs bi-directionally across sibling stores; state reconciliation must occur strictly via explicit, discrete action dispatches rather than passive reactive effects. - Custom runes implemented in .svelte.ts files MUST NOT instantiate circular cross-references where Rune A's internal effect mutates Rune B while Rune B's internal effect mutates Rune A. - Components NEVER use $effect.pre or $effect to sync props back to internal state; use $bindable() with explicit boundary validation or functional updater callbacks. ## Bad vs Good Implementations ### Eliminate Cyclic Microtask Explosion in Dual State Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Both $effect routines create a cyclic dependency graph where each state mutation re-schedules the opposite effect into the microtask queue. Even with simple inequality checks, float mismatches, reference mutations, or downstream derived transforms will exhaust the microtask queue and crash the browser tab with 'maximum update depth exceeded'. ```typescript // BAD: Bi-directional effect synchronization triggers microtask re-entrancy and stack exhaustion import { runeState } from './runeState.svelte'; export class SyncCoordinator { primary = $state({ count: 0 }); secondary = $state({ count: 0 }); constructor() { // Effect 1 tracks primary and writes secondary $effect(() => { if (this.primary.count !== this.secondary.count) { this.secondary.count = this.primary.count; } }); // Effect 2 tracks secondary and writes primary, creating an oscillating reactive loop $effect(() => { if (this.secondary.count !== this.primary.count) { this.primary.count = this.secondary.count; } }); } } ``` #### Production Standard (Correct) > **Standard**: The anti-pattern is resolved by replacing dual-synced $state with a single private source of truth (#baseCount) projected outwards via pure $derived accessors. Mutations occur exclusively via explicit methods rather than autonomous reactive watchers, and untrack() is utilized when peripheral data must be read without subscribing. ```typescript // GOOD: Unidirectional flow with single canonical state and explicit action barriers import { untrack } from 'svelte'; export class SyncCoordinator { // Single source of truth #baseCount = $state(0); // Deterministic, non-looping derived projections primary = $derived({ count: this.#baseCount }); secondary = $derived({ count: this.#baseCount }); // Explicit action mutations bypass reactive effect ping-pong entirely setCount(newCount: number): void { if (this.#baseCount === newCount) return; this.#baseCount = newCount; } // Safe side-effecting audit hook reading without subscription re-entrancy logDelta(modifier: number): void { $effect(() => { const current = this.primary.count; untrack(() => { // Read isolated secondary metrics safely without triggering reactive cycles console.info(`Base updated to ${current}, modifier context: ${modifier}`); }); }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Microtask Re-entrancy & Reactive Dependency Cycle Barrier

Svelte 5 Runes Microtask Re-entrancy & Reactive Dependency Cycle Barrier defines an industrial-grade behavioral standard for frontend engineering. Enforces strict unidirectional data flow and non-cyclical dependency invariants across Svelte 5 custom runes and effect handlers. Prevents catastrophic microtask queue starvation and synchronous infinite re-entrancy caused by bi-directional state mutations across nested reactive contexts. 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: Bi-directional Ping-Pong Synchronization via Cascading $effect State Mutations 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	Bi-directional Ping-Pong Synchronization via Cascading $effect State Mutations	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 mutate a reactive $state rune within an $effect block that reads from that same state or a downstream $derived property without an explicit termination gate or untrack() guard.

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.