Workspace mobility
A workspace or clean room is a whole, portable environment (not a folder) so moving one is a first-class, governed operation, not an out-of-band script. This page is the map of the mobility plane: the operations that copy, move, reshape, and retire a workspace, and the invariants that keep every one of them consistent and provable.
It is the umbrella over the per-operation pages: cloning (the copy-on-write mechanics), migrating a workspace (the identity-preserving move), disaster recovery (the unplanned failover), and the day-to-day lifecycle operations (rename, promote, snapshot, merge/split, quarantine, archive).
Three verbs, and the difference that matters
The load-bearing distinction is what happens to the workspace's identity and address. Three verbs, three answers:
Figure: clone vs migrate vs failover. Clone mints a new identity and a new address and leaves the source live (a copy). Migrate keeps the same identity and address and moves the home, the source is fenced, then retired once the destination is proven (a planned move). Failover also keeps identity and address, but is the unplanned promotion of a standby after the source is lost. Ceiling: workspace clones materialize as copy-on-write or deep; a "live" copy that tracks the source is the province of failover/failback, not a clone mode.
Table equivalent
| Verb | Identity (id) | Address (inbox/feed) | Source afterward | Planned? |
|---|---|---|---|---|
| Clone | New | New | Stays live | Yes: a copy |
| Migrate | Kept | Kept | Fenced, then retired once destination proven | Yes: a planned move |
| Failover | Kept | Kept | Lost (that is why you failed over) | No: an unplanned recovery |
Because migrate keeps the address, a migrated user keeps their inbox and feed, that is the defining property, and the migrate engine refuses a plan that would mint a new address ("a clone wearing a migrate label") before any effect.
Every entity keeps a home
Underneath all of this is one invariant: every entity has exactly one default workspace, and that workspace keeps the entity addressable. The entity's messaging inbox and feed both resolve through that default workspace, so a mobility operation must never leave an entity with zero defaults (unaddressable) or two (ambiguous). The rule is enforced at the database (partial-unique indexes), at boot, and by a runtime reconciler, and lifecycle states that have been deliberately torn down (archived, retired, soft-deleted, purged) are exempted so the reaper and the invariant never fight.
This is why several operations below refuse rather than proceed: promoting or merging away an entity's sole default, or a migrate that would change the address, would break addressability, so the engine stops.
Eight planes move together
A workspace is not one database. It is eight canonical domains, and any move carries all of them consistently:
- Three bulk planes (storage: data, and messaging) move through per-service coordinators that know how to copy-on-write each store.
- Five metadata planes: directory, catalog, system, compute, and sessions, move through a metadata copier that row-copies in dependency order and remaps keys so the destination is internally consistent.
The plan is derived from the live schema, never hand-listed: a resource-graph walk enumerates every canonical table and asserts completeness fail-closed (nothing is silently skipped) before any bytes move. The move then runs as a compensating saga (an ordered plan of steps, each with an inverse) persisted step-by-step so a failure (or a governance stop) rolls back newest-first and leaves no half-moved environment, and the whole run is resumable from its ledger after a crash.
Crossing an organization is a trust overlay
A move inside one organization runs under that organization's own authority. A cross-organization move is cross-node plus a trust overlay that is checked deny-closed before a single byte crosses:
| Gate | What it requires |
|---|---|
| Consent | Explicit authorization: one owner for a workspace; N-of-M consent from every collaborator organization for a clean room (cross-org clean-room moves are default-prohibited) |
| Egress | Per-resource-class default-deny; each class must be permitted |
| Residency | A residency gate must admit the destination organization's cells |
| Identity remap | Owner, org, domain, and every principal reference are remapped to target-org principals; cross-org trust paths (SSH, federated identity links) are dropped, and source-org secrets are never carried |
| Protection placement | The destination cells must satisfy replication factor / erasure width / anti-affinity: a destination that cannot is refused, never collapsed onto one cell |
| Key reseal | The workspace's key material is re-sealed under the destination organization's cell key before the source is fenced |
Every cross-org move seals a signed, itemized manifest into both organizations' hash-chained audit records with an identical content hash, so neither party can later deny what moved. This mirrors the cross-organization replication model: a partner relationship is a directory trust edge, and revoking it is dropping an edge, not rotating a shared secret.
Every move is provable
Mobility is not a quiet background copy, it leaves two independent records:
- A durable saga ledger records every step of the move, and the terminal step writes a signed move manifest into the audit chain.
- A hash-chained mobility activity ledger records the operation tamper-evidently and
is independently
verify_chain()-verifiable. A cloned clean room does not copy the source's chain (that would break verification, which binds the source's identity); instead the destination starts a fresh chain seeded with a genesis event that carries what it was cloned from, the source chain head, and a move proof (resealed key reference, differential-privacy budget consumed and remaining, output-review posture, consenting collaborators, and source/target cells).
A high-consequence move (a deep clone, a real migrate) consults a net-potential-gain decision boundary and can refuse rather than run, and every mobility activity ledger event records the verdict. The gate is wired and enforced structurally, but its scoring runs today largely over unclassified, seeded inputs (it annotates its own reasoning when inputs are unclassified and, by default, does not refuse on them). It is a structural governance gate that is in place, rather than a fully-observing value filter.
Where it runs, and where it does not
Workspace mobility runs on cells, not on Edge Agents. An Edge Agent is a tentacle: it reads from and ingests to a cell and does no placement, cloning, or workspace movement of its own. Mobility is a cell-side data-plane operation throughout.
| Corner | How mobility behaves |
|---|---|
| Single-cell | Copy-style operations (clone, snapshot, archive) run locally; a migrate refuses: there is no distinct target to move to |
| Multi-cell (same org) | Full clone, migrate, and failover across cells; residency and protection decide where a target may land |
| Cross-organization | Consent-gated, residency-checked, resealed, dual-audited; refuses fail-closed without a trust edge |
| Sovereign / air-gapped | Signed manifests and plane bundles move over physical media and store-and-forward, verified locally at the destination |
Workspace mobility and disaster recovery span cells. Clean rooms are single-cell for cross-cell recovery today: the same-organization room-clone primitives and the fail-closed cutover admission gate are real, but a clean-room mid-run re-placement, carrying differential-privacy budget, output-review posture, and egress-on-replication admission across cells for an in-flight room, is owed. A run interrupted by the loss of a cell restarts on the recovered room rather than migrating with its state.
Related topics
- Cloning, the copy-on-write mechanics and the eight planes in detail.
- Migrating a workspace, the identity-preserving move, in-org and cross-org, step by step.
- Workspace lifecycle operations, rename, promote, snapshot, merge/split, quarantine, and archive.
- Disaster recovery, the unplanned failover and failback.
- Replication, DR & federation, the cross-org cryptographic model and the protection placement mobility reuses.
- The two work boundaries, the workspace and clean room that mobility moves.