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(text) => text.upsert_document(doc).await.map_err(Into::into),
409                Err(error) => Err(error),
410            }
411        };
412        fts_result.map_err(|error| {
413            RuntimeError::Internal(format!(
414                "entity {} persists but its text index failed: {error}",
415                entity.id
416            ))
417        })?;
418
419        for model_name in self.registered_embedding_model_names() {
420            let outcome = self
421                .embed_document_with_model_outcome_for_token(token, &model_name, &embed_body)
422                .await
423                .map_err(|error| {
424                    RuntimeError::Internal(format!(
425                        "entity {} persists but model {model_name} embedding failed: {error}",
426                        entity.id
427                    ))
428                })?;
429            #[cfg(any(test, feature = "fault-injection"))]
430            let vector_inject = consume_fault(&VECTOR_FAIL_NS, &entity.namespace);
431            #[cfg(not(any(test, feature = "fault-injection")))]
432            let vector_inject = false;
433            if vector_inject {
434                return Err(RuntimeError::Internal(format!(
435                    "entity {} persists but model {model_name} vector indexing failed: injected vector failure",
436                    entity.id
437                )));
438            }
439            self.vectors_for_model(token, &model_name)
440                .map_err(|error| {
441                    RuntimeError::Internal(format!(
442                        "entity {} persists but model {model_name} vector store is unavailable: {error}",
443                        entity.id
444                    ))
445                })?
446                .insert(
447                    entity.id,
448                    SubstrateKind::Entity,
449                    &entity.namespace,
450                    "entity.body",
451                    vec![outcome.vector],
452                )
453                .await
454                .map_err(|error| {
455                    RuntimeError::Internal(format!(
456                        "entity {} persists but model {model_name} vector indexing failed: {error}",
457                        entity.id
458                    ))
459                })?;
460        }
461        Ok(())
462    }
463
464    /// Create and persist a new entity.
465    ///
466    /// Indexing failures trigger compensation across the entity row, FTS
467    /// document, and any vector models touched by this call. If compensation
468    /// also fails, the returned structured internal error identifies possible
469    /// partial persistence, includes both failure classes, and carries the
470    /// entity ID as a reconciliation handle.
471    // REASON: entity creation requires kind, type, name, description, properties, tags, and
472    // namespace token — refactoring into a builder would add indirection without reducing
473    // caller complexity; this signature mirrors the MCP verb surface directly.
474    #[allow(clippy::too_many_arguments)]
475    #[cfg(test)]
476    pub(crate) async fn create_entity(
477        &self,
478        token: &NamespaceToken,
479        kind: &str,
480        entity_type: Option<&str>,
481        name: &str,
482        description: Option<&str>,
483        properties: Option<serde_json::Value>,
484        tags: Vec<String>,
485    ) -> RuntimeResult<Entity> {
486        let (entity, _, degradations) = self
487            .create_entity_with_embedding_report_inner(
488                token,
489                kind,
490                entity_type,
491                name,
492                description,
493                properties,
494                tags,
495                Vec::new(),
496            )
497            .await?;
498        legacy_post_commit_result("create_entity", entity.id, entity, degradations)
499    }
500
501    /// Create an entity with role-keyed bytes already published to `BlobStore`.
502    ///
503    /// Every [`NewAttachment`] carries a typed content reference, so malformed
504    /// references cannot enter through this consumer seam. Blob existence is
505    /// checked before the database write. The entity row and all attachment rows
506    /// then commit in one storage transaction; the FTS/vector compensation path
507    /// hard-deletes the entity and its attachments together if a later indexing
508    /// step fails. Published bytes remain recoverable by the BlobStore grace-period
509    /// orphan policy when any post-publication step fails.
510    /// A bounded embedding returns a non-retryable error carrying the committed
511    /// entity ID and truncation report; use the report-aware variant to receive
512    /// the entity and report together.
513    #[allow(clippy::too_many_arguments)]
514    pub async fn create_entity_with_attachments(
515        &self,
516        token: &NamespaceToken,
517        kind: &str,
518        entity_type: Option<&str>,
519        name: &str,
520        description: Option<&str>,
521        properties: Option<serde_json::Value>,
522        tags: Vec<String>,
523        attachments: Vec<NewAttachment>,
524    ) -> RuntimeResult<Entity> {
525        let (entity, embedding, degradations) = self
526            .create_entity_with_attachments_inner(
527                token,
528                kind,
529                entity_type,
530                name,
531                description,
532                properties,
533                tags,
534                attachments,
535            )
536            .await?;
537        legacy_post_commit_result_with_embedding(
538            "create_entity_with_attachments",
539            entity.id,
540            entity,
541            embedding,
542            degradations,
543        )
544    }
545
546    /// Create an entity with attachments and retain embedding truncation accounting.
547    #[allow(clippy::too_many_arguments)]
548    pub async fn create_entity_with_attachments_and_report(
549        &self,
550        token: &NamespaceToken,
551        kind: &str,
552        entity_type: Option<&str>,
553        name: &str,
554        description: Option<&str>,
555        properties: Option<serde_json::Value>,
556        tags: Vec<String>,
557        attachments: Vec<NewAttachment>,
558    ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
559        let (entity, embedding, degradations) = self
560            .create_entity_with_attachments_inner(
561                token,
562                kind,
563                entity_type,
564                name,
565                description,
566                properties,
567                tags,
568                attachments,
569            )
570            .await?;
571        legacy_post_commit_result(
572            "create_entity_with_attachments_and_report",
573            entity.id,
574            (entity, embedding),
575            degradations,
576        )
577    }
578
579    #[allow(clippy::too_many_arguments)]
580    async fn create_entity_with_attachments_inner(
581        &self,
582        token: &NamespaceToken,
583        kind: &str,
584        entity_type: Option<&str>,
585        name: &str,
586        description: Option<&str>,
587        properties: Option<serde_json::Value>,
588        tags: Vec<String>,
589        attachments: Vec<NewAttachment>,
590    ) -> RuntimeResult<(
591        Entity,
592        crate::retrieval::EmbeddingTruncationReport,
593        Vec<PostCommitDegradation>,
594    )> {
595        // Attachment rows are the process-wide BlobStore's liveness authority.
596        // Validate placement before existence probes or any record write: pack
597        // runtimes bound to a secondary backend must explicitly call `core()`.
598        drop(self.attachments()?);
599        let blob_store = self.blob_store().ok_or_else(|| {
600            RuntimeError::Unconfigured(
601                "create_entity_with_attachments requires an installed BlobStore".to_string(),
602            )
603        })?;
604        let mut roles = std::collections::HashSet::with_capacity(attachments.len());
605        for attachment in &attachments {
606            attachment.validate()?;
607            if !roles.insert(attachment.role.as_str()) {
608                return Err(RuntimeError::InvalidInput(format!(
609                    "duplicate attachment role {:?}",
610                    attachment.role
611                )));
612            }
613        }
614        for attachment in &attachments {
615            if !blob_store.exists(&attachment.content_ref).await? {
616                return Err(RuntimeError::InvalidInput(format!(
617                    "create_entity_with_attachments requires a published blob; no object exists for {}",
618                    attachment.content_ref
619                )));
620            }
621        }
622        let validated_type = self.validate_entity_type_for_kind(kind, entity_type)?;
623        let (entity, embedding, degradations) = self
624            .create_entity_with_embedding_report_inner(
625                token,
626                kind,
627                validated_type.as_deref(),
628                name,
629                description,
630                properties,
631                tags,
632                attachments,
633            )
634            .await?;
635        Ok((entity, embedding, degradations))
636    }
637
638    #[allow(clippy::too_many_arguments)]
639    pub async fn create_entity_with_embedding_report(
640        &self,
641        token: &NamespaceToken,
642        kind: &str,
643        entity_type: Option<&str>,
644        name: &str,
645        description: Option<&str>,
646        properties: Option<serde_json::Value>,
647        tags: Vec<String>,
648    ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
649        let (entity, embedding, degradations) = self
650            .create_entity_with_embedding_report_inner(
651                token,
652                kind,
653                entity_type,
654                name,
655                description,
656                properties,
657                tags,
658                Vec::new(),
659            )
660            .await?;
661        legacy_post_commit_result(
662            "create_entity_with_embedding_report",
663            entity.id,
664            (entity, embedding),
665            degradations,
666        )
667    }
668
669    /// The committed entity and its non-retryable post-commit diagnostics.
670    #[allow(clippy::too_many_arguments)]
671    pub async fn create_entity_with_post_commit_report(
672        &self,
673        token: &NamespaceToken,
674        kind: &str,
675        entity_type: Option<&str>,
676        name: &str,
677        description: Option<&str>,
678        properties: Option<serde_json::Value>,
679        tags: Vec<String>,
680    ) -> RuntimeResult<(
681        Entity,
682        crate::retrieval::EmbeddingTruncationReport,
683        Vec<PostCommitDegradation>,
684    )> {
685        self.create_entity_with_embedding_report_inner(
686            token,
687            kind,
688            entity_type,
689            name,
690            description,
691            properties,
692            tags,
693            Vec::new(),
694        )
695        .await
696    }
697
698    #[allow(clippy::too_many_arguments)]
699    async fn create_entity_with_embedding_report_inner(
700        &self,
701        token: &NamespaceToken,
702        kind: &str,
703        entity_type: Option<&str>,
704        name: &str,
705        description: Option<&str>,
706        properties: Option<serde_json::Value>,
707        tags: Vec<String>,
708        attachments: Vec<NewAttachment>,
709    ) -> RuntimeResult<(
710        Entity,
711        crate::retrieval::EmbeddingTruncationReport,
712        Vec<PostCommitDegradation>,
713    )> {
714        self.validate_entity_kind(kind)?;
715        crate::secret_gate::reject_reserved_secret_gate_property(properties.as_ref())?;
716        let ns = token.namespace().as_str();
717        let mut entity = Entity::new(ns, kind, name).with_entity_type(entity_type);
718        if let Some(d) = description {
719            entity = entity.with_description(d);
720        }
721        if let Some(p) = properties {
722            entity = entity.with_properties(p);
723        }
724        if !tags.is_empty() {
725            entity = entity.with_tags(tags);
726        }
727        let projected_content_ref = attachments
728            .iter()
729            .find(|attachment| attachment.role == "content")
730            .map(|attachment| attachment.content_ref.to_string());
731        let attachment_rows: Vec<Attachment> = attachments
732            .into_iter()
733            .map(|attachment| {
734                Attachment::from_new(
735                    entity.id,
736                    AttachmentSubstrate::Entity,
737                    attachment,
738                    entity.created_at,
739                )
740            })
741            .collect();
742        entity.content_ref = projected_content_ref.clone();
743        entity = match prepare_entity_admission(token, EntityEntryPoint::Create, entity)? {
744            EntityAdmission::Legacy(candidate) => candidate,
745            EntityAdmission::Exempt(prepared) => {
746                let entity = prepared.entity().clone();
747                let (required, report) = self
748                    .prepare_admitted_entity_indexes(token, &entity, &attachment_rows, true)
749                    .await?;
750                let plan = prepared.into_plan(
751                    EntityCandidateMutation::CreateIfAbsent,
752                    required,
753                    PostCommitEffect::None,
754                )?;
755                match run_atomic_unit(
756                    self.sql().as_ref(),
757                    vec![AtomicOpPlan::FinalizeEntity(Box::new(plan))],
758                )
759                .await
760                {
761                    Ok(AtomicRunOutcome::Committed { .. }) => {
762                        let degradations = self.record_created_entity_event(token, &entity).await;
763                        return Ok((entity, report, degradations));
764                    }
765                    Ok(AtomicRunOutcome::RolledBack { failure, .. }) => {
766                        return Err(RuntimeError::Internal(format!(
767                            "entity finalization rolled back: {failure:?}"
768                        )));
769                    }
770                    Err(error) => return Err(RuntimeError::Storage(error.0)),
771                }
772            }
773        };
774        self.entities(token)?
775            .upsert_entity_with_attachments(entity.clone(), attachment_rows)
776            .await?;
777        entity.content_ref = projected_content_ref;
778
779        let doc = entity_fts_document(&entity);
780        let embed_body = doc.body.clone();
781
782        // FTS step — compensate entity row on failure (mirrors create_note_inner).
783        {
784            #[cfg(any(test, feature = "fault-injection"))]
785            let fts_inject = consume_fault(&FTS_FAIL_NS, ns);
786            #[cfg(not(any(test, feature = "fault-injection")))]
787            let fts_inject = false;
788            let fts_result: RuntimeResult<()> = if fts_inject {
789                Err(RuntimeError::Internal("injected FTS failure".to_string()))
790            } else {
791                match self.text(token) {
792                    Ok(fts) => fts.upsert_document(doc).await.map_err(RuntimeError::from),
793                    Err(e) => Err(e),
794                }
795            };
796            if let Err(e) = fts_result {
797                let cleanup_errors = self
798                    .compensate_entity_create(token, entity.id, ns, &[])
799                    .await;
800                return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
801            }
802        }
803
804        // Vector embedding + insert step — compensate entity row + FTS doc on failure.
805        // Fan out to ALL registered models (mirrors create_note_inner multi-model path).
806        let embed_model_names = {
807            let names = self.registered_embedding_model_names();
808            if names.is_empty() {
809                vec![]
810            } else {
811                names
812            }
813        };
814
815        let mut embedding_report = crate::retrieval::EmbeddingTruncationReport::default();
816        if embed_model_names.len() == 1 {
817            let model_name = &embed_model_names[0];
818            let vec_result = self
819                .embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
820                .await;
821
822            #[cfg(any(test, feature = "fault-injection"))]
823            let vec_inject = consume_fault(&VECTOR_FAIL_NS, ns);
824            #[cfg(not(any(test, feature = "fault-injection")))]
825            let vec_inject = false;
826            let vec_result: RuntimeResult<crate::retrieval::DocumentEmbeddingOutcome> =
827                if vec_inject {
828                    Err(RuntimeError::Internal(
829                        "injected vector failure".to_string(),
830                    ))
831                } else {
832                    vec_result
833                };
834
835            let single_result: RuntimeResult<()> = match vec_result {
836                Ok(outcome) => {
837                    embedding_report.observe(&outcome);
838                    match self.vectors_for_model(token, model_name) {
839                        Ok(vs) => vs
840                            .insert(
841                                entity.id,
842                                SubstrateKind::Entity,
843                                ns,
844                                "entity.body",
845                                vec![outcome.vector],
846                            )
847                            .await
848                            .map_err(RuntimeError::from),
849                        Err(e) => Err(e),
850                    }
851                }
852                Err(e) => Err(e),
853            };
854            if let Err(e) = single_result {
855                let cleanup_errors = self
856                    .compensate_entity_create(
857                        token,
858                        entity.id,
859                        ns,
860                        std::slice::from_ref(model_name),
861                    )
862                    .await;
863                return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
864            }
865        } else if !embed_model_names.is_empty() {
866            // Multi-model path: embed with each model in parallel, then insert sequentially
867            // with inserted_models tracking for rollback on partial failure.
868            let rt_clone = self.clone();
869            let body_owned = embed_body.clone();
870            let usage_ctx = crate::usage::current();
871            let mut join_set = tokio::task::JoinSet::new();
872            for (idx, model_name) in embed_model_names.iter().enumerate() {
873                let rt = rt_clone.clone();
874                let text = body_owned.clone();
875                let name = model_name.clone();
876                let ctx = usage_ctx.clone();
877                let token = (*token).clone();
878                join_set.spawn(crate::runtime::inherit_request_embedder_scope(async move {
879                    let fut = rt.embed_document_with_model_outcome_for_token(&token, &name, &text);
880                    let result = match ctx {
881                        Some(ctx) => crate::usage::scope(ctx, fut).await,
882                        None => fut.await,
883                    };
884                    (idx, result)
885                }));
886            }
887            // The first failed or panicked handle aborts and detaches its
888            // siblings. Embed usage is counted at dispatch, so a synchronous
889            // provider winding down in the background cannot change it.
890            let outcomes = match drain_embed_join_set(join_set, embed_model_names.len()).await {
891                Ok(outcomes) => outcomes,
892                Err(e) => {
893                    let cleanup_errors = self
894                        .compensate_entity_create(token, entity.id, ns, &[])
895                        .await;
896                    return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
897                }
898            };
899            // TODO(P2): parallelize vector inserts
900            let mut inserted_models: Vec<String> = Vec::with_capacity(embed_model_names.len());
901            for (model_name, outcome) in embed_model_names.iter().zip(outcomes) {
902                embedding_report.observe(&outcome);
903                // Count-targetable fault injection for multi-model insert path.
904                #[cfg(any(test, feature = "fault-injection"))]
905                let count_inject = VECTOR_FAIL_AFTER.with(|cell| match cell.get() {
906                    Some(0) => {
907                        cell.set(None);
908                        true
909                    }
910                    Some(n) => {
911                        cell.set(Some(n - 1));
912                        false
913                    }
914                    None => false,
915                });
916                #[cfg(not(any(test, feature = "fault-injection")))]
917                let count_inject = false;
918
919                let insert_result = if count_inject {
920                    Err(RuntimeError::Internal(
921                        "injected vector insert failure".to_string(),
922                    ))
923                } else {
924                    match self.vectors_for_model(token, model_name) {
925                        Ok(vs) => vs
926                            .insert(
927                                entity.id,
928                                SubstrateKind::Entity,
929                                ns,
930                                "entity.body",
931                                vec![outcome.vector],
932                            )
933                            .await
934                            .map_err(RuntimeError::from),
935                        Err(e) => Err(e),
936                    }
937                };
938                if let Err(e) = insert_result {
939                    // Include the model whose INSERT returned an error: a backend
940                    // error does not prove the write had no side effects.
941                    let mut cleanup_models = inserted_models.clone();
942                    cleanup_models.push(model_name.clone());
943                    let cleanup_errors = self
944                        .compensate_entity_create(token, entity.id, ns, &cleanup_models)
945                        .await;
946                    return Err(Self::entity_create_failure(entity.id, e, cleanup_errors));
947                }
948                inserted_models.push(model_name.clone());
949            }
950        }
951
952        let degradations = self.record_created_entity_event(token, &entity).await;
953        Ok((entity, embedding_report, degradations))
954    }
955
956    async fn record_created_entity_event(
957        &self,
958        token: &NamespaceToken,
959        entity: &Entity,
960    ) -> Vec<PostCommitDegradation> {
961        // The arrival event, appended only after every compensating step has had
962        // its chance to fire: a create that rolled back returns above and never
963        // reaches here, so the event plane cannot name an entity that does not
964        // exist. Deletes and updates already emitted theirs; creates did not,
965        // which left the audit trail able to say what left the graph and not
966        // what entered it.
967        let created_event = khive_storage::event::Event::new(
968            entity.namespace.clone(),
969            "create",
970            EventKind::EntityCreated,
971            SubstrateKind::Entity,
972            "",
973        )
974        .with_target(entity.id)
975        .with_payload(serde_json::json!({
976            "id": entity.id,
977            "namespace": entity.namespace,
978            "kind": entity.kind,
979        }));
980        let event_result = match self.events(token) {
981            Ok(store) => store
982                .append_event(created_event)
983                .await
984                .map_err(RuntimeError::from),
985            Err(error) => Err(error),
986        };
987        let mut degradations = Vec::new();
988        if let Err(error) = event_result {
989            record_post_commit_degradation(
990                &mut degradations,
991                "create_entity",
992                entity.id,
993                "event_append",
994                error,
995            );
996        }
997
998        degradations
999    }
1000}