Reference snapshot · source revision 7a2e36f2b250934a095e542ae20e62dcfb0d5f70

SPEC-CONVENTIONS — shared vocabulary for the SPEC-*.md corpus

Status: Normative for how every other docs/specs/SPEC-*.md document is written and read. This document does not itself specify any on-disk or wire format; it fixes the small set of conventions those documents lean on so each one doesn't have to restate them.

Scope: RFC 2119/8174 keyword usage (§1), the frontmatter status vocabulary and versioning posture (§2), shared wire-encoding notation (§3), domain-separator/namespace naming (§4), golden-vector citation conventions (§5), the no-vendor-references rule (§6), and requirement classification (§7).

1. Normative keywords

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and REQUIRED are used per RFC 2119 as clarified by RFC 8174 (the keywords carry their defined meaning only when written in this specific upper-case form). A spec that uses lower-case "must"/"should" in ordinary prose is making a descriptive statement, not a normative one.

2. Status vocabulary and versioning

2.1 Frontmatter status

Two independent axes, written as a single hyphenated token <maturity>-<bindingness>:

Bare draft or stable (no bindingness suffix) is permitted where a document predates this convention or bindingness genuinely doesn't apply (for example, this document itself). New or heavily-revised specs SHOULD use the full <maturity>-<bindingness> form.

Some existing SPEC-*.md documents in this corpus predate this convention and use ad hoc status strings. That is a known, non-urgent inconsistency — retrofitting them is left as a documentation cleanup, not a normative requirement of this section.

2.2 Versioning

A reader accepts one version of each format. It rejects every other version. A format change bumps the version and does not add a second read path. This rule follows from §2.1's bindingness axis:

• normative documents describe durable-state contracts, including authoritative local-only state. A version bump replaces the old version.
• advisory documents may describe disposable, reconstructible caches. Whether state can be rebuilt is determined by its contents and source of truth, not whether it crosses a network. Staged paths, selected object hashes, mode choices and deletion tombstones in .kit/index are authoritative: neither HEAD nor current working files can recreate them. SPEC-INDEX therefore rejects unsupported versions without rewriting those selections. Only stat observations may be discarded.

3. Wire-encoding notation

Where a SPEC-*.md document specifies byte layout:

• Every multi-byte integer is little-endian unless the document says otherwise (the one exception in this corpus is network-facing wire formats that inherit a big-endian convention from the protocol they implement — for example, AWS SigV4 in SPEC-TRANSPORT — those documents say so explicitly).
• A length-prefixed field means [u32 LE length][length bytes] unless a document specifies a different integer width for that field. This applies even to fixed-size fields (for example, a 24-byte nonce still carries its own 4-byte length prefix) for uniformity across a format's field list, not because the length is ever in doubt.

4. Domain-separator and namespace naming

kit's signing and hashing domain separators (for example, kit.tag\0) are permanent, literal byte strings baked into the signing/hashing contract — not a version field and not a label that gets bumped in place. A distinct new application of an existing key MUST mint its own, distinctly-named domain/namespace constant rather than repurpose an existing one for a second meaning. A domain separator's bytes never change.

Every domain separator, magic and predicate URI MUST have a value that no other one has. The reference implementation checks this: a test scans the source of every crate and fails when two definitions share a value. A definition is a const or static item, a tag passed inline to a hash call, or a magic written inline as a byte string.

Every magic is a distinct ASCII value that begins with K. The table below is the one registry of magics. Each owning spec states how the magic is used.

A registry (informative, not itself normative) of the domain separators and namespace strings currently in use is maintained inline in each format's own spec (SPEC-MERKLE-OBJECTS §2 and §3 for object-hash domains, SPEC-SIGNING §2 for the commit, remix and tag signing domains); this document does not duplicate that list, only the naming rule.

5. Golden vectors and conformance tests

Where a SPEC-*.md document lists numbered test vectors, the corresponding fixtures live under rust/tests/golden/<area>/ (one directory per format) and are the authoritative pinned bytes — the prose vector description is a human-readable label for a fixture that already exists, not a promise of one that will exist later. A spec revision that changes wire bytes MUST update the golden fixtures in the same change (CONTRIBUTING.md's "spec + golden vector updated" checklist item); a stale "TO BE FIXED IN IMPLEMENTATION" marker left after the fixtures already ship is a documentation bug, not a disclaimer.

6. No vendor references

A SPEC-*.md document specifies behavior as an implementation-independent contract — a wire format, an algorithm, a predicate a verifier evaluates — not as a reference to a specific library function or crate API. Where a document needs to describe how kit happens to implement a requirement, that belongs in a doc comment on the code itself (cross-referenced by file/function name, not restated), not in the spec's normative text. This keeps a spec usable by an independent, non-Rust implementation and keeps it from silently going stale the moment kit's own internal factoring changes without the contract changing.

7. Requirement classification

Protocol requirement. Classify a rule by who relies on it. A rule is a protocol requirement when a client, verifier, or another conforming server relies on it regardless of the operator's product choices. An optional feature creates a conditional requirement: "a server that offers X MUST ...". Protocol requirements apply to every conforming server offering that feature. They do not prescribe the reference server's implementation.

Protocol requirements MUST be layout-independent and orchestration-independent. They specify observable decisions, atomicity, durability, ordering, and refusal classes that any conforming implementation can test. They MUST NOT require shards, partitions, coordinators, internal key classes, work slices, phases, timers, call budgets, or chain limits. A published wire field that advertises an implementation limit remains a protocol field; the implementation's chosen limit and mechanism remain reference-server behavior. Optional-feature requirements MUST state the feature condition rather than assume a particular server orchestration. Other servers need only the protocol specifications, conformance tiers 1 and 2, and pure protocol primitives; they do not depend on the reference server.

Reference-server behavior. A mechanism, storage layout, or implementation limit of the reference server is reference-server behavior. It does not become a protocol requirement merely because the reference server implements it. Reference details MUST NOT substitute for an observable safety requirement. For example, atomic acceptance is a protocol requirement; implementing it with one storage transaction is a reference mechanism. A reference mechanism's source documentation supplies internal layouts and APIs (§6).

Protocol requirement. Authors MUST mark new or revised behavioral sections with **Protocol requirement.** or **Reference-server behavior.** at the start. A marker covers the following paragraphs until the next marker or heading. Mixed sections MUST mark each scope separately. A draft protocol requirement also carries its draft status; draft maturity does not make a reference mechanism normative. Existing unmarked sections retain their documented status pending classification when revised.