A sound implementation does not ask users to refresh until it works. Each phase has an input, an output, a timeout, and a terminal state. One offset works only for a contiguous prefix. Parallel or partially reliable delivery creates islands of completed data; a percentage or highest offset can skip holes after refresh.
File transfer must reconcile sender offsets, durable receiver writes, chunk integrity, and terminal state on both peers. A full progress bar may show queued bytes, not a complete usable file.
Define the system contract first
Start from facts the data and protocol can guarantee, then decide what the interface may promise. Each rule below needs an owner, a bound, and a compatibility policy rather than an oral convention from one review.
- Merge a range into the manifest only after durable chunk storage, committing their relationship transactionally.
- Send a normalized compressed received-range set; let the sender compute and batch missing work.
- Require matching task version, file digest, and chunk size before reusing an old manifest.
Real resume preserves a provable set of completed data, not a decorative percentage. Manifest, chunk storage, and final digest form one recoverable evidence chain.
What can break that contract
Prioritize faults that silently preserve false facts: the interface looks recovered while a queue, permission, or counter has diverged. The defect often appears only on the next action.
- An off-by-one merge leaves the final byte duplicated or permanently missing.
- The manifest commits before chunk storage fails, advertising bytes that do not exist.
- A huge gap list is sent in one signaling message and exceeds limits during weak-network recovery.
How to test the contract line by line
Observe both endpoints, persisted records, and operational signals during verification. One button state or one successful response cannot prove the complete loop.
- Generate overlapping, adjacent, and reversed ranges and property-test normalization equivalence.
- Crash between every chunk write and manifest commit; restart must never skip an unwritten block.
- Create thousands of sparse gaps and verify paged exchange, fair repair, and final digest.
The result must be correct, recoverable, and explainable. If any part depends on refreshing the page or an engineer guessing, the protocol loop remains incomplete.