Cloning
A workspace or clean room is a portable, recoverable environment, not a folder that happens to hold data, so copying one is a first-class, governed operation rather than an out-of-band script. Cloning gives you an independent working copy without paying, up front, to duplicate a whole environment: a copy-on-write clone references the source and only diverges where you actually write, and a background worker promotes it toward a fully independent copy over time.
Three ways to clone
Cloning has three modes, chosen by how independent the copy needs to be and how soon:
| Mode | What it copies up front | How it diverges | Use it for |
|---|---|---|---|
| Shallow (copy-on-write) | Metadata and references only | Reads fall through to the source; writes land on the clone | A cheap, fast working copy: branch an environment to experiment |
| Deep | A full, independent copy of every plane | Independent from creation | A copy that must not depend on the source's continued existence |
| Live sync | Starts as a shallow clone, then continuously follows the source | Source changes stream onto the clone until you detach | A standby that tracks the original until you cut it loose |
A shallow clone can be promoted to deep in the background, so "cheap now" and "independent later" are the same object over its lifetime, not a choice you make once.
How copy-on-write works
The load-bearing idea is that a fresh shallow clone owns no data of its own, it holds references into the source, and only the ranges you write diverge.
Figure: copy-on-write for one plane. The green source holds the real data; the cyan shared reference in the clone points at the source ranges and copies nothing. A read below the clone-creation high-water mark falls through to the source; a read above it, and every write, is clone-local. A background worker promotes the clone by relabeling shared references as independent, for some planes that copies nothing at all, only the label. Ceiling: the exact glyph varies by plane, messaging clones reference source sequence ranges, storage clones reference content-addressed blocks, and the data plane shares filesystem extents by reflink; the copy-on-write behavior is common to all three.
Table equivalent
| Operation | Condition | Where it resolves |
|---|---|---|
| Read | Range at or below the clone-creation high-water mark | Falls through to the source (shared reference) |
| Read | Range above the high-water mark | Reads from the clone (clone-local) |
| Write | Any | Lands on the clone; never mutates the source |
| Promote | Background worker tick | Relabels a shared reference as independent, copying data only where a plane needs it |
For the messaging plane, the copy-on-write overlay that records a clone's shared ranges is held in memory, so the durable state is the persisted clone rows rather than the overlay itself. The messaging service rebuilds the overlays from those rows when it starts, before the promotion worker runs, so a shallow clone's shared ranges survive a restart and a promotion in progress resumes rather than stalling. A rebuild that fails is logged and leaves the clone rows intact. Storage and data-plane clones persist their reference state directly.
Eight planes move together
A workspace is not one database. It is eight domains, and a clone has to carry all of them consistently. They move in two groups:
- Three bulk planes (storage: data, and messaging) go through per-service coordinators that know how to copy-on-write each store.
- Five metadata planes: directory, catalog, system, compute, and sessions, go through a metadata copier that copies rows in foreign-key order, re-mints primary keys, and remaps foreign keys so the clone is internally consistent.
A resource-graph walk plans the copy and asserts completeness fail-closed (nothing is silently skipped), notebook references are repointed so they follow the move, and the whole operation is recorded step-by-step in a hash-chained mobility activity ledger. The copy runs as a saga: an ordered plan of steps, each with a compensation, so a failure rolls back in reverse rather than leaving a half-cloned environment.
A full deep clone is gated on net gain
Duplicating all eight planes is a high-consequence act, so a full deep clone consults a net-potential-gain decision boundary before proceeding. If the gain is negative (or there is not enough data to judge it) the clone is refused rather than run. A refusal is a recorded, honest outcome, in keeping with the platform's discipline of refusing at the boundary instead of doing expensive work that is not worth its cost.
Which refusal you get: the net-gain refusal on a deep clone is returned as a failed clone result, not an HTTP 403. The 403 belongs to the cross-organization guard described below, a cross-org clone that lacks consent is rejected with a typed permission failure the API maps to 403. The net-gain gate itself does not return the 403; the permission layer does.
Crossing an organization boundary
A clone that stays inside one organization moves under that organization's own authority. A cross-organization clone is cryptographically separate and consent-gated, mirroring the cross-org replication model:
- A cross-org guard enforces consent and default-deny egress per resource class, refusing with a permission error (surfaced as 403) when consent is missing.
- An identity map deterministically translates every source identifier to a target identifier, so the operation is idempotent and resumable.
- A signed manifest itemizes exactly what was carried, remapped, or dropped, with a content hash both organizations can verify independently.
- A plane transport pushes each plane over a mutual-TLS channel authenticated with a per-trust-edge key, fail-closed if no trust edge or signing key exists.
- An audit sink seals the manifest into both organizations' hash-chained audit records, neither party can later deny the movement.
Every clone, in-org or cross-org, is metered (units shared versus units copied, with provenance) so its cost is accounted for rather than invisible.
Cloning a clean room
A clean room carries mutual-distrust guarantees that a naive copy would break, so room cloning adds its own fail-closed gate on top of the workspace machinery:
- Compartment admission: the target cell must be cleared for the room's compartment before any plane moves.
- Copy-safety checks: differential-privacy budget, output-review posture, and egress consent are all checked before the room is copied.
- Per-room key re-seal: the room's encryption key is re-sealed for the destination, so crypto isolation survives the move.
- Alias rewrite: the room's per-collaborator asset aliases are remapped so no party's real names leak through the copy.
A cross-organization transfer of a clean room is default-prohibited without recorded N-of-M consent from every collaborator organization, one party cannot unilaterally export another party's data and consent context.
Workspace mobility and cloning are multi-cell, and a clean room runs on one cell at a time, so room recovery is a cutover rather than a live spread.
Room failover and failback are driven operations. Each plane is taken through
fence, promote, reconcile and flip, the whole workspace moves under an
all-or-nothing gate (a plane that ends partial withholds the home flip and leaves
the workspace in a state an operator reconciles, rather than half cut over), the
operation passes the net-potential-gain gate, and a room.failover or
room.failback entry lands on the tamper-evident chronicle for every room on the
affected plane.
The room-specific safety properties are enforced as admission checks on the target, each fail-closed:
- Differential-privacy budget continuity. A copy that would land a room on a target with its epsilon ledger reset to full is refused, because that would be a way to spend the budget twice.
- Output review. A room that requires output review may not land on a cell that cannot honour it.
- Replication egress. A collaborator who has not consented to replication egress blocks the copy.
- Compartment and region targeting. A standby not cleared for the room's compartment, or outside its region constraint, is not a valid recovery target even when the workspace as a whole is ready. An unknown or empty clearance set denies rather than admitting.
What does not exist is a mid-run re-placement executor: there is no path that moves a room to another cell while a computation is in flight, carrying that run's state with it. Recovery moves a room between runs, not during one.
Across the deployment matrix
| Corner | How cloning behaves |
|---|---|
| Single-cell | A local clone within one cell; copy-on-write shares the source's storage until divergence |
| Multi-cell (same org) | A clone can target another cell; residency and admission decide where it may land |
| Cross-organization | Consent-gated, signed-manifest, dual-audited; refuses fail-closed without a trust edge |
| Air-gapped | The signed manifest and plane bundles move over physical media and store-and-forward, verified locally at the destination |
Related topics
- The two work boundaries, the workspace and clean room that cloning copies.
- Replication, DR & federation, the convergence engine and the cross-org cryptographic model cloning reuses.
- Disaster recovery, archive, restore, and the failover path that build on the same mobility machinery.
- Data residency, the constraint that decides which cell a clone may land on.