Skip to main content

khive_runtime/
portability.rs

1//! KG export / import — portable JSON archive for namespace-scoped knowledge graphs.
2//!
3//! Embeddings are excluded (regenerable from text + model). Edges are collected by
4//! querying all entity IDs in the namespace first, then fetching incident edges.
5
6use std::collections::{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
27/// Parse an optional archive timestamp, using `fallback` only when absent.
28///
29/// Present values must be RFC3339 and are converted to UTC. Invalid values keep
30/// their parser error with the original timestamp as context.
31pub 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// ── Archive types ─────────────────────────────────────────────────────────────
44
45/// Portable JSON archive of a namespace-scoped knowledge graph.
46///
47/// The `format` field is always `"khive-kg"`. The `version` field identifies
48/// the serialization schema; parsers should reject unknown versions.
49#[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/// An entity record in the portable archive.
60#[derive(Clone, Debug, Serialize, Deserialize)]
61pub struct ExportedEntity {
62    pub id: Uuid,
63    /// Pack-owned kind string (e.g. `"concept"`, `"person"`).
64    pub kind: String,
65    /// Pack-governed subtype token (e.g. `"paper"`, `"snapshot"`).
66    #[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/// A directed edge record in the portable archive.
80#[derive(Clone, Debug, Serialize, Deserialize)]
81pub struct ExportedEdge {
82    /// Stable edge identity across export/import cycles.
83    ///
84    /// Old archives (pre-0.2) omit this field. `serde(default)` assigns a fresh
85    /// UUID on import so backward-compatible archives are accepted as-is.
86    #[serde(default = "Uuid::new_v4")]
87    pub edge_id: Uuid,
88    pub source: Uuid,
89    pub target: Uuid,
90    /// One of the canonical edge relations (closed enum).
91    pub relation: EdgeRelation,
92    pub weight: f64,
93    /// Portable edge metadata, named `properties` in the ADR-020 wire shape.
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub properties: Option<serde_json::Value>,
96    /// Edge creation time. Older archives may omit it; those imports use the
97    /// time at which the archive is decoded.
98    #[serde(
99        default = "default_import_timestamp",
100        deserialize_with = "deserialize_import_timestamp"
101    )]
102    pub created_at: DateTime<Utc>,
103    /// Edge last-update time. Kept independent from `created_at` so imported
104    /// provenance is not collapsed during a round trip.
105    #[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/// Why an archive edge was skipped during a successful import.
127#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "snake_case")]
129pub enum ImportEdgeSkipCause {
130    /// The source entity was not found during the initial endpoint check.
131    MissingSource,
132    /// The source exists, but the target entity was not found.
133    MissingTarget,
134    /// The later endpoint-contract check returned InvalidInput or NotFound.
135    EndpointContract,
136}
137
138/// One skipped archive edge, retaining its identity and endpoint-contract error.
139#[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    /// The original RuntimeError display text for EndpointContract only.
147    #[serde(default, skip_serializing_if = "Option::is_none")]
148    pub error: Option<String>,
149}
150
151/// Outcome of a successful import operation.
152#[derive(Clone, Debug, Serialize, Deserialize)]
153pub struct ImportSummary {
154    pub entities_imported: usize,
155    pub edges_imported: usize,
156    /// Number of edges skipped for missing endpoints or endpoint-contract refusal.
157    ///
158    /// Newly successful imports set this to skipped_edges.len(). Historical
159    /// summaries can retain a non-zero count without individual details.
160    pub edges_skipped: usize,
161    /// Every skipped entry in archive order, including duplicates. Missing-source
162    /// takes precedence when both endpoints are absent. Empty lists are omitted
163    /// from JSON to preserve the previous zero-skip summary shape.
164    #[serde(default, skip_serializing_if = "Vec::is_empty")]
165    pub skipped_edges: Vec<ImportSkippedEdge>,
166    /// Aggregate actual outcomes from reindexing imported entities. Source
167    /// text remains complete in the entity store and FTS when this is non-zero.
168    #[serde(default)]
169    pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
170}
171
172/// Pure preflight result. Unknown kinds are distinct and in first-record order.
173/// Preflight emits no warnings and opens no destination store.
174#[derive(Clone, Debug, Default, PartialEq, Eq)]
175pub struct ImportValidation {
176    pub unknown_entity_kinds: Vec<String>,
177}
178
179// ── KhiveRuntime impl ─────────────────────────────────────────────────────────
180
181impl KhiveRuntime {
182    /// Export all entities and edges in a namespace to a portable JSON archive.
183    ///
184    /// Edge collection: all entity IDs in the namespace are gathered first;
185    /// `query_edges` is then called with those IDs as `source_ids`. This
186    /// captures every edge whose source entity belongs to the namespace.
187    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    /// Export to a JSON string (convenience wrapper around `export_kg`).
273    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    /// Import an archive into `target_namespace`.
279    ///
280    /// If `target_namespace` is `None`, the archive's own namespace is used.
281    ///
282    /// - Entities: upserted by ID; existing records are overwritten.
283    /// - Edges: upserted; existing records are overwritten.
284    /// - Validation: `format != "khive-kg"` or unsupported version → `InvalidInput`.
285    ///   Invalid edge relations are caught at JSON deserialization time.
286    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    /// Validate the complete archive without destination access or warnings.
296    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        // Complete deterministic validation before opening a store or issuing
315        // the first write. Endpoint existence and namespace checks remain at
316        // write time because they depend on mutable target state.
317        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                // A recognized alias/case variant is not an unknown kind. Keep
332                // archive exact-vocabulary validation; adapters normalize first.
333                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            // Archive content is caller-controlled input: the runtime-owned
357            // `khive:secret_gate` property key is reservation-only on import,
358            // exactly as on every other properties-bearing write path
359            // (ADR-115 Amendment 1 §3). Import never consumes exemptions.
360            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            // Edge properties are caller-controlled input: the runtime-owned
372            // `khive:secret_gate` key is reservation-only on import, and edge
373            // metadata is in ADR-115 Amendment 1 §3's unchanged blocking-scanner
374            // class, so credential-shaped values are rejected here as well.
375            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    /// Import with explicit admission for unknown entity kinds only.
385    /// Every other deterministic check precedes writes; operational store/index
386    /// failures retain the existing import behavior and are not transactional.
387    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                // Publish each record through the same guarded FTS/vector writer
453                // as an ordinary reindex, including its best-effort model failures.
454                embedding_truncation.merge(
455                    self.reindex_entity_with_precomputed(token, &entity, outcomes)
456                        .await?,
457                );
458                entities_imported += 1;
459            }
460        }
461
462        // Untrusted archives may reference entities absent from the target namespace;
463        // check both endpoints and skip edges with a missing source or target to avoid
464        // dangling references in the graph store.
465        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            // Only a contract verdict (InvalidInput) or an endpoint-resolution
514            // miss (NotFound) is a property of the edge being imported; any
515            // other error is an operational failure of the check itself and
516            // must abort the import rather than silently discard a valid edge.
517            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    /// Import from a JSON string (convenience wrapper around `import_kg`).
569    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    /// Decode and import JSON with explicit unknown-entity-kind admission.
579    /// Closed edge relations still fail during deserialization.
580    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// ── Tests ─────────────────────────────────────────────────────────────────────
597
598// Kept inline: these tests exercise round-trip invariants over private encoding
599// helpers that would otherwise need to be made pub to test from tests/.
600#[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    /// 1. Roundtrip: 3 entities + 2 edges survive export → import on a fresh runtime.
1008    #[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    /// 2. JSON roundtrip: export_kg_json → import_kg_json produces equivalent state.
1072    #[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    /// 3. Namespace targeting: export from namespace "a", import into namespace "b" on a
1109    ///    fresh runtime — entities land in "b", and the source runtime's "a" is unaffected.
1110    ///
1111    ///    Note: source and destination are separate runtimes (separate in-memory DBs).
1112    ///    Same-DB cross-namespace copy is not a portability use case — portability is about
1113    ///    moving graphs between instances, not between namespaces within one instance.
1114    #[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    /// 4. Format validation: wrong `format` field → InvalidInput.
1142    #[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    /// 5. Unsupported archive version → InvalidInput.
1159    #[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    /// ADR-115 Amendment 1 §3: an archive entity carrying the reserved
1185    /// `khive:secret_gate` property key must be rejected before any upsert —
1186    /// import is a caller-controlled write path and stays reservation-only.
1187    #[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    /// ADR-115 Amendment 1 §3: an archive edge carrying the reserved
1226    /// `khive:secret_gate` property key is rejected in the same deterministic
1227    /// pre-write pass as entities — edge metadata is a properties-bearing
1228    /// write path.
1229    #[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        // The rejection happens before any write, so the archive's entities
1273        // must not have been created either.
1274        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    /// ADR-115 Amendment 1 §3: edge metadata is in the unchanged
1282    /// blocking-scanner class, so a credential-shaped value in edge
1283    /// properties fails the import in the same pre-write pass.
1284    #[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    /// 6. Invalid relation in archive → InvalidInput.
1335    #[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    // ── Dangling-edge validation tests ────────────────────────────────────────
1354
1355    /// 6. Edge with dangling source (source UUID not in entity table) is skipped.
1356    ///
1357    /// The archive has one entity + one edge whose source is a phantom UUID.
1358    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
1359    #[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    /// 7. Edge with dangling target (target UUID not in entity table) is skipped.
1412    ///
1413    /// The archive has one entity + one edge whose target is a phantom UUID.
1414    /// Import succeeds, entities_imported=1, edges_imported=0, edges_skipped=1.
1415    #[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    /// 8. Mixed batch: some valid edges and some dangling edges — correct counts reported.
1468    ///
1469    /// Archive has 3 entities, 2 valid edges, and 1 dangling edge (phantom target).
1470    /// Import succeeds with edges_imported=2, edges_skipped=1.
1471    #[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                    // #1235: concept->concept is not in depends_on's endpoint
1546                    // contract; use variant_of (concept->concept is valid) so
1547                    // this fixture exercises "one dangling edge skipped" only,
1548                    // not an endpoint-contract violation this test isn't about.
1549                    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    /// 9. All-valid edges produce edges_skipped=0 (no regression on the happy path).
1582    #[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    /// #1235: an edge whose (source kind, relation, target kind) triple violates the
1609    /// endpoint contract (here: `precedes` between two `concept` entities — `precedes`
1610    /// is restricted to document/dataset/artifact/service/project pairs) must be
1611    /// skipped by import the same way a dangling endpoint is, not written straight
1612    /// through with `graph.upsert_edge`.
1613    #[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    // ── edge_id contract tests ────────────────────────────────────────────────
1694
1695    /// 10. export_kg sets edge_id in the archive to the LinkId returned by link.
1696    #[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    /// 11. import_kg writes the archive edge identity and timestamps exactly.
1723    #[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    /// 12. Old archive (no edge_id field) deserializes, imports, and re-exports with the
1788    ///     same generated UUID — proving the generated ID survives the full round trip.
1789    ///
1790    ///     The fixture includes two entities so the edge is not skipped during import.
1791    #[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        // Simulate a pre-0.2 archive JSON where the edge lacks an edge_id field.
1797        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        // serde(default) must assign a fresh non-nil UUID when edge_id is absent.
1819        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    /// 13. Explicit export → import → export equality: the edge_id is unchanged across
1858    ///     a full round trip when the source archive already contains an edge_id.
1859    ///
1860    ///     Verifies by (source, target, relation) key that re-export emits the original ID.
1861    #[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    // Skipped-edge details retain archive identity, order and the original refusal.
1906    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}