# Atomic Prepare — DML Plan Builders
`atomic_prepare.rs` turns a subset of verb calls into a static, guarded DML plan
(`crate::atomic_plan::PlanStatement`s) that the `--atomic` execution path can run inside one
transaction without invoking the normal async handler. This document covers which verbs are
in scope, why some are deliberately excluded, and the DML-shape parity guarantees for the
functions that build those plans.
Pack-owned mutation invariants are adapted at the `kkernel` boundary, where both
the `VerbRegistry` and this runtime plan vocabulary are visible. For task note
updates and task dependency links, `kkernel` invokes the same `KindHook` validators
as canonical KG dispatch after building the substrate plan. Core migration V15's
transaction-time triggers remain the final backstop: they see earlier statements
in the same atomic unit and close concurrent check/write races that an async prepare
pass cannot.
## Scope: what is excluded and why
`gtd.transition` / `gtd.complete` prepare is deliberately **not** here: their lifecycle
vocabulary (`is_terminal`, `can_transition`, ...) lives in `khive-pack-gtd`, which depends on
`khive-runtime` — not the other way around. Reproducing that dependency here would invert the
crate graph, so their prepare functions live in `kkernel` (which already depends on both crates),
calling back into the plain `PlanStatement`/`AffectedRowGuard` shapes exported from this module's
sibling, `crate::atomic_plan`.
`propose` / `review` / `withdraw` (the event-sourced governance lifecycle) are on the v1
admissible list (`khive_types::pack::ATOMIC_ADMISSIBLE_VERBS`) but have no prepare implementation
here: their apply path is a changeset-interpreter (`apply_worker`) over a dedicated
`proposals_open` table, not a small number of guarded DML statements — a faithful, non-stub
atomic prepare for them is separate follow-on work. `prepare_governance_unimplemented` fails
loudly, before any write, naming this as a known scope gap rather than silently no-opping.
`merge` is likewise on the v1 admissible list but is deferred: full-parity field folding,
survivor index reindex, loser index purge, provenance, and same-kind rejection are achievable as
static DML, but `curation::merge_entity_sql`'s graceful edge-conflict resolution is not (it is
per-row procedural, incompatible with the static predicate/guard plan shape): rather than ship a
partially-scoped atomic merge, it is rejected at the same pre-runtime static guard as governance
(`khive_types::pack::ATOMIC_KNOWN_UNIMPLEMENTED_VERBS`). `prepare_merge` is therefore unreachable
through `--atomic`; it remains only as the earlier direct-prepare implementation, exercised by
this module's own tests, and as defense in depth.
## prepare_update_edge
Mirrors `khive-runtime::operations::KhiveRuntime::update_edge`'s patch semantics exactly:
`relation`/`weight`/`properties` are the only applicable fields
(`reject_inapplicable_update_fields`'s `"edge"` arm enforces this before any mutation), a changed
`relation` is endpoint-validated first, `weight` is range-checked, and `properties` REPLACES
`metadata` wholesale (no merge — `update_edge` does `edge.metadata = Some(props)`, unlike the
entity/note branches' `merge_properties`).
DML shape:
- non-symmetric relation: a single `edge_upsert_statement` call on the patched `Edge` — the same
builder `update_edge`'s own non-symmetric branch calls via `graph.upsert_edge(edge.clone())`
(`khive-db::stores::graph::SqlGraphStore::upsert_edge`), so parity is exact by construction.
- symmetric relation (`competes_with`, `composed_with`): `update_edge` does NOT use the upsert
builder here, because `upsert_edge` resolves `ON CONFLICT(namespace, id)` first and cannot
detect a natural-key collision with a _different_ id. Canonical (`update_edge_symmetric_dml`)
runs a conflict probe and branches in Rust inside a single uninterrupted transaction, which is
safe there. This atomic path cannot do that (see the in-source invariant note on
`prepare_update_edge`).
## event_append_statements
Builds the `Event` exactly as each canonical site does and turns it into plain-data
`SqlStatement`s via `khive_db::stores::event::event_insert_statements`: the same builder the async
execution path every canonical `event_store.append_event(...)` call reaches uses. There is exactly
one place that knows the `events`/`event_observations` insert shape; this function only adapts its
output into unguarded `PlanStatement`s for the atomic-unit plan.
This is a `PlanStatement` inside the atomic unit, not a `PostCommitEffect` (reserved for
best-effort or non-SQL work): the insert is a small number of plain, deterministic `INSERT`s
computed entirely from data already on hand at prepare time, unlike the
`ReindexEntity`/`ReindexNote` post-commit effects this module defers because those need an
embedding call.
`apply_post_commit_effects_with_report` returns one `PostCommitEmbeddingOutcome` for every reindex
effect it successfully executes. Each outcome retains the originating effect identity plus its
typed truncation report, allowing CLI or pack response builders to attach warnings to the exact
write without rerunning registry prediction. The original `apply_post_commit_effects` remains the
unit-returning compatibility wrapper.