Skip to main content

uqa_engine/transactions/
row_locks_session.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Session-level integration between the SQL transaction stack and the row-lock manager: typed-mutation locking, statement-scoped recheck contexts, and change publication for tuple-local rechecks.
8
9use super::{
10    panic_description, BackendTransactionMode, Engine, SQLError, TransactionIntent,
11    TransactionRowChange,
12};
13
14impl Engine {
15    fn ensure_row_mutation_allowed(&self, table: &str) -> Result<(), SQLError> {
16        if self.current_transaction_is_read_only()
17            && self
18                .table_persistence(table)
19                .map_err(|error| {
20                    SQLError::Internal(format!(
21                        "resolve read-only row mutation target `{table}`: {error}"
22                    ))
23                })?
24                .is_some_and(|persistence| {
25                    persistence != uqa_sql::ast::RelationPersistence::Temporary
26                })
27        {
28            return Err(SQLError::Routine {
29                sqlstate: "25006".into(),
30                message: "cannot execute row mutation in a read-only transaction".into(),
31            });
32        }
33        Ok(())
34    }
35
36    /// Keep the row mutation transaction boundary after SQL has acquired its chosen tuple-lock strength. Existing temporary rows retain their read-only transaction permission without taking a stronger lock.
37    pub(crate) fn with_prepared_row_write_transaction<R>(
38        &self,
39        table: &str,
40        f: impl FnOnce(&Self) -> Result<R, SQLError>,
41    ) -> Result<R, SQLError> {
42        let _statement = self.lock_statement_gate();
43        self.ensure_row_mutation_allowed(table)?;
44        self.with_implicit_transaction_mutation(f)
45    }
46
47    /// Run one typed row mutation with the same relation/tuple locking order as SQL DML: logical locks first, backend-writer promotion second. This prevents typed APIs from bypassing `SELECT ... FOR UPDATE` and avoids a writer/row-lock inversion while waiting for another transaction.
48    pub(crate) fn with_implicit_row_write_transaction<R>(
49        &self,
50        table: &str,
51        doc_id: uqa_core::DocId,
52        strength: uqa_sql::ast::LockStrength,
53        f: impl FnOnce(&Self) -> Result<R, SQLError>,
54    ) -> Result<R, SQLError> {
55        self.row_write_transaction(table, Some((doc_id, strength)), true, f)
56    }
57
58    /// Run the write of an inserted row. One that may replace a row locks it as any typed row mutation does.
59    ///
60    /// A new row takes no lock of its own. No other transaction can address its identity before this one commits: a supplied identity is a unique key whose value this transaction has reserved, a generated one was reserved for the row, and a versioned transaction keeps the row private until it commits. `PostgreSQL` likewise locks no tuple it inserts and makes no session wait for a row that session cannot see. The row may still be written over the revision a deleted row left, which the write must expect as it stands now, so the storage target is refreshed unless the identity was never used.
61    pub(crate) fn with_inserted_row_write_transaction<R>(
62        &self,
63        table: &str,
64        doc_id: uqa_core::DocId,
65        inserted: uqa_execution::mutation::publication::InsertedIdentity,
66        f: impl FnOnce(&Self) -> Result<R, SQLError>,
67    ) -> Result<R, SQLError> {
68        if inserted.is_vacant() && self.versioned_backend_transactions() {
69            return self.row_write_transaction(table, None, !inserted.is_unused(), f);
70        }
71        self.with_implicit_row_write_transaction(
72            table,
73            doc_id,
74            uqa_sql::ast::LockStrength::ForUpdate,
75            f,
76        )
77    }
78
79    /// `row` is the tuple to lock before the write, and `refresh` says whether the write needs the latest committed state, as it does after a lock that may have waited for a writer that has since committed.
80    fn row_write_transaction<R>(
81        &self,
82        table: &str,
83        row: Option<(uqa_core::DocId, uqa_sql::ast::LockStrength)>,
84        refresh: bool,
85        f: impl FnOnce(&Self) -> Result<R, SQLError>,
86    ) -> Result<R, SQLError> {
87        let _statement = self.lock_statement_gate();
88        self.ensure_row_mutation_allowed(table)?;
89        if self.storage.backend.is_none() && self.transaction_depth() == 0 {
90            return f(self);
91        }
92        if self.transaction_depth() != 0 {
93            self.ensure_transaction_usable()?;
94        }
95
96        let started = self.transaction_depth() == 0;
97        if started {
98            self.begin_implicit_statement_transaction(false)?;
99        }
100        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
101            self.prepare_serializable_transaction_snapshot()?;
102            self.lock_relation(table, crate::row_locks::RelationLockMode::RowExclusive)?;
103            if let Some((doc_id, strength)) = row {
104                match self.lock_row(
105                    table,
106                    doc_id,
107                    strength,
108                    uqa_sql::ast::LockWait::Block,
109                    table,
110                )? {
111                    crate::row_locks::LockAcquire::Granted { .. } => {}
112                    crate::row_locks::LockAcquire::Skipped => {
113                        return Err(SQLError::Internal(
114                            "blocking typed row mutation unexpectedly skipped a row".into(),
115                        ));
116                    }
117                }
118            }
119            if refresh {
120                self.prepare_explicit_transaction_writer()?;
121            } else {
122                self.prepare_unrefreshed_transaction_writer()?;
123            }
124            f(self)
125        }));
126
127        if !started {
128            return self.finish_existing_transaction_operation(result, std::convert::identity);
129        }
130        match result {
131            Ok(Ok(value)) => {
132                self.commit()?;
133                Ok(value)
134            }
135            Ok(Err(error)) => match self.rollback() {
136                Ok(()) => Err(error),
137                Err(rollback_error) => Err(Self::rollback_cleanup_error(&rollback_error, format!(
138                    "typed row mutation failed: {error}; rollback also failed: {rollback_error}"
139                ))),
140            },
141            Err(payload) => match self.rollback() {
142                Ok(()) => std::panic::resume_unwind(payload),
143                Err(rollback_error) => Err(Self::rollback_cleanup_error(&rollback_error, format!(
144                    "typed row mutation rollback after panic failed: {rollback_error}; original panic: {}",
145                    panic_description(payload.as_ref())
146                ))),
147            },
148        }
149    }
150
151    fn row_lock_table_name(&self, table: &str) -> Result<String, SQLError> {
152        self.try_resolve_table_name(table)
153            .map_err(|error| {
154                SQLError::Internal(format!("resolve row-lock table `{table}`: {error}"))
155            })
156            .map(|resolved| resolved.unwrap_or_else(|| table.to_string()))
157    }
158
159    pub(crate) fn row_lock_change_requires_recheck(&self) -> Result<bool, SQLError> {
160        let Some(backend) = self.storage.backend.as_ref() else {
161            return Ok(true);
162        };
163        if self.storage.provider.is_none() {
164            return Ok(false);
165        }
166        if backend.transaction_model().is_versioned() {
167            return Ok(true);
168        }
169        let stack = self.session.transactions.lock();
170        let deferred_reader = stack.first().is_some_and(|frame| {
171            frame.intent == TransactionIntent::ReadOnly
172                || frame.backend_mode == BackendTransactionMode::Deferred
173        });
174        drop(stack);
175        if !deferred_reader {
176            return Ok(false);
177        }
178        backend
179            .transaction_has_written()
180            .map(|written| !written)
181            .map_err(|error| Self::storage_tx_error("inspect row-lock recheck snapshot", &error))
182    }
183
184    pub(crate) fn lock_row(
185        &self,
186        table: &str,
187        doc_id: uqa_core::DocId,
188        strength: uqa_sql::ast::LockStrength,
189        wait: uqa_sql::ast::LockWait,
190        display_name: &str,
191    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
192        let canonical = self.row_lock_table_name(table)?;
193        let key = crate::row_locks::RowLockKey {
194            table: self.row_locks.table_key(&canonical),
195            doc_id,
196        };
197        self.row_locks.acquire(&crate::row_locks::LockRequest {
198            session_id: self.session_id,
199            key,
200            strength,
201            mark: self.current_lock_mark(),
202            wait,
203            cancel: &self.runtime.cancellation,
204            relation: display_name,
205        })
206    }
207
208    /// Refresh a named parameter after obtaining its transaction-retained logical lock. Execution workers already belong to the parent command, so this adapter must not reenter its thread-owned statement gate.
209    pub(crate) fn lock_scoring_parameter_write(&self, name: &str) -> Result<(), SQLError> {
210        let Some(backend) = self
211            .storage
212            .backend
213            .as_ref()
214            .filter(|backend| backend.transaction_model().is_versioned())
215        else {
216            return Ok(());
217        };
218        if self.transaction_depth() == 0 {
219            return Err(SQLError::Internal(
220                "scoring parameter writes require an active transaction".into(),
221            ));
222        }
223        self.row_locks.acquire(&crate::row_locks::LockRequest {
224            session_id: self.session_id,
225            key: crate::row_locks::RowLockKey {
226                table: self.row_locks.scoring_parameters_key(name),
227                doc_id: 0,
228            },
229            strength: uqa_sql::ast::LockStrength::ForUpdate,
230            mark: self.current_lock_mark(),
231            wait: uqa_sql::ast::LockWait::Block,
232            cancel: &self.runtime.cancellation,
233            relation: name,
234        })?;
235        backend
236            .refresh_transaction_snapshot(&self.runtime.cancellation)
237            .map_err(|error| Self::storage_tx_error("refresh scoring parameters", &error))
238    }
239
240    pub(crate) fn reserve_document_id_candidate(
241        &self,
242        table: &str,
243        doc_id: uqa_core::DocId,
244    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
245        let canonical = self.row_lock_table_name(table)?;
246        self.row_locks.acquire(&crate::row_locks::LockRequest {
247            session_id: self.session_id,
248            key: crate::row_locks::RowLockKey {
249                table: self.row_locks.document_identity_key(&canonical),
250                doc_id,
251            },
252            strength: uqa_sql::ast::LockStrength::ForUpdate,
253            mark: self.current_lock_mark(),
254            wait: uqa_sql::ast::LockWait::SkipLocked,
255            cancel: &self.runtime.cancellation,
256            relation: table,
257        })
258    }
259
260    pub(crate) fn lock_key_reservation(
261        &self,
262        digest: [u8; 32],
263        display_name: &str,
264    ) -> Result<crate::row_locks::LockAcquire, SQLError> {
265        let retained = self.row_locks.retain_key_reservation(digest);
266        let key = crate::row_locks::RowLockKey {
267            table: retained.table_key(),
268            doc_id: 0,
269        };
270        self.row_locks.acquire(&crate::row_locks::LockRequest {
271            session_id: self.session_id,
272            key,
273            strength: uqa_sql::ast::LockStrength::ForUpdate,
274            mark: self.current_lock_mark(),
275            wait: uqa_sql::ast::LockWait::Block,
276            cancel: &self.runtime.cancellation,
277            relation: display_name,
278        })
279    }
280
281    pub(crate) fn lock_key_reservations(
282        &self,
283        keys: &[[u8; 32]],
284        display_name: &str,
285    ) -> Result<Vec<crate::row_locks::LockAcquire>, SQLError> {
286        let mark = self.current_lock_mark();
287        let retained = keys
288            .iter()
289            .map(|key| self.row_locks.retain_key_reservation(*key))
290            .collect::<Vec<_>>();
291        let requests = retained
292            .iter()
293            .map(|identity| crate::row_locks::LockRequest {
294                session_id: self.session_id,
295                key: crate::row_locks::RowLockKey {
296                    table: identity.table_key(),
297                    doc_id: 0,
298                },
299                strength: uqa_sql::ast::LockStrength::ForUpdate,
300                mark,
301                wait: uqa_sql::ast::LockWait::Block,
302                cancel: &self.runtime.cancellation,
303                relation: display_name,
304            })
305            .collect::<Vec<_>>();
306        self.row_locks.acquire_batch(&requests)
307    }
308
309    pub(crate) fn lock_relation(
310        &self,
311        table: &str,
312        mode: crate::row_locks::RelationLockMode,
313    ) -> Result<(), SQLError> {
314        let canonical = self.row_lock_table_name(table)?;
315        self.row_locks.acquire_relation(
316            self.session_id,
317            self.row_locks.table_key(&canonical),
318            mode,
319            self.current_lock_mark(),
320            &self.runtime.cancellation,
321        )
322    }
323
324    pub(crate) fn temporary_relation_lock(
325        &self,
326        table: &str,
327        mode: crate::row_locks::RelationLockMode,
328    ) -> Result<crate::row_locks::ScopedRelationLock<'_>, SQLError> {
329        let canonical = self.row_lock_table_name(table)?;
330        self.prepare_transaction_lock_wait()?;
331        self.row_locks.acquire_scoped_relation(
332            self.session_id,
333            self.row_locks.table_key(&canonical),
334            mode,
335            self.temporary_relation_lock_marks()?,
336            &self.runtime.cancellation,
337        )
338    }
339
340    /// Whether the open transaction of this session already changed or rewrote the row itself. Such a row's current image is authoritative for this session, so cross-process verification must not replace it with the older committed image.
341    pub(crate) fn row_changed_in_open_transaction(
342        &self,
343        table: &str,
344        doc_id: uqa_core::DocId,
345    ) -> Result<bool, SQLError> {
346        let canonical = self.row_lock_table_name(table)?;
347        let key = crate::row_locks::RowLockKey {
348            table: self.row_locks.table_key(&canonical),
349            doc_id,
350        };
351        Ok(self.session.transactions.lock().iter().any(|frame| {
352            frame.row_changes.iter().any(|change| {
353                change.pending.key == key
354                    || matches!(
355                        change.pending.kind,
356                        crate::row_locks::PendingRowChangeKind::Rewrite(successor)
357                            if successor == key
358                    )
359            })
360        }))
361    }
362
363    /// The row identity a committed primary-key rewrite moved `doc_id` to, following chained rewrites to the final identity. `None` when the row keeps its identity in the latest committed state visible to the lock manager. Rewrites are recorded only while a lock or observer keeps them alive, which covers every DML statement waiting on the row.
364    pub(crate) fn committed_row_successor(
365        &self,
366        table: &str,
367        doc_id: uqa_core::DocId,
368    ) -> Result<crate::row_locks::RowChangeTarget, SQLError> {
369        let canonical = self.row_lock_table_name(table)?;
370        self.row_locks.row_successor_after(
371            &canonical,
372            doc_id,
373            &self.row_lock_snapshot_change_baseline()?,
374        )
375    }
376
377    pub(crate) fn committed_physical_row_successor(
378        &self,
379        table: &str,
380        doc_id: uqa_core::DocId,
381    ) -> Result<crate::row_locks::PhysicalRowChangeTarget, SQLError> {
382        let canonical = self.row_lock_table_name(table)?;
383        self.row_locks.physical_row_successor_after(
384            &canonical,
385            doc_id,
386            &self.row_lock_snapshot_change_baseline()?,
387        )
388    }
389
390    pub(crate) fn row_lock_table_for_hash(&self, table_hash: u64) -> Result<String, SQLError> {
391        let tables = self.storage.tables.read();
392        let mut matches = tables
393            .keys()
394            .map(uqa_storage::RelationIdentity::qualified_name)
395            .filter(|table| {
396                crate::row_locks::RowLockManager::stable_table_hash(table) == table_hash
397            });
398        let table = matches.next().ok_or_else(|| {
399            SQLError::Internal(format!(
400                "row-change successor refers to unknown relation hash {table_hash}"
401            ))
402        })?;
403        if matches.next().is_some() {
404            return Err(SQLError::Internal(format!(
405                "row-change successor relation hash {table_hash} is ambiguous"
406            )));
407        }
408        Ok(table)
409    }
410
411    fn deferred_foreign_key_checks_for_row(
412        &self,
413        table: &str,
414        row: crate::row_locks::RowLockKey,
415        rewrite: Option<(&crate::Document, &crate::Document)>,
416    ) -> Result<Vec<crate::DeferredForeignKeyCheck>, SQLError> {
417        let firing_relation =
418            crate::RelationIdentity::from_legacy_name(table).map_err(|error| {
419                SQLError::Internal(format!(
420                    "decode deferred foreign-key firing relation '{table}': {error}"
421                ))
422            })?;
423        let foreign_keys = self.foreign_keys_in_execution(table).map_err(|error| {
424            SQLError::Internal(format!(
425                "read deferred foreign keys for table `{table}`: {error}"
426            ))
427        })?;
428        let mut checks = Vec::new();
429        for foreign_key in foreign_keys {
430            if rewrite.is_some_and(|(old_document, new_document)| {
431                foreign_key.local_columns.iter().all(|column| {
432                    old_document
433                        .get(column)
434                        .cloned()
435                        .unwrap_or(crate::Value::Null)
436                        == new_document
437                            .get(column)
438                            .cloned()
439                            .unwrap_or(crate::Value::Null)
440                })
441            }) {
442                continue;
443            }
444            if foreign_key.enforced && self.foreign_key_is_deferred(table, &foreign_key)? {
445                checks.push(crate::DeferredForeignKeyCheck {
446                    constraint: self.foreign_key_constraint_identity(table, &foreign_key)?,
447                    firing_relation: firing_relation.clone(),
448                    row: Some(row),
449                    referenced: false,
450                });
451            }
452        }
453        Ok(checks)
454    }
455
456    fn note_row_change(
457        &self,
458        table: &str,
459        doc_id: uqa_core::DocId,
460        kind: crate::row_locks::PendingRowChangeKind,
461    ) -> Result<(), SQLError> {
462        let canonical = self.row_lock_table_name(table)?;
463        let key = crate::row_locks::RowLockKey {
464            table: self.row_locks.table_key(&canonical),
465            doc_id,
466        };
467        let source_generation = self.require_table(&canonical)?.storage_generation();
468        let mut stack = self.session.transactions.lock();
469        let pending = crate::row_locks::PendingRowChange { key, kind };
470        if let Some(frame) = stack.last_mut() {
471            let change = TransactionRowChange {
472                pending,
473                source_generation,
474                successor_generation: None,
475                query_origin: self
476                    .session_execution_view()
477                    .transaction_snapshot_identity(),
478            };
479            frame.row_changes.push(change);
480            self.follow_row_change(&mut stack, &change)
481        } else {
482            drop(stack);
483            let publication = self
484                .row_locks
485                .begin_change_publication(&self.runtime.cancellation)?;
486            let result = self
487                .row_locks
488                .publish_row_changes(self.session_id, [pending]);
489            drop(publication);
490            result
491        }
492    }
493
494    pub(crate) fn note_row_inserted(
495        &self,
496        table: &str,
497        doc_id: uqa_core::DocId,
498    ) -> Result<(), SQLError> {
499        self.note_row_change(
500            table,
501            doc_id,
502            crate::row_locks::PendingRowChangeKind::Insert,
503        )
504    }
505
506    pub(crate) fn note_row_changed(
507        &self,
508        table: &str,
509        doc_id: uqa_core::DocId,
510    ) -> Result<(), SQLError> {
511        self.note_row_change(
512            table,
513            doc_id,
514            crate::row_locks::PendingRowChangeKind::Update,
515        )
516    }
517
518    pub(crate) fn note_row_deleted(
519        &self,
520        table: &str,
521        doc_id: uqa_core::DocId,
522    ) -> Result<(), SQLError> {
523        self.note_row_change(
524            table,
525            doc_id,
526            crate::row_locks::PendingRowChangeKind::Delete,
527        )
528    }
529
530    pub(crate) fn defer_inserted_foreign_key_checks(
531        &self,
532        table: &str,
533        doc_id: uqa_core::DocId,
534    ) -> Result<(), SQLError> {
535        if self.session.transactions.lock().is_empty() {
536            return Ok(());
537        }
538        let canonical = self.row_lock_table_name(table)?;
539        let row = crate::row_locks::RowLockKey {
540            table: self.row_locks.table_key(&canonical),
541            doc_id,
542        };
543        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, None)?;
544        if let Some(frame) = self.session.transactions.lock().last_mut() {
545            frame.deferred_foreign_key_checks.extend(checks);
546        }
547        Ok(())
548    }
549
550    pub(crate) fn defer_rewritten_foreign_key_checks(
551        &self,
552        table: &str,
553        doc_id: uqa_core::DocId,
554        old_document: Option<&crate::Document>,
555        new_document: &crate::Document,
556    ) -> Result<(), SQLError> {
557        if self.session.transactions.lock().is_empty() {
558            return Ok(());
559        }
560        let canonical = self.row_lock_table_name(table)?;
561        let row = crate::row_locks::RowLockKey {
562            table: self.row_locks.table_key(&canonical),
563            doc_id,
564        };
565        let rewrite = old_document.map(|old_document| (old_document, new_document));
566        let checks = self.deferred_foreign_key_checks_for_row(&canonical, row, rewrite)?;
567        if let Some(frame) = self.session.transactions.lock().last_mut() {
568            frame.deferred_foreign_key_checks.extend(checks);
569        }
570        Ok(())
571    }
572
573    /// Defer the check of a referencing row that a change to a referenced row fired, under the constraint whose deferral governs it.
574    pub(crate) fn defer_foreign_key_check(
575        &self,
576        event: super::DeferredReferencedKey<'_>,
577        row_table: &str,
578        doc_id: uqa_core::DocId,
579    ) -> Result<(), SQLError> {
580        let canonical_row_table = self.row_lock_table_name(row_table)?;
581        let check = crate::DeferredForeignKeyCheck {
582            constraint: self.referenced_key_constraint_identity(&event)?,
583            firing_relation: self.deferred_firing_relation(event.firing_table)?,
584            row: Some(crate::row_locks::RowLockKey {
585                table: self.row_locks.table_key(&canonical_row_table),
586                doc_id,
587            }),
588            referenced: true,
589        };
590        let mut stack = self.session.transactions.lock();
591        let frame = stack.last_mut().ok_or_else(|| {
592            SQLError::Internal("deferred foreign-key check outside a transaction".into())
593        })?;
594        frame.deferred_foreign_key_checks.push(check);
595        Ok(())
596    }
597
598    fn deferred_firing_relation(
599        &self,
600        firing_table: &str,
601    ) -> Result<crate::RelationIdentity, SQLError> {
602        let canonical_firing_table = self.row_lock_table_name(firing_table)?;
603        crate::RelationIdentity::from_legacy_name(&canonical_firing_table).map_err(|error| {
604            SQLError::Internal(format!(
605                "decode deferred foreign-key firing relation '{canonical_firing_table}': {error}"
606            ))
607        })
608    }
609
610    pub(crate) fn defer_foreign_key_parent_event(
611        &self,
612        event: super::DeferredReferencedKey<'_>,
613    ) -> Result<(), SQLError> {
614        let check = crate::DeferredForeignKeyCheck {
615            constraint: self.referenced_key_constraint_identity(&event)?,
616            firing_relation: self.deferred_firing_relation(event.firing_table)?,
617            row: None,
618            referenced: true,
619        };
620        let mut stack = self.session.transactions.lock();
621        let frame = stack.last_mut().ok_or_else(|| {
622            SQLError::Internal("deferred foreign-key event outside a transaction".into())
623        })?;
624        frame.deferred_foreign_key_checks.push(check);
625        Ok(())
626    }
627
628    pub(crate) fn note_row_rewritten_between_tables(
629        &self,
630        old_table: &str,
631        old_doc_id: uqa_core::DocId,
632        new_table: &str,
633        new_doc_id: uqa_core::DocId,
634    ) -> Result<(), SQLError> {
635        let old_table = self.row_lock_table_name(old_table)?;
636        let new_table = self.row_lock_table_name(new_table)?;
637        let old = crate::row_locks::RowLockKey {
638            table: self.row_locks.table_key(&old_table),
639            doc_id: old_doc_id,
640        };
641        let new = crate::row_locks::RowLockKey {
642            table: self.row_locks.table_key(&new_table),
643            doc_id: new_doc_id,
644        };
645        let source_generation = self.require_table(&old_table)?.storage_generation();
646        let successor_generation = self.require_table(&new_table)?.storage_generation();
647        let mut stack = self.session.transactions.lock();
648        let pending = crate::row_locks::PendingRowChange {
649            key: old,
650            kind: crate::row_locks::PendingRowChangeKind::Rewrite(new),
651        };
652        if let Some(frame) = stack.last_mut() {
653            for check in &mut frame.deferred_foreign_key_checks {
654                if check.row == Some(old) {
655                    check.row = Some(new);
656                }
657            }
658            let change = TransactionRowChange {
659                pending,
660                source_generation,
661                successor_generation: Some(successor_generation),
662                query_origin: self
663                    .session_execution_view()
664                    .transaction_snapshot_identity(),
665            };
666            frame.row_changes.push(change);
667            self.follow_row_change(&mut stack, &change)
668        } else {
669            drop(stack);
670            let publication = self
671                .row_locks
672                .begin_change_publication(&self.runtime.cancellation)?;
673            let result = self
674                .row_locks
675                .publish_row_changes(self.session_id, [pending]);
676            drop(publication);
677            result
678        }
679    }
680
681    pub(crate) fn row_lock_manager(&self) -> std::sync::Arc<crate::row_locks::RowLockManager> {
682        std::sync::Arc::clone(&self.row_locks)
683    }
684
685    /// Mark one in-flight SQL statement so every locking scope it executes, including scopes inside query-bearing commands, prepared execution, `EXPLAIN ANALYZE`, and DML sources, shares one row-lock recheck context. Host-callback statements nested inside another statement push their own frame.
686    pub(crate) fn begin_row_lock_statement(&self) -> RowLockStatementScope<'_> {
687        self.session.row_lock_statements.lock().push(None);
688        RowLockStatementScope { engine: self }
689    }
690
691    /// The active statement's shared row-lock recheck context, created on first use with the statement snapshot's change epoch as its recheck baseline. A direct engine call outside any SQL statement owns an ephemeral context with the same baseline semantics.
692    pub(crate) fn statement_row_lock_cache(
693        &self,
694    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
695    {
696        let budget_bytes = self.work_mem_bytes()?;
697        let baseline = self.row_lock_snapshot_change_baseline()?;
698        let mut statements = self.session.row_lock_statements.lock();
699        let Some(slot) = statements.last_mut() else {
700            drop(statements);
701            return Ok(std::sync::Arc::new(
702                uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
703                    budget_bytes,
704                    self.row_lock_manager(),
705                    baseline,
706                ),
707            ));
708        };
709        if let Some(cache) = slot.as_ref() {
710            return Ok(std::sync::Arc::clone(cache));
711        }
712        let cache = std::sync::Arc::new(
713            uqa_execution::row_locks::retry_cache::RowLockRetryCache::new(
714                budget_bytes,
715                self.row_lock_manager(),
716                baseline,
717            ),
718        );
719        *slot = Some(std::sync::Arc::clone(&cache));
720        Ok(cache)
721    }
722
723    pub(crate) fn row_lock_snapshot_change_baseline(
724        &self,
725    ) -> Result<crate::row_locks::RowChangeBaseline, SQLError> {
726        if let Some(frame) = self.session.transactions.lock().first() {
727            return Ok(frame.snapshot_change_baseline.clone());
728        }
729        self.row_locks
730            .begin_change_snapshot(&self.runtime.cancellation)?
731            .baseline()
732    }
733
734    pub(crate) fn update_statement_row_lock_baseline(
735        &self,
736        baseline: crate::row_locks::RowChangeBaseline,
737    ) {
738        if let Some(Some(cache)) = self.session.row_lock_statements.lock().last() {
739            cache.set_snapshot_baseline(baseline);
740        }
741    }
742
743    pub(crate) fn rollback_row_lock_acquisition(
744        &self,
745        acquisition: crate::row_locks::RowLockAcquisition,
746    ) {
747        self.row_locks.rollback_acquisition(acquisition);
748    }
749}
750
751/// RAII frame for one in-flight SQL statement's shared row-lock recheck context. Dropping the frame releases the statement's change observation so the lock manager can prune retained row-change versions.
752pub(crate) struct RowLockStatementScope<'engine> {
753    engine: &'engine Engine,
754}
755
756impl uqa_execution::statement::batch::context::RowLockStatementGuard for RowLockStatementScope<'_> {}
757
758impl uqa_execution::statement::batch::context::BatchRowLocks for Engine {
759    fn begin_row_lock_statement(
760        &self,
761    ) -> Box<dyn uqa_execution::statement::batch::context::RowLockStatementGuard + '_> {
762        Box::new(Engine::begin_row_lock_statement(self))
763    }
764    fn statement_row_lock_cache(
765        &self,
766    ) -> Result<std::sync::Arc<uqa_execution::row_locks::retry_cache::RowLockRetryCache>, SQLError>
767    {
768        Engine::statement_row_lock_cache(self)
769    }
770}
771
772impl Drop for RowLockStatementScope<'_> {
773    fn drop(&mut self) {
774        self.engine.session.row_lock_statements.lock().pop();
775    }
776}
777
778impl uqa_execution::row_locks::retry_cache::CommittedRowSource for crate::Engine {
779    fn get_committed_document(
780        &self,
781        table: &str,
782        doc_id: uqa_core::DocId,
783    ) -> Result<Option<uqa_storage::StoredDocument>, uqa_sql::SQLError> {
784        crate::Engine::get_committed_document(self, table, doc_id)
785    }
786}