Skip to main content

kernel/graph/
chart.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//! chartulary capability-trait impls for the web [`Node`] (graph re-base, G5).
8//!
9//! mere's `Node` is the canonical *foreign* implementor of the chartulary
10//! container capabilities: its `id` is the stable identity, its address claims map
11//! to scheme-qualified addresses, and its title and tags are the curated labels.
12//! This is the first step of the graph re-base: the real web node satisfies the
13//! generic substrate's node traits, so the substrate can hold and project it. The
14//! browser-runtime facets (favicon, viewer routing, session restore, lifecycle)
15//! stay on `Node` and simply do not participate in the generic capabilities.
16//!
17//! `ContentBearing` reports the node's inline authored body (`Node::body`, a knot
18//! note's djot) as content: `content()` is the blake3 `muniment::Hash` of the body
19//! bytes, the address that body would have in a muniment `BlobStore`. So the node
20//! names its content's identity even though the bytes still live inline. Moving the
21//! bytes out-of-line into an actual blob store (and content-addressing fetched web
22//! pages, which live in mere's own cache, not on the node) is the follow-on step.
23
24use chartulary::{
25    Address, Addressed, Classified, ContentBearing, GraphBearing, Identified, Labeled, Predicated,
26    RelationClass,
27};
28use uuid::Uuid;
29
30use super::edge_payload::EdgePayload;
31use super::node::Node;
32
33impl Identified for Node {
34    type Id = Uuid;
35
36    fn id(&self) -> &Uuid {
37        &self.id
38    }
39}
40
41impl Addressed for Node {
42    fn addresses(&self) -> Vec<Address> {
43        Addressed::addresses(&self.container)
44    }
45}
46
47impl Labeled for Node {
48    fn title(&self) -> Option<&str> {
49        Labeled::title(&self.container)
50    }
51
52    fn tags(&self) -> Vec<String> {
53        self.tags.iter().cloned().collect()
54    }
55}
56
57impl ContentBearing for Node {
58    fn content(&self) -> Option<muniment::Hash> {
59        ContentBearing::content(&self.container)
60    }
61
62    fn media_type(&self) -> Option<&str> {
63        ContentBearing::media_type(&self.container)
64    }
65}
66
67impl GraphBearing for Node {
68    fn nested(&self) -> Option<&muniment::LogId> {
69        // Structural containment (the one-node ruling): the node BEARS the
70        // graph named by this log identity. A participant's inner world hangs
71        // here; agency (subject + kind) stays a facet.
72        GraphBearing::nested(&self.container)
73    }
74}
75
76/// The single predicate IRI a semantic edge projects, or `None` if the edge
77/// carries no semantic relation (an experience-layer edge: Traversal, Containment,
78/// Arrangement, Imported). Withdrawn assertions remain in history but do not
79/// project. This single-predicate capability selects the first held semantic
80/// statement; readers needing every statement use the assertion APIs.
81fn edge_predicate(payload: &EdgePayload) -> Option<&str> {
82    payload
83        .held_semantic_statements()
84        .next()
85        .map(|statement| statement.predicate.as_str())
86}
87
88impl Predicated for EdgePayload {
89    fn predicate(&self) -> Option<&str> {
90        edge_predicate(self)
91    }
92}
93
94impl Classified for EdgePayload {
95    fn class(&self) -> RelationClass {
96        match edge_predicate(self) {
97            // A semantic edge joins the shared ring as an open predicate (its IRI),
98            // so it projects to RDF.
99            Some(iri) => RelationClass::open(iri.to_string()),
100            // An experience-layer edge is mere's private family: it does not project.
101            None => RelationClass::app("mere", 0),
102        }
103    }
104}
105
106#[cfg(test)]
107mod tests {
108    use super::super::edge_data::{SemanticData, SemanticStatementSpec, predicate_iri};
109    use super::super::edge_taxonomy::{EdgeAssertion, SemanticSubKind};
110    use super::*;
111
112    #[test]
113    fn web_node_satisfies_the_container_capabilities() {
114        // A compile-time proof that mere's Node implements the substrate's node
115        // capability traits.
116        fn assert_caps<N: Identified<Id = Uuid> + Addressed + Labeled + ContentBearing>() {}
117        assert_caps::<Node>();
118    }
119
120    #[cfg(not(target_arch = "wasm32"))]
121    #[test]
122    fn a_web_node_projects_its_identity_address_and_label() {
123        let mut node = Node::test_stub("https://example.test/paper");
124        node.title = "A Paper".to_string();
125        node.tags.insert("research".to_string());
126
127        assert_eq!(Identified::id(&node), &node.id);
128        assert_eq!(
129            Addressed::primary_address(&node).unwrap().as_str(),
130            "https://example.test/paper"
131        );
132        assert_eq!(Labeled::title(&node), Some("A Paper"));
133        assert_eq!(Labeled::tags(&node), vec!["research".to_string()]);
134    }
135
136    #[cfg(not(target_arch = "wasm32"))]
137    #[test]
138    fn a_web_node_reports_its_body_as_content() {
139        let mut node = Node::test_stub("mere://note/x");
140        assert_eq!(
141            ContentBearing::content(&node),
142            None,
143            "no body: no graph-owned content (a bare web tab's content lives in the cache)"
144        );
145        node.body = Some("# A note".to_string());
146        node.media_type = Some("text/markdown".to_string());
147        assert_eq!(
148            ContentBearing::content(&node),
149            Some(muniment::Hash::of(b"# A note")),
150            "content is the body's blake3 hash, the muniment blob address"
151        );
152        assert_eq!(ContentBearing::media_type(&node), Some("text/markdown"));
153    }
154
155    #[cfg(not(target_arch = "wasm32"))]
156    #[test]
157    fn a_bearing_node_reports_its_nested_graph() {
158        let mut node = Node::test_stub("mere://denizen/ab12");
159        assert_eq!(
160            GraphBearing::nested(&node),
161            None,
162            "an ordinary node bears no graph"
163        );
164        node.nested = Some(muniment::LogId::new("denizens/trail-keeper"));
165        assert_eq!(
166            GraphBearing::nested(&node).map(muniment::LogId::as_str),
167            Some("denizens/trail-keeper"),
168            "containment is structural: the borne world reads off the node itself"
169        );
170    }
171
172    #[test]
173    fn semantic_edges_project_experience_edges_do_not() {
174        // A semantic edge carries a predicate IRI and joins the RDF-projecting ring.
175        let mut cites = EdgePayload::new();
176        cites.assert_relation(EdgeAssertion::Semantic {
177            sub_kind: SemanticSubKind::Cites,
178            label: None,
179        });
180        assert_eq!(
181            Predicated::predicate(&cites),
182            Some(predicate_iri(SemanticSubKind::Cites))
183        );
184        assert!(
185            Classified::class(&cites).predicate().is_some(),
186            "a semantic edge projects"
187        );
188
189        // An edge with no semantic relation is experience-layer: it does not project.
190        let experience = EdgePayload::new();
191        assert_eq!(Predicated::predicate(&experience), None);
192        assert!(
193            Classified::class(&experience).predicate().is_none(),
194            "an experience edge stays private"
195        );
196    }
197
198    #[test]
199    fn generic_projection_uses_only_held_semantic_statements() {
200        let mut data = SemanticData::default();
201        let first = data.assert_statement(SemanticStatementSpec {
202            predicate: "urn:test:first".into(),
203            ..Default::default()
204        });
205        let second = data.assert_statement(SemanticStatementSpec {
206            predicate: "urn:test:second".into(),
207            ..Default::default()
208        });
209        let mut payload = EdgePayload::new();
210        payload.assertions = data;
211        assert_eq!(Predicated::predicate(&payload), Some("urn:test:first"));
212
213        let withdrawal = crate::types::AssertionWithdrawal {
214            at_ms: Some(1),
215            by: None,
216        };
217        assert!(
218            payload
219                .assertions
220                .withdraw_statement(&first.statement_id, withdrawal.clone())
221        );
222        assert_eq!(Predicated::predicate(&payload), Some("urn:test:second"));
223        assert_eq!(
224            Classified::class(&payload).predicate(),
225            Some("urn:test:second")
226        );
227
228        assert!(
229            payload
230                .assertions
231                .withdraw_statement(&second.statement_id, withdrawal)
232        );
233        assert_eq!(payload.semantic_statements().len(), 2, "history survives");
234        assert_eq!(Predicated::predicate(&payload), None);
235        assert_eq!(Classified::class(&payload).predicate(), None);
236    }
237}