V6 Phase 2 complete

docs/data_migration.md

@@ -19,13 +19,36 @@ Optional source overrides:
 - `--source-db <path-or-sqlalchemy-url>`
 - `--source-upload-dir <path>`
 
-### 2) Import bundle into a fresh DB + uploads root
+### 2) Import bundle into a fresh target (SQLite or PostgreSQL)
 
 ```bash
 uv run python tools/export_import_migration.py import --bundle-dir .migration-bundle --target-db .\data\transcription-new.db --target-upload-dir .\data-new
 ```
 
-### 3) One-shot export+import
+PostgreSQL target example:
+
+```bash
+uv run python tools/export_import_migration.py import --bundle-dir .migration-bundle --target-db postgresql://transcription:change-me@localhost:5432/transcription --target-upload-dir .\data-new
+```
+
+### 3) Verify migration parity and integrity
+
+```bash
+uv run python tools/export_import_migration.py verify --source-db .\data\transcription.db --target-db postgresql://transcription:change-me@localhost:5432/transcription
+```
+
+The verify command checks:
+
+- row-count parity across migration tables
+- orphan-reference checks for `source`, `job`, `job_source`, and `execution_attempt`
+- duplicate `(job_id, source_id, attempt_number)` in `execution_attempt`
+
+Exit code:
+
+- `0` when counts and integrity checks pass
+- `1` when mismatches or integrity violations are detected
+
+### 4) One-shot export+import
 
 ```bash
 uv run python tools/export_import_migration.py migrate --bundle-dir .migration-bundle --target-db .\data\transcription-new.db --target-upload-dir .\data-new
@@ -50,9 +73,22 @@ Legacy V4.x portrait/homepage backfill in the export step:
 - Legacy homepage markdown is relocated from `UPLOAD_DIR/homepage/homepage.md` to `UPLOAD_DIR/homepage.md`.
 - Legacy `person.full_name` values are split into `given_names` + `last_name` for V5.1 schema compatibility.
 
-## Cutover
+## Cutover (SQLite -> PostgreSQL)
 
 After importing to a fresh target:
-1. Stop the app.
-2. Point `DATABASE__*` and `UPLOAD_DIR` to the new targets.
-3. Start the app and run smoke checks (`/healthz`, create/upload/process one job).
+1. Stop app and worker services to freeze writes.
+2. Export a migration bundle from the last SQLite state.
+3. Import bundle to PostgreSQL target.
+4. Run `verify` against source and target before switching runtime.
+5. Switch runtime config to PostgreSQL (`DATABASE__DRIVER=postgres` and related `DATABASE__*` values).
+6. Start app and worker services.
+7. Run smoke checks (`/healthz`, create/upload/process one job).
+
+## Rollback
+
+If verify or smoke checks fail:
+
+1. Stop app and worker services.
+2. Revert runtime config to SQLite.
+3. Start app and worker against pre-cutover SQLite database.
+4. Preserve failed migration bundle and logs for analysis.

docs/production-runbook.md

@@ -20,6 +20,7 @@ This runbook is the operational checklist for releasing and monitoring the trans
 
 1. Deploy artifact/config to target environment.
    - V6.0 Phase 1 production stack: `docker compose -f docker-compose.production.yml up -d --build`
+   - For SQLite -> PostgreSQL cutover, run `uv run python tools/export_import_migration.py verify --source-db <sqlite-path-or-url> --target-db <postgres-url>` before switching runtime.
 2. Validate service startup:
    - `/healthz` responds `200`
    - if `RUN_EMBEDDED_WORKER=true`, `worker.state` is `running`

docs/v6_0_hosting_migration_plan.md

@@ -38,6 +38,11 @@ Persistence:
 2. Run migration in staging-like environment and validate entity counts and key relationships.
 3. Execute cutover with rollback guardrails and preserved evidence/provenance history.
 
+Implemented workflow references:
+
+- `tools/export_import_migration.py` (`export`, `import`, `migrate`, `verify`)
+- `docs/data_migration.md` for cutover and rollback procedure
+
 ## 3.3 Cloudflare remote access
 
 1. Configure tunnel routing for service hostnames.