1use super::{CoverageNote, Graph, GraphStratum};
9use crate::persistence::PersistedEdge;
10use serde::{Deserialize, Serialize};
11use uuid::Uuid;
12
13pub const FROZEN_SELECTION: &str = "graph.frozen-selection/v1";
14#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
15#[serde(deny_unknown_fields)]
16pub struct FrozenSelection {
17 version: u32,
18 spec: serde_json::Value,
19 revision: u64,
20 members: Vec<Uuid>,
21 statements: Vec<PersistedEdge>,
22}
23impl FrozenSelection {
24 pub fn spec(&self) -> &serde_json::Value {
25 &self.spec
26 }
27 pub fn revision(&self) -> u64 {
28 self.revision
29 }
30 pub fn members(&self) -> &[Uuid] {
31 &self.members
32 }
33 pub fn statements(&self) -> &[PersistedEdge] {
34 &self.statements
35 }
36}
37pub struct OpenedFrozenSelection<'a> {
38 pub selection: &'a FrozenSelection,
39 pub coverage: CoverageNote,
40}
41pub(super) fn validate_retained_keys(
44 input: &serde_json::Value,
45 known: &serde_json::Value,
46) -> Result<(), String> {
47 match (input, known) {
48 (serde_json::Value::Object(input), serde_json::Value::Object(known)) => {
49 for (key, value) in input {
50 let expected = known
51 .get(key)
52 .ok_or_else(|| format!("unknown frozen payload field {key}"))?;
53 validate_retained_keys(value, expected)?;
54 }
55 },
56 (serde_json::Value::Array(input), serde_json::Value::Array(known)) => {
57 for (value, expected) in input.iter().zip(known) {
58 validate_retained_keys(value, expected)?;
59 }
60 },
61 (serde_json::Value::Object(_), _) | (serde_json::Value::Array(_), _) => {
62 return Err("unrepresentable frozen payload shape".into());
63 },
64 _ => {},
65 }
66 Ok(())
67}
68
69pub(super) fn normalize_statement_defaults(statements: &mut [serde_json::Value]) {
70 for statement in statements {
71 let object = statement
72 .as_object_mut()
73 .expect("serialized statement object");
74 for field in [
75 "recognized_sub_kind",
76 "label",
77 "graph_scope",
78 "provenance_iri",
79 "asserted_at_ms",
80 "first_asserted_ms",
81 "withdrawn",
82 "basis",
83 ] {
84 object.entry(field).or_insert(serde_json::Value::Null);
85 }
86 }
87}
88
89pub(crate) fn selection_from_record(
91 record: &crate::persistence::PersistedResourceRecord,
92) -> Result<Option<FrozenSelection>, String> {
93 let Some(facet) = record
94 .facets
95 .iter()
96 .find(|facet| facet.facet == FROZEN_SELECTION)
97 else {
98 return Ok(None);
99 };
100 let raw: serde_json::Value = serde_json::from_str(&facet.value_json)
101 .map_err(|e| format!("invalid frozen selection: {e}"))?;
102 let selection: FrozenSelection = serde_json::from_value(raw.clone())
103 .map_err(|e| format!("invalid frozen selection: {e}"))?;
104 let mut known = serde_json::to_value(&selection).map_err(|e| e.to_string())?;
105 for edge in known["statements"]
108 .as_array_mut()
109 .expect("serialized edge array")
110 {
111 if let Some(statements) = edge
112 .get_mut("assertions")
113 .and_then(serde_json::Value::as_array_mut)
114 {
115 normalize_statement_defaults(statements);
116 }
117 if let Some(statements) = edge
118 .get_mut("semantic")
119 .and_then(|semantic| semantic.get_mut("statements"))
120 .and_then(serde_json::Value::as_array_mut)
121 {
122 normalize_statement_defaults(statements);
123 }
124 }
125 validate_retained_keys(&raw, &known)?;
126 if selection.version != 1 {
127 return Err("unsupported frozen selection version".into());
128 }
129 let members: std::collections::BTreeSet<_> = selection.members.iter().copied().collect();
130 if members.len() != selection.members.len() || members.contains(&Uuid::nil()) {
131 return Err("invalid frozen member references".into());
132 }
133 super::assertion_handles::validate_assertion_handles(
134 selection
135 .statements
136 .iter()
137 .map(|edge| (GraphStratum::Resource, edge)),
138 )
139 .map_err(|error| error.to_string())?;
140 for edge in &selection.statements {
141 let from = edge
142 .from_node_id
143 .parse::<Uuid>()
144 .map_err(|_| "invalid frozen source id")?;
145 let to = edge
146 .to_node_id
147 .parse::<Uuid>()
148 .map_err(|_| "invalid frozen target id")?;
149 if from.to_string() != edge.from_node_id
150 || to.to_string() != edge.to_node_id
151 || !members.contains(&from)
152 || !members.contains(&to)
153 {
154 return Err("frozen statement endpoints must be member references".into());
155 }
156 if edge.assertions.is_some() && edge.has_legacy_assertion_data() {
157 return Err("frozen relation mixes canonical and legacy assertion data".into());
158 }
159 if edge.assertions.is_none() {
160 if let Some(semantic) = &edge.semantic
161 && semantic.statements.is_empty()
162 && (!semantic.sub_kinds.is_empty() || semantic.predicate.is_some())
163 {
164 return Err("frozen semantic statements require exact handles".into());
165 }
166 }
167 let payload = super::snapshot::payload_from_persisted(edge);
169 if super::snapshot::persisted_edge_for_ids(from, to, &payload) != *edge {
170 return Err("inconsistent frozen relation payload".into());
171 }
172 }
173 Ok(Some(selection))
174}
175
176impl Graph {
177 #[cfg(not(target_arch = "wasm32"))]
181 pub fn freeze_resource_selection(
182 &mut self,
183 spec: serde_json::Value,
184 members: Vec<Uuid>,
185 ) -> Result<Uuid, String> {
186 self.freeze_resource_selection_with_nonce(spec, members, Uuid::new_v4())
187 }
188
189 pub fn freeze_resource_selection_with_nonce(
192 &mut self,
193 spec: serde_json::Value,
194 mut members: Vec<Uuid>,
195 nonce: Uuid,
196 ) -> Result<Uuid, String> {
197 members.sort();
198 members.dedup();
199 if members.iter().any(|id| self.resource(*id).is_none()) {
200 return Err("missing frozen member resource".into());
201 }
202 let set: std::collections::BTreeSet<_> = members.iter().copied().collect();
203 let statements = self
204 .resource_edges()
205 .filter(|(from, to, _)| set.contains(&from.id()) && set.contains(&to.id()))
206 .map(|(from, to, payload)| {
207 super::snapshot::persisted_edge_for_ids(from.id(), to.id(), payload)
208 })
209 .collect();
210 let selection = FrozenSelection {
211 version: 1,
212 spec,
213 revision: self.revision(),
214 members,
215 statements,
216 };
217 if nonce.is_nil() {
219 return Err("frozen Resource nonce must be fresh".into());
220 }
221 let iri = format!("urn:uuid:{nonce}");
222 let resource = super::ResourceNode::for_term(&iri);
223 let record = crate::persistence::PersistedResourceRecord {
224 canonical_iri: iri,
225 facets: vec![crate::persistence::PersistedResourceFacet {
226 facet: FROZEN_SELECTION.into(),
227 value_json: serde_json::to_string(&selection).map_err(|e| e.to_string())?,
228 }],
229 };
230 selection_from_record(&record)?;
231 if self.resource(resource.id()).is_some()
232 || !self.set_resource_record(resource.id(), Some(record.clone()))
233 {
234 return Err("frozen Resource admission refused".into());
235 }
236 self.record_delta(&super::CapturedDelta::ReplaySetResourceRecordById {
237 resource_id: resource.id().to_string(),
238 record: Some(record),
239 });
240 Ok(resource.id())
241 }
242
243 pub fn open_frozen_selection(&self, owner: Uuid) -> Result<OpenedFrozenSelection<'_>, String> {
245 let selection = self
246 .resource(owner)
247 .and_then(|resource| resource.nested_selection())
248 .ok_or("resource bears no frozen selection")?;
249 Ok(OpenedFrozenSelection {
250 selection,
251 coverage: self.coverage_for_resource_refs(selection.members()),
252 })
253 }
254}
255
256#[cfg(test)]
257mod canonical_record_tests {
258 use super::*;
259 use crate::persistence::{
260 PersistedEdge, PersistedResourceFacet, PersistedResourceRecord, PersistedSemanticStatement,
261 };
262 use crate::types::{AssertionBasis, GraphScope};
263
264 fn assertion_edge(from: Uuid, to: Uuid, id: &str) -> PersistedEdge {
265 PersistedEdge {
266 from_node_id: from.to_string(),
267 to_node_id: to.to_string(),
268 families: vec![crate::persistence::PersistedEdgeFamily::Semantic],
269 semantic: None,
270 traversal: None,
271 containment: None,
272 arrangement: None,
273 imported: None,
274 provenance: None,
275 assertions: Some(vec![PersistedSemanticStatement {
276 statement_id: id.into(),
277 predicate: "urn:test:claim".into(),
278 recognized_sub_kind: None,
279 label: Some("claim".into()),
280 graph_scope: GraphScope::User,
281 provenance_iri: Some("urn:test:author".into()),
282 asserted_at_ms: Some(12),
283 first_asserted_ms: Some(10),
284 withdrawn: None,
285 basis: AssertionBasis {
286 note: Some("basis note".into()),
287 ..Default::default()
288 },
289 }]),
290 }
291 }
292
293 fn record(statements: Vec<PersistedEdge>) -> PersistedResourceRecord {
294 let members = (1..=3).map(Uuid::from_u128).collect();
295 let selection = FrozenSelection {
296 version: 1,
297 spec: serde_json::json!({}),
298 revision: 1,
299 members,
300 statements,
301 };
302 PersistedResourceRecord {
303 canonical_iri: "urn:uuid:selection".into(),
304 facets: vec![PersistedResourceFacet {
305 facet: FROZEN_SELECTION.into(),
306 value_json: serde_json::to_string(&selection).unwrap(),
307 }],
308 }
309 }
310
311 #[test]
312 fn frozen_selection_rejects_conflicting_canonical_ids_across_pairs() {
313 let (first, second, third) = (Uuid::from_u128(1), Uuid::from_u128(2), Uuid::from_u128(3));
314 let error = selection_from_record(&record(vec![
315 assertion_edge(first, second, "same-id"),
316 assertion_edge(first, third, "same-id"),
317 ]))
318 .unwrap_err();
319 assert!(error.contains("one handle means one row"), "{error}");
320 }
321
322 #[test]
323 fn frozen_selection_rejects_identical_copies_on_parallel_rows() {
324 let row = assertion_edge(Uuid::from_u128(1), Uuid::from_u128(2), "copied");
325 assert!(selection_from_record(&record(vec![row.clone()])).is_ok());
326 let error = selection_from_record(&record(vec![row.clone(), row])).unwrap_err();
327 assert!(error.contains("one handle means one row"), "{error}");
328 }
329}