Migrating a workspace
Migration is a planned failover. It moves a workspace to a new home without changing its identity or address, so the user keeps their inbox and feed and every reference that points at the workspace keeps resolving. This runbook covers when to migrate (versus clone), the in-org sequence, failing back, and the extra gates when the destination is in another organization.
It builds on the workspace mobility concepts; read that first for the clone/migrate/failover distinction.
- A distinct destination cell or node, a migrate on a single-cell deployment refuses (nothing to move to).
- The destination can satisfy the workspace's protection policy (replication factor / erasure width / anti-affinity) and its residency constraint.
- A governance net-gain guard for a real (non-dry-run) run, without one, the migrate refuses.
First: do you want a clone or a migrate?
| You want to… | Use | Why |
|---|---|---|
| Keep the user's inbox/feed and move where the data lives | Migrate | Identity and address are preserved; the source is retired |
| Branch an environment to experiment, keeping the original | Clone | A new identity and address; the source stays live |
| Recover after the source was lost | Failover | Unplanned promotion of a standby |
If you need the original to keep existing, you want a clone, stop here and use the cloning runbook. The rest of this page is the migrate path.
The in-org migrate sequence
A migrate runs as a fail-closed, resumable saga. The order is what makes it safe: bytes move before the source is fenced, and the source is retired only after the destination is proven complete and healthy.
Figure: the migrate saga. The move asserts the identity-preserving plan first (a plan that would mint a new address is rejected outright), then moves bytes while the source still serves, gates on a fail-closed completeness reconcile, fences the source (aborting on a bad epoch to avoid split-brain), repoints resolvers to the new home, drains in-flight work, and releases (retires) the source only after the destination is confirmed healthy, otherwise it rolls back inside the fenced window and refuses.
Table equivalent
| Step | What happens | On failure |
|---|---|---|
| Assert identity | Verify the plan preserves id + address | Refuse: "a clone wearing a migrate label" |
| Move bytes | Copy planes to the destination while the source still serves | Source intact and serving; retry |
| Reconcile | Fail-closed completeness gate: destination must hold a complete snapshot | Abort; source never fenced |
| Fence | Fence the source home (verified epoch required) | Abort on a non-positive epoch |
| Repoint | Swing resolvers to the new home: shard primaries first, then the home switch, then followers | Ordered so a resolve is never blackholed mid-cutover |
| Drain | Held inbox messages re-delivered on the new home; running agents re-anchored | Re-anchor is best-effort |
| Confirm | Destination health check | If unhealthy → roll back |
| Release | Retire the source | Only reached once destination is complete and healthy |
The move is recorded on the hash-chained mobility activity ledger after cutover, the release is irreversible, so the record follows the fact.
Failing back
Failback is the same operation with source and destination swapped. If you need to return a workspace to its original home, run the migrate in reverse; it takes the same completeness and health gates, and the same net-gain guard. Because a migrate retires its source, a failback is a fresh planned move back, not an undo of a retained copy.
Cross-organization migrate
Moving to a different organization runs the same saga with the destination in another org, wrapped in the cross-org trust overlay. Every overlay gate is checked deny-closed before any byte crosses:
Figure: the cross-org migrate gate ladder. The amber gates (consent, egress, residency, protection placement) are all deny-closed and run before any byte crosses; the key is resealed under the destination organization's cell key (cyan); only then does the same migrate saga run; and the operation seals a signed manifest into both organizations' audit chains (green). Any gate that fails refuses, nothing moves.
Table equivalent
| Gate | Passes when | On failure |
|---|---|---|
| Consent | Owner auth (workspace) / N-of-M all collaborators (clean room) | Refuse |
| Egress | Every resource class is permitted (default-deny) | Refuse |
| Residency | The destination org's cells are admitted | Refuse |
| Protection placement | Destination cells satisfy RF / EC / anti-affinity | Refuse: never collapse onto one cell |
| Key reseal | Key material re-wraps under the destination org's cell key | Abort before the source is fenced |
| Audit | Signed manifest seals into both orgs' chains | Fail-closed if neither observer seals |
On a cross-org migrate the workspace's identity is preserved for the user, but its principals are remapped to target-org principals, and cross-org trust paths (SSH keys, federated identity links) and source-org secrets are not carried, a move across a trust boundary does not smuggle the old organization's trust with it.
Across the deployment matrix
| Corner | Migrate behavior |
|---|---|
| Single-cell | Refuses: no distinct target |
| Multi-cell (same org) | Full saga; residency and protection choose the target |
| Cross-organization | Same saga plus the deny-closed trust overlay; dual-audited |
| Air-gapped | Plane bundles and the signed manifest move by physical media and store-and-forward, verified at the destination |
Related topics
- Workspace mobility, the clone/migrate/failover model and the eight planes.
- Cloning, when you want a copy instead of a move.
- Disaster recovery, the unplanned failover this saga is modeled on.
- Data residency, the constraint bounding where a migrate may land.
- Replication, DR & federation, the protection placement and cross-org cryptographic model a migrate honors.