HM26
Draft resource and authority schemas, with decisions and unresolved protocol choices.

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 resource.schema.json; the separate signed change type is change.schema.json. Every resource variant extends base-resource.schema.json (BaseResource); BaseResource 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. BaseResource owns optional resource, parent, and name. Names and field spellings are provisional.

Stable resource identity is the CID of the initial resource blob. The initial statement omits resource 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.

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

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

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

    tombstone: optional prev breadcrumb.

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

    republish: BaseResource-only placeholder. Payload, behavior, and whether a previous-resource 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 resource 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. Resource 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 resource 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 states 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-state derive truth from their change DAG. How redeclarations interact with later DAG roots or concurrent variants remains open. Utility states are never authoritative.

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

BaseResource, placement, and inherited envelope

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

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

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

The existing HM26 roadmap (hypermedia/protocol/roadmap.md in the Seed repository) records a parent as a space plus resource ID. This draft represents space as the existing principal bytes type and parent resource 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 resource, 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: BaseResource extends hm://hyper.media/blob, and each resource variant extends BaseResource. BaseResource defines no stored type override or fixed resource type tag. Required kind selects the six closed resource variants. BaseResource remains a common structural schema, not a seventh resource union variant.

Residual envelope requirement: the existing signed Blob schema requires a stored type string. BaseResource still inherits that field, so any string satisfies this structural constraint and omission still fails validation. Removing the BaseResource 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 resource variants. This is an explicit provisional modeling choice, not a decision that capability resources can never be represented as resources. 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.

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.

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.

Learn this in the sync playground

Sync playground extension · 2026-10-23. Teaching prototype; no production protocol or schema adoption.

Start with the graph-reading guide, then follow a single exchange and inspect its local SQL effects. The playground is a second, explicitly experimental synchronization design alongside the earlier tentative RPC contract. It does not change the published resource or capability schemas.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Comments