aside: add warnings about MultiWriterIdGenerator starting at 2

Author: reivilibre

synapse/storage/util/id_generators.py

@@ -184,6 +184,12 @@ class MultiWriterIdGenerator(AbstractStreamIdGenerator):
 
     Note: Only works with Postgres.
 
+    Warning: Streams using this generator start at ID 2, because ID 1 is always assumed
+        to have been 'seen as persisted'.
+        Unclear if this extant behaviour is desirable for some reason.
+        When creating a new sequence for a new stream,
+        it will be necessary to use `START WITH 2`.
+
     Args:
         db_conn
         db
@@ -269,6 +275,9 @@ def __init__(
         self._known_persisted_positions: List[int] = []
 
         # The maximum stream ID that we have seen been allocated across any writer.
+        # Since this defaults to 1, this means that ID 1 is assumed to have already
+        # been 'seen'. In other words, multi-writer streams start at 2.
+        # Unclear if this is desirable behaviour.
         self._max_seen_allocated_stream_id = 1
 
         # The maximum position of the local instance. This can be higher than