@getstrata/core 2.2.17 → 2.2.20

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @getstrata/core changelog
 
+## 2.2.20
+
+Validate complete migration definitions before callbacks, locks or database effects; reject malformed exports and duplicate names with source diagnostics. Refuse fresh with missing applied definitions and rollback with incomplete latest batches; preserve partial forward migration and remove blanket history deletion. Cover physical schema/data/history preservation and reset recovery on real Postgres, MySQL and SQLite, plus loader and preflight regressions; document safe missing-file recovery and unchanged atomicity limits.
+
+## 2.2.19
+
+Fix explicit development fresh resets with unfinished outbox deliveries while preserving ordinary rollback guards. Record each completed reset down immediately so later refusal leaves recoverable migration progress; document partial-DDL/crash limits and old-history reconciliation. Add independent outbox-state and reset failure/migrate/retry regressions on real Postgres, MySQL and SQLite, history-write/reapplication fault injection, and a documented stateful regression review flow.
+
+## 2.2.18
+
+Add optional typed guardMigrationRollback for application-owned rollback history predicates; skip history reads only during explicit development fresh resets, propagate predicate failures, and reuse the contract for encryption-checkpoint archival protection. Document guard placement and unchanged reset/rollback safety; cover type, runner and real SQLite history regressions.
+
 ## 2.2.17
 
 Add explicit development-only migration reset context while preserving guarded rollback and encryption archival; align generated fresh entries and reject production/staging or unsupported reset arguments before provisioning. Replace CSP-blocked error-page JavaScript navigation with safe same-origin links, and correct ambiguous Postgres/SQLite foreign-key messages without changing their HTTP status.

package/dist/core/database/migrations/rollbackGuard.d.ts

@@ -0,0 +1,10 @@
+import type { MigrationDownContext } from "./types.ts";
+interface MigrationRollbackGuard {
+    /** Application-owned history check. It is not evaluated during an explicit fresh reset. */
+    hasHistory(): boolean | Promise<boolean>;
+    message: string;
+}
+/** Await before destructive DDL. Predicate failures propagate; ordinary rollback remains guarded. */
+declare function guardMigrationRollback(context: MigrationDownContext | undefined, guard: MigrationRollbackGuard): Promise<void>;
+export type { MigrationRollbackGuard };
+export { guardMigrationRollback };

package/dist/core/database/migrations/runner.d.ts

@@ -23,4 +23,5 @@ declare function freshDatabase(db: MigrationDatabase, migrations: Migration[], o
     destructive?: boolean;
 }): Promise<void>;
 export { withMigrationLock } from "./advisoryLock.ts";
+export { guardMigrationRollback, type MigrationRollbackGuard } from "./rollbackGuard.ts";
 export { ensureMigrationsTable, freshDatabase, getAppliedMigrations, getMigrationStatus, loadMigrationsFromDirectory, migrateDatabase, rollbackDatabase, runPendingMigrations, };

package/dist/entries/database/migrations.js

@@ -265,9 +265,38 @@ async function withMigrationLock(db, callback, lockKey = MIGRATION_LOCK_KEY) {
     await db.unsafe("SELECT pg_advisory_unlock($1)", [lockKey]);
   }
 }
+// ../../src/core/database/migrations/rollbackGuard.ts
+async function guardMigrationRollback(context, guard) {
+  if (context?.operation === "fresh")
+    return;
+  if (await guard.hasHistory())
+    throw new Error(guard.message);
+}
 
 // ../../src/core/database/migrations/runner.ts
 var MIGRATIONS_TABLE = "framework_migrations";
+function validateMigrations(migrations, sources) {
+  if (!Array.isArray(migrations))
+    throw new Error("Migrations must be an array of definitions.");
+  const names = new Map;
+  for (const [index, migration] of migrations.entries()) {
+    const source = sources?.[index] ?? `migration at index ${index}`;
+    if (!migration || typeof migration !== "object" || Array.isArray(migration) || typeof migration.name !== "string" || migration.name.trim().length === 0 || typeof migration.up !== "function" || typeof migration.down !== "function") {
+      throw new Error(`Invalid ${source}: expected a migration with a non-empty string name and up/down functions.`);
+    }
+    const previous = names.get(migration.name);
+    if (previous !== undefined)
+      throw new Error(`Duplicate migration name "${migration.name}" in ${previous} and ${source}.`);
+    names.set(migration.name, source);
+  }
+}
+function requireMigrationDefinitions(applied, migrations, operation) {
+  const names = new Set(migrations.map(({ name }) => name));
+  const missing = applied.filter(({ name }) => !names.has(name)).map(({ name }) => name);
+  if (missing.length > 0) {
+    throw new Error(`Cannot ${operation}: missing applied migration definitions: ${missing.join(", ")}. Restore the migration files before retrying; history has not been removed.`);
+  }
+}
 function migrationsNameColumn() {
   return currentSqlDialect().driver === "mysql" ? "VARCHAR(255) PRIMARY KEY" : "TEXT PRIMARY KEY";
 }
@@ -309,15 +338,17 @@ async function getAppliedMigrations(db) {
 }
 async function loadMigrationsFromDirectory(directory) {
   const entries = await readdir(directory);
-  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && entry !== "types.ts" && entry !== "index.ts" && entry !== "runner.ts").sort();
+  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && !entry.endsWith(".d.ts") && !["types", "index", "runner", "advisoryLock", "migrationDatabase"].some((name) => entry === `${name}.ts` || entry === `${name}.js`)).sort();
   const loadedMigrations = await Promise.all(migrationFiles.map(async (fileName) => {
     const moduleUrl = pathToFileURL(join(directory, fileName)).href;
     const module = await import(moduleUrl);
     return module.default;
   }));
-  return loadedMigrations.filter((migration) => migration?.name !== undefined);
+  validateMigrations(loadedMigrations, migrationFiles.map((file) => join(directory, file)));
+  return loadedMigrations;
 }
 async function getMigrationStatus(db, migrations) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedByName = new Map(applied.map(({ name, batch }) => [name, Number(batch)]));
   return migrations.map(({ name }) => ({
@@ -327,6 +358,7 @@ async function getMigrationStatus(db, migrations) {
   }));
 }
 async function runPendingMigrations(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedNames = new Set(applied.map(({ name }) => name));
   const nextBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0) + 1;
@@ -342,6 +374,7 @@ async function runPendingMigrations(db, migrations, options = {}) {
   return pendingMigrations.length;
 }
 async function migrateDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const { advisoryLock = false, onMigration } = options;
   if (advisoryLock) {
     return withMigrationLock(db, () => runPendingMigrations(db, migrations, { onMigration }));
@@ -349,11 +382,13 @@ async function migrateDatabase(db, migrations, options = {}) {
   return runPendingMigrations(db, migrations, { onMigration });
 }
 async function rollbackDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   if (applied.length === 0) {
     return 0;
   }
   const lastBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0);
+  requireMigrationDefinitions(applied.filter(({ batch }) => Number(batch) === lastBatch), migrations, "roll back latest batch");
   const migrationsToRollback = new Set(applied.filter(({ batch }) => Number(batch) === lastBatch).map(({ name }) => name));
   let rolledBack = 0;
   for (const migration of [...migrations].reverse()) {
@@ -371,8 +406,10 @@ async function freshDatabase(db, migrations, options = {}) {
   if (options.destructive && isProductionEnv()) {
     throw new Error("Destructive migration reset is only available in development/test environments.");
   }
+  validateMigrations(migrations);
   const runFresh = async () => {
     const applied = await getAppliedMigrations(db);
+    requireMigrationDefinitions(applied, migrations, "reset database");
     const appliedNames = new Set(applied.map(({ name }) => name));
     const appliedMigrations = migrations.filter(({ name }) => appliedNames.has(name));
     for (const migration of [...appliedMigrations].reverse()) {
@@ -381,9 +418,7 @@ async function freshDatabase(db, migrations, options = {}) {
         await migration.down(db, { operation: "fresh" });
       else
         await migration.down(db);
-    }
-    if (appliedMigrations.length > 0) {
-      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE}`);
+      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE} WHERE name = ${currentSqlDialect().placeholder(1)}`, [migration.name]);
     }
     await runPendingMigrations(db, migrations, options);
   };
@@ -398,6 +433,7 @@ export {
   freshDatabase,
   getAppliedMigrations,
   getMigrationStatus,
+  guardMigrationRollback,
   loadMigrationsFromDirectory,
   migrateDatabase,
   rollbackDatabase,

package/dist/index.js

@@ -6369,6 +6369,16 @@ var baseRepository_default = BaseRepository;
 
 // ../../src/core/crypto/fieldEncryptionRotation.ts
 init_boundConnection();
+
+// ../../src/core/database/migrations/rollbackGuard.ts
+async function guardMigrationRollback(context, guard) {
+  if (context?.operation === "fresh")
+    return;
+  if (await guard.hasHistory())
+    throw new Error(guard.message);
+}
+
+// ../../src/core/crypto/fieldEncryptionRotation.ts
 init_repositoryConnection();
 
 // ../../src/core/database/schema/columnDefinition.ts
@@ -7165,13 +7175,13 @@ function createFieldEncryptionRotationMigration(name, driver, options = {}) {
         await db.unsafe(enableTenantRlsSql(checkpointTable.name));
     },
     async down(db, context) {
-      if (context?.operation === "fresh") {
-        await Schema.run(db, driver, (schema) => {
-          schema.drop(checkpointTable.name);
-        });
-        return;
-      }
-      throw new Error("Encryption rotation checkpoints require explicit administrative archival.");
+      await guardMigrationRollback(context, {
+        hasHistory: () => true,
+        message: "Encryption rotation checkpoints require explicit administrative archival."
+      });
+      await Schema.run(db, driver, (schema) => {
+        schema.drop(checkpointTable.name);
+      });
     }
   };
 }
@@ -7531,6 +7541,28 @@ import { join } from "path";
 import { pathToFileURL } from "url";
 init_dialect();
 var MIGRATIONS_TABLE = "framework_migrations";
+function validateMigrations(migrations, sources) {
+  if (!Array.isArray(migrations))
+    throw new Error("Migrations must be an array of definitions.");
+  const names = new Map;
+  for (const [index, migration] of migrations.entries()) {
+    const source = sources?.[index] ?? `migration at index ${index}`;
+    if (!migration || typeof migration !== "object" || Array.isArray(migration) || typeof migration.name !== "string" || migration.name.trim().length === 0 || typeof migration.up !== "function" || typeof migration.down !== "function") {
+      throw new Error(`Invalid ${source}: expected a migration with a non-empty string name and up/down functions.`);
+    }
+    const previous = names.get(migration.name);
+    if (previous !== undefined)
+      throw new Error(`Duplicate migration name "${migration.name}" in ${previous} and ${source}.`);
+    names.set(migration.name, source);
+  }
+}
+function requireMigrationDefinitions(applied, migrations, operation) {
+  const names = new Set(migrations.map(({ name }) => name));
+  const missing = applied.filter(({ name }) => !names.has(name)).map(({ name }) => name);
+  if (missing.length > 0) {
+    throw new Error(`Cannot ${operation}: missing applied migration definitions: ${missing.join(", ")}. Restore the migration files before retrying; history has not been removed.`);
+  }
+}
 function migrationsNameColumn() {
   return currentSqlDialect().driver === "mysql" ? "VARCHAR(255) PRIMARY KEY" : "TEXT PRIMARY KEY";
 }
@@ -7572,15 +7604,17 @@ async function getAppliedMigrations(db) {
 }
 async function loadMigrationsFromDirectory(directory) {
   const entries = await readdir(directory);
-  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && entry !== "types.ts" && entry !== "index.ts" && entry !== "runner.ts").sort();
+  const migrationFiles = entries.filter((entry) => (entry.endsWith(".ts") || entry.endsWith(".js")) && !entry.endsWith(".d.ts") && !["types", "index", "runner", "advisoryLock", "migrationDatabase"].some((name) => entry === `${name}.ts` || entry === `${name}.js`)).sort();
   const loadedMigrations = await Promise.all(migrationFiles.map(async (fileName) => {
     const moduleUrl = pathToFileURL(join(directory, fileName)).href;
     const module = await import(moduleUrl);
     return module.default;
   }));
-  return loadedMigrations.filter((migration) => migration?.name !== undefined);
+  validateMigrations(loadedMigrations, migrationFiles.map((file) => join(directory, file)));
+  return loadedMigrations;
 }
 async function getMigrationStatus(db, migrations) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedByName = new Map(applied.map(({ name, batch }) => [name, Number(batch)]));
   return migrations.map(({ name }) => ({
@@ -7590,6 +7624,7 @@ async function getMigrationStatus(db, migrations) {
   }));
 }
 async function runPendingMigrations(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   const appliedNames = new Set(applied.map(({ name }) => name));
   const nextBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0) + 1;
@@ -7605,6 +7640,7 @@ async function runPendingMigrations(db, migrations, options = {}) {
   return pendingMigrations.length;
 }
 async function migrateDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const { advisoryLock = false, onMigration } = options;
   if (advisoryLock) {
     return withMigrationLock(db, () => runPendingMigrations(db, migrations, { onMigration }));
@@ -7612,11 +7648,13 @@ async function migrateDatabase(db, migrations, options = {}) {
   return runPendingMigrations(db, migrations, { onMigration });
 }
 async function rollbackDatabase(db, migrations, options = {}) {
+  validateMigrations(migrations);
   const applied = await getAppliedMigrations(db);
   if (applied.length === 0) {
     return 0;
   }
   const lastBatch = applied.reduce((currentMax, { batch }) => Math.max(currentMax, Number(batch)), 0);
+  requireMigrationDefinitions(applied.filter(({ batch }) => Number(batch) === lastBatch), migrations, "roll back latest batch");
   const migrationsToRollback = new Set(applied.filter(({ batch }) => Number(batch) === lastBatch).map(({ name }) => name));
   let rolledBack = 0;
   for (const migration of [...migrations].reverse()) {
@@ -7634,8 +7672,10 @@ async function freshDatabase(db, migrations, options = {}) {
   if (options.destructive && isProductionEnv()) {
     throw new Error("Destructive migration reset is only available in development/test environments.");
   }
+  validateMigrations(migrations);
   const runFresh = async () => {
     const applied = await getAppliedMigrations(db);
+    requireMigrationDefinitions(applied, migrations, "reset database");
     const appliedNames = new Set(applied.map(({ name }) => name));
     const appliedMigrations = migrations.filter(({ name }) => appliedNames.has(name));
     for (const migration of [...appliedMigrations].reverse()) {
@@ -7644,9 +7684,7 @@ async function freshDatabase(db, migrations, options = {}) {
         await migration.down(db, { operation: "fresh" });
       else
         await migration.down(db);
-    }
-    if (appliedMigrations.length > 0) {
-      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE}`);
+      await db.unsafe(`DELETE FROM ${MIGRATIONS_TABLE} WHERE name = ${currentSqlDialect().placeholder(1)}`, [migration.name]);
     }
     await runPendingMigrations(db, migrations, options);
   };
@@ -10302,10 +10340,14 @@ function createOutboxMigration(name, driver, options = {}) {
           SELECT 1 FROM strata_outbox_event WHERE id = strata_outbox_delivery.event_id))`);
       }
     },
-    async down(db) {
-      const [row] = await db.unsafe("SELECT COUNT(*) AS pending FROM strata_outbox_delivery WHERE status <> 'completed'");
-      if (Number(row?.pending) > 0)
-        throw new Error("Cannot drop outbox tables while undelivered events remain.");
+    async down(db, context) {
+      await guardMigrationRollback(context, {
+        async hasHistory() {
+          const [row] = await db.unsafe("SELECT COUNT(*) AS pending FROM strata_outbox_delivery WHERE status <> 'completed'");
+          return Number(row?.pending) > 0;
+        },
+        message: "Cannot drop outbox tables while undelivered events remain."
+      });
       await db.unsafe("DROP TABLE strata_outbox_delivery");
       await db.unsafe("DROP TABLE strata_outbox_event");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.17",
+  "version": "2.2.20",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",