mvcc-transaction-model

name	mvcc-transaction-model
description	How transaction, snapshot, and MVCC semantics map between Turso's Rust core and Ahtola's managed engine, and what must stay aligned. Use this when touching transactions, snapshots, isolation, commit/rollback, or the local/replica adapter dispatch.

MVCC and transaction model

Turso implements an MVCC layer (turso-src/core/mvcc/: clock.rs, cursor.rs, portable_logical.rs, yield_hooks.rs, yield_points.rs) on top of the storage/pager layer. Ahtola's managed engine mirrors the observable transaction semantics (begin/commit/rollback, snapshot isolation, savepoints) but adapts the implementation to managed idioms.

Where things live in Ahtola

• Transaction execution: src/Ahtola.Core/Execution/VdbeTransaction.cs (BeginTransaction/CommitTransaction/RollbackTransaction opcodes).
• Snapshot/adapter layer: src/Ahtola.Core/ManagedLocalAdapters.cs — IManagedConnectionAdapter, ManagedSnapshotException, ManagedSnapshotFailure, CopySnapshotTo(...) between connections.
• Rollback journal: src/Ahtola.Core/Storage/SqliteRollbackJournal.cs.
• WAL read-snapshot/checkpoint coordination: SqliteWalReadSnapshotCoordinator.cs, SqliteWalWriterCheckpointCoordinator.cs.
• Local/remote/replica provider dispatch: Ahtola.Data (connection pooling, provider dispatch, Hrana remote client).

What must stay aligned

• Isolation semantics: a snapshot taken at begin-transaction must see a consistent database view for the transaction's lifetime. Do not weaken snapshot isolation to "read latest" to fix a test — fix the snapshot coordinator.
• Commit/rollback atomicity: commit must durably flush per the WAL contract; rollback must restore the pre-transaction page state exactly. Cross-check SqliteRollbackJournal.cs and the WAL checkpoint coordinator against turso-src/core/mvcc/ and turso-src/core/storage/wal.rs.
• Schema version / user version / application id: ApplySnapshotPragmaHeader propagates these on snapshot copy; do not drop them.
• Snapshot copy invariants: CopySnapshotTo checks CannotProveDistinctSnapshotFiles(...) and raises a ManagedSnapshotException with a ManagedSnapshotFailure reason. Preserve those failure reasons — callers branch on them.

Adaptation, not reimplementation

• Turso's MVCC uses cooperative yielding (yield_hooks/yield_points) for scheduling. Ahtola uses async/await or synchronous managed flow — the semantics (when a transaction yields, what a reader sees) must match, not the call style. See the async-io-port skill.
• The Turso MVCC clock (clock.rs) assigns logical timestamps; mirror the ordering invariants in the managed layer even if the clock implementation differs.
• Do not introduce a native MVCC or sync companion. Replica/sync behavior references Turso.Data.Sync by name and fails closed (see pure-managed-closure); that is a product decision.

When unsure

Consult turso-src/core/mvcc/ for the upstream semantics and docs/wal-interoperability-contract.md for the WAL framing that the snapshot coordinators depend on.