Add Inter-Hub migration bundle importer

docs/specs/testing-release-and-migration.md

@@ -30,6 +30,67 @@ A Core Hub release cannot replace Inter-Hub until:
 - Run dual-read or shadow smokes.
 - Switch traffic only after smoke evidence is recorded.
 
+## Migration Bundle v1
+
+Core Hub staging imports use `core-hub.migration.v1` JSON bundles. The bundle is
+the handoff contract from the Haskell Inter-Hub export path into the Python/FastAPI
+replacement:
+
+- `schemaVersion`: `core-hub.migration.v1`
+- `source`: normally `inter-hub-haskell`
+- `exportedAt`: export timestamp for operator traceability
+- `records.hubs`
+- `records.hubCapabilityManifests`
+- `records.apiConsumers`
+- `records.apiKeys`
+- `records.widgets`
+- `records.interactionEvents`
+
+API key records may contain `keyPrefix`, `keyHash`, scopes, status, and lifecycle
+metadata. They must not contain full key material, raw tokens, or secrets. Existing
+runtime keys are not recoverable from Inter-Hub unless an approved custody path
+provides them; migration preserves only non-secret evidence.
+
+The reference schema is
+`contracts/schemas/migration-bundle.schema.json`, with a minimal fixture at
+`contracts/fixtures/migration/interhub-minimal.bundle.json`.
+
+## Import Procedure
+
+Validate a bundle without database access:
+
+```bash
+PYTHONPATH=src uv run --extra dev python scripts/core_hub_migrate.py validate \
+  contracts/fixtures/migration/interhub-minimal.bundle.json
+```
+
+Dry-run against the configured target database:
+
+```bash
+CORE_HUB_DATABASE_URL=postgresql+asyncpg://... \
+PYTHONPATH=src uv run --extra dev python scripts/core_hub_migrate.py import \
+  /secure/operator/path/interhub-export.bundle.json --dry-run
+```
+
+Import after the dry-run report is reviewed:
+
+```bash
+CORE_HUB_DATABASE_URL=postgresql+asyncpg://... \
+PYTHONPATH=src uv run --extra dev python scripts/core_hub_migrate.py import \
+  /secure/operator/path/interhub-export.bundle.json
+```
+
+Each successful import writes a `migration_runs` row containing the source,
+schema version, bundle SHA-256, row counts, warnings, and relationship checks.
+
+## Rollback Procedure
+
+For staging, reset the target database and replay the same bundle after fixing the
+export or mapper. For production cutover, take a database snapshot before import,
+keep Inter-Hub read-only during verification, and roll traffic back to Inter-Hub if
+row counts, relationship checks, or consumer smokes fail. Do not delete or rotate
+legacy key custody records during the rollback window.
+
 ## Haskell Retirement Gate
 
 Do not retire production Inter-Hub or the haskelseed/Haskell build lane until Core Hub serves the required compatibility surface and production traffic has moved.