Part of Stem. This page defines path and pretty path, the two URL forms Stem adds to the hm:// grammar, and how a URL is resolved to a node.
A path is the slash-joined sequence of names from the space root to a node, read off the placement tree; it is derived from Node blobs, it can change, and it is never a node's identity.
A pretty path is the same thing said from the user's side: a readable address like /projects/design that a space owner is free to arrange and rearrange. Because paths are derived, two peers that hold the same Node blobs compute the same paths, but a path may name different nodes at different times and some nodes have no path at all.
URL forms
Stem adds one segment form (a node id as the first segment) and one query parameter (n) to the URL grammar; everything else is unchanged. Because a node id is a CID string and a name may not be one, the two never collide.
Form | Example | Meaning |
|---|---|---|
space |
| the space root |
node |
| the mutable URL of the node with that id; a first segment that is a CID ( |
pretty path |
| the node reached by following names top down |
full context |
| the pretty path, the node id, a version and a block; what writers emit |
facet |
| a facet of a node, with the spelling HM24 already uses |
legacy |
| an HM24 path, which resolves through migrated names |
Resolution
Given a URL, a peer resolves it to a node in this order:
If the URL has n, or its first segment is a node id, look up the node with that id in the space. If it exists and the caller may read it, that is the node, and the pretty path in the URL is informational.
Otherwise follow the pretty path: starting at the space root, for each segment pick the child whose head Node blob declares that name. When several children declare the same name, pick the one whose creating Node blob has the lowest CID; this is deterministic, and clients should surface the collision.
If the node found by n and the node found by the path differ, the node from n wins and the client may warn that the link's path is stale.
If a resolved node's head target is redirect, follow to, up to five hops and never in a cycle.
Otherwise the URL does not resolve. A peer answers the same way for a node that does not exist and for one the caller may not read.
Legacy HM24 URLs resolve by step 2, because migration gives every migrated node its last path segment as its name under the migrated parent chain.
Writing links
A writer records as much context as it has: the pretty path for people, n for identity, v when the link is to a specific version. The link the handler derives from such a URL carries the node reference, so backlinks and mentions follow the node when it moves. A link written with a pretty path only still works until the path changes, and then works again if the owner leaves a redirect.
Where it is used
Placement: the full rules for names and redirects.
Node reference: the data form of a resolved link.
Migration: how legacy paths become names.
Today (HM24)
A path is identity, placement and permission scope at once, and the Ref for a path carries its generation, its heads and its visibility. The roadmap decided that pretty paths become the space owner's responsibility, served by a redirect layer, and that links carry node id plus path with a fallback order. Stem keeps the redirect inside the permanent data as a Node target, because a redirect is just another state a node can be in, and makes the fallback order the one above.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime