dimamitya

← writing

verify before retrying

an upload times out. the obvious next step is to try again. but the server may have already changed the profile photo; only the response was lost. another request can create another entry in the photo history while telling you nothing about what happened to the first one.

i built clubdeck-avatar to change a clubhouse avatar using an existing clubdeck login. it prepares two jpegs, submits them, and checks the result. the interesting part is what the tool does when those steps disagree.

give uncertainty a place to live

each run gets its own directory with the prepared images and a receipt.json. the receipt starts as prepared. before sending the upload, the tool saves submitting, the account id, the previous profile url, and the photo-history count. it also records which run a later verification command should inspect.

the response determines the next state. an explicit success becomes accepted; an explicit rejection below http 500 becomes rejected. a lost response or an ambiguous result leaves the outcome uncertain.

that distinction controls what the tool can do next. the upload command refuses to proceed while the latest receipt is submitting or uncertain. a local lock also prevents concurrent upload commands sharing the same output directory. after a crash, recovery starts with the saved receipt.

these are local controls. they cannot prevent another device from changing the same account, and they do not provide server-side idempotency. the upload implementation makes that scope inspectable.

acceptance needs a follow-up read

an accepted upload still needs verification. the tool reads both the current profile and photo history. the profile must match the image identity returned by the upload, and history must contain a matching photo key or image identity.

comparison needs a little care: a thumbnail suffix or signed query string can change the url without changing which photo it identifies. history keys can also use different timestamp precision. the verifier accounts for those representations before deciding whether the records agree.

if the profile is stale, the tool polls those reads a bounded number of times. it leaves the upload alone. verification can also be run separately:

node --env-file=.env avatar.mjs verify

that command checks the latest attempted upload without sending another image. exit code 2 means verification is still pending or inconclusive. a caller has a concrete outcome to handle instead of treating every incomplete result as a reason to repeat the write.

recovery has an evidence limit

when the upload response is lost, there may be no returned photo identity to compare against. the fallback downloads the current avatar and compares its sha256 hash with the prepared jpeg. recovery also requires the history count to have grown and the current photo to match a history entry.

this is deliberately narrow. if the server re-encodes the image, the bytes can differ even when the picture looks identical. the tool then leaves the outcome unresolved and saves the downloaded image for inspection. a human can review the account before allowing a new upload.

test the gap between sending and knowing

the tests use synthetic data and mocked requests. they check that a lost response produces one upload attempt, stale reads can settle without another upload, receipts from another account are rejected, and exact-image recovery also requires new history. those checks exercise the local policy; they cannot promise that an undocumented remote api will keep behaving the same way.

this is the contract i want around an agent’s side effects: record the attempt, keep uncertainty explicit, and offer a way to inspect the result. an agent trying to finish a task needs that recovery path as much as it needs the tool that performs the action.