test: add PostgreSQL migration integration coverage

docs/architecture/decisions/0009-transactional-module-migrations.md

@@ -122,10 +122,14 @@ messages, machine-specific paths, causes, stacks, or partial execution results.
 are reported without hiding the primary failure and without copying underlying exception text.
 
 The developer commands read `DATABASE_URL` from the environment. A local uncommitted `.env` may
-supply it, but commands never print it. This slice verifies database behavior through a narrow
-in-memory database port and unit tests. A real PostgreSQL integration suite for lock contention,
-DDL rollback, history creation, and driver behavior is deliberately deferred rather than claimed
-by the current verification gate.
+supply it, but commands never print it. This decision's implementation slice verified database
+behavior through a narrow in-memory database port and unit tests; it deliberately deferred live
+PostgreSQL evidence to a follow-up slice rather than claiming it at acceptance time.
+
+Implementation follow-up (2026-07-21): `pnpm test:migrations:integration` now runs the production
+adapter and migration services against disposable PostgreSQL for lock contention, DDL rollback,
+history creation, approvals, and sanitized driver failures. The Docker-backed command remains
+separate from the code-only `pnpm verify` gate.
 
 The transaction and single-client choices follow node-postgres's
 [transaction guidance](https://node-postgres.com/features/transactions). The non-blocking lock and
@@ -162,6 +166,6 @@ that invocation's schema or history changes committed. Destructive migrations ar
 a trusted approval provider is composed, by design.
 
 The all-or-nothing batch can hold locks for longer than per-migration transactions and excludes
-operations PostgreSQL forbids in a transaction. The current unit-tested database port gives fast,
-deterministic coverage but cannot prove real server behavior. The next infrastructure-focused
-slice must add live PostgreSQL tests before production operation is considered complete.
+operations PostgreSQL forbids in a transaction. The narrow database port continues to provide fast,
+deterministic unit coverage; the dated implementation follow-up above records the separate live
+PostgreSQL evidence added after this decision was accepted.

docs/architecture/platform-architecture.md

@@ -69,8 +69,9 @@ validated metadata, explicit destructive-change declarations, and exact SHA-256
 now compare that inventory with its fixed PostgreSQL history table, produce a read-only plan, and
 apply the complete pending batch under a session advisory lock and one transaction. Destructive
 migrations require an exact externally supplied approval bound to module, identity, and checksum.
+Hermetic integration coverage now exercises those contracts through the production adapter against
+the pinned PostgreSQL container, including real DDL rollback and advisory-lock concurrency.
 
-Target architecture, not yet implemented: production approval-provider composition, live
-PostgreSQL migration-runner integration coverage, Better Auth,
+Target architecture, not yet implemented: production approval-provider composition, Better Auth,
 permission enforcement, physical storage-bucket provisioning, Surface SDK, richer public resource
 and action contracts, API server, dashboard, Builder, and reference feature modules.