Backend roadmap: resumable backend-to-backend migration with verified fidelity and fenced cutover #1589

Type: implementation slice of the accepted SDK-first/backend-neutral direction; precise API and adapter design remain proposals. Parent: #1399, not a reported migration failure. Depends on authoritative backend identity/revision/export/import capability contracts and #1472 preservation/admission. Existing schema evolution and workspace snapshot recovery are foundations, not a complete cross-backend migration claim.

Evidence: snapshot manifest hashes file paths/bytes; schema migration evolves metadata over current stores; workspace transaction owns a local journal/writer-lock root. Keep those contracts intact while adding semantic cross-backend transfer.

Outcome: one shared SDK planner/executor, exposed by a thin CLI. Users do not need custom per-backend migration scripts or recreate PM items (losing provenance/history) to switch storage.

Bounded implementation:

1. Read-only plan: capture source/destination identities, capability/version checks, source revision/coherent snapshot requirement, counts, conflicts, mapped metadata and unsupported semantics. Separate lossless migration from explicitly acknowledged lossy export. Unsupported required preservation blocks before destination mutation.
2. Capture recoverable source evidence and destination-before state appropriate to each backend. Preserve stable IDs/references, relationships/tombstones, taxonomy/status/schema/settings, unknown supported fields, actor/timestamp/history provenance and immutable artifact references. Exclude clone-local caches/locks; explicitly classify each inventory domain, including pending transactions/jobs. Never silently transfer active leases as valid ownership.
3. Transfer into a staged destination with a durable resumable receipt, stable operation identity and conditional writes. Repeated retries/restarts cannot duplicate history or items. Destination conflicts and source changes must be reconciled by the plan, not overwritten blindly.
4. Validate semantic counts/content/history/relationships and format compatibility independently of the importer. Preserve exact historical integrity material where required; database row order or JSON reserialization is not permission to rewrite historical evidence. Keep path-byte snapshots distinct from canonical semantic transfer digests.
5. Cut over only after source writers are quiesced/fenced or supported change capture reaches a verified barrier and destination verification succeeds. Start with safe quiesced migration; online replication is a separate later capability, not required for first delivery. Failure before cutover keeps the source authoritative. After new destination writes, rollback requires reconciliation—not blindly switching back to stale source.

Acceptance:

• Filesystem → native database → filesystem round-trip preserves the declared semantics; each supported database pair reuses the engine, not pairwise bespoke business logic.
• Dry-run performs no writes. Traces cover interruption before/during transfer, lost acknowledgements, concurrent source/destination writers, refusal, resumable rerun, verification mismatch and cutover failure.
• Verification/refusal leaves original data intact, reports precise unsupported/lossy fields, and never reports successful migration solely from item counts or successful exit of a copy command.
• Shared SDK result contains versioned source/destination identity, frozen revisions/barriers, plan/receipt, preservation report and explicit authority/cutover outcome; CLI renders it without duplicating semantics.
• Synthetic fixtures only for initial tests, telemetry/live integrations disabled; no implicit configuration switch, deletion, database provisioning, deployment or destructive cleanup. Retention/cleanup is explicit and separately confirmed.

Tradeoff: a universally lossless migration into arbitrary third-party providers is not promised. A provider that cannot retain history, arbitrary metadata or stable references must expose that limitation and refuse a required lossless migration, rather than maintaining an undisclosed shadow PM store.

Intake: Targeted all-status issue searches and canonical source records were rechecked on 2026-10-25. Reuse #1399 / pm-gh1399 as the parent; if a more specific canonical owner already covers this slice, attach it there rather than create a competing PM item. This report is static source evidence at df5bf4aa4db17b7743b4f6bfddb32098f2cbd521, not executed backend tests or a claim of a reproduced defect. No deadline, assignee, deployment or backend switch is implied.