Add a first-party rate limiter package

.env.example

@@ -43,8 +43,9 @@
 # REDIS_DB=1
 # REDIS_TEST_DB_MIN=1
 # REDIS_TEST_DB_MAX=14
-# Database 15 is excluded from the worker range. Reverb state and secondary
-# Redis tests share it safely because those tests use unique keys and never flush it.
+# Database 15 is excluded from the worker range for Reverb integration servers
+# and tests that explicitly request the secondary database. InteractsWithRedis
+# remaps every named application connection, including reverb, to its worker database.
 # REDIS_REVERB_DB=15
 # REDIS_TEST_SECONDARY_DB=15
 

.github/workflows/redis.yml

@@ -64,9 +64,12 @@ jobs:
         # Cap ParaTest's auto-detected workers: database 1 is reserved via
         # REDIS_TEST_SECONDARY_DB, leaving 15 worker databases in the 0-15 range.
         run: |
-          vendor/bin/paratest --max-processes=15 tests/Integration/Auth
+          vendor/bin/paratest --max-processes=15 tests/Integration/Auth/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Cache/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Horizon
+          vendor/bin/paratest --max-processes=15 tests/Integration/Http/Redis
+          vendor/bin/paratest --max-processes=15 tests/Integration/Queue/Redis
+          vendor/bin/paratest --max-processes=15 tests/Integration/RateLimiter/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Redis
 
   valkey_9:
@@ -125,7 +128,10 @@ jobs:
         # Cap ParaTest's auto-detected workers: database 1 is reserved via
         # REDIS_TEST_SECONDARY_DB, leaving 15 worker databases in the 0-15 range.
         run: |
-          vendor/bin/paratest --max-processes=15 tests/Integration/Auth
+          vendor/bin/paratest --max-processes=15 tests/Integration/Auth/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Cache/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Horizon
+          vendor/bin/paratest --max-processes=15 tests/Integration/Http/Redis
+          vendor/bin/paratest --max-processes=15 tests/Integration/Queue/Redis
+          vendor/bin/paratest --max-processes=15 tests/Integration/RateLimiter/Redis
           vendor/bin/paratest --max-processes=15 tests/Integration/Redis

AGENTS.md

@@ -20,6 +20,7 @@ When working on Hypervel, start from this frame:
 - Per-request state must live in coroutine-scoped storage (CoroutineContext), not process-global state.
 - Laravel source is the default parity reference, but Laravel internals often assume per-request bootstrap and are not optimized to take advantage of static caching of immutable state.
 - Hyperf source can be useful for Swoole/coroutine behavior, but Hyperf container/config/listener patterns are not the target architecture.
+- Laravel's rate limiter lives under `Illuminate\Cache`; Hypervel's canonical implementation is the dedicated `hypervel/rate-limiter` package under `Hypervel\RateLimiter`. It uses typed policies and dedicated atomic stores and has no `Hypervel\Cache` alias or primitive counter API. Use this package directly when porting rate-limited Laravel code.
 
 ## Repository Layout and Commands
 
@@ -33,7 +34,7 @@ Key paths:
 | `src/testbench/` | Hypervel's testbench package (port of `orchestra/testbench`). Contains `TestCase`, attributes (`WithConfig`, `WithMigration`), and bootstrap logic. Part of the monorepo, not a vendor dependency. |
 | `src/testbench/hypervel/` | Committed Hypervel app skeleton. On bootstrap, testbench clones this to a disposable temp directory (`/tmp/hypervel-components-testbench-{token}-{pid}/`) and points `BASE_PATH` at the clone — tests that write files under `BASE_PATH` (generated providers, migrations, fixtures, etc.) hit the temp copy, not this committed path. The clone is deleted on shutdown and stale copies from crashed runs are cleaned up. Testbench also exports `TESTBENCH_BASE_PATH` so subprocesses can locate the active runtime. |
 | `src/testbench/workbench/` | Committed shared test fixtures (NOT cloned). Subdirs are psr-4-mapped from the monorepo root as `Workbench\App\*`, `Workbench\Database\Factories\*`, `Workbench\Database\Seeders\*` so multiple tests can reuse the same models/factories/seeders without redefining them. Not the runtime app — that's the disposable clone of `src/testbench/hypervel/`. |
-| `docs/ai/` | Supplementary agent guides, including `porting-hyperf.md` (Hyperf conversion mechanics) and `differences-vs-laravel.md` (user-facing Laravel differences). |
+| `docs/ai/` | Supplementary agent guides, including `porting-hyperf.md` (Hyperf conversion mechanics). |
 | `docs/todo.md` | Tracked gaps and improvements worth doing. |
 
 ### Running tests
@@ -119,6 +120,7 @@ The Working rules and the Avoid overengineering rules apply to all work in this
 
 ### Working rules
 
+- **Never use subagents without explicit user consent** — Do not spawn or delegate work to subagents unless the user explicitly requests or approves their use.
 - **Avoid bulk modification tools** — tools like `sed` and `replace_all` often have unwanted side effects. Never use bulk modification tools without explicit user approval; prefer manual edits. When approved, run them in multiple passes that each target long, exact, case-sensitive strings to avoid accidental changes.
 - **One file at a time** — never work on multiple files simultaneously. This governs manual editing; package-manager and formatter runs may touch multiple files.
 - **Never use Write to overwrite files** — always use Edit for targeted updates.
@@ -200,8 +202,6 @@ Build complete, long-term solutions, not MVPs or local workarounds. A broad chan
 
 Hypervel's container keeps Laravel's API surface — `bind()`, `singleton()`, `scoped()`, `instance()`, aliases, contextual bindings — with resolution adapted for long-lived Swoole workers. `make()` and `get()` resolve identically; `get()` is just the PSR-compliant exception wrapper. Use `make()`, and use it instead of array access too: `offsetGet()` always returns `mixed`, while `make()` carries class-string generics phpstan can follow, `make()` can take parameters, and `$app[$key] = $value` is a hidden `bind()`. Converting `$app['...']` in ported code to `make()` is an approved modernization (see Policy under Porting Packages). `Container::getInstance()` auto-creates via `??= new static()`, so it always returns a container.
 
-A user-facing summary of these differences lives in `docs/ai/differences-vs-laravel.md` — keep it consistent with this section when container behavior changes.
-
 ### Resolution semantics vs Laravel
 
 The critical difference: **unbound concrete classes are auto-singletoned**. In Laravel, `make()` on a class with no binding builds a fresh instance every call. In Hypervel, the first resolution caches the instance (in `$autoSingletons`) for the worker lifetime — in Swoole's long-running process model services are stateless singletons by design, and re-creating them on every resolution wastes CPU and memory. Explicit bindings override this (bound classes follow their binding type), and `SelfBuilding` classes are excluded.
@@ -376,7 +376,7 @@ Test supported public behavior, meaningful branches, verified regressions, and r
 
 ### Directory layout
 
-All tests live in `tests/{PackageName}/` (PascalCase). Tests that require external services go in `tests/Integration/{PackageName}/` — see Integration tests below.
+All tests live in `tests/{PackageName}/` (PascalCase). Tests that require external services go in `tests/Integration/{PackageName}/` — see Integration tests below. When only some integration tests for a package require one service, group them in `tests/Integration/{PackageName}/{ServiceName}/`. When every integration test for the package requires that service, keep them directly in the package directory.
 
 Package-specific tests that require one database driver go in `tests/Integration/{PackageName}/Database/{Postgres|MySql|MariaDb|Sqlite}/`. The database workflows discover these directories by convention.
 
@@ -644,6 +644,8 @@ If a test fails with a type error, the source code type may be wrong — not the
 
 Tests that require external services (databases, Redis, HTTP servers, search engines) that can't run in every environment go in `tests/Integration/{PackageName}/`. The exception is tests that call freely-available external APIs (e.g., the Guzzle tests hitting the public Pokemon API) — those can stay in regular `tests/` since they need no local service configuration.
 
+Service workflows enumerate their test directories explicitly. Adding a service-specific directory requires adding it to the matching workflow; using the service trait provides isolation and skip behavior but does not make CI discover the test.
+
 #### External service test traits
 
 Integration tests that use an external service must use that service's test trait.
@@ -677,8 +679,8 @@ Each integration group has its own workflow file in `.github/workflows/`:
 | Workflow | Runs | Directory |
 |----------|------|-----------|
 | `engine.yml` | HTTP test servers | `tests/Integration/Engine`, `tests/Integration/HttpServer` |
-| `databases.yml` | MySQL, MariaDB, PostgreSQL, SQLite | `tests/Integration/Database` |
-| `redis.yml` | Redis, Valkey | `tests/Integration/Cache/Redis`, `tests/Redis/Integration` |
+| `databases.yml` | MySQL, MariaDB, PostgreSQL, SQLite | `tests/Integration/Database`, `tests/Integration/*/Database/*` |
+| `redis.yml` | Redis, Valkey | `tests/Integration/Auth/Redis`, `tests/Integration/Cache/Redis`, `tests/Integration/Horizon`, `tests/Integration/Http/Redis`, `tests/Integration/Queue/Redis`, `tests/Integration/RateLimiter/Redis`, `tests/Integration/Redis` |
 | `scout.yml` | Meilisearch, Typesense | `tests/Integration/Scout/*` |
 
 When adding integration tests that need a new service, either add them to an existing workflow or create a new one. The workflow must spin up the service container and set the appropriate env vars.

composer.json

@@ -67,6 +67,7 @@
             "Hypervel\\Process\\": "src/process/src/",
             "Hypervel\\Prompts\\": "src/prompts/src/",
             "Hypervel\\Queue\\": "src/queue/src/",
+            "Hypervel\\RateLimiter\\": "src/rate-limiter/src/",
             "Hypervel\\Redis\\": "src/redis/src/",
             "Hypervel\\Reverb\\": "src/reverb/src/",
             "Hypervel\\Routing\\": "src/routing/src/",
@@ -261,6 +262,7 @@
         "hypervel/process": "self.version",
         "hypervel/prompts": "self.version",
         "hypervel/queue": "self.version",
+        "hypervel/rate-limiter": "self.version",
         "hypervel/redis": "self.version",
         "hypervel/reflection": "self.version",
         "hypervel/routing": "self.version",
@@ -349,6 +351,7 @@
                 "Hypervel\\Grpc\\GrpcServiceProvider",
                 "Hypervel\\Pipeline\\PipelineServiceProvider",
                 "Hypervel\\Queue\\QueueServiceProvider",
+                "Hypervel\\RateLimiter\\RateLimiterServiceProvider",
                 "Hypervel\\Redis\\RedisServiceProvider",
                 "Hypervel\\Reverb\\ReverbServiceProvider",
                 "Hypervel\\Routing\\RoutingServiceProvider",