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

src/thoughtsync/app.py

@@ -18,7 +18,7 @@ from .notes import bp as notes_bp
 from .saved_filters import bp as saved_filters_bp
 from .settings import get_public_config, get_setting, load_or_create_secret_key
 from .settings_api import bp as settings_bp
-from .sync import bp as sync_bp
+from .sync import bp as sync_bp, protocol_advertisement
 
 STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
 
@@ -91,6 +91,10 @@ def create_app() -> Quart:
         async with session_scope() as db:
             data = await get_public_config(db)
         data["version"] = app.config["APP_VERSION"]
+        # The sync-protocol handshake (M10.6). A native client reads this BEFORE
+        # linking — while it still has no token and possibly no account — to decide
+        # whether it can talk to this server, and which optional features to offer.
+        data.update(protocol_advertisement())
         return jsonify(data)
 
     @app.get("/", defaults={"path": ""})

src/thoughtsync/sync.py

@@ -46,6 +46,48 @@ DEFAULT_LIMIT = 500
 MAX_LIMIT = 1000
 MAX_PUSH = 1000  # per-batch change cap
 
+# --- protocol versioning (M10.6) --------------------------------------------
+#
+# The client<->server compatibility contract. These integers version the WIRE
+# PROTOCOL, deliberately separate from the app's release version, so a client and
+# server on different releases can still work out whether they can talk. Without
+# that separation every protocol change would force app<->server lockstep.
+#
+#   SYNC_PROTOCOL_VERSION       what this server speaks.
+#   MIN_CLIENT_PROTOCOL_VERSION the oldest client protocol it still accepts.
+#
+# Bump SYNC_PROTOCOL_VERSION for ANY wire change. Raise
+# MIN_CLIENT_PROTOCOL_VERSION only for a genuinely BREAKING one: it is the switch
+# that hard-blocks older clients, so additive changes must leave it alone.
+SYNC_PROTOCOL_VERSION = 1
+MIN_CLIENT_PROTOCOL_VERSION = 1
+
+# Named capabilities beyond the base protocol. An ADDITIVE change earns a name
+# here rather than a min-version bump, so a newer client meeting an older server
+# can degrade to "some features unavailable" instead of refusing to sync. Clients
+# test for the name, never infer a capability from a version number — that's what
+# keeps feature gating independent of release lockstep.
+SYNC_FEATURES: tuple[str, ...] = (
+    "notes",  # note delta sync (pull + push)
+    "labels",  # the label catalog as its own entity
+    "attachments",  # blob upload/download, deduped by sha256
+    "tombstones",  # purge propagates as a content-less row
+    "revisions",  # an overwritten version snapshots into note history
+)
+
+
+def protocol_advertisement() -> dict:
+    """What the server publishes about the sync protocol, merged into `/api/config`.
+
+    DB-free and unauthenticated on purpose: a client has to be able to ask "can I
+    talk to you at all?" before it holds a device token — or even has an account.
+    """
+    return {
+        "sync_protocol_version": SYNC_PROTOCOL_VERSION,
+        "min_client_protocol_version": MIN_CLIENT_PROTOCOL_VERSION,
+        "sync_features": list(SYNC_FEATURES),
+    }
+
 
 def _parse_since(raw: str | None) -> int:
     """The pull cursor: a non-negative revision watermark. Bad/absent → 0 (full sync)."""