1use super::{Graph, NodeKey};
10use crate::persistence::{PersistedEdge, PersistedResourceFacet, PersistedResourceRecord};
11use chartulary::{Address, Addressed, Identified};
12use petgraph::visit::{EdgeRef, IntoEdgeReferences};
13use uuid::Uuid;
14
15pub use super::resource_pair_bounds::ResourceEdgesBoundError;
16
17pub const TAGGED_WITH_IRI: &str = "https://mere.computer/ns/rel#taggedWith";
19
20#[derive(Debug, Clone, PartialEq)]
25pub struct ResourceNode {
26 container: chartulary::Container<Uuid>,
27 pub(super) nested_selection: Option<super::FrozenSelection>,
28 pub(super) nested_link: Option<super::FrozenLink>,
29}
30
31impl ResourceNode {
32 pub fn new(iri: &str) -> Self {
34 let canonical = chartulary::canonical_url(iri);
35 Self::from_canonical_iri(&canonical)
36 }
37
38 pub fn for_term(iri: &str) -> Self {
41 Self::from_canonical_iri(iri)
42 }
43
44 pub(crate) fn from_canonical_iri(canonical: &str) -> Self {
45 Self {
46 nested_selection: None,
47 nested_link: None,
48 container: chartulary::Container::with_identity(
49 chartulary::resource_id_from_canonical_iri(canonical),
50 )
51 .with_address_record(Address::new(canonical)),
52 }
53 }
54
55 pub fn nested_selection(&self) -> Option<&super::FrozenSelection> {
57 self.nested_selection.as_ref()
58 }
59
60 pub fn nested_link(&self) -> Option<&super::FrozenLink> {
62 self.nested_link.as_ref()
63 }
64
65 pub fn id(&self) -> Uuid {
67 self.container.id
68 }
69
70 pub fn canonical_iri(&self) -> &str {
72 self.container.addresses[0].as_str()
73 }
74}
75
76impl Graph {
77 pub fn resource(&self, id: Uuid) -> Option<&ResourceNode> {
79 self.resources.get(&id)
80 }
81
82 pub fn resource_nodes(&self) -> impl Iterator<Item = &ResourceNode> {
84 self.resources.nodes().map(|(_, resource)| resource)
85 }
86
87 pub fn resource_edges(
89 &self,
90 ) -> impl Iterator<Item = (&ResourceNode, &ResourceNode, &super::EdgePayload)> {
91 self.resources.inner().edge_references().map(|edge| {
92 (
93 self.resources
94 .node(edge.source())
95 .expect("resource endpoint exists"),
96 self.resources
97 .node(edge.target())
98 .expect("resource endpoint exists"),
99 edge.weight(),
100 )
101 })
102 }
103
104 pub fn resource_facets(&self) -> &chartulary::FacetStore<Uuid> {
106 &self.resource_facets
107 }
108
109 pub fn shown_resource_id(&self, surface: NodeKey) -> Option<Uuid> {
111 self.shown_resources
112 .get(&self.get_node(surface)?.id)
113 .copied()
114 }
115
116 pub fn surface_ids_showing_resource(&self, resource_id: Uuid) -> Vec<Uuid> {
118 self.shown_resources
119 .iter()
120 .filter_map(|(surface, resource)| (*resource == resource_id).then_some(*surface))
121 .collect()
122 }
123
124 pub fn resource_record(&self, id: Uuid) -> Option<PersistedResourceRecord> {
125 let resource = self.resource(id)?;
126 let facets = self
127 .resource_facets
128 .facets_of(&id)
129 .into_iter()
130 .flat_map(|facets| facets.iter())
131 .map(|(facet, value)| PersistedResourceFacet {
132 facet: facet.as_str().to_string(),
133 value_json: serde_json::to_string(value).expect("JSON value serializes"),
134 })
135 .collect();
136 Some(PersistedResourceRecord {
137 canonical_iri: resource.canonical_iri().to_string(),
138 facets,
139 })
140 }
141
142 pub(crate) fn set_resource_record(
143 &mut self,
144 id: Uuid,
145 record: Option<PersistedResourceRecord>,
146 ) -> bool {
147 let Some(record) = record else {
148 let Some(key) = self.resources.key_of(&id) else {
149 return false;
150 };
151 if self
152 .shown_resources
153 .values()
154 .any(|resource| *resource == id)
155 || self
156 .resources
157 .inner()
158 .edge_references()
159 .any(|edge| edge.source() == key || edge.target() == key)
160 {
161 return false;
162 }
163 self.resources.remove(key);
164 self.resource_facets.remove_node(&id);
165 self.bump_revision();
166 return true;
167 };
168 let mut resource = ResourceNode::from_canonical_iri(&record.canonical_iri);
169 let Ok(selection) = super::frozen_selection::selection_from_record(&record) else {
170 return false;
171 };
172 let Ok(link) = super::frozen_link::validate_frozen_link_record(&record) else {
173 return false;
174 };
175 if let Some(existing) = self
176 .resource(id)
177 .and_then(|resource| resource.nested_selection())
178 && selection.as_ref() != Some(existing)
179 {
180 return false;
181 }
182 if self
183 .resource(id)
184 .is_some_and(|resource| resource.nested_selection().is_some())
185 {
186 let stored = self.resource_facets.get(
187 &id,
188 &chartulary::FacetId::new(super::frozen_selection::FROZEN_SELECTION),
189 );
190 let incoming = record
191 .facets
192 .iter()
193 .find(|facet| facet.facet == super::frozen_selection::FROZEN_SELECTION)
194 .and_then(|facet| {
195 serde_json::from_str::<serde_json::Value>(&facet.value_json).ok()
196 });
197 if stored != incoming.as_ref() {
198 return false;
199 }
200 }
201 if let Some(existing) = self
202 .resource(id)
203 .and_then(|resource| resource.nested_link())
204 && link.as_ref() != Some(existing)
205 {
206 return false;
207 }
208 if self
209 .resource(id)
210 .is_some_and(|resource| resource.nested_link().is_some())
211 {
212 let stored = self.resource_facets.get(
213 &id,
214 &chartulary::FacetId::new(super::frozen_link::FROZEN_LINK),
215 );
216 let incoming = record
217 .facets
218 .iter()
219 .find(|facet| facet.facet == super::frozen_link::FROZEN_LINK)
220 .and_then(|facet| {
221 serde_json::from_str::<serde_json::Value>(&facet.value_json).ok()
222 });
223 if stored != incoming.as_ref() {
224 return false;
225 }
226 }
227 resource.nested_selection = selection;
228 resource.nested_link = link;
229 if resource.id() != id {
230 return false;
231 }
232 if super::predicate_declarations::predicate_declarations_from_record(&record).is_err() {
233 return false;
234 }
235 if super::resource_content::validate_content_record(&record).is_err() {
236 return false;
237 }
238 let mut facets = std::collections::BTreeMap::new();
239 for facet in record.facets {
240 let Ok(value) = serde_json::from_str::<serde_json::Value>(&facet.value_json) else {
241 return false;
242 };
243 if facets
244 .insert(chartulary::FacetId::new(facet.facet), value)
245 .is_some()
246 {
247 return false;
248 }
249 }
250 if self
251 .resource(id)
252 .is_some_and(|existing| existing == &resource)
253 && self
254 .resource_facets
255 .facets_of(&id)
256 .map(|values| {
257 values
258 .iter()
259 .map(|(key, value)| (key.clone(), value.clone()))
260 .collect::<std::collections::BTreeMap<_, _>>()
261 })
262 .unwrap_or_default()
263 == facets
264 {
265 return false;
266 }
267 self.resources.insert(resource);
268 self.resource_facets.remove_node(&id);
269 for (facet, value) in facets {
270 self.resource_facets
271 .set(id, facet, value, &chartulary::AcceptAll)
272 .expect("permissive facet validator");
273 }
274 self.bump_revision();
275 true
276 }
277
278 pub fn appearance_admission_revision(&self) -> u64 {
281 self.appearance_admission_revision
282 }
283
284 pub(crate) fn set_shown_resource(&mut self, surface: Uuid, resource: Option<Uuid>) -> bool {
285 if self.inner.key_of(&surface).is_none()
286 || resource.is_some_and(|id| self.resource(id).is_none())
287 {
288 return false;
289 }
290 if self.shown_resources.get(&surface).copied() == resource {
291 return false;
292 }
293 if let Some(resource) = resource {
294 self.shown_resources.insert(surface, resource);
295 self.appearance_admission_revision = self.appearance_admission_revision.wrapping_add(1);
296 } else {
297 self.shown_resources.remove(&surface);
298 }
299 self.bump_revision();
300 true
301 }
302
303 pub(crate) fn persisted_resource_edges_between(
304 &self,
305 from: Uuid,
306 to: Uuid,
307 ) -> Vec<PersistedEdge> {
308 let (Some(source), Some(target)) =
309 (self.resources.key_of(&from), self.resources.key_of(&to))
310 else {
311 return Vec::new();
312 };
313 self.resources
314 .inner()
315 .edges_connecting(source, target)
316 .map(|edge| super::snapshot::persisted_edge_for_ids(from, to, edge.weight()))
317 .collect()
318 }
319
320 pub(crate) fn set_resource_edges_between(
321 &mut self,
322 from: Uuid,
323 to: Uuid,
324 edges: &[PersistedEdge],
325 ) -> bool {
326 let (Some(source), Some(target)) =
327 (self.resources.key_of(&from), self.resources.key_of(&to))
328 else {
329 return false;
330 };
331 if !super::edge_admission::resource_rows_wellformed(from, to, edges) {
332 return false;
333 }
334 let mut statements = std::collections::BTreeMap::new();
335 for statement in edges.iter().flat_map(|edge| edge.retained_assertions()) {
336 if let Some(previous) = statements.insert(&statement.statement_id, statement)
337 && previous != statement
338 {
339 return false;
340 }
341 }
342 for edge in self.resources.inner().edge_references() {
343 if edge.source() == source && edge.target() == target {
344 continue;
345 }
346 if edge
347 .weight()
348 .assertions()
349 .iter()
350 .any(|statement| statements.contains_key(&statement.statement_id))
351 {
352 return false;
353 }
354 }
355 if self.inner.inner().edge_weights().any(|edge| {
356 edge.assertions()
357 .iter()
358 .any(|statement| statements.contains_key(&statement.statement_id))
359 }) {
360 return false;
361 }
362 let payloads: Vec<_> = edges
363 .iter()
364 .enumerate()
365 .map(|(ordinal, edge)| {
366 super::snapshot::payload_from_persisted_at(
367 edge,
368 super::GraphStratum::Resource,
369 ordinal,
370 )
371 })
372 .collect();
373 let current: Vec<_> = self
374 .resources
375 .inner()
376 .edges_connecting(source, target)
377 .map(|edge| edge.weight())
378 .collect();
379 if current.len() == payloads.len()
380 && current.iter().zip(&payloads).all(|(old, new)| *old == new)
381 {
382 return false;
383 }
384 let old: Vec<_> = self
385 .resources
386 .inner()
387 .edges_connecting(source, target)
388 .map(|edge| edge.id())
389 .collect();
390 for edge in old {
391 self.resources.disconnect(edge);
392 }
393 for payload in payloads.into_iter().rev() {
394 self.resources.connect(source, target, payload);
395 }
396 self.bump_revision();
397 true
398 }
399}
400
401impl Identified for ResourceNode {
402 type Id = Uuid;
403
404 fn id(&self) -> &Uuid {
405 &self.container.id
406 }
407}
408
409impl Addressed for ResourceNode {
410 fn addresses(&self) -> Vec<Address> {
411 self.container.addresses.clone()
412 }
413}
414
415#[cfg(test)]
416mod tests {
417 use super::*;
418 use crate::graph::{Graph, SurfaceNode};
419
420 fn record(iri: &str, value_json: &str) -> PersistedResourceRecord {
421 PersistedResourceRecord {
422 canonical_iri: chartulary::canonical_url(iri),
423 facets: vec![PersistedResourceFacet {
424 facet: "test.content".into(),
425 value_json: value_json.into(),
426 }],
427 }
428 }
429
430 #[test]
431 fn resource_record_validation_is_atomic_and_replacement_clears_old_facets() {
432 let mut graph = Graph::new();
433 let iri = "https://example.com/resource";
434 let id = chartulary::resource_id(iri);
435 let original = record(iri, "{\"title\":\"original\"}");
436 assert!(graph.set_resource_record(id, Some(original.clone())));
437 assert_eq!(graph.resource_record(id), Some(original.clone()));
438 assert!(!graph.set_resource_record(id, Some(original.clone())));
439 assert!(!graph.set_resource_record(Uuid::nil(), Some(original.clone())));
440 assert!(!graph.set_resource_record(id, Some(record(iri, "invalid JSON"))));
441 let mut duplicate = original.clone();
442 duplicate.facets.push(duplicate.facets[0].clone());
443 assert!(!graph.set_resource_record(id, Some(duplicate)));
444 assert_eq!(graph.resource_record(id), Some(original));
445 assert!(graph.set_resource_record(
446 id,
447 Some(PersistedResourceRecord {
448 canonical_iri: iri.into(),
449 facets: vec![]
450 })
451 ));
452 assert!(graph.resource_record(id).unwrap().facets.is_empty());
453 assert!(graph.set_resource_record(id, None));
454 assert!(graph.resource(id).is_none());
455 assert!(graph.resource_facets.facets_of(&id).is_none());
456 }
457
458 #[test]
459 fn shown_resource_is_explicit_and_references_guard_inverse_creation() {
460 let mut graph = Graph::new();
461 let first = graph.add_node(
462 "https://example.com/page".into(),
463 euclid::default::Point2D::new(0.0, 0.0),
464 );
465 let second = graph.add_node(
466 "https://example.com/page#part".into(),
467 euclid::default::Point2D::new(1.0, 0.0),
468 );
469 let surface = graph.get_node(first).unwrap().id;
470 let alias = graph.get_node(second).unwrap().id;
471 let id = chartulary::resource_id("https://example.com/page");
472 assert!(graph.shown_resource_id(first).is_none());
473 assert!(!graph.set_shown_resource(surface, Some(id)));
474 assert!(graph.set_resource_record(id, Some(record("https://example.com/page", "null"))));
475 assert!(graph.set_shown_resource(surface, Some(id)));
476 assert!(graph.set_shown_resource(alias, Some(id)));
477 let mut expected = vec![surface, alias];
478 expected.sort();
479 assert_eq!(graph.surface_ids_showing_resource(id), expected);
480 assert!(!graph.set_shown_resource(surface, Some(id)));
481 assert!(!graph.set_resource_record(id, None));
482 assert!(graph.remove_node(first));
483 assert_eq!(graph.surface_ids_showing_resource(id), vec![alias]);
484 assert!(graph.set_shown_resource(alias, None));
485 assert!(graph.set_resource_record(id, None));
486 }
487
488 #[test]
489 fn resource_pair_rejects_conflicting_handles_before_replacing_truth() {
490 use crate::graph::{EdgePayload, SemanticStatement, SemanticSubKind};
491 let mut graph = Graph::new();
492 let ids: Vec<_> = ["https://a.test/", "https://b.test/", "https://c.test/"]
493 .into_iter()
494 .map(|iri| {
495 let id = chartulary::resource_id(iri);
496 assert!(graph.set_resource_record(id, Some(record(iri, "null"))));
497 id
498 })
499 .collect();
500 let mut payload = EdgePayload::new();
501 payload.push_persisted_semantic_statement(SemanticStatement {
502 statement_id: "stable-handle".into(),
503 predicate: crate::graph::predicate_iri(SemanticSubKind::Cites).into(),
504 recognized_sub_kind: Some(SemanticSubKind::Cites),
505 label: Some("original".into()),
506 graph_scope: crate::types::GraphScope::Default,
507 provenance_iri: Some("https://alice.test/".into()),
508 asserted_at_ms: Some(17),
509 first_asserted_ms: Some(17),
510 withdrawn: None,
511 basis: Default::default(),
512 });
513 let original = super::super::snapshot::persisted_edge_for_ids(ids[0], ids[1], &payload);
514 let mut aggregate_only = original.clone();
515 aggregate_only.assertions = None;
516 aggregate_only.semantic = Some(Default::default());
517 aggregate_only.semantic.as_mut().unwrap().sub_kinds =
518 vec![crate::persistence::PersistedSemanticSubKind::Cites];
519 assert!(!graph.set_resource_edges_between(ids[0], ids[1], &[aggregate_only.clone()]));
520 assert!(!graph.set_resource_edges_between(ids[0], ids[1], &[aggregate_only]));
521 assert!(
522 graph
523 .persisted_resource_edges_between(ids[0], ids[1])
524 .is_empty()
525 );
526 assert!(graph.set_resource_edges_between(ids[0], ids[1], &[original.clone()]));
527 assert!(!graph.set_resource_edges_between(ids[0], ids[1], &[original.clone()]));
528 let mut conflicting = original.clone();
529 conflicting.retained_assertions_mut()[0].label = Some("conflict".into());
530 assert!(!graph.set_resource_edges_between(
531 ids[0],
532 ids[1],
533 &[original.clone(), conflicting]
534 ));
535 assert_eq!(
536 graph.persisted_resource_edges_between(ids[0], ids[1]),
537 vec![original.clone()]
538 );
539 let mut other_pair = original.clone();
540 other_pair.to_node_id = ids[2].to_string();
541 assert!(!graph.set_resource_edges_between(ids[0], ids[2], &[other_pair.clone()]));
542 assert!(
543 graph
544 .persisted_resource_edges_between(ids[0], ids[2])
545 .is_empty()
546 );
547 other_pair.retained_assertions_mut()[0].statement_id = "other-handle".into();
548 assert!(graph.set_resource_edges_between(ids[0], ids[2], &[other_pair.clone()]));
549 assert_eq!(
550 graph.persisted_resource_edges_between(ids[0], ids[2]),
551 vec![other_pair.clone()]
552 );
553 let first = graph.add_node(
554 "https://surface.test/a".into(),
555 euclid::default::Point2D::new(0.0, 0.0),
556 );
557 let second = graph.add_node(
558 "https://surface.test/b".into(),
559 euclid::default::Point2D::new(1.0, 0.0),
560 );
561 let mut collision = other_pair.clone();
562 collision.retained_assertions_mut()[0].statement_id = "surface-handle".into();
563 graph.inner.connect(
564 first,
565 second,
566 super::super::snapshot::payload_from_persisted(&collision),
567 );
568 assert!(!graph.set_resource_edges_between(ids[0], ids[2], &[collision.clone()]));
569 assert_eq!(
570 graph.persisted_resource_edges_between(ids[0], ids[2]),
571 vec![other_pair]
572 );
573 collision.retained_assertions_mut()[0].statement_id = "fresh-resource-handle".into();
574 assert!(graph.set_resource_edges_between(ids[0], ids[2], &[collision.clone()]));
575 assert_eq!(
576 graph.persisted_resource_edges_between(ids[0], ids[2]),
577 vec![collision]
578 );
579 assert!(!graph.set_resource_record(ids[0], None));
580 assert!(graph.set_resource_edges_between(ids[0], ids[1], &[]));
581 assert!(graph.set_resource_edges_between(ids[0], ids[2], &[]));
582 assert!(graph.set_resource_record(ids[0], None));
583 }
584
585 #[test]
586 fn resource_identity_is_common_and_canonical_without_renumbering_surfaces() {
587 let iri = "https://example.com/page?id=7";
588 let alias = "https://EXAMPLE.COM:443/page?utm_source=news&id=7#part";
589 let resource = ResourceNode::new(alias);
590 assert_eq!(resource.canonical_iri(), iri);
591 assert_eq!(resource.id(), chartulary::resource_id(iri));
592 assert_eq!(*Identified::id(&resource), resource.id());
593 assert_eq!(resource.primary_address(), Some(Address::new(iri)));
594 assert_eq!(resource, ResourceNode::new(iri));
595 assert_ne!(
596 resource.id(),
597 ResourceNode::new("https://example.com/page?id=8").id()
598 );
599 assert_ne!(resource.id(), Graph::node_namespace_id(iri));
600
601 let first = SurfaceNode::test_stub(iri);
602 let second = SurfaceNode::test_stub(alias);
603 assert_ne!(first.id, second.id);
604 assert_eq!(
605 ResourceNode::new(first.url()),
606 ResourceNode::new(second.url())
607 );
608 }
609
610 #[test]
611 fn vocabulary_term_identity_preserves_fragments_query_and_case() {
612 let cat = ResourceNode::for_term("https://vocab.test/concepts#Cat");
613 for iri in [
614 "https://vocab.test/concepts#Dog",
615 "https://vocab.test/concepts#cat",
616 "https://VOCAB.test/concepts#Cat",
617 "https://vocab.test/concepts?edition=1#Cat",
618 ] {
619 let term = ResourceNode::for_term(iri);
620 assert_eq!(term.canonical_iri(), iri);
621 assert_eq!(term.id(), chartulary::resource_id_from_canonical_iri(iri));
622 assert_ne!(term.id(), cat.id());
623 }
624 assert_eq!(cat, ResourceNode::for_term(cat.canonical_iri()));
625 assert_eq!(
626 ResourceNode::new("https://vocab.test/concepts#Cat"),
627 ResourceNode::new("https://VOCAB.test:443/concepts#Dog")
628 );
629 assert_ne!(cat.id(), ResourceNode::new(cat.canonical_iri()).id());
630 }
631
632 #[test]
633 fn exact_term_records_and_resource_edge_endpoints_survive_checked_load() {
634 use crate::graph::{EdgePayload, SemanticStatement, SemanticSubKind};
635 let mut graph = Graph::new();
636 let terms = [
637 ResourceNode::for_term("https://vocab.test/concepts#Cat"),
638 ResourceNode::for_term("https://vocab.test/concepts#Dog"),
639 ];
640 for term in &terms {
641 assert!(graph.set_resource_record(
642 term.id(),
643 Some(PersistedResourceRecord {
644 canonical_iri: term.canonical_iri().into(),
645 facets: vec![],
646 })
647 ));
648 }
649 let mut payload = EdgePayload::new();
650 payload.push_persisted_semantic_statement(SemanticStatement {
651 statement_id: "exact-vocabulary-assertion".into(),
652 predicate: crate::graph::predicate_iri(SemanticSubKind::SameEntityAs).into(),
653 recognized_sub_kind: Some(SemanticSubKind::SameEntityAs),
654 label: None,
655 graph_scope: crate::types::GraphScope::Default,
656 provenance_iri: Some("https://author.test/".into()),
657 asserted_at_ms: Some(19),
658 first_asserted_ms: Some(19),
659 withdrawn: None,
660 basis: Default::default(),
661 });
662 let edge =
663 super::super::snapshot::persisted_edge_for_ids(terms[0].id(), terms[1].id(), &payload);
664 assert!(graph.set_resource_edges_between(terms[0].id(), terms[1].id(), &[edge]));
665 let restored = Graph::try_from_snapshot(&graph.to_snapshot()).unwrap();
666 for term in &terms {
667 assert_eq!(restored.resource(term.id()), Some(term));
668 }
669 let edges: Vec<_> = restored.resource_edges().collect();
670 assert_eq!(edges.len(), 1);
671 assert_eq!(edges[0].0, &terms[0]);
672 assert_eq!(edges[0].1, &terms[1]);
673 assert_eq!(edges[0].2, &payload);
674 assert_eq!(
675 restored.edge_count(),
676 0,
677 "resource edges do not create surface edges"
678 );
679 }
680
681 #[test]
682 fn chartulary_indexes_resources_by_the_shared_identity() {
683 let mut graph = chartulary::Graph::<ResourceNode, ()>::new();
684 let first = graph.insert(ResourceNode::new("https://example.com/page"));
685 let alias = graph.insert(ResourceNode::new("https://EXAMPLE.COM/page#part"));
686 assert_eq!(first, alias);
687 assert_eq!(graph.node_count(), 1);
688 let other = graph.insert(ResourceNode::new("https://example.com/other"));
689 assert_ne!(first, other);
690 assert_eq!(graph.node_count(), 2);
691 let clone = graph.clone();
692 assert_eq!(
693 clone.get(&chartulary::resource_id("https://example.com/page")),
694 graph.node(first)
695 );
696 assert_eq!(
697 clone.get(&chartulary::resource_id("https://example.com/other")),
698 graph.node(other)
699 );
700 }
701}