1use 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#[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#[derive(Clone, Debug, Serialize, Deserialize)]
36pub struct ExportedEntity {
37 pub id: Uuid,
38 pub kind: String,
40 #[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#[derive(Clone, Debug, Serialize, Deserialize)]
56pub struct ExportedEdge {
57 #[serde(default = "Uuid::new_v4")]
62 pub edge_id: Uuid,
63 pub source: Uuid,
64 pub target: Uuid,
65 pub relation: EdgeRelation,
67 pub weight: f64,
68 #[serde(default, skip_serializing_if = "Option::is_none")]
70 pub properties: Option<serde_json::Value>,
71 #[serde(
74 default = "default_import_timestamp",
75 deserialize_with = "deserialize_import_timestamp"
76 )]
77 pub created_at: DateTime<Utc>,
78 #[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#[derive(Clone, Debug, Serialize, Deserialize)]
103pub struct ImportSummary {
104 pub entities_imported: usize,
105 pub edges_imported: usize,
106 pub edges_skipped: usize,
112 #[serde(default)]
115 pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
116}
117
118impl KhiveRuntime {
121 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 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 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 for (index, entity) in archive.entities.iter().enumerate() {
249 self.validate_entity_kind(&entity.kind)?;
250 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 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 embedding_truncation.merge(self.reindex_entity(token, &entity).await?);
299 entities_imported += 1;
300 }
301
302 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 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 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#[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 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 #[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 #[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 #[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 #[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 #[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 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 #[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 #[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 #[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 #[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 #[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 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 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 #[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}