Better description of the mainline of a PL event. (#1107)

changelogs/room_versions/newsfragments/1107.clarification

@@ -0,0 +1 @@
+For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events.

content/rooms/fragments/v2-state-res.md

@@ -89,27 +89,43 @@ selecting, among all the candidate vertices, the smallest vertex using
 the above comparison relation.
 
 **Mainline ordering.**
-Given an `m.room.power_levels` event *P*, the *mainline of* *P* is the
-list of events generated by starting with *P* and recursively taking the
-`m.room.power_levels` events from the `auth_events`, ordered such that
-*P* is last. Given another event *e*, the *closest mainline event to*
-*e* is the first event encountered in the mainline when iteratively
-descending through the `m.room.power_levels` events in the `auth_events`
-starting at *e*. If no mainline event is encountered when iteratively
-descending through the `m.room.power_levels` events, then the closest
-mainline event to *e* can be considered to be a dummy event that is
-before any other event in the mainline of *P* for the purposes of
-condition 1 below.
-
-The *mainline ordering based on* *P* of a set of events is the ordering,
+Let *P* = *P*<sub>0</sub> be an `m.room.power_levels` event.
+Starting with *i* = 0, repeatedly fetch *P*<sub>*i*+1</sub>, the
+`m.room.power_levels` event in the `auth_events` of *P<sub>i</sub>*.
+Increment *i* and repeat until *P<sub>i</sub>* has no `m.room.power_levels`
+event in its `auth_events`.
+The *mainline of P*<sub>0</sub> is the list of events
+    [*P*<sub>0</sub> , *P*<sub>1</sub>, ... , *P<sub>n</sub>*],
+fetched in this way.
+
+Let *e* = *e<sub>0</sub>* be another event (possibly another
+`m.room.power_levels` event). We can compute a similar list of events
+    [*e*<sub>1</sub>, ..., *e<sub>m</sub>*],
+where *e*<sub>*j*+1</sub> is the `m.room.power_levels` event in the
+`auth_events` of *e<sub>j</sub>* and where *e<sub>m</sub>* has no
+`m.room.power_levels` event in its `auth_events`. (Note that the event we
+started with, *e<sub>0</sub>*, is not included in this list. Also note that it
+may be empty, because *e* may not cite an `m.room.power_levels` event in its
+`auth_events` at all.)
+
+Now compare these two lists as follows.
+* Find the smallest index *j* ≥ 1 for which *e<sub>j</sub>* belongs to the
+   mainline of *P*.
+* If such a *j* exists, then *e<sub>j</sub>* = *P<sub>i</sub>* for some unique
+  index *i* ≥ 0. Otherwise set *i* = ∞, where ∞ is a sentinel value greater
+  than any integer.
+* In both cases, the *mainline position* of *e* is *i*.
+
+Given mainline positions calculated from *P*, the *mainline ordering based on* *P* of a set of events is the ordering,
 from smallest to largest, using the following comparison relation on
 events: for events *x* and *y*, *x* &lt; *y* if
 
-1.  the closest mainline event to *x* appears *before* the closest
-    mainline event to *y*; or
-2.  the closest mainline events are the same, but *x*'s
+1.  the mainline position of *x* is **greater** than
+    the mainline position of *y* (i.e. the auth chain of 
+    *x* is based on an earlier event in the mainline than *y*); or
+2.  the mainline positions of the events are the same, but *x*'s
     `origin_server_ts` is *less* than *y*'s `origin_server_ts`; or
-3.  the closest mainline events are the same and the events have the
+3.  the mainline positions of the events are the same and the events have the
     same `origin_server_ts`, but *x*'s `event_id` is *less* than *y*'s
     `event_id`.