Part of Stem. This page defines placement and the placement tree, and separates them from identity and authority.

Placement is the pair (parent, name) that a node's head Node blob declares: the node it sits under and the optional relative name it has there. The placement tree of a space is the tree those parent pointers form under the space root.

Placement answers two questions: where does this resource appear in the sidebar, and what pretty path reaches it. It answers nothing about identity and nothing about who may read or write. Identity is the node id. Authority is the authority graph. The team's phrase for this separation is that the authority graph is critical and the placement graph is for naming and addressing.

Parent

Every node except the space root names a parent in the same space, by its node id; top-level nodes name the root id. The parent must exist (its creating Node blob must be indexed) before a child's Node blob is applied; a child that arrives first is stashed. A node may not be its own ancestor: a Node blob that would create a cycle is rejected. Creating a node under a parent requires write on that parent, whoever the signer is: a key holding such a grant creates nodes in another owner's space by setting space to the owner. Moving a node to a new parent requires write on the node and on the new parent.

Placement interacts with authority in one way: a grant whose subject is a node covers, by default, the node's whole subtree. So a reader of a folder reads what is placed under it, and a writer of a folder may create under it. Moving a node into a folder therefore changes who may read it, which is why the move needs write on the destination. Moving a node out of a folder does not revoke anything granted on the node itself.

Name

A name is one path segment, as constrained by Name. Names are chosen by writers and the protocol does not make them unique; two nodes under one parent may declare the same name, concurrently or not. Resolution of a name to a node is defined in Path. A node with no name is unnamed: it is reachable by id only, appears in listings only where the client chooses to show unnamed children (comments are not shown as children of the document they target; they are children of the author's root), and has no pretty path.

Moves

A move is one Node blob: same id, new parent or new name, prev naming the previous head. Nothing else changes. Children keep pointing at the moved node's id, so the whole subtree moves. Comments keep targeting the id. Grants keep naming the id. Full-context links keep resolving through n. A client may additionally leave a redirect behind: a new node at the old place whose target is redirect to the moved node, so that pretty-path links written without n keep working. The redirect is optional, which is what makes the move a one-blob operation.

Where it is used

Node blob: the parent and name fields.

Placement: the full rules for moves, renames, redirects and pretty paths.

Scope: depth children and subtree walk the placement tree.

Today (HM24)

A document's placement is its path, which is also its identity and the scope of its capabilities. The path of a child repeats the names of its ancestors, so a parent cannot be renamed without republishing every descendant; the team called this unreliable, and the app's "reliable document references" project exists to paper over it. Stem makes placement two fields of one blob.

Parent

Name

Moves

Where it is used

Today (HM24)

See also