HM26 resource schemas — draft

Status: reviewable design draft, 2026-10-14. These schemas do not change the shipped HM24 protocol, registry, lockfile, or runtime. The hidden .drafts directory is intentionally excluded by the existing library enumeration and sync. References under hm://hyper.media/.drafts/hm26/ are local draft names, not claims that these names have been published. Publication must rewrite draft references to the approved destination or immutable schema CIDs.

The resource union is node.schema.json; the separate signed change type is change.schema.json. Every node variant extends base-node.schema.json (BaseNode); BaseNode extends the existing signed blob envelope (type, signer, sig, ts), including its signing rule: canonical DAG-CBOR with sig zeroed to 64 bytes before signing. BaseNode owns optional node, parent, and name. Names and field spellings are provisional.

Stable node identity is the CID of the initial node blob. The initial statement omits node and takes its own CID as identity; every later statement specifies that initial CID. The structural schema cannot prove initialness or CID relationships. Among authorized statements, higher ts selects the newer statement. Authorization and equal-timestamp tie-breaking remain open; signing alone does not settle authority.

snapshot: authoritative full-state redeclaration, with optional prev pointing to the previous node-version CID.

changes: state derives from the DAG named by heads and the exact immutable apply function. No prev field is accepted.

changes-snapshot: same DAG-derived truth, with a utility snapshot. On mismatch history wins. No prev field is accepted.

tombstone: optional prev breadcrumb.

redirect: optional prev breadcrumb, with provisional destination node identity in target.

republish: BaseNode-only placeholder. Payload, behavior, and whether a previous-node link is allowed remain open. Its current closed schema rejects prev; that does not decide eventual republish semantics.

The six variants are closed maps discriminated by required kind. History links are breadcrumbs, not authorization or guaranteed secrecy. Omitting a node history link does not hide accessible change DAG history. Tombstone visibility, revival, redirect resolution, and cross-variant transitions require semantic rules beyond these shapes.

A Change has an explicit deps list supporting multiple ancestors (empty for a root), and an ordered ops list. Node heads must be nonempty. Dependencies and heads are CID links; their target types, availability, cycles, ownership, and duplicate policy need semantic validation. HM26 provisionally requires a deterministic order across the change DAG; the exact order is TBD. HM24 is a reference, not a claim that ordinary sequential operation replay replicates its CRDT semantics. List order preserves operations within each change but does not settle DAG linearization or merge behavior.

Every change-bearing node must specify an exact immutable operation-application function as apply. Its representation is provisionally a CID link; executable format, runtime, inputs, initial state, compatibility, determinism contract, and verification remain open. State and utility snapshots provisionally accept any IPLD value, including a link. Operations also provisionally accept any IPLD value. These choices expose undecided content shapes rather than inventing a document/block model. The existing any schema includes all nine IPLD kinds; the narrower existing value schema is unsuitable here.

Full-state redeclarations are authoritative; change-only and change-with-snapshot derive truth from their change DAG. How redeclarations interact with later DAG roots or concurrent variants remains open. Utility snapshots are never authoritative.

Alex's offline notes and Excalidraw have not been supplied or incorporated. No assumptions about their contents are encoded here.

BaseNode, placement, and inherited envelope

The inheritance hierarchy is Blob → BaseNode → each of the six node variants. The separate Change type still extends Blob directly. BaseNode defines optional node (initial node CID), optional parent, and optional name (string). Both change-bearing variants still reject prev; it is absent from BaseNode and appears only on snapshot, tombstone, and redirect.

Parent is provisionally a closed struct with two required fields when present:

{
  "space": { "/": { "bytes": "<base64 principal key bytes>" } },
  "node": { "/": "<initial parent-node CID>" }
}

The existing HM26 roadmap (hypermedia/protocol/roadmap.md in the Seed repository) records a parent as a space plus node ID. This draft represents space as the existing principal bytes type and parent node identity as cid. The exact parent representation is provisional. It does not establish authority, grant permissions, or settle moves between spaces. A single parent struct allows at most one parent in each statement. Optional parent reflects the current requested shape; whether absence means root, detached node, or another placement condition remains open.

Name and parent placement construct paths. name is an optional string; this draft deliberately does not choose segment restrictions, escaping, empty-name meaning, duplicate-name resolution, path canonicalization, or behavior when either placement field is absent. Renaming or moving a parent should be interpreted through placement links; exact resolution behavior remains to be designed. Placement does not by itself determine authorization.

The outer schema type expresses inheritance: BaseNode extends hm://hyper.media/blob, and each node variant extends BaseNode. BaseNode defines no stored type override or fixed node type tag. Required kind selects the six closed node variants. BaseNode remains a common structural schema, not a seventh resource union variant.

Residual envelope requirement: the existing signed Blob schema requires a stored type string. BaseNode still inherits that field, so any string satisfies this structural constraint and omission still fails validation. Removing the BaseNode override does not remove the inherited field. Whether the HM26 protocol should also eliminate this stored field requires a separate envelope design decision; no replacement dispatch mechanism is proposed here and the shipped Blob schema is unchanged. The separate Change, capability, and revocation type literals remain their own provisional proposals.

Capability and revocation drafts

The current capability/revocation drafts are described in Authority-chain design notes. Confirmed HM26 decisions: exactly reader, writer, and irrevocable admin; irrevocable admins may grant irrevocable admin to another key; admin grants and their admin ancestry cannot be revoked; reader/writer grants can be revoked only by an admin authorized for the same scope, with no independent issuer revocation right. Irrevocable admin is intended to let validators establish an admin chain without checking admin revocation state. Other authorization and revocation policies remain open.

Capability authority statements and revocation statements currently extend Blob directly, separately from the six mutable node variants. This is an explicit provisional modeling choice, not a decision that capability resources can never be represented as nodes. The authority graph must remain separate from placement. No shipped capability schemas, daemon code, or real grant/revocation instances are changed or published.

Validate locally with direnv exec . node hypermedia/.drafts/hm26/validate.mjs. This uses the existing reference validator and meta-schema, checks all draft shapes, accepts all six variants, and checks rejection of forbidden history links and malformed changes. It also checks the confirmed admin-ancestry and admin-only revocation invariants against synthetic linked fixtures. It does not verify signatures, CID contents, full authorization, ordering, or execution.

Publication authorized under production Starlight at hm26 on 2026-10-14. All thirteen schema pages and the overview are published; publication.json records page URLs and immutable schema CIDs. Published union references use the Starlight destination; source-file references remain local draft names.

Schemas

node-changes-snapshot

Understanding HM26 permissions

A concrete tentative sharing policy, its lifecycle and its most consequential tradeoffs.

Understanding HM26 syncing

The chosen tentative peer exchange, indexing pipeline and everyday syncing procedures.

HM26 tentative decisions and remaining alternatives

The concrete chosen assumptions, their consequences, and the decisions needed before implementation.

HM26 research sources and disagreements

Coverage, the latest Alex Burdiyan material, primary prior art, and code worth reusing.

Research reading order

These guides explain permissions and syncing, distinguish current decisions from proposals, and record the latest public Alex Burdiyan and team material reviewed on 2026-10-14.

Understanding permissions

Understanding syncing

Decisions still needed

Sources, coverage and disagreements

HM26 tentative authority model

A concrete first implementation policy for roots, grants, revocation, historical state and service custody.

HM26 tentative syncing workflows

End-to-end algorithms for cold and warm reads, publishing, initial sync, change delivery, revocation and live republishing.

HM26 tentative peer RPC contract

Concrete peer methods, authentication, allowed sets, cursors, block transfer, durable offers and resumable watches.

HM26 tentative SQLite node index

Concrete source and derived tables, authority evaluation, allowed-set queries, transactional invalidation and recovery.

Operational design proposal

The guides now choose tentative assumptions and specify end-to-end workflows, peer messages and a transactional SQLite index. These are reviewable recommendations, not implemented protocol rules or changes to the published schemas. In particular, current-standing writer authorization can roll selected state back on revoke and revive statements on regrant; historical adoption alternatives remain important.

Tentative authority model

Reading, publishing, first sync, change delivery and revocation

Peer RPC contract and candidate protobuf

SQLite node index, evaluator, queries and validation