Specifications

The approved specs in this folder are the promises libxmtp and the self-hosted backend keep. SPEC-spec-format.md defines the format, the admission test, the identifier scheme, and the backlink rules. GLOSSARY.md defines the actors and shared terms. Requirement identifiers are globally unique, such as CONF-012 or JOIN-046.

Specs supersede XIPs. The documents they replaced were deleted under one blanket disposition (SPEC-013) once the replacing specs held their obligations; their history is in git.

Waivers

A requirement without a proving test needs a waiver under SPEC-055, SPEC-094, and SPEC-095. Use analysis when a recorded review proves a property that no test can prove. Use gap when the code does not satisfy the requirement; name an owner and an issue. Use untested when the reason names the code that satisfies the requirement but no test proves it yet; name an owner.

Capability map

Prefix	Spec	Owns
SPEC	Specification format	The format, admission, identifiers, backlinks, waivers, plans’ spec-change section
TOPIC	Topic format	The kind byte and identifier layout of every topic
API	Backend API contract	The gRPC contract: ordering, publish, query, subscribe, identity RPCs, connection statistics, error codes, admission validation
CONF	Backend configuration	Configuration validation, what is published, how the client applies it
AUTH	Backend auth	Request authentication and authorization, client credentials, terminal auth failures
OPS	Backend operations	Retention and pruning, readiness and health, shutdown as observed, the metric catalogue
PUSH	Push subscriptions and webhooks	Recipient registration, channels, subscription sync, dispatch, HMAC suppression, webhook signing
IDENT	Identity updates	Association log, signature kinds, inbox id derivation, replay protection, installation lifecycle, local signing-key persistence
JOIN	Joining groups	Key packages, Welcomes, welcome pointers, when a Welcome replaces local state, join validation
GMOD	Modifying groups	Commits and proposals, commit validation, adding members, failed installations
PERM	Group permissions	The policy set, evaluation, admin semantics, policy versioning
META	Group metadata and app data	Immutable and mutable metadata, the app-data dictionary and registry, disappearing messages
DMS	DMs and stitching	DM id, fixed DM policy, duplicate detection and stitching
PROC	Message processing	Streams and queries into one ordered processor, durable positions, retry and rejection
SEND	Message sending	Intents, message ids, publish retries, per-group ordering, failed sends
FORK	Fork recovery and commit log	Commit-log entries, fork detection, readd requests, one-shot groups
CONS	Consent	Consent states, precedence, defaults, gating of listing and streaming
SYNC	Device sync	The sync group, preference updates, trust of sync invitations
ARCH	Archive format	The backup export and import format and its compatibility promise
MIG	Legacy database migration	Closed legacy source conversion, source preservation, metadata fallback, and atomic local archives
CTYPE	Content types	Content type ids, the encoded-content envelope, the standard catalogue
STORE	Client storage	Client database locations, storage lifecycle, and unencrypted database support
ATCH	Remote attachments	Published attachment storage, download URLs, the upload request, pending attachments, local attachment files, downloads
EVENT	Client events	Live event kinds, payloads, filters, delivery, and subscriptions
LOG	Client logging	Client diagnostic logs and app sinks

Tools

Run each one as dev/nix-shell 'just <recipe>'.

just spec-check            # validate docs/specs/ and the backlinks in code; part of just lint
just spec-index            # print every requirement with its links; --json for tooling
just spec-show JOIN-012    # print one requirement with its links

Skills for this work live in .agents/skills/: authoring-specs, reviewing-specs, and checking-spec-compliance.