Skip to content
calternal docs

calternal_collab::history::restore

Restore and selective undo for #975 Phase 2 C (DESIGN §§60–61).

Phase 1 selected Y4/500/segment: Canvas Restore p95 48.55 ms and undo 19.91 ms. The store owns decoding and checkpoint caching. This module reads complete v1 states and produces a forward edit on a copy of the live room. It never writes the room, files or the Index. The event path must verify the precondition and apply the returned update under its existing room lock. Encoded baseline bytes survive store awaits; decoded historical documents are released before the forward edit to bound peak memory.

Only the replay document keeps deleted content, for yrs UndoManager. Live documents and clients keep GC on. Foreign edits protect a whole element or top-level Note block, including equal-value writes and deletes. Temporary Note attributes carry block identity through UndoManager resurrection; they are removed before the existing block bridge creates the forward update.

Source: crates/calternal-collab/src/history/restore.rs

Structs

Section titled “Structs”

PreparedChange

Section titled “PreparedChange”
pub struct PreparedChange

An immutable edit plan. Bytes are accessible only after an exact-state precondition check; a delete-only edit also invalidates it (unlike a vector). The event path supplies authentication, author attribution and persistence.

Fields

  • pub report: UndoReport

PreparedChange::checked_update

Section titled “PreparedChange::checked_update”
pub fn checked_update<'a>(&'a self, key: &DocKey, live: &Doc) -> Result<&'a [u8]>

Call while holding the room lock, then apply these bytes through the normal collaboration event path before releasing it (DESIGN §60).

PreparedChange::is_empty

Section titled “PreparedChange::is_empty”
pub fn is_empty(&self) -> bool

A no-op still has a precondition, but needs no event or history append.

Source: crates/calternal-collab/src/history/restore.rs:80

UndoReport

Section titled “UndoReport”
pub struct UndoReport

Sorted stable units changed or kept by selective undo. Note blocks without Markdown anchors use their original Yjs branch identity, never a position.

Fields

  • pub reverted: Vec<String>
  • pub kept: Vec<String>

Implements: Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize

Source: crates/calternal-collab/src/history/restore.rs:72

Enums

Section titled “Enums”

DocumentKind

Section titled “DocumentKind”
pub enum DocumentKind

Room shape. Canvas stores one JSON value per stable element ID in this map; the caller supplies the map name used by its room binding (DESIGN §60).

Variants

  • Canvas { elements: String }
  • Note

Implements: Clone, Debug

Source: crates/calternal-collab/src/history/restore.rs:44

RestoreError

Section titled “RestoreError”
pub enum RestoreError

A preflight failure cannot mutate the live room (#975).

Variants

  • InvalidState
  • InvalidShape
  • InvalidRange
  • IncompleteHistory
  • LimitExceeded
  • StalePreflight
  • ReservedAttribute
  • WrongDocument

Implements: Debug, Clone, Copy, Eq, PartialEq, std::fmt::Display, std::error::Error

Source: crates/calternal-collab/src/history/restore.rs:51

Functions

Section titled “Functions”

prepare_restore

Section titled “prepare_restore”
pub async fn prepare_restore(
    store: &dyn HistoryStore,
    key: &DocKey,
    point: PointId,
    kind: &DocumentKind,
    live: &Doc,
) -> Result<PreparedChange>

Read the exact historical state, then prepare one forward collaboration edit. The caller must check owner access before calling this store-facing helper.

Source: crates/calternal-collab/src/history/restore.rs:108

prepare_undo

Section titled “prepare_undo”
pub async fn prepare_undo(
    store: &dyn HistoryStore,
    key: &DocKey,
    author: &Author,
    from: PointId,
    to: PointId,
    head: PointId,
    kind: &DocumentKind,
    live: &Doc,
) -> Result<PreparedChange>

Undo the author’s inclusive range, retaining edits through the captured head. Foreign edits after a selected write protect the whole unit even if the author writes there again. Missing/folded points fail instead of guessing. head must describe live exactly; apply rechecks it after the preflight.

Source: crates/calternal-collab/src/history/restore.rs:129