use super::{CoverageNote, Graph, GraphStratum};
use crate::persistence::PersistedEdge;
use serde::{Deserialize, Serialize};
use uuid::Uuid;
pub const FROZEN_SELECTION: &str = "graph.frozen-selection/v1";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FrozenSelection {
version: u32,
spec: serde_json::Value,
revision: u64,
members: Vec<Uuid>,
statements: Vec<PersistedEdge>,
}
impl FrozenSelection {
pub fn spec(&self) -> &serde_json::Value {
&self.spec
}
pub fn revision(&self) -> u64 {
self.revision
}
pub fn members(&self) -> &[Uuid] {
&self.members
}
pub fn statements(&self) -> &[PersistedEdge] {
&self.statements
}
}
pub struct OpenedFrozenSelection<'a> {
pub selection: &'a FrozenSelection,
pub coverage: CoverageNote,
}
pub(super) fn validate_retained_keys(
input: &serde_json::Value,
known: &serde_json::Value,
) -> Result<(), String> {
match (input, known) {
(serde_json::Value::Object(input), serde_json::Value::Object(known)) => {
for (key, value) in input {
let expected = known
.get(key)
.ok_or_else(|| format!("unknown frozen payload field {key}"))?;
validate_retained_keys(value, expected)?;
}
},
(serde_json::Value::Array(input), serde_json::Value::Array(known)) => {
for (value, expected) in input.iter().zip(known) {
validate_retained_keys(value, expected)?;
}
},
(serde_json::Value::Object(_), _) | (serde_json::Value::Array(_), _) => {
return Err("unrepresentable frozen payload shape".into());
},
_ => {},
}
Ok(())
}
pub(super) fn normalize_statement_defaults(statements: &mut [serde_json::Value]) {
for statement in statements {
let object = statement
.as_object_mut()
.expect("serialized statement object");
for field in [
"recognized_sub_kind",
"label",
"graph_scope",
"provenance_iri",
"asserted_at_ms",
"first_asserted_ms",
"withdrawn",
"basis",
] {
object.entry(field).or_insert(serde_json::Value::Null);
}
}
}
pub(crate) fn selection_from_record(
record: &crate::persistence::PersistedResourceRecord,
) -> Result<Option<FrozenSelection>, String> {
let Some(facet) = record
.facets
.iter()
.find(|facet| facet.facet == FROZEN_SELECTION)
else {
return Ok(None);
};
let raw: serde_json::Value = serde_json::from_str(&facet.value_json)
.map_err(|e| format!("invalid frozen selection: {e}"))?;
let selection: FrozenSelection = serde_json::from_value(raw.clone())
.map_err(|e| format!("invalid frozen selection: {e}"))?;
let mut known = serde_json::to_value(&selection).map_err(|e| e.to_string())?;
for edge in known["statements"]
.as_array_mut()
.expect("serialized edge array")
{
if let Some(statements) = edge
.get_mut("assertions")
.and_then(serde_json::Value::as_array_mut)
{
normalize_statement_defaults(statements);
}
if let Some(statements) = edge
.get_mut("semantic")
.and_then(|semantic| semantic.get_mut("statements"))
.and_then(serde_json::Value::as_array_mut)
{
normalize_statement_defaults(statements);
}
}
validate_retained_keys(&raw, &known)?;
if selection.version != 1 {
return Err("unsupported frozen selection version".into());
}
let members: std::collections::BTreeSet<_> = selection.members.iter().copied().collect();
if members.len() != selection.members.len() || members.contains(&Uuid::nil()) {
return Err("invalid frozen member references".into());
}
super::assertion_handles::validate_assertion_handles(
selection
.statements
.iter()
.map(|edge| (GraphStratum::Resource, edge)),
)
.map_err(|error| error.to_string())?;
for edge in &selection.statements {
let from = edge
.from_node_id
.parse::<Uuid>()
.map_err(|_| "invalid frozen source id")?;
let to = edge
.to_node_id
.parse::<Uuid>()
.map_err(|_| "invalid frozen target id")?;
if from.to_string() != edge.from_node_id
|| to.to_string() != edge.to_node_id
|| !members.contains(&from)
|| !members.contains(&to)
{
return Err("frozen statement endpoints must be member references".into());
}
if edge.assertions.is_some() && edge.has_legacy_assertion_data() {
return Err("frozen relation mixes canonical and legacy assertion data".into());
}
if edge.assertions.is_none() {
if let Some(semantic) = &edge.semantic
&& semantic.statements.is_empty()
&& (!semantic.sub_kinds.is_empty() || semantic.predicate.is_some())
{
return Err("frozen semantic statements require exact handles".into());
}
}
let payload = super::snapshot::payload_from_persisted(edge);
if super::snapshot::persisted_edge_for_ids(from, to, &payload) != *edge {
return Err("inconsistent frozen relation payload".into());
}
}
Ok(Some(selection))
}
impl Graph {
#[cfg(not(target_arch = "wasm32"))]
pub fn freeze_resource_selection(
&mut self,
spec: serde_json::Value,
members: Vec<Uuid>,
) -> Result<Uuid, String> {
self.freeze_resource_selection_with_nonce(spec, members, Uuid::new_v4())
}
pub fn freeze_resource_selection_with_nonce(
&mut self,
spec: serde_json::Value,
mut members: Vec<Uuid>,
nonce: Uuid,
) -> Result<Uuid, String> {
members.sort();
members.dedup();
if members.iter().any(|id| self.resource(*id).is_none()) {
return Err("missing frozen member resource".into());
}
let set: std::collections::BTreeSet<_> = members.iter().copied().collect();
let statements = self
.resource_edges()
.filter(|(from, to, _)| set.contains(&from.id()) && set.contains(&to.id()))
.map(|(from, to, payload)| {
super::snapshot::persisted_edge_for_ids(from.id(), to.id(), payload)
})
.collect();
let selection = FrozenSelection {
version: 1,
spec,
revision: self.revision(),
members,
statements,
};
if nonce.is_nil() {
return Err("frozen Resource nonce must be fresh".into());
}
let iri = format!("urn:uuid:{nonce}");
let resource = super::ResourceNode::for_term(&iri);
let record = crate::persistence::PersistedResourceRecord {
canonical_iri: iri,
facets: vec![crate::persistence::PersistedResourceFacet {
facet: FROZEN_SELECTION.into(),
value_json: serde_json::to_string(&selection).map_err(|e| e.to_string())?,
}],
};
selection_from_record(&record)?;
if self.resource(resource.id()).is_some()
|| !self.set_resource_record(resource.id(), Some(record.clone()))
{
return Err("frozen Resource admission refused".into());
}
self.record_delta(&super::CapturedDelta::ReplaySetResourceRecordById {
resource_id: resource.id().to_string(),
record: Some(record),
});
Ok(resource.id())
}
pub fn open_frozen_selection(&self, owner: Uuid) -> Result<OpenedFrozenSelection<'_>, String> {
let selection = self
.resource(owner)
.and_then(|resource| resource.nested_selection())
.ok_or("resource bears no frozen selection")?;
Ok(OpenedFrozenSelection {
selection,
coverage: self.coverage_for_resource_refs(selection.members()),
})
}
}
#[cfg(test)]
mod canonical_record_tests {
use super::*;
use crate::persistence::{
PersistedEdge, PersistedResourceFacet, PersistedResourceRecord, PersistedSemanticStatement,
};
use crate::types::{AssertionBasis, GraphScope};
fn assertion_edge(from: Uuid, to: Uuid, id: &str) -> PersistedEdge {
PersistedEdge {
from_node_id: from.to_string(),
to_node_id: to.to_string(),
families: vec![crate::persistence::PersistedEdgeFamily::Semantic],
semantic: None,
traversal: None,
containment: None,
arrangement: None,
imported: None,
provenance: None,
assertions: Some(vec![PersistedSemanticStatement {
statement_id: id.into(),
predicate: "urn:test:claim".into(),
recognized_sub_kind: None,
label: Some("claim".into()),
graph_scope: GraphScope::User,
provenance_iri: Some("urn:test:author".into()),
asserted_at_ms: Some(12),
first_asserted_ms: Some(10),
withdrawn: None,
basis: AssertionBasis {
note: Some("basis note".into()),
..Default::default()
},
}]),
}
}
fn record(statements: Vec<PersistedEdge>) -> PersistedResourceRecord {
let members = (1..=3).map(Uuid::from_u128).collect();
let selection = FrozenSelection {
version: 1,
spec: serde_json::json!({}),
revision: 1,
members,
statements,
};
PersistedResourceRecord {
canonical_iri: "urn:uuid:selection".into(),
facets: vec![PersistedResourceFacet {
facet: FROZEN_SELECTION.into(),
value_json: serde_json::to_string(&selection).unwrap(),
}],
}
}
#[test]
fn frozen_selection_rejects_conflicting_canonical_ids_across_pairs() {
let (first, second, third) = (Uuid::from_u128(1), Uuid::from_u128(2), Uuid::from_u128(3));
let error = selection_from_record(&record(vec![
assertion_edge(first, second, "same-id"),
assertion_edge(first, third, "same-id"),
]))
.unwrap_err();
assert!(error.contains("one handle means one row"), "{error}");
}
#[test]
fn frozen_selection_rejects_identical_copies_on_parallel_rows() {
let row = assertion_edge(Uuid::from_u128(1), Uuid::from_u128(2), "copied");
assert!(selection_from_record(&record(vec![row.clone()])).is_ok());
let error = selection_from_record(&record(vec![row.clone(), row])).unwrap_err();
assert!(error.contains("one handle means one row"), "{error}");
}
}