Models
======

Client
------

Server
------

Events
------
An event is a collection of data (the `payload`) and metadata associated with
it to be distributed across servers and is the primary data unit in Matrix.
Events are extensible so that clients and servers can add extra fields to the
payload or metadata that are not in this specification.

Events are distributed to interested servers upon creation. Historical events
may be requested from servers, though servers are not required to produce all
or any events requested.

All events have a metadata `type` field that is used by client and servers to
determine how the payload should be processed and used. There are a number of
types reserved by the protocol for particular uses, but otherwise types may be
defined by applications, clients or servers for their own purposes.

Graph
~~~~~
Each event has a list of zero or more `parent` events. These relations form
directed acyclic graphs of events, called `event graphs`. Every event graph has
a single root event.

Event graphs give a partial ordering of events, i.e. given two events one may
be considered to have come before the other if one is an ancestor of the other.
Since two events may be on separate branches, not all events can be compared in
this manner.

Every event has a metadata `depth` field that is a positive integer that is
strictly greater than the depths of any of its parents. The root event should
have a depth of 1.

[Note: if one event is before another, then it must have a strictly smaller
depth]

Integrity
~~~~~~~~~
Portions of events will be signed by one or more servers or clients. The parent
relations, type, depth and payload (as well as other metadata fields that will
be specified) must be signed by the originating server. [Note: Thus, once an
event is distributed and referenced by later events, they effectively become
immutable].

The payload may also be encrypted by clients, except in the case where the
payload need to be interpreted by the servers. A list of event types that
cannot have an encrypted payload are given later.


State
-----
Event graphs may have meta information associated with them, called `state`.
State can be updated over time by servers or clients, subject to
authentication.

The state of a graph is split into `sections` that can be atomically updated
independently of each other.

State is stored within the graph itself, and can be computed by looking at the
graph in its entirety. Thus we can define the state at a given event to be the
state of the sub graph of all events "before" and including that event.

Some sections of the state may determine behaviour of the protocol, including
authorization and distribution. These sections must not be encrypted.

State Events
~~~~~~~~~~~~
`State events` are events that update a section of the state of a graph. These
state events hold all the same properties of events, and are part of the event
graph. The payload of the event is the replacement value for the particular
section of state being updated.

State events must also include a `state_key` metadata field, which in
conjunction with the type field defines the section of state that is to be
updated.

State Resolution
~~~~~~~~~~~~~~~~
A given state section may have multiple state events associated with it in a
given graph. A consistent method of selecting which state event takes
precedence is therefore required. 

This is done by taking the latest state events, i.e. the set of events that
either incomparable or after every other event. A state resolution algorithm is
then applied to this set to select one.

The state resolution algorithm must be transitive and not depend on server
state, as it must consistently select the same event irrespective of the server
or the order the events were received in.

State Dictionary
~~~~~~~~~~~~~~~~
The state dictionary is the mapping from sections of state to the state events
which set the section to its current value.  The state dictionary, like the
state itself, depends on the events currently in the graph and so is updated
with each new event received.

Since the sections of the state are defined by a pair of strings that came from
the type and state_key of the events that update them, the state dictionary can
be defined as a mapping from the pair (type, state_key) to a state event with
those values in the graph.

Deleting State
~~~~~~~~~~~~~~
TODO