Module transfer 

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

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

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 room (crate::persist) transfers the same way (Origin::AppDocument): its document arrives as a record, and a moved one is retired where it was.

Every function works on the durable store a room’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.

Structs

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

Origin

What a transfer takes out of the source room.

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 room as a record.

Traits

DurableStore

Keyed, ordered, honestly-acknowledged storage.

Functions

adopt_fetched

Verify bytes another device sent as record id of room, 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 room 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.

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 room. Refuses to overwrite anything already stored under its id.

install_as

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

is_retired

Whether doc is a record that left its room.

provenance

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

read

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

read_by_id

A live record of package in room 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_room: its whole history, one more change giving it target’s id and to_room’s scope, and a record’s origin id kept as provenance. source is not changed.

retire

Stamp origin in room as retired: one last change in its own history, after which it is never opened as a live document again.

retirement

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

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 room 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 room, live, holding no room 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 room any more: the point after which nothing more can arrive from it.