1use 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#[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 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 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#[derive(Debug, Clone, PartialEq, Eq)]
132pub enum AtomicOpFailure {
133 GuardFailed {
139 statement_label: Option<String>,
140 expected: AffectedRowGuard,
141 observed: u64,
142 },
143 SqlError {
147 statement_label: Option<String>,
148 message: String,
149 },
150}
151
152#[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 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#[derive(Debug, PartialEq, Eq)]
197pub enum AtomicRunOutcome {
198 Committed {
206 post_commit: CommittedPostCommitEffects,
207 },
208 RolledBack {
216 failed_op_index: usize,
217 failure: AtomicOpFailure,
218 },
219}
220
221#[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
271async 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
303pub 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 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 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 std::mem::forget(dir);
424 pool
425 }
426
427 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 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 #[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 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 #[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 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 #[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 let plan = rename_plan(a, "alpha-v2", "rename-a");
747
748 {
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 #[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 #[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 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 #[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 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 #[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 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 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 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 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"), ];
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}