Skip to main content

kernel/
persistence_edge.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Edge persistence types — family/sub-kind enums, per-family data structs,
5//! and the edge container. Re-exported through [`crate::persistence`] to keep
6//! `persistence.rs` under the per-file ceiling.
7
8use rkyv::{Archive, Deserialize, Serialize};
9
10use crate::types::GraphScope;
11
12// ---------------------------------------------------------------------------
13// Edge persistence types
14// ---------------------------------------------------------------------------
15
16#[derive(
17    Archive,
18    Serialize,
19    Deserialize,
20    Clone,
21    Copy,
22    Debug,
23    PartialEq,
24    Eq,
25    serde::Serialize,
26    serde::Deserialize,
27)]
28#[rkyv(derive(Debug, PartialEq))]
29pub enum PersistedEdgeFamily {
30    Semantic,
31    Traversal,
32    Containment,
33    Arrangement,
34    Imported,
35    Provenance,
36}
37
38#[derive(
39    Archive,
40    Serialize,
41    Deserialize,
42    Clone,
43    Copy,
44    Debug,
45    PartialEq,
46    Eq,
47    serde::Serialize,
48    serde::Deserialize,
49)]
50#[rkyv(derive(Debug, PartialEq))]
51pub enum PersistedSemanticSubKind {
52    Hyperlink,
53    UserGrouped,
54    AgentDerived,
55    Cites,
56    Quotes,
57    Summarizes,
58    Elaborates,
59    ExampleOf,
60    Supports,
61    Contradicts,
62    Questions,
63    SameEntityAs,
64    DuplicateOf,
65    CanonicalMirrorOf,
66    DependsOn,
67    Blocks,
68    NextStep,
69}
70
71#[derive(
72    Archive,
73    Serialize,
74    Deserialize,
75    Clone,
76    Copy,
77    Debug,
78    PartialEq,
79    Eq,
80    serde::Serialize,
81    serde::Deserialize,
82)]
83#[rkyv(derive(Debug, PartialEq))]
84pub enum PersistedContainmentSubKind {
85    UrlPath,
86    Domain,
87    FileSystem,
88    UserFolder,
89    ClipSource,
90    NotebookSection,
91    CollectionMember,
92}
93
94#[derive(
95    Archive,
96    Serialize,
97    Deserialize,
98    Clone,
99    Copy,
100    Debug,
101    PartialEq,
102    Eq,
103    serde::Serialize,
104    serde::Deserialize,
105)]
106#[rkyv(derive(Debug, PartialEq))]
107pub enum PersistedArrangementSubKind {
108    FrameMember,
109    TileGroup,
110    SplitPair,
111    TabNeighbor,
112    ActiveTab,
113    PinnedInFrame,
114}
115
116#[derive(
117    Archive,
118    Serialize,
119    Deserialize,
120    Clone,
121    Copy,
122    Debug,
123    PartialEq,
124    Eq,
125    serde::Serialize,
126    serde::Deserialize,
127)]
128#[rkyv(derive(Debug, PartialEq))]
129pub enum PersistedImportedSubKind {
130    BookmarkFolder,
131    HistoryImport,
132    SessionImport,
133    RssMembership,
134    FileSystemImport,
135    ArchiveMembership,
136    SharedCollection,
137}
138
139#[derive(
140    Archive,
141    Serialize,
142    Deserialize,
143    Clone,
144    Copy,
145    Debug,
146    PartialEq,
147    Eq,
148    serde::Serialize,
149    serde::Deserialize,
150)]
151#[rkyv(derive(Debug, PartialEq))]
152pub enum PersistedProvenanceSubKind {
153    ClippedFrom,
154    ExcerptedFrom,
155    SummarizedFrom,
156    TranslatedFrom,
157    RewrittenFrom,
158    GeneratedFrom,
159    ExtractedFrom,
160    ImportedFromSource,
161    /// Verbatim duplicate (cross-graph copy / tear-out fork). Appended last to
162    /// keep existing ordinals stable. Mirrors `ProvenanceSubKind::CopiedFrom`.
163    CopiedFrom,
164}
165
166#[derive(
167    Archive, Serialize, Deserialize, Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize,
168)]
169#[rkyv(derive(Debug, PartialEq))]
170pub struct PersistedSemanticStatement {
171    pub statement_id: String,
172    pub predicate: String,
173    #[serde(default)]
174    pub recognized_sub_kind: Option<PersistedSemanticSubKind>,
175    #[serde(default)]
176    pub label: Option<String>,
177    #[serde(default)]
178    pub graph_scope: GraphScope,
179    #[serde(default)]
180    pub provenance_iri: Option<String>,
181    #[serde(default)]
182    pub asserted_at_ms: Option<u64>,
183}
184
185#[derive(
186    Archive,
187    Serialize,
188    Deserialize,
189    Clone,
190    Debug,
191    Default,
192    PartialEq,
193    serde::Serialize,
194    serde::Deserialize,
195)]
196#[rkyv(derive(Debug, PartialEq))]
197pub struct PersistedSemanticEdgeData {
198    #[serde(default)]
199    pub sub_kinds: Vec<PersistedSemanticSubKind>,
200    #[serde(default)]
201    pub label: Option<String>,
202    #[serde(default)]
203    pub agent_decay_progress: Option<f32>,
204    /// Open predicate IRI (statements-over-schema). `#[serde(default)]` so old
205    /// graphs load with `None`.
206    #[serde(default)]
207    pub predicate: Option<String>,
208    /// Pair-local semantic statement bucket. `#[serde(default)]` keeps old
209    /// snapshots loading through the aggregate compatibility fields above.
210    #[serde(default)]
211    pub statements: Vec<PersistedSemanticStatement>,
212}
213
214#[derive(
215    Archive,
216    Serialize,
217    Deserialize,
218    Clone,
219    Debug,
220    PartialEq,
221    Eq,
222    serde::Serialize,
223    serde::Deserialize,
224)]
225#[rkyv(derive(Debug, PartialEq))]
226pub struct PersistedTraversalRecord {
227    pub timestamp_ms: u64,
228    pub trigger: PersistedNavigationTrigger,
229}
230
231#[derive(
232    Archive,
233    Serialize,
234    Deserialize,
235    Clone,
236    Debug,
237    Default,
238    PartialEq,
239    Eq,
240    serde::Serialize,
241    serde::Deserialize,
242)]
243#[rkyv(derive(Debug, PartialEq))]
244pub struct PersistedTraversalMetrics {
245    pub total_navigations: u64,
246    pub forward_navigations: u64,
247    pub backward_navigations: u64,
248    pub last_navigated_at: Option<u64>,
249}
250
251#[derive(
252    Archive,
253    Serialize,
254    Deserialize,
255    Clone,
256    Debug,
257    Default,
258    PartialEq,
259    Eq,
260    serde::Serialize,
261    serde::Deserialize,
262)]
263#[rkyv(derive(Debug, PartialEq))]
264pub struct PersistedTraversalEdgeData {
265    #[serde(default)]
266    pub traversals: Vec<PersistedTraversalRecord>,
267    #[serde(default)]
268    pub metrics: PersistedTraversalMetrics,
269}
270
271#[derive(
272    Archive,
273    Serialize,
274    Deserialize,
275    Clone,
276    Debug,
277    Default,
278    PartialEq,
279    Eq,
280    serde::Serialize,
281    serde::Deserialize,
282)]
283#[rkyv(derive(Debug, PartialEq))]
284pub struct PersistedContainmentEdgeData {
285    #[serde(default)]
286    pub sub_kinds: Vec<PersistedContainmentSubKind>,
287}
288
289#[derive(
290    Archive,
291    Serialize,
292    Deserialize,
293    Clone,
294    Debug,
295    Default,
296    PartialEq,
297    Eq,
298    serde::Serialize,
299    serde::Deserialize,
300)]
301#[rkyv(derive(Debug, PartialEq))]
302pub struct PersistedArrangementEdgeData {
303    #[serde(default)]
304    pub sub_kinds: Vec<PersistedArrangementSubKind>,
305}
306
307#[derive(
308    Archive,
309    Serialize,
310    Deserialize,
311    Clone,
312    Debug,
313    Default,
314    PartialEq,
315    Eq,
316    serde::Serialize,
317    serde::Deserialize,
318)]
319#[rkyv(derive(Debug, PartialEq))]
320pub struct PersistedImportedEdgeData {
321    #[serde(default)]
322    pub sub_kinds: Vec<PersistedImportedSubKind>,
323}
324
325#[derive(
326    Archive,
327    Serialize,
328    Deserialize,
329    Clone,
330    Debug,
331    Default,
332    PartialEq,
333    Eq,
334    serde::Serialize,
335    serde::Deserialize,
336)]
337#[rkyv(derive(Debug, PartialEq))]
338pub struct PersistedProvenanceEdgeData {
339    #[serde(default)]
340    pub sub_kinds: Vec<PersistedProvenanceSubKind>,
341}
342
343#[derive(
344    Archive, Serialize, Deserialize, Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize,
345)]
346#[rkyv(derive(Debug, PartialEq))]
347pub enum PersistedEdgeAssertion {
348    Semantic {
349        sub_kind: PersistedSemanticSubKind,
350        label: Option<String>,
351        agent_decay_progress: Option<f32>,
352    },
353    Containment {
354        sub_kind: PersistedContainmentSubKind,
355    },
356    Arrangement {
357        sub_kind: PersistedArrangementSubKind,
358    },
359    Imported {
360        sub_kind: PersistedImportedSubKind,
361    },
362    Provenance {
363        sub_kind: PersistedProvenanceSubKind,
364    },
365}
366
367#[derive(
368    Archive,
369    Serialize,
370    Deserialize,
371    Clone,
372    Debug,
373    PartialEq,
374    Eq,
375    serde::Serialize,
376    serde::Deserialize,
377)]
378#[rkyv(derive(Debug, PartialEq))]
379pub enum PersistedRelationSelector {
380    Family(PersistedEdgeFamily),
381    Semantic(PersistedSemanticSubKind),
382    Containment(PersistedContainmentSubKind),
383    Arrangement(PersistedArrangementSubKind),
384    Imported(PersistedImportedSubKind),
385    Provenance(PersistedProvenanceSubKind),
386}
387
388/// Persisted traversal trigger classification.
389#[derive(
390    Archive,
391    Serialize,
392    Deserialize,
393    Clone,
394    Copy,
395    Debug,
396    PartialEq,
397    Eq,
398    serde::Serialize,
399    serde::Deserialize,
400)]
401#[rkyv(derive(Debug, PartialEq))]
402pub enum PersistedNavigationTrigger {
403    Unknown,
404    LinkClick,
405    Back,
406    Forward,
407    AddressBarEntry,
408    PanePromotion,
409    Programmatic,
410    /// Server redirect (3xx) or meta-refresh.
411    Redirect,
412    /// Navigation re-issued by session restore.
413    ReopenSession,
414    /// In-document anchor / fragment jump.
415    JumpAnchor,
416    /// Find-in-page-style within-document search jump.
417    InPageSearchJump,
418    /// Imported from another browser's history database.
419    ImportedHistory,
420}
421
422/// Persisted edge.
423#[derive(Archive, Serialize, Deserialize, Clone, Debug, serde::Serialize, serde::Deserialize)]
424pub struct PersistedEdge {
425    pub from_node_id: String,
426    pub to_node_id: String,
427    #[serde(default)]
428    pub families: Vec<PersistedEdgeFamily>,
429    #[serde(default)]
430    pub semantic: Option<PersistedSemanticEdgeData>,
431    #[serde(default)]
432    pub traversal: Option<PersistedTraversalEdgeData>,
433    #[serde(default)]
434    pub containment: Option<PersistedContainmentEdgeData>,
435    #[serde(default)]
436    pub arrangement: Option<PersistedArrangementEdgeData>,
437    #[serde(default)]
438    pub imported: Option<PersistedImportedEdgeData>,
439    #[serde(default)]
440    pub provenance: Option<PersistedProvenanceEdgeData>,
441}