Skip to main content

kernel/graph/
predicate_declarations.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//! Per-mere predicate nature, recorded as ordinary resource metadata.
8
9use 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
19/// Typed declaration data on the exact-IRI resource identifying a predicate.
20pub const PREDICATE_DECLARATIONS_FACET: &str = "semantic.predicate-declarations/v1";
21
22/// One carried declaration and its original author, version, application and time.
23#[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/// All retained variants, with an explicit choice when their natures differ.
481/// Every field is serialized, including an absent choice.
482#[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    /// Exact variant identities cannot select different carried origins or natures.
536    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    /// A retained explicit selection wins; agreeing variants need no selection.
567    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
603/// Parse only the owned declaration namespace; unknown resource facets stay opaque.
604pub 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
614/// Read a declaration facet without canonicalizing the predicate's vocabulary IRI.
615pub 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
633/// Union exact origins and variants without choosing either input's selection.
634/// Differing selections clear the choice; agreeing natures remain unambiguous.
635pub 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    /// The declarations held by this mere for one predicate.
666    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    /// Placement for a future assertion; exact historical handles retain their stores.
677    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    /// Retain an authored nature change and explicitly select it for future writes.
691    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    /// Resolve a retained conflict by exact declaration id, without moving statements.
730    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}