hoarse 0.1.1__py3-none-any.whl

hoarse/__init__.py

@@ -0,0 +1,12 @@
+"""Hoarse — a desktop email client that stays fast at a million messages.
+
+The specification in ``docs/spec/`` is normative. Hard invariants live in
+``.claude/skills/hoarse/SKILL.md``; the two that bite earliest are:
+
+* ``hoarse.ui`` must not import ``hoarse.net`` or ``hoarse.engine`` (ARC-4).
+* ``hoarse.engine`` must not import Qt, directly or transitively (ARC-3).
+
+Both are enforced by ``tests/unit/test_layering.py``, not by convention.
+"""
+
+__version__ = "0.1.1"

hoarse/__main__.py

@@ -0,0 +1,80 @@
+"""Launcher. Acquires the profile lock, starts the UI, spawns the engine (ARC-7)."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from hoarse.core import logging as hoarse_logging
+from hoarse.core.paths import Paths
+
+
+def main(argv: list[str] | None = None) -> int:
+    from hoarse import __version__
+
+    parser = argparse.ArgumentParser(prog="hoarse")
+    parser.add_argument("--version", action="version", version=f"hoarse {__version__}")
+    parser.add_argument("--build-info", action="store_true",
+                        help="print the version, commit and runtime, for bug reports")
+    parser.add_argument("--profile", type=Path, help="override the profile directory")
+    parser.add_argument("--no-keyring", action="store_true", help="never persist credentials")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--demo", action="store_true",
+                        help="open the interface on synthetic data (1,000,000 messages, no store)")
+    parser.add_argument("--theme", default="modern-light",
+                        choices=("modern-light", "modern-dark", "retro", "high-contrast"),
+                        help="theme pack for --demo (switchable live: View > Theme)")
+    from hoarse.features.cli import add_subcommands  # argparse only; no Qt, no store
+
+    add_subcommands(parser)
+    args = parser.parse_args(argv)
+    if args.build_info:
+        from hoarse.buildinfo import build_info
+
+        sys.stdout.write(build_info().text() + "\n")
+        return 0
+
+    hoarse_logging.configure(logging.DEBUG if args.verbose else logging.INFO)
+    if args.command in ("import", "export"):  # FEA-24: headless, no window, no engine
+        from hoarse.features.cli import run
+
+        return run(args)
+    if args.demo:
+        from hoarse.ui.app import run_demo  # lazy: Qt loads after argument parsing (UI-36)
+
+        return run_demo(args.theme)
+    paths = Paths(args.profile)
+    paths.ensure()
+
+    from hoarse.features.profile_lock import ProfileBusyError, ProfileLock
+
+    log = logging.getLogger("hoarse")
+    log.info("profile at %s", paths.data)
+    lock = ProfileLock(paths.data / "hoarse.lock")  # ARC-7: one UI (and one engine) per profile
+    try:
+        lock.acquire()
+    except ProfileBusyError as exc:
+        log.error("%s", exc)
+        return 1
+    try:
+        from hoarse.engine.spawn import spawn_engine  # the launcher may; the UI package may not
+        from hoarse.ui.app import run_profile  # lazy: Qt loads after argument parsing (UI-36)
+        from hoarse.ui.credsession import CredentialSession  # no Qt in this one
+
+        session = CredentialSession(use_keyring=not args.no_keyring)
+
+        def launch():  # type: ignore[no-untyped-def]
+            # The session may have switched to --no-keyring after a keychain failure (SEC-24),
+            # so the flag is read at each (re)start, not once.
+            extra = ("--no-keyring",) if session.no_keyring else ()
+            return spawn_engine(args.profile, extra_args=extra)
+
+        return run_profile(args.profile, launch, args.theme, session=session)
+    finally:
+        lock.release()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hoarse/_build_meta.py

@@ -0,0 +1,6 @@
+"""Written by hatch_build.py at build time. Do not edit."""
+
+COMMIT = '918ab9ece652'
+COMMIT_DATE = '2026-10-22'
+BUILT = '2026-10-22 13:30 UTC'
+DIRTY = False

hoarse/buildinfo.py

@@ -0,0 +1,101 @@
+"""What build this is: version, source commit, and the runtime it runs on.
+
+No Qt and no store: ``hoarse --version`` and the About dialog both use it.
+
+The commit comes from, in order:
+
+1. ``hoarse._build_meta``, written into the wheel and sdist at build time by
+   ``hatch_build.py`` (a release installed from PyPI has no ``.git``);
+2. ``git`` in the checkout this package was imported from (``uv run hoarse``);
+3. otherwise it is unknown, and says so.
+"""
+
+from __future__ import annotations
+
+import platform
+import sqlite3
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from hoarse import __version__
+
+__all__ = ["BuildInfo", "build_info"]
+
+_CHECKOUT = Path(__file__).resolve().parents[2]  # src/hoarse/ -> repository root
+
+
+@dataclass(frozen=True, slots=True)
+class BuildInfo:
+    version: str
+    commit: str | None        # short hash; None when unknown
+    commit_date: str | None   # ISO date of that commit
+    built: str | None         # ISO time the package was built; None for a checkout
+    dirty: bool               # a checkout with uncommitted changes
+    origin: str               # "release build" | "source checkout" | "unknown origin"
+    python: str
+    platform: str
+    sqlite: str
+    qt: str | None = None     # filled in by the UI (Qt must not be imported here)
+    pyside: str | None = None
+
+    @property
+    def commit_text(self) -> str:
+        if self.commit is None:
+            return "unknown"
+        text = self.commit + (" (uncommitted changes)" if self.dirty else "")
+        return f"{text}, {self.commit_date}" if self.commit_date else text
+
+    def lines(self) -> list[tuple[str, str]]:
+        """``(label, value)`` rows, in display order."""
+        rows = [("Version", self.version), ("Build", self.origin),
+                ("Commit", self.commit_text)]
+        if self.built:
+            rows.append(("Built", self.built))
+        rows += [("Python", self.python), ("Platform", self.platform),
+                 ("SQLite", self.sqlite)]
+        if self.qt:
+            rows.append(("Qt", f"{self.qt} (PySide6 {self.pyside})" if self.pyside else self.qt))
+        return rows
+
+    def text(self) -> str:
+        """Plain text for "Copy build info" and bug reports."""
+        return "\n".join(f"{k}: {v}" for k, v in [("Hoarse", self.version), *self.lines()[1:]])
+
+
+def _git(*args: str) -> str | None:
+    try:
+        out = subprocess.run(["git", "-C", str(_CHECKOUT), *args], capture_output=True,
+                             text=True, timeout=2, check=True)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip()
+
+
+def build_info() -> BuildInfo:
+    commit = commit_date = built = None
+    dirty = False
+    try:
+        from hoarse import _build_meta  # type: ignore[attr-defined]
+    except ImportError:
+        _build_meta = None
+    if _build_meta is not None:
+        commit, commit_date = _build_meta.COMMIT, _build_meta.COMMIT_DATE
+        built, dirty = _build_meta.BUILT, bool(getattr(_build_meta, "DIRTY", False))
+        origin = "release build"
+    elif (_CHECKOUT / ".git").exists():
+        commit = _git("rev-parse", "--short=12", "HEAD")
+        commit_date = _git("log", "-1", "--format=%cs") if commit else None
+        dirty = bool(_git("status", "--porcelain", "--untracked-files=no"))
+        origin = "source checkout"
+    else:
+        origin = "unknown origin"
+    return BuildInfo(
+        version=__version__, commit=commit or None, commit_date=commit_date or None,
+        built=built, dirty=dirty, origin=origin,
+        python=f"{platform.python_implementation()} {platform.python_version()}",
+        platform=f"{platform.system()} {platform.release()} ({platform.machine()})"
+        if sys.platform != "darwin" else f"macOS {platform.mac_ver()[0]} ({platform.machine()})",
+        sqlite=sqlite3.sqlite_version,
+    )

hoarse/core/__init__.py

@@ -0,0 +1 @@
+"""See docs/spec/ — this package's contract is normative."""

hoarse/core/credentials.py

@@ -0,0 +1,104 @@
+"""Secrets live in the OS keychain, never in settings or IPC (ch. 12 §12.4).
+
+Contract shared by the UI and the engine. The window collects a password,
+stores it here under a reference, and sends the engine only the reference
+(ARC-14). The engine resolves the reference when it connects.
+
+Backends: ``keyring`` (Secret Service / Keychain / Credential Manager), or an
+in-memory store for ``--no-keyring`` sessions and tests (SEC-25). The
+encrypted-file vault fallback is a later work package.
+"""
+
+from __future__ import annotations
+
+import secrets
+import threading
+from typing import Final, Protocol
+
+from hoarse.core.errors import HoarseError
+
+SERVICE: Final = "hoarse"
+
+
+class CredentialError(HoarseError):
+    """The keychain is unavailable, locked, or refused the request (SEC-24)."""
+
+
+class CredentialStore(Protocol):
+    def get(self, ref: str) -> str | None: ...
+    def put(self, ref: str, secret: str) -> None: ...
+    def delete(self, ref: str) -> None: ...
+    @property
+    def backend_name(self) -> str: ...   # shown in settings (SEC-23)
+
+
+def new_ref(kind: str = "server") -> str:
+    """A fresh opaque reference. Not derived from the address or host, so the
+    keychain listing does not reveal which accounts a user has."""
+    return f"{kind}:{secrets.token_hex(12)}"
+
+
+class MemoryCredentials:
+    """Per-process store: ``--no-keyring`` and tests. Nothing persists."""
+
+    backend_name = "memory (not saved)"
+
+    def __init__(self) -> None:
+        self._d: dict[str, str] = {}
+        self._lock = threading.Lock()
+
+    def get(self, ref: str) -> str | None:
+        with self._lock:
+            return self._d.get(ref)
+
+    def put(self, ref: str, secret: str) -> None:
+        with self._lock:
+            self._d[ref] = secret
+
+    def delete(self, ref: str) -> None:
+        with self._lock:
+            self._d.pop(ref, None)
+
+
+class KeyringCredentials:
+    """The OS keychain via ``keyring``. Every failure is a CredentialError, never
+    a hang or a silent plaintext fallback (SEC-24)."""
+
+    def __init__(self) -> None:
+        try:
+            import keyring
+            from keyring.backends.fail import Keyring as FailKeyring
+        except ImportError as e:  # pragma: no cover - keyring is a dependency
+            raise CredentialError(f"keyring is not installed: {e}") from e
+        self._kr = keyring
+        backend = keyring.get_keyring()
+        if isinstance(backend, FailKeyring):
+            raise CredentialError("no system keychain is available")
+        self.backend_name = f"system keychain ({type(backend).__name__})"
+
+    def get(self, ref: str) -> str | None:
+        try:
+            value: str | None = self._kr.get_password(SERVICE, ref)
+            return value
+        except Exception as e:  # keyring raises backend-specific types
+            raise CredentialError(f"keychain read failed: {type(e).__name__}") from e
+
+    def put(self, ref: str, secret: str) -> None:
+        try:
+            self._kr.set_password(SERVICE, ref, secret)
+        except Exception as e:
+            raise CredentialError(f"keychain write failed: {type(e).__name__}") from e
+
+    def delete(self, ref: str) -> None:
+        try:
+            self._kr.delete_password(SERVICE, ref)
+        except self._kr.errors.PasswordDeleteError:
+            pass
+        except Exception as e:
+            raise CredentialError(f"keychain delete failed: {type(e).__name__}") from e
+
+
+def open_store(*, use_keyring: bool = True) -> CredentialStore:
+    """The store for this session. Raises CredentialError if the keychain was
+    requested and is unusable; the caller offers ``--no-keyring`` (SEC-25)."""
+    return KeyringCredentials() if use_keyring else MemoryCredentials()

hoarse/core/errors.py

@@ -0,0 +1,78 @@
+"""Error types shared across packages.
+
+Every parser in Hoarse is *total*: malformed input produces a typed error carrying
+the offending bytes, never an ``IndexError`` and never a hang (MIM-3, PRO-4).
+"""
+
+from __future__ import annotations
+
+
+class HoarseError(Exception):
+    """Base for every error Hoarse raises deliberately."""
+
+
+class ProtocolError(HoarseError):
+    """A server sent something that does not parse.
+
+    Carries the offending bytes so a transcript fixture can be minted from a
+    failure in the field (PRO-4).
+    """
+
+    def __init__(self, message: str, *, raw: bytes = b"", offset: int | None = None) -> None:
+        super().__init__(message)
+        self.raw = raw
+        self.offset = offset
+
+
+class StoreError(HoarseError):
+    """The store could not satisfy a request."""
+
+
+class SchemaVersionError(StoreError):
+    """The database was written by a newer Hoarse than this one (STO-31).
+
+    Refusing to open is deliberate: guessing at an unknown schema is how stores
+    get corrupted.
+    """
+
+
+class NotFound(StoreError):  # noqa: N818 -- names fixed by the IPC codes
+    """A folder, message or account named by a request does not exist.
+
+    The engine maps it to the IPC error code ``NOT_FOUND``.
+    """
+
+
+class NameExists(StoreError):  # noqa: N818
+    """A folder of that name already exists under the same parent (``NAME_EXISTS``)."""
+
+
+class InvalidName(StoreError):  # noqa: N818
+    """A folder name is empty, too long, or contains the hierarchy delimiter or a
+    control character (``INVALID_NAME``)."""
+
+
+class NotAllowed(StoreError):  # noqa: N818
+    """The request is well-formed but refused (``NOT_ALLOWED``).
+
+    Deleting or renaming a special-use folder, moving messages to the folder they
+    are already in, and anything that would span two accounts (D-14).
+    """
+
+
+class StaleSync(StoreError):  # noqa: N818 -- reads as the condition, like NotFound
+    """A sync batch was fetched under a ``UIDVALIDITY`` the folder no longer has.
+
+    Raised by the store's server-state writes when the caller's ``uidvalidity``
+    does not match the folder's: the batch predates a ``reset_folder`` and its
+    uids name other messages now (`SYN-16`). Nothing is written; the engine
+    drops the batch and resyncs the folder.
+    """
+
+
+class ContentError(HoarseError):
+    """Message content could not be handled; the message is kept and flagged."""
+
+
+class ConfigError(HoarseError):
+    """Settings on disk are unusable."""

hoarse/core/logging.py

@@ -0,0 +1,106 @@
+"""Logging with redaction on by default (SEC-32).
+
+Logs carry no address, subject, body or credential unless a verbose protocol
+trace is explicitly enabled for the session. ``print`` is banned by ruff (T20)
+so that nothing can bypass this.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+import re
+from typing import Final
+
+_REDACTED: Final = "[redacted]"
+
+# Ordered most-specific first: a credential must never survive because an
+# address pattern matched part of it first.
+_PATTERNS: Final[tuple[tuple[re.Pattern[str], str], ...]] = (
+    (re.compile(r"(?i)\b(AUTHENTICATE|LOGIN|AUTH)\s+\S+.*"), r"\1 " + _REDACTED),
+    (re.compile(r"(?i)\b(bearer|basic)\s+[\w.\-+/=]+"), r"\1 " + _REDACTED),
+    # A quoted value is redacted up to its closing quote, so a passphrase with
+    # spaces or commas goes whole; an unquoted one up to whitespace , or }.
+    (re.compile(r"(?i)\b(password|passwd|passphrase|secret|token|client_secret|pw|pwd)"
+                r"""(['"]?)\s*[=:]\s*(?:(['"])(?:(?!\3)[^\r\n])*\3?|[^\s,}'"]+)"""),
+     r"\1\2=\3" + _REDACTED + r"\3"),
+    # Addresses: quoted local parts, domain literals and dotless hosts too.
+    (re.compile(r'"[^"\r\n]{1,256}"@[\w.\[\]:-]+'), _REDACTED),
+    (re.compile(r"[\w.+-]+@(?:\[[0-9A-Fa-f.:]+\]|[\w-]+(?:\.[\w-]+)*)"), _REDACTED),
+)
+
+# A bare SASL PLAIN response is base64 of "authzid\0user\0pass": decode any
+# base64-looking token and redact it if it carries NUL separators.
+_B64: Final = re.compile(r"(?<![A-Za-z0-9+/=])[A-Za-z0-9+/]{8,}={0,2}(?![A-Za-z0-9+/=])")
+
+
+def _scrub_sasl(match: re.Match[str]) -> str:
+    token = match.group(0)
+    try:
+        decoded = base64.b64decode(token + "=" * (-len(token) % 4), validate=True)
+    except (ValueError, binascii.Error):
+        return token
+    return _REDACTED if b"\x00" in decoded else token
+
+
+class RedactingFilter(logging.Filter):
+    """Strips credentials and addresses from every record.
+
+    Applied to the message *and* its arguments, because ``log("%s", addr)``
+    would otherwise leak through the lazy-formatting path.
+    """
+
+    def __init__(self, *, enabled: bool = True) -> None:
+        super().__init__()
+        self.enabled = enabled
+
+    @staticmethod
+    def _scrub(text: str) -> str:
+        for pattern, replacement in _PATTERNS:
+            text = pattern.sub(replacement, text)
+        text = _B64.sub(_scrub_sasl, text)
+        return text
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not self.enabled:
+            return True
+        if isinstance(record.msg, str):
+            record.msg = self._scrub(record.msg)
+        else:  # log.error(exc) / log.info(obj): scrub its text, not just str messages
+            record.msg = self._scrub(str(record.msg))
+        if record.args:
+            # Scrub strings only: stringifying everything breaks %d/%f formats.
+            if isinstance(record.args, dict):
+                record.args = {k: self._scrub_arg(v) for k, v in record.args.items()}
+            else:
+                record.args = tuple(self._scrub_arg(a) for a in record.args)
+        if record.exc_info and not record.exc_text:
+            # Tracebacks carry exception messages, which can carry addresses.
+            record.exc_text = self._scrub(logging.Formatter().formatException(record.exc_info))
+        elif record.exc_text:
+            record.exc_text = self._scrub(record.exc_text)
+        return True
+
+    @classmethod
+    def _scrub_arg(cls, value: object) -> object:
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return value
+        return cls._scrub(str(value))
+
+
+def configure(level: int = logging.INFO, *, redact: bool = True) -> None:
+    """Install a redacting handler on the root logger.
+
+    ``redact=False`` is the opt-in protocol trace of SEC-32, and the caller is
+    responsible for showing the user that it is running.
+    """
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)-7s %(name)-24s %(message)s")
+    )
+    handler.addFilter(RedactingFilter(enabled=redact))
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(level)

hoarse/core/mailtypes.py

@@ -0,0 +1,187 @@
+"""Neutral server-state types shared by ``net`` (which produces them) and
+``store`` (which persists them), so neither imports the other (ARC-19).
+
+The engine is the only place both meet: it calls the IMAP client, gets these
+values, and hands them to ``StoreWriter``. Qt-free, asyncio-free, I/O-free.
+
+Strings here are already decoded (RFC 2047 words in ENVELOPE are decoded by
+the parser via ``hoarse.mime``); raw protocol bytes never cross this seam.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Final
+
+# STO-6 bit values. Mirrors ``store.schema.Flags``; a test pins the two
+# together so they cannot drift.
+SEEN: Final = 1
+ANSWERED: Final = 2
+FLAGGED: Final = 4
+DELETED: Final = 8
+DRAFT: Final = 16
+RECENT: Final = 32
+FORWARDED: Final = 64
+JUNK: Final = 128
+NOT_JUNK: Final = 256
+
+_SYSTEM: Final[dict[str, int]] = {
+    "\\seen": SEEN,
+    "\\answered": ANSWERED,
+    "\\flagged": FLAGGED,
+    "\\deleted": DELETED,
+    "\\draft": DRAFT,
+    "\\recent": RECENT,
+    "$forwarded": FORWARDED,
+    "$junk": JUNK,
+    "$notjunk": NOT_JUNK,
+    "junk": JUNK,        # common non-standard spellings seen in the wild
+    "nonjunk": NOT_JUNK,
+    "notjunk": NOT_JUNK,
+}
+
+_CANONICAL: Final[dict[int, str]] = {
+    SEEN: "\\Seen",
+    ANSWERED: "\\Answered",
+    FLAGGED: "\\Flagged",
+    DELETED: "\\Deleted",
+    DRAFT: "\\Draft",
+    FORWARDED: "$Forwarded",
+    JUNK: "$Junk",
+    NOT_JUNK: "$NotJunk",
+}
+
+
+def split_flags(names: Iterable[str]) -> tuple[int, tuple[str, ...]]:
+    """IMAP flag names -> (STO-6 bitfield, remaining keywords, case preserved,
+    de-duplicated case-insensitively, in first-seen order)."""
+    bits = 0
+    seen: set[str] = set()
+    keywords: list[str] = []
+    for name in names:
+        low = name.lower()
+        if low in _SYSTEM:
+            bits |= _SYSTEM[low]
+        elif low not in seen and not low.startswith("\\"):
+            seen.add(low)
+            keywords.append(name)
+    return bits, tuple(keywords)
+
+
+def flag_names(bits: int) -> list[str]:
+    """STO-6 bits -> the IMAP names to STORE. ``RECENT`` is server-only and
+    never stored by a client, so it is omitted."""
+    return [name for bit, name in _CANONICAL.items() if bits & bit]
+
+
+@dataclass(frozen=True, slots=True)
+class Address:
+    """One address. RFC 5322 groups are flattened: the group's start is
+    ``Address(name=<phrase>, addr="", group=<phrase>)``, and each member
+    carries ``group=<phrase>`` with its own name and addr."""
+    name: str          # decoded display name, "" if none
+    addr: str          # "local@domain"; "" for a group marker
+    group: str | None = None   # set on members of an RFC 5322 group, and on its marker
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope:
+    """IMAP ENVELOPE (RFC 3501 §7.4.2), decoded. ``date`` is the raw Date:
+    string; the store parses it with ``mime.dates`` and falls back to
+    INTERNALDATE (MIM-7)."""
+    date: str | None
+    subject: str
+    from_: tuple[Address, ...]
+    sender: tuple[Address, ...]
+    reply_to: tuple[Address, ...]
+    to: tuple[Address, ...]
+    cc: tuple[Address, ...]
+    bcc: tuple[Address, ...]
+    in_reply_to: str | None    # raw, angle brackets kept
+    message_id: str | None     # raw, angle brackets kept
+
+
+@dataclass(frozen=True, slots=True)
+class BodyPart:
+    """One leaf of BODYSTRUCTURE, flattened. Multipart containers are not
+    listed; their structure is implied by ``part_id`` ("1", "1.2", ...)."""
+    part_id: str
+    type: str                  # lowercased, e.g. "text"
+    subtype: str               # lowercased, e.g. "plain"
+    params: dict[str, str] = field(default_factory=dict)    # lowercased keys
+    content_id: str | None = None
+    encoding: str | None = None                             # lowercased
+    size: int = 0              # octets as encoded
+    lines: int | None = None
+    disposition: str | None = None                          # "inline"/"attachment"
+    disposition_params: dict[str, str] = field(default_factory=dict)
+    filename: str | None = None  # decoded (RFC 2231/2047), from disposition or name
+
+    @property
+    def is_attachment(self) -> bool:
+        return self.disposition == "attachment" or (
+            self.filename is not None and self.type not in ("text", "multipart")
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServerMessage:
+    """A message as described by one header FETCH (SYN-9, MIM-1):
+    ``UID FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODYSTRUCTURE [MODSEQ]
+    [X-GM-MSGID X-GM-THRID] [EMAILID THREADID]``."""
+    uid: int
+    flags: int                 # STO-6 bits, via split_flags
+    keywords: tuple[str, ...]
+    internal_date: int         # unix seconds
+    size: int
+    envelope: Envelope
+    parts: tuple[BodyPart, ...]
+    references: tuple[str, ...] = ()   # from BODY.PEEK[HEADER.FIELDS (REFERENCES)], raw ids
+    modseq: int | None = None
+    gm_msgid: int | None = None
+    gm_thrid: int | None = None
+    email_id: str | None = None        # OBJECTID (RFC 8474)
+    thread_id: str | None = None
+    gm_labels: tuple[str, ...] = ()    # X-GM-LABELS, decoded (WP 5.8)
+
+
+@dataclass(frozen=True, slots=True)
+class FlagChange:
+    uid: int
+    flags: int
+    keywords: tuple[str, ...]
+    modseq: int | None = None
+    gm_labels: tuple[str, ...] | None = None   # None = labels not reported in this update
+
+
+@dataclass(frozen=True, slots=True)
+class ServerFolder:
+    """One LIST response (with LIST-EXTENDED/SPECIAL-USE/STATUS where given).
+    ``path`` is the decoded mailbox name (modified UTF-7 or UTF8=ACCEPT)."""
+    path: str
+    delimiter: str | None
+    special_use: str | None    # "inbox","drafts","sent","junk","trash","archive","all","flagged"
+    selectable: bool = True
+    subscribed: bool = True
+    has_children: bool | None = None
+    # STATUS, when LIST-STATUS or a separate STATUS supplied it
+    messages: int | None = None
+    unseen: int | None = None
+    uidnext: int | None = None
+    uidvalidity: int | None = None
+    highestmodseq: int | None = None
+    # Raw mailbox name, when ``path`` cannot round-trip (invalid modified UTF-7).
+    wire_name: bytes | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class FolderSyncState:
+    """What the store remembers per folder to resync cheaply (§6.4)."""
+    uidvalidity: int | None
+    uidnext: int | None
+    highestmodseq: int | None
+    tier: str            # "qresync" | "condstore" | "plain" | "new"
+    complete: bool       # headers fully backfilled
+    lowest_uid: int | None   # backfill frontier (newest-first, SYN-10)
+    error: str | None = None  # last sync failure for this folder, user-presentable; None = healthy