1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
// 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
//! Typed projections over the graph's atomic per-node facet store.
//!
//! The store remains JSON-shaped and unknown-forward at its boundary. These
//! helpers give kernel consumers concrete types without putting optional
//! metadata columns back on [`Node`](super::Node).
use serde::{Serialize, de::DeserializeOwned};
use uuid::Uuid;
use super::snapshot::ResourceSnapshotError;
use super::{Graph, NodeKey};
use crate::types::{NodeClassification, NodeProperty, NodeTagPresentationState};
pub const ARRANGEMENT_PIN: &str = "arrangement.pin";
pub const ARRANGEMENT_FRAME_LAYOUT: &str = "arrangement.frame-layout";
pub const ARRANGEMENT_SPLIT_OFFER_SUPPRESSED: &str = "arrangement.split-offer-suppressed";
pub const PRESENTATION_TAGS: &str = "presentation.tags";
pub const VISIT_HISTORY: &str = "visit.history";
pub const PROVENANCE_IMPORT: &str = "provenance.import";
pub const PROVENANCE_DERIVATIONS: &str = "provenance.derivations";
pub const SEMANTIC_CLASSIFICATIONS: &str = "semantic.classifications";
pub const SEMANTIC_PROPERTIES: &str = "semantic.properties";
pub type NodeFacetStore = chartulary::FacetStore<Uuid>;
/// The durable visit clocks formerly stored as two columns on `Node`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, serde::Deserialize)]
pub struct VisitHistoryFacet {
#[serde(default)]
pub last_visited_ms: Option<u64>,
#[serde(default)]
pub last_session_visited: u64,
}
impl Graph {
/// The graph's single live atomic-facet authority.
pub fn facets(&self) -> &NodeFacetStore {
&self.facets
}
/// Raw mutable access to the store, for kernel code and test fixtures.
///
/// Outside the kernel a loaded store goes in through
/// [`install_facets`](Self::install_facets) or
/// [`overlay_facets`](Self::overlay_facets), which apply the handle rule
/// checked open applies; this skips it.
///
/// A write through it may touch visit history, so taking it advances the
/// [visit revision](Graph::visit_revision).
pub(crate) fn facets_mut(&mut self) -> &mut NodeFacetStore {
self.bump_visit_revision();
&mut self.facets
}
/// Replace the facet store with `facets`, a sidecar loaded for this graph.
///
/// Refused, with the previous store kept, when the result would fail
/// checked open: a retained Surface literal may not reuse a handle a
/// Resource holds ([`validate_active_resource_assertion_handles`]
/// (Graph::validate_active_resource_assertion_handles)).
pub fn install_facets(&mut self, facets: NodeFacetStore) -> Result<(), ResourceSnapshotError> {
let previous = std::mem::replace(&mut self.facets, facets);
if let Err(error) = self.validate_active_resource_assertion_handles() {
self.facets = previous;
return Err(ResourceSnapshotError::InvalidFacets(error));
}
self.bump_visit_revision();
Ok(())
}
/// Overlay a canonical sidecar after snapshot load.
///
/// Legacy snapshot columns are imported while reconstructing the graph.
/// Existing `facets.json` values then win for matching keys, while both
/// stores preserve unrelated namespaces. Checked and kept as
/// [`install_facets`](Self::install_facets) is.
pub fn overlay_facets(&mut self, facets: NodeFacetStore) -> Result<(), ResourceSnapshotError> {
let mut merged = self.facets.clone();
merged.overlay(facets);
self.install_facets(merged)
}
pub(crate) fn node_facet<T: DeserializeOwned>(
&self,
key: NodeKey,
facet: &'static str,
) -> Option<T> {
let node = self.inner.node(key)?;
let value = self
.facets
.get(&node.id, &chartulary::FacetId::new(facet))?;
// Borrowing deserializer: `&Value` is itself a `Deserializer`, so the
// stored subtree is read in place. `from_value` would deep-clone the
// whole tree first, and these accessors sit on the per-frame paint path.
T::deserialize(value).ok()
}
pub(crate) fn node_facet_or_default<T: DeserializeOwned + Default>(
&self,
key: NodeKey,
facet: &'static str,
) -> T {
self.node_facet(key, facet).unwrap_or_default()
}
pub(crate) fn set_node_facet<T: Serialize>(
&mut self,
key: NodeKey,
facet: &'static str,
value: &T,
) -> bool {
let Some(node_id) = self.inner.node(key).map(|node| node.id) else {
return false;
};
let facet_id = chartulary::FacetId::new(facet);
let value = serde_json::to_value(value).expect("kernel facet must serialize");
if self.facets.get(&node_id, &facet_id) == Some(&value) {
return false;
}
self.facets
.set(node_id, facet_id, value, &chartulary::AcceptAll)
.expect("AcceptAll cannot reject a kernel facet");
if facet == VISIT_HISTORY {
self.bump_visit_revision();
}
true
}
pub(crate) fn remove_facets_for_node(&mut self, node_id: Uuid) {
self.facets.remove_node(&node_id);
}
}
// ---------------------------------------------------------------------------
// Live batched content writers. Exact Resource captures carry the shared content;
// legacy Replay variants continue using the raw Surface setters in node_props.
// ---------------------------------------------------------------------------
impl Graph {
/// Insert tags on the shown Resource, retaining each tagger's assertion.
pub fn insert_node_tags(&mut self, key: NodeKey, tags: Vec<String>) -> bool {
let mut changed = false;
for tag in tags {
changed |= self.insert_shown_tag(key, tag);
}
changed
}
/// Append literal assertions to the shown Resource in one facet replacement.
pub fn append_node_properties(&mut self, key: NodeKey, incoming: Vec<NodeProperty>) -> bool {
self.append_shown_properties(key, incoming)
}
/// Preserve complete classification variants and the caller's origin.
pub fn add_node_classifications(
&mut self,
key: NodeKey,
incoming: Vec<NodeClassification>,
) -> bool {
self.add_shown_classifications(key, incoming)
}
}