kitcn 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",
@@ -31,6 +31,8 @@
     "./auth/start/server": "./dist/auth/start/server/index.js",
     "./crpc": "./dist/crpc/index.js",
     "./orm": "./dist/orm/index.js",
+    "./orm/aggregate-index": "./dist/orm/aggregate-index/index.js",
+    "./orm/migrations": "./dist/orm/migrations/index.js",
     "./plugins": "./dist/plugins/index.js",
     "./ratelimit": "./dist/ratelimit/index.js",
     "./ratelimit/react": "./dist/ratelimit/react/index.js",
@@ -73,7 +75,6 @@
     "jose": "^6.1.3",
     "picocolors": "^1.1.1",
     "remeda": "^2.33.6",
-    "svix": "^1.84.1",
     "typescript": "5.9.3",
     "type-fest": "^5.4.4"
   },

package/skills/kitcn/SKILL.md

@@ -171,10 +171,9 @@ Schema rules that matter:
 ### 2) Procedure Builders + Middleware
 
 ```ts
-import { getHeaders } from "kitcn/auth";
+import { getSession } from "kitcn/auth";
 import { CRPCError } from "kitcn/server";
-import { getAuth } from "../functions/generated/auth";
-import { initCRPC } from "../functions/generated/server";
+import { initCRPC, type QueryCtx } from "../functions/generated/server";
 
 const c = initCRPC
   .meta<{
@@ -190,40 +189,42 @@ function requireAuth<T>(user: T | null): T {
   }
   return user;
 }
+async function getSessionUser(ctx: QueryCtx) {
+  const session = await getSession(ctx);
+  if (!session) return null;
+  return await ctx.orm.query.user.findFirst({
+    where: { id: { eq: session.userId } },
+  });
+}
+
 export const publicQuery = c.query.meta({ auth: "optional" });
 export const authQuery = c.query
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   });
 export const authMutation = c.mutation
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 ```
 
 Builder rules that matter:
 
-1. Build `public`, `optional`, `auth`, and `private` procedure families once in `convex/lib/crpc.ts`.
+1. Build `public`, `optional`, `auth`, and `private` procedure families once in `convex/lib/crpc.ts`. Authenticated action builders live in `convex/lib/crpc-action.ts`, the only builder module that imports `getAuth`.
 2. `.meta(...)` is client-visible via generated API metadata. Never put secrets there.
 3. Middleware receives server-only `procedure` info. When procedures are built from your app `generated/server` helper, standard `export const` queries, mutations, and actions infer `module:function` automatically from file path + export name. Use `.name("module:function")` only to override or cover unusual export shapes.
 4. Resolve session/user once in middleware. Do not re-fetch auth state in every procedure.
+   Query/mutation middleware uses `getSession(ctx)` from `kitcn/auth`, which reads the session row
+   directly. Keep `getAuth(ctx)` out of `convex/lib/crpc.ts`: it pulls the whole Better Auth
+   definition and every auth plugin into the static import closure of every procedure module, and
+   Convex has no dynamic `import()` to escape it. Import `getAuth` only in the modules that call
+   `auth.api.*` — `convex/lib/crpc-action.ts`, HTTP routes, and organization/admin mutations.
 5. Shared `c.middleware()` chains preserve mutation writer types on mutation procedures. If the middleware itself performs writes, type it as mutation-only with `c.middleware<MutationCtx>(...)`.
 6. Keep deeper auth/runtime edge cases in `references/setup/server.md` and `references/features/auth*.md`.
 

package/skills/kitcn/references/features/aggregates.md

@@ -9,6 +9,27 @@ Canonical runtime rules:
 - Use `rankIndex` + `rank()` for rankings, random access, sorted pagination
 - `aggregateIndex` and `rankIndex` backfill automatically via `kitcn dev` — no manual trigger wiring needed
 
+## Setup
+
+Aggregate and rank indexes are an optional ORM subsystem. Register it where the ORM is created:
+
+```ts
+import { createOrm } from "kitcn/orm";
+import { aggregateCapability } from "kitcn/orm/aggregate-index";
+
+export const orm = createOrm({ schema, capabilities: [aggregateCapability()] });
+```
+
+`kitcn codegen` writes this into `<functionsDir>/generated/server.ts` for schemas that declare an
+`aggregateIndex` or `rankIndex`, and leaves it out otherwise. Convex bundles everything a module
+statically imports and has no dynamic `import()`, and every procedure module imports
+`generated/server.ts`, so an unused registration would put the aggregate btree in every Convex
+function of the app. Declare the index first, then rerun `kitcn codegen`.
+
+Without the capability, `aggregateIndex`/`rankIndex` schemas and filtered `count()` / `aggregate()`
+/ `groupBy()` / `rank()` / relation `_count` throw a setup error. Unfiltered `count()` and
+`aggregate({ _count: true })` are served by the native Convex count syscall and need nothing.
+
 ## ORM Scalar Metrics
 
 ### `aggregateIndex` Schema Declaration

package/skills/kitcn/references/features/auth-organizations.md

@@ -438,9 +438,9 @@ export const updateOrganization = authMutation
   });
 ```
 
-Use an `authAction` instead of an `authMutation` for any Better Auth endpoint
-that can run external plugin work such as Stripe, Polar, or email delivery.
-Convex mutations cannot call those SDKs.
+Use an `authAction` (from `../lib/crpc-action`) instead of an `authMutation` for
+any Better Auth endpoint that can run external plugin work such as Stripe,
+Polar, or email delivery. Convex mutations cannot call those SDKs.
 
 ### Delete Organization
 

package/skills/kitcn/references/features/auth-polar.md

@@ -435,7 +435,8 @@ export const updateUserPolarCustomerId = privateMutation
 import '../lib/polar-polyfills';
 import { CRPCError } from 'kitcn/server';
 import { z } from 'zod';
-import { authAction, privateMutation, privateQuery } from '../lib/crpc';
+import { privateMutation, privateQuery } from '../lib/crpc';
+import { authAction } from '../lib/crpc-action';
 import { getPolarClient } from '../lib/polar-client';
 import { createPolarSubscriptionCaller } from './generated/polarSubscription.runtime';
 

package/skills/kitcn/references/features/auth.md

@@ -15,7 +15,14 @@ Covers Better Auth integration with Convex: server setup, client hooks, triggers
 | Query/Mutation (`ctx.db`) | Direct DB | No `runQuery`/`runMutation` wrapper |
 | Action/HTTP | HTTP adapter | Uses `ctx.run*` APIs |
 
-**Entrypoint**: `getAuth(ctx)` everywhere (query, mutation, action, HTTP).
+**Entrypoints**:
+
+- `getSession(ctx)` from `kitcn/auth` in queries and mutations, including the shared cRPC auth
+  middleware. It reads the session row directly and keeps the Better Auth definition out of the
+  importing module's static closure.
+- `getAuth(ctx)` only where `auth.api.*` is actually called: `convex/lib/crpc-action.ts`, HTTP
+  routes, and organization/admin mutations. Convex has no dynamic `import()`, so every module that
+  names `getAuth` carries the whole auth definition and its plugins into its evaluation closure.
 
 ## Auth Flow
 

package/skills/kitcn/references/features/http.md

@@ -495,8 +495,18 @@ crpc.http.todos.list.queryOptions({
   searchParams: { limit: "10" },
   headers: { "X-Custom": "value" },
 });
+
+// Override the default 30s staleTime
+crpc.http.todos.list.queryOptions(
+  { searchParams: { limit: "10" } },
+  { staleTime: 0 }
+);
 ```
 
+`queryOptions` defaults to a 30 second `staleTime` so RSC-prefetched entries hydrate
+without an immediate refetch. `refetchOnMount` keeps TanStack's default, so a route
+invalidated while unmounted still refetches.
+
 ### One-Time Fetch
 
 ```ts
@@ -558,6 +568,20 @@ const updateTodo = useMutation(
 );
 ```
 
+### Cache Keys
+
+```ts
+const queryKey = crpc.http.todos.list.queryKey();
+// => ['httpQuery', 'todos.list', {}]
+queryClient.getQueryData(queryKey);
+
+crpc.http.todos.get.queryKey({ params: { id: '123' } });
+// => ['httpQuery', 'todos.get', { params: { id: '123' } }]
+```
+
+`queryKey()` is the exact key `queryOptions()` and RSC prefetching store under, so
+`getQueryData`/`setQueryData` hit. Use `queryFilter()` to match every args variant.
+
 See [Client Methods](#client-methods) in API Reference.
 
 ## RSC Prefetching
@@ -645,4 +669,5 @@ Client args can include `params`, `searchParams`, `form`, custom `fetch`,
 ### Client Methods
 
 Generated clients expose `queryOptions`, `staticQueryOptions`,
-`mutationOptions`, `queryKey`, and `queryFilter`.
+`mutationOptions`, `queryKey` (exact cache key), and `queryFilter` (matches every
+args variant when called without args).

package/skills/kitcn/references/features/ratelimit.md

@@ -81,6 +81,17 @@ For denied reserved fixed-window and token-bucket requests, `reset` is when the
 
 A request larger than every shard's capacity plus finite reservation headroom can never succeed. It returns `reason: 'requestTooLarge'` and `reset: 0` without reading shard state. When only smaller shards cannot serve a request, they are excluded from retry calculations. Fresh, full, and partial snapshot projections preserve permanent denial as `retryAfter: Infinity`, and the React hook reports `ok: false` without scheduling a retry timer. Reduce `count`, reduce `shards`, or raise the configured capacity.
 
+## Protection / deny list — delta from parity
+
+With `enableProtection: true`, failures are counted per identifier, ip, userAgent, and country.
+
+- A value's block is cached for up to 24 h once it reaches `denyListThreshold` **within a rolling 10 minute window**. Failures paced wider than that window decay, so a shared NAT/carrier IP is not blocked by unrelated failures accumulated over days.
+- Protection state is a bounded in-memory LRU. Failure histories are evicted before blocks, active blocks refresh on use, and the coldest block can be evicted above 4,096 simultaneous blocked values per prefix. Evicted values fall through to the database-backed limiter.
+- A success clears the **identifier** counter only. ip/userAgent counters are attacker-supplied; clearing them on success would let a caller loop `threshold - 1` failures plus one success indefinitely, or reset a victim's counter by forging their user-agent.
+- State is module-scope memory: at most 4096 tracked values per prefix with least-recently-hit eviction, and values over 128 characters stored truncated. It is per-isolate, so it does not survive a cold start and is not shared across function entries.
+- Increments are not rolled back when Convex retries a mutation after a write conflict, so a value can count slightly more failures than it was served.
+- `pickDeniedValue` runs before any database read, so a blocked value is rejected without touching `ratelimitState`.
+
 ## Convex constraints
 
 - `blockUntilReady()` needs `setTimeout`, so it only runs in actions or non-Convex runtimes. It throws with that guidance inside queries and mutations. `limit()` and `check()` never touch timers.

package/skills/kitcn/references/features/react.md

@@ -28,7 +28,7 @@ export const { CRPCProvider, useCRPC, useCRPCClient } = createCRPCContext({
 
 ### QueryClient
 
-cRPC auto-sets `staleTime: Infinity`, `refetch*: false` per query (Convex pushes via WebSocket — never stale).
+cRPC auto-sets `staleTime: Infinity`, `refetch*: false` per query (Convex pushes via WebSocket — never stale). `crpc.http.*` routes are pull-model instead: `staleTime: 30_000` with `refetchOnMount` left at TanStack's default, so RSC-prefetched data hydrates but an invalidated route still refetches.
 
 ```ts
 // src/lib/convex/query-client.ts

package/skills/kitcn/references/setup/auth.md

@@ -331,11 +331,10 @@ Again: printed payload only. You still need to set the env manually.
 After non-auth baseline is green, replace `convex/lib/crpc.ts` with this auth-aware variant:
 
 ```ts
-import { getHeaders } from "kitcn/auth";
+import { getSession } from "kitcn/auth";
 import { CRPCError } from "kitcn/server";
 
-import { getAuth } from "../functions/generated/auth";
-import { initCRPC } from "../functions/generated/server";
+import { initCRPC, type QueryCtx } from "../functions/generated/server";
 
 const c = initCRPC
   .meta<{
@@ -366,6 +365,14 @@ function requireAuth<T>(user: T | null): T {
   return user;
 }
 
+async function getSessionUser(ctx: QueryCtx) {
+  const session = await getSession(ctx);
+  if (!session) return null;
+  return await ctx.orm.query.user.findFirst({
+    where: { id: { eq: session.userId } },
+  });
+}
+
 export const publicQuery = c.query.meta({ auth: "optional" });
 export const publicAction = c.action;
 export const publicMutation = c.mutation;
@@ -377,28 +384,17 @@ export const privateAction = c.action.internal();
 export const optionalAuthQuery = c.query
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
 
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 
 export const authQuery = c.query
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   })
   .use(roleMiddleware);
@@ -406,43 +402,21 @@ export const authQuery = c.query
 export const optionalAuthMutation = c.mutation
   .meta({ auth: "optional" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
+    const user = await getSessionUser(ctx);
 
     return next({
-      ctx: {
-        ...ctx,
-        user: session?.user ?? null,
-        userId: session?.user?.id ?? null,
-      },
+      ctx: { ...ctx, user, userId: user?.id ?? null },
     });
   });
 
 export const authMutation = c.mutation
   .meta({ auth: "required" })
   .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
+    const user = requireAuth(await getSessionUser(ctx));
     return next({ ctx: { ...ctx, user, userId: user.id } });
   })
   .use(roleMiddleware);
 
-export const authAction = c.action
-  .meta({ auth: "required" })
-  .use(async ({ ctx, next }) => {
-    const auth = getAuth(ctx);
-    const session = await auth.api.getSession({
-      headers: await getHeaders(ctx),
-    });
-    const user = requireAuth(session?.user ?? null);
-    return next({ ctx: { ...ctx, user, userId: user.id } });
-  });
-
 export const publicRoute = c.httpAction;
 export const authRoute = c.httpAction.use(async ({ ctx, next }) => {
   const identity = await ctx.auth.getUserIdentity();
@@ -480,6 +454,42 @@ export const optionalAuthRoute = c.httpAction.use(async ({ ctx, next }) => {
 export const router = c.router;
 ```
 
+### 6.9.1 Authenticated action builders
+
+Authenticated actions live in their own module. Actions have no `ctx.db`, so they resolve the
+session through `auth.api.getSession` instead of `getSession(ctx)`. `getAuth` carries the whole
+Better Auth definition and every plugin into the static import closure of whatever imports it, and
+Convex has no dynamic `import()`, so it stays out of `convex/lib/crpc.ts` — the module every
+procedure imports.
+
+Skip this file if the app has no authenticated actions.
+
+**Create:** `convex/lib/crpc-action.ts`
+
+```ts
+import { getHeaders } from "kitcn/auth";
+import { CRPCError } from "kitcn/server";
+
+import { getAuth } from "../functions/generated/auth";
+import { publicAction } from "./crpc";
+
+export const authAction = publicAction
+  .meta({ auth: "required" })
+  .use(async ({ ctx, next }) => {
+    const auth = getAuth(ctx);
+    const session = await auth.api.getSession({
+      headers: await getHeaders(ctx),
+    });
+    const user = session?.user;
+    if (!user) {
+      throw new CRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
+    }
+    return next({ ctx: { ...ctx, user, userId: user.id } });
+  });
+```
+
+Import `authAction` from `../lib/crpc-action`. Every other builder comes from `../lib/crpc`.
+
 ### 6.10 Auth sign-in gate (required before Section 7+ and all optional modules/plugins)
 
 Do not continue until all checks below pass:

package/skills/kitcn/references/setup/index.md

@@ -755,7 +755,7 @@ domain depth: `orm.md`, `http.md`, `react.md`, `aggregates.md`,
 | HTTP calls fail but queries work                                                      | `.site` URL missing or wrong                                                                    | Set `NEXT_PUBLIC_CONVEX_SITE_URL` correctly                                                                                                                                                 |
 | Auth works locally but fails in prod                                                  | JWKS not pushed                                                                                 | Run `bunx kitcn env push --prod`                                                                                                                                                    |
 | Sign-in fails on `/auth` (loop, no session, or immediate sign-out)                    | Auth route/env/provider wiring mismatch                                                         | Recheck Sections 6.5-6.7 (`authMiddleware`, route registration, env push), verify provider credentials/URLs, then rerun Section 11.3                                                        |
-| `UNAUTHORIZED` on protected procedures                                                | auth middleware not attaching `userId`                                                          | Ensure `getAuth(ctx)` + `getHeaders(ctx)` session lookup is in middleware                                                                                                                   |
+| `UNAUTHORIZED` on protected procedures                                                | auth middleware not attaching `userId`                                                          | Ensure the `getSession(ctx)` session lookup is in middleware                                                                                                                   |
 | `ctx.orm` missing in handlers                                                         | Generated `initCRPC` not used                                                                   | Use `initCRPC` from `../functions/generated/server` — ORM context is pre-wired                                                                                                              |
 | `Property 'insert'/'update' does not exist on type 'OrmReader'`                       | Using query context for mutations                                                               | Ensure mutation handlers use `publicMutation` / `protectedMutation` builders                                                                                                                |
 | `useCRPC must be used within CRPCProvider`                                            | Provider chain not mounted around route tree                                                    | Wrap app with `AppConvexProvider` and verify `CRPCProvider` is inside QueryClientProvider (Section 7.4 / 8.A.4)                                                                          |

package/skills/kitcn/references/setup/server.md

@@ -175,7 +175,8 @@ export const router = c.router;
 Phase ordering rule:
 
 1. Keep this non-auth baseline until Section 11.2 fully passes.
-2. Only then replace this file with the auth-aware variant in Section 6.9.
+2. Only then replace this file with the auth-aware variant in Section 6.9, and add
+   `convex/lib/crpc-action.ts` from Section 6.9.1 if the app has authenticated actions.
 
 ### 5.4 Shared API/type helpers (generated)
 
@@ -356,7 +357,7 @@ Rate limiting is opt-in: scaffold the full starter once.
 bunx kitcn add ratelimit
 ```
 
-This creates `convex/lib/plugins/ratelimit/schema.ts`, `convex/lib/plugins/ratelimit/plugin.ts`, and registers `ratelimitExtension()` in `convex/functions/schema.ts`.
+This creates `convex/lib/plugins/ratelimit/schema.ts`, `convex/lib/plugins/ratelimit/plugin.ts`, `convex/functions/plugins/ratelimit.ts`, and registers `ratelimitExtension()` in `convex/functions/schema.ts`.
 
 ```ts
 import { defineSchema } from "kitcn/orm";
@@ -365,12 +366,18 @@ import { ratelimitExtension } from "../lib/plugins/ratelimit/schema";
 export default defineSchema(tables).extend(ratelimitExtension());
 ```
 
-Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes and reserve `.meta({ ratelimit: ... })` for named overrides. Runtime accounting (`shards`, `check()`, snapshots, read accuracy) lives in `features/ratelimit.md`.
+Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes; the starter's `interactive` bucket demonstrates a named `.meta({ ratelimit: ... })` override. Rename or remove it to match the application. Runtime accounting (`shards`, `check()`, snapshots, read accuracy) lives in `features/ratelimit.md`.
 
 Use `RatelimitPlugin` from `kitcn/ratelimit`:
 
 ```ts
-import { MINUTE, Ratelimit, RatelimitPlugin } from "kitcn/ratelimit";
+import {
+  type LimitRequest,
+  MINUTE,
+  Ratelimit,
+  RatelimitPlugin,
+  SECOND,
+} from "kitcn/ratelimit";
 import type { MutationCtx } from "../../../functions/generated/server";
 
 const fixed = (rate: number) => Ratelimit.fixedWindow(rate, MINUTE);
@@ -381,6 +388,11 @@ export const ratelimitBuckets = {
     free: fixed(60),
     premium: fixed(200),
   },
+  interactive: {
+    public: Ratelimit.fixedWindow(3, 30 * SECOND),
+    free: Ratelimit.fixedWindow(3, 30 * SECOND),
+    premium: Ratelimit.fixedWindow(3, 30 * SECOND),
+  },
 } as const;
 
 type RatelimitTier = keyof (typeof ratelimitBuckets)["default"];
@@ -415,14 +427,27 @@ async function getRequestSignals(ctx: RatelimitCtx) {
   };
 }
 
+function getRequestIdentifier(
+  user: RatelimitUser | null,
+  signals: LimitRequest | undefined
+) {
+  if (user) return user.id;
+  return signals?.ip ? `ip:${signals.ip}` : "ip:unknown";
+}
+
 export const ratelimit = RatelimitPlugin.configure({
   buckets: ratelimitBuckets,
   getBucket: ({ meta }: { meta: RatelimitMeta }) => meta.ratelimit ?? "default",
   getUser: ({ ctx }: { ctx: RatelimitCtx }) => ctx.user ?? null,
-  getIdentifier: ({ user }: { user: RatelimitUser | null }) =>
-    user?.id ?? "anonymous",
   getTier: getUserTier,
   getSignals: ({ ctx }: { ctx: RatelimitCtx }) => getRequestSignals(ctx),
+  getIdentifier: ({
+    user,
+    signals,
+  }: {
+    user: RatelimitUser | null;
+    signals: LimitRequest | undefined;
+  }) => getRequestIdentifier(user, signals),
   prefix: ({ bucket, tier }) => `ratelimit:${bucket}:${tier}`,
   failureMode: "closed",
   enableProtection: true,
@@ -432,6 +457,12 @@ export const ratelimit = RatelimitPlugin.configure({
 
 Use `ctx.meta.getRequestMetadata()` on Convex 1.38.0+ for IP/user-agent signals in mutation rate limits. Convex also exposes this metadata in actions; route action-side enforcement through a mutation when database-backed ratelimit state is required.
 
+The identifier is the partition key: every request resolving to the same string shares one budget and one `ratelimitState` document. Never key unauthenticated traffic to a constant — `fixedWindow(30, MINUTE)` under a constant identifier is 30 req/min for the whole deployment, and 30 consecutive denials arm a 24 h deny-list block against that constant. `getSignals` runs once per request, before `getIdentifier`, so keying on `signals.ip` costs no extra syscall.
+
+Plan for the two consequences: shared NAT/CGNAT addresses share a budget, and calls without request metadata all land on `ip:unknown`. One `ratelimitState` row exists per identifier per `bucket:tier`; run the scaffolded `plugins/ratelimit:cleanup` private mutation on demand, with `olderThanMs` longer than every configured rate-limit window, and repeat while it returns `hasMore: true`.
+
+`RatelimitPlugin.configure` also forwards `failureMode`, `timeout`, `enableProtection`, `denyListThreshold`, `denyList`, `dynamicLimits`, and `ephemeralCache` to the limiter.
+
 ### 9.5 Scheduling gate
 
 Create `convex/functions/crons.ts` with `cronJobs()` and use `caller.schedule.now/after/at` in mutations/actions for delayed procedure jobs (`ctx.scheduler.*` only for raw `internal.*` functions).