RevoraOrg · thlpkee20-wq · Aug 31, 2026 · Aug 29, 2026 · Aug 31, 2026
diff --git a/README-MIGRATIONS.md b/README-MIGRATIONS.md
@@ -1,44 +1,16 @@
-# Managing Database Migrations
+# Database Migrations
 
-This project uses a custom raw SQL migration script to manage database schema changes reliably.
+## Prefix Numbering Rule
 
-## Structure
-
-- `src/db/migrations/`: Directory where all `.sql` migration files are stored.
-- `src/db/migrate.ts`: The script that executes pending migrations against the database. 
+All database migrations must follow a strict prefix numbering convention to ensure deterministic execution order and prevent collisions.
 
-## Creating Migrations
+### Rules
 
-To add a new migration, create a new `.sql` file in `src/db/migrations/`. 
+1. **Numeric Prefix**: Every migration file MUST begin with a numeric prefix followed by an underscore (e.g., `001_create_users.sql`).
+2. **Sequential Ordering**: The prefixes MUST be strictly monotonic and strictly increasing.
+3. **No Duplicates**: Duplicate prefixes are NOT allowed. If two developers create a migration at the same time with the same prefix, one must be renamed during the merge process.
+4. **No Out-of-Band Migrations**: The `999_*` prefix is flagged as an out-of-band prefix and is rejected by the system.
+5. **Extension**: All migration files MUST have the `.sql` extension.
+6. **Hidden Files**: Hidden files (starting with `.`) are ignored.
 
-**Naming Convention & Safety Rules:** 
-Use a sequential, zero-padded numeric prefix followed by a descriptive name: `XXX_description.sql` (e.g., `003_add_user_status.sql`). 
-
-To ensure safety and execution predictability, the following strict rules are enforced:
-1. **Unique Prefixes**: Every migration file must have a unique sequential prefix. Duplicate prefixes (e.g., two `001_*` files) are strictly rejected to prevent execution order ambiguity and collisions.
-2. **Strict Monotonicity**: Alphabetic ordering of the filenames must match their numeric prefix sequence. Non-padded or incorrectly ordered prefixes that violate monotonic progression are caught and rejected.
-3. **Out-of-band Prefix (`999_`)**: Filenames starting with `999_*` are flagged as "out-of-band" migrations (used for temporary/development purposes) and will be rejected unless explicit relaxed options are enabled.
-4. **Valid File Extension**: Every migration file must end with `.sql`. Files with incorrect extensions (e.g., `.sql.bak` or `.txt`) will be rejected.
-5. **Hidden Files**: Any hidden files starting with a dot (e.g., `.DS_Store` or `.gitkeep`) are automatically ignored during migration resolution.
-
-## Running Migrations
-
-Migrations rely on the `DATABASE_URL` environment variable.
-
-1. Ensure your `.env` file has a valid `DATABASE_URL`:
-   ```env
-   DATABASE_URL="postgres://user:password@localhost:5432/revora"
-   ```
-2. Run the migration script via npm:
-   ```bash
-   npm run migrate
-   ```
-
-This command will:
-1. Compile the TypeScript code (`tsc`).
-2. Connect to the database specified by `DATABASE_URL`.
-3. Create the `schema_version` table if it doesn't already exist.
-4. Apply any `.sql` file in `src/db/migrations/` that hasn't been recorded in `schema_version`, within a transaction.
-5. Record the applied filename in `schema_version`.
-
-If a migration fails mid-execution, the transaction will rollback, leaving your database safely unmodified.
+These rules are enforced by the `resolveMigrations` function in `src/db/migrate.js` during the test run and at startup. A duplicate numeric prefix or non-monotonic ordering will fail the test run with a clear diagnostic.
diff --git a/src/db/migrate.js b/src/db/migrate.js
@@ -128,9 +128,9 @@ async function runMigrations() {
                 return;
             }
 
-            // Load and resolve migrations with relaxed options for the pre-existing production folder
+            // Load and resolve migrations with strict options
             const allFiles = fs.readdirSync(migrationsDir);
-            const files = resolveMigrations(allFiles, { allowDuplicates: true, allowOutOfBand: true, strictExtensions: false });
+            const files = resolveMigrations(allFiles);
 
             let appliedCount = 0;
 

diff --git a/src/db/migrate.test.ts b/src/db/migrate.test.ts
@@ -121,28 +121,27 @@ describe('Database Migration Ordering and Collision Resolver', () => {
   });
 
   describe('On-Disk Active Migration List Assertions', () => {
-    it('should successfully validate the on-disk migrations directory under production rules', () => {
+    it('should successfully validate the on-disk migrations directory under strict rules', () => {
       const migrationsDir = path.join(__dirname, 'migrations');
       expect(fs.existsSync(migrationsDir)).toBe(true);
 
       const allFiles = fs.readdirSync(migrationsDir);
 
-      // The on-disk list contains duplicates (001, 002, 011) and out-of-band prefix 999.
-      // Therefore, it must succeed when using the Option A fallback options.
-      const resolved = resolveMigrations(allFiles, { allowDuplicates: true, allowOutOfBand: true, strictExtensions: false });
+      // The on-disk list must pass strict validation with no duplicates or out-of-band prefixes.
+      const resolved = resolveMigrations(allFiles);
 
       expect(resolved.length).toBeGreaterThan(0);
-      expect(resolved.some(f => f.startsWith('001_'))).toBe(true);
-      expect(resolved.some(f => f.startsWith('999_'))).toBe(true);
-    });
-
-    it('should fail with duplicate prefix error if duplicates are not allowed on the real on-disk files', () => {
-      const migrationsDir = path.join(__dirname, 'migrations');
-      const allFiles = fs.readdirSync(migrationsDir);
-
-      expect(() => {
-        resolveMigrations(allFiles, { allowDuplicates: false, allowOutOfBand: true, strictExtensions: false });
-      }).toThrow('Duplicate migration prefix detected');
+
+      let lastPrefixNum = -1;
+      for (const filename of resolved) {
+        const match = filename.match(/^(\d+)_.*\.sql$/);
+        expect(match).not.toBeNull();
+        if (match) {
+          const prefixNum = parseInt(match[1], 10);
+          expect(prefixNum).toBeGreaterThan(lastPrefixNum);
+          lastPrefixNum = prefixNum;
+        }
+      }
     });
   });
 });
diff --git a/src/db/migrations/001_create_audit_logs.sql → src/db/migrations/002_create_audit_logs.sql b/src/db/migrations/001_create_audit_logs.sql → src/db/migrations/002_create_audit_logs.sql
diff --git a/...ns/001_create_token_balance_snapshots.sql → ...ns/003_create_token_balance_snapshots.sql b/...ns/001_create_token_balance_snapshots.sql → ...ns/003_create_token_balance_snapshots.sql
diff --git a/src/db/migrations/001_create_users.sql → src/db/migrations/004_create_users.sql b/src/db/migrations/001_create_users.sql → src/db/migrations/004_create_users.sql
diff --git a/...igrations/002_create_idempotency_keys.sql → ...igrations/005_create_idempotency_keys.sql b/...igrations/002_create_idempotency_keys.sql → ...igrations/005_create_idempotency_keys.sql
diff --git a/src/db/migrations/002_create_investments.sql → src/db/migrations/006_create_investments.sql b/src/db/migrations/002_create_investments.sql → src/db/migrations/006_create_investments.sql
diff --git a/...s/002_create_notification_preferences.sql → ...s/007_create_notification_preferences.sql b/...s/002_create_notification_preferences.sql → ...s/007_create_notification_preferences.sql
diff --git a/src/db/migrations/002_create_sessions.sql → src/db/migrations/008_create_sessions.sql b/src/db/migrations/002_create_sessions.sql → src/db/migrations/008_create_sessions.sql
diff --git a/src/db/migrations/002_create_users.sql → src/db/migrations/009_create_users.sql b/src/db/migrations/002_create_users.sql → src/db/migrations/009_create_users.sql
diff --git a/...b/migrations/003_create_notifications.sql → ...b/migrations/010_create_notifications.sql b/...b/migrations/003_create_notifications.sql → ...b/migrations/010_create_notifications.sql
diff --git a/src/db/migrations/003_create_offerings.sql → src/db/migrations/011_create_offerings.sql b/src/db/migrations/003_create_offerings.sql → src/db/migrations/011_create_offerings.sql
diff --git a/...grations/003_create_webhook_endpoints.sql → ...grations/012_create_webhook_endpoints.sql b/...grations/003_create_webhook_endpoints.sql → ...grations/012_create_webhook_endpoints.sql
diff --git a/...b/migrations/004_create_distributions.sql → ...b/migrations/013_create_distributions.sql b/...b/migrations/004_create_distributions.sql → ...b/migrations/013_create_distributions.sql
diff --git a/...create_notification_preferences_table.sql → ...create_notification_preferences_table.sql b/...create_notification_preferences_table.sql → ...create_notification_preferences_table.sql
diff --git a/...tions/005_create_distribution_payouts.sql → ...tions/015_create_distribution_payouts.sql b/...tions/005_create_distribution_payouts.sql → ...tions/015_create_distribution_payouts.sql
diff --git a/...migrations/006_create_revenue_reports.sql → ...migrations/016_create_revenue_reports.sql b/...migrations/006_create_revenue_reports.sql → ...migrations/016_create_revenue_reports.sql
diff --git a/...rations/007_create_webhook_deliveries.sql → ...rations/017_create_webhook_deliveries.sql b/...rations/007_create_webhook_deliveries.sql → ...rations/017_create_webhook_deliveries.sql
diff --git a/...ions/010_create_password_reset_tokens.sql → ...ions/018_create_password_reset_tokens.sql b/...ions/010_create_password_reset_tokens.sql → ...ions/018_create_password_reset_tokens.sql
diff --git a/...011_create_password_reset_rate_limits.sql → ...019_create_password_reset_rate_limits.sql b/...011_create_password_reset_rate_limits.sql → ...019_create_password_reset_rate_limits.sql
diff --git a/...rations/011_ensure_users_email_unique.sql → ...rations/020_ensure_users_email_unique.sql b/...rations/011_ensure_users_email_unique.sql → ...rations/020_ensure_users_email_unique.sql
diff --git a/...ions/011_update_sessions_for_rotation.sql → ...ions/021_update_sessions_for_rotation.sql b/...ions/011_update_sessions_for_rotation.sql → ...ions/021_update_sessions_for_rotation.sql
diff --git a/...db/migrations/012_create_dispute_slas.sql → ...db/migrations/022_create_dispute_slas.sql b/...db/migrations/012_create_dispute_slas.sql → ...db/migrations/022_create_dispute_slas.sql
diff --git a/.../migrations/012_create_indexer_tables.sql → .../migrations/023_create_indexer_tables.sql b/.../migrations/012_create_indexer_tables.sql → .../migrations/023_create_indexer_tables.sql
diff --git a/...grations/012_enhance_session_security.sql → ...grations/024_enhance_session_security.sql b/...grations/012_enhance_session_security.sql → ...grations/024_enhance_session_security.sql
diff --git a/...d_revenue_reports_distribution_status.sql → ...d_revenue_reports_distribution_status.sql b/...d_revenue_reports_distribution_status.sql → ...d_revenue_reports_distribution_status.sql
diff --git a/...b/migrations/013_audit_log_hash_chain.sql → ...b/migrations/026_audit_log_hash_chain.sql b/...b/migrations/013_audit_log_hash_chain.sql → ...b/migrations/026_audit_log_hash_chain.sql
diff --git a/...3_create_reconciliation_run_summaries.sql → ...7_create_reconciliation_run_summaries.sql b/...3_create_reconciliation_run_summaries.sql → ...7_create_reconciliation_run_summaries.sql
diff --git a/...d_max_investor_share_bps_to_offerings.sql → ...d_max_investor_share_bps_to_offerings.sql b/...d_max_investor_share_bps_to_offerings.sql → ...d_max_investor_share_bps_to_offerings.sql
diff --git a/.../migrations/014_create_webhook_outbox.sql → .../migrations/029_create_webhook_outbox.sql b/.../migrations/014_create_webhook_outbox.sql → .../migrations/029_create_webhook_outbox.sql
diff --git a/.../migrations/015_create_oidc_providers.sql → .../migrations/030_create_oidc_providers.sql b/.../migrations/015_create_oidc_providers.sql → .../migrations/030_create_oidc_providers.sql
diff --git a/...tions/015_create_payout_drift_reports.sql → ...tions/031_create_payout_drift_reports.sql b/...tions/015_create_payout_drift_reports.sql → ...tions/031_create_payout_drift_reports.sql
diff --git a/...grations/015_create_social_identities.sql → ...grations/032_create_social_identities.sql b/...grations/015_create_social_identities.sql → ...grations/032_create_social_identities.sql
diff --git a/...ations/016_add_kyc_risk_tier_to_users.sql → ...ations/033_add_kyc_risk_tier_to_users.sql b/...ations/016_add_kyc_risk_tier_to_users.sql → ...ations/033_add_kyc_risk_tier_to_users.sql
diff --git a/...grations/016_create_contract_upgrades.sql → ...grations/034_create_contract_upgrades.sql b/...grations/016_create_contract_upgrades.sql → ...grations/034_create_contract_upgrades.sql
diff --git a/...tions/017_create_email_deliverability.sql → ...tions/035_create_email_deliverability.sql b/...tions/017_create_email_deliverability.sql → ...tions/035_create_email_deliverability.sql
diff --git a/...ations/017_create_ledger_period_locks.sql → ...ations/036_create_ledger_period_locks.sql b/...ations/017_create_ledger_period_locks.sql → ...ations/036_create_ledger_period_locks.sql
diff --git a/...migrations/017_create_pdf_render_jobs.sql → ...migrations/037_create_pdf_render_jobs.sql b/...migrations/017_create_pdf_render_jobs.sql → ...migrations/037_create_pdf_render_jobs.sql
diff --git a/...migrations/017_create_tenant_settings.sql → ...migrations/038_create_tenant_settings.sql b/...migrations/017_create_tenant_settings.sql → ...migrations/038_create_tenant_settings.sql
diff --git a/...ons/018_create_audit_witness_receipts.sql → ...ons/039_create_audit_witness_receipts.sql b/...ons/018_create_audit_witness_receipts.sql → ...ons/039_create_audit_witness_receipts.sql
diff --git a/...migrations/018_create_dispute_refunds.sql → ...migrations/040_create_dispute_refunds.sql b/...migrations/018_create_dispute_refunds.sql → ...migrations/040_create_dispute_refunds.sql
diff --git a/...db/migrations/018_create_ofac_reviews.sql → ...db/migrations/041_create_ofac_reviews.sql b/...db/migrations/018_create_ofac_reviews.sql → ...db/migrations/041_create_ofac_reviews.sql
diff --git a/...igrations/018_create_retention_labels.sql → ...igrations/042_create_retention_labels.sql b/...igrations/018_create_retention_labels.sql → ...igrations/042_create_retention_labels.sql
diff --git a/...ions/019_create_dispute_ledger_events.sql → ...ions/043_create_dispute_ledger_events.sql b/...ions/019_create_dispute_ledger_events.sql → ...ions/043_create_dispute_ledger_events.sql
diff --git a/...ns/020_add_cron_schedule_to_offerings.sql → ...ns/044_add_cron_schedule_to_offerings.sql b/...ns/020_add_cron_schedule_to_offerings.sql → ...ns/044_add_cron_schedule_to_offerings.sql
diff --git a/...020_add_partial_index_active_sessions.sql → ...045_add_partial_index_active_sessions.sql b/...020_add_partial_index_active_sessions.sql → ...045_add_partial_index_active_sessions.sql
diff --git a/...grations/020_contract_upgrades_canary.sql → ...grations/046_contract_upgrades_canary.sql b/...grations/020_contract_upgrades_canary.sql → ...grations/046_contract_upgrades_canary.sql
diff --git a/...migrations/020_create_investment_lots.sql → ...migrations/047_create_investment_lots.sql b/...migrations/020_create_investment_lots.sql → ...migrations/047_create_investment_lots.sql
diff --git a/...ations/020_create_oidc_group_mappings.sql → ...ations/048_create_oidc_group_mappings.sql b/...ations/020_create_oidc_group_mappings.sql → ...ations/048_create_oidc_group_mappings.sql
diff --git a/...igrations/020_create_push_experiments.sql → ...igrations/049_create_push_experiments.sql b/...igrations/020_create_push_experiments.sql → ...igrations/049_create_push_experiments.sql
diff --git a/...ons/021_add_last_oidc_groups_to_users.sql → ...ons/050_add_last_oidc_groups_to_users.sql b/...ons/021_add_last_oidc_groups_to_users.sql → ...ons/050_add_last_oidc_groups_to_users.sql
diff --git a/...ns/021_create_aml_investment_velocity.sql → ...ns/051_create_aml_investment_velocity.sql b/...ns/021_create_aml_investment_velocity.sql → ...ns/051_create_aml_investment_velocity.sql
diff --git a/src/db/migrations/021_create_disposals.sql → src/db/migrations/052_create_disposals.sql b/src/db/migrations/021_create_disposals.sql → src/db/migrations/052_create_disposals.sql
diff --git a/...ns/021_create_sanctions_list_versions.sql → ...ns/053_create_sanctions_list_versions.sql b/...ns/021_create_sanctions_list_versions.sql → ...ns/053_create_sanctions_list_versions.sql
diff --git a/...add_session_policy_to_tenant_settings.sql → ...add_session_policy_to_tenant_settings.sql b/...add_session_policy_to_tenant_settings.sql → ...add_session_policy_to_tenant_settings.sql
diff --git a/...3_add_frozen_fx_rate_to_distributions.sql → ...5_add_frozen_fx_rate_to_distributions.sql b/...3_add_frozen_fx_rate_to_distributions.sql → ...5_add_frozen_fx_rate_to_distributions.sql
diff --git a/...dd_private_relay_to_social_identities.sql → ...dd_private_relay_to_social_identities.sql b/...dd_private_relay_to_social_identities.sql → ...dd_private_relay_to_social_identities.sql
diff --git a/src/db/migrations/023_create_push_tokens.sql → src/db/migrations/057_create_push_tokens.sql b/src/db/migrations/023_create_push_tokens.sql → src/db/migrations/057_create_push_tokens.sql
diff --git a/...ons/024_add_frozen_fx_rate_to_payouts.sql → ...ons/058_add_frozen_fx_rate_to_payouts.sql b/...ons/024_add_frozen_fx_rate_to_payouts.sql → ...ons/058_add_frozen_fx_rate_to_payouts.sql
diff --git a/...ions/024_create_wash_sale_adjustments.sql → ...ions/059_create_wash_sale_adjustments.sql b/...ions/024_create_wash_sale_adjustments.sql → ...ions/059_create_wash_sale_adjustments.sql
diff --git a/...ns/999_add_token_consumed_to_sessions.sql → ...ns/060_add_token_consumed_to_sessions.sql b/...ns/999_add_token_consumed_to_sessions.sql → ...ns/060_add_token_consumed_to_sessions.sql
diff --git a/src/db/migrations/safety/executor.ts b/src/db/migrations/safety/executor.ts
@@ -598,9 +598,9 @@ export class MigrationManager {
     const appliedMigrations = await this.getAppliedMigrations();
     const appliedSet = new Set(appliedMigrations);
 
-    const files = fs.readdirSync(migrationsDir)
-      .filter((f: string) => f.endsWith('.sql'))
-      .sort();
+    const allFiles = fs.readdirSync(migrationsDir);
+    const { resolveMigrations } = require('../../migrate');
+    const files = resolveMigrations(allFiles);
 
     return files.filter((file: string) => !appliedSet.has(file));
   }