Part of Stem. This page defines the word resource and fixes how it relates to the words node, kind, state and version.

A resource is a mutable thing with a stable identity, identified by a space and a node id, conforming to one kind, whose current state is computed from the signed Node blobs that declare it.

A resource is what people see and edit: a document, a comment, a contact, a schema, a file, a sync policy, the space itself. Blobs are immutable and named by hash; a resource is the mutable thing that a sequence of blobs describes. The identity of a resource is the pair (space, node id), where the space is an account's principal and the node id is the CID of the Node blob that created the resource, so it is unique by construction and never reused. The pair is written as the mutable URL hm://<owner>/<nodeId>. Its kind is fixed by the first Node blob that creates it and names the kind definition the resource conforms to. Its state is either a graph of Change blobs or a chain of Snapshot blobs, as the kind decides, and a version names one state immutably.

Every resource has exactly one place in its space's placement tree, a parent node and an optional name, except the space root. A resource may be deleted (its Node target becomes a tombstone) or moved elsewhere (a redirect). Both are states of the same resource; the id stays taken. Resources are the things grants speak about, scopes select, policies follow and links point at.

Resource and node

Stem uses two words for one thing seen from two sides. A node is the identity and placement record: the (space, id) pair, the parent and the name, as written in Node blobs. A resource is that node together with its state and kind, as a reader experiences it. "The node bafyrei…r2 has the space root as parent" and "the resource bafyrei…r2 is a document titled Design" are statements about the same entity. The team's roadmap settled on resource for the mutable thing and node for its tree position; Stem keeps both and never uses either for anything else. See Node.

What is not a resource

A blob is not a resource; it is a value. A Grant, a Revocation and a Group are blobs that feed the authority graph and are not nodes: they have no parent, no state and no version. A version is not a resource; it is an immutable name for one state. A link and a fact are derived records, not resources. A peer is not a resource. An account is a key; its space is the tree of resources that key owns, and the space root is the resource that stands for the account.

Where it is used

Resources and nodes gives the rule that computes a resource's state from its Node blobs.

Resource kinds lists the kinds a resource can have.

Subject and Scope select resources for grants and sync.

Node reference is how a resource is named inside other data.

Today (HM24)

The glossary already uses resource as the umbrella word for "anything mutable that is rebuilt from immutable blobs", and the Resources RPC returns a document, a comment or a contact. But the identity of a document is its path (a Ref row keyed by hm://space/path), a comment's identity is its author plus a TSID, and a profile has no identity record at all. Stem gives all of them the same identity, (space, node id), and the same declaring blob.

Resource and node

What is not a resource

Where it is used

Today (HM24)

See also