Part of Stem. This page is the index of the low-level data: every signed blob and every derived record that Stem defines, each with a Hypermedia Schema attached to its own page. It starts with the one question the model answers: how is a resource specified?
How a resource is specified
A resource is a mutable thing with a stable identity. Everything about it is carried by immutable blobs, signed and named by their CID exactly as today. Stem reduces the ways of specifying a resource to one blob type with four targets.
The Node blob says what the resource is (space, id, kind), where it sits (parent, name), who may read it (access) and what its state is (target). The target is one of four:
target | meaning | state lives in |
|---|---|---|
the state is a Change graph with these heads | Change blobs | |
the state is one complete value | a Snapshot blob | |
the resource is deleted | nothing new | |
the resource lives elsewhere | the target node |
So there are exactly two state representations. A Change graph is for documents, where edits are small deltas merged by the CRDT described in Documents. A Snapshot is for everything whose edit replaces the whole value: comments, contacts, schemas, kinds, files and sync policies. Which one a resource uses is declared by its Kind.
Authority is carried by three more blob types. A Grant says that an audience holds an access level over a subject. A Revocation cuts a grant. A Group is a permanode that gives a set of principals one name.
flowchart LR
N[Node] -- heads --> C[Change]
C -- deps --> C
N -- snapshot --> S[Snapshot]
S -- prev --> S
C -- deps --> S
N -- prev --> N
N -- parent --> N2[Node]
N -- redirect --> N3[Node]
N -- proof --> G[Grant]
G -- proof --> G
G -- subject/audience --> GR[Group]
R[Revocation] -- grant --> G
S -- files --> F[UnixFS / raw]
C -- files --> FEvery arrow is a typed link that the handler emits when it indexes the blob. Sync, retention and audience evaluation read the links, not the blob types. That is what lets the daemon treat a document and a sync policy with the same code.
What this replaces
Today's protocol (HM24) has six signed blob types with one indexing path each. Stem keeps the envelope, the Change layout and the file blobs, and replaces the rest:
HM24 | Stem |
|---|---|
Ref with heads | Node with target |
Ref tombstone (empty heads) | Node with target |
Ref redirect | Node with target |
Ref | gone: a node id is the CID of its creating Node blob, so an id has exactly one life and is never reused |
Ref | Grants with audience |
Grant | |
unnamed Node of kind comment with a Snapshot | |
Profile and home document | the space root node of kind space |
unnamed Node of kind contact with a Snapshot | |
TSID identity for comments and contacts | node id |
nothing | Group, Revocation, Snapshot, Kind, policy, disclosure, transfer |
The old blobs stay valid. The migration page says how the indexer converts each of them.
The pages
Signed blobs:
Grant, Revocation, Group.
Any Stem blob, the union.
Values used inside blobs:
Definitions that drive the daemon:
Kind and link rule; the kinds themselves are listed in Resource kinds.
scope and policy rule.
Conventions shared by every page
Every signed blob extends the library envelope blob: type, signer, sig, ts. Signing, hashing and encoding are unchanged from Signed blobs. Optional fields are omitted, never null. Lists of CIDs are sorted by CID. Timestamps are advisory everywhere: no rule in Stem orders two blobs by ts. Unions are discriminated by a pinned literal (type for blobs, kind for targets, audiences, subjects and bases). Every schema here is written in the Hypermedia Schemas language and bound to its page through schemaDefinition, so the Seed app can show each type and validate instances of it.
See also
Resources and nodes: how a node's state is computed from its blobs.
Resource kinds: the kinds Stem ships with.
Every Stem schema: the flat list with URLs.
Signed blobs: the envelope and encoding, unchanged.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime