ircd:Ⓜ️ Add README for m::room directory.

include/ircd/m/room.h

@@ -11,6 +11,14 @@
 #pragma once
 #define HAVE_IRCD_M_ROOM_H
 
+// Matrix Room interface.
+//
+// This header is the index for the Room interface suite. The `class room`
+// itself is available in room/room.h.
+//
+// See room/README.md for more information.
+//
+
 namespace ircd::m
 {
 	IRCD_M_EXCEPTION(m::error, CONFLICT, http::CONFLICT);

include/ircd/m/room/README.md

@@ -0,0 +1,88 @@
+## Matrix Room Interface
+
+The headers in this directory as well as `../room.h` comprise the API for
+Matrix rooms. These interfaces may conduct IO for both the local database
+and the network; many calls may block an ircd::ctx for these purposes.
+
+A room is composed from a timeline of events. We use several key-value
+tables as the database for room in addition to the raw event data itself.
+
+- room_events
+This is the timeline for room events. We sort the keys of this table by
+an event's `depth`. This table allows us to scan the room's events as
+a collection. See: `m::room::messages`.
+
+- room_state
+This is the present state table for a room. We sort the keys of this table
+by `(type,state_key)`. See: `m::room::state`.
+
+- room_joined
+This is the present joined members list. It is technically redundant to that
+aspect of the room_state table but it is more efficient for us to maintain
+a separate table. See: `m::room::origins` which uses this table. Other
+interfaces are internally optimized by this table for some calls.
+
+- room_head
+This is the collection of forward extremities (unreferenced) for a room. This
+is a fast-moving table that would otherwise be just a list in RAM; however
+persisting this through the database prevents recalculating it on startup.
+
+- state_node
+This is a key-value store of nodes in a b-tree which is how we efficiently
+represent the state of a room at any past event. See: `m::state` subsystem.
+Note that `m::state` should not be confused with `m::room::state`. The latter
+is the user interface to room state which you are probably looking for; the
+former is the actual implementation of the b-tree and low-level details.
+                    
+
+### Sending & Transmission
+
+The write interface for rooms is aggregated almost entirely in the index
+header `../room.h`. These calls all converge on a single function `commit`
+which sends a partial event to a room via `m::vm` evaluation.
+
+These calls all take a `room` structure as an argument which will be further
+explained in the Reading section. For now know that the `room` argument is
+lightweight and trivially constructed from a `room_id`. It can take a pointer
+to `m::vm::eval` options which offer extensive control over the transmission
+process.
+
+All of the transmitting calls will block an `ircd::ctx` but the extent to
+which they do is configurable via the eval options. All of the calls return
+an `event::id::buf` of the event which they just committed to the room.
+
+Above the lowest-level `commit()` function there are two mid-level `send()`
+suites. One suite creates and sends a state event to the room, the other
+creates and sends a non-state event. The overloads are distinguished by an
+extra state_key argument for the former.
+
+Above the mid-level `send()` suites there is an accumulation of higher-level
+convenience functions, like `message()` and `join()` et al.
+
+### Reading & Access
+
+The rest of these interfaces are read-only interfaces which present aspects of
+the room as efficiently as possible.
+
+##### m::room
+
+The principal structure is `m::room` in `room/room.h`. There are no ways to
+change an actual room through this interface, but an instance can be used with
+calls that do. Instances of `room` are lightweight, maintaining a reference to
+a `room_id` and an optional `event_id`. The data behind those references must
+stay in scope for the duration of the `room` instance. 
+
+When a `room` instance is used either for reading or writing, the `event_id`
+indicates a cursory position in the room to conduct operations. The room will
+be represented at that `event_id`. If no `event_id` is specified, the room
+will be represented at the latest "present" state; note the present state of
+a room is subject to change between calls.
+
+The `room` class interface offers a convenience frontend which brings together
+the basic elements of the `room::messages` and `room::state` interfaces. These
+have different characteristics.
+
+#### Other interfaces
+
+The remainder of `room/` is comprised of specialized interfaces which operate
+efficiently and friendly for their specific purpose.