Module atomic_runner 

ADR-099 migration step 3 (sub-slice B2) — the atomic runner: the synchronous commit-pass mechanism that applies a caller-supplied sequence of prepared write plans (crate::atomic_plan) as ONE SqlAccess::atomic_unit, under a per-op SAVEPOINT, committing every plan or rolling back the whole unit.

ADR-099 B3 caller: kkernel exec --ops-file --atomic — async prepare, then this runner’s one synchronous commit pass, then async post-commit effects. Runtime callers also supply prepared plans directly (hard-delete in operations.rs). See docs/api/atomic_runner.md for the full three-phase shape (ADR-099 D1).

Safety: suspend-free invariant

run_atomic_unit is the one place in this crate that builds an AtomicUnitOp closure for SqlAccess::atomic_unit, whose contract requires the closure’s future to resolve on its first poll — synchronous DML against the provided &mut dyn SqlWriter only, never a suspending .await. Every statement driven here comes from AtomicOpPlan::plan_statements, which can only ever produce PlanStatements (plain parameterized SQL), so no code path in this module can hand atomic_unit a suspending future. The paired suspend-trap tests at the bottom of this file check both the happy-path (real commit pass resolves on first poll) and the misuse-is-caught case (a hand-built suspending closure fails loudly through the same seam). See docs/api/atomic_runner.md#suspend-free-invariant for the full argument.

Structs

AtomicRunnerError

A failure of the atomic_unit seam itself — the storage layer refused or could not complete the call at all (read-only backend, no async runtime for the writer-task lookup, or an AtomicUnitOp that violated the suspend-free invariant and got caught by block_on_sync). Never returned for an ordinary op-level guard or SQL failure inside the unit — those surface as AtomicRunOutcome::RolledBack, not this error.

Enums

AtomicOpFailure

Why a single op’s plan failed inside the commit pass (ADR-099 acceptance criteria: “the failing op index is recorded”).

AtomicOpPlan

One admissible op’s prepared write plan (ADR-099 D3’s v1 admissible verb groups), ready for the commit pass. This is the Vec<AtomicOpPlan> shape run_atomic_unit consumes — the runner is agnostic to which verb produced a given plan; it only needs each plan’s ordered statements (plan_statements) and any deferred post-commit effect (post_commit_effect).

AtomicRunOutcome

The whole-unit outcome of a completed run_atomic_unit call — the commit pass ran to a clean, distinguishable verdict (never returned for a seam-level failure; see AtomicRunnerError for that case).

Functions

run_atomic_unit

Run plans as ONE atomic unit (ADR-099 D1 commit pass): open a single SqlAccess::atomic_unit, apply every plan’s statements under a named SAVEPOINT (adr099_atomic_op_<n>), and commit all or roll back all.