Skip to main content

kernel/graph/
legacy_content_migration.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//! Historical content placement alongside the legacy relation adapter.
8
9use super::legacy_resource_migration::LegacyMigrationError;
10use super::resource_classifications::{ClassificationOrigin, ClassificationVariant};
11use super::resource_content::{RESOURCE_CLASSIFICATIONS, RESOURCE_PROPERTIES};
12use super::resource_tags::{TagConcept, tag_concept_iri};
13use super::{Author, CapturedDelta, Graph, ResourceNode, SemanticStatement};
14use crate::persistence::PersistedResourceRecord;
15use crate::types::{GraphScope, NodeProperty};
16use serde::{Deserialize, Serialize};
17use std::collections::{BTreeMap, BTreeSet};
18use uuid::Uuid;
19
20/// Stable identity of the source mere, required only for unattributed tag concepts.
21#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
22pub struct LegacyContentContext {
23    pub original_mere_iri: String,
24}
25
26pub const LEGACY_CONTENT_ORIGINS: &str = "semantic.legacy-content-origins/v1";
27#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
28pub struct LegacyContentOrigin {
29    pub kind: String,
30    pub record_id: String,
31    pub surface_id: Uuid,
32    pub original_url: String,
33    pub author: Option<Author>,
34    pub uncertainty: Option<String>,
35    pub original: serde_json::Value,
36}
37
38type TagKey = (Uuid, String);
39type ClassKey = (Uuid, String, String);
40#[derive(Clone)]
41struct TagMember {
42    resource: Uuid,
43    concept: Uuid,
44    handle: String,
45}
46#[derive(Clone)]
47struct ClassMember {
48    resource: Uuid,
49    variant: String,
50}
51#[derive(Default)]
52pub(crate) struct ContentReplay {
53    properties: BTreeMap<String, Uuid>,
54    active_properties: BTreeMap<(Uuid, String), Uuid>,
55    tags: BTreeMap<TagKey, TagMember>,
56    classes: BTreeMap<ClassKey, ClassMember>,
57    retired: BTreeSet<(Uuid, String)>,
58    retired_tag_handles: BTreeSet<String>,
59}
60
61impl ContentReplay {
62    pub(crate) fn typed_record(&mut self, delta: &CapturedDelta) {
63        if let CapturedDelta::ReplaySetResourceEdgesByIds {
64            from_resource_id,
65            to_resource_id,
66            ..
67        } = delta
68            && let (Ok(from), Ok(to)) = (
69                Uuid::parse_str(from_resource_id),
70                Uuid::parse_str(to_resource_id),
71            )
72        {
73            for member in self
74                .tags
75                .values()
76                .filter(|member| member.resource == from && member.concept == to)
77            {
78                self.retired_tag_handles.insert(member.handle.clone());
79            }
80        }
81        if let CapturedDelta::ReplaySetResourceRecordById {
82            resource_id,
83            record: Some(record),
84        } = delta
85            && let Ok(id) = Uuid::parse_str(resource_id)
86        {
87            for facet in &record.facets {
88                if facet.facet == RESOURCE_PROPERTIES || facet.facet == RESOURCE_CLASSIFICATIONS {
89                    self.retired.insert((id, facet.facet.clone()));
90                }
91            }
92        }
93    }
94
95    pub(crate) fn sync(
96        &mut self,
97        source: &Graph,
98        output: &mut Graph,
99        context: Option<&LegacyContentContext>,
100        author: Option<&Author>,
101    ) -> Result<(), LegacyMigrationError> {
102        // Remove the retained Surface assertions before admitting their exact
103        // Resource handles. The original source and receipt remain unchanged.
104        for (key, node) in source.nodes() {
105            if let Some(output_key) = output.get_node_key_by_id(node.id) {
106                if !source
107                    .legacy_node_properties(key)
108                    .unwrap_or_default()
109                    .is_empty()
110                {
111                    output.set_node_facet(
112                        output_key,
113                        super::node_facets::SEMANTIC_PROPERTIES,
114                        &Vec::<NodeProperty>::new(),
115                    );
116                }
117                if !source
118                    .legacy_node_classifications(key)
119                    .unwrap_or_default()
120                    .is_empty()
121                {
122                    output.set_node_facet(
123                        output_key,
124                        super::node_facets::SEMANTIC_CLASSIFICATIONS,
125                        &Vec::<crate::types::NodeClassification>::new(),
126                    );
127                }
128            }
129        }
130        let mut present_props = BTreeMap::new();
131        let mut present_tags = BTreeSet::new();
132        let mut present_classes = BTreeSet::new();
133        for (key, node) in source.nodes() {
134            let surface = node.id;
135            let raw_url = node.primary_address().as_url_str();
136            let props = source.legacy_node_properties(key).unwrap_or_default();
137            let classes = source.legacy_node_classifications(key).unwrap_or_default();
138            if node.tags.is_empty() && props.is_empty() && classes.is_empty() {
139                continue;
140            }
141            let resource = ResourceNode::new(raw_url);
142            if output.resource(resource.id()).is_none() {
143                let record = PersistedResourceRecord {
144                    canonical_iri: resource.canonical_iri().into(),
145                    facets: vec![],
146                };
147                if !output.set_resource_record(resource.id(), Some(record)) {
148                    return Err(error("content Resource insertion refused"));
149                }
150            }
151            if let Some(output_key) = output.get_node_key_by_id(surface) {
152                if output.shown_resource_id(output_key).is_none() {
153                    output.set_shown_resource(surface, Some(resource.id()));
154                }
155            }
156            for mut property in props {
157                let original = serde_json::to_value(&property).expect("property serializes");
158                let id = property.statement_id.clone();
159                let owner = *self.properties.entry(id.clone()).or_insert(resource.id());
160                if self.active_properties.contains_key(&(surface, id.clone())) == false
161                    && owner != resource.id()
162                    && self.active_properties.keys().any(|(_, held)| held == &id)
163                {
164                    return Err(error("legacy literal handle reused by another Resource"));
165                }
166                if self.retired.contains(&(owner, RESOURCE_PROPERTIES.into())) {
167                    continue;
168                }
169                if let Some(existing_owner) = present_props.insert((surface, id.clone()), owner)
170                    && existing_owner != owner
171                {
172                    return Err(error("literal ownership conflict"));
173                }
174                let mut held = output.resource_properties(owner);
175                if property.provenance_iri.is_none() {
176                    property.provenance_iri = held
177                        .iter()
178                        .find(|existing| existing.statement_id == id)
179                        .and_then(|existing| existing.provenance_iri.clone())
180                        .or_else(|| {
181                            Some(author.map(Author::asserter_iri).unwrap_or_else(|| {
182                                super::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI.into()
183                            }))
184                        });
185                }
186                if let Some(existing) = held.iter_mut().find(|entry| entry.statement_id == id) {
187                    if !existing.content_eq(&property) {
188                        return Err(error("legacy literal handle changed content"));
189                    }
190                    existing.asserted_at_ms = property.asserted_at_ms;
191                } else {
192                    held.push(property.clone());
193                }
194                output
195                    .write_resource_content(owner, RESOURCE_PROPERTIES, &held)
196                    .map_err(content_error)?;
197                self.note(
198                    output,
199                    owner,
200                    LegacyContentOrigin {
201                        kind: "literal".into(),
202                        record_id: id,
203                        surface_id: surface,
204                        original_url: raw_url.into(),
205                        author: author.cloned(),
206                        uncertainty: uncertainty(author),
207                        original,
208                    },
209                )?;
210            }
211            for tag in &node.tags {
212                let tag_key = (surface, tag.clone());
213                present_tags.insert(tag_key.clone());
214                if !self.tags.contains_key(&tag_key) {
215                    let owner_iri = match author {
216                        Some(author) => author.asserter_iri(),
217                        None => context.map(|context| context.original_mere_iri.clone()).filter(|iri| !iri.is_empty()).ok_or_else(|| error("unattributed legacy tags require stable original-mere content context"))?,
218                    };
219                    let iri = tag_concept_iri(&owner_iri, tag);
220                    let mut statement = SemanticStatement::new(
221                        super::resource::TAGGED_WITH_IRI.into(),
222                        None,
223                        None,
224                        GraphScope::Default,
225                        Some(author.map(Author::asserter_iri).unwrap_or_else(|| {
226                            super::edge_data::UNKNOWN_LEGACY_ASSERTER_IRI.into()
227                        })),
228                        None,
229                    );
230                    let handle_key = serde_json::to_vec(&(surface, resource.id(), &iri))
231                        .expect("key serializes");
232                    statement.statement_id = format!(
233                        "legacy-tag:{}",
234                        Uuid::new_v5(&Uuid::NAMESPACE_URL, &handle_key)
235                    );
236                    let source_iri = statement.provenance_iri.clone();
237                    let mut handle = statement.statement_id.clone();
238                    output
239                        .tag_resource_with_statement(
240                            resource.id(),
241                            &iri,
242                            TagConcept {
243                                owner_iri,
244                                label: tag.clone(),
245                            },
246                            statement,
247                        )
248                        .map_err(content_error)?;
249                    if let Some(existing) = output
250                        .resource_edges()
251                        .filter(|(from, to, _)| {
252                            from.id() == resource.id()
253                                && to.id() == ResourceNode::for_term(&iri).id()
254                        })
255                        .flat_map(|(_, _, payload)| payload.semantic_statements())
256                        .find(|held| {
257                            held.predicate == super::resource::TAGGED_WITH_IRI
258                                && held.provenance_iri == source_iri
259                        })
260                    {
261                        handle = existing.statement_id.clone();
262                    }
263                    self.note(
264                        output,
265                        resource.id(),
266                        LegacyContentOrigin {
267                            kind: "tag".into(),
268                            record_id: handle.clone(),
269                            surface_id: surface,
270                            original_url: raw_url.into(),
271                            author: author.cloned(),
272                            uncertainty: uncertainty(author),
273                            original: serde_json::json!(tag),
274                        },
275                    )?;
276                    self.tags.insert(
277                        tag_key,
278                        TagMember {
279                            resource: resource.id(),
280                            concept: ResourceNode::for_term(&iri).id(),
281                            handle,
282                        },
283                    );
284                }
285            }
286            for classification in classes {
287                let class_key = (
288                    surface,
289                    serde_json::to_string(&classification.scheme).expect("scheme serializes"),
290                    classification.value.clone(),
291                );
292                present_classes.insert(class_key.clone());
293                let member = self
294                    .classes
295                    .entry(class_key.clone())
296                    .or_insert_with(|| {
297                        let encoded = serde_json::to_vec(&(class_key, resource.id()))
298                            .expect("key serializes");
299                        ClassMember {
300                            resource: resource.id(),
301                            variant: format!(
302                                "legacy-classification:{}",
303                                Uuid::new_v5(&Uuid::NAMESPACE_URL, &encoded)
304                            ),
305                        }
306                    })
307                    .clone();
308                if self
309                    .retired
310                    .contains(&(member.resource, RESOURCE_CLASSIFICATIONS.into()))
311                {
312                    continue;
313                }
314                let original =
315                    serde_json::to_value(&classification).expect("classification serializes");
316                let mut variants = output.resource_classification_variants(member.resource);
317                if let Some(existing) = variants
318                    .iter_mut()
319                    .find(|entry| entry.variant_id == member.variant)
320                {
321                    existing.classification = classification;
322                } else {
323                    variants.push(ClassificationVariant {
324                        variant_id: member.variant.clone(),
325                        original_variant_id: None,
326                        classification,
327                        origins: vec![ClassificationOrigin {
328                            surface_id: surface,
329                            author: author.cloned(),
330                            uncertainty: uncertainty(author),
331                        }],
332                    });
333                }
334                output
335                    .write_resource_content(member.resource, RESOURCE_CLASSIFICATIONS, &variants)
336                    .map_err(content_error)?;
337                self.note(
338                    output,
339                    member.resource,
340                    LegacyContentOrigin {
341                        kind: "classification".into(),
342                        record_id: member.variant,
343                        surface_id: surface,
344                        original_url: raw_url.into(),
345                        author: author.cloned(),
346                        uncertainty: uncertainty(author),
347                        original,
348                    },
349                )?;
350            }
351            // Retained originals remain in the source receipt and content-origin ledger.
352            if let Some(output_key) = output.get_node_key_by_id(surface) {
353                if let Some(node) = output.inner.node_mut(output_key) {
354                    node.tags.clear();
355                }
356                output.set_node_facet(
357                    output_key,
358                    super::node_facets::SEMANTIC_PROPERTIES,
359                    &Vec::<NodeProperty>::new(),
360                );
361                output.set_node_facet(
362                    output_key,
363                    super::node_facets::SEMANTIC_CLASSIFICATIONS,
364                    &Vec::<crate::types::NodeClassification>::new(),
365                );
366            }
367        }
368        let remaining_ids: BTreeSet<_> = present_props.keys().map(|(_, id)| id.clone()).collect();
369        for ((_, id), owner) in &self.active_properties {
370            if !remaining_ids.contains(id)
371                && !self.retired.contains(&(*owner, RESOURCE_PROPERTIES.into()))
372            {
373                output
374                    .retract_resource_property(*owner, id)
375                    .map_err(content_error)?;
376            }
377        }
378        self.active_properties = present_props;
379        let removed: Vec<_> = self
380            .tags
381            .keys()
382            .filter(|key| !present_tags.contains(*key))
383            .cloned()
384            .collect();
385        for key in removed {
386            let member = self.tags.remove(&key).expect("key exists");
387            // Typed pair replacements may already have retired this raw assertion.
388            if !self.retired_tag_handles.contains(&member.handle)
389                && !self.tags.values().any(|held| held.handle == member.handle)
390            {
391                output.retract_assertion(&member.handle);
392            }
393        }
394        let removed: Vec<_> = self
395            .classes
396            .keys()
397            .filter(|key| !present_classes.contains(*key))
398            .cloned()
399            .collect();
400        for key in removed {
401            let member = self.classes.remove(&key).expect("key exists");
402            if !self
403                .retired
404                .contains(&(member.resource, RESOURCE_CLASSIFICATIONS.into()))
405            {
406                output
407                    .remove_resource_classification(member.resource, &member.variant)
408                    .map_err(content_error)?;
409            }
410        }
411        Ok(())
412    }
413
414    fn note(
415        &self,
416        output: &mut Graph,
417        id: Uuid,
418        note: LegacyContentOrigin,
419    ) -> Result<(), LegacyMigrationError> {
420        let mut notes: Vec<LegacyContentOrigin> = output
421            .resource_content(id, LEGACY_CONTENT_ORIGINS)
422            .unwrap_or_default();
423        if !notes.iter().any(|existing| {
424            existing.kind == note.kind
425                && existing.record_id == note.record_id
426                && existing.surface_id == note.surface_id
427        }) {
428            notes.push(note);
429            output
430                .write_resource_content(id, LEGACY_CONTENT_ORIGINS, &notes)
431                .map_err(content_error)?;
432        }
433        Ok(())
434    }
435}
436fn uncertainty(author: Option<&Author>) -> Option<String> {
437    author
438        .is_none()
439        .then(|| "baseline minting author and historical URL are unavailable".into())
440}
441fn error(detail: &str) -> LegacyMigrationError {
442    LegacyMigrationError(detail.into())
443}
444fn content_error(error: super::resource_content::ContentError) -> LegacyMigrationError {
445    LegacyMigrationError(error.to_string())
446}
447
448#[cfg(test)]
449#[path = "legacy_content_tests.rs"]
450mod tests;