work work hard work

docs/modules/router/rate-limiting.md

@@ -0,0 +1,39 @@
+# Router · Rate Limiting
+
+This page is the module-level dossier for centralized rate limiting in the Router gateway (`StellaOps.Router.Gateway`).
+
+## What it is
+- A **gateway responsibility** that applies policy and protects both the Router process and upstream microservices.
+- Configurable by environment, microservice, and (for environment scope) by route.
+- Deterministic outputs and bounded metric cardinality by default.
+
+## How it works
+
+### Scopes
+- **for_instance**: in-memory sliding window counters (fast path).
+- **for_environment**: Valkey-backed fixed windows (distributed coordination).
+
+### Inheritance
+- Environment defaults → microservice override → route override.
+- Replacement semantics: a more-specific `rules` set replaces the parent rules.
+
+### Rule stacking
+- Multiple rules on a target are evaluated with AND logic.
+- Denials return the most restrictive `Retry-After` across violated rules.
+
+## Operational posture
+- Valkey failures are fail-open (availability over strict enforcement).
+- Activation gate reduces Valkey load at low traffic.
+- Circuit breaker prevents cascading latency when Valkey is degraded.
+
+## Migration notes (avoid double-limiting)
+- Prefer centralized enforcement at the Router; remove service-level HTTP limiters after Router limits are validated.
+- Roll out in phases (high limits → soft limits → production limits).
+- If a microservice must keep internal protection (e.g., expensive job submission), ensure it is semantically distinct from HTTP admission control and does not produce conflicting client UX.
+
+## Documents
+- Configuration guide: `docs/router/rate-limiting.md`
+- Per-route guide: `docs/router/rate-limiting-routes.md`
+- Ops runbook: `docs/operations/router-rate-limiting.md`
+- Testing: `tests/StellaOps.Router.Gateway.Tests/` and `tests/load/router-rate-limiting-load-test.js`
+