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