core_api/
history.rs

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

core_api/
history.rs
