Changes to the Seed Hypermedia Protocol must be deliberate, documented, and technically justified. The permanent data model is the foundation of our network.
Protocol changes that impact it follow a formal process.
If you need to deliver a new feature, first try building it at the application layer without modifying permanent data. Only proceed with this process if the change permanently affects how peers store, sync, or interpret data.
Scope
A Protocol Change is any modification that alters:
The structure or semantics of permanent data (documents, changes, DAGs, CRDTs).
The synchronization protocol or message formats exchanged between peers.
The capabilities model or identity and signing systems.
Any on-disk or over-the-wire representation that must remain interoperable.
If a change can be done purely within application logic or client interfaces, it does not require this process.
Goals
Preserve backward compatibility and data permanence.
Maintain a clear history of reasoning behind protocol evolution.
Base decisions on technical arguments, not popularity.
Keep the protocol small, stable, and explicit.
Process Overview
Stage 1 — Request for Comments (Seed-RFC)
Open a new document in the protocol.hyper.media Site under /rfcs/.
Follow the format:
Title: Seed-RFC-XXXX: Short Title
Summary
Motivation / Problem Statement
Proposed Change
Compatibility and Migration Plan
Alternative Solutions Considered
Open Questions
The goal is to expose reasoning early, not to finalize design.
Stage 2 — Argumentation Mapping
Each RFC becomes a knowledge repository for its debate.
Use clear claims, counter-claims, and supporting evidence.
Prefer structured reasoning with links and transclusions instead of linear comment threads.
Encourage related documents to link directly to arguments.
Preserve the entire debate in hypermedia form.
Stage 3 — Technical Review and Decision
Review is conducted by a Protocol Working Group (PWG):
Typically 2–5 engineers who understand the core stack.
External reviewers may be invited.
Decisions are not by consensus, but by technical merit.
At the end of deliberation, the PWG publishes a Decision Note documenting:
Accepted / Rejected / Deferred
Rationale
Required implementation or migration work
Stage 4 — Specification and Documentation
Accepted changes are applied to:
Protocol Buffers / Type definitions
Synchronization or capability specifications
CRDT schema and entity definitions
All updates must be reflected in the canonical documentation at: hyper.media/specs/protocol
Versioning rules:
v1alpha → v1beta → v1
Breaking changes only between major versions.
Stage 5 — Implementation and Validation
Implement in a feature branch.
Validate interoperability between peers running different protocol versions.
Add automated tests or fixtures verifying old data remains valid.
Once validated, tag a new protocol version and release notes.
Stage 6 — Archival
Every RFC and Decision Note remains permanently available.
New RFCs must link back to previous documents they amend or replace.
This creates a transparent lineage of protocol reasoning.
We aim to minimize protocol churn and extend the protocol only when necessary. Any breaking change must be handled explicitly — no silent migrations. The specification must always live in canonical form on hyper.media, ensuring that peers share a single, unambiguous source of truth.
Every decision must remain transparent and traceable, linkable back to its reasoning and supporting arguments. Changes are adopted on the strength of their technical merit, not by popularity or consensus.
The Seed Hypermedia Protocol defines the shared substrate of our system.
Treat it as a living constitution: slow to change, clear in intent, and grounded in technical truth.