Module transfer 

Transfer: the explicit verb that takes a record across a workspace boundary.

A record id names a document only inside the workspace whose replica hydrates it (super::workspace_scope), so nothing crosses workspaces by reference. Transfer is the counterpart of super::index::duplicate for a document that already has content: the destination workspace receives the record’s whole change graph under a fresh id of its own, scoped to that workspace, with the source id kept in its formerly list as provenance. Nothing ever looks a record up through that list.

A record’s workspace is stored under room, the key every record is written with, so a document this module writes names it the way every reader knows; a document written while the field was named workspace holds super::WORKSPACE_ALIAS and is read where it is.

Moving is transfer followed by retire: the source record gets one last change saying it left, which stays in its history the way a deletion does, and it is never opened as a live document again (super::RecordOpenError::Retired). Copying is transfer alone: the source keeps going and the two histories diverge from here. An app that keeps one document for itself in a workspace (its record index) transfers the same way (Origin::AppDocument).

Every function works on the durable store a workspace’s app profile keeps, through the same keys, leases and validation the record owners use. A write needs the key’s exclusive lease, so it fails with TransferError::Busy while an app process still has the record open; a caller waits for that process to go rather than racing its writer.

A write returns a Landing rather than waiting for the disk: the shell’s frame loop drives transfers and never waits for a commit. The next process to open the record reads it from disk, so whatever hands the record over asks Landing::durability until the write has landed, while the store’s own thread does the waiting.

Structs

Landing

A transfer’s write, accepted by the store and on its way to disk.

Successor

Where a moved record went and who moved it, as its retirement records. Anyone who can read the old record learns only these ids; whether they can see the destination is for their own desktop to say.

Enums

Durability

Whether an accepted write has survived.

Origin

What a transfer takes out of the source workspace.

Retirement

Why a record is retired, as stamped into its last change.

TransferError

Constants

APP_DOCUMENT_KIND

The kind an app’s own document (Origin::AppDocument) takes when it arrives in another workspace as a record.

Traits

DurableStore

Keyed, ordered, honestly-acknowledged storage.

Functions

adopt_fetched

Verify bytes another device sent as record id of workspace, and keep it here: installed when new, merged when this device already holds it. The bytes are only trusted as far as they prove to be that live record.

catch_up

Merge every change source holds that target in workspace lacks — the edits its old writer made after the transfer read it. Deterministic: it is a CRDT merge, so the order it runs in cannot change the result. Returns how many changes arrived, and the write bringing them when any did.

changes_since

The changes source holds beyond the known heads of an earlier read: what its writer committed after that read.

install

Make doc (from rehome) a record of package in workspace. Refuses to overwrite anything already stored under its id. Open it elsewhere once the Landing has landed.

install_as

install a document that arrived for checkout, including the workspace’s package-primary record, whose identity the document does not carry.

install_workspace_document

Put doc in place as the workspace’s own document of package in workspace (the package-primary record), as an earlier version of the app left it on this device: how a workspace written before a change of the app’s storage is opened in a test. Refuses to overwrite one.

is_retired

Whether doc is a record that left its workspace.

provenance

The origin ids a transferred record came from, oldest first.

read

Read origin as package last made it durable in workspace, without taking its writer: the app showing it may still be running.

read_by_id

A live record of package in workspace by its id alone, whatever its kind: what another device asks for when all it knows is the id.

read_until

read as of heads: what the document held before its app stamped it retired, which is everything a move still has to bring along.

rehome

The destination’s copy of source, read from origin in from_workspace: its whole history, one more change giving it target’s id and to_workspace’s scope, and a record’s origin id kept as provenance. source is not changed.

retire

Stamp origin in workspace as retired: one last change in its own history, after which it is never opened as a live document again. No write, and no Landing, for one already retired.

retirement

The retirement stamped into doc, when it has left its workspace.

stamp_retired

Stamp doc retired, in one change of its own, unless it already is. The shell does this to a record at rest; an app does it to the live document it shows, so the stamp travels to everyone holding that record over its normal route.

validate_import

Check bytes offered to become record id of workspace with their whole history, before anything keeps them: at most max_bytes, a complete document whose identity is exactly that freshly minted record scoped to that workspace, live, holding no workspace index and no references to other records, and naming earlier ids only as provenance.

writer_released

Whether no app process holds origin’s writer in workspace any more: the point after which nothing more can arrive from it.