Skip to main content

khive_runtime/curation/
entity_curation.rs

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(&current.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(&current.kind, Some(entity_type))?);
60        }
61        // ADR-115 §4 against the prepared row: the writer repeats this against the row it
62        // meets, which also decides whether a stored reserved value carries.
63        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(&current.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    /// Patch-style entity update.
133    ///
134    /// Only fields set to `Some(_)` are changed. Re-indexes FTS5 (and vectors if configured)
135    /// when `name`, `description`, or `entity_type` changes; skips re-indexing for
136    /// property/tag-only patches.
137    ///
138    /// Returns `RuntimeError::NotFound` if the entity does not exist or belongs to a different
139    /// namespace. Namespace isolation is enforced at the runtime layer.
140    /// Computes the patched `Entity`, `reindex_required`, and `changed_fields` without
141    /// writing anything, so both the normal write path and the atomic-prepare path
142    /// share one source of truth for what a patched entity looks like.
143    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        // ADR-014 tri-state: outer `None` = unchanged; `Some(None)` = explicit
247        // clear (no vocabulary validation — there is no value to validate);
248        // `Some(Some(raw))` = set, validated and normalized.
249        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        // A patch may carry properties from the stored row into the full
266        // replacement. Validate the final object, including that carry.
267        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        // #2943: `entity.properties`, `entity.entity_type`, and `entity.tags`
281        // are all final here — the owning pack's KindHook, if any, validates
282        // the resulting record, mirroring `prepare_note_update_hook` on the
283        // note side. `Ok(())` when no pack registered a hook for this entity
284        // kind (the trait default, or the runtime-layer aggregate was never
285        // installed). Placed after the no-op early return above so a
286        // genuinely unchanged guarded update never re-runs the hook for
287        // nothing; only `updated_at` remains to be bumped after this point.
288        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        // `updated_at` is also the optimistic-concurrency revision for
294        // full-entity replacement. Make it strictly advance even when two
295        // operations land inside one clock microsecond. Saturation is not a
296        // valid fallback: reusing i64::MAX would make the CAS accept a write
297        // without advancing its revision.
298        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    /// Entity update with an optional caller revision, checked inside the writer transaction.
340    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    /// Apply an entity patch and report committed but unfinished index targets.
354    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    /// Apply an admin patch only if the entity still matches the full read snapshot.
456    /// Property removals apply after the normal merge and preserve all other keys.
457    /// Missing keys alone are a no-op; reserved runtime-owned keys cannot be removed.
458    /// A changed, deleted, or missing entity returns a conflict without writing.
459    /// A bounded embedding returns a non-retryable error with the committed ID
460    /// and truncation report; use the report-aware variant to retain the record.
461    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    /// Apply a guarded admin patch and retain embedding truncation accounting.
486    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        // This final whole-object replacement must reserve the complete
534        // candidate, even if a future caller bypasses the patch preparer.
535        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        // One immutable metadata snapshot, captured before writer admission.
548        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            // Preserve the storage owner's unknown-outcome classification unchanged.
635            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    /// Merge `from_id` into `into_id`.
688    ///
689    /// All edges incident to `from_id` are rewired to `into_id`. Self-loops that would
690    /// result from the rewire are dropped. Properties and tags are merged per `strategy`.
691    /// `from_id` is tombstoned with merge provenance and removed from indexes. Returns a summary.
692    ///
693    /// If `dry_run` is true, computes and returns the planned summary without mutating any rows.
694    ///
695    /// Atomic: all SQL (entity reads/writes, edge rewires, FTS updates, vec-index
696    /// delete, merge event with destructive edge preimages) runs on one pool
697    /// connection inside one `BEGIN IMMEDIATE` transaction via
698    /// `merge_entity_sql`. If embedding vectors are configured, the vector re-insert for
699    /// `into_id` is performed after the transaction (requires async embedding computation).
700    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    /// Merge `from_id` into `into_id` and include an optional reason in the audit event.
722    // REASON: these arguments mirror the merge verb's policy, content strategy,
723    // dry-run, and audit-reason fields; a builder would only move that surface.
724    #[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    /// Merge two entities with an explicit override for the entity safety floor.
749    ///
750    /// Non-forced calls enforce entity kind, name similarity, and project compatibility
751    /// against the rows reread inside the merge transaction. Legacy merge methods retain
752    /// their historical same-kind-only policy.
753    /// A non-dry-run override is recorded as `force: true` in the merge event.
754    // REASON: these arguments mirror the merge verb's policy, content strategy,
755    // dry-run, audit-reason, and force fields; a builder would only move that surface.
756    #[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        // One immutable registry view governs transactional deletion, table
809        // preparation, and survivor reindex. A late model belongs to a later
810        // write/backfill rather than only one leg of this merge.
811        let embedding_plan = EmbeddingModelPlan::capture(self);
812        let vec_tables = embedding_plan.vector_tables();
813        // Loaded once here (sync, cheap) so the rewire loop can evaluate the
814        // endpoint contract without an async round-trip per edge (khive#1216).
815        let pack_rules = self.pack_edge_rules();
816
817        // Ensure all required tables exist (idempotent DDL) before the transaction.
818        let _ = self.entities(token)?;
819        let _ = self.graph(token)?;
820        let _ = self.text(token)?;
821        let _ = self.events(token)?;
822        // vectors_for_model (not the default-model-only self.vectors()) so
823        // custom-only runtimes (no default embedding_model) still get DDL primed.
824        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        // Minted before the transaction so the tombstone and its in-transaction
833        // EntityMerged event carry the same id.
834        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        // Count only committed event rows; dry-run never inserts an event.
916        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        // FTS and vec-deletes already committed inside the transaction above;
930        // only the embedding re-insert needs an async step outside it.
931        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    // ---- Internal helpers ----
953
954    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            // This raw replacement cannot attest the embedded input. Clear the old
1027            // sidecar in the same atomic index revision even when the new BLOB is
1028            // byte-identical to the old one.
1029            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    /// Re-upsert FTS5 document and vector(s) for the entity across all registered models.
1101    ///
1102    /// Uses `entity.namespace` — the authoritative namespace stored on the record — rather
1103    /// than the caller-supplied `namespace` parameter. This prevents a cross-namespace
1104    /// reindex from writing the search document into the wrong namespace's FTS index.
1105    ///
1106    /// Best-effort for vectors: if embedding or inserting for a particular model fails,
1107    /// logs a warning and continues to the next model. The FTS step is fail-closed
1108    /// (propagates error). Callers (update_entity, merge_entity) have already committed
1109    /// the entity row, so a partial embed miss leaves a stale vector rather than
1110    /// rolling back the update. Each failed guarded vector replacement rolls back
1111    /// its own index writes, keeping the prior row searchable.
1112    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        // Test-only fault seam: force the post-commit FTS leg to fail after a
1141        // merge or update has already persisted its entity row.
1142        #[cfg(test)]
1143        if crate::operations::consume_fts_fail_fault(&entity.namespace) {
1144            return Err(RuntimeError::Internal("injected FTS failure".to_string()));
1145        }
1146        // Use entity.namespace (authoritative) rather than token.namespace().as_str() (caller claim).
1147        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}