From Spinner to Percentage: A Progress Contract for Work of Unknown Size

A progress bar that guesses its total invents precision. When the size of the work is not yet known, say so, then switch to counts when the total is real. This article proposes a contract between worker and display. It is a conditional design, not a feature claim.

The contract

The worker reports one of three modes:

indeterminate: no total known. Fields: phase label, items_done so far, last_update time.
counted: total known. Fields: items_done, total, phase label.
ended: outcome of completed, failed or cancelled, with final counts.

Rules:

Never show a percentage in indeterminate mode.
Move to counted only when total is a confirmed number, not an estimate.
If total later changes, show the change explicitly and do not let the bar jump backwards without explanation.
items_done never decreases within a run.
A stale last_update beyond a limit you choose shows as no recent update, not as progress.

Branches

Total discovered at the start: begin directly in counted.
Total discovered mid-run (for example after a listing step): switch once, from indeterminate to counted.
Total revised upward: remain counted, show the new total and a note.
Total never known: stay indeterminate to the end and report final counts only.
Worker stops responding: keep the last counts, flag stale, do not claim failure or success without a final report.

Worked example

An import of a supplier file begins.

Phase reading: indeterminate, 0 rows done.
After 40 rows are read, still indeterminate, shown as 40 rows read.
The reader reaches the end and confirms 120 rows. The mode switches to counted: 40 of 120.
Validation proceeds to 120 of 120.
Ended, completed, with 118 accepted and 2 rejected, so 118 plus 2 equals 120.

If instead the reader found 150 rows after showing 120, the display shows total revised from 120 to 150 and keeps items_done where it was.

Stop conditions

Stop trusting the display if items_done exceeds total, if counts decrease, or if the final accepted plus rejected does not equal the confirmed total. Report an inconsistency rather than rounding it away. Avoid time estimates unless you have measured throughput, and then present a range.

Proposed acceptance tests (proposed, not performed)

Run with unknown total: expect no percentage shown.
Confirm total mid-run: expect exactly one mode switch.
Revise total upward: expect a visible note and no backwards counter.
Silence the worker: expect a stale flag, not completion.
Complete a run: expect accepted plus rejected equal to total.
Cancel a run: expect ended cancelled with the counts reached.