Reject duplicate module migration revisions

2026-08-03 15:04:18 +02:00
parent fa32cca03f
commit ad57fad1ea
3 changed files with 93 additions and 0 deletions
@@ -1,5 +1,11 @@
 # Module Lifecycle Recovery

+## Migration Revision Namespace
+
+All enabled module migration directories are assembled into one Alembic graph. Revision IDs are therefore global across Core and every module even though each module owns a separate `migrations/versions` directory. Core validates literal revision declarations before constructing the graph and rejects duplicates with both file paths. A module must assign a new globally unique revision ID; reusing another module's ID can otherwise make Alembic treat an unrelated schema change as already applied or report an ancestor/head overlap.
+
+When correcting a collision that has already reached a database, first verify the schema objects that identify which migration actually ran. Rename the unapplied migration, or transactionally translate the corresponding `alembic_version` row when the applied owner is unambiguous. Never add both colliding IDs as heads or blindly stamp the database.
+
 Package changes and live module-graph changes use Core's durable recovery
 ledger. The local `install.lock` still prevents duplicate work in one runtime
 directory; the database lease `core:module-lifecycle:deployment` is the