1#[cfg(test)]
2use super::race_seam;
3use super::{
4 entity_fts_document, map_merge_entity_storage_error, merge_entity_sql, merge_properties,
5 stale_entity_snapshot_error, Any, AtomicUnitOp, ContentMergeStrategy, EmbeddingModelPlan,
6 Entity, EntityDedupMergePolicy, EntityMergeValidation, EntityPatch, EventAttribution,
7 EventKind, HashMap, KhiveRuntime, MergeEventContext, MergeSqlError, MergeSummary,
8 MergeTxLimits, NamespaceToken, RuntimeError, RuntimeResult, RuntimeWriteOperation,
9 SqlStatement, SqlValue, SqliteError, SubstrateKind, Uuid, Value,
10};
11
12use super::entity_pending_index::EntityUpdateReport;
13use crate::secret_gate_finalizer::entity_admission::{
14 EntityAdmission, OrdinaryEntityUpdateContext,
15};
16use crate::EntityCandidateMutation;
17
18#[derive(Clone, Copy)]
19enum EntityUpdateRoute<'a> {
20 ReservationOnly,
21 OrdinaryConstructor(&'a OrdinaryEntityUpdateContext),
22}
23
24struct PreparedEntityUpdate {
25 entity: Entity,
26 reindex_required: bool,
27 changed_fields: Vec<&'static str>,
28 expected_updated_at: i64,
29 expected_deleted_at: Option<i64>,
30 original: Entity,
31}
32
33impl KhiveRuntime {
34 pub(crate) async fn validate_canonical_entity_patch(
35 &self,
36 token: &NamespaceToken,
37 current: &Entity,
38 mut patch: EntityPatch,
39 ) -> RuntimeResult<EntityPatch> {
40 crate::atomic_prepare::canonical_refuse_registry_tags(¤t.tags, "update")?;
41 if let Some(name) = &patch.name {
42 if name.trim().is_empty() {
43 return Err(RuntimeError::InvalidInput("name must not be empty".into()));
44 }
45 crate::secret_gate::check_at(name, "entity", "name")?;
46 }
47 if let Some(Some(description)) = &patch.description {
48 crate::secret_gate::check_at(description, "entity", "description")?;
49 }
50 if let Some(properties) = &patch.properties {
51 crate::secret_gate::check_json_at(properties, "entity", "properties")?;
52 }
53 if let Some(tags) = &patch.tags {
54 crate::atomic_prepare::canonical_refuse_registry_tags(tags, "update")?;
55 crate::secret_gate::check_tags_at(tags, "entity", "tags")?;
56 }
57 if let Some(Some(entity_type)) = &patch.entity_type {
58 patch.entity_type =
59 Some(self.validate_entity_type_for_kind(¤t.kind, Some(entity_type))?);
60 }
61 if let Some(properties) = &patch.properties {
64 crate::secret_gate::strip_reserved_echo(
65 &mut properties.clone(),
66 current.properties.as_ref(),
67 )?;
68 }
69 let mut projected = current.clone();
70 Self::apply_entity_patch_fields(&mut projected, patch.clone(), &[], true);
71 if let Some(hook) = self.entity_kind_hook(¤t.kind) {
72 hook.validate_entity_update(self, token, &projected, projected.properties.as_ref())
73 .await?;
74 }
75 Ok(patch)
76 }
77
78 pub(crate) fn apply_entity_patch_fields(
79 entity: &mut Entity,
80 patch: EntityPatch,
81 remove_properties: &[&str],
82 replace_properties: bool,
83 ) -> (bool, Vec<&'static str>) {
84 let mut reindex_required = false;
85 let mut changed_fields: Vec<&'static str> = Vec::new();
86
87 if let Some(name) = patch.name {
88 reindex_required |= entity.name != name;
89 entity.name = name;
90 changed_fields.push("name");
91 }
92 if let Some(desc_patch) = patch.description {
93 reindex_required |= entity.description != desc_patch;
94 entity.description = desc_patch;
95 changed_fields.push("description");
96 }
97 if let Some(props) = patch.properties {
98 if replace_properties {
99 entity.properties = Some(props);
100 } else {
101 let (merged, _) = merge_properties(
102 &entity.properties,
103 &Some(props),
104 EntityDedupMergePolicy::PreferFrom,
105 );
106 entity.properties = merged;
107 }
108 changed_fields.push("properties");
109 }
110 if let Some(Value::Object(properties)) = entity.properties.as_mut() {
111 let mut removed = false;
112 for key in remove_properties {
113 removed |= properties.remove(*key).is_some();
114 }
115 if removed && !changed_fields.contains(&"properties") {
116 changed_fields.push("properties");
117 }
118 }
119 if let Some(tags) = patch.tags {
120 entity.tags = tags;
121 changed_fields.push("tags");
122 }
123 if let Some(entity_type) = patch.entity_type {
124 reindex_required |= entity.entity_type != entity_type;
125 entity.entity_type = entity_type;
126 changed_fields.push("entity_type");
127 }
128
129 (reindex_required, changed_fields)
130 }
131
132 pub(crate) async fn prepare_update_entity(
144 &self,
145 token: &NamespaceToken,
146 id: Uuid,
147 patch: EntityPatch,
148 ) -> RuntimeResult<(Entity, bool, Vec<&'static str>, i64, Option<i64>)> {
149 self.prepare_guarded_entity_update(token, id, patch, None, &[])
150 .await
151 }
152
153 async fn prepare_guarded_entity_update(
154 &self,
155 token: &NamespaceToken,
156 id: Uuid,
157 patch: EntityPatch,
158 expected: Option<&Entity>,
159 remove_properties: &[&str],
160 ) -> RuntimeResult<(Entity, bool, Vec<&'static str>, i64, Option<i64>)> {
161 let prepared = self
162 .prepare_entity_update_for_route(
163 token,
164 id,
165 patch,
166 expected,
167 remove_properties,
168 EntityUpdateRoute::ReservationOnly,
169 )
170 .await?;
171 Ok((
172 prepared.entity,
173 prepared.reindex_required,
174 prepared.changed_fields,
175 prepared.expected_updated_at,
176 prepared.expected_deleted_at,
177 ))
178 }
179
180 async fn prepare_entity_update_for_route(
181 &self,
182 token: &NamespaceToken,
183 id: Uuid,
184 patch: EntityPatch,
185 expected: Option<&Entity>,
186 remove_properties: &[&str],
187 route: EntityUpdateRoute<'_>,
188 ) -> RuntimeResult<PreparedEntityUpdate> {
189 crate::secret_gate::reject_reserved_secret_gate_property(patch.properties.as_ref())?;
190 if !remove_properties.is_empty() {
191 let removals = Value::Object(
192 remove_properties
193 .iter()
194 .map(|key| ((*key).to_string(), Value::Null))
195 .collect(),
196 );
197 crate::secret_gate::reject_reserved_secret_gate_property(Some(&removals))?;
198 }
199 if matches!(route, EntityUpdateRoute::ReservationOnly) {
200 if let Some(ref name) = patch.name {
201 crate::secret_gate::check_at(name, "entity", "name")?;
202 }
203 if let Some(Some(ref desc)) = patch.description {
204 crate::secret_gate::check_at(desc, "entity", "description")?;
205 }
206 if let Some(ref props) = patch.properties {
207 crate::secret_gate::check_json_at(props, "entity", "properties")?;
208 }
209 if let Some(ref tags) = patch.tags {
210 crate::secret_gate::check_tags_at(tags, "entity", "tags")?;
211 }
212 } else if let EntityUpdateRoute::OrdinaryConstructor(context) = route {
213 context.check_patch(
214 patch.name.as_deref(),
215 patch
216 .description
217 .as_ref()
218 .and_then(|value| value.as_deref()),
219 patch.properties.as_ref(),
220 patch.tags.as_deref(),
221 )?;
222 }
223 let store = self.entities(token)?;
224 let mut entity = store.get_entity(id).await?.ok_or_else(|| {
225 if expected.is_some() {
226 stale_entity_snapshot_error(id)
227 } else {
228 RuntimeError::NotFound(format!("entity {id}"))
229 }
230 })?;
231 if let Some(expected) = expected {
232 let actual = serde_json::to_value(&entity)
233 .map_err(|error| RuntimeError::Internal(error.to_string()))?;
234 let expected = serde_json::to_value(expected)
235 .map_err(|error| RuntimeError::Internal(error.to_string()))?;
236 if actual != expected {
237 return Err(stale_entity_snapshot_error(id));
238 }
239 }
240 let original = entity.clone();
241 let expected_updated_at = entity.updated_at;
242 let expected_deleted_at = entity.deleted_at;
243 #[cfg(test)]
244 race_seam::pause_after_read().await;
245
246 let validated_entity_type = match &patch.entity_type {
250 Some(None) => Some(None),
251 Some(Some(raw)) => Some(Some(
252 self.validate_entity_type_for_kind(&entity.kind, Some(raw))?
253 .expect("set branch always yields a normalized value"),
254 )),
255 None => None,
256 };
257
258 let patch = EntityPatch {
259 entity_type: validated_entity_type,
260 ..patch
261 };
262 let (reindex_required, changed_fields) =
263 Self::apply_entity_patch_fields(&mut entity, patch, remove_properties, false);
264
265 crate::secret_gate::reject_reserved_secret_gate_property(entity.properties.as_ref())?;
268
269 if expected.is_some() && changed_fields.is_empty() {
270 return Ok(PreparedEntityUpdate {
271 entity,
272 reindex_required,
273 changed_fields,
274 expected_updated_at,
275 expected_deleted_at,
276 original,
277 });
278 }
279
280 if let Some(hook) = self.entity_kind_hook(&entity.kind) {
289 hook.validate_entity_update(self, token, &entity, entity.properties.as_ref())
290 .await?;
291 }
292
293 let minimum_updated_at = expected_updated_at.checked_add(1).ok_or_else(|| {
299 RuntimeError::Internal(format!(
300 "entity {id} updated_at is already at i64::MAX and cannot advance"
301 ))
302 })?;
303 entity.updated_at = chrono::Utc::now()
304 .timestamp_micros()
305 .max(minimum_updated_at);
306 Ok(PreparedEntityUpdate {
307 entity,
308 reindex_required,
309 changed_fields,
310 expected_updated_at,
311 expected_deleted_at,
312 original,
313 })
314 }
315
316 #[cfg(test)]
317 pub(crate) async fn update_entity(
318 &self,
319 token: &NamespaceToken,
320 id: Uuid,
321 patch: EntityPatch,
322 ) -> RuntimeResult<Entity> {
323 Ok(self
324 .update_entity_with_embedding_report(token, id, patch)
325 .await?
326 .0)
327 }
328
329 pub async fn update_entity_with_embedding_report(
330 &self,
331 token: &NamespaceToken,
332 id: Uuid,
333 patch: EntityPatch,
334 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
335 self.update_entity_with_expected_version_and_embedding_report(token, id, patch, None)
336 .await
337 }
338
339 pub async fn update_entity_with_expected_version_and_embedding_report(
341 &self,
342 token: &NamespaceToken,
343 id: Uuid,
344 patch: EntityPatch,
345 expected_version: Option<i64>,
346 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
347 let (entity, report) = self
348 .update_entity_with_index_report(token, id, patch, expected_version)
349 .await?;
350 report.into_legacy(entity)
351 }
352
353 pub async fn update_entity_with_index_report(
355 &self,
356 token: &NamespaceToken,
357 id: Uuid,
358 patch: EntityPatch,
359 expected_version: Option<i64>,
360 ) -> RuntimeResult<(Entity, EntityUpdateReport)> {
361 crate::entity_write::validate_expected_version(expected_version)?;
362 let admission = OrdinaryEntityUpdateContext::capture(token);
363 let PreparedEntityUpdate {
364 entity,
365 reindex_required,
366 changed_fields,
367 expected_updated_at,
368 expected_deleted_at,
369 original,
370 } = self
371 .prepare_entity_update_for_route(
372 token,
373 id,
374 patch,
375 None,
376 &[],
377 EntityUpdateRoute::OrdinaryConstructor(&admission),
378 )
379 .await?;
380 let entity = match admission.admit(token, entity)? {
381 EntityAdmission::Legacy(entity) => entity,
382 EntityAdmission::Exempt(prepared) => {
383 use crate::atomic_plan::PostCommitEffect;
384 use crate::atomic_runner::{
385 run_atomic_unit, AtomicOpFailure, AtomicOpPlan, AtomicRunOutcome,
386 };
387 let mut entity = prepared.entity().clone();
388 let next_version = original
389 .version
390 .checked_add(1)
391 .ok_or_else(|| RuntimeError::InvalidInput("entity version overflow".into()))?;
392 let (mut required, report) = self
393 .prepare_admitted_entity_indexes(token, &entity, &[], reindex_required)
394 .await?;
395 required.extend(crate::atomic_prepare::event_append_statements(
396 token, &entity.namespace, "update", EventKind::EntityUpdated,
397 SubstrateKind::Entity, entity.id,
398 serde_json::json!({"id": entity.id, "namespace": entity.namespace, "changed_fields": changed_fields}),
399 )?);
400 let plan = prepared.into_plan(
401 EntityCandidateMutation::ReplaceIfUnchanged {
402 expected: original,
403 expected_version,
404 },
405 required,
406 PostCommitEffect::None,
407 )?;
408 match run_atomic_unit(
409 self.sql().as_ref(),
410 vec![AtomicOpPlan::FinalizeEntity(Box::new(plan))],
411 )
412 .await
413 {
414 Ok(AtomicRunOutcome::Committed { .. }) => {
415 entity.version = next_version;
416 return Ok((
417 entity,
418 EntityUpdateReport::complete(report, reindex_required),
419 ));
420 }
421 Ok(AtomicRunOutcome::RolledBack {
422 failure: AtomicOpFailure::EntityConflict(conflict),
423 ..
424 }) => {
425 return Err(conflict.into_error().into());
426 }
427 Ok(AtomicRunOutcome::RolledBack {
428 failure: AtomicOpFailure::GuardFailed { .. },
429 ..
430 }) => {
431 return Err(stale_entity_snapshot_error(id));
432 }
433 Ok(AtomicRunOutcome::RolledBack { failure, .. }) => {
434 return Err(RuntimeError::Internal(format!(
435 "entity update finalization rolled back: {failure:?}"
436 )));
437 }
438 Err(error) => return Err(RuntimeError::Storage(error.0)),
439 }
440 }
441 };
442
443 self.persist_prepared_entity_update(
444 token,
445 entity,
446 reindex_required,
447 changed_fields,
448 expected_updated_at,
449 expected_deleted_at,
450 expected_version,
451 )
452 .await
453 }
454
455 pub async fn update_entity_if_unchanged(
462 &self,
463 token: &NamespaceToken,
464 expected: &Entity,
465 patch: EntityPatch,
466 remove_properties: &[&str],
467 ) -> RuntimeResult<Entity> {
468 let (entity, embedding) = self
469 .update_entity_if_unchanged_with_embedding_report(
470 token,
471 expected,
472 patch,
473 remove_properties,
474 )
475 .await?;
476 crate::operations::legacy_post_commit_result_with_embedding(
477 "update_entity_if_unchanged",
478 entity.id,
479 entity,
480 embedding,
481 Vec::new(),
482 )
483 }
484
485 pub async fn update_entity_if_unchanged_with_required_event(
491 &self,
492 token: &NamespaceToken,
493 expected: &Entity,
494 patch: EntityPatch,
495 remove_properties: &[&str],
496 required_event: khive_storage::Event,
497 ) -> RuntimeResult<Entity> {
498 let (entity, embedding) = self
499 .update_entity_if_unchanged_with_optional_event(
500 token,
501 expected,
502 patch,
503 remove_properties,
504 Some(required_event),
505 )
506 .await?;
507 crate::operations::legacy_post_commit_result_with_embedding(
508 "update_entity_if_unchanged",
509 entity.id,
510 entity,
511 embedding,
512 Vec::new(),
513 )
514 }
515
516 pub async fn update_entity_if_unchanged_with_embedding_report(
518 &self,
519 token: &NamespaceToken,
520 expected: &Entity,
521 patch: EntityPatch,
522 remove_properties: &[&str],
523 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
524 self.update_entity_if_unchanged_with_optional_event(
525 token,
526 expected,
527 patch,
528 remove_properties,
529 None,
530 )
531 .await
532 }
533
534 async fn update_entity_if_unchanged_with_optional_event(
535 &self,
536 token: &NamespaceToken,
537 expected: &Entity,
538 patch: EntityPatch,
539 remove_properties: &[&str],
540 required_event: Option<khive_storage::Event>,
541 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
542 let (entity, reindex_required, changed_fields, expected_updated_at, expected_deleted_at) =
543 self.prepare_guarded_entity_update(
544 token,
545 expected.id,
546 patch,
547 Some(expected),
548 remove_properties,
549 )
550 .await?;
551 if changed_fields.is_empty() {
552 return Ok((
553 entity,
554 crate::retrieval::EmbeddingTruncationReport::default(),
555 ));
556 }
557 let (entity, report) = self
558 .persist_prepared_entity_update_with_required_event(
559 token,
560 entity,
561 reindex_required,
562 changed_fields,
563 expected_updated_at,
564 expected_deleted_at,
565 None,
566 required_event,
567 )
568 .await?;
569 report.into_legacy(entity)
570 }
571
572 #[allow(clippy::too_many_arguments)]
573 pub(super) async fn persist_prepared_entity_update(
574 &self,
575 token: &NamespaceToken,
576 entity: Entity,
577 reindex_required: bool,
578 changed_fields: Vec<&'static str>,
579 expected_updated_at: i64,
580 expected_deleted_at: Option<i64>,
581 expected_version: Option<i64>,
582 ) -> RuntimeResult<(Entity, EntityUpdateReport)> {
583 self.persist_prepared_entity_update_with_required_event(
584 token,
585 entity,
586 reindex_required,
587 changed_fields,
588 expected_updated_at,
589 expected_deleted_at,
590 expected_version,
591 None,
592 )
593 .await
594 }
595
596 #[allow(clippy::too_many_arguments)]
597 async fn persist_prepared_entity_update_with_required_event(
598 &self,
599 token: &NamespaceToken,
600 mut entity: Entity,
601 reindex_required: bool,
602 changed_fields: Vec<&'static str>,
603 expected_updated_at: i64,
604 expected_deleted_at: Option<i64>,
605 expected_version: Option<i64>,
606 required_event: Option<khive_storage::Event>,
607 ) -> RuntimeResult<(Entity, EntityUpdateReport)> {
608 crate::secret_gate::reject_reserved_secret_gate_property(entity.properties.as_ref())?;
611 let id = entity.id;
612 let _ = self.entities(token)?;
613 let next_version = entity
614 .version
615 .checked_add(1)
616 .ok_or_else(|| RuntimeError::InvalidInput("entity version overflow".into()))?;
617 use crate::atomic_plan::{AffectedRowGuard, PlanStatement, PostCommitEffect, UpdatePlan};
618 use crate::atomic_runner::{
619 apply_plan_preserving_storage, run_prepared_atomic_unit, AtomicOpFailure, AtomicOpPlan,
620 PlanExecutionFailure, PreparedAtomicError, PreparedAtomicOp, PreparedAtomicOutcome,
621 };
622 let models = if reindex_required {
624 self.entity_index_model_snapshot()?
625 } else {
626 Vec::new()
627 };
628 let mut statements = vec![PlanStatement {
629 statement: khive_db::stores::entity::entity_replace_if_unchanged_statement(
630 &entity,
631 expected_updated_at,
632 expected_deleted_at,
633 ),
634 guard: Some(AffectedRowGuard::exactly(1)),
635 }];
636 if let Some(event) = required_event {
637 let event = EventAttribution::from_token(token).stamp(event);
638 statements.extend(
639 khive_db::stores::event::event_insert_statements(&event)
640 .map_err(|error| {
641 RuntimeError::Internal(format!("required entity event: {error}"))
642 })?
643 .into_iter()
644 .map(|statement| PlanStatement {
645 statement,
646 guard: None,
647 }),
648 );
649 }
650 let plan = UpdatePlan {
651 target_id: id,
652 statements,
653 post_commit: PostCommitEffect::None,
654 edge_natural_key: None,
655 idempotent_noop: false,
656 entity_guard: expected_version.map(|expected_version| {
657 crate::entity_write::EntityWriteGuard {
658 id,
659 expected_version,
660 }
661 }),
662 note_guard: None,
663 note_vector_purge: None,
664 note_embedding_inheritance: None,
665 graph_effects: Vec::new(),
666 };
667 let captured_models = models.clone();
668 let generation = Uuid::new_v4();
669 let pending_at = chrono::Utc::now().timestamp_micros();
670 let namespace = entity.namespace.clone();
671 let op: PreparedAtomicOp<
672 Option<khive_db::pending_index::PendingEntityIndex>,
673 AtomicOpFailure,
674 > = Box::new(move |writer| {
675 Box::pin(async move {
676 let plan = AtomicOpPlan::Update(Box::new(plan));
677 match apply_plan_preserving_storage(writer, &plan, false).await {
678 Ok(_) => {}
679 Err(PlanExecutionFailure::Operation(failure)) => {
680 return Err(PreparedAtomicError::Refused {
681 message: "entity update guard refused".into(),
682 failure,
683 });
684 }
685 Err(PlanExecutionFailure::Storage { source, .. }) => {
686 return Err(PreparedAtomicError::Storage(source));
687 }
688 }
689 let pending = if reindex_required {
690 Some(
691 khive_db::pending_index::enqueue(
692 writer,
693 id,
694 &namespace,
695 next_version,
696 &captured_models,
697 generation,
698 pending_at,
699 )
700 .await?,
701 )
702 } else {
703 None
704 };
705 Ok((pending, Vec::new()))
706 })
707 });
708 let pending = match run_prepared_atomic_unit(self.sql().as_ref(), op).await {
709 Ok(PreparedAtomicOutcome::Committed { value, .. }) => {
710 entity.version = next_version;
711 value
712 }
713 Ok(PreparedAtomicOutcome::RolledBack(AtomicOpFailure::EntityConflict(conflict))) => {
714 return Err(conflict.into_error().into());
715 }
716 Ok(PreparedAtomicOutcome::RolledBack(AtomicOpFailure::GuardFailed { .. })) => {
717 return Err(stale_entity_snapshot_error(id));
718 }
719 Ok(PreparedAtomicOutcome::RolledBack(failure)) => {
720 return Err(RuntimeError::Internal(format!(
721 "entity update rolled back: {failure:?}"
722 )));
723 }
724 Err(error) => return Err(RuntimeError::Storage(error)),
726 };
727
728 let event_result: RuntimeResult<()> = async {
729 let event_token =
730 token.with_namespace(crate::Namespace::parse(&entity.namespace).map_err(
731 |error| RuntimeError::Internal(format!("entity namespace invalid: {error}")),
732 )?);
733 let event_store = self.events(&event_token)?;
734 let event = khive_storage::event::Event::new(
735 entity.namespace.clone(),
736 "update",
737 EventKind::EntityUpdated,
738 SubstrateKind::Entity,
739 "",
740 )
741 .with_target(entity.id)
742 .with_payload(serde_json::json!({
743 "id": entity.id,
744 "namespace": entity.namespace,
745 "changed_fields": changed_fields,
746 }));
747 event_store
748 .append_event(event)
749 .await
750 .map(|_| ())
751 .map_err(RuntimeError::Storage)
752 }
753 .await;
754
755 let mut report = match pending {
756 Some(pending) => {
757 self.publish_pending_entity_indexes(token, &entity, &pending, &models)
758 .await
759 }
760 None => EntityUpdateReport::complete(
761 crate::retrieval::EmbeddingTruncationReport::default(),
762 false,
763 ),
764 };
765 if event_result.is_err() {
766 report
767 .post_commit_degradations
768 .push(crate::PostCommitDegradation {
769 stage: "event_append",
770 error: "entity committed; event append did not return a confirmed success"
771 .into(),
772 });
773 }
774 Ok((entity, report))
775 }
776
777 pub async fn merge_entity(
791 &self,
792 token: &NamespaceToken,
793 into_id: Uuid,
794 from_id: Uuid,
795 strategy: EntityDedupMergePolicy,
796 content_strategy: ContentMergeStrategy,
797 dry_run: bool,
798 ) -> RuntimeResult<MergeSummary> {
799 self.merge_entity_with_reason(
800 token,
801 into_id,
802 from_id,
803 strategy,
804 content_strategy,
805 dry_run,
806 None,
807 )
808 .await
809 }
810
811 #[allow(clippy::too_many_arguments)]
815 pub async fn merge_entity_with_reason(
816 &self,
817 token: &NamespaceToken,
818 into_id: Uuid,
819 from_id: Uuid,
820 strategy: EntityDedupMergePolicy,
821 content_strategy: ContentMergeStrategy,
822 dry_run: bool,
823 reason: Option<String>,
824 ) -> RuntimeResult<MergeSummary> {
825 self.merge_entity_with_validation(
826 token,
827 into_id,
828 from_id,
829 strategy,
830 content_strategy,
831 dry_run,
832 reason,
833 EntityMergeValidation::LegacyKind,
834 )
835 .await
836 }
837
838 #[allow(clippy::too_many_arguments)]
847 pub async fn merge_entity_with_reason_and_force(
848 &self,
849 token: &NamespaceToken,
850 into_id: Uuid,
851 from_id: Uuid,
852 strategy: EntityDedupMergePolicy,
853 content_strategy: ContentMergeStrategy,
854 dry_run: bool,
855 reason: Option<String>,
856 force: bool,
857 ) -> RuntimeResult<MergeSummary> {
858 let validation = if force {
859 EntityMergeValidation::Forced
860 } else {
861 EntityMergeValidation::SafetyFloor
862 };
863 self.merge_entity_with_validation(
864 token,
865 into_id,
866 from_id,
867 strategy,
868 content_strategy,
869 dry_run,
870 reason,
871 validation,
872 )
873 .await
874 }
875
876 #[allow(clippy::too_many_arguments)]
877 async fn merge_entity_with_validation(
878 &self,
879 token: &NamespaceToken,
880 into_id: Uuid,
881 from_id: Uuid,
882 strategy: EntityDedupMergePolicy,
883 content_strategy: ContentMergeStrategy,
884 dry_run: bool,
885 reason: Option<String>,
886 validation: EntityMergeValidation,
887 ) -> RuntimeResult<MergeSummary> {
888 if let Some(reason) = reason.as_deref() {
889 crate::secret_gate::check_at(reason, "merge", "reason")?;
890 }
891 if into_id == from_id {
892 return Err(RuntimeError::InvalidInput(
893 "cannot merge an entity into itself".into(),
894 ));
895 }
896 let ns = token.namespace().as_str().to_owned();
897 let fts_table = "fts_entities".to_string();
898 let embedding_plan = EmbeddingModelPlan::capture(self);
902 let vec_tables = embedding_plan.vector_tables();
903 let pack_rules = self.pack_edge_rules();
906
907 let _ = self.entities(token)?;
909 let _ = self.graph(token)?;
910 let _ = self.text(token)?;
911 let _ = self.events(token)?;
912 for model_name in embedding_plan.model_names() {
915 let _ = self.vectors_for_model(token, model_name)?;
916 }
917
918 let pool = self.backend().pool_arc();
919 let writer_task = pool
920 .writer_task_for_runtime_write(RuntimeWriteOperation::MergeEntity)
921 .map_err(RuntimeError::Storage)?;
922 let merge_event_id = Uuid::new_v4();
925 let event_context = MergeEventContext {
926 attribution: EventAttribution::from_token(token),
927 reason,
928 force: validation == EntityMergeValidation::Forced,
929 strategy,
930 content_strategy,
931 kind: EventKind::EntityMerged,
932 substrate: SubstrateKind::Entity,
933 event_id: Some(merge_event_id),
934 };
935
936 let (mut summary, updated_entity) = if let Some(writer_task) = writer_task {
937 writer_task
938 .send(move |conn| {
939 merge_entity_sql(
940 conn,
941 ns,
942 fts_table,
943 vec_tables,
944 into_id,
945 from_id,
946 strategy,
947 content_strategy,
948 dry_run,
949 pack_rules,
950 validation,
951 MergeTxLimits::default(),
952 merge_event_id,
953 Some(event_context),
954 )
955 .map_err(|e| {
956 e.into_storage_error(
957 khive_storage::StorageCapability::Entities,
958 "merge_entity",
959 )
960 })
961 })
962 .await
963 .inspect_err(|error| khive_storage::usage::account_event_write(Err(error)))
964 .map_err(map_merge_entity_storage_error)?
965 } else {
966 tokio::task::spawn_blocking(move || {
967 let guard = pool.writer()?;
968 let mut refusal = None;
969 let result = guard.transaction(|conn| {
970 merge_entity_sql(
971 conn,
972 ns,
973 fts_table,
974 vec_tables,
975 into_id,
976 from_id,
977 strategy,
978 content_strategy,
979 dry_run,
980 pack_rules,
981 validation,
982 MergeTxLimits::default(),
983 merge_event_id,
984 Some(event_context),
985 )
986 .map_err(|error| match error {
987 MergeSqlError::Sqlite(error) => error,
988 MergeSqlError::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),
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 {
1007 khive_storage::usage::account_event_write(Ok(1));
1008 tracing::info!(
1009 into_id = %summary.kept_id,
1010 from_id = %summary.removed_id,
1011 budget_rows = summary.tx_budget.rows_charged,
1012 budget_bytes = summary.tx_budget.bytes_charged,
1013 budget_max_rows = summary.tx_budget.max_rows,
1014 budget_max_bytes = summary.tx_budget.max_bytes,
1015 "merge_entity: transaction materialization budget"
1016 );
1017 }
1018
1019 if !dry_run && !embedding_plan.is_empty() {
1022 match self
1023 .reindex_entity_with_plan(token, &updated_entity, &embedding_plan, None)
1024 .await
1025 {
1026 Ok(report) => summary.embedding_truncation = report,
1027 Err(error) => {
1028 tracing::warn!(
1029 into_id = %summary.kept_id,
1030 from_id = %summary.removed_id,
1031 error = %error,
1032 "merge_entity: committed merge but survivor reindex failed"
1033 );
1034 summary.post_commit_reindex_error = Some(error.to_string());
1035 }
1036 }
1037 }
1038
1039 Ok(summary)
1040 }
1041
1042 pub(crate) async fn apply_entity_index_revision(
1045 &self,
1046 entity: &Entity,
1047 statements: Vec<SqlStatement>,
1048 ) -> RuntimeResult<bool> {
1049 let namespace = entity.namespace.clone();
1050 let id = entity.id.to_string();
1051 let version = entity.version;
1052 let op: AtomicUnitOp = Box::new(move |writer| {
1053 Box::pin(async move {
1054 let current = writer
1055 .query_scalar(SqlStatement {
1056 sql: "SELECT version FROM entities \
1057 WHERE namespace=?1 AND id=?2 AND deleted_at IS NULL"
1058 .into(),
1059 params: vec![SqlValue::Text(namespace), SqlValue::Text(id)],
1060 label: Some("entity-index-revision".into()),
1061 })
1062 .await?;
1063 if !matches!(current, Some(SqlValue::Integer(current)) if current == version) {
1064 return Ok(Box::new(false) as Box<dyn Any + Send>);
1065 }
1066 for statement in statements {
1067 writer.execute(statement).await?;
1068 }
1069 Ok(Box::new(true) as Box<dyn Any + Send>)
1070 })
1071 });
1072 self.sql()
1073 .atomic_unit(op)
1074 .await?
1075 .downcast::<bool>()
1076 .map(|result| *result)
1077 .map_err(|_| RuntimeError::Internal("invalid entity index outcome".into()))
1078 }
1079
1080 pub(crate) fn entity_vector_insert_statements(
1081 table: &str,
1082 entity: &Entity,
1083 model_name: &str,
1084 vector: &[f32],
1085 ) -> Vec<SqlStatement> {
1086 let subject = entity.id.to_string();
1087 let model_key = table
1088 .strip_prefix("vec_")
1089 .expect("runtime vector tables use the vec_ prefix");
1090 let kind = SubstrateKind::Entity.to_string();
1091 let field = "entity.body";
1092 let blob = khive_storage::encode_f32_native(vector);
1093 vec![
1094 SqlStatement {
1095 sql: format!(
1096 "INSERT INTO ann_write_log \
1097 (namespace, embedding_model, kind, field, subject_id, op) \
1098 SELECT namespace, embedding_model, kind, field, subject_id, 'delete' \
1099 FROM {table} WHERE subject_id=?1 AND NOT \
1100 (namespace=?2 AND embedding_model=?3 AND kind=?4 AND field=?5)"
1101 ),
1102 params: vec![
1103 SqlValue::Text(subject.clone()),
1104 SqlValue::Text(entity.namespace.clone()),
1105 SqlValue::Text(model_name.to_string()),
1106 SqlValue::Text(kind.clone()),
1107 SqlValue::Text(field.into()),
1108 ],
1109 label: Some("entity-reindex-log-delete".into()),
1110 },
1111 SqlStatement {
1112 sql: format!("DELETE FROM {table} WHERE subject_id=?1"),
1113 params: vec![SqlValue::Text(subject.clone())],
1114 label: Some("entity-reindex-vector-delete".into()),
1115 },
1116 SqlStatement {
1120 sql: "DELETE FROM vector_provenance \
1121 WHERE model_key = ?1 AND subject_id = ?2"
1122 .into(),
1123 params: vec![
1124 SqlValue::Text(model_key.to_string()),
1125 SqlValue::Text(subject.clone()),
1126 ],
1127 label: Some("entity-reindex-provenance-clear".into()),
1128 },
1129 SqlStatement {
1130 sql: format!(
1131 "INSERT INTO {table} \
1132 (subject_id, namespace, kind, field, embedding_model, embedding) \
1133 VALUES (?1, ?2, ?3, ?4, ?5, ?6)"
1134 ),
1135 params: vec![
1136 SqlValue::Text(subject.clone()),
1137 SqlValue::Text(entity.namespace.clone()),
1138 SqlValue::Text(kind.clone()),
1139 SqlValue::Text(field.into()),
1140 SqlValue::Text(model_name.to_string()),
1141 SqlValue::Blob(blob),
1142 ],
1143 label: Some("entity-reindex-vector-insert".into()),
1144 },
1145 SqlStatement {
1146 sql: "INSERT INTO ann_write_log \
1147 (namespace, embedding_model, kind, field, subject_id, op) \
1148 VALUES (?1, ?2, ?3, ?4, ?5, 'upsert')"
1149 .into(),
1150 params: vec![
1151 SqlValue::Text(entity.namespace.clone()),
1152 SqlValue::Text(model_name.to_string()),
1153 SqlValue::Text(kind),
1154 SqlValue::Text(field.into()),
1155 SqlValue::Text(subject),
1156 ],
1157 label: Some("entity-reindex-log-upsert".into()),
1158 },
1159 ]
1160 }
1161
1162 pub(crate) async fn publish_entity_vector_revision(
1163 &self,
1164 token: &NamespaceToken,
1165 entity: &Entity,
1166 model_name: &str,
1167 vector: &[f32],
1168 ) -> RuntimeResult<bool> {
1169 self.vectors_for_model(token, model_name)?;
1170 let (storage_model, dimensions) = self.vector_model_metadata(model_name)?;
1171 if let Some(index) = crate::atomic_message::non_finite_index(vector) {
1172 return Err(RuntimeError::InvalidInput(format!(
1173 "non-finite entity vector at index {index}"
1174 )));
1175 }
1176 if vector.len() != dimensions {
1177 return Err(RuntimeError::InvalidInput(format!(
1178 "entity vector has {} dimensions; expected {dimensions}",
1179 vector.len()
1180 )));
1181 }
1182 let table = format!("vec_{}", crate::config::sanitize_key(&storage_model));
1183 let statements =
1184 Self::entity_vector_insert_statements(&table, entity, &storage_model, vector);
1185 #[cfg(test)]
1186 race_seam::pause_before_entity_vector_publish().await;
1187 self.apply_entity_index_revision(entity, statements).await
1188 }
1189
1190 pub(crate) async fn reindex_entity(
1203 &self,
1204 token: &NamespaceToken,
1205 entity: &Entity,
1206 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1207 let embedding_plan = EmbeddingModelPlan::capture(self);
1208 self.reindex_entity_with_plan(token, entity, &embedding_plan, None)
1209 .await
1210 }
1211
1212 pub(crate) async fn reindex_entity_with_precomputed(
1213 &self,
1214 token: &NamespaceToken,
1215 entity: &Entity,
1216 mut precomputed: HashMap<String, crate::retrieval::DocumentEmbeddingOutcome>,
1217 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1218 let embedding_plan = EmbeddingModelPlan::capture(self);
1219 self.reindex_entity_with_plan(token, entity, &embedding_plan, Some(&mut precomputed))
1220 .await
1221 }
1222
1223 pub(super) async fn reindex_entity_with_plan(
1224 &self,
1225 token: &NamespaceToken,
1226 entity: &Entity,
1227 embedding_plan: &EmbeddingModelPlan,
1228 mut precomputed: Option<&mut HashMap<String, crate::retrieval::DocumentEmbeddingOutcome>>,
1229 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1230 #[cfg(test)]
1233 if crate::operations::consume_fts_fail_fault(&entity.namespace) {
1234 return Err(RuntimeError::Internal("injected FTS failure".to_string()));
1235 }
1236 let doc = entity_fts_document(entity);
1238 let embed_body = doc.body.clone();
1239 let _ = self.text(token)?;
1240 #[cfg(test)]
1241 race_seam::pause_before_entity_index_publish().await;
1242 let statements = khive_db::stores::text::delete_document_statements(
1243 "fts_entities",
1244 &entity.namespace,
1245 entity.id,
1246 )
1247 .into_iter()
1248 .chain(khive_db::stores::text::insert_document_statements(
1249 "fts_entities",
1250 &doc,
1251 ))
1252 .collect();
1253 if !self.apply_entity_index_revision(entity, statements).await? {
1254 return Ok(crate::retrieval::EmbeddingTruncationReport::default());
1255 }
1256
1257 let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1258 for model_name in embedding_plan.model_names() {
1259 let embedding = match precomputed
1260 .as_mut()
1261 .and_then(|outcomes| outcomes.remove(model_name))
1262 {
1263 Some(outcome) => Ok(outcome),
1264 None => {
1265 self.embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
1266 .await
1267 }
1268 };
1269 match embedding {
1270 Ok(outcome) => {
1271 report.observe(&outcome);
1272 match self
1273 .publish_entity_vector_revision(token, entity, model_name, &outcome.vector)
1274 .await
1275 {
1276 Ok(true) => {}
1277 Ok(false) => break,
1278 Err(error) => tracing::warn!(
1279 model = model_name,
1280 id = %entity.id,
1281 "reindex_entity: vector insert failed, skipping model: {error}"
1282 ),
1283 }
1284 }
1285 Err(e) => {
1286 tracing::warn!(
1287 model = model_name,
1288 id = %entity.id,
1289 "reindex_entity: embed failed for model, skipping: {e}"
1290 );
1291 }
1292 }
1293 }
1294
1295 Ok(report)
1296 }
1297}