M10.6: client↔server sync protocol handshake (task 1995)

Version the sync WIRE PROTOCOL separately from either program's release
version, so a self-hosted server and the desktop app can sit on different
releases and still work out whether they can talk.

Each side declares two numbers — what it speaks, and the oldest counterpart
it accepts. Either side can therefore mark a change breaking without the
other shipping in step, which is the whole point: no app↔server lockstep.

Server advertises on the existing public /api/config (a client must be able
to ask "can I talk to you?" before it holds a device token, or even has an
account): sync_protocol_version, min_client_protocol_version, sync_features.

sync_features exists because a version number can only say newer/older. An
ADDITIVE change earns a capability name instead of a minimum bump, so a
newer client meeting an older server drops that one feature and syncs the
rest, rather than refusing. Raising a minimum is reserved for genuinely
breaking changes — it's the switch that hard-blocks the other side.

Client half is pure decision logic (sync/compat.rs), no I/O, so every branch
is unit-testable — there's no live-server lane in CI. Three outcomes: ok /
degraded{unavailable} / incompatible{reason, client_must_update}. The last
names which side can fix it, so the message is actionable. A server that
predates the handshake sends no protocol fields at all; that reads as
"update the server", deliberately not as a parse error, which would look to
the user like they mistyped the URL.

normalize_base_url defaults a bare host to https://, never http:// —
silently downgrading would put a long-lived device token on the wire in
cleartext because someone omitted five characters. Plain HTTP on a trusted
LAN stays supported; the user types http:// and thereby chooses it.

Transport (the actual fetch) lands next, separately: it needs an HTTP/TLS
stack, and that's a real risk to the Windows cross-compile lane, so it gets
its own CI run to bisect against rather than riding along with this.

No UI here by design — the link/settings surface it feeds is M10.7's, per
this task's own sequencing.

Policy documented in docs/sync.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi

tests/test_sync.py

@@ -6,10 +6,14 @@ from thoughtsync.app import create_app
 from thoughtsync.sync import (
     DEFAULT_LIMIT,
     MAX_LIMIT,
+    MIN_CLIENT_PROTOCOL_VERSION,
+    SYNC_FEATURES,
+    SYNC_PROTOCOL_VERSION,
     _clamp_limit,
     _page_cursor,
     _parse_since,
     client_wins,
+    protocol_advertisement,
 )
 
 
@@ -82,3 +86,28 @@ def test_page_cursor_both_full_uses_min_boundary():
     cursor, more = _page_cursor([1, 2, 10], [3, 4, 5], since=0, limit=3)
     assert cursor == 5
     assert more is True
+
+
+# --- protocol handshake (M10.6) ---------------------------------------------
+
+
+def test_protocol_advertisement_shape():
+    ad = protocol_advertisement()
+    assert ad["sync_protocol_version"] == SYNC_PROTOCOL_VERSION
+    assert ad["min_client_protocol_version"] == MIN_CLIENT_PROTOCOL_VERSION
+    # A list, not a tuple — it has to survive jsonify as a JSON array.
+    assert isinstance(ad["sync_features"], list)
+    assert ad["sync_features"] == list(SYNC_FEATURES)
+
+
+def test_protocol_floor_never_exceeds_current():
+    # A server can't demand a client protocol newer than the one it speaks itself —
+    # that would lock out every client, including a perfectly current one.
+    assert MIN_CLIENT_PROTOCOL_VERSION <= SYNC_PROTOCOL_VERSION
+
+
+def test_protocol_features_are_unique_nonempty_names():
+    # Clients match capabilities by exact name, so duplicates or blanks would make
+    # a feature check silently meaningless.
+    assert all(f and f.strip() == f for f in SYNC_FEATURES)
+    assert len(set(SYNC_FEATURES)) == len(SYNC_FEATURES)