Skip to main content

khive_runtime/
atomic_runner.rs

1//! ADR-099 migration step 3 (sub-slice B2) — the atomic runner: the
2//! synchronous commit-pass mechanism that applies a caller-supplied sequence
3//! of prepared write plans ([`crate::atomic_plan`]) as **ONE**
4//! [`SqlAccess::atomic_unit`], under a per-op `SAVEPOINT`, committing every
5//! plan or rolling back the whole unit.
6//!
7//! ADR-099 B3 caller: `kkernel exec --ops-file --atomic` — async prepare,
8//! then this runner's one synchronous commit pass, then async post-commit
9//! effects. Runtime callers also supply prepared plans directly (hard-delete
10//! in `operations.rs`). See `docs/api/atomic_runner.md` for the full
11//! three-phase shape (ADR-099 D1).
12//!
13//! # Safety: suspend-free invariant
14//!
15//! [`run_atomic_unit`] is the one place in this crate that builds an
16//! [`AtomicUnitOp`] closure for [`SqlAccess::atomic_unit`], whose contract
17//! requires the closure's future to resolve on its first poll — synchronous
18//! DML against the provided `&mut dyn SqlWriter` only, never a suspending
19//! `.await`. Every statement driven here comes from
20//! `AtomicOpPlan::plan_statements`, which can only ever produce
21//! [`PlanStatement`]s (plain parameterized SQL), so no code path in this
22//! module can hand `atomic_unit` a suspending future. The paired
23//! suspend-trap tests at the bottom of this file check both the happy-path
24//! (real commit pass resolves on first poll) and the misuse-is-caught case
25//! (a hand-built suspending closure fails loudly through the same seam). See
26//! `docs/api/atomic_runner.md#suspend-free-invariant` for the full argument.
27
28use std::any::Any;
29use std::sync::{Arc, Mutex};
30
31use khive_storage::{AtomicUnitOp, SqlAccess, SqlStatement, SqlWriter, StorageError};
32
33use crate::atomic_plan::{
34    AddEntityPlan, AddNotePlan, AffectedRowGuard, DeletePlan, GovernancePlan, GtdCompletePlan,
35    GtdTransitionPlan, LinkPlan, MergePlan, PlanStatement, PostCommitEffect, UpdatePlan,
36};
37
38/// One admissible op's prepared write plan (ADR-099 D3's v1 admissible verb
39/// groups), ready for the commit pass. This is the `Vec<AtomicOpPlan>` shape
40/// [`run_atomic_unit`] consumes — the runner is agnostic to which verb
41/// produced a given plan; it only needs each plan's ordered statements
42/// (`plan_statements`) and any deferred post-commit effect
43/// (`post_commit_effect`).
44#[derive(Debug, Clone)]
45pub enum AtomicOpPlan {
46    AddEntity(AddEntityPlan),
47    AddNote(AddNotePlan),
48    Update(UpdatePlan),
49    Delete(DeletePlan),
50    Link(LinkPlan),
51    Merge(MergePlan),
52    GtdTransition(GtdTransitionPlan),
53    GtdComplete(GtdCompletePlan),
54    Governance(GovernancePlan),
55}
56
57impl AtomicOpPlan {
58    /// This op's statements, in the order the commit pass must apply them.
59    ///
60    /// For [`AtomicOpPlan::Merge`], the predicate-based rewires
61    /// (`MergePlan::rewires`) come first, converted to unguarded
62    /// [`PlanStatement`]s (ADR-099 D1 rule 1 — a rewire may legitimately
63    /// touch zero or many rows and is never guarded), followed by the
64    /// always-guarded lifecycle writes (`MergePlan::lifecycle`). Every other
65    /// variant already carries a flat `Vec<PlanStatement>` in apply order.
66    fn plan_statements(&self) -> Vec<PlanStatement> {
67        match self {
68            AtomicOpPlan::AddEntity(p) => p.statements.clone(),
69            AtomicOpPlan::AddNote(p) => p.statements.clone(),
70            AtomicOpPlan::Update(p) => p.statements.clone(),
71            AtomicOpPlan::Delete(p) => p.statements.clone(),
72            AtomicOpPlan::Link(p) => vec![p.statement.clone()],
73            AtomicOpPlan::Merge(p) => {
74                let mut statements: Vec<PlanStatement> = p
75                    .rewires
76                    .iter()
77                    .map(|rewire| PlanStatement {
78                        statement: rewire.statement.clone(),
79                        guard: None,
80                    })
81                    .collect();
82                statements.extend(p.lifecycle.clone());
83                statements
84            }
85            AtomicOpPlan::GtdTransition(p) => p.statements.clone(),
86            AtomicOpPlan::GtdComplete(p) => p.statements.clone(),
87            AtomicOpPlan::Governance(p) => p.statements.clone(),
88        }
89    }
90
91    /// The deferred post-commit effect this op's plan recorded, if any.
92    ///
93    /// [`UpdatePlan`] carries a [`PostCommitEffect`] field for the `update`
94    /// reindex caveat (ADR-099 D3). Under B3 (GAP-5),
95    /// [`GtdTransitionPlan`]/[`GtdCompletePlan`] also carry one, for the
96    /// best-effort lifecycle audit row. Since #750, [`DeletePlan`] also
97    /// carries one, for the note-mutation
98    /// hook fire on a committed note delete. Every other admissible verb's
99    /// apply is pure DML with no deferred side effect. `merge`'s existing
100    /// post-transaction vector re-insert (D3: "merge already performs its
101    /// vector re-insert after its transaction") is the handler's own
102    /// pre-existing behavior outside this plan shape — [`MergePlan`] itself
103    /// carries no `post_commit` field, so this runner records none for it.
104    fn post_commit_effect(&self) -> Option<PostCommitEffect> {
105        match self {
106            AtomicOpPlan::AddEntity(p) if p.post_commit != PostCommitEffect::None => {
107                Some(p.post_commit.clone())
108            }
109            AtomicOpPlan::AddNote(p) if p.post_commit != PostCommitEffect::None => {
110                Some(p.post_commit.clone())
111            }
112            AtomicOpPlan::Update(p) if p.post_commit != PostCommitEffect::None => {
113                Some(p.post_commit.clone())
114            }
115            AtomicOpPlan::Delete(p) if p.post_commit != PostCommitEffect::None => {
116                Some(p.post_commit.clone())
117            }
118            AtomicOpPlan::GtdTransition(p) if p.post_commit != PostCommitEffect::None => {
119                Some(p.post_commit.clone())
120            }
121            AtomicOpPlan::GtdComplete(p) if p.post_commit != PostCommitEffect::None => {
122                Some(p.post_commit.clone())
123            }
124            _ => None,
125        }
126    }
127}
128
129/// Why a single op's plan failed inside the commit pass (ADR-099 acceptance
130/// criteria: "the failing op index is recorded").
131#[derive(Debug, Clone, PartialEq, Eq)]
132pub enum AtomicOpFailure {
133    /// The statement executed without a SQL error, but its affected-row
134    /// count did not satisfy the guard prepare attached to it (ADR-099 D1
135    /// rule 2 — "a prepare-time validation is a plan hypothesis, re-verified
136    /// under the transaction, never a commitment"). This is the shape both
137    /// the dangling-edge and zero-row acceptance criteria trip.
138    GuardFailed {
139        statement_label: Option<String>,
140        expected: AffectedRowGuard,
141        observed: u64,
142    },
143    /// The statement itself returned a storage error (a genuine SQL
144    /// failure — malformed SQL, a constraint violation not modeled as a
145    /// guard, etc.), not a guard mismatch.
146    SqlError {
147        statement_label: Option<String>,
148        message: String,
149    },
150}
151
152/// Deferred effects whose owning atomic unit has committed successfully.
153///
154/// Only [`run_atomic_unit`] can construct this token. Consumers may inspect
155/// its effects through [`CommittedPostCommitEffects::as_slice`], while the
156/// phase-3 executor takes the token by value; no public API exposes the owned
157/// effect collection or accepts a prepare-time [`PostCommitEffect`] in its
158/// place.
159///
160/// A committed token is a one-shot capability and cannot be cloned for
161/// replay:
162///
163/// ```compile_fail
164/// use khive_runtime::CommittedPostCommitEffects;
165///
166/// fn duplicate(
167///     committed: &CommittedPostCommitEffects,
168/// ) -> CommittedPostCommitEffects {
169///     committed.clone()
170/// }
171/// ```
172#[derive(Debug, PartialEq, Eq)]
173pub struct CommittedPostCommitEffects {
174    effects: Vec<PostCommitEffect>,
175}
176
177impl CommittedPostCommitEffects {
178    fn new(effects: Vec<PostCommitEffect>) -> Self {
179        Self { effects }
180    }
181
182    /// Inspect the committed effects without discarding their commit
183    /// provenance.
184    pub fn as_slice(&self) -> &[PostCommitEffect] {
185        &self.effects
186    }
187
188    pub(crate) fn into_effects(self) -> Vec<PostCommitEffect> {
189        self.effects
190    }
191}
192
193/// The whole-unit outcome of a completed [`run_atomic_unit`] call — the
194/// commit pass ran to a clean, distinguishable verdict (never returned for
195/// a seam-level failure; see [`AtomicRunnerError`] for that case).
196#[derive(Debug, PartialEq, Eq)]
197pub enum AtomicRunOutcome {
198    /// Every op's plan applied and the unit committed. Carries an opaque
199    /// [`CommittedPostCommitEffects`] token containing the deferred effects
200    /// in op order. Phase 3 consumes that token through
201    /// [`crate::atomic_prepare::apply_post_commit_effects`] after
202    /// `run_atomic_unit` returns and outside any transaction; callers can
203    /// inspect the effects without converting them back into an executable
204    /// raw collection.
205    Committed {
206        post_commit: CommittedPostCommitEffects,
207    },
208    /// The op at `failed_op_index` failed; the whole unit rolled back
209    /// (ADR-099 D1: "the whole unit rolls back and the failing op index is
210    /// recorded"). No op's writes are present in the database after this
211    /// outcome — including any earlier op whose own `SAVEPOINT` had already
212    /// been `RELEASE`d, because `RELEASE` only merges a savepoint's changes
213    /// into its parent transaction; it does not commit them independently
214    /// of the outer `atomic_unit` transaction's own COMMIT/ROLLBACK.
215    RolledBack {
216        failed_op_index: usize,
217        failure: AtomicOpFailure,
218    },
219}
220
221/// A failure of the `atomic_unit` seam itself — the storage layer refused
222/// or could not complete the call at all (read-only backend, no async
223/// runtime for the writer-task lookup, or an [`AtomicUnitOp`] that violated
224/// the suspend-free invariant and got caught by `block_on_sync`). Never
225/// returned for an ordinary op-level guard or SQL failure inside the unit —
226/// those surface as `AtomicRunOutcome::RolledBack`, not this error.
227#[derive(Debug)]
228pub struct AtomicRunnerError(pub StorageError);
229
230impl std::fmt::Display for AtomicRunnerError {
231    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
232        write!(f, "atomic_unit seam failure: {}", self.0)
233    }
234}
235
236impl std::error::Error for AtomicRunnerError {
237    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
238        Some(&self.0)
239    }
240}
241
242fn raw_stmt(sql: String) -> SqlStatement {
243    SqlStatement {
244        sql,
245        params: vec![],
246        label: None,
247    }
248}
249
250async fn begin_savepoint(writer: &mut dyn SqlWriter, name: &str) -> Result<(), StorageError> {
251    writer
252        .execute(raw_stmt(format!("SAVEPOINT {name}")))
253        .await
254        .map(|_| ())
255}
256
257async fn release_savepoint(writer: &mut dyn SqlWriter, name: &str) -> Result<(), StorageError> {
258    writer
259        .execute(raw_stmt(format!("RELEASE {name}")))
260        .await
261        .map(|_| ())
262}
263
264async fn rollback_to_savepoint(writer: &mut dyn SqlWriter, name: &str) -> Result<(), StorageError> {
265    writer
266        .execute(raw_stmt(format!("ROLLBACK TO {name}")))
267        .await
268        .map(|_| ())
269}
270
271/// Apply one op's plan statements in order, checking each guarded
272/// statement's affected-row count before moving to the next (ADR-099 D1
273/// rule 2). Returns on the first statement that either errors or fails its
274/// guard — never applies a later statement once an earlier one in the same
275/// plan has failed.
276async fn apply_plan(
277    writer: &mut dyn SqlWriter,
278    plan: &AtomicOpPlan,
279) -> Result<(), AtomicOpFailure> {
280    for stmt in plan.plan_statements() {
281        let label = stmt.statement.label.clone();
282        let affected =
283            writer
284                .execute(stmt.statement)
285                .await
286                .map_err(|e| AtomicOpFailure::SqlError {
287                    statement_label: label.clone(),
288                    message: e.to_string(),
289                })?;
290        if let Some(guard) = stmt.guard {
291            if !guard.holds_for(affected) {
292                return Err(AtomicOpFailure::GuardFailed {
293                    statement_label: label,
294                    expected: guard,
295                    observed: affected,
296                });
297            }
298        }
299    }
300    Ok(())
301}
302
303/// Run `plans` as ONE atomic unit (ADR-099 D1 commit pass): open a single
304/// [`SqlAccess::atomic_unit`], apply every plan's statements under a named
305/// `SAVEPOINT` (`adr099_atomic_op_<n>`), and commit all or roll back all.
306///
307/// **This is the seam the atomic-unit suspend-free invariant governs (see
308/// the module doc comment above).** The closure built here drives only
309/// `AtomicOpPlan::plan_statements` — plain DML — against the writer
310/// `atomic_unit` hands it; it issues no transaction control of its own
311/// (`BEGIN`/`COMMIT`/`ROLLBACK` are owned entirely by `atomic_unit`, exactly
312/// like the existing `execute_batch` contract) beyond the per-op
313/// `SAVEPOINT`/`RELEASE`/`ROLLBACK TO` statements, which are themselves
314/// synchronous DML from SQLite's perspective, not transaction boundaries the
315/// storage layer needs to track.
316///
317/// On the first op whose plan fails (a guard mismatch or a genuine SQL
318/// error), this function does **not** propagate a generic storage error for
319/// that case: it unwinds just that op's own `SAVEPOINT` (best-effort — the
320/// outer `atomic_unit` transaction is rolled back in full regardless, per
321/// ADR-099 D1) and returns `Ok(AtomicRunOutcome::RolledBack { .. })` naming
322/// the failing op and why. [`AtomicRunnerError`] is reserved for a failure
323/// of the `atomic_unit` seam itself — the storage layer refusing or being
324/// unable to run the call at all.
325pub async fn run_atomic_unit(
326    access: &dyn SqlAccess,
327    plans: Vec<AtomicOpPlan>,
328) -> Result<AtomicRunOutcome, AtomicRunnerError> {
329    let failure_slot: Arc<Mutex<Option<(usize, AtomicOpFailure)>>> = Arc::new(Mutex::new(None));
330    let failure_slot_for_closure = Arc::clone(&failure_slot);
331
332    let op: AtomicUnitOp = Box::new(move |writer| {
333        Box::pin(async move {
334            let mut post_commit = Vec::new();
335            for (op_index, plan) in plans.iter().enumerate() {
336                let savepoint = format!("adr099_atomic_op_{op_index}");
337                begin_savepoint(writer, &savepoint).await?;
338                match apply_plan(writer, plan).await {
339                    Ok(()) => {
340                        release_savepoint(writer, &savepoint).await?;
341                        if let Some(effect) = plan.post_commit_effect() {
342                            post_commit.push(effect);
343                        }
344                    }
345                    Err(failure) => {
346                        // Best-effort unwind of just this op's own partial
347                        // DML. The outer `atomic_unit` transaction is rolled
348                        // back in full once this closure returns `Err`
349                        // regardless (ADR-099 D1: "the whole unit rolls
350                        // back") — a failure in this cleanup step is not
351                        // itself a correctness gap in the no-partial-state
352                        // guarantee, only a diagnostic nicety.
353                        let _ = rollback_to_savepoint(writer, &savepoint).await;
354                        let _ = release_savepoint(writer, &savepoint).await;
355                        *failure_slot_for_closure
356                            .lock()
357                            .expect("atomic runner failure slot poisoned") =
358                            Some((op_index, failure));
359                        return Err(StorageError::Internal(format!(
360                            "ADR-099 atomic unit aborted at op {op_index}"
361                        )));
362                    }
363                }
364            }
365            Ok(Box::new(post_commit) as Box<dyn Any + Send>)
366        })
367    });
368
369    match access.atomic_unit(op).await {
370        Ok(boxed) => {
371            let post_commit = *boxed.downcast::<Vec<PostCommitEffect>>().expect(
372                "run_atomic_unit's own closure always returns Box<Vec<PostCommitEffect>> on Ok",
373            );
374            Ok(AtomicRunOutcome::Committed {
375                post_commit: CommittedPostCommitEffects::new(post_commit),
376            })
377        }
378        Err(storage_err) => {
379            let recorded = failure_slot
380                .lock()
381                .expect("atomic runner failure slot poisoned")
382                .take();
383            match recorded {
384                Some((failed_op_index, failure)) => Ok(AtomicRunOutcome::RolledBack {
385                    failed_op_index,
386                    failure,
387                }),
388                None => Err(AtomicRunnerError(storage_err)),
389            }
390        }
391    }
392}
393
394#[cfg(test)]
395mod tests {
396    use super::*;
397
398    use std::sync::Arc as StdArc;
399
400    use khive_db::{ConnectionPool, PoolConfig, SqlBridge};
401    use khive_storage::types::{SqlValue, StorageResult as StorageResultAlias};
402    use uuid::Uuid;
403
404    /// A scratch pool wired exactly like the daemon.rs / sql_bridge.rs
405    /// tests above it: file-backed (atomic_unit's single-writer path is
406    /// only reachable file-backed), `write_queue_enabled: true` so
407    /// `atomic_unit` routes through the real `WriterTask` + `block_on_sync`
408    /// seam rather than the flag-off manual-transaction fallback — the
409    /// suspend-trap contract only fires on this path.
410    fn scratch_pool(name: &str) -> StdArc<ConnectionPool> {
411        let dir = tempfile::tempdir().expect("tempdir");
412        let path = dir.path().join(format!("{name}.db"));
413        let pool = StdArc::new(
414            ConnectionPool::new(PoolConfig {
415                path: Some(path),
416                write_queue_enabled: true,
417                ..PoolConfig::default()
418            })
419            .expect("pool open"),
420        );
421        // Leak the tempdir so the file lives for the pool's lifetime within
422        // one test function — every test here is single-scoped and short.
423        std::mem::forget(dir);
424        pool
425    }
426
427    /// Minimal real schema slice (`entities`, `graph_edges`) — copied from
428    /// `crates/khive-db/sql/entities-ddl.sql` / `graph-ddl.sql` rather than
429    /// invented ad hoc, since the dangling-edge and merge-rewire tests below
430    /// depend on `graph_edges` having no foreign-key enforcement (ADR-099
431    /// D1: "`graph_edges` has no foreign-key enforcement ... SQLite will
432    /// happily commit the inconsistency" absent the guard/predicate rules
433    /// this runner implements).
434    fn seed_schema(pool: &ConnectionPool) {
435        let writer = pool.try_writer().expect("writer");
436        writer
437            .conn()
438            .execute_batch(
439                "CREATE TABLE entities (
440                    id             TEXT PRIMARY KEY,
441                    namespace      TEXT NOT NULL,
442                    kind           TEXT NOT NULL,
443                    entity_type    TEXT,
444                    name           TEXT NOT NULL,
445                    description    TEXT,
446                    properties     TEXT,
447                    tags           TEXT NOT NULL DEFAULT '[]',
448                    created_at     INTEGER NOT NULL,
449                    updated_at     INTEGER NOT NULL,
450                    deleted_at     INTEGER,
451                    merged_into    TEXT,
452                    merge_event_id TEXT
453                );
454                CREATE TABLE graph_edges (
455                    namespace      TEXT NOT NULL,
456                    id             TEXT NOT NULL,
457                    source_id      TEXT NOT NULL,
458                    target_id      TEXT NOT NULL,
459                    relation       TEXT NOT NULL,
460                    weight         REAL NOT NULL DEFAULT 1.0,
461                    created_at     INTEGER NOT NULL,
462                    updated_at     INTEGER NOT NULL,
463                    deleted_at     INTEGER,
464                    metadata       TEXT,
465                    target_backend TEXT,
466                    PRIMARY KEY (namespace, id)
467                );",
468            )
469            .expect("seed schema");
470    }
471
472    fn insert_entity(pool: &ConnectionPool, id: Uuid, name: &str) {
473        let writer = pool.try_writer().expect("writer");
474        writer
475            .conn()
476            .execute(
477                "INSERT INTO entities \
478                 (id, namespace, kind, name, created_at, updated_at) \
479                 VALUES (?1, 'local', 'concept', ?2, 0, 0)",
480                rusqlite::params![id.to_string(), name],
481            )
482            .expect("insert entity");
483    }
484
485    fn entity_exists(pool: &ConnectionPool, id: Uuid) -> bool {
486        let writer = pool.try_writer().expect("writer");
487        let count: i64 = writer
488            .conn()
489            .query_row(
490                "SELECT COUNT(*) FROM entities WHERE id = ?1 AND deleted_at IS NULL",
491                rusqlite::params![id.to_string()],
492                |row| row.get(0),
493            )
494            .expect("query entity");
495        count > 0
496    }
497
498    fn edge_count(pool: &ConnectionPool, source: Uuid, target: Uuid) -> i64 {
499        let writer = pool.try_writer().expect("writer");
500        writer
501            .conn()
502            .query_row(
503                "SELECT COUNT(*) FROM graph_edges \
504                 WHERE source_id = ?1 AND target_id = ?2 AND deleted_at IS NULL",
505                rusqlite::params![source.to_string(), target.to_string()],
506                |row| row.get(0),
507            )
508            .expect("query edge")
509    }
510
511    fn entities_snapshot(pool: &ConnectionPool) -> Vec<String> {
512        let writer = pool.try_writer().expect("writer");
513        let mut stmt = writer
514            .conn()
515            .prepare("SELECT id, name, deleted_at FROM entities ORDER BY id")
516            .expect("prepare snapshot");
517        let rows = stmt
518            .query_map([], |row| {
519                let id: String = row.get(0)?;
520                let name: String = row.get(1)?;
521                let deleted_at: Option<i64> = row.get(2)?;
522                Ok(format!("{id}:{name}:{deleted_at:?}"))
523            })
524            .expect("query snapshot");
525        rows.collect::<Result<Vec<_>, _>>()
526            .expect("collect snapshot")
527    }
528
529    fn delete_plan(id: Uuid, label: &str) -> AtomicOpPlan {
530        AtomicOpPlan::Delete(DeletePlan {
531            target_id: id,
532            statements: vec![PlanStatement {
533                statement: SqlStatement {
534                    sql: "DELETE FROM entities WHERE id = ?1 AND deleted_at IS NULL".to_string(),
535                    params: vec![SqlValue::Text(id.to_string())],
536                    label: Some(label.to_string()),
537                },
538                guard: Some(AffectedRowGuard::exactly(1)),
539            }],
540            post_commit: PostCommitEffect::None,
541        })
542    }
543
544    fn rename_plan(id: Uuid, new_name: &str, label: &str) -> AtomicOpPlan {
545        AtomicOpPlan::Update(UpdatePlan {
546            target_id: id,
547            statements: vec![PlanStatement {
548                statement: SqlStatement {
549                    sql: "UPDATE entities SET name = ?1, updated_at = 1 \
550                          WHERE id = ?2 AND deleted_at IS NULL"
551                        .to_string(),
552                    params: vec![
553                        SqlValue::Text(new_name.to_string()),
554                        SqlValue::Text(id.to_string()),
555                    ],
556                    label: Some(label.to_string()),
557                },
558                guard: Some(AffectedRowGuard::exactly(1)),
559            }],
560            post_commit: PostCommitEffect::None,
561            edge_natural_key: None,
562        })
563    }
564
565    /// The guarded `INSERT ... SELECT ... WHERE EXISTS` shape `LinkPlan`
566    /// documents: the affected-row count of this ONE statement doubles as
567    /// the in-transaction endpoint-existence probe (ADR-099 acceptance
568    /// criteria: dangling-edge).
569    fn link_plan(edge_id: Uuid, source: Uuid, target: Uuid) -> AtomicOpPlan {
570        AtomicOpPlan::Link(LinkPlan {
571            source_id: source,
572            target_id: target,
573            statement: PlanStatement {
574                statement: SqlStatement {
575                    sql: "INSERT INTO graph_edges \
576                          (namespace, id, source_id, target_id, relation, created_at, updated_at) \
577                          SELECT 'local', ?1, ?2, ?3, 'annotates', 0, 0 \
578                          WHERE EXISTS (SELECT 1 FROM entities WHERE id = ?2 AND deleted_at IS NULL) \
579                            AND EXISTS (SELECT 1 FROM entities WHERE id = ?3 AND deleted_at IS NULL)"
580                        .to_string(),
581                    params: vec![
582                        SqlValue::Text(edge_id.to_string()),
583                        SqlValue::Text(source.to_string()),
584                        SqlValue::Text(target.to_string()),
585                    ],
586                    label: Some("insert-edge-where-exists".to_string()),
587                },
588                guard: Some(AffectedRowGuard::exactly(1)),
589            },
590        })
591    }
592
593    fn merge_plan(into_id: Uuid, from_id: Uuid) -> AtomicOpPlan {
594        AtomicOpPlan::Merge(MergePlan {
595            into_id,
596            from_id,
597            rewires: vec![crate::atomic_plan::PlanPredicate {
598                description: "source_id = :from".to_string(),
599                statement: SqlStatement {
600                    sql: "UPDATE graph_edges SET source_id = ?1, updated_at = 1 \
601                          WHERE source_id = ?2"
602                        .to_string(),
603                    params: vec![
604                        SqlValue::Text(into_id.to_string()),
605                        SqlValue::Text(from_id.to_string()),
606                    ],
607                    label: Some("merge-rewire".to_string()),
608                },
609            }],
610            lifecycle: vec![PlanStatement {
611                statement: SqlStatement {
612                    sql: "UPDATE entities SET deleted_at = 1, merged_into = ?1 \
613                          WHERE id = ?2 AND deleted_at IS NULL"
614                        .to_string(),
615                    params: vec![
616                        SqlValue::Text(into_id.to_string()),
617                        SqlValue::Text(from_id.to_string()),
618                    ],
619                    label: Some("tombstone-from-entity".to_string()),
620                },
621                guard: Some(AffectedRowGuard::exactly(1)),
622            }],
623        })
624    }
625
626    // ------------------------------------------------------------------
627    // 1. Rollback end-to-end
628    // ------------------------------------------------------------------
629
630    #[tokio::test]
631    async fn rollback_end_to_end_leaves_zero_partial_state() {
632        let pool = scratch_pool("rollback_end_to_end");
633        seed_schema(&pool);
634        let a = Uuid::new_v4();
635        let b = Uuid::new_v4();
636        insert_entity(&pool, a, "alpha");
637        insert_entity(&pool, b, "bravo");
638        let before = entities_snapshot(&pool);
639
640        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
641        let plans = vec![
642            rename_plan(a, "alpha-renamed", "rename-a"),
643            // Induced failure: b does not exist under this id, so the
644            // guard (expects exactly 1 affected row) fails.
645            delete_plan(Uuid::new_v4(), "delete-nonexistent"),
646            rename_plan(b, "bravo-renamed", "rename-b"),
647        ];
648
649        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
650        match outcome {
651            AtomicRunOutcome::RolledBack {
652                failed_op_index,
653                failure,
654            } => {
655                assert_eq!(failed_op_index, 1);
656                assert!(matches!(failure, AtomicOpFailure::GuardFailed { .. }));
657            }
658            other => panic!("expected RolledBack, got {other:?}"),
659        }
660
661        let after = entities_snapshot(&pool);
662        assert_eq!(
663            before, after,
664            "a mid-unit failure must leave the database byte-for-byte unchanged"
665        );
666    }
667
668    // ------------------------------------------------------------------
669    // 2. Suspend-trap paired: the runner's happy path resolves on first
670    //    poll (commits); a hand-built suspending closure through the SAME
671    //    `atomic_unit` seam fails loudly instead of silently succeeding.
672    // ------------------------------------------------------------------
673
674    #[tokio::test]
675    async fn commit_pass_resolves_on_first_poll_and_commits() {
676        let pool = scratch_pool("suspend_trap_happy_path");
677        seed_schema(&pool);
678        let a = Uuid::new_v4();
679        insert_entity(&pool, a, "alpha");
680
681        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
682        let plans = vec![rename_plan(a, "alpha-v2", "rename-a")];
683
684        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
685        assert!(
686            matches!(outcome, AtomicRunOutcome::Committed { .. }),
687            "the real commit-pass closure (SAVEPOINT + guarded DML only) must \
688             resolve on block_on_sync's first poll and commit: {outcome:?}"
689        );
690
691        let writer = pool.try_writer().expect("writer");
692        let name: String = writer
693            .conn()
694            .query_row(
695                "SELECT name FROM entities WHERE id = ?1",
696                rusqlite::params![a.to_string()],
697                |row| row.get(0),
698            )
699            .expect("query renamed entity");
700        assert_eq!(name, "alpha-v2");
701    }
702
703    #[tokio::test]
704    async fn hand_built_suspending_closure_fails_loudly_through_the_same_seam() {
705        // The exact misuse the module-doc "suspend-trap" promise guards
706        // against: a closure sent through this crate's OWN integration of
707        // `SqlAccess::atomic_unit` (the same `bridge` type `run_atomic_unit`
708        // uses) that reaches a real suspension point instead of staying
709        // synchronous DML — a stand-in for "a future edit admits a verb
710        // whose apply forgot to hoist its embedding out of the transaction"
711        // (ADR-099 acceptance criteria). `tokio::task::yield_now` returns
712        // `Poll::Pending` on its first poll by construction, so this is a
713        // real suspension, not `std::future::pending`'s permanent one.
714        let pool = scratch_pool("suspend_trap_misuse");
715        seed_schema(&pool);
716
717        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
718        let suspending_op: AtomicUnitOp = Box::new(|_writer| {
719            Box::pin(async move {
720                tokio::task::yield_now().await;
721                Ok(Box::new(()) as Box<dyn Any + Send>)
722            })
723        });
724
725        let result: StorageResultAlias<Box<dyn Any + Send>> =
726            khive_storage::SqlAccess::atomic_unit(&bridge, suspending_op).await;
727        assert!(
728            result.is_err(),
729            "a closure that suspends on first poll must fail loudly through \
730             `atomic_unit`, never silently succeed or wedge; got {result:?}"
731        );
732    }
733
734    // ------------------------------------------------------------------
735    // 3. Staleness both directions
736    // ------------------------------------------------------------------
737
738    #[tokio::test]
739    async fn concurrent_mutation_between_prepare_and_apply_trips_guard_and_rolls_back() {
740        let pool = scratch_pool("staleness_tripped");
741        seed_schema(&pool);
742        let a = Uuid::new_v4();
743        insert_entity(&pool, a, "alpha");
744
745        // Plan prepared against pre-transaction state (a exists).
746        let plan = rename_plan(a, "alpha-v2", "rename-a");
747
748        // Concurrent mutation between prepare and apply: a is deleted by a
749        // separate writer before the commit pass runs.
750        {
751            let writer = pool.try_writer().expect("writer");
752            writer
753                .conn()
754                .execute(
755                    "DELETE FROM entities WHERE id = ?1",
756                    rusqlite::params![a.to_string()],
757                )
758                .expect("concurrent delete");
759        }
760
761        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
762        let outcome = run_atomic_unit(&bridge, vec![plan])
763            .await
764            .expect("seam call ok");
765        match outcome {
766            AtomicRunOutcome::RolledBack {
767                failed_op_index,
768                failure,
769            } => {
770                assert_eq!(failed_op_index, 0);
771                assert!(matches!(
772                    failure,
773                    AtomicOpFailure::GuardFailed { observed: 0, .. }
774                ));
775            }
776            other => panic!("expected RolledBack from the stale guard, got {other:?}"),
777        }
778    }
779
780    #[tokio::test]
781    async fn no_mutation_twin_commits() {
782        let pool = scratch_pool("staleness_untripped");
783        seed_schema(&pool);
784        let a = Uuid::new_v4();
785        insert_entity(&pool, a, "alpha");
786
787        let plan = rename_plan(a, "alpha-v2", "rename-a");
788        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
789        let outcome = run_atomic_unit(&bridge, vec![plan])
790            .await
791            .expect("seam call ok");
792        assert!(matches!(outcome, AtomicRunOutcome::Committed { .. }));
793        assert!(entity_exists(&pool, a));
794    }
795
796    // ------------------------------------------------------------------
797    // 4. Dangling-edge
798    // ------------------------------------------------------------------
799
800    #[tokio::test]
801    async fn dangling_edge_from_delete_then_link_rolls_back_whole_unit() {
802        let pool = scratch_pool("dangling_edge");
803        seed_schema(&pool);
804        let x = Uuid::new_v4();
805        let a = Uuid::new_v4();
806        insert_entity(&pool, x, "x");
807        insert_entity(&pool, a, "a");
808        let before = entities_snapshot(&pool);
809
810        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
811        let edge_id = Uuid::new_v4();
812        let plans = vec![delete_plan(x, "delete-x"), link_plan(edge_id, a, x)];
813
814        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
815        match outcome {
816            AtomicRunOutcome::RolledBack {
817                failed_op_index,
818                failure,
819            } => {
820                assert_eq!(
821                    failed_op_index, 1,
822                    "delete(x) succeeds; link(a, x) is the op whose \
823                     endpoint-existence guard fails once x is gone"
824                );
825                assert!(matches!(
826                    failure,
827                    AtomicOpFailure::GuardFailed { observed: 0, .. }
828                ));
829            }
830            other => panic!("expected RolledBack, got {other:?}"),
831        }
832
833        assert_eq!(
834            edge_count(&pool, a, x),
835            0,
836            "no dangling edge may be committed"
837        );
838        assert_eq!(
839            entities_snapshot(&pool),
840            before,
841            "x must still exist — the whole unit rolled back, including the delete"
842        );
843    }
844
845    // ------------------------------------------------------------------
846    // 5. Merge-rewire
847    // ------------------------------------------------------------------
848
849    #[tokio::test]
850    async fn merge_rewire_sees_earlier_in_file_edge_write() {
851        let pool = scratch_pool("merge_rewire");
852        seed_schema(&pool);
853        let z = Uuid::new_v4();
854        let from = Uuid::new_v4();
855        let into = Uuid::new_v4();
856        insert_entity(&pool, z, "z");
857        insert_entity(&pool, from, "from-entity");
858        insert_entity(&pool, into, "into-entity");
859
860        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
861        let edge_id = Uuid::new_v4();
862        // [link(from, z), merge(into, from)] — the rewire's predicate-based
863        // UPDATE must see the edge the earlier op in THIS SAME unit
864        // inserted (ADR-099 acceptance criteria: "merge rewires see earlier
865        // in-file writes").
866        let plans = vec![link_plan(edge_id, from, z), merge_plan(into, from)];
867
868        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
869        assert!(
870            matches!(outcome, AtomicRunOutcome::Committed { .. }),
871            "expected the unit to commit: {outcome:?}"
872        );
873
874        assert_eq!(
875            edge_count(&pool, from, z),
876            0,
877            "no live edge may remain sourced from the merged-away entity"
878        );
879        assert_eq!(
880            edge_count(&pool, into, z),
881            1,
882            "the edge must be rewired onto `into`"
883        );
884        assert!(
885            !entity_exists(&pool, from),
886            "the `from` entity must be tombstoned (soft-deleted)"
887        );
888    }
889
890    // ------------------------------------------------------------------
891    // 6. Zero-row
892    // ------------------------------------------------------------------
893
894    #[tokio::test]
895    async fn zero_row_apply_fails_the_whole_unit() {
896        let pool = scratch_pool("zero_row");
897        seed_schema(&pool);
898        let x = Uuid::new_v4();
899        insert_entity(&pool, x, "x");
900        let before = entities_snapshot(&pool);
901
902        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
903        // [delete(x, hard), update(x)] — update's affected-row guard
904        // observes zero rows once x is already gone.
905        let plans = vec![
906            delete_plan(x, "delete-x"),
907            rename_plan(x, "x-v2", "update-x"),
908        ];
909
910        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
911        match outcome {
912            AtomicRunOutcome::RolledBack {
913                failed_op_index,
914                failure,
915            } => {
916                assert_eq!(failed_op_index, 1);
917                assert_eq!(
918                    failure,
919                    AtomicOpFailure::GuardFailed {
920                        statement_label: Some("update-x".to_string()),
921                        expected: AffectedRowGuard::exactly(1),
922                        observed: 0,
923                    }
924                );
925            }
926            other => panic!("expected RolledBack, got {other:?}"),
927        }
928
929        assert_eq!(
930            entities_snapshot(&pool),
931            before,
932            "x must be restored — the whole unit rolled back"
933        );
934    }
935
936    // ------------------------------------------------------------------
937    // Post-commit effect collection (UpdatePlan's reindex caveat, D3)
938    // ------------------------------------------------------------------
939
940    // ------------------------------------------------------------------
941    // 7. Daemon coexistence (ADR-099 B3 acceptance test 5)
942    // ------------------------------------------------------------------
943
944    /// An atomic unit must go through the SAME `WriterTaskHandle` queue as
945    /// an ordinary single-row write — not a separate connection that would
946    /// let it silently bypass single-writer serialization (ADR-067
947    /// Component A). This reuses the deterministic occupier pattern from
948    /// `khive-db::stores::graph_tests::upsert_edge_routes_through_writer_task_when_flag_enabled`
949    /// (Slice A): an occupier closure parks on a oneshot inside the writer
950    /// task's one drain slot, so both the atomic unit's `atomic_unit` call
951    /// and a concurrent ordinary `upsert_entity` call are forced to queue
952    /// behind it. `queue_depth` reaching 2 while both are pending, then
953    /// draining to 0 once the occupier releases and both complete, is the
954    /// proof that `run_atomic_unit` "discriminates" through the real queue
955    /// gauge rather than opening a competing connection.
956    #[tokio::test]
957    async fn atomic_unit_and_concurrent_normal_write_share_the_same_writer_queue() {
958        let pool = scratch_pool("daemon_coexistence");
959        seed_schema(&pool);
960        let a = Uuid::new_v4();
961        let b = Uuid::new_v4();
962        insert_entity(&pool, a, "alpha");
963
964        let writer_task = pool
965            .writer_task_handle()
966            .expect("writer task lookup")
967            .expect("writer task must be spawned with the flag on for a file-backed pool");
968
969        let (started_tx, started_rx) = tokio::sync::oneshot::channel::<()>();
970        let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
971        let occupier = {
972            let writer_task = writer_task.clone();
973            tokio::spawn(async move {
974                writer_task
975                    .send(move |_conn| {
976                        let _ = started_tx.send(());
977                        let _ = release_rx.blocking_recv();
978                        Ok::<(), StorageError>(())
979                    })
980                    .await
981            })
982        };
983
984        started_rx
985            .await
986            .expect("occupier must signal it has started running inside the writer task");
987        assert_eq!(
988            writer_task.queue_depth(),
989            0,
990            "channel must start empty once the occupier has been dequeued and is running"
991        );
992
993        // The atomic unit: renames `a`.
994        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
995        let atomic_plans = vec![rename_plan(a, "alpha-atomic", "rename-a-atomic")];
996        let atomic_task = tokio::spawn(async move { run_atomic_unit(&bridge, atomic_plans).await });
997
998        // A concurrent ORDINARY write, routed through the SAME
999        // `WriterTaskHandle::send` the real `with_writer` path uses
1000        // (khive-db's own `graph_tests` occupier test asserts this for
1001        // `upsert_edge`) — NOT a second `pool.try_writer()` connection,
1002        // which would open a competing SQLite handle and contend on the
1003        // file lock the occupier's `BEGIN IMMEDIATE` already holds,
1004        // producing a `DatabaseBusy` false failure unrelated to the queue
1005        // this test is actually proving something about.
1006        let normal_write_task = {
1007            let writer_task = writer_task.clone();
1008            let b_str = b.to_string();
1009            tokio::spawn(async move {
1010                writer_task
1011                    .send(move |conn| {
1012                        conn.execute(
1013                            "INSERT INTO entities \
1014                             (id, namespace, kind, name, created_at, updated_at) \
1015                             VALUES (?1, 'local', 'concept', ?2, 0, 0)",
1016                            rusqlite::params![b_str, "bravo"],
1017                        )
1018                        .map_err(|e| StorageError::Internal(e.to_string()))
1019                    })
1020                    .await
1021            })
1022        };
1023
1024        // Both the atomic unit's `atomic_unit` call and (best-effort) the
1025        // ordinary write must appear in the SAME queue while the occupier
1026        // holds the slot — this is the coexistence proof: neither one opens
1027        // a side-channel connection that would let it skip the queue.
1028        let mut saw_both_enqueued = false;
1029        for _ in 0..200 {
1030            if writer_task.queue_depth() >= 2 {
1031                saw_both_enqueued = true;
1032                break;
1033            }
1034            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
1035        }
1036        assert!(
1037            saw_both_enqueued,
1038            "expected BOTH the atomic unit's atomic_unit() call and the \
1039             concurrent ordinary write to appear in the writer task's queue \
1040             while the occupier held the single drain slot (queue_depth \
1041             should have reached 2) — observed {}; run_atomic_unit is not \
1042             sharing the same queue as an ordinary write",
1043            writer_task.queue_depth()
1044        );
1045
1046        release_tx.send(()).expect("release occupier");
1047        occupier
1048            .await
1049            .expect("occupier task join")
1050            .expect("occupier op ok");
1051
1052        let atomic_outcome = atomic_task
1053            .await
1054            .expect("atomic task join")
1055            .expect("seam call ok");
1056        assert!(
1057            matches!(atomic_outcome, AtomicRunOutcome::Committed { .. }),
1058            "atomic unit must commit once the occupier releases: {atomic_outcome:?}"
1059        );
1060        normal_write_task
1061            .await
1062            .expect("normal write task join")
1063            .expect("normal write op ok");
1064
1065        assert!(
1066            entity_exists(&pool, a),
1067            "a must exist (renamed) after commit"
1068        );
1069        {
1070            // Scoped: the `WriterGuard` returned by `try_writer()` holds a
1071            // non-reentrant `parking_lot::Mutex` for as long as it lives.
1072            // Left unscoped, it would still be held when `entity_exists`
1073            // below tries to check out the same writer, deadlocking (in
1074            // practice, timing out after `checkout_timeout`) against itself
1075            // rather than against anything the writer task/occupier hold.
1076            let writer = pool.try_writer().expect("writer");
1077            let renamed: String = writer
1078                .conn()
1079                .query_row(
1080                    "SELECT name FROM entities WHERE id = ?1",
1081                    rusqlite::params![a.to_string()],
1082                    |row| row.get(0),
1083                )
1084                .expect("query renamed entity");
1085            assert_eq!(renamed, "alpha-atomic");
1086        }
1087        assert!(
1088            entity_exists(&pool, b),
1089            "the concurrent ordinary write must also have landed"
1090        );
1091    }
1092
1093    #[tokio::test]
1094    async fn post_commit_effects_are_collected_in_op_order_and_only_for_update() {
1095        let pool = scratch_pool("post_commit_collection");
1096        seed_schema(&pool);
1097        let a = Uuid::new_v4();
1098        let b = Uuid::new_v4();
1099        insert_entity(&pool, a, "alpha");
1100        insert_entity(&pool, b, "bravo");
1101
1102        let bridge = SqlBridge::new(StdArc::clone(&pool), true);
1103        let mut update_a = match rename_plan(a, "alpha-v2", "rename-a") {
1104            AtomicOpPlan::Update(p) => p,
1105            _ => unreachable!(),
1106        };
1107        update_a.post_commit = PostCommitEffect::ReindexEntity { entity_id: a };
1108        let plans = vec![
1109            AtomicOpPlan::Update(update_a),
1110            delete_plan(b, "delete-b"), // no post-commit effect for delete
1111        ];
1112
1113        let outcome = run_atomic_unit(&bridge, plans).await.expect("seam call ok");
1114        match outcome {
1115            AtomicRunOutcome::Committed { post_commit } => {
1116                fn require_commit_provenance(_: &CommittedPostCommitEffects) {}
1117                require_commit_provenance(&post_commit);
1118                assert_eq!(
1119                    post_commit.as_slice(),
1120                    &[PostCommitEffect::ReindexEntity { entity_id: a }]
1121                );
1122            }
1123            other => panic!("expected Committed, got {other:?}"),
1124        }
1125    }
1126}