Reconciliation in the Android client: Dealing with ambiguous network status and interupted transmissions

In the field, a slow network or long-running request can leave the user in an ambiguous state. A recording upload may have been accepted even though the phone never got a clean response. A submit action may still be processing even though the request appeared to stall. In those cases, the question is not whether the client can send data. The question is whether the user can tell what actually happened. That uncertainty matters because it interrupts the task and erodes the confidence of users and cutomers.

If the observer is left wondering whether to retry an upload, resend a submit, or wait, attention shifts away from the work and back onto the device. The recent reconciliation work has been about reducing that uncertainty and making recovery more explicit.

The technical direction has been to make the round the reconciliation unit. The "round" is a revision or addition to the observation by the client -- each time the user taps "submit for processing". Instead of forcing the client to reconstruct state from several different routes or payloads, the server should have one coherent answer for a given round: what it knows about the round, which revision it believes is current, which artifacts it has accepted, and whether processing is underway, completed, or failed.

First, important workflow identity needs to be first-class state. The notes are explicit that client_revision_id should not survive only indirectly inside review or final payloads. It should be persisted as round state so the server can answer a simple question directly: which logical client revision is current for this round?

Second, accepted artifact state needs to be directly readable. The client should not have to guess whether a recording or image was accepted by inspecting side effects or reconstructing state from other payloads. Accepted recording IDs and image IDs should come from DB-backed round metadata and be returned as part of the reconciliation read. That gives the client a clear basis for deciding whether the same stable ID should be retried or suppressed.

Third, retry behavior needs to be grounded in the actual contract. The current upload behavior is closer to stable-ID-safe retry than to a duplicate-reject model. That means the right direction is not to assume a 409 already exists response, but to make it clear that retrying the same upload with the same stable ID is allowed and that reconciliation should tell the client what the server already knows.

The frontend clarification notes tighten that logic further. If a recording ID or image ID appears in the accepted set, that is enough to suppress a same-ID re-upload. If a round comes back with processing_state=accepted, that means the server knows the round and the state is non-terminal, not that the work was rolled back. And if the client_revision_id returned by the server does not match the local one, that should be treated as likely staleness or conflict rather than as an ordinary retry case.

That is the point of reconciliation in this phase of development. It is not just about recovering from a timeout. It is about making the workflow more legible after something ambiguous happens. The user should be able to tell what the server accepted, what state the round is in, and whether retrying would help or only repeat work.