test: validate M3 imports and locking on PostgreSQL

Add isolated PostgreSQL fixtures, two-session locking coverage, and a disposable remote Docker test runner. Correct the canonical-root fixture and document verified SQLite and PostgreSQL results.

docs/postgres-tests.md

@@ -0,0 +1,47 @@
+# PostgreSQL integration tests
+
+From a checkout on a Linux Docker host, run:
+
+```sh
+sh bin/test-postgres.sh
+```
+
+This builds `docker/php/Dockerfile.test` from the current checkout and lockfile,
+starts a disposable PostgreSQL 17 container on a unique network, runs the full
+suite with PostgreSQL enabled, then runs lint. It publishes no ports, mounts no
+existing database volumes, and removes its database container, network and test
+image on exit. Build layers remain cached. PHP 8.4 is used for the PHPUnit 12 test
+runtime; the production image is unchanged. Docker and network access for the
+initial image/dependency build are required.
+
+For remote validation, copy the current source to a **separate** remote directory
+(do not overwrite an existing dirty checkout), then execute the command there.
+Do not copy `.env`, host `vendor`, collection directories or other secrets.
+Capture the command exit status along with its output.
+
+## Existing dedicated test database
+
+Alternatively, export these variables before invoking `composer test`:
+
+```sh
+export MESHVAULT_TEST_PG_DSN='pgsql:host=127.0.0.1;port=5432;dbname=meshvault_test'
+export MESHVAULT_TEST_PG_USER=meshvault_test
+# Supply MESHVAULT_TEST_PG_PASSWORD securely through your environment.
+composer test
+```
+
+Use a dedicated test database and a role permitted to create schemas. Each test
+migrates production Phinx migrations into a randomly named schema, sets its
+connections' search path to that schema only, and drops that schema on teardown.
+Configured connection or migration errors fail the suite rather than skip it.
+An abruptly killed process may leave `meshvault_test_*` schemas; only remove
+schemas known to belong to a finished test run.
+
+Without `MESHVAULT_TEST_PG_DSN`, repository and pipeline tests continue to use
+SQLite and the five PostgreSQL-only tests skip. Those tests cover schema isolation,
+overlapping claims using `SKIP LOCKED`, rollback/reclaim, and item-lock timeout and
+retry using two independent PDO sessions. They are not a multiprocess load test.
+
+The older `MigrationTest` suite uses the separate application `MESHVAULT_DB_*`
+variables and remains skipped in this isolated runner. Production migrations are
+nevertheless exercised by the repository/pipeline fixtures on PostgreSQL.

docs/superpowers/plans/2026-10-11-m3-import-indexing-engine.md

@@ -185,14 +185,33 @@
 - Live CLI exit-code probe: `help`=0, `bogus`=1, no args=1, `import` (no path)=1,
   `worker --sleep=x`=1, `worker-once extra`=1, `import C:\nope` (unconfigured env)=2.
 
+### PostgreSQL follow-up validation (2026-10-12)
+
+- Windows SQLite/default run: **291 tests, 1801 assertions, 22 skips**, test exit 0;
+  lint exit 0.
+- Remote isolated workspace `/tmp/meshvault-pg-tests-20261011` on `192.168.2.23`:
+  PHP 8.4.26, PostgreSQL 17, **291 tests, 1863 assertions, 7 skips**, runner exit 0
+  after both tests and lint. Log: `/tmp/meshvault-pg-run.log`.
+- Existing `/tmp/MeshVault` checkout and dev database were not modified. Disposable
+  database/test containers and network were removed after the run.
+- Linux execution uncovered an invalid canonical-root fixture: it supplied a symlink root,
+  intentionally rejected by PathSafety. It now uses a safe noncanonical trailing separator
+  and runs on Windows too. No production safety policy was weakened.
+- New test tooling and follow-up changes are included in the PostgreSQL validation follow-up
+  commit; the original M3 work is in `9d277d9`.
+
 ### Limitations
 
-- **PostgreSQL was not exercised.** Integration tests run against SQLite built from the Phinx
-  migrations; `FOR UPDATE SKIP LOCKED` is driver-detected but unverified on a live server.
-  `tests/Integration/MigrationTest.php` still skips without DB credentials.
+- **PostgreSQL exercised on 2026-10-12.** The isolated remote Docker runner uses PostgreSQL 17
+  and production Phinx migrations for the repository and import pipeline suites. Two-session
+  tests verify overlapping `SKIP LOCKED` claims, rollback/reclaim, item lock timeout/retry,
+  explicit `FOR UPDATE` read locking and schema isolation. This is not a multiprocess load test.
+  The older `MigrationTest` still skips without application DB credentials; the runner does
+  not point it at the existing dev database. See `docs/postgres-tests.md`.
 - **Signals are POSIX-only.** `bin/meshvault` installs `SIGTERM`/`SIGINT` handlers when `pcntl`
   is available; on Windows the worker stops only at `--max-iterations`.
 - Graceful stop is verified between items, not mid-copy.
 - Symlink unit tests skip on hosts that cannot create links (11 skips here).
-- Nothing is committed, merged or pushed; all work is uncommitted in the working tree.
+- Original M3 work was committed as `9d277d9`; PostgreSQL validation is recorded in the
+  subsequent follow-up commit.