Index repair and fallback
A missing index is not a missing message
If an offset is below the committed end but its generation-0 index is absent, the logical record is already part of the committed stream. The resolver treats this as derived-state loss, not as a negative read result.
Repair starts at the current head anchor or a published recovery checkpoint, pages through reachable commits, verifies range and commit-version continuity, validates the exact target identity, and rebuilds the generation-0 index/replay marker within a bounded budget.
If the budget expires, the result is a retryable resolution failure. “Not found in this page” is never converted into KNOWN_NOT_COMMITTED or EOF.
Candidate fallback
When a higher generation is missing, corrupt, or temporarily unavailable:
- classify the physical error;
- release the failed candidate's reader pin;
- quarantine the exact generation/root when evidence is permanent;
- fresh-resolve candidates in the same read view;
- choose a lower healthy generation that still covers the requested range.
Fallback cannot cross COMMITTED and TOPIC_COMPACTED, use a retired/deleted target, ignore a checksum/identity failure, or bypass a mandatory Kafka compacted-generation coverage contract.
Cache rules
Positive offset-index results may be cached and invalidated by metadata watch/version changes, TTL, physical failure, or failed pin revalidation. The cache does not own generation truth. A negative “no candidate” result is not kept indefinitely because head advancement or index repair can make the candidate appear later.
Fresh resolve after physical failure
A stale target can hide a newly published generation. After a classified physical target failure, the read path clears the stream's offset-index cache and resolves without cache. If the candidate set is unchanged, it returns the same error or enters the permitted fallback/quarantine path.