A capability stays maintainable only when the team can explain every state, retry, and piece of residual data—not merely show one successful run. Sender send() only queues bytes; meaningful progress is receiver-verified persisted data. Final 100 percent requires whole-file integrity and atomic completion.
A product loop covers start, wait, cancel, failure, recovery, and re-entry while automation obeys the user’s latest explicit choice. Metrics measure task outcomes rather than button clicks.
Questions the design must answer
List non-negotiable invariants before selecting performance knobs. Tuning can roll out gradually; identity, permission, and terminal-state rules cannot drift at runtime.
- Use confirmedBytes over total for primary progress, show prepare/transfer/verify/save stages, avoid counting repair twice, and hide ETA without enough samples.
- Separate protocol facts, user intent, and automatic recovery; automation may restore facts but never overturn an explicit choice.
- Ship conservative defaults, server-side ceilings, and a rollout switch instead of trusting browser-provided numbers as resource budgets.
The delivery standard for Honest File Progress: Read, Sent, Acknowledged, or Persisted is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
Edge cases are part of the feature
An abnormal path is more than an error banner. It decides how in-flight work stops, how the peer learns the outcome, what residue remains, and whether the next operation inherits it.
- Counting bytesSent exceeds 100 percent on repair, while declaring complete before a long final hash invites users to close and lose the result.
- A stale response arriving after a new task can overwrite healthy state or restart cancelled work without version fencing.
- Without backpressure or quota, a slow consumer raises memory, queue depth, and tail latency until unrelated users are affected.
Prove that it works with evidence
Do not stop verification when the final action succeeds. Count side effects, measure wait time, inspect privacy, and prove the next run begins from a clean baseline.
- Cover normal, pause, duplicate, repair, refresh resume, hash failure, and slow disk; percentage stays monotonic, terminal state accurate, and bytes reconcile.
- Race refresh, cancel, timeout, and remote completion in one scheduling window; assert one terminal state and one side effect.
- Before release, record success rate, p50/p95/p99 latency, error classes, and resource high-water marks with explicit rollback thresholds.
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.