Read targets and offset indexes
ReadTarget
A ReadTarget is the provider-neutral description of how to read a logical range. It carries the stream range, physical identity, generation/view information, and the boundary mode needed by the reader.
The core can therefore ask a dispatcher for a reader without knowing whether the bytes live in BookKeeper, an Object WAL, or a higher read-optimized generation.
Offset index
The offset index is a derived directory from logical ranges to physical targets. It accelerates reads but is not the authority for whether a range is committed. If it is missing or stale, the implementation can rebuild or repair it from the committed stream state and exact physical metadata.
Boundary modes
EXACT_STARTrequires a physical entry that starts at the requested logical boundary.CONTAINING_ENTRYpermits a ranged physical entry to contain the requested offset, then decodes the requested subrange.
The second mode is important for Kafka RecordBatch ranges. It does not permit a reader to return data outside the requested logical and protocol limits.
Fresh resolve after physical failure
A cached target can become invalid after generation publication, provider failure, or GC race. The safe response is to establish a fresh metadata snapshot and resolve again. Reusing a failed physical target indefinitely would turn a repairable projection into a false logical outage.