Skip to main content

khive_runtime/
atomic_prepare.rs

1//! ADR-099: the per-verb async prepare pass for the KG-substrate v1
2//! admissible verbs (`update`, `delete`, `link`, `merge`), plus
3//! [`prepare_add_entity`]/[`prepare_add_note`] for the ADR-046 proposal
4//! changeset `AddEntity`/`AddNote` arms. Each `prepare_*` function reads
5//! current state (async, outside any transaction) and returns a plain-data
6//! [`crate::atomic_runner::AtomicOpPlan`] ([`crate::atomic_plan`]) for the
7//! synchronous commit pass ([`crate::atomic_runner::run_atomic_unit`]) to
8//! apply.
9//!
10//! `gtd.transition`/`gtd.complete` prepare is deliberately not here (lives in
11//! `kkernel` instead), and `propose`/`review`/`withdraw`/`merge` are on the
12//! v1 admissible list but have no working prepare implementation in this
13//! module (`prepare_governance_unimplemented` fails loudly rather than
14//! silently no-opping; `prepare_merge` is unreachable through `--atomic` and
15//! kept only for its own tests and as defense in depth). See
16//! `docs/api/atomic_prepare.md#scope-what-is-excluded-and-why` for why each of these is excluded
17//! and what would be required to admit them.
18
19use serde_json::Value;
20use uuid::Uuid;
21
22mod index_purge;
23
24use index_purge::push_index_purge_statements;
25pub(crate) use index_purge::{
26    event_append_statements, push_index_purge_for_tables, vector_table_names,
27    vector_tables_in_writer,
28};
29
30use khive_storage::types::SqlValue;
31use khive_storage::{AttachmentSubstrate, EdgeRelation, EdgeUpsertDisposition, SqlStatement};
32use khive_types::pack::pack_registry_tag;
33use khive_types::{EventKind, SubstrateKind};
34
35use crate::atomic_plan::{
36    AddEntityPlan, AddNotePlan, AffectedRowGuard, DeletePlan, EdgeNaturalKey, LinkPlan, MergePlan,
37    PlanStatement, PostCommitEffect, UpdatePlan,
38};
39use crate::atomic_runner::AtomicOpPlan;
40use crate::atomic_runner::CommittedPostCommitEffects;
41use crate::curation::{entity_fts_document, note_fts_document};
42use crate::error::{RuntimeError, RuntimeResult};
43use crate::operations::{
44    canonical_edge_endpoint_kinds, canonical_edge_endpoints, merge_dependency_kind,
45    validate_edge_metadata, validate_edge_weight, Resolved,
46};
47use crate::runtime::{KhiveRuntime, NamespaceToken};
48
49use khive_db::stores::attachment::delete_record_attachments_statement;
50use khive_db::stores::entity::{
51    entity_hard_delete_statement, entity_replace_if_unchanged_statement,
52    entity_soft_delete_statement, entity_upsert_statement,
53};
54use khive_db::stores::event::event_insert_statements;
55use khive_db::stores::event::hard_delete_lineage_warning_statements;
56use khive_db::stores::graph::{
57    edge_hard_delete_statement, edge_insert_new_guarded_by_endpoints_statement,
58    edge_link_replace_if_unchanged_and_endpoints_exist_statement,
59    edge_replace_if_unchanged_statement, edge_soft_delete_statement,
60    edge_symmetric_absorb_or_update_inplace_statement, edge_symmetric_delete_if_conflict_statement,
61    purge_incident_edges_statement,
62};
63use khive_db::stores::note::{
64    note_hard_delete_statement, note_soft_delete_statement, note_upsert_statement,
65};
66use khive_db::stores::text::{delete_document_statements, insert_document_statements};
67
68mod add_update;
69pub(crate) use add_update::{
70    attach_note_update_effects, prepare_add_entity_record, prepare_add_note_record,
71    prepare_import_entity_record, prepare_update_entity_record, validate_import_entity_record,
72};
73pub use add_update::{
74    prepare_add_entity, prepare_add_note, prepare_op, prepare_update, prepare_update_entity_plan,
75    prepare_update_from_note_snapshot, validate_note_update_expected_kind, AtomicUpdateKind,
76};
77use add_update::{
78    prepare_update_entity_plan_with_version_and_type, reject_inapplicable_update_fields,
79};
80
81mod note_reindex_effect;
82mod patch_helpers;
83
84use patch_helpers::{
85    entity_name_patch, obj, optional_create_string, optional_entity_type_patch, optional_f64,
86    optional_f64_patch, optional_properties, optional_str, optional_string_patch, optional_tags,
87    refuse_pack_registry_tags, require_str, require_uuid,
88};
89
90pub(crate) fn canonical_refuse_registry_tags(tags: &[String], verb: &str) -> RuntimeResult<()> {
91    refuse_pack_registry_tags(tags, verb)
92}
93
94pub(crate) async fn prepare_update_entity_plan_with_version(
95    runtime: &KhiveRuntime,
96    token: &NamespaceToken,
97    id: Uuid,
98    patch: crate::curation::EntityPatch,
99    expected_version: Option<i64>,
100) -> RuntimeResult<AtomicOpPlan> {
101    prepare_update_entity_plan_with_version_and_type(
102        runtime,
103        token,
104        id,
105        patch,
106        expected_version,
107        None,
108    )
109    .await
110}
111
112// ---------------------------------------------------------------------------
113// post-commit effects
114// ---------------------------------------------------------------------------
115
116mod embedding_outcome;
117pub use embedding_outcome::{
118    apply_post_commit_effects_with_failures, PostCommitEffectsReport, PostCommitEmbeddingOutcome,
119    ReindexModelFailure, ReindexModelStage,
120};
121
122mod link_merge;
123use link_merge::{parse_edge_relation, prepare_link, prepare_merge};
124
125mod post_commit;
126pub(crate) use post_commit::apply_one_post_commit_effect;
127pub use post_commit::{apply_post_commit_effects, apply_post_commit_effects_with_report};
128
129mod edge_delete;
130use edge_delete::prepare_update_edge;
131pub(crate) use edge_delete::{note_delete_plan, prepare_delete_edge};
132pub use edge_delete::{prepare_delete, AtomicDeleteKind};
133pub(crate) use edge_delete::{prepare_delete_from_snapshot, prepare_update_edge_plan};
134
135#[cfg(test)]
136#[path = "atomic_prepare_tests.rs"]
137mod tests;