Clarify wording further for how to handle redundant members

Note: This makes assumptions on what the TODO comment in Synapse means: e26e6b3230/synapse/handlers/pagination.py (L262)

Due to lack of implementation, it is assumed that using the same filter across multiple calls to /sync OR /messages will result in the redundant members being excluded in the next request. For example, calling /sync, then /messages which returns some members, then /sync again will exclude the members due to them being in /messages.

api/client-server/definitions/room_event_filter.yaml

@@ -24,27 +24,28 @@ allOf:
         display the ``sender`` of the timeline events in the response.
         If ``false``, ``m.room.member`` events are not filtered.
         By default, servers should suppress duplicate redundant
-        lazy-loaded ``m.room.member`` events from being sent to a given
+        lazy-loaded ``m.room.member`` events from being sent to a
-        client across multiple calls, given that most clients
+        given client in a previous request using the same filter,
-        cache membership events (see ``include_redundant_members``
+        given that most clients cache membership events (see
-        to change this behaviour).
+        ``include_redundant_members`` to change this behaviour).
 
         Only applicable when filtering state events, such as the
-        ``state`` section of a ``/sync`` or ``/messages``.
+        ``state`` section of a ``/sync`` or ``/messages`` response.
     include_redundant_members:
       type: boolean
       description: |-
         If ``true``, response will always contain the ``m.room.member``
         events required to display the ``sender`` of the timeline events
-        in that response, assuming ``lazy_load_members`` is enabled. This
+        in that response, assuming ``lazy_load_members`` is enabled.
-        means that redundant duplicate member events may be returned across
+        This means that redundant duplicate member events will be returned
-        multiple calls to. This is useful for naive clients who never track
+        across multiple calls using the same filter. This is useful for
-        membership data. If ``false``, duplicate ``m.room.member`` events
+        naive clients who never track membership data. If ``false`` or
-        may be suppressed by the server across multiple calls. If
+        not provided, duplicate ``m.room.member`` events should be
-        ``lazy_load_members`` is ``false`` this field is ignored.
+        suppressed by the server across multiple calls. If ``lazy_load_members``
+        is ``false`` this field is ignored.
 
         Only applicable when filtering state events, such as the
-        ``state`` section of a ``/sync`` or ``/messages``.
+        ``state`` section of a ``/sync`` or ``/messages`` response.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
         are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``

api/client-server/message_pagination.yaml

@@ -108,6 +108,23 @@ paths:
                   type: object
                   title: RoomEvent
                   "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+              state:
+                type: array
+                description: |-
+                  A list of state events relevant to showing the ``chunk``. For example, if
+                  lazy-loading members is enabled in the filter then this will contain any
+                  applicable membership events. Servers should be careful to not exclude
+                  membership events which are older than ones already sent to the client.
+                  Likewise, clients should be cautious and avoid using older membership
+                  events as the current membership event when paginating backwards.
+
+                  Unless ``include_redundant_members`` is ``true``, the server should remove
+                  redundant members which would have already been sent to clients in prior calls
+                  to ``/messages`` or ``/sync`` with the same filter.
+                items:
+                  type: object
+                  title: RoomStateEvent
+                  $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
           examples:
             application/json: {
                 "start": "t47429-4392820_219380_26003_2265",