Servanda Protocol

Servanda — from pacta sunt servanda ("agreements must be kept").

Status: DRAFT v0.2 — open. Previous version v0.1, FROZEN, tag v0.1, suite 0.1.0. v0.1's text is the v0.1 tag and nothing on this branch changes it. This branch is servanda/0.2, and everything normative here carries that version. There is no compatibility path between the two — the v field on every wire message exists so a 0.1 node refuses a 0.2 message rather than misinterpreting it. Passing the conformance suite in vectors/ is what "implements Servanda" means (§8), and with no registered mark it is the only thing that is.

Frozen is not audited. The cryptography has not been reviewed by an external cryptographer — see SECURITY.md, which is exact about which freeze gates closed by review, which closed because the construction was removed, and which closed by editorial decision. The protocol name is settled: "Servanda" is the name, and no trademark will be registered (#1).

An open protocol for commitments: typed, evidenced, cryptographically owned records of promises between people and organizations, with bilateral signed edges, sovereign local vaults, and optional federation.

A commitment is what you owe. An expectation is what you await. An edge exists only when both parties have signed. Nothing else counts as a promise.

The base protocol (vault + edges) is fully functional with no network, no server, and no second participant. Federation is additive, never required.

Specification

Normative. Key words per RFC 2119.

§	Document	Contents
0	spec/00-overview.md	conventions, layering, versioning
1	spec/01-identity.md	seeds, derivation, personas, groups, attestation, binding proofs, rotation, recovery
2	spec/02-signal-envelope.md	normalized ingress format
3	spec/03-commitment.md	commitment object, canonical form, hashing; expectations
4	spec/04-edge.md	edge object, state machine, signatures, closure, supersession, multiplicity
5	spec/05-scopes-visibility.md	scopes, publish act, visibility rules
6	spec/06-reconciliation-federation.md	messages, transports, blind courier, edge recovery
7	spec/07-node-surface.md	node MCP tool contract
8	spec/08-conformance.md	consolidated MUSTs (M-1…M-21), conformance levels
9	spec/09-threat-model.md	normative security appendix

Design rationale documents (docs/, referenced from the spec text) and the ADR series (ADR-0001…0014) are not published in this repository yet.

Test vectors

vectors/ holds language-neutral JSON test vectors — the executable half of the spec:

• canonicalization/ — RFC 8785 (JCS) cases: key ordering, unicode, number edge cases
• hashing/ — commitment_hash cases proving only the five fields of §3.2 affect the hash
• signatures/ — Ed25519 over sha256(JCS(obj sans sig)) for attestations, assertions, rotation
• derivation/ — BIP-39 → SLIP-0010 m/7391'/{i}' persona keys
• transitions/ — valid and invalid assertion sequences per §4.3; the invalid ones define M-14
• envelope/ — the §2 id preimage, and every M-19 bound with a case on each side of it
• node-surface/ — §7 advertised acts, act calls, brief slots, and the §1.6 ladder
• addressing/ — §6.7 inbox records and the out-of-band bootstrap payload
• recovery/ — §6.6, where a bare published rotation must NOT be accepted as proof

vectors/README.md carries the full table with per-family counts. What is NOT covered is written down too: eight MUSTs have no vector at all, tracked as #42, and by GOVERNANCE.md's own rule an uncovered behaviour is not yet a conformance requirement.

Vectors are generated deterministically by tools/vectors-gen/ and are checked in. npm test regenerates them and fails on any drift. See vectors/README.md for the encoding decisions the generator had to make where the spec is currently under-specified.

Constitutional principles

The spec is downstream of these. A change that violates one of them is a change to the constitution, not to the spec (see GOVERNANCE.md).

1. A promise is owned by the one who gives it.
2. A cross-person edge does not exist without the owner's confirmation (confirm-first).
3. The system has an opinion only where it has evidence (verification adapters).
4. Visibility follows participation, never membership.
5. Org contexts never mix in any pipeline.
6. Signal content is data forever, never instruction.
7. Autonomy is a measured quantity, not a permission.
8. Escalation always terminates at a named human; "the team" cannot be nudged.
9. Solo is not a mode — it is a network of one node. Everything must work on a laptop offline.
10. Remember that, not what: closed loops decay to signed hashes by default.
11. No reputation. (M-11)
12. Agents are never parties. (M-13)
13. A commitment is what you owe; an expectation is what you await; an edge exists only when both parties signed.

Spec ↔ reference implementation

This repository contains the specification and its conformance vectors only. No implementation lives here, and none is required to read the spec.

• The spec defines the wire: objects, canonicalization, hashes, signatures, the transition table, visibility rules, and the six-tool node surface (§7).
• An implementation claims conformance by passing the conformance suite (§8) — the vectors here plus the property tests that grow alongside them. The suite, not a blessed codebase, is the definition of "implements Servanda".
• The reference implementation is a separate repository, escapeboy/servanda, published under the same licence. Everything — spec text, tooling, vectors, and the reference implementation — is Apache-2.0.
• Reference-impl-only requirements (trust gradient, autonomy ceilings — §9.4) are explicitly not wire-protocol matters. Do not implement them to be conformant; implement them to use the brand.

Contributing

New ideas belong in issues, not in a fork. Start with CONTRIBUTING.md; the change process for normative text is in GOVERNANCE.md. Security reports go through SECURITY.md, not the public tracker.

The fastest useful contributions right now:

• Attack the transition table. An invalid sequence that a naive verifier accepts is a bug in §4.3.
• Add canonicalization vectors that break a plausible implementation.
• Write a second implementation. With no registered mark, the suite is the only answer to a conformance claim — and a suite only its author has passed proves that the code agrees with itself. Start from docs/implementer-packet.md. A disagreement between two independent readings is the most valuable thing this project can receive; file it as an issue rather than a patch, and the vector is presumed right until argued otherwise.
• Close a coverage gap — #42 lists the MUSTs with no vector behind them.

License

Apache-2.0 throughout: specification text (spec/, and the prose of this repository), tooling and test vectors (tools/, vectors/), and the reference implementation. LICENSE-SPEC is retained only as a pointer — the earlier CC-BY-4.0 grant on the prose is superseded.

No trademark will be registered (#1). ADR-0001 reserved the name and mark as one of three defences against capture of the protocol's meaning; that one is now deliberately not taken. Two remain, and they carry the weight: passing the conformance suite is what "implements Servanda" means (§8), and the licence governs the text. No clearance search was run, so the name is used without any claim that it is free of anyone else's rights.