Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Executing un-bracketed multi-key Lua scripts with static node clients against dynamic Valkey clusters) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants

--- description: Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants - Valkey 8.0 cluster architectures require strict hash-tag co-location for multi-key operations and scripts to prevent CROSSSLOT runtime failures. Applications must leverage cluster-aware connection pooling with automated slot cache invalidation on MOVED/ASK redirects to prevent connection thrashing and deadlocks during primary-replica failovers. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/valkey-8-cluster-topology-slot-atomicity" --- # Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing un-bracketed multi-key Lua scripts with static node clients against dynamic Valkey clusters ## System Constraints You are a Principal Software Architect enforcing Valkey 8.0 cluster standards. Multi-threaded I/O handles pipeline reads and writes off the main execution thread, but execution atomicity and cluster routing invariants remain strictly bound to 16,384 hash slots. Mandate hash tagging for multi-key scripts, deterministic slot redirection handling, and automated cluster topology refresh during failovers. ## Strict Guidelines - Engineers MUST ALWAYS enforce hash tagging ({hashTag}) on all keys accessed within atomic operations, transactions, or Lua scripts to ensure co-location in the same hash slot. - Engineers MUST NOT execute multi-key commands (MGET, MSET, EVAL, FCALL) across heterogeneous keys without an identical curly-bracket hash tag prefix. - Code MUST configure Valkey cluster clients with automated topology refresh triggered by MOVED redirects and dynamic DNS/IP discovery during failover. - Services MUST properly follow the ASK redirection protocol by sending ASKING prior to re-executing redirected commands on the target node without invalidating local slot routing tables. - Components NEVER use non-cluster single-node drivers or hardcoded master endpoints in clustered Valkey environments, as thread I/O buffers will choke on unhandled redirect socket errors. ## Bad vs Good Implementations ### Cross-slot Scripting vs Hash-Tagged Cluster Atomicity with Topology Refresh #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The client instantiates a single-node connection rather than a cluster manager, preventing automatic handling of MOVED/ASK redirects during node failover. Furthermore, KEYS[1] and KEYS[2] lack curly bracket hash tags ({...}), causing Valkey's cluster engine to hash them to separate slots and throw a CROSSSLOT error. ```typescript import Redis from 'ioredis'; // Anti-pattern: Single-node client configured against cluster node, // lacking cluster failover topology refresh and omitting hash tags in multi-key Lua const valkeyClient = new Redis('valkey://primary-node-1:6379'); export async function transferBalance(senderId: string, recipientId: string, amount: number) { const script = ` local senderBal = redis.call('GET', KEYS[1]) if not senderBal or tonumber(senderBal) < tonumber(ARGV[1]) then return -1 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 0 `; // FAILS in Valkey Cluster with: CROSSSLOT Keys in request don't hash to the same slot // Also crashes during cluster failovers due to unhandled MOVED 12182 IP:PORT redirects return await valkeyClient.eval( script, 2, `wallet:${senderId}:balance`, `wallet:${recipientId}:balance`, amount ); } ``` #### Production Standard (Correct) > **Standard**: The production solution uses a resilient Cluster client configured with automated slot discovery and retry limits on MOVED/ASK errors. The keys incorporate hash tags (`{tenant:${tenantId}}`), guaranteeing that both keys hash to the identical slot and maintain script atomicity on Valkey 8.0 without violating cluster constraints. ```typescript import { Cluster } from 'ioredis'; // Production Invariant: Initialize Valkey Cluster client with proactive slot refresh const valkeyCluster = new Cluster( [ { host: 'valkey-seed-0.internal', port: 6379 }, { host: 'valkey-seed-1.internal', port: 6379 }, ], { enableOfflineQueue: false, enableReadyCheck: true, maxRedirections: 16, slotsRefreshTimeout: 2000, redisOptions: { connectTimeout: 5000, autoResubscribe: false, }, } ); export async function transferBalance( tenantId: string, senderId: string, recipientId: string, amount: number ): Promise<number> { // Invariant: Co-locate records into identical hash slots using '{tenantId}' hash-tag const senderKey = `{tenant:${tenantId}}:wallet:${senderId}`; const recipientKey = `{tenant:${tenantId}}:wallet:${recipientId}`; const script = ` local senderBal = redis.call('GET', KEYS[1]) if not senderBal or tonumber(senderBal) < tonumber(ARGV[1]) then return -1 end redis.call('DECRBY', KEYS[1], ARGV[1]) redis.call('INCRBY', KEYS[2], ARGV[1]) return 0 `; const result = await valkeyCluster.eval( script, 2, senderKey, recipientKey, amount ); return Number(result); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants

Valkey 8.0 Multi-Threaded I/O, Topology Failover, and Cluster Script Invariants defines an industrial-grade behavioral standard for backend engineering. Valkey 8.0 cluster architectures require strict hash-tag co-location for multi-key operations and scripts to prevent CROSSSLOT runtime failures. Applications must leverage cluster-aware connection pooling with automated slot cache invalidation on MOVED/ASK redirects to prevent connection thrashing and deadlocks during primary-replica failovers. 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: Executing un-bracketed multi-key Lua scripts with static node clients against dynamic Valkey clusters 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	Executing un-bracketed multi-key Lua scripts with static node clients against dynamic Valkey clusters	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 enforce hash tagging ({hashTag}) on all keys accessed within atomic operations, transactions, or Lua scripts to ensure co-location in the same hash slot.

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.