@@ -103,61 +103,68 @@ jobs:
         working-directory: zk
         run: npm test
 
-  zk-tests:
-    name: ZK Circuit Tests
+  migration-dry-run:
+    name: Migration Dry-Run
     runs-on: ubuntu-latest
+    env:
+      # Custom runner reads TIMESCALEDB_* env vars; point them at the ephemeral
+      # timescaledb service container spun up for this job.
+      TIMESCALEDB_HOST: localhost
+      TIMESCALEDB_PORT: 5432
+      TIMESCALEDB_DATABASE: pactum_migration_test
+      TIMESCALEDB_USER: postgres
+      TIMESCALEDB_PASSWORD: postgres
+    services:
+      postgres:
+        # Same image docker-compose.yml uses for the real service, so
+        # CREATE EXTENSION timescaledb (001_timescale_setup.sql) succeeds here
+        # instead of only in the full docker-compose e2e stack.
+        image: timescale/timescaledb:latest-pg16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: pactum_migration_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d pactum_migration_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      # Node 22.18+ runs the package's TypeScript sources directly, so there is no
-      # build step to keep in sync with the tests.
-      - name: Set up Node.js 22.x
+      - name: Set up Node.js 22.x (LTS)
         uses: actions/setup-node@v4
         with:
           node-version: '22.x'
 
-      - name: Install Rust stable toolchain
-        uses: dtolnay/rust-toolchain@stable
-
-      # circom is not published to npm, so it is built from source and cached — the
-      # circuit tests skip without it, and a skipped circuit test proves nothing.
-      - name: Cache circom binary
-        id: cache_circom
-        uses: actions/cache@v4
-        with:
-          path: ~/.cargo/bin/circom
-          key: ${{ runner.os }}-circom-2.2.3
-
-      - name: Build circom from source
-        if: steps.cache_circom.outputs.cache-hit != 'true'
-        run: cargo install --locked --git https://github.com/iden3/circom.git --tag v2.2.3 circom
-
       - name: Cache npm dependencies
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-node-zk-${{ hashFiles('zk/package-lock.json', 'zk/package.json') }}
+          key: ${{ runner.os }}-node-${{ hashFiles('backend/package-lock.json', 'backend/package.json') }}
           restore-keys: |
-            ${{ runner.os }}-node-zk-
+            ${{ runner.os }}-node-
 
-      - name: Install zk dependencies
-        working-directory: zk
+      - name: Install backend dependencies
+        working-directory: backend
         run: |
           if [ -f package-lock.json ]; then
             npm ci
           else
             npm install
           fi
 
-      - name: Compile circuit and run the Groth16 setup
-        working-directory: zk
-        run: npm run build:circuit
+      - name: Build backend
+        working-directory: backend
+        run: npm run build
+
+      - name: Run migration dry-run against ephemeral TimescaleDB
+        working-directory: backend
+        run: node dist/db/migrate-dry-run.js
 
-      - name: Run zk test suite
-        working-directory: zk
-        run: npm test
 
   backend-tests:
     name: Backend Tests
 
@@ -13,7 +13,7 @@ Pactum lets any two parties register a real-world commitment on Stellar — a re
 
 ## The problem
 
-Escrow contracts handle *one-time* deals — money goes in, money comes out once conditions are met. But a lot of real commitments aren't one-time payments at all:
+Escrow contracts handle _one-time_ deals — money goes in, money comes out once conditions are met. But a lot of real commitments aren't one-time payments at all:
 
 - A landlord promising to return a deposit within 30 days of move-out
 - An API provider guaranteeing 99.9% uptime this quarter
@@ -81,43 +81,43 @@ See [`docs/architecture.md`](./docs/architecture.md) for the full breakdown.
 
 ## Tech stack
 
-| Layer | Technology |
-|---|---|
-| Smart contract | Rust + Soroban SDK |
-| Contract network | Stellar Testnet |
-| Backend API | Node.js + TypeScript + Express |
-| Indexer | Soroban RPC event listener |
-| Database | PostgreSQL + TimescaleDB (time-series analytics) |
-| Cache | Redis (optional read cache for reputation lookups) |
-| SDK | TypeScript, published as `@pactum/sdk` |
-| ZK proofs | Circom 2 + snarkjs (Groth16 over BN254) |
-| Testing | Cargo test (contract) · Jest (backend) · `node --test` (zk) |
-| CI/CD | GitHub Actions |
+| Layer            | Technology                                                  |
+| ---------------- | ----------------------------------------------------------- |
+| Smart contract   | Rust + Soroban SDK                                          |
+| Contract network | Stellar Testnet                                             |
+| Backend API      | Node.js + TypeScript + Express                              |
+| Indexer          | Soroban RPC event listener                                  |
+| Database         | PostgreSQL + TimescaleDB (time-series analytics)            |
+| Cache            | Redis (optional read cache for reputation lookups)          |
+| SDK              | TypeScript, published as `@pactum/sdk`                      |
+| ZK proofs        | Circom 2 + snarkjs (Groth16 over BN254)                     |
+| Testing          | Cargo test (contract) · Jest (backend) · `node --test` (zk) |
+| CI/CD            | GitHub Actions                                              |
 
 ---
 
 ## Contract interface (early draft)
 
-| Method | Kind | Description |
-|---|---|---|
-| `create_commitment(issuer, counterparty, terms_hash, due_at)` | write | Register a new commitment between two addresses |
-| `create_milestone_commitment(issuer, counterparty, terms_hash, due_at, resolver, milestone_count)` | write | Register a commitment fulfilled across several milestones |
-| `attest(commitment_id, outcome)` | write | Mark the next pending milestone fulfilled, late, or breached — resolving the commitment if it is the last one |
-| `attest_milestone(commitment_id, milestone_index, outcome)` | write | Mark one milestone of a commitment; the commitment resolves on the last one |
-| `get_milestone(commitment_id, milestone_index)` | read | Fetch a single milestone's outcome, or nothing while it is pending |
-| `dispute(commitment_id, reason)` | write | Flag a commitment as contested rather than resolved |
-| `resolve_dispute(commitment_id, outcome)` | write | Designated arbitrator/oracle settles a disputed commitment |
-| `get_commitment(commitment_id)` | read | Fetch a single commitment's details and status |
-| `get_reputation(address)` | read | Aggregate fulfilled / late / breached counts for an address |
+| Method                                                                                             | Kind  | Description                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------- |
+| `create_commitment(issuer, counterparty, terms_hash, due_at)`                                      | write | Register a new commitment between two addresses                                                               |
+| `create_milestone_commitment(issuer, counterparty, terms_hash, due_at, resolver, milestone_count)` | write | Register a commitment fulfilled across several milestones                                                     |
+| `attest(commitment_id, outcome)`                                                                   | write | Mark the next pending milestone fulfilled, late, or breached — resolving the commitment if it is the last one |
+| `attest_milestone(commitment_id, milestone_index, outcome)`                                        | write | Mark one milestone of a commitment; the commitment resolves on the last one                                   |
+| `get_milestone(commitment_id, milestone_index)`                                                    | read  | Fetch a single milestone's outcome, or nothing while it is pending                                            |
+| `dispute(commitment_id, reason)`                                                                   | write | Flag a commitment as contested rather than resolved                                                           |
+| `resolve_dispute(commitment_id, outcome)`                                                          | write | Designated arbitrator/oracle settles a disputed commitment                                                    |
+| `get_commitment(commitment_id)`                                                                    | read  | Fetch a single commitment's details and status                                                                |
+| `get_reputation(address)`                                                                          | read  | Aggregate fulfilled / late / breached counts for an address                                                   |
 
 Full spec lives in [`docs/contract-reference.md`](./docs/contract-reference.md) as the contract develops.
 
 ## Production Deployment
 
 The contract is currently deployed on the Stellar Testnet for testing and integration.
 
-| Contract | Network | Contract ID | Explorer |
-|----------|---------|-------------|----------|
+| Contract | Network | Contract ID                                                | Explorer                                                                                                                    |
+| -------- | ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | Registry | Testnet | `CBADTVTJ6IN332HIKZ7LWUYMYTLPZYCEBV3X2HS47VHR5UDBHQ3GAA7E` | [Stellar Expert](https://stellar.expert/explorer/testnet/contract/CBADTVTJ6IN332HIKZ7LWUYMYTLPZYCEBV3X2HS47VHR5UDBHQ3GAA7E) |
 
 ### Example Transactions
@@ -153,13 +153,50 @@ cd ../backend
 npm install
 cp .env.example .env      # fill in DATABASE_URL, SOROBAN_RPC_URL, TIMESCALEDB_* config, etc.
 npm run build
-npm run migrate:timescale  # Run TimescaleDB migrations
+npm run migrate:up        # Run all pending migrations
 npm run dev
 
 # 5. Start analytics worker (optional, for background data processing)
 npm run analytics:worker
 ```
 
+### Database migrations
+
+Pactum uses a custom immutable migration runner built into the backend. Every migration file is content-addressed with a SHA-256 checksum frozen on first apply — editing an already-applied file is detected and rejected at startup, preventing silent schema drift between environments.
+
+Migration files live in `backend/src/db/migrations/` and are numbered with a three-digit prefix (`001_`, `002_`, …) so they execute in a deterministic lexicographic order.
+
+| NPM script                              | What it does                                                |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `npm run migrate:up`                    | Build the backend and apply all pending migrations          |
+| `npm run migrate:make -- <description>` | Create a new numbered migration stub                        |
+| `npm run migrate:status`                | Print which migrations are applied, pending, or tampered    |
+| `npm run migrate:dry-run`               | Validate checksums and SQL syntax without writing to the DB |
+
+#### Day-to-day workflow
+
+```bash
+# Check what is currently applied
+cd backend
+npm run migrate:status
+
+# Create a new migration
+npm run migrate:make -- add_webhook_deliveries_table
+# → writes backend/src/db/migrations/008_add_webhook_deliveries_table.sql
+
+# Edit the generated stub, then apply
+npm run migrate:up
+
+# Validate all migrations without touching the database (also runs in CI)
+npm run migrate:dry-run
+```
+
+#### Immutability rules
+
+- **Never edit a migration that has already been applied to any environment.** The runner stores the SHA-256 of each file at apply time and compares it on every subsequent run. A mismatch aborts the migration cycle and exits non-zero.
+- To change something that was already applied, create a new migration that issues the corrective `ALTER`, `DROP`, or `CREATE` statement.
+- The `migrate:dry-run` script is run automatically on every pull request by CI (see `.github/workflows/ci.yml` → `migration-dry-run` job).
+
 ### Running the whole stack with Docker
 
 **Prerequisites:** Docker with Compose v2.
@@ -170,11 +207,11 @@ docker compose up --build
 
 That boots TimescaleDB, the backend (which applies `backend/src/db/migrations/*.sql` on startup) and an nginx-served frontend build.
 
-| Service | URL | Override |
-|---|---|---|
-| Frontend | http://localhost | `FRONTEND_PORT` |
-| Backend | http://localhost:3000 | `BACKEND_PORT` |
-| TimescaleDB | `localhost:5432` | `TIMESCALEDB_PORT` |
+| Service     | URL                   | Override           |
+| ----------- | --------------------- | ------------------ |
+| Frontend    | http://localhost      | `FRONTEND_PORT`    |
+| Backend     | http://localhost:3000 | `BACKEND_PORT`     |
+| TimescaleDB | `localhost:5432`      | `TIMESCALEDB_PORT` |
 
 The frontend is built to call the API on its own origin, and nginx proxies `/api`, `/reputation`, `/commitments` and `/health` to the backend container. Database credentials and Soroban settings come from the same `TIMESCALEDB_*` / `SOROBAN_*` variables as `backend/.env.example`; set them in a root `.env` to override the defaults.
 
 
@@ -17,6 +17,10 @@
     "indexer": "node dist/workers/indexer.js",
     "analytics:worker": "node dist/workers/analyticsWorker.js",
     "migrate:timescale": "node dist/db/migrate.js",
+    "migrate:up": "npm run build && node dist/db/migrate.js",
+    "migrate:make": "node scripts/migrate-make.js",
+    "migrate:status": "npm run build && node dist/db/migrate-status.js",
+    "migrate:dry-run": "npm run build && node dist/db/migrate-dry-run.js",
     "backfill:commitments": "node dist/indexer/backfill-commitments.js"
   },
   "keywords": [],
 
@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * migrate-make.js — create a new numbered migration file.
+ *
+ * Usage:
+ *   npm run migrate:make -- <description>
+ *
+ * Example:
+ *   npm run migrate:make -- add_webhook_deliveries_table
+ *
+ * The script finds the highest existing migration number, increments it by 1,
+ * and writes an empty SQL stub:
+ *
+ *   backend/src/db/migrations/006_add_webhook_deliveries_table.sql
+ *
+ * Rules enforced here intentionally mirror those in timescale.ts:
+ *   - Files are sorted lexicographically, so zero-padded three-digit prefixes
+ *     are required for correct ordering up to migration 999.
+ *   - Each file's checksum is frozen on first run; never edit an applied file.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require('fs');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require('path');
+
+const MIGRATIONS_DIR = path.join(__dirname, '..', 'src', 'db', 'migrations');
+
+function main() {
+  const args = process.argv.slice(2);
+  const raw = args.join('_').trim();
+
+  if (!raw) {
+    console.error('Usage: npm run migrate:make -- <description>');
+    console.error('Example: npm run migrate:make -- add_webhook_deliveries_table');
+    process.exit(1);
+  }
+
+  // Sanitise: lowercase, replace spaces/hyphens with underscores, strip non-word chars
+  const description = raw
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_')
+    .replace(/[^\w]/g, '');
+
+  if (!description) {
+    console.error('Error: description must contain at least one alphanumeric character.');
+    process.exit(1);
+  }
+
+  // Find the highest existing sequence number
+  const existing = fs
+    .readdirSync(MIGRATIONS_DIR)
+    .filter((f) => /^\d{3}_.*\.sql$/.test(f))
+    .map((f) => parseInt(f.slice(0, 3), 10));
+
+  const next = existing.length > 0 ? Math.max(...existing) + 1 : 1;
+  const prefix = String(next).padStart(3, '0');
+  const filename = `${prefix}_${description}.sql`;
+  const fullPath = path.join(MIGRATIONS_DIR, filename);
+
+  if (fs.existsSync(fullPath)) {
+    console.error(`Error: migration file already exists: ${filename}`);
+    process.exit(1);
+  }
+
+  const timestamp = new Date().toISOString();
+  const template = `-- Migration ${prefix}: ${description}
+-- Created: ${timestamp}
+--
+-- IMPORTANT: Once this migration has been applied to any environment its
+-- checksum is frozen. Do NOT edit this file; create a new migration instead.
+--
+-- Write your SQL below this line.
+`;
+
+  fs.writeFileSync(fullPath, template, 'utf8');
+  console.log(`Created migration: src/db/migrations/${filename}`);
+}
+
+main();
@@ -0,0 +1,49 @@
+import pool, { dryRunMigrations } from './timescale';
+
+// Validates all migration files (checksum integrity + SQL syntax) against an
+// ephemeral database without making any persistent changes.  Used by CI to
+// gate PRs that touch migration files.
+//
+// Exit codes:
+//   0 — all migrations are valid (applied checksums match, pending SQL is clean)
+//   1 — at least one migration is tampered or contains a syntax error
+dryRunMigrations()
+  .then(async (report) => {
+    let hasError = false;
+
+    for (const entry of report) {
+      const icon =
+        entry.status === 'applied'
+          ? '✓'
+          : entry.status === 'pending'
+            ? '⧖'
+            : entry.status === 'tampered'
+              ? '✗'
+              : '✗';
+
+      const detail = entry.message ? ` — ${entry.message}` : '';
+      console.log(`[migrate:dry-run] ${icon} ${entry.file} (${entry.status})${detail}`);
+
+      if (entry.status === 'tampered' || entry.status === 'error') {
+        hasError = true;
+      }
+    }
+
+    if (hasError) {
+      console.error('\n[migrate:dry-run] FAILED — fix the errors above before merging.');
+    } else {
+      console.log(`\n[migrate:dry-run] OK — ${report.length} migration(s) validated successfully.`);
+    }
+
+    await pool.end();
+    process.exit(hasError ? 1 : 0);
+  })
+  .catch(async (err) => {
+    console.error('[migrate:dry-run] Error:', err);
+    try {
+      await pool.end();
+    } catch {
+      // ignore teardown errors
+    }
+    process.exit(1);
+  });