Protocol version field in the message contract #53

New issue

Open

opened 2026-08-31 17:30:06 +02:00 by robert · 0 comments

robert commented

2026-08-31 17:30:06 +02:00

(Migrated from git.butzei.de)

Goal

The watchapp and the companion are installed and updated independently - you will sideload a new watchapp and forget the APK, or the reverse. Without a version field the failure mode is subtly wrong numbers rather than an honest error.

Acceptance criteria

Protocol version constant defined in shared/message_keys.json and generated into both sides
Version included in the handshake when the watchapp connects to the companion
Mismatch detected on both sides and surfaced as a clear message naming which side is stale
App degrades to a safe subset or refuses to start rather than displaying wrong values
Version bump rules documented: additive keys do not bump, changed semantics do
Mismatch path covered by tests

Files

shared/message_keys.json
watchapp/src/c/proto.c
companion/.../pebble/Proto.kt

Notes

Cheap now, painful to retrofit - this is why it lands in Phase 0 alongside #7 rather than later.

Update — 2026-09-02: say what a mismatch actually does

"Surfaced, not tolerated" did not say whether the app refuses to run or degrades (D46).

On mismatch the watchapp refuses to start a ride, and names which side is stale and which
version each side speaks
No degraded or reduced mode. A bike computer showing plausible wrong numbers is worse than one
showing none
Adding a key does not bump the version; changed semantics, a removed key, or a changed rate in
PROTOCOL §4 do

## Goal The watchapp and the companion are installed and updated independently - you will sideload a new watchapp and forget the APK, or the reverse. Without a version field the failure mode is subtly wrong numbers rather than an honest error. ## Acceptance criteria - [ ] Protocol version constant defined in `shared/message_keys.json` and generated into both sides - [ ] Version included in the handshake when the watchapp connects to the companion - [ ] Mismatch detected on both sides and surfaced as a clear message naming which side is stale - [ ] App degrades to a safe subset or refuses to start rather than displaying wrong values - [ ] Version bump rules documented: additive keys do not bump, changed semantics do - [ ] Mismatch path covered by tests ## Files - `shared/message_keys.json` - `watchapp/src/c/proto.c` - `companion/.../pebble/Proto.kt` ## Notes Cheap now, painful to retrofit - this is why it lands in Phase 0 alongside #7 rather than later. ## Update — 2026-09-02: say what a mismatch actually does "Surfaced, not tolerated" did not say whether the app refuses to run or degrades (D46). - [ ] On mismatch the watchapp **refuses to start a ride**, and names which side is stale and which version each side speaks - [ ] No degraded or reduced mode. A bike computer showing plausible wrong numbers is worse than one showing none - [ ] Adding a key does not bump the version; changed semantics, a removed key, or a changed rate in PROTOCOL §4 do