Skip to main content

kernel/graph/
predicate_registry.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//! Fixed placement catalog. Effective custom placement must also consult the
8//! mere's durable declarations; these defaults do not resolve those declarations.
9
10use super::resource::TAGGED_WITH_IRI;
11use super::{
12    ArrangementSubKind, ContainmentSubKind, ImportedSubKind, ProvenanceSubKind, RelationKind,
13    SemanticSubKind,
14};
15
16/// The owning graph stratum of a relation.
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
18#[serde(rename_all = "snake_case")]
19pub enum GraphStratum {
20    Resource,
21    Surface,
22}
23
24/// Built-in placement by relation nature. `OpenPredicate` supplies only the
25/// unfamiliar-predicate default, before any per-mere declaration is consulted.
26pub const fn built_in_relation_stratum(kind: RelationKind) -> GraphStratum {
27    match kind {
28        RelationKind::Semantic(kind) => match kind {
29            SemanticSubKind::UserGrouped => GraphStratum::Surface,
30            SemanticSubKind::Hyperlink
31            | SemanticSubKind::AgentDerived
32            | SemanticSubKind::Cites
33            | SemanticSubKind::Quotes
34            | SemanticSubKind::Summarizes
35            | SemanticSubKind::Elaborates
36            | SemanticSubKind::ExampleOf
37            | SemanticSubKind::Supports
38            | SemanticSubKind::Contradicts
39            | SemanticSubKind::Questions
40            | SemanticSubKind::SameEntityAs
41            | SemanticSubKind::DuplicateOf
42            | SemanticSubKind::CanonicalMirrorOf
43            | SemanticSubKind::DependsOn
44            | SemanticSubKind::Blocks
45            | SemanticSubKind::NextStep => GraphStratum::Resource,
46        },
47        RelationKind::Provenance(kind) => match kind {
48            ProvenanceSubKind::CopiedFrom | ProvenanceSubKind::MergedFrom => GraphStratum::Surface,
49            ProvenanceSubKind::ClippedFrom
50            | ProvenanceSubKind::ExcerptedFrom
51            | ProvenanceSubKind::SummarizedFrom
52            | ProvenanceSubKind::TranslatedFrom
53            | ProvenanceSubKind::RewrittenFrom
54            | ProvenanceSubKind::GeneratedFrom
55            | ProvenanceSubKind::ExtractedFrom
56            | ProvenanceSubKind::ImportedFromSource => GraphStratum::Resource,
57        },
58        RelationKind::Imported(kind) => match kind {
59            ImportedSubKind::BookmarkFolder
60            | ImportedSubKind::HistoryImport
61            | ImportedSubKind::SessionImport => GraphStratum::Surface,
62            ImportedSubKind::RssMembership
63            | ImportedSubKind::FileSystemImport
64            | ImportedSubKind::ArchiveMembership
65            | ImportedSubKind::SharedCollection => GraphStratum::Resource,
66        },
67        RelationKind::Containment(kind) => match kind {
68            ContainmentSubKind::UserFolder
69            | ContainmentSubKind::NotebookSection
70            | ContainmentSubKind::CollectionMember => GraphStratum::Surface,
71            ContainmentSubKind::UrlPath
72            | ContainmentSubKind::Domain
73            | ContainmentSubKind::FileSystem
74            | ContainmentSubKind::ClipSource => GraphStratum::Resource,
75        },
76        RelationKind::Arrangement(
77            ArrangementSubKind::FrameMember
78            | ArrangementSubKind::TileGroup
79            | ArrangementSubKind::SplitPair,
80        )
81        | RelationKind::Traversal => GraphStratum::Surface,
82        RelationKind::OpenPredicate => GraphStratum::Resource,
83    }
84}
85
86/// Fixed placement for canonical built-in predicate IRIs. Unfamiliar strings
87/// return `None`; their effective placement can include a custom declaration.
88pub fn built_in_predicate_stratum(iri: &str) -> Option<GraphStratum> {
89    if iri == TAGGED_WITH_IRI {
90        return Some(GraphStratum::Resource);
91    }
92    RelationKind::from_predicate_iri(iri).map(built_in_relation_stratum)
93}
94
95/// Predicate placement before per-mere declarations are applied. This fallback
96/// must not replace effective placement for registered custom predicates.
97pub fn default_predicate_stratum(iri: &str) -> GraphStratum {
98    built_in_predicate_stratum(iri).unwrap_or(GraphStratum::Resource)
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104    use crate::graph::predicate_iri;
105    use strum::IntoEnumIterator;
106
107    #[test]
108    fn all_recognized_kinds_match_the_settled_placement_table() {
109        let surfaces = [
110            RelationKind::Semantic(SemanticSubKind::UserGrouped),
111            RelationKind::Provenance(ProvenanceSubKind::CopiedFrom),
112            RelationKind::Provenance(ProvenanceSubKind::MergedFrom),
113            RelationKind::Imported(ImportedSubKind::BookmarkFolder),
114            RelationKind::Imported(ImportedSubKind::HistoryImport),
115            RelationKind::Imported(ImportedSubKind::SessionImport),
116            RelationKind::Containment(ContainmentSubKind::UserFolder),
117            RelationKind::Containment(ContainmentSubKind::NotebookSection),
118            RelationKind::Containment(ContainmentSubKind::CollectionMember),
119            RelationKind::Arrangement(ArrangementSubKind::FrameMember),
120            RelationKind::Arrangement(ArrangementSubKind::TileGroup),
121            RelationKind::Arrangement(ArrangementSubKind::SplitPair),
122        ];
123        let kinds: Vec<_> = SemanticSubKind::iter()
124            .map(RelationKind::Semantic)
125            .chain(ProvenanceSubKind::iter().map(RelationKind::Provenance))
126            .chain(ImportedSubKind::iter().map(RelationKind::Imported))
127            .chain(ContainmentSubKind::iter().map(RelationKind::Containment))
128            .chain(ArrangementSubKind::iter().map(RelationKind::Arrangement))
129            .collect();
130        assert_eq!(kinds.len(), 44);
131        let mut resource_count = 0;
132        let mut surface_count = 0;
133        for kind in kinds {
134            let expected = if surfaces.contains(&kind) {
135                surface_count += 1;
136                GraphStratum::Surface
137            } else {
138                resource_count += 1;
139                GraphStratum::Resource
140            };
141            assert_eq!(built_in_relation_stratum(kind), expected, "{kind:?}");
142        }
143        assert_eq!((resource_count, surface_count), (32, 12));
144        assert_eq!(
145            built_in_relation_stratum(RelationKind::Traversal),
146            GraphStratum::Surface
147        );
148        assert_eq!(
149            built_in_relation_stratum(RelationKind::OpenPredicate),
150            GraphStratum::Resource
151        );
152    }
153
154    #[test]
155    fn canonical_predicates_tags_and_open_defaults_have_distinct_controls() {
156        assert_eq!(SemanticSubKind::iter().count(), 17);
157        for kind in SemanticSubKind::iter() {
158            let expected = if kind == SemanticSubKind::UserGrouped {
159                GraphStratum::Surface
160            } else {
161                GraphStratum::Resource
162            };
163            assert_eq!(
164                built_in_predicate_stratum(predicate_iri(kind)),
165                Some(expected)
166            );
167            assert_eq!(default_predicate_stratum(predicate_iri(kind)), expected);
168        }
169        for kind in [
170            SemanticSubKind::AgentDerived,
171            SemanticSubKind::DependsOn,
172            SemanticSubKind::Blocks,
173            SemanticSubKind::NextStep,
174        ] {
175            assert_eq!(
176                built_in_relation_stratum(RelationKind::Semantic(kind)),
177                GraphStratum::Resource
178            );
179        }
180        assert_eq!(
181            built_in_relation_stratum(RelationKind::Imported(ImportedSubKind::SharedCollection)),
182            GraphStratum::Resource
183        );
184        assert_eq!(
185            built_in_predicate_stratum(TAGGED_WITH_IRI),
186            Some(GraphStratum::Resource)
187        );
188        for unfamiliar in [
189            "https://foreign.test/predicate",
190            "",
191            "arbitrary predicate",
192            "https://mere.computer/ns/rel#User-grouped",
193        ] {
194            assert_eq!(built_in_predicate_stratum(unfamiliar), None);
195            assert_eq!(
196                default_predicate_stratum(unfamiliar),
197                GraphStratum::Resource
198            );
199        }
200    }
201
202    #[test]
203    fn relation_predicate_mapping_is_unique_bidirectional_and_placement_preserving() {
204        let kinds: Vec<_> = SemanticSubKind::iter()
205            .map(RelationKind::Semantic)
206            .chain(ContainmentSubKind::iter().map(RelationKind::Containment))
207            .chain(ArrangementSubKind::iter().map(RelationKind::Arrangement))
208            .chain(ImportedSubKind::iter().map(RelationKind::Imported))
209            .chain(ProvenanceSubKind::iter().map(RelationKind::Provenance))
210            .collect();
211        assert_eq!(kinds.len(), 44);
212
213        let mut predicates = std::collections::BTreeSet::new();
214        for kind in kinds {
215            let iri = kind
216                .predicate_iri()
217                .expect("every sub-kind relation has a predicate IRI");
218            assert!(predicates.insert(iri), "duplicate predicate IRI {iri}");
219            assert_eq!(RelationKind::from_predicate_iri(iri), Some(kind), "{iri}");
220            assert_eq!(
221                built_in_predicate_stratum(iri),
222                Some(built_in_relation_stratum(kind)),
223                "placement for {iri}"
224            );
225        }
226
227        for sub_kind in SemanticSubKind::iter() {
228            assert_eq!(
229                RelationKind::Semantic(sub_kind).predicate_iri(),
230                Some(predicate_iri(sub_kind)),
231                "semantic predicate bytes remain unchanged for {sub_kind:?}"
232            );
233        }
234        assert_eq!(RelationKind::Traversal.predicate_iri(), None);
235        assert_eq!(RelationKind::OpenPredicate.predicate_iri(), None);
236        assert_eq!(
237            RelationKind::from_predicate_iri("https://foreign.test/rel"),
238            None
239        );
240        assert_eq!(
241            RelationKind::from_predicate_iri("https://mere.computer/ns/rel#containment.UserFolder"),
242            None
243        );
244        assert_eq!(
245            built_in_predicate_stratum("https://mere.computer/ns/rel#containment.UserFolder"),
246            None
247        );
248    }
249}