Enum StreamOutcome 

pub enum StreamOutcome {
    Empty {
        watermark: Watermark,
        rpo: RpoStatus,
    },
    Streamed {
        generation_key: String,
        first_frame: u64,
        last_frame: u64,
        checkpoint_seq: u32,
        frame_count: u64,
        backpressure: BackpressureReport,
        rpo: RpoStatus,
    },
    Restarted {
        generation_key: String,
        previous_generation: WalGeneration,
        new_generation: WalGeneration,
        first_frame: u64,
        last_frame: u64,
        frame_count: u64,
        backpressure: BackpressureReport,
        rpo: RpoStatus,
    },
    Shed {
        checkpoint_seq: u32,
        first_frame: u64,
        last_frame: u64,
        backpressure: BackpressureReport,
        rpo: RpoStatus,
    },
    Fenced {
        current_epoch: u64,
        our_epoch: u64,
        current_pointer_generation: u64,
        our_pointer_generation: u64,
    },
}

What a tail_frames call did.

Variants

Empty

No new frames since the last tail — sink is already current.

Fields

watermark: Watermark

rpo: RpoStatus

R574-T4: staleness of the last durably-persisted watermark — still meaningful here, since “nothing new to stream” and “the caller’s scheduler stopped invoking us” look identical from the engine’s side and only this field tells them apart.

Streamed

Uploaded a contiguous range of frames and wrote a generation manifest.

Fields

generation_key: String

first_frame: u64

last_frame: u64

checkpoint_seq: u32

frame_count: u64

backpressure: BackpressureReport

R574-F2: backpressure activity during this call (policy, high-water spill-buffer occupancy, shed count, throttle retries).

rpo: RpoStatus

R574-T4: see StreamOutcome::Empty::rpo.

Restarted

The live WAL is not provably the one the sidecar watermark was taken from, so this call re-uploaded frames 1..N from the top rather than resuming.

R858-B19 widened this from “checkpoint_seq advanced” to “the WalGeneration did not prove itself unchanged”, which is why both fields are now generations rather than bare sequence numbers: the motivating case is a writer restart where the sequence reads 0 -> 0 and only the salt moved. previous_generation.salt == None names the third case — a sidecar written before the salt existed, restarted because it cannot be checked, not because it was seen to change.

Fields

generation_key: String

previous_generation: WalGeneration

new_generation: WalGeneration

first_frame: u64

last_frame: u64

frame_count: u64

backpressure: BackpressureReport

R574-F2: see StreamOutcome::Streamed::backpressure.

rpo: RpoStatus

R574-T4: see StreamOutcome::Empty::rpo.

Shed

R574-F2: BackpressurePolicy::Shed dropped every buffered frame in this call before any of them persisted (R2 was throttling harder than the spill buffer + backoff could absorb). No manifest/watermark was written — the next tail_frames call re-attempts the same range from the unchanged prior watermark. Distinct from Empty, which means the engine itself had nothing new.

Fields

checkpoint_seq: u32

first_frame: u64

last_frame: u64

backpressure: BackpressureReport

rpo: RpoStatus

R574-T4: see StreamOutcome::Empty::rpo.

Fenced

R732-F2 (W245) / R736-T2 (W250): this writer is a stale owner and wrote nothing. Either the sink’s watermark is stamped with an epoch higher than StreamConfig::epoch (ownership moved within the cell), or with a pointer generation higher than StreamConfig::pointer_generation (ownership moved to a different cell) — the two-level fence bounces on either. Detected before the first frame upload, so a fenced call is a pure read — no frames, no manifest, no watermark write.

This is the outcome the whole fencing design exists to produce. Without it a partitioned old master and a freshly-promoted new master both stream into the same prefix and silently corrupt each other; with it the loser finds out on its very next tail and can stop.

Deliberately carries no RpoStatus: a fenced writer’s view of watermark staleness is not its stream’s RPO any more, and reporting one here would page the wrong operator about the wrong node.

Fields

current_epoch: u64

The epoch recorded at the sink — the real owner’s token.

our_epoch: u64

The (lower) epoch this writer tried to stream under.

current_pointer_generation: u64

R736-T2: the pointer generation recorded at the sink.

our_pointer_generation: u64

R736-T2: the (lower) generation this writer tried to stream under.

Implementations

impl StreamOutcome

pub fn rpo(&self) -> Option<&RpoStatus>

This call’s RPO snapshot, or None for StreamOutcome::Fenced — see that variant’s doc for why it deliberately carries none.

R782: the accessor a caller (tenant-streamer’s tail loop) uses to push watermark_age onward without re-deriving this match on every call site that needs it.

pub fn backpressure(&self) -> Option<&BackpressureReport>

This call’s backpressure activity, or None for the two outcomes that never reached the drain loop (StreamOutcome::Empty had nothing to send, StreamOutcome::Fenced was refused before the first frame).

R760-B8: the accessor a multi-tenant caller needs. Streamed is not the same thing as “the sink took everything” — under BackpressurePolicy::Shed a call that persisted a partial prefix and dropped the rest reports Streamed with a nonzero BackpressureReport::frames_shed, and a caller that only matches the variant cannot tell that apart from a clean tail. roadcase’s shard flusher reads this on every arm so a struggling cell is nameable from its own metrics rather than by bisecting tenants.

Trait Implementations

impl Clone for StreamOutcome

fn clone(&self) -> StreamOutcome

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StreamOutcome

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for StreamOutcome

impl PartialEq for StreamOutcome

fn eq(&self, other: &StreamOutcome) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for StreamOutcome