feat: lag-aware DB read routing (#715)

[Bug00Joe]

Overview

This PR adds lag-aware read routing for cross-region replicas. When replica lag exceeds the RPO SLO, readQuery() steers SELECTs to the primary and emits db.replica.route_primary. When lag recovers, replica routing resumes and db.replica.recovered is emitted.

Related Issue

Closes #715

Changes

🗄️ Lag-aware routing

• [MODIFY] src/db/replicaLagMonitor.ts
  • Background poller for replica lag via pg_last_xact_replay_timestamp().
  • Conservative default (unhealthy until first successful poll).
  • Automatic recovery when lag drops below SLO; emits db.replica.recovered.
• [MODIFY] src/db/pool.ts — readQuery() applies routing per-query (not per-connection); emits db.replica.route_primary on primary fallback.
• [MODIFY] src/config/env.ts — declares REPLICA_DB_URL, REPLICA_LAG_THRESHOLD_MS, REPLICA_POLL_INTERVAL_MS.
• [MODIFY] src/db/replicaLagMonitor.test.ts — recovery metric assertion.
• [MODIFY] docs/lag-aware-read-routing.md — docs for Multi-region failover: cross-region replica lag SLO with automatic read routing #715.

Verification Results

npx jest src/db/replicaLagMonitor.test.ts --forceExit
✅ 28/28 passed

Acceptance Criteria	Status
ReplicaLagMonitor service	✅
Router wired in pool.ts per-query	✅ readQuery()
Emit db.replica.route_primary on primary fallback	✅
Recovery restores replica routing after lag drops	✅ + db.replica.recovered

Timeline

• Implemented lag monitor + per-query routing + env schema + recovery metric.
• Documented security assumptions and edge cases.

[drips-wave]

@Bug00Joe 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

[Bug00Joe]

@thlpkee20-wq done closes #715