Part of Stem. This page defines state and its two representations, and fixes the meaning of deleted and redirected.

The state of a resource is the value obtained by taking the targets of its head Node blobs and, for a Change target, replaying the Change graph from its genesis to those heads, or, for a Snapshot target, reading the Snapshot's value.

A resource's state is never stored as such. It is computed, by the same rule on every peer, from signed blobs. The Node blob's target says where the state is. The fold says which Node blobs count and how concurrent ones merge.

The two representations

Change graph. The target is heads, a sorted list of Change CIDs. The state is the result of replaying every Change reachable from the heads through deps, in causal order, with the two CRDTs described in Documents: one for attributes, one for the block tree. Documents and the space root use this representation. Its strength is that concurrent edits by several writers merge without anyone resolving anything, and every paragraph keeps its author.

Snapshot. The target is snapshot, the CID of one Snapshot blob whose value is the whole state, validated against the schema the kind names. Comments, contacts, schemas, kinds, files and policies use this representation. Its strength is that the state is one blob: cheap to fetch, cheap to validate, and trivially the same on every peer. Edits replace the value; the new Snapshot lists the old one in prev.

A kind says which representation its resources use. The two can meet: a Change may list a Snapshot in deps, which is how a document can be continued from a signed snapshot once the custom CRDT the team plans makes snapshots of Change graphs possible.

Deleted and redirected

A resource whose head Node target is tombstone is deleted: its state is empty, its name is free for another node, its id stays taken, and every earlier version stays retrievable by version. A resource whose head target is redirect has no state of its own: readers are sent to the node named by to, and with republish the redirecting node shows that node's state under its own name. Both are states of the resource, folded by the same rule as any other.

Version

A version is the immutable name of one state: for a Change graph the sorted head CIDs joined with ., for a Snapshot its CID. It is the value of ?v= in an hm:// URL and the version field of a node reference. Given a version a peer can rebuild exactly that state, forever, without consulting any Node blob.

Where it is used

Resources and nodes: the fold that selects heads and merges them.

Kind: the state and schema fields.

Fact: indexed statements read from the state.

Today (HM24)

A document's state is the Change graph behind a Ref's heads, exactly as in Stem. A comment, contact or profile is a "snapshot blob" whose newest version by timestamp wins, with identity by TSID or by key. Stem keeps the Change representation unchanged and turns the snapshot blobs into one Snapshot type whose ordering comes from prev, not from timestamps.

The two representations

Deleted and redirected

Version

Where it is used

Today (HM24)

See also