Skip to main content

kernel/graph/snapshot/
to.rs

1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! `Graph::to_snapshot` — serialize the runtime graph into a
8//! [`GraphSnapshot`] for persistence.
9//!
10//! Extracted from `graph/snapshot.rs` per the 2026-05-11 kernel
11//! decomposition pass (the original file was 724 LOC).
12
13use petgraph::visit::EdgeRef;
14
15use super::super::*;
16use crate::persistence::{
17    GraphSnapshot, PersistedAddress, PersistedCoupling, PersistedCouplingResponse, PersistedEdge,
18    PersistedEdgeFamily, PersistedField, PersistedFieldExtent, PersistedFieldLifecycle,
19    PersistedNavigationTrigger, PersistedNode, PersistedNodeSelector, PersistedNodeSessionState,
20    PersistedSemanticStatement, PersistedSemanticSubKind, PersistedShownResource,
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    /// The graph's snapshot, dated now by the wall clock.
47    pub fn to_snapshot(&self) -> GraphSnapshot {
48        self.to_snapshot_at(crate::time::unix_epoch_seconds())
49    }
50
51    /// The graph's snapshot dated `timestamp_secs`, reading no clock: two
52    /// snapshots of one graph at one date are equal whenever they are taken
53    /// (reservoir plan ruling 47).
54    pub fn to_snapshot_at(&self, timestamp_secs: u64) -> GraphSnapshot {
55        let nodes = self
56            .nodes()
57            .map(|(_, node)| PersistedNode {
58                node_id: node.id.to_string(),
59                // Legacy wire field only. Hostnames are derived from the
60                // Container's primary address and are never stored anew.
61                cached_host: None,
62                title: node.title.clone(),
63                tags: {
64                    let mut tags = node.tags.iter().cloned().collect::<Vec<_>>();
65                    tags.sort();
66                    tags
67                },
68                tag_presentation: Default::default(),
69                import_provenance: Vec::new(),
70                is_pinned: false,
71                images: node.images.clone(),
72                // Never written: a saved snapshot carries references only.
73                legacy_thumbnail_png: None,
74                legacy_thumbnail_width: 0,
75                legacy_thumbnail_height: 0,
76                legacy_favicon_rgba: None,
77                legacy_favicon_width: 0,
78                legacy_favicon_height: 0,
79                // Scroll / form draft left for the host's BrowserNodeState
80                // sidecar (boundary pass slice C); the snapshot now carries
81                // only the last-visited clock here. `session_state` itself
82                // stays for legacy readers and the one-time load migration.
83                session_state: Some(PersistedNodeSessionState {
84                    scroll_x: None,
85                    scroll_y: None,
86                    form_draft: None,
87                    last_visited_ms: None,
88                }),
89                address: match node.primary_address() {
90                    Address::Http(s) => PersistedAddress::Http(s.clone()),
91                    Address::File(s) => PersistedAddress::File(s.clone()),
92                    Address::Data(s) => PersistedAddress::Data(s.clone()),
93                    Address::Clip(s) => PersistedAddress::Clip(s.clone()),
94                    Address::Directory(s) => PersistedAddress::Directory(s.clone()),
95                    Address::Custom(s) => PersistedAddress::Custom(s.clone()),
96                },
97                // Written for backward compat: pre-Stage C.2 readers use this field.
98                url: node.primary_address().as_url_str().to_string(),
99                classifications: Vec::new(),
100                mime_hint: node.media_type.clone(),
101                frame_layout_hints: Vec::new(),
102                frame_split_offer_suppressed: false,
103                properties: Vec::new(),
104                derivations: Vec::new(),
105                body: node.body.clone(),
106                last_session_visited: 0,
107                nested: node.nested.as_ref().map(|log| log.as_str().to_string()),
108                content_hash: node.content.map(|hash| hash.to_hex()),
109            })
110            .collect();
111
112        // Edge slots are reused, so storage order is history; the snapshot is
113        // in the order of each edge's JSON bytes, so comparisons need no sort of
114        // their own. The statements inside an edge keep their exact order.
115        let mut edges: Vec<_> = self
116            .inner
117            .inner()
118            .edge_references()
119            .map(|edge| self.persisted_edge(edge.source(), edge.target(), edge.weight()))
120            .collect();
121        edges.sort_by_cached_key(|edge| {
122            serde_json::to_vec(edge).expect("persisted surface edge encodes")
123        });
124
125        let fields = self
126            .fields()
127            .map(|f| PersistedField {
128                id: f.id.as_uuid().to_string(),
129                name: f.name.clone(),
130                // The recursive AST rides as a JSON blob (see persistence_fields).
131                definition_json: serde_json::to_string(&f.definition).unwrap_or_default(),
132                extent: match &f.extent {
133                    FieldExtent::Global => PersistedFieldExtent::Global,
134                    FieldExtent::Region {
135                        min_x,
136                        min_y,
137                        max_x,
138                        max_y,
139                    } => PersistedFieldExtent::Region {
140                        min_x: *min_x,
141                        min_y: *min_y,
142                        max_x: *max_x,
143                        max_y: *max_y,
144                    },
145                    FieldExtent::AttachedToNode(id) => {
146                        PersistedFieldExtent::AttachedToNode(id.to_string())
147                    },
148                    FieldExtent::Polygon { points } => PersistedFieldExtent::Polygon {
149                        points: points.clone(),
150                    },
151                },
152                lifecycle: match f.lifecycle {
153                    FieldLifecycle::Active => PersistedFieldLifecycle::Active,
154                    FieldLifecycle::Retired => PersistedFieldLifecycle::Retired,
155                },
156            })
157            .collect();
158
159        let couplings = self
160            .couplings()
161            .map(|c| PersistedCoupling {
162                id: c.id.as_uuid().to_string(),
163                field_id: c.field.as_uuid().to_string(),
164                selector: match &c.selector {
165                    NodeSelector::All => PersistedNodeSelector::All,
166                    NodeSelector::Tagged(t) => PersistedNodeSelector::Tagged(t.clone()),
167                    NodeSelector::Kind(k) => PersistedNodeSelector::Kind(k.clone()),
168                    NodeSelector::NotTagged(t) => PersistedNodeSelector::NotTagged(t.clone()),
169                },
170                response: match &c.response {
171                    CouplingResponse::AttractToMin => PersistedCouplingResponse::AttractToMin,
172                    CouplingResponse::RepelFromMax => PersistedCouplingResponse::RepelFromMax,
173                    CouplingResponse::AlignVelocity => PersistedCouplingResponse::AlignVelocity,
174                    CouplingResponse::FlowAdvect => PersistedCouplingResponse::FlowAdvect,
175                    CouplingResponse::DampenInside { factor } => {
176                        PersistedCouplingResponse::DampenInside { factor: *factor }
177                    },
178                    CouplingResponse::ContainmentWall => PersistedCouplingResponse::ContainmentWall,
179                    CouplingResponse::Open { predicate } => PersistedCouplingResponse::Open {
180                        predicate: predicate.clone(),
181                    },
182                },
183                strength: c.strength,
184            })
185            .collect();
186
187        let resources = self
188            .resources
189            .nodes()
190            .filter_map(|(_, resource)| self.resource_record(resource.id()))
191            .collect();
192        let resource_pairs = self
193            .resources
194            .inner()
195            .edge_references()
196            .filter_map(|edge| {
197                let from = self.resources.node(edge.source())?.id();
198                let to = self.resources.node(edge.target())?.id();
199                Some((from, to))
200            })
201            .collect::<std::collections::BTreeSet<_>>();
202        let resource_edges = resource_pairs
203            .into_iter()
204            .flat_map(|(from, to)| self.persisted_resource_edges_between(from, to))
205            .collect();
206        let shown_resources = self
207            .shown_resources
208            .iter()
209            .map(|(surface_id, resource_id)| PersistedShownResource {
210                surface_id: surface_id.to_string(),
211                resource_id: resource_id.to_string(),
212            })
213            .collect();
214
215        GraphSnapshot {
216            assertion_schema: 1,
217            nodes,
218            edges,
219            import_records: self.import_records.clone(),
220            timestamp_secs,
221            fields,
222            couplings,
223            navigation: self.nav.clone(),
224            resources,
225            resource_edges,
226            shown_resources,
227        }
228    }
229}
230
231impl Graph {
232    /// One edge's relations in persisted form: the one place live relations
233    /// become a `PersistedEdge`, for snapshots and for undo's exact edge write.
234    pub(crate) fn persisted_edge(
235        &self,
236        from: NodeKey,
237        to: NodeKey,
238        payload: &EdgePayload,
239    ) -> PersistedEdge {
240        let from_node_id = self
241            .get_node(from)
242            .map(|n| n.id.to_string())
243            .unwrap_or_default();
244        let to_node_id = self
245            .get_node(to)
246            .map(|n| n.id.to_string())
247            .unwrap_or_default();
248        persisted_edge_with_ids(from_node_id, to_node_id, payload)
249    }
250
251    /// Every live Surface edge from `from` to `to`, in exact capture order.
252    /// Retains session arrangements that durable snapshots intentionally omit.
253    pub fn persisted_edges_between(&self, from: NodeKey, to: NodeKey) -> Vec<PersistedEdge> {
254        self.inner
255            .inner()
256            .edges_connecting(from, to)
257            .map(|edge| {
258                let mut persisted = self.persisted_edge(from, to, edge.weight());
259                // Pair captures/undo retain session arrangements too.
260                persisted.assertions = Some(
261                    edge.weight()
262                        .assertions()
263                        .iter()
264                        .map(persisted_assertion)
265                        .collect(),
266                );
267                persisted
268            })
269            .collect()
270    }
271}
272
273/// Encode a pair using explicit ids from either graph stratum.
274pub(crate) fn persisted_edge_for_ids(from: Uuid, to: Uuid, payload: &EdgePayload) -> PersistedEdge {
275    persisted_edge_with_ids(from.to_string(), to.to_string(), payload)
276}
277
278pub(crate) fn persisted_assertion(statement: &SemanticStatement) -> PersistedSemanticStatement {
279    PersistedSemanticStatement {
280        statement_id: statement.statement_id.clone(),
281        predicate: statement.predicate.clone(),
282        recognized_sub_kind: statement
283            .recognized_sub_kind
284            .map(persisted_semantic_sub_kind),
285        label: statement.label.clone(),
286        basis: statement.basis.clone(),
287        graph_scope: statement.graph_scope.clone(),
288        provenance_iri: statement.provenance_iri.clone(),
289        asserted_at_ms: statement.asserted_at_ms,
290        first_asserted_ms: statement.first_asserted_ms,
291        withdrawn: statement.withdrawn.clone(),
292    }
293}
294
295fn persisted_edge_with_ids(
296    from_node_id: String,
297    to_node_id: String,
298    payload: &EdgePayload,
299) -> PersistedEdge {
300    let assertions: Vec<_> = payload
301        .assertions()
302        .iter()
303        .filter(|statement| {
304            !matches!(statement.relation_kind(), RelationKind::Arrangement(kind)
305            if kind.durability() != RelationDurability::Durable)
306        })
307        .map(persisted_assertion)
308        .collect();
309    PersistedEdge {
310        from_node_id,
311        to_node_id,
312        families: payload
313            .families()
314            .into_iter()
315            .map(|family| match family {
316                EdgeFamily::Semantic => PersistedEdgeFamily::Semantic,
317                EdgeFamily::Traversal => PersistedEdgeFamily::Traversal,
318                EdgeFamily::Containment => PersistedEdgeFamily::Containment,
319                EdgeFamily::Arrangement => PersistedEdgeFamily::Arrangement,
320                EdgeFamily::Imported => PersistedEdgeFamily::Imported,
321                EdgeFamily::Provenance => PersistedEdgeFamily::Provenance,
322            })
323            .collect(),
324        semantic: None,
325        containment: None,
326        arrangement: None,
327        imported: None,
328        provenance: None,
329        assertions: Some(assertions),
330        traversal: payload
331            .traversal_data()
332            .map(|data| PersistedTraversalEdgeData {
333                traversals: data
334                    .traversals
335                    .iter()
336                    .map(|traversal| PersistedTraversalRecord {
337                        timestamp_ms: traversal.timestamp_ms,
338                        trigger: match traversal.trigger {
339                            NavigationTrigger::Unknown => PersistedNavigationTrigger::Unknown,
340                            NavigationTrigger::LinkClick => PersistedNavigationTrigger::LinkClick,
341                            NavigationTrigger::Back => PersistedNavigationTrigger::Back,
342                            NavigationTrigger::Forward => PersistedNavigationTrigger::Forward,
343                            NavigationTrigger::AddressBarEntry => {
344                                PersistedNavigationTrigger::AddressBarEntry
345                            },
346                            NavigationTrigger::PanePromotion => {
347                                PersistedNavigationTrigger::PanePromotion
348                            },
349                            NavigationTrigger::Programmatic => {
350                                PersistedNavigationTrigger::Programmatic
351                            },
352                            NavigationTrigger::Redirect => PersistedNavigationTrigger::Redirect,
353                            NavigationTrigger::ReopenSession => {
354                                PersistedNavigationTrigger::ReopenSession
355                            },
356                            NavigationTrigger::JumpAnchor => PersistedNavigationTrigger::JumpAnchor,
357                            NavigationTrigger::InPageSearchJump => {
358                                PersistedNavigationTrigger::InPageSearchJump
359                            },
360                            NavigationTrigger::ImportedHistory => {
361                                PersistedNavigationTrigger::ImportedHistory
362                            },
363                        },
364                    })
365                    .collect(),
366                metrics: PersistedTraversalMetrics {
367                    total_navigations: data.metrics.total_navigations,
368                    forward_navigations: data.metrics.forward_navigations,
369                    backward_navigations: data.metrics.backward_navigations,
370                    last_navigated_at: data.metrics.last_navigated_at,
371                },
372            }),
373    }
374}