The Hardware Did Not Read the API Contract

Web software encourages a dangerous reflex: if the contract is wrong, deploy another version.

Connected products remove that comfort. While working around the companion software behind Myotrek, the physical experience kept forcing a better question: which system currently knows the truth?

The phone may know the intended workout. The backend may know the saved plan. The device may know what physically happened. The person knows whether feedback felt immediate and believable. Those truths arrive at different times.

The clean model failed first #

client sends command → server accepts → device performs → UI confirms

Reality contains disconnections, delayed acknowledgements, app suspension, repeated commands, partial movement, firmware differences, and a person who will not wait for a distributed transaction before moving again.

Treating an API response as completed physical work creates false confidence. Treating every disconnect as failure can cause unsafe repetition.

The resolution was a richer state #

We need to separate intent, acceptance, observation, and completion:

requested ≠ accepted ≠ observed ≠ completed

“Saved,” “sent,” and “completed” should not collapse into one optimistic checkmark. Commands need stable identities. Device observations need monotonic sequence information where possible. Reconnection needs reconciliation rather than assuming the latest client screen is authoritative.

Product management across physics #

Hardware makes prioritization less abstract. A visual imperfection can wait; a confusing state around physical action cannot. The cheapest backend shortcut may create the most expensive support problem when users cannot distinguish delay from failure.

Compatibility must span devices that will not all update together. The contract needs capability negotiation and safe defaults, not only a version number.

I now review a connected feature as a timeline, not a screen:

• What does each participant believe at every step?
• Which acknowledgement proves receipt, and which proves effect?
• What can repeat safely?
• What happens when the app disappears mid-operation?
• How does an older device respond to a newer command?
• What does the person see while truth is incomplete?

The physical world does not conform to the abstraction. Good architecture makes that mismatch explicit and gives the user a truthful, calm experience while systems converge.

All Field Notes · Offline-first payments · API evolution without flag days