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    /// Portable edge metadata, named `properties` in the ADR-020 wire shape.
69    #[serde(default, skip_serializing_if = "Option::is_none")]
70    pub properties: Option<serde_json::Value>,
71    /// Edge creation time. Older archives may omit it; those imports use the
72    /// time at which the archive is decoded.
73    #[serde(
74        default = "default_import_timestamp",
75        deserialize_with = "deserialize_import_timestamp"
76    )]
77    pub created_at: DateTime<Utc>,
78    /// Edge last-update time. Kept independent from `created_at` so imported
79    /// provenance is not collapsed during a round trip.
80    #[serde(
81        default = "default_import_timestamp",
82        deserialize_with = "deserialize_import_timestamp"
83    )]
84    pub updated_at: DateTime<Utc>,
85}
86
87fn default_import_timestamp() -> DateTime<Utc> {
88    Utc::now()
89}
90
91fn deserialize_import_timestamp<'de, D>(deserializer: D) -> Result<DateTime<Utc>, D::Error>
92where
93    D: serde::Deserializer<'de>,
94{
95    let raw = String::deserialize(deserializer)?;
96    DateTime::parse_from_rfc3339(&raw)
97        .map(|timestamp| timestamp.with_timezone(&Utc))
98        .map_err(|error| serde::de::Error::custom(format!("timestamp must be RFC3339: {error}")))
99}
100
101/// Outcome of a successful import operation.
102#[derive(Clone, Debug, Serialize, Deserialize)]
103pub struct ImportSummary {
104    pub entities_imported: usize,
105    pub edges_imported: usize,
106    /// Number of edges that were skipped because one or both endpoint UUIDs
107    /// were not found in the target namespace after entity import.
108    ///
109    /// A non-zero value indicates the archive contained dangling edges (edges
110    /// referencing entities not present in the archive or the existing graph).
111    pub edges_skipped: usize,
112    /// Aggregate actual outcomes from reindexing imported entities. Source
113    /// text remains complete in the entity store and FTS when this is non-zero.
114    #[serde(default)]
115    pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
116}
117
118// ── KhiveRuntime impl ─────────────────────────────────────────────────────────
119
120impl KhiveRuntime {
121    /// Export all entities and edges in a namespace to a portable JSON archive.
122    ///
123    /// Edge collection: all entity IDs in the namespace are gathered first;
124    /// `query_edges` is then called with those IDs as `source_ids`. This
125    /// captures every edge whose source entity belongs to the namespace.
126    pub async fn export_kg(&self, token: &NamespaceToken) -> RuntimeResult<KgArchive> {
127        let ns = token.namespace().as_str().to_owned();
128
129        let entity_page = self
130            .entities(token)?
131            .query_entities(
132                &ns,
133                EntityFilter::default(),
134                PageRequest {
135                    offset: 0,
136                    limit: u32::MAX,
137                },
138            )
139            .await?;
140
141        let entities: Vec<ExportedEntity> = entity_page
142            .items
143            .into_iter()
144            .map(|e| {
145                let created_at =
146                    DateTime::from_timestamp_micros(e.created_at).unwrap_or_else(Utc::now);
147                let updated_at =
148                    DateTime::from_timestamp_micros(e.updated_at).unwrap_or_else(Utc::now);
149                ExportedEntity {
150                    id: e.id,
151                    kind: e.kind.to_string(),
152                    entity_type: e.entity_type,
153                    name: e.name,
154                    description: e.description,
155                    properties: e.properties,
156                    tags: e.tags,
157                    created_at,
158                    updated_at,
159                }
160            })
161            .collect();
162
163        let source_ids: Vec<Uuid> = entities.iter().map(|e| e.id).collect();
164        let edges = if source_ids.is_empty() {
165            Vec::new()
166        } else {
167            let filter = EdgeFilter {
168                source_ids: source_ids.clone(),
169                ..Default::default()
170            };
171            let edge_page = self
172                .graph(token)?
173                .query_edges(
174                    filter,
175                    Vec::new(),
176                    PageRequest {
177                        offset: 0,
178                        limit: u32::MAX,
179                    },
180                )
181                .await?;
182
183            let id_set: HashSet<Uuid> = source_ids.into_iter().collect();
184            edge_page
185                .items
186                .into_iter()
187                .filter(|e| id_set.contains(&e.source_id))
188                .map(|e| ExportedEdge {
189                    edge_id: e.id.into(),
190                    source: e.source_id,
191                    target: e.target_id,
192                    relation: e.relation,
193                    weight: e.weight,
194                    properties: e.metadata,
195                    created_at: e.created_at,
196                    updated_at: e.updated_at,
197                })
198                .collect()
199        };
200
201        Ok(KgArchive {
202            format: "khive-kg".to_string(),
203            version: "0.1".to_string(),
204            namespace: ns,
205            exported_at: Utc::now(),
206            entities,
207            edges,
208        })
209    }
210
211    /// Export to a JSON string (convenience wrapper around `export_kg`).
212    pub async fn export_kg_json(&self, token: &NamespaceToken) -> RuntimeResult<String> {
213        let archive = self.export_kg(token).await?;
214        serde_json::to_string(&archive).map_err(|e| RuntimeError::InvalidInput(e.to_string()))
215    }
216
217    /// Import an archive into `target_namespace`.
218    ///
219    /// If `target_namespace` is `None`, the archive's own namespace is used.
220    ///
221    /// - Entities: upserted by ID; existing records are overwritten.
222    /// - Edges: upserted; existing records are overwritten.
223    /// - Validation: `format != "khive-kg"` or unsupported version → `InvalidInput`.
224    ///   Invalid edge relations are caught at JSON deserialization time.
225    pub async fn import_kg(
226        &self,
227        archive: &KgArchive,
228        token: &NamespaceToken,
229    ) -> RuntimeResult<ImportSummary> {
230        if archive.format != "khive-kg" {
231            return Err(RuntimeError::InvalidInput(format!(
232                "unsupported archive format {:?}; expected \"khive-kg\"",
233                archive.format
234            )));
235        }
236        if archive.version != "0.1" {
237            return Err(RuntimeError::InvalidInput(format!(
238                "unsupported archive version {:?}; supported: \"0.1\"",
239                archive.version
240            )));
241        }
242
243        let ns = token.namespace().as_str().to_owned();
244
245        // Complete deterministic validation before opening a store or issuing
246        // the first write. Endpoint existence and namespace checks remain at
247        // write time because they depend on mutable target state.
248        for (index, entity) in archive.entities.iter().enumerate() {
249            self.validate_entity_kind(&entity.kind)?;
250            // Archive content is caller-controlled input: the runtime-owned
251            // `khive:secret_gate` property key is reservation-only on import,
252            // exactly as on every other properties-bearing write path
253            // (ADR-115 Amendment 1 §3). Import never consumes exemptions.
254            crate::secret_gate::reject_reserved_secret_gate_property(entity.properties.as_ref())?;
255            if entity.name.trim().is_empty() {
256                return Err(RuntimeError::InvalidInput(format!(
257                    "archive entity {index} ({}) name must be non-blank",
258                    entity.id
259                )));
260            }
261        }
262        for edge in &archive.edges {
263            crate::operations::validate_edge_weight(edge.weight)?;
264            // Edge properties are caller-controlled input: the runtime-owned
265            // `khive:secret_gate` key is reservation-only on import, and edge
266            // metadata is in ADR-115 Amendment 1 §3's unchanged blocking-scanner
267            // class, so credential-shaped values are rejected here as well.
268            crate::secret_gate::reject_reserved_secret_gate_property(edge.properties.as_ref())?;
269            if let Some(p) = edge.properties.as_ref() {
270                crate::secret_gate::check_json(p)?;
271            }
272        }
273
274        let store = self.entities(token)?;
275        let mut entities_imported = 0usize;
276        let mut embedding_truncation = crate::retrieval::EmbeddingTruncationReport::default();
277        for ee in &archive.entities {
278            let created_micros = ee.created_at.timestamp_micros();
279            let updated_micros = ee.updated_at.timestamp_micros();
280            let entity = khive_storage::entity::Entity {
281                id: ee.id,
282                namespace: ns.clone(),
283                kind: ee.kind.clone(),
284                entity_type: ee.entity_type.clone(),
285                name: ee.name.clone(),
286                description: ee.description.clone(),
287                properties: ee.properties.clone(),
288                tags: ee.tags.clone(),
289                created_at: created_micros,
290                updated_at: updated_micros,
291                deleted_at: None,
292                merged_into: None,
293                merge_event_id: None,
294                content_ref: None,
295            };
296            store.upsert_entity(entity.clone()).await?;
297            // Reindex so imported entities are searchable via hybrid_search immediately.
298            embedding_truncation.merge(self.reindex_entity(token, &entity).await?);
299            entities_imported += 1;
300        }
301
302        // Untrusted archives may reference entities absent from the target namespace;
303        // check both endpoints and skip edges with a missing source or target to avoid
304        // dangling references in the graph store.
305        let graph = self.graph(token)?;
306        let mut edges_imported = 0usize;
307        let mut edges_skipped = 0usize;
308        for ee in &archive.edges {
309            let source_ok = match self.get_entity(token, ee.source).await {
310                Ok(_) => true,
311                Err(RuntimeError::NotFound(_)) => false,
312                Err(e) => return Err(e),
313            };
314            if !source_ok {
315                tracing::warn!(
316                    source = %ee.source,
317                    target = %ee.target,
318                    relation = ?ee.relation,
319                    "import_kg: skipping edge — source entity not found in namespace {ns:?}"
320                );
321                edges_skipped += 1;
322                continue;
323            }
324            let target_ok = match self.get_entity(token, ee.target).await {
325                Ok(_) => true,
326                Err(RuntimeError::NotFound(_)) => false,
327                Err(e) => return Err(e),
328            };
329            if !target_ok {
330                tracing::warn!(
331                    source = %ee.source,
332                    target = %ee.target,
333                    relation = ?ee.relation,
334                    "import_kg: skipping edge — target entity not found in namespace {ns:?}"
335                );
336                edges_skipped += 1;
337                continue;
338            }
339            // Only a contract verdict (InvalidInput) or an endpoint-resolution
340            // miss (NotFound) is a property of the edge being imported; any
341            // other error is an operational failure of the check itself and
342            // must abort the import rather than silently discard a valid edge.
343            match self
344                .validate_edge_relation_endpoints(token, ee.source, ee.target, ee.relation)
345                .await
346            {
347                Ok(()) => {}
348                Err(e @ (RuntimeError::InvalidInput(_) | RuntimeError::NotFound(_))) => {
349                    tracing::warn!(
350                        source = %ee.source,
351                        target = %ee.target,
352                        relation = ?ee.relation,
353                        error = %e,
354                        "import_kg: skipping edge — endpoint contract violation in namespace {ns:?}"
355                    );
356                    edges_skipped += 1;
357                    continue;
358                }
359                Err(e) => return Err(e),
360            }
361            let edge = khive_storage::types::Edge {
362                id: LinkId::from(ee.edge_id),
363                namespace: ns.clone(),
364                source_id: ee.source,
365                target_id: ee.target,
366                relation: ee.relation,
367                weight: ee.weight,
368                created_at: ee.created_at,
369                updated_at: ee.updated_at,
370                deleted_at: None,
371                metadata: ee.properties.clone(),
372                target_backend: None,
373            };
374            graph.upsert_edge(edge).await?;
375            edges_imported += 1;
376        }
377
378        Ok(ImportSummary {
379            entities_imported,
380            edges_imported,
381            edges_skipped,
382            embedding_truncation,
383        })
384    }
385
386    /// Import from a JSON string (convenience wrapper around `import_kg`).
387    pub async fn import_kg_json(
388        &self,
389        json: &str,
390        token: &NamespaceToken,
391    ) -> RuntimeResult<ImportSummary> {
392        let archive: KgArchive =
393            serde_json::from_str(json).map_err(|e| RuntimeError::InvalidInput(e.to_string()))?;
394        self.import_kg(&archive, token).await
395    }
396}
397
398// ── Tests ─────────────────────────────────────────────────────────────────────
399
400// Kept inline: these tests exercise round-trip invariants over private encoding
401// helpers that would otherwise need to be made pub to test from tests/.
402#[cfg(test)]
403mod tests {
404    use std::sync::Arc;
405
406    use super::*;
407    use crate::runtime::{KhiveRuntime, NamespaceToken};
408    use crate::{EmbedderProvider, Namespace};
409    use async_trait::async_trait;
410    use khive_storage::EdgeRelation;
411    use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService, MAX_TEXT_BYTES};
412
413    const IMPORT_TEST_MODEL: &str = "all-minilm-l6-v2";
414
415    struct ImportEmbeddingService;
416
417    #[async_trait]
418    impl EmbeddingService for ImportEmbeddingService {
419        async fn embed(
420            &self,
421            texts: &[String],
422            _model: EmbeddingModel,
423        ) -> std::result::Result<Vec<Vec<f32>>, EmbedError> {
424            let dimensions = EmbeddingModel::AllMiniLmL6V2.dimensions();
425            Ok(texts.iter().map(|_| vec![1.0; dimensions]).collect())
426        }
427
428        fn supports_model(&self, _model: EmbeddingModel) -> bool {
429            true
430        }
431
432        fn name(&self) -> &'static str {
433            "kg-import-truncation-test"
434        }
435    }
436
437    struct ImportEmbeddingProvider;
438
439    #[async_trait]
440    impl EmbedderProvider for ImportEmbeddingProvider {
441        fn name(&self) -> &str {
442            IMPORT_TEST_MODEL
443        }
444
445        fn dimensions(&self) -> usize {
446            EmbeddingModel::AllMiniLmL6V2.dimensions()
447        }
448
449        async fn build(&self) -> std::result::Result<Arc<dyn EmbeddingService>, RuntimeError> {
450            Ok(Arc::new(ImportEmbeddingService))
451        }
452    }
453
454    async fn make_rt() -> KhiveRuntime {
455        KhiveRuntime::memory().expect("in-memory runtime")
456    }
457
458    fn make_rt_with_embedder() -> KhiveRuntime {
459        let runtime = KhiveRuntime::memory().expect("in-memory runtime");
460        runtime.register_embedder(ImportEmbeddingProvider);
461        runtime
462    }
463
464    #[tokio::test]
465    async fn import_summary_reports_actual_embedding_truncation() {
466        let runtime = make_rt_with_embedder();
467        let token = NamespaceToken::local();
468        let archive = KgArchive {
469            format: "khive-kg".to_string(),
470            version: "0.1".to_string(),
471            namespace: "local".to_string(),
472            exported_at: Utc::now(),
473            entities: vec![ExportedEntity {
474                id: Uuid::new_v4(),
475                kind: "concept".to_string(),
476                entity_type: None,
477                name: "Imported long entity".to_string(),
478                description: Some("x".repeat(MAX_TEXT_BYTES + 1)),
479                properties: None,
480                tags: vec![],
481                created_at: Utc::now(),
482                updated_at: Utc::now(),
483            }],
484            edges: vec![],
485        };
486
487        let summary = runtime
488            .import_kg(&archive, &token)
489            .await
490            .expect("import with bounded embedding input");
491
492        assert_eq!(summary.entities_imported, 1);
493        assert_eq!(summary.embedding_truncation.truncated, 1);
494        assert!(summary.embedding_truncation.discarded_bytes > 0);
495        let wire = serde_json::to_value(&summary).expect("serialize import summary");
496        assert_eq!(wire["embedding_truncation"]["truncated"], 1);
497    }
498
499    #[tokio::test]
500    async fn import_rejects_whitespace_name_before_any_entity_write() {
501        let runtime = make_rt().await;
502        let token = NamespaceToken::local();
503        let valid_id = Uuid::new_v4();
504        let archive = KgArchive {
505            format: "khive-kg".to_string(),
506            version: "0.1".to_string(),
507            namespace: "local".to_string(),
508            exported_at: Utc::now(),
509            entities: vec![
510                ExportedEntity {
511                    id: valid_id,
512                    kind: "concept".to_string(),
513                    entity_type: None,
514                    name: "Must not be written".to_string(),
515                    description: None,
516                    properties: None,
517                    tags: vec![],
518                    created_at: Utc::now(),
519                    updated_at: Utc::now(),
520                },
521                ExportedEntity {
522                    id: Uuid::new_v4(),
523                    kind: "concept".to_string(),
524                    entity_type: None,
525                    name: " \t\n ".to_string(),
526                    description: None,
527                    properties: None,
528                    tags: vec![],
529                    created_at: Utc::now(),
530                    updated_at: Utc::now(),
531                },
532            ],
533            edges: vec![],
534        };
535
536        let err = runtime
537            .import_kg(&archive, &token)
538            .await
539            .expect_err("whitespace-only entity names must fail the whole import");
540        assert!(
541            err.to_string().contains("non-blank"),
542            "error must explain the name invariant: {err}"
543        );
544        assert!(
545            runtime.get_entity(&token, valid_id).await.is_err(),
546            "deterministic validation must finish before the first entity write"
547        );
548    }
549
550    /// 1. Roundtrip: 3 entities + 2 edges survive export → import on a fresh runtime.
551    #[tokio::test]
552    async fn roundtrip_entities_and_edges() {
553        let src = make_rt().await;
554        let tok = NamespaceToken::local();
555        let e1 = src
556            .create_entity(
557                &tok,
558                "concept",
559                None,
560                "FlashAttention",
561                Some("fast attention"),
562                None,
563                vec![],
564            )
565            .await
566            .unwrap();
567        let e2 = src
568            .create_entity(
569                &tok,
570                "concept",
571                None,
572                "FlashAttention-2",
573                None,
574                None,
575                vec![],
576            )
577            .await
578            .unwrap();
579        let e3 = src
580            .create_entity(
581                &tok,
582                "person",
583                None,
584                "Tri Dao",
585                None,
586                None,
587                vec!["author".into()],
588            )
589            .await
590            .unwrap();
591        src.link(&tok, e2.id, e1.id, EdgeRelation::Extends, 1.0, None)
592            .await
593            .unwrap();
594        src.link(&tok, e1.id, e3.id, EdgeRelation::IntroducedBy, 0.9, None)
595            .await
596            .unwrap();
597
598        let archive = src.export_kg(&tok).await.unwrap();
599        assert_eq!(archive.entities.len(), 3);
600        assert_eq!(archive.edges.len(), 2);
601        assert_eq!(archive.format, "khive-kg");
602        assert_eq!(archive.version, "0.1");
603
604        let dst = make_rt().await;
605        let summary = dst.import_kg(&archive, &tok).await.unwrap();
606        assert_eq!(summary.entities_imported, 3);
607        assert_eq!(summary.edges_imported, 2);
608
609        let got = dst.get_entity(&tok, e1.id).await.unwrap();
610        assert_eq!(got.name, "FlashAttention");
611        assert_eq!(got.description.as_deref(), Some("fast attention"));
612    }
613
614    /// 2. JSON roundtrip: export_kg_json → import_kg_json produces equivalent state.
615    #[tokio::test]
616    async fn json_roundtrip() {
617        let src = make_rt().await;
618        let tok = NamespaceToken::local();
619        let e1 = src
620            .create_entity(
621                &tok,
622                "concept",
623                None,
624                "LoRA",
625                Some("low-rank adaptation"),
626                Some(serde_json::json!({"year": "2021"})),
627                vec!["fine-tuning".into()],
628            )
629            .await
630            .unwrap();
631        let e2 = src
632            .create_entity(&tok, "concept", None, "QLoRA", None, None, vec![])
633            .await
634            .unwrap();
635        src.link(&tok, e2.id, e1.id, EdgeRelation::VariantOf, 0.9, None)
636            .await
637            .unwrap();
638
639        let json_str = src.export_kg_json(&tok).await.unwrap();
640        assert!(json_str.contains("khive-kg"));
641
642        let dst = make_rt().await;
643        let summary = dst.import_kg_json(&json_str, &tok).await.unwrap();
644        assert_eq!(summary.entities_imported, 2);
645        assert_eq!(summary.edges_imported, 1);
646
647        let got = dst.get_entity(&tok, e1.id).await.unwrap();
648        assert_eq!(got.tags, vec!["fine-tuning"]);
649    }
650
651    /// 3. Namespace targeting: export from namespace "a", import into namespace "b" on a
652    ///    fresh runtime — entities land in "b", and the source runtime's "a" is unaffected.
653    ///
654    ///    Note: source and destination are separate runtimes (separate in-memory DBs).
655    ///    Same-DB cross-namespace copy is not a portability use case — portability is about
656    ///    moving graphs between instances, not between namespaces within one instance.
657    #[tokio::test]
658    async fn namespace_targeting() {
659        let src = make_rt().await;
660        let tok_a = NamespaceToken::for_namespace(Namespace::parse("a").unwrap());
661        let tok_b = NamespaceToken::for_namespace(Namespace::parse("b").unwrap());
662        src.create_entity(&tok_a, "concept", None, "Sinkhorn", None, None, vec![])
663            .await
664            .unwrap();
665
666        let archive = src.export_kg(&tok_a).await.unwrap();
667        assert_eq!(archive.namespace, "a");
668
669        let dst = make_rt().await;
670        let summary = dst.import_kg(&archive, &tok_b).await.unwrap();
671        assert_eq!(summary.entities_imported, 1);
672
673        let in_b = dst.list_entities(&tok_b, None, None, 100, 0).await.unwrap();
674        assert_eq!(in_b.len(), 1);
675        assert_eq!(in_b[0].name, "Sinkhorn");
676
677        let in_a = src.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
678        assert_eq!(in_a.len(), 1);
679
680        let dst_a = dst.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
681        assert_eq!(dst_a.len(), 0);
682    }
683
684    /// 4. Format validation: wrong `format` field → InvalidInput.
685    #[tokio::test]
686    async fn format_validation_rejects_wrong_format() {
687        let rt = make_rt().await;
688        let tok = NamespaceToken::local();
689        let bad = KgArchive {
690            format: "wrong".to_string(),
691            version: "0.1".to_string(),
692            namespace: "local".to_string(),
693            exported_at: Utc::now(),
694            entities: vec![],
695            edges: vec![],
696        };
697        let err = rt.import_kg(&bad, &tok).await.unwrap_err();
698        assert!(matches!(err, RuntimeError::InvalidInput(_)));
699    }
700
701    /// 5. Unsupported archive version → InvalidInput.
702    #[tokio::test]
703    async fn import_unsupported_archive_version_returns_error() {
704        let rt = make_rt().await;
705        let tok = NamespaceToken::local();
706        let bad = KgArchive {
707            format: "khive-kg".to_string(),
708            version: "999.0".to_string(),
709            namespace: "local".to_string(),
710            exported_at: Utc::now(),
711            entities: vec![],
712            edges: vec![],
713        };
714        let err = rt.import_kg(&bad, &tok).await.unwrap_err();
715        assert!(
716            matches!(err, RuntimeError::InvalidInput(_)),
717            "expected InvalidInput, got {err:?}"
718        );
719        if let RuntimeError::InvalidInput(msg) = err {
720            assert!(
721                msg.contains("999.0"),
722                "error message should mention the unsupported version, got: {msg:?}"
723            );
724        }
725    }
726
727    /// ADR-115 Amendment 1 §3: an archive entity carrying the reserved
728    /// `khive:secret_gate` property key must be rejected before any upsert —
729    /// import is a caller-controlled write path and stays reservation-only.
730    #[tokio::test]
731    async fn import_entity_with_reserved_secret_gate_property_is_rejected() {
732        let rt = make_rt().await;
733        let tok = NamespaceToken::local();
734        let archive = KgArchive {
735            format: "khive-kg".to_string(),
736            version: "0.1".to_string(),
737            namespace: "local".to_string(),
738            exported_at: Utc::now(),
739            entities: vec![ExportedEntity {
740                id: Uuid::new_v4(),
741                kind: "concept".to_string(),
742                entity_type: None,
743                name: "ReservedKeyImport".to_string(),
744                description: None,
745                properties: Some(serde_json::json!({
746                    "khive:secret_gate": "exempted:content-sha256-manifest-v1"
747                })),
748                tags: vec![],
749                created_at: Utc::now(),
750                updated_at: Utc::now(),
751            }],
752            edges: vec![],
753        };
754
755        let err = rt.import_kg(&archive, &tok).await.unwrap_err();
756        assert!(
757            matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
758            "expected a reservation rejection, got {err:?}"
759        );
760
761        let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
762        assert!(
763            !entities.iter().any(|e| e.name == "ReservedKeyImport"),
764            "rejected archive import must not create the entity"
765        );
766    }
767
768    /// ADR-115 Amendment 1 §3: an archive edge carrying the reserved
769    /// `khive:secret_gate` property key is rejected in the same deterministic
770    /// pre-write pass as entities — edge metadata is a properties-bearing
771    /// write path.
772    #[tokio::test]
773    async fn import_edge_with_reserved_secret_gate_property_is_rejected() {
774        let rt = make_rt().await;
775        let tok = NamespaceToken::local();
776        let a = Uuid::new_v4();
777        let b = Uuid::new_v4();
778        let mk = |id: Uuid, name: &str| ExportedEntity {
779            id,
780            kind: "concept".to_string(),
781            entity_type: None,
782            name: name.to_string(),
783            description: None,
784            properties: None,
785            tags: vec![],
786            created_at: Utc::now(),
787            updated_at: Utc::now(),
788        };
789        let archive = KgArchive {
790            format: "khive-kg".to_string(),
791            version: "0.1".to_string(),
792            namespace: "local".to_string(),
793            exported_at: Utc::now(),
794            entities: vec![mk(a, "EdgeGateA"), mk(b, "EdgeGateB")],
795            edges: vec![ExportedEdge {
796                edge_id: Uuid::new_v4(),
797                source: a,
798                target: b,
799                relation: EdgeRelation::Extends,
800                weight: 0.5,
801                properties: Some(serde_json::json!({
802                    "khive:secret_gate": "exempted:content-sha256-manifest-v1"
803                })),
804                created_at: Utc::now(),
805                updated_at: Utc::now(),
806            }],
807        };
808
809        let err = rt.import_kg(&archive, &tok).await.unwrap_err();
810        assert!(
811            matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
812            "expected a reservation rejection, got {err:?}"
813        );
814
815        // The rejection happens before any write, so the archive's entities
816        // must not have been created either.
817        let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
818        assert!(
819            !entities.iter().any(|e| e.name == "EdgeGateA"),
820            "rejected archive import must not create any records"
821        );
822    }
823
824    /// ADR-115 Amendment 1 §3: edge metadata is in the unchanged
825    /// blocking-scanner class, so a credential-shaped value in edge
826    /// properties fails the import in the same pre-write pass.
827    #[tokio::test]
828    async fn import_edge_with_credential_shaped_property_is_rejected() {
829        let rt = make_rt().await;
830        let tok = NamespaceToken::local();
831        let a = Uuid::new_v4();
832        let b = Uuid::new_v4();
833        let mk = |id: Uuid, name: &str| ExportedEntity {
834            id,
835            kind: "concept".to_string(),
836            entity_type: None,
837            name: name.to_string(),
838            description: None,
839            properties: None,
840            tags: vec![],
841            created_at: Utc::now(),
842            updated_at: Utc::now(),
843        };
844        let archive = KgArchive {
845            format: "khive-kg".to_string(),
846            version: "0.1".to_string(),
847            namespace: "local".to_string(),
848            exported_at: Utc::now(),
849            entities: vec![mk(a, "EdgeScanA"), mk(b, "EdgeScanB")],
850            edges: vec![ExportedEdge {
851                edge_id: Uuid::new_v4(),
852                source: a,
853                target: b,
854                relation: EdgeRelation::Extends,
855                weight: 0.5,
856                properties: Some(serde_json::json!({
857                    "api_key": "AKIAFAKEKEY1234567890"
858                })),
859                created_at: Utc::now(),
860                updated_at: Utc::now(),
861            }],
862        };
863
864        let err = rt.import_kg(&archive, &tok).await.unwrap_err();
865        assert!(
866            matches!(err, RuntimeError::SecretDetected(_)),
867            "expected the blocking scanner to reject the value, got {err:?}"
868        );
869
870        let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
871        assert!(
872            !entities.iter().any(|e| e.name == "EdgeScanA"),
873            "rejected archive import must not create any records"
874        );
875    }
876
877    /// 6. Invalid relation in archive → InvalidInput.
878    #[test]
879    fn invalid_relation_rejected_at_deserialize() {
880        let json = r#"{
881            "format":"khive-kg","version":"0.1","namespace":"local",
882            "exported_at":"2026-01-01T00:00:00Z",
883            "entities":[],
884            "edges":[{"edge_id":"00000000-0000-0000-0000-000000000099",
885                       "source":"00000000-0000-0000-0000-000000000001",
886                       "target":"00000000-0000-0000-0000-000000000002",
887                       "relation":"related_to","weight":0.5}]
888        }"#;
889        let result: Result<KgArchive, _> = serde_json::from_str(json);
890        assert!(
891            result.is_err(),
892            "non-canonical relation should fail to deserialize"
893        );
894    }
895
896    // ── Dangling-edge validation tests ────────────────────────────────────────
897
898    /// 6. Edge with dangling source (source UUID not in entity table) is skipped.
899    ///
900    /// The archive has one entity + one edge whose source is a phantom UUID.
901    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
902    #[tokio::test]
903    async fn import_edge_with_dangling_source_is_skipped() {
904        let phantom_source = Uuid::parse_str("deadbeef-dead-4ead-dead-deadbeefcafe").unwrap();
905
906        let rt = make_rt().await;
907        let tok = NamespaceToken::local();
908        let real = rt
909            .create_entity(&tok, "concept", None, "Real", None, None, vec![])
910            .await
911            .unwrap();
912
913        let archive = KgArchive {
914            format: "khive-kg".to_string(),
915            version: "0.1".to_string(),
916            namespace: "local".to_string(),
917            exported_at: Utc::now(),
918            entities: vec![ExportedEntity {
919                id: real.id,
920                kind: "concept".to_string(),
921                entity_type: None,
922                name: "Real".to_string(),
923                description: None,
924                properties: None,
925                tags: vec![],
926                created_at: Utc::now(),
927                updated_at: Utc::now(),
928            }],
929            edges: vec![ExportedEdge {
930                edge_id: Uuid::new_v4(),
931                source: phantom_source,
932                target: real.id,
933                relation: EdgeRelation::Extends,
934                weight: 1.0,
935                properties: None,
936                created_at: Utc::now(),
937                updated_at: Utc::now(),
938            }],
939        };
940
941        let dst = make_rt().await;
942        let summary = dst.import_kg(&archive, &tok).await.unwrap();
943        assert_eq!(summary.entities_imported, 1);
944        assert_eq!(
945            summary.edges_imported, 0,
946            "dangling source must not be imported"
947        );
948        assert_eq!(
949            summary.edges_skipped, 1,
950            "dangling source must be counted as skipped"
951        );
952    }
953
954    /// 7. Edge with dangling target (target UUID not in entity table) is skipped.
955    ///
956    /// The archive has one entity + one edge whose target is a phantom UUID.
957    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
958    #[tokio::test]
959    async fn import_edge_with_dangling_target_is_skipped() {
960        let phantom_target = Uuid::parse_str("cafebabe-cafe-4abe-cafe-cafebabecafe").unwrap();
961
962        let rt = make_rt().await;
963        let tok = NamespaceToken::local();
964        let real = rt
965            .create_entity(&tok, "concept", None, "Source", None, None, vec![])
966            .await
967            .unwrap();
968
969        let archive = KgArchive {
970            format: "khive-kg".to_string(),
971            version: "0.1".to_string(),
972            namespace: "local".to_string(),
973            exported_at: Utc::now(),
974            entities: vec![ExportedEntity {
975                id: real.id,
976                kind: "concept".to_string(),
977                entity_type: None,
978                name: "Source".to_string(),
979                description: None,
980                properties: None,
981                tags: vec![],
982                created_at: Utc::now(),
983                updated_at: Utc::now(),
984            }],
985            edges: vec![ExportedEdge {
986                edge_id: Uuid::new_v4(),
987                source: real.id,
988                target: phantom_target,
989                relation: EdgeRelation::DependsOn,
990                weight: 0.8,
991                properties: None,
992                created_at: Utc::now(),
993                updated_at: Utc::now(),
994            }],
995        };
996
997        let dst = make_rt().await;
998        let summary = dst.import_kg(&archive, &tok).await.unwrap();
999        assert_eq!(summary.entities_imported, 1);
1000        assert_eq!(
1001            summary.edges_imported, 0,
1002            "dangling target must not be imported"
1003        );
1004        assert_eq!(
1005            summary.edges_skipped, 1,
1006            "dangling target must be counted as skipped"
1007        );
1008    }
1009
1010    /// 8. Mixed batch: some valid edges and some dangling edges — correct counts reported.
1011    ///
1012    /// Archive has 3 entities, 2 valid edges, and 1 dangling edge (phantom target).
1013    /// Import succeeds with edges_imported=2, edges_skipped=1.
1014    #[tokio::test]
1015    async fn import_mixed_edges_reports_correct_counts() {
1016        let phantom = Uuid::parse_str("11111111-1111-4111-8111-111111111111").unwrap();
1017
1018        let src = make_rt().await;
1019        let tok = NamespaceToken::local();
1020        let a = src
1021            .create_entity(&tok, "concept", None, "A", None, None, vec![])
1022            .await
1023            .unwrap();
1024        let b = src
1025            .create_entity(&tok, "concept", None, "B", None, None, vec![])
1026            .await
1027            .unwrap();
1028        let c = src
1029            .create_entity(&tok, "concept", None, "C", None, None, vec![])
1030            .await
1031            .unwrap();
1032
1033        let archive = KgArchive {
1034            format: "khive-kg".to_string(),
1035            version: "0.1".to_string(),
1036            namespace: "local".to_string(),
1037            exported_at: Utc::now(),
1038            entities: vec![
1039                ExportedEntity {
1040                    id: a.id,
1041                    kind: "concept".to_string(),
1042                    entity_type: None,
1043                    name: "A".to_string(),
1044                    description: None,
1045                    properties: None,
1046                    tags: vec![],
1047                    created_at: Utc::now(),
1048                    updated_at: Utc::now(),
1049                },
1050                ExportedEntity {
1051                    id: b.id,
1052                    kind: "concept".to_string(),
1053                    entity_type: None,
1054                    name: "B".to_string(),
1055                    description: None,
1056                    properties: None,
1057                    tags: vec![],
1058                    created_at: Utc::now(),
1059                    updated_at: Utc::now(),
1060                },
1061                ExportedEntity {
1062                    id: c.id,
1063                    kind: "concept".to_string(),
1064                    entity_type: None,
1065                    name: "C".to_string(),
1066                    description: None,
1067                    properties: None,
1068                    tags: vec![],
1069                    created_at: Utc::now(),
1070                    updated_at: Utc::now(),
1071                },
1072            ],
1073            edges: vec![
1074                ExportedEdge {
1075                    edge_id: Uuid::new_v4(),
1076                    source: a.id,
1077                    target: b.id,
1078                    relation: EdgeRelation::Extends,
1079                    weight: 1.0,
1080                    properties: None,
1081                    created_at: Utc::now(),
1082                    updated_at: Utc::now(),
1083                },
1084                ExportedEdge {
1085                    edge_id: Uuid::new_v4(),
1086                    source: b.id,
1087                    target: c.id,
1088                    // #1235: concept->concept is not in depends_on's endpoint
1089                    // contract; use variant_of (concept->concept is valid) so
1090                    // this fixture exercises "one dangling edge skipped" only,
1091                    // not an endpoint-contract violation this test isn't about.
1092                    relation: EdgeRelation::VariantOf,
1093                    weight: 0.9,
1094                    properties: None,
1095                    created_at: Utc::now(),
1096                    updated_at: Utc::now(),
1097                },
1098                ExportedEdge {
1099                    edge_id: Uuid::new_v4(),
1100                    source: a.id,
1101                    target: phantom,
1102                    relation: EdgeRelation::Enables,
1103                    weight: 0.5,
1104                    properties: None,
1105                    created_at: Utc::now(),
1106                    updated_at: Utc::now(),
1107                },
1108            ],
1109        };
1110
1111        let dst = make_rt().await;
1112        let summary = dst.import_kg(&archive, &tok).await.unwrap();
1113        assert_eq!(summary.entities_imported, 3);
1114        assert_eq!(
1115            summary.edges_imported, 2,
1116            "only valid edges must be imported"
1117        );
1118        assert_eq!(
1119            summary.edges_skipped, 1,
1120            "one dangling edge must be reported"
1121        );
1122    }
1123
1124    /// 9. All-valid edges produce edges_skipped=0 (no regression on the happy path).
1125    #[tokio::test]
1126    async fn import_all_valid_edges_reports_zero_skipped() {
1127        let src = make_rt().await;
1128        let tok = NamespaceToken::local();
1129        let e1 = src
1130            .create_entity(&tok, "concept", None, "E1", None, None, vec![])
1131            .await
1132            .unwrap();
1133        let e2 = src
1134            .create_entity(&tok, "concept", None, "E2", None, None, vec![])
1135            .await
1136            .unwrap();
1137        src.link(&tok, e1.id, e2.id, EdgeRelation::VariantOf, 0.7, None)
1138            .await
1139            .unwrap();
1140
1141        let archive = src.export_kg(&tok).await.unwrap();
1142        let dst = make_rt().await;
1143        let summary = dst.import_kg(&archive, &tok).await.unwrap();
1144        assert_eq!(summary.edges_imported, 1);
1145        assert_eq!(
1146            summary.edges_skipped, 0,
1147            "no edges should be skipped when all endpoints exist"
1148        );
1149    }
1150
1151    /// #1235: an edge whose (source kind, relation, target kind) triple violates the
1152    /// endpoint contract (here: `precedes` between two `concept` entities — `precedes`
1153    /// is restricted to document/dataset/artifact/service/project pairs) must be
1154    /// skipped by import the same way a dangling endpoint is, not written straight
1155    /// through with `graph.upsert_edge`.
1156    #[tokio::test]
1157    async fn import_edge_violating_endpoint_contract_is_skipped() {
1158        let src = make_rt().await;
1159        let tok = NamespaceToken::local();
1160        let e1 = src
1161            .create_entity(&tok, "concept", None, "E1", None, None, vec![])
1162            .await
1163            .unwrap();
1164        let e2 = src
1165            .create_entity(&tok, "concept", None, "E2", None, None, vec![])
1166            .await
1167            .unwrap();
1168
1169        let archive = KgArchive {
1170            format: "khive-kg".to_string(),
1171            version: "0.1".to_string(),
1172            namespace: "local".to_string(),
1173            exported_at: Utc::now(),
1174            entities: vec![
1175                ExportedEntity {
1176                    id: e1.id,
1177                    kind: "concept".to_string(),
1178                    entity_type: None,
1179                    name: "E1".to_string(),
1180                    description: None,
1181                    properties: None,
1182                    tags: vec![],
1183                    created_at: Utc::now(),
1184                    updated_at: Utc::now(),
1185                },
1186                ExportedEntity {
1187                    id: e2.id,
1188                    kind: "concept".to_string(),
1189                    entity_type: None,
1190                    name: "E2".to_string(),
1191                    description: None,
1192                    properties: None,
1193                    tags: vec![],
1194                    created_at: Utc::now(),
1195                    updated_at: Utc::now(),
1196                },
1197            ],
1198            edges: vec![ExportedEdge {
1199                edge_id: Uuid::new_v4(),
1200                source: e1.id,
1201                target: e2.id,
1202                relation: EdgeRelation::Precedes,
1203                weight: 1.0,
1204                properties: None,
1205                created_at: Utc::now(),
1206                updated_at: Utc::now(),
1207            }],
1208        };
1209
1210        let dst = make_rt().await;
1211        let summary = dst.import_kg(&archive, &tok).await.unwrap();
1212        assert_eq!(summary.entities_imported, 2);
1213        assert_eq!(
1214            summary.edges_imported, 0,
1215            "an endpoint-contract-violating edge must not be imported"
1216        );
1217        assert_eq!(
1218            summary.edges_skipped, 1,
1219            "an endpoint-contract-violating edge must be counted as skipped"
1220        );
1221        assert!(
1222            dst.neighbors(
1223                &tok,
1224                e1.id,
1225                khive_storage::types::Direction::Out,
1226                None,
1227                None
1228            )
1229            .await
1230            .unwrap()
1231            .is_empty(),
1232            "the contract-violating edge must not exist in the destination graph"
1233        );
1234    }
1235
1236    // ── edge_id contract tests ────────────────────────────────────────────────
1237
1238    /// 10. export_kg sets edge_id in the archive to the LinkId returned by link.
1239    #[tokio::test]
1240    async fn export_kg_preserves_edge_id() {
1241        let rt = make_rt().await;
1242        let tok = NamespaceToken::local();
1243        let a = rt
1244            .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
1245            .await
1246            .unwrap();
1247        let b = rt
1248            .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
1249            .await
1250            .unwrap();
1251        let stored_edge = rt
1252            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1253            .await
1254            .unwrap();
1255        let stored_id: Uuid = stored_edge.id.into();
1256
1257        let archive = rt.export_kg(&tok).await.unwrap();
1258        assert_eq!(archive.edges.len(), 1);
1259        assert_eq!(
1260            archive.edges[0].edge_id, stored_id,
1261            "exported edge_id must equal the LinkId returned by link"
1262        );
1263    }
1264
1265    /// 11. import_kg writes the archive edge identity and timestamps exactly.
1266    #[tokio::test]
1267    async fn import_kg_persists_edge_id_and_timestamps() {
1268        let src = make_rt().await;
1269        let tok = NamespaceToken::local();
1270        let a = src
1271            .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
1272            .await
1273            .unwrap();
1274        let b = src
1275            .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
1276            .await
1277            .unwrap();
1278        let stored_edge = src
1279            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1280            .await
1281            .unwrap();
1282        let original_id: Uuid = stored_edge.id.into();
1283
1284        let expected_created = chrono::DateTime::parse_from_rfc3339("2026-03-03T00:00:00Z")
1285            .unwrap()
1286            .with_timezone(&Utc);
1287        let expected_updated = chrono::DateTime::parse_from_rfc3339("2026-04-04T00:00:00Z")
1288            .unwrap()
1289            .with_timezone(&Utc);
1290        let mut archive = src.export_kg(&tok).await.unwrap();
1291        archive.edges[0].created_at = expected_created;
1292        archive.edges[0].updated_at = expected_updated;
1293        archive.edges[0].properties = Some(serde_json::json!({"confidence": 0.95}));
1294        let dst = make_rt().await;
1295        dst.import_kg(&archive, &tok).await.unwrap();
1296
1297        let imported_edge = dst.get_edge(&tok, original_id).await.unwrap();
1298        assert!(
1299            imported_edge.is_some(),
1300            "imported edge must be retrievable by the original edge_id"
1301        );
1302        let imported_edge = imported_edge.unwrap();
1303        assert_eq!(
1304            Uuid::from(imported_edge.id),
1305            original_id,
1306            "stored edge id must equal the archive edge_id"
1307        );
1308        assert_eq!(
1309            imported_edge.created_at, expected_created,
1310            "present edge created_at must not be replaced with import time"
1311        );
1312        assert_eq!(
1313            imported_edge.updated_at, expected_updated,
1314            "present edge updated_at must not be replaced with created_at or import time"
1315        );
1316        assert_eq!(
1317            imported_edge.metadata,
1318            Some(serde_json::json!({"confidence": 0.95})),
1319            "edge properties must persist as storage metadata"
1320        );
1321
1322        let reexported = dst.export_kg(&tok).await.unwrap();
1323        assert_eq!(
1324            reexported.edges[0].properties,
1325            Some(serde_json::json!({"confidence": 0.95})),
1326            "edge metadata must re-export as portable properties"
1327        );
1328    }
1329
1330    /// 12. Old archive (no edge_id field) deserializes, imports, and re-exports with the
1331    ///     same generated UUID — proving the generated ID survives the full round trip.
1332    ///
1333    ///     The fixture includes two entities so the edge is not skipped during import.
1334    #[tokio::test]
1335    async fn old_archive_missing_edge_id_round_trips() {
1336        let src_id = Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap();
1337        let tgt_id = Uuid::parse_str("00000000-0000-0000-0000-000000000002").unwrap();
1338
1339        // Simulate a pre-0.2 archive JSON where the edge lacks an edge_id field.
1340        let json = format!(
1341            r#"{{
1342                "format": "khive-kg",
1343                "version": "0.1",
1344                "namespace": "local",
1345                "exported_at": "2026-01-01T00:00:00Z",
1346                "entities": [
1347                    {{"id":"{src_id}","kind":"concept","name":"SrcNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}},
1348                    {{"id":"{tgt_id}","kind":"concept","name":"TgtNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}}
1349                ],
1350                "edges": [
1351                    {{
1352                        "source": "{src_id}",
1353                        "target": "{tgt_id}",
1354                        "relation": "extends",
1355                        "weight": 0.9
1356                    }}
1357                ]
1358            }}"#
1359        );
1360
1361        // serde(default) must assign a fresh non-nil UUID when edge_id is absent.
1362        let archive: KgArchive = serde_json::from_str(&json)
1363            .expect("old archive without edge_id must deserialize successfully");
1364        assert_eq!(archive.edges.len(), 1);
1365        let generated_id = archive.edges[0].edge_id;
1366        assert_ne!(
1367            generated_id,
1368            Uuid::nil(),
1369            "missing edge_id in old archive must get a fresh non-nil UUID"
1370        );
1371
1372        let rt = make_rt().await;
1373        let tok = NamespaceToken::local();
1374        let summary = rt.import_kg(&archive, &tok).await.unwrap();
1375        assert_eq!(summary.entities_imported, 2);
1376        assert_eq!(
1377            summary.edges_imported, 1,
1378            "edge must be imported when both endpoints exist"
1379        );
1380
1381        let stored = rt.get_edge(&tok, generated_id).await.unwrap();
1382        assert!(
1383            stored.is_some(),
1384            "imported edge must be retrievable by the generated edge_id"
1385        );
1386        assert_eq!(
1387            Uuid::from(stored.unwrap().id),
1388            generated_id,
1389            "stored edge id must equal the generated edge_id"
1390        );
1391
1392        let re_archive = rt.export_kg(&tok).await.unwrap();
1393        assert_eq!(re_archive.edges.len(), 1);
1394        assert_eq!(
1395            re_archive.edges[0].edge_id, generated_id,
1396            "re-exported edge_id must equal the ID generated on first import"
1397        );
1398    }
1399
1400    /// 13. Explicit export → import → export equality: the edge_id is unchanged across
1401    ///     a full round trip when the source archive already contains an edge_id.
1402    ///
1403    ///     Verifies by (source, target, relation) key that re-export emits the original ID.
1404    #[tokio::test]
1405    async fn export_import_export_edge_id_equality() {
1406        let src = make_rt().await;
1407        let tok = NamespaceToken::local();
1408        let a = src
1409            .create_entity(&tok, "concept", None, "NodeA", None, None, vec![])
1410            .await
1411            .unwrap();
1412        let b = src
1413            .create_entity(&tok, "concept", None, "NodeB", None, None, vec![])
1414            .await
1415            .unwrap();
1416        let stored = src
1417            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1418            .await
1419            .unwrap();
1420        let original_edge_id: Uuid = stored.id.into();
1421
1422        let archive1 = src.export_kg(&tok).await.unwrap();
1423        assert_eq!(archive1.edges.len(), 1);
1424        assert_eq!(
1425            archive1.edges[0].edge_id, original_edge_id,
1426            "first export must carry the stored edge_id"
1427        );
1428
1429        let dst = make_rt().await;
1430        dst.import_kg(&archive1, &tok).await.unwrap();
1431
1432        let archive2 = dst.export_kg(&tok).await.unwrap();
1433        assert_eq!(archive2.edges.len(), 1);
1434
1435        let re_edge = archive2
1436            .edges
1437            .iter()
1438            .find(|e| e.source == a.id && e.target == b.id && e.relation == EdgeRelation::Extends)
1439            .expect(
1440                "re-exported archive must contain the original edge by (source,target,relation)",
1441            );
1442        assert_eq!(
1443            re_edge.edge_id, original_edge_id,
1444            "edge_id must be identical across export → import → export"
1445        );
1446    }
1447}