Merge 910340a98b into 8ebf4a4789

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

changelogs/client_server/newsfragments/2240.clarification

@@ -0,0 +1 @@
+Clarify how to use `state_after` ahead of declaring full support for its spec version.

changelogs/client_server/newsfragments/2245.clarification

@@ -0,0 +1 @@
+`device_one_time_keys_count` is only optional if no unclaimed one-time keys exist.

content/client-server-api/modules/end_to_end_encryption.md

@@ -1775,19 +1775,18 @@ property is required for inclusion, though previous versions of the
 specification did not have it. In addition to `/versions`, this can be
 a way to identify the server's support for fallback keys.
 
-
-| Parameter                        | Type               | Description                                                                                                            |
-|----------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
-| device_lists                     | DeviceLists        | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
-| device_one_time_keys_count       | {string: integer}  | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device.  If an algorithm is unlisted, the count for that algorithm is assumed to be zero.  If this entire parameter is missing, the count for all algorithms is assumed to be zero.  |
-| device_unused_fallback_key_types | [string]           | **Required.** The unused fallback key algorithms.                                                                      |
+| Parameter                        | Type              | Description                                                                                                            |
+|----------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------|
+| device_lists                     | DeviceLists       | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
+| device_one_time_keys_count       | {string: integer} | **Required if any unclaimed one-time keys exist.** For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If the count for an algorithm is zero, servers MAY omit that algorithm. If the count for all algorithms is zero, servers MAY omit this parameter entirely. |
+| device_unused_fallback_key_types | [string]          | **Required.** The unused fallback key algorithms.                                                                      |
 
 `DeviceLists`
 
-| Parameter  | Type      | Description                                                                                                                                                      |
-|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| changed    | [string]  | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
-| left       | [string]  | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
+| Parameter | Type     | Description                                                                                                                                                      |
+|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| changed   | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
+| left      | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
 
 {{% boxes/note %}}
 For optimal performance, Alice should be added to `changed` in Bob's

data/api/client-server/login.yaml

@@ -262,8 +262,8 @@ paths:
                 or the requested device ID is the same as a cross-signing key
                 ID.
               * `M_USER_DEACTIVATED`: The user has been deactivated.
-                Note that servers MAY choose not to use this error code and instead use `M_FORBIDDEN`,
-                particularly when the server can't authenticate the deactivated user.
+                Servers MAY instead use `M_FORBIDDEN` when they can no longer authenticate
+                the deactivated user (i.e. their password has been wiped).
           content:
             application/json:
               schema:

data/api/client-server/sync.yaml

@@ -133,10 +133,15 @@ paths:
             sync and the **start** of the timeline in `state` and MUST omit
             `state_after`.
 
-            Even if this is set to `true`, clients MUST update their local state
-            with events in `state` and `timeline` if `state_after` is missing in
-            the response, for compatibility with servers that don't support this
-            parameter.
+            Servers MAY implement this parameter ahead of declaring support for
+            the version of the spec in which it was introduced. Consequently,
+            clients MAY set this parameter to `true` regardless of the
+            [`/versions`](/client-server-api/#get_matrixclientversions) response.
+            If they do, they can infer whether the server actually supports this
+            parameter from the presence of `state_after` in the response. If
+            `state_after` is missing, clients MUST behave as if they had not
+            specified the parameter and update their local state with events
+            in `state` and `timeline`.
 
             By default, this is `false`.
           example: false