Skip to main content

kernel/graph/snapshot/
from.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! `Graph::from_snapshot` — reconstruct the runtime graph from a
5//! persisted [`GraphSnapshot`].
6//!
7//! Extracted from `graph/snapshot.rs` per the 2026-05-11 kernel
8//! decomposition pass.
9
10use euclid::default::Point2D;
11use uuid::Uuid;
12
13use super::super::*;
14use crate::address::{address_from_url, detect_mime};
15use crate::persistence::{
16    GraphSnapshot, PersistedArrangementSubKind, PersistedContainmentSubKind,
17    PersistedCouplingResponse, PersistedFieldExtent, PersistedFieldLifecycle,
18    PersistedImportedSubKind, PersistedNavigationTrigger, PersistedNodeSelector,
19    PersistedProvenanceSubKind, PersistedSemanticSubKind,
20};
21
22fn semantic_sub_kind(sub_kind: PersistedSemanticSubKind) -> SemanticSubKind {
23    match sub_kind {
24        PersistedSemanticSubKind::Hyperlink => SemanticSubKind::Hyperlink,
25        PersistedSemanticSubKind::UserGrouped => SemanticSubKind::UserGrouped,
26        PersistedSemanticSubKind::AgentDerived => SemanticSubKind::AgentDerived,
27        PersistedSemanticSubKind::Cites => SemanticSubKind::Cites,
28        PersistedSemanticSubKind::Quotes => SemanticSubKind::Quotes,
29        PersistedSemanticSubKind::Summarizes => SemanticSubKind::Summarizes,
30        PersistedSemanticSubKind::Elaborates => SemanticSubKind::Elaborates,
31        PersistedSemanticSubKind::ExampleOf => SemanticSubKind::ExampleOf,
32        PersistedSemanticSubKind::Supports => SemanticSubKind::Supports,
33        PersistedSemanticSubKind::Contradicts => SemanticSubKind::Contradicts,
34        PersistedSemanticSubKind::Questions => SemanticSubKind::Questions,
35        PersistedSemanticSubKind::SameEntityAs => SemanticSubKind::SameEntityAs,
36        PersistedSemanticSubKind::DuplicateOf => SemanticSubKind::DuplicateOf,
37        PersistedSemanticSubKind::CanonicalMirrorOf => SemanticSubKind::CanonicalMirrorOf,
38        PersistedSemanticSubKind::DependsOn => SemanticSubKind::DependsOn,
39        PersistedSemanticSubKind::Blocks => SemanticSubKind::Blocks,
40        PersistedSemanticSubKind::NextStep => SemanticSubKind::NextStep,
41    }
42}
43
44impl Graph {
45    pub fn from_snapshot(snapshot: &GraphSnapshot) -> Self {
46        let mut graph = Graph::new();
47        // Restore the shared navigation history (one visit space, owner per node)
48        // before the node loop, so each node's restored current page reads from it.
49        graph.nav = snapshot.navigation.clone();
50
51        for pnode in &snapshot.nodes {
52            let Ok(node_id) = Uuid::parse_str(&pnode.node_id) else {
53                continue;
54            };
55            // Prefer the typed address field (Stage C.2+); fall back to the legacy
56            // `url` string field for snapshots written before Stage C.2.
57            let node_url = {
58                let from_address = pnode.address.as_url_str();
59                if from_address.is_empty() {
60                    pnode.url.clone()
61                } else {
62                    from_address.to_string()
63                }
64            };
65            // Positions are no longer graph truth; they live in the cartography
66            // sidecar (the Cartography projection's geometry). Seed at the origin and
67            // let the sidecar override on load. (Position gut.)
68            let key = graph.add_node_with_id(node_id, node_url, Point2D::new(0.0, 0.0));
69            if let Some(node) = graph.inner.node_mut(key) {
70                node.title = pnode.title.clone();
71                node.tags = pnode.tags.iter().cloned().collect();
72                // References only. Legacy inline bytes are externalized by the
73                // host before conversion (`pandect::image_store::
74                // migrate_legacy_images`), because hashing and blob storage
75                // are the store's job, not the kernel's. A snapshot that still
76                // carries them here has skipped that pass — see
77                // `GraphSnapshot::legacy_image_count`.
78                node.images = pnode.images.clone();
79                node.media_type = pnode.mime_hint.clone();
80                // address was already set by add_node_with_id from pnode.url; no re-derivation needed.
81                node.body = pnode.body.clone();
82                node.nested = pnode.nested.clone().map(codicil::LogId::new);
83            }
84            // One-time legacy-column import. Canonical saves put these records
85            // in `facets.json`; the old graph fields are written empty.
86            graph.set_node_facet(
87                key,
88                super::super::node_facets::PRESENTATION_TAGS,
89                &pnode.tag_presentation,
90            );
91            graph.set_node_facet(
92                key,
93                super::super::node_facets::PROVENANCE_IMPORT,
94                &pnode.import_provenance,
95            );
96            graph.set_node_facet(
97                key,
98                super::super::node_facets::SEMANTIC_CLASSIFICATIONS,
99                &pnode.classifications,
100            );
101            graph.set_node_facet(
102                key,
103                super::super::node_facets::SEMANTIC_PROPERTIES,
104                &pnode.properties,
105            );
106            graph.set_node_facet(
107                key,
108                super::super::node_facets::PROVENANCE_DERIVATIONS,
109                &pnode.derivations,
110            );
111            graph.set_node_facet(
112                key,
113                super::super::node_facets::ARRANGEMENT_PIN,
114                &pnode.is_pinned,
115            );
116            graph.set_node_facet(
117                key,
118                super::super::node_facets::ARRANGEMENT_FRAME_LAYOUT,
119                &pnode.frame_layout_hints,
120            );
121            graph.set_node_facet(
122                key,
123                super::super::node_facets::ARRANGEMENT_SPLIT_OFFER_SUPPRESSED,
124                &pnode.frame_split_offer_suppressed,
125            );
126            let last_visited_ms = pnode
127                .session_state
128                .as_ref()
129                .and_then(|session| session.last_visited_ms);
130            if let Some(last_visited_ms) = last_visited_ms {
131                graph.set_node_facet(
132                    key,
133                    super::super::node_facets::VISIT_HISTORY,
134                    &super::super::node_facets::VisitHistoryFacet {
135                        last_visited_ms: Some(last_visited_ms),
136                        last_session_visited: pnode.last_session_visited,
137                    },
138                );
139            } else if pnode.last_session_visited != 0 {
140                // Old snapshots could carry a session ordinal without an
141                // explicit visit timestamp. Preserve the creation-time visit
142                // installed by `add_node_with_id` while importing that ordinal.
143                graph.set_node_last_session_visited(key, pnode.last_session_visited);
144            }
145            // The node's restored current page comes from the shared nav history.
146            if let Some(current_url) = graph.nav.current_url(node_id)
147                && !current_url.is_empty()
148            {
149                let preserve_route_identity = graph.inner.node(key).is_some_and(|node| {
150                    node.primary_address().address_kind() == AddressKind::GraphshellClip
151                });
152                if !preserve_route_identity {
153                    // Recompute MIME hint and Primary address from the
154                    // restored URL. update_node_url then reindexes the
155                    // url_to_nodes map.
156                    if let Some(node) = graph.inner.node_mut(key) {
157                        node.media_type = detect_mime(&current_url, None);
158                        if let Some(primary) = node.addresses.first_mut() {
159                            *primary = address_from_url(&current_url);
160                        }
161                    }
162                    let _ = graph.update_node_url(key, current_url);
163                }
164            }
165        }
166
167        for pedge in &snapshot.edges {
168            let from_key = Uuid::parse_str(&pedge.from_node_id)
169                .ok()
170                .and_then(|id| graph.get_node_key_by_id(id));
171            let to_key = Uuid::parse_str(&pedge.to_node_id)
172                .ok()
173                .and_then(|id| graph.get_node_key_by_id(id));
174            if let (Some(from), Some(to)) = (from_key, to_key) {
175                if let Some(semantic) = &pedge.semantic {
176                    if !semantic.statements.is_empty() {
177                        let key = graph
178                            .find_edge_key(from, to)
179                            .unwrap_or_else(|| graph.inner.connect(from, to, EdgePayload::new()));
180                        if let Some(payload) = graph.inner.edge_mut(key) {
181                            for statement in &semantic.statements {
182                                let _ =
183                                    payload.push_persisted_semantic_statement(SemanticStatement {
184                                        statement_id: statement.statement_id.clone(),
185                                        predicate: statement.predicate.clone(),
186                                        recognized_sub_kind: statement
187                                            .recognized_sub_kind
188                                            .map(semantic_sub_kind),
189                                        label: statement.label.clone(),
190                                        graph_scope: statement.graph_scope.clone(),
191                                        provenance_iri: statement.provenance_iri.clone(),
192                                        asserted_at_ms: statement.asserted_at_ms,
193                                    });
194                            }
195                        }
196                    } else {
197                        for sub_kind in &semantic.sub_kinds {
198                            let assertion = EdgeAssertion::Semantic {
199                                sub_kind: semantic_sub_kind(sub_kind.clone()),
200                                label: semantic.label.clone(),
201                                decay_progress: semantic.agent_decay_progress,
202                            };
203                            let _ = graph.assert_relation(from, to, assertion);
204                        }
205                        // Restore the open predicate IRI. Create the edge when the
206                        // sub-kind loop above made none — a raw predicate-only
207                        // Semantic edge (linked-data ingest) has empty `sub_kinds`.
208                        if semantic.predicate.is_some() {
209                            let key = graph.find_edge_key(from, to).unwrap_or_else(|| {
210                                graph.inner.connect(from, to, EdgePayload::new())
211                            });
212                            if let Some(payload) = graph.inner.edge_mut(key) {
213                                payload.set_semantic_predicate(semantic.predicate.clone());
214                            }
215                        }
216                    }
217                }
218                if let Some(arrangement) = &pedge.arrangement {
219                    for sub_kind in &arrangement.sub_kinds {
220                        let assertion = match sub_kind {
221                            PersistedArrangementSubKind::FrameMember => {
222                                EdgeAssertion::Arrangement {
223                                    sub_kind: ArrangementSubKind::FrameMember,
224                                }
225                            }
226                            PersistedArrangementSubKind::TileGroup => EdgeAssertion::Arrangement {
227                                sub_kind: ArrangementSubKind::TileGroup,
228                            },
229                            PersistedArrangementSubKind::SplitPair => EdgeAssertion::Arrangement {
230                                sub_kind: ArrangementSubKind::SplitPair,
231                            },
232                            PersistedArrangementSubKind::TabNeighbor
233                            | PersistedArrangementSubKind::ActiveTab
234                            | PersistedArrangementSubKind::PinnedInFrame => continue,
235                        };
236                        let _ = graph.assert_relation(from, to, assertion);
237                    }
238                }
239                if let Some(containment) = &pedge.containment {
240                    for sub_kind in &containment.sub_kinds {
241                        let assertion = match sub_kind {
242                            PersistedContainmentSubKind::UrlPath => EdgeAssertion::Containment {
243                                sub_kind: ContainmentSubKind::UrlPath,
244                            },
245                            PersistedContainmentSubKind::Domain => EdgeAssertion::Containment {
246                                sub_kind: ContainmentSubKind::Domain,
247                            },
248                            _ => continue,
249                        };
250                        let _ = graph.assert_relation(from, to, assertion);
251                    }
252                }
253                if let Some(imported) = &pedge.imported {
254                    for sub_kind in &imported.sub_kinds {
255                        let assertion = match sub_kind {
256                            PersistedImportedSubKind::BookmarkFolder => EdgeAssertion::Imported {
257                                sub_kind: ImportedSubKind::BookmarkFolder,
258                            },
259                            PersistedImportedSubKind::HistoryImport => EdgeAssertion::Imported {
260                                sub_kind: ImportedSubKind::HistoryImport,
261                            },
262                            PersistedImportedSubKind::SessionImport => EdgeAssertion::Imported {
263                                sub_kind: ImportedSubKind::SessionImport,
264                            },
265                            PersistedImportedSubKind::RssMembership => EdgeAssertion::Imported {
266                                sub_kind: ImportedSubKind::RssMembership,
267                            },
268                            PersistedImportedSubKind::FileSystemImport => EdgeAssertion::Imported {
269                                sub_kind: ImportedSubKind::FileSystemImport,
270                            },
271                            PersistedImportedSubKind::ArchiveMembership => {
272                                EdgeAssertion::Imported {
273                                    sub_kind: ImportedSubKind::ArchiveMembership,
274                                }
275                            }
276                            PersistedImportedSubKind::SharedCollection => EdgeAssertion::Imported {
277                                sub_kind: ImportedSubKind::SharedCollection,
278                            },
279                        };
280                        let _ = graph.assert_relation(from, to, assertion);
281                    }
282                }
283                if let Some(provenance) = &pedge.provenance {
284                    for sub_kind in &provenance.sub_kinds {
285                        let assertion = match sub_kind {
286                            PersistedProvenanceSubKind::ClippedFrom => EdgeAssertion::Provenance {
287                                sub_kind: ProvenanceSubKind::ClippedFrom,
288                            },
289                            PersistedProvenanceSubKind::ExcerptedFrom => {
290                                EdgeAssertion::Provenance {
291                                    sub_kind: ProvenanceSubKind::ExcerptedFrom,
292                                }
293                            }
294                            PersistedProvenanceSubKind::SummarizedFrom => {
295                                EdgeAssertion::Provenance {
296                                    sub_kind: ProvenanceSubKind::SummarizedFrom,
297                                }
298                            }
299                            PersistedProvenanceSubKind::TranslatedFrom => {
300                                EdgeAssertion::Provenance {
301                                    sub_kind: ProvenanceSubKind::TranslatedFrom,
302                                }
303                            }
304                            PersistedProvenanceSubKind::RewrittenFrom => {
305                                EdgeAssertion::Provenance {
306                                    sub_kind: ProvenanceSubKind::RewrittenFrom,
307                                }
308                            }
309                            PersistedProvenanceSubKind::GeneratedFrom => {
310                                EdgeAssertion::Provenance {
311                                    sub_kind: ProvenanceSubKind::GeneratedFrom,
312                                }
313                            }
314                            PersistedProvenanceSubKind::ExtractedFrom => {
315                                EdgeAssertion::Provenance {
316                                    sub_kind: ProvenanceSubKind::ExtractedFrom,
317                                }
318                            }
319                            PersistedProvenanceSubKind::ImportedFromSource => {
320                                EdgeAssertion::Provenance {
321                                    sub_kind: ProvenanceSubKind::ImportedFromSource,
322                                }
323                            }
324                            PersistedProvenanceSubKind::CopiedFrom => EdgeAssertion::Provenance {
325                                sub_kind: ProvenanceSubKind::CopiedFrom,
326                            },
327                        };
328                        let _ = graph.assert_relation(from, to, assertion);
329                    }
330                }
331                if let Some(traversal) = &pedge.traversal {
332                    // Ensure a payload exists for from→to, then
333                    // overwrite its traversal sidecar with the persisted
334                    // events + metrics.
335                    let edge_key = graph
336                        .find_edge_key(from, to)
337                        .unwrap_or_else(|| graph.inner.connect(from, to, EdgePayload::new()));
338                    if let Some(payload) = graph.inner.edge_mut(edge_key) {
339                        let data = payload.traversal.get_or_insert_with(TraversalData::default);
340                        data.traversals = traversal
341                            .traversals
342                            .iter()
343                            .map(|record| Traversal {
344                                timestamp_ms: record.timestamp_ms,
345                                trigger: match record.trigger {
346                                    PersistedNavigationTrigger::Unknown => {
347                                        NavigationTrigger::Unknown
348                                    }
349                                    PersistedNavigationTrigger::LinkClick => {
350                                        NavigationTrigger::LinkClick
351                                    }
352                                    PersistedNavigationTrigger::Back => NavigationTrigger::Back,
353                                    PersistedNavigationTrigger::Forward => {
354                                        NavigationTrigger::Forward
355                                    }
356                                    PersistedNavigationTrigger::AddressBarEntry => {
357                                        NavigationTrigger::AddressBarEntry
358                                    }
359                                    PersistedNavigationTrigger::PanePromotion => {
360                                        NavigationTrigger::PanePromotion
361                                    }
362                                    PersistedNavigationTrigger::Programmatic => {
363                                        NavigationTrigger::Programmatic
364                                    }
365                                    PersistedNavigationTrigger::Redirect => {
366                                        NavigationTrigger::Redirect
367                                    }
368                                    PersistedNavigationTrigger::ReopenSession => {
369                                        NavigationTrigger::ReopenSession
370                                    }
371                                    PersistedNavigationTrigger::JumpAnchor => {
372                                        NavigationTrigger::JumpAnchor
373                                    }
374                                    PersistedNavigationTrigger::InPageSearchJump => {
375                                        NavigationTrigger::InPageSearchJump
376                                    }
377                                    PersistedNavigationTrigger::ImportedHistory => {
378                                        NavigationTrigger::ImportedHistory
379                                    }
380                                },
381                            })
382                            .collect();
383                        data.metrics = EdgeMetrics {
384                            total_navigations: traversal.metrics.total_navigations,
385                            forward_navigations: traversal.metrics.forward_navigations,
386                            backward_navigations: traversal.metrics.backward_navigations,
387                            last_navigated_at: traversal.metrics.last_navigated_at,
388                        };
389                    }
390                }
391            }
392        }
393
394        // Field layer (field-system Phase 2). Malformed ids / definitions skip the
395        // entry rather than failing the whole load, matching the node/edge loops.
396        for pfield in &snapshot.fields {
397            let Ok(id) = Uuid::parse_str(&pfield.id) else {
398                continue;
399            };
400            let Ok(definition) = serde_json::from_str::<FieldDefinition>(&pfield.definition_json)
401            else {
402                continue;
403            };
404            let extent = match &pfield.extent {
405                PersistedFieldExtent::Global => FieldExtent::Global,
406                PersistedFieldExtent::Region {
407                    min_x,
408                    min_y,
409                    max_x,
410                    max_y,
411                } => FieldExtent::Region {
412                    min_x: *min_x,
413                    min_y: *min_y,
414                    max_x: *max_x,
415                    max_y: *max_y,
416                },
417                PersistedFieldExtent::AttachedToNode(s) => match Uuid::parse_str(s) {
418                    Ok(node_id) => FieldExtent::AttachedToNode(node_id),
419                    Err(_) => FieldExtent::Global,
420                },
421                PersistedFieldExtent::Polygon { points } => FieldExtent::Polygon {
422                    points: points.clone(),
423                },
424            };
425            let mut field = Field::new(FieldId::from_uuid(id), definition).with_extent(extent);
426            if let Some(name) = &pfield.name {
427                field = field.with_name(name.clone());
428            }
429            field.lifecycle = match pfield.lifecycle {
430                PersistedFieldLifecycle::Active => FieldLifecycle::Active,
431                PersistedFieldLifecycle::Retired => FieldLifecycle::Retired,
432            };
433            graph.add_field(field);
434        }
435
436        for pcoupling in &snapshot.couplings {
437            let Ok(cid) = Uuid::parse_str(&pcoupling.id) else {
438                continue;
439            };
440            let Ok(fid) = Uuid::parse_str(&pcoupling.field_id) else {
441                continue;
442            };
443            let selector = match &pcoupling.selector {
444                PersistedNodeSelector::All => NodeSelector::All,
445                PersistedNodeSelector::Tagged(t) => NodeSelector::Tagged(t.clone()),
446                PersistedNodeSelector::Kind(k) => NodeSelector::Kind(k.clone()),
447                PersistedNodeSelector::NotTagged(t) => NodeSelector::NotTagged(t.clone()),
448            };
449            let response = match &pcoupling.response {
450                PersistedCouplingResponse::AttractToMin => CouplingResponse::AttractToMin,
451                PersistedCouplingResponse::RepelFromMax => CouplingResponse::RepelFromMax,
452                PersistedCouplingResponse::AlignVelocity => CouplingResponse::AlignVelocity,
453                PersistedCouplingResponse::FlowAdvect => CouplingResponse::FlowAdvect,
454                PersistedCouplingResponse::DampenInside { factor } => {
455                    CouplingResponse::DampenInside { factor: *factor }
456                }
457                PersistedCouplingResponse::ContainmentWall => CouplingResponse::ContainmentWall,
458                PersistedCouplingResponse::Open { predicate } => CouplingResponse::Open {
459                    predicate: predicate.clone(),
460                },
461            };
462            graph.add_coupling(Coupling::new(
463                CouplingId::from_uuid(cid),
464                FieldId::from_uuid(fid),
465                selector,
466                response,
467                pcoupling.strength,
468            ));
469        }
470
471        if snapshot.import_records.is_empty() {
472            graph.rebuild_import_records_from_node_provenance(snapshot.timestamp_secs);
473        } else {
474            graph.import_records = snapshot.import_records.clone();
475            normalize_import_records(&mut graph.import_records);
476            graph.sync_node_import_provenance_from_records();
477        }
478
479        graph.rebuild_derived_containment_relations();
480
481        graph
482    }
483}