An unsynced-work indicator on a disconnected client - why is it product behaviour a case must assert rather than a diagnostic?

On a device that keeps accepting work with no connection, there is a window in which the user's work exists in exactly one place - their handset - and nothing outside it knows. The only thing standing between the user and a wrong belief about that work is whatever the interface tells them: a count of items waiting, a per-item marker, a summary line saying when everything was last delivered. That display is not instrumentation for engineers. It is the product's answer to *is my work safe*, and it is asserted like any other output. ## Why the diagnostic framing loses Calling it a diagnostic leads to three bad outcomes, and all three show up in real suites: - It gets excluded from cases as noise, so nothing ever checks it. - It is allowed to be a spinner or a subtle tint, because "engineers can read the logs" - which makes it unassertable *and* useless to the user. - Worst, it is allowed to clear optimistically the moment a delivery attempt is sent, because clearing early looks better. The user closes the application believing the work is delivered. It is not. The third one is the case that justifies the leaf. Nothing crashes, nothing is logged as an error, and no assertion on the record itself catches it, because the record is fine - it simply is not where the user thinks it is. ## The three points to assert | Point in the flow | Expected display | The failure it catches | | --- | --- | --- | | Work created with no link | Count rises; the item is marked | Work silently accepted and forgotten | | Link restored, delivery running | Still reports outstanding work | Clearing on send rather than on success | | Delivery confirmed | Clears, and says when it happened | A marker that never goes away | Notice that the middle row is the only one requiring the case to hold the product in an inconvenient state, and it is the one that finds real defects. Getting there means controlling the far side: have a programmable stand-in refuse the write, or seed a record that will be rejected on arrival, so the attempt happens and does not succeed. ## Make it assertable, then assert the negative An indicator the case cannot read is an indicator the user cannot rely on either, so the two problems have the same fix. 1. **Prefer a countable state to a motion cue.** A number of outstanding items, or a per-item marker, can be compared with an expected value. A spinner cannot; the case can only observe that something is animating, which is true whether one item or forty are stuck. 2. **Assert rises, holds and clears** - all three transitions, in one case, so the display is proved to track reality rather than to appear at the right moment by coincidence. 3. **Force a failed delivery** and require the indicator to keep reporting the work, together with something the user can act on: which item, and what they can do about it. This is the assertion that stops optimistic clearing shipping. 4. **Assert the wording, not only the number**, for a small state the case constructs - a known count and one rejected item. Keep the expected text in the case rather than reading it from the same source the screen renders from, or the assertion compares a value with itself. 5. **Check the durable path.** If the product promises the work survives the application being closed, close and reopen it, and require the indicator to come back reporting the same outstanding items. ## Where the boundary sits This is a behavioural case, so it takes the display as a promise and proves it. It does not choose how often delivery is attempted, how the queue is stored, or what backoff is applied after a rejection - those live with the design of the mechanism. Nor is it the run's own logging: a case may certainly log the pending state to make failures diagnosable, but logging is read by an engineer after the fact, while the indicator is read by a user making a decision in the moment. Only one of the two is a promise, and only that one should fail the build when it lies. ## The judgement worth showing The interesting question is not whether to assert the indicator but what it is allowed to say. A count with no detail is honest but not actionable. A per-item marker is actionable but noisy on a long list. Silence after a permanent rejection is the only option that is never defensible, because it converts a recoverable situation - the user still has the text on screen and can retry or copy it - into invisible loss. Whatever the product chooses, the case pins it, so the next person who tunes the display for tidiness cannot quietly remove the only signal the user had.