Skip to main content

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}