Self-describing Types & Extensible Models

Stem is an effort to give Seed Hypermedia a smaller, clearer foundation for structured knowledge. The goal is one consistent, linked data model for documents, conversations, schemas, RPCs, workflows, apps and agents, so that each can describe and refer to the others, and so that the same few rules decide what a thing is, who may see it, and how it travels between peers.

This site is the specification of that foundation. It augments the protocol that ships today, which these pages call HM24 and which is documented at The Hypermedia Protocol. Everything that does not change is linked there and not restated here. Everything that changes is defined here, with a Hypermedia Schema attached to every page that defines data or an RPC, and a definition page for every term the specification uses.

The idea

Data should carry, or link to, the context needed to interpret it: what it represents, which schema it follows, and how it connects to other data. Schemas and interface definitions belong in the knowledge system alongside the content they describe. An RPC declares its inputs and outputs; a workflow connects those operations; an agent inspects those definitions to discover what is available. None of this needs a side channel. It is all resources and links, readable with the same tools as any document.

Today Seed already has most of the raw material. Every blob is signed and content-addressed. Hypermedia Schemas are documents that other documents point at. Capabilities are signed statements about authority. Links between blobs are indexed as citations. What is missing is the single runtime model that treats all of these uniformly, instead of one special case per blob type.

Four commitments

One model, few primitives. A resource is a named root whose state is a set of signed blobs. A link is a typed edge from one blob to another, and links drive everything downstream: what a peer must fetch to interpret a resource, what must be kept, what must be applied first, and what evidence authorises what. Schemas, interface definitions, access rules and sync policies are expressed in this same model wherever practical. See The runtime model, Resources and nodes and Links.

Privacy is part of the foundation. Public publishing, private collaboration and local-only work all fit the model. Access rules make clear who can read or change data, and they protect sensitive metadata as well as content, because a private link or a private schema can itself reveal information. Storage and access are separate concerns: a server that holds encrypted data does not need permission to read it. The permissions direction and the Permissions System proposal feed into this.

Sync is selective and governed by explicit policy. Users and applications choose which resources to follow, which peers to exchange data with, what to fetch on demand, and what to keep available offline. Permission to read something does not by itself trigger replication, and sharing one resource does not require sharing a whole space. Policies are inspectable, with clear scope and predictable behaviour. See The sync protocol and the sync cases exercise.

The core stays small as the system grows. New concepts should normally arrive as new schemas and new linked records, not as protocol changes. Protocol changes are reserved for genuinely new underlying capabilities. The test for a proposal is whether people and software can inspect, validate, combine and reuse the result, with deliberate control over access and distribution.

What changes

Stem keeps the signed blob envelope, the Change CRDT, blocks, files, hm:// URLs and the libp2p transport exactly as they are. It replaces the parts of HM24 that mix identity, placement and permission into one path, and the parts of sync that trust any sender.

HM24 today	Stem	Why
Ref, keyed by path, in three shapes	Node, keyed by a stable node id, with a `target` of heads, snapshot, tombstone or redirect	identity, placement and state become separate fields of one blob
Path is identity	Node id is identity: the CID of the node's creating blob, so the mutable URL is `hm://<owner>/<nodeId>`; a path is a chain of names	a move rewrites one blob and every child, comment and grant follows; anyone with `write` on a parent may create nodes there
`generation` and `genesisBlob`	`prev` links between Node blobs of one node	ordering is causal, never by timestamp; ids are never reused
Capability with WRITER and AGENT	Grant and Revocation with sync, read, write and admin, delegation and groups	one statement kind covers membership, sharing, publishing and revocation
`visibility` field, public or private	Audience of a grant, computed readers of a node	public is a grant to everyone; sharing one document needs no new concept
Comment, Profile, Contact as separate blob types	Snapshot state of resources of a kind	one handler reads a kind descriptor instead of one indexer per type
Bitswap fetch of any CID	Fetch, access-checked, authority first, recorded	a peer serves only what the caller may read and remembers that it did
AnnounceBlobs push of arbitrary CIDs	Offer for a claimed scope with proof	nothing enters a peer without a scope it is interested in and authority it can check
Subscriptions plus discovery	A policy resource plus one Sync call	standing interest is data the account's devices share; one API instead of two
`siteUrl` string and an HTTPS lookup	A site relationship signed by both sides	a site's authority over a space is a grant, not DNS

The team's whiteboard called the stable node id an "inode". These pages say node id.

How to read this site

Read The protocol in one page first. Then follow the data model from the Node outward, read Resources, Authority and Privacy for the semantics, and finish with The sync protocol. Whenever a word is unfamiliar, Definitions has a page for it. Implementers should read Database structure, the Sync RPC specification and Migration.

The documents

The protocol in one page: the whole model in a flow, the six decisions, and one worked example.

Definitions: every term, with a page per term that Stem introduces.

The data model: the six signed blob types and the records they produce, one schema page each.

Resource kinds: space, document, comment, contact, file, schema, kind and policy, each as a kind descriptor with its state schema.

Resources and nodes: identity, how state is folded from Node blobs, forgery, versions.

Placement: parents, names, moves, redirects and pretty paths.

Authority: grants, groups, delegation, revocation and the evaluation algorithm.

Privacy: audiences, readers, blob access, disclosures, transfers and uniform denial.

The runtime model: the one handler, facts, links, the stash, re-evaluation and the migration box.

Links: the nine link kinds and what each means for fetching, retention and presentation.

Database structure: every table a Stem daemon keeps, classified as permanent, derived or local.

The sync protocol: scopes, policy, peers, reconciliation, authority-first fetching, offers and watching.

Sync RPC specification: every peer-to-peer and local method, with a schema per method.

Migration: how HM24 blobs become Stem resources inside the indexer.

Worked cases: public multi-space sync, a private space, an externally shared document, a shared schema and a revoked writer, worked through the model.

Agents and notifications: agents, sessions, triggers and notifications as resources.

Open questions: every open question, its status and where it is discussed.

Schemas: every Stem schema with its URL.

Where it comes from

Alexandr Burdiyan's "Seed Resources" whiteboard (tldraw, 6 and 7 October 2026) is the first working session on the unified runtime model for resources, permissions and sync. The documents under Stem convert that board into linked, commentable pages and extend it. The board itself stays the sketchpad: open it in tldraw.

Stem sits on top of direction the team has already decided, recorded in Where this is going: the node and resource redesign (HM26), whole-space capabilities with a group concept, private documents phase two, one sync API, schemas as daemon resources, and a custom CRDT. Stem does not reopen those decisions. It asks what single model makes them cohere, and writes that model down precisely enough to build.

How to contribute

Comment on any page here. Decisions follow the team's usual process: a written proposal, argument, and a decision by technical extenuation. When something is decided it should move into the roadmap, and when it ships it moves into the concept pages.