google / google/tpu-sync

RFC: epoch-scoped destination-byte coverage completion (peer-death mid-transfer → mixed-version dst)

Open
#668 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.