presentation/QuickMailBackend.h - GCC Code Coverage Report

Directory:	src/
Coverage:	low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
	Coverage	Exec / Excl / Total
Lines:	95.0%	57 / 0 / 60
Functions:	94.9%	56 / 0 / 59
Branches:	92.3%	12 / 0 / 13
    presentation/QuickMailBackend.h
    
        Line
        Branch
        Exec
        Source
      
        #pragma once
      
        #include "FolderIconCatalog.h"
      
        #include "StatusMessageState.h"
      
        #include "FolderSubscriptionEditor.h"
      
        #include "MessageCopyQueue.h"
      
        #include "DavCollectionDiscovery.h"
      
        #include "AccountConnectionTest.h"
      
        #include "QuickPreferences.h"
      
        #include "app/core/SettingsSyncSession.h"
      
        #include "ComposeDraftStore.h"
      
        #include "FolderPresentationModel.h"
      
        #include "MailPresentationModel.h"
      
        #include "QuickMailSelection.h"
      
        #include "QuickPimBackend.h"
      
        #include "QuickSourceViewer.h"
      
        #include "QuickFolderActions.h"
      
        #include "QuickMailMenu.h"
      
        #include "QuickAccountSettings.h"
      
        #include "QuickComposeBackend.h"
      
        #include "QuickInvitation.h"
      
        #include "QuickCalendarIcs.h"
      
        #include "QuickContactVcf.h"
      
        #include "QuickMailEventLink.h"
      
        #include "EventQuickInput.h"
      
        #include "QuickThreadListModel.h"
      
        #include "MailSelectionSummary.h"
      
        #include "data/MailSort.h"
      
        #include "QuickRulesBackend.h"
      
        #include "MailSearchSessions.h"
      
        #include "data/MailRequest.h"
      
        #include "service/FolderPredictionService.h"
      
        #include <QObject>
      
        #include <QHash>
      
        #include <QPointer>
      
        #include <QSet>
      
        #include <QThreadPool>
      
        #include <QTimer>
      
        #include <QUrl>
      
        #include <QCache>
      
        #include "ConflictCenter.h"
      
        #include "QuickConflictResolver.h"
      
        #include <atomic>
      
        #include <functional>
      
        #include <memory>
      
        #include <optional>
      
        class MailSessionCore;
      
        class WorkspaceState;
      
        class SearchCoordinator;
      
        class MailSearchReadService;
      
        class ExternalWhitelistModel;
      
        class MailPayloadPreview;
      
        struct FolderInfo;
      
        // Frontend adapter over the shared product session. It owns no transport/cache.
      
        class QuickMailBackend final : public QObject {
      
        2316
          Q_OBJECT
      
          Q_PROPERTY(QuickPreferences *preferences READ preferences CONSTANT)
      
          Q_PROPERTY(QAbstractItemModel *folders READ folders CONSTANT)
      
          // S91.1.1: calendar, tasks and contacts (QML `backend.pim.*`).
      
          Q_PROPERTY(QuickPimBackend *pim READ pim CONSTANT)
      
          // S91.1.2: raw source, inline PDF and attachment export (QML `backend.source.*`).
      
          Q_PROPERTY(QuickSourceViewer *source READ source CONSTANT)
      
          // S91.3.1: send, drafts, sessions, attachments (QML `backend.compose.*`).
      
          Q_PROPERTY(QuickComposeBackend *compose READ compose CONSTANT)
      
          // Sprint 93 S93.5.2: invitation card of the displayed mail
      
          // (QML `backend.invitation.*`); the host reports the displayed mail.
      
          Q_PROPERTY(QuickInvitation *invitation READ invitation CONSTANT)
      
          // Sprint 93 S93.5.3: calendar file import/export (QML `backend.ics.*`).
      
          Q_PROPERTY(QuickCalendarIcs *ics READ ics CONSTANT)
      
          // Sprint 97 S97.5.8: vCard import and export (QML `backend.vcf.*`).
      
          Q_PROPERTY(QuickContactVcf *vcf READ vcf CONSTANT)
      
          // Sprint 93 S93.5.6: mail <-> appointment links (QML `backend.mailEvent.*`).
      
          Q_PROPERTY(QuickMailEventLink *mailEvent READ mailEvent CONSTANT)
      
          // Sprint 93 S93.4.5: ":event <text>" grammar (QML `backend.eventInput`).
      
          Q_PROPERTY(QuickEventInput *eventInput READ eventInput CONSTANT)
      
          Q_PROPERTY(QAbstractItemModel *messageCopies READ messageCopies CONSTANT)
      
          // S91.2.2: accounts, DAV accounts, image policy, reading mode, settings sync
      
          // (QML `backend.settings.*`).
      
          Q_PROPERTY(QuickAccountSettings *settings READ settings CONSTANT)
      
          Q_PROPERTY(QuickRulesBackend *rules READ rules CONSTANT)
      
          // Sprint 107: the conflict resolver (`backend.resolver`) and the open
      
          // conflicts of every area (`backend.conflicts`).
      
          Q_PROPERTY(QuickConflictResolver *resolver READ resolver CONSTANT)
      
          Q_PROPERTY(ConflictCenter *conflicts READ conflicts CONSTANT)
      
          // Sprint 101: the search tabs (QML `backend.searchTabs.active`).
      
          Q_PROPERTY(MailSearchSessions *searchTabs READ searchTabs CONSTANT)
      
          Q_PROPERTY(QuickMailMenu *mailMenu READ mailMenu CONSTANT)
      
          // F95-10: the header's "☰" menu (own instance: its picks are no mail commands).
      
          Q_PROPERTY(QuickMailMenu *appMenu READ appMenu CONSTANT)
      
          // F100-03/F100-09: native menus of the views (PNativeMenu, routed by name).
      
          Q_PROPERTY(QuickMailMenu *contextMenu READ contextMenu CONSTANT)
      
          Q_PROPERTY(QuickMailMenu *searchMenu READ searchMenu CONSTANT)
      
          Q_PROPERTY(QString accountEmail READ accountEmail NOTIFY accountChanged)
      
          Q_PROPERTY(QString accountName READ accountName NOTIFY accountChanged)
      
          Q_PROPERTY(QString activeAccountId READ activeAccountId NOTIFY accountChanged)
      
          Q_PROPERTY(QVariantList accountChoices READ accountChoices NOTIFY accountChanged)
      
          Q_PROPERTY(QAbstractItemModel *folderSubscriptions READ folderSubscriptions CONSTANT)
      
          // S91.2.1: folder operations/properties/cache maintenance (QML `backend.folderActions.*`).
      
          Q_PROPERTY(QuickFolderActions *folderActions READ folderActions CONSTANT)
      
          Q_PROPERTY(QString folderPath READ folderPath NOTIFY folderChanged)
      
          // Sprint 108 D-21: the shown folder is the account's drafts folder (Continue editing).
      
          Q_PROPERTY(bool inDraftsFolder READ inDraftsFolder NOTIFY folderChanged)
      
          Q_PROPERTY(bool threaded READ threaded WRITE setThreaded NOTIFY threadedChanged)
      
          Q_PROPERTY(bool threadProjectionPending READ threadProjectionPending NOTIFY threadedChanged)
      
          // True only while a thread rebuild runs AND it exceeds the feedback
      
          // threshold (default 300 ms): fast cached rebuilds never flash a
      
          // placeholder, slow ones announce themselves once they are really slow.
      
          Q_PROPERTY(bool threadProjectionSlow READ threadProjectionSlow NOTIFY threadProjectionSlowChanged)
      
          // Diagnostic (mailjd-bench fan-out gate): folder-prediction batches sent
      
          // to the prediction worker since start. No NOTIFY; not used by QML.
      
          Q_PROPERTY(qulonglong predictionRequestCount READ predictionRequestCount)
      
          Q_PROPERTY(bool folderSwitchInProgress READ folderSwitchInProgress NOTIFY folderSwitchInProgressChanged)
      
          Q_PROPERTY(QAbstractItemModel *mailList READ mailList NOTIFY threadedChanged)
      
          Q_PROPERTY(QString status READ status NOTIFY statusChanged)
      
          Q_PROPERTY(bool configured READ configured NOTIFY accountChanged)
      
          Q_PROPERTY(bool navigationPending READ navigationPending NOTIFY navigationChanged)
      
          Q_PROPERTY(qint64 selectionCount READ selectionCount NOTIFY selectionChanged)
      
          // F100-77: the reader's summary of a multiple selection.
      
          Q_PROPERTY(MailSelectionSummary *selectionSummary READ selectionSummary CONSTANT)
      
          Q_PROPERTY(QStringList selectedLabels READ selectedLabels NOTIFY selectedLabelsChanged)
      
          Q_PROPERTY(bool selectionPending READ selectionPending NOTIFY selectionChanged)
      
          Q_PROPERTY(bool actionPending READ actionPending NOTIFY actionChanged)
      
          Q_PROPERTY(QVariantList searchSuggestions READ searchSuggestions NOTIFY searchSuggestionsChanged)
      
          Q_PROPERTY(QStringList expandedFolders READ expandedFolders NOTIFY folderExpansionChanged)
      
          Q_PROPERTY(QVariantMap suggestion READ suggestion NOTIFY suggestionsChanged)
      
          // F105 feedback: the reader header shows whether the shown mail is
      
          // important and its labels — also in a mail tab, where no list row does
      
          // ({important, labels: chips as in the list}; empty without a mail).
      
          Q_PROPERTY(QVariantMap readerMarks READ readerMarks NOTIFY readerMarksChanged)
      
          Q_PROPERTY(bool suggestionsVisible READ suggestionsVisible NOTIFY suggestionsChanged)
      
          // The folder-suggestion column belongs to the inbox only (user decision
      
          // 2026-10-06); suggestionsVisible stays the persistent switch.
      
          Q_PROPERTY(bool suggestionColumnAvailable READ suggestionColumnAvailable NOTIFY folderChanged)
      
          // F100-66: the folder list's order, flat and threaded, read from the cache
      
          // in that order (persisted as view/mailSort). Search tabs sort their own
      
          // results (MailPresentationModel::sortByColumn).
      
          Q_PROPERTY(QString sortColumn READ sortColumn NOTIFY mailSortChanged)
      
          Q_PROPERTY(bool sortAscending READ sortAscending NOTIFY mailSortChanged)
      
          Q_PROPERTY(QStringList sortableColumns READ sortableColumns NOTIFY threadedChanged)
      
        public:
      
          // Status line text from outside the backend (S93.5.1 reminders without
      
          // a notification service).
      
        9
          void showStatus(const QString &status) { setStatus(status); }
      
        4498
          QuickPreferences *preferences() { return &m_preferences; }
      
        769
          MailSelectionSummary *selectionSummary() { return &m_selectionSummary; }
      
          QuickMailBackend(MailSessionCore &session, WorkspaceState &workspace,
      
                           QString profileDirectory, QObject *parent = nullptr,
      
                           MailSearchReadService *searchReader = nullptr);
      
          ~QuickMailBackend() override;
      
        1233
          MailPresentationModel *mailModel() { return &m_mail; }
      
          int loadedRowForIdentity(const MailId &id) const;
      
        84337
          QuickPimBackend *pim() { return &m_pim; }
      
        864
          QAbstractItemModel *folders() { return &m_folders; }
      
        5775
          QuickAccountSettings *settings() { return &m_settings; }
      
        12116
          QuickRulesBackend *rules() { return &m_rules; }
      
        2062
          QuickConflictResolver *resolver() { return &m_resolver; }
      
        7359
          ConflictCenter *conflicts() { return &m_conflicts; }
      
        22236
          MailSearchSessions *searchTabs() { return m_searchTabs.get(); }
      
        1563
          QuickMailMenu *mailMenu() { return &m_mailMenu; }
      
        1567
          QuickMailMenu *appMenu() { return &m_appMenu; }
      
        5539
          QuickMailMenu *contextMenu() { return &m_contextMenu; }
      
        2331
          QuickMailMenu *searchMenu() { return &m_searchMenu; }
      
          QString accountName() const;
      
          QString accountEmail() const;
      
          QString activeAccountId() const;
      
          QVariantList accountChoices() const;
      
          Q_INVOKABLE bool selectAccount(const QString &id);
      
        766
          QAbstractItemModel *messageCopies() { return &m_messageCopies; }
      
        766
          QAbstractItemModel *folderSubscriptions() { return &m_folderSubscriptions; }
      
        4062
          QuickFolderActions *folderActions() { return &m_folderActions; }
      
          Q_INVOKABLE void beginFolderSubscriptions();
      
        7990
          QString folderPath() const { return m_folderPath; }
      
          4/4✓ Branch 3 → 4 taken 118 times.
✓ Branch 3 → 7 taken 4156 times.
✓ Branch 5 → 6 taken 21 times.
✓ Branch 5 → 7 taken 97 times.

        4274
          bool inDraftsFolder() const { return !m_draftsFolder.isEmpty() && m_folderPath == m_draftsFolder; }
      
        1755
          QString status() const { return m_statusState.text(); }
      
          // Test/diagnostic access to the status line (the website showcase clears
      
          // the feedback of one step before it captures the next).
      
        4
          StatusMessageState *statusState() { return &m_statusState; }
      
          // Unconfirmed server actions of the active account for the status details.
      
          Q_INVOKABLE QVariantList pendingActionDetails() const;
      
        2452
          bool threaded() const { return m_threaded; }
      
        85
          bool threadProjectionPending() const { return m_threadProjectionPending; }
      
        2590
          bool folderSwitchInProgress() const { return m_folderSwitchInProgress; }
      
        780
          bool threadProjectionSlow() const { return m_threadProjectionSlow; }
      
        ✗
          qulonglong predictionRequestCount() const { return m_predictionRequestCount; }
      
          void setThreadProjectionSlowThresholdMs(int ms);
      
          void setThreaded(bool on);
      
          // The visible main list: the threaded projection while thread view is on
      
          // and no search runs (search results always present flat).
      
          QAbstractItemModel *mailList();
      
          QThreadPool *workerPool() { return &m_threadPool; } // tests (S106-291)
      
          bool configured() const;
      
          3/4✓ Branch 2 → 3 taken 3839 times.
✓ Branch 2 → 5 taken 9 times.
✗ Branch 4 → 5 not taken.
✓ Branch 4 → 6 taken 3839 times.

        3848
          bool navigationPending() const { return m_navigationActive || !m_navigation.isEmpty(); }
      
          qint64 selectionCount() const;
      
          // Labels on the currently selected mail (raw IMAP keywords, e.g. "$label1").
      
          QStringList selectedLabels() const;
      
        8740
          bool selectionPending() const { return m_selection.pending(); }
      
        3101
          bool actionPending() const { return m_actionPending; }
      
        300
          QVariantList searchSuggestions() const { return m_searchSuggestions; }
      
          QStringList expandedFolders() const;
      
          QVariantMap suggestion() const;
      
          QVariantMap readerMarks() const;
      
          // Sprint 105 S105.3.8: why a row's folder suggestion was made and whether
      
          // it is confident ({reason, strong}); empty for rows without one.
      
          Q_INVOKABLE QVariantMap suggestionDetails(const QVariantMap &identity) const;
      
          static QString suggestionReason(const FolderSuggestion &suggestion);
      
        7161
          bool suggestionsVisible() const { return m_suggestionsVisible; }
      
        799
          QString sortColumn() const { return MailSortOrder::idOf(m_mailSort.column); }
      
        800
          bool sortAscending() const { return m_mailSort.ascending; }
      
          // Threads sort by their newest mail or their first mail's sender/subject.
      
          QStringList sortableColumns() const;
      
          // A click on a column title: the same column again flips the direction,
      
          // another column starts with its natural direction.
      
          Q_INVOKABLE void sortMailList(const QString &columnId);
      
          const MailSortOrder &mailSort() const { return m_mailSort; }
      
          // IMAP's INBOX name is case-insensitive (RFC 3501 section 5.1).
      
        2898
          bool suggestionColumnAvailable() const { return m_folderPath.compare(QLatin1String("INBOX"), Qt::CaseInsensitive) == 0; }
      
          // List rows get predictions only while the column is on and available.
      
          4/4✓ Branch 2 → 3 taken 1867 times.
✓ Branch 2 → 6 taken 2590 times.
✓ Branch 4 → 5 taken 1762 times.
✓ Branch 4 → 6 taken 105 times.

        4457
          bool suggestionColumnShown() const { return m_suggestionsVisible && suggestionColumnAvailable(); }
      
          Q_INVOKABLE void setSuggestionsVisible(bool on); // F100-55: also from the column chooser
      
          bool acceptsIdentity(const MailId &identity) const;
      
          void restoreWorkspaceSelection();
      
          Q_INVOKABLE bool selectFolder(const QString &path);
      
          // Sprint 105 D-14 (g i/s/d/a/j): the path of "inbox", "sent", "drafts",
      
          // "archive" or "junk" of the active account ("" when it has none).
      
          Q_INVOKABLE QString specialFolder(const QString &role) const;
      
          Q_INVOKABLE bool markFolderRead(const QString &path);
      
          Q_INVOKABLE QStringList matchingFolders(const QString &prefix) const;
      
          Q_INVOKABLE bool executeCommand(const QString &id);
      
          // Sprint 98: `line` is a command-bar line ("folder rename", "mark read");
      
          // its first word is the command, the second word its value.
      
          Q_INVOKABLE QString namedCommandUnavailableReason(const QString &line) const;
      
          Q_INVOKABLE bool canExecuteNamedCommand(const QString &line) const;
      
          Q_INVOKABLE bool executeNamedCommand(const QString &name, const QString &argument);
      
          Q_INVOKABLE bool moveSelectedMail(const QString &path);
      
          Q_INVOKABLE void beginMailRowSelection(int row, int modifiers = 0);
      
          Q_INVOKABLE void selectMailRow(int row, int modifiers = 0);
      
          Q_INVOKABLE void selectAllMails();
      
          Q_INVOKABLE void watchSelectionRows(int first, int last);
      
          // Lazy header paging for the flat list (Widgets parity: the QTreeView drove
      
          // MailListModel::fetchMore as the viewport approached the loaded window end).
      
          Q_INVOKABLE bool canFetchMoreMails() const;
      
          Q_INVOKABLE void fetchMoreMails();
      
          Q_INVOKABLE bool canFetchPreviousMails() const;
      
          Q_INVOKABLE void fetchPreviousMails();
      
          Q_INVOKABLE void previewSearch(const QString &query);
      
          Q_INVOKABLE bool submitSearch(const QString &query, int suggestion = -1);
      
          // Sprint 101 D-1/D-2: a full search opens (or reuses) a search tab;
      
          // `newTab` asks for a second one (Alt+Enter, "In neuem Tab öffnen").
      
          Q_INVOKABLE bool openSearch(const QString &query, bool newTab = false);
      
          Q_INVOKABLE void cancelSearchPreview();
      
          Q_INVOKABLE bool setFolderExpanded(const QString &path, bool expanded);
      
        6365
          QuickSourceViewer *source() { return &m_source; }
      
        1
          int pageRows() const { return m_pageRows; }
      
          // The selectable folder paths known to the backend (updated by LIST).
      
        ✗
          Q_INVOKABLE QSet<QString> availableFolders() const { return m_availableFolders; }
      
        17345
          QuickComposeBackend *compose() { return &m_compose; }
      
        8418
          QuickInvitation *invitation() { return &m_invitation; }
      
        768
          QuickCalendarIcs *ics() { return &m_ics; }
      
        1691
          QuickContactVcf *vcf() { return &m_vcf; }
      
        39
          QuickMailEventLink *mailEvent() { return &m_mailEvent; }
      
        10
          QuickEventInput *eventInput() { return &m_eventInput; }
      
          MailId displayedMailId() const;
      
        signals:
      
          // One viewport commit from the list (measured: <= 1 per rendered frame).
      
          void viewportWatched(int first, int last);
      
          void suggestionsChanged();
      
          void readerMarksChanged();
      
          // Persistence only (F95-15); QML keeps reading suggestionsChanged.
      
          void suggestionsVisibleChanged();
      
          void folderExpansionChanged();
      
          void threadedChanged();
      
          void mailSortChanged();
      
          void threadProjectionSlowChanged();
      
          void folderSwitchInProgressChanged();
      
          void accountChanged();
      
          void folderChanged();
      
          void statusChanged();
      
          void navigationChanged();
      
          void selectionChanged();
      
          void selectedLabelsChanged();
      
          void actionChanged();
      
          void searchSuggestionsChanged();
      
          // F4.2(b): emitted when an armed quick-move retry gave up, so the shell
      
          // opens the manual move console exactly like the old direct fallback.
      
          void manualMoveRequested();
      
        private:
      
          QuickPreferences m_preferences;
      
          // Constructor wiring in its original order (S91.0.4). Qt calls slots in
      
          // connection order, so the constructor must call these exactly in this
      
          // sequence; each block moves as a whole when its unit is extracted.
      
          void wireProjectionTimers();
      
          void wireThreadInvalidation();
      
          void wireIndexedProviders();
      
          void wireHeaderProjection();
      
          void wireProjectionSignals();
      
          void wireComposeSource();
      
          void wireFolderSubscriptionsAndFilters();
      
          void wireFolderOperations();
      
          void wirePredictions();
      
          void wireRemovalFollowUp();
      
          void wireFolderChangeResets();
      
          void wireSearch(MailSearchReadService *searchReader);
      
          void wireSearchSuggestions();
      
          void wireSelection();
      
          void wireAccountReload();
      
          void wireSelectionTrace();
      
          void wireNavigation();
      
          void wireControllerStatus();
      
          void wireConnectionStatus();
      
          void refreshConnectionStatus();
      
          // Sprint 100 S100.1.5: mail connection and rule state for the Accounts page.
      
          AccountOverview::Active activeAccountState();
      
          QString m_lastImapError;
      
          // executeCommand() handlers in dispatch order (S91.2.7); each returns
      
          // nullopt when the command is not its own.
      
          std::optional<bool> handleSuggestionCommand(const QString &id);
      
          std::optional<bool> handleSurfaceClose(const QString &id);
      
          std::optional<bool> handleIndexedNavigation(const QString &id);
      
          std::optional<bool> handleTabNavigation(const QString &id);
      
          std::optional<bool> handleSearchTabNavigation(const QString &id);
      
          std::optional<bool> handleMainListNavigation(const QString &id);
      
          std::optional<bool> handleViewCommand(const QString &id);
      
          std::optional<bool> handleUndoCommand(const QString &id);
      
          std::optional<bool> handleMailMoveCommand(const QString &id, const MailId &selected);
      
          std::optional<bool> handleMailViewCommand(const QString &id, const MailId &selected);
      
          std::optional<bool> handleLabelCommand(const QString &id, const MailId &selected);
      
          std::optional<bool> handleFlagCommand(const QString &id, const MailId &selected);
      
          // MAIL-SELECTION-ACTIONS: the selection mail actions act on (more than one
      
          // message in the main folder view), else null; and one state for all of it.
      
          std::shared_ptr<const MailSelectionSnapshot> actionSelection() const;
      
          QMap<qint64, QList<qint64>> searchBulkGroups() const;
      
          bool bulkSelection() const;
      
          bool actOnSelection(MutationKind kind, const QString &label, bool desired,
      
                              std::function<void(bool)> done = {});
      
          void invalidatePredictions();
      
          void requestPredictions();
      
          void nextPredictionBatch(quint64 generation);
      
          // F4.2(b): a quick-move press that outruns the new selection's prediction
      
          // (debounce or worker batch still in flight) arms a bounded retry instead
      
          // of falling back to the manual move console.
      
          bool canArmQuickMoveRetry(const MailId &selected) const;
      
          void armQuickMoveRetry(const MailId &selected);
      
          void disarmQuickMove();
      
          void tryArmedQuickMove();
      
          // Groups identities per folder and queues bounded service batches; the
      
          // selected mail's batch is always queued first (see requestPredictions).
      
          void appendPredictionRequests(const QList<MailId> &identities);
      
          // Drops cached predictions outside the selected mail and the watched
      
          // viewport ("clears obsolete results"); the retained in-scope entries make
      
          // a revisited mail answer instantly.
      
          void prunePredictionsToScope();
      
          FolderSuggestion::Candidate visiblePrediction(const MailId &id) const;
      
          QString predictionText(const MailId &id) const;
      
          // Populates the session thread model from the presented folder's complete
      
          // cached projection while thread view is on; clears it when off, so the
      
          // full-folder tree is never retained behind a flat list.
      
          void syncThreadProjection();
      
          // F3.12: large folder projections build off the GUI thread; this cancels a
      
          // pending build and bumps the generation.
      
          void cancelThreadProjection();
      
          // True while the threaded model is the one actually presented (preference on,
      
          // no search; pending builds keep this projection selected).
      
          bool threadedPresentation() const;
      
          // Row-oriented main-list dispatch: search and flat mode answer from the
      
          // paged flat model, threaded mode from the flattened thread projection.
      
          int activeRowCount() const;
      
          QVariantMap activeMailAt(int row) const;
      
          int activeRowForIdentity(const QVariantMap &identity) const;
      
          MailSelectionKey activeKeyAt(int row) const;
      
          // F-41: presented-order identities between two selection keys.
      
          QList<qint64> visibleRangeBetween(const MailSelectionKey &anchor,
      
                                            const MailSelectionKey &key) const;
      
          void loadLocalFolders();
      
          void applyFolderList(const QList<FolderInfo> &folders, bool authoritative);
      
          // F-09 (SPRINT-104, D-4): permanent deletion in the open folder.
      
          void ensureDeleteForever();
      
          QList<qint64> deleteForeverUids(const MailId &selected) const;
      
          // P90.16: reserve the visible successor before an removing action (S/X,
      
          // archive, delete, move). Identity has priority over row numbers: when a
      
          // later projection refresh invalidates the selection, reconcileSelection()
      
          // consumes the token instead of jumping to row 0. The token is cleared by
      
          // folder/account switches, superseded by a newer action and consumed by
      
          // the next reconcileSelection that observes a valid selection.
      
          void reserveActionContinuity(int lastRemovedVisualRow);
      
          void clearActionContinuity();
      
          void reconcileSelection();
      
          void presentCachedFolder(const QString &path);
      
          void publishSelection();
      
          void requestSelectedMail(const MailId &id);
      
          void setStatus(const QString &status);
      
          void cancelNavigation();
      
          void startNavigation();
      
          void refreshSelectionScope();
      
          MailSessionCore &m_session;
      
          WorkspaceState &m_workspace;
      
          QString m_profileDirectory;
      
          MailPresentationModel m_mail;
      
          QuickThreadListModel m_threadList;
      
          QuickPimBackend m_pim;
      
          FolderPresentationModel m_folders;
      
          QuickAccountSettings m_settings;
      
          QuickMailSelection m_selection;
      
          MailSelectionSummary m_selectionSummary{{}, this}; // header lookup set in the constructor
      
          MailId m_mainCurrent;
      
          // P90.16 action-continuity token: the mail being removed, its visual rank
      
          // and the reserved surviving successor identity.
      
          MailId m_actionAnchor;
      
          MailId m_actionSuccessor;
      
          int m_actionVisualRow = -1;
      
          QString m_folderPath;
      
          QString m_previousFolder;
      
          StatusMessageState m_statusState;
      
          FolderSubscriptionEditor m_folderSubscriptions;
      
          MessageCopyQueue m_messageCopies;
      
          QSet<QString> m_availableFolders;
      
          QSet<QString> m_openTaskMessageIds; // S94.5.5, canonical Message-IDs
      
          void refreshTaskLinks();
      
          // P90.17: in-memory folder identity admission cache (path ↔ id) so the
      
          // click/selection paths never pay SQLite round trips in acceptsIdentity().
      
          QHash<QString, qint64> m_folderIdByPath;
      
          QHash<qint64, QString> m_folderPathById;
      
          QHash<qint64, quint32> m_folderEpochById;
      
          void rebuildFolderIdentityCache();
      
          qint64 folderIdForPath(const QString &path) const;
      
          bool m_reconciling = false;
      
          bool m_waitingCachedPage = false;
      
          QList<int> m_navigation;
      
          bool m_navigationActive = false;
      
          bool m_applyingNavigation = false;
      
          bool m_applyingSelection = false;
      
          bool m_actionPending = false;
      
          std::unique_ptr<SearchCoordinator> m_search;
      
          std::unique_ptr<MailSearchSessions> m_searchTabs;
      
          void wireSearchTabs(MailSearchReadService *searchReader);
      
          QTimer m_searchDebounce;
      
          QString m_searchPreviewQuery;
      
          QVariantList m_searchSuggestions;
      
          QTimer m_predictionDebounce;
      
          // Armed quick-move retry state (F4.2(b)); m_quickMoveArmed.isValid()
      
          // means a pressed s is waiting for the selected mail's prediction.
      
          QTimer m_quickMoveFallback;
      
          MailId m_quickMoveArmed;
      
          QHash<MailId, FolderSuggestion> m_predictions;
      
          QHash<qint64, quint32> m_predictionEpochs;
      
          QHash<qint64, QString> m_predictionFolders;
      
          QSet<MailId> m_alternatePredictions;
      
          QList<FolderPredictionRequest> m_predictionRequests;
      
          // Batches handed to the worker and not yet answered: taken off the queue,
      
          // yet still "in flight" for a pressed s (canArmQuickMoveRetry).
      
          int m_predictionBatchesRunning = 0;
      
          quint64 m_predictionGeneration = 0;
      
          qulonglong m_predictionRequestCount = 0;
      
          // Viewport batches are small so the suggestion column fills progressively
      
          // while later batches are still classifying on the single worker.
      
          static constexpr int ViewportPredictionChunk = 32;
      
          // Warm per-mail predictions are kept across selection changes (epoch-fenced
      
          // at use time); the cap bounds memory when many folders were visited.
      
          static constexpr int MaximumCachedPredictions = 512;
      
          // The shown mail's flags and labels as read from the cache, with the
      
          // visual-first changes of this session on top (the journal writes the
      
          // cache later; a rollback sends the restored value).
      
          struct ReaderMarks {
      
            MailId id;
      
            bool loaded = false;
      
            bool important = false;
      
            QStringList labels;
      
            std::optional<bool> importantOverride;
      
            QHash<QString, bool> labelOverrides;
      
          };
      
          mutable ReaderMarks m_readerMarks;
      
          void readerMarkChanged(qint64 folderId, qint64 uid, const std::function<void(ReaderMarks &)> &apply);
      
          // S105.3.8 (ux.md §12): a suggestion at or above this calibrated
      
          // confidence is shown in the normal text colour, below it muted.
      
          static constexpr double StrongSuggestion = 0.9;
      
          int m_predictionFirst = -1, m_predictionLast = -1;
      
          bool m_suggestionsVisible = false;
      
          QString m_junkFolder;
      
          QuickSourceViewer m_source;
      
          // Visible rows reported by the list viewport; one page of mail navigation.
      
          int m_pageRows = 10;
      
          QuickComposeBackend m_compose;
      
          QuickInvitation m_invitation{
      
              m_session,
      
        29
              {[this] { return m_pim.calendarChoices(); }, [this] { return m_pim.lastCalendar(); },
      
        1
               [this](const QStringList &recipients, const QByteArray &message, const QString &doneText) {
      
          1/1✓ Branch 3 → 4 taken 1 time.

        1
                 return m_compose.enqueuePrepared(recipients, message, doneText);
      
               },
      
        1
               [this](const QString &status) { setStatus(status); }},
      
              this};
      
          QuickCalendarIcs m_ics{
      
              m_session,
      
        5072
              {[this] { return m_pim.calendarChoices(); }, [this] { return m_pim.lastCalendar(); },
      
        3
               [this] { return displayedMailId(); }, [this](const QString &status) { setStatus(status); },
      
               m_profileDirectory + QStringLiteral("/cache/ics-export"), QString(),
      
        1
               [this] { return m_pim.taskActions()->lastList(); }},
      
              this};
      
          QuickContactVcf m_vcf{
      
              m_session,
      
        5
              {[this] { return displayedMailId(); }, [this](const QString &status) { setStatus(status); }, QString()},
      
              this};
      
        2
          QuickMailEventLink m_mailEvent{m_session, m_pim, [this] { return displayedMailId(); }, this};
      
        3
          QuickEventInput m_eventInput{[this] { return m_pim.calendarChoices(); }, this};
      
          QList<FolderInfo> m_folderInfos;
      
          QString m_archiveFolder;
      
          QString m_trashFolder;
      
          class MailPermanentDelete *m_deleteForever = nullptr; // F-09
      
          QString m_draftsFolder;
      
          QString m_sentFolder;
      
          bool m_threaded = false;
      
          MailSortOrder m_mailSort;
      
          void applyMailSort();
      
          // One worker shared with QuickComposeBackend (send and server-draft
      
          // builds). Queued jobs must run: a send job is the only path that ends
      
          // m_sendPending (S106-291), so nothing clears this pool.
      
          QThreadPool m_threadPool;
      
          struct ThreadSnapshot {
      
            MailThreadModel::Prepared data;
      
            qint64 externalVersion = -1;
      
            quint32 uidValidity = 0;
      
          };
      
          // Additional inactive-folder retention: conservative byte charges from the
      
          // prepared forest, not a number-of-folders cap. Oversized entries are refused.
      
          QCache<qint64, ThreadSnapshot> m_threadSnapshots{1024}; // KiB
      
          quint64 m_threadDataGeneration = 0;
      
          bool m_threadRefreshQueued = false;
      
          QSet<qint64> m_moveExclusionRefreshQueued;
      
          bool m_folderSwitchInProgress = false; // list view drops its delegate buffer meanwhile
      
          bool hasPendingMove(const MailId &mail) const;
      
          QuickFolderActions m_folderActions;
      
          QuickMailMenu m_mailMenu{this};
      
          QuickMailMenu m_appMenu{this};
      
          QuickMailMenu m_contextMenu{this};
      
          QuickMailMenu m_searchMenu{this};
      
          QHash<qint64, QSet<qint64>> m_visualMoveUids; // folder -> moves awaiting the durable writer
      
          void queueIndexedMoveExclusionRefresh(qint64 folderId);
      
          QTimer m_headerProjectionTimer;
      
          QString m_headerProjectionFolder;
      
          void retainThreadSnapshot(qint64 folderId, qint64 externalVersion);
      
          bool restoreThreadSnapshot(qint64 folderId);
      
          quint64 m_threadProjectionGeneration = 0;
      
          bool m_threadProjectionPending = false;
      
          bool m_threadProjectionFailed = false;
      
          bool m_threadProjectionSlow = false;
      
          int m_threadProjectionSlowThresholdMs = 300;
      
          quint64 m_folderHoldGeneration = 0;  // folder switch that owns the held rows
      
          QTimer m_threadProjectionSlowTimer;
      
          // P90 cold build: plain cached rows while the first indexed page builds.
      
          QTimer m_provisionalPageTimer;
      
          QObject m_provisionalPageOwner; // own read lane: never cancels other reads
      
          static constexpr int ProvisionalPageDelayMs = 100;
      
          void requestProvisionalPage();
      
          void armThreadProjectionSlowFlag();
      
          void clearThreadProjectionSlowFlag();
      
          // Moves the currently selected mail into targetFolder through the shared
      
          // journaled move path; the removal follow-up advances the selection.
      
          bool moveCurrentMailToFolder(const QString &targetFolder);
      
          // Sprint 95: server rules of the active account (`backend.rules`).
      
          QuickRulesBackend::Deps rulesDeps();
      
          void reportManualMove(const QList<MailId> &mails, const QString &targetPath);
      
          QuickRulesBackend m_rules{rulesDeps(), this};
      
          // Sprint 107 (QuickMailBackendConflicts.cpp).
      
          QuickConflictResolver::Deps resolverDeps();
      
          ConflictCenter::Deps conflictDeps();
      
          QuickConflictResolver m_resolver{resolverDeps(), this};
      
          ConflictCenter m_conflicts{conflictDeps(), this};
      
        };