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_embedding_report(
487 &self,
488 token: &NamespaceToken,
489 expected: &Entity,
490 patch: EntityPatch,
491 remove_properties: &[&str],
492 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
493 let (entity, reindex_required, changed_fields, expected_updated_at, expected_deleted_at) =
494 self.prepare_guarded_entity_update(
495 token,
496 expected.id,
497 patch,
498 Some(expected),
499 remove_properties,
500 )
501 .await?;
502 if changed_fields.is_empty() {
503 return Ok((
504 entity,
505 crate::retrieval::EmbeddingTruncationReport::default(),
506 ));
507 }
508 let (entity, report) = self
509 .persist_prepared_entity_update(
510 token,
511 entity,
512 reindex_required,
513 changed_fields,
514 expected_updated_at,
515 expected_deleted_at,
516 None,
517 )
518 .await?;
519 report.into_legacy(entity)
520 }
521
522 #[allow(clippy::too_many_arguments)]
523 pub(super) async fn persist_prepared_entity_update(
524 &self,
525 token: &NamespaceToken,
526 mut entity: Entity,
527 reindex_required: bool,
528 changed_fields: Vec<&'static str>,
529 expected_updated_at: i64,
530 expected_deleted_at: Option<i64>,
531 expected_version: Option<i64>,
532 ) -> RuntimeResult<(Entity, EntityUpdateReport)> {
533 crate::secret_gate::reject_reserved_secret_gate_property(entity.properties.as_ref())?;
536 let id = entity.id;
537 let _ = self.entities(token)?;
538 let next_version = entity
539 .version
540 .checked_add(1)
541 .ok_or_else(|| RuntimeError::InvalidInput("entity version overflow".into()))?;
542 use crate::atomic_plan::{AffectedRowGuard, PlanStatement, PostCommitEffect, UpdatePlan};
543 use crate::atomic_runner::{
544 apply_plan_preserving_storage, run_prepared_atomic_unit, AtomicOpFailure, AtomicOpPlan,
545 PlanExecutionFailure, PreparedAtomicError, PreparedAtomicOp, PreparedAtomicOutcome,
546 };
547 let models = if reindex_required {
549 self.entity_index_model_snapshot()?
550 } else {
551 Vec::new()
552 };
553 let plan = UpdatePlan {
554 target_id: id,
555 statements: vec![PlanStatement {
556 statement: khive_db::stores::entity::entity_replace_if_unchanged_statement(
557 &entity,
558 expected_updated_at,
559 expected_deleted_at,
560 ),
561 guard: Some(AffectedRowGuard::exactly(1)),
562 }],
563 post_commit: PostCommitEffect::None,
564 edge_natural_key: None,
565 idempotent_noop: false,
566 entity_guard: expected_version.map(|expected_version| {
567 crate::entity_write::EntityWriteGuard {
568 id,
569 expected_version,
570 }
571 }),
572 note_guard: None,
573 note_vector_purge: None,
574 note_embedding_inheritance: None,
575 graph_effects: Vec::new(),
576 };
577 let captured_models = models.clone();
578 let generation = Uuid::new_v4();
579 let pending_at = chrono::Utc::now().timestamp_micros();
580 let namespace = entity.namespace.clone();
581 let op: PreparedAtomicOp<
582 Option<khive_db::pending_index::PendingEntityIndex>,
583 AtomicOpFailure,
584 > = Box::new(move |writer| {
585 Box::pin(async move {
586 let plan = AtomicOpPlan::Update(Box::new(plan));
587 match apply_plan_preserving_storage(writer, &plan, false).await {
588 Ok(_) => {}
589 Err(PlanExecutionFailure::Operation(failure)) => {
590 return Err(PreparedAtomicError::Refused {
591 message: "entity update guard refused".into(),
592 failure,
593 });
594 }
595 Err(PlanExecutionFailure::Storage { source, .. }) => {
596 return Err(PreparedAtomicError::Storage(source));
597 }
598 }
599 let pending = if reindex_required {
600 Some(
601 khive_db::pending_index::enqueue(
602 writer,
603 id,
604 &namespace,
605 next_version,
606 &captured_models,
607 generation,
608 pending_at,
609 )
610 .await?,
611 )
612 } else {
613 None
614 };
615 Ok((pending, Vec::new()))
616 })
617 });
618 let pending = match run_prepared_atomic_unit(self.sql().as_ref(), op).await {
619 Ok(PreparedAtomicOutcome::Committed { value, .. }) => {
620 entity.version = next_version;
621 value
622 }
623 Ok(PreparedAtomicOutcome::RolledBack(AtomicOpFailure::EntityConflict(conflict))) => {
624 return Err(conflict.into_error().into());
625 }
626 Ok(PreparedAtomicOutcome::RolledBack(AtomicOpFailure::GuardFailed { .. })) => {
627 return Err(stale_entity_snapshot_error(id));
628 }
629 Ok(PreparedAtomicOutcome::RolledBack(failure)) => {
630 return Err(RuntimeError::Internal(format!(
631 "entity update rolled back: {failure:?}"
632 )));
633 }
634 Err(error) => return Err(RuntimeError::Storage(error)),
636 };
637
638 let event_result: RuntimeResult<()> = async {
639 let event_token =
640 token.with_namespace(crate::Namespace::parse(&entity.namespace).map_err(
641 |error| RuntimeError::Internal(format!("entity namespace invalid: {error}")),
642 )?);
643 let event_store = self.events(&event_token)?;
644 let event = khive_storage::event::Event::new(
645 entity.namespace.clone(),
646 "update",
647 EventKind::EntityUpdated,
648 SubstrateKind::Entity,
649 "",
650 )
651 .with_target(entity.id)
652 .with_payload(serde_json::json!({
653 "id": entity.id,
654 "namespace": entity.namespace,
655 "changed_fields": changed_fields,
656 }));
657 event_store
658 .append_event(event)
659 .await
660 .map(|_| ())
661 .map_err(RuntimeError::Storage)
662 }
663 .await;
664
665 let mut report = match pending {
666 Some(pending) => {
667 self.publish_pending_entity_indexes(token, &entity, &pending, &models)
668 .await
669 }
670 None => EntityUpdateReport::complete(
671 crate::retrieval::EmbeddingTruncationReport::default(),
672 false,
673 ),
674 };
675 if event_result.is_err() {
676 report
677 .post_commit_degradations
678 .push(crate::PostCommitDegradation {
679 stage: "event_append",
680 error: "entity committed; event append did not return a confirmed success"
681 .into(),
682 });
683 }
684 Ok((entity, report))
685 }
686
687 pub async fn merge_entity(
701 &self,
702 token: &NamespaceToken,
703 into_id: Uuid,
704 from_id: Uuid,
705 strategy: EntityDedupMergePolicy,
706 content_strategy: ContentMergeStrategy,
707 dry_run: bool,
708 ) -> RuntimeResult<MergeSummary> {
709 self.merge_entity_with_reason(
710 token,
711 into_id,
712 from_id,
713 strategy,
714 content_strategy,
715 dry_run,
716 None,
717 )
718 .await
719 }
720
721 #[allow(clippy::too_many_arguments)]
725 pub async fn merge_entity_with_reason(
726 &self,
727 token: &NamespaceToken,
728 into_id: Uuid,
729 from_id: Uuid,
730 strategy: EntityDedupMergePolicy,
731 content_strategy: ContentMergeStrategy,
732 dry_run: bool,
733 reason: Option<String>,
734 ) -> RuntimeResult<MergeSummary> {
735 self.merge_entity_with_validation(
736 token,
737 into_id,
738 from_id,
739 strategy,
740 content_strategy,
741 dry_run,
742 reason,
743 EntityMergeValidation::LegacyKind,
744 )
745 .await
746 }
747
748 #[allow(clippy::too_many_arguments)]
757 pub async fn merge_entity_with_reason_and_force(
758 &self,
759 token: &NamespaceToken,
760 into_id: Uuid,
761 from_id: Uuid,
762 strategy: EntityDedupMergePolicy,
763 content_strategy: ContentMergeStrategy,
764 dry_run: bool,
765 reason: Option<String>,
766 force: bool,
767 ) -> RuntimeResult<MergeSummary> {
768 let validation = if force {
769 EntityMergeValidation::Forced
770 } else {
771 EntityMergeValidation::SafetyFloor
772 };
773 self.merge_entity_with_validation(
774 token,
775 into_id,
776 from_id,
777 strategy,
778 content_strategy,
779 dry_run,
780 reason,
781 validation,
782 )
783 .await
784 }
785
786 #[allow(clippy::too_many_arguments)]
787 async fn merge_entity_with_validation(
788 &self,
789 token: &NamespaceToken,
790 into_id: Uuid,
791 from_id: Uuid,
792 strategy: EntityDedupMergePolicy,
793 content_strategy: ContentMergeStrategy,
794 dry_run: bool,
795 reason: Option<String>,
796 validation: EntityMergeValidation,
797 ) -> RuntimeResult<MergeSummary> {
798 if let Some(reason) = reason.as_deref() {
799 crate::secret_gate::check_at(reason, "merge", "reason")?;
800 }
801 if into_id == from_id {
802 return Err(RuntimeError::InvalidInput(
803 "cannot merge an entity into itself".into(),
804 ));
805 }
806 let ns = token.namespace().as_str().to_owned();
807 let fts_table = "fts_entities".to_string();
808 let embedding_plan = EmbeddingModelPlan::capture(self);
812 let vec_tables = embedding_plan.vector_tables();
813 let pack_rules = self.pack_edge_rules();
816
817 let _ = self.entities(token)?;
819 let _ = self.graph(token)?;
820 let _ = self.text(token)?;
821 let _ = self.events(token)?;
822 for model_name in embedding_plan.model_names() {
825 let _ = self.vectors_for_model(token, model_name)?;
826 }
827
828 let pool = self.backend().pool_arc();
829 let writer_task = pool
830 .writer_task_for_runtime_write(RuntimeWriteOperation::MergeEntity)
831 .map_err(RuntimeError::Storage)?;
832 let merge_event_id = Uuid::new_v4();
835 let event_context = MergeEventContext {
836 attribution: EventAttribution::from_token(token),
837 reason,
838 force: validation == EntityMergeValidation::Forced,
839 strategy,
840 content_strategy,
841 kind: EventKind::EntityMerged,
842 substrate: SubstrateKind::Entity,
843 event_id: Some(merge_event_id),
844 };
845
846 let (mut summary, updated_entity) = if let Some(writer_task) = writer_task {
847 writer_task
848 .send(move |conn| {
849 merge_entity_sql(
850 conn,
851 ns,
852 fts_table,
853 vec_tables,
854 into_id,
855 from_id,
856 strategy,
857 content_strategy,
858 dry_run,
859 pack_rules,
860 validation,
861 MergeTxLimits::default(),
862 merge_event_id,
863 Some(event_context),
864 )
865 .map_err(|e| {
866 e.into_storage_error(
867 khive_storage::StorageCapability::Entities,
868 "merge_entity",
869 )
870 })
871 })
872 .await
873 .inspect_err(|error| khive_storage::usage::account_event_write(Err(error)))
874 .map_err(map_merge_entity_storage_error)?
875 } else {
876 tokio::task::spawn_blocking(move || {
877 let guard = pool.writer()?;
878 let mut refusal = None;
879 let result = guard.transaction(|conn| {
880 merge_entity_sql(
881 conn,
882 ns,
883 fts_table,
884 vec_tables,
885 into_id,
886 from_id,
887 strategy,
888 content_strategy,
889 dry_run,
890 pack_rules,
891 validation,
892 MergeTxLimits::default(),
893 merge_event_id,
894 Some(event_context),
895 )
896 .map_err(|error| match error {
897 MergeSqlError::Sqlite(error) => error,
898 MergeSqlError::Refusal(error) => {
899 refusal = Some(error);
900 SqliteError::InvalidData(
901 "entity merge refused by transactional policy".to_string(),
902 )
903 }
904 })
905 });
906 match refusal {
907 Some(error) => Err(error),
908 None => result.map_err(RuntimeError::from),
909 }
910 })
911 .await
912 .map_err(|e| RuntimeError::Internal(e.to_string()))??
913 };
914
915 if !dry_run {
917 khive_storage::usage::account_event_write(Ok(1));
918 tracing::info!(
919 into_id = %summary.kept_id,
920 from_id = %summary.removed_id,
921 budget_rows = summary.tx_budget.rows_charged,
922 budget_bytes = summary.tx_budget.bytes_charged,
923 budget_max_rows = summary.tx_budget.max_rows,
924 budget_max_bytes = summary.tx_budget.max_bytes,
925 "merge_entity: transaction materialization budget"
926 );
927 }
928
929 if !dry_run && !embedding_plan.is_empty() {
932 match self
933 .reindex_entity_with_plan(token, &updated_entity, &embedding_plan, None)
934 .await
935 {
936 Ok(report) => summary.embedding_truncation = report,
937 Err(error) => {
938 tracing::warn!(
939 into_id = %summary.kept_id,
940 from_id = %summary.removed_id,
941 error = %error,
942 "merge_entity: committed merge but survivor reindex failed"
943 );
944 summary.post_commit_reindex_error = Some(error.to_string());
945 }
946 }
947 }
948
949 Ok(summary)
950 }
951
952 async fn apply_entity_index_revision(
955 &self,
956 entity: &Entity,
957 statements: Vec<SqlStatement>,
958 ) -> RuntimeResult<bool> {
959 let namespace = entity.namespace.clone();
960 let id = entity.id.to_string();
961 let version = entity.version;
962 let op: AtomicUnitOp = Box::new(move |writer| {
963 Box::pin(async move {
964 let current = writer
965 .query_scalar(SqlStatement {
966 sql: "SELECT version FROM entities \
967 WHERE namespace=?1 AND id=?2 AND deleted_at IS NULL"
968 .into(),
969 params: vec![SqlValue::Text(namespace), SqlValue::Text(id)],
970 label: Some("entity-index-revision".into()),
971 })
972 .await?;
973 if !matches!(current, Some(SqlValue::Integer(current)) if current == version) {
974 return Ok(Box::new(false) as Box<dyn Any + Send>);
975 }
976 for statement in statements {
977 writer.execute(statement).await?;
978 }
979 Ok(Box::new(true) as Box<dyn Any + Send>)
980 })
981 });
982 self.sql()
983 .atomic_unit(op)
984 .await?
985 .downcast::<bool>()
986 .map(|result| *result)
987 .map_err(|_| RuntimeError::Internal("invalid entity index outcome".into()))
988 }
989
990 pub(crate) fn entity_vector_insert_statements(
991 table: &str,
992 entity: &Entity,
993 model_name: &str,
994 vector: &[f32],
995 ) -> Vec<SqlStatement> {
996 let subject = entity.id.to_string();
997 let model_key = table
998 .strip_prefix("vec_")
999 .expect("runtime vector tables use the vec_ prefix");
1000 let kind = SubstrateKind::Entity.to_string();
1001 let field = "entity.body";
1002 let blob = khive_storage::encode_f32_native(vector);
1003 vec![
1004 SqlStatement {
1005 sql: format!(
1006 "INSERT INTO ann_write_log \
1007 (namespace, embedding_model, kind, field, subject_id, op) \
1008 SELECT namespace, embedding_model, kind, field, subject_id, 'delete' \
1009 FROM {table} WHERE subject_id=?1 AND NOT \
1010 (namespace=?2 AND embedding_model=?3 AND kind=?4 AND field=?5)"
1011 ),
1012 params: vec![
1013 SqlValue::Text(subject.clone()),
1014 SqlValue::Text(entity.namespace.clone()),
1015 SqlValue::Text(model_name.to_string()),
1016 SqlValue::Text(kind.clone()),
1017 SqlValue::Text(field.into()),
1018 ],
1019 label: Some("entity-reindex-log-delete".into()),
1020 },
1021 SqlStatement {
1022 sql: format!("DELETE FROM {table} WHERE subject_id=?1"),
1023 params: vec![SqlValue::Text(subject.clone())],
1024 label: Some("entity-reindex-vector-delete".into()),
1025 },
1026 SqlStatement {
1030 sql: "DELETE FROM vector_provenance \
1031 WHERE model_key = ?1 AND subject_id = ?2"
1032 .into(),
1033 params: vec![
1034 SqlValue::Text(model_key.to_string()),
1035 SqlValue::Text(subject.clone()),
1036 ],
1037 label: Some("entity-reindex-provenance-clear".into()),
1038 },
1039 SqlStatement {
1040 sql: format!(
1041 "INSERT INTO {table} \
1042 (subject_id, namespace, kind, field, embedding_model, embedding) \
1043 VALUES (?1, ?2, ?3, ?4, ?5, ?6)"
1044 ),
1045 params: vec![
1046 SqlValue::Text(subject.clone()),
1047 SqlValue::Text(entity.namespace.clone()),
1048 SqlValue::Text(kind.clone()),
1049 SqlValue::Text(field.into()),
1050 SqlValue::Text(model_name.to_string()),
1051 SqlValue::Blob(blob),
1052 ],
1053 label: Some("entity-reindex-vector-insert".into()),
1054 },
1055 SqlStatement {
1056 sql: "INSERT INTO ann_write_log \
1057 (namespace, embedding_model, kind, field, subject_id, op) \
1058 VALUES (?1, ?2, ?3, ?4, ?5, 'upsert')"
1059 .into(),
1060 params: vec![
1061 SqlValue::Text(entity.namespace.clone()),
1062 SqlValue::Text(model_name.to_string()),
1063 SqlValue::Text(kind),
1064 SqlValue::Text(field.into()),
1065 SqlValue::Text(subject),
1066 ],
1067 label: Some("entity-reindex-log-upsert".into()),
1068 },
1069 ]
1070 }
1071
1072 pub(crate) async fn publish_entity_vector_revision(
1073 &self,
1074 token: &NamespaceToken,
1075 entity: &Entity,
1076 model_name: &str,
1077 vector: &[f32],
1078 ) -> RuntimeResult<bool> {
1079 self.vectors_for_model(token, model_name)?;
1080 let (storage_model, dimensions) = self.vector_model_metadata(model_name)?;
1081 if let Some(index) = crate::atomic_message::non_finite_index(vector) {
1082 return Err(RuntimeError::InvalidInput(format!(
1083 "non-finite entity vector at index {index}"
1084 )));
1085 }
1086 if vector.len() != dimensions {
1087 return Err(RuntimeError::InvalidInput(format!(
1088 "entity vector has {} dimensions; expected {dimensions}",
1089 vector.len()
1090 )));
1091 }
1092 let table = format!("vec_{}", crate::config::sanitize_key(&storage_model));
1093 let statements =
1094 Self::entity_vector_insert_statements(&table, entity, &storage_model, vector);
1095 #[cfg(test)]
1096 race_seam::pause_before_entity_vector_publish().await;
1097 self.apply_entity_index_revision(entity, statements).await
1098 }
1099
1100 pub(crate) async fn reindex_entity(
1113 &self,
1114 token: &NamespaceToken,
1115 entity: &Entity,
1116 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1117 let embedding_plan = EmbeddingModelPlan::capture(self);
1118 self.reindex_entity_with_plan(token, entity, &embedding_plan, None)
1119 .await
1120 }
1121
1122 pub(crate) async fn reindex_entity_with_precomputed(
1123 &self,
1124 token: &NamespaceToken,
1125 entity: &Entity,
1126 mut precomputed: HashMap<String, crate::retrieval::DocumentEmbeddingOutcome>,
1127 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1128 let embedding_plan = EmbeddingModelPlan::capture(self);
1129 self.reindex_entity_with_plan(token, entity, &embedding_plan, Some(&mut precomputed))
1130 .await
1131 }
1132
1133 pub(super) async fn reindex_entity_with_plan(
1134 &self,
1135 token: &NamespaceToken,
1136 entity: &Entity,
1137 embedding_plan: &EmbeddingModelPlan,
1138 mut precomputed: Option<&mut HashMap<String, crate::retrieval::DocumentEmbeddingOutcome>>,
1139 ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1140 #[cfg(test)]
1143 if crate::operations::consume_fts_fail_fault(&entity.namespace) {
1144 return Err(RuntimeError::Internal("injected FTS failure".to_string()));
1145 }
1146 let doc = entity_fts_document(entity);
1148 let embed_body = doc.body.clone();
1149 let _ = self.text(token)?;
1150 #[cfg(test)]
1151 race_seam::pause_before_entity_index_publish().await;
1152 let statements = khive_db::stores::text::delete_document_statements(
1153 "fts_entities",
1154 &entity.namespace,
1155 entity.id,
1156 )
1157 .into_iter()
1158 .chain(khive_db::stores::text::insert_document_statements(
1159 "fts_entities",
1160 &doc,
1161 ))
1162 .collect();
1163 if !self.apply_entity_index_revision(entity, statements).await? {
1164 return Ok(crate::retrieval::EmbeddingTruncationReport::default());
1165 }
1166
1167 let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1168 for model_name in embedding_plan.model_names() {
1169 let embedding = match precomputed
1170 .as_mut()
1171 .and_then(|outcomes| outcomes.remove(model_name))
1172 {
1173 Some(outcome) => Ok(outcome),
1174 None => {
1175 self.embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
1176 .await
1177 }
1178 };
1179 match embedding {
1180 Ok(outcome) => {
1181 report.observe(&outcome);
1182 match self
1183 .publish_entity_vector_revision(token, entity, model_name, &outcome.vector)
1184 .await
1185 {
1186 Ok(true) => {}
1187 Ok(false) => break,
1188 Err(error) => tracing::warn!(
1189 model = model_name,
1190 id = %entity.id,
1191 "reindex_entity: vector insert failed, skipping model: {error}"
1192 ),
1193 }
1194 }
1195 Err(e) => {
1196 tracing::warn!(
1197 model = model_name,
1198 id = %entity.id,
1199 "reindex_entity: embed failed for model, skipping: {e}"
1200 );
1201 }
1202 }
1203 }
1204
1205 Ok(report)
1206 }
1207}