Module record 

Records — the unit of state, collaboration and storage. A record has a type, a stable identity, and a home room. A file’s identity is its file record — the durable id the filesystem gives the file, which a rename or move keeps — and its path is only where it currently sits (see RecordId::identify_file). Records reference other records rather than nesting (annotations reference the document they mark up), so “share the book without my notes” is expressible.

A record id is scoped by the room that hydrates it. Rooms hold references (room::reference), but an identical id in another room gets a distinct local document and collaboration route; explicit export/import is required to move content across that authority boundary.

One document per record is forced, not chosen: an Automerge change graph names its dependencies by hash, so a filtered stream leaves the receiver holding orphaned changes — it cannot be served in part.

RecordSet owns the open records and hands the active one to the toolkit; tick parks the outgoing document and checks the named one in each frame. Not all app state is a record — a theme or account stays in the package-level document (crate::persist) instead.

Modules

bootstrap

Idempotent construction of initially empty record slots.

capability

A root widget that chooses which record its document is, and owns work scoped to that record.

person

Records in the person’s own room: data that belongs to one person and follows them across their devices, never to a collaborator.

room

A room’s index of the records it holds. Ownership of the index document is the caller’s business — the compositor keeps one per room (shell::room_records).

transfer

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

Structs

BlobRef

A content-addressed blob a record depends on: immutable bytes the record’s content is about or embeds (the PDF an annotation set marks up, an image a document shows). Kept in the record’s metadata next to its record references, so sync, retention and history can see which blobs a record keeps alive without knowing the record’s own schema.

RecordCheckout

A record named together with its type — what a widget declares it is working on, and what a room index holds.

RecordId

The stable identity of a record. Encoded by prefix: file-record:<uuid> (a file, by the durable id its filesystem record carries — see RecordId::identify_file), file:<absolute path> (a file known only by where it is: a not-yet-written Save As target, or a filesystem that can’t hold the durable id), uuid:<uuid> (minted, for a record with no natural name), tab:<tab id> (a window’s scratch document until a file names it, see RecordId::for_tab) and derived:<role>@<id> (see RecordId::derived).

RecordKind

What kind of thing a record is — document, annotation-set, book, playlist. App-owned rather than system-registered, so an app can add a kind without coordinating; the cost is no cross-app library view yet (needs a system-owned type registry, not built here).

RecordOwners

Explicit profile-scoped owner registry. Clones share the original registry; weak entries never keep a closed writer alive.

RecordRef

One record’s reference to another: annotations → the document they mark up, a duplicate → the record it was copied from.

RecordReservation

The unique construction owner of a not-yet-live record. Drop cancels only this generation.

RecordSet

The records one app process has open, and which is live. Owns per-record persistence and parking — not collaboration: routing a record’s deltas is the toolkit’s business (tilo_ui::App re-announces its channel on checkout), since a channel is a property of the connection.

RecordStore

A RecordSet several widgets share via a handle, so two tabs on the same file stay one document rather than drifting under per-widget ownership. Single-threaded on purpose — a widget tree is, and a Mutex here would guard against nothing.

Enums

RecordOpenError

RecordOpenOutcome

RecordSaveStatus

Constants

MAX_DISCOVERED_ROOM_RECORDS

Upper bound for the records an app learns from one room index at once. This is deliberately small: the index is replicated input, not a request to allocate one local document per entry.

SURFACE

The key of the record identity naming the surface its changes are decided against: the content hash of its app package’s surface.toml.

Functions

add_blob_reference

Record that this record depends on blob. Idempotent on (hash, relation). Returns whether a reference was added.

add_reference

Idempotent on (target, relation): a reference is a fact, not an event.

author_writer

The actor author’s mount edits a record as, when the record’s own writer is record_writer and the host asked for per-author writers (crate::application::HostContext::write_as_author). Mounts of one profile and device share a record’s document and so its writer; this keeps each author’s edits apart in history. It is unique wherever the record’s writer is, and the same after a reopen, so history names the same author again.

blob_references

Every blob this record depends on.

former_identities

Identities this record’s document was known by before adoption, oldest first (see RecordCheckout::formerly).

genesis_actor

The actor that made the genesis of the record doc holds. Nobody edits as it, and its changes carry no time, so history lists none of them. None when doc holds no record.

home

The room this record was minted in.

identity

The identity stamped into doc, if it holds a record.

init

Stamp a document with the identity of the record it holds. Idempotent: re-opening leaves an existing stamp alone, so a restart doesn’t author a change graph entry that says nothing new.

init_scoped

Bind a record document to room. Unlike the historical init, this never rewrites an existing identity or room: accepting a document stamped for another room would turn a matching record id into a cross-room alias. A room-less legacy document may be adopted exactly once after its identity has been checked.

references

Every record this one references.

room_scope

The room this local record replica is bound to. Absent only for records written before room-partitioned persistence; callers may adopt those once with init_scoped, but must never treat an explicit different room as interchangeable.

tick

Run one record tick: if the widget tree names a record other than the live one, park it and check the named one out. tilo_ui::App calls this once per frame, before sync, so a widget that opened a file last frame is editing that file’s document by the time it next reads state. The checkout it returns is the caller’s cue to re-announce its collaboration channel — a checkout is a change of address.