Skip to main content

kernel/graph/
frozen_selection.rs

1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! Immutable selections owned by Resources, independent of local appearances.
8use 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}
41// Legacy edge DTOs deliberately remain permissive. This v1 carrier checks
42// every nested key against what their typed serialization retains instead.
43pub(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
89/// Decode and check nested references without requiring member residency.
90pub(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    // Human-readable statement serialization omits default metadata. Their
106    // known fields are still accepted explicitly, including null/default values.
107    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        // Reject malformed family/payload combinations instead of normalizing away data.
168        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    /// Mint a Resource that bears a revision-frozen nested graph of references and
178    /// exact relation copies. Member payloads stay in their owning resources.
179    /// The spec is opaque to the kernel; the facade supplies its portable value.
180    #[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    /// Portable freeze entry point: the host supplies a fresh UUID nonce, as it
190    /// does for new Surfaces on wasm. A reused address is refused before writing.
191    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        // A fresh address gives this record its own deterministic Resource identity.
218        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    /// Open the immutable graph without loading or inventing its referenced members.
244    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}