kernel/graph/source_time.rs
1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Source-time selection, distinct from projected-scene delivery revisions.
5//!
6//! A [`SourceTime`] owns immutable snapshots of its own truth. Its cursor is
7//! deliberately opaque to projection and UI code: a journal uses a sequence,
8//! while a Git-backed authority can use a commit identity. Hosts retain their
9//! own labels, playback policy, and live-update subscription.
10
11/// The selectable bounds of one source's history.
12#[derive(Clone, Debug, PartialEq, Eq)]
13pub struct SourceExtent<Cursor> {
14 /// The oldest source snapshot this provider can reproduce.
15 pub earliest: Cursor,
16 /// The current source snapshot. This can advance while a host follows live.
17 pub current: Cursor,
18}
19
20/// An ordered source of immutable snapshots.
21///
22/// This is intentionally storage- and clock-agnostic. A caller asks for a
23/// compact, stable set of cursors, selects one, then projects the returned
24/// snapshot with its existing arrangement. Selecting a historical cursor must
25/// not mutate the provider's current truth.
26pub trait SourceTime {
27 /// An opaque source-owned identity for one snapshot.
28 type Cursor: Clone + Eq;
29 /// The source's truth at one cursor.
30 type Snapshot;
31
32 /// The earliest and current selectable cursors.
33 fn source_extent(&self) -> SourceExtent<Self::Cursor>;
34
35 /// Evenly distributed, source-ordered cursors for a bounded scrubber.
36 ///
37 /// `max_points == 0` may return no cursors. Providers include both extent
38 /// ends when they differ and more than one point is requested.
39 fn source_ticks(&self, max_points: usize) -> Vec<Self::Cursor>;
40
41 /// Reproduce truth at exactly `cursor`, refusing stale or foreign cursors.
42 fn source_snapshot(&self, cursor: &Self::Cursor) -> Option<Self::Snapshot>;
43}