Module history_source

Expand description

Turning a live CRDT document into the rows the history widgets render.

ActivityTimeline consumes Vec<HistoryEntry> and is source-agnostic; this module is the producer, walking the change graph via [tilo_resource::history::versions] to emit one HistoryEntry per change with author, timestamp, op class, and a summary of what changed. It lives in ui (not a leaf crate) because both an app’s history and the compositor’s room-level timeline need it.

Two summary strategies, in order of preference: structural, which materialises the window with [tilo_doc::snapshot::series] and diffs snapshots for real per-paragraph insert/delete counts on documents carrying the tilo-doc schema; and patch, the fallback that reads the change’s own patch set via AutoCommit::diff, weaker only in that it can’t see tilo-doc-level concepts like comments or block moves. Neither path guesses — an indescribable change gets "no visible change" rather than an invented summary.

HistoryEntry::id is the first sixteen bytes of the change hash, so it’s content-addressed and stable across peers, letting heads_for_entry turn a clicked row back into a document state.

Modules§

authors: Resolving an automerge actor id to the person behind it.
compare: Exact before/after materialization for one action or a selected group.
detail: Lossless presentation model for the explorer’s selection detail.
digest: A compact, deterministic catch-up model over full history.
facets: Deterministic browse lenses over action-aware history.
groups: Where a version’s name lives: in the document, with the changes it names.
narrative: Grounded prose for passive and active history surfaces.
revert: Undoing somebody else’s work: a contiguous run of changes, addressed by what it is rather than by where it sits on a local stack.
run_undo: Undoing an instruction that spanned more than one application.
runs: One instruction that changed more than one application, recorded as one thing a person can undo.
schema_ops: Stable schema-operation projection for app metadata indexes.
seen: Private, causal-ish seen state for collaborative history.
sentence: History entries as sentences for the person reading this app’s history: in their locale, from the app’s catalogue on this thread and the labels of the actions it publishes.
steps: Undo, redo, restore and checkpoints written into the document itself, so anyone who can invoke an action can use them: a person, a script, an agent over the action door.

Structs§

ActivityBrief
ActivityBriefAction
ActivityDigest
AgentRun: One instruction that spanned one or more applications.
AuthorDirectory: Maps automerge actor ids to the people the chrome should name.
ChangeRun: A contiguous run of changes, addressed by its first and last change.
GroundedNarrative
HistoryAgent: A delegated agent as history names it: its own principal, how it is shown, and the person it acts for.
HistoryComparison
HistoryFacetIndex
HistoryLog: What HistorySource::entries_since has read of one document. Start with HistoryLog::default and hand the same log back on every call; it holds a replica of the document as of its last read.
HistoryResourceTarget
HistorySeenFrontier
HistorySelectionDetail
HistorySource: Construct one, hand it an AuthorDirectory so actor ids resolve to people, and call HistorySource::entries whenever the document changes.
KeptSlot: A slot the revert declined to touch, and why.
NarrativeRequest
NarrativeSource
RevertOutcome: What a revert did, and what it deliberately did not do.
RosterAgent: A delegated agent on a room’s roster, as the session verified it: its own device key, the person whose root signed its delegation for exactly that device, and how it is shown. Only the session produces these, after checking that delegation; history uses them to name who wrote and never to decide what anyone may do.
RunStep: One application’s share of a run.
RunUndoReport: What a whole-run undo did, across every application it touched.
SchemaHistoryOp
SchemaObjectId
StepOutcome: One application’s outcome within a run undo.

Enums§

CompareError
RevertError: Why a run could not be addressed at all — distinct from “addressed it and chose to keep some of it”, which is RevertOutcome::kept.
Slot: A place in the document a change wrote to, at the granularity where two writers collide.
StepState: What happened to one application’s share of a run.

Constants§

DEFAULT_MAX_ENTRIES: The structural path materialises one snapshot per version, so cost is linear in versions and document size; 200 is well past what a scrubber track can resolve into distinct ticks at common widths. Raise it with HistorySource::with_max_entries when a caller needs the whole chain.
GROUPS_KEY: Namespaced so it cannot collide with an app’s own schema: tilo-doc uses content / comments / props, and the shell’s room document uses workspaces / active.
NO_VISIBLE_CHANGE: Deliberately not a guess.
RUNS_KEY: Prefix of the root keys holding this document’s cross-application runs. Namespaced like GROUPS_KEY so it cannot collide with an app’s own schema.
UNKNOWN_AUTHOR_NAME: Display name used for an actor with no registered identity and no self-declared handle. Deliberately not a person’s name.

Traits§

ActivityNarrator

Functions§

actor_handle: Decode an actor id back to the handle the authoring process chose for itself, when it did. ActorId::from(&[u8]) stores the bytes verbatim, so set_actor(ActorId::from(app_id.as_bytes())) leaves the UTF-8 of app_id in the hex. Returns None for anything not a plausible handle (odd-length /non-hex input, non-UTF-8, control chars, empty, or too long); a 32-byte public key almost never survives this filter.
agent_display_label: name with the localized agent kind label, as every agent is shown in history, presence and activity.
agent_principal_name: The readable name of an agent:<id> principal, without the kind label: the id, or the localized unknown-agent name when it is empty. None for any principal that is not an agent. For surfaces that already mark the actor as software, such as an agent badge.
author_coloured: History row whose colour is already decided (a person’s own colour).
author_for_identity: History row for identity: the shared palette slot, same RGB crate::presence::user_color / crate::presence::PresenceCtx::color_for pick when no override is set.
change_summary: Describe, in one short phrase, what moving doc from from to to does: "+12 -3 chars", "+1 item", "2 fields".
clear_name: Remove a name. The changes it covered stay; only the band goes.
close_range: Close an open range at end. false when no such record exists.
committed_heads: The committed frontier for history cache invalidation. Unlike AutoCommit::get_heads, observing it never commits a pending app action.
compare_entries: Compare the dependency frontier immediately before the selected changes to the frontier after every selected change. Concurrent changes outside the selection are excluded. Pending edits are neither committed nor included.
deterministic_narrative: Privacy-preserving fallback used when no model is configured or when a generated result fails grounding validation.
entry_id_from_hash: The hash is the document’s own content address, so two peers independently building a timeline over the same history agree on the ids — what lets one peer’s [Revert] mean anything to another.
forget_run: Remove a run record. The changes it referenced stay untouched in their own documents; only the grouping goes.
heads_for_entry: The other half of HistorySource::entries: a restore needs a document state for the HistoryEntryId a widget hands back. None when the id names no change in this document — mixed ids from two artifacts.
is_group_marker: True when every patch in patches lands inside the named-range map — used by the producer to keep naming out of the row list. An empty patch set is not a marker: a change that did nothing visible is still a change, and hiding it would be incorrect behaviour.
is_run_marker: True when every patch lands inside a run record — the change did nothing but record bookkeeping, already on screen as a band, so a “1 field” row under it would be noise. An empty patch set is not a marker.
latest_run_by: The contiguous run of changes authored by actor_hex, ending at the document’s newest change by that actor.
local_identity_author: Build a HistoryAuthor from the local identity (crate::local_identity), if there is one. Public because the shell wants the same answer for its own chrome without having to own an AuthorDirectory.
materialize_entry: Materialize a committed tilo-doc history entry without committing live edits. An ID from another document returns Ok(None).
merge_named_ranges: Merge named bands into one caller-resolved range. Every old record must exist before anything is changed, so a stale UI cannot partially merge a set that a collaborator has already edited.
move_named_boundary: Move the boundary between two named bands while preserving both labels. As with split, the caller resolves the two sides from its displayed causal order and sends exact ids.
name_range: Names the run of changes from start to end, or opens an unbounded run when end is None. Returns the record id (also the document key). The transaction is left open — the host commits, so the naming lands stamped and attributed like any other edit.
participant_display_label: Turn a durable collaboration principal into copy suitable for people-facing history and audit UI.
plan_revert: Work out what undoing run would do, without touching the document.
read_named_ranges: Records that do not parse (a corrupted key, a missing label) are skipped rather than guessed at — a band in the wrong place is worse than no band.
read_runs: Read every recorded run out of doc, oldest key first. A record that does not parse is skipped rather than guessed at: an undo affordance pointing at the wrong changes is worse than no affordance.
record_run: Record a run. Returns the document key, which is also AgentRun::id. The transaction is left open — the caller commits, so the record lands stamped and attributed like any other edit. A run with no steps is not recorded: nothing changed, so there is nothing to offer undo on.
record_run_with_details: Record a run with the task evidence needed for a later review.
refuse_run: Build the report for a run that was refused whole. Nothing was written.
revert_run: Undo a run of changes by writing its inverse forward into doc.
run_starting_at: The run whose first step starts at start, if one is recorded.
schema_operations_since: Decode committed operations after heads without mutating the document.
set_room_agents: Replace the verified agents of room this thread’s app names in its history (AuthorDirectory::with_room_agents). Only the session’s context stream calls this, with what it verified.
short_id: First SHORT_LEN hex characters of an actor id, for the dim monospace label next to the name. Short ids are returned whole.
split_named_range: Split one named band into two adjacent named bands in the current transaction. The caller supplies both boundary ids because a CRDT history is not inherently linear at concurrent branches; guessing adjacency here would make the operation non-deterministic across peers.
stable_hue: Deterministic avatar hue for an actor with no registered colour: FNV-1a over the actor hex, folded into [0, 360). Same actor, same hue in every process and on every peer.
undo_run: Undo every step of a run, given the documents the caller could open.
undo_step: Undo one application’s share of a run against the document that app owns.
unreachable_steps: Steps whose documents this process cannot reach.
validate_narrative
version_index_for_entry