hoarse 0.1.1__tar.gz

hoarse-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+/profile/
+/corpus/
+.coverage
+/src/hoarse/_build_meta.py

hoarse-0.1.1/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to Hoarse. Versions are semantic (`PKG-10`); the policy for
+when each part moves is in [`docs/plan/versioning.md`](docs/plan/versioning.md).
+Each entry names the store schema version, and says so explicitly when a release
+needs a resync or a profile migration (`PKG-12`).
+
+## 0.1.1 — 2026-10-22
+
+- **Help > About Hoarse** shows the version and build information: where the
+  build came from, its commit, when it was built, and the Python, platform,
+  SQLite, Qt and store schema versions, with a button that copies them for a bug
+  report. `hoarse --build-info` prints the same on the command line.
+- Released packages carry the commit they were built from.
+- A corrected password now takes effect at once: saving it to the keychain, or
+  pressing Apply in Account Settings, retries a stopped account. An older
+  password you chose not to remember no longer overrides the saved one, and is
+  forgotten when its account is deleted.
+- Store schema 6 (unchanged); no resync needed.
+
+## 0.1.0 — 2026-10-22
+
+The first versioned release. Alpha: usable against real IMAP accounts, not yet
+feature-complete (see the roadmap, `docs/spec/15-roadmap.md`).
+
+- **Python** 3.14 (minimum and tested). **PySide6** 6.12 or later (tested 6.12.0).
+- **Store schema** 6, blob schema 2. Profiles from earlier development builds
+  migrate automatically; no resync is needed.
+
+### What works
+
+- Three-pane, Thunderbird-style window with modern, retro, dark and high-contrast
+  theme packs; a message list that stays fast at a million messages; threaded
+  view (one row per thread, shown by its first message); folder tree with context
+  menus (create subfolders, rename, delete, move, properties with subfolder totals).
+- Multiple accounts with an account wizard (autoconfig), separate incoming and
+  outgoing passwords, keychain or session-only storage.
+- IMAP sync: folder list, headers and bodies within the offline window, with
+  QRESYNC/CONDSTORE where offered.
+- Reading: header block (From, Subject, List-Id, Date, To, Cc, Reply-To by
+  default, customisable), clickable plain-text links, mark read on view.
+- Writing: composer for new, reply, reply all, reply to list and forward;
+  attachments; signatures; 10-second undo after Send; SMTP submission with an
+  exactly-once guarantee across crashes; a copy filed in Sent.
+- Changes made in Hoarse (read state, flags, moves, deletes, folder operations)
+  replay to the IMAP server through a durable op-log, with undo and retries.
+- Import and export of mbox, Maildir and .eml.
+
+### Not yet
+
+Drafts, recipient autocomplete, HTML rendering (HTML mail shows as text),
+search UI, filters, address book, OAuth, POP3 and JMAP sending/sync.

hoarse-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Gruno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hoarse-0.1.1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: hoarse
+Version: 0.1.1
+Summary: A desktop email client that stays fast at a million messages
+Author-email: Daniel Gruno <humbedooh@apache.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: client,email,imap,mail,pyside6,qt,smtp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
+Requires-Python: >=3.14
+Requires-Dist: jeepney>=0.9; sys_platform == 'linux'
+Requires-Dist: keyring>=25.7
+Requires-Dist: nh3>=0.3.7
+Requires-Dist: pyside6-essentials>=6.12
+Requires-Dist: pywin32-ctypes>=0.2; sys_platform == 'win32'
+Requires-Dist: secretstorage>=3.3; sys_platform == 'linux'
+Provides-Extra: webengine
+Requires-Dist: pyside6-addons>=6.12; extra == 'webengine'
+Description-Content-Type: text/markdown
+
+# Hoarse
+
+A desktop email client for Linux, macOS and Windows, written in Python, that stays responsive on
+mail accounts far larger than the ones most clients are tested against.
+
+- Laid out like Thunderbird: three panes, a folder tree per account, a dense message list.
+- Themed by declarative packs — a modern pack and a retro pack that genuinely look different.
+- Designed against a single account holding **more than one million messages**.
+
+**Start with the specification: [`docs/spec/README.md`](docs/spec/README.md).** It is normative.
+
+## Install
+
+Hoarse needs Python 3.14 and installs from PyPI with no compiler and no system
+packages:
+
+```bash
+uvx hoarse            # or: pipx install hoarse  /  uv tool install hoarse
+```
+
+From a checkout, for development:
+
+```bash
+uv run hoarse
+```
+
+Versions are semantic; see [`CHANGELOG.md`](CHANGELOG.md) and
+[`docs/plan/versioning.md`](docs/plan/versioning.md).
+
+Development is split across five tracks — see [`docs/plan/parallel-tracks.md`](docs/plan/parallel-tracks.md).

hoarse-0.1.1/README.md

@@ -0,0 +1,30 @@
+# Hoarse
+
+A desktop email client for Linux, macOS and Windows, written in Python, that stays responsive on
+mail accounts far larger than the ones most clients are tested against.
+
+- Laid out like Thunderbird: three panes, a folder tree per account, a dense message list.
+- Themed by declarative packs — a modern pack and a retro pack that genuinely look different.
+- Designed against a single account holding **more than one million messages**.
+
+**Start with the specification: [`docs/spec/README.md`](docs/spec/README.md).** It is normative.
+
+## Install
+
+Hoarse needs Python 3.14 and installs from PyPI with no compiler and no system
+packages:
+
+```bash
+uvx hoarse            # or: pipx install hoarse  /  uv tool install hoarse
+```
+
+From a checkout, for development:
+
+```bash
+uv run hoarse
+```
+
+Versions are semantic; see [`CHANGELOG.md`](CHANGELOG.md) and
+[`docs/plan/versioning.md`](docs/plan/versioning.md).
+
+Development is split across five tracks — see [`docs/plan/parallel-tracks.md`](docs/plan/parallel-tracks.md).

hoarse-0.1.1/docs/spec/01-goals.md

@@ -0,0 +1,59 @@
+# 1. Goals and non-goals
+
+## 1.1 What Hoarse is
+
+A desktop email client for Linux, macOS and Windows, written in Python, that stays responsive on mail accounts far larger than the ones most clients are tested against.
+
+Three things define it:
+
+1. **It is laid out like Thunderbird.** A three-pane window, a folder tree, a dense sortable message list, a reader pane, tabs, a quick filter. People migrating from Thunderbird should not have to relearn where anything is.
+2. **It looks like whatever you want.** The entire appearance — palette, metrics, borders, icons, row density, fonts — comes from a declarative theme pack. Hoarse ships a modern light and dark pack and a retro pack, and a third party can write more without touching Python.
+3. **It does not slow down.** The design target is a single account holding **more than one million messages**, and every interaction budget in [chapter 14](14-quality.md) is written against that corpus, not against a 5,000-message test account.
+
+## 1.2 Who it is for
+
+Someone with a large, long-lived mail archive — a decade or two of mailing lists, work mail and personal mail — who wants it local, searchable, fast and under their own control. They are comfortable installing a tool with `uv`. They care about the client not leaking their reading habits to senders.
+
+## 1.3 Goals
+
+| ID | Goal |
+|---|---|
+| `GOA-1` | A folder containing 1,000,000 messages MUST open, scroll, sort and filter without the interface stalling. |
+| `GOA-2` | The interface MUST never block on the network. Every view reads from the local store only. |
+| `GOA-3` | Every action that changes server state MUST apply locally first and be replayed to the server afterwards, with undo. |
+| `GOA-4` | Hoarse MUST support IMAP, IMAPS, POP3 and SMTP, with multiple accounts and multiple sending identities per account. |
+| `GOA-5` | Hoarse MUST run on Linux, macOS and Windows from one code base, with no platform-specific forks of the UI. |
+| `GOA-6` | The appearance MUST be fully determined by a theme pack, and a retro pack MUST look genuinely different from a modern one — not merely recoloured. |
+| `GOA-7` | Remote content in mail MUST be blocked by default; no message may cause a network request without the user asking for it. |
+| `GOA-8` | Hoarse MUST be installable and runnable with `uv` alone, with no compiler, system package or build step required of the user. |
+| `GOA-9` | Importing an existing archive (mbox, Maildir, a Thunderbird profile) MUST work by streaming, at any size. |
+| `GOA-10` | Hoarse MUST collect no telemetry and MUST make no network connection that the user has not configured. |
+
+## 1.4 Non-goals
+
+These are out of scope for the specification. They are listed so that nobody has to re-litigate them.
+
+| Not in scope | Why |
+|---|---|
+| **Calendar and tasks (CalDAV)** | A second protocol stack, a second store schema, recurrence, timezones and a whole second UI. It roughly doubles the project. Use a dedicated calendar client. |
+| **Contact sync (CardDAV)** | Follows the calendar decision. The local address book in [chapter 13](13-features.md) is in scope; synchronising it is not. |
+| **OpenPGP and S/MIME** | Key management, trust models, per-recipient policy and a UI for all three are a large sub-project in their own right, and a client that encrypts badly is worse than one that does not encrypt. **Note:** the original argument also rested on having no crypto primitives, which stopped being true when `cryptography` was admitted ([`A-07`](02-decisions.md)). This is now a scope decision, not a capability one, and can be revisited on its own merits. |
+| **Exchange EWS / Microsoft Graph** | A large, awkward API surface with shifting authentication. Microsoft 365 accounts with IMAP enabled are supported through IMAP + OAuth2; accounts with IMAP disabled by policy are not reachable. |
+| **RSS feeds and NNTP newsgroups** | Thunderbird carries them for historical reasons. They share almost nothing with the mail path. |
+| **A mobile client** | The architecture ([chapter 3](03-architecture.md)) does not preclude one; nothing here is written for it. |
+| **Cross-account unified folders** | See [D-14](02-decisions.md#d-14). Accounts are strictly separate, which is what keeps every list query on a single index. |
+| **A web or server mode** | Hoarse is a desktop application. The engine process is not a daemon for other users. |
+
+## 1.5 What success looks like
+
+Hoarse v1.0 is done when all of the following hold on a real account of at least one million messages, on all three platforms:
+
+- Cold start to a painted window showing the last-viewed folder, with no network, in under 800 ms (`PRF-1`).
+- Switching to a 1,000,000-message folder paints the first screen in under 100 ms (`PRF-2`).
+- Scrolling that folder holds 60 fps with no frame over 16.7 ms (`PRF-4`).
+- A local search returns its first results in under 150 ms (`PRF-6`).
+- Marking read, flagging, moving and deleting feel instantaneous and are undoable (`PRF-8`, `OPL-9`).
+- An incremental resync of every folder on a QRESYNC-capable server completes in under two seconds (`PRF-11`).
+- A fresh install reaches a usable inbox from `uvx hoarse` with no compiler and no system packages (`PKG-1`).
+
+Everything else is negotiable. These are not.

hoarse-0.1.1/docs/spec/02-decisions.md

@@ -0,0 +1,225 @@
+# 2. Decisions
+
+Each decision below is **binding**. A work package that needs one of them changed must stop and say so rather than working around it ([brief rules](../plan/brief-template.md)).
+
+Decisions carry a date and the alternatives that were rejected, so that a future reader can tell whether the reasoning still holds. Several of them were close calls; those are marked **revisit** with the condition that would reopen them.
+
+---
+
+## D-01 — User interface: PySide6, Qt Widgets
+
+**Decided 2026-10-20.** The UI is built on **PySide6 (Qt 6.12+) using Qt Widgets**, with custom-painted item delegates for the message list.
+
+Qt Widgets gives the strongest model/view framework available to Python for dense tabular data, native menus and shortcuts on all three platforms, and a mature accessibility bridge. PySide6 6.12.0 ships `cp310-abi3` wheels covering Linux x86-64 and aarch64, macOS universal2, and Windows amd64 and arm64, which means one wheel per platform works across Python 3.10–3.15. It is LGPLv3, which imposes no obligation on Hoarse's own licensing.
+
+*Rejected:* **Qt Quick/QML** — a better story for skinning and animation, but its views are weak for dense tabular data and the list virtualisation would be hand-rolled; GPU driver variance across three desktop platforms is a support cost we do not want on the critical path. **GTK4/libadwaita** — excellent on Linux, materially worse to package and to live with on Windows and macOS. **A web UI in a native shell** — the most flexible theming, but it puts a Python↔JS bridge between the user and a million-row list.
+
+**Consequence:** the message list is a `QTableView`, *not* a `QTreeView`. See [D-06](#d-06).
+
+## D-02 — Dependencies: pure Python, plus Qt, plus a named allowlist
+
+**Decided 2026-10-20. Amended 2026-10-20 to admit `nh3`.**
+
+Hoarse's dependencies MUST be the standard library, a pure-Python package, or a member of the **compiled allowlist** below. The allowlist is closed: adding to it is a specification change, decided against the admission criteria, not a judgement call made inside a work package.
+
+### The compiled allowlist
+
+| Package | Why it is admitted | Governs |
+|---|---|---|
+| **PySide6** (Essentials; Addons under the `webengine` extra) | There is no credible pure-Python path to a native desktop UI with a model/view framework that survives a million rows | [10](10-ui.md), [11](11-theming.md) |
+| **nh3** 0.3.7+ | Python bindings over the Rust `ammonia` crate. Security-critical, actively maintained, and the component we are least well placed to write ourselves | [09](09-mime-render.md) |
+| **cryptography** (and **cffi**) | Reached transitively through `keyring` → `secretstorage` on Linux, and admitted on the same grounds as nh3: we cannot write AES safely ourselves. PyCA-maintained, abi3 wheels on every target, a real security-response history | [12](12-accounts-security.md) |
+
+### Admission criteria
+
+A compiled package may be admitted only when **all** of these hold:
+
+1. **Wheels on every target** — Linux (glibc and musl, x86-64 and aarch64), macOS (universal2), Windows (amd64 and arm64), with no build step for the user.
+2. **A stable ABI** (`abi3`), so a new CPython release does not strand the project.
+3. **No transitive compiled dependencies.**
+4. **Either** we cannot write it safely ourselves, **or** the pure-Python version misses a `PRF` budget by more than 3× after optimisation.
+5. An active maintainer and a security-response history.
+
+### Why nh3 qualifies
+
+Verified 2026-10-20 against PyPI and by installing it on this machine:
+
+- **27 wheels**, `cp38-abi3`, covering manylinux and musllinux on x86-64, aarch64, armv7l, i686, ppc64, ppc64le, s390x and riscv64; macOS universal2; and Windows win32, amd64 **and** arm64. That is broader coverage than PySide6's own wheels. 0.8–1.5 MB each.
+- **Zero transitive dependencies.** MIT licensed. Installs in seconds with `uv`.
+- `abi3` means one wheel spans 3.8 through 3.15+, with free-threaded (`cp314t`) builds also published.
+
+And it passes the bar that matters: tested against this chapter's own hard rules, **nh3 leaked nothing** across 28 adversarial cases — script and style stripping, every `on*` form, entity-encoded and control-character scheme smuggling, `vbscript:`/`file:`/`data:` in `href`, SVG, CSS `expression()`, remote `url()`, `-moz-binding`, `position:fixed`, and the `noscript`/`math` mXSS mutations. Its URL handling was checked against a real Chromium URL parser: it strips exactly the characters a browser strips (tab, LF, CR, leading space — all of which *do* resolve to an executable `javascript:`) and leaves the ones a browser percent-encodes into an inert relative path (`NUL`, `\x01`, `\x0b`).
+
+*Rejected:* writing the sanitiser ourselves on `html.parser`. It was the original decision, and it made the single highest-risk component in the application something we maintained alone, against an adversary who gets to pick the input. `bleach` is not an option — final release, unmaintained since June 2026, on top of the unmaintained `html5lib`.
+
+### What Hoarse still writes
+
+Admitting nh3 removes the sanitiser core, not the pipeline around it:
+
+| Component | Why it is still ours | Where |
+|---|---|---|
+| Remote-content blocking and counting | Product policy, not sanitising. Implemented in nh3's `attribute_filter` callback | [09 §9.4](09-mime-render.md) |
+| `<style>` block parsing and inlining | nh3 **discards** `<style>` blocks rather than inlining them, and a large share of real mail styles itself that way (`MIM-18`) | [09 §9.4](09-mime-render.md) |
+| `data:` URL type and size caps | nh3 allows a `data:` scheme wholesale; the 2 MiB and image-type caps are ours | [09 §9.4](09-mime-render.md) |
+| Depth and node caps | Denial-of-service bounds, applied before and after nh3 | [09 §9.4](09-mime-render.md) |
+| Full-text search | SQLite FTS5 via stdlib `sqlite3`. `tantivy` is **not** admitted — see the note below | [05](05-search.md) |
+| IMAP engine | A purpose-built asyncio client; see [D-03](#d-03) | [07](07-protocols.md) |
+| Fast header parsing | A streaming header parser for bulk import; the stdlib `email` module is too slow for a million messages | [09](09-mime-render.md) |
+| Credential vault fallback | ChaCha20-Poly1305 in pure Python against RFC 8439 vectors, for small secrets when no OS keychain is available | [12](12-accounts-security.md) |
+
+**Permitted pure-Python dependencies.** `keyring` and its platform backends (`jeepney` on Linux, `pywin32-ctypes` on Windows; macOS shells out to `/usr/bin/security`).
+
+### How `cryptography` came to be admitted
+
+Worth recording, because it was found rather than designed. The layering guard (`QA-2`) caught it on its first run, contradicting what an earlier draft of this chapter claimed: **`keyring` is not pure Python on Linux.** It hard-depends on `secretstorage`, which depends on `cryptography`, which depends on `cffi`:
+
+```
+keyring ──(sys_platform == "linux")──► secretstorage ──► cryptography ──► cffi ──► pycparser
+                                                         [compiled]      [compiled]  [pure]
+```
+
+The alternatives were writing our own `net/secrets/` over `jeepney` and `ctypes`, or making the system keyring an opt-in extra on Linux and defaulting to Hoarse's own vault. Both keep the allowlist at two entries; both make the common Linux case worse, and the first puts three hand-written platform paths on the credential route — which is precisely where a subtle bug is most expensive.
+
+**Decided 2026-10-20: admit it.** Criterion 4 applies exactly as it did for nh3 — we cannot write AES safely ourselves — and `cryptography` is the most scrutinised package in the Python ecosystem for this job.
+
+**Knock-on, flagged deliberately.** OpenPGP and S/MIME were ruled out of scope partly because pure Python meant hand-written RSA, ECC and AES ([01 §1.4](01-goals.md#14-non-goals)). That argument is now weaker: the primitives are present. The non-goal **still stands** on its remaining grounds — key management, trust models, and a UI for them are a large sub-project regardless of who supplies the maths — but it is now a scope decision rather than a capability one, and can be revisited on its own merits.
+
+**On `tantivy` specifically.** It meets criteria 1–3 and 5, and it is several times faster than FTS5. It is **not** admitted, because nh3 and tantivy differ in kind: nh3 is a pure function with no state, while tantivy is a second persistent store that must stay consistent with SQLite across crashes, eviction and migration — it would reopen [chapter 5](05-search.md) and add a whole class of recovery requirements. Admitting it is a decision to take deliberately, not a consequence of admitting nh3. **Revisit** if `PRF-6` proves unreachable with FTS5 on the 1M corpus.
+
+## D-03 — IMAP: a purpose-built asyncio engine
+
+**Decided 2026-10-20.** Hoarse implements its own IMAP client, on asyncio, supporting CONDSTORE and **QRESYNC** (RFC 7162), `COMPRESS=DEFLATE`, command pipelining, literal streaming, `ESEARCH`, `MOVE`, `UIDPLUS`, `OBJECTID`, `SPECIAL-USE`, `LIST-STATUS` and `NOTIFY`.
+
+No Python IMAP library supports QRESYNC. IMAPClient 4.1.0 is synchronous, built on `imaplib`, offers CONDSTORE only through `enable()`, and has no COMPRESS. aioimaplib 2.0.3 is asynchronous and actively maintained but still lists STARTTLS and most of `AUTHENTICATE` as unimplemented. QRESYNC is the single lever that turns resync cost from *per message* into *per mailbox*; at a million messages that is the difference between a two-second resync and a two-minute one. It cannot be bolted on from outside a library's parser.
+
+*Rejected:* building on IMAPClient with raw commands (fastest to a working client, permanent ceiling on resync cost); extending aioimaplib upstream (inherits someone else's parser and release cadence); a driver interface shipping IMAPClient first (defers the long pole, but the engine's scheduling and connection-pool design is shaped by the protocol client, so the interface would be guessed rather than derived).
+
+**This is the largest single item in the project.** It is budgeted accordingly in [the roadmap](15-roadmap.md).
+
+## D-04 — Two processes: UI and engine
+
+**Decided 2026-10-20.** Hoarse runs as **two processes**: `hoarse-ui` (PySide6, read-only on the store) and `hoarse-engine` (asyncio, sole writer). They communicate over a local socket.
+
+PySide6 does not support free-threaded Python, so the GIL is a given. In a single process, every burst of MIME parsing, HTML sanitising, index building or database writing competes with the UI thread for the interpreter — which is exactly the mechanism behind scroll stutter in Python GUI applications. Separating the processes removes the contention entirely, gives crash isolation (an engine fault does not take the window down), and lets the engine be restarted, upgraded or debugged independently.
+
+*Rejected:* one process with worker threads (much simpler, but GIL contention is the known failure mode); one process plus a `ProcessPoolExecutor` (helps the CPU-bound bursts, leaves the sync loop in the UI process); a three-tier engine-plus-worker-pool (more headroom than v1 needs).
+
+The engine MAY use a `ProcessPoolExecutor` internally for bulk import and initial index builds. That is an implementation detail, not a third architectural tier.
+
+## D-05 — Store: SQLite for metadata, a second SQLite database for bodies
+
+**Decided 2026-10-20.** Per account: one `meta.db` holding envelopes, flags, folders, threads, addresses, parts, the op-log and the search index; and **sharded `blobs/NNN.db` files** holding message bodies and parts as compressed BLOBs.
+
+SQLite is measurably faster than the filesystem for BLOBs under about 256 KB and uses roughly 20% less disk for them, because it avoids per-file `open`/`close` and filesystem block rounding. It also brings crash safety, incremental blob I/O and `VACUUM` that we would otherwise hand-write. Splitting bodies into their own file keeps `meta.db` small and hot in page cache — which is what makes list scrolling fast.
+
+Blob databases are **sharded and sealed**: the writer appends to the newest shard until it reaches a size cap (default 8 GB), then seals it and opens a new one. Sealed shards are read-only, so they never need `VACUUM`, and they back up incrementally. A blob locator is the pair `(shard_id, rowid)`.
+
+*Rejected:* hand-rolled append-only pack files (better dedup and compression control, but fsync ordering, CRC, crash recovery and compaction are a sub-project in themselves); Maildir files (great interoperability, but a million inodes per account and poor small-file behaviour on NTFS and APFS); blobs with spillover to files above a threshold (two code paths for one job).
+
+## D-06 — Message list: `QTableView` over a windowed model
+
+**Decided 2026-10-20.** The message list is a `QTableView` with fixed row metrics and a single full-width custom delegate. Threading is **materialised in the store** and rendered as indentation by the delegate.
+
+`QTreeView` builds an internal item structure for every visible row and is well documented as slow at large item counts; `QTableView` computes geometry from fixed section sizes and handles millions of rows. Keeping the model flat means the threaded view is still a single keyset-paginated index range read.
+
+The model never holds the whole folder: it reports the true row count and materialises a sliding window of rows around the viewport. See [chapter 10](10-ui.md).
+
+## D-07 — Search: SQLite FTS5, headers always, bodies inside the offline window
+
+**Decided 2026-10-20.** Subject and addresses are indexed for **every** message. Body text is indexed for exactly those messages whose bodies are stored locally under the account's body-retention policy ([D-08](#d-08)). Anything outside that is searched on the server and merged into the result list.
+
+This bounds the index — the usual failure mode of local mail search is an index that grows without limit — and it matches the body policy exactly, so there is one rule to explain rather than two. Verified available in CPython 3.14.4 (SQLite 3.46.1): FTS5 with `contentless_delete=1`, the `trigram` tokenizer for substring search, and `fts5vocab` for the query planner's selectivity estimates.
+
+*Rejected:* headers only (no offline body search at all); indexing every body unconditionally (unbounded index, permanent background indexer); an opt-in body index (a setting that only exists because we could not decide).
+
+## D-08 — Offline policy: per account, with a window by default
+
+**Decided 2026-10-20.** Headers are synchronised for every message in every account. Bodies are fetched according to a **per-account, per-folder policy**, defaulting to a rolling window (90 days) plus anything the user opens, evicted by LRU under a disk cap.
+
+People with several accounts use them differently: a full mirror for a small work account, a 30-day window for a million-message archive, headers-only for a high-volume mailing-list account. One global policy serves none of those well.
+
+*Rejected:* a single global window; full mirror by default (30–100 GB and hours of first sync before the client is usable); headers-only by default (every read needs the network).
+
+## D-09 — HTML rendering: safe by default, full fidelity on request
+
+**Decided 2026-10-20.** Mail renders by default through Hoarse's own sanitiser into a `QTextDocument` — fast, offline, no Chromium, no network. A per-message and per-sender **"render fully"** action switches to QtWebEngine with JavaScript disabled, a strict CSP, remote content blocked and a custom scheme handler for inline parts.
+
+The default path costs nothing and leaks nothing. The escape hatch exists because a meaningful share of real mail is built with CSS that Qt's rich-text engine does not implement, and telling the user "this message cannot be displayed correctly" is not an acceptable answer.
+
+QtWebEngine lives in `PySide6-Addons` (~250 MB), so it is an **extra**: `hoarse[webengine]`. A build without it degrades gracefully to "show original source".
+
+*Rejected:* QtWebEngine for everything (correct, but ~150 MB and a render process per view, for a default path that does not need it); `QTextDocument` only (a lot of mail renders visibly wrong, with no recourse); plain-text first (safest and most retro-appropriate, but the switch gets used constantly).
+
+## D-10 — Feature scope: address book and filters, not calendar or crypto
+
+**Decided 2026-10-20.** In scope: a local **address book** with recipient autocomplete, and **filters, rules and junk control**. Out of scope: calendar, CalDAV, CardDAV, OpenPGP and S/MIME. See [non-goals](01-goals.md#14-non-goals).
+
+## D-11 — Protocols: IMAP, POP3, SMTP, JMAP, ManageSieve, local mailboxes
+
+**Decided 2026-10-20.** Beyond the required IMAP/IMAPS/POP3/SMTP, Hoarse also implements **JMAP**, **ManageSieve** (RFC 5804), and streaming **import and export** of mbox, Maildir and `.eml`, including Thunderbird profile import. Exchange EWS and Microsoft Graph are out of scope.
+
+JMAP is a second account driver behind the same interface, with no MIME-level sync logic at all — `Email/changes` returns exactly what changed. Fastmail, Stalwart, Cyrus and Apache James speak it, and Thunderbird is rolling it out. ManageSieve is small, well-specified, and means filters keep running when Hoarse is closed. Import is the migration path: without it, nobody with a million messages can switch.
+
+## D-12 — OAuth2: the client is implemented, the registration is the user's
+
+**Decided 2026-10-20.** Hoarse implements OAuth2 fully — loopback redirect with PKCE (S256), the device-code flow, refresh-ahead, `XOAUTH2` and `OAUTHBEARER` — but ships **no client IDs**. The user registers their own application with Google or Microsoft and pastes in the client ID.
+
+Google's full-mail IMAP scope is a *restricted* scope: a publicly distributed client ID requires app verification including a third-party security assessment, with real cost and real calendar time before a first release. An open-source client also cannot keep a client secret secret. Pushing registration to the user removes the whole problem and leaves Hoarse's release schedule under its own control.
+
+**This is a real usability cost** and must be mitigated by documentation, not hidden: the setup wizard walks through registration step by step, per provider, with direct links.
+
+*Rejected:* shipping our own IDs for both (best onboarding, gated on Google verification); shipping Microsoft's only (half a solution with two code paths); app passwords only (Microsoft 365 is unreachable, as basic auth for IMAP and POP is already disabled there).
+
+**Revisit** once Hoarse has a stable release and a maintainer willing to own the verification process.
+
+## D-13 — Theming: declarative theme packs, no Python `QStyle`
+
+**Decided 2026-10-20.** Appearance comes from declarative theme packs: palette, metrics, borders, icons, fonts, density. The engine turns a pack into a `QPalette`, a generated stylesheet, an icon set and a set of precomputed delegate parameters.
+
+Hoarse MUST NOT subclass `QStyle` or `QProxyStyle` in Python on any painting path. Every virtual call crosses the C++/Python boundary, once per primitive, per widget, per repaint — which is precisely the budget the message list needs. Custom painting is confined to a small, known set of delegates and widget subclasses that read pre-resolved theme values.
+
+*Rejected:* theme packs plus full period chrome (frameless windows, drawn title bars, bitmap fonts — a much larger painting surface and a per-theme golden-image suite); native-first with only a density setting (does not deliver the retro half of the brief); stylesheets alone (QSS cannot change pixel metrics or primitive painting, so "retro" would be a colour scheme).
+
+**Revisit** for period chrome once the theme engine is stable and the golden-image infrastructure exists.
+
+## D-14 — Accounts are strictly separate
+
+**Decided 2026-10-20.** Each account has its own folder tree, its own database files, and its own views. There are **no cross-account unified folders**.
+
+This is a performance decision as much as a UI one. Every message-list query hits exactly one account's indexes with no merging, which keeps the hardest query shape in the application — an ordered window over a million rows — on a single covering index. It also means an account can be added, removed, resynchronised or corrupted without touching any other.
+
+*Rejected:* Thunderbird's per-account trees plus optional unified folders (familiar, but every unified view is a merged cursor across N indexes); unified-first (modern, but makes per-account operations awkward and every query a merge).
+
+**Consequence:** search is per account too. The address book is the one genuinely global store, and it holds no messages.
+
+## D-15 — Python 3.14 floor, 3.15 as the recommended runtime
+
+**Decided 2026-10-20.** `requires-python = ">=3.14"`. Hoarse tracks 3.15 as the recommended runtime and MUST pass CI on both.
+
+3.14 brings `compression.zstd` into the standard library (PEP 784) — under [D-02](#d-02) that is the only way to get zstd at all, and it is a markedly better ratio and speed than zlib for body blobs. It also brings `imaplib.IMAP4.idle()`, the best interpreter performance to date, and officially supported free-threading, which the engine process can use even though the UI process cannot. Because `uv` provisions the interpreter, a high floor costs users nothing.
+
+Verified on CPython 3.14.4: `compression.zstd` present; SQLite 3.46.1 with FTS5, `contentless_delete=1`, the `trigram` tokenizer and `fts5vocab`.
+
+## D-16 — Distribution: `uv` first, native installers later
+
+**Decided 2026-10-20.** v1 ships as a `uv`-managed install — `uvx hoarse` or `uv tool install hoarse` — which pulls the right interpreter and the Qt wheels on all three platforms. Native installers are a later milestone ([M8](15-roadmap.md)).
+
+Under [D-02](#d-02) there is nothing to compile, so `uv` alone is a genuinely complete installation story for the audience Hoarse is aimed at. Shipping installers from day one would mean a three-OS build matrix, code-signing certificates and notarisation before the application is even stable.
+
+*Rejected:* PyInstaller bundles alongside `uv` from the start; Briefcase; `uv` as the only channel, forever.
+
+---
+
+## Assumptions
+
+Assumptions are not decisions: they are things taken as true that nobody has confirmed. Each one names what would falsify it.
+
+| ID | Assumption | Falsified by |
+|---|---|---|
+| `A-01` | The design target is **one account over 1,000,000 messages**, with a handful of smaller accounts alongside it. Totals beyond ~3M messages across all accounts are out of scope for the performance budgets. | A user corpus materially larger than this |
+| `A-02` | Hoarse's own licence is not yet fixed. PySide6's LGPLv3 works for either an open-source or a proprietary licence, so no decision is forced. | A licence choice that conflicts with LGPLv3 dynamic-linking terms |
+| `A-03` | Target servers are Dovecot, Cyrus, Gmail, Microsoft 365, Stalwart and Zimbra. QRESYNC is assumed present on Dovecot, Cyrus and Stalwart, and absent on Gmail (which has `X-GM-*` instead). | The capability survey in [M2](15-roadmap.md) |
+| `A-04` | The pure-Python HTML sanitiser can keep up with rendering one message at a time (budget `PRF-7`), since it never runs over a million messages at once. | A benchmark over a real mail corpus |
+| `A-05` | `keyring` is available and working on the great majority of target systems; the encrypted-file vault is a fallback, not the main path. | Field reports from Linux users without a Secret Service provider |
+| `A-06` | A million-row account fits comfortably in `meta.db` at roughly 0.5–0.8 GB plus 0.2–0.4 GB of header index. | The `tools/corpus` census in [M1](15-roadmap.md) |
+| `A-07` | **Resolved 2026-10-20.** `cryptography` and `cffi` are admitted to the compiled allowlist; `keyring` with `secretstorage` is the credential path on Linux. See the note above. | — |