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                content_hash: node.content.map(|hash| hash.to_hex()),
101            })
102            .collect();
103
104        let edges = self
105            .inner
106            .inner()
107            .edge_references()
108            .map(|edge| {
109                let from_node_id = self
110                    .get_node(edge.source())
111                    .map(|n| n.id.to_string())
112                    .unwrap_or_default();
113                let to_node_id = self
114                    .get_node(edge.target())
115                    .map(|n| n.id.to_string())
116                    .unwrap_or_default();
117                let payload = edge.weight();
118                PersistedEdge {
119                    from_node_id,
120                    to_node_id,
121                    families: payload
122                        .families()
123                        .iter()
124                        .map(|family| match family {
125                            EdgeFamily::Semantic => PersistedEdgeFamily::Semantic,
126                            EdgeFamily::Traversal => PersistedEdgeFamily::Traversal,
127                            EdgeFamily::Containment => PersistedEdgeFamily::Containment,
128                            EdgeFamily::Arrangement => PersistedEdgeFamily::Arrangement,
129                            EdgeFamily::Imported => PersistedEdgeFamily::Imported,
130                            EdgeFamily::Provenance => PersistedEdgeFamily::Provenance,
131                        })
132                        .collect(),
133                    semantic: Some(PersistedSemanticEdgeData {
134                        sub_kinds: payload
135                            .semantic_data()
136                            .map(|data| {
137                                data.sub_kinds
138                                    .iter()
139                                    .copied()
140                                    .map(persisted_semantic_sub_kind)
141                                    .collect()
142                            })
143                            .unwrap_or_default(),
144                        label: payload.semantic_data().and_then(|data| data.label.clone()),
145                        agent_decay_progress: payload
146                            .has_relation(RelationSelector::Semantic(SemanticSubKind::AgentDerived))
147                            .then_some(0.0),
148                        predicate: payload
149                            .semantic_data()
150                            .and_then(|data| data.predicate.clone()),
151                        statements: payload
152                            .semantic_statements()
153                            .iter()
154                            .map(|statement| PersistedSemanticStatement {
155                                statement_id: statement.statement_id.clone(),
156                                predicate: statement.predicate.clone(),
157                                recognized_sub_kind: statement
158                                    .recognized_sub_kind
159                                    .map(persisted_semantic_sub_kind),
160                                label: statement.label.clone(),
161                                graph_scope: statement.graph_scope.clone(),
162                                provenance_iri: statement.provenance_iri.clone(),
163                                asserted_at_ms: statement.asserted_at_ms,
164                            })
165                            .collect(),
166                    })
167                    .filter(|data| {
168                        !data.sub_kinds.is_empty()
169                            || data.label.is_some()
170                            || data.predicate.is_some()
171                            || !data.statements.is_empty()
172                    }),
173                    traversal: payload
174                        .traversal_data()
175                        .map(|data| PersistedTraversalEdgeData {
176                            traversals: data
177                                .traversals
178                                .iter()
179                                .map(|traversal| PersistedTraversalRecord {
180                                    timestamp_ms: traversal.timestamp_ms,
181                                    trigger: match traversal.trigger {
182                                        NavigationTrigger::Unknown => {
183                                            PersistedNavigationTrigger::Unknown
184                                        }
185                                        NavigationTrigger::LinkClick => {
186                                            PersistedNavigationTrigger::LinkClick
187                                        }
188                                        NavigationTrigger::Back => PersistedNavigationTrigger::Back,
189                                        NavigationTrigger::Forward => {
190                                            PersistedNavigationTrigger::Forward
191                                        }
192                                        NavigationTrigger::AddressBarEntry => {
193                                            PersistedNavigationTrigger::AddressBarEntry
194                                        }
195                                        NavigationTrigger::PanePromotion => {
196                                            PersistedNavigationTrigger::PanePromotion
197                                        }
198                                        NavigationTrigger::Programmatic => {
199                                            PersistedNavigationTrigger::Programmatic
200                                        }
201                                        NavigationTrigger::Redirect => {
202                                            PersistedNavigationTrigger::Redirect
203                                        }
204                                        NavigationTrigger::ReopenSession => {
205                                            PersistedNavigationTrigger::ReopenSession
206                                        }
207                                        NavigationTrigger::JumpAnchor => {
208                                            PersistedNavigationTrigger::JumpAnchor
209                                        }
210                                        NavigationTrigger::InPageSearchJump => {
211                                            PersistedNavigationTrigger::InPageSearchJump
212                                        }
213                                        NavigationTrigger::ImportedHistory => {
214                                            PersistedNavigationTrigger::ImportedHistory
215                                        }
216                                    },
217                                })
218                                .collect(),
219                            metrics: PersistedTraversalMetrics {
220                                total_navigations: data.metrics.total_navigations,
221                                forward_navigations: data.metrics.forward_navigations,
222                                backward_navigations: data.metrics.backward_navigations,
223                                last_navigated_at: data.metrics.last_navigated_at,
224                            },
225                        }),
226                    containment: payload.containment_data().map(|data| {
227                        PersistedContainmentEdgeData {
228                            sub_kinds: data
229                                .sub_kinds
230                                .iter()
231                                .map(|sub_kind| match sub_kind {
232                                    ContainmentSubKind::UrlPath => {
233                                        PersistedContainmentSubKind::UrlPath
234                                    }
235                                    ContainmentSubKind::Domain => {
236                                        PersistedContainmentSubKind::Domain
237                                    }
238                                    ContainmentSubKind::FileSystem => {
239                                        PersistedContainmentSubKind::FileSystem
240                                    }
241                                    ContainmentSubKind::UserFolder => {
242                                        PersistedContainmentSubKind::UserFolder
243                                    }
244                                    ContainmentSubKind::ClipSource => {
245                                        PersistedContainmentSubKind::ClipSource
246                                    }
247                                    ContainmentSubKind::NotebookSection => {
248                                        PersistedContainmentSubKind::NotebookSection
249                                    }
250                                    ContainmentSubKind::CollectionMember => {
251                                        PersistedContainmentSubKind::CollectionMember
252                                    }
253                                })
254                                .collect(),
255                        }
256                    }),
257                    arrangement: payload.arrangement_data().map(|data| {
258                        PersistedArrangementEdgeData {
259                            sub_kinds: data
260                                .sub_kinds
261                                .iter()
262                                .copied()
263                                .filter(|sub_kind| {
264                                    sub_kind.durability() == RelationDurability::Durable
265                                })
266                                .map(|sub_kind| match sub_kind {
267                                    ArrangementSubKind::FrameMember => {
268                                        PersistedArrangementSubKind::FrameMember
269                                    }
270                                    ArrangementSubKind::TileGroup => {
271                                        PersistedArrangementSubKind::TileGroup
272                                    }
273                                    ArrangementSubKind::SplitPair => {
274                                        PersistedArrangementSubKind::SplitPair
275                                    }
276                                })
277                                .collect(),
278                        }
279                    }),
280                    imported: payload
281                        .imported_data()
282                        .map(|data| PersistedImportedEdgeData {
283                            sub_kinds: data
284                                .sub_kinds
285                                .iter()
286                                .map(|sub_kind| match sub_kind {
287                                    ImportedSubKind::BookmarkFolder => {
288                                        PersistedImportedSubKind::BookmarkFolder
289                                    }
290                                    ImportedSubKind::HistoryImport => {
291                                        PersistedImportedSubKind::HistoryImport
292                                    }
293                                    ImportedSubKind::SessionImport => {
294                                        PersistedImportedSubKind::SessionImport
295                                    }
296                                    ImportedSubKind::RssMembership => {
297                                        PersistedImportedSubKind::RssMembership
298                                    }
299                                    ImportedSubKind::FileSystemImport => {
300                                        PersistedImportedSubKind::FileSystemImport
301                                    }
302                                    ImportedSubKind::ArchiveMembership => {
303                                        PersistedImportedSubKind::ArchiveMembership
304                                    }
305                                    ImportedSubKind::SharedCollection => {
306                                        PersistedImportedSubKind::SharedCollection
307                                    }
308                                })
309                                .collect(),
310                        }),
311                    provenance: payload
312                        .provenance_data()
313                        .map(|data| PersistedProvenanceEdgeData {
314                            sub_kinds: data
315                                .sub_kinds
316                                .iter()
317                                .map(|sub_kind| match sub_kind {
318                                    ProvenanceSubKind::ClippedFrom => {
319                                        PersistedProvenanceSubKind::ClippedFrom
320                                    }
321                                    ProvenanceSubKind::ExcerptedFrom => {
322                                        PersistedProvenanceSubKind::ExcerptedFrom
323                                    }
324                                    ProvenanceSubKind::SummarizedFrom => {
325                                        PersistedProvenanceSubKind::SummarizedFrom
326                                    }
327                                    ProvenanceSubKind::TranslatedFrom => {
328                                        PersistedProvenanceSubKind::TranslatedFrom
329                                    }
330                                    ProvenanceSubKind::RewrittenFrom => {
331                                        PersistedProvenanceSubKind::RewrittenFrom
332                                    }
333                                    ProvenanceSubKind::GeneratedFrom => {
334                                        PersistedProvenanceSubKind::GeneratedFrom
335                                    }
336                                    ProvenanceSubKind::ExtractedFrom => {
337                                        PersistedProvenanceSubKind::ExtractedFrom
338                                    }
339                                    ProvenanceSubKind::ImportedFromSource => {
340                                        PersistedProvenanceSubKind::ImportedFromSource
341                                    }
342                                    ProvenanceSubKind::CopiedFrom => {
343                                        PersistedProvenanceSubKind::CopiedFrom
344                                    }
345                                })
346                                .collect(),
347                        }),
348                }
349            })
350            .collect();
351
352        let fields = self
353            .fields()
354            .map(|f| PersistedField {
355                id: f.id.as_uuid().to_string(),
356                name: f.name.clone(),
357                // The recursive AST rides as a JSON blob (see persistence_fields).
358                definition_json: serde_json::to_string(&f.definition).unwrap_or_default(),
359                extent: match &f.extent {
360                    FieldExtent::Global => PersistedFieldExtent::Global,
361                    FieldExtent::Region {
362                        min_x,
363                        min_y,
364                        max_x,
365                        max_y,
366                    } => PersistedFieldExtent::Region {
367                        min_x: *min_x,
368                        min_y: *min_y,
369                        max_x: *max_x,
370                        max_y: *max_y,
371                    },
372                    FieldExtent::AttachedToNode(id) => {
373                        PersistedFieldExtent::AttachedToNode(id.to_string())
374                    }
375                    FieldExtent::Polygon { points } => PersistedFieldExtent::Polygon {
376                        points: points.clone(),
377                    },
378                },
379                lifecycle: match f.lifecycle {
380                    FieldLifecycle::Active => PersistedFieldLifecycle::Active,
381                    FieldLifecycle::Retired => PersistedFieldLifecycle::Retired,
382                },
383            })
384            .collect();
385
386        let couplings = self
387            .couplings()
388            .map(|c| PersistedCoupling {
389                id: c.id.as_uuid().to_string(),
390                field_id: c.field.as_uuid().to_string(),
391                selector: match &c.selector {
392                    NodeSelector::All => PersistedNodeSelector::All,
393                    NodeSelector::Tagged(t) => PersistedNodeSelector::Tagged(t.clone()),
394                    NodeSelector::Kind(k) => PersistedNodeSelector::Kind(k.clone()),
395                    NodeSelector::NotTagged(t) => PersistedNodeSelector::NotTagged(t.clone()),
396                },
397                response: match &c.response {
398                    CouplingResponse::AttractToMin => PersistedCouplingResponse::AttractToMin,
399                    CouplingResponse::RepelFromMax => PersistedCouplingResponse::RepelFromMax,
400                    CouplingResponse::AlignVelocity => PersistedCouplingResponse::AlignVelocity,
401                    CouplingResponse::FlowAdvect => PersistedCouplingResponse::FlowAdvect,
402                    CouplingResponse::DampenInside { factor } => {
403                        PersistedCouplingResponse::DampenInside { factor: *factor }
404                    }
405                    CouplingResponse::ContainmentWall => PersistedCouplingResponse::ContainmentWall,
406                    CouplingResponse::Open { predicate } => PersistedCouplingResponse::Open {
407                        predicate: predicate.clone(),
408                    },
409                },
410                strength: c.strength,
411            })
412            .collect();
413
414        let timestamp_secs = crate::time::unix_epoch_seconds();
415
416        GraphSnapshot {
417            nodes,
418            edges,
419            import_records: self.import_records.clone(),
420            timestamp_secs,
421            fields,
422            couplings,
423            navigation: self.nav.clone(),
424        }
425    }
426}