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
heads	the state is a Change graph with these heads	Change blobs
snapshot	the state is one complete value	a Snapshot blob
tombstone	the resource is deleted	nothing new
redirect	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 --> F

Every 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 `heads`
Ref tombstone (empty heads)	Node with target `tombstone`
Ref redirect	Node with target `redirect`
Ref `generation`, `genesisBlob`	gone: a node id is the CID of its creating Node blob, so an id has exactly one life and is never reused
Ref `visibility`, Comment `visibility`	Grants with audience `everyone` or narrower, and the Node `access` mode
Capability	Grant
Comment	unnamed Node of kind comment with a Snapshot
Profile and home document	the space root node of kind space
Contact	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:

Node, with target (heads, snapshot, tombstone, redirect) and access.

Change and Snapshot.

Grant, Revocation, Group.

Any Stem blob, the union.

Values used inside blobs:

node id, name, node reference, version, peer id.

access level.

audience: everyone, key, group, bearer, readers.

subject: node, group.

Definitions that drive the daemon:

Kind and link rule; the kinds themselves are listed in Resource kinds.

scope and policy rule.

Derived records (never signed, computed by the indexing peer):

link and link kind, fact.

disclosure, basis, transfer.

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.

How a resource is specified

What this replaces

The pages

Conventions shared by every page

See also