1use std::collections::{HashMap, HashSet};
7
8use anyhow::Context;
9use chrono::{DateTime, Utc};
10use serde::{Deserialize, Serialize};
11use uuid::Uuid;
12
13use khive_storage::types::{EdgeFilter, LinkId, PageRequest};
14use khive_storage::{EdgeRelation, EntityFilter};
15use khive_types::{EntityKind, ImportKindPolicy};
16use std::str::FromStr;
17
18use crate::error::{RuntimeError, RuntimeResult};
19use crate::runtime::{KhiveRuntime, NamespaceToken};
20
21mod conflicts;
22pub use conflicts::{
23 ImportConflictMode, ImportConflictSummary, ImportOptions, ImportPolicySkipCause,
24 ImportPolicySkippedEdge,
25};
26
27pub fn parse_archive_timestamp(
32 value: Option<&str>,
33 fallback: DateTime<Utc>,
34) -> anyhow::Result<DateTime<Utc>> {
35 let Some(raw) = value else {
36 return Ok(fallback);
37 };
38 DateTime::parse_from_rfc3339(raw)
39 .map(|dt| dt.with_timezone(&Utc))
40 .with_context(|| format!("timestamp {raw:?} must be RFC3339"))
41}
42
43#[derive(Clone, Debug, Serialize, Deserialize)]
50pub struct KgArchive {
51 pub format: String,
52 pub version: String,
53 pub namespace: String,
54 pub exported_at: DateTime<Utc>,
55 pub entities: Vec<ExportedEntity>,
56 pub edges: Vec<ExportedEdge>,
57}
58
59#[derive(Clone, Debug, Serialize, Deserialize)]
61pub struct ExportedEntity {
62 pub id: Uuid,
63 pub kind: String,
65 #[serde(skip_serializing_if = "Option::is_none")]
67 pub entity_type: Option<String>,
68 pub name: String,
69 #[serde(skip_serializing_if = "Option::is_none")]
70 pub description: Option<String>,
71 #[serde(skip_serializing_if = "Option::is_none")]
72 pub properties: Option<serde_json::Value>,
73 #[serde(default)]
74 pub tags: Vec<String>,
75 pub created_at: DateTime<Utc>,
76 pub updated_at: DateTime<Utc>,
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize)]
81pub struct ExportedEdge {
82 #[serde(default = "Uuid::new_v4")]
87 pub edge_id: Uuid,
88 pub source: Uuid,
89 pub target: Uuid,
90 pub relation: EdgeRelation,
92 pub weight: f64,
93 #[serde(default, skip_serializing_if = "Option::is_none")]
95 pub properties: Option<serde_json::Value>,
96 #[serde(
99 default = "default_import_timestamp",
100 deserialize_with = "deserialize_import_timestamp"
101 )]
102 pub created_at: DateTime<Utc>,
103 #[serde(
106 default = "default_import_timestamp",
107 deserialize_with = "deserialize_import_timestamp"
108 )]
109 pub updated_at: DateTime<Utc>,
110}
111
112fn default_import_timestamp() -> DateTime<Utc> {
113 Utc::now()
114}
115
116fn deserialize_import_timestamp<'de, D>(deserializer: D) -> Result<DateTime<Utc>, D::Error>
117where
118 D: serde::Deserializer<'de>,
119{
120 let raw = String::deserialize(deserializer)?;
121 DateTime::parse_from_rfc3339(&raw)
122 .map(|timestamp| timestamp.with_timezone(&Utc))
123 .map_err(|error| serde::de::Error::custom(format!("timestamp must be RFC3339: {error}")))
124}
125
126#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "snake_case")]
129pub enum ImportEdgeSkipCause {
130 MissingSource,
132 MissingTarget,
134 EndpointContract,
136}
137
138#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
140pub struct ImportSkippedEdge {
141 pub edge_id: Uuid,
142 pub source: Uuid,
143 pub target: Uuid,
144 pub relation: EdgeRelation,
145 pub cause: ImportEdgeSkipCause,
146 #[serde(default, skip_serializing_if = "Option::is_none")]
148 pub error: Option<String>,
149}
150
151#[derive(Clone, Debug, Serialize, Deserialize)]
153pub struct ImportSummary {
154 pub entities_imported: usize,
155 pub edges_imported: usize,
156 pub edges_skipped: usize,
161 #[serde(default, skip_serializing_if = "Vec::is_empty")]
165 pub skipped_edges: Vec<ImportSkippedEdge>,
166 #[serde(default)]
169 pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
170}
171
172#[derive(Clone, Debug, Default, PartialEq, Eq)]
175pub struct ImportValidation {
176 pub unknown_entity_kinds: Vec<String>,
177}
178
179impl KhiveRuntime {
182 pub async fn export_kg(&self, token: &NamespaceToken) -> RuntimeResult<KgArchive> {
188 let ns = token.namespace().as_str().to_owned();
189
190 let entity_page = self
191 .entities(token)?
192 .query_entities(
193 &ns,
194 EntityFilter::default(),
195 PageRequest {
196 offset: 0,
197 limit: u32::MAX,
198 },
199 )
200 .await?;
201
202 let entities: Vec<ExportedEntity> = entity_page
203 .items
204 .into_iter()
205 .map(|e| {
206 let created_at =
207 DateTime::from_timestamp_micros(e.created_at).unwrap_or_else(Utc::now);
208 let updated_at =
209 DateTime::from_timestamp_micros(e.updated_at).unwrap_or_else(Utc::now);
210 ExportedEntity {
211 id: e.id,
212 kind: e.kind.to_string(),
213 entity_type: e.entity_type,
214 name: e.name,
215 description: e.description,
216 properties: e.properties,
217 tags: e.tags,
218 created_at,
219 updated_at,
220 }
221 })
222 .collect();
223
224 let source_ids: Vec<Uuid> = entities.iter().map(|e| e.id).collect();
225 let edges = if source_ids.is_empty() {
226 Vec::new()
227 } else {
228 let filter = EdgeFilter {
229 source_ids: source_ids.clone(),
230 ..Default::default()
231 };
232 let edge_page = self
233 .graph(token)?
234 .query_edges(
235 filter,
236 Vec::new(),
237 PageRequest {
238 offset: 0,
239 limit: u32::MAX,
240 },
241 )
242 .await?;
243
244 let id_set: HashSet<Uuid> = source_ids.into_iter().collect();
245 edge_page
246 .items
247 .into_iter()
248 .filter(|e| id_set.contains(&e.source_id))
249 .map(|e| ExportedEdge {
250 edge_id: e.id.into(),
251 source: e.source_id,
252 target: e.target_id,
253 relation: e.relation,
254 weight: e.weight,
255 properties: e.metadata,
256 created_at: e.created_at,
257 updated_at: e.updated_at,
258 })
259 .collect()
260 };
261
262 Ok(KgArchive {
263 format: "khive-kg".to_string(),
264 version: "0.1".to_string(),
265 namespace: ns,
266 exported_at: Utc::now(),
267 entities,
268 edges,
269 })
270 }
271
272 pub async fn export_kg_json(&self, token: &NamespaceToken) -> RuntimeResult<String> {
274 let archive = self.export_kg(token).await?;
275 serde_json::to_string(&archive).map_err(|e| RuntimeError::InvalidInput(e.to_string()))
276 }
277
278 pub async fn import_kg(
287 &self,
288 archive: &KgArchive,
289 token: &NamespaceToken,
290 ) -> RuntimeResult<ImportSummary> {
291 self.import_kg_with_policy(archive, token, ImportKindPolicy::Strict)
292 .await
293 }
294
295 pub fn validate_kg_import(
297 &self,
298 archive: &KgArchive,
299 policy: ImportKindPolicy,
300 ) -> RuntimeResult<ImportValidation> {
301 if archive.format != "khive-kg" {
302 return Err(RuntimeError::InvalidInput(format!(
303 "unsupported archive format {:?}; expected \"khive-kg\"",
304 archive.format
305 )));
306 }
307 if archive.version != "0.1" {
308 return Err(RuntimeError::InvalidInput(format!(
309 "unsupported archive version {:?}; supported: \"0.1\"",
310 archive.version
311 )));
312 }
313
314 let kinds = self.import_entity_kind_registry()?;
318 let mut validation = ImportValidation::default();
319 let mut seen_unknown = HashSet::new();
320 for (index, entity) in archive.entities.iter().enumerate() {
321 if entity.kind.trim().is_empty() {
322 return Err(RuntimeError::InvalidInput(format!(
323 "archive entity {index} kind must be non-blank"
324 )));
325 }
326 let base_kind = EntityKind::from_str(&entity.kind).is_ok();
327 let normalized = entity.kind.trim().to_ascii_lowercase();
328 let known =
329 kinds.iter().any(|kind| kind == &entity.kind) || (kinds.is_empty() && base_kind);
330 if !known {
331 let recognized = base_kind
334 || kinds
335 .iter()
336 .any(|kind| kind.eq_ignore_ascii_case(&normalized));
337 if policy == ImportKindPolicy::Strict || recognized {
338 let valid = if kinds.is_empty() {
339 EntityKind::ALL
340 .iter()
341 .map(|kind| kind.name())
342 .collect::<Vec<_>>()
343 .join(", ")
344 } else {
345 kinds.join(", ")
346 };
347 return Err(RuntimeError::InvalidInput(format!(
348 "archive entity {index} ({}) has unknown entity kind {:?} (or non-canonical spelling); valid: {valid}",
349 entity.id, entity.kind
350 )));
351 }
352 if seen_unknown.insert(entity.kind.clone()) {
353 validation.unknown_entity_kinds.push(entity.kind.clone());
354 }
355 }
356 crate::secret_gate::reject_reserved_secret_gate_property(entity.properties.as_ref())?;
361 if entity.name.trim().is_empty() {
362 return Err(RuntimeError::InvalidInput(format!(
363 "archive entity {index} ({}) name must be non-blank",
364 entity.id
365 )));
366 }
367 }
368 for (index, edge) in archive.edges.iter().enumerate() {
369 let record = format!("edge[{index}]");
370 crate::operations::validate_edge_weight(edge.weight)?;
371 crate::secret_gate::reject_reserved_secret_gate_property(edge.properties.as_ref())?;
376 if let Some(p) = edge.properties.as_ref() {
377 crate::secret_gate::check_json_at(p, &record, "properties")?;
378 }
379 }
380
381 Ok(validation)
382 }
383
384 pub async fn import_kg_with_policy(
388 &self,
389 archive: &KgArchive,
390 token: &NamespaceToken,
391 policy: ImportKindPolicy,
392 ) -> RuntimeResult<ImportSummary> {
393 let validation = self.validate_kg_import(archive, policy)?;
394 for kind in validation.unknown_entity_kinds {
395 tracing::warn!(target: "khive.import.schema",
396 kind = %crate::secret_gate::bounded_masked_log_text(&kind),
397 "preserving unknown entity kind during explicit import");
398 }
399 let ns = token.namespace().as_str().to_owned();
400
401 let store = self.entities(token)?;
402 let mut entities_imported = 0usize;
403 let mut embedding_truncation = crate::retrieval::EmbeddingTruncationReport::default();
404 for page in archive
405 .entities
406 .chunks(crate::retrieval::EMBEDDING_BATCH_PAGE_SIZE)
407 {
408 let entities: Vec<khive_storage::entity::Entity> = page
409 .iter()
410 .map(|ee| khive_storage::entity::Entity {
411 entity_type: ee.entity_type.clone(),
412 description: ee.description.clone(),
413 properties: ee.properties.clone(),
414 tags: ee.tags.clone(),
415 ..khive_storage::entity::Entity::minimal(
416 ee.id,
417 ns.clone(),
418 ee.kind.clone(),
419 ee.name.clone(),
420 ee.created_at.timestamp_micros(),
421 ee.updated_at.timestamp_micros(),
422 )
423 })
424 .collect();
425 let texts: Vec<String> = entities
426 .iter()
427 .map(crate::curation::entity_embedding_text)
428 .collect();
429 let mut embeddings: Vec<HashMap<String, crate::retrieval::DocumentEmbeddingOutcome>> =
430 (0..entities.len()).map(|_| HashMap::new()).collect();
431 for model_name in self.registered_embedding_model_names() {
432 match self
433 .embed_document_batch_with_model_outcomes_for_token(token, &model_name, &texts)
434 .await
435 {
436 Ok(outcomes) => {
437 for (slot, outcome) in embeddings.iter_mut().zip(outcomes) {
438 slot.insert(model_name.clone(), outcome);
439 }
440 }
441 Err(error) => {
442 tracing::warn!(
443 model = %model_name,
444 error = %error,
445 "import_kg: batch embed failed; retrying records individually"
446 );
447 }
448 }
449 }
450 for (entity, outcomes) in entities.into_iter().zip(embeddings) {
451 store.upsert_entity(entity.clone()).await?;
452 embedding_truncation.merge(
455 self.reindex_entity_with_precomputed(token, &entity, outcomes)
456 .await?,
457 );
458 entities_imported += 1;
459 }
460 }
461
462 let graph = self.graph(token)?;
466 let mut edges_imported = 0usize;
467 let mut skipped_edges = Vec::new();
468 for ee in &archive.edges {
469 let source_ok = match self.get_entity(token, ee.source).await {
470 Ok(_) => true,
471 Err(RuntimeError::NotFound(_)) => false,
472 Err(e) => return Err(e),
473 };
474 if !source_ok {
475 tracing::warn!(
476 source = %ee.source,
477 target = %ee.target,
478 relation = ?ee.relation,
479 "import_kg: skipping edge — source entity not found in namespace {ns:?}"
480 );
481 skipped_edges.push(ImportSkippedEdge {
482 edge_id: ee.edge_id,
483 source: ee.source,
484 target: ee.target,
485 relation: ee.relation,
486 cause: ImportEdgeSkipCause::MissingSource,
487 error: None,
488 });
489 continue;
490 }
491 let target_ok = match self.get_entity(token, ee.target).await {
492 Ok(_) => true,
493 Err(RuntimeError::NotFound(_)) => false,
494 Err(e) => return Err(e),
495 };
496 if !target_ok {
497 tracing::warn!(
498 source = %ee.source,
499 target = %ee.target,
500 relation = ?ee.relation,
501 "import_kg: skipping edge — target entity not found in namespace {ns:?}"
502 );
503 skipped_edges.push(ImportSkippedEdge {
504 edge_id: ee.edge_id,
505 source: ee.source,
506 target: ee.target,
507 relation: ee.relation,
508 cause: ImportEdgeSkipCause::MissingTarget,
509 error: None,
510 });
511 continue;
512 }
513 match self
518 .validate_edge_relation_endpoints(token, ee.source, ee.target, ee.relation)
519 .await
520 {
521 Ok(_) => {}
522 Err(e @ (RuntimeError::InvalidInput(_) | RuntimeError::NotFound(_))) => {
523 tracing::warn!(
524 source = %ee.source,
525 target = %ee.target,
526 relation = ?ee.relation,
527 error = %e,
528 "import_kg: skipping edge — endpoint contract violation in namespace {ns:?}"
529 );
530 skipped_edges.push(ImportSkippedEdge {
531 edge_id: ee.edge_id,
532 source: ee.source,
533 target: ee.target,
534 relation: ee.relation,
535 cause: ImportEdgeSkipCause::EndpointContract,
536 error: Some(e.to_string()),
537 });
538 continue;
539 }
540 Err(e) => return Err(e),
541 }
542 let edge = khive_storage::types::Edge {
543 id: LinkId::from(ee.edge_id),
544 namespace: ns.clone(),
545 source_id: ee.source,
546 target_id: ee.target,
547 relation: ee.relation,
548 weight: ee.weight,
549 created_at: ee.created_at,
550 updated_at: ee.updated_at,
551 deleted_at: None,
552 metadata: ee.properties.clone(),
553 target_backend: None,
554 };
555 graph.upsert_edge(edge).await?;
556 edges_imported += 1;
557 }
558
559 Ok(ImportSummary {
560 entities_imported,
561 edges_imported,
562 edges_skipped: skipped_edges.len(),
563 skipped_edges,
564 embedding_truncation,
565 })
566 }
567
568 pub async fn import_kg_json(
570 &self,
571 json: &str,
572 token: &NamespaceToken,
573 ) -> RuntimeResult<ImportSummary> {
574 self.import_kg_json_with_policy(json, token, ImportKindPolicy::Strict)
575 .await
576 }
577
578 pub async fn import_kg_json_with_policy(
581 &self,
582 json: &str,
583 token: &NamespaceToken,
584 policy: ImportKindPolicy,
585 ) -> RuntimeResult<ImportSummary> {
586 let archive: KgArchive =
587 serde_json::from_str(json).map_err(|e| RuntimeError::InvalidInput(e.to_string()))?;
588 self.import_kg_with_policy(&archive, token, policy).await
589 }
590}
591
592#[cfg(test)]
593#[path = "portability_import_policy_tests.rs"]
594mod import_policy_tests;
595
596#[cfg(test)]
601mod tests {
602 use std::sync::atomic::{AtomicUsize, Ordering};
603 use std::sync::Arc;
604
605 use super::*;
606 use crate::runtime::{KhiveRuntime, NamespaceToken};
607 use crate::{EmbedderProvider, Namespace};
608 use async_trait::async_trait;
609 use khive_storage::EdgeRelation;
610 use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService, MAX_TEXT_BYTES};
611
612 const IMPORT_TEST_MODEL: &str = "all-minilm-l6-v2";
613 const IMPORT_BATCH_MODEL: &str = "import-batch-model";
614 const IMPORT_BATCH_MODEL_TWO: &str = "import-batch-model-two";
615
616 struct CountingImportService {
617 calls: Arc<AtomicUsize>,
618 reject_poison: bool,
619 }
620
621 #[async_trait]
622 impl EmbeddingService for CountingImportService {
623 async fn embed(
624 &self,
625 texts: &[String],
626 _model: EmbeddingModel,
627 ) -> std::result::Result<Vec<Vec<f32>>, EmbedError> {
628 self.calls.fetch_add(1, Ordering::SeqCst);
629 if self.reject_poison
630 && (texts.len() > 1 || texts.iter().any(|text| text.contains("poison")))
631 {
632 return Err(EmbedError::InferenceFailed("poison input".into()));
633 }
634 Ok(texts
635 .iter()
636 .map(|text| {
637 vec![
638 text.len() as f32,
639 text.bytes().map(u32::from).sum::<u32>() as f32,
640 text.as_bytes().first().copied().unwrap_or_default() as f32,
641 text.as_bytes().last().copied().unwrap_or_default() as f32,
642 ]
643 })
644 .collect())
645 }
646
647 fn supports_model(&self, _model: EmbeddingModel) -> bool {
648 true
649 }
650
651 fn name(&self) -> &'static str {
652 "import-batch-counting-service"
653 }
654 }
655
656 struct CountingImportProvider {
657 name: &'static str,
658 calls: Arc<AtomicUsize>,
659 reject_poison: bool,
660 }
661
662 #[async_trait]
663 impl EmbedderProvider for CountingImportProvider {
664 fn name(&self) -> &str {
665 self.name
666 }
667
668 fn dimensions(&self) -> usize {
669 4
670 }
671
672 async fn build(&self) -> std::result::Result<Arc<dyn EmbeddingService>, RuntimeError> {
673 Ok(Arc::new(CountingImportService {
674 calls: Arc::clone(&self.calls),
675 reject_poison: self.reject_poison,
676 }))
677 }
678 }
679
680 fn batch_archive(names: impl IntoIterator<Item = String>) -> KgArchive {
681 KgArchive {
682 format: "khive-kg".to_string(),
683 version: "0.1".to_string(),
684 namespace: "local".to_string(),
685 exported_at: Utc::now(),
686 entities: names
687 .into_iter()
688 .map(|name| ExportedEntity {
689 id: Uuid::new_v4(),
690 kind: "concept".to_string(),
691 entity_type: None,
692 name,
693 description: Some("batch body".to_string()),
694 properties: None,
695 tags: vec![],
696 created_at: Utc::now(),
697 updated_at: Utc::now(),
698 })
699 .collect(),
700 edges: vec![],
701 }
702 }
703
704 struct ImportEmbeddingService;
705
706 #[async_trait]
707 impl EmbeddingService for ImportEmbeddingService {
708 async fn embed(
709 &self,
710 texts: &[String],
711 _model: EmbeddingModel,
712 ) -> std::result::Result<Vec<Vec<f32>>, EmbedError> {
713 let dimensions = EmbeddingModel::AllMiniLmL6V2.dimensions();
714 Ok(texts.iter().map(|_| vec![1.0; dimensions]).collect())
715 }
716
717 fn supports_model(&self, _model: EmbeddingModel) -> bool {
718 true
719 }
720
721 fn name(&self) -> &'static str {
722 "kg-import-truncation-test"
723 }
724 }
725
726 struct ImportEmbeddingProvider;
727
728 #[async_trait]
729 impl EmbedderProvider for ImportEmbeddingProvider {
730 fn name(&self) -> &str {
731 IMPORT_TEST_MODEL
732 }
733
734 fn dimensions(&self) -> usize {
735 EmbeddingModel::AllMiniLmL6V2.dimensions()
736 }
737
738 async fn build(&self) -> std::result::Result<Arc<dyn EmbeddingService>, RuntimeError> {
739 Ok(Arc::new(ImportEmbeddingService))
740 }
741 }
742
743 async fn make_rt() -> KhiveRuntime {
744 KhiveRuntime::memory().expect("in-memory runtime")
745 }
746
747 fn make_rt_with_embedder() -> KhiveRuntime {
748 let runtime = KhiveRuntime::memory().expect("in-memory runtime");
749 runtime.register_embedder(ImportEmbeddingProvider);
750 runtime
751 }
752
753 #[test]
754 fn archive_timestamp_falls_back_only_when_absent_and_converts_offsets_to_utc() {
755 let fallback = DateTime::parse_from_rfc3339("2020-01-01T00:00:00Z")
756 .unwrap()
757 .with_timezone(&Utc);
758 assert_eq!(parse_archive_timestamp(None, fallback).unwrap(), fallback);
759
760 let utc = parse_archive_timestamp(Some("2024-05-06T07:08:09Z"), fallback).unwrap();
761 assert_eq!(utc.to_rfc3339(), "2024-05-06T07:08:09+00:00");
762
763 let offset = parse_archive_timestamp(Some("2024-05-06T09:08:09+02:00"), fallback).unwrap();
764 assert_eq!(offset, utc);
765
766 let err = parse_archive_timestamp(Some("2024-05-06 07:08:09"), fallback).unwrap_err();
767 let text = format!("{err:#}");
768 assert!(text.contains("\"2024-05-06 07:08:09\""), "{text}");
769 assert!(text.contains("must be RFC3339"), "{text}");
770 assert!(
771 err.chain().count() > 1,
772 "parser source error is kept: {text}"
773 );
774 }
775
776 #[tokio::test]
777 async fn import_batches_provider_calls_and_matches_per_record_reindex_vectors() {
778 let token = NamespaceToken::local();
779 let archive = batch_archive((0..257).map(|index| format!("Batch entity {index}")));
780 let ids: Vec<Uuid> = archive.entities.iter().map(|entity| entity.id).collect();
781 let calls = Arc::new(AtomicUsize::new(0));
782 let runtime = KhiveRuntime::memory().unwrap();
783 runtime.register_embedder(CountingImportProvider {
784 name: IMPORT_BATCH_MODEL,
785 calls: Arc::clone(&calls),
786 reject_poison: false,
787 });
788 let usage = crate::usage::UsageContext::new();
789 let summary = crate::usage::scope(usage.clone(), runtime.import_kg(&archive, &token))
790 .await
791 .unwrap();
792 assert_eq!(summary.entities_imported, ids.len());
793 assert_eq!(usage.snapshot()["embed_calls"], ids.len() as u64);
794 assert_eq!(
795 calls.load(Ordering::SeqCst),
796 2,
797 "257 records need two provider batches"
798 );
799
800 let singles = KhiveRuntime::memory().unwrap();
801 let singleton_calls = Arc::new(AtomicUsize::new(0));
802 singles.register_embedder(CountingImportProvider {
803 name: IMPORT_BATCH_MODEL,
804 calls: Arc::clone(&singleton_calls),
805 reject_poison: false,
806 });
807 for id in &ids {
808 let entity = runtime.get_entity(&token, *id).await.unwrap();
809 singles
810 .entities(&token)
811 .unwrap()
812 .upsert_entity(entity.clone())
813 .await
814 .unwrap();
815 singles.reindex_entity(&token, &entity).await.unwrap();
816 }
817 assert_eq!(singleton_calls.load(Ordering::SeqCst), ids.len());
818 let batched_vectors = runtime
819 .vectors_for_model(&token, IMPORT_BATCH_MODEL)
820 .unwrap()
821 .get_vectors(&ids, "local", "entity.body")
822 .await
823 .unwrap();
824 let singleton_vectors = singles
825 .vectors_for_model(&token, IMPORT_BATCH_MODEL)
826 .unwrap()
827 .get_vectors(&ids, "local", "entity.body")
828 .await
829 .unwrap();
830 assert_eq!(batched_vectors.len(), ids.len());
831 assert_eq!(batched_vectors, singleton_vectors);
832 }
833
834 #[tokio::test]
835 async fn import_batches_each_registered_model_once_per_page() {
836 let token = NamespaceToken::local();
837 let archive = batch_archive(["alpha", "beta", "gamma"].map(str::to_string));
838 let calls_a = Arc::new(AtomicUsize::new(0));
839 let calls_b = Arc::new(AtomicUsize::new(0));
840 let runtime = KhiveRuntime::memory().unwrap();
841 for (name, calls) in [
842 (IMPORT_BATCH_MODEL, Arc::clone(&calls_a)),
843 (IMPORT_BATCH_MODEL_TWO, Arc::clone(&calls_b)),
844 ] {
845 runtime.register_embedder(CountingImportProvider {
846 name,
847 calls,
848 reject_poison: false,
849 });
850 }
851 runtime.import_kg(&archive, &token).await.unwrap();
852 assert_eq!(calls_a.load(Ordering::SeqCst), 1);
853 assert_eq!(calls_b.load(Ordering::SeqCst), 1);
854 let ids: Vec<Uuid> = archive.entities.iter().map(|entity| entity.id).collect();
855 for model in [IMPORT_BATCH_MODEL, IMPORT_BATCH_MODEL_TWO] {
856 assert_eq!(
857 runtime
858 .vectors_for_model(&token, model)
859 .unwrap()
860 .get_vectors(&ids, "local", "entity.body")
861 .await
862 .unwrap()
863 .len(),
864 ids.len()
865 );
866 }
867 }
868
869 #[tokio::test]
870 async fn import_failed_batch_isolates_poison_without_duplicate_vector_writes() {
871 use khive_storage::types::{SqlStatement, SqlValue};
872
873 let token = NamespaceToken::local();
874 let archive = batch_archive(["good one", "poison", "good two"].map(str::to_string));
875 let ids: Vec<Uuid> = archive.entities.iter().map(|entity| entity.id).collect();
876 let calls = Arc::new(AtomicUsize::new(0));
877 let runtime = KhiveRuntime::memory().unwrap();
878 runtime.register_embedder(CountingImportProvider {
879 name: IMPORT_BATCH_MODEL,
880 calls: Arc::clone(&calls),
881 reject_poison: true,
882 });
883 let summary = runtime.import_kg(&archive, &token).await.unwrap();
884 assert_eq!(summary.entities_imported, 3);
885 assert_eq!(
886 calls.load(Ordering::SeqCst),
887 4,
888 "one failed page plus three singleton retries"
889 );
890 let vectors = runtime
891 .vectors_for_model(&token, IMPORT_BATCH_MODEL)
892 .unwrap()
893 .get_vectors(&ids, "local", "entity.body")
894 .await
895 .unwrap();
896 assert_eq!(vectors.len(), 2);
897 assert!(!vectors.contains_key(&ids[1]));
898 let mut reader = runtime.sql().reader().await.unwrap();
899 let rows = reader
900 .query_all(SqlStatement {
901 sql: "SELECT COUNT(*) FROM ann_write_log WHERE embedding_model = ?1 AND op = 'upsert'".into(),
902 params: vec![SqlValue::Text(IMPORT_BATCH_MODEL.into())],
903 label: Some("import-batch-upsert-count".into()),
904 })
905 .await
906 .unwrap();
907 assert!(matches!(&rows[0].columns[0].value, SqlValue::Integer(2)));
908 let provenance = reader
909 .query_scalar(SqlStatement {
910 sql: "SELECT COUNT(*) FROM vector_provenance WHERE model_key = ?1".into(),
911 params: vec![SqlValue::Text(crate::config::sanitize_key(
912 IMPORT_BATCH_MODEL,
913 ))],
914 label: Some("import-batch-provenance-count".into()),
915 })
916 .await
917 .unwrap();
918 assert!(matches!(provenance, Some(SqlValue::Integer(0))));
919 }
920
921 #[tokio::test]
922 async fn import_summary_reports_actual_embedding_truncation() {
923 let runtime = make_rt_with_embedder();
924 let token = NamespaceToken::local();
925 let archive = KgArchive {
926 format: "khive-kg".to_string(),
927 version: "0.1".to_string(),
928 namespace: "local".to_string(),
929 exported_at: Utc::now(),
930 entities: vec![ExportedEntity {
931 id: Uuid::new_v4(),
932 kind: "concept".to_string(),
933 entity_type: None,
934 name: "Imported long entity".to_string(),
935 description: Some("x".repeat(MAX_TEXT_BYTES + 1)),
936 properties: None,
937 tags: vec![],
938 created_at: Utc::now(),
939 updated_at: Utc::now(),
940 }],
941 edges: vec![],
942 };
943
944 let summary = runtime
945 .import_kg(&archive, &token)
946 .await
947 .expect("import with bounded embedding input");
948
949 assert_eq!(summary.entities_imported, 1);
950 assert_eq!(summary.embedding_truncation.truncated, 1);
951 assert!(summary.embedding_truncation.discarded_bytes > 0);
952 let wire = serde_json::to_value(&summary).expect("serialize import summary");
953 assert_eq!(wire["embedding_truncation"]["truncated"], 1);
954 }
955
956 #[tokio::test]
957 async fn import_rejects_whitespace_name_before_any_entity_write() {
958 let runtime = make_rt().await;
959 let token = NamespaceToken::local();
960 let valid_id = Uuid::new_v4();
961 let archive = KgArchive {
962 format: "khive-kg".to_string(),
963 version: "0.1".to_string(),
964 namespace: "local".to_string(),
965 exported_at: Utc::now(),
966 entities: vec![
967 ExportedEntity {
968 id: valid_id,
969 kind: "concept".to_string(),
970 entity_type: None,
971 name: "Must not be written".to_string(),
972 description: None,
973 properties: None,
974 tags: vec![],
975 created_at: Utc::now(),
976 updated_at: Utc::now(),
977 },
978 ExportedEntity {
979 id: Uuid::new_v4(),
980 kind: "concept".to_string(),
981 entity_type: None,
982 name: " \t\n ".to_string(),
983 description: None,
984 properties: None,
985 tags: vec![],
986 created_at: Utc::now(),
987 updated_at: Utc::now(),
988 },
989 ],
990 edges: vec![],
991 };
992
993 let err = runtime
994 .import_kg(&archive, &token)
995 .await
996 .expect_err("whitespace-only entity names must fail the whole import");
997 assert!(
998 err.to_string().contains("non-blank"),
999 "error must explain the name invariant: {err}"
1000 );
1001 assert!(
1002 runtime.get_entity(&token, valid_id).await.is_err(),
1003 "deterministic validation must finish before the first entity write"
1004 );
1005 }
1006
1007 #[tokio::test]
1009 async fn roundtrip_entities_and_edges() {
1010 let src = make_rt().await;
1011 let tok = NamespaceToken::local();
1012 let e1 = src
1013 .create_entity(
1014 &tok,
1015 "concept",
1016 None,
1017 "FlashAttention",
1018 Some("fast attention"),
1019 None,
1020 vec![],
1021 )
1022 .await
1023 .unwrap();
1024 let e2 = src
1025 .create_entity(
1026 &tok,
1027 "concept",
1028 None,
1029 "FlashAttention-2",
1030 None,
1031 None,
1032 vec![],
1033 )
1034 .await
1035 .unwrap();
1036 let e3 = src
1037 .create_entity(
1038 &tok,
1039 "person",
1040 None,
1041 "Tri Dao",
1042 None,
1043 None,
1044 vec!["author".into()],
1045 )
1046 .await
1047 .unwrap();
1048 src.link(&tok, e2.id, e1.id, EdgeRelation::Extends, 1.0, None)
1049 .await
1050 .unwrap();
1051 src.link(&tok, e1.id, e3.id, EdgeRelation::IntroducedBy, 0.9, None)
1052 .await
1053 .unwrap();
1054
1055 let archive = src.export_kg(&tok).await.unwrap();
1056 assert_eq!(archive.entities.len(), 3);
1057 assert_eq!(archive.edges.len(), 2);
1058 assert_eq!(archive.format, "khive-kg");
1059 assert_eq!(archive.version, "0.1");
1060
1061 let dst = make_rt().await;
1062 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1063 assert_eq!(summary.entities_imported, 3);
1064 assert_eq!(summary.edges_imported, 2);
1065
1066 let got = dst.get_entity(&tok, e1.id).await.unwrap();
1067 assert_eq!(got.name, "FlashAttention");
1068 assert_eq!(got.description.as_deref(), Some("fast attention"));
1069 }
1070
1071 #[tokio::test]
1073 async fn json_roundtrip() {
1074 let src = make_rt().await;
1075 let tok = NamespaceToken::local();
1076 let e1 = src
1077 .create_entity(
1078 &tok,
1079 "concept",
1080 None,
1081 "LoRA",
1082 Some("low-rank adaptation"),
1083 Some(serde_json::json!({"year": "2021"})),
1084 vec!["fine-tuning".into()],
1085 )
1086 .await
1087 .unwrap();
1088 let e2 = src
1089 .create_entity(&tok, "concept", None, "QLoRA", None, None, vec![])
1090 .await
1091 .unwrap();
1092 src.link(&tok, e2.id, e1.id, EdgeRelation::VariantOf, 0.9, None)
1093 .await
1094 .unwrap();
1095
1096 let json_str = src.export_kg_json(&tok).await.unwrap();
1097 assert!(json_str.contains("khive-kg"));
1098
1099 let dst = make_rt().await;
1100 let summary = dst.import_kg_json(&json_str, &tok).await.unwrap();
1101 assert_eq!(summary.entities_imported, 2);
1102 assert_eq!(summary.edges_imported, 1);
1103
1104 let got = dst.get_entity(&tok, e1.id).await.unwrap();
1105 assert_eq!(got.tags, vec!["fine-tuning"]);
1106 }
1107
1108 #[tokio::test]
1115 async fn namespace_targeting() {
1116 let src = make_rt().await;
1117 let tok_a = NamespaceToken::for_namespace(Namespace::parse("a").unwrap());
1118 let tok_b = NamespaceToken::for_namespace(Namespace::parse("b").unwrap());
1119 src.create_entity(&tok_a, "concept", None, "Sinkhorn", None, None, vec![])
1120 .await
1121 .unwrap();
1122
1123 let archive = src.export_kg(&tok_a).await.unwrap();
1124 assert_eq!(archive.namespace, "a");
1125
1126 let dst = make_rt().await;
1127 let summary = dst.import_kg(&archive, &tok_b).await.unwrap();
1128 assert_eq!(summary.entities_imported, 1);
1129
1130 let in_b = dst.list_entities(&tok_b, None, None, 100, 0).await.unwrap();
1131 assert_eq!(in_b.len(), 1);
1132 assert_eq!(in_b[0].name, "Sinkhorn");
1133
1134 let in_a = src.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
1135 assert_eq!(in_a.len(), 1);
1136
1137 let dst_a = dst.list_entities(&tok_a, None, None, 100, 0).await.unwrap();
1138 assert_eq!(dst_a.len(), 0);
1139 }
1140
1141 #[tokio::test]
1143 async fn format_validation_rejects_wrong_format() {
1144 let rt = make_rt().await;
1145 let tok = NamespaceToken::local();
1146 let bad = KgArchive {
1147 format: "wrong".to_string(),
1148 version: "0.1".to_string(),
1149 namespace: "local".to_string(),
1150 exported_at: Utc::now(),
1151 entities: vec![],
1152 edges: vec![],
1153 };
1154 let err = rt.import_kg(&bad, &tok).await.unwrap_err();
1155 assert!(matches!(err, RuntimeError::InvalidInput(_)));
1156 }
1157
1158 #[tokio::test]
1160 async fn import_unsupported_archive_version_returns_error() {
1161 let rt = make_rt().await;
1162 let tok = NamespaceToken::local();
1163 let bad = KgArchive {
1164 format: "khive-kg".to_string(),
1165 version: "999.0".to_string(),
1166 namespace: "local".to_string(),
1167 exported_at: Utc::now(),
1168 entities: vec![],
1169 edges: vec![],
1170 };
1171 let err = rt.import_kg(&bad, &tok).await.unwrap_err();
1172 assert!(
1173 matches!(err, RuntimeError::InvalidInput(_)),
1174 "expected InvalidInput, got {err:?}"
1175 );
1176 if let RuntimeError::InvalidInput(msg) = err {
1177 assert!(
1178 msg.contains("999.0"),
1179 "error message should mention the unsupported version, got: {msg:?}"
1180 );
1181 }
1182 }
1183
1184 #[tokio::test]
1188 async fn import_entity_with_reserved_secret_gate_property_is_rejected() {
1189 let rt = make_rt().await;
1190 let tok = NamespaceToken::local();
1191 let archive = KgArchive {
1192 format: "khive-kg".to_string(),
1193 version: "0.1".to_string(),
1194 namespace: "local".to_string(),
1195 exported_at: Utc::now(),
1196 entities: vec![ExportedEntity {
1197 id: Uuid::new_v4(),
1198 kind: "concept".to_string(),
1199 entity_type: None,
1200 name: "ReservedKeyImport".to_string(),
1201 description: None,
1202 properties: Some(serde_json::json!({
1203 "khive:secret_gate": "exempted:content-sha256-manifest-v1"
1204 })),
1205 tags: vec![],
1206 created_at: Utc::now(),
1207 updated_at: Utc::now(),
1208 }],
1209 edges: vec![],
1210 };
1211
1212 let err = rt.import_kg(&archive, &tok).await.unwrap_err();
1213 assert!(
1214 matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
1215 "expected a reservation rejection, got {err:?}"
1216 );
1217
1218 let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
1219 assert!(
1220 !entities.iter().any(|e| e.name == "ReservedKeyImport"),
1221 "rejected archive import must not create the entity"
1222 );
1223 }
1224
1225 #[tokio::test]
1230 async fn import_edge_with_reserved_secret_gate_property_is_rejected() {
1231 let rt = make_rt().await;
1232 let tok = NamespaceToken::local();
1233 let a = Uuid::new_v4();
1234 let b = Uuid::new_v4();
1235 let mk = |id: Uuid, name: &str| ExportedEntity {
1236 id,
1237 kind: "concept".to_string(),
1238 entity_type: None,
1239 name: name.to_string(),
1240 description: None,
1241 properties: None,
1242 tags: vec![],
1243 created_at: Utc::now(),
1244 updated_at: Utc::now(),
1245 };
1246 let archive = KgArchive {
1247 format: "khive-kg".to_string(),
1248 version: "0.1".to_string(),
1249 namespace: "local".to_string(),
1250 exported_at: Utc::now(),
1251 entities: vec![mk(a, "EdgeGateA"), mk(b, "EdgeGateB")],
1252 edges: vec![ExportedEdge {
1253 edge_id: Uuid::new_v4(),
1254 source: a,
1255 target: b,
1256 relation: EdgeRelation::Extends,
1257 weight: 0.5,
1258 properties: Some(serde_json::json!({
1259 "khive:secret_gate": "exempted:content-sha256-manifest-v1"
1260 })),
1261 created_at: Utc::now(),
1262 updated_at: Utc::now(),
1263 }],
1264 };
1265
1266 let err = rt.import_kg(&archive, &tok).await.unwrap_err();
1267 assert!(
1268 matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
1269 "expected a reservation rejection, got {err:?}"
1270 );
1271
1272 let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
1275 assert!(
1276 !entities.iter().any(|e| e.name == "EdgeGateA"),
1277 "rejected archive import must not create any records"
1278 );
1279 }
1280
1281 #[tokio::test]
1285 async fn import_edge_with_credential_shaped_property_is_rejected() {
1286 let rt = make_rt().await;
1287 let tok = NamespaceToken::local();
1288 let a = Uuid::new_v4();
1289 let b = Uuid::new_v4();
1290 let mk = |id: Uuid, name: &str| ExportedEntity {
1291 id,
1292 kind: "concept".to_string(),
1293 entity_type: None,
1294 name: name.to_string(),
1295 description: None,
1296 properties: None,
1297 tags: vec![],
1298 created_at: Utc::now(),
1299 updated_at: Utc::now(),
1300 };
1301 let archive = KgArchive {
1302 format: "khive-kg".to_string(),
1303 version: "0.1".to_string(),
1304 namespace: "local".to_string(),
1305 exported_at: Utc::now(),
1306 entities: vec![mk(a, "EdgeScanA"), mk(b, "EdgeScanB")],
1307 edges: vec![ExportedEdge {
1308 edge_id: Uuid::new_v4(),
1309 source: a,
1310 target: b,
1311 relation: EdgeRelation::Extends,
1312 weight: 0.5,
1313 properties: Some(serde_json::json!({
1314 "api_key": "AKIAFAKEKEY1234567890"
1315 })),
1316 created_at: Utc::now(),
1317 updated_at: Utc::now(),
1318 }],
1319 };
1320
1321 let err = rt.import_kg(&archive, &tok).await.unwrap_err();
1322 assert!(
1323 matches!(err, RuntimeError::SecretDetected(_)),
1324 "expected the blocking scanner to reject the value, got {err:?}"
1325 );
1326
1327 let entities = rt.list_entities(&tok, None, None, 100, 0).await.unwrap();
1328 assert!(
1329 !entities.iter().any(|e| e.name == "EdgeScanA"),
1330 "rejected archive import must not create any records"
1331 );
1332 }
1333
1334 #[test]
1336 fn invalid_relation_rejected_at_deserialize() {
1337 let json = r#"{
1338 "format":"khive-kg","version":"0.1","namespace":"local",
1339 "exported_at":"2026-01-01T00:00:00Z",
1340 "entities":[],
1341 "edges":[{"edge_id":"00000000-0000-0000-0000-000000000099",
1342 "source":"00000000-0000-0000-0000-000000000001",
1343 "target":"00000000-0000-0000-0000-000000000002",
1344 "relation":"related_to","weight":0.5}]
1345 }"#;
1346 let result: Result<KgArchive, _> = serde_json::from_str(json);
1347 assert!(
1348 result.is_err(),
1349 "non-canonical relation should fail to deserialize"
1350 );
1351 }
1352
1353 #[tokio::test]
1360 async fn import_edge_with_dangling_source_is_skipped() {
1361 let phantom_source = Uuid::parse_str("deadbeef-dead-4ead-dead-deadbeefcafe").unwrap();
1362
1363 let rt = make_rt().await;
1364 let tok = NamespaceToken::local();
1365 let real = rt
1366 .create_entity(&tok, "concept", None, "Real", None, None, vec![])
1367 .await
1368 .unwrap();
1369
1370 let archive = KgArchive {
1371 format: "khive-kg".to_string(),
1372 version: "0.1".to_string(),
1373 namespace: "local".to_string(),
1374 exported_at: Utc::now(),
1375 entities: vec![ExportedEntity {
1376 id: real.id,
1377 kind: "concept".to_string(),
1378 entity_type: None,
1379 name: "Real".to_string(),
1380 description: None,
1381 properties: None,
1382 tags: vec![],
1383 created_at: Utc::now(),
1384 updated_at: Utc::now(),
1385 }],
1386 edges: vec![ExportedEdge {
1387 edge_id: Uuid::new_v4(),
1388 source: phantom_source,
1389 target: real.id,
1390 relation: EdgeRelation::Extends,
1391 weight: 1.0,
1392 properties: None,
1393 created_at: Utc::now(),
1394 updated_at: Utc::now(),
1395 }],
1396 };
1397
1398 let dst = make_rt().await;
1399 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1400 assert_eq!(summary.entities_imported, 1);
1401 assert_eq!(
1402 summary.edges_imported, 0,
1403 "dangling source must not be imported"
1404 );
1405 assert_eq!(
1406 summary.edges_skipped, 1,
1407 "dangling source must be counted as skipped"
1408 );
1409 }
1410
1411 #[tokio::test]
1416 async fn import_edge_with_dangling_target_is_skipped() {
1417 let phantom_target = Uuid::parse_str("cafebabe-cafe-4abe-cafe-cafebabecafe").unwrap();
1418
1419 let rt = make_rt().await;
1420 let tok = NamespaceToken::local();
1421 let real = rt
1422 .create_entity(&tok, "concept", None, "Source", None, None, vec![])
1423 .await
1424 .unwrap();
1425
1426 let archive = KgArchive {
1427 format: "khive-kg".to_string(),
1428 version: "0.1".to_string(),
1429 namespace: "local".to_string(),
1430 exported_at: Utc::now(),
1431 entities: vec![ExportedEntity {
1432 id: real.id,
1433 kind: "concept".to_string(),
1434 entity_type: None,
1435 name: "Source".to_string(),
1436 description: None,
1437 properties: None,
1438 tags: vec![],
1439 created_at: Utc::now(),
1440 updated_at: Utc::now(),
1441 }],
1442 edges: vec![ExportedEdge {
1443 edge_id: Uuid::new_v4(),
1444 source: real.id,
1445 target: phantom_target,
1446 relation: EdgeRelation::DependsOn,
1447 weight: 0.8,
1448 properties: None,
1449 created_at: Utc::now(),
1450 updated_at: Utc::now(),
1451 }],
1452 };
1453
1454 let dst = make_rt().await;
1455 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1456 assert_eq!(summary.entities_imported, 1);
1457 assert_eq!(
1458 summary.edges_imported, 0,
1459 "dangling target must not be imported"
1460 );
1461 assert_eq!(
1462 summary.edges_skipped, 1,
1463 "dangling target must be counted as skipped"
1464 );
1465 }
1466
1467 #[tokio::test]
1472 async fn import_mixed_edges_reports_correct_counts() {
1473 let phantom = Uuid::parse_str("11111111-1111-4111-8111-111111111111").unwrap();
1474
1475 let src = make_rt().await;
1476 let tok = NamespaceToken::local();
1477 let a = src
1478 .create_entity(&tok, "concept", None, "A", None, None, vec![])
1479 .await
1480 .unwrap();
1481 let b = src
1482 .create_entity(&tok, "concept", None, "B", None, None, vec![])
1483 .await
1484 .unwrap();
1485 let c = src
1486 .create_entity(&tok, "concept", None, "C", None, None, vec![])
1487 .await
1488 .unwrap();
1489
1490 let archive = KgArchive {
1491 format: "khive-kg".to_string(),
1492 version: "0.1".to_string(),
1493 namespace: "local".to_string(),
1494 exported_at: Utc::now(),
1495 entities: vec![
1496 ExportedEntity {
1497 id: a.id,
1498 kind: "concept".to_string(),
1499 entity_type: None,
1500 name: "A".to_string(),
1501 description: None,
1502 properties: None,
1503 tags: vec![],
1504 created_at: Utc::now(),
1505 updated_at: Utc::now(),
1506 },
1507 ExportedEntity {
1508 id: b.id,
1509 kind: "concept".to_string(),
1510 entity_type: None,
1511 name: "B".to_string(),
1512 description: None,
1513 properties: None,
1514 tags: vec![],
1515 created_at: Utc::now(),
1516 updated_at: Utc::now(),
1517 },
1518 ExportedEntity {
1519 id: c.id,
1520 kind: "concept".to_string(),
1521 entity_type: None,
1522 name: "C".to_string(),
1523 description: None,
1524 properties: None,
1525 tags: vec![],
1526 created_at: Utc::now(),
1527 updated_at: Utc::now(),
1528 },
1529 ],
1530 edges: vec![
1531 ExportedEdge {
1532 edge_id: Uuid::new_v4(),
1533 source: a.id,
1534 target: b.id,
1535 relation: EdgeRelation::Extends,
1536 weight: 1.0,
1537 properties: None,
1538 created_at: Utc::now(),
1539 updated_at: Utc::now(),
1540 },
1541 ExportedEdge {
1542 edge_id: Uuid::new_v4(),
1543 source: b.id,
1544 target: c.id,
1545 relation: EdgeRelation::VariantOf,
1550 weight: 0.9,
1551 properties: None,
1552 created_at: Utc::now(),
1553 updated_at: Utc::now(),
1554 },
1555 ExportedEdge {
1556 edge_id: Uuid::new_v4(),
1557 source: a.id,
1558 target: phantom,
1559 relation: EdgeRelation::Enables,
1560 weight: 0.5,
1561 properties: None,
1562 created_at: Utc::now(),
1563 updated_at: Utc::now(),
1564 },
1565 ],
1566 };
1567
1568 let dst = make_rt().await;
1569 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1570 assert_eq!(summary.entities_imported, 3);
1571 assert_eq!(
1572 summary.edges_imported, 2,
1573 "only valid edges must be imported"
1574 );
1575 assert_eq!(
1576 summary.edges_skipped, 1,
1577 "one dangling edge must be reported"
1578 );
1579 }
1580
1581 #[tokio::test]
1583 async fn import_all_valid_edges_reports_zero_skipped() {
1584 let src = make_rt().await;
1585 let tok = NamespaceToken::local();
1586 let e1 = src
1587 .create_entity(&tok, "concept", None, "E1", None, None, vec![])
1588 .await
1589 .unwrap();
1590 let e2 = src
1591 .create_entity(&tok, "concept", None, "E2", None, None, vec![])
1592 .await
1593 .unwrap();
1594 src.link(&tok, e1.id, e2.id, EdgeRelation::VariantOf, 0.7, None)
1595 .await
1596 .unwrap();
1597
1598 let archive = src.export_kg(&tok).await.unwrap();
1599 let dst = make_rt().await;
1600 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1601 assert_eq!(summary.edges_imported, 1);
1602 assert_eq!(
1603 summary.edges_skipped, 0,
1604 "no edges should be skipped when all endpoints exist"
1605 );
1606 }
1607
1608 #[tokio::test]
1614 async fn import_edge_violating_endpoint_contract_is_skipped() {
1615 let src = make_rt().await;
1616 let tok = NamespaceToken::local();
1617 let e1 = src
1618 .create_entity(&tok, "concept", None, "E1", None, None, vec![])
1619 .await
1620 .unwrap();
1621 let e2 = src
1622 .create_entity(&tok, "concept", None, "E2", None, None, vec![])
1623 .await
1624 .unwrap();
1625
1626 let archive = KgArchive {
1627 format: "khive-kg".to_string(),
1628 version: "0.1".to_string(),
1629 namespace: "local".to_string(),
1630 exported_at: Utc::now(),
1631 entities: vec![
1632 ExportedEntity {
1633 id: e1.id,
1634 kind: "concept".to_string(),
1635 entity_type: None,
1636 name: "E1".to_string(),
1637 description: None,
1638 properties: None,
1639 tags: vec![],
1640 created_at: Utc::now(),
1641 updated_at: Utc::now(),
1642 },
1643 ExportedEntity {
1644 id: e2.id,
1645 kind: "concept".to_string(),
1646 entity_type: None,
1647 name: "E2".to_string(),
1648 description: None,
1649 properties: None,
1650 tags: vec![],
1651 created_at: Utc::now(),
1652 updated_at: Utc::now(),
1653 },
1654 ],
1655 edges: vec![ExportedEdge {
1656 edge_id: Uuid::new_v4(),
1657 source: e1.id,
1658 target: e2.id,
1659 relation: EdgeRelation::Precedes,
1660 weight: 1.0,
1661 properties: None,
1662 created_at: Utc::now(),
1663 updated_at: Utc::now(),
1664 }],
1665 };
1666
1667 let dst = make_rt().await;
1668 let summary = dst.import_kg(&archive, &tok).await.unwrap();
1669 assert_eq!(summary.entities_imported, 2);
1670 assert_eq!(
1671 summary.edges_imported, 0,
1672 "an endpoint-contract-violating edge must not be imported"
1673 );
1674 assert_eq!(
1675 summary.edges_skipped, 1,
1676 "an endpoint-contract-violating edge must be counted as skipped"
1677 );
1678 assert!(
1679 dst.neighbors(
1680 &tok,
1681 e1.id,
1682 khive_storage::types::Direction::Out,
1683 None,
1684 None
1685 )
1686 .await
1687 .unwrap()
1688 .is_empty(),
1689 "the contract-violating edge must not exist in the destination graph"
1690 );
1691 }
1692
1693 #[tokio::test]
1697 async fn export_kg_preserves_edge_id() {
1698 let rt = make_rt().await;
1699 let tok = NamespaceToken::local();
1700 let a = rt
1701 .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
1702 .await
1703 .unwrap();
1704 let b = rt
1705 .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
1706 .await
1707 .unwrap();
1708 let stored_edge = rt
1709 .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1710 .await
1711 .unwrap();
1712 let stored_id: Uuid = stored_edge.id.into();
1713
1714 let archive = rt.export_kg(&tok).await.unwrap();
1715 assert_eq!(archive.edges.len(), 1);
1716 assert_eq!(
1717 archive.edges[0].edge_id, stored_id,
1718 "exported edge_id must equal the LinkId returned by link"
1719 );
1720 }
1721
1722 #[tokio::test]
1724 async fn import_kg_persists_edge_id_and_timestamps() {
1725 let src = make_rt().await;
1726 let tok = NamespaceToken::local();
1727 let a = src
1728 .create_entity(&tok, "concept", None, "Alpha", None, None, vec![])
1729 .await
1730 .unwrap();
1731 let b = src
1732 .create_entity(&tok, "concept", None, "Beta", None, None, vec![])
1733 .await
1734 .unwrap();
1735 let stored_edge = src
1736 .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1737 .await
1738 .unwrap();
1739 let original_id: Uuid = stored_edge.id.into();
1740
1741 let expected_created = chrono::DateTime::parse_from_rfc3339("2026-03-03T00:00:00Z")
1742 .unwrap()
1743 .with_timezone(&Utc);
1744 let expected_updated = chrono::DateTime::parse_from_rfc3339("2026-04-04T00:00:00Z")
1745 .unwrap()
1746 .with_timezone(&Utc);
1747 let mut archive = src.export_kg(&tok).await.unwrap();
1748 archive.edges[0].created_at = expected_created;
1749 archive.edges[0].updated_at = expected_updated;
1750 archive.edges[0].properties = Some(serde_json::json!({"confidence": 0.95}));
1751 let dst = make_rt().await;
1752 dst.import_kg(&archive, &tok).await.unwrap();
1753
1754 let imported_edge = dst.get_edge(&tok, original_id).await.unwrap();
1755 assert!(
1756 imported_edge.is_some(),
1757 "imported edge must be retrievable by the original edge_id"
1758 );
1759 let imported_edge = imported_edge.unwrap();
1760 assert_eq!(
1761 Uuid::from(imported_edge.id),
1762 original_id,
1763 "stored edge id must equal the archive edge_id"
1764 );
1765 assert_eq!(
1766 imported_edge.created_at, expected_created,
1767 "present edge created_at must not be replaced with import time"
1768 );
1769 assert_eq!(
1770 imported_edge.updated_at, expected_updated,
1771 "present edge updated_at must not be replaced with created_at or import time"
1772 );
1773 assert_eq!(
1774 imported_edge.metadata,
1775 Some(serde_json::json!({"confidence": 0.95})),
1776 "edge properties must persist as storage metadata"
1777 );
1778
1779 let reexported = dst.export_kg(&tok).await.unwrap();
1780 assert_eq!(
1781 reexported.edges[0].properties,
1782 Some(serde_json::json!({"confidence": 0.95})),
1783 "edge metadata must re-export as portable properties"
1784 );
1785 }
1786
1787 #[tokio::test]
1792 async fn old_archive_missing_edge_id_round_trips() {
1793 let src_id = Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap();
1794 let tgt_id = Uuid::parse_str("00000000-0000-0000-0000-000000000002").unwrap();
1795
1796 let json = format!(
1798 r#"{{
1799 "format": "khive-kg",
1800 "version": "0.1",
1801 "namespace": "local",
1802 "exported_at": "2026-01-01T00:00:00Z",
1803 "entities": [
1804 {{"id":"{src_id}","kind":"concept","name":"SrcNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}},
1805 {{"id":"{tgt_id}","kind":"concept","name":"TgtNode","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}}
1806 ],
1807 "edges": [
1808 {{
1809 "source": "{src_id}",
1810 "target": "{tgt_id}",
1811 "relation": "extends",
1812 "weight": 0.9
1813 }}
1814 ]
1815 }}"#
1816 );
1817
1818 let archive: KgArchive = serde_json::from_str(&json)
1820 .expect("old archive without edge_id must deserialize successfully");
1821 assert_eq!(archive.edges.len(), 1);
1822 let generated_id = archive.edges[0].edge_id;
1823 assert_ne!(
1824 generated_id,
1825 Uuid::nil(),
1826 "missing edge_id in old archive must get a fresh non-nil UUID"
1827 );
1828
1829 let rt = make_rt().await;
1830 let tok = NamespaceToken::local();
1831 let summary = rt.import_kg(&archive, &tok).await.unwrap();
1832 assert_eq!(summary.entities_imported, 2);
1833 assert_eq!(
1834 summary.edges_imported, 1,
1835 "edge must be imported when both endpoints exist"
1836 );
1837
1838 let stored = rt.get_edge(&tok, generated_id).await.unwrap();
1839 assert!(
1840 stored.is_some(),
1841 "imported edge must be retrievable by the generated edge_id"
1842 );
1843 assert_eq!(
1844 Uuid::from(stored.unwrap().id),
1845 generated_id,
1846 "stored edge id must equal the generated edge_id"
1847 );
1848
1849 let re_archive = rt.export_kg(&tok).await.unwrap();
1850 assert_eq!(re_archive.edges.len(), 1);
1851 assert_eq!(
1852 re_archive.edges[0].edge_id, generated_id,
1853 "re-exported edge_id must equal the ID generated on first import"
1854 );
1855 }
1856
1857 #[tokio::test]
1862 async fn export_import_export_edge_id_equality() {
1863 let src = make_rt().await;
1864 let tok = NamespaceToken::local();
1865 let a = src
1866 .create_entity(&tok, "concept", None, "NodeA", None, None, vec![])
1867 .await
1868 .unwrap();
1869 let b = src
1870 .create_entity(&tok, "concept", None, "NodeB", None, None, vec![])
1871 .await
1872 .unwrap();
1873 let stored = src
1874 .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
1875 .await
1876 .unwrap();
1877 let original_edge_id: Uuid = stored.id.into();
1878
1879 let archive1 = src.export_kg(&tok).await.unwrap();
1880 assert_eq!(archive1.edges.len(), 1);
1881 assert_eq!(
1882 archive1.edges[0].edge_id, original_edge_id,
1883 "first export must carry the stored edge_id"
1884 );
1885
1886 let dst = make_rt().await;
1887 dst.import_kg(&archive1, &tok).await.unwrap();
1888
1889 let archive2 = dst.export_kg(&tok).await.unwrap();
1890 assert_eq!(archive2.edges.len(), 1);
1891
1892 let re_edge = archive2
1893 .edges
1894 .iter()
1895 .find(|e| e.source == a.id && e.target == b.id && e.relation == EdgeRelation::Extends)
1896 .expect(
1897 "re-exported archive must contain the original edge by (source,target,relation)",
1898 );
1899 assert_eq!(
1900 re_edge.edge_id, original_edge_id,
1901 "edge_id must be identical across export → import → export"
1902 );
1903 }
1904
1905 fn skip_report_entity(id: Uuid, name: &str) -> ExportedEntity {
1907 let timestamp = DateTime::parse_from_rfc3339("2026-01-01T00:00:00Z")
1908 .unwrap()
1909 .with_timezone(&Utc);
1910 ExportedEntity {
1911 id,
1912 kind: "document".into(),
1913 entity_type: None,
1914 name: name.into(),
1915 description: None,
1916 properties: None,
1917 tags: vec![],
1918 created_at: timestamp,
1919 updated_at: timestamp,
1920 }
1921 }
1922
1923 fn skip_report_edge(
1924 id: u128,
1925 source: Uuid,
1926 target: Uuid,
1927 relation: EdgeRelation,
1928 ) -> ExportedEdge {
1929 let timestamp = DateTime::parse_from_rfc3339("2026-01-01T00:00:00Z")
1930 .unwrap()
1931 .with_timezone(&Utc);
1932 ExportedEdge {
1933 edge_id: Uuid::from_u128(id),
1934 source,
1935 target,
1936 relation,
1937 weight: 0.7,
1938 properties: None,
1939 created_at: timestamp,
1940 updated_at: timestamp,
1941 }
1942 }
1943
1944 fn skip_report_archive(entities: Vec<ExportedEntity>, edges: Vec<ExportedEdge>) -> KgArchive {
1945 KgArchive {
1946 format: "khive-kg".into(),
1947 version: "0.1".into(),
1948 namespace: "local".into(),
1949 exported_at: Utc::now(),
1950 entities,
1951 edges,
1952 }
1953 }
1954
1955 #[tokio::test]
1956 async fn skipped_edge_details_cover_three_causes_and_retain_the_valid_edge() {
1957 let runtime = make_rt().await;
1958 let token = NamespaceToken::local();
1959 let source = Uuid::from_u128(1);
1960 let target = Uuid::from_u128(2);
1961 let absent = Uuid::from_u128(3);
1962 let mut valid = skip_report_edge(101, source, target, EdgeRelation::LinksTo);
1963 valid.properties = Some(serde_json::json!({"retained": true}));
1964 let archive = skip_report_archive(
1965 vec![
1966 skip_report_entity(source, "Source"),
1967 skip_report_entity(target, "Target"),
1968 ],
1969 vec![
1970 skip_report_edge(100, absent, source, EdgeRelation::LinksTo),
1971 valid.clone(),
1972 skip_report_edge(102, source, absent, EdgeRelation::DependsOn),
1973 skip_report_edge(103, source, target, EdgeRelation::Annotates),
1974 ],
1975 );
1976 let summary = runtime.import_kg(&archive, &token).await.unwrap();
1977 let expected = vec![
1978 ImportSkippedEdge {
1979 edge_id: Uuid::from_u128(100),
1980 source: absent,
1981 target: source,
1982 relation: EdgeRelation::LinksTo,
1983 cause: ImportEdgeSkipCause::MissingSource,
1984 error: None,
1985 },
1986 ImportSkippedEdge {
1987 edge_id: Uuid::from_u128(102),
1988 source,
1989 target: absent,
1990 relation: EdgeRelation::DependsOn,
1991 cause: ImportEdgeSkipCause::MissingTarget,
1992 error: None,
1993 },
1994 ImportSkippedEdge {
1995 edge_id: Uuid::from_u128(103),
1996 source,
1997 target,
1998 relation: EdgeRelation::Annotates,
1999 cause: ImportEdgeSkipCause::EndpointContract,
2000 error: Some(format!(
2001 "invalid input: annotates source {source} must be a note"
2002 )),
2003 },
2004 ];
2005 assert_eq!(summary.entities_imported, 2);
2006 assert_eq!(summary.edges_imported, 1);
2007 assert_eq!(summary.edges_skipped, 3);
2008 assert_eq!(summary.skipped_edges, expected);
2009 let wire = serde_json::to_value(&summary).unwrap();
2010 assert_eq!(
2011 wire["skipped_edges"],
2012 serde_json::json!([
2013 {"edge_id":Uuid::from_u128(100),"source":absent,"target":source,
2014 "relation":"links_to","cause":"missing_source"},
2015 {"edge_id":Uuid::from_u128(102),"source":source,"target":absent,
2016 "relation":"depends_on","cause":"missing_target"},
2017 {"edge_id":Uuid::from_u128(103),"source":source,"target":target,
2018 "relation":"annotates","cause":"endpoint_contract",
2019 "error":format!("invalid input: annotates source {source} must be a note")}
2020 ])
2021 );
2022 let decoded: ImportSummary = serde_json::from_value(wire).unwrap();
2023 assert_eq!(decoded.skipped_edges, expected);
2024 assert_eq!(decoded.edges_skipped, 3);
2025 for id in [100, 102, 103] {
2026 assert!(runtime
2027 .get_edge(&token, Uuid::from_u128(id))
2028 .await
2029 .unwrap()
2030 .is_none());
2031 }
2032 let stored = runtime
2033 .get_edge(&token, valid.edge_id)
2034 .await
2035 .unwrap()
2036 .unwrap();
2037 assert_eq!(Uuid::from(stored.id), valid.edge_id);
2038 assert_eq!(stored.source_id, source);
2039 assert_eq!(stored.target_id, target);
2040 assert_eq!(stored.relation, EdgeRelation::LinksTo);
2041 assert_eq!(stored.metadata, valid.properties);
2042 assert_eq!(stored.created_at, valid.created_at);
2043 assert_eq!(stored.updated_at, valid.updated_at);
2044 let exported = runtime.export_kg(&token).await.unwrap();
2045 assert_eq!(exported.edges.len(), 1);
2046 assert_eq!(exported.edges[0].edge_id, valid.edge_id);
2047 }
2048
2049 #[tokio::test]
2050 async fn skipped_edge_details_preserve_duplicates_order_and_both_missing_precedence() {
2051 let runtime = make_rt().await;
2052 let token = NamespaceToken::local();
2053 let present = Uuid::from_u128(1);
2054 let absent = Uuid::from_u128(3);
2055 let other_absent = Uuid::from_u128(4);
2056 let repeated = skip_report_edge(111, absent, present, EdgeRelation::LinksTo);
2057 let archive = skip_report_archive(
2058 vec![skip_report_entity(present, "Present")],
2059 vec![
2060 skip_report_edge(110, present, absent, EdgeRelation::DependsOn),
2061 repeated.clone(),
2062 skip_report_edge(112, absent, present, EdgeRelation::LinksTo),
2063 repeated,
2064 skip_report_edge(113, absent, other_absent, EdgeRelation::Extends),
2065 ],
2066 );
2067 let summary = runtime.import_kg(&archive, &token).await.unwrap();
2068 assert_eq!(summary.edges_imported, 0);
2069 assert_eq!(summary.edges_skipped, 5);
2070 assert_eq!(
2071 summary.skipped_edges,
2072 vec![
2073 ImportSkippedEdge {
2074 edge_id: Uuid::from_u128(110),
2075 source: present,
2076 target: absent,
2077 relation: EdgeRelation::DependsOn,
2078 cause: ImportEdgeSkipCause::MissingTarget,
2079 error: None,
2080 },
2081 ImportSkippedEdge {
2082 edge_id: Uuid::from_u128(111),
2083 source: absent,
2084 target: present,
2085 relation: EdgeRelation::LinksTo,
2086 cause: ImportEdgeSkipCause::MissingSource,
2087 error: None,
2088 },
2089 ImportSkippedEdge {
2090 edge_id: Uuid::from_u128(112),
2091 source: absent,
2092 target: present,
2093 relation: EdgeRelation::LinksTo,
2094 cause: ImportEdgeSkipCause::MissingSource,
2095 error: None,
2096 },
2097 ImportSkippedEdge {
2098 edge_id: Uuid::from_u128(111),
2099 source: absent,
2100 target: present,
2101 relation: EdgeRelation::LinksTo,
2102 cause: ImportEdgeSkipCause::MissingSource,
2103 error: None,
2104 },
2105 ImportSkippedEdge {
2106 edge_id: Uuid::from_u128(113),
2107 source: absent,
2108 target: other_absent,
2109 relation: EdgeRelation::Extends,
2110 cause: ImportEdgeSkipCause::MissingSource,
2111 error: None,
2112 },
2113 ]
2114 );
2115 assert!(runtime.export_kg(&token).await.unwrap().edges.is_empty());
2116 }
2117
2118 #[tokio::test]
2119 async fn successful_imports_without_skips_keep_the_previous_json_shape() {
2120 let token = NamespaceToken::local();
2121 let a = Uuid::from_u128(1);
2122 let b = Uuid::from_u128(2);
2123 for (archive, entities, edges) in [
2124 (skip_report_archive(vec![], vec![]), 0, 0),
2125 (
2126 skip_report_archive(
2127 vec![skip_report_entity(a, "A"), skip_report_entity(b, "B")],
2128 vec![skip_report_edge(101, a, b, EdgeRelation::LinksTo)],
2129 ),
2130 2,
2131 1,
2132 ),
2133 ] {
2134 let runtime = make_rt().await;
2135 let summary = runtime.import_kg(&archive, &token).await.unwrap();
2136 assert!(summary.skipped_edges.is_empty());
2137 assert_eq!(summary.edges_skipped, 0);
2138 assert_eq!(
2139 serde_json::to_value(&summary).unwrap(),
2140 serde_json::json!({
2141 "entities_imported":entities,"edges_imported":edges,"edges_skipped":0,
2142 "embedding_truncation":{"truncated":0,"discarded_bytes":0}
2143 })
2144 );
2145 }
2146 }
2147
2148 #[test]
2149 fn historical_summary_counts_do_not_invent_skipped_edge_details() {
2150 for count in [0, 2] {
2151 let old = serde_json::json!({
2152 "entities_imported":1,"edges_imported":0,"edges_skipped":count
2153 });
2154 let summary: ImportSummary = serde_json::from_value(old).unwrap();
2155 assert_eq!(summary.edges_skipped, count);
2156 assert!(summary.skipped_edges.is_empty());
2157 assert_eq!(
2158 serde_json::to_value(summary).unwrap(),
2159 serde_json::json!({
2160 "entities_imported":1,"edges_imported":0,"edges_skipped":count,
2161 "embedding_truncation":{"truncated":0,"discarded_bytes":0}
2162 })
2163 );
2164 }
2165 }
2166
2167 #[test]
2168 fn skipped_edge_cause_spellings_are_closed_and_error_is_preserved_verbatim() {
2169 let wire = serde_json::json!({
2170 "edge_id":"00000000-0000-0000-0000-000000000103",
2171 "source":"00000000-0000-0000-0000-000000000001",
2172 "target":"00000000-0000-0000-0000-000000000002",
2173 "relation":"annotates","cause":"endpoint_contract",
2174 "error":"not found: link target changed during endpoint validation"
2175 });
2176 let detail: ImportSkippedEdge = serde_json::from_value(wire.clone()).unwrap();
2177 assert_eq!(detail.cause, ImportEdgeSkipCause::EndpointContract);
2178 assert_eq!(
2179 detail.error.as_deref(),
2180 Some("not found: link target changed during endpoint validation")
2181 );
2182 assert_eq!(serde_json::to_value(detail).unwrap(), wire);
2183 let mut invalid = wire;
2184 invalid["cause"] = serde_json::json!("storage_failure");
2185 assert!(serde_json::from_value::<ImportSkippedEdge>(invalid).is_err());
2186 }
2187}