feat: adaptive per-wallet query cost governor with rolling Redis budget

[wheval]

Summary

Implements the query cost governor from #755: assigns a cost unit to every request, tracks a rolling per-caller spend in a Redis sorted set, and rejects requests that would push the caller over budget with 429 query_budget_exceeded.

Design notes worth reading before reviewing

Identity. Most of the routes this is meant to protect (GET /creators, GET /creators/:id/holders, search) are public reads with no wallet-auth middleware in front of them today — unlike the mutating routes requireStellarSignature() already covers. So "per-wallet" only applies when the caller sends a valid JWT (the same one requireJwtAuth checks); the governor decodes it without rejecting when absent/invalid (unlike requireJwtAuth), and falls back to an IP-keyed budget for anonymous callers. Without this, the governor would only ever protect already-authenticated write routes, not the public read routes the issue actually names.

Cost map routes. The issue's own examples (GET /search, GET /creators/:id/history) don't exist verbatim in this codebase. Substituted the closest real equivalents: GET /keys/search, GET /creators/:id/stats. See src/constants/query-cost.constants.ts.

Matching, not req.route. The governor is mounted once, globally, ahead of every route group in src/modules/index.ts — at that point Express hasn't resolved the specific route yet, so req.route.path isn't populated. Cost-map patterns are matched against req.path directly via a small pattern compiler in src/utils/query-cost.utils.ts.

Concurrency. Evicts expired entries, sums the caller's remaining cost, and only admits the request if it fits the budget — true check-before-append (matching the issue's literal wording), not append-then-check. This is two Redis round trips rather than one atomic Lua script; under truly concurrent requests from the same caller there's a small window where slightly more than budget could be admitted. That's the same non-atomic tradeoff wallet-rate-limit.middleware.ts already accepts for its own sliding-window limiter — matched that existing rigor level rather than introducing a different one for this one feature. Documented inline.

Admin bypass / reset endpoint. POST /internal/qcost/reset/:walletAddress added to the existing sequencerRouter (already mounted at /internal with no app-level auth guard — network isolation only, same convention as the existing /internal/sequencer/clear-drift/:creatorWallet).

Acceptance criteria

• Cost map applied per route with limit param multiplier
• Rolling budget tracked in Redis with window eviction
• Budget exceeded returns 429 with Retry-After and X-Query-Budget-Reset
• X-Query-Cost / X-Query-Budget-Remaining headers on every authenticated response
• Admin wallets (QUERY_COST_ADMIN_WALLETS, comma-separated) bypass the governor
• Budget resets correctly after the rolling window (covered by a real-timer integration test)

Testing

26 new tests across query-cost.utils.test.ts, query-cost-governor.middleware.test.ts, query-cost.controllers.test.ts — all passing (npx jest <files>). Covers: exact-budget admission, over-budget throttling with correct headers, limit-multiplied cost, window expiry, admin-wallet bypass, internal-service-call bypass, /health//internal/qcost exemption, and fail-open on both "Redis unavailable" and "Redis command throws".

Verified, not just assumed

• Full-repo npx tsc --noEmit diff against a clean main checkout: identical 78 pre-existing errors before and after this change (confirmed via git stash -u).
• Update: pnpm build was failing on main itself (unrelated to the query-cost governor), for the reasons below — since it was blocking this PR's CI regardless, fixed it in a follow-up commit rather than leaving it red:
  • redis.utils.ts exported redis/getRedis as an alias to a function returning Redis | null; ~13 call sites across subscriptions, key price-moved pub/sub, sequencer locking, and the supply-drift guard used it without a null check. Added getRequiredRedisClient() (throws instead of silently no-opping) for these hard-dependency call sites, and the connectRedis() export server.ts already imports and calls at startup but never existed.
  • wallets.routes.ts (jwtAuth, httpGetWalletFollowing) and keys.routes.ts (getKeyProposals/getKeySupply, ProposalKeyNotFoundError/SupplyKeyNotFoundError) referenced real, already-implemented functions with no imports at all.
  • jwt.middleware.ts's dead, unused signJwt referenced a nonexistent JWT_EXPIRES_IN config field — removed rather than inventing a second, redundant token-expiry config alongside the real one in jwt.utils.ts. One test file did import it with a token shape that was already incompatible with the auth middleware it was testing against — switched to the real signWalletAccessToken.
  • Added the config schema fields real code already referenced (SSE_* subscription settings, STELLAR_AUTH_SECRET).
  • Prisma schema drift: walletCreatorFollow was never declared in schema.prisma even though its migration was already applied (added the model, mapped to the existing table); dividend.service.ts ordered by a field name that was never a real column (fixed to the actual column); KeyOwnership.lastBuyAt was genuinely never migrated (added the column + a real migration).
  • Four integration test files imported from vitest (this repo uses Jest) and three of those also imported a createServer from a module that doesn't exist — switched to the same import app from '../../app' pattern every other integration test in the repo already uses, plus a few incidental Prisma create() calls missing required fields.
  • Verified with the exact three commands .github/workflows/ci.yml's verify job runs, in order: npx tsc (0 errors, was 75), pnpm build, pnpm lint — all clean.
  • Still not attempted: a from-scratch prisma migrate deploy against the full migration history fails partway through on an unrelated pre-existing migration-ordering bug, discovered while verifying the new migration but not caused by it — worth its own issue, doesn't affect this repo's CI (which only runs prisma generate, not migrate deploy).
• pnpm lint clean on all touched/new files.

Related Issues

Closes #755