Clarify `history_visibility` behaviour

Clear up some lies in the history_visibility section, and clarify behaviour for
`m.room.history_visibility` and the user's own `m.room.member` events.

changelogs/client_server.rst

@@ -1,8 +1,9 @@
 <Next release>
 ==============
 
-No changes yet.
+- Spec clarifications:
 
+  - Clarify the behaviour of the "Room History Visibility" module; in particular, the behaviour of the ``shared`` history visibilty, and how events at visibility boundaries should be handled.
 
 r0.0.1
 ======

specification/modules/history_visibility.rst

@@ -9,24 +9,24 @@ room.
 In all cases except ``world_readable``, a user needs to join a room to view events in that room. Once they
 have joined a room, they will gain access to a subset of events in the room. How
 this subset is chosen is controlled by the ``m.room.history_visibility`` event
-outlined below. After a user has left a room, they may seen any events which they
+outlined below. After a user has left a room, they may see any events which they
 were allowed to see before they left the room, but no events received after they
 left.
 
 The four options for the ``m.room.history_visibility`` event are:
 
+- ``world_readable`` - All events while this is the
+  ``m.room.history_visibility`` value may be shared by any participating
+  homeserver with anyone, regardless of whether they have ever joined the room.
 - ``shared`` - Previous events are always accessible to newly joined members. All
   events in the room are accessible, even those sent when the member was not a part
   of the room.
-- ``invited`` - Previous events are accessible to newly joined members from the point
+- ``invited`` - Events are accessible to newly joined members from the point
   they were invited onwards. Events stop being accessible when the member's state
   changes to something other than ``invite`` or ``join``.
-- ``joined`` - Previous events are accessible to newly joined members from the point
+- ``joined`` - Events are accessible to newly joined members from the point
   they joined the room onwards. Events stop being accessible when the member's state
   changes to something other than ``join``.
-- ``world_readable`` - All events while this is the ``m.room.history_visibility`` value
-  may be shared by any participating homeserver with anyone, regardless of whether
-  they have ever joined the room.
 
 .. WARNING::
   These options are applied at the point an event is *sent*. Checks are
@@ -54,14 +54,29 @@ Server behaviour
 
 By default if no ``history_visibility`` is set, or if the value is not understood, the visibility is assumed to be
 ``shared``. The rules governing whether a user is allowed to see an event depend
-solely on the state of the room *at that event*:
+on the state of the room *at that event*.
-
+
-1. If the user was joined, allow.
+1. If the ``history_visibility`` was set to ``world_readable``, allow.
-2. If the user was invited and the ``history_visibility`` was set to
+2. If the user's ``membership`` was ``join``, allow.
-   ``invited`` or ``shared``, allow.
+3. If ``history_visibility`` was set to ``shared``, and the user joined the
-3. If the user was neither invited nor joined but the ``history_visibility``
+   room at any point after the event was sent, allow.
-   was set to ``shared``, allow.
+4. If the user's ``membership`` was ``invite``, and the ``history_visibility``
-4. Otherwise, deny.
+   was set to ``invited``, allow.
+5. Otherwise, deny.
+
+For ``m.room.history_visibility`` events themselves, the user should be allowed
+to see the event if the ``history_visibility`` before *or* after the event
+would allow them to see it. (For example, a user should be able to see
+``m.room.history_visibility`` events which change the ``history_visibility``
+from ``world_readable`` to ``joined`` *or* from ``joineded`` to
+``world_readable``, even if that user was not a member of the room.)
+
+Likewise, for the user's own ``m.room.member`` events, the user should be
+allowed to see the event if their ``membership`` before *or* after the event
+would allow them to see it. (For example, a user can always see
+``m.room.member`` events which set their membership to ``join``, or which
+change their membership from ``join`` to any other value, even if
+``history_visibility`` is ``joined``.)
 
 Security considerations
 -----------------------