Skip to main content

khive_runtime/operations/
entity_create.rs

1//! Entity construction, claims and their indexing outcomes.
2
3use 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    /// Mirror document=(name,masked_content), source=(URI,type,checksum), previous=caller-resolved URI head; first-poll-ready cursor(writer,new_id) rechecks head/fence. Outer Ok commits; inner Err is post-commit; outer Err may be unknown.
34    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    /// Claim a caller-derived entity id without replacing a competing row.
221    /// Index writes are repeatable and never compensate by deleting the claim.
222    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    /// A claimed row may survive a failed event append. Verify the event before
334    /// a retry can report the row as registered.
335    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    /// Repair a claimed row after an earlier post-insert indexing failure.
386    /// This path is strict: any failed index stage names the still-live id.
387    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    /// Create and persist a new entity.
478    ///
479    /// Indexing failures trigger compensation across the entity row, FTS
480    /// document, and any vector models touched by this call. If compensation
481    /// also fails, the returned structured internal error identifies possible
482    /// partial persistence, includes both failure classes, and carries the
483    /// entity ID as a reconciliation handle.
484    // REASON: entity creation requires kind, type, name, description, properties, tags, and
485    // namespace token — refactoring into a builder would add indirection without reducing
486    // caller complexity; this signature mirrors the MCP verb surface directly.
487    #[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    /// Create an entity with role-keyed bytes already published to `BlobStore`.
515    ///
516    /// Every [`NewAttachment`] carries a typed content reference, so malformed
517    /// references cannot enter through this consumer seam. Blob existence is
518    /// checked before the database write. The entity row and all attachment rows
519    /// then commit in one storage transaction; the FTS/vector compensation path
520    /// hard-deletes the entity and its attachments together if a later indexing
521    /// step fails. Published bytes remain recoverable by the BlobStore grace-period
522    /// orphan policy when any post-publication step fails.
523    /// A bounded embedding returns a non-retryable error carrying the committed
524    /// entity ID and truncation report; use the report-aware variant to receive
525    /// the entity and report together.
526    #[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    /// Create an entity with attachments and retain embedding truncation accounting.
560    #[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        // Attachment rows are the process-wide BlobStore's liveness authority.
609        // Validate placement before existence probes or any record write: pack
610        // runtimes bound to a secondary backend must explicitly call `core()`.
611        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    /// The committed entity and its non-retryable post-commit diagnostics.
683    #[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        // FTS step — compensate entity row on failure (mirrors create_note_inner).
796        {
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        // Vector embedding + insert step — compensate entity row + FTS doc on failure.
818        // Fan out to ALL registered models (mirrors create_note_inner multi-model path).
819        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            // Multi-model path: embed with each model in parallel, then insert sequentially
880            // with inserted_models tracking for rollback on partial failure.
881            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            // The first failed or panicked handle aborts and detaches its
901            // siblings. Embed usage is counted at dispatch, so a synchronous
902            // provider winding down in the background cannot change it.
903            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            // TODO(P2): parallelize vector inserts
913            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                // Count-targetable fault injection for multi-model insert path.
917                #[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                    // Include the model whose INSERT returned an error: a backend
953                    // error does not prove the write had no side effects.
954                    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        // The arrival event, appended only after every compensating step has had
975        // its chance to fire: a create that rolled back returns above and never
976        // reaches here, so the event plane cannot name an entity that does not
977        // exist. Deletes and updates already emitted theirs; creates did not,
978        // which left the audit trail able to say what left the graph and not
979        // what entered it.
980        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}