Skip to main content

kernel/graph/snapshot/
to.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! `Graph::to_snapshot` — serialize the runtime graph into a
5//! [`GraphSnapshot`] for persistence.
6//!
7//! Extracted from `graph/snapshot.rs` per the 2026-05-11 kernel
8//! decomposition pass (the original file was 724 LOC).
9
10use petgraph::visit::EdgeRef;
11
12use super::super::*;
13use crate::persistence::{
14    GraphSnapshot, PersistedAddress, PersistedArrangementEdgeData, PersistedArrangementSubKind,
15    PersistedContainmentEdgeData, PersistedContainmentSubKind, PersistedCoupling,
16    PersistedCouplingResponse, PersistedEdge, PersistedEdgeFamily, PersistedField,
17    PersistedFieldExtent, PersistedFieldLifecycle, PersistedImportedEdgeData,
18    PersistedImportedSubKind, PersistedNavigationTrigger, PersistedNode, PersistedNodeSelector,
19    PersistedNodeSessionState, PersistedProvenanceEdgeData, PersistedProvenanceSubKind,
20    PersistedSemanticEdgeData, PersistedSemanticStatement, PersistedSemanticSubKind,
21    PersistedTraversalEdgeData, PersistedTraversalMetrics, PersistedTraversalRecord,
22};
23fn persisted_semantic_sub_kind(sub_kind: SemanticSubKind) -> PersistedSemanticSubKind {
24    match sub_kind {
25        SemanticSubKind::Hyperlink => PersistedSemanticSubKind::Hyperlink,
26        SemanticSubKind::UserGrouped => PersistedSemanticSubKind::UserGrouped,
27        SemanticSubKind::AgentDerived => PersistedSemanticSubKind::AgentDerived,
28        SemanticSubKind::Cites => PersistedSemanticSubKind::Cites,
29        SemanticSubKind::Quotes => PersistedSemanticSubKind::Quotes,
30        SemanticSubKind::Summarizes => PersistedSemanticSubKind::Summarizes,
31        SemanticSubKind::Elaborates => PersistedSemanticSubKind::Elaborates,
32        SemanticSubKind::ExampleOf => PersistedSemanticSubKind::ExampleOf,
33        SemanticSubKind::Supports => PersistedSemanticSubKind::Supports,
34        SemanticSubKind::Contradicts => PersistedSemanticSubKind::Contradicts,
35        SemanticSubKind::Questions => PersistedSemanticSubKind::Questions,
36        SemanticSubKind::SameEntityAs => PersistedSemanticSubKind::SameEntityAs,
37        SemanticSubKind::DuplicateOf => PersistedSemanticSubKind::DuplicateOf,
38        SemanticSubKind::CanonicalMirrorOf => PersistedSemanticSubKind::CanonicalMirrorOf,
39        SemanticSubKind::DependsOn => PersistedSemanticSubKind::DependsOn,
40        SemanticSubKind::Blocks => PersistedSemanticSubKind::Blocks,
41        SemanticSubKind::NextStep => PersistedSemanticSubKind::NextStep,
42    }
43}
44
45impl Graph {
46    pub fn to_snapshot(&self) -> GraphSnapshot {
47        let nodes = self
48            .nodes()
49            .map(|(_, node)| PersistedNode {
50                node_id: node.id.to_string(),
51                // Legacy wire field only. Hostnames are derived from the
52                // Container's primary address and are never stored anew.
53                cached_host: None,
54                title: node.title.clone(),
55                tags: {
56                    let mut tags = node.tags.iter().cloned().collect::<Vec<_>>();
57                    tags.sort();
58                    tags
59                },
60                tag_presentation: Default::default(),
61                import_provenance: Vec::new(),
62                is_pinned: false,
63                images: node.images.clone(),
64                // Never written: a saved snapshot carries references only.
65                legacy_thumbnail_png: None,
66                legacy_thumbnail_width: 0,
67                legacy_thumbnail_height: 0,
68                legacy_favicon_rgba: None,
69                legacy_favicon_width: 0,
70                legacy_favicon_height: 0,
71                // Scroll / form draft left for the host's BrowserNodeState
72                // sidecar (boundary pass slice C); the snapshot now carries
73                // only the last-visited clock here. `session_state` itself
74                // stays for legacy readers and the one-time load migration.
75                session_state: Some(PersistedNodeSessionState {
76                    scroll_x: None,
77                    scroll_y: None,
78                    form_draft: None,
79                    last_visited_ms: None,
80                }),
81                address: match node.primary_address() {
82                    Address::Http(s) => PersistedAddress::Http(s.clone()),
83                    Address::File(s) => PersistedAddress::File(s.clone()),
84                    Address::Data(s) => PersistedAddress::Data(s.clone()),
85                    Address::Clip(s) => PersistedAddress::Clip(s.clone()),
86                    Address::Directory(s) => PersistedAddress::Directory(s.clone()),
87                    Address::Custom(s) => PersistedAddress::Custom(s.clone()),
88                },
89                // Written for backward compat: pre-Stage C.2 readers use this field.
90                url: node.primary_address().as_url_str().to_string(),
91                classifications: Vec::new(),
92                mime_hint: node.media_type.clone(),
93                frame_layout_hints: Vec::new(),
94                frame_split_offer_suppressed: false,
95                properties: Vec::new(),
96                derivations: Vec::new(),
97                body: node.body.clone(),
98                last_session_visited: 0,
99                nested: node.nested.as_ref().map(|log| log.as_str().to_string()),
100            })
101            .collect();
102
103        let edges = self
104            .inner
105            .inner()
106            .edge_references()
107            .map(|edge| {
108                let from_node_id = self
109                    .get_node(edge.source())
110                    .map(|n| n.id.to_string())
111                    .unwrap_or_default();
112                let to_node_id = self
113                    .get_node(edge.target())
114                    .map(|n| n.id.to_string())
115                    .unwrap_or_default();
116                let payload = edge.weight();
117                PersistedEdge {
118                    from_node_id,
119                    to_node_id,
120                    families: payload
121                        .families()
122                        .iter()
123                        .map(|family| match family {
124                            EdgeFamily::Semantic => PersistedEdgeFamily::Semantic,
125                            EdgeFamily::Traversal => PersistedEdgeFamily::Traversal,
126                            EdgeFamily::Containment => PersistedEdgeFamily::Containment,
127                            EdgeFamily::Arrangement => PersistedEdgeFamily::Arrangement,
128                            EdgeFamily::Imported => PersistedEdgeFamily::Imported,
129                            EdgeFamily::Provenance => PersistedEdgeFamily::Provenance,
130                        })
131                        .collect(),
132                    semantic: Some(PersistedSemanticEdgeData {
133                        sub_kinds: payload
134                            .semantic_data()
135                            .map(|data| {
136                                data.sub_kinds
137                                    .iter()
138                                    .copied()
139                                    .map(persisted_semantic_sub_kind)
140                                    .collect()
141                            })
142                            .unwrap_or_default(),
143                        label: payload.semantic_data().and_then(|data| data.label.clone()),
144                        agent_decay_progress: payload
145                            .has_relation(RelationSelector::Semantic(SemanticSubKind::AgentDerived))
146                            .then_some(0.0),
147                        predicate: payload
148                            .semantic_data()
149                            .and_then(|data| data.predicate.clone()),
150                        statements: payload
151                            .semantic_statements()
152                            .iter()
153                            .map(|statement| PersistedSemanticStatement {
154                                statement_id: statement.statement_id.clone(),
155                                predicate: statement.predicate.clone(),
156                                recognized_sub_kind: statement
157                                    .recognized_sub_kind
158                                    .map(persisted_semantic_sub_kind),
159                                label: statement.label.clone(),
160                                graph_scope: statement.graph_scope.clone(),
161                                provenance_iri: statement.provenance_iri.clone(),
162                                asserted_at_ms: statement.asserted_at_ms,
163                            })
164                            .collect(),
165                    })
166                    .filter(|data| {
167                        !data.sub_kinds.is_empty()
168                            || data.label.is_some()
169                            || data.predicate.is_some()
170                            || !data.statements.is_empty()
171                    }),
172                    traversal: payload
173                        .traversal_data()
174                        .map(|data| PersistedTraversalEdgeData {
175                            traversals: data
176                                .traversals
177                                .iter()
178                                .map(|traversal| PersistedTraversalRecord {
179                                    timestamp_ms: traversal.timestamp_ms,
180                                    trigger: match traversal.trigger {
181                                        NavigationTrigger::Unknown => {
182                                            PersistedNavigationTrigger::Unknown
183                                        }
184                                        NavigationTrigger::LinkClick => {
185                                            PersistedNavigationTrigger::LinkClick
186                                        }
187                                        NavigationTrigger::Back => PersistedNavigationTrigger::Back,
188                                        NavigationTrigger::Forward => {
189                                            PersistedNavigationTrigger::Forward
190                                        }
191                                        NavigationTrigger::AddressBarEntry => {
192                                            PersistedNavigationTrigger::AddressBarEntry
193                                        }
194                                        NavigationTrigger::PanePromotion => {
195                                            PersistedNavigationTrigger::PanePromotion
196                                        }
197                                        NavigationTrigger::Programmatic => {
198                                            PersistedNavigationTrigger::Programmatic
199                                        }
200                                        NavigationTrigger::Redirect => {
201                                            PersistedNavigationTrigger::Redirect
202                                        }
203                                        NavigationTrigger::ReopenSession => {
204                                            PersistedNavigationTrigger::ReopenSession
205                                        }
206                                        NavigationTrigger::JumpAnchor => {
207                                            PersistedNavigationTrigger::JumpAnchor
208                                        }
209                                        NavigationTrigger::InPageSearchJump => {
210                                            PersistedNavigationTrigger::InPageSearchJump
211                                        }
212                                        NavigationTrigger::ImportedHistory => {
213                                            PersistedNavigationTrigger::ImportedHistory
214                                        }
215                                    },
216                                })
217                                .collect(),
218                            metrics: PersistedTraversalMetrics {
219                                total_navigations: data.metrics.total_navigations,
220                                forward_navigations: data.metrics.forward_navigations,
221                                backward_navigations: data.metrics.backward_navigations,
222                                last_navigated_at: data.metrics.last_navigated_at,
223                            },
224                        }),
225                    containment: payload.containment_data().map(|data| {
226                        PersistedContainmentEdgeData {
227                            sub_kinds: data
228                                .sub_kinds
229                                .iter()
230                                .map(|sub_kind| match sub_kind {
231                                    ContainmentSubKind::UrlPath => {
232                                        PersistedContainmentSubKind::UrlPath
233                                    }
234                                    ContainmentSubKind::Domain => {
235                                        PersistedContainmentSubKind::Domain
236                                    }
237                                    ContainmentSubKind::FileSystem => {
238                                        PersistedContainmentSubKind::FileSystem
239                                    }
240                                    ContainmentSubKind::UserFolder => {
241                                        PersistedContainmentSubKind::UserFolder
242                                    }
243                                    ContainmentSubKind::ClipSource => {
244                                        PersistedContainmentSubKind::ClipSource
245                                    }
246                                    ContainmentSubKind::NotebookSection => {
247                                        PersistedContainmentSubKind::NotebookSection
248                                    }
249                                    ContainmentSubKind::CollectionMember => {
250                                        PersistedContainmentSubKind::CollectionMember
251                                    }
252                                })
253                                .collect(),
254                        }
255                    }),
256                    arrangement: payload.arrangement_data().map(|data| {
257                        PersistedArrangementEdgeData {
258                            sub_kinds: data
259                                .sub_kinds
260                                .iter()
261                                .copied()
262                                .filter(|sub_kind| {
263                                    sub_kind.durability() == RelationDurability::Durable
264                                })
265                                .map(|sub_kind| match sub_kind {
266                                    ArrangementSubKind::FrameMember => {
267                                        PersistedArrangementSubKind::FrameMember
268                                    }
269                                    ArrangementSubKind::TileGroup => {
270                                        PersistedArrangementSubKind::TileGroup
271                                    }
272                                    ArrangementSubKind::SplitPair => {
273                                        PersistedArrangementSubKind::SplitPair
274                                    }
275                                })
276                                .collect(),
277                        }
278                    }),
279                    imported: payload
280                        .imported_data()
281                        .map(|data| PersistedImportedEdgeData {
282                            sub_kinds: data
283                                .sub_kinds
284                                .iter()
285                                .map(|sub_kind| match sub_kind {
286                                    ImportedSubKind::BookmarkFolder => {
287                                        PersistedImportedSubKind::BookmarkFolder
288                                    }
289                                    ImportedSubKind::HistoryImport => {
290                                        PersistedImportedSubKind::HistoryImport
291                                    }
292                                    ImportedSubKind::SessionImport => {
293                                        PersistedImportedSubKind::SessionImport
294                                    }
295                                    ImportedSubKind::RssMembership => {
296                                        PersistedImportedSubKind::RssMembership
297                                    }
298                                    ImportedSubKind::FileSystemImport => {
299                                        PersistedImportedSubKind::FileSystemImport
300                                    }
301                                    ImportedSubKind::ArchiveMembership => {
302                                        PersistedImportedSubKind::ArchiveMembership
303                                    }
304                                    ImportedSubKind::SharedCollection => {
305                                        PersistedImportedSubKind::SharedCollection
306                                    }
307                                })
308                                .collect(),
309                        }),
310                    provenance: payload
311                        .provenance_data()
312                        .map(|data| PersistedProvenanceEdgeData {
313                            sub_kinds: data
314                                .sub_kinds
315                                .iter()
316                                .map(|sub_kind| match sub_kind {
317                                    ProvenanceSubKind::ClippedFrom => {
318                                        PersistedProvenanceSubKind::ClippedFrom
319                                    }
320                                    ProvenanceSubKind::ExcerptedFrom => {
321                                        PersistedProvenanceSubKind::ExcerptedFrom
322                                    }
323                                    ProvenanceSubKind::SummarizedFrom => {
324                                        PersistedProvenanceSubKind::SummarizedFrom
325                                    }
326                                    ProvenanceSubKind::TranslatedFrom => {
327                                        PersistedProvenanceSubKind::TranslatedFrom
328                                    }
329                                    ProvenanceSubKind::RewrittenFrom => {
330                                        PersistedProvenanceSubKind::RewrittenFrom
331                                    }
332                                    ProvenanceSubKind::GeneratedFrom => {
333                                        PersistedProvenanceSubKind::GeneratedFrom
334                                    }
335                                    ProvenanceSubKind::ExtractedFrom => {
336                                        PersistedProvenanceSubKind::ExtractedFrom
337                                    }
338                                    ProvenanceSubKind::ImportedFromSource => {
339                                        PersistedProvenanceSubKind::ImportedFromSource
340                                    }
341                                    ProvenanceSubKind::CopiedFrom => {
342                                        PersistedProvenanceSubKind::CopiedFrom
343                                    }
344                                })
345                                .collect(),
346                        }),
347                }
348            })
349            .collect();
350
351        let fields = self
352            .fields()
353            .map(|f| PersistedField {
354                id: f.id.as_uuid().to_string(),
355                name: f.name.clone(),
356                // The recursive AST rides as a JSON blob (see persistence_fields).
357                definition_json: serde_json::to_string(&f.definition).unwrap_or_default(),
358                extent: match &f.extent {
359                    FieldExtent::Global => PersistedFieldExtent::Global,
360                    FieldExtent::Region {
361                        min_x,
362                        min_y,
363                        max_x,
364                        max_y,
365                    } => PersistedFieldExtent::Region {
366                        min_x: *min_x,
367                        min_y: *min_y,
368                        max_x: *max_x,
369                        max_y: *max_y,
370                    },
371                    FieldExtent::AttachedToNode(id) => {
372                        PersistedFieldExtent::AttachedToNode(id.to_string())
373                    }
374                    FieldExtent::Polygon { points } => PersistedFieldExtent::Polygon {
375                        points: points.clone(),
376                    },
377                },
378                lifecycle: match f.lifecycle {
379                    FieldLifecycle::Active => PersistedFieldLifecycle::Active,
380                    FieldLifecycle::Retired => PersistedFieldLifecycle::Retired,
381                },
382            })
383            .collect();
384
385        let couplings = self
386            .couplings()
387            .map(|c| PersistedCoupling {
388                id: c.id.as_uuid().to_string(),
389                field_id: c.field.as_uuid().to_string(),
390                selector: match &c.selector {
391                    NodeSelector::All => PersistedNodeSelector::All,
392                    NodeSelector::Tagged(t) => PersistedNodeSelector::Tagged(t.clone()),
393                    NodeSelector::Kind(k) => PersistedNodeSelector::Kind(k.clone()),
394                    NodeSelector::NotTagged(t) => PersistedNodeSelector::NotTagged(t.clone()),
395                },
396                response: match &c.response {
397                    CouplingResponse::AttractToMin => PersistedCouplingResponse::AttractToMin,
398                    CouplingResponse::RepelFromMax => PersistedCouplingResponse::RepelFromMax,
399                    CouplingResponse::AlignVelocity => PersistedCouplingResponse::AlignVelocity,
400                    CouplingResponse::FlowAdvect => PersistedCouplingResponse::FlowAdvect,
401                    CouplingResponse::DampenInside { factor } => {
402                        PersistedCouplingResponse::DampenInside { factor: *factor }
403                    }
404                    CouplingResponse::ContainmentWall => PersistedCouplingResponse::ContainmentWall,
405                    CouplingResponse::Open { predicate } => PersistedCouplingResponse::Open {
406                        predicate: predicate.clone(),
407                    },
408                },
409                strength: c.strength,
410            })
411            .collect();
412
413        let timestamp_secs = crate::time::unix_epoch_seconds();
414
415        GraphSnapshot {
416            nodes,
417            edges,
418            import_records: self.import_records.clone(),
419            timestamp_secs,
420            fields,
421            couplings,
422            navigation: self.nav.clone(),
423        }
424    }
425}