clean-architecture-backend-template/docs/superpowers/plans/2026-07-28-redis-distributed-rate-limit.md

Redis Distributed Rate-Limit Implementation Plan

Repository commit policy is human-only. Do not stage, commit, amend or push.

Task 1: Shared edge rate-limit contract

• Write RED contract/policy tests in shared-contract.
• Add bounded request, algorithm parameters, policy, decision, outcome and port types.
• Reject unsupported dedup/failure claims and unsafe fixed-point arithmetic.
• Verify the shared contract without Redis/Spring types.

Task 2: Structured Redis program execution

• Write RED tests for MULTI reply arity/status/ASCII integer bounds and NOSCRIPT.
• Add bounded structured EVALSHA/EVAL command support without changing scalar primitives.
• Add exact catalog descriptors and resource digests for three rate programs.

Task 3: Three atomic algorithms and semantic provider

• Implement fixed-window Lua and golden vectors.
• Implement sliding-counter Lua with conservative fixed-point arithmetic.
• Implement token-bucket Lua with saturation and exact ceiling retry.
• Add canonical private keys, policy lookup and typed failure mapping.
• Prove denial does not consume quota and revision changes physical state.

Task 4: Dedicated runtime and explicit composition

• Add strict app.rate-limit settings and disabled-zero-side-effect configuration.
• Use a dedicated coordination runtime rather than cache Redis beans/settings.
• Add exact environment registry/application configuration entries.
• Keep readiness at standalone provider R1.

Task 5: Verification and review

• Run shared/Redis/bootstrap focused checks.
• Run architecture/dependency/env/diff gates.
• Run the public-path gate with the final combined change set.
• Run an explicit real Redis lane when a service is available.
• Request independent spec and quality review.

The Redis 7.4 service lane executes the exact-boundary admission after a denied non-consuming request for all three algorithms, excessive clock-regression state immutability, token refill remainder carry, malformed hash classification, cache NX, and observation-token compare-replace. The program manifests therefore declare 7.4 as the minimum qualified version until a lower-version service lane exists.