Feat/cost control tiers

[mrmushfiq]

What's new

Project default customer limits

• Eight projects.default_* columns (daily/monthly spend, per-request max, request rates, on_limit_behavior, downgrade_model)
• CLI: scripts/manage_project_defaults.sh
• Applies to every request with X-Customer-ID; customer_spend auto-provisions on first request
  Customer tiers
• New customer_tiers table + scripts/manage_tiers.sh
• Header: X-Customer-Tier (server-to-server only)
• Resolution: tier, then project default, then unlimited
  Enforcement fixes
• Streaming enforces same customer limits as non-streaming
• downgrade swaps model (X-Downgraded, X-Downgraded-Model)
• Streaming cost estimate uses real prompt size + max_tokens
  muUSD precision
• USD columns DECIMAL(14,6); headers/errors use six decimals
• Idempotent schema migration in schema/schema.sql
  Docs and tests
• test_guide/cost-control-slice-a.md
• Unit tests for LimitSpec and resolver precedence

---

Breaking change

customer_limits rows are no longer read on the request path.

• Before: manage_limits.sh set-customer-limit
• After: manage_project_defaults.sh or manage_tiers.sh
  Migration:
• Same cap for all users: project defaults
• Plan-based caps: tiers + X-Customer-Tier
• One-off VIP: unique tier slug (e.g. vip-acme)
  manage_limits.sh still handles API key rate limits, project monthly_cap_usd, and cache settings. Dead Go code (GetCustomerLimit) removed in v0.4.0.

---

Upgrade

git pull
docker compose build gateway
docker compose exec -T postgres psql -U llm0 -d llm0_gateway -f /docker-entrypoint-initdb.d/01_schema.sql
docker compose up -d
docker compose exec -T redis redis-cli FLUSHDB

Cache refresh:

• Project defaults (manage_project_defaults.sh): FLUSHDB or wait CACHE_TTL_SECONDS
• Tiers (manage_tiers.sh): restart gateway or wait ~60s (tiers are in gateway memory, not Redis)
  Existing monthly_cap_usd values unchanged. X-Customer-Limit-Daily is now six decimals.