feat: add transactional module migration runner

docs/module-development/README.md

@@ -218,18 +218,20 @@ Run the module's `migration:generate` script with a lowercase snake-case name, r
 SQL and snapshot, and add the matching entry to `drizzle/meta/_ekklesia.json`. Every entry must
 explicitly declare either `{"mode":"none"}` or
 `{"mode":"approval-required","reason":"..."}`. Do not add an `approved` flag; approval will be
-an external Core-owned record bound to the migration checksum.
+supplied by an external Core-owned provider and bound to module ID, identity, and checksum.
 
 Migration identities are `<module-id>:<generated-tag>`. Core preserves Drizzle journal order inside
 each module and dependency-first discovery order between modules. It calculates SHA-256 from the
 exact SQL bytes, so changing whitespace or line endings changes the checksum. Never edit an
-already-applied migration; the future database history will detect checksum changes. Add a new
-forward migration instead. Downgrade and uninstall migrations are not supported.
+already-applied migration: Core compares the current exact checksum and metadata with its fixed
+PostgreSQL history and refuses changed, missing, unknown, or out-of-prefix entries. Add a new forward
+migration instead. Downgrade and uninstall migrations are not supported.
 
 A module may migrate only its own objects. SQL is intentionally treated as opaque: offline
 validation checks the artifact and metadata contract but cannot prove SQL ownership or classify
-destructive behavior. Review those properties explicitly. Core remains the only future migration
-executor.
+destructive behavior. Review those properties explicitly. Core is the only migration executor. It
+follows Drizzle's exact `--> statement-breakpoint` delimiter and never naively splits semicolons or
+falls back to non-transactional execution.
 
 ## Discovery and lifecycle
 
@@ -239,6 +241,7 @@ From the repository root, run:
 pnpm install
 pnpm modules:validate
 pnpm migrations:validate
+pnpm migrations:plan
 pnpm verify
 ```
 
@@ -260,6 +263,22 @@ Drizzle journals and snapshot chains, Ekklesia policy metadata, ordering, invent
 checksums atomically. Its concise report lists every installed module and migration in deterministic
 order.
 
+With `DATABASE_URL` set through the uncommitted root `.env`, `pnpm migrations:plan` performs a
+read-only applied-history comparison. The plan can become stale. `pnpm migrations:apply` is a
+separate, explicit database mutation: Core acquires its bounded session advisory lock, rereads and
+validates history, preflights the whole destructive-approval set, and applies all pending modules in
+dependency-first order in one transaction. If a later migration fails, every schema and history
+change from that invocation rolls back; migrations committed by an earlier invocation remain.
+
+An `approval-required` migration needs an approval from an external provider matching its module
+ID, exact identity, and exact checksum. Module metadata cannot grant approval, and there is no
+wildcard, force, or approve-all option. The default developer command supplies no approvals and
+therefore refuses destructive pending migrations.
+
+Runner behavior is unit-tested through a narrow database port. Live PostgreSQL coverage of DDL
+rollback, advisory-lock contention, and driver behavior is a deferred infrastructure slice; the
+current verification suite does not claim that coverage.
+
 Core completes discovery before importing any server entrypoint. It then loads and verifies every
 runtime definition before running hooks, registers all modules dependency-first into an unpublished
 staged capability registry, and starts them in the same order. Shutdown is reverse-order. If a later