Skip to main content

reef_core/transcript/
store.rs

1//! In-memory transcript truth source with capability-narrowed handles.
2//!
3//! Mutation semantics are stated as version arithmetic: batch
4//! append advances by its length, replacement advances by one, compare-and-swap
5//! checks and commits share one write critical section, and restore continues a
6//! saved version epoch.
7
8use std::error;
9use std::fmt;
10use std::sync::{Arc, RwLock};
11#[cfg(test)]
12use std::sync::{Barrier, Mutex, TryLockError};
13
14use super::item::Item;
15use crate::redact::Locked;
16
17/// A monotonic transcript revision within one store epoch.
18///
19/// `Version` never wraps. A write which cannot be represented returns
20/// [`Error::VersionOverflow`] without changing the store.
21///
22/// ```
23/// use reef_core::transcript::store;
24/// assert!(store::Version::from_u64(2) > store::Version::from_u64(1));
25/// assert_eq!(store::Version::ZERO.as_u64(), 0);
26/// ```
27#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
28pub struct Version(u64);
29
30impl Version {
31    /// The first version in a fresh epoch.
32    pub const ZERO: Self = Self(0);
33
34    /// The greatest representable transcript version.
35    pub const MAX: Self = Self(u64::MAX);
36
37    /// Creates a version from its persisted integer representation.
38    #[must_use]
39    pub const fn from_u64(value: u64) -> Self {
40        Self(value)
41    }
42
43    /// Returns the persisted integer representation.
44    #[must_use]
45    pub const fn as_u64(self) -> u64 {
46        self.0
47    }
48
49    fn checked_add(self, delta: u64) -> Option<Self> {
50        self.0.checked_add(delta).map(Self)
51    }
52}
53
54impl fmt::Display for Version {
55    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
56        self.0.fmt(formatter)
57    }
58}
59
60/// One atomic, immutable transcript state.
61///
62/// Cloning a snapshot is O(1): unchanged readers share the same immutable item
63/// backing. [`Store::restore`] adopts that backing and continues exactly at its
64/// saved version; [`Store::from_items`] instead starts a new version-zero epoch.
65#[derive(Clone, Debug)]
66pub struct Snapshot {
67    version: Version,
68    items: Arc<Vec<Item>>,
69}
70
71impl Snapshot {
72    /// Creates a versioned snapshot by adopting an owned item history.
73    #[must_use]
74    pub fn new(version: Version, items: Vec<Item>) -> Self {
75        Self::from_shared(version, Arc::new(items))
76    }
77
78    const fn from_shared(version: Version, items: Arc<Vec<Item>>) -> Self {
79        Self { version, items }
80    }
81
82    pub(crate) fn with_version(self, version: Version) -> Self {
83        Self {
84            version,
85            items: self.items,
86        }
87    }
88
89    /// Returns the atomically captured version.
90    #[must_use]
91    pub const fn version(&self) -> Version {
92        self.version
93    }
94
95    /// Returns the captured ordered items.
96    #[must_use]
97    pub fn items(&self) -> &[Item] {
98        self.items.as_slice()
99    }
100
101    /// Transfers ownership of the version and ordered items.
102    ///
103    /// If another snapshot or store still shares the item backing, this method
104    /// clones the items to produce the requested unique vector.
105    #[must_use]
106    pub fn into_parts(self) -> (Version, Vec<Item>) {
107        let items = Arc::try_unwrap(self.items).unwrap_or_else(|items| items.as_ref().clone());
108        (self.version, items)
109    }
110
111    #[cfg(test)]
112    pub(crate) fn shares_items_with(&self, other: &Self) -> bool {
113        Arc::ptr_eq(&self.items, &other.items)
114    }
115
116    #[cfg(test)]
117    pub(crate) fn items_backing_ptr(&self) -> *const Vec<Item> {
118        Arc::as_ptr(&self.items)
119    }
120}
121
122/// A typed transcript store failure.
123#[derive(Clone, Copy, Debug, Eq, PartialEq)]
124#[non_exhaustive]
125pub enum Error {
126    /// The store changed after the caller observed `expected`.
127    #[non_exhaustive]
128    VersionConflict {
129        /// The stale version supplied by the caller.
130        expected: Version,
131        /// The version observed while holding the commit lock.
132        actual: Version,
133    },
134    /// A successful mutation would exceed [`Version::MAX`].
135    #[non_exhaustive]
136    VersionOverflow {
137        /// The current version.
138        current: Version,
139        /// The requested increment.
140        delta: u64,
141    },
142    /// A panic occurred while a writer held the lock.
143    ///
144    /// Reef fails closed rather than exposing potentially inconsistent state.
145    Poisoned,
146}
147
148impl fmt::Display for Error {
149    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
150        match self {
151            Self::VersionConflict { expected, actual } => write!(
152                formatter,
153                "transcript version conflict: expected {expected}, actual {actual}"
154            ),
155            Self::VersionOverflow { current, delta } => write!(
156                formatter,
157                "transcript version overflow: current {current}, increment {delta}"
158            ),
159            Self::Poisoned => formatter.write_str("transcript store lock poisoned"),
160        }
161    }
162}
163
164impl error::Error for Error {}
165
166struct State {
167    version: Version,
168    items: Arc<Vec<Item>>,
169    staged_tail: Option<Vec<Item>>,
170}
171
172impl State {
173    fn has_staged_items(&self) -> bool {
174        self.staged_tail
175            .as_ref()
176            .is_some_and(|tail| !tail.is_empty())
177    }
178
179    fn materialize_staged_items(&mut self) {
180        let Some(mut tail) = self.staged_tail.take() else {
181            return;
182        };
183        if tail.is_empty() {
184            self.staged_tail = Some(tail);
185            return;
186        }
187        Arc::make_mut(&mut self.items).append(&mut tail);
188        self.staged_tail = Some(Vec::new());
189    }
190
191    fn snapshot(&self) -> Snapshot {
192        debug_assert!(!self.has_staged_items());
193        Snapshot::from_shared(self.version, Arc::clone(&self.items))
194    }
195
196    fn into_snapshot(mut self) -> Snapshot {
197        self.materialize_staged_items();
198        Snapshot::from_shared(self.version, self.items)
199    }
200
201    fn into_snapshot_with_suffix(mut self, mut suffix: Vec<Item>) -> Snapshot {
202        if let Some(tail) = &mut self.staged_tail {
203            tail.append(&mut suffix);
204        } else {
205            Arc::make_mut(&mut self.items).append(&mut suffix);
206        }
207        self.into_snapshot()
208    }
209}
210
211struct Core {
212    state: RwLock<State>,
213    #[cfg(test)]
214    commit_overlap: Mutex<Option<Arc<CommitOverlap>>>,
215}
216
217#[cfg(test)]
218struct CommitOverlap {
219    writer_ready: Barrier,
220    reader_contending: Barrier,
221    commit_release: Barrier,
222}
223
224#[cfg(test)]
225impl CommitOverlap {
226    fn new() -> Self {
227        Self {
228            writer_ready: Barrier::new(2),
229            reader_contending: Barrier::new(3),
230            commit_release: Barrier::new(2),
231        }
232    }
233}
234
235#[cfg(test)]
236pub(super) struct CommitOverlapControl {
237    overlap: Arc<CommitOverlap>,
238}
239
240#[cfg(test)]
241impl CommitOverlapControl {
242    pub(super) fn wait_for_writer(&self) {
243        self.overlap.writer_ready.wait();
244    }
245
246    pub(super) fn wait_for_reader(&self) {
247        self.overlap.reader_contending.wait();
248    }
249
250    pub(super) fn release_writer(&self) {
251        self.overlap.commit_release.wait();
252    }
253}
254
255impl Core {
256    /// Renders one capability handle by the transcript version behind it.
257    ///
258    /// The five handles differ in authority, not in state, so the version is
259    /// the fact worth printing and the only one they can all reach. The read is
260    /// non-blocking: a handle is routinely formatted from inside code that
261    /// already holds the lock, and a `Debug` that waited there would deadlock.
262    fn debug_handle(&self, name: &str, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
263        let mut handle = formatter.debug_struct(name);
264        match self.state.try_read() {
265            Ok(state) => handle.field("version", &state.version),
266            Err(_contended_or_poisoned) => handle.field("version", &Locked),
267        }
268        .finish()
269    }
270
271    #[cfg(test)]
272    fn test_before_read(&self) {
273        let overlap = self
274            .commit_overlap
275            .lock()
276            .expect("test overlap lock must be healthy")
277            .clone();
278        if let Some(overlap) = overlap {
279            // The writer holds the production write lock before it reaches this
280            // seam, so a mechanical try_read must fail fast with WouldBlock.
281            // This proves the reader below genuinely contends with a live
282            // writer rather than merely waiting on the test barrier.
283            assert!(
284                matches!(self.state.try_read(), Err(TryLockError::WouldBlock)),
285                "overlap seam requires the production write lock to be held"
286            );
287            overlap.reader_contending.wait();
288        }
289    }
290
291    #[cfg(test)]
292    fn test_before_commit(&self) {
293        let overlap = self
294            .commit_overlap
295            .lock()
296            .expect("test overlap lock must be healthy")
297            .clone();
298        if let Some(overlap) = overlap {
299            // At this point the candidate and next version are complete while
300            // the production write lock is still held. Do not permit the
301            // single state mutation until a reader has entered its lock path.
302            overlap.writer_ready.wait();
303            overlap.reader_contending.wait();
304            overlap.commit_release.wait();
305            *self
306                .commit_overlap
307                .lock()
308                .expect("test overlap lock must be healthy") = None;
309        }
310    }
311
312    fn items(&self) -> Result<Vec<Item>, Error> {
313        self.snapshot().map(|snapshot| snapshot.into_parts().1)
314    }
315
316    fn snapshot(&self) -> Result<Snapshot, Error> {
317        #[cfg(test)]
318        self.test_before_read();
319        {
320            let state = self.state.read().map_err(|_| Error::Poisoned)?;
321            if !state.has_staged_items() {
322                return Ok(state.snapshot());
323            }
324        }
325
326        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
327        state.materialize_staged_items();
328        Ok(state.snapshot())
329    }
330
331    fn version(&self) -> Result<Version, Error> {
332        #[cfg(test)]
333        self.test_before_read();
334        let state = self.state.read().map_err(|_| Error::Poisoned)?;
335        Ok(state.version)
336    }
337
338    fn append_batch(
339        &self,
340        mut candidate: Vec<Item>,
341        expected: Option<Version>,
342    ) -> Result<Version, Error> {
343        // Rust's supported targets have pointer widths no greater than 64 bits,
344        // so every possible Vec length is representable as u64.
345        let delta = candidate.len() as u64;
346        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
347        if let Some(expected) = expected {
348            if state.version != expected {
349                return Err(Error::VersionConflict {
350                    expected,
351                    actual: state.version,
352                });
353            }
354        }
355        let next = state
356            .version
357            .checked_add(delta)
358            .ok_or(Error::VersionOverflow {
359                current: state.version,
360                delta,
361            })?;
362        #[cfg(test)]
363        self.test_before_commit();
364        if let Some(tail) = &mut state.staged_tail {
365            tail.append(&mut candidate);
366        } else {
367            Arc::make_mut(&mut state.items).append(&mut candidate);
368        }
369        state.version = next;
370        Ok(next)
371    }
372
373    fn replace(&self, candidate: Vec<Item>, expected: Option<Version>) -> Result<Version, Error> {
374        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
375        if let Some(expected) = expected {
376            if state.version != expected {
377                return Err(Error::VersionConflict {
378                    expected,
379                    actual: state.version,
380                });
381            }
382        }
383        let next = state.version.checked_add(1).ok_or(Error::VersionOverflow {
384            current: state.version,
385            delta: 1,
386        })?;
387        #[cfg(test)]
388        self.test_before_commit();
389        state.items = Arc::new(candidate);
390        if let Some(tail) = &mut state.staged_tail {
391            tail.clear();
392        }
393        state.version = next;
394        Ok(next)
395    }
396
397    fn replace_snapshot(&self, candidate: Snapshot, expected: Version) -> Result<Version, Error> {
398        // `Snapshot::version` is supplied by crate-owned transaction assembly.
399        // Make a producer bug equally loud in debug and release without poisoning
400        // the store lock; `Version::MAX` remains the typed overflow path below.
401        if let Some(next) = expected.checked_add(1) {
402            assert_eq!(
403                candidate.version(),
404                next,
405                "snapshot installed at a live boundary must carry that boundary's successor version"
406            );
407        }
408        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
409        if state.version != expected {
410            return Err(Error::VersionConflict {
411                expected,
412                actual: state.version,
413            });
414        }
415        let next = state.version.checked_add(1).ok_or(Error::VersionOverflow {
416            current: state.version,
417            delta: 1,
418        })?;
419        #[cfg(test)]
420        self.test_before_commit();
421        state.items = candidate.items;
422        if let Some(tail) = &mut state.staged_tail {
423            tail.clear();
424        }
425        state.version = next;
426        Ok(next)
427    }
428}
429
430/// Owns one transcript and issues independent minimal-permission capabilities.
431///
432/// `Store` itself has no read or mutation methods. Give consumers only the
433/// handle they require; none of the handles can recover or mint another facet.
434///
435/// ```
436/// use reef_core::transcript::store;
437/// let store = store::Store::new();
438/// let reader = store.reader();
439/// assert!(reader.items().unwrap().is_empty());
440/// ```
441#[derive(Clone)]
442pub struct Store {
443    core: Arc<Core>,
444}
445
446impl fmt::Debug for Store {
447    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
448        self.core.debug_handle("Store", formatter)
449    }
450}
451
452impl Store {
453    /// Creates an empty version-zero transcript.
454    #[must_use]
455    pub fn new() -> Self {
456        Self::from_items(Vec::new())
457    }
458
459    /// Creates a new version-zero epoch owning `items`.
460    #[must_use]
461    pub fn from_items(items: Vec<Item>) -> Self {
462        Self::from_state(Version::ZERO, items)
463    }
464
465    /// Restores an owned snapshot and continues its exact saved version.
466    ///
467    /// The closed [`Item`] enum makes every `Snapshot` structurally valid, so
468    /// restore is infallible. Subsequent conflicting or overflowing writes use
469    /// [`Error`] rather than resetting or wrapping the saved version.
470    #[must_use]
471    pub fn restore(snapshot: Snapshot) -> Self {
472        let Snapshot { version, items } = snapshot;
473        Self::from_shared_state(version, items, None)
474    }
475
476    pub(crate) fn fork(&self) -> Result<Self, Error> {
477        let snapshot = self.core.snapshot()?;
478        Ok(Self::from_shared_state(
479            snapshot.version,
480            snapshot.items,
481            Some(Vec::new()),
482        ))
483    }
484
485    pub(crate) fn version(&self) -> Result<Version, Error> {
486        self.core.version()
487    }
488
489    pub(crate) fn into_snapshot(self) -> Result<Snapshot, Error> {
490        match Arc::try_unwrap(self.core) {
491            Ok(core) => core
492                .state
493                .into_inner()
494                .map(State::into_snapshot)
495                .map_err(|_| Error::Poisoned),
496            Err(core) => core.snapshot(),
497        }
498    }
499
500    pub(crate) fn into_snapshot_with_suffix(self, suffix: Vec<Item>) -> Result<Snapshot, Error> {
501        match Arc::try_unwrap(self.core) {
502            Ok(core) => core
503                .state
504                .into_inner()
505                .map(|state| state.into_snapshot_with_suffix(suffix))
506                .map_err(|_| Error::Poisoned),
507            Err(core) => {
508                let mut snapshot = core.snapshot()?;
509                Arc::make_mut(&mut snapshot.items).extend(suffix);
510                Ok(snapshot)
511            }
512        }
513    }
514
515    #[cfg(test)]
516    pub(crate) fn into_items(self) -> Result<Vec<Item>, Error> {
517        self.into_snapshot().map(|snapshot| snapshot.into_parts().1)
518    }
519
520    fn from_state(version: Version, items: Vec<Item>) -> Self {
521        Self::from_shared_state(version, Arc::new(items), None)
522    }
523
524    fn from_shared_state(
525        version: Version,
526        items: Arc<Vec<Item>>,
527        staged_tail: Option<Vec<Item>>,
528    ) -> Self {
529        Self {
530            core: Arc::new(Core {
531                state: RwLock::new(State {
532                    version,
533                    items,
534                    staged_tail,
535                }),
536                #[cfg(test)]
537                commit_overlap: Mutex::new(None),
538            }),
539        }
540    }
541
542    /// Issues an owned-items read capability.
543    #[must_use]
544    pub fn reader(&self) -> Reader {
545        Reader {
546            core: Arc::clone(&self.core),
547        }
548    }
549
550    /// Issues an atomic versioned-snapshot capability.
551    #[must_use]
552    pub fn snapshot_reader(&self) -> SnapshotReader {
553        SnapshotReader {
554            core: Arc::clone(&self.core),
555        }
556    }
557
558    /// Issues append-only authority.
559    #[must_use]
560    pub fn appender(&self) -> Appender {
561        Appender {
562            core: Arc::clone(&self.core),
563        }
564    }
565
566    /// Issues whole-history replacement authority.
567    #[must_use]
568    pub fn replacer(&self) -> Replacer {
569        Replacer {
570            core: Arc::clone(&self.core),
571        }
572    }
573}
574
575impl Default for Store {
576    fn default() -> Self {
577        Self::new()
578    }
579}
580
581/// Read-only access returning an owned item history.
582///
583/// This handle intentionally has no method that returns [`Store`], [`Appender`],
584/// or [`Replacer`].
585///
586/// ```compile_fail
587/// use reef_core::transcript::{item, store};
588/// let reader = store::Store::new().reader();
589/// reader.append(item::Item::System(item::System::new(
590///     String::new(), String::new(), item::ModelVisibility::Visible,
591/// )));
592/// ```
593#[derive(Clone)]
594pub struct Reader {
595    core: Arc<Core>,
596}
597
598impl fmt::Debug for Reader {
599    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
600        self.core.debug_handle("Reader", formatter)
601    }
602}
603
604impl Reader {
605    /// Returns an owned copy of the complete ordered history.
606    ///
607    /// # Errors
608    ///
609    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
610    /// Reading is otherwise infallible: the history is already a closed [`Item`]
611    /// sequence, so there is nothing here to validate.
612    pub fn items(&self) -> Result<Vec<Item>, Error> {
613        self.core.items()
614    }
615}
616
617/// Atomic version-and-items snapshot access without mutation authority.
618///
619/// ```compile_fail
620/// use reef_core::transcript::store;
621/// let snapshots = store::Store::new().snapshot_reader();
622/// snapshots.replace(Vec::new());
623/// ```
624#[derive(Clone)]
625pub struct SnapshotReader {
626    core: Arc<Core>,
627}
628
629impl fmt::Debug for SnapshotReader {
630    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
631        self.core.debug_handle("SnapshotReader", formatter)
632    }
633}
634
635impl SnapshotReader {
636    /// Atomically captures a shared immutable history and its version.
637    ///
638    /// # Errors
639    ///
640    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
641    /// There is no partial capture: a snapshot either observes one version
642    /// together with the items that belong to it, or reports the poison.
643    pub fn snapshot(&self) -> Result<Snapshot, Error> {
644        self.core.snapshot()
645    }
646
647    /// Returns the current version without cloning item history.
648    ///
649    /// # Errors
650    ///
651    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
652    pub fn version(&self) -> Result<Version, Error> {
653        self.core.version()
654    }
655}
656
657/// Append-only transcript authority.
658///
659/// Every method consumes an owned candidate before taking the commit lock. No
660/// user clone or callback runs while the write lock is held; after all checks,
661/// the ordered batch and version become visible in one critical section.
662///
663/// ```compile_fail
664/// use reef_core::transcript::store;
665/// let append = store::Store::new().appender();
666/// append.replace(Vec::new());
667/// ```
668#[derive(Clone)]
669pub struct Appender {
670    core: Arc<Core>,
671}
672
673impl fmt::Debug for Appender {
674    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
675        self.core.debug_handle("Appender", formatter)
676    }
677}
678
679impl Appender {
680    /// Appends one owned item and advances the version by one.
681    ///
682    /// # Errors
683    ///
684    /// [`Error::VersionOverflow`] if the store already stands at
685    /// [`Version::MAX`], and [`Error::Poisoned`] if a writer panicked while
686    /// holding the store lock. Either way the history is unchanged. There is no
687    /// conflict to report, because this append accepts whatever version it finds.
688    pub fn append(&self, item: Item) -> Result<Version, Error> {
689        self.core.append_batch(vec![item], None)
690    }
691
692    /// Atomically appends an owned ordered batch.
693    ///
694    /// The version advances by `items.len()`. An empty batch is a successful
695    /// no-op which still reports lock poisoning.
696    ///
697    /// # Errors
698    ///
699    /// [`Error::VersionOverflow`], reporting the current version and the
700    /// requested increment, if advancing by `items.len()` would pass
701    /// [`Version::MAX`]; and [`Error::Poisoned`] if a writer panicked while
702    /// holding the store lock. A failure appends none of the batch — this is the
703    /// atomicity the whole crate's "never write half of an exchange" rule rests
704    /// on, so a rejected batch leaves no partial history behind.
705    pub fn append_batch(&self, items: Vec<Item>) -> Result<Version, Error> {
706        self.core.append_batch(items, None)
707    }
708
709    /// Atomically appends a batch only at `expected`.
710    ///
711    /// Even an empty batch checks `expected`; conflicts and overflow leave both
712    /// history and version unchanged.
713    ///
714    /// # Errors
715    ///
716    /// - [`Error::VersionConflict`], reporting both `expected` and the version
717    ///   actually observed under the commit lock, if another writer advanced the
718    ///   store after the caller read `expected`. The concurrent winner is never
719    ///   overwritten; the loser is expected to re-read and decide again.
720    /// - [`Error::VersionOverflow`] if the batch would advance past
721    ///   [`Version::MAX`]. The conflict check runs first, so a stale caller hears
722    ///   about staleness rather than about a limit it may not be near.
723    /// - [`Error::Poisoned`] if a writer panicked while holding the store lock.
724    pub fn append_batch_if_version(
725        &self,
726        items: Vec<Item>,
727        expected: Version,
728    ) -> Result<Version, Error> {
729        self.core.append_batch(items, Some(expected))
730    }
731}
732
733/// Whole-history replacement authority without append authority.
734///
735/// Candidates are fully owned before locking. A successful replacement swaps
736/// the complete vector and advances the version once.
737///
738/// ```compile_fail
739/// use reef_core::transcript::store;
740/// let replace = store::Store::new().replacer();
741/// replace.append_batch(Vec::new());
742/// ```
743#[derive(Clone)]
744pub struct Replacer {
745    core: Arc<Core>,
746}
747
748impl fmt::Debug for Replacer {
749    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
750        self.core.debug_handle("Replacer", formatter)
751    }
752}
753
754impl Replacer {
755    /// Atomically replaces all items and advances the version by one.
756    ///
757    /// # Errors
758    ///
759    /// [`Error::VersionOverflow`] if the store already stands at
760    /// [`Version::MAX`], and [`Error::Poisoned`] if a writer panicked while
761    /// holding the store lock. A failed replacement swaps nothing: the previous
762    /// history is still the whole history.
763    pub fn replace(&self, items: Vec<Item>) -> Result<Version, Error> {
764        self.core.replace(items, None)
765    }
766
767    /// Atomically replaces all items only when the live version is `expected`.
768    ///
769    /// A conflict returns the expected and actual versions without overwriting
770    /// the concurrent winner.
771    ///
772    /// # Errors
773    ///
774    /// - [`Error::VersionConflict`], reporting both `expected` and the version
775    ///   observed under the commit lock, if another writer advanced the store
776    ///   after the caller read `expected`. This is the check that makes a
777    ///   compaction safe to attempt concurrently: the candidate is discarded
778    ///   rather than overwriting work the caller never saw.
779    /// - [`Error::VersionOverflow`] if the store already stands at
780    ///   [`Version::MAX`]. The conflict check runs first.
781    /// - [`Error::Poisoned`] if a writer panicked while holding the store lock.
782    pub fn replace_if_version(
783        &self,
784        items: Vec<Item>,
785        expected: Version,
786    ) -> Result<Version, Error> {
787        self.core.replace(items, Some(expected))
788    }
789
790    pub(crate) fn install_snapshot_if_version(
791        &self,
792        snapshot: Snapshot,
793        expected: Version,
794    ) -> Result<Version, Error> {
795        self.core.replace_snapshot(snapshot, expected)
796    }
797}
798
799#[cfg(test)]
800pub(super) fn install_commit_overlap(store: &Store) -> CommitOverlapControl {
801    let overlap = Arc::new(CommitOverlap::new());
802    *store
803        .core
804        .commit_overlap
805        .lock()
806        .expect("test overlap lock must be healthy") = Some(Arc::clone(&overlap));
807    CommitOverlapControl { overlap }
808}
809
810/// Holds the production write lock so a `Debug` must observe contention.
811///
812/// ADR-018 forbids a formatter from waiting on a lock, and the only way to
813/// prove it does not is to format one that is genuinely held.
814#[cfg(test)]
815pub(super) fn hold_write_lock(store: &Store, held: &Barrier, release: &Barrier) {
816    let _guard = store.core.state.write().expect("test lock starts healthy");
817    held.wait();
818    release.wait();
819}
820
821#[cfg(test)]
822pub(crate) fn poison(store: &Store) {
823    let _guard = store.core.state.write().expect("test lock starts healthy");
824    panic!("intentional transcript-store poison");
825}
826
827/// The serialized form of [`Version`] and [`Snapshot`] (ADR-019 D5).
828///
829/// A version is a bare integer — its own documentation already calls that "the
830/// persisted integer representation" — and a snapshot is `version` then `items`.
831///
832/// `Snapshot::version` is not a schema version and core emits none. It counts the
833/// history's revisions, not the encoding's; a version belongs to a document, and
834/// core serializes values, so the layer that writes a file owns its envelope.
835#[cfg(feature = "serde")]
836mod serde_impl {
837    use std::fmt::{self, Formatter};
838
839    use serde_core::de::{
840        Deserialize, Deserializer, Error as DeError, MapAccess, SeqAccess, Visitor,
841    };
842    use serde_core::ser::{Serialize, SerializeStruct, Serializer};
843
844    use super::{Snapshot, Version};
845    use crate::wire::{self, IdentifierSeed};
846
847    const SNAPSHOT_FIELDS: &[&str] = &["version", "items"];
848
849    impl Serialize for Version {
850        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
851        where
852            S: Serializer,
853        {
854            serializer.serialize_u64(self.0)
855        }
856    }
857
858    impl<'de> Deserialize<'de> for Version {
859        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
860        where
861            D: Deserializer<'de>,
862        {
863            u64::deserialize(deserializer).map(Self::from_u64)
864        }
865    }
866
867    impl Serialize for Snapshot {
868        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
869        where
870            S: Serializer,
871        {
872            let mut record = serializer.serialize_struct("Snapshot", 2)?;
873            record.serialize_field("version", &self.version)?;
874            record.serialize_field("items", self.items())?;
875            record.end()
876        }
877    }
878
879    impl<'de> Deserialize<'de> for Snapshot {
880        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
881        where
882            D: Deserializer<'de>,
883        {
884            deserializer.deserialize_struct("Snapshot", SNAPSHOT_FIELDS, SnapshotVisitor)
885        }
886    }
887
888    struct SnapshotVisitor;
889
890    impl<'de> Visitor<'de> for SnapshotVisitor {
891        type Value = Snapshot;
892
893        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
894            formatter.write_str("a transcript snapshot")
895        }
896
897        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
898        where
899            A: SeqAccess<'de>,
900        {
901            let version = wire::element(&mut sequence, 0)?;
902            let items = wire::element(&mut sequence, 1)?;
903            wire::end(&mut sequence, 2)?;
904            Ok(Snapshot::new(version, items))
905        }
906
907        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
908        where
909            A: MapAccess<'de>,
910        {
911            let mut version = None;
912            let mut items = None;
913            while let Some(field) = entries.next_key_seed(IdentifierSeed(SNAPSHOT_FIELDS))? {
914                match field.0.as_str() {
915                    "version" => wire::accept(&mut version, entries.next_value()?, "version")?,
916                    "items" => wire::accept(&mut items, entries.next_value()?, "items")?,
917                    unknown => return Err(A::Error::unknown_field(unknown, SNAPSHOT_FIELDS)),
918                }
919            }
920            Ok(Snapshot::new(
921                wire::require(version, "version")?,
922                wire::require(items, "items")?,
923            ))
924        }
925    }
926}