RFC: epoch-scoped destination-byte coverage completion (peer-death mid-transfer → mixed-version dst)
- Dominant language
- C++
- Stars
- 132
- Forks
- 32
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 173
Description
**RFC / design proposal — no implementation is attached to this issue.** Filing to solicit maintainer feedback on the intended semantics before any code.
## Problem (open)
Native transfer completion is **counter-based** (per-UUID chunk count), not per-`(epoch, variable)` **byte coverage**. If a peer dies mid-transfer, a *partial* epoch can reach H2D, producing a **mixed-version policy** at the destination (some variables new, some old) while the transfer reports success. This is orthogonal to the D2H event-completion issue (silent rank-1 byte-drop) filed separately.
## Proposed design (specification only)
- **`coverage_complete(uuid, epoch_id)`** keyed on **destination-byte coverage per variable**, not chunk count.
- **H2D fires only at full byte coverage** for the epoch → state transitions to `PUBLISHED`.
- **Any failure** (peer death / EOF-before-coverage / deadline / truncated stream) → **`FAILED`**: **no partial H2D**; the destination stays **OLD-COMPLETE** (the previous fully-published version); the caller receives a **terminal error**. (Parking in `FAILED` while returning success, or hanging, would **not** be fail-closed and is explicitly out of contract.)
- **Stale-epoch packets do not contribute** to coverage.
## Invariant
The destination is always exactly one *complete* version — either the new epoch (on full coverage) or the prior epoch (on any failure). Never a byte-level mix of two epochs.
## Status / explicit non-claims
- **Not implemented.** No native C++ has been written, compiled, or silicon-tested for this design.
- This RFC makes **no** peer-death-safe / atomic / fail-closed **claim** about the current code. The current counter-based path can still publish a partial epoch on peer death — that behavior is **open**.
- A composition built on the current code may show a *successful* publication under normal conditions but must **not** be described as transactionally safe until this (or equivalent) coverage-based completion lands.
## Questions for maintainers
1. Is destination-byte coverage the right completion key, or is there an existing per-variable accounting hook to reuse?
2. Preferred failure surface for `FAILED` (exception vs. status enum on the transfer handle)?
3. Should stale-epoch rejection live in the controller or the native listener?
---
*Filed with agentic assistance (Navi) on behalf of the reporter. RFC only — no code proposed here.*
Contributor guide
Research direction
Start by reviewing the native C++ counter-based completion path and the H2D publication transition described in the issue, then compare the controller and native listener as possible locations for stale-epoch rejection. Done means maintainers agree on the coverage key, failure surface, and rejection location, followed by implementation and validation; this RFC names no files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100