Skip to main content

khive_runtime/
portability.rs

1//! KG export / import — portable JSON archive for namespace-scoped knowledge graphs.
2//!
3//! Embeddings are excluded (regenerable from text + model). Edges are collected by
4//! querying all entity IDs in the namespace first, then fetching incident edges.
5
6use std::collections::HashSet;
7
8use chrono::{DateTime, Utc};
9use serde::{Deserialize, Serialize};
10use uuid::Uuid;
11
12use khive_storage::types::{EdgeFilter, LinkId, PageRequest};
13use khive_storage::{EdgeRelation, EntityFilter};
14
15use crate::error::{RuntimeError, RuntimeResult};
16use crate::runtime::{KhiveRuntime, NamespaceToken};
17
18// ── Archive types ─────────────────────────────────────────────────────────────
19
20/// Portable JSON archive of a namespace-scoped knowledge graph.
21///
22/// The `format` field is always `"khive-kg"`. The `version` field identifies
23/// the serialization schema; parsers should reject unknown versions.
24#[derive(Clone, Debug, Serialize, Deserialize)]
25pub struct KgArchive {
26    pub format: String,
27    pub version: String,
28    pub namespace: String,
29    pub exported_at: DateTime<Utc>,
30    pub entities: Vec<ExportedEntity>,
31    pub edges: Vec<ExportedEdge>,
32}
33
34/// An entity record in the portable archive.
35#[derive(Clone, Debug, Serialize, Deserialize)]
36pub struct ExportedEntity {
37    pub id: Uuid,
38    /// Pack-owned kind string (e.g. `"concept"`, `"person"`).
39    pub kind: String,
40    /// Pack-governed subtype token (e.g. `"paper"`, `"snapshot"`).
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub entity_type: Option<String>,
43    pub name: String,
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub description: Option<String>,
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub properties: Option<serde_json::Value>,
48    #[serde(default)]
49    pub tags: Vec<String>,
50    pub created_at: DateTime<Utc>,
51    pub updated_at: DateTime<Utc>,
52}
53
54/// A directed edge record in the portable archive.
55#[derive(Clone, Debug, Serialize, Deserialize)]
56pub struct ExportedEdge {
57    /// Stable edge identity across export/import cycles.
58    ///
59    /// Old archives (pre-0.2) omit this field. `serde(default)` assigns a fresh
60    /// UUID on import so backward-compatible archives are accepted as-is.
61    #[serde(default = "Uuid::new_v4")]
62    pub edge_id: Uuid,
63    pub source: Uuid,
64    pub target: Uuid,
65    /// One of the canonical edge relations (closed enum).
66    pub relation: EdgeRelation,
67    pub weight: f64,
68}
69
70/// Outcome of a successful import operation.
71#[derive(Clone, Debug, Serialize, Deserialize)]
72pub struct ImportSummary {
73    pub entities_imported: usize,
74    pub edges_imported: usize,
75    /// Number of edges that were skipped because one or both endpoint UUIDs
76    /// were not found in the target namespace after entity import.
77    ///
78    /// A non-zero value indicates the archive contained dangling edges (edges
79    /// referencing entities not present in the archive or the existing graph).
80    pub edges_skipped: usize,
81    /// Aggregate actual outcomes from reindexing imported entities. Source
82    /// text remains complete in the entity store and FTS when this is non-zero.
83    #[serde(default)]
84    pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
85}
86
87// ── KhiveRuntime impl ─────────────────────────────────────────────────────────
88
89impl KhiveRuntime {
90    /// Export all entities and edges in a namespace to a portable JSON archive.
91    ///
92    /// Edge collection: all entity IDs in the namespace are gathered first;
93    /// `query_edges` is then called with those IDs as `source_ids`. This
94    /// captures every edge whose source entity belongs to the namespace.
95    pub async fn export_kg(&self, token: &NamespaceToken) -> RuntimeResult<KgArchive> {
96        let ns = token.namespace().as_str().to_owned();
97
98        let entity_page = self
99            .entities(token)?
100            .query_entities(
101                &ns,
102                EntityFilter::default(),
103                PageRequest {
104                    offset: 0,
105                    limit: u32::MAX,
106                },
107            )
108            .await?;
109
110        let entities: Vec<ExportedEntity> = entity_page
111            .items
112            .into_iter()
113            .map(|e| {
114                let created_at =
115                    DateTime::from_timestamp_micros(e.created_at).unwrap_or_else(Utc::now);
116                let updated_at =
117                    DateTime::from_timestamp_micros(e.updated_at).unwrap_or_else(Utc::now);
118                ExportedEntity {
119                    id: e.id,
120                    kind: e.kind.to_string(),
121                    entity_type: e.entity_type,
122                    name: e.name,
123                    description: e.description,
124                    properties: e.properties,
125                    tags: e.tags,
126                    created_at,
127                    updated_at,
128                }
129            })
130            .collect();
131
132        let source_ids: Vec<Uuid> = entities.iter().map(|e| e.id).collect();
133        let edges = if source_ids.is_empty() {
134            Vec::new()
135        } else {
136            let filter = EdgeFilter {
137                source_ids: source_ids.clone(),
138                ..Default::default()
139            };
140            let edge_page = self
141                .graph(token)?
142                .query_edges(
143                    filter,
144                    Vec::new(),
145                    PageRequest {
146                        offset: 0,
147                        limit: u32::MAX,
148                    },
149                )
150                .await?;
151
152            let id_set: HashSet<Uuid> = source_ids.into_iter().collect();
153            edge_page
154                .items
155                .into_iter()
156                .filter(|e| id_set.contains(&e.source_id))
157                .map(|e| ExportedEdge {
158                    edge_id: e.id.into(),
159                    source: e.source_id,
160                    target: e.target_id,
161                    relation: e.relation,
162                    weight: e.weight,
163                })
164                .collect()
165        };
166
167        Ok(KgArchive {
168            format: "khive-kg".to_string(),
169            version: "0.1".to_string(),
170            namespace: ns,
171            exported_at: Utc::now(),
172            entities,
173            edges,
174        })
175    }
176
177    /// Export to a JSON string (convenience wrapper around `export_kg`).
178    pub async fn export_kg_json(&self, token: &NamespaceToken) -> RuntimeResult<String> {
179        let archive = self.export_kg(token).await?;
180        serde_json::to_string(&archive).map_err(|e| RuntimeError::InvalidInput(e.to_string()))
181    }
182
183    /// Import an archive into `target_namespace`.
184    ///
185    /// If `target_namespace` is `None`, the archive's own namespace is used.
186    ///
187    /// - Entities: upserted by ID; existing records are overwritten.
188    /// - Edges: upserted; existing records are overwritten.
189    /// - Validation: `format != "khive-kg"` or unsupported version → `InvalidInput`.
190    ///   Invalid edge relations are caught at JSON deserialization time.
191    pub async fn import_kg(
192        &self,
193        archive: &KgArchive,
194        token: &NamespaceToken,
195    ) -> RuntimeResult<ImportSummary> {
196        if archive.format != "khive-kg" {
197            return Err(RuntimeError::InvalidInput(format!(
198                "unsupported archive format {:?}; expected \"khive-kg\"",
199                archive.format
200            )));
201        }
202        if archive.version != "0.1" {
203            return Err(RuntimeError::InvalidInput(format!(
204                "unsupported archive version {:?}; supported: \"0.1\"",
205                archive.version
206            )));
207        }
208
209        let ns = token.namespace().as_str().to_owned();
210
211        let store = self.entities(token)?;
212        let mut entities_imported = 0usize;
213        let mut embedding_truncation = crate::retrieval::EmbeddingTruncationReport::default();
214        for ee in &archive.entities {
215            self.validate_entity_kind(&ee.kind)?;
216            let created_micros = ee.created_at.timestamp_micros();
217            let updated_micros = ee.updated_at.timestamp_micros();
218            let entity = khive_storage::entity::Entity {
219                id: ee.id,
220                namespace: ns.clone(),
221                kind: ee.kind.clone(),
222                entity_type: ee.entity_type.clone(),
223                name: ee.name.clone(),
224                description: ee.description.clone(),
225                properties: ee.properties.clone(),
226                tags: ee.tags.clone(),
227                created_at: created_micros,
228                updated_at: updated_micros,
229                deleted_at: None,
230                merged_into: None,
231                merge_event_id: None,
232                content_ref: None,
233            };
234            store.upsert_entity(entity.clone()).await?;
235            // Reindex so imported entities are searchable via hybrid_search immediately.
236            embedding_truncation.merge(self.reindex_entity(token, &entity).await?);
237            entities_imported += 1;
238        }
239
240        // Untrusted archives may reference entities absent from the target namespace;
241        // check both endpoints and skip edges with a missing source or target to avoid
242        // dangling references in the graph store.
243        let graph = self.graph(token)?;
244        let mut edges_imported = 0usize;
245        let mut edges_skipped = 0usize;
246        for ee in &archive.edges {
247            crate::operations::validate_edge_weight(ee.weight)?;
248            let source_ok = match self.get_entity(token, ee.source).await {
249                Ok(_) => true,
250                Err(RuntimeError::NotFound(_)) => false,
251                Err(e) => return Err(e),
252            };
253            if !source_ok {
254                tracing::warn!(
255                    source = %ee.source,
256                    target = %ee.target,
257                    relation = ?ee.relation,
258                    "import_kg: skipping edge — source entity not found in namespace {ns:?}"
259                );
260                edges_skipped += 1;
261                continue;
262            }
263            let target_ok = match self.get_entity(token, ee.target).await {
264                Ok(_) => true,
265                Err(RuntimeError::NotFound(_)) => false,
266                Err(e) => return Err(e),
267            };
268            if !target_ok {
269                tracing::warn!(
270                    source = %ee.source,
271                    target = %ee.target,
272                    relation = ?ee.relation,
273                    "import_kg: skipping edge — target entity not found in namespace {ns:?}"
274                );
275                edges_skipped += 1;
276                continue;
277            }
278            // Only a contract verdict (InvalidInput) or an endpoint-resolution
279            // miss (NotFound) is a property of the edge being imported; any
280            // other error is an operational failure of the check itself and
281            // must abort the import rather than silently discard a valid edge.
282            match self
283                .validate_edge_relation_endpoints(token, ee.source, ee.target, ee.relation)
284                .await
285            {
286                Ok(()) => {}
287                Err(e @ (RuntimeError::InvalidInput(_) | RuntimeError::NotFound(_))) => {
288                    tracing::warn!(
289                        source = %ee.source,
290                        target = %ee.target,
291                        relation = ?ee.relation,
292                        error = %e,
293                        "import_kg: skipping edge — endpoint contract violation in namespace {ns:?}"
294                    );
295                    edges_skipped += 1;
296                    continue;
297                }
298                Err(e) => return Err(e),
299            }
300            let now = Utc::now();
301            let edge = khive_storage::types::Edge {
302                id: LinkId::from(ee.edge_id),
303                namespace: ns.clone(),
304                source_id: ee.source,
305                target_id: ee.target,
306                relation: ee.relation,
307                weight: ee.weight,
308                created_at: now,
309                updated_at: now,
310                deleted_at: None,
311                metadata: None,
312                target_backend: None,
313            };
314            graph.upsert_edge(edge).await?;
315            edges_imported += 1;
316        }
317
318        Ok(ImportSummary {
319            entities_imported,
320            edges_imported,
321            edges_skipped,
322            embedding_truncation,
323        })
324    }
325
326    /// Import from a JSON string (convenience wrapper around `import_kg`).
327    pub async fn import_kg_json(
328        &self,
329        json: &str,
330        token: &NamespaceToken,
331    ) -> RuntimeResult<ImportSummary> {
332        let archive: KgArchive =
333            serde_json::from_str(json).map_err(|e| RuntimeError::InvalidInput(e.to_string()))?;
334        self.import_kg(&archive, token).await
335    }
336}
337
338// ── Tests ─────────────────────────────────────────────────────────────────────
339
340// Kept inline: these tests exercise round-trip invariants over private encoding
341// helpers that would otherwise need to be made pub to test from tests/.
342#[cfg(test)]
343mod tests {
344    use std::sync::Arc;
345
346    use super::*;
347    use crate::runtime::{KhiveRuntime, NamespaceToken};
348    use crate::{EmbedderProvider, Namespace};
349    use async_trait::async_trait;
350    use khive_storage::EdgeRelation;
351    use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService, MAX_TEXT_CHARS};
352
353    const IMPORT_TEST_MODEL: &str = "all-minilm-l6-v2";
354
355    struct ImportEmbeddingService;
356
357    #[async_trait]
358    impl EmbeddingService for ImportEmbeddingService {
359        async fn embed(
360            &self,
361            texts: &[String],
362            _model: EmbeddingModel,
363        ) -> std::result::Result<Vec<Vec<f32>>, EmbedError> {
364            let dimensions = EmbeddingModel::AllMiniLmL6V2.dimensions();
365            Ok(texts.iter().map(|_| vec![1.0; dimensions]).collect())
366        }
367
368        fn supports_model(&self, _model: EmbeddingModel) -> bool {
369            true
370        }
371
372        fn name(&self) -> &'static str {
373            "kg-import-truncation-test"
374        }
375    }
376
377    struct ImportEmbeddingProvider;
378
379    #[async_trait]
380    impl EmbedderProvider for ImportEmbeddingProvider {
381        fn name(&self) -> &str {
382            IMPORT_TEST_MODEL
383        }
384
385        fn dimensions(&self) -> usize {
386            EmbeddingModel::AllMiniLmL6V2.dimensions()
387        }
388
389        async fn build(&self) -> std::result::Result<Arc<dyn EmbeddingService>, RuntimeError> {
390            Ok(Arc::new(ImportEmbeddingService))
391        }
392    }
393
394    async fn make_rt() -> KhiveRuntime {
395        KhiveRuntime::memory().expect("in-memory runtime")
396    }
397
398    fn make_rt_with_embedder() -> KhiveRuntime {
399        let runtime = KhiveRuntime::memory().expect("in-memory runtime");
400        runtime.register_embedder(ImportEmbeddingProvider);
401        runtime
402    }
403
404    #[tokio::test]
405    async fn import_summary_reports_actual_embedding_truncation() {
406        let runtime = make_rt_with_embedder();
407        let token = NamespaceToken::local();
408        let archive = KgArchive {
409            format: "khive-kg".to_string(),
410            version: "0.1".to_string(),
411            namespace: "local".to_string(),
412            exported_at: Utc::now(),
413            entities: vec![ExportedEntity {
414                id: Uuid::new_v4(),
415                kind: "concept".to_string(),
416                entity_type: None,
417                name: "Imported long entity".to_string(),
418                description: Some("x".repeat(MAX_TEXT_CHARS + 1)),
419                properties: None,
420                tags: vec![],
421                created_at: Utc::now(),
422                updated_at: Utc::now(),
423            }],
424            edges: vec![],
425        };
426
427        let summary = runtime
428            .import_kg(&archive, &token)
429            .await
430            .expect("import with bounded embedding input");
431
432        assert_eq!(summary.entities_imported, 1);
433        assert_eq!(summary.embedding_truncation.truncated, 1);
434        assert!(summary.embedding_truncation.discarded_bytes > 0);
435        let wire = serde_json::to_value(&summary).expect("serialize import summary");
436        assert_eq!(wire["embedding_truncation"]["truncated"], 1);
437    }
438
439    /// 1. Roundtrip: 3 entities + 2 edges survive export → import on a fresh runtime.
440    #[tokio::test]
441    async fn roundtrip_entities_and_edges() {
442        let src = make_rt().await;
443        let tok = NamespaceToken::local();
444        let e1 = src
445            .create_entity(
446                &tok,
447                "concept",
448                None,
449                "FlashAttention",
450                Some("fast attention"),
451                None,
452                vec![],
453            )
454            .await
455            .unwrap();
456        let e2 = src
457            .create_entity(
458                &tok,
459                "concept",
460                None,
461                "FlashAttention-2",
462                None,
463                None,
464                vec![],
465            )
466            .await
467            .unwrap();
468        let e3 = src
469            .create_entity(
470                &tok,
471                "person",
472                None,
473                "Tri Dao",
474                None,
475                None,
476                vec!["author".into()],
477            )
478            .await
479            .unwrap();
480        src.link(&tok, e2.id, e1.id, EdgeRelation::Extends, 1.0, None)
481            .await
482            .unwrap();
483        src.link(&tok, e1.id, e3.id, EdgeRelation::IntroducedBy, 0.9, None)
484            .await
485            .unwrap();
486
487        let archive = src.export_kg(&tok).await.unwrap();
488        assert_eq!(archive.entities.len(), 3);
489        assert_eq!(archive.edges.len(), 2);
490        assert_eq!(archive.format, "khive-kg");
491        assert_eq!(archive.version, "0.1");
492
493        let dst = make_rt().await;
494        let summary = dst.import_kg(&archive, &tok).await.unwrap();
495        assert_eq!(summary.entities_imported, 3);
496        assert_eq!(summary.edges_imported, 2);
497
498        let got = dst.get_entity(&tok, e1.id).await.unwrap();
499        assert_eq!(got.name, "FlashAttention");
500        assert_eq!(got.description.as_deref(), Some("fast attention"));
501    }
502
503    /// 2. JSON roundtrip: export_kg_json → import_kg_json produces equivalent state.
504    #[tokio::test]
505    async fn json_roundtrip() {
506        let src = make_rt().await;
507        let tok = NamespaceToken::local();
508        let e1 = src
509            .create_entity(
510                &tok,
511                "concept",
512                None,
513                "LoRA",
514                Some("low-rank adaptation"),
515                Some(serde_json::json!({"year": "2021"})),
516                vec!["fine-tuning".into()],
517            )
518            .await
519            .unwrap();
520        let e2 = src
521            .create_entity(&tok, "concept", None, "QLoRA", None, None, vec![])
522            .await
523            .unwrap();
524        src.link(&tok, e2.id, e1.id, EdgeRelation::VariantOf, 0.9, None)
525            .await
526            .unwrap();
527
528        let json_str = src.export_kg_json(&tok).await.unwrap();
529        assert!(json_str.contains("khive-kg"));
530
531        let dst = make_rt().await;
532        let summary = dst.import_kg_json(&json_str, &tok).await.unwrap();
533        assert_eq!(summary.entities_imported, 2);
534        assert_eq!(summary.edges_imported, 1);
535
536        let got = dst.get_entity(&tok, e1.id).await.unwrap();
537        assert_eq!(got.tags, vec!["fine-tuning"]);
538    }
539
540    /// 3. Namespace targeting: export from namespace "a", import into namespace "b" on a
541    ///    fresh runtime — entities land in "b", and the source runtime's "a" is unaffected.
542    ///
543    ///    Note: source and destination are separate runtimes (separate in-memory DBs).
544    ///    Same-DB cross-namespace copy is not a portability use case — portability is about
545    ///    moving graphs between instances, not between namespaces within one instance.
546    #[tokio::test]
547    async fn namespace_targeting() {
548        let src = make_rt().await;
549        let tok_a = NamespaceToken::for_namespace(Namespace::parse("a").unwrap());
550        let tok_b = NamespaceToken::for_namespace(Namespace::parse("b").unwrap());
551        src.create_entity(&tok_a, "concept", None, "Sinkhorn", None, None, vec![])
552            .await
553            .unwrap();
554
555        let archive = src.export_kg(&tok_a).await.unwrap();
556        assert_eq!(archive.namespace, "a");
557
558        let dst = make_rt().await;
559        let summary = dst.import_kg(&archive, &tok_b).await.unwrap();
560        assert_eq!(summary.entities_imported, 1);
561
562        let in_b = dst.list_entities(&tok_b, None, None, 100, 0).await.unwrap();
563        assert_eq!(in_b.len(), 1);
564        assert_eq!(in_b[0].name, "Sinkhorn");
565
566        let in_a = src.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
567        assert_eq!(in_a.len(), 1);
568
569        let dst_a = dst.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
570        assert_eq!(dst_a.len(), 0);
571    }
572
573    /// 4. Format validation: wrong `format` field → InvalidInput.
574    #[tokio::test]
575    async fn format_validation_rejects_wrong_format() {
576        let rt = make_rt().await;
577        let tok = NamespaceToken::local();
578        let bad = KgArchive {
579            format: "wrong".to_string(),
580            version: "0.1".to_string(),
581            namespace: "local".to_string(),
582            exported_at: Utc::now(),
583            entities: vec![],
584            edges: vec![],
585        };
586        let err = rt.import_kg(&bad, &tok).await.unwrap_err();
587        assert!(matches!(err, RuntimeError::InvalidInput(_)));
588    }
589
590    /// 5. Unsupported archive version → InvalidInput.
591    #[tokio::test]
592    async fn import_unsupported_archive_version_returns_error() {
593        let rt = make_rt().await;
594        let tok = NamespaceToken::local();
595        let bad = KgArchive {
596            format: "khive-kg".to_string(),
597            version: "999.0".to_string(),
598            namespace: "local".to_string(),
599            exported_at: Utc::now(),
600            entities: vec![],
601            edges: vec![],
602        };
603        let err = rt.import_kg(&bad, &tok).await.unwrap_err();
604        assert!(
605            matches!(err, RuntimeError::InvalidInput(_)),
606            "expected InvalidInput, got {err:?}"
607        );
608        if let RuntimeError::InvalidInput(msg) = err {
609            assert!(
610                msg.contains("999.0"),
611                "error message should mention the unsupported version, got: {msg:?}"
612            );
613        }
614    }
615
616    /// 6. Invalid relation in archive → InvalidInput.
617    #[test]
618    fn invalid_relation_rejected_at_deserialize() {
619        let json = r#"{
620            "format":"khive-kg","version":"0.1","namespace":"local",
621            "exported_at":"2026-01-01T00:00:00Z",
622            "entities":[],
623            "edges":[{"edge_id":"00000000-0000-0000-0000-000000000099",
624                       "source":"00000000-0000-0000-0000-000000000001",
625                       "target":"00000000-0000-0000-0000-000000000002",
626                       "relation":"related_to","weight":0.5}]
627        }"#;
628        let result: Result<KgArchive, _> = serde_json::from_str(json);
629        assert!(
630            result.is_err(),
631            "non-canonical relation should fail to deserialize"
632        );
633    }
634
635    // ── Dangling-edge validation tests ────────────────────────────────────────
636
637    /// 6. Edge with dangling source (source UUID not in entity table) is skipped.
638    ///
639    /// The archive has one entity + one edge whose source is a phantom UUID.
640    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
641    #[tokio::test]
642    async fn import_edge_with_dangling_source_is_skipped() {
643        let phantom_source = Uuid::parse_str("deadbeef-dead-4ead-dead-deadbeefcafe").unwrap();
644
645        let rt = make_rt().await;
646        let tok = NamespaceToken::local();
647        let real = rt
648            .create_entity(&tok, "concept", None, "Real", None, None, vec![])
649            .await
650            .unwrap();
651
652        let archive = KgArchive {
653            format: "khive-kg".to_string(),
654            version: "0.1".to_string(),
655            namespace: "local".to_string(),
656            exported_at: Utc::now(),
657            entities: vec![ExportedEntity {
658                id: real.id,
659                kind: "concept".to_string(),
660                entity_type: None,
661                name: "Real".to_string(),
662                description: None,
663                properties: None,
664                tags: vec![],
665                created_at: Utc::now(),
666                updated_at: Utc::now(),
667            }],
668            edges: vec![ExportedEdge {
669                edge_id: Uuid::new_v4(),
670                source: phantom_source,
671                target: real.id,
672                relation: EdgeRelation::Extends,
673                weight: 1.0,
674            }],
675        };
676
677        let dst = make_rt().await;
678        let summary = dst.import_kg(&archive, &tok).await.unwrap();
679        assert_eq!(summary.entities_imported, 1);
680        assert_eq!(
681            summary.edges_imported, 0,
682            "dangling source must not be imported"
683        );
684        assert_eq!(
685            summary.edges_skipped, 1,
686            "dangling source must be counted as skipped"
687        );
688    }
689
690    /// 7. Edge with dangling target (target UUID not in entity table) is skipped.
691    ///
692    /// The archive has one entity + one edge whose target is a phantom UUID.
693    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
694    #[tokio::test]
695    async fn import_edge_with_dangling_target_is_skipped() {
696        let phantom_target = Uuid::parse_str("cafebabe-cafe-4abe-cafe-cafebabecafe").unwrap();
697
698        let rt = make_rt().await;
699        let tok = NamespaceToken::local();
700        let real = rt
701            .create_entity(&tok, "concept", None, "Source", None, None, vec![])
702            .await
703            .unwrap();
704
705        let archive = KgArchive {
706            format: "khive-kg".to_string(),
707            version: "0.1".to_string(),
708            namespace: "local".to_string(),
709            exported_at: Utc::now(),
710            entities: vec![ExportedEntity {
711                id: real.id,
712                kind: "concept".to_string(),
713                entity_type: None,
714                name: "Source".to_string(),
715                description: None,
716                properties: None,
717                tags: vec![],
718                created_at: Utc::now(),
719                updated_at: Utc::now(),
720            }],
721            edges: vec![ExportedEdge {
722                edge_id: Uuid::new_v4(),
723                source: real.id,
724                target: phantom_target,
725                relation: EdgeRelation::DependsOn,
726                weight: 0.8,
727            }],
728        };
729
730        let dst = make_rt().await;
731        let summary = dst.import_kg(&archive, &tok).await.unwrap();
732        assert_eq!(summary.entities_imported, 1);
733        assert_eq!(
734            summary.edges_imported, 0,
735            "dangling target must not be imported"
736        );
737        assert_eq!(
738            summary.edges_skipped, 1,
739            "dangling target must be counted as skipped"
740        );
741    }
742
743    /// 8. Mixed batch: some valid edges and some dangling edges — correct counts reported.
744    ///
745    /// Archive has 3 entities, 2 valid edges, and 1 dangling edge (phantom target).
746    /// Import succeeds with edges_imported=2, edges_skipped=1.
747    #[tokio::test]
748    async fn import_mixed_edges_reports_correct_counts() {
749        let phantom = Uuid::parse_str("11111111-1111-4111-8111-111111111111").unwrap();
750
751        let src = make_rt().await;
752        let tok = NamespaceToken::local();
753        let a = src
754            .create_entity(&tok, "concept", None, "A", None, None, vec![])
755            .await
756            .unwrap();
757        let b = src
758            .create_entity(&tok, "concept", None, "B", None, None, vec![])
759            .await
760            .unwrap();
761        let c = src
762            .create_entity(&tok, "concept", None, "C", None, None, vec![])
763            .await
764            .unwrap();
765
766        let archive = KgArchive {
767            format: "khive-kg".to_string(),
768            version: "0.1".to_string(),
769            namespace: "local".to_string(),
770            exported_at: Utc::now(),
771            entities: vec![
772                ExportedEntity {
773                    id: a.id,
774                    kind: "concept".to_string(),
775                    entity_type: None,
776                    name: "A".to_string(),
777                    description: None,
778                    properties: None,
779                    tags: vec![],
780                    created_at: Utc::now(),
781                    updated_at: Utc::now(),
782                },
783                ExportedEntity {
784                    id: b.id,
785                    kind: "concept".to_string(),
786                    entity_type: None,
787                    name: "B".to_string(),
788                    description: None,
789                    properties: None,
790                    tags: vec![],
791                    created_at: Utc::now(),
792                    updated_at: Utc::now(),
793                },
794                ExportedEntity {
795                    id: c.id,
796                    kind: "concept".to_string(),
797                    entity_type: None,
798                    name: "C".to_string(),
799                    description: None,
800                    properties: None,
801                    tags: vec![],
802                    created_at: Utc::now(),
803                    updated_at: Utc::now(),
804                },
805            ],
806            edges: vec![
807                ExportedEdge {
808                    edge_id: Uuid::new_v4(),
809                    source: a.id,
810                    target: b.id,
811                    relation: EdgeRelation::Extends,
812                    weight: 1.0,
813                },
814                ExportedEdge {
815                    edge_id: Uuid::new_v4(),
816                    source: b.id,
817                    target: c.id,
818                    // #1235: concept->concept is not in depends_on's endpoint
819                    // contract; use variant_of (concept->concept is valid) so
820                    // this fixture exercises "one dangling edge skipped" only,
821                    // not an endpoint-contract violation this test isn't about.
822                    relation: EdgeRelation::VariantOf,
823                    weight: 0.9,
824                },
825                ExportedEdge {
826                    edge_id: Uuid::new_v4(),
827                    source: a.id,
828                    target: phantom,
829                    relation: EdgeRelation::Enables,
830                    weight: 0.5,
831                },
832            ],
833        };
834
835        let dst = make_rt().await;
836        let summary = dst.import_kg(&archive, &tok).await.unwrap();
837        assert_eq!(summary.entities_imported, 3);
838        assert_eq!(
839            summary.edges_imported, 2,
840            "only valid edges must be imported"
841        );
842        assert_eq!(
843            summary.edges_skipped, 1,
844            "one dangling edge must be reported"
845        );
846    }
847
848    /// 9. All-valid edges produce edges_skipped=0 (no regression on the happy path).
849    #[tokio::test]
850    async fn import_all_valid_edges_reports_zero_skipped() {
851        let src = make_rt().await;
852        let tok = NamespaceToken::local();
853        let e1 = src
854            .create_entity(&tok, "concept", None, "E1", None, None, vec![])
855            .await
856            .unwrap();
857        let e2 = src
858            .create_entity(&tok, "concept", None, "E2", None, None, vec![])
859            .await
860            .unwrap();
861        src.link(&tok, e1.id, e2.id, EdgeRelation::VariantOf, 0.7, None)
862            .await
863            .unwrap();
864
865        let archive = src.export_kg(&tok).await.unwrap();
866        let dst = make_rt().await;
867        let summary = dst.import_kg(&archive, &tok).await.unwrap();
868        assert_eq!(summary.edges_imported, 1);
869        assert_eq!(
870            summary.edges_skipped, 0,
871            "no edges should be skipped when all endpoints exist"
872        );
873    }
874
875    /// #1235: an edge whose (source kind, relation, target kind) triple violates the
876    /// endpoint contract (here: `precedes` between two `concept` entities — `precedes`
877    /// is restricted to document/dataset/artifact/service/project pairs) must be
878    /// skipped by import the same way a dangling endpoint is, not written straight
879    /// through with `graph.upsert_edge`.
880    #[tokio::test]
881    async fn import_edge_violating_endpoint_contract_is_skipped() {
882        let src = make_rt().await;
883        let tok = NamespaceToken::local();
884        let e1 = src
885            .create_entity(&tok, "concept", None, "E1", None, None, vec![])
886            .await
887            .unwrap();
888        let e2 = src
889            .create_entity(&tok, "concept", None, "E2", None, None, vec![])
890            .await
891            .unwrap();
892
893        let archive = KgArchive {
894            format: "khive-kg".to_string(),
895            version: "0.1".to_string(),
896            namespace: "local".to_string(),
897            exported_at: Utc::now(),
898            entities: vec![
899                ExportedEntity {
900                    id: e1.id,
901                    kind: "concept".to_string(),
902                    entity_type: None,
903                    name: "E1".to_string(),
904                    description: None,
905                    properties: None,
906                    tags: vec![],
907                    created_at: Utc::now(),
908                    updated_at: Utc::now(),
909                },
910                ExportedEntity {
911                    id: e2.id,
912                    kind: "concept".to_string(),
913                    entity_type: None,
914                    name: "E2".to_string(),
915                    description: None,
916                    properties: None,
917                    tags: vec![],
918                    created_at: Utc::now(),
919                    updated_at: Utc::now(),
920                },
921            ],
922            edges: vec![ExportedEdge {
923                edge_id: Uuid::new_v4(),
924                source: e1.id,
925                target: e2.id,
926                relation: EdgeRelation::Precedes,
927                weight: 1.0,
928            }],
929        };
930
931        let dst = make_rt().await;
932        let summary = dst.import_kg(&archive, &tok).await.unwrap();
933        assert_eq!(summary.entities_imported, 2);
934        assert_eq!(
935            summary.edges_imported, 0,
936            "an endpoint-contract-violating edge must not be imported"
937        );
938        assert_eq!(
939            summary.edges_skipped, 1,
940            "an endpoint-contract-violating edge must be counted as skipped"
941        );
942        assert!(
943            dst.neighbors(
944                &tok,
945                e1.id,
946                khive_storage::types::Direction::Out,
947                None,
948                None
949            )
950            .await
951            .unwrap()
952            .is_empty(),
953            "the contract-violating edge must not exist in the destination graph"
954        );
955    }
956
957    // ── edge_id contract tests ────────────────────────────────────────────────
958
959    /// 10. export_kg sets edge_id in the archive to the LinkId returned by link.
960    #[tokio::test]
961    async fn export_kg_preserves_edge_id() {
962        let rt = make_rt().await;
963        let tok = NamespaceToken::local();
964        let a = rt
965            .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
966            .await
967            .unwrap();
968        let b = rt
969            .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
970            .await
971            .unwrap();
972        let stored_edge = rt
973            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
974            .await
975            .unwrap();
976        let stored_id: Uuid = stored_edge.id.into();
977
978        let archive = rt.export_kg(&tok).await.unwrap();
979        assert_eq!(archive.edges.len(), 1);
980        assert_eq!(
981            archive.edges[0].edge_id, stored_id,
982            "exported edge_id must equal the LinkId returned by link"
983        );
984    }
985
986    /// 11. import_kg writes the archive edge_id as the stored LinkId.
987    #[tokio::test]
988    async fn import_kg_persists_edge_id() {
989        let src = make_rt().await;
990        let tok = NamespaceToken::local();
991        let a = src
992            .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
993            .await
994            .unwrap();
995        let b = src
996            .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
997            .await
998            .unwrap();
999        let stored_edge = src
1000            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1001            .await
1002            .unwrap();
1003        let original_id: Uuid = stored_edge.id.into();
1004
1005        let archive = src.export_kg(&tok).await.unwrap();
1006        let dst = make_rt().await;
1007        dst.import_kg(&archive, &tok).await.unwrap();
1008
1009        let imported_edge = dst.get_edge(&tok, original_id).await.unwrap();
1010        assert!(
1011            imported_edge.is_some(),
1012            "imported edge must be retrievable by the original edge_id"
1013        );
1014        let imported_edge = imported_edge.unwrap();
1015        assert_eq!(
1016            Uuid::from(imported_edge.id),
1017            original_id,
1018            "stored edge id must equal the archive edge_id"
1019        );
1020    }
1021
1022    /// 12. Old archive (no edge_id field) deserializes, imports, and re-exports with the
1023    ///     same generated UUID — proving the generated ID survives the full round trip.
1024    ///
1025    ///     The fixture includes two entities so the edge is not skipped during import.
1026    #[tokio::test]
1027    async fn old_archive_missing_edge_id_round_trips() {
1028        let src_id = Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap();
1029        let tgt_id = Uuid::parse_str("00000000-0000-0000-0000-000000000002").unwrap();
1030
1031        // Simulate a pre-0.2 archive JSON where the edge lacks an edge_id field.
1032        let json = format!(
1033            r#"{{
1034                "format": "khive-kg",
1035                "version": "0.1",
1036                "namespace": "local",
1037                "exported_at": "2026-01-01T00:00:00Z",
1038                "entities": [
1039                    {{"id":"{src_id}","kind":"concept","name":"SrcNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}},
1040                    {{"id":"{tgt_id}","kind":"concept","name":"TgtNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}}
1041                ],
1042                "edges": [
1043                    {{
1044                        "source": "{src_id}",
1045                        "target": "{tgt_id}",
1046                        "relation": "extends",
1047                        "weight": 0.9
1048                    }}
1049                ]
1050            }}"#
1051        );
1052
1053        // serde(default) must assign a fresh non-nil UUID when edge_id is absent.
1054        let archive: KgArchive = serde_json::from_str(&json)
1055            .expect("old archive without edge_id must deserialize successfully");
1056        assert_eq!(archive.edges.len(), 1);
1057        let generated_id = archive.edges[0].edge_id;
1058        assert_ne!(
1059            generated_id,
1060            Uuid::nil(),
1061            "missing edge_id in old archive must get a fresh non-nil UUID"
1062        );
1063
1064        let rt = make_rt().await;
1065        let tok = NamespaceToken::local();
1066        let summary = rt.import_kg(&archive, &tok).await.unwrap();
1067        assert_eq!(summary.entities_imported, 2);
1068        assert_eq!(
1069            summary.edges_imported, 1,
1070            "edge must be imported when both endpoints exist"
1071        );
1072
1073        let stored = rt.get_edge(&tok, generated_id).await.unwrap();
1074        assert!(
1075            stored.is_some(),
1076            "imported edge must be retrievable by the generated edge_id"
1077        );
1078        assert_eq!(
1079            Uuid::from(stored.unwrap().id),
1080            generated_id,
1081            "stored edge id must equal the generated edge_id"
1082        );
1083
1084        let re_archive = rt.export_kg(&tok).await.unwrap();
1085        assert_eq!(re_archive.edges.len(), 1);
1086        assert_eq!(
1087            re_archive.edges[0].edge_id, generated_id,
1088            "re-exported edge_id must equal the ID generated on first import"
1089        );
1090    }
1091
1092    /// 13. Explicit export → import → export equality: the edge_id is unchanged across
1093    ///     a full round trip when the source archive already contains an edge_id.
1094    ///
1095    ///     Verifies by (source, target, relation) key that re-export emits the original ID.
1096    #[tokio::test]
1097    async fn export_import_export_edge_id_equality() {
1098        let src = make_rt().await;
1099        let tok = NamespaceToken::local();
1100        let a = src
1101            .create_entity(&tok, "concept", None, "NodeA", None, None, vec![])
1102            .await
1103            .unwrap();
1104        let b = src
1105            .create_entity(&tok, "concept", None, "NodeB", None, None, vec![])
1106            .await
1107            .unwrap();
1108        let stored = src
1109            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1110            .await
1111            .unwrap();
1112        let original_edge_id: Uuid = stored.id.into();
1113
1114        let archive1 = src.export_kg(&tok).await.unwrap();
1115        assert_eq!(archive1.edges.len(), 1);
1116        assert_eq!(
1117            archive1.edges[0].edge_id, original_edge_id,
1118            "first export must carry the stored edge_id"
1119        );
1120
1121        let dst = make_rt().await;
1122        dst.import_kg(&archive1, &tok).await.unwrap();
1123
1124        let archive2 = dst.export_kg(&tok).await.unwrap();
1125        assert_eq!(archive2.edges.len(), 1);
1126
1127        let re_edge = archive2
1128            .edges
1129            .iter()
1130            .find(|e| e.source == a.id && e.target == b.id && e.relation == EdgeRelation::Extends)
1131            .expect(
1132                "re-exported archive must contain the original edge by (source,target,relation)",
1133            );
1134        assert_eq!(
1135            re_edge.edge_id, original_edge_id,
1136            "edge_id must be identical across export → import → export"
1137        );
1138    }
1139}