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, owned transcript state.
61///
62/// Snapshots own a `Vec<Item>` disjoint from both the live store and every later
63/// snapshot. [`Store::restore`] consumes this state 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: Vec<Item>,
69}
70
71impl Snapshot {
72    /// Creates a versioned owned state for persistence restore.
73    #[must_use]
74    pub const fn new(version: Version, items: Vec<Item>) -> Self {
75        Self { version, items }
76    }
77
78    /// Returns the atomically captured version.
79    #[must_use]
80    pub const fn version(&self) -> Version {
81        self.version
82    }
83
84    /// Returns the captured ordered items.
85    #[must_use]
86    pub fn items(&self) -> &[Item] {
87        &self.items
88    }
89
90    /// Transfers ownership of the version and ordered items.
91    #[must_use]
92    pub fn into_parts(self) -> (Version, Vec<Item>) {
93        (self.version, self.items)
94    }
95}
96
97/// A typed transcript store failure.
98#[derive(Clone, Copy, Debug, Eq, PartialEq)]
99#[non_exhaustive]
100pub enum Error {
101    /// The store changed after the caller observed `expected`.
102    #[non_exhaustive]
103    VersionConflict {
104        /// The stale version supplied by the caller.
105        expected: Version,
106        /// The version observed while holding the commit lock.
107        actual: Version,
108    },
109    /// A successful mutation would exceed [`Version::MAX`].
110    #[non_exhaustive]
111    VersionOverflow {
112        /// The current version.
113        current: Version,
114        /// The requested increment.
115        delta: u64,
116    },
117    /// A panic occurred while a writer held the lock.
118    ///
119    /// Reef fails closed rather than exposing potentially inconsistent state.
120    Poisoned,
121}
122
123impl fmt::Display for Error {
124    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
125        match self {
126            Self::VersionConflict { expected, actual } => write!(
127                formatter,
128                "transcript version conflict: expected {expected}, actual {actual}"
129            ),
130            Self::VersionOverflow { current, delta } => write!(
131                formatter,
132                "transcript version overflow: current {current}, increment {delta}"
133            ),
134            Self::Poisoned => formatter.write_str("transcript store lock poisoned"),
135        }
136    }
137}
138
139impl error::Error for Error {}
140
141struct State {
142    version: Version,
143    items: Vec<Item>,
144}
145
146struct Core {
147    state: RwLock<State>,
148    #[cfg(test)]
149    commit_overlap: Mutex<Option<Arc<CommitOverlap>>>,
150}
151
152#[cfg(test)]
153struct CommitOverlap {
154    writer_ready: Barrier,
155    reader_contending: Barrier,
156    commit_release: Barrier,
157}
158
159#[cfg(test)]
160impl CommitOverlap {
161    fn new() -> Self {
162        Self {
163            writer_ready: Barrier::new(2),
164            reader_contending: Barrier::new(3),
165            commit_release: Barrier::new(2),
166        }
167    }
168}
169
170#[cfg(test)]
171pub(super) struct CommitOverlapControl {
172    overlap: Arc<CommitOverlap>,
173}
174
175#[cfg(test)]
176impl CommitOverlapControl {
177    pub(super) fn wait_for_writer(&self) {
178        self.overlap.writer_ready.wait();
179    }
180
181    pub(super) fn wait_for_reader(&self) {
182        self.overlap.reader_contending.wait();
183    }
184
185    pub(super) fn release_writer(&self) {
186        self.overlap.commit_release.wait();
187    }
188}
189
190impl Core {
191    /// Renders one capability handle by the transcript version behind it.
192    ///
193    /// The five handles differ in authority, not in state, so the version is
194    /// the fact worth printing and the only one they can all reach. The read is
195    /// non-blocking: a handle is routinely formatted from inside code that
196    /// already holds the lock, and a `Debug` that waited there would deadlock.
197    fn debug_handle(&self, name: &str, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
198        let mut handle = formatter.debug_struct(name);
199        match self.state.try_read() {
200            Ok(state) => handle.field("version", &state.version),
201            Err(_contended_or_poisoned) => handle.field("version", &Locked),
202        }
203        .finish()
204    }
205
206    #[cfg(test)]
207    fn test_before_read(&self) {
208        let overlap = self
209            .commit_overlap
210            .lock()
211            .expect("test overlap lock must be healthy")
212            .clone();
213        if let Some(overlap) = overlap {
214            // The writer holds the production write lock before it reaches this
215            // seam, so a mechanical try_read must fail fast with WouldBlock.
216            // This proves the reader below genuinely contends with a live
217            // writer rather than merely waiting on the test barrier.
218            assert!(
219                matches!(self.state.try_read(), Err(TryLockError::WouldBlock)),
220                "overlap seam requires the production write lock to be held"
221            );
222            overlap.reader_contending.wait();
223        }
224    }
225
226    #[cfg(test)]
227    fn test_before_commit(&self) {
228        let overlap = self
229            .commit_overlap
230            .lock()
231            .expect("test overlap lock must be healthy")
232            .clone();
233        if let Some(overlap) = overlap {
234            // At this point the candidate and next version are complete while
235            // the production write lock is still held. Do not permit the
236            // single state mutation until a reader has entered its lock path.
237            overlap.writer_ready.wait();
238            overlap.reader_contending.wait();
239            overlap.commit_release.wait();
240            *self
241                .commit_overlap
242                .lock()
243                .expect("test overlap lock must be healthy") = None;
244        }
245    }
246
247    fn items(&self) -> Result<Vec<Item>, Error> {
248        #[cfg(test)]
249        self.test_before_read();
250        let state = self.state.read().map_err(|_| Error::Poisoned)?;
251        Ok(state.items.clone())
252    }
253
254    fn snapshot(&self) -> Result<Snapshot, Error> {
255        #[cfg(test)]
256        self.test_before_read();
257        let state = self.state.read().map_err(|_| Error::Poisoned)?;
258        Ok(Snapshot::new(state.version, state.items.clone()))
259    }
260
261    fn version(&self) -> Result<Version, Error> {
262        #[cfg(test)]
263        self.test_before_read();
264        let state = self.state.read().map_err(|_| Error::Poisoned)?;
265        Ok(state.version)
266    }
267
268    fn append_batch(
269        &self,
270        mut candidate: Vec<Item>,
271        expected: Option<Version>,
272    ) -> Result<Version, Error> {
273        // Rust's supported targets have pointer widths no greater than 64 bits,
274        // so every possible Vec length is representable as u64.
275        let delta = candidate.len() as u64;
276        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
277        if let Some(expected) = expected {
278            if state.version != expected {
279                return Err(Error::VersionConflict {
280                    expected,
281                    actual: state.version,
282                });
283            }
284        }
285        let next = state
286            .version
287            .checked_add(delta)
288            .ok_or(Error::VersionOverflow {
289                current: state.version,
290                delta,
291            })?;
292        #[cfg(test)]
293        self.test_before_commit();
294        state.items.append(&mut candidate);
295        state.version = next;
296        Ok(next)
297    }
298
299    fn replace(&self, candidate: Vec<Item>, expected: Option<Version>) -> Result<Version, Error> {
300        let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
301        if let Some(expected) = expected {
302            if state.version != expected {
303                return Err(Error::VersionConflict {
304                    expected,
305                    actual: state.version,
306                });
307            }
308        }
309        let next = state.version.checked_add(1).ok_or(Error::VersionOverflow {
310            current: state.version,
311            delta: 1,
312        })?;
313        #[cfg(test)]
314        self.test_before_commit();
315        state.items = candidate;
316        state.version = next;
317        Ok(next)
318    }
319}
320
321/// Owns one transcript and issues independent minimal-permission capabilities.
322///
323/// `Store` itself has no read or mutation methods. Give consumers only the
324/// handle they require; none of the handles can recover or mint another facet.
325///
326/// ```
327/// use reef_core::transcript::store;
328/// let store = store::Store::new();
329/// let reader = store.reader();
330/// assert!(reader.items().unwrap().is_empty());
331/// ```
332#[derive(Clone)]
333pub struct Store {
334    core: Arc<Core>,
335}
336
337impl fmt::Debug for Store {
338    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
339        self.core.debug_handle("Store", formatter)
340    }
341}
342
343impl Store {
344    /// Creates an empty version-zero transcript.
345    #[must_use]
346    pub fn new() -> Self {
347        Self::from_items(Vec::new())
348    }
349
350    /// Creates a new version-zero epoch owning `items`.
351    #[must_use]
352    pub fn from_items(items: Vec<Item>) -> Self {
353        Self::from_state(Version::ZERO, items)
354    }
355
356    /// Restores an owned snapshot and continues its exact saved version.
357    ///
358    /// The closed [`Item`] enum makes every `Snapshot` structurally valid, so
359    /// restore is infallible. Subsequent conflicting or overflowing writes use
360    /// [`Error`] rather than resetting or wrapping the saved version.
361    #[must_use]
362    pub fn restore(snapshot: Snapshot) -> Self {
363        let (version, items) = snapshot.into_parts();
364        Self::from_state(version, items)
365    }
366
367    fn from_state(version: Version, items: Vec<Item>) -> Self {
368        Self {
369            core: Arc::new(Core {
370                state: RwLock::new(State { version, items }),
371                #[cfg(test)]
372                commit_overlap: Mutex::new(None),
373            }),
374        }
375    }
376
377    /// Issues an owned-items read capability.
378    #[must_use]
379    pub fn reader(&self) -> Reader {
380        Reader {
381            core: Arc::clone(&self.core),
382        }
383    }
384
385    /// Issues an atomic versioned-snapshot capability.
386    #[must_use]
387    pub fn snapshot_reader(&self) -> SnapshotReader {
388        SnapshotReader {
389            core: Arc::clone(&self.core),
390        }
391    }
392
393    /// Issues append-only authority.
394    #[must_use]
395    pub fn appender(&self) -> Appender {
396        Appender {
397            core: Arc::clone(&self.core),
398        }
399    }
400
401    /// Issues whole-history replacement authority.
402    #[must_use]
403    pub fn replacer(&self) -> Replacer {
404        Replacer {
405            core: Arc::clone(&self.core),
406        }
407    }
408}
409
410impl Default for Store {
411    fn default() -> Self {
412        Self::new()
413    }
414}
415
416/// Read-only access returning an owned item history.
417///
418/// This handle intentionally has no method that returns [`Store`], [`Appender`],
419/// or [`Replacer`].
420///
421/// ```compile_fail
422/// use reef_core::transcript::{item, store};
423/// let reader = store::Store::new().reader();
424/// reader.append(item::Item::System(item::System::new(
425///     String::new(), String::new(), item::ModelVisibility::Visible,
426/// )));
427/// ```
428#[derive(Clone)]
429pub struct Reader {
430    core: Arc<Core>,
431}
432
433impl fmt::Debug for Reader {
434    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
435        self.core.debug_handle("Reader", formatter)
436    }
437}
438
439impl Reader {
440    /// Returns an owned copy of the complete ordered history.
441    ///
442    /// # Errors
443    ///
444    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
445    /// Reading is otherwise infallible: the history is already a closed [`Item`]
446    /// sequence, so there is nothing here to validate.
447    pub fn items(&self) -> Result<Vec<Item>, Error> {
448        self.core.items()
449    }
450}
451
452/// Atomic version-and-items snapshot access without mutation authority.
453///
454/// ```compile_fail
455/// use reef_core::transcript::store;
456/// let snapshots = store::Store::new().snapshot_reader();
457/// snapshots.replace(Vec::new());
458/// ```
459#[derive(Clone)]
460pub struct SnapshotReader {
461    core: Arc<Core>,
462}
463
464impl fmt::Debug for SnapshotReader {
465    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
466        self.core.debug_handle("SnapshotReader", formatter)
467    }
468}
469
470impl SnapshotReader {
471    /// Atomically captures a disjoint owned history and its version.
472    ///
473    /// # Errors
474    ///
475    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
476    /// There is no partial capture: a snapshot either observes one version
477    /// together with the items that belong to it, or reports the poison.
478    pub fn snapshot(&self) -> Result<Snapshot, Error> {
479        self.core.snapshot()
480    }
481
482    /// Returns the current version without cloning item history.
483    ///
484    /// # Errors
485    ///
486    /// [`Error::Poisoned`] if a writer panicked while holding the store lock.
487    pub fn version(&self) -> Result<Version, Error> {
488        self.core.version()
489    }
490}
491
492/// Append-only transcript authority.
493///
494/// Every method consumes an owned candidate before taking the commit lock. No
495/// user clone or callback runs while the write lock is held; after all checks,
496/// the ordered batch and version become visible in one critical section.
497///
498/// ```compile_fail
499/// use reef_core::transcript::store;
500/// let append = store::Store::new().appender();
501/// append.replace(Vec::new());
502/// ```
503#[derive(Clone)]
504pub struct Appender {
505    core: Arc<Core>,
506}
507
508impl fmt::Debug for Appender {
509    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
510        self.core.debug_handle("Appender", formatter)
511    }
512}
513
514impl Appender {
515    /// Appends one owned item and advances the version by one.
516    ///
517    /// # Errors
518    ///
519    /// [`Error::VersionOverflow`] if the store already stands at
520    /// [`Version::MAX`], and [`Error::Poisoned`] if a writer panicked while
521    /// holding the store lock. Either way the history is unchanged. There is no
522    /// conflict to report, because this append accepts whatever version it finds.
523    pub fn append(&self, item: Item) -> Result<Version, Error> {
524        self.core.append_batch(vec![item], None)
525    }
526
527    /// Atomically appends an owned ordered batch.
528    ///
529    /// The version advances by `items.len()`. An empty batch is a successful
530    /// no-op which still reports lock poisoning.
531    ///
532    /// # Errors
533    ///
534    /// [`Error::VersionOverflow`], reporting the current version and the
535    /// requested increment, if advancing by `items.len()` would pass
536    /// [`Version::MAX`]; and [`Error::Poisoned`] if a writer panicked while
537    /// holding the store lock. A failure appends none of the batch — this is the
538    /// atomicity the whole crate's "never write half of an exchange" rule rests
539    /// on, so a rejected batch leaves no partial history behind.
540    pub fn append_batch(&self, items: Vec<Item>) -> Result<Version, Error> {
541        self.core.append_batch(items, None)
542    }
543
544    /// Atomically appends a batch only at `expected`.
545    ///
546    /// Even an empty batch checks `expected`; conflicts and overflow leave both
547    /// history and version unchanged.
548    ///
549    /// # Errors
550    ///
551    /// - [`Error::VersionConflict`], reporting both `expected` and the version
552    ///   actually observed under the commit lock, if another writer advanced the
553    ///   store after the caller read `expected`. The concurrent winner is never
554    ///   overwritten; the loser is expected to re-read and decide again.
555    /// - [`Error::VersionOverflow`] if the batch would advance past
556    ///   [`Version::MAX`]. The conflict check runs first, so a stale caller hears
557    ///   about staleness rather than about a limit it may not be near.
558    /// - [`Error::Poisoned`] if a writer panicked while holding the store lock.
559    pub fn append_batch_if_version(
560        &self,
561        items: Vec<Item>,
562        expected: Version,
563    ) -> Result<Version, Error> {
564        self.core.append_batch(items, Some(expected))
565    }
566}
567
568/// Whole-history replacement authority without append authority.
569///
570/// Candidates are fully owned before locking. A successful replacement swaps
571/// the complete vector and advances the version once.
572///
573/// ```compile_fail
574/// use reef_core::transcript::store;
575/// let replace = store::Store::new().replacer();
576/// replace.append_batch(Vec::new());
577/// ```
578#[derive(Clone)]
579pub struct Replacer {
580    core: Arc<Core>,
581}
582
583impl fmt::Debug for Replacer {
584    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
585        self.core.debug_handle("Replacer", formatter)
586    }
587}
588
589impl Replacer {
590    /// Atomically replaces all items and advances the version by one.
591    ///
592    /// # Errors
593    ///
594    /// [`Error::VersionOverflow`] if the store already stands at
595    /// [`Version::MAX`], and [`Error::Poisoned`] if a writer panicked while
596    /// holding the store lock. A failed replacement swaps nothing: the previous
597    /// history is still the whole history.
598    pub fn replace(&self, items: Vec<Item>) -> Result<Version, Error> {
599        self.core.replace(items, None)
600    }
601
602    /// Atomically replaces all items only when the live version is `expected`.
603    ///
604    /// A conflict returns the expected and actual versions without overwriting
605    /// the concurrent winner.
606    ///
607    /// # Errors
608    ///
609    /// - [`Error::VersionConflict`], reporting both `expected` and the version
610    ///   observed under the commit lock, if another writer advanced the store
611    ///   after the caller read `expected`. This is the check that makes a
612    ///   compaction safe to attempt concurrently: the candidate is discarded
613    ///   rather than overwriting work the caller never saw.
614    /// - [`Error::VersionOverflow`] if the store already stands at
615    ///   [`Version::MAX`]. The conflict check runs first.
616    /// - [`Error::Poisoned`] if a writer panicked while holding the store lock.
617    pub fn replace_if_version(
618        &self,
619        items: Vec<Item>,
620        expected: Version,
621    ) -> Result<Version, Error> {
622        self.core.replace(items, Some(expected))
623    }
624}
625
626#[cfg(test)]
627pub(super) fn install_commit_overlap(store: &Store) -> CommitOverlapControl {
628    let overlap = Arc::new(CommitOverlap::new());
629    *store
630        .core
631        .commit_overlap
632        .lock()
633        .expect("test overlap lock must be healthy") = Some(Arc::clone(&overlap));
634    CommitOverlapControl { overlap }
635}
636
637/// Holds the production write lock so a `Debug` must observe contention.
638///
639/// ADR-018 forbids a formatter from waiting on a lock, and the only way to
640/// prove it does not is to format one that is genuinely held.
641#[cfg(test)]
642pub(super) fn hold_write_lock(store: &Store, held: &Barrier, release: &Barrier) {
643    let _guard = store.core.state.write().expect("test lock starts healthy");
644    held.wait();
645    release.wait();
646}
647
648#[cfg(test)]
649pub(crate) fn poison(store: &Store) {
650    let _guard = store.core.state.write().expect("test lock starts healthy");
651    panic!("intentional transcript-store poison");
652}
653
654/// The serialized form of [`Version`] and [`Snapshot`] (ADR-019 D5).
655///
656/// A version is a bare integer — its own documentation already calls that "the
657/// persisted integer representation" — and a snapshot is `version` then `items`.
658///
659/// `Snapshot::version` is not a schema version and core emits none. It counts the
660/// history's revisions, not the encoding's; a version belongs to a document, and
661/// core serializes values, so the layer that writes a file owns its envelope.
662#[cfg(feature = "serde")]
663mod serde_impl {
664    use std::fmt::{self, Formatter};
665
666    use serde_core::de::{
667        Deserialize, Deserializer, Error as DeError, MapAccess, SeqAccess, Visitor,
668    };
669    use serde_core::ser::{Serialize, SerializeStruct, Serializer};
670
671    use super::{Snapshot, Version};
672    use crate::wire::{self, IdentifierSeed};
673
674    const SNAPSHOT_FIELDS: &[&str] = &["version", "items"];
675
676    impl Serialize for Version {
677        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
678        where
679            S: Serializer,
680        {
681            serializer.serialize_u64(self.0)
682        }
683    }
684
685    impl<'de> Deserialize<'de> for Version {
686        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
687        where
688            D: Deserializer<'de>,
689        {
690            u64::deserialize(deserializer).map(Self::from_u64)
691        }
692    }
693
694    impl Serialize for Snapshot {
695        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
696        where
697            S: Serializer,
698        {
699            let mut record = serializer.serialize_struct("Snapshot", 2)?;
700            record.serialize_field("version", &self.version)?;
701            record.serialize_field("items", &self.items)?;
702            record.end()
703        }
704    }
705
706    impl<'de> Deserialize<'de> for Snapshot {
707        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
708        where
709            D: Deserializer<'de>,
710        {
711            deserializer.deserialize_struct("Snapshot", SNAPSHOT_FIELDS, SnapshotVisitor)
712        }
713    }
714
715    struct SnapshotVisitor;
716
717    impl<'de> Visitor<'de> for SnapshotVisitor {
718        type Value = Snapshot;
719
720        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
721            formatter.write_str("a transcript snapshot")
722        }
723
724        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
725        where
726            A: SeqAccess<'de>,
727        {
728            let version = wire::element(&mut sequence, 0)?;
729            let items = wire::element(&mut sequence, 1)?;
730            Ok(Snapshot::new(version, items))
731        }
732
733        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
734        where
735            A: MapAccess<'de>,
736        {
737            let mut version = None;
738            let mut items = None;
739            while let Some(field) = entries.next_key_seed(IdentifierSeed(SNAPSHOT_FIELDS))? {
740                match field.0.as_str() {
741                    "version" => wire::accept(&mut version, entries.next_value()?, "version")?,
742                    "items" => wire::accept(&mut items, entries.next_value()?, "items")?,
743                    unknown => return Err(A::Error::unknown_field(unknown, SNAPSHOT_FIELDS)),
744                }
745            }
746            Ok(Snapshot::new(
747                wire::require(version, "version")?,
748                wire::require(items, "items")?,
749            ))
750        }
751    }
752}