Part of Stem. This page defines the word node and distinguishes a node (a position in a space) from a Node blob (a signed declaration about that position).

A node is a resource's identity and place in a space: a stable node id, which is the CID of the Node blob that created it, exactly one parent node, and an optional name, as declared by the creating blob and by the later authorized Node blobs that carry that id.

Nodes form a tree per space. The tree has one root, the space root, which every other node descends from through its parent. A node is both a directory and a file: it may have children and it has a state of its own. There are no hard links, because a node has exactly one parent. A node may be unnamed, which is how private documents and comments exist without a human-readable path.

The node's id is fixed the moment the node is created: it is the CID of the creating Node blob, so nobody chooses it and nobody can pick an id that is already taken. The creating blob carries no id; every later Node blob for the node carries that CID in id, exactly as a Change carries its genesis. The resource's mutable URL is hm://<owner>/<nodeId>. The parent and the name may change; that is a move or a rename, and it is one new Node blob. Children reference the parent's id, not its name, so a move of a parent moves the whole subtree without touching a single child blob. Grants reference node ids too, so authority moves with the node.

Node and Node blob

A Node blob (schema) is a signed statement about a node: who declares it, what kind it is, where it sits, what its state is, and which earlier statements it supersedes. A node is the thing those statements are about. One node accumulates many Node blobs over its life: one that creates it, one per change of heads, one per move, one tombstone. The fold reads the authorized Node blobs for an id and computes the node's current placement and state.

Creation and forgery

A Node blob with no id creates a node, and its own CID becomes the node's id. It is authorized when its signer holds write on the parent it names, or is the space owner. Any key with such a grant may create nodes in another owner's space: it sets space to the owner, and the owner signs nothing. A Node blob that carries an id updates an existing node: the creating blob with that CID must be known (the id is a dep link, so it is fetched first), the signer must hold write on that node, and the blob must name the same kind as the creating blob. So a writer invited to one subtree cannot claim a node that belongs to another part of the space, cannot invent an id, and cannot change what kind of thing a resource is. See Node id.

Where it is used

Node blob: the blob that declares a node.

Placement: parents, names and the tree.

Readers: the audience computed per node.

Subject: a grant covers a node and, by default, its subtree.

Today (HM24)

A document is identified by its path, and a path is a chain of names, so the child of /cars is /cars/ford and carries the name cars inside its own Ref. Renaming cars means republishing every descendant with a new Ref and a redirect. The roadmap's node and resource redesign decided that every mutable thing becomes a node with a stable id and one parent. Stem is that decision written down: the node id is identity, the parent is placement, and the name is a label.

Node and Node blob

Creation and forgery

Where it is used

Today (HM24)

See also