[mumusama75]

Summary

Resolves #583 by replacing unbounded whole-file schema.sql replay with numbered, checksummed forward-only migrations executed under a PostgreSQL advisory lock.

Key Changes

1. Migration Files:

   • db/migrations/0001_baseline.sql: Preserves baseline schema for new environments.
   • db/migrations/0002_align_constraints_and_timestamps.sql:
     • Drops duplicate tx-hash unique index invoices_payment_tx_hash_unique, standardizing on uq_invoices_payment_tx_hash.
     • Converts payment_events.created_at and ransactions.processed_at from naive TIMESTAMP to TIMESTAMPTZ using AT TIME ZONE 'UTC'.
     • Adds loud pre-check and invoices_paid_row_check CHECK constraint enforcing that PAID rows have both payment_tx_hash and paid_at.

2. Migration Runner (�ackend/src/db/migration-runner.ts):

   • Creates schema_migrations tracking table (�ersion,
     ame, checksum, �pplied_at).
   • Executes under pg_advisory_lock (ID 742918451) with one transaction per pending file.
   • Automatically detects existing databases with legacy schema and adopts 001_baseline without replay.
   • Re-running migrations is strictly idempotent (second run applies nothing).
   • Validates checksums against previously applied migrations and rejects tampered files.

3. Readiness Probe & Health (�ackend/src/config/runtime.ts & health.ts):

   • In PostgreSQL mode, readiness probe checks connectivity and verifies that the database has applied all bundled migrations.
   • Returns HTTP 503 (
     ot_ready, storageReady: false) when migrations are pending.

4. Integration & Tooling Updates:

   • Updated db/migrate.ts, db/seed.ts, and cutover.ts to use migration-runner.ts.
   • Updated docs/POSTGRES_CUTOVER.md with versioned migration details.
   • Added PostgreSQL service container to GitHub Actions CI workflow, running
     pm run db:migrate twice and running the unskipped Postgres test suite.

Verification

• Added comprehensive unit and integration tests in �ackend/tests/migration-runner.test.ts.
• Verified duplicate tx hash payment claims raise typed PaymentClaimError in �ackend/tests/invoice-postgres.integration.test.ts.
• Verified HTTP 503 on unmigrated database in �ackend/tests/health-readiness.test.ts.
• Full suite passing: 902 tests pass, 0 failing. Clean TypeScript typecheck ( sc --noEmit).