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                node.content = pnode
84                    .content_hash
85                    .as_deref()
86                    .and_then(muniment::Hash::from_hex);
87                if node.content.is_some() {
88                    node.body = None;
89                }
90            }
91            // One-time legacy-column import. Canonical saves put these records
92            // in `facets.json`; the old graph fields are written empty.
93            graph.set_node_facet(
94                key,
95                super::super::node_facets::PRESENTATION_TAGS,
96                &pnode.tag_presentation,
97            );
98            graph.set_node_facet(
99                key,
100                super::super::node_facets::PROVENANCE_IMPORT,
101                &pnode.import_provenance,
102            );
103            graph.set_node_facet(
104                key,
105                super::super::node_facets::SEMANTIC_CLASSIFICATIONS,
106                &pnode.classifications,
107            );
108            graph.set_node_facet(
109                key,
110                super::super::node_facets::SEMANTIC_PROPERTIES,
111                &pnode.properties,
112            );
113            graph.set_node_facet(
114                key,
115                super::super::node_facets::PROVENANCE_DERIVATIONS,
116                &pnode.derivations,
117            );
118            graph.set_node_facet(
119                key,
120                super::super::node_facets::ARRANGEMENT_PIN,
121                &pnode.is_pinned,
122            );
123            graph.set_node_facet(
124                key,
125                super::super::node_facets::ARRANGEMENT_FRAME_LAYOUT,
126                &pnode.frame_layout_hints,
127            );
128            graph.set_node_facet(
129                key,
130                super::super::node_facets::ARRANGEMENT_SPLIT_OFFER_SUPPRESSED,
131                &pnode.frame_split_offer_suppressed,
132            );
133            let last_visited_ms = pnode
134                .session_state
135                .as_ref()
136                .and_then(|session| session.last_visited_ms);
137            if let Some(last_visited_ms) = last_visited_ms {
138                graph.set_node_facet(
139                    key,
140                    super::super::node_facets::VISIT_HISTORY,
141                    &super::super::node_facets::VisitHistoryFacet {
142                        last_visited_ms: Some(last_visited_ms),
143                        last_session_visited: pnode.last_session_visited,
144                    },
145                );
146            } else if pnode.last_session_visited != 0 {
147                // Old snapshots could carry a session ordinal without an
148                // explicit visit timestamp. Preserve the creation-time visit
149                // installed by `add_node_with_id` while importing that ordinal.
150                graph.set_node_last_session_visited(key, pnode.last_session_visited);
151            }
152            // The node's restored current page comes from the shared nav history.
153            if let Some(current_url) = graph.nav.current_url(node_id)
154                && !current_url.is_empty()
155            {
156                let preserve_route_identity = graph.inner.node(key).is_some_and(|node| {
157                    node.primary_address().address_kind() == AddressKind::GraphshellClip
158                });
159                if !preserve_route_identity {
160                    // Recompute MIME hint and Primary address from the
161                    // restored URL. update_node_url then reindexes the
162                    // url_to_nodes map.
163                    if let Some(node) = graph.inner.node_mut(key) {
164                        node.media_type = detect_mime(&current_url, None);
165                        if let Some(primary) = node.addresses.first_mut() {
166                            *primary = address_from_url(&current_url);
167                        }
168                    }
169                    let _ = graph.update_node_url(key, current_url);
170                }
171            }
172        }
173
174        for pedge in &snapshot.edges {
175            let from_key = Uuid::parse_str(&pedge.from_node_id)
176                .ok()
177                .and_then(|id| graph.get_node_key_by_id(id));
178            let to_key = Uuid::parse_str(&pedge.to_node_id)
179                .ok()
180                .and_then(|id| graph.get_node_key_by_id(id));
181            if let (Some(from), Some(to)) = (from_key, to_key) {
182                if let Some(semantic) = &pedge.semantic {
183                    if !semantic.statements.is_empty() {
184                        let key = graph
185                            .find_edge_key(from, to)
186                            .unwrap_or_else(|| graph.inner.connect(from, to, EdgePayload::new()));
187                        if let Some(payload) = graph.inner.edge_mut(key) {
188                            for statement in &semantic.statements {
189                                let _ =
190                                    payload.push_persisted_semantic_statement(SemanticStatement {
191                                        statement_id: statement.statement_id.clone(),
192                                        predicate: statement.predicate.clone(),
193                                        recognized_sub_kind: statement
194                                            .recognized_sub_kind
195                                            .map(semantic_sub_kind),
196                                        label: statement.label.clone(),
197                                        graph_scope: statement.graph_scope.clone(),
198                                        provenance_iri: statement.provenance_iri.clone(),
199                                        asserted_at_ms: statement.asserted_at_ms,
200                                    });
201                            }
202                        }
203                    } else {
204                        for sub_kind in &semantic.sub_kinds {
205                            let assertion = EdgeAssertion::Semantic {
206                                sub_kind: semantic_sub_kind(sub_kind.clone()),
207                                label: semantic.label.clone(),
208                                decay_progress: semantic.agent_decay_progress,
209                            };
210                            let _ = graph.assert_relation(from, to, assertion);
211                        }
212                        // Restore the open predicate IRI. Create the edge when the
213                        // sub-kind loop above made none — a raw predicate-only
214                        // Semantic edge (linked-data ingest) has empty `sub_kinds`.
215                        if semantic.predicate.is_some() {
216                            let key = graph.find_edge_key(from, to).unwrap_or_else(|| {
217                                graph.inner.connect(from, to, EdgePayload::new())
218                            });
219                            if let Some(payload) = graph.inner.edge_mut(key) {
220                                payload.set_semantic_predicate(semantic.predicate.clone());
221                            }
222                        }
223                    }
224                }
225                if let Some(arrangement) = &pedge.arrangement {
226                    for sub_kind in &arrangement.sub_kinds {
227                        let assertion = match sub_kind {
228                            PersistedArrangementSubKind::FrameMember => {
229                                EdgeAssertion::Arrangement {
230                                    sub_kind: ArrangementSubKind::FrameMember,
231                                }
232                            }
233                            PersistedArrangementSubKind::TileGroup => EdgeAssertion::Arrangement {
234                                sub_kind: ArrangementSubKind::TileGroup,
235                            },
236                            PersistedArrangementSubKind::SplitPair => EdgeAssertion::Arrangement {
237                                sub_kind: ArrangementSubKind::SplitPair,
238                            },
239                            PersistedArrangementSubKind::TabNeighbor
240                            | PersistedArrangementSubKind::ActiveTab
241                            | PersistedArrangementSubKind::PinnedInFrame => continue,
242                        };
243                        let _ = graph.assert_relation(from, to, assertion);
244                    }
245                }
246                if let Some(containment) = &pedge.containment {
247                    for sub_kind in &containment.sub_kinds {
248                        let assertion = match sub_kind {
249                            PersistedContainmentSubKind::UrlPath => EdgeAssertion::Containment {
250                                sub_kind: ContainmentSubKind::UrlPath,
251                            },
252                            PersistedContainmentSubKind::Domain => EdgeAssertion::Containment {
253                                sub_kind: ContainmentSubKind::Domain,
254                            },
255                            _ => continue,
256                        };
257                        let _ = graph.assert_relation(from, to, assertion);
258                    }
259                }
260                if let Some(imported) = &pedge.imported {
261                    for sub_kind in &imported.sub_kinds {
262                        let assertion = match sub_kind {
263                            PersistedImportedSubKind::BookmarkFolder => EdgeAssertion::Imported {
264                                sub_kind: ImportedSubKind::BookmarkFolder,
265                            },
266                            PersistedImportedSubKind::HistoryImport => EdgeAssertion::Imported {
267                                sub_kind: ImportedSubKind::HistoryImport,
268                            },
269                            PersistedImportedSubKind::SessionImport => EdgeAssertion::Imported {
270                                sub_kind: ImportedSubKind::SessionImport,
271                            },
272                            PersistedImportedSubKind::RssMembership => EdgeAssertion::Imported {
273                                sub_kind: ImportedSubKind::RssMembership,
274                            },
275                            PersistedImportedSubKind::FileSystemImport => EdgeAssertion::Imported {
276                                sub_kind: ImportedSubKind::FileSystemImport,
277                            },
278                            PersistedImportedSubKind::ArchiveMembership => {
279                                EdgeAssertion::Imported {
280                                    sub_kind: ImportedSubKind::ArchiveMembership,
281                                }
282                            }
283                            PersistedImportedSubKind::SharedCollection => EdgeAssertion::Imported {
284                                sub_kind: ImportedSubKind::SharedCollection,
285                            },
286                        };
287                        let _ = graph.assert_relation(from, to, assertion);
288                    }
289                }
290                if let Some(provenance) = &pedge.provenance {
291                    for sub_kind in &provenance.sub_kinds {
292                        let assertion = match sub_kind {
293                            PersistedProvenanceSubKind::ClippedFrom => EdgeAssertion::Provenance {
294                                sub_kind: ProvenanceSubKind::ClippedFrom,
295                            },
296                            PersistedProvenanceSubKind::ExcerptedFrom => {
297                                EdgeAssertion::Provenance {
298                                    sub_kind: ProvenanceSubKind::ExcerptedFrom,
299                                }
300                            }
301                            PersistedProvenanceSubKind::SummarizedFrom => {
302                                EdgeAssertion::Provenance {
303                                    sub_kind: ProvenanceSubKind::SummarizedFrom,
304                                }
305                            }
306                            PersistedProvenanceSubKind::TranslatedFrom => {
307                                EdgeAssertion::Provenance {
308                                    sub_kind: ProvenanceSubKind::TranslatedFrom,
309                                }
310                            }
311                            PersistedProvenanceSubKind::RewrittenFrom => {
312                                EdgeAssertion::Provenance {
313                                    sub_kind: ProvenanceSubKind::RewrittenFrom,
314                                }
315                            }
316                            PersistedProvenanceSubKind::GeneratedFrom => {
317                                EdgeAssertion::Provenance {
318                                    sub_kind: ProvenanceSubKind::GeneratedFrom,
319                                }
320                            }
321                            PersistedProvenanceSubKind::ExtractedFrom => {
322                                EdgeAssertion::Provenance {
323                                    sub_kind: ProvenanceSubKind::ExtractedFrom,
324                                }
325                            }
326                            PersistedProvenanceSubKind::ImportedFromSource => {
327                                EdgeAssertion::Provenance {
328                                    sub_kind: ProvenanceSubKind::ImportedFromSource,
329                                }
330                            }
331                            PersistedProvenanceSubKind::CopiedFrom => EdgeAssertion::Provenance {
332                                sub_kind: ProvenanceSubKind::CopiedFrom,
333                            },
334                        };
335                        let _ = graph.assert_relation(from, to, assertion);
336                    }
337                }
338                if let Some(traversal) = &pedge.traversal {
339                    // Ensure a payload exists for from→to, then
340                    // overwrite its traversal sidecar with the persisted
341                    // events + metrics.
342                    let edge_key = graph
343                        .find_edge_key(from, to)
344                        .unwrap_or_else(|| graph.inner.connect(from, to, EdgePayload::new()));
345                    if let Some(payload) = graph.inner.edge_mut(edge_key) {
346                        let data = payload.traversal.get_or_insert_with(TraversalData::default);
347                        data.traversals = traversal
348                            .traversals
349                            .iter()
350                            .map(|record| Traversal {
351                                timestamp_ms: record.timestamp_ms,
352                                trigger: match record.trigger {
353                                    PersistedNavigationTrigger::Unknown => {
354                                        NavigationTrigger::Unknown
355                                    }
356                                    PersistedNavigationTrigger::LinkClick => {
357                                        NavigationTrigger::LinkClick
358                                    }
359                                    PersistedNavigationTrigger::Back => NavigationTrigger::Back,
360                                    PersistedNavigationTrigger::Forward => {
361                                        NavigationTrigger::Forward
362                                    }
363                                    PersistedNavigationTrigger::AddressBarEntry => {
364                                        NavigationTrigger::AddressBarEntry
365                                    }
366                                    PersistedNavigationTrigger::PanePromotion => {
367                                        NavigationTrigger::PanePromotion
368                                    }
369                                    PersistedNavigationTrigger::Programmatic => {
370                                        NavigationTrigger::Programmatic
371                                    }
372                                    PersistedNavigationTrigger::Redirect => {
373                                        NavigationTrigger::Redirect
374                                    }
375                                    PersistedNavigationTrigger::ReopenSession => {
376                                        NavigationTrigger::ReopenSession
377                                    }
378                                    PersistedNavigationTrigger::JumpAnchor => {
379                                        NavigationTrigger::JumpAnchor
380                                    }
381                                    PersistedNavigationTrigger::InPageSearchJump => {
382                                        NavigationTrigger::InPageSearchJump
383                                    }
384                                    PersistedNavigationTrigger::ImportedHistory => {
385                                        NavigationTrigger::ImportedHistory
386                                    }
387                                },
388                            })
389                            .collect();
390                        data.metrics = EdgeMetrics {
391                            total_navigations: traversal.metrics.total_navigations,
392                            forward_navigations: traversal.metrics.forward_navigations,
393                            backward_navigations: traversal.metrics.backward_navigations,
394                            last_navigated_at: traversal.metrics.last_navigated_at,
395                        };
396                    }
397                }
398            }
399        }
400
401        // Field layer (field-system Phase 2). Malformed ids / definitions skip the
402        // entry rather than failing the whole load, matching the node/edge loops.
403        for pfield in &snapshot.fields {
404            let Ok(id) = Uuid::parse_str(&pfield.id) else {
405                continue;
406            };
407            let Ok(definition) = serde_json::from_str::<FieldDefinition>(&pfield.definition_json)
408            else {
409                continue;
410            };
411            let extent = match &pfield.extent {
412                PersistedFieldExtent::Global => FieldExtent::Global,
413                PersistedFieldExtent::Region {
414                    min_x,
415                    min_y,
416                    max_x,
417                    max_y,
418                } => FieldExtent::Region {
419                    min_x: *min_x,
420                    min_y: *min_y,
421                    max_x: *max_x,
422                    max_y: *max_y,
423                },
424                PersistedFieldExtent::AttachedToNode(s) => match Uuid::parse_str(s) {
425                    Ok(node_id) => FieldExtent::AttachedToNode(node_id),
426                    Err(_) => FieldExtent::Global,
427                },
428                PersistedFieldExtent::Polygon { points } => FieldExtent::Polygon {
429                    points: points.clone(),
430                },
431            };
432            let mut field = Field::new(FieldId::from_uuid(id), definition).with_extent(extent);
433            if let Some(name) = &pfield.name {
434                field = field.with_name(name.clone());
435            }
436            field.lifecycle = match pfield.lifecycle {
437                PersistedFieldLifecycle::Active => FieldLifecycle::Active,
438                PersistedFieldLifecycle::Retired => FieldLifecycle::Retired,
439            };
440            graph.add_field(field);
441        }
442
443        for pcoupling in &snapshot.couplings {
444            let Ok(cid) = Uuid::parse_str(&pcoupling.id) else {
445                continue;
446            };
447            let Ok(fid) = Uuid::parse_str(&pcoupling.field_id) else {
448                continue;
449            };
450            let selector = match &pcoupling.selector {
451                PersistedNodeSelector::All => NodeSelector::All,
452                PersistedNodeSelector::Tagged(t) => NodeSelector::Tagged(t.clone()),
453                PersistedNodeSelector::Kind(k) => NodeSelector::Kind(k.clone()),
454                PersistedNodeSelector::NotTagged(t) => NodeSelector::NotTagged(t.clone()),
455            };
456            let response = match &pcoupling.response {
457                PersistedCouplingResponse::AttractToMin => CouplingResponse::AttractToMin,
458                PersistedCouplingResponse::RepelFromMax => CouplingResponse::RepelFromMax,
459                PersistedCouplingResponse::AlignVelocity => CouplingResponse::AlignVelocity,
460                PersistedCouplingResponse::FlowAdvect => CouplingResponse::FlowAdvect,
461                PersistedCouplingResponse::DampenInside { factor } => {
462                    CouplingResponse::DampenInside { factor: *factor }
463                }
464                PersistedCouplingResponse::ContainmentWall => CouplingResponse::ContainmentWall,
465                PersistedCouplingResponse::Open { predicate } => CouplingResponse::Open {
466                    predicate: predicate.clone(),
467                },
468            };
469            graph.add_coupling(Coupling::new(
470                CouplingId::from_uuid(cid),
471                FieldId::from_uuid(fid),
472                selector,
473                response,
474                pcoupling.strength,
475            ));
476        }
477
478        if snapshot.import_records.is_empty() {
479            graph.rebuild_import_records_from_node_provenance(snapshot.timestamp_secs);
480        } else {
481            graph.import_records = snapshot.import_records.clone();
482            normalize_import_records(&mut graph.import_records);
483            graph.sync_node_import_provenance_from_records();
484        }
485
486        graph.rebuild_derived_containment_relations();
487
488        graph
489    }
490}