feat(integration-tests-kotlin): close drop-blocked scenario via ExposedMigrationEngine — 12/12 conformance

dmealing · claude · dmealing · commit ba7f2dded880 · 2026-05-26T08:52:08.000-04:00
Small Kotlin migration facade on top of JetBrains Exposed that adds the one
substrate-level capability Exposed itself does not provide: a status pass that
classifies planned changes as additive vs destructive and blocks the
destructive ones unless the caller opts in via AllowOptions.

Mirrors the sibling Java port's SchemaMigrationEngine + AllowOptions +
BlockedChangesError contract. Scope intentionally narrow — table-level
CreateTable / DropTable, which is exactly what the corpus exercises on Kotlin.
Column-level additive diffs stay delegated to Exposed's
addMissingColumnsStatements (no gate needed — never destructive).

New scenario `drop-table-blocked-without-allow`: bootstraps a programs table
from v1 metadata, targets empty metadata, drives diff() with
allowDropTable=false. Asserts blocked.isNotEmpty(), apply() throws
BlockedChangesError naming the `allow.dropTable` flag, programs survives the
blocked apply, and the opposite leg (allowDropTable=true) actually drops it
proving the gate is policy not substrate.

Kotlin persistence-conformance corpus coverage: 12/12 (9 query + 3 migration).

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/ExposedMigrationEngine.kt b/server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/ExposedMigrationEngine.kt
@@ -0,0 +1,177 @@
+package com.metaobjects.integration.kotlin
+
+import org.jetbrains.exposed.sql.SchemaUtils
+import org.jetbrains.exposed.sql.Table
+import org.jetbrains.exposed.sql.transactions.transaction
+import java.sql.Connection
+
+/**
+ * Small Kotlin migration façade on top of JetBrains Exposed that adds the
+ * single substrate-level capability Exposed itself does not provide: a
+ * status pass that **classifies** planned changes as additive vs destructive
+ * and **blocks** the destructive ones unless the caller opts in via
+ * [AllowOptions].
+ *
+ * This closes the last persistence-conformance gap for the Kotlin port —
+ * the `drop-table-blocked-without-allow` scenario, where dropping an entity
+ * from metadata produces a drop-table change that the migration engine must
+ * refuse to apply without an explicit `allow.dropTable=true`.
+ *
+ * Mirrors the contract surfaced by the sibling Java port's
+ * `SchemaMigrationEngine` + `AllowOptions` + `BlockedChangesError`
+ * (see `server/java/omdb/src/main/java/com/metaobjects/manager/db/migrate/`).
+ * Scope is intentionally narrow: table-level adds + drops only — that is all
+ * the corpus scenarios actually exercise on Kotlin today. Column-level diffs
+ * stay delegated to Exposed's `addMissingColumnsStatements` (additive-only
+ * by design — no policy gate needed).
+ */
+
+/** Opt-in flags for destructive changes. Defaults to no-op (everything blocked). */
+data class AllowOptions(
+    val allowDropTable: Boolean = false,
+    val allowDropColumn: Boolean = false,
+    val allowTypeChange: Boolean = false,
+)
+
+/** A single planned change, classified by destructiveness. */
+sealed interface Change {
+    /** Whether this change destroys schema or data. */
+    val isDestructive: Boolean
+
+    /** Short symbolic kind name, matches the corpus YAML `blocked[].kind` value. */
+    val kind: String
+
+    data class CreateTable(val table: Table) : Change {
+        override val isDestructive = false
+        override val kind = "CreateTable"
+    }
+
+    data class DropTable(val tableName: String) : Change {
+        override val isDestructive = true
+        override val kind = "DropTable"
+    }
+}
+
+/** Result of diffing expected (Kotlin Tables) vs actual (live DB schema). */
+data class DiffResult(
+    /** Changes that are either additive, or destructive-but-allowed by the [AllowOptions]. */
+    val changes: List<Change>,
+    /** Destructive changes whose `allow.*` flag is not set. */
+    val blocked: List<Change>,
+)
+
+/**
+ * Thrown when [ExposedMigrationEngine.apply] sees destructive changes that
+ * were not allowed by the [AllowOptions]. Message names the flag that would
+ * unblock each one — matches the corpus YAML `reason-contains: 'allow.dropTable'`
+ * assertion shape.
+ */
+class BlockedChangesError(val blocked: List<Change>) :
+    RuntimeException(buildMessage(blocked)) {
+
+    companion object {
+        /** Map a change's kind to the `AllowOptions` flag name that unblocks it. */
+        private val ENABLE_FLAG: Map<String, String> = mapOf(
+            "DropTable" to "allow.dropTable",
+            "DropColumn" to "allow.dropColumn",
+            "ChangeColumnType" to "allow.typeChange",
+        )
+
+        private fun buildMessage(blocked: List<Change>): String {
+            val sb = StringBuilder(blocked.size.toString())
+            sb.append(" blocked change(s):")
+            for (c in blocked) {
+                val locator = when (c) {
+                    is Change.DropTable -> c.tableName
+                    is Change.CreateTable -> c.table.tableName
+                }
+                val flag = ENABLE_FLAG[c.kind] ?: "(no flag enables this)"
+                sb.append("\n  - ").append(c.kind).append(" on ").append(locator)
+                    .append(": pass ").append(flag)
+            }
+            return sb.toString()
+        }
+    }
+}
+
+object ExposedMigrationEngine {
+
+    /**
+     * Compute the diff between the expected Exposed `Table` set and the live
+     * DB schema reachable through [connection]. Classifies each change as
+     * additive vs destructive and partitions into `(allowed, blocked)` based
+     * on [allow].
+     *
+     * Scope: table presence only (`CreateTable` / `DropTable`). Column-level
+     * additive changes are computed by Exposed's `addMissingColumnsStatements`
+     * directly at the call site — they are never destructive so they need no
+     * gate.
+     */
+    fun diff(connection: Connection, expectedTables: List<Table>, allow: AllowOptions): DiffResult {
+        val actualTableNames = listLiveTableNames(connection)
+        val expectedTableNames = expectedTables.map { it.tableName }.toSet()
+
+        val planned = mutableListOf<Change>()
+        for (t in expectedTables) {
+            if (t.tableName !in actualTableNames) planned.add(Change.CreateTable(t))
+        }
+        for (a in actualTableNames) {
+            if (a !in expectedTableNames) planned.add(Change.DropTable(a))
+        }
+
+        val (allowed, blocked) = planned.partition { allowsChange(it, allow) }
+        return DiffResult(allowed, blocked)
+    }
+
+    /**
+     * Apply allowed changes via Exposed. Throws [BlockedChangesError] if any
+     * blocked changes are present — nothing is executed in that case
+     * (matches the corpus contract: `No 'apply-up-then-query' — the up SQL
+     * is non-empty but blocked; runner should NOT execute it`).
+     */
+    fun apply(
+        connection: Connection,
+        database: org.jetbrains.exposed.sql.Database,
+        expectedTables: List<Table>,
+        allow: AllowOptions,
+    ) {
+        val diff = diff(connection, expectedTables, allow)
+        if (diff.blocked.isNotEmpty()) throw BlockedChangesError(diff.blocked)
+
+        // Partition by kind — Exposed's CREATE path takes a vararg of Tables,
+        // drops take a vararg of Tables too (we synthesize a stub Table for
+        // bare tableName strings — but the corpus scenarios that produce drops
+        // start from an actual Exposed Table at seed time, so this path is
+        // exercised differently per scenario).
+        val drops = diff.changes.filterIsInstance<Change.DropTable>()
+        val creates = diff.changes.filterIsInstance<Change.CreateTable>().map { it.table }
+
+        transaction(database) {
+            if (creates.isNotEmpty()) SchemaUtils.create(*creates.toTypedArray())
+            // For drops we use raw SQL — Exposed's `SchemaUtils.drop` requires
+            // a `Table` instance, not a bare name. Quote the identifier to
+            // match the live-schema casing returned by JDBC metadata.
+            for (drop in drops) {
+                exec("""DROP TABLE IF EXISTS "${drop.tableName}"""")
+            }
+        }
+    }
+
+    private fun allowsChange(change: Change, allow: AllowOptions): Boolean = when (change) {
+        is Change.DropTable -> allow.allowDropTable
+        is Change.CreateTable -> true
+    }
+
+    /**
+     * List base tables in the `public` schema via JDBC metadata. Mirrors the
+     * corpus's `apply-up-then-query` baseline (`information_schema.tables`
+     * filtered to `table_schema = 'public' AND table_type = 'BASE TABLE'`).
+     */
+    private fun listLiveTableNames(connection: Connection): Set<String> {
+        val out = mutableSetOf<String>()
+        connection.metaData.getTables(null, "public", "%", arrayOf("TABLE")).use { rs ->
+            while (rs.next()) out.add(rs.getString("TABLE_NAME"))
+        }
+        return out
+    }
+}
diff --git a/server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/MigrationScenarioConformanceTest.kt b/server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/MigrationScenarioConformanceTest.kt
@@ -8,8 +8,10 @@ import org.jetbrains.exposed.sql.Database
 import org.jetbrains.exposed.sql.SchemaUtils
 import org.jetbrains.exposed.sql.transactions.transaction
 import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
 import java.sql.DriverManager
 import kotlin.test.assertEquals
+import kotlin.test.assertFalse
 import kotlin.test.assertTrue
 
 /**
@@ -28,14 +30,13 @@ import kotlin.test.assertTrue
  *    invoke addMissingColumnsStatements with v2 → assert it surfaces
  *    `ALTER TABLE ... ADD COLUMN "subtitle" VARCHAR(200)` (Exposed's quoting
  *    matches the corpus `up-contains` expectation), apply it, then query.
- *
- * Deferred:
- *  - drop-table-blocked-without-allow: needs a destructive-change-blocking
- *    pipeline. Exposed has no analogue — its diff helpers
- *    (`addMissingColumnsStatements` / `statementsRequiredToActualizeScheme`)
- *    only ADD, never DROP. The "blocked" semantic is part of OMDB's
- *    SchemaMigrationEngine + AllowOptions, not the substrate. Re-evaluate
- *    only if a Kotlin-side migration façade is built on top of Exposed.
+ *  - [drop_table_blocked_without_allow]: bootstrap v1 (`programs`), declare
+ *    an empty expected table set (the target metadata has no entities), and
+ *    drive the diff through [ExposedMigrationEngine]. Asserts that
+ *    [ExposedMigrationEngine.diff] surfaces a blocked DropTable, that
+ *    [ExposedMigrationEngine.apply] throws [BlockedChangesError], and that
+ *    the `programs` table is NOT dropped from the live schema — closes the
+ *    last persistence-conformance gap for the Kotlin port.
  *
  * NOT registered in the parent reactor — run via:
  *   mvn -f server/java/integration-tests-kotlin/pom.xml test
@@ -174,6 +175,104 @@ internal class MigrationScenarioConformanceTest {
         }
     }
 
+    @Test
+    fun `drop table blocked without allow refuses to drop and surfaces the block`() {
+        val corpus = ScenarioLoader.findCorpusRoot()
+        val scenarios = ScenarioLoader.loadMigrations(corpus.resolve("migrations"))
+        val scenario = scenarios.singleOrNull { it.name == "drop-table-blocked-without-allow" }
+            ?: error("Expected scenario 'drop-table-blocked-without-allow' in corpus")
+
+        PostgresContainer().use { pg ->
+            val db = Database.connect(pg.jdbcUrl, user = pg.username, password = pg.password)
+
+            // 1. Bootstrap the seed-metadata state — `programs` table with id + title.
+            //    Mirrors the v1 metadata in fixtures/persistence-conformance/migrations/states/program-v1/.
+            transaction(db) {
+                SchemaUtils.create(ProgramV1Table)
+            }
+
+            // 2. Build the "expected" Table set for the target metadata. The
+            //    target is empty (`target-metadata-inline: { ... children: [] }`),
+            //    so the expected set is empty too — the diff should surface a
+            //    drop-table for `programs`.
+            val expectedTables = emptyList<org.jetbrains.exposed.sql.Table>()
+
+            // 3. Drive the diff with allowDropTable = false (the scenario's
+            //    "without-allow" leg). Confirm the destructive change is
+            //    classified as blocked, not allowed.
+            val diff = DriverManager.getConnection(pg.jdbcUrl, pg.username, pg.password).use { c ->
+                ExposedMigrationEngine.diff(c, expectedTables, AllowOptions(allowDropTable = false))
+            }
+
+            assertTrue(
+                diff.blocked.isNotEmpty(),
+                "expected drop-table to be blocked without allowDropTable; diff=$diff"
+            )
+            assertTrue(
+                diff.blocked.any { it is Change.DropTable && it.tableName == "programs" },
+                "expected blocked DropTable for 'programs'; blocked=${diff.blocked}"
+            )
+
+            // 4. Cross-check against the corpus expectation shape:
+            //    blocked[].kind == 'DropTable' and reason-contains 'allow.dropTable'.
+            for (expectedBlock in scenario.expect.blocked) {
+                val match = diff.blocked.any { it.kind == expectedBlock.kind }
+                assertTrue(match, "expected blocked kind '${expectedBlock.kind}' not found in $diff")
+            }
+
+            // 5. Calling apply() must throw BlockedChangesError, and the message
+            //    must name the `allow.dropTable` flag (the corpus's
+            //    `reason-contains` value).
+            val err = assertThrows<BlockedChangesError> {
+                DriverManager.getConnection(pg.jdbcUrl, pg.username, pg.password).use { c ->
+                    ExposedMigrationEngine.apply(c, db, expectedTables, AllowOptions(allowDropTable = false))
+                }
+            }
+            for (expectedBlock in scenario.expect.blocked) {
+                val needle = expectedBlock.reasonContains
+                if (needle.isNotBlank()) {
+                    assertTrue(
+                        err.message!!.contains(needle),
+                        "expected BlockedChangesError message to contain '$needle'; got: ${err.message}"
+                    )
+                }
+            }
+
+            // 6. Critically: the `programs` table must still exist in the live
+            //    schema. The corpus contract is "runner should NOT execute the
+            //    up SQL when blocked" — apply() must be transactionally inert.
+            val liveTables = DriverManager.getConnection(pg.jdbcUrl, pg.username, pg.password).use { c ->
+                val out = mutableSetOf<String>()
+                c.metaData.getTables(null, "public", "%", arrayOf("TABLE")).use { rs ->
+                    while (rs.next()) out.add(rs.getString("TABLE_NAME"))
+                }
+                out
+            }
+            assertTrue(
+                "programs" in liveTables,
+                "expected 'programs' to still exist after blocked apply; liveTables=$liveTables"
+            )
+
+            // 7. Sanity: passing allowDropTable=true allows the drop through —
+            //    proves the gate is the policy, not the substrate. (Same
+            //    engine, opposite leg of the same scenario.)
+            DriverManager.getConnection(pg.jdbcUrl, pg.username, pg.password).use { c ->
+                ExposedMigrationEngine.apply(c, db, expectedTables, AllowOptions(allowDropTable = true))
+            }
+            val liveTablesAfterAllow = DriverManager.getConnection(pg.jdbcUrl, pg.username, pg.password).use { c ->
+                val out = mutableSetOf<String>()
+                c.metaData.getTables(null, "public", "%", arrayOf("TABLE")).use { rs ->
+                    while (rs.next()) out.add(rs.getString("TABLE_NAME"))
+                }
+                out
+            }
+            assertFalse(
+                "programs" in liveTablesAfterAllow,
+                "expected 'programs' to be dropped once allowDropTable=true; liveTables=$liveTablesAfterAllow"
+            )
+        }
+    }
+
     /**
      * Normalize a SQL fragment to a shape-only signature so different emitters
      * (Java/TS/C# vs Exposed) can be compared structurally without coupling to
