sigelo — versioning

Two things carry version numbers and they move independently: the wire (v inside every signed object, SPEC §3.1) and the packages (npm, the Go module). An agent that adopts a format that then changes under it does not come back, so the wire moves rarely and loudly.

1. The wire: sigelo/0

v is "sigelo/0". Verifiers reject any other value (invariant 7; SPEC §9 step 2). There is no minor version and no negotiation: a bundle is sigelo/0 or it is not sigelo.

Before the freeze (today): the wire may change. Every change gets a CHANGELOG line starting wire:, the commit hash, and at least one vector that fails on the old behaviour.

Frozen at tag v0.2. From then on, sigelo/0 means exactly SPEC.md and test-vectors.json as they stand at that tag. The freeze needs 30 consecutive days with no wire change first (ROADMAP R6); any wire change restarts the count. After it, a wire change is sigelo/1 or it does not happen.

A breaking change is any of:

• a vector's expected output changes: a canonical string, a DID, a signature, a §9.1 result, or a negative's stated reason or outcome;
• a new mandatory field, or a field removed, retyped or made optional (SPEC §3.1 table);
• any change to what is rejected, or to which outcome a failure gets (SPEC §7.4: "not a candidate" versus REJECT; §9: fatal versus per-item discard);
• the signing input, the suite (invariant 2), an encoding (SPEC §2), or the precedence rule.

Not breaking, allowed after the freeze: spec prose that changes no outcome; a new vector for a rule the spec already states, provided both shipped implementations pass it unchanged (if one fails, the rule was ambiguous and fixing it is breaking); anything below the wire (keys, ceremony, keeper, adapters, MONERO.md) — those follow package semver.

2. Introducing sigelo/1

• A verifier accepts a set of wire versions and each bundle carries one. A bundle that mixes versions across its objects is malformed. No object carries a list.
• sigelo/1 gets its own SPEC and its own vector file; sigelo/0 keeps its frozen ones.
• A sigelo/1 verifier SHOULD also accept sigelo/0 for at least 12 months after sigelo/1 ships, and MUST report which version it verified (a §9.1 field in sigelo/1).
• Identities carry over by rotation: a sigelo/0 chain rotates into a sigelo/1 genesis. How, and whether a sigelo/0 recovery commitment governs it, is part of the sigelo/1 spec and must be decided before anything else in it.

3. Test vectors

test-vectors.json is versioned with the wire, not the packages. Its spec field names the wire ("sigelo v0.1 (wire sigelo/0)"). Every release records its SHA-256 in SHA256SUMS (ROADMAP §5.5). After the freeze the file only grows, under §1's rule; nothing in it is edited. It is regenerated from documented seeds by ts/src/gen_vectors.ts, and CI diffs the result.

4. Packages

Semver, per package: sigelo (ts), sigelo-spend, sigelo-agent, the Go module. Each package states the wire versions it speaks. Until 1.0.0, a minor bump may break the package API; it may never change the wire. A package that starts speaking sigelo/1 gets a new major. The Go module's path is github.com/csigelo/sigelo/go in the public repository (release/publish.sh rewrites the private tree's bare sigelo at export, T4). The module sits in the repository's go/ directory, so Go resolves go install github.com/csigelo/sigelo/go/cmd/sigelo-verify@v0.1.0 through the tag go/v0.1.0, not v0.1.0: every release pushes both tags on the same commit. sigelo-verify releases carry static binaries and a signed release object (ROADMAP §5.5).

5. Deprecation

A wire version is deprecated by a CHANGELOG entry and a date, never by code alone. Minimum 12 months from deprecation to removal from the reference verifier. The keeper's HTTP surface and the sigelo-wallet lines (spend/README.md) are package API: a removed route, verb or exit code is a major bump with one minor release of overlap that warns.

6. Dependency pinning

• Exact versions in every package.json (no ^, no ~) and in go.mod; go.sum committed; Go builds with GOFLAGS=-mod=readonly and a toolchain line.
• Lockfiles committed; CI installs with npm ci --ignore-scripts, never npm install.
• GitHub Actions pinned by commit SHA, with the tag in a comment.
• Renovate and Dependabot are off. Updates are manual: one dependency per commit, its changelog read, the full vector run in both implementations before and after. Security advisories are read by hand (GitHub advisory feed, npm audit, govulncheck).
• Runtime dependencies stay as CLAUDE.md lists them: @noble/ed25519 and @noble/hashes for ts, filippo.io/edwards25519 for Go. monero-wallet-rpc is pinned too (0.18.5.0, RPC 1.30) by the canary in spend/canary.ts.