core_api/
history.rs

1use core_storage::Value;
2
3// ── Edge history types ────────────────────────────────────────────────────────
4
5/// Result wrapper for history queries. Carries the event list, the total
6/// number of WAL commits, and the oldest commit still reachable.
7///
8/// Valid commit indices for `was_linked` are `horizon..total_commits`. Any index
9/// outside that range is unreachable and `was_linked` will return
10/// `CommitOutOfRange`.
11#[derive(Debug)]
12pub struct HistoryResult<T> {
13    pub items: Vec<T>,
14    /// Exclusive upper bound for valid commit indices.
15    /// The horizon window is `[horizon, total_commits)`.
16    pub total_commits: u64,
17    /// The oldest commit index still reachable (the WAL horizon floor). `0`
18    /// when nothing has been pruned; when `> 0`, events before this commit
19    /// were pruned and are not part of `items`.
20    pub horizon: u64,
21}
22
23/// A single add-or-retract event for an edge between two nodes.
24#[derive(Debug, PartialEq)]
25pub struct EdgeHistoryEvent {
26    pub edge_type: String,
27    /// 0-based WAL frame index of the commit that produced this event.
28    pub commit: u64,
29    pub event: EdgeEvent,
30    /// `Some(rule_name)` for rule-derived edges, `None` for manually written
31    /// edges. Derived edges are represented by `DerivedEdgeAdded` /
32    /// `DerivedEdgeRetracted` WAL markers (discriminants 18/19) written by
33    /// `log_then_apply_with` after each rule-firing mutation; see
34    /// `derived_edge_state_records_not_wal_logged_markers_are` in rules.rs.
35    pub rule: Option<String>,
36}
37
38/// Whether an edge was added or retracted.
39#[derive(Debug, PartialEq)]
40pub enum EdgeEvent {
41    Added,
42    Retracted,
43}
44
45// ── Node history types ────────────────────────────────────────────────────────
46
47/// A single change event in a node's history, paired with the WAL commit that produced it.
48///
49/// ## Horizon
50///
51/// History reaches back only to the last WAL-truncating snapshot, exactly like `open_at`.
52/// Snapshots written with `keep_wal: true` preserve deeper history. This is the honest,
53/// zero-cost contract; a durable history log is out of scope.
54///
55/// ## Derived edges
56///
57/// Rule-created (derived) edges appear in edge history via `DerivedEdgeAdded` /
58/// `DerivedEdgeRetracted` WAL markers; they do not appear in node history.
59#[derive(Debug, PartialEq)]
60pub struct HistoryEntry {
61    /// 0-based WAL frame index of the commit that produced this change.
62    pub commit: u64,
63    pub change: HistoryChange,
64}
65
66#[derive(Debug, PartialEq)]
67pub enum HistoryChange {
68    NodeInserted {
69        label: String,
70    },
71    PropSet {
72        field: String,
73        value: Value,
74    },
75    PropRemoved {
76        field: String,
77    },
78    /// An edge involving this node was added.
79    ///
80    /// `outgoing` is `true` if this node is the source, `false` if it is the destination.
81    ///
82    /// Self-edges (src == dst == this node) produce a single entry with `outgoing: true`.
83    EdgeAdded {
84        edge_type: String,
85        other: String,
86        outgoing: bool,
87    },
88    /// An edge involving this node was removed.
89    ///
90    /// `outgoing` is `true` if this node is the source, `false` if it is the destination.
91    ///
92    /// Self-edges (src == dst == this node) produce a single entry with `outgoing: true`.
93    EdgeRemoved {
94        edge_type: String,
95        other: String,
96        outgoing: bool,
97    },
98    NodeDeleted,
99}
core_api/history.rs

core_api/
history.rs
