feat: DB pool saturation as autoscale signal (#712)

[jaymoneymanxl]

Overview

This PR exports DB pool saturation gauges (db.pool.waiters, db.pool.utilization) on every auth-gated /metrics scrape so horizontal autoscaling can react to connection-pool contention — not just CPU.

Related Issue

Closes #712

Changes

📈 Pool saturation autoscale signal

• [MODIFY] src/lib/metrics.ts
  • Adds updatePoolSaturationMetrics() which always publishes both gauges (including when the pool is idle → 0).
• [MODIFY] src/middleware/metricsMiddleware.ts
  • createPrometheusHandler(metrics, pool) refreshes pool gauges on every scrape before export.
• [MODIFY] src/app.ts — wires the primary pool into /metrics (still behind scrape auth).
• [MODIFY] src/db/pool.ts — documents the autoscale metrics contract.
• [ADD] docs/autoscale-db-pool-signal.md — HPA guidance, suggested thresholds, Prometheus alert examples.

Verification Results

npx jest src/lib/metrics.test.ts --testNamePattern="updatePoolSaturationMetrics" --forceExit
✅ 5/5 passed

Acceptance Criteria	Status
Emit db.pool.waiters	✅
Emit db.pool.utilization	✅
Metrics stay defined when pool is idle	✅ both series = 0
Metrics guarded by scrape auth	✅ /metrics behind METRICS_TOKEN middleware
HPA guidance + alert rules documented	✅

Timeline

• Implemented pool saturation gauges + scrape wiring + HPA/alert runbook.

[drips-wave]

@jaymoneymanxl Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[jaymoneymanxl]

@thlpkee20-wq done closes #712