1use rkyv::{Archive, Deserialize, Serialize};
12
13use crate::types::{AssertionBasis, AssertionWithdrawal, GraphScope};
14
15#[derive(
20 Archive,
21 Serialize,
22 Deserialize,
23 Clone,
24 Copy,
25 Debug,
26 PartialEq,
27 Eq,
28 serde::Serialize,
29 serde::Deserialize,
30)]
31#[rkyv(derive(Debug, PartialEq))]
32pub enum PersistedEdgeFamily {
33 Semantic,
34 Traversal,
35 Containment,
36 Arrangement,
37 Imported,
38 Provenance,
39}
40
41#[derive(
42 Archive,
43 Serialize,
44 Deserialize,
45 Clone,
46 Copy,
47 Debug,
48 PartialEq,
49 Eq,
50 serde::Serialize,
51 serde::Deserialize,
52)]
53#[rkyv(derive(Debug, PartialEq))]
54pub enum PersistedSemanticSubKind {
55 Hyperlink,
56 UserGrouped,
57 AgentDerived,
58 Cites,
59 Quotes,
60 Summarizes,
61 Elaborates,
62 ExampleOf,
63 Supports,
64 Contradicts,
65 Questions,
66 SameEntityAs,
67 DuplicateOf,
68 CanonicalMirrorOf,
69 DependsOn,
70 Blocks,
71 NextStep,
72}
73
74#[derive(
75 Archive,
76 Serialize,
77 Deserialize,
78 Clone,
79 Copy,
80 Debug,
81 PartialEq,
82 Eq,
83 serde::Serialize,
84 serde::Deserialize,
85)]
86#[rkyv(derive(Debug, PartialEq))]
87pub enum PersistedContainmentSubKind {
88 UrlPath,
89 Domain,
90 FileSystem,
91 UserFolder,
92 ClipSource,
93 NotebookSection,
94 CollectionMember,
95}
96
97#[derive(
98 Archive,
99 Serialize,
100 Deserialize,
101 Clone,
102 Copy,
103 Debug,
104 PartialEq,
105 Eq,
106 serde::Serialize,
107 serde::Deserialize,
108)]
109#[rkyv(derive(Debug, PartialEq))]
110pub enum PersistedArrangementSubKind {
111 FrameMember,
112 TileGroup,
113 SplitPair,
114 TabNeighbor,
115 ActiveTab,
116 PinnedInFrame,
117}
118
119#[derive(
120 Archive,
121 Serialize,
122 Deserialize,
123 Clone,
124 Copy,
125 Debug,
126 PartialEq,
127 Eq,
128 serde::Serialize,
129 serde::Deserialize,
130)]
131#[rkyv(derive(Debug, PartialEq))]
132pub enum PersistedImportedSubKind {
133 BookmarkFolder,
134 HistoryImport,
135 SessionImport,
136 RssMembership,
137 FileSystemImport,
138 ArchiveMembership,
139 SharedCollection,
140}
141
142#[derive(
143 Archive,
144 Serialize,
145 Deserialize,
146 Clone,
147 Copy,
148 Debug,
149 PartialEq,
150 Eq,
151 serde::Serialize,
152 serde::Deserialize,
153)]
154#[rkyv(derive(Debug, PartialEq))]
155pub enum PersistedProvenanceSubKind {
156 ClippedFrom,
157 ExcerptedFrom,
158 SummarizedFrom,
159 TranslatedFrom,
160 RewrittenFrom,
161 GeneratedFrom,
162 ExtractedFrom,
163 ImportedFromSource,
164 CopiedFrom,
167 MergedFrom,
170}
171
172#[derive(Archive, Serialize, Deserialize, Clone, Debug, PartialEq)]
173#[rkyv(derive(Debug, PartialEq))]
174pub struct PersistedSemanticStatement {
175 pub statement_id: String,
176 pub predicate: String,
177 pub recognized_sub_kind: Option<PersistedSemanticSubKind>,
178 pub label: Option<String>,
179 pub graph_scope: GraphScope,
180 pub provenance_iri: Option<String>,
181 pub asserted_at_ms: Option<u64>,
182 pub first_asserted_ms: Option<u64>,
185 pub withdrawn: Option<AssertionWithdrawal>,
186 pub basis: AssertionBasis,
188}
189
190struct PresentOptionU64(Option<Option<u64>>);
191struct PresentBasis(Option<Option<AssertionBasis>>);
192
193impl Default for PresentOptionU64 {
194 fn default() -> Self {
195 Self(None)
196 }
197}
198
199impl Default for PresentBasis {
200 fn default() -> Self {
201 Self(None)
202 }
203}
204
205impl<'de> serde::Deserialize<'de> for PresentBasis {
206 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
207 where
208 D: serde::Deserializer<'de>,
209 {
210 let value = if deserializer.is_human_readable() {
211 Option::<AssertionBasis>::deserialize(deserializer)?
212 } else {
213 Some(AssertionBasis::deserialize(deserializer)?)
214 };
215 Ok(Self(Some(value)))
216 }
217}
218
219impl<'de> serde::Deserialize<'de> for PresentOptionU64 {
220 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
221 where
222 D: serde::Deserializer<'de>,
223 {
224 let value = <Option<u64> as serde::Deserialize>::deserialize(deserializer)?;
225 Ok(Self(Some(value)))
226 }
227}
228
229impl<'de> serde::Deserialize<'de> for PersistedSemanticStatement {
230 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
231 where
232 D: serde::Deserializer<'de>,
233 {
234 #[derive(serde::Deserialize)]
235 struct Fields {
236 statement_id: String,
237 predicate: String,
238 #[serde(default)]
239 recognized_sub_kind: Option<PersistedSemanticSubKind>,
240 #[serde(default)]
241 label: Option<String>,
242 #[serde(default)]
243 graph_scope: GraphScope,
244 #[serde(default)]
245 provenance_iri: Option<String>,
246 #[serde(default)]
247 asserted_at_ms: Option<u64>,
248 #[serde(default)]
249 first_asserted_ms: PresentOptionU64,
250 #[serde(default)]
251 withdrawn: Option<AssertionWithdrawal>,
252 #[serde(default)]
253 basis: PresentBasis,
254 }
255
256 let fields = <Fields as serde::Deserialize>::deserialize(deserializer)?;
257 let basis = fields.basis.0.flatten().unwrap_or_else(|| AssertionBasis {
258 note: fields.label.clone(),
259 ..Default::default()
260 });
261 let label = basis.note.clone();
262 Ok(Self {
263 statement_id: fields.statement_id,
264 predicate: fields.predicate,
265 recognized_sub_kind: fields.recognized_sub_kind,
266 label,
267 basis,
268 graph_scope: fields.graph_scope,
269 provenance_iri: fields.provenance_iri,
270 first_asserted_ms: fields.first_asserted_ms.0.unwrap_or(fields.asserted_at_ms),
271 asserted_at_ms: fields.asserted_at_ms,
272 withdrawn: fields.withdrawn,
273 })
274 }
275}
276
277impl serde::Serialize for PersistedSemanticStatement {
278 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
279 use serde::ser::SerializeStruct;
280
281 let human = serializer.is_human_readable();
282 let scoped = self.graph_scope != GraphScope::Default;
283 let fields = if human {
284 2 + usize::from(self.recognized_sub_kind.is_some())
285 + usize::from(self.label.is_some())
286 + usize::from(scoped)
287 + usize::from(self.provenance_iri.is_some())
288 + usize::from(self.asserted_at_ms.is_some())
289 + usize::from(self.first_asserted_ms.is_some() || self.asserted_at_ms.is_some())
290 + usize::from(self.withdrawn.is_some())
291 + usize::from(!self.basis.is_empty() || self.label.is_some())
292 } else {
293 10
294 };
295 let mut state = serializer.serialize_struct("PersistedSemanticStatement", fields)?;
297 state.serialize_field("statement_id", &self.statement_id)?;
298 state.serialize_field("predicate", &self.predicate)?;
299 if !human || self.recognized_sub_kind.is_some() {
300 state.serialize_field("recognized_sub_kind", &self.recognized_sub_kind)?;
301 }
302 if !human || self.label.is_some() {
303 state.serialize_field("label", &self.label)?;
304 }
305 if !human || scoped {
306 state.serialize_field("graph_scope", &self.graph_scope)?;
307 }
308 if !human || self.provenance_iri.is_some() {
309 state.serialize_field("provenance_iri", &self.provenance_iri)?;
310 }
311 if !human || self.asserted_at_ms.is_some() {
312 state.serialize_field("asserted_at_ms", &self.asserted_at_ms)?;
313 }
314 if !human || self.first_asserted_ms.is_some() || self.asserted_at_ms.is_some() {
315 state.serialize_field("first_asserted_ms", &self.first_asserted_ms)?;
316 }
317 if !human || self.withdrawn.is_some() {
318 state.serialize_field("withdrawn", &self.withdrawn)?;
319 }
320 if !human || !self.basis.is_empty() || self.label.is_some() {
321 state.serialize_field("basis", &self.basis)?;
322 }
323 state.end()
324 }
325}
326
327#[derive(
328 Archive,
329 Serialize,
330 Deserialize,
331 Clone,
332 Debug,
333 Default,
334 PartialEq,
335 serde::Serialize,
336 serde::Deserialize,
337)]
338#[rkyv(derive(Debug, PartialEq))]
339pub struct PersistedSemanticEdgeData {
340 #[serde(default)]
341 pub sub_kinds: Vec<PersistedSemanticSubKind>,
342 #[serde(default)]
343 pub label: Option<String>,
344 #[serde(default)]
345 pub agent_decay_progress: Option<f32>,
346 #[serde(default)]
349 pub predicate: Option<String>,
350 #[serde(default)]
353 pub statements: Vec<PersistedSemanticStatement>,
354}
355
356#[derive(
357 Archive,
358 Serialize,
359 Deserialize,
360 Clone,
361 Debug,
362 PartialEq,
363 Eq,
364 serde::Serialize,
365 serde::Deserialize,
366)]
367#[rkyv(derive(Debug, PartialEq))]
368pub struct PersistedTraversalRecord {
369 pub timestamp_ms: u64,
370 pub trigger: PersistedNavigationTrigger,
371}
372
373#[derive(
374 Archive,
375 Serialize,
376 Deserialize,
377 Clone,
378 Debug,
379 Default,
380 PartialEq,
381 Eq,
382 serde::Serialize,
383 serde::Deserialize,
384)]
385#[rkyv(derive(Debug, PartialEq))]
386pub struct PersistedTraversalMetrics {
387 pub total_navigations: u64,
388 pub forward_navigations: u64,
389 pub backward_navigations: u64,
390 pub last_navigated_at: Option<u64>,
391}
392
393#[derive(
394 Archive,
395 Serialize,
396 Deserialize,
397 Clone,
398 Debug,
399 Default,
400 PartialEq,
401 Eq,
402 serde::Serialize,
403 serde::Deserialize,
404)]
405#[rkyv(derive(Debug, PartialEq))]
406pub struct PersistedTraversalEdgeData {
407 #[serde(default)]
408 pub traversals: Vec<PersistedTraversalRecord>,
409 #[serde(default)]
410 pub metrics: PersistedTraversalMetrics,
411}
412
413#[derive(
414 Archive,
415 Serialize,
416 Deserialize,
417 Clone,
418 Debug,
419 Default,
420 PartialEq,
421 Eq,
422 serde::Serialize,
423 serde::Deserialize,
424)]
425#[rkyv(derive(Debug, PartialEq))]
426pub struct PersistedContainmentEdgeData {
427 #[serde(default)]
428 pub sub_kinds: Vec<PersistedContainmentSubKind>,
429}
430
431#[derive(
432 Archive,
433 Serialize,
434 Deserialize,
435 Clone,
436 Debug,
437 Default,
438 PartialEq,
439 Eq,
440 serde::Serialize,
441 serde::Deserialize,
442)]
443#[rkyv(derive(Debug, PartialEq))]
444pub struct PersistedArrangementEdgeData {
445 #[serde(default)]
446 pub sub_kinds: Vec<PersistedArrangementSubKind>,
447}
448
449#[derive(
450 Archive,
451 Serialize,
452 Deserialize,
453 Clone,
454 Debug,
455 Default,
456 PartialEq,
457 Eq,
458 serde::Serialize,
459 serde::Deserialize,
460)]
461#[rkyv(derive(Debug, PartialEq))]
462pub struct PersistedImportedEdgeData {
463 #[serde(default)]
464 pub sub_kinds: Vec<PersistedImportedSubKind>,
465}
466
467#[derive(
468 Archive,
469 Serialize,
470 Deserialize,
471 Clone,
472 Debug,
473 Default,
474 PartialEq,
475 Eq,
476 serde::Serialize,
477 serde::Deserialize,
478)]
479#[rkyv(derive(Debug, PartialEq))]
480pub struct PersistedProvenanceEdgeData {
481 #[serde(default)]
482 pub sub_kinds: Vec<PersistedProvenanceSubKind>,
483}
484
485#[derive(
486 Archive, Serialize, Deserialize, Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize,
487)]
488#[rkyv(derive(Debug, PartialEq))]
489pub enum PersistedEdgeAssertion {
490 Semantic {
491 sub_kind: PersistedSemanticSubKind,
492 label: Option<String>,
493 agent_decay_progress: Option<f32>,
494 },
495 Containment {
496 sub_kind: PersistedContainmentSubKind,
497 },
498 Arrangement {
499 sub_kind: PersistedArrangementSubKind,
500 },
501 Imported {
502 sub_kind: PersistedImportedSubKind,
503 },
504 Provenance {
505 sub_kind: PersistedProvenanceSubKind,
506 },
507}
508
509#[derive(
510 Archive,
511 Serialize,
512 Deserialize,
513 Clone,
514 Debug,
515 PartialEq,
516 Eq,
517 serde::Serialize,
518 serde::Deserialize,
519)]
520#[rkyv(derive(Debug, PartialEq))]
521pub enum PersistedRelationSelector {
522 Family(PersistedEdgeFamily),
523 Semantic(PersistedSemanticSubKind),
524 Containment(PersistedContainmentSubKind),
525 Arrangement(PersistedArrangementSubKind),
526 Imported(PersistedImportedSubKind),
527 Provenance(PersistedProvenanceSubKind),
528}
529
530#[derive(
532 Archive,
533 Serialize,
534 Deserialize,
535 Clone,
536 Copy,
537 Debug,
538 PartialEq,
539 Eq,
540 serde::Serialize,
541 serde::Deserialize,
542)]
543#[rkyv(derive(Debug, PartialEq))]
544pub enum PersistedNavigationTrigger {
545 Unknown,
546 LinkClick,
547 Back,
548 Forward,
549 AddressBarEntry,
550 PanePromotion,
551 Programmatic,
552 Redirect,
554 ReopenSession,
556 JumpAnchor,
558 InPageSearchJump,
560 ImportedHistory,
562}
563
564#[derive(
566 Archive, Serialize, Deserialize, Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize,
567)]
568pub struct PersistedEdge {
569 pub from_node_id: String,
570 pub to_node_id: String,
571 #[serde(default)]
572 pub families: Vec<PersistedEdgeFamily>,
573 #[serde(default)]
574 pub semantic: Option<PersistedSemanticEdgeData>,
575 #[serde(default)]
576 pub traversal: Option<PersistedTraversalEdgeData>,
577 #[serde(default)]
578 pub containment: Option<PersistedContainmentEdgeData>,
579 #[serde(default)]
580 pub arrangement: Option<PersistedArrangementEdgeData>,
581 #[serde(default)]
582 pub imported: Option<PersistedImportedEdgeData>,
583 #[serde(default)]
584 pub provenance: Option<PersistedProvenanceEdgeData>,
585 #[serde(default, skip_serializing_if = "Option::is_none")]
588 pub assertions: Option<Vec<PersistedSemanticStatement>>,
589}
590
591impl PersistedEdge {
592 pub fn retained_assertions(&self) -> &[PersistedSemanticStatement] {
593 self.assertions.as_deref().unwrap_or_else(|| self.semantic.as_ref()
594 .map(|data| data.statements.as_slice()).unwrap_or(&[]))
595 }
596 pub fn retained_assertions_mut(&mut self) -> &mut [PersistedSemanticStatement] {
597 match self.assertions.as_mut() {
598 Some(records) => records.as_mut_slice(),
599 None => self.semantic.as_mut().map(|data| data.statements.as_mut_slice()).unwrap_or(&mut []),
600 }
601 }
602 pub fn has_legacy_assertion_data(&self) -> bool {
603 self.semantic.as_ref().is_some_and(|data| !data.statements.is_empty() || !data.sub_kinds.is_empty()
604 || data.predicate.is_some() || data.label.is_some())
605 || self.containment.as_ref().is_some_and(|data| !data.sub_kinds.is_empty())
606 || self.arrangement.as_ref().is_some_and(|data| !data.sub_kinds.is_empty())
607 || self.imported.as_ref().is_some_and(|data| !data.sub_kinds.is_empty())
608 || self.provenance.as_ref().is_some_and(|data| !data.sub_kinds.is_empty())
609 }
610}
611
612#[cfg(test)]
613mod statement_serialization_tests {
614 use super::*;
615
616 fn cases() -> Vec<PersistedSemanticStatement> {
617 let plain = PersistedSemanticStatement {
618 statement_id: "held\nassertion".into(),
619 predicate: "urn:predicate:held".into(),
620 recognized_sub_kind: None,
621 label: None,
622 graph_scope: GraphScope::Default,
623 provenance_iri: Some("https://author.test/".into()),
624 asserted_at_ms: None,
625 first_asserted_ms: None,
626 withdrawn: None,
627 basis: Default::default(),
628 };
629 let mut legacy = plain.clone();
630 legacy.provenance_iri = None;
631 let mut marker = plain.clone();
632 marker.provenance_iri = Some(crate::graph::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI.into());
633 let mut rich = plain.clone();
634 rich.statement_id = String::new();
635 rich.recognized_sub_kind = Some(PersistedSemanticSubKind::Cites);
636 rich.label = Some(String::new());
637 rich.graph_scope = GraphScope::Custom("urn:graph:held".into());
638 rich.provenance_iri = Some(String::new());
639 rich.asserted_at_ms = Some(0);
640 rich.first_asserted_ms = Some(0);
641 rich.basis.note = Some(String::new());
642 vec![plain, legacy, marker, rich]
643 }
644
645 #[test]
646 fn statement_json_omits_absent_metadata_and_preserves_explicit_values() {
647 let cases = cases();
648 let plain = serde_json::to_value(&cases[0]).unwrap();
649 assert_eq!(plain.as_object().unwrap().len(), 3);
650 assert_eq!(plain["statement_id"], "held\nassertion");
651 assert_eq!(plain["provenance_iri"], "https://author.test/");
652 for absent in [
653 "recognized_sub_kind",
654 "label",
655 "graph_scope",
656 "asserted_at_ms",
657 ] {
658 assert!(plain.get(absent).is_none());
659 }
660 let legacy = serde_json::to_value(&cases[1]).unwrap();
661 assert!(legacy.get("provenance_iri").is_none());
662 assert_eq!(
663 serde_json::from_value::<PersistedSemanticStatement>(legacy).unwrap(),
664 cases[1]
665 );
666 let marker = serde_json::to_value(&cases[2]).unwrap();
667 assert_eq!(
668 marker["provenance_iri"],
669 crate::graph::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI
670 );
671 let rich = serde_json::to_value(&cases[3]).unwrap();
672 assert_eq!(rich.as_object().unwrap().len(), 9);
673 assert_eq!(rich["statement_id"], "");
674 assert_eq!(rich["label"], "");
675 assert_eq!(rich["provenance_iri"], "");
676 assert_eq!(rich["asserted_at_ms"], 0);
677 assert_eq!(rich["first_asserted_ms"], 0);
678 for value in cases {
679 let bytes = serde_json::to_vec(&value).unwrap();
680 assert_eq!(
681 serde_json::from_slice::<PersistedSemanticStatement>(&bytes).unwrap(),
682 value
683 );
684 }
685 }
686
687 #[test]
688 fn statement_binary_current_shape_round_trips() {
689 for value in cases() {
690 let bytes = postcard::to_allocvec(&value).unwrap();
691 assert_eq!(
692 postcard::from_bytes::<PersistedSemanticStatement>(&bytes).unwrap(),
693 value
694 );
695 let archive = rkyv::to_bytes::<rkyv::rancor::Error>(&value).unwrap();
696 assert_eq!(
697 rkyv::from_bytes::<PersistedSemanticStatement, rkyv::rancor::Error>(&archive)
698 .unwrap(),
699 value
700 );
701 }
702 }
703
704 #[test]
705 fn legacy_postcard_sequence_is_not_a_supported_store_format() {
706 #[derive(serde::Serialize)]
707 struct Legacy {
708 statement_id: String,
709 predicate: String,
710 recognized_sub_kind: Option<PersistedSemanticSubKind>,
711 label: Option<String>,
712 graph_scope: GraphScope,
713 provenance_iri: Option<String>,
714 asserted_at_ms: Option<u64>,
715 }
716
717 let legacy = Legacy {
718 statement_id: "legacy-sequence".into(),
719 predicate: "urn:p".into(),
720 recognized_sub_kind: None,
721 label: None,
722 graph_scope: GraphScope::Default,
723 provenance_iri: Some("urn:source".into()),
724 asserted_at_ms: Some(42),
725 };
726 let bytes = postcard::to_allocvec(&legacy).unwrap();
727 assert!(postcard::from_bytes::<PersistedSemanticStatement>(&bytes).is_err());
728 }
729
730 #[test]
731 fn legacy_time_falls_back_only_when_first_time_is_absent() {
732 let legacy = serde_json::json!({
733 "statement_id": "legacy",
734 "predicate": "urn:p",
735 "asserted_at_ms": 42
736 });
737 let decoded: PersistedSemanticStatement = serde_json::from_value(legacy).unwrap();
738 assert_eq!(decoded.first_asserted_ms, Some(42));
739 assert_eq!(decoded.asserted_at_ms, Some(42));
740
741 let explicit_unknown = serde_json::json!({
742 "statement_id": "unknown-first",
743 "predicate": "urn:p",
744 "first_asserted_ms": null,
745 "asserted_at_ms": 42
746 });
747 let decoded: PersistedSemanticStatement = serde_json::from_value(explicit_unknown).unwrap();
748 assert_eq!(decoded.first_asserted_ms, None);
749 assert_eq!(decoded.asserted_at_ms, Some(42));
750 let encoded = serde_json::to_value(decoded).unwrap();
751 assert!(encoded.get("first_asserted_ms").is_some());
752 assert!(encoded["first_asserted_ms"].is_null());
753 }
754}