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}