ADR index

Every structural choice in OxiMail is recorded as an Architecture Decision Record before it is implemented: the context, the decision, the alternatives rejected, and the consequences. The ADRs are working engineering documents in the server repository; when the AGPL repository opens publicly, the full texts come with it. Until then, this index lists what exists — number, status, title — so the depth and direction of the architecture are visible. Statuses: Accepted (in force, implemented unless noted), Design (decision engraved, implementation tracked), Superseded (replaced by a later ADR; retained parts noted in the title), Proposed/Reserved (not yet ratified).

ADR	Status	Title
001	Accepted	JMAP-first, not protocol-agnostic
002	Accepted	SQLite by default, not RocksDB
003	Accepted	Tantivy instead of ElasticSearch
004	Accepted	AGPL-3.0-or-later with commercial extensions
005	Superseded	Custom Sieve interpreter — for-primary → ADR-054+058 (retained: legacy ManageSieve + v1→v2 migration)
006	Superseded	Native undelete — mechanism → ADR-035 (policy “not enterprise-gated” retained)
007	Accepted	TOML + DB overrides, not full-DB config
008	Accepted	UUIDv7 for all IDs
009	Accepted	Store raw RFC 5322 + parsed metadata
010	Accepted	Optimistic concurrency via state strings
011	Accepted	Internal event bus + task queue for cross-domain
012	Accepted	Explicit Account/Principal model (RFC 9670)
013	Accepted	Versioned DB migrations from day 1
014	Accepted	Blob dedup by content-hash, not by Message-ID
015	Accepted	Tenant isolation at the storage layer
016	Accepted	ArcSwap for hot-reloadable components
017	Accepted	Accepted email MUST be delivered
018	Accepted	clippy::unwrap_used banned in production
019	Superseded	Thread IDs by stored Message-ID — for-primary → ADR-054 (retained: migration + IMAP shim)
020	Accepted	Mandatory encryption at rest
021	Accepted	Chat over JMAP + WebSocket
024	Accepted	Legacy protocols as feature-gated translation layers
027	Accepted	Fail-silent audit
028	Accepted	Dynamic accountCapabilities
029	Accepted	Unified provisioning pipeline
031	Accepted	Trusted network policy
032	Accepted	Logging single source of truth
035	Accepted	Two-stage destroy with visible trash
036	Accepted	Blob reuse cross-module
038	Accepted	AGPL scheduler primitive
040	Accepted	Chat schedule send
041	Accepted	Chat personal reminders
042	Accepted	Principal status auto-clear via scheduler
043	Accepted	Link unfurl serveur (Open Graph)
044	Accepted	Custom emoji workspace (V1.6b)
045	Accepted	Tenant-shared blob plumbing (V1.6a)
046	Accepted	Polls in chat (V1.7)
047	Accepted	Structural mentions @here/@channel/@everyone (V1.9)
048	Accepted	Extract oximail-blob from oximail-mail
049	Accepted	Extend MTA-STS coverage to backup MX path
050	Accepted	Fail-loud invariant on encryption keys
051	Accepted	DANE outbound wiring + conditional allow_invalid_certs
052	Accepted	Backup MX proxy mode for synchronous primary reject propagation
053	Accepted	User preferences singleton — server-side, multi-tenant safe
054	Accepted	JMAP v2 architecture overview
055	Accepted	Schema migrations v1 → v2 (destructive, irreversible)
056	Accepted	JMAP v2 capability negotiation — no v1 fallback
057	Accepted	IMAP / SMTP shims preserved unchanged across v1 → v2
058	Accepted	ManageSieve shim is read-only
059	Accepted	CardDAV shim translates Contact ↔ vCard
060	Accepted	CalDAV shim translates Event / RecurrenceRule ↔ iCalendar
061	Accepted	One-off data migration script for the v1 → v2 cutover
062	Accepted	Raw RFC 5322 + structured storage cohabitation under JMAP v2
063	Superseded	recurrenceOverrides keys: parent-Event-tz → ADR-091 (civil-local)
064	Accepted	Attendee ACL on Event/set update, no Event/respond method
065	Accepted	SieveScript → Rule migration is best-effort with retention
066	Accepted	JMAP v2 schema evolution policy
067	Accepted	JMAP v2 ifInState transactional semantics
068	Design	JMAP v2 blob retention semantics — mechanism unbuilt (no tier/tieredAt columns, no purge worker) (impl #490)
069	Accepted	Background worker SQLite contention discipline
070	Accepted	Boundary atomicity bridge for legacy protocol shims
071	Accepted	Auth boundary hardening
072	Accepted	Per-collection volume caps in JMAP request payloads
073	Accepted	oximail-backup CLI
074	Accepted	Spam classification keywords deferred to typed field
075	Accepted	Admin observability surface lives on JMAP, not parallel REST — partial; observability still REST (#486)
076	Accepted	oximail-parser & oximail-auth stay AGPL, not on crates.io
077	Accepted	Unified spam/phishing classification model
078	Accepted	Spam open-core boundary: algorithm-free, network-paid
079	Proposed	High-availability / disaster-recovery ladder
080	Accepted	Spam classification & disposition spine
081	Accepted	Conversation primitive: substrate + producers (gen. Thread)
082	Accepted	Name-keyed row access, Email column registry, projection
083	Accepted	Cross-layer change-tracking coherence (modseq/CTag bumps)
084	Accepted	Consumer projection wiring + property-resolution policy
085	Accepted	jemalloc as the server allocator (RSS tracks working set)
086	Accepted	System-container naming — canonical EN + derived localizedName
087	Accepted	Owned core, thin compatibility faces + identity invariants
089	Accepted	Aliases as sendable identities (synthesized, not materialized)
090	Accepted	Local-zone recurrence expansion
091	Accepted	Civil-local recurrence override keys
092	Accepted	Projected event occurrence + server-emitted identity
093	Accepted	Per-occurrence confidentiality, no occurrence type — partial; per-override encryption deferred
094	Accepted	Parseable civil-local composite occurrence id
095	Accepted	Async destroy side-effects via transactional outbox
096	Design	Self-describing blobs — encryption params in ciphertext header (impl #391)
097	Accepted	Principal v2 — RFC 9670 identity foundation (core shipped; sessionState #170 + group re-keying deferred)
098	Accepted	Body-part blobs are derived caches, served lazily
099	Proposed	Chat relations first-class — reaction/edit aggregation vs E2EE
101	Design	Inbound MTA isolation across the deployment ladder — opt-in seam unbuilt; in-process default in force (impl #491)
102	Accepted	Server-key recovery — backup carries no key material
103	Accepted	At-rest key model — content/container split, trivial rotation (Lot 1 shipped; MWK/BYOK Lot 2 deferred)
104	Accepted	Encrypted-by-default appliance delivery vehicle — socle shipped; image factory (Lot B) deferred
105	Reserved	Appliance network posture (firewall/egress/IPv6) — sibling of ADR-101
106	Reserved	Appliance lifecycle, hardware HCL & go-to-market
107	Accepted	Bootstrap & install topology — one engine, producer-everywhere TLS
108	Design	Privileged system mutations via a pull-reconciler — nftables ban-set (impl #474)
109	Design	Clickable-href scheme validation at the write chokepoint — spec the convention, not the doc model (impl #445/#448)
110	Design	Cross-account notification push + read-state where you own the store + generic client notification center (impl #472)
111	Design	Authenticated sender brand indicator — server-resolved BIMI, DMARC-gated; no unauthenticated logo in the brand slot (impl #508)
112	Design	Unified identity & rights substrate — shared-account kind, one MyRights model, capability plane (impl #515-519)
113	Design	Substrate/consumer boundary — what belongs in OxiMail vs an external JMAP-client application (impl #568/#569)
114	Design	CLI admin surface — grammar, guards & the “substrate owns the data” verb criterion; mechanized guard test
115	Accepted	Device-bound tokens — DPoP proof-of-possession on /auth/refresh; login-time binding, ES256, jti burn (Amdt 1: server nonce + resource PoP; Amdt 2: media token)
116	Design	Outbound smarthost relay — relay accounts, DNS domain proof, recipient quotas, manual warm-up preflight (automated ramp outstanding)
117	Accepted	Unified local delivery pipeline — sender locality is a transport optimization, never a delivery semantic; closed provenance enum
118	Design	Account-agency freeze and erasure-integrity seams
119	Accepted	Outbound delivery scheduler — per-recipient terminal state, token-claimed bounded concurrency, origin-typed DSN policy
121	Accepted	Resource and location principals own their account — windowed availability, explicit window overflow, destroy-side deprovision
122	Accepted	`Email/get` wire surface — headers materialized (RFC 8621 §4.1.3), `headerJson`/`searchTokens` retired, `spamScore`/`metadataSource`/`indexerVersion` admin-scoped
123	Design	Anonymous route contract — fail-closed anonymous context, three server-side tenancy derivations (vhost / capability / provider reference), network-prefix rate limiting
124	Design	Federation transport — a transport choice that changes an authorization decision is not a transport choice: ordinary HTTPS, node anchor pinned at pairing, peer materialized as a restricted local principal
125	Design	Cross-organization availability grants — an authorization may only key on an identity you verify yourself: realm-scoped consent record, owner-written, self-expiring, widens the access axis only
126	Design	Federation pairing ceremony — bilateral out-of-band pairing, fingerprint over realm + key, node key per organization, expiry deferred to the transport (§5, custody, superseded by ADR-127)
127	Design	Node identity root versus working key — a key that must survive and a key that must work are not the same key: portable root held by the subscribing entity, disposable root-certified working key on the box, monotonic epoch so rotation is revocation
128	Accepted	No RCPT-time greylisting — the 2003 gate retired; auth enforcement and the scored pipeline are the defence. The score-conditional greylist stays dormant. Supersedes the greylist clauses of ADR-031
129	Accepted	App-password scopes enforced — the scope rides the token and survives refresh, one capability matrix, protocol access derives from the capability set, enforced at JMAP dispatch, IMAP login and DAV
130	Accepted	Public-asset cleartext carve-out from ADR-020 — the published avatar (an opt-in re-encoded thumbnail behind a capability token, the original photo staying encrypted) and the tenant branding logo; two distinct consent models sharing only an HTTP transport; the carve-out list is enumerated, never inferred; erasure is revocation
131	Accepted	Bind-by-exposure appliance posture — blast radius over “separate IP” theatre: file surfaces bind to the local network (v4 and v6, loopback default on single-address boxes, fail-loud config check before public exposure), mail and HTTPS public, the pre-auth port 25 hardened first. Exposure is not trust: ADR-031 remains the trust authority
132	Accepted	Signed release distribution — `.deb` plus a signed apt tree, minisign on the tarballs. The package ships no unit, no user and no config: the wizard stays the configurator. Offline certify-only root key, sign-only repository subkey that never sits on the build host
133	Accepted	Tenant contact directories — N admin-plane directories per tenant, JSContact entries, editors named as principals; members never see a container, they see a flat projection carrying its source; directory writes are admin-gated, entry writes editor-gated
134	Accepted	Creation is a privilege of the write path — a JMAP `/get`, `/query` or `/changes` handler creates no domain row: it requires and fails loudly. The ambient guard fails hard in test and CI, meters and logs in production. An object created outside the write path has no owner, and what has no owner has no lifetime. Twin clause: no pre-auth path creates a row
135	Design	Sorting taxonomy, danger versus attention — a sorter either returns a danger verdict (it decides a disposition) or an attention category (it decides a rendering), never both. Closed danger kinds `{spam, phishing, malware}`, closed `category` dimension `{transactions, updates, promotions}` chosen by measurement over two real populations, danger taking precedence over the user override

The numbering has gaps: the ADR number space is shared with companion repositories, so some numbers live outside the AGPL server repository and are not listed here.

Design is not a synonym for shipped. Several federation records above (124 to 127) are ratified as the architecture of record with their mechanisms partially built — the pairing ceremony and the grant model are deployed, while individual clauses named inside them are still open. ADR-135 is at the other end of the same scale: the decision is engraved, and none of it is served yet — no category dimension and no malware kind exist on the wire today. Where this documentation describes behaviour, it describes what is served; the ADR status column describes the state of the decision.

Get Started

Operator Manual

Developer / JMAP API

Architecture Reference

Reference