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 workspace-level timeline need it.

A row says what a change did as the change’s action record names it (sentence::step_summary); a change made outside any action (a framework change, or a write that names no finer action than the document) says so in the framework’s words, never by guessing from its content. Its op class and text delta are read from the change itself: 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, which reads the change’s own patch set via AutoCommit::diff.

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.
descriptions: What a change did, as a sentence a model wrote on a member’s device.
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.
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.
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.

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
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.
SchemaChange: One committed change as an index of what changed when reads it: its time, the objects it made and every object it wrote into, each once.
SchemaCreation: An object a change made: in which object, and under which map key.
SchemaObjectId
StepOutcome: One application’s outcome within a run undo.
ThreadWords: History in this thread’s words: a step as sentence says it, and a person as a directory that knows nobody yet names them. What the history verbs below the toolkit (steps::undo) speak in for an app.

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.
GENERATED_BY: The by of a name a model wrote, in place of a person’s actor hex. A generated name is the document’s guess at what a run of changes was: it is replaced by anyone who names the same range, and it is never shown as somebody’s words (NamedRange::named_by stays empty for it).
GROUPS_KEY: Namespaced so it cannot collide with an app’s own schema: tilo-doc uses content / comments / props, and the shell’s workspace document uses workspaces / active.
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
HistoryWords: The words a history verb speaks in. See the module docs.

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.
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.
contains_opaque_id: Whether text contains a machine identifier: a long hex run (hashes, actor and record ids), a uuid, or a long mixed letter/digit token.
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.
human_label: label when a person could read it as a name; None when it is empty, repeats the machine id, or carries an identifier such as a hash or uuid. Producers fall back to ids when a record has no title yet, and those must not reach anyone reading the activity feed.
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_history_metadata: Whether a change only wrote history’s own metadata about other changes: names of runs (GROUPS_KEY), cross-app runs (RUNS_KEY) and descriptions (DESCRIPTIONS_KEY). Such a change is neither a row nor an undo step.
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_is_generated: Whether the name at record_id was written by a model rather than a person. A record this device cannot read counts as a person’s: never overwrite what another writer may have said.
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.
name_range_by: name_range, with the by written into the record: a person’s actor hex, or GENERATED_BY for a name a model wrote.
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.
revert_step: Undo one entry’s share of a run of work by writing its inverse forward into doc: revert_run for a run of one change, which is what a step of an agent’s run names (the toolkit’s RunStep).
run_starting_at: The run whose first step starts at start, if one is recorded.
schema_changes_since: The committed changes of doc after heads, oldest first, each read as a SchemaChange. Takes the document itself so a copy can be read off the UI thread.
set_workspace_agents: Replace the verified agents of workspace this thread’s app names in its history (AuthorDirectory::with_workspace_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

Type Aliases§

PassOver: Which changes a HistorySource passes over; see HistorySource::passing_over.