1use std::collections::BTreeMap;
10use std::fmt;
11
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14
15use super::{Author, CapturedDelta, Graph, GraphStratum, ResourceNode, built_in_predicate_stratum};
16use crate::persistence::{PersistedResourceFacet, PersistedResourceRecord};
17use crate::types::mint_local_statement_id;
18
19pub const PREDICATE_DECLARATIONS_FACET: &str = "semantic.predicate-declarations/v1";
21
22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(deny_unknown_fields)]
25pub struct PredicateDeclaration {
26 pub declaration_id: String,
27 pub stratum: GraphStratum,
28 pub author: Author,
29 pub declared_at_ms: Option<u64>,
30}
31
32#[cfg(test)]
33mod tests {
34 use std::sync::{Arc, Mutex};
35
36 use super::*;
37 use crate::graph::revert::{Part, revert_change};
38 use crate::graph::{
39 EdgePayload, SemanticStatement, SemanticSubKind, predicate_iri, replay_captured_deltas_onto,
40 };
41 use crate::types::GraphScope;
42 use euclid::default::Point2D;
43
44 const PREDICATE: &str = "https://Vocabulary.test/terms?edition=1#custom";
45
46 fn value(id: &str, stratum: GraphStratum, author: Author) -> Value {
47 serde_json::to_value(PredicateDeclarations {
48 variants: vec![PredicateDeclaration {
49 declaration_id: id.into(),
50 stratum,
51 author,
52 declared_at_ms: Some(17),
53 }],
54 selected: Some(id.into()),
55 })
56 .unwrap()
57 }
58
59 fn record(predicate: &str, value: &Value) -> PersistedResourceRecord {
60 PersistedResourceRecord {
61 canonical_iri: predicate.into(),
62 facets: vec![PersistedResourceFacet {
63 facet: PREDICATE_DECLARATIONS_FACET.into(),
64 value_json: value.to_string(),
65 }],
66 }
67 }
68
69 fn capture(graph: &mut Graph) -> Arc<Mutex<Vec<CapturedDelta>>> {
70 let deltas = Arc::new(Mutex::new(vec![]));
71 let recorded = Arc::clone(&deltas);
72 graph.set_recorder(Some(Arc::new(move |delta| {
73 recorded.lock().unwrap().push(delta.clone())
74 })));
75 deltas
76 }
77
78 #[test]
79 fn predicate_declarations_persist_exact_origins_identity_and_replay() {
80 let mut graph = Graph::new();
81 let deltas = capture(&mut graph);
82 let mut author = Author::engine("extractor", "v2");
83 author.via = Some("origin-host".into());
84 let id = graph.write_as(author.clone(), |graph| {
85 graph
86 .declare_predicate(PREDICATE, GraphStratum::Surface)
87 .unwrap()
88 });
89 let declarations = graph.predicate_declarations(PREDICATE).unwrap().unwrap();
90 assert_eq!(declarations.selected.as_deref(), Some(id.as_str()));
91 assert_eq!(declarations.variants[0].author, author);
92 assert!(declarations.variants[0].declared_at_ms.is_some());
93 assert_eq!(
94 graph
95 .resource(ResourceNode::for_term(PREDICATE).id())
96 .unwrap()
97 .canonical_iri(),
98 PREDICATE
99 );
100 assert_eq!(
101 graph.node_count(),
102 0,
103 "a declaration needs no invented surface"
104 );
105 assert_eq!(
106 graph.clone().predicate_declarations(PREDICATE).unwrap(),
107 Some(declarations.clone())
108 );
109 let snapshot = graph.to_snapshot();
110 let bytes = serde_json::to_vec(&snapshot).unwrap();
111 let saved = serde_json::from_slice(&bytes).unwrap();
112 let restored = Graph::try_from_snapshot(&saved).unwrap();
113 assert_eq!(
114 restored.predicate_declarations(PREDICATE).unwrap(),
115 Some(declarations.clone())
116 );
117 let captured = deltas.lock().unwrap().clone();
118 assert_eq!(captured.len(), 1);
119 assert!(matches!(
120 &captured[0],
121 CapturedDelta::ReplaySetResourceRecordById { .. }
122 ));
123 let captured: Vec<CapturedDelta> =
124 postcard::from_bytes(&postcard::to_allocvec(&captured).unwrap()).unwrap();
125 let mut replayed = Graph::new();
126 replay_captured_deltas_onto(&mut replayed, captured.iter().cloned());
127 assert_eq!(
128 replayed.predicate_declarations(PREDICATE).unwrap(),
129 Some(declarations)
130 );
131 assert_eq!(
132 replayed.effective_predicate_stratum(PREDICATE),
133 Ok(GraphStratum::Surface)
134 );
135 assert_eq!(
136 replayed.effective_predicate_stratum("https://unrelated.test/predicate"),
137 Ok(GraphStratum::Resource)
138 );
139 let revision = graph.revision();
140 let same_id = graph.write_as(author, |graph| {
141 graph
142 .declare_predicate(PREDICATE, GraphStratum::Surface)
143 .unwrap()
144 });
145 assert_eq!(id, same_id);
146 assert_eq!(graph.revision(), revision);
147 assert_eq!(
148 deltas.lock().unwrap().len(),
149 1,
150 "no-op declarations emit no capture"
151 );
152 }
153
154 #[test]
155 fn predicate_declarations_conflicts_require_exact_choice_with_unambiguous_controls() {
156 let left = value("alice", GraphStratum::Resource, Author::person("alice"));
157 let right = value("bob", GraphStratum::Surface, Author::person("bob"));
158 let merged = merge_predicate_declarations(PREDICATE, &left, &right).unwrap();
159 assert_eq!(
160 merge_predicate_declarations(PREDICATE, &right, &left).unwrap(),
161 merged
162 );
163 let declarations = parse_predicate_declarations(PREDICATE, &merged).unwrap();
164 assert_eq!(declarations.variants.len(), 2);
165 assert_eq!(declarations.selected, None);
166 assert!(matches!(
167 declarations.effective_stratum(PREDICATE),
168 Err(PredicateDeclarationError::Conflict { .. })
169 ));
170 assert_eq!(
171 merge_predicate_declarations(PREDICATE, &left, &left).unwrap(),
172 left
173 );
174 let agreement = value("carol", GraphStratum::Resource, Author::person("carol"));
175 let agreed = merge_predicate_declarations(PREDICATE, &left, &agreement).unwrap();
176 assert_eq!(
177 parse_predicate_declarations(PREDICATE, &agreed)
178 .unwrap()
179 .effective_stratum(PREDICATE),
180 Ok(GraphStratum::Resource)
181 );
182 let mut graph = Graph::new();
183 let resource_id = ResourceNode::for_term(PREDICATE).id();
184 assert!(graph.set_resource_record(resource_id, Some(record(PREDICATE, &merged))));
185 assert!(matches!(
186 graph.effective_predicate_stratum(PREDICATE),
187 Err(PredicateDeclarationError::Conflict { .. })
188 ));
189 assert_eq!(
190 graph.effective_predicate_stratum("https://unrelated.test/predicate"),
191 Ok(GraphStratum::Resource)
192 );
193 let deltas = capture(&mut graph);
194 let before = graph.predicate_declarations(PREDICATE).unwrap().unwrap();
195 assert!(
196 graph
197 .select_predicate_declaration(PREDICATE, "absent")
198 .is_err()
199 );
200 assert_eq!(
201 graph.predicate_declarations(PREDICATE).unwrap().unwrap(),
202 before
203 );
204 assert!(deltas.lock().unwrap().is_empty());
205 assert!(
206 graph
207 .select_predicate_declaration(PREDICATE, "bob")
208 .unwrap()
209 );
210 assert_eq!(
211 graph.effective_predicate_stratum(PREDICATE),
212 Ok(GraphStratum::Surface)
213 );
214 assert_eq!(
215 graph
216 .predicate_declarations(PREDICATE)
217 .unwrap()
218 .unwrap()
219 .variants,
220 before.variants
221 );
222 assert!(
223 !graph
224 .select_predicate_declaration(PREDICATE, "bob")
225 .unwrap()
226 );
227 assert_eq!(deltas.lock().unwrap().len(), 1);
228 let mut replayed = Graph::new();
229 assert!(replayed.set_resource_record(resource_id, Some(record(PREDICATE, &merged))));
230 replay_captured_deltas_onto(&mut replayed, deltas.lock().unwrap().iter().cloned());
231 assert_eq!(
232 replayed.effective_predicate_stratum(PREDICATE),
233 Ok(GraphStratum::Surface)
234 );
235 }
236
237 #[test]
238 fn predicate_declarations_reused_origin_and_builtin_edits_are_atomic_errors() {
239 let left = value("same-id", GraphStratum::Resource, Author::person("alice"));
240 let different_origin = value("same-id", GraphStratum::Resource, Author::person("bob"));
241 assert!(merge_predicate_declarations(PREDICATE, &left, &different_origin).is_err());
242 let distinct = value(
243 "different-id",
244 GraphStratum::Resource,
245 Author::person("bob"),
246 );
247 assert!(merge_predicate_declarations(PREDICATE, &left, &distinct).is_ok());
248 assert_eq!(
249 left,
250 value("same-id", GraphStratum::Resource, Author::person("alice"))
251 );
252 let mut graph = Graph::new();
253 let deltas = capture(&mut graph);
254 for kind in [SemanticSubKind::UserGrouped, SemanticSubKind::Cites] {
255 let iri = predicate_iri(kind);
256 let before = graph.effective_predicate_stratum(iri).unwrap();
257 assert!(matches!(
258 graph.declare_predicate(iri, GraphStratum::Surface),
259 Err(PredicateDeclarationError::BuiltIn { .. })
260 ));
261 assert!(graph.select_predicate_declaration(iri, "any").is_err());
262 assert_eq!(graph.effective_predicate_stratum(iri), Ok(before));
263 }
264 assert_eq!(graph.resource_nodes().count(), 0);
265 assert_eq!(graph.revision(), 0);
266 assert!(deltas.lock().unwrap().is_empty());
267 assert!(
268 graph
269 .declare_predicate(PREDICATE, GraphStratum::Surface)
270 .is_ok()
271 );
272 assert_eq!(graph.resource_nodes().count(), 1);
273 assert_eq!(deltas.lock().unwrap().len(), 1);
274 }
275
276 #[test]
277 fn predicate_declarations_checked_load_and_raw_record_reject_invalid_typed_data() {
278 let mut graph = Graph::new();
279 let resource_id = ResourceNode::for_term(PREDICATE).id();
280 let valid = value("valid", GraphStratum::Surface, Author::person("alice"));
281 assert!(graph.set_resource_record(resource_id, Some(record(PREDICATE, &valid))));
282 let snapshot = graph.to_snapshot();
283 let mut bad = valid.clone();
284 bad["selected"] = Value::String("absent".into());
285 assert!(!graph.set_resource_record(resource_id, Some(record(PREDICATE, &bad))));
286 assert_eq!(graph.to_snapshot().resources, snapshot.resources);
287 let mut invalid = snapshot.clone();
288 invalid.resources[0] = record(PREDICATE, &bad);
289 let bytes = serde_json::to_vec(&invalid).unwrap();
290 let error = Graph::try_from_snapshot(&invalid)
291 .err()
292 .expect("invalid typed declaration")
293 .to_string();
294 assert!(
295 error.contains(PREDICATE_DECLARATIONS_FACET) && error.contains("absent"),
296 "{error}"
297 );
298 assert_eq!(
299 serde_json::to_vec(&invalid).unwrap(),
300 bytes,
301 "failed load retains source bytes"
302 );
303 assert!(Graph::try_from_snapshot(&snapshot).is_ok());
304 let mut opaque = record(PREDICATE, &bad);
305 opaque.facets[0].facet = "foreign.uninterpreted".into();
306 invalid.resources[0] = opaque.clone();
307 let restored = Graph::try_from_snapshot(&invalid).unwrap();
308 assert_eq!(restored.resource_record(resource_id).unwrap(), opaque);
309 assert_eq!(
310 restored.effective_predicate_stratum(PREDICATE),
311 Ok(GraphStratum::Resource)
312 );
313 let legacy = Graph::new().to_snapshot();
314 assert_eq!(
315 Graph::try_from_snapshot(&legacy)
316 .unwrap()
317 .effective_predicate_stratum(PREDICATE),
318 Ok(GraphStratum::Resource)
319 );
320 }
321
322 #[test]
323 fn predicate_declarations_conditional_undo_keeps_later_facets_and_declarations() {
324 let mut graph = Graph::new();
325 let resource_id = ResourceNode::for_term(PREDICATE).id();
326 assert!(graph.set_resource_record(
327 resource_id,
328 Some(PersistedResourceRecord {
329 canonical_iri: PREDICATE.into(),
330 facets: vec![PersistedResourceFacet {
331 facet: "foreign.before".into(),
332 value_json: "1".into()
333 }]
334 })
335 ));
336 let before = graph.clone();
337 let deltas = capture(&mut graph);
338 graph
339 .declare_predicate(PREDICATE, GraphStratum::Surface)
340 .unwrap();
341 let change = deltas.lock().unwrap().clone();
342 let after = graph.clone();
343 let mut updated = graph.resource_record(resource_id).unwrap();
344 updated.facets.push(PersistedResourceFacet {
345 facet: "foreign.later".into(),
346 value_json: "{\"nested\":[2]}".into(),
347 });
348 assert!(graph.set_resource_record(resource_id, Some(updated)));
349 let undo = revert_change(&change, &before, &after, &graph);
350 assert!(undo.kept.is_empty());
351 replay_captured_deltas_onto(&mut graph, undo.edits.iter().cloned());
352 assert_eq!(graph.predicate_declarations(PREDICATE).unwrap(), None);
353 assert_eq!(graph.resource_record(resource_id).unwrap().facets.len(), 2);
354 assert_eq!(
355 graph.effective_predicate_stratum(PREDICATE),
356 Ok(GraphStratum::Resource)
357 );
358 let mut later = after.clone();
359 later.write_as(Author::person("later-author"), |graph| {
360 graph
361 .declare_predicate(PREDICATE, GraphStratum::Resource)
362 .unwrap()
363 });
364 let current = later.predicate_declarations(PREDICATE).unwrap();
365 let kept = revert_change(&change, &before, &after, &later);
366 assert!(kept.kept.contains(&Part::ResourceFacet(
367 resource_id,
368 PREDICATE_DECLARATIONS_FACET.into()
369 )));
370 replay_captured_deltas_onto(&mut later, kept.edits.iter().cloned());
371 assert_eq!(later.predicate_declarations(PREDICATE).unwrap(), current);
372 assert_eq!(
373 later.effective_predicate_stratum(PREDICATE),
374 Ok(GraphStratum::Resource)
375 );
376 }
377
378 #[test]
379 fn predicate_declarations_nature_changes_leave_held_claims_in_both_strata_exact() {
380 let mut graph = Graph::new();
381 let a = graph.add_node("https://surface.test/a".into(), Point2D::zero());
382 let b = graph.add_node("https://surface.test/b".into(), Point2D::zero());
383 let held = |id: &str| {
384 let mut payload = EdgePayload::new();
385 payload.push_persisted_semantic_statement(SemanticStatement {
386 statement_id: id.into(),
387 predicate: PREDICATE.into(),
388 recognized_sub_kind: None,
389 label: Some("held claim".into()),
390 graph_scope: GraphScope::User,
391 provenance_iri: Some("https://original-author.test/".into()),
392 asserted_at_ms: Some(19),
393 first_asserted_ms: Some(19),
394 withdrawn: None,
395 basis: Default::default(),
396 });
397 payload
398 };
399 graph.inner.connect(a, b, held("surface-claim"));
400 let ra = ResourceNode::for_term("https://resource.test/a");
401 let rb = ResourceNode::for_term("https://resource.test/b");
402 for resource in [&ra, &rb] {
403 assert!(graph.set_resource_record(
404 resource.id(),
405 Some(PersistedResourceRecord {
406 canonical_iri: resource.canonical_iri().into(),
407 facets: vec![]
408 })
409 ));
410 }
411 let edge = super::super::snapshot::persisted_edge_for_ids(
412 ra.id(),
413 rb.id(),
414 &held("resource-claim"),
415 );
416 assert!(graph.set_resource_edges_between(ra.id(), rb.id(), &[edge]));
417 let before = graph.to_snapshot();
418 let deltas = capture(&mut graph);
419 let first = graph
420 .declare_predicate(PREDICATE, GraphStratum::Surface)
421 .unwrap();
422 let second = graph
423 .declare_predicate(PREDICATE, GraphStratum::Resource)
424 .unwrap();
425 assert_ne!(first, second);
426 assert_eq!(
427 graph.effective_predicate_stratum(PREDICATE),
428 Ok(GraphStratum::Resource)
429 );
430 assert_eq!(
431 graph
432 .predicate_declarations(PREDICATE)
433 .unwrap()
434 .unwrap()
435 .variants
436 .len(),
437 2
438 );
439 assert_eq!(graph.to_snapshot().edges, before.edges);
440 assert_eq!(graph.to_snapshot().resource_edges, before.resource_edges);
441 assert_eq!(deltas.lock().unwrap().len(), 2);
442 assert!(
443 deltas
444 .lock()
445 .unwrap()
446 .iter()
447 .all(|delta| matches!(delta, CapturedDelta::ReplaySetResourceRecordById { .. }))
448 );
449 let mut replayed = Graph::try_from_snapshot(&before).unwrap();
450 let restored_before = replayed.to_snapshot();
451 assert!(restored_before.edges.iter().any(|edge| {
452 edge.retained_assertions()
453 .iter()
454 .any(|statement| statement.statement_id == "surface-claim")
455 }));
456 assert!(
457 restored_before
458 .edges
459 .iter()
460 .any(|edge| edge.retained_assertions().iter().any(|record| {
461 super::super::RelationKind::from_predicate_iri(&record.predicate).is_some_and(
462 |kind| matches!(kind, super::super::RelationKind::Containment(_)),
463 )
464 })),
465 "restored aggregate control is present"
466 );
467 replay_captured_deltas_onto(&mut replayed, deltas.lock().unwrap().iter().cloned());
468 assert_eq!(replayed.to_snapshot().edges, restored_before.edges);
469 assert_eq!(
470 replayed.to_snapshot().resource_edges,
471 restored_before.resource_edges
472 );
473 assert_eq!(
474 replayed.predicate_declarations(PREDICATE).unwrap(),
475 graph.predicate_declarations(PREDICATE).unwrap()
476 );
477 }
478}
479
480#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
483#[serde(deny_unknown_fields)]
484pub struct PredicateDeclarations {
485 pub variants: Vec<PredicateDeclaration>,
486 pub selected: Option<String>,
487}
488
489#[derive(Debug, Clone, PartialEq, Eq)]
490pub enum PredicateDeclarationError {
491 Invalid {
492 predicate: String,
493 detail: String,
494 },
495 BuiltIn {
496 predicate: String,
497 },
498 Conflict {
499 predicate: String,
500 declaration_ids: Vec<String>,
501 },
502}
503
504impl fmt::Display for PredicateDeclarationError {
505 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
506 match self {
507 Self::Invalid { predicate, detail } => write!(
508 f,
509 "predicate {predicate:?} has invalid declarations: {detail}"
510 ),
511 Self::BuiltIn { predicate } => {
512 write!(f, "predicate {predicate:?} has fixed built-in placement")
513 },
514 Self::Conflict {
515 predicate,
516 declaration_ids,
517 } => write!(
518 f,
519 "predicate {predicate:?} requires a declaration choice among {declaration_ids:?}"
520 ),
521 }
522 }
523}
524
525impl std::error::Error for PredicateDeclarationError {}
526
527fn invalid(predicate: &str, detail: impl Into<String>) -> PredicateDeclarationError {
528 PredicateDeclarationError::Invalid {
529 predicate: predicate.into(),
530 detail: detail.into(),
531 }
532}
533
534impl PredicateDeclarations {
535 fn validate(&self, predicate: &str) -> Result<(), PredicateDeclarationError> {
537 if built_in_predicate_stratum(predicate).is_some() {
538 return Err(PredicateDeclarationError::BuiltIn {
539 predicate: predicate.into(),
540 });
541 }
542 let mut ids = BTreeMap::new();
543 for variant in &self.variants {
544 if let Some(previous) = ids.insert(variant.declaration_id.as_str(), variant) {
545 return Err(invalid(
546 predicate,
547 if previous == variant {
548 format!("repeated declaration {:?}", variant.declaration_id)
549 } else {
550 format!("conflicting declaration {:?}", variant.declaration_id)
551 },
552 ));
553 }
554 }
555 if let Some(selected) = &self.selected
556 && !ids.contains_key(selected.as_str())
557 {
558 return Err(invalid(
559 predicate,
560 format!("selected declaration {selected:?} is absent"),
561 ));
562 }
563 Ok(())
564 }
565
566 pub fn effective_stratum(
568 &self,
569 predicate: &str,
570 ) -> Result<GraphStratum, PredicateDeclarationError> {
571 self.validate(predicate)?;
572 if let Some(selected) = &self.selected {
573 return Ok(self
574 .variants
575 .iter()
576 .find(|variant| variant.declaration_id == *selected)
577 .expect("validated selection")
578 .stratum);
579 }
580 let Some(first) = self.variants.first() else {
581 return Ok(GraphStratum::Resource);
582 };
583 if self
584 .variants
585 .iter()
586 .all(|variant| variant.stratum == first.stratum)
587 {
588 return Ok(first.stratum);
589 }
590 let mut declaration_ids: Vec<_> = self
591 .variants
592 .iter()
593 .map(|variant| variant.declaration_id.clone())
594 .collect();
595 declaration_ids.sort();
596 Err(PredicateDeclarationError::Conflict {
597 predicate: predicate.into(),
598 declaration_ids,
599 })
600 }
601}
602
603pub fn parse_predicate_declarations(
605 predicate: &str,
606 value: &Value,
607) -> Result<PredicateDeclarations, PredicateDeclarationError> {
608 let declarations: PredicateDeclarations =
609 Deserialize::deserialize(value).map_err(|error| invalid(predicate, error.to_string()))?;
610 declarations.validate(predicate)?;
611 Ok(declarations)
612}
613
614pub fn predicate_declarations_from_record(
616 record: &PersistedResourceRecord,
617) -> Result<Option<PredicateDeclarations>, PredicateDeclarationError> {
618 let mut facet = record
619 .facets
620 .iter()
621 .filter(|facet| facet.facet == PREDICATE_DECLARATIONS_FACET);
622 let Some(declaration) = facet.next() else {
623 return Ok(None);
624 };
625 if facet.next().is_some() {
626 return Err(invalid(&record.canonical_iri, "repeated declaration facet"));
627 }
628 let value: Value = serde_json::from_str(&declaration.value_json)
629 .map_err(|error| invalid(&record.canonical_iri, error.to_string()))?;
630 parse_predicate_declarations(&record.canonical_iri, &value).map(Some)
631}
632
633pub fn merge_predicate_declarations(
636 predicate: &str,
637 left: &Value,
638 right: &Value,
639) -> Result<Value, PredicateDeclarationError> {
640 let left = parse_predicate_declarations(predicate, left)?;
641 let right = parse_predicate_declarations(predicate, right)?;
642 let selected = (left.selected == right.selected)
643 .then(|| left.selected.clone())
644 .flatten();
645 let mut variants = BTreeMap::new();
646 for variant in left.variants.into_iter().chain(right.variants) {
647 if let Some(previous) = variants.get(&variant.declaration_id)
648 && previous != &variant
649 {
650 return Err(invalid(
651 predicate,
652 format!("conflicting declaration {:?}", variant.declaration_id),
653 ));
654 }
655 variants.insert(variant.declaration_id.clone(), variant);
656 }
657 let merged = PredicateDeclarations {
658 variants: variants.into_values().collect(),
659 selected,
660 };
661 serde_json::to_value(merged).map_err(|error| invalid(predicate, error.to_string()))
662}
663
664impl Graph {
665 pub fn predicate_declarations(
667 &self,
668 predicate: &str,
669 ) -> Result<Option<PredicateDeclarations>, PredicateDeclarationError> {
670 let Some(record) = self.resource_record(ResourceNode::for_term(predicate).id()) else {
671 return Ok(None);
672 };
673 predicate_declarations_from_record(&record)
674 }
675
676 pub fn effective_predicate_stratum(
678 &self,
679 predicate: &str,
680 ) -> Result<GraphStratum, PredicateDeclarationError> {
681 if let Some(stratum) = built_in_predicate_stratum(predicate) {
682 return Ok(stratum);
683 }
684 match self.predicate_declarations(predicate)? {
685 Some(declarations) => declarations.effective_stratum(predicate),
686 None => Ok(GraphStratum::Resource),
687 }
688 }
689
690 pub fn declare_predicate(
692 &mut self,
693 predicate: &str,
694 stratum: GraphStratum,
695 ) -> Result<String, PredicateDeclarationError> {
696 if built_in_predicate_stratum(predicate).is_some() {
697 return Err(PredicateDeclarationError::BuiltIn {
698 predicate: predicate.into(),
699 });
700 }
701 let mut declarations =
702 self.predicate_declarations(predicate)?
703 .unwrap_or(PredicateDeclarations {
704 variants: vec![],
705 selected: None,
706 });
707 if let Some(selected) = &declarations.selected
708 && let Some(existing) = declarations
709 .variants
710 .iter()
711 .find(|variant| variant.declaration_id == *selected)
712 && existing.stratum == stratum
713 && existing.author == *self.write_author()
714 {
715 return Ok(existing.declaration_id.clone());
716 }
717 let declaration_id = mint_local_statement_id();
718 declarations.variants.push(PredicateDeclaration {
719 declaration_id: declaration_id.clone(),
720 stratum,
721 author: self.write_author().clone(),
722 declared_at_ms: Some(Self::epoch_ms()),
723 });
724 declarations.selected = Some(declaration_id.clone());
725 self.write_predicate_declarations(predicate, declarations)?;
726 Ok(declaration_id)
727 }
728
729 pub fn select_predicate_declaration(
731 &mut self,
732 predicate: &str,
733 declaration_id: &str,
734 ) -> Result<bool, PredicateDeclarationError> {
735 if built_in_predicate_stratum(predicate).is_some() {
736 return Err(PredicateDeclarationError::BuiltIn {
737 predicate: predicate.into(),
738 });
739 }
740 let mut declarations = self
741 .predicate_declarations(predicate)?
742 .ok_or_else(|| invalid(predicate, "no retained declarations"))?;
743 if !declarations
744 .variants
745 .iter()
746 .any(|variant| variant.declaration_id == declaration_id)
747 {
748 return Err(invalid(
749 predicate,
750 format!("declaration {declaration_id:?} is absent"),
751 ));
752 }
753 if declarations.selected.as_deref() == Some(declaration_id) {
754 return Ok(false);
755 }
756 declarations.selected = Some(declaration_id.into());
757 self.write_predicate_declarations(predicate, declarations)
758 }
759
760 fn write_predicate_declarations(
761 &mut self,
762 predicate: &str,
763 mut declarations: PredicateDeclarations,
764 ) -> Result<bool, PredicateDeclarationError> {
765 declarations.validate(predicate)?;
766 declarations
767 .variants
768 .sort_by(|a, b| a.declaration_id.cmp(&b.declaration_id));
769 let resource_id = ResourceNode::for_term(predicate).id();
770 let mut record = self
771 .resource_record(resource_id)
772 .unwrap_or(PersistedResourceRecord {
773 canonical_iri: predicate.into(),
774 facets: vec![],
775 });
776 record
777 .facets
778 .retain(|facet| facet.facet != PREDICATE_DECLARATIONS_FACET);
779 record.facets.push(PersistedResourceFacet {
780 facet: PREDICATE_DECLARATIONS_FACET.into(),
781 value_json: serde_json::to_string(&declarations)
782 .map_err(|error| invalid(predicate, error.to_string()))?,
783 });
784 let changed = self.set_resource_record(resource_id, Some(record));
785 if changed {
786 self.record_delta(&CapturedDelta::ReplaySetResourceRecordById {
787 resource_id: resource_id.to_string(),
788 record: self.resource_record(resource_id),
789 });
790 }
791 Ok(changed)
792 }
793}