feat: add transactional module migration runner

README.md

@@ -11,9 +11,11 @@ capabilities, static module manifests, deterministic automatic discovery, compil
 a staged capability registry, dependency-ordered lifecycle with rollback, module-owned Drizzle table
 contracts, deterministic schema aggregation, and a cloneable backend-only module template. Migration
 artifacts now have module-owned Drizzle contracts, deterministic offline discovery, explicit
-destructive-change declarations, and exact checksums. Transactional migration execution, identity,
-HTTP routing, jobs, physical storage provisioning, surfaces, and feature modules remain later
-vertical slices.
+destructive-change declarations, and exact checksums. Core now provides read-only applied-history
+planning and a locked, whole-batch transactional PostgreSQL runner with exact external destructive
+approval matching. Live PostgreSQL runner integration coverage, production approval-provider
+composition, identity, HTTP routing, jobs, physical storage provisioning, surfaces, and feature
+modules remain later vertical slices.
 
 ## Quick start
 
@@ -25,9 +27,18 @@ cp .env.example .env
 pnpm infrastructure:up
 pnpm modules:validate
 pnpm migrations:validate
+pnpm migrations:plan
 pnpm verify
 ```
 
+`pnpm migrations:plan` uses `DATABASE_URL` from the uncommitted `.env` and is read-only.
+`pnpm migrations:apply` uses the same validated inventory but mutates PostgreSQL under Core's
+advisory lock and one transaction. Review the plan before applying. Destructive migrations are
+blocked by default and require an exact externally supplied approval; there is no force flag.
+
+The runner currently has deterministic unit coverage through a database port. Live PostgreSQL
+migration-runner tests are deferred and are not yet claimed by `pnpm verify`.
+
 Run `pnpm infrastructure:smoke` for an isolated end-to-end PostgreSQL and authenticated S3 check.
 
 The development services bind only to loopback: