1use std::collections::{HashMap, HashSet, VecDeque};
12
13use serde::{Deserialize, Serialize};
14use serde_json::Value;
15use uuid::Uuid;
16
17use khive_db::SqliteError;
18use khive_storage::note::Note;
19use khive_storage::types::{EdgeFilter, TextDocument};
20use khive_storage::{EdgeRelation, Entity, SubstrateKind};
21use khive_types::{Details, EdgeEndpointRule, EventKind, KhiveError};
22use rusqlite::OptionalExtension;
23
24use crate::error::{RuntimeError, RuntimeResult};
25use crate::operations::{base_entity_rule_allows, canonical_edge_endpoints, endpoint_matches};
26use crate::runtime::{KhiveRuntime, NamespaceToken};
27
28#[derive(Clone, Debug, Default)]
34struct EmbeddingModelPlan {
35 model_names: Vec<String>,
36}
37
38impl EmbeddingModelPlan {
39 fn capture(runtime: &KhiveRuntime) -> Self {
40 Self {
41 model_names: runtime.registered_embedding_model_names(),
42 }
43 }
44
45 fn is_empty(&self) -> bool {
46 self.model_names.is_empty()
47 }
48
49 fn model_names(&self) -> &[String] {
50 &self.model_names
51 }
52
53 fn vector_tables(&self) -> Vec<String> {
54 self.model_names
55 .iter()
56 .map(|name| format!("vec_{}", crate::config::sanitize_key(name)))
57 .collect()
58 }
59}
60
61#[derive(Clone, Debug, Default)]
83pub struct EntityPatch {
84 pub name: Option<String>,
85 pub description: Option<Option<String>>,
86 pub properties: Option<Value>,
87 pub tags: Option<Vec<String>>,
88}
89
90#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
92#[serde(rename_all = "snake_case")]
93pub enum EntityDedupMergePolicy {
94 #[default]
97 PreferInto,
98 PreferFrom,
100 Union,
102}
103
104#[derive(Clone, Copy, Debug, PartialEq, Eq)]
106pub enum EntityMergeGuard {
107 EntityKind,
108 NameSimilarity,
109 ProjectCompatibility,
110}
111
112impl EntityMergeGuard {
113 pub fn as_str(self) -> &'static str {
114 match self {
115 Self::EntityKind => "entity_kind",
116 Self::NameSimilarity => "name_similarity",
117 Self::ProjectCompatibility => "project_compatibility",
118 }
119 }
120}
121
122pub fn validate_entity_merge_floor(into: &Entity, from: &Entity) -> Result<(), EntityMergeGuard> {
124 if into.kind != from.kind {
125 return Err(EntityMergeGuard::EntityKind);
126 }
127 if !names_are_similar(&into.name, &from.name) {
128 return Err(EntityMergeGuard::NameSimilarity);
129 }
130 if projects_are_disjoint(into, from) {
131 return Err(EntityMergeGuard::ProjectCompatibility);
132 }
133 Ok(())
134}
135
136pub fn entity_merge_guard_error(guard: EntityMergeGuard) -> RuntimeError {
138 RuntimeError::Khive(
139 KhiveError::conflict(format!(
140 "entity merge refused by {} guard; use force=true only when the caller accepts responsibility",
141 guard.as_str()
142 ))
143 .with_details(Details::new([
144 ("guard", guard.as_str()),
145 ("override", "force=true"),
146 ])),
147 )
148}
149
150fn names_are_similar(left: &str, right: &str) -> bool {
151 let left = normalize_name(left);
152 let right = normalize_name(right);
153 if left.is_empty() || right.is_empty() {
154 return false;
155 }
156 if left == right {
157 return true;
158 }
159
160 let shorter_len = left.chars().count().min(right.chars().count());
161 if shorter_len >= 3 && (left.starts_with(&right) || right.starts_with(&left)) {
162 return true;
163 }
164
165 let left_trigrams = trigrams(&left);
166 let right_trigrams = trigrams(&right);
167 if left_trigrams.is_empty() || right_trigrams.is_empty() {
168 return false;
169 }
170 let overlap = left_trigrams.intersection(&right_trigrams).count();
171 overlap.saturating_mul(4) >= left_trigrams.len().saturating_add(right_trigrams.len())
172}
173
174fn normalize_name(name: &str) -> String {
175 let mut normalized = String::with_capacity(name.len());
176 let mut pending_space = false;
177 for ch in name.chars().flat_map(char::to_lowercase) {
178 if ch.is_whitespace() {
179 pending_space = !normalized.is_empty();
180 } else {
181 if pending_space {
182 normalized.push(' ');
183 pending_space = false;
184 }
185 normalized.push(ch);
186 }
187 }
188 normalized
189}
190
191fn trigrams(value: &str) -> HashSet<[char; 3]> {
192 let chars: Vec<char> = value.chars().collect();
193 chars
194 .windows(3)
195 .map(|window| [window[0], window[1], window[2]])
196 .collect()
197}
198
199fn projects_are_disjoint(into: &Entity, from: &Entity) -> bool {
200 let Some(into_projects) = into
201 .properties
202 .as_ref()
203 .and_then(|properties| properties.get("projects"))
204 .and_then(Value::as_array)
205 else {
206 return false;
207 };
208 let Some(from_projects) = from
209 .properties
210 .as_ref()
211 .and_then(|properties| properties.get("projects"))
212 .and_then(Value::as_array)
213 else {
214 return false;
215 };
216 if into_projects.is_empty() || from_projects.is_empty() {
217 return false;
218 }
219
220 let (indexed, candidates) = if into_projects.len() <= from_projects.len() {
221 (into_projects, from_projects)
222 } else {
223 (from_projects, into_projects)
224 };
225 let mut indexed_strings = HashSet::new();
226 let mut indexed_values = HashSet::new();
227 for value in indexed {
228 if let Some(value) = value.as_str() {
229 indexed_strings.insert(normalize_project_string(value));
230 } else {
231 indexed_values.insert(value.clone());
232 }
233 }
234 !candidates.iter().any(|candidate| {
235 if let Some(candidate) = candidate.as_str() {
236 indexed_strings.contains(&normalize_project_string(candidate))
237 } else {
238 indexed_values.contains(candidate)
239 }
240 })
241}
242
243fn normalize_project_string(value: &str) -> String {
244 value.trim().to_ascii_lowercase()
245}
246
247#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
249#[serde(rename_all = "snake_case")]
250pub enum ContentMergeStrategy {
251 #[default]
252 Append,
253 PreferInto,
254 PreferFrom,
255}
256
257#[derive(Clone, Debug, Serialize, Deserialize)]
259pub struct MergeSummary {
260 pub kept_id: Uuid,
261 pub removed_id: Uuid,
262 pub edges_rewired: usize,
263 #[serde(default)]
269 pub edges_contract_skipped: usize,
270 #[serde(default)]
274 pub edge_conflict_preimages: Vec<MergeEdgeConflictPreimage>,
275 pub properties_merged: usize,
276 pub tags_unioned: usize,
277 pub content_appended: bool,
278 pub dry_run: bool,
279 #[serde(skip)]
281 pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
282}
283
284#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
290pub struct MergeEdgePreimage {
291 pub id: Uuid,
292 pub namespace: String,
293 pub source_id: Uuid,
294 pub target_id: Uuid,
295 pub relation: String,
296 pub weight: f64,
297 pub created_at: i64,
298 pub updated_at: i64,
299 pub deleted_at: Option<i64>,
300 pub target_backend: Option<String>,
301 pub metadata: Option<Value>,
302}
303
304#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
306pub struct MergeEdgeConflictPreimage {
307 pub surviving_edge_id: Uuid,
308 pub dropped_edge: MergeEdgePreimage,
309 #[serde(default, skip_serializing_if = "Vec::is_empty")]
313 pub incident_edge_preimages: Vec<MergeEdgePreimage>,
314}
315
316#[derive(Clone, Debug, Default)]
321pub struct EdgePatch {
322 pub relation: Option<EdgeRelation>,
323 pub weight: Option<f64>,
324 pub properties: Option<Value>,
325}
326
327#[derive(Clone, Debug, Default)]
334pub struct NotePatch {
335 pub name: Option<Option<String>>,
336 pub content: Option<String>,
337 pub salience: Option<Option<f64>>,
338 pub decay_factor: Option<Option<f64>>,
339 pub properties: Option<Value>,
340 pub(crate) kind_status: Option<String>,
341}
342
343impl NotePatch {
344 pub fn new(
347 name: Option<Option<String>>,
348 content: Option<String>,
349 salience: Option<Option<f64>>,
350 decay_factor: Option<Option<f64>>,
351 properties: Option<Value>,
352 ) -> Self {
353 Self {
354 name,
355 content,
356 salience,
357 decay_factor,
358 properties,
359 kind_status: None,
360 }
361 }
362}
363
364#[derive(Clone, Debug, Default)]
366pub struct EdgeListFilter {
367 pub source_id: Option<Uuid>,
368 pub target_id: Option<Uuid>,
369 pub relations: Vec<EdgeRelation>,
371 pub min_weight: Option<f64>,
372 pub max_weight: Option<f64>,
373}
374
375impl From<EdgeListFilter> for EdgeFilter {
376 fn from(f: EdgeListFilter) -> Self {
377 EdgeFilter {
378 source_ids: f.source_id.into_iter().collect(),
379 target_ids: f.target_id.into_iter().collect(),
380 relations: f.relations,
381 min_weight: f.min_weight,
382 max_weight: f.max_weight,
383 ..Default::default()
384 }
385 }
386}
387
388#[derive(Clone, Copy, Debug, PartialEq, Eq)]
393enum EntityMergeValidation {
394 LegacyKind,
395 SafetyFloor,
396 Forced,
397}
398
399#[derive(Debug)]
400enum EntityMergeRefusal {
401 LegacyKind {
402 into_id: Uuid,
403 into_kind: String,
404 from_id: Uuid,
405 from_kind: String,
406 },
407 SafetyFloor(EntityMergeGuard),
408}
409
410impl EntityMergeRefusal {
411 fn into_runtime_error(self) -> RuntimeError {
412 match self {
413 Self::LegacyKind {
414 into_id,
415 into_kind,
416 from_id,
417 from_kind,
418 } => RuntimeError::InvalidInput(format!(
419 "cannot merge entities of different kinds: into={into_id} ({into_kind}), \
420 from={from_id} ({from_kind}); merge requires both entities to share the same kind"
421 )),
422 Self::SafetyFloor(guard) => entity_merge_guard_error(guard),
423 }
424 }
425}
426
427#[derive(Debug)]
428enum MergeEntitySqlError {
429 Sqlite(SqliteError),
430 Refusal(EntityMergeRefusal),
431}
432
433impl std::fmt::Display for MergeEntitySqlError {
434 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
435 match self {
436 Self::Sqlite(error) => std::fmt::Display::fmt(error, f),
437 Self::Refusal(_) => f.write_str("entity merge refused by transactional policy"),
438 }
439 }
440}
441
442impl std::error::Error for MergeEntitySqlError {}
443
444impl From<SqliteError> for MergeEntitySqlError {
445 fn from(error: SqliteError) -> Self {
446 Self::Sqlite(error)
447 }
448}
449
450impl From<rusqlite::Error> for MergeEntitySqlError {
451 fn from(error: rusqlite::Error) -> Self {
452 Self::Sqlite(SqliteError::Rusqlite(error))
453 }
454}
455
456fn map_merge_entity_storage_error(error: khive_storage::StorageError) -> RuntimeError {
457 match error {
458 khive_storage::StorageError::Driver {
459 capability,
460 operation,
461 source,
462 } => match source.downcast::<MergeEntitySqlError>() {
463 Ok(error) => match *error {
464 MergeEntitySqlError::Sqlite(error) => RuntimeError::Sqlite(error),
465 MergeEntitySqlError::Refusal(error) => error.into_runtime_error(),
466 },
467 Err(source) => RuntimeError::Storage(khive_storage::StorageError::Driver {
468 capability,
469 operation,
470 source,
471 }),
472 },
473 error => RuntimeError::Storage(error),
474 }
475}
476
477#[derive(Clone)]
481struct EdgeRow {
482 id: Uuid,
483 namespace: String,
489 source_id: Uuid,
490 target_id: Uuid,
491 relation: String,
492 weight: f64,
493 created_at: i64,
494 updated_at: i64,
495 deleted_at: Option<i64>,
496 target_backend: Option<String>,
497 metadata: Option<String>,
498}
499
500fn edge_row_preimage(edge: &EdgeRow) -> Result<MergeEdgePreimage, SqliteError> {
501 let metadata = edge
502 .metadata
503 .as_deref()
504 .map(serde_json::from_str)
505 .transpose()
506 .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
507 Ok(MergeEdgePreimage {
508 id: edge.id,
509 namespace: edge.namespace.clone(),
510 source_id: edge.source_id,
511 target_id: edge.target_id,
512 relation: edge.relation.clone(),
513 weight: edge.weight,
514 created_at: edge.created_at,
515 updated_at: edge.updated_at,
516 deleted_at: edge.deleted_at,
517 target_backend: edge.target_backend.clone(),
518 metadata,
519 })
520}
521
522fn collect_conflict_incident_edge_preimages(
528 conn: &rusqlite::Connection,
529 root_edge_id: Uuid,
530 original_edges: &HashMap<Uuid, EdgeRow>,
531) -> Result<Vec<MergeEdgePreimage>, SqliteError> {
532 let parse_id =
533 |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
534 let mut queue = VecDeque::from([root_edge_id]);
535 let mut seen = HashSet::from([root_edge_id]);
536 let mut preimages = Vec::new();
537
538 while let Some(target_edge_id) = queue.pop_front() {
539 let mut stmt = conn.prepare(
540 "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
541 updated_at, deleted_at, target_backend, metadata \
542 FROM graph_edges WHERE source_id = ?1 OR target_id = ?1 ORDER BY id",
543 )?;
544 let mut rows = stmt.query(rusqlite::params![target_edge_id.to_string()])?;
545 while let Some(row) = rows.next()? {
546 let edge = EdgeRow {
547 id: parse_id(row.get(0)?)?,
548 namespace: row.get(1)?,
549 source_id: parse_id(row.get(2)?)?,
550 target_id: parse_id(row.get(3)?)?,
551 relation: row.get(4)?,
552 weight: row.get(5)?,
553 created_at: row.get(6)?,
554 updated_at: row.get(7)?,
555 deleted_at: row.get(8)?,
556 target_backend: row.get(9)?,
557 metadata: row.get(10)?,
558 };
559 if !seen.insert(edge.id) {
560 continue;
561 }
562 let preimage = match original_edges.get(&edge.id) {
563 Some(original) => edge_row_preimage(original)?,
564 None => edge_row_preimage(&edge)?,
565 };
566 queue.push_back(edge.id);
567 preimages.push(preimage);
568 }
569 }
570
571 Ok(preimages)
572}
573
574fn delete_conflict_incident_edges(
575 conn: &rusqlite::Connection,
576 preimages: &[MergeEdgePreimage],
577) -> Result<(), SqliteError> {
578 for edge in preimages.iter().rev() {
579 conn.execute(
580 khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
581 rusqlite::params![&edge.namespace, edge.id.to_string()],
582 )?;
583 }
584 Ok(())
585}
586
587type MergeEdgeEndpointInfo = (&'static str, String, Option<String>);
596
597fn resolve_merge_edge_endpoint(
598 conn: &rusqlite::Connection,
599 id: Uuid,
600) -> Result<Option<MergeEdgeEndpointInfo>, SqliteError> {
601 let id_str = id.to_string();
602 if let Some((kind, entity_type)) = conn
603 .query_row(
604 "SELECT kind, entity_type FROM entities WHERE id = ?1",
605 rusqlite::params![&id_str],
606 |row| Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?)),
607 )
608 .optional()
609 .map_err(SqliteError::Rusqlite)?
610 {
611 return Ok(Some(("entity", kind, entity_type)));
612 }
613 if let Some(kind) = conn
614 .query_row(
615 "SELECT kind FROM notes WHERE id = ?1",
616 rusqlite::params![&id_str],
617 |row| row.get::<_, String>(0),
618 )
619 .optional()
620 .map_err(SqliteError::Rusqlite)?
621 {
622 return Ok(Some(("note", kind, None)));
623 }
624 Ok(None)
625}
626
627#[allow(clippy::too_many_arguments)]
645fn merge_rewire_endpoint_contract_allows(
646 pack_rules: &[EdgeEndpointRule],
647 relation: EdgeRelation,
648 src_sub: &str,
649 src_kind: &str,
650 src_type: Option<&str>,
651 tgt_sub: &str,
652 tgt_kind: &str,
653 tgt_type: Option<&str>,
654) -> bool {
655 if relation == EdgeRelation::Annotates {
656 return true;
657 }
658 if src_sub == "note" && tgt_sub == "note" && crate::pack::is_special_relation(relation) {
661 return true;
662 }
663 if src_sub == "entity"
664 && tgt_sub == "entity"
665 && base_entity_rule_allows(src_kind, relation, tgt_kind)
666 {
667 return true;
668 }
669 pack_rules.iter().any(|r| {
670 r.relation == relation
671 && endpoint_matches(&r.source, src_sub, src_kind, src_type)
672 && endpoint_matches(&r.target, tgt_sub, tgt_kind, tgt_type)
673 })
674}
675
676impl KhiveRuntime {
681 pub(crate) async fn prepare_update_entity(
692 &self,
693 token: &NamespaceToken,
694 id: Uuid,
695 patch: EntityPatch,
696 ) -> RuntimeResult<(Entity, bool, Vec<&'static str>)> {
697 if let Some(ref name) = patch.name {
698 crate::secret_gate::check(name)?;
699 }
700 if let Some(Some(ref desc)) = patch.description {
701 crate::secret_gate::check(desc)?;
702 }
703 if let Some(ref props) = patch.properties {
704 crate::secret_gate::check_json(props)?;
705 }
706 if let Some(ref tags) = patch.tags {
707 crate::secret_gate::check_tags(tags)?;
708 }
709 let store = self.entities(token)?;
710 let mut entity = store
711 .get_entity(id)
712 .await?
713 .ok_or_else(|| RuntimeError::NotFound(format!("entity {id}")))?;
714
715 let mut text_changed = false;
716 let mut changed_fields: Vec<&'static str> = Vec::new();
717
718 if let Some(name) = patch.name {
719 text_changed |= entity.name != name;
720 entity.name = name;
721 changed_fields.push("name");
722 }
723 if let Some(desc_patch) = patch.description {
724 text_changed |= entity.description != desc_patch;
725 entity.description = desc_patch;
726 changed_fields.push("description");
727 }
728 if let Some(props) = patch.properties {
729 let (merged, _) = merge_properties(
730 &entity.properties,
731 &Some(props),
732 EntityDedupMergePolicy::PreferFrom,
733 );
734 entity.properties = merged;
735 changed_fields.push("properties");
736 }
737 if let Some(tags) = patch.tags {
738 entity.tags = tags;
739 changed_fields.push("tags");
740 }
741
742 entity.updated_at = chrono::Utc::now().timestamp_micros();
743 Ok((entity, text_changed, changed_fields))
744 }
745
746 pub async fn update_entity(
747 &self,
748 token: &NamespaceToken,
749 id: Uuid,
750 patch: EntityPatch,
751 ) -> RuntimeResult<Entity> {
752 Ok(self
753 .update_entity_with_embedding_report(token, id, patch)
754 .await?
755 .0)
756 }
757
758 pub async fn update_entity_with_embedding_report(
759 &self,
760 token: &NamespaceToken,
761 id: Uuid,
762 patch: EntityPatch,
763 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
764 let (entity, text_changed, changed_fields) =
765 self.prepare_update_entity(token, id, patch).await?;
766
767 let store = self.entities(token)?;
768 store.upsert_entity(entity.clone()).await?;
769
770 let embedding_report = if text_changed {
771 self.reindex_entity(token, &entity).await?
772 } else {
773 crate::retrieval::EmbeddingTruncationReport::default()
774 };
775
776 let event_store = self.events(token)?;
777 let event = khive_storage::event::Event::new(
778 entity.namespace.clone(),
779 "update",
780 EventKind::EntityUpdated,
781 SubstrateKind::Entity,
782 "",
783 )
784 .with_target(entity.id)
785 .with_payload(serde_json::json!({
786 "id": entity.id,
787 "namespace": entity.namespace,
788 "changed_fields": changed_fields,
789 }));
790 event_store.append_event(event).await.map_err(|e| {
791 RuntimeError::Internal(format!("update_entity: event store write failed: {e}"))
792 })?;
793
794 Ok((entity, embedding_report))
795 }
796
797 pub async fn merge_entity(
810 &self,
811 token: &NamespaceToken,
812 into_id: Uuid,
813 from_id: Uuid,
814 strategy: EntityDedupMergePolicy,
815 content_strategy: ContentMergeStrategy,
816 dry_run: bool,
817 ) -> RuntimeResult<MergeSummary> {
818 self.merge_entity_with_reason(
819 token,
820 into_id,
821 from_id,
822 strategy,
823 content_strategy,
824 dry_run,
825 None,
826 )
827 .await
828 }
829
830 #[allow(clippy::too_many_arguments)]
834 pub async fn merge_entity_with_reason(
835 &self,
836 token: &NamespaceToken,
837 into_id: Uuid,
838 from_id: Uuid,
839 strategy: EntityDedupMergePolicy,
840 content_strategy: ContentMergeStrategy,
841 dry_run: bool,
842 reason: Option<String>,
843 ) -> RuntimeResult<MergeSummary> {
844 self.merge_entity_with_validation(
845 token,
846 into_id,
847 from_id,
848 strategy,
849 content_strategy,
850 dry_run,
851 reason,
852 EntityMergeValidation::LegacyKind,
853 )
854 .await
855 }
856
857 #[allow(clippy::too_many_arguments)]
866 pub async fn merge_entity_with_reason_and_force(
867 &self,
868 token: &NamespaceToken,
869 into_id: Uuid,
870 from_id: Uuid,
871 strategy: EntityDedupMergePolicy,
872 content_strategy: ContentMergeStrategy,
873 dry_run: bool,
874 reason: Option<String>,
875 force: bool,
876 ) -> RuntimeResult<MergeSummary> {
877 let validation = if force {
878 EntityMergeValidation::Forced
879 } else {
880 EntityMergeValidation::SafetyFloor
881 };
882 self.merge_entity_with_validation(
883 token,
884 into_id,
885 from_id,
886 strategy,
887 content_strategy,
888 dry_run,
889 reason,
890 validation,
891 )
892 .await
893 }
894
895 #[allow(clippy::too_many_arguments)]
896 async fn merge_entity_with_validation(
897 &self,
898 token: &NamespaceToken,
899 into_id: Uuid,
900 from_id: Uuid,
901 strategy: EntityDedupMergePolicy,
902 content_strategy: ContentMergeStrategy,
903 dry_run: bool,
904 reason: Option<String>,
905 validation: EntityMergeValidation,
906 ) -> RuntimeResult<MergeSummary> {
907 if let Some(reason) = reason.as_deref() {
908 crate::secret_gate::check(reason)?;
909 }
910 if into_id == from_id {
911 return Err(RuntimeError::InvalidInput(
912 "cannot merge an entity into itself".into(),
913 ));
914 }
915 let ns = token.namespace().as_str().to_owned();
916 let fts_table = "fts_entities".to_string();
917 let embedding_plan = EmbeddingModelPlan::capture(self);
921 let vec_tables = embedding_plan.vector_tables();
922 let pack_rules = self.pack_edge_rules();
925
926 let _ = self.entities(token)?;
928 let _ = self.graph(token)?;
929 let _ = self.text(token)?;
930 for model_name in embedding_plan.model_names() {
933 let _ = self.vectors_for_model(token, model_name)?;
934 }
935
936 let pool = self.backend().pool_arc();
937 let writer_task = pool.writer_task_handle().ok().flatten();
941
942 let (mut summary, updated_entity) = if let Some(writer_task) = writer_task {
943 writer_task
944 .send(move |conn| {
945 merge_entity_sql(
946 conn,
947 ns,
948 fts_table,
949 vec_tables,
950 into_id,
951 from_id,
952 strategy,
953 content_strategy,
954 dry_run,
955 pack_rules,
956 validation,
957 )
958 .map_err(|e| {
959 khive_storage::StorageError::driver(
960 khive_storage::StorageCapability::Entities,
961 "merge_entity",
962 e,
963 )
964 })
965 })
966 .await
967 .map_err(map_merge_entity_storage_error)?
968 } else {
969 tokio::task::spawn_blocking(move || {
970 let guard = pool.writer()?;
971 let mut refusal = None;
972 let result = guard.transaction(|conn| {
973 merge_entity_sql(
974 conn,
975 ns,
976 fts_table,
977 vec_tables,
978 into_id,
979 from_id,
980 strategy,
981 content_strategy,
982 dry_run,
983 pack_rules,
984 validation,
985 )
986 .map_err(|error| match error {
987 MergeEntitySqlError::Sqlite(error) => error,
988 MergeEntitySqlError::Refusal(error) => {
989 refusal = Some(error);
990 SqliteError::InvalidData(
991 "entity merge refused by transactional policy".to_string(),
992 )
993 }
994 })
995 });
996 match refusal {
997 Some(error) => Err(error.into_runtime_error()),
998 None => result.map_err(RuntimeError::from),
999 }
1000 })
1001 .await
1002 .map_err(|e| RuntimeError::Internal(e.to_string()))??
1003 };
1004
1005 if !dry_run && !embedding_plan.is_empty() {
1008 summary.embedding_truncation = self
1009 .reindex_entity_with_plan(token, &updated_entity, &embedding_plan)
1010 .await?;
1011 }
1012
1013 if !dry_run {
1015 let event_store = self.events(token)?;
1016 let policy_str = match strategy {
1019 EntityDedupMergePolicy::PreferInto => "prefer_into",
1020 EntityDedupMergePolicy::PreferFrom => "prefer_from",
1021 EntityDedupMergePolicy::Union => "union",
1022 };
1023 let mut payload = serde_json::json!({
1024 "into_id": summary.kept_id,
1025 "from_id": summary.removed_id,
1026 "policy": policy_str,
1027 "content_strategy": format!("{:?}", content_strategy),
1028 "edges_rewired": summary.edges_rewired,
1029 "edges_contract_skipped": summary.edges_contract_skipped,
1030 "edge_conflict_preimages": &summary.edge_conflict_preimages,
1031 });
1032 if let Some(reason) = reason {
1033 payload["reason"] = serde_json::Value::String(reason);
1034 }
1035 if validation == EntityMergeValidation::Forced {
1036 payload["force"] = serde_json::Value::Bool(true);
1037 }
1038 let event = khive_storage::event::Event::new(
1039 updated_entity.namespace.clone(),
1040 "merge",
1041 EventKind::EntityMerged,
1042 SubstrateKind::Entity,
1043 "",
1044 )
1045 .with_target(summary.kept_id)
1046 .with_payload(payload);
1047 event_store.append_event(event).await.map_err(|e| {
1048 RuntimeError::Internal(format!("merge_entity: event store write failed: {e}"))
1049 })?;
1050 }
1051
1052 Ok(summary)
1053 }
1054
1055 pub(crate) async fn reindex_entity(
1070 &self,
1071 token: &NamespaceToken,
1072 entity: &Entity,
1073 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1074 let embedding_plan = EmbeddingModelPlan::capture(self);
1075 self.reindex_entity_with_plan(token, entity, &embedding_plan)
1076 .await
1077 }
1078
1079 async fn reindex_entity_with_plan(
1080 &self,
1081 token: &NamespaceToken,
1082 entity: &Entity,
1083 embedding_plan: &EmbeddingModelPlan,
1084 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1085 let ns = entity.namespace.clone();
1087 let doc = entity_fts_document(entity);
1088 let embed_body = doc.body.clone();
1089 self.text(token)?.upsert_document(doc).await?;
1090
1091 let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1092 for model_name in embedding_plan.model_names() {
1093 match self
1094 .embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
1095 .await
1096 {
1097 Ok(outcome) => {
1098 report.observe(&outcome);
1099 match self.vectors_for_model(token, model_name) {
1100 Ok(vs) => {
1101 if let Err(e) = vs
1102 .insert(
1103 entity.id,
1104 SubstrateKind::Entity,
1105 &ns,
1106 "entity.body",
1107 vec![outcome.vector],
1108 )
1109 .await
1110 {
1111 tracing::warn!(
1112 model = model_name,
1113 id = %entity.id,
1114 "reindex_entity: vector insert failed, skipping model: {e}"
1115 );
1116 }
1117 }
1118 Err(e) => {
1119 tracing::warn!(
1120 model = model_name,
1121 id = %entity.id,
1122 "reindex_entity: could not access vector store for model, skipping: {e}"
1123 );
1124 }
1125 }
1126 }
1127 Err(e) => {
1128 tracing::warn!(
1129 model = model_name,
1130 id = %entity.id,
1131 "reindex_entity: embed failed for model, skipping: {e}"
1132 );
1133 }
1134 }
1135 }
1136
1137 Ok(report)
1138 }
1139
1140 pub(crate) async fn remove_from_indexes(
1142 &self,
1143 token: &NamespaceToken,
1144 id: Uuid,
1145 ) -> RuntimeResult<()> {
1146 let ns = token.namespace().as_str().to_owned();
1147 self.text(token)?.delete_document(&ns, id).await?;
1148 for model_name in self.registered_embedding_model_names() {
1149 self.vectors_for_model(token, &model_name)?
1150 .delete(id)
1151 .await?;
1152 }
1153 Ok(())
1154 }
1155
1156 pub(crate) async fn reindex_note(
1160 &self,
1161 token: &NamespaceToken,
1162 note: &khive_storage::note::Note,
1163 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1164 let embedding_plan = EmbeddingModelPlan::capture(self);
1165 self.reindex_note_with_plan(token, note, &embedding_plan)
1166 .await
1167 }
1168
1169 async fn reindex_note_with_plan(
1170 &self,
1171 token: &NamespaceToken,
1172 note: &khive_storage::note::Note,
1173 embedding_plan: &EmbeddingModelPlan,
1174 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1175 self.text_for_notes(token)?
1176 .upsert_document(note_fts_document(note))
1177 .await?;
1178
1179 let ns = note.namespace.clone();
1180 let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1181 for model_name in embedding_plan.model_names() {
1182 match self
1183 .embed_document_with_model_outcome_for_token(
1184 token,
1185 model_name,
1186 ¬e_embedding_text(note),
1187 )
1188 .await
1189 {
1190 Ok(outcome) => {
1191 report.observe(&outcome);
1192 match self.vectors_for_model(token, model_name) {
1193 Ok(vs) => {
1194 if let Err(e) = vs
1195 .insert(
1196 note.id,
1197 SubstrateKind::Note,
1198 &ns,
1199 "note.content",
1200 vec![outcome.vector],
1201 )
1202 .await
1203 {
1204 tracing::warn!(
1205 model = model_name,
1206 id = %note.id,
1207 "reindex_note: vector insert failed, skipping model: {e}"
1208 );
1209 }
1210 }
1211 Err(e) => {
1212 tracing::warn!(
1213 model = model_name,
1214 id = %note.id,
1215 "reindex_note: could not access vector store for model, skipping: {e}"
1216 );
1217 }
1218 }
1219 }
1220 Err(e) => {
1221 tracing::warn!(
1222 model = model_name,
1223 id = %note.id,
1224 "reindex_note: embed failed for model, skipping: {e}"
1225 );
1226 }
1227 }
1228 }
1229 Ok(report)
1230 }
1231
1232 pub(crate) async fn prepare_update_note(
1236 &self,
1237 token: &NamespaceToken,
1238 id: Uuid,
1239 patch: NotePatch,
1240 ) -> RuntimeResult<(khive_storage::note::Note, bool)> {
1241 if let Some(ref content) = patch.content {
1242 crate::secret_gate::check(content)?;
1243 }
1244 if let Some(Some(ref name)) = patch.name {
1245 crate::secret_gate::check(name)?;
1246 }
1247 if let Some(ref props) = patch.properties {
1248 crate::secret_gate::check_json(props)?;
1249 }
1250 let store = self.notes(token)?;
1251 let mut note = store
1252 .get_note(id)
1253 .await?
1254 .ok_or_else(|| RuntimeError::NotFound(format!("note {id}")))?;
1255
1256 reject_pack_managed_schedule_mutation(¬e, "update")?;
1257
1258 let mut text_changed = false;
1259
1260 if let Some(name_patch) = patch.name {
1261 text_changed |= note.name != name_patch;
1262 note.name = name_patch;
1263 }
1264 if let Some(content) = patch.content {
1265 text_changed |= note.content != content;
1266 note.content = content;
1267 }
1268 if let Some(salience_patch) = patch.salience {
1269 if let Some(s) = salience_patch {
1271 if !s.is_finite() || !(0.0..=1.0).contains(&s) {
1272 return Err(crate::RuntimeError::InvalidInput(format!(
1273 "salience must be a finite value in [0.0, 1.0]; got {s}"
1274 )));
1275 }
1276 }
1277 note.salience = salience_patch;
1278 }
1279 if let Some(decay_patch) = patch.decay_factor {
1280 if let Some(d) = decay_patch {
1282 if !d.is_finite() || d < 0.0 {
1283 return Err(crate::RuntimeError::InvalidInput(format!(
1284 "decay_factor must be a finite value >= 0.0; got {d}"
1285 )));
1286 }
1287 }
1288 note.decay_factor = decay_patch;
1289 }
1290 if let Some(props) = patch.properties {
1291 let (merged, _) = merge_properties(
1292 ¬e.properties,
1293 &Some(props),
1294 EntityDedupMergePolicy::PreferFrom,
1295 );
1296 note.properties = merged;
1297 }
1298 if let Some(status) = patch.kind_status {
1299 note.status = status;
1300 }
1301
1302 note.updated_at = chrono::Utc::now().timestamp_micros();
1303 Ok((note, text_changed))
1304 }
1305
1306 pub async fn update_note(
1308 &self,
1309 token: &NamespaceToken,
1310 id: Uuid,
1311 patch: NotePatch,
1312 ) -> RuntimeResult<khive_storage::note::Note> {
1313 Ok(self
1314 .update_note_with_embedding_report(token, id, patch)
1315 .await?
1316 .0)
1317 }
1318
1319 pub async fn update_note_with_embedding_report(
1320 &self,
1321 token: &NamespaceToken,
1322 id: Uuid,
1323 patch: NotePatch,
1324 ) -> RuntimeResult<(
1325 khive_storage::note::Note,
1326 crate::retrieval::EmbeddingTruncationReport,
1327 )> {
1328 let (note, text_changed) = self.prepare_update_note(token, id, patch).await?;
1329
1330 let store = self.notes(token)?;
1331 store.upsert_note(note.clone()).await?;
1332
1333 let embedding_report = if text_changed {
1334 let report = self.reindex_note(token, ¬e).await?;
1335 self.fire_note_mutation_hook(¬e.kind, note.id).await;
1339 report
1340 } else {
1341 crate::retrieval::EmbeddingTruncationReport::default()
1342 };
1343
1344 Ok((note, embedding_report))
1345 }
1346
1347 pub async fn merge_note(
1356 &self,
1357 token: &NamespaceToken,
1358 into_id: Uuid,
1359 from_id: Uuid,
1360 strategy: EntityDedupMergePolicy,
1361 content_strategy: ContentMergeStrategy,
1362 dry_run: bool,
1363 ) -> RuntimeResult<MergeSummary> {
1364 self.merge_note_with_reason(
1365 token,
1366 into_id,
1367 from_id,
1368 strategy,
1369 content_strategy,
1370 dry_run,
1371 None,
1372 )
1373 .await
1374 }
1375
1376 #[allow(clippy::too_many_arguments)]
1380 pub async fn merge_note_with_reason(
1381 &self,
1382 token: &NamespaceToken,
1383 into_id: Uuid,
1384 from_id: Uuid,
1385 strategy: EntityDedupMergePolicy,
1386 content_strategy: ContentMergeStrategy,
1387 dry_run: bool,
1388 reason: Option<String>,
1389 ) -> RuntimeResult<MergeSummary> {
1390 if let Some(reason) = reason.as_deref() {
1391 crate::secret_gate::check(reason)?;
1392 }
1393 if into_id == from_id {
1394 return Err(RuntimeError::InvalidInput(
1395 "cannot merge a note into itself".into(),
1396 ));
1397 }
1398 let ns = token.namespace().as_str().to_string();
1399 let fts_table = "fts_notes".to_string();
1400 let embedding_plan = EmbeddingModelPlan::capture(self);
1403 let vec_tables = embedding_plan.vector_tables();
1404 let pack_rules = self.pack_edge_rules();
1405
1406 let note_store = self.notes(token)?;
1407 let into_note = note_store
1408 .get_note(into_id)
1409 .await?
1410 .ok_or_else(|| RuntimeError::NotFound("not found in this namespace".into()))?;
1411 Self::ensure_namespace(&into_note.namespace, &ns)?;
1412
1413 let from_note = note_store
1414 .get_note(from_id)
1415 .await?
1416 .ok_or_else(|| RuntimeError::NotFound("not found in this namespace".into()))?;
1417 Self::ensure_namespace(&from_note.namespace, &ns)?;
1418
1419 reject_pack_managed_schedule_mutation(&into_note, "merge")?;
1420 reject_pack_managed_schedule_mutation(&from_note, "merge")?;
1421
1422 let _ = self.graph(token)?;
1423 let _ = self.text_for_notes(token)?;
1424 for model_name in embedding_plan.model_names() {
1425 let _ = self.vectors_for_model(token, model_name)?;
1426 }
1427
1428 let pool = self.backend().pool_arc();
1429 let writer_task = pool.writer_task_handle().ok().flatten();
1430
1431 let (mut summary, updated_note) = if let Some(writer_task) = writer_task {
1432 writer_task
1433 .send(move |conn| {
1434 merge_note_sql(
1435 conn,
1436 ns,
1437 fts_table,
1438 vec_tables,
1439 into_id,
1440 from_id,
1441 strategy,
1442 content_strategy,
1443 dry_run,
1444 pack_rules,
1445 )
1446 .map_err(|e| {
1447 khive_storage::StorageError::driver(
1448 khive_storage::StorageCapability::Notes,
1449 "merge_note",
1450 e,
1451 )
1452 })
1453 })
1454 .await
1455 .map_err(RuntimeError::Storage)?
1456 } else {
1457 tokio::task::spawn_blocking(move || {
1458 let guard = pool.writer()?;
1459 guard.transaction(|conn| {
1460 merge_note_sql(
1461 conn,
1462 ns,
1463 fts_table,
1464 vec_tables,
1465 into_id,
1466 from_id,
1467 strategy,
1468 content_strategy,
1469 dry_run,
1470 pack_rules,
1471 )
1472 })
1473 })
1474 .await
1475 .map_err(|e| RuntimeError::Internal(e.to_string()))??
1476 };
1477
1478 if !dry_run && !embedding_plan.is_empty() {
1479 summary.embedding_truncation = self
1480 .reindex_note_with_plan(token, &updated_note, &embedding_plan)
1481 .await?;
1482 self.fire_note_mutation_hook(&updated_note.kind, updated_note.id)
1486 .await;
1487 }
1488
1489 if !dry_run {
1491 let event_store = self.events(token)?;
1492 let policy_str = match strategy {
1495 EntityDedupMergePolicy::PreferInto => "prefer_into",
1496 EntityDedupMergePolicy::PreferFrom => "prefer_from",
1497 EntityDedupMergePolicy::Union => "union",
1498 };
1499 let mut payload = serde_json::json!({
1500 "into_id": summary.kept_id,
1501 "from_id": summary.removed_id,
1502 "policy": policy_str,
1503 "content_strategy": format!("{:?}", content_strategy),
1504 "edges_rewired": summary.edges_rewired,
1505 "edges_contract_skipped": summary.edges_contract_skipped,
1506 "edge_conflict_preimages": &summary.edge_conflict_preimages,
1507 });
1508 if let Some(reason) = reason {
1509 payload["reason"] = serde_json::Value::String(reason);
1510 }
1511 let event = khive_storage::event::Event::new(
1512 updated_note.namespace.clone(),
1513 "merge",
1514 EventKind::NoteMerged,
1515 SubstrateKind::Note,
1516 "",
1517 )
1518 .with_target(summary.kept_id)
1519 .with_payload(payload);
1520 event_store.append_event(event).await.map_err(|e| {
1521 RuntimeError::Internal(format!("merge_note: event store write failed: {e}"))
1522 })?;
1523 }
1524
1525 Ok(summary)
1526 }
1527}
1528
1529fn reject_pack_managed_schedule_mutation(
1537 note: &khive_storage::note::Note,
1538 operation: &str,
1539) -> RuntimeResult<()> {
1540 if note.kind == "scheduled_event" {
1541 return Err(RuntimeError::InvalidInput(format!(
1542 "cannot {operation} a schedule-managed `scheduled_event` note through generic KG \
1543 mutation; use schedule.cancel or create a replacement schedule"
1544 )));
1545 }
1546 Ok(())
1547}
1548
1549pub fn entity_embedding_text(entity: &Entity) -> String {
1556 match &entity.description {
1557 Some(description) if !description.is_empty() => {
1558 format!("{} {description}", entity.name)
1559 }
1560 _ => entity.name.clone(),
1561 }
1562}
1563
1564pub fn note_embedding_text(note: &Note) -> String {
1567 note.content.clone()
1568}
1569
1570pub fn entity_fts_document(entity: &Entity) -> TextDocument {
1583 let updated_at =
1584 chrono::DateTime::from_timestamp_micros(entity.updated_at).unwrap_or_else(chrono::Utc::now);
1585 TextDocument {
1586 subject_id: entity.id,
1587 kind: SubstrateKind::Entity,
1588 title: Some(entity.name.clone()),
1589 body: entity_embedding_text(entity),
1590 tags: entity.tags.clone(),
1591 namespace: entity.namespace.clone(),
1592 metadata: entity.properties.clone(),
1593 updated_at,
1594 }
1595}
1596
1597pub fn note_fts_document(note: &Note) -> TextDocument {
1610 let body = match ¬e.name {
1611 Some(n) => format!("{n} {}", note.content),
1612 None => note.content.clone(),
1613 };
1614 let updated_at =
1615 chrono::DateTime::from_timestamp_micros(note.updated_at).unwrap_or_else(chrono::Utc::now);
1616 TextDocument {
1617 subject_id: note.id,
1618 kind: SubstrateKind::Note,
1619 title: note.name.clone(),
1620 body,
1621 tags: vec![],
1622 namespace: note.namespace.clone(),
1623 metadata: note.properties.clone(),
1624 updated_at,
1625 }
1626}
1627
1628pub(crate) struct NoteFtsScalars {
1634 pub title: String,
1637 pub body: String,
1638 pub tags: String,
1640 pub metadata: Option<String>,
1642 pub updated_at_micros: i64,
1644}
1645
1646pub(crate) fn note_fts_scalars(note: &Note) -> NoteFtsScalars {
1651 let doc = note_fts_document(note);
1652 NoteFtsScalars {
1653 title: doc.title.unwrap_or_default(),
1654 body: doc.body,
1655 tags: "[]".to_string(),
1656 metadata: doc
1657 .metadata
1658 .as_ref()
1659 .map(|v| serde_json::to_string(v).unwrap_or_default()),
1660 updated_at_micros: doc.updated_at.timestamp_micros(),
1661 }
1662}
1663
1664fn read_merge_entity(
1670 conn: &rusqlite::Connection,
1671 id: Uuid,
1672 namespace: &str,
1673) -> Result<Entity, SqliteError> {
1674 let id_str = id.to_string();
1675 let mut stmt = conn.prepare(
1676 "SELECT id, namespace, kind, entity_type, name, description, properties, tags, \
1677 created_at, updated_at, deleted_at, merged_into, merge_event_id, content_ref \
1678 FROM entities WHERE id = ?1 AND deleted_at IS NULL",
1679 )?;
1680 let mut rows = stmt.query(rusqlite::params![id_str])?;
1681 let row = rows
1682 .next()?
1683 .ok_or_else(|| SqliteError::InvalidData(format!("entity {id} not found")))?;
1684
1685 let id_s: String = row.get(0)?;
1686 let ns: String = row.get(1)?;
1687 let kind: String = row.get(2)?;
1688 let entity_type: Option<String> = row.get(3)?;
1689 let name: String = row.get(4)?;
1690 let description: Option<String> = row.get(5)?;
1691 let properties_str: Option<String> = row.get(6)?;
1692 let tags_str: String = row.get(7)?;
1693 let created_at: i64 = row.get(8)?;
1694 let updated_at: i64 = row.get(9)?;
1695 let deleted_at: Option<i64> = row.get(10)?;
1696 let merged_into_str: Option<String> = row.get(11)?;
1697 let merge_event_id_str: Option<String> = row.get(12)?;
1698 let content_ref: Option<String> = row.get(13)?;
1699
1700 if ns != namespace {
1701 return Err(SqliteError::InvalidData(format!(
1702 "entity {id} belongs to namespace '{ns}', not '{namespace}'"
1703 )));
1704 }
1705
1706 let entity_id = Uuid::parse_str(&id_s).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1707 let properties: Option<Value> = properties_str
1708 .map(|s| {
1709 serde_json::from_str::<Value>(&s).map_err(|e| SqliteError::InvalidData(e.to_string()))
1710 })
1711 .transpose()?;
1712 let tags: Vec<String> =
1713 serde_json::from_str(&tags_str).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1714 let merged_into = merged_into_str
1715 .as_deref()
1716 .map(Uuid::parse_str)
1717 .transpose()
1718 .map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1719 let merge_event_id = merge_event_id_str
1720 .as_deref()
1721 .map(Uuid::parse_str)
1722 .transpose()
1723 .map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1724
1725 Ok(Entity {
1726 id: entity_id,
1727 namespace: ns,
1728 kind,
1729 entity_type,
1730 name,
1731 description,
1732 properties,
1733 tags,
1734 created_at,
1735 updated_at,
1736 deleted_at,
1737 merged_into,
1738 merge_event_id,
1739 content_ref,
1740 })
1741}
1742
1743#[allow(clippy::too_many_arguments)]
1754fn merge_entity_sql(
1755 conn: &rusqlite::Connection,
1756 namespace: String,
1757 fts_table: String,
1758 vec_tables: Vec<String>,
1759 into_id: Uuid,
1760 from_id: Uuid,
1761 strategy: EntityDedupMergePolicy,
1762 content_strategy: ContentMergeStrategy,
1763 dry_run: bool,
1764 pack_rules: Vec<EdgeEndpointRule>,
1765 validation: EntityMergeValidation,
1766) -> Result<(MergeSummary, Entity), MergeEntitySqlError> {
1767 let into_entity = read_merge_entity(conn, into_id, &namespace)?;
1768 let from_entity = read_merge_entity(conn, from_id, &namespace)?;
1769
1770 match validation {
1771 EntityMergeValidation::LegacyKind if into_entity.kind != from_entity.kind => {
1772 return Err(MergeEntitySqlError::Refusal(
1773 EntityMergeRefusal::LegacyKind {
1774 into_id,
1775 into_kind: into_entity.kind,
1776 from_id,
1777 from_kind: from_entity.kind,
1778 },
1779 ));
1780 }
1781 EntityMergeValidation::SafetyFloor => {
1782 validate_entity_merge_floor(&into_entity, &from_entity).map_err(|guard| {
1783 MergeEntitySqlError::Refusal(EntityMergeRefusal::SafetyFloor(guard))
1784 })?;
1785 }
1786 EntityMergeValidation::LegacyKind | EntityMergeValidation::Forced => {}
1787 }
1788
1789 let parse_id =
1791 |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
1792
1793 let from_str = from_id.to_string();
1794
1795 let mut outbound: Vec<EdgeRow> = Vec::new();
1802 {
1803 let mut stmt = conn.prepare(
1804 "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
1805 updated_at, deleted_at, target_backend, metadata \
1806 FROM graph_edges WHERE source_id = ?1",
1807 )?;
1808 let mut rows = stmt.query(rusqlite::params![&from_str])?;
1809 while let Some(row) = rows.next()? {
1810 outbound.push(EdgeRow {
1811 id: parse_id(row.get(0)?)?,
1812 namespace: row.get(1)?,
1813 source_id: parse_id(row.get(2)?)?,
1814 target_id: parse_id(row.get(3)?)?,
1815 relation: row.get(4)?,
1816 weight: row.get(5)?,
1817 created_at: row.get(6)?,
1818 updated_at: row.get(7)?,
1819 deleted_at: row.get(8)?,
1820 target_backend: row.get(9)?,
1821 metadata: row.get(10)?,
1822 });
1823 }
1824 }
1825
1826 let mut inbound: Vec<EdgeRow> = Vec::new();
1827 {
1828 let mut stmt = conn.prepare(
1829 "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
1830 updated_at, deleted_at, target_backend, metadata \
1831 FROM graph_edges WHERE target_id = ?1",
1832 )?;
1833 let mut rows = stmt.query(rusqlite::params![&from_str])?;
1834 while let Some(row) = rows.next()? {
1835 inbound.push(EdgeRow {
1836 id: parse_id(row.get(0)?)?,
1837 namespace: row.get(1)?,
1838 source_id: parse_id(row.get(2)?)?,
1839 target_id: parse_id(row.get(3)?)?,
1840 relation: row.get(4)?,
1841 weight: row.get(5)?,
1842 created_at: row.get(6)?,
1843 updated_at: row.get(7)?,
1844 deleted_at: row.get(8)?,
1845 target_backend: row.get(9)?,
1846 metadata: row.get(10)?,
1847 });
1848 }
1849 }
1850
1851 let mut seen: HashSet<Uuid> = HashSet::new();
1853 let mut all_edges: Vec<EdgeRow> = Vec::new();
1854 for edge in outbound.into_iter().chain(inbound) {
1855 if seen.insert(edge.id) {
1856 all_edges.push(edge);
1857 }
1858 }
1859 let original_edges: HashMap<Uuid, EdgeRow> = all_edges
1860 .iter()
1861 .map(|edge| (edge.id, edge.clone()))
1862 .collect();
1863
1864 let (merged_props, properties_merged) =
1866 merge_properties(&into_entity.properties, &from_entity.properties, strategy);
1867 let merged_name = merge_string_field(&into_entity.name, &from_entity.name, strategy);
1868 let (merged_description, content_appended) = match content_strategy {
1869 ContentMergeStrategy::Append => {
1870 let into_desc = into_entity.description.as_deref().unwrap_or("");
1871 let from_desc = from_entity.description.as_deref().unwrap_or("");
1872 if from_desc.is_empty() {
1873 (into_entity.description.clone(), false)
1874 } else if into_desc.is_empty() {
1875 (from_entity.description.clone(), true)
1876 } else {
1877 (Some(format!("{}\n\n---\n\n{}", into_desc, from_desc)), true)
1878 }
1879 }
1880 ContentMergeStrategy::PreferInto => (into_entity.description.clone(), false),
1884 ContentMergeStrategy::PreferFrom => (from_entity.description.clone(), false),
1885 };
1886 let (merged_tags, tags_unioned) = union_tags(&into_entity.tags, &from_entity.tags);
1887
1888 let now = chrono::Utc::now().timestamp_micros();
1889 let into_str = into_id.to_string();
1890 let props_str = merged_props
1891 .as_ref()
1892 .map(|v| serde_json::to_string(v).unwrap_or_default());
1893 let tags_json = serde_json::to_string(&merged_tags).unwrap_or_else(|_| "[]".to_string());
1894
1895 let mut rewired_edge_ids = HashSet::new();
1898 let mut edges_contract_skipped = 0usize;
1899 let mut edge_conflict_preimages = Vec::new();
1900 let mut conflict_deleted_edge_ids = HashSet::new();
1901 for edge in all_edges {
1902 if conflict_deleted_edge_ids.contains(&edge.id) {
1903 continue;
1904 }
1905 let raw_src = if edge.source_id == from_id {
1906 into_id
1907 } else {
1908 edge.source_id
1909 };
1910 let raw_tgt = if edge.target_id == from_id {
1911 into_id
1912 } else {
1913 edge.target_id
1914 };
1915 let relation_typed = edge.relation.parse::<EdgeRelation>().ok();
1916 let (new_src, new_tgt) = match relation_typed {
1919 Some(rel) => canonical_edge_endpoints(rel, raw_src, raw_tgt),
1920 None => (raw_src, raw_tgt),
1921 };
1922
1923 if new_src == new_tgt {
1924 if !dry_run {
1925 conn.execute(
1926 "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
1927 rusqlite::params![&edge.namespace, edge.id.to_string()],
1928 )?;
1929 }
1930 continue;
1931 }
1932
1933 let contract_ok = match relation_typed {
1941 Some(EdgeRelation::Annotates) => true,
1946 Some(rel) => {
1947 let src_info = if new_src == into_id {
1948 Some((
1949 "entity",
1950 into_entity.kind.clone(),
1951 into_entity.entity_type.clone(),
1952 ))
1953 } else {
1954 resolve_merge_edge_endpoint(conn, new_src)?
1955 };
1956 let tgt_info = if new_tgt == into_id {
1957 Some((
1958 "entity",
1959 into_entity.kind.clone(),
1960 into_entity.entity_type.clone(),
1961 ))
1962 } else {
1963 resolve_merge_edge_endpoint(conn, new_tgt)?
1964 };
1965 match (src_info, tgt_info) {
1966 (Some((src_sub, src_kind, src_type)), Some((tgt_sub, tgt_kind, tgt_type))) => {
1967 merge_rewire_endpoint_contract_allows(
1968 &pack_rules,
1969 rel,
1970 src_sub,
1971 &src_kind,
1972 src_type.as_deref(),
1973 tgt_sub,
1974 &tgt_kind,
1975 tgt_type.as_deref(),
1976 )
1977 }
1978 _ => false,
1981 }
1982 }
1983 None => true,
1986 };
1987 if !contract_ok {
1988 if !dry_run {
1989 conn.execute(
1990 "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
1991 rusqlite::params![&edge.namespace, edge.id.to_string()],
1992 )?;
1993 }
1994 tracing::warn!(
1995 edge_id = %edge.id,
1996 source = %new_src,
1997 target = %new_tgt,
1998 relation = %edge.relation,
1999 "merge_entity: dropping rewired edge — endpoint contract violation post-merge"
2000 );
2001 edges_contract_skipped += 1;
2002 continue;
2003 }
2004
2005 let now_ts = chrono::Utc::now().timestamp_micros();
2006 let conflict_id: Option<String> = {
2013 let conflict_src = new_src.to_string();
2014 let conflict_tgt = new_tgt.to_string();
2015 conn.query_row(
2016 khive_db::stores::graph::EDGE_SYMMETRIC_CONFLICT_PROBE_SQL,
2017 rusqlite::params![
2018 &edge.namespace,
2019 &conflict_src,
2020 &conflict_tgt,
2021 &edge.relation,
2022 edge.id.to_string(),
2023 ],
2024 |row| row.get(0),
2025 )
2026 .optional()
2027 .map_err(SqliteError::Rusqlite)?
2028 };
2029
2030 if let Some(conflict_id) = conflict_id {
2031 let surviving_edge_id = Uuid::parse_str(&conflict_id)
2037 .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
2038 let incident_edge_preimages =
2039 collect_conflict_incident_edge_preimages(conn, edge.id, &original_edges)?;
2040 for incident in &incident_edge_preimages {
2041 conflict_deleted_edge_ids.insert(incident.id);
2042 rewired_edge_ids.remove(&incident.id);
2043 }
2044 conflict_deleted_edge_ids.insert(edge.id);
2045 rewired_edge_ids.insert(edge.id);
2046
2047 if !dry_run {
2048 delete_conflict_incident_edges(conn, &incident_edge_preimages)?;
2049 conn.execute(
2050 khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
2051 rusqlite::params![&edge.namespace, edge.id.to_string()],
2052 )?;
2053 }
2054 edge_conflict_preimages.push(MergeEdgeConflictPreimage {
2055 surviving_edge_id,
2056 dropped_edge: edge_row_preimage(&edge)?,
2057 incident_edge_preimages,
2058 });
2059 } else {
2060 if dry_run {
2061 rewired_edge_ids.insert(edge.id);
2062 continue;
2063 }
2064 let changed = conn.execute(
2065 "UPDATE graph_edges SET \
2066 source_id = ?1, target_id = ?2, updated_at = ?3 \
2067 WHERE namespace = ?4 AND id = ?5",
2068 rusqlite::params![
2069 new_src.to_string(),
2070 new_tgt.to_string(),
2071 now_ts,
2072 &edge.namespace,
2073 edge.id.to_string(),
2074 ],
2075 )?;
2076 if changed > 0 {
2077 rewired_edge_ids.insert(edge.id);
2078 }
2079 }
2080 }
2081 let edges_rewired = rewired_edge_ids.len();
2082
2083 if !dry_run {
2084 conn.execute(
2088 "UPDATE entities SET \
2089 name = ?1, description = ?2, properties = ?3, tags = ?4, \
2090 updated_at = ?5, merged_into = NULL, merge_event_id = NULL \
2091 WHERE namespace = ?6 AND id = ?7",
2092 rusqlite::params![
2093 &merged_name,
2094 &merged_description,
2095 &props_str,
2096 &tags_json,
2097 now,
2098 &namespace,
2099 &into_str,
2100 ],
2101 )?;
2102
2103 let fts_body = match &merged_description {
2107 Some(d) if !d.is_empty() => format!("{} {}", merged_name, d),
2108 _ => merged_name.clone(),
2109 };
2110 let kind_str = SubstrateKind::Entity.to_string();
2111
2112 conn.execute(
2113 &format!(
2114 "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2115 fts_table
2116 ),
2117 rusqlite::params![&namespace, &into_str],
2118 )?;
2119 conn.execute(
2120 &format!(
2121 "INSERT INTO {} \
2122 (subject_id, kind, title, body, tags, namespace, metadata, updated_at) \
2123 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2124 fts_table
2125 ),
2126 rusqlite::params![
2127 &into_str,
2128 &kind_str,
2129 &merged_name,
2130 &fts_body,
2131 &tags_json,
2132 &namespace,
2133 &props_str,
2134 now,
2135 ],
2136 )?;
2137
2138 conn.execute(
2139 &format!(
2140 "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2141 fts_table
2142 ),
2143 rusqlite::params![&namespace, &from_str],
2144 )?;
2145
2146 khive_db::stores::vectors::delete_subject_from_vector_tables(
2147 conn,
2148 &vec_tables,
2149 from_id,
2150 &namespace,
2151 )?;
2152
2153 let merge_event_id = Uuid::new_v4();
2154 conn.execute(
2155 "UPDATE entities \
2156 SET deleted_at = ?1, merged_into = ?2, merge_event_id = ?3, updated_at = ?1 \
2157 WHERE namespace = ?4 AND id = ?5 AND deleted_at IS NULL",
2158 rusqlite::params![
2159 now,
2160 into_str,
2161 merge_event_id.to_string(),
2162 &namespace,
2163 &from_str,
2164 ],
2165 )?;
2166 }
2167
2168 let updated_entity = Entity {
2169 id: into_id,
2170 namespace,
2171 kind: into_entity.kind,
2172 entity_type: into_entity.entity_type,
2173 name: merged_name,
2174 description: merged_description,
2175 properties: merged_props,
2176 tags: merged_tags,
2177 created_at: into_entity.created_at,
2178 updated_at: now,
2179 deleted_at: into_entity.deleted_at,
2180 merged_into: None,
2181 merge_event_id: None,
2182 content_ref: into_entity.content_ref,
2183 };
2184
2185 Ok((
2186 MergeSummary {
2187 kept_id: into_id,
2188 removed_id: from_id,
2189 edges_rewired,
2190 edges_contract_skipped,
2191 edge_conflict_preimages,
2192 properties_merged,
2193 tags_unioned,
2194 content_appended,
2195 dry_run,
2196 embedding_truncation: Default::default(),
2197 },
2198 updated_entity,
2199 ))
2200}
2201
2202fn read_merge_note(
2208 conn: &rusqlite::Connection,
2209 id: Uuid,
2210 namespace: &str,
2211) -> Result<khive_storage::note::Note, SqliteError> {
2212 use khive_storage::note::Note;
2213 let id_str = id.to_string();
2214 let mut stmt = conn.prepare(
2215 "SELECT id, namespace, kind, status, name, content, salience, decay_factor, \
2216 expires_at, properties, created_at, updated_at, deleted_at \
2217 FROM notes WHERE id = ?1 AND deleted_at IS NULL",
2218 )?;
2219 let mut rows = stmt.query(rusqlite::params![id_str])?;
2220 let row = rows
2221 .next()?
2222 .ok_or_else(|| SqliteError::InvalidData(format!("note {id} not found")))?;
2223
2224 let id_s: String = row.get(0)?;
2225 let ns: String = row.get(1)?;
2226 let kind: String = row.get(2)?;
2227 let status: String = row.get(3)?;
2228 let name: Option<String> = row.get(4)?;
2229 let content: String = row.get(5)?;
2230 let salience: Option<f64> = row.get(6)?;
2231 let decay_factor: Option<f64> = row.get(7)?;
2232 let expires_at: Option<i64> = row.get(8)?;
2233 let properties_str: Option<String> = row.get(9)?;
2234 let created_at: i64 = row.get(10)?;
2235 let updated_at: i64 = row.get(11)?;
2236 let deleted_at: Option<i64> = row.get(12)?;
2237
2238 if ns != namespace {
2239 return Err(SqliteError::InvalidData(format!(
2240 "note {id} belongs to namespace '{ns}', not '{namespace}'"
2241 )));
2242 }
2243
2244 let note_id = Uuid::parse_str(&id_s).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
2245 let properties: Option<serde_json::Value> = properties_str
2246 .map(|s| serde_json::from_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string())))
2247 .transpose()?;
2248
2249 Ok(Note {
2250 id: note_id,
2251 namespace: ns,
2252 kind,
2253 status,
2254 name,
2255 content,
2256 salience,
2257 decay_factor,
2258 expires_at,
2259 properties,
2260 created_at,
2261 updated_at,
2262 deleted_at,
2263 })
2264}
2265
2266fn max_option_f64(a: Option<f64>, b: Option<f64>) -> Option<f64> {
2267 match (a, b) {
2268 (Some(x), Some(y)) => Some(x.max(y)),
2269 (Some(x), None) => Some(x),
2270 (None, Some(y)) => Some(y),
2271 (None, None) => None,
2272 }
2273}
2274
2275fn append_merge_history(props: Option<Value>, entry: Value) -> Result<Option<Value>, SqliteError> {
2276 use serde_json::{json, Map};
2277 let mut obj: Map<String, Value> = match props {
2278 Some(Value::Object(m)) => m,
2279 Some(other) => {
2280 let mut m = Map::new();
2281 m.insert("_value".into(), other);
2282 m
2283 }
2284 None => Map::new(),
2285 };
2286 let history = obj
2287 .entry("_merge_history".to_string())
2288 .or_insert_with(|| json!([]));
2289 if let Value::Array(arr) = history {
2290 arr.push(entry);
2291 }
2292 Ok(Some(Value::Object(obj)))
2293}
2294
2295#[allow(clippy::too_many_arguments)]
2305fn merge_note_sql(
2306 conn: &rusqlite::Connection,
2307 namespace: String,
2308 fts_table: String,
2309 vec_tables: Vec<String>,
2310 into_id: Uuid,
2311 from_id: Uuid,
2312 strategy: EntityDedupMergePolicy,
2313 content_strategy: ContentMergeStrategy,
2314 dry_run: bool,
2315 pack_rules: Vec<EdgeEndpointRule>,
2316) -> Result<(MergeSummary, khive_storage::note::Note), SqliteError> {
2317 let into_note = read_merge_note(conn, into_id, &namespace)?;
2318 let from_note = read_merge_note(conn, from_id, &namespace)?;
2319
2320 if into_note.kind != from_note.kind {
2321 return Err(SqliteError::InvalidData(format!(
2322 "cannot merge notes of different kinds: {} vs {}",
2323 into_note.kind, from_note.kind
2324 )));
2325 }
2326
2327 let now = chrono::Utc::now().timestamp_micros();
2328 let into_str = into_id.to_string();
2329 let from_str = from_id.to_string();
2330
2331 let parse_id =
2333 |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
2334
2335 let mut outbound: Vec<EdgeRow> = Vec::new();
2338 {
2339 let mut stmt = conn.prepare(
2340 "SELECT id, namespace, source_id, target_id, relation, weight, created_at, updated_at, deleted_at, target_backend, metadata \
2341 FROM graph_edges WHERE source_id = ?1",
2342 )?;
2343 let mut rows = stmt.query(rusqlite::params![&from_str])?;
2344 while let Some(row) = rows.next()? {
2345 outbound.push(EdgeRow {
2346 id: parse_id(row.get(0)?)?,
2347 namespace: row.get(1)?,
2348 source_id: parse_id(row.get(2)?)?,
2349 target_id: parse_id(row.get(3)?)?,
2350 relation: row.get(4)?,
2351 weight: row.get(5)?,
2352 created_at: row.get(6)?,
2353 updated_at: row.get(7)?,
2354 deleted_at: row.get(8)?,
2355 target_backend: row.get(9)?,
2356 metadata: row.get(10)?,
2357 });
2358 }
2359 }
2360 let mut inbound: Vec<EdgeRow> = Vec::new();
2361 {
2362 let mut stmt = conn.prepare(
2363 "SELECT id, namespace, source_id, target_id, relation, weight, created_at, updated_at, deleted_at, target_backend, metadata \
2364 FROM graph_edges WHERE target_id = ?1",
2365 )?;
2366 let mut rows = stmt.query(rusqlite::params![&from_str])?;
2367 while let Some(row) = rows.next()? {
2368 inbound.push(EdgeRow {
2369 id: parse_id(row.get(0)?)?,
2370 namespace: row.get(1)?,
2371 source_id: parse_id(row.get(2)?)?,
2372 target_id: parse_id(row.get(3)?)?,
2373 relation: row.get(4)?,
2374 weight: row.get(5)?,
2375 created_at: row.get(6)?,
2376 updated_at: row.get(7)?,
2377 deleted_at: row.get(8)?,
2378 target_backend: row.get(9)?,
2379 metadata: row.get(10)?,
2380 });
2381 }
2382 }
2383 let mut seen: HashSet<Uuid> = HashSet::new();
2384 let mut all_edges: Vec<EdgeRow> = Vec::new();
2385 for edge in outbound.into_iter().chain(inbound) {
2386 if seen.insert(edge.id) {
2387 all_edges.push(edge);
2388 }
2389 }
2390 let original_edges: HashMap<Uuid, EdgeRow> = all_edges
2391 .iter()
2392 .map(|edge| (edge.id, edge.clone()))
2393 .collect();
2394
2395 let (merged_content, content_appended) = match content_strategy {
2397 ContentMergeStrategy::Append => {
2398 if from_note.content.is_empty() {
2399 (into_note.content.clone(), false)
2400 } else {
2401 (
2402 format!("{}\n\n---\n\n{}", into_note.content, from_note.content),
2403 true,
2404 )
2405 }
2406 }
2407 ContentMergeStrategy::PreferInto => (into_note.content.clone(), false),
2408 ContentMergeStrategy::PreferFrom => (from_note.content.clone(), false),
2409 };
2410
2411 let merged_name = match strategy {
2412 EntityDedupMergePolicy::PreferFrom => from_note.name.clone().or(into_note.name.clone()),
2413 _ => into_note.name.clone().or(from_note.name.clone()),
2414 };
2415
2416 let (merged_props, properties_merged) =
2417 merge_properties(&into_note.properties, &from_note.properties, strategy);
2418
2419 let merge_history_entry = serde_json::json!({
2420 "merged_from": from_id.to_string(),
2421 "merged_at": now,
2422 "strategy": format!("{:?}", strategy),
2423 "content_strategy": format!("{:?}", content_strategy),
2424 });
2425 let merged_props = append_merge_history(merged_props, merge_history_entry)?;
2426
2427 let merged_salience = max_option_f64(into_note.salience, from_note.salience);
2428 let merged_expires_at = match (into_note.expires_at, from_note.expires_at) {
2429 (Some(a), Some(b)) => Some(a.max(b)),
2430 (Some(a), None) => Some(a),
2431 (None, Some(b)) => Some(b),
2432 (None, None) => None,
2433 };
2434
2435 let props_str = merged_props
2436 .as_ref()
2437 .map(|v| serde_json::to_string(v).unwrap_or_default());
2438
2439 let mut rewired_edge_ids = HashSet::new();
2442 let mut edges_contract_skipped = 0usize;
2443 let mut edge_conflict_preimages = Vec::new();
2444 let mut conflict_deleted_edge_ids = HashSet::new();
2445 {
2446 for edge in all_edges {
2447 if conflict_deleted_edge_ids.contains(&edge.id) {
2448 continue;
2449 }
2450 let raw_src = if edge.source_id == from_id {
2451 into_id
2452 } else {
2453 edge.source_id
2454 };
2455 let raw_tgt = if edge.target_id == from_id {
2456 into_id
2457 } else {
2458 edge.target_id
2459 };
2460 let relation_typed = edge.relation.parse::<EdgeRelation>().ok();
2461 let (new_src, new_tgt) = match relation_typed {
2463 Some(rel) => canonical_edge_endpoints(rel, raw_src, raw_tgt),
2464 None => (raw_src, raw_tgt),
2465 };
2466 if new_src == new_tgt {
2467 if !dry_run {
2468 conn.execute(
2469 "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
2470 rusqlite::params![&edge.namespace, edge.id.to_string()],
2471 )?;
2472 }
2473 continue;
2474 }
2475
2476 let contract_ok = match relation_typed {
2481 Some(EdgeRelation::Annotates) => true,
2485 Some(rel) => {
2486 let src_info = if new_src == into_id {
2487 Some(("note", into_note.kind.clone(), None))
2488 } else {
2489 resolve_merge_edge_endpoint(conn, new_src)?
2490 };
2491 let tgt_info = if new_tgt == into_id {
2492 Some(("note", into_note.kind.clone(), None))
2493 } else {
2494 resolve_merge_edge_endpoint(conn, new_tgt)?
2495 };
2496 match (src_info, tgt_info) {
2497 (
2498 Some((src_sub, src_kind, src_type)),
2499 Some((tgt_sub, tgt_kind, tgt_type)),
2500 ) => merge_rewire_endpoint_contract_allows(
2501 &pack_rules,
2502 rel,
2503 src_sub,
2504 &src_kind,
2505 src_type.as_deref(),
2506 tgt_sub,
2507 &tgt_kind,
2508 tgt_type.as_deref(),
2509 ),
2510 _ => false,
2511 }
2512 }
2513 None => true,
2514 };
2515 if !contract_ok {
2516 if !dry_run {
2517 conn.execute(
2518 "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
2519 rusqlite::params![&edge.namespace, edge.id.to_string()],
2520 )?;
2521 }
2522 tracing::warn!(
2523 edge_id = %edge.id,
2524 source = %new_src,
2525 target = %new_tgt,
2526 relation = %edge.relation,
2527 "merge_note: dropping rewired edge — endpoint contract violation post-merge"
2528 );
2529 edges_contract_skipped += 1;
2530 continue;
2531 }
2532
2533 let now_ts = chrono::Utc::now().timestamp_micros();
2534 let conflict_id: Option<String> = {
2535 let conflict_src = new_src.to_string();
2536 let conflict_tgt = new_tgt.to_string();
2537 conn.query_row(
2538 khive_db::stores::graph::EDGE_SYMMETRIC_CONFLICT_PROBE_SQL,
2539 rusqlite::params![
2540 &edge.namespace,
2541 &conflict_src,
2542 &conflict_tgt,
2543 &edge.relation,
2544 edge.id.to_string(),
2545 ],
2546 |row| row.get(0),
2547 )
2548 .optional()
2549 .map_err(SqliteError::Rusqlite)?
2550 };
2551
2552 if let Some(conflict_id) = conflict_id {
2553 let surviving_edge_id = Uuid::parse_str(&conflict_id)
2559 .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
2560 let incident_edge_preimages =
2561 collect_conflict_incident_edge_preimages(conn, edge.id, &original_edges)?;
2562 for incident in &incident_edge_preimages {
2563 conflict_deleted_edge_ids.insert(incident.id);
2564 rewired_edge_ids.remove(&incident.id);
2565 }
2566 conflict_deleted_edge_ids.insert(edge.id);
2567 rewired_edge_ids.insert(edge.id);
2568
2569 if !dry_run {
2570 delete_conflict_incident_edges(conn, &incident_edge_preimages)?;
2571 conn.execute(
2572 khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
2573 rusqlite::params![&edge.namespace, edge.id.to_string()],
2574 )?;
2575 }
2576 edge_conflict_preimages.push(MergeEdgeConflictPreimage {
2577 surviving_edge_id,
2578 dropped_edge: edge_row_preimage(&edge)?,
2579 incident_edge_preimages,
2580 });
2581 } else {
2582 if dry_run {
2583 rewired_edge_ids.insert(edge.id);
2584 continue;
2585 }
2586 let changed = conn.execute(
2587 "UPDATE graph_edges SET \
2588 source_id = ?1, target_id = ?2, updated_at = ?3 \
2589 WHERE namespace = ?4 AND id = ?5",
2590 rusqlite::params![
2591 new_src.to_string(),
2592 new_tgt.to_string(),
2593 now_ts,
2594 &edge.namespace,
2595 edge.id.to_string(),
2596 ],
2597 )?;
2598 if changed > 0 {
2599 rewired_edge_ids.insert(edge.id);
2600 }
2601 }
2602 }
2603 }
2604 let edges_rewired = rewired_edge_ids.len();
2605
2606 if !dry_run {
2607 conn.prepare_cached(khive_db::stores::note::NOTE_UPSERT_SQL)?
2608 .execute(rusqlite::params![
2609 &into_str,
2610 &namespace,
2611 &into_note.kind,
2612 &into_note.status,
2613 &merged_name,
2614 &merged_content,
2615 merged_salience,
2616 into_note.decay_factor,
2617 merged_expires_at,
2618 &props_str,
2619 into_note.created_at,
2620 now,
2621 into_note.deleted_at,
2622 ])?;
2623
2624 conn.execute(
2625 &format!(
2626 "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2627 fts_table
2628 ),
2629 rusqlite::params![&namespace, &into_str],
2630 )?;
2631 let fts_merged = {
2636 let mut merged_note = Note::new(&namespace, &*into_note.kind, &*merged_content);
2637 merged_note.id = into_id;
2638 merged_note.name = merged_name.clone();
2639 merged_note.properties = merged_props.clone();
2640 merged_note.updated_at = now;
2641 note_fts_scalars(&merged_note)
2642 };
2643 conn.execute(
2644 &format!(
2645 "INSERT INTO {} \
2646 (subject_id, kind, title, body, tags, namespace, metadata, updated_at) \
2647 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2648 fts_table
2649 ),
2650 rusqlite::params![
2651 &into_str,
2652 SubstrateKind::Note.to_string(),
2653 &fts_merged.title,
2654 &fts_merged.body,
2655 &fts_merged.tags,
2656 &namespace,
2657 &fts_merged.metadata,
2658 fts_merged.updated_at_micros,
2659 ],
2660 )?;
2661
2662 conn.execute(
2663 &format!(
2664 "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2665 fts_table
2666 ),
2667 rusqlite::params![&namespace, &from_str],
2668 )?;
2669
2670 khive_db::stores::vectors::delete_subject_from_vector_tables(
2671 conn,
2672 &vec_tables,
2673 from_id,
2674 &namespace,
2675 )?;
2676
2677 conn.execute(
2678 "UPDATE notes SET status = 'deleted', deleted_at = ?1, updated_at = ?1 \
2679 WHERE namespace = ?2 AND id = ?3 AND deleted_at IS NULL",
2680 rusqlite::params![now, &namespace, &from_str],
2681 )?;
2682 }
2683
2684 let updated_note = khive_storage::note::Note {
2685 id: into_id,
2686 namespace: namespace.clone(),
2687 kind: into_note.kind.clone(),
2688 status: into_note.status.clone(),
2689 name: merged_name,
2690 content: merged_content,
2691 salience: merged_salience,
2692 decay_factor: into_note.decay_factor,
2693 expires_at: merged_expires_at,
2694 properties: merged_props,
2695 created_at: into_note.created_at,
2696 updated_at: now,
2697 deleted_at: into_note.deleted_at,
2698 };
2699
2700 Ok((
2701 MergeSummary {
2702 kept_id: into_id,
2703 removed_id: from_id,
2704 edges_rewired,
2705 edges_contract_skipped,
2706 edge_conflict_preimages,
2707 properties_merged,
2708 tags_unioned: 0,
2709 content_appended,
2710 dry_run,
2711 embedding_truncation: Default::default(),
2712 },
2713 updated_note,
2714 ))
2715}
2716
2717pub(crate) fn merge_string_field(
2724 into: &str,
2725 from: &str,
2726 strategy: EntityDedupMergePolicy,
2727) -> String {
2728 match strategy {
2729 EntityDedupMergePolicy::PreferInto | EntityDedupMergePolicy::Union => into.to_string(),
2730 EntityDedupMergePolicy::PreferFrom => from.to_string(),
2731 }
2732}
2733
2734pub(crate) fn merge_properties(
2739 into: &Option<Value>,
2740 from: &Option<Value>,
2741 strategy: EntityDedupMergePolicy,
2742) -> (Option<Value>, usize) {
2743 match (into, from) {
2744 (None, None) => (None, 0),
2745 (Some(a), None) => (Some(a.clone()), 0),
2746 (None, Some(b)) => {
2747 let count = if let Value::Object(m) = b { m.len() } else { 1 };
2748 (Some(b.clone()), count)
2749 }
2750 (Some(into_val), Some(from_val)) => {
2751 let (merged, added) = merge_json(into_val, from_val, strategy);
2752 (Some(merged), added)
2753 }
2754 }
2755}
2756
2757fn merge_json(into: &Value, from: &Value, strategy: EntityDedupMergePolicy) -> (Value, usize) {
2759 match (into, from, strategy) {
2760 (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::Union) => {
2761 let mut result = a.clone();
2762 let mut added = 0usize;
2763 for (k, v_from) in b {
2764 if let Some(v_into) = a.get(k) {
2765 let (merged, sub_added) =
2766 merge_json(v_into, v_from, EntityDedupMergePolicy::Union);
2767 result.insert(k.clone(), merged);
2768 added += sub_added;
2769 } else {
2770 result.insert(k.clone(), v_from.clone());
2771 added += 1;
2772 }
2773 }
2774 (Value::Object(result), added)
2775 }
2776 (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::PreferInto) => {
2777 let mut result = a.clone();
2778 let mut added = 0usize;
2779 for (k, v) in b {
2780 if !a.contains_key(k) {
2781 result.insert(k.clone(), v.clone());
2782 added += 1;
2783 }
2784 }
2785 (Value::Object(result), added)
2786 }
2787 (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::PreferFrom) => {
2788 let mut result = a.clone();
2789 let mut added = 0usize;
2790 for (k, v) in b {
2791 result.insert(k.clone(), v.clone());
2792 if !a.contains_key(k) {
2793 added += 1;
2794 }
2795 }
2796 (Value::Object(result), added)
2797 }
2798 (_into_val, from_val, EntityDedupMergePolicy::PreferFrom) => (from_val.clone(), 1),
2800 _ => (into.clone(), 0),
2801 }
2802}
2803
2804pub(crate) fn union_tags(into: &[String], from: &[String]) -> (Vec<String>, usize) {
2807 let mut seen: HashSet<&str> = into.iter().map(|s| s.as_str()).collect();
2808 let mut result: Vec<String> = into.to_vec();
2809 let mut added = 0usize;
2810 for tag in from {
2811 if seen.insert(tag.as_str()) {
2812 result.push(tag.clone());
2813 added += 1;
2814 }
2815 }
2816 (result, added)
2817}
2818
2819#[cfg(test)]
2828mod tests {
2829 use super::*;
2830 use crate::runtime::{KhiveRuntime, NamespaceToken};
2831 use khive_storage::types::{Direction, TextFilter, TextQueryMode, TextSearchRequest};
2832 use khive_types::EndpointKind;
2833
2834 fn rt() -> KhiveRuntime {
2835 KhiveRuntime::memory().unwrap()
2836 }
2837
2838 fn secret_shaped_reason() -> String {
2839 const ALPHANUMERIC: &[u8] =
2840 b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
2841 let candidate: String = (0..48)
2842 .map(|index| char::from(ALPHANUMERIC[(index * 17 + 11) % ALPHANUMERIC.len()]))
2843 .collect();
2844 format!("secret value: {candidate}")
2845 }
2846
2847 async fn restore_edge_preimage(
2848 rt: &KhiveRuntime,
2849 token: &NamespaceToken,
2850 preimage: &MergeEdgePreimage,
2851 ) {
2852 let edge = khive_storage::types::Edge {
2853 id: preimage.id.into(),
2854 namespace: preimage.namespace.clone(),
2855 source_id: preimage.source_id,
2856 target_id: preimage.target_id,
2857 relation: preimage.relation.parse().expect("stored relation"),
2858 weight: preimage.weight,
2859 created_at: chrono::DateTime::from_timestamp_micros(preimage.created_at)
2860 .expect("stored created_at"),
2861 updated_at: chrono::DateTime::from_timestamp_micros(preimage.updated_at)
2862 .expect("stored updated_at"),
2863 deleted_at: preimage.deleted_at.map(|value| {
2864 chrono::DateTime::from_timestamp_micros(value).expect("stored deleted_at")
2865 }),
2866 metadata: preimage.metadata.clone(),
2867 target_backend: preimage.target_backend.clone(),
2868 };
2869 rt.graph(token)
2870 .expect("graph store")
2871 .upsert_edge(edge)
2872 .await
2873 .expect("restore edge preimage");
2874 }
2875
2876 fn assert_edge_matches_preimage(
2877 edge: &khive_storage::types::Edge,
2878 preimage: &MergeEdgePreimage,
2879 ) {
2880 assert_eq!(Uuid::from(edge.id), preimage.id);
2881 assert_eq!(edge.namespace, preimage.namespace);
2882 assert_eq!(edge.source_id, preimage.source_id);
2883 assert_eq!(edge.target_id, preimage.target_id);
2884 assert_eq!(edge.relation.to_string(), preimage.relation);
2885 assert_eq!(edge.weight, preimage.weight);
2886 assert_eq!(edge.created_at.timestamp_micros(), preimage.created_at);
2887 assert_eq!(edge.updated_at.timestamp_micros(), preimage.updated_at);
2888 assert_eq!(
2889 edge.deleted_at.map(|value| value.timestamp_micros()),
2890 preimage.deleted_at
2891 );
2892 assert_eq!(edge.metadata, preimage.metadata);
2893 assert_eq!(edge.target_backend, preimage.target_backend);
2894 }
2895
2896 async fn fts_hit(rt: &KhiveRuntime, token: &NamespaceToken, query: &str) -> Vec<Uuid> {
2898 let ns = token.namespace().as_str().to_string();
2899 rt.text(token)
2900 .unwrap()
2901 .search(TextSearchRequest {
2902 query: query.to_string(),
2903 mode: TextQueryMode::Plain,
2904 filter: Some(TextFilter {
2905 namespaces: vec![ns],
2906 ..Default::default()
2907 }),
2908 top_k: 50,
2909 snippet_chars: 100,
2910 })
2911 .await
2912 .unwrap()
2913 .into_iter()
2914 .map(|h| h.subject_id)
2915 .collect()
2916 }
2917
2918 #[tokio::test]
2919 async fn update_entity_patch_changes_only_specified_fields() {
2920 let rt = rt();
2921 let tok = NamespaceToken::local();
2922 let entity = rt
2923 .create_entity(
2924 &tok,
2925 "concept",
2926 None,
2927 "OriginalName",
2928 Some("orig desc"),
2929 Some(serde_json::json!({"k":"v"})),
2930 vec![],
2931 )
2932 .await
2933 .unwrap();
2934
2935 let updated = rt
2936 .update_entity(
2937 &tok,
2938 entity.id,
2939 EntityPatch {
2940 description: Some(Some("new desc".to_string())),
2941 ..Default::default()
2942 },
2943 )
2944 .await
2945 .unwrap();
2946
2947 assert_eq!(updated.name, "OriginalName");
2948 assert_eq!(updated.description.as_deref(), Some("new desc"));
2949 assert_eq!(updated.properties, Some(serde_json::json!({"k":"v"})));
2950 }
2951
2952 #[tokio::test]
2953 async fn update_entity_clear_description_with_some_none() {
2954 let rt = rt();
2955 let tok = NamespaceToken::local();
2956 let entity = rt
2957 .create_entity(
2958 &tok,
2959 "concept",
2960 None,
2961 "ClearDesc",
2962 Some("has description"),
2963 None,
2964 vec![],
2965 )
2966 .await
2967 .unwrap();
2968
2969 let updated = rt
2970 .update_entity(
2971 &tok,
2972 entity.id,
2973 EntityPatch {
2974 description: Some(None),
2975 ..Default::default()
2976 },
2977 )
2978 .await
2979 .unwrap();
2980
2981 assert!(
2982 updated.description.is_none(),
2983 "description should be cleared"
2984 );
2985 }
2986
2987 #[tokio::test]
2988 async fn update_entity_reindexes_when_name_changes() {
2989 let rt = rt();
2990 let tok = NamespaceToken::local();
2991 let entity = rt
2992 .create_entity(&tok, "concept", None, "OldName", None, None, vec![])
2993 .await
2994 .unwrap();
2995
2996 let hits_before = fts_hit(&rt, &tok, "OldName").await;
2997 assert!(
2998 hits_before.contains(&entity.id),
2999 "entity should be findable by old name"
3000 );
3001
3002 rt.update_entity(
3003 &tok,
3004 entity.id,
3005 EntityPatch {
3006 name: Some("NewName".to_string()),
3007 ..Default::default()
3008 },
3009 )
3010 .await
3011 .unwrap();
3012
3013 let hits_old = fts_hit(&rt, &tok, "OldName").await;
3014 let hits_new = fts_hit(&rt, &tok, "NewName").await;
3015
3016 assert!(
3017 !hits_old.contains(&entity.id),
3018 "old name should no longer match after rename"
3019 );
3020 assert!(
3021 hits_new.contains(&entity.id),
3022 "new name should be findable after rename"
3023 );
3024 }
3025
3026 #[tokio::test]
3027 async fn update_entity_properties_merges_preserving_existing_keys() {
3028 let rt = rt();
3029 let tok = NamespaceToken::local();
3030 let entity = rt
3031 .create_entity(
3032 &tok,
3033 "concept",
3034 None,
3035 "MergeProps",
3036 None,
3037 Some(serde_json::json!({
3038 "domain": "inference",
3039 "repo": "lattice",
3040 "status": "researched",
3041 })),
3042 vec![],
3043 )
3044 .await
3045 .unwrap();
3046
3047 let updated = rt
3048 .update_entity(
3049 &tok,
3050 entity.id,
3051 EntityPatch {
3052 properties: Some(serde_json::json!({"status": "implemented"})),
3053 ..Default::default()
3054 },
3055 )
3056 .await
3057 .unwrap();
3058
3059 let props = updated.properties.expect("properties should remain set");
3060 assert_eq!(props["domain"], "inference", "domain key must be preserved");
3061 assert_eq!(props["repo"], "lattice", "repo key must be preserved");
3062 assert_eq!(
3063 props["status"], "implemented",
3064 "status key must be updated by patch"
3065 );
3066 }
3067
3068 #[tokio::test]
3069 async fn update_entity_skips_reindex_when_only_properties_change() {
3070 let rt = rt();
3071 let tok = NamespaceToken::local();
3072 let entity = rt
3073 .create_entity(&tok, "concept", None, "StableIndexed", None, None, vec![])
3074 .await
3075 .unwrap();
3076
3077 let hits_before = fts_hit(&rt, &tok, "StableIndexed").await;
3078 assert!(hits_before.contains(&entity.id));
3079
3080 rt.update_entity(
3081 &tok,
3082 entity.id,
3083 EntityPatch {
3084 properties: Some(serde_json::json!({"new": "prop"})),
3085 ..Default::default()
3086 },
3087 )
3088 .await
3089 .unwrap();
3090
3091 let hits_after = fts_hit(&rt, &tok, "StableIndexed").await;
3092 assert!(
3093 hits_after.contains(&entity.id),
3094 "still findable after props-only patch"
3095 );
3096 }
3097
3098 #[tokio::test]
3099 async fn merge_entity_rewires_edges() {
3100 let rt = rt();
3101 let tok = NamespaceToken::local();
3102 let a = rt
3103 .create_entity(&tok, "concept", None, "A", None, None, vec![])
3104 .await
3105 .unwrap();
3106 let b = rt
3107 .create_entity(&tok, "concept", None, "B", None, None, vec![])
3108 .await
3109 .unwrap();
3110 let c = rt
3111 .create_entity(&tok, "concept", None, "C", None, None, vec![])
3112 .await
3113 .unwrap();
3114 let d = rt
3115 .create_entity(&tok, "concept", None, "D", None, None, vec![])
3116 .await
3117 .unwrap();
3118
3119 rt.link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
3121 .await
3122 .unwrap();
3123 rt.link(&tok, c.id, b.id, EdgeRelation::Extends, 1.0, None)
3124 .await
3125 .unwrap();
3126
3127 let summary = rt
3128 .merge_entity_with_reason(
3129 &tok,
3130 d.id,
3131 b.id,
3132 EntityDedupMergePolicy::PreferInto,
3133 ContentMergeStrategy::Append,
3134 false,
3135 None,
3136 )
3137 .await
3138 .unwrap();
3139
3140 assert_eq!(summary.kept_id, d.id);
3141 assert_eq!(summary.removed_id, b.id);
3142 assert_eq!(summary.edges_rewired, 2);
3143
3144 let a_neighbors = rt
3145 .neighbors(&tok, a.id, Direction::Out, None, None)
3146 .await
3147 .unwrap();
3148 assert_eq!(a_neighbors.len(), 1);
3149 assert_eq!(a_neighbors[0].node_id, d.id);
3150
3151 let c_neighbors = rt
3152 .neighbors(&tok, c.id, Direction::Out, None, None)
3153 .await
3154 .unwrap();
3155 assert_eq!(c_neighbors.len(), 1);
3156 assert_eq!(c_neighbors[0].node_id, d.id);
3157 }
3158
3159 #[tokio::test]
3164 async fn merge_entity_rewires_edges_from_other_namespaces() {
3165 use crate::Namespace;
3166
3167 let rt = rt();
3168 let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
3169 let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
3170
3171 let into_a = rt
3172 .create_entity(&ns_a, "concept", None, "Into A", None, None, vec![])
3173 .await
3174 .unwrap();
3175 let from_a = rt
3176 .create_entity(&ns_a, "concept", None, "From A", None, None, vec![])
3177 .await
3178 .unwrap();
3179 let foreign_b = rt
3180 .create_entity(&ns_b, "concept", None, "Foreign B", None, None, vec![])
3181 .await
3182 .unwrap();
3183
3184 rt.link(
3187 &ns_b,
3188 foreign_b.id,
3189 from_a.id,
3190 EdgeRelation::Extends,
3191 1.0,
3192 None,
3193 )
3194 .await
3195 .unwrap();
3196
3197 let summary = rt
3198 .merge_entity_with_reason(
3199 &ns_a,
3200 into_a.id,
3201 from_a.id,
3202 EntityDedupMergePolicy::PreferInto,
3203 ContentMergeStrategy::Append,
3204 false,
3205 None,
3206 )
3207 .await
3208 .unwrap();
3209
3210 assert_eq!(
3211 summary.edges_rewired, 1,
3212 "the ns_b-stamped edge incident to from_id must be discovered and rewired, not missed"
3213 );
3214
3215 let foreign_neighbors = rt
3216 .neighbors(&ns_b, foreign_b.id, Direction::Out, None, None)
3217 .await
3218 .unwrap();
3219 assert_eq!(
3220 foreign_neighbors.len(),
3221 1,
3222 "cross-namespace edge must survive the merge, rewired to point at into_id"
3223 );
3224 assert_eq!(foreign_neighbors[0].node_id, into_a.id);
3225 }
3226
3227 #[tokio::test]
3234 async fn merge_entity_drops_edge_violating_endpoint_contract_after_rewire() {
3235 let rt = rt();
3236 let tok = NamespaceToken::local();
3237
3238 rt.install_edge_rules(vec![EdgeEndpointRule {
3241 relation: EdgeRelation::DependsOn,
3242 source: EndpointKind::EntityOfType {
3243 kind: "concept",
3244 entity_type: "theorem",
3245 },
3246 target: EndpointKind::EntityOfType {
3247 kind: "concept",
3248 entity_type: "definition",
3249 },
3250 }]);
3251
3252 let def_entity = rt
3253 .create_entity(
3254 &tok,
3255 "concept",
3256 Some("definition"),
3257 "Def",
3258 None,
3259 None,
3260 vec![],
3261 )
3262 .await
3263 .unwrap();
3264 let from_theorem = rt
3265 .create_entity(
3266 &tok,
3267 "concept",
3268 Some("theorem"),
3269 "FromTheorem",
3270 None,
3271 None,
3272 vec![],
3273 )
3274 .await
3275 .unwrap();
3276 let into_lemma = rt
3280 .create_entity(
3281 &tok,
3282 "concept",
3283 Some("lemma"),
3284 "IntoLemma",
3285 None,
3286 None,
3287 vec![],
3288 )
3289 .await
3290 .unwrap();
3291
3292 rt.link(
3293 &tok,
3294 from_theorem.id,
3295 def_entity.id,
3296 EdgeRelation::DependsOn,
3297 1.0,
3298 None,
3299 )
3300 .await
3301 .unwrap();
3302
3303 let summary = rt
3304 .merge_entity_with_reason(
3305 &tok,
3306 into_lemma.id,
3307 from_theorem.id,
3308 EntityDedupMergePolicy::PreferInto,
3309 ContentMergeStrategy::Append,
3310 false,
3311 None,
3312 )
3313 .await
3314 .unwrap();
3315
3316 assert_eq!(
3317 summary.edges_rewired, 0,
3318 "the contract-violating rewire must not be counted as rewired"
3319 );
3320 assert_eq!(
3321 summary.edges_contract_skipped, 1,
3322 "the depends_on edge must be dropped, not silently rewritten past the endpoint contract"
3323 );
3324
3325 let def_neighbors = rt
3326 .neighbors(&tok, def_entity.id, Direction::In, None, None)
3327 .await
3328 .unwrap();
3329 assert!(
3330 def_neighbors.is_empty(),
3331 "no contract-violating depends_on edge should survive onto into_lemma; got {def_neighbors:?}"
3332 );
3333 }
3334
3335 #[tokio::test]
3338 async fn merge_entity_dry_run_predicts_contract_skip_without_writing() {
3339 let rt = rt();
3340 let tok = NamespaceToken::local();
3341
3342 rt.install_edge_rules(vec![EdgeEndpointRule {
3343 relation: EdgeRelation::DependsOn,
3344 source: EndpointKind::EntityOfType {
3345 kind: "concept",
3346 entity_type: "theorem",
3347 },
3348 target: EndpointKind::EntityOfType {
3349 kind: "concept",
3350 entity_type: "definition",
3351 },
3352 }]);
3353
3354 let def_entity = rt
3355 .create_entity(
3356 &tok,
3357 "concept",
3358 Some("definition"),
3359 "Def",
3360 None,
3361 None,
3362 vec![],
3363 )
3364 .await
3365 .unwrap();
3366 let from_theorem = rt
3367 .create_entity(
3368 &tok,
3369 "concept",
3370 Some("theorem"),
3371 "FromTheorem",
3372 None,
3373 None,
3374 vec![],
3375 )
3376 .await
3377 .unwrap();
3378 let into_lemma = rt
3379 .create_entity(
3380 &tok,
3381 "concept",
3382 Some("lemma"),
3383 "IntoLemma",
3384 None,
3385 None,
3386 vec![],
3387 )
3388 .await
3389 .unwrap();
3390
3391 rt.link(
3392 &tok,
3393 from_theorem.id,
3394 def_entity.id,
3395 EdgeRelation::DependsOn,
3396 1.0,
3397 None,
3398 )
3399 .await
3400 .unwrap();
3401
3402 let summary = rt
3403 .merge_entity_with_reason(
3404 &tok,
3405 into_lemma.id,
3406 from_theorem.id,
3407 EntityDedupMergePolicy::PreferInto,
3408 ContentMergeStrategy::Append,
3409 true, None,
3411 )
3412 .await
3413 .unwrap();
3414
3415 assert_eq!(summary.edges_rewired, 0);
3416 assert_eq!(summary.edges_contract_skipped, 1);
3417
3418 let def_neighbors = rt
3420 .neighbors(&tok, def_entity.id, Direction::In, None, None)
3421 .await
3422 .unwrap();
3423 assert_eq!(def_neighbors.len(), 1);
3424 assert_eq!(def_neighbors[0].node_id, from_theorem.id);
3425 }
3426
3427 #[tokio::test]
3430 async fn merge_entity_conflict_keeps_survivor_edge_attributes() {
3431 let rt = rt();
3432 let tok = NamespaceToken::local();
3433 let into = rt
3434 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3435 .await
3436 .unwrap();
3437 let from = rt
3438 .create_entity(&tok, "concept", None, "From", None, None, vec![])
3439 .await
3440 .unwrap();
3441 let shared = rt
3442 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3443 .await
3444 .unwrap();
3445
3446 let survivor = rt
3447 .link(&tok, into.id, shared.id, EdgeRelation::Extends, 0.9, None)
3448 .await
3449 .unwrap();
3450 rt.link(&tok, from.id, shared.id, EdgeRelation::Extends, 0.2, None)
3451 .await
3452 .unwrap();
3453
3454 rt.merge_entity(
3455 &tok,
3456 into.id,
3457 from.id,
3458 EntityDedupMergePolicy::PreferInto,
3459 ContentMergeStrategy::Append,
3460 false,
3461 )
3462 .await
3463 .unwrap();
3464
3465 let edges = rt
3466 .list_edges(
3467 &tok,
3468 crate::EdgeListFilter {
3469 source_id: Some(into.id),
3470 target_id: Some(shared.id),
3471 relations: vec![EdgeRelation::Extends],
3472 ..Default::default()
3473 },
3474 10,
3475 0,
3476 )
3477 .await
3478 .unwrap();
3479 assert_eq!(edges.len(), 1);
3480 assert_eq!(edges[0].id, survivor.id);
3481 assert!(
3482 (edges[0].weight - 0.9).abs() < f64::EPSILON,
3483 "survivor weight must not be overwritten by the merged-from edge; got {}",
3484 edges[0].weight
3485 );
3486 }
3487
3488 #[tokio::test]
3489 async fn merge_entity_conflict_records_restorable_edge_and_annotation_preimages() {
3490 let rt = rt();
3491 let tok = NamespaceToken::local();
3492 let into = rt
3493 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3494 .await
3495 .unwrap();
3496 let from = rt
3497 .create_entity(&tok, "concept", None, "From", None, None, vec![])
3498 .await
3499 .unwrap();
3500 let shared = rt
3501 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3502 .await
3503 .unwrap();
3504 let annotator = rt
3505 .create_note(
3506 &tok,
3507 "observation",
3508 None,
3509 "edge judgment",
3510 None,
3511 None,
3512 vec![],
3513 )
3514 .await
3515 .unwrap();
3516 let nested_annotator = rt
3517 .create_note(
3518 &tok,
3519 "observation",
3520 None,
3521 "judgment review",
3522 None,
3523 None,
3524 vec![],
3525 )
3526 .await
3527 .unwrap();
3528
3529 let survivor = rt
3530 .link(
3531 &tok,
3532 into.id,
3533 shared.id,
3534 EdgeRelation::Extends,
3535 0.9,
3536 Some(serde_json::json!({"source": "survivor"})),
3537 )
3538 .await
3539 .unwrap();
3540 let dropped = rt
3541 .link(
3542 &tok,
3543 from.id,
3544 shared.id,
3545 EdgeRelation::Extends,
3546 0.2,
3547 Some(serde_json::json!({"source": "dropped"})),
3548 )
3549 .await
3550 .unwrap();
3551 let annotation = rt
3552 .link(
3553 &tok,
3554 annotator.id,
3555 dropped.id.into(),
3556 EdgeRelation::Annotates,
3557 0.7,
3558 Some(serde_json::json!({"basis": "manual"})),
3559 )
3560 .await
3561 .unwrap();
3562 let nested_annotation = rt
3563 .link(
3564 &tok,
3565 nested_annotator.id,
3566 annotation.id.into(),
3567 EdgeRelation::Annotates,
3568 0.6,
3569 Some(serde_json::json!({"review": "confirmed"})),
3570 )
3571 .await
3572 .unwrap();
3573 rt.delete_edge(&tok, annotation.id.into(), false)
3574 .await
3575 .unwrap();
3576
3577 let summary = rt
3578 .merge_entity(
3579 &tok,
3580 into.id,
3581 from.id,
3582 EntityDedupMergePolicy::PreferInto,
3583 ContentMergeStrategy::Append,
3584 false,
3585 )
3586 .await
3587 .unwrap();
3588
3589 let [conflict] = summary.edge_conflict_preimages.as_slice() else {
3590 panic!(
3591 "expected one edge-conflict preimage, got {:?}",
3592 summary.edge_conflict_preimages
3593 );
3594 };
3595 assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
3596 assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
3597 assert_eq!(conflict.dropped_edge.source_id, from.id);
3598 assert_eq!(conflict.dropped_edge.target_id, shared.id);
3599 assert_eq!(conflict.dropped_edge.relation, "extends");
3600 assert_eq!(conflict.dropped_edge.weight, 0.2);
3601 assert_eq!(
3602 conflict.dropped_edge.metadata,
3603 Some(serde_json::json!({"source": "dropped"}))
3604 );
3605 assert_eq!(conflict.incident_edge_preimages.len(), 2);
3606 assert_eq!(
3607 conflict.incident_edge_preimages[0].id,
3608 Uuid::from(annotation.id)
3609 );
3610 assert_eq!(
3611 conflict.incident_edge_preimages[1].id,
3612 Uuid::from(nested_annotation.id)
3613 );
3614
3615 for id in [dropped.id, annotation.id, nested_annotation.id] {
3616 assert!(
3617 rt.get_edge_including_deleted(&tok, id.into())
3618 .await
3619 .unwrap()
3620 .is_none(),
3621 "merge conflict cascade must leave no dangling edge row for {id}"
3622 );
3623 }
3624
3625 let events = rt
3626 .events(&tok)
3627 .unwrap()
3628 .query_events(
3629 khive_storage::EventFilter {
3630 kinds: vec![EventKind::EntityMerged],
3631 ..Default::default()
3632 },
3633 khive_storage::types::PageRequest {
3634 offset: 0,
3635 limit: 10,
3636 },
3637 )
3638 .await
3639 .unwrap();
3640 assert_eq!(events.items.len(), 1);
3641 assert_eq!(
3642 events.items[0].payload["edge_conflict_preimages"],
3643 serde_json::to_value(&summary.edge_conflict_preimages).unwrap()
3644 );
3645
3646 restore_edge_preimage(&rt, &tok, &conflict.dropped_edge).await;
3647 for preimage in &conflict.incident_edge_preimages {
3648 restore_edge_preimage(&rt, &tok, preimage).await;
3649 }
3650 for preimage in
3651 std::iter::once(&conflict.dropped_edge).chain(conflict.incident_edge_preimages.iter())
3652 {
3653 let restored = rt
3654 .get_edge_including_deleted(&tok, preimage.id)
3655 .await
3656 .unwrap()
3657 .expect("restored edge");
3658 assert_edge_matches_preimage(&restored, preimage);
3659 }
3660 }
3661
3662 #[tokio::test]
3671 async fn merge_entity_dry_run_conflict_returns_preimages_without_mutating() {
3672 let rt = rt();
3673 let tok = NamespaceToken::local();
3674 let into = rt
3675 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3676 .await
3677 .unwrap();
3678 let from = rt
3679 .create_entity(&tok, "concept", None, "From", None, None, vec![])
3680 .await
3681 .unwrap();
3682 let shared = rt
3683 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3684 .await
3685 .unwrap();
3686 let annotator = rt
3687 .create_note(
3688 &tok,
3689 "observation",
3690 None,
3691 "edge judgment",
3692 None,
3693 None,
3694 vec![],
3695 )
3696 .await
3697 .unwrap();
3698 let nested_annotator = rt
3699 .create_note(
3700 &tok,
3701 "observation",
3702 None,
3703 "judgment review",
3704 None,
3705 None,
3706 vec![],
3707 )
3708 .await
3709 .unwrap();
3710
3711 let survivor = rt
3712 .link(
3713 &tok,
3714 into.id,
3715 shared.id,
3716 EdgeRelation::Extends,
3717 0.9,
3718 Some(serde_json::json!({"source": "survivor"})),
3719 )
3720 .await
3721 .unwrap();
3722 let dropped = rt
3723 .link(
3724 &tok,
3725 from.id,
3726 shared.id,
3727 EdgeRelation::Extends,
3728 0.2,
3729 Some(serde_json::json!({"source": "dropped"})),
3730 )
3731 .await
3732 .unwrap();
3733 let annotation = rt
3734 .link(
3735 &tok,
3736 annotator.id,
3737 dropped.id.into(),
3738 EdgeRelation::Annotates,
3739 0.7,
3740 Some(serde_json::json!({"basis": "manual"})),
3741 )
3742 .await
3743 .unwrap();
3744 let nested_annotation = rt
3745 .link(
3746 &tok,
3747 nested_annotator.id,
3748 annotation.id.into(),
3749 EdgeRelation::Annotates,
3750 0.6,
3751 Some(serde_json::json!({"basis": "nested"})),
3752 )
3753 .await
3754 .unwrap();
3755 rt.delete_edge(&tok, nested_annotation.id.into(), false)
3756 .await
3757 .unwrap();
3758
3759 let survivor_before = rt
3760 .get_edge_including_deleted(&tok, survivor.id.into())
3761 .await
3762 .unwrap()
3763 .expect("survivor edge exists");
3764 let dropped_before = rt
3765 .get_edge_including_deleted(&tok, dropped.id.into())
3766 .await
3767 .unwrap()
3768 .expect("dropped edge exists");
3769 let annotation_before = rt
3770 .get_edge_including_deleted(&tok, annotation.id.into())
3771 .await
3772 .unwrap()
3773 .expect("annotation edge exists");
3774 let nested_annotation_before = rt
3775 .get_edge_including_deleted(&tok, nested_annotation.id.into())
3776 .await
3777 .unwrap()
3778 .expect("nested annotation edge exists");
3779 let into_before = rt
3780 .get_entity(&tok, into.id)
3781 .await
3782 .expect("into entity exists");
3783 let from_before = rt
3784 .get_entity(&tok, from.id)
3785 .await
3786 .expect("from entity exists");
3787
3788 let summary = rt
3789 .merge_entity(
3790 &tok,
3791 into.id,
3792 from.id,
3793 EntityDedupMergePolicy::PreferInto,
3794 ContentMergeStrategy::Append,
3795 true,
3796 )
3797 .await
3798 .unwrap();
3799
3800 let [conflict] = summary.edge_conflict_preimages.as_slice() else {
3801 panic!(
3802 "expected one edge-conflict preimage from the dry run, got {:?}",
3803 summary.edge_conflict_preimages
3804 );
3805 };
3806 assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
3807 assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
3808 assert_eq!(conflict.dropped_edge.source_id, from.id);
3809 assert_eq!(conflict.dropped_edge.target_id, shared.id);
3810 assert_eq!(conflict.dropped_edge.weight, 0.2);
3811 assert_eq!(conflict.incident_edge_preimages.len(), 2);
3814 assert_eq!(
3815 conflict.incident_edge_preimages[0].id,
3816 Uuid::from(annotation.id)
3817 );
3818 assert!(
3819 conflict.incident_edge_preimages[0].deleted_at.is_none(),
3820 "the direct annotation was never soft-deleted"
3821 );
3822 assert_eq!(
3823 conflict.incident_edge_preimages[1].id,
3824 Uuid::from(nested_annotation.id)
3825 );
3826 assert!(
3827 conflict.incident_edge_preimages[1].deleted_at.is_some(),
3828 "dry-run preimage must retain the nested annotation's tombstone state"
3829 );
3830
3831 let survivor_after = rt
3832 .get_edge_including_deleted(&tok, survivor.id.into())
3833 .await
3834 .unwrap()
3835 .expect("dry run must not delete the survivor edge");
3836 let dropped_after = rt
3837 .get_edge_including_deleted(&tok, dropped.id.into())
3838 .await
3839 .unwrap()
3840 .expect("dry run must not delete the dropped edge");
3841 let annotation_after = rt
3842 .get_edge_including_deleted(&tok, annotation.id.into())
3843 .await
3844 .unwrap()
3845 .expect("dry run must not delete the cascaded annotation");
3846 let nested_annotation_after = rt
3847 .get_edge_including_deleted(&tok, nested_annotation.id.into())
3848 .await
3849 .unwrap()
3850 .expect("dry run must not delete the nested cascaded annotation");
3851 assert_eq!(
3852 serde_json::to_value(&survivor_before).unwrap(),
3853 serde_json::to_value(&survivor_after).unwrap(),
3854 "dry run must not mutate the surviving edge's row at all"
3855 );
3856 assert_eq!(
3857 serde_json::to_value(&dropped_before).unwrap(),
3858 serde_json::to_value(&dropped_after).unwrap(),
3859 "dry run must not mutate the would-be-dropped edge's row at all"
3860 );
3861 assert_eq!(
3862 serde_json::to_value(&annotation_before).unwrap(),
3863 serde_json::to_value(&annotation_after).unwrap(),
3864 "dry run must not mutate the incident annotation's row at all"
3865 );
3866 assert_eq!(
3867 serde_json::to_value(&nested_annotation_before).unwrap(),
3868 serde_json::to_value(&nested_annotation_after).unwrap(),
3869 "dry run must not mutate the nested incident annotation's row at all"
3870 );
3871
3872 let into_after = rt
3873 .get_entity(&tok, into.id)
3874 .await
3875 .expect("into entity must remain unmerged after a dry run");
3876 let from_after = rt
3877 .get_entity(&tok, from.id)
3878 .await
3879 .expect("from entity must not be merged away by a dry run");
3880 assert_eq!(
3881 serde_json::to_value(&into_before).unwrap(),
3882 serde_json::to_value(&into_after).unwrap(),
3883 "dry run must not mutate the into entity's row at all"
3884 );
3885 assert_eq!(
3886 serde_json::to_value(&from_before).unwrap(),
3887 serde_json::to_value(&from_after).unwrap(),
3888 "dry run must not mutate the from entity's row at all"
3889 );
3890 assert_eq!(from_after.deleted_at, None);
3891 assert_eq!(from_after.merged_into, None);
3892 assert_eq!(from_after.merge_event_id, None);
3893
3894 let events = rt
3895 .events(&tok)
3896 .unwrap()
3897 .query_events(
3898 khive_storage::EventFilter {
3899 kinds: vec![EventKind::EntityMerged],
3900 ..Default::default()
3901 },
3902 khive_storage::types::PageRequest {
3903 offset: 0,
3904 limit: 10,
3905 },
3906 )
3907 .await
3908 .unwrap();
3909 assert!(
3910 events.items.is_empty(),
3911 "a dry run must not record a merge audit event"
3912 );
3913 }
3914
3915 #[tokio::test]
3918 async fn merge_entity_conflict_does_not_resurrect_tombstoned_edge() {
3919 let rt = rt();
3920 let tok = NamespaceToken::local();
3921 let into = rt
3922 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3923 .await
3924 .unwrap();
3925 let from = rt
3926 .create_entity(&tok, "concept", None, "From", None, None, vec![])
3927 .await
3928 .unwrap();
3929 let shared = rt
3930 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3931 .await
3932 .unwrap();
3933
3934 let survivor = rt
3935 .link(&tok, into.id, shared.id, EdgeRelation::Extends, 0.9, None)
3936 .await
3937 .unwrap();
3938 rt.delete_edge(&tok, survivor.id.into(), false)
3939 .await
3940 .unwrap();
3941 rt.link(&tok, from.id, shared.id, EdgeRelation::Extends, 0.2, None)
3942 .await
3943 .unwrap();
3944
3945 rt.merge_entity(
3946 &tok,
3947 into.id,
3948 from.id,
3949 EntityDedupMergePolicy::PreferInto,
3950 ContentMergeStrategy::Append,
3951 false,
3952 )
3953 .await
3954 .unwrap();
3955
3956 for (src, label) in [(into.id, "into"), (from.id, "from")] {
3957 let edges = rt
3958 .list_edges(
3959 &tok,
3960 crate::EdgeListFilter {
3961 source_id: Some(src),
3962 target_id: Some(shared.id),
3963 relations: vec![EdgeRelation::Extends],
3964 ..Default::default()
3965 },
3966 10,
3967 0,
3968 )
3969 .await
3970 .unwrap();
3971 assert!(
3972 edges.is_empty(),
3973 "no live {label}→shared edge may exist after merging over a tombstone; got: {edges:?}"
3974 );
3975 }
3976 }
3977
3978 #[tokio::test]
3982 async fn merge_entity_preserves_survivor_entity_type() {
3983 let rt = rt();
3984 let tok = NamespaceToken::local();
3985 let into = rt
3986 .create_entity(&tok, "resource", Some("skill"), "Into", None, None, vec![])
3987 .await
3988 .unwrap();
3989 assert_eq!(into.entity_type.as_deref(), Some("skill"));
3990 let from = rt
3991 .create_entity(&tok, "resource", None, "From", None, None, vec![])
3992 .await
3993 .unwrap();
3994
3995 rt.merge_entity(
3996 &tok,
3997 into.id,
3998 from.id,
3999 EntityDedupMergePolicy::PreferInto,
4000 ContentMergeStrategy::Append,
4001 false,
4002 )
4003 .await
4004 .unwrap();
4005
4006 let got = rt.get_entity(&tok, into.id).await.unwrap();
4007 assert_eq!(
4008 got.entity_type.as_deref(),
4009 Some("skill"),
4010 "merge must not null the survivor's entity_type"
4011 );
4012 }
4013
4014 #[tokio::test]
4015 async fn merge_entity_preserves_survivor_content_ref() {
4016 let rt = rt();
4017 let tok = NamespaceToken::local();
4018 let into = rt
4019 .create_entity(&tok, "document", None, "Into", None, None, vec![])
4020 .await
4021 .unwrap();
4022 let from = rt
4023 .create_entity(&tok, "document", None, "From", None, None, vec![])
4024 .await
4025 .unwrap();
4026
4027 let content_ref = "blake3:0000000000000000000000000000000000000000000000000000000000000000";
4028 let store = rt.entities(&tok).unwrap();
4029 let stored = store.get_entity(into.id).await.unwrap().unwrap();
4030 store
4031 .upsert_entity(stored.with_content_ref(content_ref))
4032 .await
4033 .unwrap();
4034
4035 rt.merge_entity(
4036 &tok,
4037 into.id,
4038 from.id,
4039 EntityDedupMergePolicy::PreferInto,
4040 ContentMergeStrategy::Append,
4041 false,
4042 )
4043 .await
4044 .unwrap();
4045
4046 let got = store.get_entity(into.id).await.unwrap().unwrap();
4047 assert_eq!(
4048 got.content_ref.as_deref(),
4049 Some(content_ref),
4050 "merge must not null the survivor's content_ref"
4051 );
4052 }
4053
4054 #[tokio::test]
4055 async fn merge_entity_self_merge_rejected() {
4056 let rt = rt();
4057 let tok = NamespaceToken::local();
4058 let a = rt
4059 .create_entity(&tok, "concept", None, "A", None, None, vec![])
4060 .await
4061 .unwrap();
4062 let err = rt
4063 .merge_entity_with_reason(
4064 &tok,
4065 a.id,
4066 a.id,
4067 EntityDedupMergePolicy::PreferInto,
4068 ContentMergeStrategy::Append,
4069 false,
4070 None,
4071 )
4072 .await
4073 .unwrap_err();
4074 assert!(
4075 format!("{err:?}").contains("cannot merge an entity into itself"),
4076 "expected self-merge rejection, got: {err:?}"
4077 );
4078 }
4079
4080 #[tokio::test]
4081 async fn merge_entity_prefer_into_strategy() {
4082 let rt = rt();
4083 let tok = NamespaceToken::local();
4084 let into = rt
4085 .create_entity(
4086 &tok,
4087 "concept",
4088 None,
4089 "Into",
4090 None,
4091 Some(serde_json::json!({"a": 1})),
4092 vec![],
4093 )
4094 .await
4095 .unwrap();
4096 let from = rt
4097 .create_entity(
4098 &tok,
4099 "concept",
4100 None,
4101 "From",
4102 None,
4103 Some(serde_json::json!({"a": 2, "b": 3})),
4104 vec![],
4105 )
4106 .await
4107 .unwrap();
4108
4109 rt.merge_entity_with_reason(
4110 &tok,
4111 into.id,
4112 from.id,
4113 EntityDedupMergePolicy::PreferInto,
4114 ContentMergeStrategy::Append,
4115 false,
4116 None,
4117 )
4118 .await
4119 .unwrap();
4120
4121 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4122 let props = kept.properties.unwrap();
4123 assert_eq!(props["a"], 1);
4125 assert_eq!(props["b"], 3);
4126 }
4127
4128 #[tokio::test]
4129 async fn merge_entity_prefer_from_strategy() {
4130 let rt = rt();
4131 let tok = NamespaceToken::local();
4132 let into = rt
4133 .create_entity(
4134 &tok,
4135 "concept",
4136 None,
4137 "Into",
4138 None,
4139 Some(serde_json::json!({"a": 1})),
4140 vec![],
4141 )
4142 .await
4143 .unwrap();
4144 let from = rt
4145 .create_entity(
4146 &tok,
4147 "concept",
4148 None,
4149 "From",
4150 None,
4151 Some(serde_json::json!({"a": 2, "b": 3})),
4152 vec![],
4153 )
4154 .await
4155 .unwrap();
4156
4157 rt.merge_entity_with_reason(
4158 &tok,
4159 into.id,
4160 from.id,
4161 EntityDedupMergePolicy::PreferFrom,
4162 ContentMergeStrategy::Append,
4163 false,
4164 None,
4165 )
4166 .await
4167 .unwrap();
4168
4169 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4170 let props = kept.properties.unwrap();
4171 assert_eq!(props["a"], 2);
4173 assert_eq!(props["b"], 3);
4174 }
4175
4176 #[tokio::test]
4177 async fn merge_entity_union_strategy() {
4178 let rt = rt();
4179 let tok = NamespaceToken::local();
4180 let into = rt
4181 .create_entity(
4182 &tok,
4183 "concept",
4184 None,
4185 "Into",
4186 None,
4187 Some(serde_json::json!({"a": 1})),
4188 vec![],
4189 )
4190 .await
4191 .unwrap();
4192 let from = rt
4193 .create_entity(
4194 &tok,
4195 "concept",
4196 None,
4197 "From",
4198 None,
4199 Some(serde_json::json!({"a": 2, "b": 3})),
4200 vec![],
4201 )
4202 .await
4203 .unwrap();
4204
4205 rt.merge_entity_with_reason(
4206 &tok,
4207 into.id,
4208 from.id,
4209 EntityDedupMergePolicy::Union,
4210 ContentMergeStrategy::Append,
4211 false,
4212 None,
4213 )
4214 .await
4215 .unwrap();
4216
4217 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4218 let props = kept.properties.unwrap();
4219 assert_eq!(props["a"], 1);
4221 assert_eq!(props["b"], 3);
4222 }
4223
4224 #[tokio::test]
4225 async fn merge_entity_unions_tags() {
4226 let rt = rt();
4227 let tok = NamespaceToken::local();
4228 let into = rt
4229 .create_entity(
4230 &tok,
4231 "concept",
4232 None,
4233 "Into",
4234 None,
4235 None,
4236 vec!["x".to_string(), "y".to_string()],
4237 )
4238 .await
4239 .unwrap();
4240 let from = rt
4241 .create_entity(
4242 &tok,
4243 "concept",
4244 None,
4245 "From",
4246 None,
4247 None,
4248 vec!["y".to_string(), "z".to_string()],
4249 )
4250 .await
4251 .unwrap();
4252
4253 rt.merge_entity_with_reason(
4254 &tok,
4255 into.id,
4256 from.id,
4257 EntityDedupMergePolicy::PreferInto,
4258 ContentMergeStrategy::Append,
4259 false,
4260 None,
4261 )
4262 .await
4263 .unwrap();
4264
4265 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4266 let mut tags = kept.tags.clone();
4267 tags.sort();
4268 assert_eq!(tags, vec!["x", "y", "z"]);
4269 }
4270
4271 #[tokio::test]
4272 async fn merge_entity_drops_self_loops() {
4273 let rt = rt();
4274 let tok = NamespaceToken::local();
4275 let a = rt
4276 .create_entity(&tok, "concept", None, "A", None, None, vec![])
4277 .await
4278 .unwrap();
4279 let b = rt
4280 .create_entity(&tok, "concept", None, "B", None, None, vec![])
4281 .await
4282 .unwrap();
4283
4284 rt.link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
4286 .await
4287 .unwrap();
4288
4289 let summary = rt
4290 .merge_entity_with_reason(
4291 &tok,
4292 a.id,
4293 b.id,
4294 EntityDedupMergePolicy::PreferInto,
4295 ContentMergeStrategy::Append,
4296 false,
4297 None,
4298 )
4299 .await
4300 .unwrap();
4301
4302 assert_eq!(
4303 summary.edges_rewired, 0,
4304 "self-loop should be dropped, not rewired"
4305 );
4306
4307 let a_out = rt
4308 .neighbors(&tok, a.id, Direction::Out, None, None)
4309 .await
4310 .unwrap();
4311 assert!(a_out.is_empty(), "no self-loop should remain");
4312 }
4313
4314 #[tokio::test]
4317 async fn merge_entity_append_strategy_concatenates_descriptions() {
4318 let rt = rt();
4319 let tok = NamespaceToken::local();
4320 let into = rt
4321 .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4322 .await
4323 .unwrap();
4324 let from = rt
4325 .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4326 .await
4327 .unwrap();
4328
4329 let summary = rt
4330 .merge_entity_with_reason(
4331 &tok,
4332 into.id,
4333 from.id,
4334 EntityDedupMergePolicy::PreferInto,
4335 ContentMergeStrategy::Append,
4336 false,
4337 None,
4338 )
4339 .await
4340 .unwrap();
4341
4342 assert!(
4343 summary.content_appended,
4344 "append strategy with two non-empty descriptions must report content_appended=true"
4345 );
4346 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4347 assert_eq!(kept.description.as_deref(), Some("desc A\n\n---\n\ndesc B"));
4348 }
4349
4350 #[tokio::test]
4351 async fn merge_entity_append_strategy_from_empty_is_noop() {
4352 let rt = rt();
4353 let tok = NamespaceToken::local();
4354 let into = rt
4355 .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4356 .await
4357 .unwrap();
4358 let from = rt
4359 .create_entity(&tok, "concept", None, "From", None, None, vec![])
4360 .await
4361 .unwrap();
4362
4363 let summary = rt
4364 .merge_entity_with_reason(
4365 &tok,
4366 into.id,
4367 from.id,
4368 EntityDedupMergePolicy::PreferInto,
4369 ContentMergeStrategy::Append,
4370 false,
4371 None,
4372 )
4373 .await
4374 .unwrap();
4375
4376 assert!(
4377 !summary.content_appended,
4378 "from's empty description means nothing was appended"
4379 );
4380 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4381 assert_eq!(kept.description.as_deref(), Some("desc A"));
4382 }
4383
4384 #[tokio::test]
4385 async fn merge_entity_append_strategy_into_empty_takes_from() {
4386 let rt = rt();
4387 let tok = NamespaceToken::local();
4388 let into = rt
4389 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4390 .await
4391 .unwrap();
4392 let from = rt
4393 .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4394 .await
4395 .unwrap();
4396
4397 let summary = rt
4398 .merge_entity_with_reason(
4399 &tok,
4400 into.id,
4401 from.id,
4402 EntityDedupMergePolicy::PreferInto,
4403 ContentMergeStrategy::Append,
4404 false,
4405 None,
4406 )
4407 .await
4408 .unwrap();
4409
4410 assert!(
4411 summary.content_appended,
4412 "taking from's description into an empty into is real content preservation"
4413 );
4414 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4415 assert_eq!(kept.description.as_deref(), Some("desc B"));
4416 }
4417
4418 #[tokio::test]
4419 async fn merge_entity_prefer_into_strategy_still_discards_explicitly() {
4420 let rt = rt();
4421 let tok = NamespaceToken::local();
4422 let into = rt
4423 .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4424 .await
4425 .unwrap();
4426 let from = rt
4427 .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4428 .await
4429 .unwrap();
4430
4431 let summary = rt
4432 .merge_entity_with_reason(
4433 &tok,
4434 into.id,
4435 from.id,
4436 EntityDedupMergePolicy::PreferInto,
4437 ContentMergeStrategy::PreferInto,
4438 false,
4439 None,
4440 )
4441 .await
4442 .unwrap();
4443
4444 assert!(
4445 !summary.content_appended,
4446 "explicit PreferInto opt-out must not report an append"
4447 );
4448 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4449 assert_eq!(
4450 kept.description.as_deref(),
4451 Some("desc A"),
4452 "explicit PreferInto opt-out keeps the old discard behavior"
4453 );
4454 }
4455
4456 #[tokio::test]
4461 async fn merge_entity_prefer_from_content_strategy_wins_over_default_entity_policy() {
4462 let rt = rt();
4463 let tok = NamespaceToken::local();
4464 let into = rt
4465 .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4466 .await
4467 .unwrap();
4468 let from = rt
4469 .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4470 .await
4471 .unwrap();
4472
4473 let summary = rt
4474 .merge_entity_with_reason(
4475 &tok,
4476 into.id,
4477 from.id,
4478 EntityDedupMergePolicy::PreferInto,
4479 ContentMergeStrategy::PreferFrom,
4480 false,
4481 None,
4482 )
4483 .await
4484 .unwrap();
4485
4486 assert!(
4487 !summary.content_appended,
4488 "explicit PreferFrom is not an append"
4489 );
4490 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4491 assert_eq!(
4492 kept.description.as_deref(),
4493 Some("desc B"),
4494 "content_strategy=prefer_from must win over the default prefer_into entity policy"
4495 );
4496 }
4497
4498 #[tokio::test]
4499 async fn merge_entity_dry_run_previews_append() {
4500 let rt = rt();
4501 let tok = NamespaceToken::local();
4502 let into = rt
4503 .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4504 .await
4505 .unwrap();
4506 let from = rt
4507 .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4508 .await
4509 .unwrap();
4510
4511 let summary = rt
4512 .merge_entity_with_reason(
4513 &tok,
4514 into.id,
4515 from.id,
4516 EntityDedupMergePolicy::PreferInto,
4517 ContentMergeStrategy::Append,
4518 true,
4519 None,
4520 )
4521 .await
4522 .unwrap();
4523
4524 assert!(summary.dry_run);
4525 assert!(
4526 summary.content_appended,
4527 "dry-run must preview the append outcome without writing"
4528 );
4529 let kept = rt.get_entity(&tok, into.id).await.unwrap();
4530 assert_eq!(
4531 kept.description.as_deref(),
4532 Some("desc A"),
4533 "dry_run=true must not mutate the into entity's description"
4534 );
4535 }
4536
4537 #[tokio::test]
4540 async fn merge_entity_dry_run_predicts_edges_rewired_without_writing() {
4541 use khive_storage::EdgeRelation;
4542
4543 let rt = rt();
4544 let tok = NamespaceToken::local();
4545 let a = rt
4546 .create_entity(&tok, "concept", None, "A", None, None, vec![])
4547 .await
4548 .unwrap();
4549 let into = rt
4550 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4551 .await
4552 .unwrap();
4553 let from = rt
4554 .create_entity(&tok, "concept", None, "From", None, None, vec![])
4555 .await
4556 .unwrap();
4557
4558 rt.link(&tok, a.id, from.id, EdgeRelation::Extends, 1.0, None)
4559 .await
4560 .unwrap();
4561
4562 let summary = rt
4563 .merge_entity_with_reason(
4564 &tok,
4565 into.id,
4566 from.id,
4567 EntityDedupMergePolicy::PreferInto,
4568 ContentMergeStrategy::Append,
4569 true,
4570 None,
4571 )
4572 .await
4573 .unwrap();
4574
4575 assert!(summary.dry_run);
4576 assert_eq!(
4577 summary.edges_rewired, 1,
4578 "dry-run must predict the edge that would be rewired, not report zero"
4579 );
4580
4581 let a_neighbors = rt
4582 .neighbors(&tok, a.id, Direction::Out, None, None)
4583 .await
4584 .unwrap();
4585 assert_eq!(a_neighbors.len(), 1);
4586 assert_eq!(
4587 a_neighbors[0].node_id, from.id,
4588 "dry_run=true must not rewire any edges"
4589 );
4590
4591 let events = rt
4592 .events(&tok)
4593 .unwrap()
4594 .query_events(
4595 khive_storage::EventFilter {
4596 kinds: vec![EventKind::EntityMerged],
4597 ..Default::default()
4598 },
4599 khive_storage::types::PageRequest {
4600 offset: 0,
4601 limit: 10,
4602 },
4603 )
4604 .await
4605 .unwrap();
4606 assert!(
4607 events.items.is_empty(),
4608 "dry_run=true must not append an EntityMerged event"
4609 );
4610 }
4611
4612 #[tokio::test]
4616 async fn merge_entity_event_reason_present_when_supplied_absent_when_not() {
4617 let rt = rt();
4618 let tok = NamespaceToken::local();
4619
4620 let into_a = rt
4621 .create_entity(&tok, "concept", None, "IntoA", None, None, vec![])
4622 .await
4623 .unwrap();
4624 let from_a = rt
4625 .create_entity(&tok, "concept", None, "FromA", None, None, vec![])
4626 .await
4627 .unwrap();
4628 rt.merge_entity_with_reason(
4629 &tok,
4630 into_a.id,
4631 from_a.id,
4632 EntityDedupMergePolicy::PreferInto,
4633 ContentMergeStrategy::Append,
4634 false,
4635 Some("duplicate".to_string()),
4636 )
4637 .await
4638 .unwrap();
4639
4640 let into_b = rt
4641 .create_entity(&tok, "concept", None, "IntoB", None, None, vec![])
4642 .await
4643 .unwrap();
4644 let from_b = rt
4645 .create_entity(&tok, "concept", None, "FromB", None, None, vec![])
4646 .await
4647 .unwrap();
4648 rt.merge_entity_with_reason(
4649 &tok,
4650 into_b.id,
4651 from_b.id,
4652 EntityDedupMergePolicy::PreferInto,
4653 ContentMergeStrategy::Append,
4654 false,
4655 None,
4656 )
4657 .await
4658 .unwrap();
4659
4660 let events = rt
4661 .events(&tok)
4662 .unwrap()
4663 .query_events(
4664 khive_storage::EventFilter {
4665 kinds: vec![EventKind::EntityMerged],
4666 ..Default::default()
4667 },
4668 khive_storage::types::PageRequest {
4669 offset: 0,
4670 limit: 10,
4671 },
4672 )
4673 .await
4674 .unwrap();
4675 assert_eq!(events.items.len(), 2);
4676
4677 let with_reason = events
4678 .items
4679 .iter()
4680 .find(|e| {
4681 e.payload.get("from_id").and_then(|v| v.as_str())
4682 == Some(from_a.id.to_string()).as_deref()
4683 })
4684 .expect("event for the reasoned merge must exist");
4685 assert_eq!(
4686 with_reason.payload.get("reason").and_then(|v| v.as_str()),
4687 Some("duplicate"),
4688 "reason must be threaded verbatim into the payload when supplied"
4689 );
4690
4691 let without_reason = events
4692 .items
4693 .iter()
4694 .find(|e| {
4695 e.payload.get("from_id").and_then(|v| v.as_str())
4696 == Some(from_b.id.to_string()).as_deref()
4697 })
4698 .expect("event for the reasonless merge must exist");
4699 assert!(
4700 without_reason.payload.get("reason").is_none(),
4701 "reason key must be absent (never null) when the caller omits it, got: {:?}",
4702 without_reason.payload
4703 );
4704 }
4705
4706 #[tokio::test]
4707 async fn merge_entity_with_reason_preserves_an_explicit_empty_reason() {
4708 let rt = rt();
4709 let tok = NamespaceToken::local();
4710 let into = rt
4711 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4712 .await
4713 .unwrap();
4714 let from = rt
4715 .create_entity(&tok, "concept", None, "From", None, None, vec![])
4716 .await
4717 .unwrap();
4718
4719 rt.merge_entity_with_reason(
4720 &tok,
4721 into.id,
4722 from.id,
4723 EntityDedupMergePolicy::PreferInto,
4724 ContentMergeStrategy::Append,
4725 false,
4726 Some(String::new()),
4727 )
4728 .await
4729 .unwrap();
4730
4731 let events = rt
4732 .events(&tok)
4733 .unwrap()
4734 .query_events(
4735 khive_storage::EventFilter {
4736 kinds: vec![EventKind::EntityMerged],
4737 ..Default::default()
4738 },
4739 khive_storage::types::PageRequest {
4740 offset: 0,
4741 limit: 10,
4742 },
4743 )
4744 .await
4745 .unwrap();
4746 assert_eq!(events.items.len(), 1);
4747 assert_eq!(
4748 events.items[0].payload.get("reason"),
4749 Some(&Value::String(String::new()))
4750 );
4751 }
4752
4753 #[tokio::test]
4754 async fn merge_entity_with_reason_rejects_secrets_before_reads_or_writes() {
4755 let rt = rt();
4756 let tok = NamespaceToken::local();
4757 let into = rt
4758 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4759 .await
4760 .unwrap();
4761 let from = rt
4762 .create_entity(&tok, "concept", None, "From", None, None, vec![])
4763 .await
4764 .unwrap();
4765 let secret = secret_shaped_reason();
4766
4767 let error = rt
4768 .merge_entity_with_reason(
4769 &tok,
4770 into.id,
4771 from.id,
4772 EntityDedupMergePolicy::PreferInto,
4773 ContentMergeStrategy::Append,
4774 false,
4775 Some(secret),
4776 )
4777 .await
4778 .unwrap_err();
4779
4780 assert!(matches!(error, RuntimeError::SecretDetected(_)));
4781 assert_eq!(rt.get_entity(&tok, into.id).await.unwrap().id, into.id);
4782 assert_eq!(rt.get_entity(&tok, from.id).await.unwrap().id, from.id);
4783 let event_count = rt
4784 .events(&tok)
4785 .unwrap()
4786 .count_events(khive_storage::EventFilter {
4787 kinds: vec![EventKind::EntityMerged],
4788 ..Default::default()
4789 })
4790 .await
4791 .unwrap();
4792 assert_eq!(event_count, 0);
4793 }
4794
4795 #[tokio::test]
4798 async fn merge_note_emits_exactly_one_note_merged_event_with_kept_and_absorbed_ids() {
4799 let rt = rt();
4800 let tok = NamespaceToken::local();
4801 let into = rt
4802 .create_note(&tok, "observation", None, "into note", None, None, vec![])
4803 .await
4804 .unwrap();
4805 let from = rt
4806 .create_note(&tok, "observation", None, "from note", None, None, vec![])
4807 .await
4808 .unwrap();
4809
4810 let summary = rt
4811 .merge_note_with_reason(
4812 &tok,
4813 into.id,
4814 from.id,
4815 EntityDedupMergePolicy::PreferInto,
4816 ContentMergeStrategy::Append,
4817 false,
4818 Some("duplicate".to_string()),
4819 )
4820 .await
4821 .unwrap();
4822
4823 let events = rt
4824 .events(&tok)
4825 .unwrap()
4826 .query_events(
4827 khive_storage::EventFilter {
4828 kinds: vec![EventKind::NoteMerged],
4829 ..Default::default()
4830 },
4831 khive_storage::types::PageRequest {
4832 offset: 0,
4833 limit: 10,
4834 },
4835 )
4836 .await
4837 .unwrap();
4838 assert_eq!(
4839 events.items.len(),
4840 1,
4841 "merge_note must emit exactly one NoteMerged event"
4842 );
4843
4844 let payload = &events.items[0].payload;
4845 assert_eq!(
4846 payload.get("into_id").and_then(|v| v.as_str()),
4847 Some(summary.kept_id.to_string()).as_deref()
4848 );
4849 assert_eq!(
4850 payload.get("from_id").and_then(|v| v.as_str()),
4851 Some(summary.removed_id.to_string()).as_deref()
4852 );
4853 assert_eq!(
4854 payload.get("reason").and_then(|v| v.as_str()),
4855 Some("duplicate")
4856 );
4857 }
4858
4859 #[tokio::test]
4860 async fn merge_note_with_reason_preserves_an_explicit_empty_reason() {
4861 let rt = rt();
4862 let tok = NamespaceToken::local();
4863 let into = rt
4864 .create_note(&tok, "observation", None, "into note", None, None, vec![])
4865 .await
4866 .unwrap();
4867 let from = rt
4868 .create_note(&tok, "observation", None, "from note", None, None, vec![])
4869 .await
4870 .unwrap();
4871
4872 rt.merge_note_with_reason(
4873 &tok,
4874 into.id,
4875 from.id,
4876 EntityDedupMergePolicy::PreferInto,
4877 ContentMergeStrategy::Append,
4878 false,
4879 Some(String::new()),
4880 )
4881 .await
4882 .unwrap();
4883
4884 let events = rt
4885 .events(&tok)
4886 .unwrap()
4887 .query_events(
4888 khive_storage::EventFilter {
4889 kinds: vec![EventKind::NoteMerged],
4890 ..Default::default()
4891 },
4892 khive_storage::types::PageRequest {
4893 offset: 0,
4894 limit: 10,
4895 },
4896 )
4897 .await
4898 .unwrap();
4899 assert_eq!(events.items.len(), 1);
4900 assert_eq!(
4901 events.items[0].payload.get("reason"),
4902 Some(&Value::String(String::new()))
4903 );
4904 }
4905
4906 #[tokio::test]
4907 async fn merge_note_with_reason_rejects_secrets_before_reads_or_writes() {
4908 let rt = rt();
4909 let tok = NamespaceToken::local();
4910 let into = rt
4911 .create_note(&tok, "observation", None, "into note", None, None, vec![])
4912 .await
4913 .unwrap();
4914 let from = rt
4915 .create_note(&tok, "observation", None, "from note", None, None, vec![])
4916 .await
4917 .unwrap();
4918 let secret = secret_shaped_reason();
4919
4920 let error = rt
4921 .merge_note_with_reason(
4922 &tok,
4923 into.id,
4924 from.id,
4925 EntityDedupMergePolicy::PreferInto,
4926 ContentMergeStrategy::Append,
4927 false,
4928 Some(secret),
4929 )
4930 .await
4931 .unwrap_err();
4932
4933 assert!(matches!(error, RuntimeError::SecretDetected(_)));
4934 let note_store = rt.notes(&tok).unwrap();
4935 assert_eq!(
4936 note_store.get_note(into.id).await.unwrap().unwrap().id,
4937 into.id
4938 );
4939 assert_eq!(
4940 note_store.get_note(from.id).await.unwrap().unwrap().id,
4941 from.id
4942 );
4943 let event_count = rt
4944 .events(&tok)
4945 .unwrap()
4946 .count_events(khive_storage::EventFilter {
4947 kinds: vec![EventKind::NoteMerged],
4948 ..Default::default()
4949 })
4950 .await
4951 .unwrap();
4952 assert_eq!(event_count, 0);
4953 }
4954
4955 #[tokio::test]
4956 async fn legacy_merge_methods_remain_source_compatible() {
4957 let rt = rt();
4958 let tok = NamespaceToken::local();
4959 let into_entity = rt
4960 .create_entity(&tok, "concept", None, "Entity A", None, None, vec![])
4961 .await
4962 .unwrap();
4963 let from_entity = rt
4964 .create_entity(&tok, "concept", None, "Entity B", None, None, vec![])
4965 .await
4966 .unwrap();
4967 let into_note = rt
4968 .create_note(&tok, "observation", None, "note A", None, None, vec![])
4969 .await
4970 .unwrap();
4971 let from_note = rt
4972 .create_note(&tok, "observation", None, "note B", None, None, vec![])
4973 .await
4974 .unwrap();
4975
4976 rt.merge_entity(
4977 &tok,
4978 into_entity.id,
4979 from_entity.id,
4980 EntityDedupMergePolicy::PreferInto,
4981 ContentMergeStrategy::Append,
4982 false,
4983 )
4984 .await
4985 .unwrap();
4986 rt.merge_note(
4987 &tok,
4988 into_note.id,
4989 from_note.id,
4990 EntityDedupMergePolicy::PreferInto,
4991 ContentMergeStrategy::Append,
4992 false,
4993 )
4994 .await
4995 .unwrap();
4996 }
4997
4998 #[tokio::test]
5001 async fn get_entity_after_merge_discloses_kept_id() {
5002 let rt = rt();
5003 let tok = NamespaceToken::local();
5004 let into = rt
5005 .create_entity(&tok, "concept", None, "Kept", None, None, vec![])
5006 .await
5007 .unwrap();
5008 let from = rt
5009 .create_entity(&tok, "concept", None, "Absorbed", None, None, vec![])
5010 .await
5011 .unwrap();
5012
5013 rt.merge_entity(
5014 &tok,
5015 into.id,
5016 from.id,
5017 EntityDedupMergePolicy::PreferInto,
5018 ContentMergeStrategy::Append,
5019 false,
5020 )
5021 .await
5022 .unwrap();
5023
5024 let err = rt.get_entity(&tok, from.id).await.unwrap_err();
5025 let msg = err.to_string();
5026 assert!(
5027 msg.contains("was merged into") && msg.contains(&into.id.to_string()),
5028 "expected a merged_into disclosure naming {}, got {msg:?}",
5029 into.id
5030 );
5031 }
5032
5033 #[tokio::test]
5034 async fn get_entity_on_plain_soft_delete_stays_bare_not_found() {
5035 let rt = rt();
5036 let tok = NamespaceToken::local();
5037 let entity = rt
5038 .create_entity(&tok, "concept", None, "Deleted", None, None, vec![])
5039 .await
5040 .unwrap();
5041 assert!(rt.delete_entity(&tok, entity.id, false).await.unwrap());
5042
5043 let err = rt.get_entity(&tok, entity.id).await.unwrap_err();
5044 let msg = err.to_string();
5045 assert!(
5046 !msg.contains("merged into"),
5047 "plain soft-delete must not gain a merge hint, got {msg:?}"
5048 );
5049 assert_eq!(msg, format!("not found: entity {}", entity.id));
5050 }
5051
5052 #[tokio::test]
5053 async fn get_entity_on_absent_id_stays_bare_not_found() {
5054 let rt = rt();
5055 let tok = NamespaceToken::local();
5056 let absent = Uuid::new_v4();
5057
5058 let err = rt.get_entity(&tok, absent).await.unwrap_err();
5059 let msg = err.to_string();
5060 assert!(
5061 !msg.contains("merged into"),
5062 "a never-existed id must not gain a merge hint, got {msg:?}"
5063 );
5064 assert_eq!(msg, format!("not found: entity {absent}"));
5065 }
5066
5067 #[test]
5070 fn union_tags_deduplicates() {
5071 let (tags, added) = union_tags(
5072 &["x".to_string(), "y".to_string()],
5073 &["y".to_string(), "z".to_string()],
5074 );
5075 let mut sorted = tags.clone();
5076 sorted.sort();
5077 assert_eq!(sorted, vec!["x", "y", "z"]);
5078 assert_eq!(added, 1);
5079 }
5080
5081 #[test]
5082 fn merge_properties_prefer_into_fills_missing_keys() {
5083 let a = serde_json::json!({"a": 1});
5084 let b = serde_json::json!({"a": 99, "b": 2});
5085 let (merged, added) =
5086 merge_properties(&Some(a), &Some(b), EntityDedupMergePolicy::PreferInto);
5087 let m = merged.unwrap();
5088 assert_eq!(m["a"], 1);
5089 assert_eq!(m["b"], 2);
5090 assert_eq!(added, 1);
5091 }
5092
5093 #[tokio::test]
5096 async fn merge_entity_tombstones_source_with_provenance() {
5097 let rt = rt();
5098 let tok = NamespaceToken::local();
5099 let into = rt
5100 .create_entity(&tok, "concept", None, "Into", None, None, vec![])
5101 .await
5102 .unwrap();
5103 let from = rt
5104 .create_entity(&tok, "concept", None, "From", None, None, vec![])
5105 .await
5106 .unwrap();
5107 let from_id = from.id;
5108
5109 rt.merge_entity_with_reason(
5110 &tok,
5111 into.id,
5112 from_id,
5113 EntityDedupMergePolicy::PreferInto,
5114 ContentMergeStrategy::Append,
5115 false,
5116 None,
5117 )
5118 .await
5119 .unwrap();
5120
5121 assert!(
5122 rt.get_entity(&tok, from_id).await.is_err(),
5123 "tombstoned source should not be returned by get_entity"
5124 );
5125
5126 let pool = rt.backend().pool_arc();
5127 let (deleted_at, merged_into): (Option<i64>, Option<String>) =
5128 tokio::task::spawn_blocking(move || {
5129 let guard = pool.writer().unwrap();
5130 guard
5131 .conn()
5132 .query_row(
5133 "SELECT deleted_at, merged_into FROM entities WHERE id = ?1",
5134 [from_id.to_string()],
5135 |row| Ok((row.get(0)?, row.get(1)?)),
5136 )
5137 .unwrap()
5138 })
5139 .await
5140 .unwrap();
5141 assert!(
5142 deleted_at.is_some(),
5143 "tombstoned entity must have deleted_at set"
5144 );
5145 assert_eq!(
5146 merged_into.as_deref(),
5147 Some(into.id.to_string().as_str()),
5148 "merged_into must point to into_id"
5149 );
5150 }
5151
5152 #[tokio::test]
5153 async fn generic_update_and_merge_reject_schedule_managed_notes() {
5154 let rt = rt();
5155 let tok = NamespaceToken::local();
5156 let schedule_a = rt
5157 .create_note(
5158 &tok,
5159 "scheduled_event",
5160 None,
5161 "stats()",
5162 None,
5163 Some(serde_json::json!({
5164 "event_type": "schedule",
5165 "payload": "stats()",
5166 "status": "pending",
5167 "trigger_at": "2099-01-01T00:00:00Z"
5168 })),
5169 vec![],
5170 )
5171 .await
5172 .unwrap();
5173 let schedule_b = rt
5174 .create_note(
5175 &tok,
5176 "scheduled_event",
5177 None,
5178 "stats()",
5179 None,
5180 Some(serde_json::json!({
5181 "event_type": "schedule",
5182 "payload": "stats()",
5183 "status": "pending",
5184 "trigger_at": "2099-01-02T00:00:00Z"
5185 })),
5186 vec![],
5187 )
5188 .await
5189 .unwrap();
5190
5191 let update_error = rt
5192 .update_note(
5193 &tok,
5194 schedule_a.id,
5195 NotePatch::new(
5196 None,
5197 None,
5198 None,
5199 None,
5200 Some(serde_json::json!({ "payload": "delete(id=\"victim\")" })),
5201 ),
5202 )
5203 .await
5204 .expect_err("schedule-managed note update must fail");
5205 assert!(
5206 update_error.to_string().contains("schedule-managed"),
5207 "{update_error}"
5208 );
5209
5210 for (into_id, from_id) in [
5211 (schedule_a.id, schedule_b.id),
5212 (schedule_b.id, schedule_a.id),
5213 ] {
5214 let merge_error = rt
5215 .merge_note(
5216 &tok,
5217 into_id,
5218 from_id,
5219 EntityDedupMergePolicy::PreferFrom,
5220 ContentMergeStrategy::PreferFrom,
5221 false,
5222 )
5223 .await
5224 .expect_err("either schedule-managed merge operand must fail");
5225 assert!(
5226 merge_error.to_string().contains("schedule-managed"),
5227 "{merge_error}"
5228 );
5229 }
5230
5231 let store = rt.notes(&tok).unwrap();
5232 for (id, trigger_at) in [
5233 (schedule_a.id, "2099-01-01T00:00:00Z"),
5234 (schedule_b.id, "2099-01-02T00:00:00Z"),
5235 ] {
5236 let note = store
5237 .get_note(id)
5238 .await
5239 .unwrap()
5240 .expect("rejected generic mutation leaves the schedule intact");
5241 assert_eq!(note.properties.as_ref().unwrap()["trigger_at"], trigger_at);
5242 }
5243 }
5244
5245 #[tokio::test]
5246 async fn merge_note_same_kind_appends_content() {
5247 let rt = rt();
5248 let tok = NamespaceToken::local();
5249 let into = rt
5250 .create_note(
5251 &tok,
5252 "observation",
5253 None,
5254 "Into content",
5255 None,
5256 None,
5257 vec![],
5258 )
5259 .await
5260 .unwrap();
5261 let from = rt
5262 .create_note(
5263 &tok,
5264 "observation",
5265 None,
5266 "From content",
5267 None,
5268 None,
5269 vec![],
5270 )
5271 .await
5272 .unwrap();
5273 let from_id = from.id;
5274
5275 let summary = rt
5276 .merge_note_with_reason(
5277 &tok,
5278 into.id,
5279 from_id,
5280 EntityDedupMergePolicy::PreferInto,
5281 ContentMergeStrategy::Append,
5282 false,
5283 None,
5284 )
5285 .await
5286 .unwrap();
5287
5288 assert_eq!(summary.kept_id, into.id);
5289 assert_eq!(summary.removed_id, from_id);
5290 assert!(summary.content_appended);
5291 assert!(!summary.dry_run);
5292
5293 let from_store = rt.notes(&tok).unwrap();
5294 assert!(
5295 from_store.get_note(from_id).await.unwrap().is_none(),
5296 "merged-from note should be soft-deleted"
5297 );
5298 }
5299
5300 #[tokio::test]
5303 async fn merge_note_survives_shared_edge_to_third_party() {
5304 use khive_storage::EdgeRelation;
5305 let rt = rt();
5306 let tok = NamespaceToken::local();
5307
5308 let into = rt
5309 .create_note(&tok, "observation", None, "Into", None, None, vec![])
5310 .await
5311 .unwrap();
5312 let from = rt
5313 .create_note(&tok, "observation", None, "From", None, None, vec![])
5314 .await
5315 .unwrap();
5316 let shared = rt
5317 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5318 .await
5319 .unwrap();
5320
5321 rt.link(&tok, into.id, shared.id, EdgeRelation::Annotates, 1.0, None)
5325 .await
5326 .unwrap();
5327 rt.link(&tok, from.id, shared.id, EdgeRelation::Annotates, 1.0, None)
5328 .await
5329 .unwrap();
5330
5331 let summary = rt
5332 .merge_note_with_reason(
5333 &tok,
5334 into.id,
5335 from.id,
5336 EntityDedupMergePolicy::PreferInto,
5337 ContentMergeStrategy::Append,
5338 false,
5339 None,
5340 )
5341 .await
5342 .expect("merge must succeed even when both notes annotate the same entity");
5343
5344 assert_eq!(summary.kept_id, into.id);
5345 assert_eq!(summary.removed_id, from.id);
5346
5347 let into_edges = rt
5348 .list_edges(
5349 &tok,
5350 crate::EdgeListFilter {
5351 source_id: Some(into.id),
5352 target_id: Some(shared.id),
5353 relations: vec![EdgeRelation::Annotates],
5354 ..Default::default()
5355 },
5356 10,
5357 0,
5358 )
5359 .await
5360 .unwrap();
5361 assert_eq!(
5362 into_edges.len(),
5363 1,
5364 "exactly one live into→shared annotates edge must exist after merge; got: {into_edges:?}"
5365 );
5366 }
5367
5368 #[tokio::test]
5369 async fn merge_note_conflict_records_dropped_edge_and_cascades_annotation() {
5370 let rt = rt();
5371 let tok = NamespaceToken::local();
5372 let into = rt
5373 .create_note(&tok, "observation", None, "Into", None, None, vec![])
5374 .await
5375 .unwrap();
5376 let from = rt
5377 .create_note(&tok, "observation", None, "From", None, None, vec![])
5378 .await
5379 .unwrap();
5380 let annotator = rt
5381 .create_note(
5382 &tok,
5383 "observation",
5384 None,
5385 "edge annotation",
5386 None,
5387 None,
5388 vec![],
5389 )
5390 .await
5391 .unwrap();
5392 let shared = rt
5393 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5394 .await
5395 .unwrap();
5396
5397 let survivor = rt
5398 .link(
5399 &tok,
5400 into.id,
5401 shared.id,
5402 EdgeRelation::Annotates,
5403 1.0,
5404 Some(serde_json::json!({"source": "survivor"})),
5405 )
5406 .await
5407 .unwrap();
5408 let dropped = rt
5409 .link(
5410 &tok,
5411 from.id,
5412 shared.id,
5413 EdgeRelation::Annotates,
5414 0.4,
5415 Some(serde_json::json!({"source": "dropped"})),
5416 )
5417 .await
5418 .unwrap();
5419 let annotation = rt
5420 .link(
5421 &tok,
5422 annotator.id,
5423 dropped.id.into(),
5424 EdgeRelation::Annotates,
5425 0.8,
5426 Some(serde_json::json!({"why": "duplicate claim"})),
5427 )
5428 .await
5429 .unwrap();
5430 rt.delete_edge(&tok, annotation.id.into(), false)
5431 .await
5432 .unwrap();
5433
5434 let summary = rt
5435 .merge_note(
5436 &tok,
5437 into.id,
5438 from.id,
5439 EntityDedupMergePolicy::PreferInto,
5440 ContentMergeStrategy::Append,
5441 false,
5442 )
5443 .await
5444 .unwrap();
5445
5446 let [conflict] = summary.edge_conflict_preimages.as_slice() else {
5447 panic!(
5448 "expected one note-merge edge conflict, got {:?}",
5449 summary.edge_conflict_preimages
5450 );
5451 };
5452 assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
5453 assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
5454 assert_eq!(conflict.dropped_edge.source_id, from.id);
5455 assert_eq!(conflict.dropped_edge.weight, 0.4);
5456 assert_eq!(
5457 conflict.dropped_edge.metadata,
5458 Some(serde_json::json!({"source": "dropped"}))
5459 );
5460 assert_eq!(conflict.incident_edge_preimages.len(), 1);
5461 assert_eq!(
5462 conflict.incident_edge_preimages[0].id,
5463 Uuid::from(annotation.id)
5464 );
5465 assert_eq!(
5466 conflict.incident_edge_preimages[0].metadata,
5467 Some(serde_json::json!({"why": "duplicate claim"}))
5468 );
5469 assert!(
5470 conflict.incident_edge_preimages[0].deleted_at.is_some(),
5471 "the cascade preimage must retain an annotation's tombstone state"
5472 );
5473 assert!(rt
5474 .get_edge_including_deleted(&tok, dropped.id.into())
5475 .await
5476 .unwrap()
5477 .is_none());
5478 assert!(
5479 rt.get_edge_including_deleted(&tok, annotation.id.into())
5480 .await
5481 .unwrap()
5482 .is_none(),
5483 "annotation targeting the dropped edge must be cascaded, not left dangling"
5484 );
5485
5486 let events = rt
5487 .events(&tok)
5488 .unwrap()
5489 .query_events(
5490 khive_storage::EventFilter {
5491 kinds: vec![EventKind::NoteMerged],
5492 ..Default::default()
5493 },
5494 khive_storage::types::PageRequest {
5495 offset: 0,
5496 limit: 10,
5497 },
5498 )
5499 .await
5500 .unwrap();
5501 assert_eq!(events.items.len(), 1);
5502 assert_eq!(
5503 events.items[0].payload["edge_conflict_preimages"],
5504 serde_json::to_value(&summary.edge_conflict_preimages).unwrap()
5505 );
5506 }
5507
5508 #[tokio::test]
5517 async fn merge_note_dry_run_conflict_returns_preimages_without_mutating() {
5518 let rt = rt();
5519 let tok = NamespaceToken::local();
5520 let into = rt
5521 .create_note(&tok, "observation", None, "Into", None, None, vec![])
5522 .await
5523 .unwrap();
5524 let from = rt
5525 .create_note(&tok, "observation", None, "From", None, None, vec![])
5526 .await
5527 .unwrap();
5528 let annotator = rt
5529 .create_note(
5530 &tok,
5531 "observation",
5532 None,
5533 "edge annotation",
5534 None,
5535 None,
5536 vec![],
5537 )
5538 .await
5539 .unwrap();
5540 let nested_annotator = rt
5541 .create_note(
5542 &tok,
5543 "observation",
5544 None,
5545 "nested edge annotation",
5546 None,
5547 None,
5548 vec![],
5549 )
5550 .await
5551 .unwrap();
5552 let shared = rt
5553 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5554 .await
5555 .unwrap();
5556
5557 let survivor = rt
5558 .link(
5559 &tok,
5560 into.id,
5561 shared.id,
5562 EdgeRelation::Annotates,
5563 1.0,
5564 Some(serde_json::json!({"source": "survivor"})),
5565 )
5566 .await
5567 .unwrap();
5568 let dropped = rt
5569 .link(
5570 &tok,
5571 from.id,
5572 shared.id,
5573 EdgeRelation::Annotates,
5574 0.4,
5575 Some(serde_json::json!({"source": "dropped"})),
5576 )
5577 .await
5578 .unwrap();
5579 let annotation = rt
5580 .link(
5581 &tok,
5582 annotator.id,
5583 dropped.id.into(),
5584 EdgeRelation::Annotates,
5585 0.8,
5586 Some(serde_json::json!({"why": "duplicate claim"})),
5587 )
5588 .await
5589 .unwrap();
5590 let nested_annotation = rt
5591 .link(
5592 &tok,
5593 nested_annotator.id,
5594 annotation.id.into(),
5595 EdgeRelation::Annotates,
5596 0.6,
5597 Some(serde_json::json!({"why": "nested duplicate claim"})),
5598 )
5599 .await
5600 .unwrap();
5601 rt.delete_edge(&tok, nested_annotation.id.into(), false)
5602 .await
5603 .unwrap();
5604
5605 let survivor_before = rt
5606 .get_edge_including_deleted(&tok, survivor.id.into())
5607 .await
5608 .unwrap()
5609 .expect("survivor edge exists");
5610 let dropped_before = rt
5611 .get_edge_including_deleted(&tok, dropped.id.into())
5612 .await
5613 .unwrap()
5614 .expect("dropped edge exists");
5615 let annotation_before = rt
5616 .get_edge_including_deleted(&tok, annotation.id.into())
5617 .await
5618 .unwrap()
5619 .expect("annotation edge exists");
5620 let nested_annotation_before = rt
5621 .get_edge_including_deleted(&tok, nested_annotation.id.into())
5622 .await
5623 .unwrap()
5624 .expect("nested annotation edge exists");
5625 let into_before = rt
5626 .get_note_including_deleted(&tok, into.id)
5627 .await
5628 .unwrap()
5629 .expect("into note exists");
5630 let from_before = rt
5631 .get_note_including_deleted(&tok, from.id)
5632 .await
5633 .unwrap()
5634 .expect("from note exists");
5635
5636 let summary = rt
5637 .merge_note(
5638 &tok,
5639 into.id,
5640 from.id,
5641 EntityDedupMergePolicy::PreferInto,
5642 ContentMergeStrategy::Append,
5643 true,
5644 )
5645 .await
5646 .unwrap();
5647
5648 let [conflict] = summary.edge_conflict_preimages.as_slice() else {
5649 panic!(
5650 "expected one note-merge edge conflict from the dry run, got {:?}",
5651 summary.edge_conflict_preimages
5652 );
5653 };
5654 assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
5655 assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
5656 assert_eq!(conflict.dropped_edge.source_id, from.id);
5657 assert_eq!(conflict.dropped_edge.weight, 0.4);
5658 assert_eq!(conflict.incident_edge_preimages.len(), 2);
5661 assert_eq!(
5662 conflict.incident_edge_preimages[0].id,
5663 Uuid::from(annotation.id)
5664 );
5665 assert!(
5666 conflict.incident_edge_preimages[0].deleted_at.is_none(),
5667 "the direct annotation was never soft-deleted"
5668 );
5669 assert_eq!(
5670 conflict.incident_edge_preimages[1].id,
5671 Uuid::from(nested_annotation.id)
5672 );
5673 assert!(
5674 conflict.incident_edge_preimages[1].deleted_at.is_some(),
5675 "dry-run preimage must retain the nested annotation's tombstone state"
5676 );
5677
5678 let survivor_after = rt
5679 .get_edge_including_deleted(&tok, survivor.id.into())
5680 .await
5681 .unwrap()
5682 .expect("dry run must not delete the survivor edge");
5683 let dropped_after = rt
5684 .get_edge_including_deleted(&tok, dropped.id.into())
5685 .await
5686 .unwrap()
5687 .expect("dry run must not delete the dropped edge");
5688 let annotation_after = rt
5689 .get_edge_including_deleted(&tok, annotation.id.into())
5690 .await
5691 .unwrap()
5692 .expect("dry run must not delete the cascaded annotation");
5693 let nested_annotation_after = rt
5694 .get_edge_including_deleted(&tok, nested_annotation.id.into())
5695 .await
5696 .unwrap()
5697 .expect("dry run must not delete the nested cascaded annotation");
5698 assert_eq!(
5699 serde_json::to_value(&survivor_before).unwrap(),
5700 serde_json::to_value(&survivor_after).unwrap(),
5701 "dry run must not mutate the surviving edge's row at all"
5702 );
5703 assert_eq!(
5704 serde_json::to_value(&dropped_before).unwrap(),
5705 serde_json::to_value(&dropped_after).unwrap(),
5706 "dry run must not mutate the would-be-dropped edge's row at all"
5707 );
5708 assert_eq!(
5709 serde_json::to_value(&annotation_before).unwrap(),
5710 serde_json::to_value(&annotation_after).unwrap(),
5711 "dry run must not mutate the incident annotation's row at all"
5712 );
5713 assert_eq!(
5714 serde_json::to_value(&nested_annotation_before).unwrap(),
5715 serde_json::to_value(&nested_annotation_after).unwrap(),
5716 "dry run must not mutate the nested incident annotation's row at all"
5717 );
5718
5719 let into_after = rt
5720 .get_note_including_deleted(&tok, into.id)
5721 .await
5722 .unwrap()
5723 .expect("into note must remain unmerged after a dry run");
5724 let from_after = rt
5725 .get_note_including_deleted(&tok, from.id)
5726 .await
5727 .unwrap()
5728 .expect("from note must not be deleted by a dry run");
5729 assert_eq!(
5730 serde_json::to_value(&into_before).unwrap(),
5731 serde_json::to_value(&into_after).unwrap(),
5732 "dry run must not mutate the into note's row at all"
5733 );
5734 assert_eq!(
5735 serde_json::to_value(&from_before).unwrap(),
5736 serde_json::to_value(&from_after).unwrap(),
5737 "dry run must not mutate the from note's row at all"
5738 );
5739 assert_eq!(from_after.status, from_before.status);
5740 assert_eq!(from_after.deleted_at, None);
5741
5742 let events = rt
5743 .events(&tok)
5744 .unwrap()
5745 .query_events(
5746 khive_storage::EventFilter {
5747 kinds: vec![EventKind::NoteMerged],
5748 ..Default::default()
5749 },
5750 khive_storage::types::PageRequest {
5751 offset: 0,
5752 limit: 10,
5753 },
5754 )
5755 .await
5756 .unwrap();
5757 assert!(
5758 events.items.is_empty(),
5759 "a dry run must not record a merge audit event"
5760 );
5761 }
5762
5763 #[tokio::test]
5768 async fn merge_note_preserves_note_to_note_epistemic_and_supersession_edges() {
5769 use khive_storage::EdgeRelation;
5770 let rt = rt();
5771 let tok = NamespaceToken::local();
5772
5773 let into = rt
5774 .create_note(&tok, "observation", None, "Into", None, None, vec![])
5775 .await
5776 .unwrap();
5777 let from = rt
5778 .create_note(&tok, "observation", None, "From", None, None, vec![])
5779 .await
5780 .unwrap();
5781 let superseded = rt
5782 .create_note(&tok, "observation", None, "Old", None, None, vec![])
5783 .await
5784 .unwrap();
5785 let claim = rt
5786 .create_note(&tok, "insight", None, "Claim", None, None, vec![])
5787 .await
5788 .unwrap();
5789 let counter = rt
5790 .create_note(&tok, "observation", None, "Counter", None, None, vec![])
5791 .await
5792 .unwrap();
5793
5794 rt.link(
5797 &tok,
5798 from.id,
5799 superseded.id,
5800 EdgeRelation::Supersedes,
5801 1.0,
5802 None,
5803 )
5804 .await
5805 .unwrap();
5806 rt.link(&tok, from.id, claim.id, EdgeRelation::Supports, 1.0, None)
5807 .await
5808 .unwrap();
5809 rt.link(&tok, counter.id, from.id, EdgeRelation::Refutes, 1.0, None)
5810 .await
5811 .unwrap();
5812
5813 let summary = rt
5814 .merge_note_with_reason(
5815 &tok,
5816 into.id,
5817 from.id,
5818 EntityDedupMergePolicy::PreferInto,
5819 ContentMergeStrategy::Append,
5820 false,
5821 None,
5822 )
5823 .await
5824 .unwrap();
5825
5826 assert_eq!(
5827 summary.edges_rewired, 3,
5828 "all three note→note edges must be rewired, not contract-dropped"
5829 );
5830 assert_eq!(
5831 summary.edges_contract_skipped, 0,
5832 "no valid note→note supersedes/supports/refutes edge may be dropped"
5833 );
5834
5835 for (src, tgt, rel) in [
5836 (into.id, superseded.id, EdgeRelation::Supersedes),
5837 (into.id, claim.id, EdgeRelation::Supports),
5838 (counter.id, into.id, EdgeRelation::Refutes),
5839 ] {
5840 let edges = rt
5841 .list_edges(
5842 &tok,
5843 crate::EdgeListFilter {
5844 source_id: Some(src),
5845 target_id: Some(tgt),
5846 relations: vec![rel],
5847 ..Default::default()
5848 },
5849 10,
5850 0,
5851 )
5852 .await
5853 .unwrap();
5854 assert_eq!(
5855 edges.len(),
5856 1,
5857 "rewired {rel:?} edge {src}→{tgt} must survive the merge; got {edges:?}"
5858 );
5859 }
5860 }
5861
5862 #[tokio::test]
5867 async fn merge_note_preserves_annotates_edges_targeting_edges_and_events() {
5868 use khive_storage::EdgeRelation;
5869 let rt = rt();
5870 let tok = NamespaceToken::local();
5871
5872 let a = rt
5874 .create_entity(&tok, "concept", None, "A", None, None, vec![])
5875 .await
5876 .unwrap();
5877 let b = rt
5878 .create_entity(&tok, "concept", None, "B", None, None, vec![])
5879 .await
5880 .unwrap();
5881 let annotated_edge = rt
5882 .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
5883 .await
5884 .unwrap();
5885
5886 let scrap_into = rt
5889 .create_note(&tok, "observation", None, "ScrapInto", None, None, vec![])
5890 .await
5891 .unwrap();
5892 let scrap_from = rt
5893 .create_note(&tok, "observation", None, "ScrapFrom", None, None, vec![])
5894 .await
5895 .unwrap();
5896 rt.merge_note_with_reason(
5897 &tok,
5898 scrap_into.id,
5899 scrap_from.id,
5900 EntityDedupMergePolicy::PreferInto,
5901 ContentMergeStrategy::Append,
5902 false,
5903 None,
5904 )
5905 .await
5906 .unwrap();
5907 let events = rt
5908 .events(&tok)
5909 .unwrap()
5910 .query_events(
5911 khive_storage::EventFilter {
5912 kinds: vec![EventKind::NoteMerged],
5913 ..Default::default()
5914 },
5915 khive_storage::types::PageRequest {
5916 offset: 0,
5917 limit: 1,
5918 },
5919 )
5920 .await
5921 .unwrap();
5922 let annotated_event_id = events.items[0].id;
5923
5924 let into = rt
5925 .create_note(&tok, "observation", None, "Into", None, None, vec![])
5926 .await
5927 .unwrap();
5928 let from = rt
5929 .create_note(&tok, "observation", None, "From", None, None, vec![])
5930 .await
5931 .unwrap();
5932
5933 rt.link(
5934 &tok,
5935 from.id,
5936 annotated_edge.id.0,
5937 EdgeRelation::Annotates,
5938 1.0,
5939 None,
5940 )
5941 .await
5942 .unwrap();
5943 rt.link(
5944 &tok,
5945 from.id,
5946 annotated_event_id,
5947 EdgeRelation::Annotates,
5948 1.0,
5949 None,
5950 )
5951 .await
5952 .unwrap();
5953
5954 let summary = rt
5955 .merge_note_with_reason(
5956 &tok,
5957 into.id,
5958 from.id,
5959 EntityDedupMergePolicy::PreferInto,
5960 ContentMergeStrategy::Append,
5961 false,
5962 None,
5963 )
5964 .await
5965 .unwrap();
5966
5967 assert_eq!(
5968 summary.edges_rewired, 2,
5969 "annotates edges targeting an edge and an event must be rewired"
5970 );
5971 assert_eq!(
5972 summary.edges_contract_skipped, 0,
5973 "no valid annotates edge may be dropped as contract-violating"
5974 );
5975
5976 for tgt in [annotated_edge.id.0, annotated_event_id] {
5977 let edges = rt
5978 .list_edges(
5979 &tok,
5980 crate::EdgeListFilter {
5981 source_id: Some(into.id),
5982 target_id: Some(tgt),
5983 relations: vec![EdgeRelation::Annotates],
5984 ..Default::default()
5985 },
5986 10,
5987 0,
5988 )
5989 .await
5990 .unwrap();
5991 assert_eq!(
5992 edges.len(),
5993 1,
5994 "rewired annotates edge onto target {tgt} must survive the merge; got {edges:?}"
5995 );
5996 }
5997 }
5998
5999 #[tokio::test]
6002 async fn merge_note_dry_run_predicts_edges_rewired() {
6003 use khive_storage::EdgeRelation;
6004 let rt = rt();
6005 let tok = NamespaceToken::local();
6006 let into = rt
6007 .create_note(&tok, "observation", None, "Into", None, None, vec![])
6008 .await
6009 .unwrap();
6010 let from = rt
6011 .create_note(&tok, "observation", None, "From", None, None, vec![])
6012 .await
6013 .unwrap();
6014 let shared = rt
6015 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6016 .await
6017 .unwrap();
6018 rt.link(&tok, from.id, shared.id, EdgeRelation::Annotates, 1.0, None)
6019 .await
6020 .unwrap();
6021
6022 let summary = rt
6023 .merge_note_with_reason(
6024 &tok,
6025 into.id,
6026 from.id,
6027 EntityDedupMergePolicy::PreferInto,
6028 ContentMergeStrategy::Append,
6029 true,
6030 None,
6031 )
6032 .await
6033 .unwrap();
6034 assert!(summary.dry_run);
6035 assert_eq!(
6036 summary.edges_rewired, 1,
6037 "note dry-run must predict the rewire count"
6038 );
6039
6040 let from_edges = rt
6041 .list_edges(
6042 &tok,
6043 crate::EdgeListFilter {
6044 source_id: Some(from.id),
6045 target_id: Some(shared.id),
6046 relations: vec![EdgeRelation::Annotates],
6047 ..Default::default()
6048 },
6049 10,
6050 0,
6051 )
6052 .await
6053 .unwrap();
6054 assert_eq!(from_edges.len(), 1, "dry-run must leave topology untouched");
6055 }
6056
6057 #[tokio::test]
6058 async fn merge_note_different_kinds_rejected() {
6059 let rt = rt();
6060 let tok = NamespaceToken::local();
6061 let into = rt
6062 .create_note(&tok, "observation", None, "Into", None, None, vec![])
6063 .await
6064 .unwrap();
6065 let from = rt
6066 .create_note(&tok, "decision", None, "From", None, None, vec![])
6067 .await
6068 .unwrap();
6069
6070 let result = rt
6071 .merge_note_with_reason(
6072 &tok,
6073 into.id,
6074 from.id,
6075 EntityDedupMergePolicy::PreferInto,
6076 ContentMergeStrategy::Append,
6077 false,
6078 None,
6079 )
6080 .await;
6081 assert!(result.is_err(), "merging different note kinds must fail");
6082 }
6083
6084 #[tokio::test]
6085 async fn merge_note_dry_run_leaves_notes_unchanged() {
6086 let rt = rt();
6087 let tok = NamespaceToken::local();
6088 let into = rt
6089 .create_note(
6090 &tok,
6091 "observation",
6092 None,
6093 "Into content",
6094 None,
6095 None,
6096 vec![],
6097 )
6098 .await
6099 .unwrap();
6100 let from = rt
6101 .create_note(
6102 &tok,
6103 "observation",
6104 None,
6105 "From content",
6106 None,
6107 None,
6108 vec![],
6109 )
6110 .await
6111 .unwrap();
6112 let into_id = into.id;
6113 let from_id = from.id;
6114
6115 let summary = rt
6116 .merge_note_with_reason(
6117 &tok,
6118 into_id,
6119 from_id,
6120 EntityDedupMergePolicy::PreferInto,
6121 ContentMergeStrategy::Append,
6122 true,
6123 None,
6124 )
6125 .await
6126 .unwrap();
6127
6128 assert!(summary.dry_run);
6129
6130 let store = rt.notes(&tok).unwrap();
6131 let into_after = store.get_note(into_id).await.unwrap().unwrap();
6132 let from_after = store.get_note(from_id).await.unwrap().unwrap();
6133 assert_eq!(
6134 into_after.content, "Into content",
6135 "dry_run must not mutate into-note"
6136 );
6137 assert_eq!(
6138 from_after.content, "From content",
6139 "dry_run must not mutate from-note"
6140 );
6141
6142 let events = rt
6143 .events(&tok)
6144 .unwrap()
6145 .query_events(
6146 khive_storage::EventFilter {
6147 kinds: vec![EventKind::NoteMerged],
6148 ..Default::default()
6149 },
6150 khive_storage::types::PageRequest {
6151 offset: 0,
6152 limit: 10,
6153 },
6154 )
6155 .await
6156 .unwrap();
6157 assert!(
6158 events.items.is_empty(),
6159 "dry_run=true must not append a NoteMerged event"
6160 );
6161 }
6162
6163 #[tokio::test]
6168 async fn merge_nameless_notes_fts_document_is_parity_correct() {
6169 use khive_storage::types::TextSearchRequest;
6170
6171 let rt = rt(); let tok = NamespaceToken::local();
6173
6174 let into = rt
6175 .create_note(
6176 &tok,
6177 "observation",
6178 None,
6179 "intosentinelzxq body",
6180 None,
6181 Some(serde_json::json!({"src": "into"})),
6182 vec![],
6183 )
6184 .await
6185 .expect("create into-note");
6186 let from = rt
6187 .create_note(
6188 &tok,
6189 "observation",
6190 None,
6191 "fromsentinelzxq body",
6192 None,
6193 None,
6194 vec![],
6195 )
6196 .await
6197 .expect("create from-note");
6198
6199 let into_id = into.id;
6200 let from_id = from.id;
6201
6202 rt.merge_note_with_reason(
6203 &tok,
6204 into_id,
6205 from_id,
6206 EntityDedupMergePolicy::PreferInto,
6207 ContentMergeStrategy::Append,
6208 false,
6209 None,
6210 )
6211 .await
6212 .expect("merge_note must succeed");
6213
6214 let note_store = rt.notes(&tok).expect("note store");
6215 let merged_note = note_store
6216 .get_note(into_id)
6217 .await
6218 .expect("get_note")
6219 .expect("merged note must exist");
6220
6221 let expected = note_fts_document(&merged_note);
6222
6223 let fts = rt.text_for_notes(&tok).expect("FTS store");
6224 let stored = fts
6225 .get_document("local", into_id)
6226 .await
6227 .expect("get_document must not error")
6228 .expect("FTS document must exist after merge");
6229
6230 assert_eq!(stored.subject_id, expected.subject_id, "subject_id");
6231 assert_eq!(
6232 stored.title, expected.title,
6233 "title (None for nameless note)"
6234 );
6235 assert_eq!(stored.body, expected.body, "body");
6236 assert_eq!(stored.namespace, expected.namespace, "namespace");
6237 assert_eq!(stored.kind, expected.kind, "kind");
6238
6239 assert!(
6240 stored.title.is_none(),
6241 "nameless merged note must have title=None in FTS (was NULL before fix)"
6242 );
6243
6244 let hits = fts
6246 .search(TextSearchRequest {
6247 query: "intosentinelzxq".to_string(),
6248 mode: khive_storage::types::TextQueryMode::Plain,
6249 filter: None,
6250 top_k: 10,
6251 snippet_chars: 0,
6252 })
6253 .await
6254 .expect("search");
6255 assert!(
6256 hits.iter().any(|h| h.subject_id == into_id),
6257 "merged note must be searchable by into-note content"
6258 );
6259 }
6260
6261 #[tokio::test]
6262 async fn update_edge_updates_properties() {
6263 use khive_storage::EdgeRelation;
6264 let rt = rt();
6265 let tok = NamespaceToken::local();
6266 let a = rt
6267 .create_entity(&tok, "concept", None, "A", None, None, vec![])
6268 .await
6269 .unwrap();
6270 let b = rt
6271 .create_entity(&tok, "concept", None, "B", None, None, vec![])
6272 .await
6273 .unwrap();
6274 let edge = rt
6275 .link(&tok, a.id, b.id, EdgeRelation::Extends, 0.5, None)
6276 .await
6277 .unwrap();
6278 let edge_id: Uuid = edge.id.into();
6279
6280 let updated = rt
6281 .update_edge(
6282 &tok,
6283 edge_id,
6284 EdgePatch {
6285 properties: Some(serde_json::json!({"source": "manual"})),
6286 ..Default::default()
6287 },
6288 )
6289 .await
6290 .unwrap();
6291
6292 assert_eq!(updated.metadata.as_ref().unwrap()["source"], "manual");
6293 assert!((updated.weight - 0.5).abs() < 0.001, "weight unchanged");
6294 }
6295
6296 #[tokio::test]
6300 async fn merge_entity_survives_shared_edge_to_third_party() {
6301 use khive_storage::EdgeRelation;
6302 let rt = rt();
6303 let tok = NamespaceToken::local();
6304
6305 let a = rt
6308 .create_entity(&tok, "concept", None, "A", None, None, vec![])
6309 .await
6310 .unwrap();
6311 let b = rt
6312 .create_entity(&tok, "concept", None, "B", None, None, vec![])
6313 .await
6314 .unwrap();
6315 let shared = rt
6316 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6317 .await
6318 .unwrap();
6319
6320 rt.link(&tok, a.id, shared.id, EdgeRelation::Extends, 1.0, None)
6323 .await
6324 .unwrap();
6325 rt.link(&tok, b.id, shared.id, EdgeRelation::Extends, 1.0, None)
6326 .await
6327 .unwrap();
6328
6329 let summary = rt
6330 .merge_entity_with_reason(
6331 &tok,
6332 a.id,
6333 b.id,
6334 crate::EntityDedupMergePolicy::PreferInto,
6335 ContentMergeStrategy::Append,
6336 false,
6337 None,
6338 )
6339 .await
6340 .expect(
6341 "C1: merge must succeed even when both entities share an edge to a third party",
6342 );
6343
6344 assert_eq!(summary.kept_id, a.id);
6345 assert_eq!(summary.removed_id, b.id);
6346 let a_edges = rt
6352 .list_edges(
6353 &tok,
6354 crate::EdgeListFilter {
6355 source_id: Some(a.id),
6356 target_id: Some(shared.id),
6357 relations: vec![EdgeRelation::Extends],
6358 ..Default::default()
6359 },
6360 10,
6361 0,
6362 )
6363 .await
6364 .unwrap();
6365 assert_eq!(
6366 a_edges.len(),
6367 1,
6368 "C1: exactly one live A→shared Extends edge must exist after merge; got: {a_edges:?}"
6369 );
6370
6371 let b_after = rt.entities(&tok).unwrap().get_entity(b.id).await.unwrap();
6373 assert!(
6374 b_after.is_none(),
6375 "C3: from_entity must be tombstoned (get_entity returns None for deleted) after merge; got: {b_after:?}"
6376 );
6377 }
6378
6379 #[tokio::test]
6383 async fn merge_entity_symmetric_conflict_preserves_survivor_fields() {
6384 use khive_storage::EdgeRelation;
6385 let rt = rt();
6386 let tok = NamespaceToken::local();
6387
6388 let a = rt
6389 .create_entity(&tok, "concept", None, "A", None, None, vec![])
6390 .await
6391 .unwrap();
6392 let b = rt
6393 .create_entity(&tok, "concept", None, "B", None, None, vec![])
6394 .await
6395 .unwrap();
6396 let shared = rt
6397 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6398 .await
6399 .unwrap();
6400
6401 let survivor_edge = rt
6402 .link(
6403 &tok,
6404 a.id,
6405 shared.id,
6406 EdgeRelation::Extends,
6407 1.0,
6408 Some(serde_json::json!({"source": "survivor"})),
6409 )
6410 .await
6411 .unwrap();
6412 rt.link(
6413 &tok,
6414 b.id,
6415 shared.id,
6416 EdgeRelation::Extends,
6417 0.3,
6418 Some(serde_json::json!({"source": "loser"})),
6419 )
6420 .await
6421 .unwrap();
6422
6423 rt.merge_entity_with_reason(
6424 &tok,
6425 a.id,
6426 b.id,
6427 crate::EntityDedupMergePolicy::PreferInto,
6428 ContentMergeStrategy::Append,
6429 false,
6430 None,
6431 )
6432 .await
6433 .expect("merge must succeed across the symmetric-edge collision");
6434
6435 let after = rt
6436 .get_edge(&tok, survivor_edge.id.into())
6437 .await
6438 .unwrap()
6439 .expect("survivor edge must still exist after merge");
6440 assert!(
6441 (after.weight - 1.0).abs() < 0.001,
6442 "survivor weight must be untouched by the dropped duplicate; got {}",
6443 after.weight
6444 );
6445 assert_eq!(
6446 after.metadata.as_ref().unwrap()["source"],
6447 "survivor",
6448 "survivor metadata must be untouched by the dropped duplicate; got {:?}",
6449 after.metadata
6450 );
6451 }
6452
6453 #[tokio::test]
6456 async fn merge_entity_symmetric_conflict_does_not_resurrect_soft_deleted_survivor() {
6457 use khive_storage::EdgeRelation;
6458 let rt = rt();
6459 let tok = NamespaceToken::local();
6460
6461 let a = rt
6462 .create_entity(&tok, "concept", None, "A", None, None, vec![])
6463 .await
6464 .unwrap();
6465 let b = rt
6466 .create_entity(&tok, "concept", None, "B", None, None, vec![])
6467 .await
6468 .unwrap();
6469 let shared = rt
6470 .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6471 .await
6472 .unwrap();
6473
6474 let survivor_edge = rt
6475 .link(&tok, a.id, shared.id, EdgeRelation::Extends, 1.0, None)
6476 .await
6477 .unwrap();
6478 rt.delete_edge(&tok, survivor_edge.id.into(), false)
6479 .await
6480 .unwrap();
6481 rt.link(&tok, b.id, shared.id, EdgeRelation::Extends, 0.5, None)
6482 .await
6483 .unwrap();
6484
6485 rt.merge_entity_with_reason(
6486 &tok,
6487 a.id,
6488 b.id,
6489 crate::EntityDedupMergePolicy::PreferInto,
6490 ContentMergeStrategy::Append,
6491 false,
6492 None,
6493 )
6494 .await
6495 .expect("merge must succeed even when the surviving edge is soft-deleted");
6496
6497 let after = rt
6498 .get_edge_including_deleted(&tok, survivor_edge.id.into())
6499 .await
6500 .unwrap()
6501 .expect("survivor edge row must still exist after merge");
6502 assert!(
6503 after.deleted_at.is_some(),
6504 "soft-deleted survivor must stay soft-deleted after merge collision; got: {after:?}"
6505 );
6506 }
6507
6508 #[tokio::test]
6512 async fn merge_entity_cross_kind_rejected_at_runtime() {
6513 let rt = rt();
6514 let tok = NamespaceToken::local();
6515
6516 let concept = rt
6517 .create_entity(&tok, "concept", None, "H2Concept", None, None, vec![])
6518 .await
6519 .unwrap();
6520 let project = rt
6521 .create_entity(&tok, "project", None, "H2Project", None, None, vec![])
6522 .await
6523 .unwrap();
6524
6525 let err = rt
6526 .merge_entity_with_reason(
6527 &tok,
6528 concept.id,
6529 project.id,
6530 crate::EntityDedupMergePolicy::PreferInto,
6531 ContentMergeStrategy::Append,
6532 false,
6533 None,
6534 )
6535 .await
6536 .expect_err("H2: cross-kind merge must be rejected by runtime");
6537 assert!(
6538 matches!(err, crate::RuntimeError::InvalidInput(_)),
6539 "H2: expected InvalidInput, got: {err:?}"
6540 );
6541
6542 let concept_after = rt.get_entity(&tok, concept.id).await;
6543 let project_after = rt.get_entity(&tok, project.id).await;
6544 assert!(
6545 concept_after.is_ok(),
6546 "H2: concept must remain live after rejected merge; got: {concept_after:?}"
6547 );
6548 assert!(
6549 project_after.is_ok(),
6550 "H2: project must remain live after rejected merge; got: {project_after:?}"
6551 );
6552 }
6553
6554 #[tokio::test]
6556 async fn merge_entity_same_kind_succeeds() {
6557 let rt = rt();
6558 let tok = NamespaceToken::local();
6559
6560 let c1 = rt
6561 .create_entity(&tok, "concept", None, "Concept1", None, None, vec![])
6562 .await
6563 .unwrap();
6564 let c2 = rt
6565 .create_entity(&tok, "concept", None, "Concept2", None, None, vec![])
6566 .await
6567 .unwrap();
6568
6569 let summary = rt
6570 .merge_entity_with_reason(
6571 &tok,
6572 c1.id,
6573 c2.id,
6574 crate::EntityDedupMergePolicy::PreferInto,
6575 ContentMergeStrategy::Append,
6576 false,
6577 None,
6578 )
6579 .await
6580 .expect("same-kind merge must succeed");
6581 assert_eq!(summary.kept_id, c1.id);
6582 assert_eq!(summary.removed_id, c2.id);
6583
6584 let c2_after = rt.entities(&tok).unwrap().get_entity(c2.id).await.unwrap();
6585 assert!(c2_after.is_none(), "from_entity must be tombstoned");
6586 }
6587
6588 #[tokio::test]
6589 async fn merge_entity_explicit_policy_rereads_names_before_commit() {
6590 let rt = rt();
6591 let tok = NamespaceToken::local();
6592
6593 let into = rt
6594 .create_entity(
6595 &tok,
6596 "concept",
6597 None,
6598 "Transactional Guard",
6599 None,
6600 None,
6601 vec![],
6602 )
6603 .await
6604 .unwrap();
6605 let from = rt
6606 .create_entity(
6607 &tok,
6608 "concept",
6609 None,
6610 "Transactional Guard",
6611 None,
6612 None,
6613 vec![],
6614 )
6615 .await
6616 .unwrap();
6617
6618 validate_entity_merge_floor(&into, &from)
6619 .expect("the handler's fast-path validation would initially pass");
6620 let renamed_into = rt
6621 .update_entity(
6622 &tok,
6623 into.id,
6624 EntityPatch {
6625 name: Some("Unrelated Renamed Target".to_string()),
6626 ..Default::default()
6627 },
6628 )
6629 .await
6630 .unwrap();
6631 let expected = validate_entity_merge_floor(&renamed_into, &from)
6632 .expect_err("the renamed transactional state must violate the name guard");
6633 let RuntimeError::Khive(expected) = entity_merge_guard_error(expected) else {
6634 unreachable!("merge guard errors are structured Khive errors")
6635 };
6636
6637 let err = rt
6638 .merge_entity_with_reason_and_force(
6639 &tok,
6640 into.id,
6641 from.id,
6642 EntityDedupMergePolicy::PreferInto,
6643 ContentMergeStrategy::Append,
6644 false,
6645 None,
6646 false,
6647 )
6648 .await
6649 .expect_err("the explicit non-forced path must validate its transactional reread");
6650 let RuntimeError::Khive(err) = err else {
6651 panic!("expected a structured merge-guard conflict, got {err:?}");
6652 };
6653 assert_eq!(err.kind(), expected.kind());
6654 assert_eq!(err.message(), expected.message());
6655 assert_eq!(err.code(), expected.code());
6656 assert_eq!(err.details(), expected.details());
6657 assert!(
6658 rt.get_entity(&tok, from.id).await.is_ok(),
6659 "a refused merge must leave the source entity live"
6660 );
6661 }
6662
6663 #[tokio::test]
6666 async fn merge_note_cross_namespace_either_id_returns_not_found() {
6667 use crate::error::RuntimeError;
6668 use crate::Namespace;
6669
6670 let rt = rt();
6671 let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6672 let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6673
6674 let into_a = rt
6675 .create_note(&ns_a, "observation", None, "Into A", None, None, vec![])
6676 .await
6677 .unwrap();
6678 let from_a = rt
6679 .create_note(&ns_a, "observation", None, "From A", None, None, vec![])
6680 .await
6681 .unwrap();
6682 let note_b = rt
6683 .create_note(&ns_b, "observation", None, "Note B", None, None, vec![])
6684 .await
6685 .unwrap();
6686
6687 let foreign_into = rt
6689 .merge_note_with_reason(
6690 &ns_a,
6691 note_b.id,
6692 from_a.id,
6693 EntityDedupMergePolicy::PreferInto,
6694 ContentMergeStrategy::Append,
6695 false,
6696 None,
6697 )
6698 .await;
6699 assert!(
6700 matches!(foreign_into, Err(RuntimeError::NotFound(_))),
6701 "foreign into_id must be denied before merge, got {foreign_into:?}"
6702 );
6703
6704 let foreign_from = rt
6706 .merge_note_with_reason(
6707 &ns_a,
6708 into_a.id,
6709 note_b.id,
6710 EntityDedupMergePolicy::PreferInto,
6711 ContentMergeStrategy::Append,
6712 false,
6713 None,
6714 )
6715 .await;
6716 assert!(
6717 matches!(foreign_from, Err(RuntimeError::NotFound(_))),
6718 "foreign from_id must be denied before merge, got {foreign_from:?}"
6719 );
6720 }
6721
6722 #[tokio::test]
6725 async fn update_entity_cross_namespace_succeeds() {
6726 use crate::Namespace;
6727
6728 let rt = rt();
6729 let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6730 let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6731
6732 let entity = rt
6733 .create_entity(
6734 &ns_a,
6735 "concept",
6736 None,
6737 "Alpha",
6738 Some("original"),
6739 None,
6740 vec![],
6741 )
6742 .await
6743 .unwrap();
6744
6745 let result = rt
6746 .update_entity(
6747 &ns_b,
6748 entity.id,
6749 EntityPatch {
6750 name: Some("Updated".into()),
6751 ..Default::default()
6752 },
6753 )
6754 .await;
6755
6756 assert!(
6757 result.is_ok(),
6758 "cross-namespace update must succeed in shared-brain OSS; got {result:?}"
6759 );
6760 assert_eq!(result.unwrap().name, "Updated");
6761 }
6762
6763 #[tokio::test]
6767 async fn merge_entity_cross_namespace_ids_fail_at_sql_layer() {
6768 use crate::Namespace;
6769
6770 let rt = rt();
6771 let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6772 let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6773
6774 let into_a = rt
6775 .create_entity(&ns_a, "concept", None, "Into A", None, None, vec![])
6776 .await
6777 .unwrap();
6778 let from_a = rt
6779 .create_entity(&ns_a, "concept", None, "From A", None, None, vec![])
6780 .await
6781 .unwrap();
6782 let foreign_b = rt
6783 .create_entity(&ns_b, "concept", None, "Foreign B", None, None, vec![])
6784 .await
6785 .unwrap();
6786
6787 let foreign_into = rt
6789 .merge_entity_with_reason(
6790 &ns_a,
6791 foreign_b.id,
6792 from_a.id,
6793 EntityDedupMergePolicy::PreferInto,
6794 ContentMergeStrategy::Append,
6795 false,
6796 None,
6797 )
6798 .await;
6799 assert!(
6800 foreign_into.is_err(),
6801 "cross-namespace into_id must still fail at SQL layer; got {foreign_into:?}"
6802 );
6803
6804 let foreign_from = rt
6806 .merge_entity_with_reason(
6807 &ns_a,
6808 into_a.id,
6809 foreign_b.id,
6810 EntityDedupMergePolicy::PreferInto,
6811 ContentMergeStrategy::Append,
6812 false,
6813 None,
6814 )
6815 .await;
6816 assert!(
6817 foreign_from.is_err(),
6818 "cross-namespace from_id must still fail at SQL layer; got {foreign_from:?}"
6819 );
6820
6821 assert!(rt.get_entity(&ns_a, into_a.id).await.is_ok());
6823 assert!(rt.get_entity(&ns_a, from_a.id).await.is_ok());
6824 assert!(rt.get_entity(&ns_b, foreign_b.id).await.is_ok());
6825 }
6826
6827 #[test]
6830 fn entity_fts_document_with_description() {
6831 let mut entity = Entity::new("local", "concept", "MyEntity");
6832 entity = entity.with_description("some description text");
6833 let doc = entity_fts_document(&entity);
6834 assert_eq!(doc.subject_id, entity.id);
6835 assert_eq!(doc.namespace, "local");
6836 assert_eq!(doc.title.as_deref(), Some("MyEntity"));
6837 assert_eq!(doc.body, "MyEntity some description text");
6838 assert_eq!(doc.kind, khive_types::SubstrateKind::Entity);
6839 }
6840
6841 #[test]
6842 fn entity_fts_document_without_description() {
6843 let entity = Entity::new("local", "concept", "NameOnly");
6844 let doc = entity_fts_document(&entity);
6845 assert_eq!(doc.title.as_deref(), Some("NameOnly"));
6846 assert_eq!(doc.body, "NameOnly");
6847 }
6848
6849 #[test]
6850 fn entity_fts_document_empty_description_uses_name_only() {
6851 let mut entity = Entity::new("local", "concept", "TitleOnly");
6852 entity = entity.with_description("");
6853 let doc = entity_fts_document(&entity);
6854 assert_eq!(
6855 doc.body, "TitleOnly",
6856 "empty description must not be appended"
6857 );
6858 }
6859
6860 #[tokio::test]
6864 async fn entity_fts_document_matches_runtime_create_path() {
6865 let rt = rt();
6866 let tok = NamespaceToken::local();
6867
6868 let entity = rt
6869 .create_entity(
6870 &tok,
6871 "concept",
6872 None,
6873 "CrossPathTitle",
6874 Some("cross path description body"),
6875 Some(serde_json::json!({"key": "val"})),
6876 vec!["tag1".to_string()],
6877 )
6878 .await
6879 .expect("create_entity");
6880
6881 let fts = rt.text(&tok).expect("FTS store");
6882 let stored = fts
6883 .get_document("local", entity.id)
6884 .await
6885 .expect("get_document")
6886 .expect("document must exist after create_entity");
6887
6888 let expected = entity_fts_document(&entity);
6889
6890 assert_eq!(stored.subject_id, expected.subject_id, "subject_id");
6891 assert_eq!(stored.kind, expected.kind, "kind");
6892 assert_eq!(stored.title, expected.title, "title");
6893 assert_eq!(stored.body, expected.body, "body");
6894 assert_eq!(stored.namespace, expected.namespace, "namespace");
6895 }
6896
6897 #[tokio::test]
6900 async fn entity_fts_document_matches_runtime_update_path() {
6901 let rt = rt();
6902 let tok = NamespaceToken::local();
6903
6904 let entity = rt
6905 .create_entity(
6906 &tok,
6907 "concept",
6908 None,
6909 "OldName",
6910 Some("old desc"),
6911 None,
6912 vec![],
6913 )
6914 .await
6915 .expect("create_entity");
6916
6917 let updated = rt
6918 .update_entity(
6919 &tok,
6920 entity.id,
6921 EntityPatch {
6922 name: Some("NewName".to_string()),
6923 description: Some(Some("new desc".to_string())),
6924 ..Default::default()
6925 },
6926 )
6927 .await
6928 .expect("update_entity");
6929
6930 let fts = rt.text(&tok).expect("FTS store");
6931 let stored = fts
6932 .get_document("local", updated.id)
6933 .await
6934 .expect("get_document")
6935 .expect("document must exist after update_entity");
6936
6937 let expected = entity_fts_document(&updated);
6938
6939 assert_eq!(stored.title, expected.title, "title after update");
6940 assert_eq!(stored.body, expected.body, "body after update");
6941 }
6942
6943 struct MergeTestVecService {
6949 dims: usize,
6950 }
6951
6952 #[async_trait::async_trait]
6953 impl lattice_embed::EmbeddingService for MergeTestVecService {
6954 async fn embed(
6955 &self,
6956 texts: &[String],
6957 _model: lattice_embed::EmbeddingModel,
6958 ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
6959 Ok(texts.iter().map(|_| vec![1.0_f32; self.dims]).collect())
6960 }
6961
6962 fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
6963 true
6964 }
6965
6966 fn name(&self) -> &'static str {
6967 "merge-test-const-vec"
6968 }
6969 }
6970
6971 struct MergeTestVecProvider {
6972 provider_name: String,
6973 dims: usize,
6974 }
6975
6976 impl MergeTestVecProvider {
6977 fn new(name: &str, dims: usize) -> Self {
6978 Self {
6979 provider_name: name.to_owned(),
6980 dims,
6981 }
6982 }
6983 }
6984
6985 #[async_trait::async_trait]
6986 impl crate::embedder_registry::EmbedderProvider for MergeTestVecProvider {
6987 fn name(&self) -> &str {
6988 &self.provider_name
6989 }
6990
6991 fn dimensions(&self) -> usize {
6992 self.dims
6993 }
6994
6995 async fn build(
6996 &self,
6997 ) -> crate::error::RuntimeResult<std::sync::Arc<dyn lattice_embed::EmbeddingService>>
6998 {
6999 Ok(std::sync::Arc::new(MergeTestVecService { dims: self.dims }))
7000 }
7001 }
7002
7003 #[tokio::test]
7004 async fn entity_reindex_with_captured_merge_plan_excludes_late_model() {
7005 const DIMS: usize = 4;
7006 const PLANNED: &str = "merge-entity-plan-existing";
7007 const LATE: &str = "merge-entity-plan-late";
7008 let rt = KhiveRuntime::memory().unwrap();
7009 let ns = crate::Namespace::parse("merge-entity-plan-snapshot").unwrap();
7010 let tok = NamespaceToken::for_namespace(ns);
7011 let entity = rt
7012 .create_entity(
7013 &tok,
7014 "concept",
7015 None,
7016 "CapturedEntityPlan",
7017 Some("full source remains indexed"),
7018 None,
7019 vec![],
7020 )
7021 .await
7022 .expect("create entity before registering embedders");
7023
7024 rt.register_embedder(MergeTestVecProvider::new(PLANNED, DIMS));
7025 let embedding_plan = EmbeddingModelPlan::capture(&rt);
7026 rt.register_embedder(MergeTestVecProvider::new(LATE, DIMS));
7027
7028 rt.reindex_entity_with_plan(&tok, &entity, &embedding_plan)
7029 .await
7030 .expect("reindex entity with captured merge plan");
7031
7032 assert_eq!(embedding_plan.model_names().len(), 1);
7033 assert_eq!(embedding_plan.model_names()[0].as_str(), PLANNED);
7034 assert_eq!(
7035 rt.vectors_for_model(&tok, PLANNED)
7036 .unwrap()
7037 .count()
7038 .await
7039 .unwrap(),
7040 1
7041 );
7042 assert_eq!(
7043 rt.vectors_for_model(&tok, LATE)
7044 .unwrap()
7045 .count()
7046 .await
7047 .unwrap(),
7048 0,
7049 "a provider registered after plan capture must not join survivor reindex"
7050 );
7051 }
7052
7053 #[tokio::test]
7054 async fn note_reindex_with_captured_merge_plan_excludes_late_model() {
7055 const DIMS: usize = 4;
7056 const PLANNED: &str = "merge-note-plan-existing";
7057 const LATE: &str = "merge-note-plan-late";
7058 let rt = KhiveRuntime::memory().unwrap();
7059 let ns = crate::Namespace::parse("merge-note-plan-snapshot").unwrap();
7060 let tok = NamespaceToken::for_namespace(ns);
7061 let note = rt
7062 .create_note(
7063 &tok,
7064 "observation",
7065 None,
7066 "full note source remains indexed",
7067 None,
7068 None,
7069 vec![],
7070 )
7071 .await
7072 .expect("create note before registering embedders");
7073
7074 rt.register_embedder(MergeTestVecProvider::new(PLANNED, DIMS));
7075 let embedding_plan = EmbeddingModelPlan::capture(&rt);
7076 rt.register_embedder(MergeTestVecProvider::new(LATE, DIMS));
7077
7078 rt.reindex_note_with_plan(&tok, ¬e, &embedding_plan)
7079 .await
7080 .expect("reindex note with captured merge plan");
7081
7082 assert_eq!(embedding_plan.model_names().len(), 1);
7083 assert_eq!(embedding_plan.model_names()[0].as_str(), PLANNED);
7084 assert_eq!(
7085 rt.vectors_for_model(&tok, PLANNED)
7086 .unwrap()
7087 .count()
7088 .await
7089 .unwrap(),
7090 1
7091 );
7092 assert_eq!(
7093 rt.vectors_for_model(&tok, LATE)
7094 .unwrap()
7095 .count()
7096 .await
7097 .unwrap(),
7098 0,
7099 "a provider registered after plan capture must not join survivor reindex"
7100 );
7101 }
7102
7103 #[tokio::test]
7109 async fn merge_entity_clears_vectors_from_all_registered_models() {
7110 const DIMS: usize = 4;
7111 let rt = KhiveRuntime::memory().unwrap();
7112 rt.register_embedder(MergeTestVecProvider::new("merge-vec-a", DIMS));
7113 rt.register_embedder(MergeTestVecProvider::new("merge-vec-b", DIMS));
7114
7115 let ns_str = "merge-entity-vec-cleanup";
7116 let ns = crate::Namespace::parse(ns_str).unwrap();
7117 let tok = NamespaceToken::for_namespace(ns);
7118
7119 let into_e = rt
7120 .create_entity(
7121 &tok,
7122 "concept",
7123 None,
7124 "IntoVecEntity",
7125 Some("desc a"),
7126 None,
7127 vec![],
7128 )
7129 .await
7130 .expect("create into");
7131 let from_e = rt
7132 .create_entity(
7133 &tok,
7134 "concept",
7135 None,
7136 "FromVecEntity",
7137 Some("desc b"),
7138 None,
7139 vec![],
7140 )
7141 .await
7142 .expect("create from");
7143
7144 let vs_a = rt.vectors_for_model(&tok, "merge-vec-a").unwrap();
7146 let vs_b = rt.vectors_for_model(&tok, "merge-vec-b").unwrap();
7147 use khive_storage::types::VectorSearchRequest;
7148 let query = vec![1.0_f32; DIMS];
7149 let pre_a = vs_a
7150 .search(VectorSearchRequest {
7151 query_vectors: vec![query.clone()],
7152 top_k: 100,
7153 namespace: Some(ns_str.to_string()),
7154 kind: Some(khive_types::SubstrateKind::Entity),
7155 embedding_model: Some("merge-vec-a".to_string()),
7156 filter: None,
7157 backend_hints: None,
7158 })
7159 .await
7160 .unwrap();
7161 assert!(
7162 pre_a.iter().any(|h| h.subject_id == into_e.id)
7163 && pre_a.iter().any(|h| h.subject_id == from_e.id),
7164 "both entities must be in model-a before merge; got {pre_a:?}"
7165 );
7166
7167 let pre_b = vs_b
7170 .search(VectorSearchRequest {
7171 query_vectors: vec![query.clone()],
7172 top_k: 100,
7173 namespace: Some(ns_str.to_string()),
7174 kind: Some(khive_types::SubstrateKind::Entity),
7175 embedding_model: Some("merge-vec-b".to_string()),
7176 filter: None,
7177 backend_hints: None,
7178 })
7179 .await
7180 .unwrap();
7181 assert!(
7182 pre_b.iter().any(|h| h.subject_id == into_e.id)
7183 && pre_b.iter().any(|h| h.subject_id == from_e.id),
7184 "both entities must be in model-b before merge; got {pre_b:?}"
7185 );
7186
7187 rt.merge_entity_with_reason(
7188 &tok,
7189 into_e.id,
7190 from_e.id,
7191 EntityDedupMergePolicy::PreferInto,
7192 ContentMergeStrategy::Append,
7193 false,
7194 None,
7195 )
7196 .await
7197 .expect("merge_entity");
7198
7199 let post_a = vs_a
7200 .search(VectorSearchRequest {
7201 query_vectors: vec![query.clone()],
7202 top_k: 100,
7203 namespace: Some(ns_str.to_string()),
7204 kind: Some(khive_types::SubstrateKind::Entity),
7205 embedding_model: Some("merge-vec-a".to_string()),
7206 filter: None,
7207 backend_hints: None,
7208 })
7209 .await
7210 .unwrap();
7211 let from_ids_a: Vec<_> = post_a
7212 .iter()
7213 .filter(|h| h.subject_id == from_e.id)
7214 .collect();
7215 assert!(
7216 from_ids_a.is_empty(),
7217 "from_id must have no vectors in model-a after merge; got {from_ids_a:?}"
7218 );
7219
7220 let post_b = vs_b
7221 .search(VectorSearchRequest {
7222 query_vectors: vec![query],
7223 top_k: 100,
7224 namespace: Some(ns_str.to_string()),
7225 kind: Some(khive_types::SubstrateKind::Entity),
7226 embedding_model: Some("merge-vec-b".to_string()),
7227 filter: None,
7228 backend_hints: None,
7229 })
7230 .await
7231 .unwrap();
7232 let from_ids_b: Vec<_> = post_b
7233 .iter()
7234 .filter(|h| h.subject_id == from_e.id)
7235 .collect();
7236 assert!(
7237 from_ids_b.is_empty(),
7238 "from_id must have no vectors in model-b after merge; got {from_ids_b:?}"
7239 );
7240 }
7241
7242 #[tokio::test]
7248 async fn merge_note_clears_vectors_from_all_registered_models() {
7249 const DIMS: usize = 4;
7250 let rt = KhiveRuntime::memory().unwrap();
7251 rt.register_embedder(MergeTestVecProvider::new("merge-note-vec-a", DIMS));
7252 rt.register_embedder(MergeTestVecProvider::new("merge-note-vec-b", DIMS));
7253
7254 let ns_str = "merge-note-vec-cleanup";
7255 let ns = crate::Namespace::parse(ns_str).unwrap();
7256 let tok = NamespaceToken::for_namespace(ns);
7257
7258 let into_n = rt
7259 .create_note(
7260 &tok,
7261 "observation",
7262 None,
7263 "IntoVecNote content",
7264 None,
7265 None,
7266 vec![],
7267 )
7268 .await
7269 .expect("create into note");
7270 let from_n = rt
7271 .create_note(
7272 &tok,
7273 "observation",
7274 None,
7275 "FromVecNote content",
7276 None,
7277 None,
7278 vec![],
7279 )
7280 .await
7281 .expect("create from note");
7282
7283 let vs_a = rt.vectors_for_model(&tok, "merge-note-vec-a").unwrap();
7284 let vs_b = rt.vectors_for_model(&tok, "merge-note-vec-b").unwrap();
7285 use khive_storage::types::VectorSearchRequest;
7286 let query = vec![1.0_f32; DIMS];
7287
7288 let pre_a = vs_a
7289 .search(VectorSearchRequest {
7290 query_vectors: vec![query.clone()],
7291 top_k: 100,
7292 namespace: Some(ns_str.to_string()),
7293 kind: Some(khive_types::SubstrateKind::Note),
7294 embedding_model: Some("merge-note-vec-a".to_string()),
7295 filter: None,
7296 backend_hints: None,
7297 })
7298 .await
7299 .unwrap();
7300 assert!(
7301 pre_a.iter().any(|h| h.subject_id == into_n.id)
7302 && pre_a.iter().any(|h| h.subject_id == from_n.id),
7303 "both notes must be in model-a before merge; got {pre_a:?}"
7304 );
7305
7306 let pre_b = vs_b
7309 .search(VectorSearchRequest {
7310 query_vectors: vec![query.clone()],
7311 top_k: 100,
7312 namespace: Some(ns_str.to_string()),
7313 kind: Some(khive_types::SubstrateKind::Note),
7314 embedding_model: Some("merge-note-vec-b".to_string()),
7315 filter: None,
7316 backend_hints: None,
7317 })
7318 .await
7319 .unwrap();
7320 assert!(
7321 pre_b.iter().any(|h| h.subject_id == into_n.id)
7322 && pre_b.iter().any(|h| h.subject_id == from_n.id),
7323 "both notes must be in model-b before merge; got {pre_b:?}"
7324 );
7325
7326 rt.merge_note_with_reason(
7327 &tok,
7328 into_n.id,
7329 from_n.id,
7330 EntityDedupMergePolicy::PreferInto,
7331 ContentMergeStrategy::PreferInto,
7332 false,
7333 None,
7334 )
7335 .await
7336 .expect("merge_note");
7337
7338 let post_a = vs_a
7339 .search(VectorSearchRequest {
7340 query_vectors: vec![query.clone()],
7341 top_k: 100,
7342 namespace: Some(ns_str.to_string()),
7343 kind: Some(khive_types::SubstrateKind::Note),
7344 embedding_model: Some("merge-note-vec-a".to_string()),
7345 filter: None,
7346 backend_hints: None,
7347 })
7348 .await
7349 .unwrap();
7350 let from_ids_a: Vec<_> = post_a
7351 .iter()
7352 .filter(|h| h.subject_id == from_n.id)
7353 .collect();
7354 assert!(
7355 from_ids_a.is_empty(),
7356 "from_id must have no vectors in model-a after merge; got {from_ids_a:?}"
7357 );
7358
7359 let post_b = vs_b
7360 .search(VectorSearchRequest {
7361 query_vectors: vec![query],
7362 top_k: 100,
7363 namespace: Some(ns_str.to_string()),
7364 kind: Some(khive_types::SubstrateKind::Note),
7365 embedding_model: Some("merge-note-vec-b".to_string()),
7366 filter: None,
7367 backend_hints: None,
7368 })
7369 .await
7370 .unwrap();
7371 let from_ids_b: Vec<_> = post_b
7372 .iter()
7373 .filter(|h| h.subject_id == from_n.id)
7374 .collect();
7375 assert!(
7376 from_ids_b.is_empty(),
7377 "from_id must have no vectors in model-b after merge; got {from_ids_b:?}"
7378 );
7379 }
7380
7381 #[tokio::test]
7384 async fn entity_fts_document_matches_runtime_merge_path() {
7385 let rt = rt();
7386 let tok = NamespaceToken::local();
7387
7388 let into_e = rt
7389 .create_entity(
7390 &tok,
7391 "concept",
7392 None,
7393 "IntoEntity",
7394 Some("into desc"),
7395 None,
7396 vec![],
7397 )
7398 .await
7399 .expect("create into");
7400 let from_e = rt
7401 .create_entity(
7402 &tok,
7403 "concept",
7404 None,
7405 "FromEntity",
7406 Some("from desc"),
7407 None,
7408 vec![],
7409 )
7410 .await
7411 .expect("create from");
7412
7413 let summary = rt
7414 .merge_entity_with_reason(
7415 &tok,
7416 into_e.id,
7417 from_e.id,
7418 EntityDedupMergePolicy::PreferInto,
7419 ContentMergeStrategy::Append,
7420 false,
7421 None,
7422 )
7423 .await
7424 .expect("merge_entity");
7425
7426 let kept = rt
7427 .get_entity(&tok, summary.kept_id)
7428 .await
7429 .expect("get kept");
7430
7431 let fts = rt.text(&tok).expect("FTS store");
7432 let stored = fts
7433 .get_document("local", kept.id)
7434 .await
7435 .expect("get_document")
7436 .expect("FTS document must exist for kept entity after merge");
7437
7438 let expected = entity_fts_document(&kept);
7439
7440 assert_eq!(stored.title, expected.title, "title after merge");
7441 assert_eq!(stored.body, expected.body, "body after merge");
7442 }
7443}