Read a saved Cellucid session: its history, checked whole

A session file (format 4) holds the history of a dataset in the viewer: every step taken – by a person, an agent, Python or R – in one or more trackers (independent histories), each a tree of steps whose branches are the alternatives tried, with its notes, bookmarks, turns, journal and every state the steps lead to. cellucid_read_session() reads and checks it whole; cellucid_trackers() and its companions read the history; cellucid_apply_session() writes the state at a step onto the object it was saved on.

Usage

cellucid_read_session(path)

cellucid_conversations(session, tracker = NULL)

Arguments

path

A .cellucid-session file: what the viewer's Save session or Share history writes, and what cellucid_session_result() collects.

session

What cellucid_read_session() or cellucid_session_result() returned.

tracker

A tracker of the session (by its name or id, or what cellucid_tracker() returned); NULL for the active one.

Value

cellucid_read_session(): a cellucid_session, a list of path, sha256 (of the file), manifest (the file's manifest as jsonlite reads JSON), created_at, app (the web app that wrote it: version, catalog – the digest of its action catalogue), actions (each action type the steps use, with the digest of its parameters' schema), scope (what the share or save kept: trackers, branches, content – "history", "state" for the current state only (one tracker: the dataset as opened and one squashed step, read and applied as any session), or "steps" for the steps only, no values –, results ("include" or "recompute"), notes, chats, journal, times and source), dataset_fingerprint, source (where the viewer opened the dataset; NULL when the share left it out), requires (the obs columns and genes the history uses), chrome (page chrome kept outside the history, which the web app puts back after a load: list(pressed = list(<group id> = <button id>)), the pressed button of each pressed-button group, such as the selection tool; empty from a file written without a page; read, never applied), cells and genes (the subsamples it was saved on, or NULL), active_tracker (an id) and trackers (each a cellucid_tracker, named by id: see cellucid_trackers()). Printing it shows the dataset, the trackers and the step shown.

cellucid_conversations(): the tracker's agent conversations the file kept, each list(conversation, transcript).

Details

The file is untrusted input and is checked whole before anything is returned, as the viewer checks it: every chunk inflated to exactly its declared size, every stored array against its digest, every value against its content hash once its parts are joined (a part, a sub-value several values share and the file stores once, is joined once and its name never trusted; a part that names itself through others, and a value whose text would pass 2^29 - 24 characters, are refused before anything is expanded), every record against the history model (inst/history_model.schema.json, the web app's, pinned by digest in the web app, cellucid-python and this package), every tracker's tree whole (one root, parents and children that agree, branches that are lines, groups that are runs of consecutive steps holding whole turns, the head on its active branch), what the share left out absent, the values the head shows in the file's first (eager) chunks with every part and array they name, and no value, part or array that nothing needs, none that something needs missing, and no trailing bytes. A damaged file is refused with "This session file is damaged: " and what is wrong. A file written by a newer Cellucid than this package, holding records this package does not know, is refused as newer (update the package), never as damaged. A session file of an earlier format (3, which held one state) or of a newer one is refused in the viewer's words.

See also

cellucid_trackers(), cellucid_apply_session(), cellucid_request_session(); cellucid-python's read_session().

Examples

# The shared golden history: three trackers (a replay, one removed), five
# branches (one forking after a squash in mid-branch), a notebook's and an
# agent's turn, notes, a bookmark.
path <- system.file("extdata", "history_golden.cellucid-session", package = "cellucid")
session <- cellucid_read_session(path)
session
#> <Cellucid session> History golden (history_golden), 600 cells
#>   saved:    2026-11-04T12:00:00.000Z by Cellucid 0.9.6
#>   trackers: Annotation (17 steps), Annotation (replay) (3 steps), Annotation (2 steps, removed)
#>   shown:    Annotation, step s13: Merged B cell into T cell in cell_type
session$scope$content
#> [1] "history"
cellucid_conversations(session)[[1L]]$conversation
#> [1] "conv-1"