khive-runtime 0.12.0

Composable Service API: entity/note CRUD, graph traversal, hybrid search, curation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

//! Direct-ingest facade retaining preflight snapshot and conditional writes.

use khive_storage::Entity;

use super::entity_admission::{EntityAdmission, EntityCandidatePrepared};
use super::entity_transaction::EntityCandidateMutation;
use crate::{
    AtomicOpFailure, AtomicOpPlan, AtomicRunOutcome, KhiveRuntime, NamespaceToken,
    PostCommitEffect, RuntimeError, RuntimeResult,
};

#[derive(Debug)]
pub enum EntityCandidateAdmission {
    /// No write occurred. Continue the existing clean-candidate storage route.
    Legacy(Entity),
    /// Record, runtime stamp, required FTS/map, and audit committed together.
    Committed(Entity),
    /// Conditional insert/CAS lost; the ingest owner may reread and rebase.
    Conflict,
}

impl KhiveRuntime {
    /// Admit a structural direct-ingest candidate. Matched candidates cannot
    /// carry content_ref, because this facade does not own attachment writes.
    /// The ordinary attachment-aware constructor remains the supported path
    /// for those records; clean Legacy candidates keep their original shape.
    pub async fn try_commit_manifest_entity_candidate(
        &self,
        token: &NamespaceToken,
        prepared: EntityCandidatePrepared,
        mutation: EntityCandidateMutation,
    ) -> RuntimeResult<EntityCandidateAdmission> {
        let admitted = match prepared.admit(token)? {
            EntityAdmission::Legacy(entity) => return Ok(EntityCandidateAdmission::Legacy(entity)),
            EntityAdmission::Exempt(admitted) => admitted,
        };
        self.validate_entity_kind(&admitted.entity().kind)?;
        self.validate_entity_type_for_kind(
            &admitted.entity().kind,
            admitted.entity().entity_type.as_deref(),
        )?;
        let (required, _) = self
            .prepare_admitted_entity_indexes(token, admitted.entity(), &[], false)
            .await?;
        let plan = admitted.into_plan(mutation, required, PostCommitEffect::None)?;
        let committed = plan.committed_entity();
        match crate::run_atomic_unit(
            self.sql().as_ref(),
            vec![AtomicOpPlan::FinalizeEntity(Box::new(plan))],
        )
        .await
        {
            Ok(AtomicRunOutcome::Committed { .. }) => {
                Ok(EntityCandidateAdmission::Committed(committed))
            }
            Ok(AtomicRunOutcome::RolledBack {
                failure: AtomicOpFailure::EntityConflict(conflict),
                ..
            }) => Err(conflict.into_error().into()),
            Ok(AtomicRunOutcome::RolledBack {
                failure: AtomicOpFailure::GuardFailed { .. },
                ..
            }) => Ok(EntityCandidateAdmission::Conflict),
            Ok(AtomicRunOutcome::RolledBack { failure, .. }) => Err(RuntimeError::Internal(
                format!("entity manifest finalization rolled back: {failure:?}"),
            )),
            Err(error) => Err(RuntimeError::Storage(error.0)),
        }
    }
}