docs: partition persist visibility invariants
Document the invariants (and non-invariants) of
Partition.persisted_sequence_number.
@@ -842,6 +842,17 @@ pub struct Partition {
/// The inclusive maximum [`SequenceNumber`] of the most recently persisted
/// data for this partition.
+ ///
+ /// All writes with a [`SequenceNumber`] less than and equal to this
+ /// [`SequenceNumber`] have been persisted to the object store. The inverse
+ /// is not guaranteed to be true due to update ordering; some files for this
+ /// partition may exist in the `parquet_files` table that have a greater
+ /// [`SequenceNumber`] than is specified here - the system will converge so
+ /// long as the ingester progresses.
+ ///
+ /// It is a system invariant that this value monotonically increases over
+ /// time - wrote another way, it is an invariant that partitions are
+ /// persisted (or at least made visible) in sequence order.
pub persisted_sequence_number: SequenceNumber,
}
