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 with one event in the same writer transaction.
486    /// The token stamps the required event's namespace, actor and operation;
487    /// callers supply its semantic kind, target and payload. An unchanged patch
488    /// appends nothing. A failed append rolls back the replacement. Existing
489    /// post-commit index and generic update-event reporting remains unchanged.
490    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    /// Apply a guarded admin patch and retain embedding truncation accounting.
517    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        // This final whole-object replacement must reserve the complete
609        // candidate, even if a future caller bypasses the patch preparer.
610        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        // One immutable metadata snapshot, captured before writer admission.
623        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            // Preserve the storage owner's unknown-outcome classification unchanged.
725            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    /// Merge `from_id` into `into_id`.
778    ///
779    /// All edges incident to `from_id` are rewired to `into_id`. Self-loops that would
780    /// result from the rewire are dropped. Properties and tags are merged per `strategy`.
781    /// `from_id` is tombstoned with merge provenance and removed from indexes. Returns a summary.
782    ///
783    /// If `dry_run` is true, computes and returns the planned summary without mutating any rows.
784    ///
785    /// Atomic: all SQL (entity reads/writes, edge rewires, FTS updates, vec-index
786    /// delete, merge event with destructive edge preimages) runs on one pool
787    /// connection inside one `BEGIN IMMEDIATE` transaction via
788    /// `merge_entity_sql`. If embedding vectors are configured, the vector re-insert for
789    /// `into_id` is performed after the transaction (requires async embedding computation).
790    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    /// Merge `from_id` into `into_id` and include an optional reason in the audit event.
812    // REASON: these arguments mirror the merge verb's policy, content strategy,
813    // dry-run, and audit-reason fields; a builder would only move that surface.
814    #[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    /// Merge two entities with an explicit override for the entity safety floor.
839    ///
840    /// Non-forced calls enforce entity kind, name similarity, and project compatibility
841    /// against the rows reread inside the merge transaction. Legacy merge methods retain
842    /// their historical same-kind-only policy.
843    /// A non-dry-run override is recorded as `force: true` in the merge event.
844    // REASON: these arguments mirror the merge verb's policy, content strategy,
845    // dry-run, audit-reason, and force fields; a builder would only move that surface.
846    #[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        // One immutable registry view governs transactional deletion, table
899        // preparation, and survivor reindex. A late model belongs to a later
900        // write/backfill rather than only one leg of this merge.
901        let embedding_plan = EmbeddingModelPlan::capture(self);
902        let vec_tables = embedding_plan.vector_tables();
903        // Loaded once here (sync, cheap) so the rewire loop can evaluate the
904        // endpoint contract without an async round-trip per edge (khive#1216).
905        let pack_rules = self.pack_edge_rules();
906
907        // Ensure all required tables exist (idempotent DDL) before the transaction.
908        let _ = self.entities(token)?;
909        let _ = self.graph(token)?;
910        let _ = self.text(token)?;
911        let _ = self.events(token)?;
912        // vectors_for_model (not the default-model-only self.vectors()) so
913        // custom-only runtimes (no default embedding_model) still get DDL primed.
914        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        // Minted before the transaction so the tombstone and its in-transaction
923        // EntityMerged event carry the same id.
924        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        // Count only committed event rows; dry-run never inserts an event.
1006        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        // FTS and vec-deletes already committed inside the transaction above;
1020        // only the embedding re-insert needs an async step outside it.
1021        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    // ---- Internal helpers ----
1043
1044    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            // This raw replacement cannot attest the embedded input. Clear the old
1117            // sidecar in the same atomic index revision even when the new BLOB is
1118            // byte-identical to the old one.
1119            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    /// Re-upsert FTS5 document and vector(s) for the entity across all registered models.
1191    ///
1192    /// Uses `entity.namespace` — the authoritative namespace stored on the record — rather
1193    /// than the caller-supplied `namespace` parameter. This prevents a cross-namespace
1194    /// reindex from writing the search document into the wrong namespace's FTS index.
1195    ///
1196    /// Best-effort for vectors: if embedding or inserting for a particular model fails,
1197    /// logs a warning and continues to the next model. The FTS step is fail-closed
1198    /// (propagates error). Callers (update_entity, merge_entity) have already committed
1199    /// the entity row, so a partial embed miss leaves a stale vector rather than
1200    /// rolling back the update. Each failed guarded vector replacement rolls back
1201    /// its own index writes, keeping the prior row searchable.
1202    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        // Test-only fault seam: force the post-commit FTS leg to fail after a
1231        // merge or update has already persisted its entity row.
1232        #[cfg(test)]
1233        if crate::operations::consume_fts_fail_fault(&entity.namespace) {
1234            return Err(RuntimeError::Internal("injected FTS failure".to_string()));
1235        }
1236        // Use entity.namespace (authoritative) rather than token.namespace().as_str() (caller claim).
1237        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}