Skip to main content

kernel/graph/
node_facets.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Typed projections over the graph's atomic per-node facet store.
5//!
6//! The store remains JSON-shaped and unknown-forward at its boundary. These
7//! helpers give kernel consumers concrete types without putting optional
8//! metadata columns back on [`Node`](super::Node).
9
10use serde::{Serialize, de::DeserializeOwned};
11use uuid::Uuid;
12
13use super::{Graph, NodeKey};
14
15pub const ARRANGEMENT_PIN: &str = "arrangement.pin";
16pub const ARRANGEMENT_FRAME_LAYOUT: &str = "arrangement.frame-layout";
17pub const ARRANGEMENT_SPLIT_OFFER_SUPPRESSED: &str = "arrangement.split-offer-suppressed";
18pub const PRESENTATION_TAGS: &str = "presentation.tags";
19pub const VISIT_HISTORY: &str = "visit.history";
20pub const PROVENANCE_IMPORT: &str = "provenance.import";
21pub const PROVENANCE_DERIVATIONS: &str = "provenance.derivations";
22pub const SEMANTIC_CLASSIFICATIONS: &str = "semantic.classifications";
23pub const SEMANTIC_PROPERTIES: &str = "semantic.properties";
24
25pub type NodeFacetStore = chartulary::FacetStore<Uuid>;
26
27/// The durable visit clocks formerly stored as two columns on `Node`.
28#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, serde::Deserialize)]
29pub struct VisitHistoryFacet {
30    #[serde(default)]
31    pub last_visited_ms: Option<u64>,
32    #[serde(default)]
33    pub last_session_visited: u64,
34}
35
36impl Graph {
37    /// The graph's single live atomic-facet authority.
38    pub fn facets(&self) -> &NodeFacetStore {
39        &self.facets
40    }
41
42    /// Mutable facet access for the host and extension gate.
43    ///
44    /// Kernel-owned facet families should still use their typed graph methods;
45    /// this surface exists for host-defined and unknown-forward namespaces.
46    pub fn facets_mut(&mut self) -> &mut NodeFacetStore {
47        &mut self.facets
48    }
49
50    /// Overlay a canonical sidecar after snapshot load.
51    ///
52    /// Legacy snapshot columns are imported while reconstructing the graph.
53    /// Existing `facets.json` values then win for matching keys, while both
54    /// stores preserve unrelated namespaces.
55    pub fn overlay_facets(&mut self, facets: NodeFacetStore) {
56        self.facets.overlay(facets);
57    }
58
59    pub(crate) fn node_facet<T: DeserializeOwned>(
60        &self,
61        key: NodeKey,
62        facet: &'static str,
63    ) -> Option<T> {
64        let node = self.inner.node(key)?;
65        let value = self
66            .facets
67            .get(&node.id, &chartulary::FacetId::new(facet))?;
68        serde_json::from_value(value.clone()).ok()
69    }
70
71    pub(crate) fn node_facet_or_default<T: DeserializeOwned + Default>(
72        &self,
73        key: NodeKey,
74        facet: &'static str,
75    ) -> T {
76        self.node_facet(key, facet).unwrap_or_default()
77    }
78
79    pub(crate) fn set_node_facet<T: Serialize>(
80        &mut self,
81        key: NodeKey,
82        facet: &'static str,
83        value: &T,
84    ) -> bool {
85        let Some(node_id) = self.inner.node(key).map(|node| node.id) else {
86            return false;
87        };
88        let facet_id = chartulary::FacetId::new(facet);
89        let value = serde_json::to_value(value).expect("kernel facet must serialize");
90        if self.facets.get(&node_id, &facet_id) == Some(&value) {
91            return false;
92        }
93        self.facets
94            .set(node_id, facet_id, value, &chartulary::AcceptAll)
95            .expect("AcceptAll cannot reject a kernel facet");
96        true
97    }
98
99    pub(crate) fn remove_facets_for_node(&mut self, node_id: Uuid) {
100        self.facets.remove_node(&node_id);
101    }
102}