mere-kernel 0.0.3

Portable identity, authority, and mutation kernel for the Mere browser. Renamed from graphshell-core.
Documentation
// Copyright 2026 Mark Alan Boykin
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0

//! `Graph::to_snapshot` — serialize the runtime graph into a
//! [`GraphSnapshot`] for persistence.
//!
//! Extracted from `graph/snapshot.rs` per the 2026-05-11 kernel
//! decomposition pass (the original file was 724 LOC).

use petgraph::visit::EdgeRef;

use super::super::*;
use crate::persistence::{
    GraphSnapshot, PersistedAddress, PersistedCoupling, PersistedCouplingResponse, PersistedEdge,
    PersistedEdgeFamily, PersistedField, PersistedFieldExtent, PersistedFieldLifecycle,
    PersistedNavigationTrigger, PersistedNode, PersistedNodeSelector, PersistedNodeSessionState,
    PersistedSemanticStatement, PersistedSemanticSubKind, PersistedShownResource,
    PersistedTraversalEdgeData, PersistedTraversalMetrics, PersistedTraversalRecord,
};
fn persisted_semantic_sub_kind(sub_kind: SemanticSubKind) -> PersistedSemanticSubKind {
    match sub_kind {
        SemanticSubKind::Hyperlink => PersistedSemanticSubKind::Hyperlink,
        SemanticSubKind::UserGrouped => PersistedSemanticSubKind::UserGrouped,
        SemanticSubKind::AgentDerived => PersistedSemanticSubKind::AgentDerived,
        SemanticSubKind::Cites => PersistedSemanticSubKind::Cites,
        SemanticSubKind::Quotes => PersistedSemanticSubKind::Quotes,
        SemanticSubKind::Summarizes => PersistedSemanticSubKind::Summarizes,
        SemanticSubKind::Elaborates => PersistedSemanticSubKind::Elaborates,
        SemanticSubKind::ExampleOf => PersistedSemanticSubKind::ExampleOf,
        SemanticSubKind::Supports => PersistedSemanticSubKind::Supports,
        SemanticSubKind::Contradicts => PersistedSemanticSubKind::Contradicts,
        SemanticSubKind::Questions => PersistedSemanticSubKind::Questions,
        SemanticSubKind::SameEntityAs => PersistedSemanticSubKind::SameEntityAs,
        SemanticSubKind::DuplicateOf => PersistedSemanticSubKind::DuplicateOf,
        SemanticSubKind::CanonicalMirrorOf => PersistedSemanticSubKind::CanonicalMirrorOf,
        SemanticSubKind::DependsOn => PersistedSemanticSubKind::DependsOn,
        SemanticSubKind::Blocks => PersistedSemanticSubKind::Blocks,
        SemanticSubKind::NextStep => PersistedSemanticSubKind::NextStep,
    }
}

impl Graph {
    /// The graph's snapshot, dated now by the wall clock.
    pub fn to_snapshot(&self) -> GraphSnapshot {
        self.to_snapshot_at(crate::time::unix_epoch_seconds())
    }

    /// The graph's snapshot dated `timestamp_secs`, reading no clock: two
    /// snapshots of one graph at one date are equal whenever they are taken
    /// (reservoir plan ruling 47).
    pub fn to_snapshot_at(&self, timestamp_secs: u64) -> GraphSnapshot {
        let nodes = self
            .nodes()
            .map(|(_, node)| PersistedNode {
                node_id: node.id.to_string(),
                // Legacy wire field only. Hostnames are derived from the
                // Container's primary address and are never stored anew.
                cached_host: None,
                title: node.title.clone(),
                tags: {
                    let mut tags = node.tags.iter().cloned().collect::<Vec<_>>();
                    tags.sort();
                    tags
                },
                tag_presentation: Default::default(),
                import_provenance: Vec::new(),
                is_pinned: false,
                images: node.images.clone(),
                // Never written: a saved snapshot carries references only.
                legacy_thumbnail_png: None,
                legacy_thumbnail_width: 0,
                legacy_thumbnail_height: 0,
                legacy_favicon_rgba: None,
                legacy_favicon_width: 0,
                legacy_favicon_height: 0,
                // Scroll / form draft left for the host's BrowserNodeState
                // sidecar (boundary pass slice C); the snapshot now carries
                // only the last-visited clock here. `session_state` itself
                // stays for legacy readers and the one-time load migration.
                session_state: Some(PersistedNodeSessionState {
                    scroll_x: None,
                    scroll_y: None,
                    form_draft: None,
                    last_visited_ms: None,
                }),
                address: match node.primary_address() {
                    Address::Http(s) => PersistedAddress::Http(s.clone()),
                    Address::File(s) => PersistedAddress::File(s.clone()),
                    Address::Data(s) => PersistedAddress::Data(s.clone()),
                    Address::Clip(s) => PersistedAddress::Clip(s.clone()),
                    Address::Directory(s) => PersistedAddress::Directory(s.clone()),
                    Address::Custom(s) => PersistedAddress::Custom(s.clone()),
                },
                // Written for backward compat: pre-Stage C.2 readers use this field.
                url: node.primary_address().as_url_str().to_string(),
                classifications: Vec::new(),
                mime_hint: node.media_type.clone(),
                frame_layout_hints: Vec::new(),
                frame_split_offer_suppressed: false,
                properties: Vec::new(),
                derivations: Vec::new(),
                body: node.body.clone(),
                last_session_visited: 0,
                nested: node.nested.as_ref().map(|log| log.as_str().to_string()),
                content_hash: node.content.map(|hash| hash.to_hex()),
            })
            .collect();

        // Edge slots are reused, so storage order is history; the snapshot is
        // in the order of each edge's JSON bytes, so comparisons need no sort of
        // their own. The statements inside an edge keep their exact order.
        let mut edges: Vec<_> = self
            .inner
            .inner()
            .edge_references()
            .map(|edge| self.persisted_edge(edge.source(), edge.target(), edge.weight()))
            .collect();
        edges.sort_by_cached_key(|edge| {
            serde_json::to_vec(edge).expect("persisted surface edge encodes")
        });

        let fields = self
            .fields()
            .map(|f| PersistedField {
                id: f.id.as_uuid().to_string(),
                name: f.name.clone(),
                // The recursive AST rides as a JSON blob (see persistence_fields).
                definition_json: serde_json::to_string(&f.definition).unwrap_or_default(),
                extent: match &f.extent {
                    FieldExtent::Global => PersistedFieldExtent::Global,
                    FieldExtent::Region {
                        min_x,
                        min_y,
                        max_x,
                        max_y,
                    } => PersistedFieldExtent::Region {
                        min_x: *min_x,
                        min_y: *min_y,
                        max_x: *max_x,
                        max_y: *max_y,
                    },
                    FieldExtent::AttachedToNode(id) => {
                        PersistedFieldExtent::AttachedToNode(id.to_string())
                    },
                    FieldExtent::Polygon { points } => PersistedFieldExtent::Polygon {
                        points: points.clone(),
                    },
                },
                lifecycle: match f.lifecycle {
                    FieldLifecycle::Active => PersistedFieldLifecycle::Active,
                    FieldLifecycle::Retired => PersistedFieldLifecycle::Retired,
                },
            })
            .collect();

        let couplings = self
            .couplings()
            .map(|c| PersistedCoupling {
                id: c.id.as_uuid().to_string(),
                field_id: c.field.as_uuid().to_string(),
                selector: match &c.selector {
                    NodeSelector::All => PersistedNodeSelector::All,
                    NodeSelector::Tagged(t) => PersistedNodeSelector::Tagged(t.clone()),
                    NodeSelector::Kind(k) => PersistedNodeSelector::Kind(k.clone()),
                    NodeSelector::NotTagged(t) => PersistedNodeSelector::NotTagged(t.clone()),
                },
                response: match &c.response {
                    CouplingResponse::AttractToMin => PersistedCouplingResponse::AttractToMin,
                    CouplingResponse::RepelFromMax => PersistedCouplingResponse::RepelFromMax,
                    CouplingResponse::AlignVelocity => PersistedCouplingResponse::AlignVelocity,
                    CouplingResponse::FlowAdvect => PersistedCouplingResponse::FlowAdvect,
                    CouplingResponse::DampenInside { factor } => {
                        PersistedCouplingResponse::DampenInside { factor: *factor }
                    },
                    CouplingResponse::ContainmentWall => PersistedCouplingResponse::ContainmentWall,
                    CouplingResponse::Open { predicate } => PersistedCouplingResponse::Open {
                        predicate: predicate.clone(),
                    },
                },
                strength: c.strength,
            })
            .collect();

        let resources = self
            .resources
            .nodes()
            .filter_map(|(_, resource)| self.resource_record(resource.id()))
            .collect();
        let resource_pairs = self
            .resources
            .inner()
            .edge_references()
            .filter_map(|edge| {
                let from = self.resources.node(edge.source())?.id();
                let to = self.resources.node(edge.target())?.id();
                Some((from, to))
            })
            .collect::<std::collections::BTreeSet<_>>();
        let resource_edges = resource_pairs
            .into_iter()
            .flat_map(|(from, to)| self.persisted_resource_edges_between(from, to))
            .collect();
        let shown_resources = self
            .shown_resources
            .iter()
            .map(|(surface_id, resource_id)| PersistedShownResource {
                surface_id: surface_id.to_string(),
                resource_id: resource_id.to_string(),
            })
            .collect();

        GraphSnapshot {
            assertion_schema: 1,
            nodes,
            edges,
            import_records: self.import_records.clone(),
            timestamp_secs,
            fields,
            couplings,
            navigation: self.nav.clone(),
            resources,
            resource_edges,
            shown_resources,
        }
    }
}

impl Graph {
    /// One edge's relations in persisted form: the one place live relations
    /// become a `PersistedEdge`, for snapshots and for undo's exact edge write.
    pub(crate) fn persisted_edge(
        &self,
        from: NodeKey,
        to: NodeKey,
        payload: &EdgePayload,
    ) -> PersistedEdge {
        let from_node_id = self
            .get_node(from)
            .map(|n| n.id.to_string())
            .unwrap_or_default();
        let to_node_id = self
            .get_node(to)
            .map(|n| n.id.to_string())
            .unwrap_or_default();
        persisted_edge_with_ids(from_node_id, to_node_id, payload)
    }

    /// Every live Surface edge from `from` to `to`, in exact capture order.
    /// Retains session arrangements that durable snapshots intentionally omit.
    pub fn persisted_edges_between(&self, from: NodeKey, to: NodeKey) -> Vec<PersistedEdge> {
        self.inner
            .inner()
            .edges_connecting(from, to)
            .map(|edge| {
                let mut persisted = self.persisted_edge(from, to, edge.weight());
                // Pair captures/undo retain session arrangements too.
                persisted.assertions = Some(
                    edge.weight()
                        .assertions()
                        .iter()
                        .map(persisted_assertion)
                        .collect(),
                );
                persisted
            })
            .collect()
    }
}

/// Encode a pair using explicit ids from either graph stratum.
pub(crate) fn persisted_edge_for_ids(from: Uuid, to: Uuid, payload: &EdgePayload) -> PersistedEdge {
    persisted_edge_with_ids(from.to_string(), to.to_string(), payload)
}

pub(crate) fn persisted_assertion(statement: &SemanticStatement) -> PersistedSemanticStatement {
    PersistedSemanticStatement {
        statement_id: statement.statement_id.clone(),
        predicate: statement.predicate.clone(),
        recognized_sub_kind: statement
            .recognized_sub_kind
            .map(persisted_semantic_sub_kind),
        label: statement.label.clone(),
        basis: statement.basis.clone(),
        graph_scope: statement.graph_scope.clone(),
        provenance_iri: statement.provenance_iri.clone(),
        asserted_at_ms: statement.asserted_at_ms,
        first_asserted_ms: statement.first_asserted_ms,
        withdrawn: statement.withdrawn.clone(),
    }
}

fn persisted_edge_with_ids(
    from_node_id: String,
    to_node_id: String,
    payload: &EdgePayload,
) -> PersistedEdge {
    let assertions: Vec<_> = payload
        .assertions()
        .iter()
        .filter(|statement| {
            !matches!(statement.relation_kind(), RelationKind::Arrangement(kind)
            if kind.durability() != RelationDurability::Durable)
        })
        .map(persisted_assertion)
        .collect();
    PersistedEdge {
        from_node_id,
        to_node_id,
        families: payload
            .families()
            .into_iter()
            .map(|family| match family {
                EdgeFamily::Semantic => PersistedEdgeFamily::Semantic,
                EdgeFamily::Traversal => PersistedEdgeFamily::Traversal,
                EdgeFamily::Containment => PersistedEdgeFamily::Containment,
                EdgeFamily::Arrangement => PersistedEdgeFamily::Arrangement,
                EdgeFamily::Imported => PersistedEdgeFamily::Imported,
                EdgeFamily::Provenance => PersistedEdgeFamily::Provenance,
            })
            .collect(),
        semantic: None,
        containment: None,
        arrangement: None,
        imported: None,
        provenance: None,
        assertions: Some(assertions),
        traversal: payload
            .traversal_data()
            .map(|data| PersistedTraversalEdgeData {
                traversals: data
                    .traversals
                    .iter()
                    .map(|traversal| PersistedTraversalRecord {
                        timestamp_ms: traversal.timestamp_ms,
                        trigger: match traversal.trigger {
                            NavigationTrigger::Unknown => PersistedNavigationTrigger::Unknown,
                            NavigationTrigger::LinkClick => PersistedNavigationTrigger::LinkClick,
                            NavigationTrigger::Back => PersistedNavigationTrigger::Back,
                            NavigationTrigger::Forward => PersistedNavigationTrigger::Forward,
                            NavigationTrigger::AddressBarEntry => {
                                PersistedNavigationTrigger::AddressBarEntry
                            },
                            NavigationTrigger::PanePromotion => {
                                PersistedNavigationTrigger::PanePromotion
                            },
                            NavigationTrigger::Programmatic => {
                                PersistedNavigationTrigger::Programmatic
                            },
                            NavigationTrigger::Redirect => PersistedNavigationTrigger::Redirect,
                            NavigationTrigger::ReopenSession => {
                                PersistedNavigationTrigger::ReopenSession
                            },
                            NavigationTrigger::JumpAnchor => PersistedNavigationTrigger::JumpAnchor,
                            NavigationTrigger::InPageSearchJump => {
                                PersistedNavigationTrigger::InPageSearchJump
                            },
                            NavigationTrigger::ImportedHistory => {
                                PersistedNavigationTrigger::ImportedHistory
                            },
                        },
                    })
                    .collect(),
                metrics: PersistedTraversalMetrics {
                    total_navigations: data.metrics.total_navigations,
                    forward_navigations: data.metrics.forward_navigations,
                    backward_navigations: data.metrics.backward_navigations,
                    last_navigated_at: data.metrics.last_navigated_at,
                },
            }),
    }
}