1use super::*;
4use crate::secret_gate_finalizer::entity_admission::{
5 prepare_entity_admission, EntityAdmission, EntityEntryPoint,
6};
7use crate::EntityCandidateMutation;
8use khive_storage::{BoxFuture, SqlWriter, StorageResult};
9
10fn claimed_entity_create_event(entity: &Entity) -> Event {
11 let mut event = Event::new(
12 entity.namespace.clone(),
13 "create",
14 EventKind::EntityCreated,
15 SubstrateKind::Entity,
16 "",
17 )
18 .with_target(entity.id)
19 .with_payload(serde_json::json!({
20 "id": entity.id,
21 "namespace": &entity.namespace,
22 "kind": &entity.kind,
23 }));
24 let event_seed = Uuid::new_v5(&Uuid::NAMESPACE_URL, b"khive:claimed-entity-create:v1");
25 let mut event_key = Vec::with_capacity(24);
26 event_key.extend_from_slice(entity.id.as_bytes());
27 event_key.extend_from_slice(&entity.created_at.to_be_bytes());
28 event.id = Uuid::new_v5(&event_seed, &event_key);
29 event
30}
31
32impl KhiveRuntime {
33 pub async fn create_workspace_document_with_cursor<F>(
35 &self,
36 registry: &crate::VerbRegistry,
37 token: &crate::NamespaceToken,
38 document: (&str, &str),
39 source: (&str, &str, &str),
40 previous: Option<khive_types::Id128>,
41 cursor: F,
42 ) -> crate::RuntimeResult<(khive_types::Id128, crate::RuntimeResult<()>)>
43 where
44 F: for<'w> FnOnce(
45 &'w mut dyn SqlWriter,
46 khive_types::Id128,
47 ) -> BoxFuture<'w, StorageResult<()>>
48 + Send
49 + 'static,
50 {
51 use crate::atomic_prepare::apply_post_commit_effects;
52 use crate::atomic_runner::PreparedAtomicError::{Refused, Storage};
53 use crate::atomic_runner::{
54 apply_plan_preserving_storage, run_prepared_atomic_unit, AtomicOpFailure, AtomicOpPlan,
55 PlanExecutionFailure, PreparedAtomicOp, PreparedAtomicOutcome,
56 };
57 use crate::canonical_apply::prepare_canonical_changeset;
58 use khive_changeset::{
59 ChangeSet, CreateOp, CreateTarget, EntityCreateFields, Envelope, LinkOp, Op,
60 };
61 use khive_storage::{SqlStatement, StorageError, WriterTaskRequestState};
62 use khive_types::{EdgeRelation, EntityKind, Id128, PropertyValue, Timestamp};
63 use std::mem::take;
64 use std::sync::{Arc, Mutex};
65 if self.backend_id().as_str() != crate::config::BackendId::MAIN {
66 return Err(RuntimeError::InvalidInput(format!(
67 "workspace mirror requires main backend; assigned backend: {}",
68 self.backend_id()
69 )));
70 }
71 let staged_at = u64::try_from(chrono::Utc::now().timestamp_micros())
72 .map(Timestamp::from_micros)
73 .map_err(|_| {
74 RuntimeError::Internal("workspace staging time precedes Unix epoch".into())
75 })?;
76 let id = Id128::from_bytes(*Uuid::new_v4().as_bytes());
77 let properties = [
78 ("source_uri".into(), PropertyValue::String(source.0.into())),
79 ("source_type".into(), PropertyValue::String(source.1.into())),
80 ("checksum".into(), PropertyValue::String(source.2.into())),
81 ]
82 .into_iter()
83 .collect();
84 let mut ops = vec![Op::Create(CreateOp {
85 id,
86 namespace: token.namespace().clone(),
87 target: CreateTarget::Entity(EntityCreateFields {
88 entity_kind: EntityKind::Document,
89 entity_type: None,
90 name: document.0.into(),
91 description: Some(document.1.into()),
92 properties,
93 tags: Vec::new(),
94 }),
95 })];
96 if let Some(previous) = previous {
97 ops.push(Op::Link(LinkOp {
98 id: Id128::from_bytes(*Uuid::new_v4().as_bytes()),
99 namespace: token.namespace().clone(),
100 source: id,
101 target: previous,
102 relation: EdgeRelation::Supersedes,
103 weight: 1.0,
104 properties: Default::default(),
105 }));
106 }
107 let changeset = ChangeSet::new(
108 Envelope::new("workspace.mirror", "deterministic", staged_at),
109 ops,
110 );
111 let plans = prepare_canonical_changeset(self, registry, token, &changeset).await?;
112 let handles = Arc::new(Mutex::new(Vec::<crate::EntityFinalizationPlan>::new()));
113 let attempted = Arc::clone(&handles);
114 let prepared: PreparedAtomicOp<(), (usize, AtomicOpFailure)> = Box::new(move |writer| {
115 Box::pin(async move {
116 let mut effects = Vec::new();
117 for (index, plan) in plans.into_iter().enumerate() {
118 let savepoint = format!("adr099_atomic_op_{index}");
119 writer
120 .execute(SqlStatement::new(format!("SAVEPOINT {savepoint}"), vec![]))
121 .await?;
122 let materialized = match plan {
123 AtomicOpPlan::Canonical(canonical) => {
124 crate::canonical_apply::materialize(writer, &canonical).await
125 }
126 plan => Ok(plan),
127 };
128 let applied = match materialized {
129 Ok(plan) => {
130 if let AtomicOpPlan::FinalizeEntity(finalizer) = &plan {
131 attempted
132 .lock()
133 .expect("workspace finalizer lock poisoned")
134 .push(finalizer.for_settlement());
135 }
136 apply_plan_preserving_storage(writer, &plan, false).await
137 }
138 Err(failure) => Err(PlanExecutionFailure::Operation(failure)),
139 };
140 match applied {
141 Ok(applied) => {
142 writer
143 .execute(SqlStatement::new(format!("RELEASE {savepoint}"), vec![]))
144 .await?;
145 if let Some(effect) = applied.effect {
146 effects.push(effect);
147 }
148 }
149 Err(failure) => {
150 let _ = writer
151 .execute(SqlStatement::new(
152 format!("ROLLBACK TO {savepoint}"),
153 vec![],
154 ))
155 .await;
156 let _ = writer
157 .execute(SqlStatement::new(format!("RELEASE {savepoint}"), vec![]))
158 .await;
159 return Err(match failure {
160 PlanExecutionFailure::Storage { source, .. } => Storage(source),
161 PlanExecutionFailure::Operation(failure) => Refused {
162 failure: (index, failure),
163 message: format!("workspace atomic unit aborted at op {index}"),
164 },
165 });
166 }
167 }
168 }
169 cursor(writer, id).await.map_err(Storage)?;
170 Ok(((), effects))
171 })
172 });
173 let access = self.sql();
174 let outcome = run_prepared_atomic_unit(access.as_ref(), prepared).await;
175 let handles = take(&mut *handles.lock().expect("workspace finalizer lock poisoned"));
176 match outcome {
177 Ok(PreparedAtomicOutcome::Committed { post_commit, .. }) => {
178 for plan in handles {
179 plan.finish_commit();
180 }
181 let effects = apply_post_commit_effects(self, token, post_commit).await;
182 Ok((id, effects))
183 }
184 Ok(PreparedAtomicOutcome::RolledBack((index, failure))) => {
185 let mut native_source = None;
186 for plan in handles {
187 if let Some(source) = plan.finish_rollback(access.as_ref()).await {
188 native_source = Some(source);
189 }
190 }
191 if let Some(source) = native_source {
192 return Err(RuntimeError::Storage(
193 StorageError::WriterTaskRequestFailed {
194 request_state: WriterTaskRequestState::TransactionRolledBack,
195 source: Box::new(source),
196 },
197 ));
198 }
199 Err(RuntimeError::Internal(format!(
200 "workspace atomic unit rolled back at op {index}: {failure:?}"
201 )))
202 }
203 Err(error) => {
204 if matches!(
205 &error,
206 StorageError::WriterTaskRequestFailed {
207 request_state: WriterTaskRequestState::TransactionRolledBack,
208 ..
209 }
210 ) {
211 for plan in handles {
212 let _ = plan.finish_rollback(access.as_ref()).await;
213 }
214 }
215 Err(RuntimeError::Storage(error))
216 }
217 }
218 }
219
220 pub async fn claim_entity_if_absent(
223 &self,
224 token: &NamespaceToken,
225 spec: EntityClaimSpec,
226 ) -> RuntimeResult<(Entity, bool)> {
227 self.validate_entity_kind(&spec.kind)?;
228 let entity_type =
229 self.validate_entity_type_for_kind(&spec.kind, spec.entity_type.as_deref())?;
230 crate::secret_gate::reject_reserved_secret_gate_property(spec.properties.as_ref())?;
231
232 let mut proposed = Entity::new(token.namespace().as_str(), &spec.kind, &spec.name);
233 proposed.id = spec.id;
234 proposed.entity_type = entity_type.clone();
235 proposed.description = spec.description;
236 proposed.properties = spec.properties;
237 proposed.tags = spec.tags;
238
239 let admission = prepare_entity_admission(token, EntityEntryPoint::Claim, proposed)?;
240 let store = self.entities(token)?;
241 let (inserted, indexes_committed) = match admission {
242 EntityAdmission::Legacy(candidate) => {
243 proposed = candidate;
244 (
245 store.insert_entity_if_absent(proposed.clone()).await?,
246 false,
247 )
248 }
249 EntityAdmission::Exempt(prepared) => {
250 proposed = prepared.entity().clone();
251 let (mut required, _) = self
252 .prepare_admitted_entity_indexes(token, &proposed, &[], true)
253 .await?;
254 let _ = self.events(token)?;
255 let event = crate::EventAttribution::from_token(token)
256 .stamp(claimed_entity_create_event(&proposed));
257 required.extend(
258 khive_db::stores::event::event_insert_statements(&event)
259 .map_err(|error| RuntimeError::Internal(error.to_string()))?
260 .into_iter()
261 .map(|statement| PlanStatement {
262 statement,
263 guard: Some(AffectedRowGuard::exactly(1)),
264 }),
265 );
266 let plan = prepared.into_plan(
267 EntityCandidateMutation::CreateIfAbsent,
268 required,
269 PostCommitEffect::None,
270 )?;
271 match run_atomic_unit(
272 self.sql().as_ref(),
273 vec![AtomicOpPlan::FinalizeEntity(Box::new(plan))],
274 )
275 .await
276 {
277 Ok(AtomicRunOutcome::Committed { .. }) => (true, true),
278 Ok(AtomicRunOutcome::RolledBack {
279 failure: crate::atomic_runner::AtomicOpFailure::GuardFailed { .. },
280 ..
281 }) => (false, false),
282 Ok(AtomicRunOutcome::RolledBack { failure, .. }) => {
283 return Err(RuntimeError::Internal(format!(
284 "entity claim finalization rolled back: {failure:?}"
285 )));
286 }
287 Err(error) => return Err(RuntimeError::Storage(error.0)),
288 }
289 }
290 };
291 let entity = if inserted {
292 proposed
293 } else {
294 store
295 .get_entity_including_deleted(spec.id)
296 .await?
297 .ok_or_else(|| {
298 RuntimeError::Internal(format!(
299 "entity claim {} lost but the winning row is missing",
300 spec.id
301 ))
302 })?
303 };
304 if entity.deleted_at.is_some() {
305 return Err(RuntimeError::InvalidInput(format!(
306 "entity claim {} is soft-deleted; restore it explicitly",
307 entity.id
308 )));
309 }
310 if entity.namespace != token.namespace().as_str()
311 || entity.kind != spec.kind
312 || entity.entity_type.as_deref() != entity_type.as_deref()
313 || !entity.name.eq_ignore_ascii_case(&spec.name)
314 || !entity
315 .tags
316 .iter()
317 .any(|tag| tag.eq_ignore_ascii_case(&spec.identity_tag))
318 {
319 return Err(RuntimeError::InvalidInput(format!(
320 "entity claim {} belongs to a different record",
321 entity.id
322 )));
323 }
324
325 if !indexes_committed {
326 self.ensure_claimed_entity_create_event(token, &entity)
327 .await?;
328 self.reindex_claimed_entity(token, &entity).await?;
329 }
330 Ok((entity, inserted))
331 }
332
333 pub async fn ensure_claimed_entity_create_event(
336 &self,
337 token: &NamespaceToken,
338 entity: &Entity,
339 ) -> RuntimeResult<()> {
340 if entity.namespace != token.namespace().as_str() || entity.deleted_at.is_some() {
341 return Err(RuntimeError::InvalidInput(format!(
342 "entity {} is not a live row in the write namespace",
343 entity.id
344 )));
345 }
346 let events = self.events(token).map_err(|error| {
347 RuntimeError::Internal(format!(
348 "entity {} persists but its create event store is unavailable: {error}",
349 entity.id
350 ))
351 })?;
352 let filter = EventFilter {
353 target_id: Some(entity.id),
354 kinds: vec![EventKind::EntityCreated],
355 verbs: vec!["create".into()],
356 substrates: vec![SubstrateKind::Entity],
357 after: Some(entity.created_at.saturating_sub(1)),
358 ..EventFilter::default()
359 };
360 let page = PageRequest {
361 offset: 0,
362 limit: 1,
363 };
364 if !events
365 .query_events(filter.clone(), page.clone())
366 .await?
367 .items
368 .is_empty()
369 {
370 return Ok(());
371 }
372
373 let event = claimed_entity_create_event(entity);
374 if let Err(error) = events.append_event(event).await {
375 if events.query_events(filter, page).await?.items.is_empty() {
376 return Err(RuntimeError::Internal(format!(
377 "entity {} persists but its create event failed: {error}",
378 entity.id
379 )));
380 }
381 }
382 Ok(())
383 }
384
385 pub async fn reindex_claimed_entity(
388 &self,
389 token: &NamespaceToken,
390 entity: &Entity,
391 ) -> RuntimeResult<()> {
392 if entity.namespace != token.namespace().as_str() || entity.deleted_at.is_some() {
393 return Err(RuntimeError::InvalidInput(format!(
394 "entity {} is not a live row in the write namespace",
395 entity.id
396 )));
397 }
398 let doc = entity_fts_document(entity);
399 let embed_body = doc.body.clone();
400 #[cfg(any(test, feature = "fault-injection"))]
401 let fts_inject = consume_fault(&FTS_FAIL_NS, &entity.namespace);
402 #[cfg(not(any(test, feature = "fault-injection")))]
403 let fts_inject = false;
404 let fts_result = if fts_inject {
405 Err(RuntimeError::Internal("injected FTS failure".into()))
406 } else {
407 match self.text(token) {
408 Ok(_) => {
409 let statements = khive_db::stores::text::delete_document_statements(
410 "fts_entities",
411 &entity.namespace,
412 entity.id,
413 )
414 .into_iter()
415 .chain(khive_db::stores::text::insert_document_statements(
416 "fts_entities",
417 &doc,
418 ))
419 .collect();
420 self.apply_entity_index_revision(entity, statements).await
421 }
422 Err(error) => Err(error),
423 }
424 };
425 let published = fts_result.map_err(|error| {
426 RuntimeError::Internal(format!(
427 "entity {} persists but its text index failed: {error}",
428 entity.id
429 ))
430 })?;
431 if !published {
432 return Err(RuntimeError::Internal(format!(
433 "entity {} persists but changed concurrently before text index publication; retry against the current row",
434 entity.id
435 )));
436 }
437
438 for model_name in self.registered_embedding_model_names() {
439 let outcome = self
440 .embed_document_with_model_outcome_for_token(token, &model_name, &embed_body)
441 .await
442 .map_err(|error| {
443 RuntimeError::Internal(format!(
444 "entity {} persists but model {model_name} embedding failed: {error}",
445 entity.id
446 ))
447 })?;
448 #[cfg(any(test, feature = "fault-injection"))]
449 let vector_inject = consume_fault(&VECTOR_FAIL_NS, &entity.namespace);
450 #[cfg(not(any(test, feature = "fault-injection")))]
451 let vector_inject = false;
452 if vector_inject {
453 return Err(RuntimeError::Internal(format!(
454 "entity {} persists but model {model_name} vector indexing failed: injected vector failure",
455 entity.id
456 )));
457 }
458 let published = self
459 .publish_entity_vector_revision(token, entity, &model_name, &outcome.vector)
460 .await
461 .map_err(|error| {
462 RuntimeError::Internal(format!(
463 "entity {} persists but model {model_name} vector indexing failed: {error}",
464 entity.id
465 ))
466 })?;
467 if !published {
468 return Err(RuntimeError::Internal(format!(
469 "entity {} persists but changed concurrently before model {model_name} vector publication; retry against the current row",
470 entity.id
471 )));
472 }
473 }
474 Ok(())
475 }
476
477 #[allow(clippy::too_many_arguments)]
488 #[cfg(test)]
489 pub(crate) async fn create_entity(
490 &self,
491 token: &NamespaceToken,
492 kind: &str,
493 entity_type: Option<&str>,
494 name: &str,
495 description: Option<&str>,
496 properties: Option<serde_json::Value>,
497 tags: Vec<String>,
498 ) -> RuntimeResult<Entity> {
499 let (entity, _, degradations) = self
500 .create_entity_with_embedding_report_inner(
501 token,
502 kind,
503 entity_type,
504 name,
505 description,
506 properties,
507 tags,
508 Vec::new(),
509 )
510 .await?;
511 legacy_post_commit_result("create_entity", entity.id, entity, degradations)
512 }
513
514 #[allow(clippy::too_many_arguments)]
527 pub async fn create_entity_with_attachments(
528 &self,
529 token: &NamespaceToken,
530 kind: &str,
531 entity_type: Option<&str>,
532 name: &str,
533 description: Option<&str>,
534 properties: Option<serde_json::Value>,
535 tags: Vec<String>,
536 attachments: Vec<NewAttachment>,
537 ) -> RuntimeResult<Entity> {
538 let (entity, embedding, degradations) = self
539 .create_entity_with_attachments_inner(
540 token,
541 kind,
542 entity_type,
543 name,
544 description,
545 properties,
546 tags,
547 attachments,
548 )
549 .await?;
550 legacy_post_commit_result_with_embedding(
551 "create_entity_with_attachments",
552 entity.id,
553 entity,
554 embedding,
555 degradations,
556 )
557 }
558
559 #[allow(clippy::too_many_arguments)]
561 pub async fn create_entity_with_attachments_and_report(
562 &self,
563 token: &NamespaceToken,
564 kind: &str,
565 entity_type: Option<&str>,
566 name: &str,
567 description: Option<&str>,
568 properties: Option<serde_json::Value>,
569 tags: Vec<String>,
570 attachments: Vec<NewAttachment>,
571 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
572 let (entity, embedding, degradations) = self
573 .create_entity_with_attachments_inner(
574 token,
575 kind,
576 entity_type,
577 name,
578 description,
579 properties,
580 tags,
581 attachments,
582 )
583 .await?;
584 legacy_post_commit_result(
585 "create_entity_with_attachments_and_report",
586 entity.id,
587 (entity, embedding),
588 degradations,
589 )
590 }
591
592 #[allow(clippy::too_many_arguments)]
593 async fn create_entity_with_attachments_inner(
594 &self,
595 token: &NamespaceToken,
596 kind: &str,
597 entity_type: Option<&str>,
598 name: &str,
599 description: Option<&str>,
600 properties: Option<serde_json::Value>,
601 tags: Vec<String>,
602 attachments: Vec<NewAttachment>,
603 ) -> RuntimeResult<(
604 Entity,
605 crate::retrieval::EmbeddingTruncationReport,
606 Vec<PostCommitDegradation>,
607 )> {
608 drop(self.attachments()?);
612 let blob_store = self.blob_store().ok_or_else(|| {
613 RuntimeError::Unconfigured(
614 "create_entity_with_attachments requires an installed BlobStore".to_string(),
615 )
616 })?;
617 let mut roles = std::collections::HashSet::with_capacity(attachments.len());
618 for attachment in &attachments {
619 attachment.validate()?;
620 if !roles.insert(attachment.role.as_str()) {
621 return Err(RuntimeError::InvalidInput(format!(
622 "duplicate attachment role {:?}",
623 attachment.role
624 )));
625 }
626 }
627 for attachment in &attachments {
628 if !blob_store.exists(&attachment.content_ref).await? {
629 return Err(RuntimeError::InvalidInput(format!(
630 "create_entity_with_attachments requires a published blob; no object exists for {}",
631 attachment.content_ref
632 )));
633 }
634 }
635 let validated_type = self.validate_entity_type_for_kind(kind, entity_type)?;
636 let (entity, embedding, degradations) = self
637 .create_entity_with_embedding_report_inner(
638 token,
639 kind,
640 validated_type.as_deref(),
641 name,
642 description,
643 properties,
644 tags,
645 attachments,
646 )
647 .await?;
648 Ok((entity, embedding, degradations))
649 }
650
651 #[allow(clippy::too_many_arguments)]
652 pub async fn create_entity_with_embedding_report(
653 &self,
654 token: &NamespaceToken,
655 kind: &str,
656 entity_type: Option<&str>,
657 name: &str,
658 description: Option<&str>,
659 properties: Option<serde_json::Value>,
660 tags: Vec<String>,
661 ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
662 let (entity, embedding, degradations) = self
663 .create_entity_with_embedding_report_inner(
664 token,
665 kind,
666 entity_type,
667 name,
668 description,
669 properties,
670 tags,
671 Vec::new(),
672 )
673 .await?;
674 legacy_post_commit_result(
675 "create_entity_with_embedding_report",
676 entity.id,
677 (entity, embedding),
678 degradations,
679 )
680 }
681
682 #[allow(clippy::too_many_arguments)]
684 pub async fn create_entity_with_post_commit_report(
685 &self,
686 token: &NamespaceToken,
687 kind: &str,
688 entity_type: Option<&str>,
689 name: &str,
690 description: Option<&str>,
691 properties: Option<serde_json::Value>,
692 tags: Vec<String>,
693 ) -> RuntimeResult<(
694 Entity,
695 crate::retrieval::EmbeddingTruncationReport,
696 Vec<PostCommitDegradation>,
697 )> {
698 self.create_entity_with_embedding_report_inner(
699 token,
700 kind,
701 entity_type,
702 name,
703 description,
704 properties,
705 tags,
706 Vec::new(),
707 )
708 .await
709 }
710
711 #[allow(clippy::too_many_arguments)]
712 async fn create_entity_with_embedding_report_inner(
713 &self,
714 token: &NamespaceToken,
715 kind: &str,
716 entity_type: Option<&str>,
717 name: &str,
718 description: Option<&str>,
719 properties: Option<serde_json::Value>,
720 tags: Vec<String>,
721 attachments: Vec<NewAttachment>,
722 ) -> RuntimeResult<(
723 Entity,
724 crate::retrieval::EmbeddingTruncationReport,
725 Vec<PostCommitDegradation>,
726 )> {
727 self.validate_entity_kind(kind)?;
728 crate::secret_gate::reject_reserved_secret_gate_property(properties.as_ref())?;
729 let ns = token.namespace().as_str();
730 let mut entity = Entity::new(ns, kind, name).with_entity_type(entity_type);
731 if let Some(d) = description {
732 entity = entity.with_description(d);
733 }
734 if let Some(p) = properties {
735 entity = entity.with_properties(p);
736 }
737 if !tags.is_empty() {
738 entity = entity.with_tags(tags);
739 }
740 let projected_content_ref = attachments
741 .iter()
742 .find(|attachment| attachment.role == "content")
743 .map(|attachment| attachment.content_ref.to_string());
744 let attachment_rows: Vec<Attachment> = attachments
745 .into_iter()
746 .map(|attachment| {
747 Attachment::from_new(
748 entity.id,
749 AttachmentSubstrate::Entity,
750 attachment,
751 entity.created_at,
752 )
753 })
754 .collect();
755 entity.content_ref = projected_content_ref.clone();
756 entity = match prepare_entity_admission(token, EntityEntryPoint::Create, entity)? {
757 EntityAdmission::Legacy(candidate) => candidate,
758 EntityAdmission::Exempt(prepared) => {
759 let entity = prepared.entity().clone();
760 let (required, report) = self
761 .prepare_admitted_entity_indexes(token, &entity, &attachment_rows, true)
762 .await?;
763 let plan = prepared.into_plan(
764 EntityCandidateMutation::CreateIfAbsent,
765 required,
766 PostCommitEffect::None,
767 )?;
768 match run_atomic_unit(
769 self.sql().as_ref(),
770 vec![AtomicOpPlan::FinalizeEntity(Box::new(plan))],
771 )
772 .await
773 {
774 Ok(AtomicRunOutcome::Committed { .. }) => {
775 let degradations = self.record_created_entity_event(token, &entity).await;
776 return Ok((entity, report, degradations));
777 }
778 Ok(AtomicRunOutcome::RolledBack { failure, .. }) => {
779 return Err(RuntimeError::Internal(format!(
780 "entity finalization rolled back: {failure:?}"
781 )));
782 }
783 Err(error) => return Err(RuntimeError::Storage(error.0)),
784 }
785 }
786 };
787 self.entities(token)?
788 .upsert_entity_with_attachments(entity.clone(), attachment_rows)
789 .await?;
790 entity.content_ref = projected_content_ref;
791
792 let doc = entity_fts_document(&entity);
793 let embed_body = doc.body.clone();
794
795 {
797 #[cfg(any(test, feature = "fault-injection"))]
798 let fts_inject = consume_fault(&FTS_FAIL_NS, ns);
799 #[cfg(not(any(test, feature = "fault-injection")))]
800 let fts_inject = false;
801 let fts_result: RuntimeResult<()> = if fts_inject {
802 Err(RuntimeError::Internal("injected FTS failure".to_string()))
803 } else {
804 match self.text(token) {
805 Ok(fts) => fts.upsert_document(doc).await.map_err(RuntimeError::from),
806 Err(e) => Err(e),
807 }
808 };
809 if let Err(e) = fts_result {
810 let cleanup_errors = self
811 .compensate_entity_create(token, entity.id, ns, &[])
812 .await;
813 return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
814 }
815 }
816
817 let embed_model_names = {
820 let names = self.registered_embedding_model_names();
821 if names.is_empty() {
822 vec![]
823 } else {
824 names
825 }
826 };
827
828 let mut embedding_report = crate::retrieval::EmbeddingTruncationReport::default();
829 if embed_model_names.len() == 1 {
830 let model_name = &embed_model_names[0];
831 let vec_result = self
832 .embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
833 .await;
834
835 #[cfg(any(test, feature = "fault-injection"))]
836 let vec_inject = consume_fault(&VECTOR_FAIL_NS, ns);
837 #[cfg(not(any(test, feature = "fault-injection")))]
838 let vec_inject = false;
839 let vec_result: RuntimeResult<crate::retrieval::DocumentEmbeddingOutcome> =
840 if vec_inject {
841 Err(RuntimeError::Internal(
842 "injected vector failure".to_string(),
843 ))
844 } else {
845 vec_result
846 };
847
848 let single_result: RuntimeResult<()> = match vec_result {
849 Ok(outcome) => {
850 embedding_report.observe(&outcome);
851 match self.vectors_for_model(token, model_name) {
852 Ok(vs) => vs
853 .insert(
854 entity.id,
855 SubstrateKind::Entity,
856 ns,
857 "entity.body",
858 vec![outcome.vector],
859 )
860 .await
861 .map_err(RuntimeError::from),
862 Err(e) => Err(e),
863 }
864 }
865 Err(e) => Err(e),
866 };
867 if let Err(e) = single_result {
868 let cleanup_errors = self
869 .compensate_entity_create(
870 token,
871 entity.id,
872 ns,
873 std::slice::from_ref(model_name),
874 )
875 .await;
876 return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
877 }
878 } else if !embed_model_names.is_empty() {
879 let rt_clone = self.clone();
882 let body_owned = embed_body.clone();
883 let usage_ctx = crate::usage::current();
884 let mut join_set = tokio::task::JoinSet::new();
885 for (idx, model_name) in embed_model_names.iter().enumerate() {
886 let rt = rt_clone.clone();
887 let text = body_owned.clone();
888 let name = model_name.clone();
889 let ctx = usage_ctx.clone();
890 let token = (*token).clone();
891 join_set.spawn(crate::runtime::inherit_request_embedder_scope(async move {
892 let fut = rt.embed_document_with_model_outcome_for_token(&token, &name, &text);
893 let result = match ctx {
894 Some(ctx) => crate::usage::scope(ctx, fut).await,
895 None => fut.await,
896 };
897 (idx, result)
898 }));
899 }
900 let outcomes = match drain_embed_join_set(join_set, embed_model_names.len()).await {
904 Ok(outcomes) => outcomes,
905 Err(e) => {
906 let cleanup_errors = self
907 .compensate_entity_create(token, entity.id, ns, &[])
908 .await;
909 return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
910 }
911 };
912 let mut inserted_models: Vec<String> = Vec::with_capacity(embed_model_names.len());
914 for (model_name, outcome) in embed_model_names.iter().zip(outcomes) {
915 embedding_report.observe(&outcome);
916 #[cfg(any(test, feature = "fault-injection"))]
918 let count_inject = VECTOR_FAIL_AFTER.with(|cell| match cell.get() {
919 Some(0) => {
920 cell.set(None);
921 true
922 }
923 Some(n) => {
924 cell.set(Some(n - 1));
925 false
926 }
927 None => false,
928 });
929 #[cfg(not(any(test, feature = "fault-injection")))]
930 let count_inject = false;
931
932 let insert_result = if count_inject {
933 Err(RuntimeError::Internal(
934 "injected vector insert failure".to_string(),
935 ))
936 } else {
937 match self.vectors_for_model(token, model_name) {
938 Ok(vs) => vs
939 .insert(
940 entity.id,
941 SubstrateKind::Entity,
942 ns,
943 "entity.body",
944 vec![outcome.vector],
945 )
946 .await
947 .map_err(RuntimeError::from),
948 Err(e) => Err(e),
949 }
950 };
951 if let Err(e) = insert_result {
952 let mut cleanup_models = inserted_models.clone();
955 cleanup_models.push(model_name.clone());
956 let cleanup_errors = self
957 .compensate_entity_create(token, entity.id, ns, &cleanup_models)
958 .await;
959 return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
960 }
961 inserted_models.push(model_name.clone());
962 }
963 }
964
965 let degradations = self.record_created_entity_event(token, &entity).await;
966 Ok((entity, embedding_report, degradations))
967 }
968
969 async fn record_created_entity_event(
970 &self,
971 token: &NamespaceToken,
972 entity: &Entity,
973 ) -> Vec<PostCommitDegradation> {
974 let created_event = khive_storage::event::Event::new(
981 entity.namespace.clone(),
982 "create",
983 EventKind::EntityCreated,
984 SubstrateKind::Entity,
985 "",
986 )
987 .with_target(entity.id)
988 .with_payload(serde_json::json!({
989 "id": entity.id,
990 "namespace": entity.namespace,
991 "kind": entity.kind,
992 }));
993 let event_result = match self.events(token) {
994 Ok(store) => store
995 .append_event(created_event)
996 .await
997 .map_err(RuntimeError::from),
998 Err(error) => Err(error),
999 };
1000 let mut degradations = Vec::new();
1001 if let Err(error) = event_result {
1002 record_post_commit_degradation(
1003 &mut degradations,
1004 "create_entity",
1005 entity.id,
1006 "event_append",
1007 error,
1008 );
1009 }
1010
1011 degradations
1012 }
1013}