Skip to main content

reef_core/runtime/
session.rs

1//! Exclusive session leases, synchronous admission, and targeted input.
2//!
3//! Four properties define the module: one active lease at a time, mutation only
4//! through a held lease, an explicit admission barrier, and FIFO targeted input.
5
6use std::collections::VecDeque;
7use std::error::Error;
8use std::fmt;
9use std::sync::{Arc, Mutex, MutexGuard};
10#[cfg(test)]
11use std::sync::{Barrier, TryLockError, mpsc};
12
13use crate::redact::Locked;
14use crate::state::session_state::{self, Writer};
15use crate::transcript::item::Item;
16use crate::transcript::store::{self, Snapshot, SnapshotReader, Store, Version};
17
18/// A lease admission or mutation failure.
19#[derive(Clone, Debug, Eq, PartialEq)]
20#[non_exhaustive]
21pub enum LeaseError {
22    /// This lease has already released its authority.
23    Released,
24    /// Admission was already committed for this lease.
25    AlreadyAdmitted,
26    /// The underlying transcript rejected the mutation.
27    Transcript(store::Error),
28}
29
30impl fmt::Display for LeaseError {
31    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
32        match self {
33            Self::Released => formatter.write_str("session lease released"),
34            Self::AlreadyAdmitted => formatter.write_str("session lease already admitted"),
35            Self::Transcript(error) => error.fmt(formatter),
36        }
37    }
38}
39
40impl Error for LeaseError {
41    fn source(&self) -> Option<&(dyn Error + 'static)> {
42        match self {
43            Self::Transcript(error) => Some(error),
44            Self::Released | Self::AlreadyAdmitted => None,
45        }
46    }
47}
48
49/// The lifecycle phase at which an input batch may be admitted.
50#[derive(Clone, Copy, Debug, Eq, PartialEq)]
51pub enum InputTarget {
52    /// Extend the active turn at its next legal step boundary.
53    NextStep,
54    /// Open a distinct turn after the active turn ends.
55    NextTurn,
56}
57
58/// A requested input batch contained no transcript items.
59#[derive(Clone, Copy, Debug, Eq, PartialEq)]
60pub struct EmptyInputBatchError;
61
62impl fmt::Display for EmptyInputBatchError {
63    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
64        formatter.write_str("input batch must not be empty")
65    }
66}
67
68impl Error for EmptyInputBatchError {}
69
70/// One owned, ordered input batch with an immutable admission target.
71#[derive(Clone, Debug)]
72pub struct InputBatch {
73    target: InputTarget,
74    items: Vec<Item>,
75}
76
77impl InputBatch {
78    /// Freezes an owned non-empty batch for one admission target.
79    ///
80    /// # Errors
81    ///
82    /// [`EmptyInputBatchError`] if `items` is empty. An empty batch would occupy
83    /// a place in the mailbox's FIFO order and then open a Turn or Step boundary
84    /// with nothing to admit, so it is refused at construction rather than
85    /// discarded later, where the discard would be invisible to whoever queued it.
86    pub fn new(target: InputTarget, items: Vec<Item>) -> Result<Self, EmptyInputBatchError> {
87        if items.is_empty() {
88            return Err(EmptyInputBatchError);
89        }
90        Ok(Self { target, items })
91    }
92
93    /// Returns the frozen target.
94    #[must_use]
95    pub const fn target(&self) -> InputTarget {
96        self.target
97    }
98
99    /// Returns the ordered owned payload by immutable view.
100    #[must_use]
101    pub fn items(&self) -> &[Item] {
102        &self.items
103    }
104
105    /// Transfers the frozen target and owned payload together.
106    #[must_use]
107    pub fn into_parts(self) -> (InputTarget, Vec<Item>) {
108        (self.target, self.items)
109    }
110}
111
112/// Thread-safe FIFO input storage with target-selective atomic claims.
113///
114/// # Panics
115///
116/// Every method here propagates a poisoned queue lock rather than recovering it,
117/// per the crate-level [lock-poisoning contract](crate#lock-poisoning). Nothing a
118/// caller passes can cause that: the queue holds owned [`InputBatch`] values and
119/// no foreign code runs under the lock.
120#[derive(Clone, Default)]
121pub struct InputMailbox {
122    batches: Arc<Mutex<VecDeque<InputBatch>>>,
123}
124
125impl fmt::Debug for InputMailbox {
126    /// Reports the queue depth at one non-blocking observation.
127    ///
128    /// The mailbox is the session's only concurrent write entry point, so a
129    /// formatter that waited for the queue lock could stall the very producer
130    /// it is describing. On contention it says so rather than guessing.
131    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
132        let mut mailbox = formatter.debug_struct("InputMailbox");
133        match self.batches.try_lock() {
134            Ok(batches) => mailbox.field("batches", &batches.len()),
135            Err(_contended_or_poisoned) => mailbox.field("batches", &Locked),
136        }
137        .finish()
138    }
139}
140
141impl InputMailbox {
142    /// Creates an empty mailbox attached to no Session.
143    ///
144    /// This is for a composition layer assembling its own queue — a test double,
145    /// or a staging buffer drained into a real inbox later. It is **not** how you
146    /// reach a running Run: [`Session::input_mailbox`] returns a handle onto the
147    /// Session's own queue, and a mailbox built here shares nothing with it, so
148    /// pushing to one succeeds and is never claimed by anybody.
149    #[must_use]
150    pub fn new() -> Self {
151        Self::default()
152    }
153
154    /// Moves one already-frozen owned batch into global FIFO order.
155    ///
156    /// # Panics
157    ///
158    /// If the queue lock is poisoned, as
159    /// [the mailbox's panic conditions](InputMailbox#panics) describe.
160    pub fn push(&self, batch: InputBatch) {
161        self.batches
162            .lock()
163            .expect("injection mailbox lock poisoned")
164            .push_back(batch);
165    }
166
167    /// Atomically removes the oldest batch for `target` without reordering peers.
168    ///
169    /// # Panics
170    ///
171    /// If the queue lock is poisoned, as
172    /// [the mailbox's panic conditions](InputMailbox#panics) describe.
173    #[must_use]
174    pub fn claim(&self, target: InputTarget) -> Option<InputBatch> {
175        let mut batches = self
176            .batches
177            .lock()
178            .expect("injection mailbox lock poisoned");
179        let index = batches.iter().position(|batch| batch.target == target)?;
180        batches.remove(index)
181    }
182
183    /// Atomically removes every currently queued batch in FIFO order.
184    ///
185    /// # Panics
186    ///
187    /// If the queue lock is poisoned, as
188    /// [the mailbox's panic conditions](InputMailbox#panics) describe.
189    #[must_use]
190    pub fn drain(&self) -> Vec<InputBatch> {
191        std::mem::take(
192            &mut *self
193                .batches
194                .lock()
195                .expect("injection mailbox lock poisoned"),
196        )
197        .into()
198    }
199
200    /// Returns the number of queued batches at one lock linearization point.
201    ///
202    /// # Panics
203    ///
204    /// If the queue lock is poisoned, as
205    /// [the mailbox's panic conditions](InputMailbox#panics) describe.
206    #[must_use]
207    pub fn len(&self) -> usize {
208        self.batches
209            .lock()
210            .expect("injection mailbox lock poisoned")
211            .len()
212    }
213
214    /// Reports whether the mailbox is empty at one lock linearization point.
215    ///
216    /// # Panics
217    ///
218    /// If the queue lock is poisoned, as
219    /// [the mailbox's panic conditions](InputMailbox#panics) describe.
220    #[must_use]
221    pub fn is_empty(&self) -> bool {
222        self.len() == 0
223    }
224}
225
226struct LeaseToken {
227    _identity: u8,
228}
229
230struct ActiveLease {
231    token: Arc<LeaseToken>,
232    admitted: bool,
233}
234
235struct Control {
236    active: Option<ActiveLease>,
237}
238
239struct SessionInner {
240    id: String,
241    transcript: Store,
242    state: session_state::Store,
243    input_mailbox: InputMailbox,
244    /// The session's sole transcript-transaction authority.
245    ///
246    /// A live transcript mutation is a reserve-commit-publish transaction that
247    /// spans more than the store's own lock, so the session owns one outer lock
248    /// that every mutation path shares: the reservation controller, a direct
249    /// compare-and-set through [`Lease`], lease release, and successor
250    /// acquisition. Holding it session-wide rather than per controller instance
251    /// is what makes "no second mutation crosses an unresolved transaction"
252    /// true for callers the controller does not know about.
253    ///
254    /// Lock order is always this lock before [`SessionInner::control`], and no
255    /// path ever takes them in the other order.
256    transaction: Mutex<()>,
257    control: Mutex<Control>,
258    #[cfg(test)]
259    admit_before_control: Mutex<Option<Arc<TestOverlap>>>,
260    #[cfg(test)]
261    admit_with_control: Mutex<Option<Arc<TestOverlap>>>,
262    #[cfg(test)]
263    commit_overlap: Mutex<Option<Arc<TestOverlap>>>,
264    #[cfg(test)]
265    release_probe: Mutex<Option<Arc<TestOverlap>>>,
266    #[cfg(test)]
267    transaction_arrivals: Mutex<Option<mpsc::Sender<()>>>,
268}
269
270impl SessionInner {
271    /// Acquires the session's sole transcript-transaction authority.
272    ///
273    /// Every transcript mutation path funnels through here, so this is the one
274    /// place the session-wide transaction domain is entered. The lock is not
275    /// reentrant: a caller that already holds a transaction must reuse it rather
276    /// than open a second one.
277    ///
278    /// The controller resumes a reservation panic while its guard is still
279    /// alive, which poisons this lock. The lock guards no data of its own, and
280    /// such a transaction has already resolved every reservation it held and
281    /// either committed fully or not at all, so the poison is recovered instead
282    /// of propagated: a successor must still be able to mutate the transcript.
283    fn enter_transaction(&self) -> MutexGuard<'_, ()> {
284        #[cfg(test)]
285        probe_transaction_lock(self);
286        self.transaction
287            .lock()
288            .unwrap_or_else(|poisoned| poisoned.into_inner())
289    }
290
291    fn control(&self) -> MutexGuard<'_, Control> {
292        self.control.lock().expect("session control lock poisoned")
293    }
294}
295
296/// A long-lived conversation substrate with a single active lease.
297///
298/// # Panics
299///
300/// A session serializes lease admission and release behind one control lock, and
301/// every operation on a `Session` or its [`Lease`] that consults that lock
302/// propagates a poisoned one rather than recovering it, per the crate-level
303/// [lock-poisoning contract](crate#lock-poisoning). The lock guards only the
304/// active-lease slot, and no foreign code runs while it is held, so nothing a
305/// caller passes can poison it.
306///
307/// The session's separate transcript-transaction lock is the crate's one
308/// deliberate recovery, for the reason that contract records: a mutation is
309/// expected to unwind through it, and a successor must still be able to mutate
310/// the transcript afterwards.
311#[derive(Clone)]
312pub struct Session {
313    inner: Arc<SessionInner>,
314}
315
316impl fmt::Debug for Session {
317    /// Prints the session identity, which is what a session is addressed by.
318    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
319        formatter
320            .debug_struct("Session")
321            .field("id", &self.inner.id)
322            .finish()
323    }
324}
325
326impl Session {
327    /// Creates a session from an optional owned transcript snapshot.
328    ///
329    /// # The seed/live boundary lives with the caller
330    ///
331    /// `seed` is the replayed prefix, so this caller already holds both
332    /// coordinates the boundary can be named in: the prefix length, and the
333    /// [`Version`] the epoch resumes at. Both remain valid as live work
334    /// appends, and a composition layer that forks or resumes keeps whichever
335    /// its own persistence is keyed on.
336    ///
337    /// The transcript stores no such marker, because no core path treats a
338    /// replayed record differently from a live one: projection, the exchange
339    /// grammar and replay validity are all properties of the whole history.
340    /// Recording the boundary here would be storing a number core neither
341    /// produces nor consumes. Session trees, branching and branch replay are
342    /// composition-layer concerns built on top of these two coordinates.
343    #[must_use]
344    pub fn new(id: String, seed: Option<Snapshot>) -> Self {
345        let transcript = seed.map_or_else(Store::new, Store::restore);
346        Self {
347            inner: Arc::new(SessionInner {
348                id,
349                transcript,
350                state: session_state::Store::new(),
351                input_mailbox: InputMailbox::new(),
352                transaction: Mutex::new(()),
353                control: Mutex::new(Control { active: None }),
354                #[cfg(test)]
355                admit_before_control: Mutex::new(None),
356                #[cfg(test)]
357                admit_with_control: Mutex::new(None),
358                #[cfg(test)]
359                commit_overlap: Mutex::new(None),
360                #[cfg(test)]
361                release_probe: Mutex::new(None),
362                #[cfg(test)]
363                transaction_arrivals: Mutex::new(None),
364            }),
365        }
366    }
367
368    /// Returns this session's identity.
369    #[must_use]
370    pub fn id(&self) -> &str {
371        &self.inner.id
372    }
373
374    /// Returns read-only atomic transcript snapshot authority.
375    #[must_use]
376    pub fn transcript(&self) -> SnapshotReader {
377        self.inner.transcript.snapshot_reader()
378    }
379
380    /// Returns read-only owned session-state authority.
381    #[must_use]
382    pub fn state(&self) -> session_state::Reader {
383        self.inner.state.reader()
384    }
385
386    /// Returns the shared asynchronous input mailbox.
387    ///
388    /// **Shared, despite being returned by value.** [`InputMailbox`] is a
389    /// handle: this hands back another one onto *this* Session's queue, so
390    /// pushing to it reaches a Run that is already running, and two calls to
391    /// `input_mailbox` address the same queue.
392    ///
393    /// The queue belongs to the Session, not to its current Run or lease. Releasing
394    /// a lease does not drain unclaimed batches: a successor Run on this Session
395    /// may claim them at their next eligible boundary. Call [`InputMailbox::drain`]
396    /// explicitly before starting that successor when the composition layer wants
397    /// a Run-local queue instead.
398    ///
399    /// That matters because [`InputMailbox::new`] is also public, and a
400    /// mailbox built that way belongs to nobody. Pushing to it succeeds, returns
401    /// nothing, and is never claimed — the one way to inject input and observe
402    /// no error and no effect. If a batch you pushed never arrived, check that it
403    /// went through `session.input_mailbox()`.
404    #[must_use]
405    pub fn input_mailbox(&self) -> InputMailbox {
406        self.inner.input_mailbox.clone()
407    }
408
409    /// Atomically acquires the sole active lease, or returns `None` while busy.
410    ///
411    /// Acquisition waits for any in-flight transcript transaction to resolve, so
412    /// a successor can never observe a committed version whose reservations have
413    /// not yet published.
414    ///
415    /// # Panics
416    ///
417    /// If the session control lock is poisoned, as
418    /// [the session's panic conditions](Session#panics) describe.
419    #[must_use]
420    pub fn try_acquire(&self) -> Option<Lease> {
421        let _transaction = self.inner.enter_transaction();
422        let mut control = self.inner.control();
423        if control.active.is_some() {
424            return None;
425        }
426        let token = Arc::new(LeaseToken { _identity: 0 });
427        control.active = Some(ActiveLease {
428            token: Arc::clone(&token),
429            admitted: false,
430        });
431        Some(Lease {
432            inner: Arc::clone(&self.inner),
433            token,
434            state: self.inner.state.acquire(),
435        })
436    }
437}
438
439/// Exclusive, explicitly admitted mutation authority for one session use.
440pub struct Lease {
441    inner: Arc<SessionInner>,
442    token: Arc<LeaseToken>,
443    state: Writer,
444}
445
446impl fmt::Debug for Lease {
447    /// Prints the session this exclusive authority was taken over.
448    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
449        formatter
450            .debug_struct("Lease")
451            .field("session", &self.inner.id)
452            .finish()
453    }
454}
455
456impl Lease {
457    /// Atomically commits successful admission for this lease.
458    ///
459    /// This is a lifecycle barrier, not a dependency-continuity policy. A
460    /// composition-layer launcher that needs continuity must validate its own
461    /// metadata before calling [`Agent::start`](crate::runtime::agent::Agent::start);
462    /// it cannot share this Session's private control lock.
463    ///
464    /// # Errors
465    ///
466    /// - [`LeaseError::Released`] if this lease is no longer the session's active
467    ///   one, which includes a lease that was released and a session that has
468    ///   since admitted a successor.
469    /// - [`LeaseError::AlreadyAdmitted`] if this lease already committed
470    ///   admission. Admission remains once per lease rather than idempotent.
471    ///
472    /// A failure leaves the admitted flag unchanged.
473    ///
474    /// # Panics
475    ///
476    /// If the session control lock is poisoned, as
477    /// [the session's panic conditions](Session#panics) describe. Admission also
478    /// asserts that the lease it verified under that lock is still the active one
479    /// when it marks it admitted; both hold the same guard, so failing that
480    /// assertion would be a defect in this crate rather than a caller error.
481    pub fn admit(&self) -> Result<(), LeaseError> {
482        #[cfg(test)]
483        pause_at(&self.inner.admit_before_control);
484        let mut control = self.inner.control();
485        if active(&control, &self.token)?.admitted {
486            return Err(LeaseError::AlreadyAdmitted);
487        }
488        #[cfg(test)]
489        pause_at(&self.inner.admit_with_control);
490        control
491            .active
492            .as_mut()
493            .expect("active lease was verified under the same lock")
494            .admitted = true;
495        Ok(())
496    }
497
498    /// Reports whether this still-active lease has synchronously committed admission.
499    ///
500    /// # Panics
501    ///
502    /// If the session control lock is poisoned, as
503    /// [the session's panic conditions](Session#panics) describe.
504    #[must_use]
505    pub fn is_admitted(&self) -> bool {
506        let control = self.inner.control();
507        control
508            .active
509            .as_ref()
510            .is_some_and(|active| Arc::ptr_eq(&active.token, &self.token) && active.admitted)
511    }
512
513    /// Returns this lease's mutable session-state capability.
514    #[must_use]
515    pub const fn state(&self) -> &Writer {
516        &self.state
517    }
518
519    /// Atomically captures the transcript; reads remain valid after release.
520    ///
521    /// # Errors
522    ///
523    /// [`store::Error::Poisoned`] if a transcript writer panicked while holding
524    /// the store lock. Release is deliberately not a failure here: this is a
525    /// read, and the shared immutable snapshot stays usable after the authority
526    /// that captured it is gone.
527    pub fn transcript_snapshot(&self) -> Result<Snapshot, store::Error> {
528        self.inner.transcript.snapshot_reader().snapshot()
529    }
530
531    pub(crate) fn transcript_reader(&self) -> SnapshotReader {
532        self.inner.transcript.snapshot_reader()
533    }
534
535    pub(crate) fn fork_transcript(&self) -> Result<Store, store::Error> {
536        self.inner.transcript.fork()
537    }
538
539    /// Opens the session's sole transcript transaction.
540    ///
541    /// Every transcript mutation, including the reservation controller's
542    /// reserve-commit-publish sequence, runs inside one of these. The returned
543    /// guard is the only route to a compare-and-set, so no caller can commit
544    /// outside the transaction domain, and a second mutation - a direct
545    /// compare-and-set, a release, or a successor acquisition - blocks until this
546    /// transaction resolves.
547    ///
548    /// A reservation callback holds no lease, so it cannot re-enter this
549    /// non-reentrant transaction from inside one.
550    pub(crate) fn begin_transaction(&self) -> Transaction<'_> {
551        Transaction {
552            _transaction: self.inner.enter_transaction(),
553            lease: self,
554        }
555    }
556
557    /// Appends an owned batch only at `expected`, inside its own transaction.
558    ///
559    /// # Errors
560    ///
561    /// [`LeaseError::Released`] if this lease is no longer the session's active
562    /// one, checked before the transcript is touched, so a stale authority never
563    /// mutates history. Otherwise [`LeaseError::Transcript`] carrying whatever
564    /// the store reported: a
565    /// [`VersionConflict`](store::Error::VersionConflict) if another writer
566    /// advanced past `expected`, a
567    /// [`VersionOverflow`](store::Error::VersionOverflow), or a
568    /// [`Poisoned`](store::Error::Poisoned) store. Every one of those leaves the
569    /// history unchanged.
570    ///
571    /// # Panics
572    ///
573    /// If the session control lock is poisoned, as
574    /// [the session's panic conditions](Session#panics) describe. Transcript
575    /// poisoning is reported instead as
576    /// [`LeaseError::Transcript`]`(`[`store::Error::Poisoned`]`)`.
577    pub fn append_batch_if_version(
578        &self,
579        items: Vec<Item>,
580        expected: Version,
581    ) -> Result<Version, LeaseError> {
582        self.begin_transaction()
583            .append_batch_if_version(items, expected)
584    }
585
586    /// Replaces the transcript only at `expected`, inside its own transaction.
587    ///
588    /// # Errors
589    ///
590    /// [`LeaseError::Released`] if this lease is no longer the session's active
591    /// one, or [`LeaseError::Transcript`] carrying a
592    /// [`VersionConflict`](store::Error::VersionConflict),
593    /// [`VersionOverflow`](store::Error::VersionOverflow), or
594    /// [`Poisoned`](store::Error::Poisoned) store. A refused replacement swaps
595    /// nothing, which is what lets a compaction be attempted against a live
596    /// session at all.
597    ///
598    /// # Panics
599    ///
600    /// If the session control lock is poisoned, as
601    /// [the session's panic conditions](Session#panics) describe. Transcript
602    /// poisoning is reported instead as
603    /// [`LeaseError::Transcript`]`(`[`store::Error::Poisoned`]`)`.
604    pub fn replace_if_version(
605        &self,
606        items: Vec<Item>,
607        expected: Version,
608    ) -> Result<Version, LeaseError> {
609        self.begin_transaction().replace_if_version(items, expected)
610    }
611
612    /// Idempotently revokes mutations and makes the session reusable.
613    ///
614    /// Release waits for any in-flight transcript transaction to resolve, so a
615    /// committed mutation always finishes publishing while its authority is
616    /// still live.
617    ///
618    /// # Panics
619    ///
620    /// If the session control lock is poisoned, as
621    /// [the session's panic conditions](Session#panics) describe. Because
622    /// [`Drop`] releases, a poisoned control lock also panics while a `Lease`
623    /// goes out of scope.
624    pub fn release(&self) {
625        let _transaction = self.inner.enter_transaction();
626        self.release_in_transaction();
627    }
628
629    fn release_in_transaction(&self) {
630        #[cfg(test)]
631        probe_control_lock(&self.inner);
632        let mut control = self.inner.control();
633        let owns = control
634            .active
635            .as_ref()
636            .is_some_and(|active| Arc::ptr_eq(&active.token, &self.token));
637        if owns {
638            self.state.release();
639            control.active = None;
640        }
641    }
642}
643
644impl Drop for Lease {
645    fn drop(&mut self) {
646        self.release();
647    }
648}
649
650/// The session's exclusive live transcript-mutation window.
651///
652/// Holding this guard is the sole way to reach a compare-and-set, so the
653/// reservation controller can reserve, commit, and publish without any other
654/// mutation path crossing the sequence. The lock order is always this guard
655/// before the session control lock.
656pub(crate) struct Transaction<'a> {
657    _transaction: MutexGuard<'a, ()>,
658    lease: &'a Lease,
659}
660
661impl Transaction<'_> {
662    /// Reads the live transcript version without materializing the history.
663    ///
664    /// Liveness is verified first, so a released lease cannot observe a version
665    /// it may no longer mutate. The value cannot go stale while this transaction
666    /// is held.
667    pub(crate) fn version(&self) -> Result<Version, LeaseError> {
668        let control = self.lease.inner.control();
669        active(&control, &self.lease.token)?;
670        self.lease
671            .inner
672            .transcript
673            .snapshot_reader()
674            .version()
675            .map_err(LeaseError::Transcript)
676    }
677
678    /// Captures live transcript truth while this transaction excludes mutations.
679    pub(crate) fn snapshot(&self) -> Result<Snapshot, LeaseError> {
680        let control = self.lease.inner.control();
681        active(&control, &self.lease.token)?;
682        self.lease
683            .inner
684            .transcript
685            .snapshot_reader()
686            .snapshot()
687            .map_err(LeaseError::Transcript)
688    }
689
690    /// Appends an owned batch only at `expected`.
691    pub(crate) fn append_batch_if_version(
692        &self,
693        items: Vec<Item>,
694        expected: Version,
695    ) -> Result<Version, LeaseError> {
696        self.commit(|| {
697            self.lease
698                .inner
699                .transcript
700                .appender()
701                .append_batch_if_version(items, expected)
702        })
703    }
704
705    /// Replaces the transcript only at `expected`.
706    pub(crate) fn replace_if_version(
707        &self,
708        items: Vec<Item>,
709        expected: Version,
710    ) -> Result<Version, LeaseError> {
711        self.commit(|| {
712            self.lease
713                .inner
714                .transcript
715                .replacer()
716                .replace_if_version(items, expected)
717        })
718    }
719
720    /// Installs an already-shared replacement only at `expected`.
721    pub(crate) fn install_snapshot(
722        &self,
723        snapshot: Snapshot,
724        expected: Version,
725    ) -> Result<Version, LeaseError> {
726        self.commit(|| {
727            self.lease
728                .inner
729                .transcript
730                .replacer()
731                .install_snapshot_if_version(snapshot, expected)
732        })
733    }
734
735    fn commit<T>(
736        &self,
737        operation: impl FnOnce() -> Result<T, store::Error>,
738    ) -> Result<T, LeaseError> {
739        let control = self.lease.inner.control();
740        active(&control, &self.lease.token)?;
741        #[cfg(test)]
742        pause_at(&self.lease.inner.commit_overlap);
743        operation().map_err(LeaseError::Transcript)
744    }
745}
746
747fn active<'a>(
748    control: &'a Control,
749    token: &Arc<LeaseToken>,
750) -> Result<&'a ActiveLease, LeaseError> {
751    control
752        .active
753        .as_ref()
754        .filter(|active| Arc::ptr_eq(&active.token, token))
755        .ok_or(LeaseError::Released)
756}
757
758#[cfg(test)]
759struct TestOverlap {
760    reached: Barrier,
761    proceed: Barrier,
762}
763
764/// Holds the mailbox lock so a `Debug` must observe contention.
765#[cfg(test)]
766pub(super) fn hold_mailbox_lock(mailbox: &InputMailbox, held: &Barrier, release: &Barrier) {
767    let _guard = mailbox
768        .batches
769        .lock()
770        .expect("injection mailbox lock poisoned");
771    held.wait();
772    release.wait();
773}
774
775#[cfg(test)]
776pub(super) struct TestOverlapControl {
777    overlap: Arc<TestOverlap>,
778    inner: Arc<SessionInner>,
779}
780
781#[cfg(test)]
782impl TestOverlapControl {
783    pub(super) fn wait_until_reached(&self) {
784        self.overlap.reached.wait();
785    }
786
787    pub(super) fn assert_control_is_locked(&self) {
788        assert!(matches!(
789            self.inner.control.try_lock(),
790            Err(TryLockError::WouldBlock)
791        ));
792    }
793
794    pub(super) fn proceed(&self) {
795        self.overlap.proceed.wait();
796    }
797}
798
799#[cfg(test)]
800fn pause_at(slot: &Mutex<Option<Arc<TestOverlap>>>) {
801    let overlap = slot.lock().expect("test overlap lock poisoned").take();
802    if let Some(overlap) = overlap {
803        overlap.reached.wait();
804        overlap.proceed.wait();
805    }
806}
807
808#[cfg(test)]
809fn probe_control_lock(inner: &SessionInner) {
810    let overlap = inner
811        .release_probe
812        .lock()
813        .expect("release probe lock poisoned")
814        .take();
815    if let Some(overlap) = overlap {
816        assert!(matches!(
817            inner.control.try_lock(),
818            Err(TryLockError::WouldBlock)
819        ));
820        overlap.reached.wait();
821        overlap.proceed.wait();
822    }
823}
824
825/// Signals one thread's arrival at an already-held transaction lock.
826///
827/// The probe runs before the arriving thread blocks, and it first proves the
828/// lock is held. A test that observes the signal therefore knows the arriving
829/// mutation cannot make progress until the transaction holder resolves, which is
830/// what makes "this path cannot cross an unresolved transaction" a deterministic
831/// assertion instead of a timing race.
832#[cfg(test)]
833fn probe_transaction_lock(inner: &SessionInner) {
834    let arrival = inner
835        .transaction_arrivals
836        .lock()
837        .expect("transaction arrival lock poisoned")
838        .take();
839    if let Some(arrival) = arrival {
840        assert!(matches!(
841            inner.transaction.try_lock(),
842            Err(TryLockError::WouldBlock)
843        ));
844        arrival
845            .send(())
846            .expect("the installing test observes the arrival");
847    }
848}
849
850/// Observes arrivals at an already-held transaction lock.
851///
852/// The signal is one-shot per [`Self::arm`], so a test can walk several distinct
853/// mutation paths into the same held transaction without a later, unblocked
854/// transaction tripping the probe.
855#[cfg(test)]
856pub(crate) struct TransactionArrival {
857    inner: Arc<SessionInner>,
858    sender: mpsc::Sender<()>,
859    arrived: mpsc::Receiver<()>,
860}
861
862#[cfg(test)]
863impl TransactionArrival {
864    /// Arms the signal for the next single thread to enter a transaction.
865    pub(crate) fn arm(&self) {
866        *self
867            .inner
868            .transaction_arrivals
869            .lock()
870            .expect("transaction arrival lock poisoned") = Some(self.sender.clone());
871    }
872
873    /// Blocks until one armed thread has reached the held transaction lock.
874    pub(crate) fn wait_until_blocked(&self) {
875        self.arrived
876            .recv()
877            .expect("the arriving thread signals before it blocks");
878    }
879}
880
881/// Creates an unarmed arrival probe for one session's transaction lock.
882#[cfg(test)]
883pub(crate) fn install_transaction_arrival(session: &Session) -> TransactionArrival {
884    let (sender, arrived) = mpsc::channel();
885    TransactionArrival {
886        inner: Arc::clone(&session.inner),
887        sender,
888        arrived,
889    }
890}
891
892#[cfg(test)]
893fn install_overlap(
894    session: &Session,
895    slot: &Mutex<Option<Arc<TestOverlap>>>,
896) -> TestOverlapControl {
897    let overlap = Arc::new(TestOverlap {
898        reached: Barrier::new(2),
899        proceed: Barrier::new(2),
900    });
901    *slot.lock().expect("test overlap lock poisoned") = Some(Arc::clone(&overlap));
902    TestOverlapControl {
903        overlap,
904        inner: Arc::clone(&session.inner),
905    }
906}
907
908#[cfg(test)]
909pub(super) fn install_admit_before_control(session: &Session) -> TestOverlapControl {
910    install_overlap(session, &session.inner.admit_before_control)
911}
912
913#[cfg(test)]
914pub(super) fn install_admit_with_control(session: &Session) -> TestOverlapControl {
915    install_overlap(session, &session.inner.admit_with_control)
916}
917
918#[cfg(test)]
919pub(super) fn install_commit_overlap(session: &Session) -> TestOverlapControl {
920    install_overlap(session, &session.inner.commit_overlap)
921}
922
923#[cfg(test)]
924pub(super) fn install_release_probe(session: &Session) -> TestOverlapControl {
925    install_overlap(session, &session.inner.release_probe)
926}